chore(memory): BDR-147, D1b contract and plan
This commit is contained in:
1 parent
8a175a5dbe
commit
0e56562574
5 files changed
+96
-1
No files matched your search
@@ -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]].
|
||||
@@ -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 `<redacted>`, 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.
|
||||
@@ -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## <date>`, 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## <date>`, 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)
|
||||
|
||||
@@ -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<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) -->\n\n## <date>\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.
|
||||
@@ -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]*<!--` sets c, `-->` 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: <text>`.
|
||||
- comment the function: "<root> → 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<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) -->\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 (<date>)` (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 (`<!--` at line start opens, `-->` 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- [ ] ghost\n### Actionable\n-->\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 '<fmt>' "$(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 (`<!--\n- [ ] ghost\n### Actionable\n-->`) + `- [ ] 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 '<same fmt>' "$(date +%Y-%m-%d)" > .claude/tasks/TODO.md`).
|
||||
Reference in new issue
Block a user