docs(spec): memory v2 write side design + contract seed — phase 4a

This commit is contained in:
bchanot committed 2026-10-27 20:40:39 +01:00
1 parent ae9a7e3dcd
commit cdc0a4778b
2 files changed
+216

No files matched your search

@@ -0,0 +1,31 @@
# 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
1. `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).
2. `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.
3. `memory.sh journal "<line>"` appends the line under today's `## YYYY-MM-DD` heading, creating the heading at the end of journal.md when absent.
4. `memory.sh index [<registry>]` prints a markdown table (ID | Date | Title | Status) derived from headings and the status parser only; no `## Index` block is read.
5. `memory.sh check [--staged]` validates: heading shape, ID uniqueness, v2 marker present, no `## Index` block in a v2 file; `--staged` also refuses a removed line inside an existing entry. It runs inside `add` and in `make test`; the generated pre-commit hook is untouched.
6. 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_open` on a fixture holding BLK-032..034 as written today returns none of them; the existing run-reconcile T1/T2 stay green.
7. The four `## Index` blocks 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.
8. Per-file v2 marker: every registry of this repo and every `templates/memory/*.md` carries it; a file without it is v1: the writer still appends, `check` reports it, and the per-project session banner warns `registry v1`.
9. 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.
10. CLAUDE.global.md "Memory registries": writes go only through `lib/memory.sh`; the "Registries load every session" premise replaced; the heading and the bold label `Always English, always caveman` kept (census); file line count not above today's 333.
11. Dropped, must NOT appear: Meta line, 434-entry backfill, scope/critical labels, triggers field, English validator.
12. 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 test` all 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).