diff --git a/docs/superpowers/plans/2026-11-04-memory-recall.md b/docs/superpowers/plans/2026-11-04-memory-recall.md deleted file mode 100644 index cba54ba..0000000 --- a/docs/superpowers/plans/2026-11-04-memory-recall.md +++ /dev/null @@ -1,273 +0,0 @@ -# Phase 4c Memory Recall Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Bring the right registry entries back to the model at three moments (a design or analysis prompt, a known error, the start of a context) without noise, inside the `mods/memory` mod and `hooks/session-start.sh`. - -**Architecture:** One file grows: `mods/memory/hooks/register.ts` (single-file house style of model-router; the validator has no local-module story we rely on). A shared reader (memory.sh `index` through `$.process.run` for statuses, `$.fs.read` for the three registries) feeds the 4b error index, a BM25 + haiku intent recall at `prompt.submit`, and a known-error line on failing Bash results; a per-context ledger and a per-turn budget bound both channels; every injection is logged in the store. The digest is a bash block at the end of the session-start banner. - -**Tech Stack:** TypeScript Claude Code mod (engine 2.1.316 types, `claude plugin test` kit), bash (session-start.sh, `lib/reconcile.sh`, `lib/memory.sh`), bun for the proof harness. - -**Spec:** `docs/superpowers/specs/2026-11-04-memory-recall-design.md` (approved 2026-11-04). Contract: `.claude/tasks/contracts/2026-11-04-memory-recall-1859.md` (answers 0-11 `[gated]`). Spike: `.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md`. - -## Global Constraints - -- Every hook fails open: `.catch` → `next(e)` (or the 4b `memory_pending` failure answer), one log line per hook per session through `warnOnce`; a failing read, model call or process run attaches nothing and changes nothing. -- The mod never writes a registry and never calls a write verb of `lib/memory.sh`; the only process it runs is `bash /.claude/lib/memory.sh -C index`. -- Model id `claude-haiku-5-5` (full id, LRN-203); every `$.model.complete` and `$.process.run` is raced by an own timer (LRN-218): haiku 3000 ms, memory.sh 2500 ms. -- Regexes over prompt, tool or registry text are bounded (no nested unbounded quantifier, no `\s*` crossing a newline under `/m`) and timed on 64 KiB inputs under 50 ms each (LRN-219, LRN-259). -- Test oracles are literal strings; nothing an oracle compares is computed by the code under test (LRN-237). Secret-shaped fixtures are built at runtime by concatenation (BLK-041). -- `register.ts`: every line ≤ 80 columns; functions ≤ 25 logic lines and ≤ 5 locals where reasonable; no global mutable state (closure `State` only). -- Injection text: ` — <lesson>`; lesson = first sentence of the kind's field, ≤ 280 chars with `…`; block ≤ 1500 chars; at most 3 entries per recall. -- Keyword patterns copied verbatim from `mods/model-router/hooks/register.ts` default prompt rules at commit 9bbd1d5 (name the commit in a comment). -- Tests: `make test suite=lib/tests/mods.test.sh` while iterating; the full `make test` once before each commit that touches shell. Never touch `settings.json` (dirty on purpose) or `~/.claude/memory.json`. -- Commits: one per task, message given in the task, only the task's files. - -## Review Focus - -1. A BDR whose `Decision` field is 2 000 chars → the lesson is cut at 280 with `…`, and three such hits stay ≤ 1500 chars (Task 3, test RB3). -2. `$.process.run` rejects, hangs, or exits non-zero (no bash, a broken `HOME`) → recall and the error channel inject nothing, `memory_pending` still answers with `index: status reader unavailable` (Task 1, tests SR3-SR5). -3. A pasted 64 KiB log as the prompt → the query is cut to 2000 chars before tokenizing and BM25 over the real-size corpus stays fast (Task 3, test RB5). -4. Design words in every prompt of a long session → already injected IDs never come back in that context; with no candidate left, no haiku call is made (Task 4, tests IR7-IR8). -5. The same known error 20 times in a context → one injection (Task 5, test TE4). - ---- - -### Task 0: Preflight (controller) - -- [ ] `git branch --show-current` → `feature/memory-recall`; `make test suite=lib/tests/mods.test.sh` green at fb6cbf1; `grep -c "test(" mods/memory/hooks/register.test.ts` noted; `ls lib/tests/*.test.sh | head` and the Makefile `test` target read to learn how a new shell suite is picked up. Drift → re-plan. - -### Task 1: Shared reader (statuses from memory.sh, entries with lessons) - -**Files:** Modify `mods/memory/hooks/register.ts` (index block ~386-523, `loadIndex`, `formatPending` callers), `mods/memory/hooks/register.test.ts`. - -**Interfaces:** -- Produces: - - `export type Kind = 'BDR' | 'LRN' | 'BLK'` - - `export type Entry = { id: string; kind: Kind; title: string; lesson: string; body: string }` - - `export function entriesOf(text: string): Entry[]` — heading regex `/^## ((BDR|LRN|BLK)-\d+)\b[ \t]*[—-]?[ \t]*([^\n]{0,300})$/gm`; `title` = the heading text after the ID with a trailing `[tag]` and ` (date)` removed, cut at 100 with `…`; body from heading to next heading (heading included). - - `export function lessonOf(kind: Kind, body: string): string` — label order BDR `Decision`; LRN `Apply`, `Future application`, `Pattern`; BLK `Solution`, `Real cause`; line shape `^[ \t]*-[ \t]*(\*\*)?<Label>(\*\*)?[ \t]*:[ \t]*(.{0,2000})$` (case-insensitive label, `/m`, bounded); first sentence = up to the first `. ` / `; ` followed by a capital or end, else the whole field; cut at 280 with `…`; `''` when no label. - - `export function parseIndex(stdout: string): Map<string, string>` — rows `| ID | Date | Title | Status |` → ID → lowercased first word of Status (`''` when empty). - - `export function isLive(status: Map<string, string>, id: string): boolean` — false when the word is `superseded` or `deprecated`, true otherwise (an ID absent from the map is live). - - `async function statusMap($: Api, root: string): Promise<Map<string, string> | undefined>` — `$.env.get('HOME')`, then `$.process.run(['bash', `${home}/.claude/lib/memory.sh`, '-C', root, 'index'], { timeoutMs: 2000 })` raced by a 2500 ms timer; `undefined` on timeout, rejection, missing HOME or `exitCode !== 0`. - - `type Registries = { entries: Entry[]; status: Map<string, string> | undefined; index: Map<string, string>; note: string }` - - `async function loadRegistries($: Api, root: string): Promise<Registries>` replaces `loadIndex`: reads `decisions.md`, `learnings.md`, `blockers.md` with the 4b `tryRead`; `index` = `buildIndex(entries.filter(BLK|LRN), status)`; `note` = the 4b `index:` line (now naming three files) plus `; status reader unavailable` when `status` is undefined. - - `export function buildIndex(entries: Entry[], status: Map<string, string> | undefined): Map<string, string>` — `status === undefined` → empty map (nothing is known without statuses); else the 4b span/gram rule over live entries. -- Removed: `isSuperseded`, `STATUS`, the `shortcut:` comment above it; the TODO.md line harvesting it is ticked in Task 7. -- Consumed by: `pendingAnswer`, `newFailureCount` (switch to `loadRegistries`). - -- [ ] **Step 1: tests (literal oracles)** - - `SR1` `parseIndex` on a literal 4-line stdout (`.claude/memory/decisions.md`, header, separator, `| BDR-031 | 2026-06-25 | t | superseded |`, `| LRN-001 | 2026-01-01 | t | |`) → `BDR-031`→`superseded`, `LRN-001`→`''`. - - `SR2` a test-side `on('process.run', …)` answering that stdout with exit 0 → `memory_pending` lists a failure matching a BLK span as `known BLK-…`, and an entry marked superseded in the stdout is not indexed (its matching failure reads `NEW`). - - `SR3` `process.run` throws → the answer holds `status reader unavailable` and the failure reads `NEW`; `SR4` exit code 2 → same; `SR5` `process.run` never settles → the answer arrives (clock advanced 2500 ms) with `status reader unavailable`. - - `LS1`-`LS4` `lessonOf`: BDR `- **Decision**: Use X. Then Y.` → `Use X.`; LRN with `Pattern` and `Apply` → the `Apply` text; BLK `- Solution: fix z` → `fix z`; a 2 000-char field → 280 chars ending `…`. - - `EN1` `entriesOf` on `## BDR-007 — Title here [accepted] (2026-01-02)` → title `Title here`; a `## Notes` heading is not an entry. - - Update IDX tests whose oracle assumed the lexical superseded reader or the 2-file `index:` line, each to a literal new expectation; list them in the report. - - `TIMEentries` `entriesOf` + `lessonOf` on a 64 KiB registry of one entry with a 64 KiB field → < 50 ms. -- [ ] **Step 2:** run `make test suite=lib/tests/mods.test.sh` → new tests FAIL. -- [ ] **Step 3:** implement; remove `isSuperseded`/`STATUS`/`shortcut:`. -- [ ] **Step 4:** suite green; `awk 'length($0) > 80' mods/memory/hooks/register.ts | wc -l` → 0. -- [ ] **Step 5:** commit `feat(memory): status reader through memory.sh, entries with lessons`. - -### Task 2: Errno phrases out of the error index - -**Files:** `register.ts` (`grams`, `PLACEHOLDERS`), `register.test.ts`. - -**Interfaces:** -- Produces: `export const ERRNO_PHRASES: readonly string[]` (the 18 phrases of spec Unit 3, lowercase); `export function deErrno(normLine: string): string` — each phrase (word-bounded, after `normalize`) → `<errno>`; `grams` calls `deErrno` first; `PLACEHOLDERS` gains `<errno>`. -- Consumed by: `buildIndex`, `matchOf` (unchanged signatures). - -- [ ] **Step 1: tests** - - `ER1` entry span `` `cat: x: No such file or directory (os error 2)` `` and failure line `ls: cannot access '/tmp/zz': No such file or directory` → NEW (the LRN-056 collision, reproduced on a fixture). - - `ER2` entry span `` `fatal: unable to access remote host thing` `` and the same failure line text → `known` (content grams still match). - - `ER3` `deErrno('cat: <path>: no such file or directory (os error #)')` → `'cat: <path>: <errno> (os error #)'`. - - `ER4` `grams` of `'<errno> <path> # <hex>'` → `[]`. - - `TIMEerrno` `deErrno` on 64 KiB of `no such file or ` repeats → < 50 ms. -- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** green, width 0. -- [ ] **Step 5:** commit `fix(memory): errno phrases never make an error known`. - -### Task 3: BM25 ranking, rerank prompt, answer parse, recall block (pure) - -**Files:** `register.ts` (new block after the index block), `register.test.ts`. - -**Interfaces:** -- Produces: - - `export function tokensOf(text: string): string[]` — lowercase, `[\p{L}\p{N}]{2,40}` runs (bounded), minus `STOP_WORDS` (a const of ≤ 60 FR+EN function words: the, and, for, with, that, this, from, les, des, une, pour, dans, avec, est, pas, que, qui, sur, …). - - `export function bm25Rank(entries: Entry[], query: string, k: number): Entry[]` — query = `cap(query, 2000)`; document = title + lesson + body; k1 1.2, b 0.75, idf `ln(1 + (N - df + 0.5) / (df + 0.5))`; entries with score > 0, highest first, ties by ID order, at most `k`. - - `export function rerankPrompt(query: string, cands: Entry[]): string` — exactly: - `Prompt: <redact(cap(query, 2000))>\nCandidates:\n<ID> | <title> | <lesson>` (one line per candidate)`\nAnswer with at most 3 candidate IDs that would help with this prompt, comma separated, or none.` - - `export function parseIds(text: string, cands: Entry[], max: number): string[]` — `/(?:BDR|LRN|BLK)-\d{1,5}/g` matches, kept when a candidate ID, deduplicated, order kept, at most `max`. - - `export function recallLine(e: Entry): string` — `${e.id} ${e.title} — ${e.lesson}` (no ` — ` when the lesson is empty). - - `export function recallBlock(lines: string[], cap: number): string` — `memory recall:` + `\n` + lines; a line that would make the block exceed `cap` is dropped; `''` when no line fits. -- [ ] **Step 1: tests** - - `RB1` three fixture entries; query `quoting heredoc shell` → the heredoc entry first (literal ID order oracle). - - `RB2` `parseIds('BLK-041, BDR-999, LRN-258', cands, 3)` with cands BLK-041, LRN-258 → `['BLK-041', 'LRN-258']`; `parseIds('none', …)` → `[]`. - - `RB3` three BDR entries with 2 000-char Decision fields → each line's lesson ends `…`, `recallBlock(…, 1500).length <= 1500`, literal first line. - - `RB4` `rerankPrompt` on two candidates → the literal expected string. - - `RB5` `bm25Rank` over 500 synthetic entries of 1 600 chars and a 64 KiB query → < 300 ms (and the query really cut: a token beyond char 2000 does not change the order). - - `RB6` a query with a token built at runtime as a secret shape (`'sk_live_' + 'a'.repeat(24)`) → `rerankPrompt` holds `<redacted:stripe>`. -- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** green, width 0. -- [ ] **Step 5:** commit `feat(memory): bm25 ranking and the rerank prompt`. - -### Task 4: Intent recall at prompt.submit (trigger, haiku, ledger, budget, log, switch) - -**Files:** `register.ts` (`State`, `newState`, `loadEnabled`, `registerSession`, `registerPrompt`, store `Project` type), `register.test.ts`. - -**Interfaces:** -- `State` gains: `recall: boolean | null` (the `"recall"` key, read with `enabled`), `seen: Map<string, Set<string>>` (context key → injected IDs), `spent: Map<string, number>` (context key → chars injected this turn / this context), `fresh: Set<string>` (session ids whose next qualifying prompt is a context start), `lastPrompt: Map<string, number>` (session id → time of the last composer prompt). -- `loadEnabled` returns `{ enabled: boolean; recall: boolean }`; `"recall": false` → recall off; a non-boolean `recall` logs one line (`memory: ~/.claude/memory.json has no boolean "recall", recall stays on`) and counts as absent. `ensureEnabled` keeps its boolean contract; add `ensureRecall($, st): Promise<boolean>`. -- `export const DESIGN_RULE`, `export const ANALYSIS_RULE` — the two router patterns (commit 9bbd1d5), flags `iu`. -- `export function isTrigger(text: string, fresh: boolean, idleMs: number): boolean` — `!text.startsWith('/')`, ≥ 12 code points, and (`fresh` or `idleMs >= 1800000` or a rule matches). -- `export const IDLE_MS = 1800000`, `export const RECALL_CAP = 1500`, `export const HAIKU = 'claude-haiku-5-5'`, `export const RERANK_MS = 3000`. -- `function contextKey(session: string, agent: string | undefined): string` → `${session}:${agent ?? 'main'}`. -- `export function onContextStart(st: State, session: string): void` — deletes every `seen`/`spent` key starting `${session}:`, adds `session` to `fresh`. Called from `session.start` and from a new `classic.SessionStart` hook when `source` is `startup`, `clear` or `compact` (`resume` → nothing). -- `async function recallFor($: Api, st: State, at: Where, text: string): Promise<string>` — loads registries; `status === undefined` → `''`; candidates = `bm25Rank(entries filtered by isLive and not in seen[key], text, 30)`; none → `''` without a model call; `$.model.complete({ model: HAIKU, prompt: rerankPrompt(text, cands), effort: 'low', maxTokens: 64, timeoutMs: RERANK_MS })` raced by `RERANK_MS`; not answered / timeout / throw → `''`; ids → lines → `recallBlock(lines, RECALL_CAP - spent)`; records ids in `seen`, chars in `spent`, and a log record. -- Project store gains `log?: { at: number; session: string; agent: string; channel: 'prompt' | 'tool'; ids: string[] }[]`, kept ≤ 200 (oldest dropped) through the 4b write chain (`queueWrite` + `loadProject`/`saveProject`); `asProject` keeps a valid `log` array and drops malformed records. -- `registerPrompt`: on a composer, non-mid-turn prompt with a non-empty root: (1) the 4b note as today; (2) when `ensureRecall` and `isTrigger(text, fresh.has(session), now - lastPrompt)`: clear `fresh` for the session, reset the main key's `spent`, append the recall block when non-empty; (3) `lastPrompt.set(session, now)` on every composer prompt. Both contexts go in one `next({ ...e, context: [...(e.context ?? []), note?, block?] })`. `session.end` also clears `seen`, `spent`, `fresh`, `lastPrompt`, `recall`. -- [ ] **Step 1: tests** (a bottom `on('model.complete', …)` recording asks, `on('process.run', …)` answering a fixture index, `mock.clock`) - - `IR1` first composer prompt of a session `on va concevoir la suite du mod` (no keyword) → one ask; context holds the literal block `memory recall:\nBLK-001 …`. - - `IR2` a second ordinary prompt 1 min later without keyword → no ask, no block. - - `IR3` 31 min later an ordinary prompt → an ask. - - `IR4` `/feat add x` → no ask; a mid-turn prompt (`turnId` set) → no ask; origin `sdk` → no ask; 11-char prompt → no ask. - - `IR5` the model answers `BDR-999, BLK-001` (BDR-999 not a candidate) → only BLK-001 injected; answers `none` → no block; never settles → no block after `RERANK_MS` (clock advanced) and the prompt passes; `isAnswered: false` → no block. - - `IR6` `classic.SessionStart` `compact` (fired with `$.classic.SessionStart({ source: 'compact' })` in the test) → the next ordinary prompt asks again and BLK-001 may come back; `resume` → no reset. - - `IR7` design keyword in three prompts in a row → BLK-001 injected once only (later asks never list it as a candidate). - - `IR8` every candidate already seen → no ask at all. - - `IR9` `"recall": false` in the switch file → no ask, the 4b note still attached after a milestone; `"recall": "no"` → recall on + one log line. - - `IR10` process.run fails → no ask, prompt unchanged. - - `IR11` after an injection, `loadProject` holds one `log` record `{channel: 'prompt', ids: ['BLK-001']}`; 205 injections → 200 records kept. - - `IR12` a milestone pending and a trigger on the same prompt → context `[note, block]` in that order. - - `TIMErules` both rules on 64 KiB of letters → < 50 ms. -- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** green, width 0. -- [ ] **Step 5:** commit `feat(memory): intent recall at the prompt, once per context`. - -### Task 5: Known-error line on failing Bash results - -**Files:** `register.ts` (`captureFailure` returns the built failure, `registerBash`), `register.test.ts`. - -**Interfaces:** -- `captureFailure` returns `Promise<Failure | undefined>` (the failure it built, stored or not). -- `async function knownLine($: Api, st: State, at: Where, f: Failure, agent: string | undefined): Promise<string>` — `ensureRecall` false → `''`; registries; `status === undefined` → `''`; `id = matchOf(index, f.key)`; none, or already in `seen[key]` → `''`; entry → `memory: known ${recallLine(entry)}`; when its length exceeds `RECALL_CAP - spent[key]` → `''`; records `seen`, `spent`, and a `tool` log record. -- `registerBash`: after capture, `line !== ''` → `return { ...out, context: [...(out.context ?? []), line] }`; else `return out` (unchanged object). -- [ ] **Step 1: tests** - - `TE1` a failing command whose line matches a fixture BLK span → the answer keeps `isError`, `text`, `result` and gains `context: ['memory: known BLK-002 …']` (literal). - - `TE2` an ENOENT line (the ER1 fixture) → no `context` key added (answer deep-equal to the tool's). - - `TE3` a sub-agent (`agentId: 'a1'`) failure → injected; the same failure in the main loop → injected too (separate keys). - - `TE4` the same failure 20 times in one context → one injection. - - `TE5` `"recall": false` → no context, capture still stored. - - `TE6` a matched entry superseded in the status stdout → no injection. - - `TE7` budget: `spent` at 1450 for the main key and a 200-char line → no injection. -- [ ] **Step 2:** FAIL. **Step 3:** implement. **Step 4:** green, width 0. -- [ ] **Step 5:** commit `feat(memory): known-error line on failing commands`. - -### Task 6: Earlier-session milestones in memory_pending - -**Files:** `register.ts` (`formatPending`, `milestoneText`), `register.test.ts`. - -**Interfaces:** `formatPending` lists the current session's milestones under `milestones:` (header renamed from `milestones (this session):`), then the earlier sessions' (newest session first), each earlier line ending ` (earlier session)`. Check `grep -rn "milestones (this session)" skills agents lib docs README.md USAGE.md` and update every citer in the same commit (BDR-100). -- [ ] **Step 1: tests** `PM1` current + one earlier milestone → literal lines in that order; `PM2` only an earlier milestone (the 4b live-proof case) → the answer is not `nothing captured` and holds `- commit fix: probe (HH:MM) (earlier session)` (HH:MM from the test clock through the same local-time helper the 4b tests use). -- [ ] **Step 2-4:** FAIL, implement, green. -- [ ] **Step 5:** commit `feat(memory): memory_pending lists earlier-session milestones`. - -### Task 7: Session digest in session-start.sh - -**Files:** Modify `hooks/session-start.sh` (end of file, before the final `echo ""`); Create `lib/tests/session-digest.test.sh` (or the name the Makefile's discovery requires, Task 0). - -**Interfaces:** a function `_memory_digest <project-root>` printing the block of spec Unit 5: -``` -memory digest: -- open: BLK-017 Bing Webmaster API unusable for a multi-client agency (W2… -- open: +1 more, +3 upstream -- todo: deferred (BDR-123): remap inline-writing best-tier skills … -- journal: 2026-11-04 — 4b memory capture merged into develop … -``` -Source handling: `_ss_source=''`; `if [ ! -t 0 ]; then _ss_in=$(timeout 1 cat 2>/dev/null); _ss_source=$(printf '%s' "$_ss_in" | jq -r '.source // empty' 2>/dev/null); fi`; digest when `_ss_source` is empty, `startup`, `clear` or `compact`. Root = `git rev-parse --show-toplevel` else `pwd`; `.claude/memory/` absent → nothing. Open BLK through `lib/reconcile.sh` `reconcile_blk_open` (source the lib from `$_repo_dir/lib`), status word `open` listed (≤ 3, then `+N more`), `upstream` counted; TODO: first 3 `- [ ]` lines under `### Actionable` up to the next `#` heading, the `- [ ] ` prefix dropped; journal: last line starting `- `. Every line cut at 160 chars (`…`), block cut at 800. All digest commands `2>/dev/null`; the function's failure never changes the exit code (`|| true`). -- [ ] **Step 1: tests** (a `mktemp -d` fixture project per case, literal expected output): - `SD1` source startup with 1 open + 2 upstream BLK, a TODO with 4 unchecked items, a journal → the literal block (3 todo lines, `+2 upstream`); `SD2` source `resume` → no `memory digest:`; `SD3` `</dev/null` → digest printed (empty source), exit 0; `SD4` no `.claude/memory` → no block; `SD5` TODO without `### Actionable` → no todo line; `SD6` a 400-char journal line → cut at 160 with `…`; `SD7` 10 open BLK with long titles → block ≤ 800 chars; `SD8` the existing callers (`lib/tests/memory.test.sh` T13c/d, `push-guard.test.sh`, `graphify-gate.test.sh`) still green. -- [ ] **Step 2-4:** FAIL, implement, `bash lib/tests/session-digest.test.sh` green, `shellcheck hooks/session-start.sh lib/tests/session-digest.test.sh` clean, full `make test` green. -- [ ] **Step 5:** commit `feat(hooks): memory digest at session start`. - -### Task 8: Measured proof harness (controller + one sonnet dispatch) - -**Files:** Create `.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts` (bun, imports `entriesOf`, `lessonOf`, `parseIndex`, `isLive`, `bm25Rank`, `rerankPrompt`, `parseIds`, `recallBlock`, `normalize`, `failureLine`, `redact`, `buildIndex`, `matchOf`, `deErrno` from `mods/memory/hooks/register.ts`), `RECALL.md` (counts and shares only). -- [ ] **Step 1 (sonnet):** the harness: mode `prompts` reads the last 14 days of `~/.claude/projects/-home-bchanot-Documents-claude/*.jsonl` (main-loop files only), keeps composer user prompts (string content, not a slash command, not a tool result) that meet `isTrigger` with `fresh` true for each session's first prompt and real idle gaps from timestamps, samples 20 with `--seed`, runs the real reader on this repo (`bash lib/memory.sh index` via `Bun.spawnSync`), BM25 top-30, then haiku through `claude -p --model claude-haiku-5-5 --output-format json` with `rerankPrompt` as the prompt, times each call, prints per prompt the prompt's first 120 chars (redacted) and the injected IDs + titles, and totals: asks, injections, mean IDs, timeout share at 3 s. Mode `errors` replays the Bash failures of the same 14 days (main + `*/subagents/*.jsonl`) through `failureLine` + the error index and prints per session the injections and each injected `(line, ID, title)` (redacted). Read-only; writes nothing but stdout. -- [ ] **Step 2 (controller):** run both modes; label each injected entry relevant / not relevant to its prompt or error; show the labels to the user at the merge gate; write `RECALL.md`: counts, the relevant share for each channel, the timeout share, the per-session injection rate, no prompt or error text. -- [ ] **Step 3:** gate input: relevant share < 64 % on either channel, or a timeout share > 25 %, → propose a change (tighter trigger, fewer candidates, `RERANK_MS` 5000) at the merge gate. -- [ ] **Step 4:** commit `chore(bench): phase 4c recall precision measured on 14 days of transcripts`. - -### Task 9: Docs and TODO (sonnet) - -**Files:** `README.md`, `USAGE.md` (French), `CHANGELOG.md` `[Unreleased]`, `ARCHITECTURE.md` (mods line), `.claude/tasks/TODO.md`. -- [ ] Content: recall triggers (first prompt of a context, after 30 min idle, design/analysis words; never slash commands), what is injected and its cap, the known-error line, the digest and its sources, `"recall": false`, the injection log (kept, not shown), residuals (3 s bound drops a share of recalls, the router's classifier label is not used, sub-agents get the error channel only, EVAL not recalled). TODO: 4c sub-bullet "built … merge pending", 4d line: "the injection log now exists (4c), 4d waits on its data", the 4b `shortcut:` harvest line ticked (the lexical superseded reader is gone, Task 1). `make test suite=lib/tests/doctrine-citers.test.sh` green. -- [ ] commit `docs: memory recall, known-error line and session digest`. - -### Task 10: Live proof (controller + user) - -- [ ] **Headless:** a `mktemp -d` repo on a feature branch, `.claude/memory/blockers.md` fixture with a BLK whose backticked span is `` `fatal: unable to access probe remote xyz` ``, `claude -p --model haiku` runs `git ls-remote https://127.0.0.1:9/probe.git` style command failing with that text (or a script echoing it to stderr with exit 1), then reports the context lines it saw: expect `memory: known BLK-001 …`. -- [ ] **Interactive (user):** in a fresh session in this repo, a design prompt → the transcript holds one `memory recall:` attachment on that prompt; `/compact` → the next session-start context holds `memory digest:`; record both in the contract § PROOF. -- [ ] `make test` all green; `shellcheck ./*.sh hooks/*.sh lib/*.sh` clean. - -## R2 CHANGES (challenge r1: correctness CONCERNS(5), robustness CONCERNS(4), simplicity CONCERNS(1); no BLOCKER; these override the task text above) - -Task split: Task 4 becomes **4a** (switch key, log store, ledger and its resets: IR6, IR9, IR11 + the tests below) and **4b** (trigger, BM25 candidates, rerank: IR1-IR5, IR7, IR8, IR10, IR12, TIMErules). Task 5 depends on 4a only. - -Task 0 (rob 11): tell the user before Task 1 that the working-tree mod is live in their sessions and the executors' from the first save, and that adding `"recall": false` to `~/.claude/memory.json` themselves is the kill switch during the build. - -Task 1 — reader: -- `boot` in register.test.ts gains one `process.run` bottom driven by a World field (default: a literal `memory.sh index` stdout matching the fixture registries, BLK-001 open, LRN-002 superseded), so IDX1, the order test and NT1b keep their meaning; IDX3 is re-anchored on that stdout; SR3-SR5 set the field to throw / exit 2 / hang (corr 3). -- `parseIndex` returns `Map<id, {status, title}>`; titles come from memory.sh (fence-aware, tag and date stripped), `entriesOf` only splits bodies (heading regex = 4b `HEADING` widened to `BDR|LRN|BLK`, no title capture); EN1's title oracle moves to SR1 (simp 2). -- Bounded captures carry no `$`: the label regex takes `.{0,2000}` as a prefix of the line, the heading `[^\n]{0,300}` likewise; tests at a 2 001-char Decision (lesson still cut at 280) and a 320-char heading (still an entry) (corr 4, rob 5). -- `loadRegistries($, root, names)`: the 4b callers (`pendingAnswer`, `newFailureCount`) pass `['blockers.md', 'learnings.md']` and keep their `index:` line unchanged; recall passes the three files (simp 3). -- Status unavailable: `memory_pending` still labels NEW/known from all entries (advisory), with `status reader unavailable` on the `index:` line; injections stay off (rob 7). -- A real-registry check in the test (skipped when the repo files are absent): the `entriesOf` IDs equal the `parseIndex` IDs on this repo (rob 6). -- `isLive`: an ID absent from the map while the map exists is NOT live (fail closed on AC3) (rob 6). -- `process.run` is skipped when no registry file was read (rob 3). - -Task 2 — errno phrases: `input/output error` is listed as `<path> error` (normalize already turned `input/output` into `<path>`); ER case for it (corr 7, rob 14). - -Task 3 — harness-facing exports: export `isTrigger`, `IDLE_MS`, `DESIGN_RULE`, `ANALYSIS_RULE` and a `failureKey(text, command)` wrapper of the `buildFailure` chain (tail → redact → lastLine → normalize) for the harness (simp 5, corr 12). - -Task 4a — ledger: -- The main key's `spent` resets on EVERY composer non-mid-turn prompt (outside the trigger branch); test: recall on prompt 1, ordinary prompt 2, then a known error is injected (corr 1, rob 1). -- One context-start call site: the `classic.SessionStart` hook on `startup | clear | compact` (not `session.start`); `resume` changes nothing; a `classic.SessionStart` carrying `agent_id` resets only that agent's key; `session.end` clears by the ending session's id only; keys use `$.session.id()` (corr 9, simp 4). -- A missing `lastPrompt` means not idle (rob 10). -- Check-and-record of `seen`/`spent` run synchronously after the last await; test: two concurrent failing Bash calls → one injection (rob 9). -- The log: `saveProject` persists `log`; the sweep keeps a project key that still holds a log (it drops sessions first); test: an injection, then a failure capture, then a sweep → the log still holds the record (corr 11, rob 8). -- Switch: an absent `enabled` key with `"recall": false` logs nothing; only a present non-boolean logs (corr 6). - -Task 4b — trigger and rerank: -- Registries load once per `prompt.submit` and are shared by the 4b note and recall (rob 3). -- A consecutive-failure pause for the rerank, modelled on the router's: 3 failed or timed-out reranks in a row → no rerank for 15 min (in the closure), reset on a success; test (rob 3). - -Task 5 — sub-agent delivery of the known line is verified headless in Task 10 or listed as a residual (corr 10). - -Task 7 — digest (corr 2, 8, 13; rob 2, 13; simp 1): -- Open BLK come from `bash "$_mem_lib" -C "$root" index blocker` (rows `| ID | date | title | status |`, status `open` listed, `upstream` counted), NOT `reconcile_blk_open`; reconcile.sh is not sourced. -- The digest runs in a subshell: `( _memory_digest "$root" ) 2>/dev/null || true`; the lib path is `$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh` (like the neighbours), never `$_repo_dir` (unset by then). -- stdin is read at the TOP of session-start.sh, behind `command -v timeout jq` (without them: no source, the digest prints only on an empty-stdin manual run, never guessed as startup). -- Cuts are char-safe (awk under a UTF-8 locale, or `cut -c` checked with a non-ASCII SD6 line containing `—`). -- SD9: a digest that hits an unset variable still exits 0 and leaves the banner intact. - -Task 8 — harness (corr 5, 12, 15; rob 4; simp 5): -- Prompts from main-loop files whose `entrypoint == "cli"` only (no `sdk-*` sessions); the walk reuses `noise.py`'s `pairs_of`/`find_files` logic as reference (ported in TS, the source named). -- haiku runs from a `mktemp -d` cwd with `--setting-sources local`, no tools; latency from the JSON `duration_api_ms`, labelled an upper bound. -- Every share is reported with its n; fewer than 10 injections on a channel → "insufficient sample" at the gate, not a pass or a fail. - -Task 9 — docs: also the plugin.json `description` and the register.ts header comment (no version bump) (simp 6, corr 14). - -Task 10 — headless recipe copies LRN-260 (`GITFLOW_NO_PUSH=1`, `--allowedTools` naming the one probe command) (rob 12); a memory fixture body is written with Write + `--body-file`, never a heredoc quoting an extraction command (extract-guard, LRN-262). - -## R3 CHANGES (confirmation pass: correctness CONCERNS(4), no BLOCKER; these override R2 and the task text) - -- **Split order (conf 1).** 4a keeps only what it can show at its own commit: the switch-key logging (corr 6 test) and log retention (a `log` seeded in the store, then a failure capture and a sweep: the log survives). IR6, IR9, IR11, the spent-reset test and the log-after-injection test move to 4b; the two-concurrent-failures test moves to Task 5. Task 5 depends on 4a and 4b. -- **Real-registry parity (conf 2).** The `entriesOf` IDs == `parseIndex` IDs check runs in a shell suite (a new case in `lib/tests/memory.test.sh`, bun one-liner importing the two functions, EVAL rows filtered), and FAILS when the registries are absent; it is not a kit test. -- **Status unavailable (conf 3).** `buildIndex(entries, undefined)` indexes ALL entries (advisory); SR3-SR5 oracles: the SR2 failure reads `known BLK-001` and the `index:` line ends `status reader unavailable`; recall and the error channel inject nothing. A spec-amendment step (end of Task 9) rewrites spec Units 1, 2 and 5 for the four R2 deviations (status unavailable labels, `classic.SessionStart` as the context-start site, titles from memory.sh, digest from `memory.sh index blocker`). -- **Entry assembly (conf 4).** Export a pure `assembleEntries(texts: string[], index: Map<string, {status, title}>): Entry[]` that joins kind, the memory.sh title cut at 100 with `…`, `lessonOf`, and the body; `loadRegistries` and the harness both use it; the harness imports also `recallLine`. -- **Digest tests (conf 5, 6, 7, 8).** SD9 = a copy of the script beside a fake `lib/memory.sh` that exits 2, then one that prints malformed rows, and a `blockers.md` that is a directory: exit 0, banner intact, no digest. The block cap drops whole lines from the end until ≤ 800 chars (never a mid-line cut); SD7 uses long TODO items and a long journal line. Cuts use bash `${v:0:159}…` under the inherited locale, with an SD6 line containing `—` checked to stay valid UTF-8 (`iconv -f UTF-8 -t UTF-8` succeeds); no `cut -c`. Without `timeout` or `jq`: the digest prints only when stdin is a terminal (`[ -t 0 ]`, a manual run), never from a hook; SD10 runs with a PATH lacking jq and a piped `{"source":"resume"}` → no digest. -- **Kill switch wording (conf 9).** Task 0 tells the user: before 4a lands, `{"enabled": false}` is the kill switch; from 4a on, `{"enabled": true, "recall": false}` cuts injections only. -- **Test world (conf 10).** Tests drive the `process.run` World field, never add a second bottom; the test at register.test.ts ~885 (expects `known LRN-002` after editing the file to open) sets its own stdout with LRN-002 open. -- **Errno phrase (conf 11).** `deErrno` runs on the lowercased line BEFORE `normalize`'s PATH step for `input/output error` only (a dedicated literal replacement), the other phrases after normalize as planned; ER case. -- **Log size (conf 12).** The log lives in its own store key `l:<root>` (≤ 200 records, ≤ 64 KiB, oldest dropped), outside the session sweep; `loadProject`/`saveProject` untouched. -- **/clear event (conf 13).** Task 10's interactive check includes a `/clear` then an ordinary prompt: the transcript shows one `memory recall:` on it; the context-start key uses the event's `session_id` when present, else `$.session.id()`. If `clear` never fires, it is reported as a residual at the merge gate. -- **Discriminating fixtures (conf 14).** The spent-reset test uses a 3-entry recall of ~1 150 chars and a known line of ~400 chars (old code: dropped; new: injected); TE7 reaches its spent level through crafted injections, the lengths stated in the test. -- **API and references (conf 15).** `$.model.complete` gets `{model, prompt, maxTokens, effort}` only if the d.ts does not type `timeoutMs` (check the d.ts; the own 3 s race stays either way); the TODO `shortcut:` tick is in Task 9; `isTrigger`, `IDLE_MS`, `DESIGN_RULE`, `ANALYSIS_RULE` are produced by 4b. diff --git a/docs/superpowers/specs/2026-11-04-memory-recall-design.md b/docs/superpowers/specs/2026-11-04-memory-recall-design.md deleted file mode 100644 index 30e8c87..0000000 --- a/docs/superpowers/specs/2026-11-04-memory-recall-design.md +++ /dev/null @@ -1,179 +0,0 @@ -# Phase 4c memory recall — design (2026-11-04) - -BDR-125 phase 4c, host `mods/memory` (BDR-137). Contract -`.claude/tasks/contracts/2026-11-04-memory-recall-1859.md` (brainstorm answers -0-11 `[gated 2026-11-04]`). Engine facts: -`.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md` (CLI 2.1.318). -Branch `feature/memory-recall`. - -## Goal -The registries hold the lessons; nothing brings them back when they matter. -4c brings back the right entries at three moments, without noise: when a -design or analysis prompt starts work, when a known error comes back, and at -the start of every context. Writing is untouched (4b capture, memory.sh). -Success: precision of the injected entries at or above the 14/22 baseline -(64 %), the error channel's noise measured before shipping, a digest seen -after a real compaction. - -## Unit 1 — shared reader (register.ts) -- Status and titles: `lib/memory.sh -C <root> index` through `$.process.run(['bash', - <HOME>/.claude/lib/memory.sh, '-C', root, 'index'], {timeoutMs: 2000})`, - raced by an own 2.5 s timer; rows `| ID | Date | Title | Status |`. memory.sh - is the single reader (BDR-129): `parseIndex` returns `Map<id, {status, - title}>`, the title already fence-aware with tag and date stripped, and an ID - is closed for recall when its status word is `superseded` or `deprecated`. - An ID absent from a map that exists is not live (fail closed). The script - path is `$HOME/.claude/lib/memory.sh`. The run is skipped when no registry - file was read. -- Status unavailable (failed, timed out or malformed read): `memory_pending` - still labels each failure `NEW` or `known <ID>` from ALL entries (advisory, - superseded ones included) and its `index:` line ends `status reader - unavailable`; recall and the error channel inject nothing. -- Entries: `decisions.md`, `learnings.md`, `blockers.md` read with `$.fs.read` - (stat first, 4 MiB cap per file). `entriesOf` only splits bodies (heading - regex = the 4b one widened to `BDR|LRN|BLK`, no title capture); the pure - `assembleEntries(texts, index)` joins kind, the memory.sh title cut at 100 - with `…`, the lesson and the body into `{id, kind, title, lesson, body}`. - 4b callers load `blockers.md` and `learnings.md` only. -- Lesson line: BDR the `Decision` field; LRN `Apply`, else `Future - application`, else `Pattern`; BLK `Solution`, else `Real cause` (label match - case-insensitive, bold or plain); its first sentence, cut at 280 chars with - `…`; none → empty lesson (title only). Label and heading regexes carry - bounded prefixes (`.{0,2000}`, `[^\n]{0,300}`), no `$`. -- The 4b lexical `isSuperseded` and its `shortcut:` comment are gone: the error - index takes its live set from the same status map. - -## Unit 2 — intent recall (`prompt.submit`) -- Trigger: origin `composer`, `turnId` absent, not a slash command (text not - starting `/`), ≥ 12 code points, and at least 5 content words (tokens minus - the stop-word list; measurement gate 2026-11-05, `MIN_CONTENT_WORDS`), and - one of: the first such prompt of the context (set at `session.start` and - consumed by the first qualifying prompt; a new context starts through the - classic `SessionStart` hook on source `startup`, `clear` or `compact`, keyed - by the event's `session_id` when present, else `$.session.id()`); the first - after ≥ 30 min without a composer prompt in this session; a match of the - design or analysis keyword patterns, copied from model-router's default - prompt rules (`mods/model-router/hooks/register.ts`, commit 9bbd1d5): - `plan|planifie|planning|brainstorm|architecture|con[cç]ois|design` and - `pourquoi|why|explique|explain|analyse|analyze|comprendre|understand|review|audit`, - same word boundaries. -- Rank: BM25 (k1 1.2, b 0.75) over title + lesson + body of the live - BDR/LRN/BLK entries, tokens = lowercase letter/digit runs of ≥ 2 chars minus - a short FR+EN stop-word list; the query is the prompt's first 2000 chars, - redacted (4b `redact`). Entries already injected in this context are - removed before ranking. Top 30 with a score > 0. -- Rerank: `$.model.complete({model: 'claude-haiku-5-5', effort: 'low', - maxTokens: 64, timeoutMs: 5000, prompt})`, raced by an own 5 s timer - (`RERANK_MS`; measurement gate 2026-11-05: 29 % of calls ran over 3 s) - (LRN-218). The prompt: the redacted query, the candidates one per line as - `ID | title | lesson`, and the instruction to answer at most 3 IDs, comma - separated, or `none`. The answer is parsed for `(BDR|LRN|BLK)-\d+`, kept - only when the ID is a candidate, at most 3, order kept. -- Inject: one context block `memory recall:` then one line per entry - `<ID> <title ≤ 100> — <lesson>`; the block ≤ 1500 chars (an entry that - would overflow is dropped). No candidate, a `none`, a timeout, a refusal or - any error → nothing attached, the prompt passes unchanged. -- The 4b milestone note on the same prompt is attached first; recall follows. - -## Unit 3 — tool-error recall (Bash `tool.call`) -- After the 4b capture (same failure rule, same redacted line): the failure's - key is matched against the error index (live BLK/LRN, Unit 1); a match whose - ID was not injected in this context attaches `memory: known <ID> <title ≤ - 100> — <lesson>` to the tool answer's `context` (the answer keeps its shape, - LRN-205; spike: the model sees it). -- Common phrases: before gramming, both the entry spans and the failure key - replace each errno phrase by the placeholder `<errno>`; a gram made only of - placeholders is skipped (LRN-258, `<errno>` joins `#`, `<path>`, `<hex>`). - Phrases: no such file or directory, permission denied, command not found, - is a directory, not a directory, file exists, directory not empty, - operation not permitted, no space left on device, connection refused, - connection timed out, broken pipe, resource temporarily unavailable, - invalid argument, too many open files, read-only file system, device or - resource busy, input/output error. -- Main loop and sub-agents (the context key carries the agent id). - -## Unit 4 — ledger, budget, log -- Once per context: `st.seen: Map<contextKey, Set<ID>>`, key = session id + - (`agentId` or `main`); cleared at `session.end`, and the session's keys on - `classic.SessionStart` source `clear` or `compact`. -- Budget: the main loop has 1500 chars per turn, shared by both channels, - reset by each composer prompt; a sub-agent (error channel only) has 1500 - chars for its whole context. -- Log: each injection appends `{at, session, agent, channel: 'prompt' | - 'tool', ids}` to its own store key `l:<root>` (≤ 200 records, ≤ 64 KiB, - oldest dropped), outside the session sweep and the project value; never - displayed; 4d reads it. No cross-root cap (TODO `shortcut:`). - -## Unit 5 — session digest (`hooks/session-start.sh`) -- Reads the hook JSON from stdin only when stdin is not a terminal, with - `timeout 1`; `source` taken with jq. Prints the digest for `startup`, - `clear`, `compact`, and for an empty source (a manual run); never for - `resume`. Without `timeout` or `jq` the source is unknowable: the digest - prints only when stdin is a terminal, never from a hook. -- Only in a project whose git toplevel (else cwd) has `.claude/memory/`: - `memory digest:` then up to four kinds of lines: - open BLK from `memory.sh -C <root> index blocker` (run under `timeout 2`, - rows with status word `open`: `- open: BLK-n title`, ≤ 160 chars each, at - most 3, then `+N more`), the upstream ones counted (`+N upstream`); the first - 3 unchecked `- [ ]` items under `### Actionable` in `.claude/tasks/TODO.md` - (≤ 160 chars each); the last `- ` line of `.claude/memory/journal.md` - (≤ 160 chars). Cuts use bash `${v:0:159}…` and stay valid UTF-8. -- Block ≤ 800 chars. Header, BLK lines, the count line and the journal line - always stay; TODO lines are added in order while they fit, so under the cap - they drop first, whole lines, never a mid-line cut. Any missing file or - section → that line is omitted; nothing to show → no block. Fail silent: a - `memory.sh` that fails, hangs, prints malformed rows or a `blockers.md` that - is a directory never changes the banner or the exit code. -- No SubagentStart twin. - -## Unit 6 — `memory_pending` -Milestones of the earlier stored sessions follow the current session's, -marked `(earlier session)`, same 3-session window; the answer order stays -header, `index:`, milestones, failures. - -## Unit 7 — off switch -`~/.claude/memory.json`: `"enabled": false` cuts everything (4b); -`"recall": false` cuts Units 2 and 3 injections only (capture, the note, the -tool and the log of past injections stay). Read like `enabled` (lazily per -session, a non-boolean logs one line and counts as absent). - -## Docs -README / USAGE (fr) memory sections gain recall, the error channel, the -digest, `"recall": false`, the residuals; CHANGELOG `[Unreleased]`; TODO (4c -ticked at merge, 4d stays deferred with the log now in place). - -## Proof -- Kit tests: reader (status map, lesson per kind, failure → fail open), - trigger (first prompt, idle, keyword, slash and mid-turn excluded), BM25 - order on fixtures, rerank parse (foreign IDs dropped, `none`, timeout, never - settles), budget and once-per-context (reset on compact/clear and - session.end), error channel (known match attaches, ENOENT does not, sub-agent - key), earlier milestones, `recall: false`, log cap; regex costs timed on - 64 KiB (LRN-259). -- Shell suite: the digest on fixture projects (sources, missing files, caps, - `</dev/null`), existing session-start callers unchanged. -- Measured before shipping (LRN-261, EVAL-056): a bun harness under - `.claude/tasks/plans/2026-11-04-memory-recall-spike/` imports the mod's own - functions (no port) and calls haiku through `claude -p --model haiku`: - (a) 20 real composer prompts from 14 days of this repo's transcripts that - meet the trigger: injected IDs per prompt, timeout share at the bound; the - controller labels each injected entry relevant or not, the user checks the - labels; bar: relevant share ≥ 64 % (14/22). (b) the 14-day Bash failure - replay: injections per session and the noise share on the injected ones, - ENOENT lines included. Counts and shares only in the committed notes. -- Live: headless `-p` for the error channel (a failing command matching a - fixture BLK attaches the line); interactive by the user for recall (a design - prompt in a fresh session), and the digest after a real `/compact`. - -## Measurement gates (2026-11-05) -`.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md`: on 14 days of -transcripts the rerank precision is 54 to 61 % against the 64 % bar. Decided: -recall ships on and switchable (`"recall": false`), with a content floor (5 -content words, Unit 2) and `RERANK_MS` 5000 (Unit 2); the injection log feeds -4d. Error channel: n = 3, insufficient sample. - -## Out of scope -Read path triggers, Bash command triggers, critical deny-once, Tier 1, -cross-repo index, `memory_search` tool, reading the router's classifier -label, a SubagentStart twin, injection citation tracking (4d), EVAL in the -recall corpus.