From cdc0a4778b4205ad8592952db7b16044037fb6d3 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 27 Oct 2026 20:40:39 +0100 Subject: [PATCH] =?UTF-8?q?docs(spec):=20memory=20v2=20write=20side=20desi?= =?UTF-8?q?gn=20+=20contract=20seed=20=E2=80=94=20phase=204a?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-27-memory-v2-write-2030.md | 31 +++ .../2026-10-27-memory-v2-write-design.md | 185 ++++++++++++++++++ 2 files changed, 216 insertions(+) create mode 100644 .claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md create mode 100644 docs/superpowers/specs/2026-10-27-memory-v2-write-design.md diff --git a/.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md b/.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md new file mode 100644 index 0000000..41fa4c6 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md @@ -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 --title --body-file [--status --supersedes]` allocating the next ID from headings under flock, `status ` appending a dated status line, `journal ""`, `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 --title --body-file [--status ] [--supersedes ]` appends one entry `## -NNN — [<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). diff --git a/docs/superpowers/specs/2026-10-27-memory-v2-write-design.md b/docs/superpowers/specs/2026-10-27-memory-v2-write-design.md new file mode 100644 index 0000000..0fe12bc --- /dev/null +++ b/docs/superpowers/specs/2026-10-27-memory-v2-write-design.md @@ -0,0 +1,185 @@ +# Memory v2, write side: design + +Phase 4a of BDR-125. Contract `.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md`. +Shell only, no mod. Four gated choices (2026-10-27): `memory.sh upgrade` runs in this +branch; mkdir lock in the git common dir; `registry v1` warn in the session banner; +the LRN "Applies to" and EVAL "Action" Index columns are dropped. + +## 1. Problem + +Five registries, ~1 MB, written by prose instructions in nine skills and agents: every +writer re-derives the next ID, appends by Edit or ad hoc shell, and is told to maintain a +`## Index` table that drifts (16 missing rows today). Status lives in three places (header +tag, body line, Index column) and `lib/reconcile.sh` reads it with a lexical grep that drops +the entry's own header and takes `fail-open` or `` `data:` OPEN `` in a Solution line for a +status: BLK-032..034 are `[resolved]` and reported open. Thirteen supersessions and eleven +BDR statuses exist only in an Index row. + +## 2. Shape + +### 2.1 `lib/memory.sh` (sourceable + CLI, the `project-rules.sh` skeleton) + +``` +memory.sh [-C <dir>] add <kind> --title <t> --body-file <f> [--status <s>] [--supersedes <ID>] +memory.sh [-C <dir>] status <ID> <text> +memory.sh [-C <dir>] journal <line> [--date YYYY-MM-DD] +memory.sh [-C <dir>] index [<kind>] +memory.sh [-C <dir>] check [--staged] [<memory-dir>] +memory.sh [-C <dir>] upgrade [<memory-dir>] +``` +`<kind>` = `decision | learning | blocker | eval` → `decisions.md` BDR, `learnings.md` LRN, +`blockers.md` BLK, `evals.md` EVAL. Registry dir `.claude/memory` under `<dir>` (default +cwd). Unknown verb or bad arity → usage, rc 2. Every refusal names its reason on stderr, +rc 2, nothing written. `/usr/bin/grep` pinned (LRN-074), no `grep -q` in a pipe (LRN-189), +no census-banned idiom (BDR-110). Functions ≤ 25 logic lines, ≤ 5 locals, lines ≤ 80. + +**add**: under the lock, next ID = max `^## <PREFIX>-[0-9]+` + 1, zero-padded to 3 digits +(4 past 999). Appends at end of file (after a blank line): +``` +## BDR-129 — <title> [<status>] (<date>) +<body file verbatim, trailing blank lines trimmed> +``` +`[<status>]` only with `--status`; `(<date>)` always (today, or `MEMORY_DATE` for tests). +Title refused when empty, over 160 chars, or containing a newline, `[`, `]` or `|`. Body +file refused when missing or empty; a blocker body must hold at least one backtick span +(the "quotes ≥ 1 error verbatim" rule). `--supersedes <ID>` (same registry, must exist): +the new body gets a last line `Supersedes [[<ID>]].` and the old entry gets a status line +`superseded by <new ID>` in the same lock. After the write, `check` runs on the file; a +failure restores the file from the pre-write copy and returns rc 2. On success the new ID is +the only stdout line. A v1 file (no marker, § 2.4) is written the same way with a stderr +warning; its post-write `check` is skipped. + +**status**: `status <ID> <text>` inserts `- **Status (<date>)**: <text>` as the last body +line of the entry: before the `---`/blank run that precedes the next `^## ` heading, or at +end of file. Never rewrites a line. Unknown ID → rc 2. + +**journal**: appends `<line>` under `## <date>` in `journal.md`; the heading is created at +end of file (preceded by a blank line) when absent; `(cont.)` legacy headings are not +matched. Multi-line input → rc 2. + +**index**: prints a markdown table `| ID | Date | Title | Status |` for one kind or all four +(one table per registry, registry name as a line above). Date = heading `(YYYY-MM-DD)`, else +the first `- **Date**:` body line, else empty. Status = § 2.2 normalized value. Reads +headings and bodies only; a `## Index` block, if any, is ignored. + +**check**: on every registry of the dir (journal excluded): every `^## <PREFIX>-` heading +matches `^## <PREFIX>-[0-9]{3,} — .+$`; IDs unique; a v2 file has `format: 2` and no +`^## Index` line; a v1 file is reported `v1: <file>` on stderr and does not fail the run +(lenient by design, the upgrade is the user's call). +`--staged`: `git diff --cached -U0 -- <registry files>` must contain no `-` line other than +the diff header, i.e. no removed line inside an existing entry (an appended line is a `+`). +`make test` runs `check` on this repo's `.claude/memory`. `lib/memory-commit.sh` runs +`check --staged` after `git add` and before `git commit`; a failure is rc 6, nothing +committed, so an in-place header flip (today's practice, 438462f) is caught at the one +chokepoint flows use. `/prune-memory` curation commits go through `/commit-change`, not +memory-commit.sh, so they need no marker; the removal rule is by chokepoint, not by commit +recognition. + +**upgrade** (§ 2.3). The generated pre-commit hook (`lib/gitflow.sh`) is untouched. + +### 2.2 Shared status parser (`lib/memory.sh`, sourced by `lib/reconcile.sh`) + +`memory_entry_status <file> <ID>` prints the winning candidate line, `memory_status_word` +normalizes it. Entry = own heading through the line before the next `^## ` heading, fenced +blocks skipped. Candidates, in document order: +- the heading's trailing tag `[<tag>]` (optionally followed by `(<date>)`), never a `[…]` + elsewhere in the title (BDR-014 `[triggers]`); +- a body line whose bold **label** carries a status keyword: `^- \*\*[^*]*(Status|Resolution| + Action|UPDATE|FINAL)[^*]*\*\*` (BLK-008 `**2026-06-23 FINAL — RESOLVED**`, BLK-009 + `**2026-07-06 UPDATE — RESOLVED**`, `**Status (2026-10-23, reconcile)**`), plus the v1 + `^Status:` / `^- Status:` lines. +A word in free prose (`fail-open`, `` `data:` OPEN `` in a Solution line, `upstream` in a +sibling title) is never a candidate. Last candidate wins. Normalized value = first of +`resolved | upstream | open | accepted | implemented | shipped | superseded | deprecated | +proposed | keep | correct | deprecate` found case-insensitively in the candidate, else the +candidate's first 40 chars. `reconcile_blk_current_status` becomes a one-line call; its +`*RESOLVED*|*resolved*` classification stays. Regression fixture +`lib/tests/fixtures/blockers-v2-status.md`: BLK-032..034 copied as written today plus +BLK-008/009-shaped compounds and a Solution line with `fail-open`; expected open set +excludes all of them. `run-reconcile.sh` T1/T2 unchanged and green. + +### 2.3 `upgrade` and the Index removal + +`upgrade [<memory-dir>]`, idempotent, per registry (journal untouched): refuse without +frontmatter (rc 2, the two non-template dialects are not upgraded by this verb); already +`format: 2` → no-op. Steps, on a tmp copy, then one `cat` into place: +1. For every Index row `| ID | date | title | status |` with a known ID: if the heading has + no `(date)` and the body no `- **Date**:` line, insert `- **Date**: <date>` as the first + body line; if the status column is non-empty and its normalized value differs from the + parser's (or the parser finds none), append `- **Status (<today>, upgrade)**: <column + text verbatim>` as the last body line. LRN "Applies to" is dropped; EVAL "Action" is + already a body label. +2. Insert `format: 2` after line 1 (`---`). +3. Delete from `^## Index` through the table's last `|` line and the blank line after it. +4. Oracle, before the file is replaced: heading count and every heading line unchanged; + for every former row, `index` date == row date and normalized status == normalized + column; `check` passes. Any failure → file untouched, rc 2, the row named. +Runs in this branch on this repo's four registries as one `chore(memory)` commit (gated +2026-10-27; BDR-045's chore branch is for a standalone curation, this one ships with its +tool). Other projects are not touched: the user runs `memory.sh -C <proj> upgrade` when +they choose to. + +### 2.4 v2 marker and v1 projects + +Marker = `format: 2` on line 2 of the YAML frontmatter. `templates/memory/*.md` carry it and +lose the `## Index` block (new projects born v2; the template comment keeps the entry +shape with `## <ID>-XXX — <title> (<date>)`). A registry without the marker is v1: `add` +and `status` still write (lenient), `check` names it, and `hooks/session-start.sh` prints +`│ ⚠️ registry v1: .claude/memory — memory.sh upgrade │` when the cwd has a +`.claude/memory/*.md` without the marker. doctor.sh is machine-scoped and stays untouched. + +### 2.5 Lock + +`add`, `status` and `journal` take `<git-common-dir>/memory.lock` by `mkdir` (atomic on +POSIX, no `flock(1)`: absent on macOS, BDR-110), retry every 0.2 s up to 10 s, steal a lock +older than 30 s. Outside a git repo → `${TMPDIR:-/tmp}/memory-<cksum of the dir path>.lock`. +Released by an EXIT trap. The lock serializes writers of one repository (worktrees share +the common dir); two branches allocating the same ID still collide at merge, and `check` +(ID uniqueness) in `make test` reports it. + +## 3. Citers (same branch, census green) + +- `skills/capitalize/SKILL.md` STEP 4/5: body to a scratch file, `memory.sh add`, `memory.sh + journal`; dedup read (:143) on headings and bodies only. `close` inherits. +- CAPITALIZE steps of feat, bugfix, hotfix, ship-feature, init-project, commit-change + + `agents/commit-changer.md` (MODE apply with `-C <dir>`): same calls, "Update the Index" + lines removed. The `CLAUDE.md "Memory registries" (Always English, always caveman)` + citations stay byte-identical. +- `skills/prune-memory/SKILL.md`: § D Index drift removed; STEP 3.2 status flags and 3.3 + mark-superseded go through `memory.sh status`; "regenerate Index" removed; STEP 4 verify + runs `memory.sh check`; `tests/run-deterministic.sh` RED-6 asserts the STEP 4 block calls + `memory.sh check` (flip test); `test-prompts.json` id 1 reworded. +- `lib/analyze-before-plan.md`, `agents/analyzer.md`, `skills/reconcile/SKILL.md`, + `lib/reconcile.sh` header comment: "never the Index" sentences become "headings only, no + Index exists in v2"; PASS 1 unchanged. +- `lib/capitalize-commit.md`: rc 5 and the new rc 6 documented. +- `CLAUDE.global.md` "Memory registries": one sentence "Write only via `bash + ~/.claude/lib/memory.sh` (add / status / journal), never by Edit or append." and the + "Registries load every session; caveman cuts ~40%…" sentence becomes "Registries are read + by the planning flows, never loaded whole; caveman keeps every read and injection small." + Net lines ≤ 0 (file at 333, warn at 320). +- `skills/onboard/SKILL.md` S7 journal line and `agents/onboarder.md` template copy: unchanged + mechanism (templates now v2); onboard S7 may call `memory.sh -C <proj> journal`. +- `mods/model-router/routing.json`: no new row (lib, not a skill). + +## 4. Tests (`lib/tests/memory.test.sh`, hermetic, mktemp fixture with a git init) + +Round-trip (`add` → heading, ID on stdout, `index` row, `check` green); refusals (kind, +title chars, empty body, blocker without backtick, unknown ID); `status` placement before a +trailing `---` and at EOF; `journal` new and existing date; `--supersedes` both sides; race: +two `add` in background on the same registry → two distinct consecutive IDs, `check` green; +lock steal after a stale dir; v1 file: `add` warns and appends, `check` names v1, +session-start banner line present (fixture dir) and absent on v2; `check --staged` red on a +removed line, green on an appended one; `memory-commit.sh` rc 6 on that red; `upgrade`: +fixture with Index-only statuses, supersessions and dates → materialized, Index gone, +marker set, oracle green, idempotent second run; `upgrade` refuses a no-frontmatter file and +restores on an oracle failure (fixture with a tampered row). Parser: BLK-032..034 fixture +(§ 2.2). Doctrine-citers census, effort-routing lock, portability census, shellcheck, +`make test` all green. No other project's `.claude/memory` differs (`git -C <proj> status` +on the known registry projects, run by the verifier). + +## 5. Out of scope (dropped or later) + +Meta line, 434-entry backfill, scope/critical labels, triggers field, English validator, +upgrade of the pipe-heading (faunosteo) and `# Blockers (BLK)` (game) dialects, a `/memory` +skill, read-side changes (4b-4d), the "Session start" directive of CLAUDE.global.md.