diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 41e8334..c9c90e1 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1562,3 +1562,9 @@ Supersedes [[BDR-030]]. - **Alternatives rejected**: drop idle (user: tighten); index body (already done); add `promoted` to `_MEM_WORDS` (classifier change for annotation only). - **Residual**: metricsOf has no fix-date split, pre-fix rows keep 3rd-pick + idle actions in later FEEDBACK.md (TODO); tool-channel noisy entries not fixed by title rewrite (body spans). - **Reference**: feature/recall-gate1-fixes 7e87d77 + 39f9790; contract .claude/tasks/contracts/2026-11-12-recall-gate1-fixes-1830.md; plan r3; gates: 3 lenses (BLOCKER x3) + confirmation, GATE 0 MET, verifier ECARTS(2)→CONFORME x2, security PASS x2. See [[BDR-140]], [[EVAL-058]], [[BDR-100]]. + +## BDR-147 — D1b: the session digest is the TODO source at start; Actionable section else first 3 items, overflow marker [accepted] (2026-11-12) +- **Decision**: D1b: session digest = only TODO source at session start. `_digest_todo` reads `## Actionable` or `### Actionable` (`/^###? Actionable([ \t\r]|$)/`), section empty/absent → file's first 3 top-level `- [ ] ` items; headings + items inside `` ignored; `- todo: +N not shown, read .claude/tasks/TODO.md` marker when 800 cap drops todo lines (room reserved only on overflow). Seeds (init-project, capitalize:83 guarded, onboard STEP 9 fresh format) emit `## Actionable` + comment. CLAUDE.global.md Session start step 1 no longer orders a TODO.md Read (digest carries it; no digest → read it). Local repos migrated insert-only: empty `## Actionable` + comment under H1, `chore/todo-actionable` per repo. +- **Why**: only this repo had `### Actionable`; every other project's digest showed no TODO, so D1 kept the Read; a cap drop with no Read = silent loss → marker. +- **Alternatives rejected**: move open items under Actionable per repo (conflicts: faunosteo feature branch edits TODO.md +231/-10, game +8); keep the Read forever (always-on cost D1 wanted gone); onboarder.md stub edited (FILE SCOPE; fallback covers it). +- **Reference**: feature/digest-todo-fallback 1124758 + 63bea87; contract .claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md; 3 lenses CONCERNS (0 BLOCKER) → r2 → confirmation CONCERNS → r3; GATE 0 MET; verifier 5/6 MET + criterion 5 (make test) closed by orchestrator run; security PASS. Supersedes D1's "TODO.md stays read at start". See [[BDR-125]]. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index ad446b1..f98734a 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -730,3 +730,4 @@ rules: - 2026-11-12: /memory-feedback gate 1 (prompt 26/20): 28 records, 75 labels, 5 spot-checked (0 flip), 7 misses on 5 asks. Precision 57 % under the 64 % target, idle 44 %, tool channel empty. EVAL-058 + 4 TODO lines on chore/memory-feedback-gate1. - 2026-11-12: phase 4b/4c proofs (chore/phase4-proofs): known-error replay `bash -c 'PATH=/nonexistent npm install'` → tool.call context `memory: known BLK-013 …` + store log record {channel: tool, ids: [BLK-013]} (4d tool channel works; 0 records = no matching error); live redaction: `API_KEY=…` + `Bearer …` in a failing echo → key/line/excerpt/command all ``, 0 raw hits in the store (Bearer swallows trailing `";`, harmless); headless /context full 27.1k (base 26.9k, +/memory-feedback skill), dev 25.2k, CLI now prints System tools (deferred) 14.1k; digest after a real compaction: no compaction in retained transcripts, waits for this run's first auto-compact. - 2026-11-12: /feat recall-gate1-fixes (block C): idle ≥ 8 content words, MAX_PICKS 2, /prune-memory step D (noisy rewrite, BDR-100 promotion); no-overlap misses accepted after replay (body already indexed). 3 lenses FATAL (promoted ∉ _MEM_WORDS) → r2 → confirmation CONCERNS → r3; GATE 0 MET, verifier ECARTS(2)→CONFORME, security PASS (LOWs folded, re-gated). BDR-146, LRN-281..283. +- 2026-11-12: /feat digest-todo-fallback (block D, D1b): Actionable ##/### else file's first 3 top-level items, comment gating, +N marker on 800 cap; seeds emit ## Actionable; Session start no longer reads TODO.md (digest). 3 lenses CONCERNS → r2 → confirmation → r3; GATE 0 MET, verifier 5/6 + make test closed by orchestrator, security PASS. BDR-147. Migration of 6 local repos next. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index dbbb802..58d11a6 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -76,7 +76,7 @@ Open children of the shipped phases (History 2026-11-12), text verbatim. ### Actionable - [x] BDR-125 obsolescence pass (2026-11-09, /code-clean merged db5bbe5; report `.claude/tasks/plans/2026-11-09-bdr125-obsolescence-clean-1650.md`): D1-D6, G1-G5 and the D3 add-ons done and merged by 2026-11-12; still open below: D1b and the G2 measured passive-cost feature. - [x] D1 doctrine (done c69ce9c + docs a37df2f, feature/doctrine-rules-graphify; TODO.md stays read at start, see D1b): CLAUDE.global.md:52-54 "Session start 1. Read `.claude/memory/`" + skills/capitalize/SKILL.md:375, while the 4c digest delivers open BLK + TODO + last journal at start (4a meant to fix the "load every session" premise) - - [ ] D1b (user 2026-11-12, after D1 challenge): every project TODO readable by the session digest. `_digest_todo` (hooks/session-start.sh:329-333) reads only a `### Actionable` heading, which only this repo has; skills/init-project seeds `# TODO\n\n## `, skills/onboard STEP 9 writes `## P0 — Critique`…. Options to choose at planning: templates/init-project/onboard emit the heading + migrate existing TODOs (game, faunosteo, zenquality…), and/or digest falls back to the first unchecked `- [ ]` items. Until then D1 keeps TODO.md read at session start. + - [x] D1b done 2026-11-12 (feature/digest-todo-fallback 1124758 + 63bea87, BDR-147; per-repo migration tracked in block D of the close-out run) (user 2026-11-12, after D1 challenge): every project TODO readable by the session digest. `_digest_todo` (hooks/session-start.sh:329-333) reads only a `### Actionable` heading, which only this repo has; skills/init-project seeds `# TODO\n\n## `, skills/onboard STEP 9 writes `## P0 — Critique`…. Options to choose at planning: templates/init-project/onboard emit the heading + migrate existing TODOs (game, faunosteo, zenquality…), and/or digest falls back to the first unchecked `- [ ]` items. Until then D1 keeps TODO.md read at session start. - [x] D2 visible (done 80f56ef, feature/banner-drop-plugin-dev): banner "OFF : plugin-dev" (plugin dropped 2026-07-02): lib/detect-plugins.sh:43-47, hooks/session-start.sh:106,111,180,210, agents/plugin-advisor.md:59,181,199,242,250-255 - [x] D3 visible (done 9b12b12, BDR-142; follow-ups in BUGS-FOUND) (= docs backlog P34): packs vocabulary in agents/plugin-advisor.md (:99 PROFILE template in the old `profile.sh current` format, :126-129 rollback, gstack ON/OFF rules, context7 ON) and USAGE.md:181,232,233,1090,1092,1095 - [x] D4 skill behavior (done 99f10b2 + docs bd0687d, feature/prune-memory-status-reader; one classifier `reconcile_status_classify`, unreadable = info-only count; follow-ups in BUGS-FOUND): skills/prune-memory STEP 1.A/3 detection (per-entry frontmatter, raw `status:` lines) → read statuses via `memory.sh index` (v1 + v2); keep example IDs 9xx (RED-7) diff --git a/.claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md b/.claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md new file mode 100644 index 0000000..35c00cb --- /dev/null +++ b/.claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md @@ -0,0 +1,36 @@ +# CONTRACT — digest-todo-fallback (D1b) +- date: 2026-11-12 | flow: feat | branch: feature/digest-todo-fallback (off develop d3d5e6c) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +D1b: every project TODO readable by the session digest. (1) hooks/session-start.sh `_digest_todo`: read a `## Actionable` or `### Actionable` heading (items = top-level `- [ ] ` lines until the next heading), and when that section is absent or holds no unchecked item, fall back to the first 3 top-level `- [ ] ` items of the whole file (indented sub-items never count); same `- todo:` line format, same 3 cap, bash 3.2 safe; tests in lib/tests/session-digest.test.sh (Actionable present, `##` level, absent → fallback, empty section → fallback, indented items ignored, HTML comment items ignored like _digest_journal). (2) skills/init-project/SKILL.md:118 seed becomes `# TODO\n\n## Actionable\n\n\n## \n`; skills/onboard/SKILL.md STEP 9 format emits the same `## Actionable` block + comment right under the `# TODO — onboard backlog` title (P0 section unchanged, the fallback then shows P0 items). (3) CLAUDE.global.md "Session start" step 1: drop the instruction to Read `.claude/tasks/TODO.md` at session start (the digest carries open BLK, actionable TODO and last journal); keep "Read TODO.md when the task needs it"; grep and patch every citer (skills/capitalize/SKILL.md:375 cited by D1, doctrine-citers census). NOT in scope here: the per-repo migration (done after merge on chore branches, insert-only empty `## Actionable` under each repo's H1 because feature branches in game/faunosteo edit TODO.md and a content move would conflict). + +(user brief 2026-11-12 block D: "le digest replie sur les premiers items si `### Actionable` manque ; templates init-project et onboard émettent le titre ; migrer les TODO des repos locaux ... puis retirer la ligne doctrine Session start (le digest suffit), census des citers".) + +## CLARIFICATIONS +- [gated 2026-11-12, orchestrator per user brief "decision not listed: take it, note it"] migration = insert-only empty `## Actionable` + comment under each repo's H1 (conflict-free with active feature branches editing TODO.md); the fallback covers empty sections. +- [gated] new Session start step 1 text: "The banner's `memory digest` lists open blockers, the first unchecked TODO items (`## Actionable`, else the file's first) and the last journal line: apply them before touching anything; a `- open: +N` line → read those entries in `blockers.md`. No digest (foreign repo, memory mod off) → read `.claude/tasks/TODO.md` and list the open blockers yourself." Step 2 adds `.claude/tasks/TODO.md` to what is read when the task needs it. +- [gated] capitalize:375 closing line: "Next session: the startup digest (open blockers, actionable TODO, last journal line)." + +## ACCEPTANCE CRITERIA +1. (r2: plus the `- todo: +N not shown, read .claude/tasks/TODO.md` marker when the 800 cap drops todo lines; headings inside comments ignored; regex `/^###? Actionable([ \t\r]|$)/`) `_digest_todo` reads `## Actionable` and `### Actionable` sections; absent or no unchecked item → first 3 top-level `- [ ] ` of the file; indented items and items inside `` blocks never count. + CHECK: bash lib/tests/session-digest.test.sh 2>&1 | tail -1 + EXPECT: , 0 failed + EVIDENCE: MET exit=0 marker-found :: session-digest: 70 passed, 0 failed +2. init-project seed and onboard STEP 9 format carry `## Actionable` + the comment line. + CHECK: echo $(grep -c '^## Actionable' skills/onboard/SKILL.md)$(grep -c 'Actionable' skills/init-project/SKILL.md | grep -c '^[1-9]') + EXPECT: 11 + EVIDENCE: MET exit=0 marker-found :: 11 +3. CLAUDE.global.md Session start no longer orders a Read of TODO.md at start; capitalize:375 updated; doctrine-citers census green. + CHECK: echo $(grep -c '^1\. Read `.claude/tasks/TODO.md`' CLAUDE.global.md)$(grep -c 'Next session: TODO.md' skills/capitalize/SKILL.md) + EXPECT: 00 + EVIDENCE: MET exit=0 marker-found :: 00 +4. Citers census + shellcheck on session-start.sh. + CHECK: bash lib/tests/doctrine-citers.test.sh >/dev/null 2>&1 && shellcheck -S warning hooks/session-start.sh lib/tests/session-digest.test.sh && echo SC-OK + EXPECT: SC-OK + EVIDENCE: MET exit=0 marker-found :: SC-OK +5. make test green with bun on PATH (manual: exceeds 120 s gate timeout). +6. Limits: changed functions ≤ 25 logic lines, added lines ≤ 80 cols; bash 3.2 safe (SD11 stays green). + +## FILE SCOPE +hooks/session-start.sh, lib/tests/session-digest.test.sh, skills/init-project/SKILL.md, skills/onboard/SKILL.md, CLAUDE.global.md, skills/capitalize/SKILL.md (:375 line + :83 seed). README.md/USAGE.md digest bullets → STEP 6 doc sync. diff --git a/.claude/tasks/plans/2026-11-12-digest-todo-fallback-2130.md b/.claude/tasks/plans/2026-11-12-digest-todo-fallback-2130.md new file mode 100644 index 0000000..ece2e26 --- /dev/null +++ b/.claude/tasks/plans/2026-11-12-digest-todo-fallback-2130.md @@ -0,0 +1,52 @@ +# PLAN — digest-todo-fallback (r1) +Contract: .claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md + +## Files +- hooks/session-start.sh:329-333 `_digest_todo` — one awk program over TODO.md: + - track HTML comment blocks like `_digest_journal` (opener `^[ \t]*` clears c; lines while c never count); + - `/^#{2,3} Actionable([ \t]|$)/` (use `^##+ Actionable` portable form `/^###? Actionable/` for mawk/BSD awk: no `{2,3}` intervals) → on=1, next; any other `^#` line → on=0; + - a top-level item = line matching `^- \[ \] ` (no leading space); in section → append to `a[]` (max 3); always → append to `f[]` (max 3); + - END: print a[] when it holds ≥ 1, else f[]; each as `- todo: `. + - comment the function: " → first 3 unchecked Actionable items, else the file's first 3". +- lib/tests/session-digest.test.sh: SD5 flips: TODO without Actionable → `- todo: hidden` shown (fallback); new SD5b `## Actionable` level read; SD5c empty Actionable section (only `- [x]`) → fallback to the file's first unchecked; SD5d indented ` - [ ] sub` never counts (section and fallback); SD5e items inside `` never count (template comment line with `- [ ]` inside); SD1 unchanged (### Actionable, `### Later` item not shown). +- skills/init-project/SKILL.md:118 printf seed → `'# TODO\n\n## Actionable\n\n\n## %s\n'` (wrap at 80 if needed with a second printf or a variable). +- skills/onboard/SKILL.md STEP 9 format block: insert under `# TODO — onboard backlog ()` (before the generated comment): `## Actionable` + the same comment line + blank line; the "append with separator" variant gets the same block under `# Onboard backlog (généré le …)`? NO: an appended backlog under an existing TODO must not add a 2nd Actionable heading → only when the file is created fresh; state that in one sentence. +- CLAUDE.global.md:52-61 per CLARIFICATION 2 (line count must not grow: CLAUDE.global.md density budget; keep ≤ current lines). +- skills/capitalize/SKILL.md:375 per CLARIFICATION 3. + +## Edge cases +- `### Actionable` heading followed by `#### sub` heading: on=0 at sub (same as today; documented). +- TODO.md absent → awk prints nothing, error to /dev/null (today the call site already drops stderr? verify `_memory_digest` guards `[ -f ]`; if not, add `[ -f "$1/.claude/tasks/TODO.md" ] || return 0`). +- CRLF lines: unchanged behavior (out of scope). +- Fallback items from a DONE section with unchecked boxes are shown (accepted: first unchecked in file order). + +## Tests +session-digest.test.sh SD5 flip + SD5b-e; SD7/SD7b (800-cap) unchanged. + +## Disposition +honors BDR-125 4c (digest = open BLK + actionable TODO + last journal, never per turn), LRN-034 (verify state), D1 decision (TODO read at start kept until D1b, now dropped), BDR-022 (no .claude content in public docs). + +## r2 (3 lenses: correctness CONCERNS(4), robustness CONCERNS(3), simplicity CONCERNS(1); no BLOCKER) — r2 wins over r1 +- Regex pinned: `/^###? Actionable([ \t\r]|$)/` (mawk/gawk/busybox checked by the simplicity lens; `\r` keeps today's CRLF match). The other forms in r1 are void. +- Comment tracking (`` closes, as `_digest_journal`) gates BOTH the heading rules and the item rule: inside a comment no heading toggles the section and no item counts. +- Overflow marker: `_digest_assemble` reserves room for one fixed line `- todo: +N not shown, read .claude/tasks/TODO.md` and prints it whenever the 800 cap dropped ≥ 1 todo line (N = dropped count). `_digest_todo` itself still emits at most 3 items. Header comment of `_digest_assemble` updated. SD7 and SD7b updated to expect the marker. +- Discriminating fixtures (session-digest.test.sh): + - SD5 flipped: TODO without Actionable → `- todo: hidden` (fallback). + - SD5b: `### Backlog\n- [ ] early\n## Actionable\n- [ ] act\n` → only `- todo: act` (section wins over earlier items; `##` level). + - SD5c: `## Actionable\n- [x] done\n\n## Later\n- [ ] fb1\n- [ ] fb2\n` → fallback `fb1`, `fb2`. + - SD5d: indented ` - [ ] sub` never counts (section and fallback). + - SD5e: multi-line comment `\n- [ ] real` → only `- todo: real` in fallback mode; and the same ghost block inside a real `## Actionable` section → only that section's real item; a `# x` line inside a comment inside the section does not end it. + - SD5f: `#### Actionable` and `### Actionables` are not sections (fallback). +- TODO.md absent: handled by the call site (`2>/dev/null`, :389); no guard added. +- init-project:118 stays ONE guarded command (`[ -f … ] || printf '' "$(date …)" > …`), long line accepted (file style); never a second unguarded printf. AC6's 80-col limit = code files (session-start.sh, the test). +- capitalize:83 seed gets the same `## Actionable` + comment format (same file as :375). onboarder.md stub left as is (fallback covers it; FILE SCOPE stays ≤ 5 code files) — stated in the plan, not hidden. +- onboard STEP 9 sentence keyed on its own condition: "no user content (the onboarder stub counts as none) → write the full format, `## Actionable` block included; existing user content → append the backlog under the separator WITHOUT a second `## Actionable`". +- Order: hook + tests first, run `bash lib/tests/session-digest.test.sh` green, THEN CLAUDE.global.md and capitalize (both are live machine-wide through ~/.claude links). +- Oracles fixed in the contract (AC1 EXPECT `, 0 failed`, AC4 census gated with `&&`, shellcheck `-S warning` because SC2001 at :175 is pre-existing style). + +## r3 (confirmation CONCERNS(1), no BLOCKER; folded, no further challenge) — r3 wins over r2 +- SD5e fallback half: `- [ ] first` + ghost block (``) + `- [ ] real` → expects `first`, `real` (an ungated heading would make `real` the only section item). SD5f: `- [ ] first\n#### Actionable\n- [ ] x\n### Actionables\n- [ ] y` → expects `first`, `x`, `y`. Fixtures written with `printf --` or `printf '%s\n'` (a format starting with `-` is rejected by bash printf). +- SD5c gets 4 fallback items, expects exactly 3 (fallback cap pinned). +- Marker reserved ONLY when the todos do not all fit: first try all todos under 800; if one drops, rebuild with room for the marker line (`- todo: +N not shown, read .claude/tasks/TODO.md`) and print it. SD7/SD7b expect the marker; new SD7c: a block whose 3 todos fit between 751 and 800 chars prints all 3 and no marker. +- Doctrine wording (CLARIFICATION 2 amended, orchestrator under the user brief): "a `- open: +N` line → read those entries in `blockers.md`". +- capitalize:83 becomes the same GUARDED one-liner as init-project:118 (`[ -f .claude/tasks/TODO.md ] || printf '' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md`). diff --git a/CHANGELOG.md b/CHANGELOG.md index df33367..91ccc8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project ### Changed - **memory recall**: a prompt after 30 minutes idle now needs 8 content words, up from 5 (a context's first prompt or a design/analysis prompt still needs 5), and the haiku rerank keeps at most 2 entries, down from 3. Measured on the first feedback gate: idle precision 44 %, third pick 35 %. +- **memory digest TODO lines**: with no `## Actionable` (or `### Actionable`) section, the digest now shows the TODO file's first 3 unchecked top-level items instead of none, and items inside HTML comments are ignored. When the 800-character cap drops TODO lines, a `- todo: +N not shown, read .claude/tasks/TODO.md` line counts them. `/init-project`, `/onboard` and `/capitalize` seed new TODO files with a `## Actionable` section. The session-start doctrine (`CLAUDE.global.md`) now trusts the digest and reads `.claude/tasks/TODO.md` only when no digest prints or the task needs it. ## [3.0.0] — 2026-11-12 diff --git a/CLAUDE.global.md b/CLAUDE.global.md index c1975c6..f4eadeb 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -50,14 +50,14 @@ code" wins. Repo-specific instructions override both. Hacky fix → rebuild clean, no over-engineering. ## Session start -1. Read `.claude/tasks/TODO.md`. The banner's `memory digest` lists open - blockers and the last journal line: apply both before touching - anything; a `+N` line → read those entries in `blockers.md`. No - digest (foreign repo, memory mod off) → list the open blockers - yourself. +1. The banner's `memory digest` lists open blockers, the first unchecked TODO + items (`## Actionable`, else the file's first) and the last journal line: + apply them before touching anything; a `- open: +N` line → read those + entries in `blockers.md`. No digest (foreign repo, memory mod off) → read + `.claude/tasks/TODO.md` and list the open blockers yourself. 2. Read a registry (`.claude/memory/`: decisions, learnings, blockers, - journal, evals) when the task needs it; planning flows scan them per - `~/.claude/lib/analyze-before-plan.md`. + journal, evals) or `.claude/tasks/TODO.md` when the task needs it; + planning flows scan them per `~/.claude/lib/analyze-before-plan.md`. 3. Either missing → create it first (templates: `~/.claude/templates/memory/`). ## Workflow diff --git a/README.md b/README.md index c208214..97cbdea 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ Limits: a main-loop switch re-reads cold the part of the context the target mode - Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists the milestones of this session and of the earlier ones kept in the store, then the failures as `NEW` or `known ` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded through `lib/memory.sh index`; when that reader is unavailable every entry is matched and the `index:` line ends `status reader unavailable`), earlier sessions marked. Every text it returns is data. It never writes a registry; every call reads the statuses through `lib/memory.sh index`. - Recall: the mod hands registry entries back at the moment they matter. A prompt typed in the composer (never a slash command, at least 5 content words, stop words excluded) triggers it when it is the first of a context (start, `/clear`, `/compact`), comes after 30 minutes idle with at least 8 content words, or holds a design or analysis word (plan, architecture, design, why, explain, analyse, review, audit and their French forms). BM25 ranks the live BDR, LRN and BLK entries, one haiku call keeps at most 2, bounded to 5 seconds. The context block `memory recall:` carries one line per entry (ID, title, lesson), at most 1500 characters per turn, each entry once per context. Any failure or timeout injects nothing. - Known error: a Bash failure whose key matches a live BLK or LRN entry attaches `memory: known — <lesson>` to the tool answer, once per ID per context, from the same 1500-character budget. Sub-agents get this channel only. -- Digest: `hooks/session-start.sh` prints `memory digest:` on `startup`, `clear` and `compact` (never `resume`) in a project that has `.claude/memory/`: up to 3 open BLK from `memory.sh index blocker` (the rest counted, upstream ones counted), up to 3 unchecked Actionable TODO items, the last journal line, 800 characters at most. When the cap bites, TODO lines drop first, then nothing else. Without `timeout` and `jq` it prints only from a terminal. +- Digest: `hooks/session-start.sh` prints `memory digest:` on `startup`, `clear` and `compact` (never `resume`) in a project that has `.claude/memory/`: up to 3 open BLK from `memory.sh index blocker` (the rest counted, upstream ones counted), up to 3 unchecked TODO items (from a `## Actionable` or `### Actionable` section, else the file's first 3 unchecked top-level items; items inside HTML comments ignored), the last journal line, 800 characters at most. When the cap bites, TODO lines drop first and a `- todo: +N not shown, read .claude/tasks/TODO.md` line counts them; nothing else drops. Without `timeout` and `jq` it prints only from a terminal. - Recall switch: `{"enabled": true, "recall": false}` in `~/.claude/memory.json` cuts the injections (recall and known-error line) and keeps capture. Every ask is logged under the `l:<root>` store key (last 200 records, 64 KiB), never shown: when, session, agent, channel, the IDs injected, the `trigger` (`fresh`, `idle`, `keyword`, `tool`) and the `outcome` (`injected`, `none`, `timeout`, `refused`, `paused`; an ask that injects nothing is logged with no IDs); a prompt ask also logs `cands` (BM25 candidates after the seen filter) and `ms` (rerank wall time, when a rerank ran). `/memory-feedback` reads it. - Recall residuals: measured on 14 days of this repo's transcripts, precision is 54 to 61 % against a 64 % bar, so recall ships on and switchable, and the log decides. The router's classifier label is not used. EVAL entries are not recalled. Each failing command that matches an entry spawns one `memory.sh index`. The haiku bound drops the recalls that answer slower than 5 seconds. - Feedback: `/memory-feedback` (phase 4d) labels each injected entry from its transcript, with a 5-label spot check by you, and reports precision, misses, noisy entries and promotion candidates against `lib/memory-feedback/thresholds.ts`. Two gates: prompt at 20 labelled asks or 35 days, tool at 10 injections (one 35-day extension, then closed). Data stays local in `~/.claude/memory-feedback/` (IDs, enums and repo tags only, never in git). The session banner prints `memory feedback: … → /memory-feedback` when a run is due, and goes silent once both gates are recorded or with `"recall": false`. diff --git a/USAGE.md b/USAGE.md index 2b6a179..72ae786 100644 --- a/USAGE.md +++ b/USAGE.md @@ -216,7 +216,7 @@ Le mod `mods/memory/` note les échecs Bash et les jalons de la session pour que - L'outil : `mcp__memory__memory_pending` (différé : un skill le charge une fois avec `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` et les étapes CAPITALIZE de `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` et `/commit-change` l'appellent en premier. Il liste les jalons de la session et ceux des sessions précédentes gardés dans le store, puis les échecs `NEW` ou `known <ID>` (4-grammes de mots comparés aux passages entre accents graves des entrées BLK et LRN, les remplacées exclues via `lib/memory.sh index` ; si ce lecteur est indisponible, toutes les entrées sont comparées et la ligne `index:` finit par `status reader unavailable`), les sessions précédentes signalées. Chaque texte est une donnée. Il n'écrit aucun registre ; chaque appel lit les statuts via `lib/memory.sh index`. - Rappel : le mod ramène les entrées des registres au bon moment. Un prompt tapé dans le composer (jamais une commande slash, au moins 5 mots de contenu, mots vides exclus) le déclenche s'il est le premier d'un contexte (démarrage, `/clear`, `/compact`), s'il suit 30 minutes d'inactivité avec au moins 8 mots de contenu, ou s'il contient un mot de conception ou d'analyse (plan, architecture, design, pourquoi, explique, analyse, review, audit et leurs équivalents anglais). BM25 classe les entrées BDR, LRN et BLK vivantes, un appel haiku en garde 2 au plus, borné à 5 secondes. Le bloc de contexte `memory recall:` porte une ligne par entrée (ID, titre, leçon), 1500 caractères par tour au plus, chaque entrée une fois par contexte. Un échec ou un dépassement n'injecte rien. - Erreur connue : un échec Bash dont la clé correspond à une entrée BLK ou LRN vivante ajoute `memory: known <ID> <titre> — <leçon>` à la réponse de l'outil, une fois par ID et par contexte, sur le même budget de 1500 caractères. Les sous-agents n'ont que ce canal. -- Digest : `hooks/session-start.sh` affiche `memory digest:` sur `startup`, `clear` et `compact` (jamais `resume`) dans un projet qui a `.claude/memory/` : jusqu'à 3 BLK ouverts issus de `memory.sh index blocker` (le reste compté, les « upstream » comptés), jusqu'à 3 items Actionable non cochés du TODO, la dernière ligne du journal, 800 caractères au plus. Quand le plafond mord, les lignes TODO tombent d'abord, rien d'autre. Sans `timeout` ni `jq`, il ne s'affiche que depuis un terminal. +- Digest : `hooks/session-start.sh` affiche `memory digest:` sur `startup`, `clear` et `compact` (jamais `resume`) dans un projet qui a `.claude/memory/` : jusqu'à 3 BLK ouverts issus de `memory.sh index blocker` (le reste compté, les « upstream » comptés), jusqu'à 3 items non cochés du TODO (section `## Actionable` ou `### Actionable`, sinon les 3 premiers items de premier niveau du fichier ; items en commentaire HTML ignorés), la dernière ligne du journal, 800 caractères au plus. Quand le plafond mord, les lignes TODO tombent d'abord et une ligne `- todo: +N not shown, read .claude/tasks/TODO.md` les compte ; rien d'autre ne tombe. Sans `timeout` ni `jq`, il ne s'affiche que depuis un terminal. - Interrupteur du rappel : `{"enabled": true, "recall": false}` dans `~/.claude/memory.json` coupe les injections (rappel et ligne d'erreur connue) et garde la capture. Chaque demande est journalisée sous la clé de store `l:<racine>` (200 enregistrements, 64 Kio), jamais affichée : date, session, agent, canal, IDs injectés, `trigger` (`fresh`, `idle`, `keyword`, `tool`) et `outcome` (`injected`, `none`, `timeout`, `refused`, `paused` ; une demande qui n'injecte rien est journalisée sans ID) ; une demande sur prompt note aussi `cands` (candidats BM25 après le filtre des entrées déjà vues) et `ms` (durée du rerank, quand il a tourné). `/memory-feedback` la lit. - Limites du rappel : mesurée sur 14 jours de transcripts de ce dépôt, la précision est de 54 à 61 % pour une barre à 64 %, donc le rappel est livré actif et coupable, et le journal tranchera. L'étiquette du classifieur du routeur n'est pas utilisée. Les entrées EVAL ne sont pas rappelées. Chaque commande en échec qui correspond à une entrée lance un `memory.sh index`. La borne haiku écarte les rappels qui répondent après 5 secondes. - Retour d'usage : `/memory-feedback` (phase 4d) étiquette chaque entrée injectée depuis son transcript, avec un contrôle de 5 étiquettes par toi, et donne la précision, les manqués, les entrées bruyantes et les candidates à promotion face aux seuils de `lib/memory-feedback/thresholds.ts`. Deux gates : prompt à 20 demandes étiquetées ou 35 jours, outil à 10 injections (une prolongation de 35 jours, puis fermé). Les données restent locales dans `~/.claude/memory-feedback/` (IDs, enums et étiquettes de dépôt seulement, jamais dans git). La bannière de session affiche `memory feedback: … → /memory-feedback` quand un passage est dû, et se tait une fois les deux gates enregistrés ou avec `"recall": false`. diff --git a/hooks/session-start.sh b/hooks/session-start.sh index 1927130..eba1ff9 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -326,9 +326,21 @@ _digest_blockers() { # <root> <memory.sh> [ -n "$more" ] && echo "- open: $more" } -_digest_todo() { # <root> → first 3 unchecked Actionable items - awk '/^### Actionable/ { on = 1; next } /^#/ { on = 0 } - on && sub(/^- \[ \] /, "") && n++ < 3 { print "- todo: " $0 }' \ +# <root> → first 3 unchecked Actionable items, else the file's first 3. +# Comment blocks (as _digest_journal) hide headings and items; indented +# items never count. +_digest_todo() { + awk '/^[ \t]*<!--/ { c = 1 } + !c && /^###? Actionable([ \t\r]|$)/ { on = 1; next } + !c && /^#/ { on = 0 } + !c && /^- \[ \] / { + t = substr($0, 7) + if (on && a < 3) A[++a] = t + if (f < 3) F[++f] = t + } + /-->/ { c = 0 } + END { if (a) { n = a; for (i = 1; i <= n; i++) print "- todo: " A[i] } + else for (i = 1; i <= f; i++) print "- todo: " F[i] }' \ "$1/.claude/tasks/TODO.md" } @@ -339,22 +351,42 @@ _digest_journal() { # <root> → last journal bullet [ -n "$last" ] && echo "- journal: ${last#- }" } +# How many leading todo lines fit in <room> chars (newline included). +_digest_fit() { # <room>; reads the array todo of the caller + local line size=0 shown=0 + for line in "${todo[@]}"; do + size=$((size + ${#line} + 1)) + [ "$size" -le "$1" ] || break + shown=$((shown + 1)) + done + echo "$shown" +} + +_digest_marker() { # <dropped count> + echo "- todo: +$1 not shown, read .claude/tasks/TODO.md" +} + # The block: header + open BLK lines + count line + todo lines + journal. # Todo lines are added in order while the block stays <= 800 chars, so the -# last ones drop first; header, open BLK lines (3 x 160 max), count line and -# journal always stay and always fit. The only loop is bounded by the todo -# count (3). Stays bash 3.2 safe (checked by SD11). +# last ones drop first; when one drops, room is reserved for a marker line +# that counts the dropped ones. Header, open BLK lines (3 x 160 max), count +# line, marker and journal always stay and always fit. The only loops are +# bounded by the todo count (3). Stays bash 3.2 safe (checked by SD11). # Built in a variable and printed once, so a failure mid-way prints nothing. _digest_assemble() { # reads the arrays blk, cnt, todo, jr of the caller - local head="memory digest:" tail="" body="" line size - for line in "${blk[@]}" "${cnt[@]}"; do head+=$'\n'"$line"; done + local out="memory digest:" tail="" line room shown + for line in "${blk[@]}" "${cnt[@]}"; do out+=$'\n'"$line"; done for line in "${jr[@]}"; do tail=$'\n'"$line"; done - size=$((${#head} + ${#tail})) - for line in "${todo[@]}"; do - [ $((size + ${#line} + 1)) -le 800 ] || break - body+=$'\n'"$line"; size=$((size + ${#line} + 1)) - done - printf '%s%s%s\n' "$head" "$body" "$tail" + room=$((800 - ${#out} - ${#tail})) + shown=$(_digest_fit "$room") + if [ "$shown" -lt "${#todo[@]}" ]; then + line=$(_digest_marker 1) + shown=$(_digest_fit $((room - ${#line} - 1))) + fi + for line in "${todo[@]:0:shown}"; do out+=$'\n'"$line"; done + [ "$shown" -lt "${#todo[@]}" ] && + out+=$'\n'"$(_digest_marker $((${#todo[@]} - shown)))" + printf '%s%s\n' "$out" "$tail" } _memory_digest() { # <project-root> diff --git a/lib/tests/session-digest.test.sh b/lib/tests/session-digest.test.sh index 5ea2e61..0b0a533 100644 --- a/lib/tests/session-digest.test.sh +++ b/lib/tests/session-digest.test.sh @@ -71,12 +71,57 @@ check SD3-empty-source "$(run "$p" - | grep -c 'memory digest:')/$rc" 1/0 mkdir -p "$WORK/sd4" check SD4-no-memory "$(run "$WORK/sd4" - | grep -c 'memory digest:')" 0 -# SD5: TODO without ### Actionable -> no todo line (others stay) +# todos <proj> <text...>: write the project TODO.md fixture (\n expands) +todos() { + local IFS= p=$1; shift + printf '%b' "$*" > "$p/.claude/tasks/TODO.md" +} +# todo_lines <proj>: the digest's todo lines, one per output line +todo_lines() { run "$1" - | digest | grep '^- todo:'; } + +# SD5: TODO without Actionable -> fallback to the file's first item p=$(mkproj sd5) blk "$p" 1 open "Only blocker" -printf '### Backlog\n- [ ] hidden\n' > "$p/.claude/tasks/TODO.md" +todos "$p" '### Backlog\n- [ ] hidden\n' check SD5-no-actionable "$(run "$p" - | digest)" 'memory digest: -- open: BLK-001 Only blocker' +- open: BLK-001 Only blocker +- todo: hidden' + +# SD5b: a `##` Actionable section wins over earlier items +p=$(mkproj sd5b) +todos "$p" '### Backlog\n- [ ] early\n## Actionable\n- [ ] act\n' +check SD5b-section-wins "$(todo_lines "$p")" '- todo: act' + +# SD5c: empty section (only checked) -> fallback, capped at 3 +p=$(mkproj sd5c) +todos "$p" '## Actionable\n- [x] done\n\n## Later\n' \ + '- [ ] fb1\n- [ ] fb2\n- [ ] fb3\n- [ ] fb4\n' +check SD5c-fallback-cap "$(todo_lines "$p")" '- todo: fb1 +- todo: fb2 +- todo: fb3' + +# SD5d: indented items never count, in the section nor in the fallback +p=$(mkproj sd5d) +todos "$p" '## Actionable\n- [ ] top\n - [ ] sub\n' +check SD5d-section "$(todo_lines "$p")" '- todo: top' +todos "$p" '# T\n - [ ] sub\n- [ ] top\n - [ ] deep\n' +check SD5d-fallback "$(todo_lines "$p")" '- todo: top' + +# SD5e: items and headings inside <!-- --> never count +p=$(mkproj sd5e) +todos "$p" '- [ ] first\n<!--\n- [ ] ghost\n### Actionable\n-->\n- [ ] real\n' +check SD5e-fallback "$(todo_lines "$p")" '- todo: first +- todo: real' +todos "$p" '## Actionable\n<!--\n- [ ] ghost\n# x\n-->\n- [ ] real\n' \ + '<!-- one line - [ ] no -->\n## Z\n- [ ] after\n' +check SD5e-in-section "$(todo_lines "$p")" '- todo: real' + +# SD5f: `#### Actionable` and `### Actionables` are not sections +p=$(mkproj sd5f) +todos "$p" '- [ ] first\n#### Actionable\n- [ ] x\n### Actionables\n- [ ] y\n' +check SD5f-not-sections "$(todo_lines "$p")" '- todo: first +- todo: x +- todo: y' # SD6: a 400-char journal line with an em dash, cut at 160, valid UTF-8 p=$(mkproj sd6) @@ -92,7 +137,8 @@ out=$(cd "$p" && LC_ALL=C.UTF-8 bash "$SS" </dev/null 2>/dev/null | digest | tai check SD6-len-160 "${#out}" 160 # SD7: 3 open BLK + 3 long todos + a journal line over the 800 cap: todo -# lines drop from the last, the journal and every BLK line stay +# lines drop from the last, a marker counts them, the journal and every +# BLK line stay rep() { printf "%$2s" '' | tr ' ' "$1"; } p=$(mkproj sd7) for i in 1 2 3; do blk "$p" "$i" open "$(rep b 100)"; done @@ -104,12 +150,24 @@ want="memory digest: - open: BLK-002 $(rep b 100) - open: BLK-003 $(rep b 100) - todo: A$(rep x 150)… -- todo: B$(rep x 150)… +- todo: +2 not shown, read .claude/tasks/TODO.md - journal: $(rep j 100)" out=$(run "$p" - | digest) check SD7-drops-last-todo "$out" "$want" check SD7-le-800 "$([ "${#out}" -le 800 ] && echo yes || echo no)" yes +# SD7c: 3 todos fit between 751 and 800 chars: all shown, no marker +p=$(mkproj sd7c) +for i in 1 2 3; do blk "$p" "$i" open "$(rep b 100)"; done +printf '### Actionable\n- [ ] A%s\n- [ ] B%s\n- [ ] C%s\n' \ + "$(rep x 91)" "$(rep x 91)" "$(rep x 91)" > "$p/.claude/tasks/TODO.md" +printf '## d\n- %s\n' "$(rep j 100)" > "$p/.claude/memory/journal.md" +out=$(run "$p" - | digest) +check SD7c-3-todos "$(printf '%s\n' "$out" | grep -c '^- todo: [ABC]')" 3 +check SD7c-no-marker "$(printf '%s\n' "$out" | grep -c 'not shown')" 0 +check SD7c-size \ + "$([ "${#out}" -gt 751 ] && [ "${#out}" -le 800 ] && echo ok)" ok + # SD7b: the worst case (10 open BLK, long titles, 3 long todos, 160-char # journal): all todos drop, 3 BLK + count + journal stay, whole lines, <= 800 p=$(mkproj sd7b) @@ -120,7 +178,9 @@ printf '### Actionable\n- [ ] %s\n- [ ] %s\n' "$(rep x 300)" "$(rep x 300)" \ printf '## d\n- %s\n' "$(rep j 300)" > "$p/.claude/memory/journal.md" out=$(run "$p" - | digest) check SD7b-le-800 "$([ "${#out}" -le 800 ] && echo yes || echo no)" yes -check SD7b-no-todo "$(printf '%s\n' "$out" | grep -c '^- todo:')" 0 +check SD7b-no-todo "$(printf '%s\n' "$out" | grep -c '^- todo: [x]')" 0 +check SD7b-marker "$(printf '%s\n' "$out" | + grep -c '^- todo: +2 not shown, read .claude/tasks/TODO.md$')" 1 check SD7b-3-blk "$(printf '%s\n' "$out" | grep -c '^- open: BLK-')" 3 check SD7b-count-line "$(printf '%s\n' "$out" | grep -x -- '- open: +7 more, +1 upstream')" '- open: +7 more, +1 upstream' check SD7b-journal "$(printf '%s\n' "$out" | tail -1)" "- journal: $(rep j 148)…" diff --git a/skills/capitalize/SKILL.md b/skills/capitalize/SKILL.md index 7b0e0d1..dbf0681 100644 --- a/skills/capitalize/SKILL.md +++ b/skills/capitalize/SKILL.md @@ -80,7 +80,7 @@ ls .claude/tasks/TODO.md 2>/dev/null reconcile volet (STEP 2B) on it: ```bash mkdir -p .claude/tasks - printf '# TODO\n\n## %s\n' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md + [ -f .claude/tasks/TODO.md ] || printf '# TODO\n\n## Actionable\n<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) -->\n\n## %s\n' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md ``` ## STEP 1 — SCAN THE CONVERSATION @@ -372,7 +372,7 @@ CAPITALIZE COMPLETE — <YYYY-MM-DD> (<pre-wipe flush | session-close>) Then the closing line — pick by the STEP 5C persist result (`<mode>` = `Context flushed` for pre-wipe, `Session closed` for ritual): -- **auto-persisted (push mode `auto`, finish rc 0 AND `ahead` = 0)** → `✅ <mode> + persisted to origin/develop (<short>). Next session: TODO.md and the startup digest (open blockers, last journal line).` +- **auto-persisted (push mode `auto`, finish rc 0 AND `ahead` = 0)** → `✅ <mode> + persisted to origin/develop (<short>). Next session: the startup digest (open blockers, actionable TODO, last journal line).` On the `--no-push` path ONLY read TWO facts first, each its own Bash call: `bash "$HOME/.claude/lib/gitflow.sh" push-mode` and `git rev-list --count origin/chore/<name>..chore/<name> 2>/dev/null || echo unknown` (`branch_ahead`). `<push mode>` below is the verb's word. The WORKING-branch and rc 3 paths have no `chore/<name>` and never use the mode. diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index ec51f8a..b16d468 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -115,7 +115,7 @@ it (doctrine: registries + TODO exist from day one; STEP 10b appends to them): ```bash mkdir -p .claude/memory .claude/tasks cp -n ~/.claude/templates/memory/{decisions,learnings,blockers,evals,journal}.md .claude/memory/ -[ -f .claude/tasks/TODO.md ] || printf '# TODO\n\n## %s\n' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md +[ -f .claude/tasks/TODO.md ] || printf '# TODO\n\n## Actionable\n<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) -->\n\n## %s\n' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md ``` Verify: `git init` + build passes. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 1b91edd..2d1360d 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -989,6 +989,9 @@ Format : ``` # TODO — onboard backlog (<date>) +## Actionable +<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) --> + <!-- Généré par /onboard — une entrée par proposition approuvée. Format: - [ ] [Priorité] [/skill] — description — fichiers estimés --> @@ -1028,7 +1031,7 @@ Format : | Audit SEO/GEO à re-lancer après corrections | `/seo` ou `/geo` | | Audit docs à re-sync après changement | `/doc` | -Ne PAS écraser `.claude/tasks/TODO.md` s'il contient déjà du contenu utilisateur : append avec un séparateur : +Sans contenu utilisateur (le stub de l'onboarder compte pour aucun) : écrire le format complet, bloc `## Actionable` inclus. Avec contenu utilisateur : ne PAS écraser, append avec un séparateur et SANS second `## Actionable` : ``` <contenu existant>