5.9 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)
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 every
templates/memory/*.mdcarries it; 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: PENDING
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).