Files
claude/.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md
T

8.4 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

  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 the four registry templates templates/memory/{decisions,learnings,blockers,evals}.md carry it (journal is not a registry: no marker); 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: MET exit=0 marker-found :: all suites green

  13. [gated 2026-10-28] memory.sh upgrade migrates 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. PROOF update (after aab9e4d, final code review): trucks_at_work is now REFUSED (bullet-list ## Index in decisions/learnings/blockers, facts would be lost; user decision at the per-repo pass, like game). Date counts corrected: the earlier zenquality 59 / angelscar356 106 were duplicates (- **Date** : spacing dialect, 65 and 106 such lines); now 0 and 1. 12/14 migrate, 2 refused untouched.