# 2026-06-07 — Recall-briefing hook (capability increment, PR2)

## Goal

Ship the first capability increment from the intelligence-amplifier reframe
(`docs/plans/2026-06-07-intelligence-amplifier-reframe.md`): make episodic memory
**proactive**. On the first substantive prompt of a session, surface the most
relevant prior activity so the agent reuses a past fix instead of re-deriving it.

This is the purest working-code expression of the new motto ("recalls what it
already solved") — an amplifier, never a gate: it cannot block a prompt.

## Design

- **Pure core** `src/lib/recall-briefing.mts` — `decideBriefing(params)` +
  `formatBriefing(hits)`. No I/O. Gates: opted-in, not-already-briefed,
  prompt above a noise floor, has hits. Fails closed on every boundary
  (disabled / already-briefed / empty-or-short prompt / no hits / malformed
  input) and never throws.
- **Thin hook** `src/hooks/recall-briefing.mts` (UserPromptSubmit) — reads the
  prompt, resolves `~/.claude/instincts/<hash>/observations.jsonl`, builds the
  BM25 index (`recall-index.mts`), queries the prompt, tracks once-per-session
  state in `recall-briefing-session.json`, and emits a `<system-reminder>` via
  `additionalContext`. Fully fail-open (exit 0 on any error).
- **Opt-in, default-off:** runs only when `CLAUDE_RECALL_BRIEFING` is
  `1|on|true|yes`. Default off — zero change to the prompt path for users who
  have not enabled it. Same operator-mode pattern as `CLAUDE_GOAL_DRIFT_GATE`.
- **Wiring:** added as the second UserPromptSubmit hook in
  `getPluginHooksConfig` (after `route-prompt`). `npm run build` regenerates
  `hooks/recall-briefing.mjs`, the bundle mirror, and `hooks.json`.

## Honesty

Recall is lexical BM25 (not semantic). The briefing says "consider `ci_recall`
for full context" — it points at the deeper tool, does not pretend to be it.
Snippets are redacted by `recall-index.redactSecrets`.

## Invariants / traps threaded

- New `.mjs` (`hooks/recall-briefing.mjs` + bundle mirror) committed with the
  executable bit (`git update-index --chmod=+x`) or Linux CI `verify:generated`
  flips the mode (repo lesson: PR #183).
- `verify:everything-mirror` byte-compares the bundle hook + `hooks.json` —
  regenerated by build, committed.
- `mcp-server.test` asserts `hooks.json` deep-equals `getPluginHooksConfig()` —
  both regenerate from source.
- New-feature boundary tests are mandatory (repo lesson 2026-06-03): green gates
  do not prove boundary safety. Covered in `src/test/recall-briefing.test.mts`.

## Verification

- `node --test test/recall-briefing.test.mjs` — 14/14 green.
- `npm run verify:all` + `npm test` — green before PR.

## Scope

Stacked on `feat/intelligence-amplifier-positioning` (both touch
`plugin-metadata.mts`). Default-off; enabling-by-default is a follow-up after
real-world tuning. Remaining roadmap items stay in the reframe plan doc.
