From fefcd9bfd6dddd169cdac50c93ee9041f6723a3e Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 3 Nov 2026 14:55:13 +0100 Subject: [PATCH] docs(spec): phase 4b memory capture design --- .../specs/2026-11-03-memory-capture-design.md | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-03-memory-capture-design.md diff --git a/docs/superpowers/specs/2026-11-03-memory-capture-design.md b/docs/superpowers/specs/2026-11-03-memory-capture-design.md new file mode 100644 index 0000000..9ccd97e --- /dev/null +++ b/docs/superpowers/specs/2026-11-03-memory-capture-design.md @@ -0,0 +1,130 @@ +# Phase 4b memory capture — design (2026-11-03) + +BDR-125 phase 4b. Contract `.claude/tasks/contracts/2026-11-03-memory-capture-0100.md` +(brainstorm answers 1-8 `[gated 2026-11-03]`). Engine facts: +`.claude/tasks/plans/2026-11-03-memory-capture-spike/REPORT.md`. Branch +`feature/memory-capture`. + +## Goal +Capture is the weak link of the memory loop (5 of 7 real errors of 2026-10-23 +had no registry entry). A mod records what failed during a session and the +moments worth capitalizing, and hands them to /capitalize and the CAPITALIZE +steps through one tool. Writing stays exactly as today: the model drafts, the +user approves, `lib/memory.sh` writes. The mod never writes a registry. + +## Unit 1 — mod `mods/memory/` +Layout like model-router (`.claude/rules/mods.md`): `.claude-plugin/plugin.json` +(name `memory`, version 0.1.0, description, author), `hooks/hooks.json` +(`{"modules": ["./register.ts"]}`), `hooks/register.ts`, +`hooks/register.test.ts`, tracked link `skills/memory -> ../mods/memory`. +Off switch: `~/.claude/memory.json` `{"enabled": false}` (read like +model-router's override; any read error → enabled). Fail open on every hook +(`.catch` → `next(e)`, one log line per hook per session). Closure state only; +persistence through `$.store`. + +## Unit 2 — failure capture +- Hook: `tool.call` on `Bash`, after `const out = await next(e)`; the answer + is returned unchanged. +- A failure: `out.isError === true` and `out.text` starts `Exit code ` + digits. + Excluded: texts starting `Permission to use`, containing `haven't granted it + yet`, starting `model-router:`, or containing ``. +- Distinctive line: the last non-empty line of `out.text` after the first line; + none → not captured (`false`, `grep` with no match). +- Entry: `{ line, excerpt, command, agent, at }` where `line` is the redacted + distinctive line (≤ 300 chars), `excerpt` the redacted last 1200 chars of the + text, `command` the redacted command (≤ 300 chars), `agent` true when + `e.agentId` is set, `at` the clock (ms). +- Normalized key: lowercase; numbers → `#`; absolute and relative paths + (`/x/y`, `./x`, `x/y.ext`) → ``; hex runs ≥ 7 → ``; whitespace + folded. The same key twice in a session is stored once (a `count` field + increments). +- Bounds: ≤ 50 entries per session (oldest dropped), entry ≤ 2 KiB after + truncation, the 3 most recent sessions per project kept, the whole store + value ≤ 1 MiB (oldest project sessions evicted first). Every regex over tool + text runs on input capped at 64 KiB (LRN-219). + +## Unit 3 — redaction (before anything is stored) +One function `redact(text)`, applied to line, excerpt and command: +- `NAME=value` where NAME matches `[A-Za-z_]*(TOKEN|API_KEY|SECRET|PASSWORD|PASSWD)[A-Za-z_]*` → `NAME=` (same rule as the rtk env-dump redaction). +- The 7 `/guardrails` SECRET_PATTERNS (skills/guardrails/scripts/checks/apis.py:10-19: Stripe, AWS access key, GitHub token, Slack token, SendGrid key, Supabase secret, private key block) → ``. +- `Bearer ` → `Bearer `; URLs `scheme://user:pass@host` → `scheme://@host`. +- 40-hex SHAs are not secrets and stay. +Test oracle: fixtures written as literal expected strings in the test, never +computed by the redactor (LRN-237); secret-shaped fixtures use the gitleaks +allowlisted shapes (`test-secret-…` and the fake AWS key named in +`.gitleaks.toml`), in files the allowlist covers. + +## Unit 4 — milestones +From successful Bash results (`out.isError` absent), on the main loop only: +- `commit`: the command's first simple command is `git commit` (optionally + `git -C commit`) and the text holds `-m "feat` / `-m 'feat` / `-m feat` + or `fix` (also `feat(` / `fix(` scopes). Other commits are not milestones. +- `finish`: the command runs `gitflow.sh finish` (bash or sh form) and not + `finish chore` (the /capitalize and /close auto-finish, BDR-068). +- `green`: a command containing `make test` that succeeded, when the same + command string (normalized whitespace) failed earlier in the session. +Stored per session with `{ kind, at, label }` (label: the commit subject's +first 80 chars, the branch named by finish if present, or the suite argument). +Note: at the first `prompt.submit` from the composer after a milestone, one +context line is attached: `memory: