From 0e5656257401c0ee07a18fa10087445293e22f3b Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 12 Nov 2026 21:58:42 +0100 Subject: [PATCH] chore(memory): BDR-147, D1b contract and plan --- .claude/memory/decisions.md | 6 +++ .claude/memory/journal.md | 1 + .claude/tasks/TODO.md | 2 +- .../2026-11-12-digest-todo-fallback-2130.md | 36 +++++++++++++ .../2026-11-12-digest-todo-fallback-2130.md | 52 +++++++++++++++++++ 5 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 .claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md create mode 100644 .claude/tasks/plans/2026-11-12-digest-todo-fallback-2130.md 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`).