diff --git a/.claude/memory/blockers.md b/.claude/memory/blockers.md index 54c5cc7..76b831b 100644 --- a/.claude/memory/blockers.md +++ b/.claude/memory/blockers.md @@ -370,3 +370,16 @@ rules: - **Real cause**: no rule or guard named package/archive extraction into system dirs; the ssh deny rule did not cover vaas-cli ssh; extraction improvised instead of telling the user there was no package manager. - **Solution**: `hooks/extract-guard.sh` (deny before run, quoted remote scripts re-scanned) + soft_deny line + doctrine bullet (list first, extract into a literal mktemp -d path, PATH/PYTHONPATH, no package manager → tell the user). See the extract-guard BDR. - **Status**: resolved 2026-11-05. + +## BLK-043 — detect_plan CLI fallback forks claude from SessionStart hook: recursive fork bomb, OOM, reboot [open] (2026-11-06) +- **Friction**: `make test suite=lib/tests/session-digest.test.sh` (uncommitted SD13 cases) ate 14 GiB in 45 s, 2026-11-05 23:49; earlyoom killed valheim, node, mariadb, docker, audio; kernel OOM; machine rebooted 23:55; all sessions + RC lost. OOM dump: 126 `claude`, 396 `bash`, 124 `sh`. +- **Real cause**: `lib/detect-plugins.sh` `detect_plan` falls back to `claude config get planType` when `$HOME/.claude.json` lacks plan markers. claude 2.1.318 has no `config` subcommand → words read as prompt → full session → its SessionStart hook (`hooks/session-start.sh:158`) calls `detect_plan` again, same HOME → unbounded recursion. SD13 `mkhome` linked `~/.claude/*` but not `~/.claude.json`. Prod survives only via internal flags `tengu_cobalt_compass` + `tengu_harbor` in `~/.claude.json`; flag rename upstream → every session start recurses. +- **Solution**: pending /bugfix (plan `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md`): CLI fallback dropped (default pro), hook recursion guard env marker, suite-wide `claude` stub in PATH + regression cases. +- **Status**: open 2026-11-06, fix in progress. +- **Status (2026-11-06)**: resolved 49aa2ff (hotfix/detect-plan-fork-bomb): CLI fallback dropped, env guard SESSION_START_RUNNING, lib/tests/detect-plan.test.sh red on main lib, green after; merge pending user + +## BLK-044 — claude processes run with oom_score_adj -1000 of unknown origin: OOM killers spare a runaway claude [open] (2026-11-06) +- **Friction**: during the detect_plan fork bomb (2026-11-05 23:49), every `claude`, `bash`, `grep` child carried `oom_score_adj=-1000`; earlyoom and kernel OOM could not kill the runaway, killed every other service instead (valheim, mariadb, docker, networkd, logind) until reboot. Live session 2026-11-06 still shows `-1000`. +- **Real cause**: unknown. Not set by the repo (`lib/cc.sh`, hooks: no OOMScoreAdjust). Suspects: inherited from launcher (dtach under `systemd-run --user --scope`, sshd, or the RC/remote-control process). +- **Solution**: none yet. Next: trace `/proc//oom_score_adj` up the parent chain of a live claude; then set `OOMScoreAdjust` (e.g. 500) on the `cc` scope so a claude runaway dies first. +- **Status**: open 2026-11-06. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index b73d838..7e2149c 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -696,3 +696,8 @@ rules: ## 2026-11-05 - 2026-11-05: extract-guard built on feature/extract-guard (hook, soft_deny, doctrine; verifier CONFORME, security PASS); live in settings working copy; 4c paused at plan r2; merge pending user. + +## 2026-11-06 +- 2026-11-06: machine OOM reboot 2026-11-05 23:55 root-caused: detect_plan `claude config get planType` fork bomb via SessionStart (BLK-043), SD13 fake HOME trigger. /bugfix: 3 lenses → r2 (hotfix off main, worktree), GATE 0 MET, verifier ECARTS(1 SC2016) → CONFORME, security PASS ×2; 49aa2ff. BLK-044 open (oom_score_adj -1000). Merge + Part B pending. +- capitalize pre-compact: 2 learnings (hook never calls claude CLI; worktree ignored symlinks + diff3); TODO BLK-043 merge checked, Part B kept. 4c digest switch committed 4a7ce37. +- 2026-11-06: BLK-043 Part B /hotfix 2f45452: session-digest suite stubs claude CLI (SD0 control, SD15 zero calls), 53/53 under TasksMax=256, security PASS (MEDIUM stub-first-on-PATH queued in TODO shortcut). 4c merge pending user. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 8b9a52e..9e22d3f 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1956,3 +1956,13 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Pattern**: a guard over shell command TEXT is never complete; plan challenges kept finding forms (r1: quote chars used as segment delimiters cut a quoted destination off its option; r2: multi-line quoted scripts split into orphan lines, wrappers hiding carriers, ssh value options, heredoc owner = last command on the line, here-strings read as heredocs, command substitutions cutting argv). Ship narrow: re-tokenize EVERY quoted word holding a blank (no carrier list), run the detector from every watched tool word, refuse unresolvable destinations, and put intent in an `autoMode.soft_deny` line for what text cannot show. - **Context**: extract-guard, feature/extract-guard 2026-11-05. awk traps found by the security gate: `index(substr(txt, i))` per quote/heredoc line = quadratic (1 MB → hook timeout → command RUNS, LRN-196); `RS="\001"` + `all = all $0` drops 0x01 bytes (comment desync); busybox awk slow on per-char appends (cap 64 KiB); the prefilter must run on a de-quoted copy or split tool names skip it. The accepted FP bit its author twice: a memory heredoc quoting a complete extraction command was refused, then the ` ` placeholder too (angle brackets read as redirections) until placeholders were kept as words. - **Apply**: any PreToolUse text guard: prefilter on a de-quoted copy, size cap before parsing, linear tokenizer (forward scans), timed flood tests under gawk + mawk + busybox awk, fail closed only past the prefilter, MISSES in the header + soft_deny as net; text bodies about the guarded command go through Write + --body-file, never a heredoc in the Bash call. + +## LRN-263 — Hooks never invoke the claude CLI; hook-running tests stub it and cap tasks (2026-11-06) +- **Pattern**: hook (or lib a hook calls) never runs `claude` CLI. Removed subcommand (`claude config`) read as prompt → full session → its SessionStart hook re-runs → fork bomb (BLK-043). +- **Context**: `detect_plan` fallback `claude config get planType`, claude 2.1.318; 126 procs, 14 GiB, reboot. +- **Future use**: tests running hooks: PATH stub `claude` (log path expanded at creation, +x, positive control first), run under `systemd-run --user --scope -q -p TasksMax=N`. Grep hooks/lib for `claude ` in review. + +## LRN-264 — Fresh git worktree lacks gitignored symlinks; repo conflicts use diff3 markers (2026-11-06) +- **Pattern**: fresh `git worktree` lacks gitignored symlinks of main tree (`skills/darwin-skill`) → suites reading them go red (run-reconcile T6c): environment, not diff. Recreate link before blaming change. +- **Context**: hotfix worktree 2026-11-06; back-merge conflict used diff3 style. +- **Future use**: worktree setup → mirror ignored symlinks (`git status --ignored`). Conflict resolution here: strip `|||||||` base marker too, not only `<<<<<<<`/`=======`/`>>>>>>>`. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 5a9e5d6..a2f03d2 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -114,10 +114,16 @@ Shared rules for every phase: - Measured recall (5 real FR prompts, 22 relevant entries): BM25 full text 9/22, haiku rerank of lexical top-30 14/22 (~8.5k chars). Error 4-gram match on real errors: BLK-030/031/034 exact, no false positive; 5 of 7 real errors of 2026-10-23 had NO entry: capture is the weak link. - **4b capture (mod).** Failure ledger: tool results with isError, deny or non-zero exit carrying a distinctive error line → normalized + verbatim + command, REDACTED at capture (rtk-rewrite redaction + gitleaks patterns), bounded ring per session in `$.store` (4 MiB cap), matched against the registry error index; unmatched = new failure modes. Milestones: feat/fix commit, `gitflow finish`, a suite red then green. `memory_pending` tool returns unmatched failures + milestones; /capitalize, /close and every CAPITALIZE step call it first; one context note at the next prompt after a milestone, never per turn, never at Stop. "Proactive capitalization" paragraph KEPT. Writing always = model draft + user approval + lib/memory.sh. - Built 2026-11-04 on feature/memory-capture (f1d4f9d..HEAD): mod `mods/memory`, kit 100+ cases, consumers wired, noise measured (NOISE.md); merged 2026-11-04 into develop (dfadf8a): GATE 0 MET, verifier criteria 1-15 met (9 proven live), security PASS ×4, BDR-137 - - shortcut: `mods/memory/hooks/register.ts` `isSuperseded` is a lexical reader, not memory.sh's status parser; upgrade = share that parser when 4c needs it (final review M11) - - **4c read side (next).** Two channels only: intent recall at `prompt.submit` for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in `hooks/session-start.sh` on `source: startup|compact|clear` (native matchers; the mod's `session.compact` only skips); a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo scope=global index, `memory_search` tool. + - [x] shortcut (done in 4c, Task 1: the lexical reader is gone, statuses come from `memory.sh index`): `mods/memory/hooks/register.ts` `isSuperseded` is a lexical reader, not memory.sh's status parser; upgrade = share that parser when 4c needs it (final review M11) + - **4c read side (built 2026-11-05 on feature/memory-recall, merge pending).** Two channels only: intent recall at `prompt.submit` for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in `hooks/session-start.sh` on `source: startup|compact|clear` (native matchers; the mod's `session.compact` only skips); a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo scope=global index, `memory_search` tool. - 4c follow-up from the 4b live proof (2026-11-04): `memory_pending` lists milestones of the current session only, so a `/capitalize` run right after `/clear` misses the previous session's `fix:`/finish milestones (they stay in the store). Option: list earlier-session milestones marked `(earlier session)`. Doctrine (capitalize before /clear) covers the normal path. - - **4d feedback and promotion.** DEFERRED until a plain injection log (ID, trigger kind, turn, cited or not) shows misses or noise; then /prune-memory reads it and promotion to a mechanism follows BDR-100. + - **4d feedback and promotion.** Plan r1 (draft, not challenged): `.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md`. Log read 2026-11-05: 1 real record, no decision possible; it cannot show usefulness or misses alone and transcripts live 7 days. Order: 4d.1 log fields `cands` + `ms` → 4d.2 weekly reader (log × transcripts, labels.tsv) → 4d.3 gate (≥20 prompt + ≥10 tool injections, or 5 weeks) with thresholds fixed now → 4d.4 /prune-memory + BDR-100 promotion, conditional. Starts after the 4c merge; 4 open choices in the plan. + - [ ] shortcut: the injection log lives under `l:` store keys (about 28 KiB each, 200 records and 64 KiB at most); `sweepLogs` counts them with the `p:` keys and evicts the oldest log key (by its newest record, never the current root's) once the total nears the engine's 4 MiB store cap; upgrade = one global log key or a smaller per-root cap (`mods/memory/hooks/register.ts`). + - [ ] residual: the pre-existing `memory.sh check` call in `hooks/session-start.sh` is not time-bounded (the digest's `memory.sh index blocker` call is); upgrade = wrap it in `timeout 2`. + - [x] BLK-043 hotfix merged 2026-11-06 (`bd5e661` main, `7e47bea` develop, back-merged into feature/memory-recall `3564e3e`, worktree removed). + - [x] BLK-043 Part B: suite-wide `claude` PATH stub + final empty-log check in `lib/tests/session-digest.test.sh` (SD0/SD15, done 2026-11-06 via /hotfix; security PASS, MEDIUM folded into the shortcut below). + - [ ] shortcut (BLK-043 gate 2 LOWs): `lib/tests/detect-plan.test.sh` unchecked `mktemp -d` (empty WORK → real `claude probe`), `bash -c "source '$LIB'"` interpolation, no `GIT_CEILING_DIRECTORIES` on hook runs; and the memory, graphify-gate, push-guard suites run the hook with no `claude` stub. Upgrade = `|| exit 1` + `command -v claude` assert, positional args, ceiling dir, shared stub helper. Same gap in `lib/tests/session-digest.test.sh` SD0 (gate MEDIUM 2026-11-06): `claude probe` runs before any check that the stub is first on PATH (stub write failure or noexec TMPDIR → real CLI), a red SD0 does not stop the suite; LOW: log path interpolated into the generated stub unquoted. + - [ ] BLK-044: trace origin of `oom_score_adj=-1000` on claude processes; set `OOMScoreAdjust` on the `cc` scope so a runaway claude dies first. - Proof: recall precision on ≥20 real prompts and ≥10 real errors, target ≥ the 14/22 baseline; digest after a real compaction; redaction test on the ledger; `/context` delta; captured-failure demo: an error from session N recalled in session N+1. ### Actionable diff --git a/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md new file mode 100644 index 0000000..eb41772 --- /dev/null +++ b/.claude/tasks/contracts/2026-11-04-memory-recall-1859.md @@ -0,0 +1,83 @@ +# CONTRACT — memory-recall (phase 4c) +- date: 2026-11-04 | flow: ship-feature | branch: feature/memory-recall (off develop 06d2576, created at STEP 4) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +Phase 4c of the context mod queue (BDR-125), TODO.md "Phase 4b-4d, memory v2 capture, read, feedback" — the 4c read side: two channels only: intent recall at `prompt.submit` for classifier labels design/analysis or the first coding prompt after idle (BM25 top-30 over title + lesson + body → haiku keeps ≤3, bounded 3 s, fail open) and tool-error 4-gram match (PostToolUse; a classic hook is acceptable if the mod ledger is not needed). Session digest (open BLK via the status parser, actionable TODO, last journal line) in `hooks/session-start.sh` on `source: startup|compact|clear`; a SubagentStart twin if sub-agents need it. Injection = ID + title + lesson line; superseded never injected; budget ~1.5k chars per turn; once per context. Deferred: Read path triggers, Bash command triggers, "critical → deny once", Tier 1, cross-repo index, `memory_search` tool. Plus the 4b follow-ups queued for 4c: earlier-session milestones in `memory_pending`, common-phrase 4-gram collisions (every ENOENT reads known LRN-056), the lexical superseded reader `shortcut:`. Host: mods/memory (BDR-137). 4d stays deferred until an injection log exists. + +(user brief 2026-11-02, step 3: "Phases 4b à 4d"; launched after the 4b merge, user "merge it" 2026-11-04. Session constraints of that brief hold: default model opus; verifier, security-auditor and plan-challengers pinned on opus; never commit a `/model` or UI write of settings.json (LRN-253); plan text through Write/Edit (BLK-039); destructive steps on the live tree in the main loop after the user's go, `mv` over `rm` (BLK-040).) + +## CLARIFICATIONS +Pass A (gaps found by the STEP 0d read-before, put to the user at the STEP 1 brainstorm; answers land `[gated]`): +- The classifier label is private to model-router (`st.turnMain`, never stored or published) and the classifier never runs on prompts its keyword rules already map (`plan|design|architecture…` → plan, `why|explain|review|audit…` → reflect), nor on slash commands: a trigger "classifier labels design/analysis" read literally misses exactly the design/analysis prompts that say so. +- No uniform "lesson line" exists in the registries (BDR `**Decision**` median 643 chars, max 1989; LRN `Apply` / `Future application` / `Pattern`; BLK `Solution` / `Real cause`; EVAL `Action`): three BDR hits overflow the 1.5k budget unless the line is cut. +- Superseded readers diverge (memory.sh parser vs the 4b lexical reader: BDR-031 live for the lexical one, EVAL-041 falsely superseded for the shell one). +- Engine types 2.1.316 expose `$.state` and `$.process.run` (4b recorded "no `$.state`" from the 2.1.277 types); runtime availability unverified for both; mod `session.start` has no `source`, `classic.SessionStart` does. +- The 4-gram collision: `no such file or` / `such file or directory` belong to LRN-056 only, so every ENOENT reads known LRN-056 (document frequency does not fix it). +- Proof needs ≥ 20 real prompts and ≥ 10 real errors labelled for relevance; precision bar = the 14/22 haiku-rerank baseline (BDR-125 amendment 2, TODO.md:114). + +Brainstorm answers `[gated 2026-11-04]` (user: "continue" to recommendations 0-11, read as yes): +0. Spike first (done: `.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md`): `$.process.run` memory.sh index 128 ms; `classic.SessionStart` fires in a mod with source startup/resume/compact and its `additionalContext` reaches the model; `tool.call` error-answer `context` reaches the model; haiku rerank median ≈ 2 s, tail 5.7-7.3 s, ≈ 4k input tokens. +1. Intent-recall trigger without the router classifier: composer prompt, not mid-turn, not a slash command, ≥ 12 chars, AND (first prompt of a context [startup, /clear, compaction] OR first prompt after ≥ 30 min idle OR a design/analysis keyword match, the router's two default rule lists copied with their source commit). +2. Corpus = live BDR + LRN + BLK (EVAL excluded). Lesson line: BDR `Decision`; LRN `Apply` > `Future application` > `Pattern`; BLK `Solution` > `Real cause`; first sentence cut at 280 chars. Injection line = `ID, title (≤ 100), lesson`; ≤ 3 entries; hard cap 1500 chars. +3. Rerank: BM25 top-30 over title + lesson + body; haiku `claude-haiku-5-5`, effort low, 64 max tokens, gets the prompt + 30 candidates as ID + title + lesson, answers IDs validated against the candidates; own 3 s race (LRN-218); failure or timeout → nothing injected (no BM25-only fallback). +4. Superseded reader = lib/memory.sh (single reader, BDR-129) through `$.process.run(['bash', memory.sh, '-C', root, 'index'])` (spike: works, 128 ms); superseded and deprecated excluded; the 4b lexical `shortcut:` reader is replaced by it for the error index too (BDR-031 becomes superseded as memory.sh says). +5. Tool-error channel in the existing Bash hook (the ledger lives in the mod): a captured failure matching a live BLK/LRN entry attaches `memory: known , title, lesson` to the tool result context; an errno stop-phrase list (no such file or directory, permission denied, command not found, …) drops grams wholly inside a stop phrase at index and match time; main loop and sub-agents; noise measured with the 14-day replay before shipping. +6. Once per context: injected IDs kept in the closure per session and agent; reset at `session.end` and on `classic.SessionStart` compact/clear; the 1500-char per-turn budget covers both channels. +7. Digest in `hooks/session-start.sh`: reads the hook JSON on stdin without blocking under ` …` line, `memory digest:` with `- open:` / `- todo:` / `- journal:` lines; the new suite is `lib/tests/session-digest.test.sh`; the `memory_pending` header `milestones (this session):` becomes `milestones:` with earlier-session lines marked `(earlier session)` (citers updated, BDR-100). + +## ACCEPTANCE CRITERIA (seed, enriched at STEP 3 `[gated]`) +1. Intent recall: on the qualifying prompts (trigger decided at the brainstorm), the mod ranks live registry entries by BM25 over title + lesson + body, asks a small model to keep ≤ 3, bounded in time, and attaches them as context (ID + title + lesson line); any failure or timeout attaches nothing and passes the prompt through unchanged. +2. Tool-error match: a captured tool failure whose error line shares a 4-gram with a live BLK/LRN entry attaches that entry (ID + title + lesson line) as context; the common-phrase collision (ENOENT → LRN-056) no longer fires. +3. Superseded entries are never injected; the superseded reader is decided at the brainstorm and its verdicts agree with lib/memory.sh on this repo's registries (an independent oracle, LRN-237). +4. Budget: at most ~1.5k chars of injected recall per turn; an entry is injected at most once per context (reset on /clear and compaction). +5. Session digest: `hooks/session-start.sh` prints open BLK (status parser), actionable TODO and the last journal line on `source` startup|compact|clear, bounded in size; runs unchanged with ` 25 % → propose 5 s). + +Digest cap order `[gated 2026-11-05]` (user: "Retirer d'abord les TODO"): over 800 chars the digest drops TODO lines first (last to first), then open-BLK lines; the header, the `+N` count line and the journal line stay. + +Measurement gate `[gated 2026-11-05]` (RECALL.md: prompt channel 19/38 = 50 % relevant < 64 % bar, noise on content-free idle prompts; timeout share 4/20 = 20 %; user: "Plancher de contenu"): no intent recall on a prompt with fewer than 5 content words (`tokensOf` minus stop words); recall ships on and switchable; the 3 s bound stays; 4d reads the injection log. + +Rerank bound gate `[gated 2026-11-05]` (three harness runs: 16/55 haiku calls over 3 s = 29 % > the 25 % bar; 1/55 over 4.5 s and over 5 s; user: "5 s"): `RERANK_MS` = 5000 (own race and `timeoutMs`). After the content floor: 25/41 = 61 % relevant counting entries written after the prompt, 19/35 = 54 % excluding them (RECALL.md). + +Final review gate `[gated 2026-11-05]` (final opus review "Approved with fixes"; user: all three now): (I1) 2-letter FR+EN function words join the stop-word list so the 5-content-word floor drops vague approvals, then a same-seed re-measure; (I2) the store sweep counts `l:` keys and evicts the oldest log key when the store would pass its cap (no total capture outage); (I3) log records carry `trigger` (`fresh` | `idle` | `keyword` | `tool`) and asks that injected nothing are logged with their outcome (`none` | `timeout` | `refused` | `paused`). + +Gates 1-2 decisions `[gated 2026-11-05]` (verifier ECARTS(2) on criteria 7 and 8; security PASS with 2 MEDIUM; user: recommended options): (a) criterion 7 — `{"enabled": false}` in `~/.claude/memory.json` also silences the session-start digest (absent or unreadable file = on; `"recall": false` does not touch the digest); (b) criterion 8 AMENDED — the precision proof is: the whole qualifying population of 14 days (15 prompts after the content floor), several harness runs with the run-to-run range reported (54-75 %, RECALL.md), the error channel reported as an insufficient sample (n = 3), the digest after a real compaction, the noise measured before shipping, and the user's decision "recall ships on and switchable; 4d measures on the injection log" (the ≥ 20 prompts / ≥ 64 % / ≥ 10 errors bar of the seed is not reachable on 14 days of data and is replaced by this, not dropped silently); (c) a repository marked foreign (`git config gitflow.protect false`) gets no recall, no known line and no digest; (d) the store fix: the sweep runs BEFORE the save that could pass the engine cap, and a rejected `set` triggers one sweep-and-retry; a mock store enforcing the cap tests it; (e) the harness passes `--no-session-persistence` to `claude -p`. + +9. `[gated 2026-11-05]` Mod tests: `mods/memory/hooks/register.test.ts` holds the plan's named tests and the mods suite is green; no line of register.ts over 80 columns. + CHECK: cd /home/bchanot/Documents/claude && T=mods/memory/hooks/register.test.ts && for n in SR1 SR3 SR5 LS1 LS4 ER1 ER3 RB1 RB3 RB5 IR1 IR5 IR6 IR7 IR8 IR9 IR11 TE1 TE2 TE4 PM1 PM2; do /usr/bin/grep -q "$n" "$T" || exit 1; done && [ "$(awk 'length($0) > 80' mods/memory/hooks/register.ts | wc -l)" = 0 ] && a=$(make test suite=lib/tests/mods.test.sh 2>&1) && printf '%s\n' "$a" | /usr/bin/grep -q 'all suites green' && echo MOD4C-OK + EXPECT: MOD4C-OK + EVIDENCE: MET exit=0 marker-found :: MOD4C-OK +10. `[gated 2026-11-05]` Digest: `lib/tests/session-digest.test.sh` exists and is green, and the existing session-start callers stay green. + CHECK: cd /home/bchanot/Documents/claude && [ -f lib/tests/session-digest.test.sh ] && a=$(make test suite=lib/tests/session-digest.test.sh 2>&1) && printf '%s\n' "$a" | /usr/bin/grep -q 'all suites green' && b=$(make test suite=lib/tests/memory.test.sh 2>&1) && printf '%s\n' "$b" | /usr/bin/grep -q 'all suites green' && echo DIGEST-OK + EXPECT: DIGEST-OK + EVIDENCE: MET exit=0 marker-found :: DIGEST-OK +11. `[gated 2026-11-05]` Measured before shipping: `.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md` holds, for the prompt channel and the error channel, the injected count n, the relevant share and the timeout share, and no prompt or error text. + CHECK: cd /home/bchanot/Documents/claude/.claude/tasks/plans/2026-11-04-memory-recall-spike && [ -s RECALL.md ] && /usr/bin/grep -qi 'timeout' RECALL.md && /usr/bin/grep -qi 'relevant' RECALL.md && /usr/bin/grep -qE '\bn ?= ?[0-9]+' RECALL.md && echo RECALL-OK + EXPECT: RECALL-OK + EVIDENCE: MET exit=0 marker-found :: RECALL-OK +12. `[gated 2026-11-05]` Whole branch: `make test` all suites green, shellcheck clean on the health stack, settings.json untouched by the branch's own commits (the develop merge excepted). + CHECK: cd /home/bchanot/Documents/claude && t=$(make test 2>&1) && printf '%s\n' "$t" | /usr/bin/grep -q 'all suites green' && shellcheck ./*.sh hooks/*.sh lib/*.sh && [ -z "$(git diff develop...HEAD --stat -- settings.json)" ] && echo BRANCH4C-OK + EXPECT: BRANCH4C-OK + EVIDENCE: MET exit=0 marker-found :: BRANCH4C-OK + +## FILE SCOPE (seed, final at STEP 3 `[gated]`) +- mods/memory/hooks/register.ts, mods/memory/hooks/register.test.ts (host, BDR-137); mods/memory/.claude-plugin/plugin.json (version) +- hooks/session-start.sh and the suites that run it (lib/tests/memory.test.sh, push-guard.test.sh, graphify-gate.test.sh) if its output changes +- lib/memory.sh only if a read helper is needed (no write path change) +- README.md, USAGE.md, CHANGELOG.md, ARCHITECTURE.md, .claude/tasks/TODO.md +- .claude/tasks/plans/ (spike and measurement notes), docs/superpowers/{specs,plans} (transient), this contract + +## PROOF (Task 10) +- Headless (2026-11-05, `claude -p --model haiku`, live user settings, mod `memory@skills-dir` from this branch, scratch repo on `feature/probe` with a fixture `BLK-001` whose friction line holds the backticked error, `GITFLOW_NO_PUSH=1`, `--allowedTools 'Bash(sh probe.sh)'`): the failing `sh probe.sh` printed the fixture error; the model quoted the tool-result context line `memory: known BLK-001 probe remote unreachable from the sandbox — Use the local mirror path instead of the remote URL.` PASS. Script `$CLAUDE_JOB_DIR/tmp/proof10/run.sh`, log `out.jsonl` beside it. +- Interactive (user, 2026-11-05 18:35-18:42, fresh session in this repo on feature/memory-recall): session 236ca087: `memory digest:` in the SessionStart context (line 9); the composer prompt "conçois un plan pour la phase 4d …" carries one `memory recall:` attachment (line 20, BDR-125). `/clear` → session 14360e08: `memory digest:` at its SessionStart (line 7); the prompt "explique pourquoi le digest …" carries one `memory recall:` (line 22, LRN-099: an off-topic pick, counted as a miss). `/compact` → compaction summary (line 114) then `memory digest:` on the following SessionStart (line 127). PASS: recall in a fresh context, recall again after /clear (classic.SessionStart clear observed through its effect), digest on startup, clear and compact. diff --git a/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md b/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md new file mode 100644 index 0000000..b79412b --- /dev/null +++ b/.claude/tasks/contracts/2026-11-06-detect-plan-fork-bomb-0105.md @@ -0,0 +1,53 @@ +# CONTRACT — detect-plan-fork-bomb +- date: 2026-11-06 | flow: bugfix | branch: hotfix/detect-plan-fork-bomb (worktree /home/bchanot/Documents/claude-hotfix-wt, off main 4093cca) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +oui lance le bugfix maintenat pour regler cette escalade et met dnas blockers + +(context, the bug as received: `make test suite=lib/tests/session-digest.test.sh` filled the RAM, OOM, machine reboot 2026-11-05 23:55; root cause `lib/detect-plugins.sh` `detect_plan` falls back to `claude config get planType`, which starts a full session whose SessionStart hook calls `detect_plan` again: recursive fork bomb. Plan: `.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md` r2.) + +## CLARIFICATIONS +Q: landing branch? / A: hotfix/* off main, in a separate git worktree; finish merges main + develop; the session-digest stub (Part B) goes to feature/memory-recall after. [gated 2026-11-06] +Q: safety order / A: NEVER run `hooks/session-start.sh`, `make test` (any form) or any suite that runs the hook, in either tree, before fix 1 is on disk in the worktree. The red proof runs `detect_plan` directly (no hook) with the `claude` stub on PATH. Every suite run goes through `systemd-run --user --scope -q -p TasksMax=256`. Never run the real `claude` CLI. [gated 2026-11-06] +Q: BLK entry / A: BLK-043 (fork bomb, open → resolved at commit) and BLK-044 (oom_score_adj -1000, open) written 2026-11-06. [gated 2026-11-06] + +## ACCEPTANCE CRITERIA +1. `detect_plan` in the worktree calls no `claude` CLI; the vulnerable call exists on main (positive control). + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && git show main:lib/detect-plugins.sh | grep -q 'claude config get planType' && ! grep -nE '(^|[^A-Za-z_./-])claude[[:space:]]+[a-z-]' lib/detect-plugins.sh && echo C1_NO_CLI + EXPECT: C1_NO_CLI + EVIDENCE: MET exit=0 marker-found :: C1_NO_CLI +2. Regression suite `lib/tests/detect-plan.test.sh` exists and passes on the fixed tree, contained. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && test -f lib/tests/detect-plan.test.sh && systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/detect-plan.test.sh && echo C2_GREEN + EXPECT: C2_GREEN + EVIDENCE: MET exit=0 marker-found :: detect-plan: 9 passed, 0 failed C2_GREEN +3. Symptom reproduced: the same suite FAILS when pointed at main's `lib/detect-plugins.sh` (the suite takes the lib path from `DETECT_PLUGINS_LIB`, default the repo copy), and the stub, not a real `claude`, caught the call. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && git show main:lib/detect-plugins.sh > /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/main-detect-plugins.sh && if DETECT_PLUGINS_LIB=/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/main-detect-plugins.sh systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/detect-plan.test.sh >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/c3.out 2>&1; then false; else grep -q 'FAIL T1-no-json-calls' /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/c3.out && echo C3_RED_BEFORE; fi + (amended 2026-11-06 by the orchestrator before GATE 0: same check, literal scratchpad paths instead of `rm -rf "$t"`; fail line pinned to the regression case) + EXPECT: C3_RED_BEFORE + EVIDENCE: MET exit=0 marker-found :: C3_RED_BEFORE +4. The suite proves its stub is reached (positive control: a `claude` call through PATH logs exactly 1 line before the absence checks), calls `detect_plan` directly with a HOME holding no `.claude.json` and asserts output `pro` with 0 new logged calls. + (judged by the verifier from the suite source) +5. Recursion guard: `hooks/session-start.sh` exits 0 with no output when `SESSION_START_RUNNING` is set, and otherwise exports `SESSION_START_RUNNING=1` before any child process. The suite asserts both: an early-exit case, and a child of the hook (a PATH stub `git`) that records `1`. The hook comment states the guard is defense-in-depth with no live caller and relies on Claude Code passing env to hooks. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && grep -q 'SESSION_START_RUNNING' hooks/session-start.sh && grep -q 'SESSION_START_RUNNING' lib/tests/detect-plan.test.sh && echo C5_GUARD_PRESENT + EXPECT: C5_GUARD_PRESENT + EVIDENCE: MET exit=0 marker-found :: C5_GUARD_PRESENT +6. Dead code removed: `detect_plan` docstring says it returns max or pro (no free); the `free)` arm of the plan `case` in `hooks/session-start.sh` is gone. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && ! grep -nE '^[[:space:]]*free\)' hooks/session-start.sh && ! grep -niE 'max, pro, or free' lib/detect-plugins.sh && echo C6_NO_DEAD + EXPECT: C6_NO_DEAD + EVIDENCE: MET exit=0 marker-found :: C6_NO_DEAD +7. shellcheck clean on the three files. + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && shellcheck lib/detect-plugins.sh hooks/session-start.sh lib/tests/detect-plan.test.sh && echo C7_LINT + EXPECT: C7_LINT + EVIDENCE: MET exit=0 marker-found :: C7_LINT +8. Full suite green once, contained (LRN-209: one full run before finish). + CHECK: cd /home/bchanot/Documents/claude-hotfix-wt && systemd-run --user --scope -q -p TasksMax=512 make test >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/hotfix-maketest.log 2>&1; rc=$?; tail -5 /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/fb6518b7-0114-4bfb-9d49-04965b322457/scratchpad/hotfix-maketest.log; [ "$rc" -eq 0 ] && echo C8_SUITE_GREEN + EXPECT: C8_SUITE_GREEN + EVIDENCE: MET exit=0 marker-found :: GREEN ✓ G3 strict-YAML: all agents/*.md frontmatter parse GREEN ✓ G4 hermetic: run-reconcile.sh reads fixtures only, not the live registry G… + +## FILE SCOPE +In /home/bchanot/Documents/claude-hotfix-wt only: +- lib/detect-plugins.sh (detect_plan) +- hooks/session-start.sh (guard at top; `free)` arm) +- lib/tests/detect-plan.test.sh (new) +Nothing in /home/bchanot/Documents/claude (the feature/memory-recall tree and its uncommitted work). diff --git a/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md b/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md new file mode 100644 index 0000000..6c3f8fb --- /dev/null +++ b/.claude/tasks/contracts/2026-11-06-session-digest-claude-stub-1439.md @@ -0,0 +1,22 @@ +# CONTRACT — session-digest-claude-stub +- date: 2026-11-06 | flow: hotfix | branch: feature/memory-recall +- status: active + +## REQUEST (verbatim — IMMUTABLE) +BLK-043 Part B on feature/memory-recall: in lib/tests/session-digest.test.sh add a suite-wide PATH stub for `claude` (log path expanded at creation, chmod +x, positive control first: call `claude` via PATH, assert 1 logged line), then a final cumulative check that the stub log has no line from any hook run of the suite. Plan: .claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md r2 (R2, R5, R6: first run under `systemd-run --user --scope -q -p TasksMax=256`). Single test file. + +## CLARIFICATIONS +Q: safety / A: every run of the suite goes through `systemd-run --user --scope -q -p TasksMax=256`; never run the real `claude` CLI. [gated 2026-11-06] + +## ACCEPTANCE CRITERIA +1. Stub present, reached, and hook runs log no call; suite green, contained. + CHECK: cd /home/bchanot/Documents/claude && systemd-run --user --scope -q -p TasksMax=256 bash lib/tests/session-digest.test.sh >/home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/049658c4-3f30-4849-8ba6-906177262d8a/scratchpad/sd.out 2>&1 && grep -q 'failed$' /home/bchanot/.cache/claude-tmp/claude-1000/-home-bchanot-Documents-claude/049658c4-3f30-4849-8ba6-906177262d8a/scratchpad/sd.out && echo C1_GREEN + EXPECT: C1_GREEN +2. The stub is written with the log path expanded at creation, `chmod +x`, exported on PATH before the first case; a positive control (SD0) asserts 1 logged line; the log is then emptied; a final check (SD15) after all cases asserts 0 lines. + (judged from the suite source) +3. shellcheck clean. + CHECK: cd /home/bchanot/Documents/claude && shellcheck lib/tests/session-digest.test.sh && echo C3_LINT + EXPECT: C3_LINT + +## FILE SCOPE +- lib/tests/session-digest.test.sh diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md new file mode 100644 index 0000000..858a06f --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/CHALLENGE-r1.md @@ -0,0 +1,19 @@ +# 4c plan r1 challenge (2026-11-04) — synthesis for the r2 revision (paused for the extract-guard /feat) + +Verdicts: correctness CONCERNS(5), robustness CONCERNS(4), simplicity CONCERNS(1). No BLOCKER. Full reports in the session transcript; findings to apply in r2: +- Budget: reset the main key's `spent` on every composer non-mid-turn prompt, not only on trigger prompts; test recall → ordinary prompt → known error injected (corr 1, rob 1). +- Digest: read open BLK through `bash memory.sh -C index blocker` (titles + status word, 17 ms) instead of sourcing reconcile.sh (`set -uo pipefail` leaks, `$_repo_dir` unset, no titles, 296-420 ms); run the digest in a subshell `( … ) 2>/dev/null || true`; lib path from `$(dirname "${BASH_SOURCE[0]}")/../lib`; read stdin at the top of the script behind `command -v timeout jq`; char-safe cuts (non-ASCII SD6) (corr 2, 8, 13; rob 2, 13; simp 1). +- Test world: `boot` gains a `process.run` bottom driven by a World field (default literal index stdout matching REGS: BLK-001 open, LRN-002 superseded) so IDX1, the order test, NT1b keep their meaning; IDX3 re-anchored; SR3-5 set throw / exit 2 / hang (corr 3). +- Regexes: no `$` after bounded captures (heading `[^\n]{0,300}`, label `.{0,2000}` as prefixes); tests at 2001 chars and a 320-char heading; entriesOf IDs == parseIndex IDs on this repo (corr 4, rob 5, rob 6). +- Harness: main-loop files with `entrypoint == "cli"` only; haiku from a `mktemp -d` cwd with the spike's isolation (`--setting-sources local`, tools off); latency from `duration_api_ms`, labelled upper bound; import `isTrigger`, `IDLE_MS`, rules, and an exported `buildFailure`/`failureKey`; reuse noise.py `pairs_of`/`find_files` as the walk reference; report n beside each share, < 10 injected = "insufficient sample" (corr 5, 12, 15; rob 4; simp 5). +- Latency stacking: load registries once per prompt.submit, shared by note and recall; skip `process.run` when no registry file was read; consecutive-failure pause for the rerank modelled on the router's (3 fails → cooldown) (rob 3). +- Switch: `{"recall": false}` alone must not log SWITCH_INVALID for an absent `enabled` (corr 6). +- `input/output error` → ` error` after normalize, or run deErrno before PATH; ER case (corr 7, rob 14). +- Ledger scope: clear by session id at session.end; `classic.SessionStart` with `agent_id` resets only that agent's key; use `$.session.id()`; one call site for context start (classic.SessionStart startup|clear|compact), not session.start (corr 9, simp 4); missing `lastPrompt` = not idle (rob 10). +- Log: `saveProject` persists `log`; sweep keeps it or a separate `l:` key; test injection → capture → log kept (corr 11, rob 8). +- Concurrency: check-and-record of `seen`/`spent` synchronous after the last await; two-concurrent-failures test (rob 9). +- Loader: `loadRegistries($, root, names)`; 4b callers keep two files and their `index:` line; recall reads three; `parseIndex` returns `{status, title}` and titles come from memory.sh (simp 2, 3). +- Status unavailable: index all entries for the advisory NEW/known label in memory_pending; injections stay off (rob 7). +- Task 4 split into 4a (switch, log store, ledger) and 4b (trigger, rerank) (simp 7). +- Docs: plugin.json description and register.ts header comment; no version bump (simp 6, corr 14). +- Live safety: Task 0 tells the user that `"recall": false` in `~/.claude/memory.json` is the kill switch during the build (rob 11); Task 10 headless recipe copies LRN-260 (`GITFLOW_NO_PUSH=1`, `--allowedTools`) (rob 12); sub-agent delivery of the known line checked headless or listed as residual (corr 10). diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md new file mode 100644 index 0000000..6fb34c4 --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/RECALL.md @@ -0,0 +1,35 @@ +# Phase 4c recall measured on 14 days of transcripts (2026-11-05) + +Harness: `recall-bench.ts` (bun) imports the mod's own functions (`isTrigger`, `bm25Rank`, `rerankPrompt`, `parseIds`, `assembleEntries`, `failureKey`, `buildIndex`, `matchOf`…); statuses from `lib/memory.sh index`; haiku `claude-haiku-5-5` through `claude -p` from a `mktemp -d` cwd with `--setting-sources local`, no tools. Counts and shares only; no prompt or error text here (LRN-124). + +## Prompt channel + +Population: main-loop transcripts with `entrypoint == "cli"`, user entries with `origin.kind == "human"` (typed prompts), not meta, not compaction summaries: 65 prompts, 11 older entries skipped (no `origin` field), 24 meet the trigger, 20 sampled (seed 42). A first run sampled `` and summary entries (origin `task-notification` / `isCompactSummary`, never seen by the mod's `composer` gate): discarded as a measurement. + +| measure | value | +|---|---| +| asks | n = 20 | +| injections (prompts with ≥ 1 entry) | 15 / 20 | +| entries injected | n = 38 (2.5 per injection) | +| relevant entries (controller labels) | 19 / 38 = 50 % | +| relevant on prompts with ≥ 5 content words (estimate) | 16 / 28 = 57 % | +| bar (BDR-125 amendment 2, haiku rerank baseline) | 14 / 22 = 64 % | +| haiku `duration_api_ms` > 3000 (upper bound) | 4 / 20 = 20 % (first run: 7 / 20) | + +The noise sits on content-free prompts triggered by idle time (short approvals): 0 relevant of 10 injected. Prompts with a topic recall the right entries. Caveat: the harness reads today's registries, so entries written after a prompt can be recalled for it (temporal leakage): the true shares are somewhat lower. + +## Error channel + +36 Bash failures keyed over 14 days (main + sub-agents), 3 known-line injections (2 sessions): one exact lesson, two plausible. n = 3: insufficient sample. + +## Decision (2026-11-05) + +User: "Plancher de contenu" — no intent recall on a prompt with fewer than 5 content words (stop words excluded); recall ships on and switchable (`"recall": false`); the injection log (4c) feeds the 4d measurement on real use. The 3 s rerank bound stays (timeout share 20 % < 25 %). + +## After the content floor (debdead) and the bound decision + +Same harness, same seed: 15 prompts meet the trigger (was 24), all sampled; 14 injections; n = 41 entries; relevant 25 / 41 = 61 % counting entries written after the prompt (temporal leakage, 6 entries), 19 / 35 = 54 % excluding them. Still under the 64 % bar; the misses are vague follow-ups, the hits are topical prompts. haiku `duration_api_ms` > 3000 over the three runs: 16 / 55 = 29 % (> 25 % bar); > 4500: 1 / 55; > 5000: 1 / 55. User decision: `RERANK_MS` = 5000. + +## After the final-review fixes (2397c36: 2-letter stop words, log trigger/outcome, log keys in the sweep) + +Same harness, same seed: still 15 prompts meet the trigger (the 2-letter stop words did not change this sample), 14 injections, n = 40 entries; relevant 30 / 40 = 75 % counting entries written after the prompt (8 such entries), 22 / 32 = 69 % excluding them; haiku > 3000 ms 1 / 15, > 5000 ms 1 / 15. Reading: the rerank is not deterministic (different picks run to run) and the labels are one labeller's on a small sample; across the four measured runs the relevant share ranged about 54-75 %. The injection log (now with `trigger` and `outcome`) is the real-use measure for 4d. diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md b/.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md new file mode 100644 index 0000000..6633f56 --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/REPORT.md @@ -0,0 +1,27 @@ +# probe4c report (CLI 2.1.318, claude -p haiku, --setting-sources local, --plugin-dir) + +Throwaway mod `$CLAUDE_JOB_DIR/tmp/probe4c/mod` (log only in the job tmp; deleted with the job). +Recommendation 0 of the 4c brainstorm (contract `.claude/tasks/contracts/2026-11-04-memory-recall-1859.md`). + +| probe | result | +|---|---| +| `$.process.run(['bash', ~/.claude/lib/memory.sh, '-C', , 'index'], {timeoutMs})` in a hook | works: exit 0, 508 lines (4 registries, `| ID | Date | Title | Status |`), 128 ms | +| `classic.SessionStart` in a mod | fires with `source` startup; `--continue "/compact"` fires `resume` then `compact`; keys: session_id, transcript_path, cwd, source, model, agent_id, agent_type, effort, … | +| `classic.SessionStart` returning `additionalContext` | reaches the model (it quoted `PROBE4C-SESSIONSTART-CONTEXT source=startup`) | +| `tool.call` Bash error answer `{...out, context: [...]}` | reaches the model (it quoted `PROBE4C-TOOL-CONTEXT` as tool-result context); the error answer has no `context` key before the hook adds one | +| `$.model.complete({model: 'claude-haiku-5-5', prompt, maxTokens: 64, effort})` | see below | + +haiku rerank latency (prompt = a design question + 30 candidates; same session, sequential): + +| variant | prompt chars | input tokens | ms (n=3, + 2 earlier full/low runs: 2494, 7332) | output tokens | +|---|---|---|---|---| +| effort low, ~350 chars per candidate | 10 865 | 3 965 | 1725, 2743, 1790 | 225-258 | +| no effort, same prompt | 10 865 | 3 965 | 2063, 5713, 1938 | 224-302 | +| effort low, ~150 chars per candidate | 4 865 | 2 045 | 2921, 2060, 2755 | 326-394 | + +- Median ≈ 2 s; tail 5.7-7.3 s (2 of 11 calls over 5 s, 3 of 11 over 2.7 s). A 3 s bound drops roughly one call in five on this sample. +- `maxTokens: 64` does not cap output tokens (220-400 reported): the model thinks; the request type has no thinking switch. A shorter candidate list does not cut latency. +- Answers were valid candidate IDs every time. +- Cost per recall ≈ 4k input + 0.3k output haiku tokens. + +Consequences for the design: decision 4 (superseded reader) = memory.sh through `$.process.run` (single reader, 128 ms, no port); the compact/clear ledger reset hooks `classic.SessionStart`; the 3 s bound is the user's number, its timeout share is measured by the proof harness on the 20 real prompts and put to the gate. diff --git a/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts b/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts new file mode 100644 index 0000000..7916607 --- /dev/null +++ b/.claude/tasks/plans/2026-11-04-memory-recall-spike/recall-bench.ts @@ -0,0 +1,268 @@ +// Measurement harness of the phase 4c memory recall (read-only, stdout). +// Transcript walk follows noise.py (2026-11-03-memory-capture-spike): +// its find_files / pairs_of logic, ported to TS. +// Run: bun recall-bench.ts prompts [--seed N] [--n 20] +// bun recall-bench.ts errors +import * as fs from 'node:fs' +import * as os from 'node:os' +import * as path from 'node:path' +import { + IDLE_MS, RECALL_CAP, HAIKU, RERANK_MS, assembleEntries, bm25Rank, + buildIndex, entriesOf, failureKey, isLive, isTrigger, matchOf, parseIds, + parseIndex, recallBlock, recallLine, redact, rerankPrompt, + type Entry, type StatusMap, +} from '../../../../mods/memory/hooks/register.ts' + +const REPO = path.resolve(import.meta.dir, '../../../..') +const ROOT = path.join( + os.homedir(), '.claude/projects/-home-bchanot-Documents-claude') +const DAYS = 14 +const MAX_CANDS = 30 +const MAX_PICKS = 3 +const MIN_SAMPLE = 10 +const MEMORY_DIR = path.join(REPO, '.claude/memory') + +type Rec = Record +type Found = { sid: string; agent: boolean; file: string } +type Composer = { sid: string; text: string; fresh: boolean; idle: number } + +function findFiles(): Found[] { + const cutoff = Date.now() - DAYS * 86400000 + const recent = (p: string) => + (fs.statSync(p, { throwIfNoEntry: false })?.mtimeMs ?? 0) >= cutoff + const found: Found[] = [] + for (const name of fs.readdirSync(ROOT).sort()) { + const full = path.join(ROOT, name) + if (name.endsWith('.jsonl') && recent(full)) { + found.push({ sid: name.slice(0, -6), agent: false, file: full }) + } + if (name.endsWith('.jsonl')) continue + const sub = path.join(full, 'subagents') + if (!fs.statSync(sub, { throwIfNoEntry: false })?.isDirectory()) continue + for (const f of fs.readdirSync(sub).sort()) { + const p = path.join(sub, f) + if (f.endsWith('.jsonl') && recent(p)) { + found.push({ sid: name, agent: true, file: p }) + } + } + } + return found +} + +function records(file: string): Rec[] { + const out: Rec[] = [] + for (const raw of fs.readFileSync(file, 'utf8').split('\n')) { + try { out.push(JSON.parse(raw)) } catch { /* skip bad line */ } + } + return out +} + +function blocksOf(r: Rec): Rec[] { + const c = r.message?.content + return Array.isArray(c) ? c.filter(b => b && typeof b === 'object') : [] +} + +function resultText(content: unknown): string { + if (typeof content === 'string') return content + if (!Array.isArray(content)) return '' + return content.filter(b => b?.type === 'text').map(b => b.text).join('') +} + +/** Bash failures: tool_use paired with its tool_result (is_error). */ +function failuresOf(file: string): { text: string; command: string }[] { + const calls = new Map() + const out: { text: string; command: string }[] = [] + for (const r of records(file)) { + for (const b of blocksOf(r)) { + if (b.type === 'tool_use' && b.name === 'Bash') { + calls.set(b.id, String(b.input?.command ?? '')) + } else if (b.type === 'tool_result' && calls.has(b.tool_use_id) && + b.is_error === true) { + out.push({ text: resultText(b.content), + command: calls.get(b.tool_use_id) ?? '' }) + } + } + } + return out +} + +const WRAPPERS = [' t.startsWith(w)) ? undefined : t +} + +/** Trigger-meeting typed prompts; fresh = first after a summary or start. */ +function triggerPrompts(files: Found[]): { all: number; hits: Composer[] } { + const hits: Composer[] = [] + let all = 0 + for (const f of files.filter(x => !x.agent)) { + let last: number | undefined + let fresh = true + for (const r of records(f.file)) { + if (r.isCompactSummary === true) { fresh = true; continue } + const text = composerText(r) + if (text === undefined) continue + all += 1 + const at = Date.parse(r.timestamp) + const idle = last === undefined || Number.isNaN(at) ? 0 : at - last + if (!Number.isNaN(at)) last = at + if (isTrigger(text, fresh, idle)) { + hits.push({ sid: f.sid, text, fresh, idle }) + } + fresh = false + } + } + return { all, hits } +} + +function rng(seed: number): () => number { + let a = seed >>> 0 + return () => { + a = (a + 0x6d2b79f5) >>> 0 + let t = Math.imul(a ^ (a >>> 15), 1 | a) + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t + return ((t ^ (t >>> 14)) >>> 0) / 4294967296 + } +} + +function sample(items: T[], n: number, seed: number): T[] { + const pool = [...items] + const next = rng(seed) + for (let i = pool.length - 1; i > 0; i--) { + const j = Math.floor(next() * (i + 1)); + [pool[i], pool[j]] = [pool[j]!, pool[i]!] + } + return pool.slice(0, n) +} + +function statuses(): StatusMap { + const r = Bun.spawnSync(['bash', 'lib/memory.sh', '-C', '.', 'index'], + { cwd: REPO }) + if (r.exitCode !== 0) throw new Error('memory.sh index failed') + return parseIndex(r.stdout.toString()) +} + +function registryTexts(names: string[]): string[] { + return names.map(n => fs.readFileSync(path.join(MEMORY_DIR, n), 'utf8')) +} + +function haiku(prompt: string): { text: string; ms: number } | undefined { + const dir = fs.mkdtempSync(os.tmpdir() + '/recall-') + try { + const r = Bun.spawnSync(['claude', '-p', '--model', HAIKU, + '--output-format', 'json', '--setting-sources', 'local', + '--tools', ''], { cwd: dir, stdin: new TextEncoder().encode(prompt) }) + const j = JSON.parse(r.stdout.toString()) + return { text: String(j.result ?? ''), ms: Number(j.duration_api_ms) } + } catch { + return undefined + } finally { + fs.rmSync(dir, { recursive: true, force: true }) + } +} + +function argOf(name: string, fallback: number): number { + const i = process.argv.indexOf(name) + const v = i < 0 ? NaN : Number(process.argv[i + 1]) + return Number.isFinite(v) ? v : fallback +} + +function share(k: number, n: number): string { + return n < MIN_SAMPLE ? `${k}/${n} (insufficient sample, < ${MIN_SAMPLE})` + : `${k}/${n}` +} + +function oneLine(text: string, n: number): string { + return redact(text).replace(/\s+/g, ' ').slice(0, n) +} + +function runPrompts(): void { + const status = statuses() + const entries = assembleEntries( + registryTexts(['decisions.md', 'learnings.md', 'blockers.md']), status) + const live = entries.filter(e => isLive(status, e.id)) + const { all, hits } = triggerPrompts(findFiles()) + const picked = sample(hits, argOf('--n', 20), argOf('--seed', 1)) + console.log(`human prompts (cli): ${all}, skipped no origin: ${skipped.noOrigin}, meeting isTrigger: ` + + `${hits.length}, sampled: ${picked.length}, live entries: ${live.length}`) + let asks = 0, answered = 0, inj = 0, ids = 0, late = 0 + picked.forEach((p, i) => { + asks += 1 + const cands = bm25Rank(live, p.text, MAX_CANDS) + const a = haiku(rerankPrompt(p.text, cands)) + const got = parseIds(a?.text ?? '', cands, MAX_PICKS) + const byId = new Map(cands.map(c => [c.id, c])) + const block = recallBlock( + got.flatMap(id => byId.get(id) ?? []).map(recallLine), RECALL_CAP) + const slow = a !== undefined && a.ms > RERANK_MS + if (a !== undefined) answered += 1 + if (slow) late += 1 + if (block !== '') { inj += 1; ids += got.length } + console.log(`#${i} [${p.fresh ? 'fresh' : 'idle/rule'}] ` + + `"${oneLine(p.text, 120)}"`) + for (const id of got) console.log(` ${id} ${byId.get(id)?.title}`) + console.log(` duration_api_ms=${a?.ms ?? 'n/a'} (upper bound) ` + + `timeout(>${RERANK_MS})=${a === undefined ? 'failed' : slow ? 'yes' : 'no'}`) + }) + console.log(`TOTAL asks=${asks} answered=${answered} injections=${inj} ` + + `mean IDs per injection=${inj ? (ids / inj).toFixed(2) : 'n/a'} ` + + `timeout share=${share(late, answered)} injection share=` + + share(inj, asks)) +} + +function errorIndex(status: StatusMap): Map { + const texts = registryTexts(['blockers.md', 'learnings.md']) + return buildIndex(assembleEntries(texts, status), status) +} + +function runErrors(): void { + const status = statuses() + const index = errorIndex(status) + const titles = new Map( + registryTexts(['blockers.md', 'learnings.md']).flatMap(entriesOf) + .map(p => [p.id, status.get(p.id)?.title ?? ''] as const)) + const seen = new Map>() + const perSession = new Map() + let failures = 0 + for (const f of findFiles()) { + const ledger = `${f.sid}|${f.agent}` + for (const x of failuresOf(f.file)) { + const key = failureKey(x.text, x.command) + if (key === undefined) continue + failures += 1 + const id = matchOf(index, key) + const done = seen.get(ledger) ?? new Set() + if (id === undefined || done.has(id)) continue + seen.set(ledger, done.add(id)) + perSession.set(f.sid, (perSession.get(f.sid) ?? 0) + 1) + console.log(`${f.sid.slice(0, 8)}${f.agent ? ' sub' : ''}: ` + + `"${oneLine(key, 120)}" -> ${id} ${titles.get(id) ?? ''}`) + } + } + const total = [...perSession.values()].reduce((a, b) => a + b, 0) + console.log('per session: ' + [...perSession] + .map(([s, n]) => `${s.slice(0, 8)}=${n}`).join(' ')) + console.log(`TOTAL failures keyed=${failures} known-line injections=` + + `${share(total, failures)} sessions with injection=` + + `${perSession.size}`) +} + +const mode = process.argv[2] +if (mode === 'prompts') runPrompts() +else if (mode === 'errors') runErrors() +else console.error('usage: recall-bench.ts prompts|errors') diff --git a/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md b/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md new file mode 100644 index 0000000..5727c19 --- /dev/null +++ b/.claude/tasks/plans/2026-11-05-memory-feedback-4d-1834.md @@ -0,0 +1,138 @@ +# Phase 4d memory feedback and promotion: plan (2026-11-05) + +BDR-125 phase 4d, host `mods/memory` (BDR-137). Input: the 4c injection log, +store key `l:` (`LogRecord` in `mods/memory/hooks/register.ts`). +Status: draft r1, not challenged, not gated. Starts after the 4c merge. + +## What the log holds (read 2026-11-05, 18:30) + +- Real use: 1 record. This repo, trigger `fresh`, outcome `injected`, IDs + BDR-125, BDR-137, LRN-261: the prompt that asked for this plan. +- Plus 1 headless proof record (tool channel, fixture BLK-001, temp repo). +- Expected rate in this repo (RECALL.md, 14 days, after the content floor): + about 15 triggered asks per 14 days, 3 tool-channel injections. + +No decision can come from this. The TODO gate ("deferred until the log shows +misses or noise") is not met, and the log alone can never meet it, for the +three reasons below. + +## Gaps between the log and the 4d questions + +1. Usefulness is not recorded. The 4d design (queue challenge 2026-10-25) + asked for "cited or not"; a record holds `at, session, agent, channel, + ids, trigger, outcome`. Relevance needs the prompt and the reply, and + both live in the transcript, not in the store. +2. Misses leave no trace. The log lists what came, never what should have + come. Example: this plan's prompt did not bring BDR-100, the promotion + rule the TODO 4d line cites, and nothing records that. +3. Transcripts live 7 days (`cleanupPeriodDays: 7`, job7 step D, secret + hygiene). A single log-to-transcript join at the gate, about 3 weeks + out, would find most turns gone. Older transcripts survive today; the + setting does not promise it. + +Minor: a prompt-channel `none` mixes "BM25 found no candidate" and "haiku +declined" (both paths in `recallFor`); rerank latency is not logged, only +the `timeout` outcome. + +## 4d.1 Two log fields (mod, /feat after the 4c merge) + +- Prompt records gain `cands` (BM25 candidates after the seen filter, 0-30) + and `ms` (rerank wall time, absent when no rerank ran). Both optional in + `isLogRecord`: records written before stay valid. +- Size: about 40 bytes more per record, 200 records stay under 40 KiB + (cap 64 KiB). +- Nothing else enters the store: no prompt text, no reply text (LRN-124), + no runtime cited flag (it would need a Stop hook reading the transcript + every turn, for a signal the offline join gets at no runtime cost). +- Proof: kit tests for both fields, an old-shape record still loads, the + `none` split visible on a fixture with zero candidates. + +## 4d.2 Weekly reader (harness, no runtime change) + +- `feedback.ts` (bun) beside this plan. It reuses `recall-bench.ts`'s + transcript loader (`findFiles`, `records`, `composerText`, exported, not + copied) and the mod's own functions (no port, LRN-261). +- Reads every `l:` key of the store file, all roots. The file path is + engine-internal (`~/.claude/plugins/store/memory_skills-dir-*.json`): + a renamed file fails loudly, acceptable for a measurement tool. +- Joins each record to its transcript by `session` and `at`: + - prompt channel: the composer prompt it answered and the assistant turn + that followed; + - tool channel: the failing command and the next 3 Bash results of the + same session (retry succeeded or not). +- Per injected entry: `cited` (the ID appears in the turn's assistant + text, a lower bound) and a relevance label (controller labels, the user + spot-checks: the 4c method). +- Misses: on up to 5 triggered asks per run, the controller searches the + registries for relevant entries the recall did not bring, and names the + cause (no lexical overlap, BM25 rank over 30, haiku declined). The + FR-prompt vs EN-entry gap is the expected first cause. +- Persists `labels.tsv` (at, root name, channel, trigger, outcome, cands, + ID, cited, label): IDs and enums only, committed. Labelled records are + skipped on the next run; prompt and reply text stay in the scratchpad. +- Writes `FEEDBACK.md`: counts and shares only. +- Cadence: once a week, inside the 7-day window, about 10 minutes of label + checks for the user. + +## 4d.3 Gate and decisions fixed before the data + +Gate: at least 20 labelled injected prompt asks and 10 tool injections (the +BDR-125 proof line), or 5 weeks after the 4c merge, whichever comes first. +At the date cap with a smaller n: report "insufficient sample" with the n, +extend once or close. + +| Signal | Threshold | Action | +|---|---|---| +| prompt precision (relevant / injected entries) | at least 64 % | keep | +| same, below 64 % | worst trigger kind below 50 % | tighten or drop that trigger (idle first: the 4c noise sat there) | +| precision of the 3rd pick | below 40 % | cap at 2 entries | +| timeout + paused share (asks with `cands` > 0) | above 25 % | revisit `RERANK_MS` or skip the rerank on short lists | +| `ms` p90 | below 2500 | lower `RERANK_MS`: every triggered prompt waits that long | +| tool precision | below 50 % | require 2 matched grams, or exclude the entry | +| misses in the sample | 1 ask in 3 or more | diagnose by cause; no fix built ahead | +| entry injected 3 times or more, 0 relevant | any | noisy: /prune-memory rewrites it | +| entry relevant 3 times or more, in 2 sessions or more | any | promotion candidate (BDR-100) | + +Each action is its own /feat or /hotfix with the measurement attached. 4d +builds no tuning before the gate. + +## 4d.4 Promotion and /prune-memory (conditional) + +Built only if the gate shows at least one noisy entry or one promotion +candidate; otherwise closed with the measurement, like phase 3. + +- Promotion stays a proposal: the reader lists each candidate with its + counts, the user picks, the mechanism (guard, test, skill step) becomes + its own TODO run, and the entry links the mechanism's commit. Never + automatic. +- /prune-memory STEP 1 gains "D. Recall feedback": reads `labels.tsv` + through one lib script that holds the thresholds (doctrine "After code + changes" step 4); noisy entries join section C, promotion candidates go + to STEP 2 as TODO lines. +- Open at that point: where other repos keep their labels (the mod logs + every root, the reader lives in this repo). + +## Open choices (user) + +1. Cadence vs retention: weekly reader runs (recommended); or raise + `cleanupPeriodDays` for the window (reverses job7 step D, transcripts + carry secrets); or one run at the gate on a single week. +2. 4d.1 fields `cands` and `ms`: add them (recommended) or measure with the + current record. +3. Gate numbers and the 5-week cap. +4. Promotion threshold: relevant 3 times in 2 sessions. + +## Prerequisite: 4c merge + +- Recall half of the interactive proof seen in this session: a fresh design + prompt brought 3 entries, all relevant to the ask by the controller's + reading (labeller and beneficiary are the same model: unchecked). +- Still owed: the digest after a real `/compact`, the 4c gates, the user's + "merge it". + +## Out of scope + +Runtime cited flag, prompt text in the store, the 4c deferrals (Read and +Bash command triggers, critical deny-once, Tier 1, cross-repo index, +`memory_search`), the `l:` cross-root shortcut and the unbounded +`memory.sh check` residual (own TODO lines). diff --git a/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md b/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md new file mode 100644 index 0000000..f2643ce --- /dev/null +++ b/.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md @@ -0,0 +1,110 @@ +# Bugfix plan: detect_plan fork bomb (2026-11-06) + +## Diagnosis + +BUG: running `lib/tests/session-digest.test.sh` (uncommitted SD13 cases) +filled 14 GiB of RAM in 45 s; 2026-11-05 23:49 → OOM → reboot 23:55. +Kernel OOM dump: 126 `claude`, 396 `bash`, 124 `sh`, all +`oom_score_adj=-1000`. + +ROOT CAUSE: `lib/detect-plugins.sh:85` `detect_plan` falls back to +`claude config get planType` when `$HOME/.claude.json` lacks the plan +markers or is absent. claude 2.1.318 has no `config` subcommand +(`claude config --help` prints the main usage), so the words are read +as a prompt and a full session starts. Its SessionStart hook +(`hooks/session-start.sh:158` → `detect_plan`) runs with the same HOME, +finds the same missing markers, starts another `claude`: unbounded +recursion. SD13's `mkhome` builds a HOME that links `~/.claude/*` but +not `~/.claude.json`, so the fallback fires. + +EVIDENCE: journal boot -1 (earlyoom + kernel OOM table), transcript +90b2c305 (`make test suite=lib/tests/session-digest.test.sh` at +23:49:07, result at 23:51:28), `claude config --help` output. + +BLAST RADIUS: production too. Real sessions survive only because +`~/.claude.json` holds `tengu_cobalt_compass` + `tengu_harbor` (internal +feature flags). If upstream renames them, every session start recurses. +`detect_plan` is called only from `hooks/session-start.sh:158`. No other +hook or lib calls the `claude` CLI (`lib/cc.sh` is the user launcher). +The hook header already promises "Filesystem only, except one git fetch". + +RELATED MEMORY: no BLK/BDR/LRN bears (grep detect_plan, fork, recurs, +oom, planType). + +## Fix plan + +1. `lib/detect-plugins.sh` `detect_plan`: delete the `claude config get + planType` fallback and its `case`; markers absent → `echo "pro"` + (the existing default). Comment states why the CLI is never called + (a hook-launched `claude` re-enters this hook). +2. `hooks/session-start.sh`: recursion guard at the top, before stdin + is read: `[ -n "${CLAUDE_SS_RUNNING:-}" ] && exit 0; export + CLAUDE_SS_RUNNING=1`. The variable lives only in the hook's process + tree: a sibling session never sees it; any `claude` a future change + spawns from the hook gets a silent no-op hook instead of a cascade. +3. `lib/tests/session-digest.test.sh` (keeps the uncommitted SD13/SD14 + cases intact): + - suite-wide stub: `$WORK/stub/claude` writes one line to + `$WORK/claude-calls` and exits 0; `PATH="$WORK/stub:$PATH"` exported + before any case. A regression then records a call instead of + forking a real session. SD13h's `PATH="$bin"` already holds no + claude. + - SD15a: `HOME` without `.claude.json` (mkhome as is), hook runs → + `claude-calls` absent/empty. + - SD15b: `CLAUDE_SS_RUNNING=1` set → hook prints nothing, rc 0. + - SD15c: `detect_plan` sourced alone with an empty HOME prints `pro`. + Replaces the `ulimit -u` idea: the per-user process cap counts every + process of the user (hundreds of live ones), so a value is either + too tight (spurious red) or too loose (no protection); the stub is + deterministic. + +ORDER: fix 1 lands before the suite runs again (DO NOT run the suite +on the current tree). + +RISK: low. Plan detection for users without the markers now always +reports Pro (banner budget label only). Guard: a user who runs the hook +by hand from inside a hook-spawned shell sees nothing (no such use). + +Out of scope: origin of `oom_score_adj=-1000` on claude processes +(recorded as an open BLK), plan detection accuracy. + +## Revision r2 (after 3-lens challenge, 2026-11-06) + +Challenge: simplicity SOLID (4 MINOR), correctness CONCERNS (1 MAJOR), +robustness CONCERNS (3 MAJOR). Named changes: + +- R1 (correctness 1, robustness 3: landing). The fallback is on main and + develop. The fix splits in two: + - Part A, on its own branch off main or develop (user choice), in a + separate `git worktree` (so `~/.claude/hooks` and `~/.claude/lib`, + symlinked to the main working tree, never flip to another branch and + the uncommitted 4c work stays untouched): fix 1, fix 2, and a + standalone regression suite `lib/tests/detect-plan.test.sh` that + needs nothing from feature/memory-recall. + - Part B, on feature/memory-recall after Part A merges: suite-wide + stub in session-digest.test.sh + final empty-log assertion. +- R2 (robustness 1+2, correctness 2+4: proof). The stub is written with + the log path expanded at creation, `chmod +x`, and a positive control + first calls `claude` through PATH and asserts 1 logged line (stub + reached). The regression case calls `detect_plan` directly (no hook, + no recursion path) with an empty HOME and asserts output `pro` AND + 0 new log lines. Red proof: that case runs once against the pre-fix + lib (safe: stub catches the single call) and must fail, then pass + after fix 1. Copied into the contract as [gated]: never run the hook, + `make test` or the session-digest suite before fix 1 is on disk. +- R3 (correctness 3, robustness 5: guard). Guard kept as + defense-in-depth (the -1000 adj made the runaway unkillable), renamed + `SESSION_START_RUNNING` (simplicity 4, repo convention). The hook + comment says it has no live caller and that it relies on claude + passing env to its hooks. Test: hook run with the variable set prints + nothing, rc 0; and a PATH stub `git` writes `$SESSION_START_RUNNING` + seen by the hook's child, asserting `1` (proves the export). +- R4 (simplicity 2, correctness 5: dead code). detect_plan docstring + "max or pro"; the `free)` arm at session-start.sh:162 dropped. +- R5 (simplicity 3): SD15a/SD15c dropped from Part B; one final + cumulative empty-log check covers every hook run of the suite. +- R6 (robustness 6: containment). The first run of each suite after the + fix goes through `systemd-run --user --scope -p TasksMax=256` (cgroup + pids cap counting only that scope). +- Deferred to TODO (robustness 4, MINOR): stub in memory, graphify-gate + and push-guard suites, which run the hook with the real HOME. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ed7b9d4..e06c19f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -20,7 +20,7 @@ claude-config/ ├── update-all.sh # One-command update for all components ├── Makefile # Unified entry point: make install / doctor / update / test (make help) ├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills -├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, code-limits line-width signal +├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, system-dir extraction guard, instruction-load log, memory digest at session start, code-limits line-width signal ├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath ├── .githooks/ # This repo's own copy of the same hooks ├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file @@ -38,6 +38,6 @@ claude-config/ - `skills/` = entry points you invoke via `/skill-name` - `agents/` = execution units called by skills (never invoked directly by user) -- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/` as `@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions; the mod also redirects a main-loop code write made outside a skill run to a skill (README, "Write guard"); `mods/memory/` is the capture mod (Bash failures and milestones in the plugin store, read by `memory_pending`) +- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/` as `@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions; the mod also redirects a main-loop code write made outside a skill run to a skill (README, "Write guard"); `mods/memory/` is the capture mod (Bash failures and milestones in the plugin store, read by `memory_pending`) that also recalls registry entries and known errors - `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually - **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go. Where `graphify-out/graph.json` exists, the session-start hook prints the graphify usage rules. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ea7201..5320979 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project - **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project (the Supabase and cloud-function detail lives in the path rules `rules/supabase.md` and `rules/cloud-functions.md`), plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server). - **/a11y skill**: accessibility leaves `/guardrails` and becomes its own skill. Same A11Y-* rules (img alt, field label, click without keyboard, focus outline removed, positive tabindex) on the shared scan engine (`skills/guardrails/scripts/scanner.py`, a `Catalogue` per CLI; `skills/a11y/scripts/scan.py`, markers `A11Y-CLEAR` / `A11Y-NO-NEW`), a Tab-only walk of the main flow on `--live` through `/browse` (marked not done otherwise), report `.claude/audits/A11Y.md`, fixes proposed with the alt and label wording as the user's choice, applied through the bugfix circuit (`bugfixer`, verify-secure gates, `bugfix/a11y-`), re-pass against a baseline. The keyboard, alt and label doctrine moves from `rules/secure-by-default.md` to the lazy `rules/a11y.md` (loads on UI files only; `rules/web-building.md` points at it). `/guardrails` scans `injection` (INJ-*) and `exposure` (EXP-*) instead, with per-language SQL patterns, shared `code_files` / `hits` / `dedupe_lines` / `client_reachable` helpers and a walker that lists files over 1 MB by path; `--domain a11y` is a usage error there. `/web-validate` keeps full WCAG conformance. Suite `lib/tests/a11y-scan.test.sh`; routing row `reflect`; a top-level skill in no pack, so on under every profile. - **memory mod**: `mods/memory/`, a Claude Code mod, captures Bash failures (`Exit code N` whose last line is error-shaped (a word like error, fatal, cannot, denied, a shellcheck code), redacted at capture (env secrets, vendor key prefixes, `--token` flags, API-key headers and cookies, JSON/YAML password/token/secret pairs, a 40-hex URL user; residual `user:p@ss@host` partial), sub-agent ones marked) and milestones (a `feat`/`fix` commit, a `gitflow.sh finish`, a `make test` red then green) in the plugin `$.store` (3 sessions per project, 50 failures each, 1 MiB). One context note at the first prompt after a milestone; the `mcp__memory__memory_pending` tool lists milestones and failures as `NEW` or `known ` against the BLK/LRN entries, and `/capitalize`, `/close` and the CAPITALIZE steps call it first. It never writes a registry. Off with `{"enabled": false}` in `~/.claude/memory.json`. Residuals: concurrent sessions last writer wins, non-Bash failures not captured, noise 83 % measured before the filter, cut by two thirds (`NOISE.md`). +- **memory recall**: the memory mod hands registry entries back. A composer prompt of 5 content words or more that opens a context, follows 30 minutes idle or holds a design or analysis word gets up to 3 live BDR, LRN or BLK entries (BM25 top 30, one haiku rerank bounded to 5 s), and a Bash failure matching a live BLK or LRN entry gets a `memory: known ` line; 1500 characters per turn, each entry once per context, sub-agents on the error channel only. `hooks/session-start.sh` prints a `memory digest:` (open BLK from `memory.sh index blocker`, 3 Actionable TODO items, last journal line, 800 characters, TODO dropped first) on startup, clear and compact. `"recall": false` in `~/.claude/memory.json` cuts the injections; each one is logged under the `l:` store key for phase 4d. Measured precision 54 to 61 % against the 64 % bar, so recall ships switchable. - **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `audit`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run `), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget ||model= effort=|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch (a `/model` hand pick excepted) runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions. - **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 12 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`. - **model-router `/model` scope**: a `/model ` typed in the composer, or a pick in the `/model` picker, with a model the table knows asks where it applies. The picker's switch is held first (PreModelSwitch deny; the engine prints that a hook blocked it); a pick while another dialog is open is refused with `answer the open dialog first`. This project writes the full id as `model` into the project's `.claude/settings.local.json` (created if absent, refused through a link) and sets a sticky model route. This conversation sets the sticky route only. Everywhere runs the native `/model` (user `settings.json`). Both non-native answers drop the run slot and keep a sticky effort. With the picker's Default, an unknown name, a headless run or another origin, the native command runs with no question. A model chosen in that dialog always switches: it bypasses the cold-read caps and the `mainUpgrade` / `mainModelSwitch` flags, and while it is marked down or outside a known window it waits and the automatic chain decides. A native switch or `/clear` drops it; `/route model=` keeps the caps. Known limits: the `/config` Model row still writes user `settings.json`; a dialog never answered has no timeout. Tests: `mods/model-router/hooks/register.test.ts`. diff --git a/README.md b/README.md index be00e4d..753c3f8 100644 --- a/README.md +++ b/README.md @@ -159,11 +159,16 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode - Records: a Bash result whose text starts `Exit code N` and whose last line (the first line and the rtk trailer dropped) is an error line. That line must hold a letter and an error-shaped word, else the failure is dropped (no earlier line is tried): a word such as error, fatal, cannot, No such, denied, failed, unexpected, traceback, or a shellcheck code (SC1234); otherwise nothing is stored. The entry is stored redacted: `KEY=value` secrets, Stripe, AWS, GitHub, Slack, SendGrid and Supabase keys, private key blocks, JWTs, Bearer and `Authorization: Basic|token` values, `user:pass@` URLs, `-u`/`--user user:pass` and `--password`; also the Anthropic, OpenAI, GitLab, Google and npm key prefixes and `github_pat_`, `--token`/`--api-key`/`--secret` flags, API-key headers (`X-Api-Key`, `api-key`, `apikey`, any name ending in `api-key` or `api_key`), `PRIVATE-TOKEN`, `Cookie` and `Set-Cookie` headers (to the end of the line), `--cookie` values and `curl -b` cookies, JSON and `key: value` password/token/secret/api-key pairs whose key may carry a prefix or suffix (`access_token`, `db_password`), and a 40-hex token as URL user. Residual: `user:p@ss@host` becomes `@ss@host`, so the password's tail after its own `@` stays. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`. - Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green. Milestones are recorded on the main loop only: sub-agent commits and finishes are ignored. -- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry, 1 MiB for the whole store. It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. +- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry. Session keys (`p:`) are swept at 1 MiB; log keys (`l:`) hold about 28 KiB per project; both sit under the engine's 4 MiB cap for the whole store, and when the total nears it the oldest log key is evicted first (never the current project's). It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-.json`, an engine layout, not fixed by this repo); delete it to wipe the captures. - Note: one context line, `memory: