8.0 KiB
CONTRACT — memory-v2-write (phase 4a)
- date: 2026-10-27 | flow: ship-feature | branch: feature/memory-v2-write (off develop
ae9a7e3) - status: active
REQUEST (verbatim — IMMUTABLE)
Phase 4a of the context mod queue (BDR-125), TODO.md "Phase 4a, memory v2 write side: shell, no mod": lib/memory.sh as the single registry writer, like gitflow.sh (add <kind> --title --body-file [--status --supersedes] allocating the next ID from headings under flock, status <ID> <new> appending a dated status line, journal "<line>", index printed on demand from headings, check [--staged] validator in add/check + make test, not in the pre-commit); one shared status parser (own-header [tag] first, then last status-bearing line wins) fixing the BLK-032..034 false-open in reconcile with a regression test; the four generated ## Index blocks removed in one /prune-memory curation and the Index steps dropped from capitalize, ship-feature, commit-changer, prune-memory § D; a per-file v2 marker so the 8 v1 projects keep working and doctor warns "registry v1"; citers patched (capitalize, close, prune-memory, CAPITALIZE steps of feat/bugfix/hotfix/ship-feature/commit-change, lib/capitalize-commit.md, lib/analyze-before-plan.md, lib/reconcile.sh, templates/memory, onboard/init-project, doctrine-citers census, CLAUDE.global.md Memory registries). Dropped: Meta line, backfill, scope/critical labels, triggers field, English validator. Proof: writer round-trip, flock race test, status parser on the three false-open BLKs + fixtures, v1 project untouched, make test green.
(user: "ok tu peux passer a la suite", 2026-10-27, after the phase 0b and extract-hardening merges.)
CLARIFICATIONS
(pass A: scope gaps surfaced by the read-before, settled at the STEP 1 brainstorm — see [gated] rows below)
Q: files outside the seed FILE SCOPE that the approved plan (STEP 3 gate 2026-10-28, plan r3 Tasks 2/3/5/6) requires? / A: agents/analyzer.md (Task 5 citer), lib/tests/run-deterministic.sh (Task 3 chokepoint test), skills/reconcile/SKILL.md (Task 2 parser doc + test count), skills/prune-memory/tests/fixtures/red6-check/ added and red6-orphan/ deleted (Task 6: RED-6 asserted "no false ORPHAN INDEX", a check that only exists with an Index; § D removal makes it obsolete, red6-check replaces it as the flip test) [gated 2026-10-28, plan approval] Q: EVAL Index "Action" column at upgrade? / A: the 2026-10-27 gate dropped the column on the premise the body carries Action; where the body has no status word, the Index action is materialized as a body status line (verifier gap 2026-10-28, EVAL-005/028/040) [gated 2026-10-27, refined 2026-10-28]
ACCEPTANCE CRITERIA
-
lib/memory.sh [-C dir] add <kind> --title <t> --body-file <f> [--status <s>] [--supersedes <ID>]appends one entry## <PREFIX>-NNN — <title> [<status>] (<date>)+ body at the end of the registry, NNN = max heading ID + 1, under a lock; prints the new ID on stdout; rc 2 with a named reason on a bad kind, a missing body file, a duplicate ID after allocation, or a validator failure (nothing written). -
memory.sh status <ID> <new>appends a dated status line to that entry (inserted before the next heading, after the body), never rewrites an existing line; rc 2 when the ID does not exist. -
memory.sh journal "<line>"appends the line under today's## YYYY-MM-DDheading, creating the heading at the end of journal.md when absent. -
memory.sh index [<registry>]prints a markdown table (ID | Date | Title | Status) derived from headings and the status parser only; no## Indexblock is read. -
memory.sh check [--staged]validates: heading shape, ID uniqueness, v2 marker present, no## Indexblock in a v2 file;--stagedalso refuses a removed line inside an existing entry. It runs insideaddand inmake test; the generated pre-commit hook is untouched. -
One shared status parser (lib function used by memory.sh and lib/reconcile.sh): candidates are the entry's own header
[tag]and labelled status lines only (never a free word in prose); the last candidate in document order wins.reconcile_blk_openon a fixture holding BLK-032..034 as written today returns none of them; the existing run-reconcile T1/T2 stay green. -
The four
## Indexblocks of this repo's registries are removed in one deterministic step; every status or supersession that lived only in an Index row is first materialized as a status line in the entry body (oracle: parser(body) == former Index status for every such row); heading count unchanged. -
Per-file v2 marker: every registry of this repo and the four registry templates
templates/memory/{decisions,learnings,blockers,evals}.mdcarry it (journal is not a registry: no marker); a file without it is v1: the writer still appends,checkreports it, and the per-project session banner warnsregistry v1. -
Citers patched in the same branch: capitalize, close, prune-memory (§ D removed, STEP 3 status carrier =
memory.sh status, STEP 4 verify =memory.sh check), CAPITALIZE steps of feat/bugfix/hotfix/ship-feature/commit-change, init-project, lib/capitalize-commit.md (rc 5 documented), lib/analyze-before-plan.md, lib/reconcile.sh, templates/memory, onboard; doctrine-citers census green. -
CLAUDE.global.md "Memory registries": writes go only through
lib/memory.sh; the "Registries load every session" premise replaced; the heading and the bold labelAlways English, always cavemankept (census); file line count not above today's 333. -
Dropped, must NOT appear: Meta line, 434-entry backfill, scope/critical labels, triggers field, English validator.
-
Proof: writer round-trip test, concurrent-add race test (two adds, distinct IDs), status parser on BLK-032..034 fixtures, every other project's
.claude/memory/untouched (no diff outside this repo),make testall green, shellcheck clean, every new lib line ≤ 80 chars, functions ≤ 25 logic lines / ≤ 5 locals / ≤ 5 params. CHECK: make test 2>&1 | tail -1 EXPECT: all suites green EVIDENCE: MET exit=0 marker-found :: all suites green -
[gated 2026-10-28]
memory.sh upgrademigrates every measured v1 dialect (hyphen, pipe,###headings, title-suffix status,date: · status:,**Statut** :, no frontmatter) to v2: headings normalized to## ID — title (date), frontmatter added, open/closed verdict of every entry identical before and after (oracle), idempotent; proven on copies of the 13 other projects. Applying it to those repos is a later per-repo pass, not this branch.
FILE SCOPE
lib/memory.sh (new), lib/tests/memory.test.sh (new), lib/tests/fixtures/* (new fixtures), lib/reconcile.sh, lib/tests/run-reconcile.sh, lib/memory-commit.sh, lib/capitalize-commit.md, lib/analyze-before-plan.md, skills/capitalize/SKILL.md, skills/close/SKILL.md, skills/prune-memory/SKILL.md (+ tests/run-deterministic.sh, test-prompts.json), skills/feat/SKILL.md, skills/bugfix/SKILL.md, skills/hotfix/SKILL.md, skills/ship-feature/SKILL.md, skills/commit-change/SKILL.md, agents/commit-changer.md, skills/init-project/SKILL.md, agents/onboarder.md, skills/onboard/SKILL.md, templates/memory/.md, hooks/session-start.sh, CLAUDE.global.md (Memory registries), Makefile (suite glob already covers lib/tests/.test.sh), .claude/memory/{decisions,learnings,blockers,evals}.md (Index removal + marker), mods/model-router/routing.json (only if a new row is needed), docs (CHANGELOG at STEP 8).
PROOF — criterion 13 (controller, 2026-10-28, after 28c5a42)
Fresh scratchpad copies of the 14 project memory dirs, bash lib/memory.sh -C <copy> upgrade (relative lib path), then check, then a second upgrade (cksum): 13 rc 0 + check 0 + idempotent (config 2, robin_petier 6, zenquality 15, angelscar356 32, bchanot-cv 3 added status lines; others 0); game rc 2 (## BDR-027 ADDENDUM, ## BDR-061 ADDENDUM headings, duplicate BLK IDs: plan Deviation 6, user decision at the per-repo pass); git -C <orig> status --short .claude/memory empty on all 14. The first run of this proof (before 28c5a42) found the template path resolved after the -C cd (rc 2 on config, faunosteo, for_you, trucks_at_work): fixed in 28c5a42, test T15-relpath.