Files
claude/docs/superpowers/plans/2026-10-27-memory-v2-write.md
T

44 KiB
Raw Blame History

Memory v2 write side (phase 4a) Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: lib/memory.sh becomes the only writer of .claude/memory registries, one status parser and one classifier serve memory.sh and reconcile on v2 registries, this repo's registries move to v2 (no ## Index), every citer writes through the lib.

Architecture: One sourceable bash lib on the lib/project-rules.sh skeleton (-C <dir>, verbs, rc 2 + named reason). The awk parser lives once in _MEM_AWK and is shared by index, upgrade and lib/reconcile.sh (v2 files). Writers serialize through a noclobber lock file in the git common dir. memory-commit.sh runs check --staged as the chokepoint. Revision r2 (2026-10-28) after a 3-lens challenge: FATAL(2) simplicity, CONCERNS(5) robustness, FATAL(6) correctness, every BLOCKER and MAJOR closed. Revision r3 (2026-10-28) after the confirmation round (CONCERNS(1) / CONCERNS(3) / CONCERNS(3), no BLOCKER): any-level ID allocation, open fence always refused, v1 status as a body line, one verified backup + trap for every writer, token lock with a serialized steal, exact journal key, staged-dir guard.

Tech Stack: bash 5, POSIX awk (no gawk-only features, no {n} intervals, no byte-count slicing around —), git. Tests via make test.

Spec: docs/superpowers/specs/2026-10-27-memory-v2-write-design.md (user-approved 2026-10-27). Contract: .claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md.

Reference implementation (proven r3): docs/superpowers/plans/memory-v2-write/ holds memory.sh, memory.test.sh, blockers-v2-status.md, blockers-v1-dialects.md. Proven on a git clone --shared of this repo through make test: suite PASS=112 FAIL=0 five runs in a row and under LC_ALL=C (the 15 r3 checks T14* are red against the r2 lib, 12 of them), 12 concurrent writers starting from a stale lock: 0 overlaps, 12 distinct IDs, no lock left (3 rounds), shellcheck clean, no # shellcheck disable, no line over 80 chars. upgrade on a copy of this repo's live registries: oracle-green, check-green, idempotent, its diff --staged-green, 26 statuses and 129 dates materialized, one Index status dropped and named (BDR-012). Task 2, 3 and 4 code below was applied to that clone and run through make test (run-reconcile 28 GREEN / 1 RED where the red is T6c, the gitignored skills/darwin-skill absent from a clone; run-deterministic 18/18; memory suite with T13 122/122). _mem_next_id equals max heading ID + 1 on all 59 registries of the 15 repos on this machine (r2 gave BDR-001 / LRN-001 / BLK-001 on trucks_at_work's ### registries: duplicates). Task 1 copies the files; do not rewrite them.

Global Constraints

  • Branch feature/memory-v2-write (already started, spec at cdc0a47). Never switch, never merge, never push by hand (hooks push).
  • Our code: functions ≤ 25 logic lines (see Deviations for awk programs), ≤ 5 locals, ≤ 5 params, lines ≤ 80 chars in lib/memory.sh.
  • No # shellcheck disable anywhere in the diff (floor guard, LRN-234). # shellcheck source=/dev/null directives are allowed.
  • /usr/bin/grep pinned in libs (MEM_GREP, LRN-074); no grep -q reading a pipe under pipefail (LRN-189); no sed -i, stat -c, realpath -m, grep -P (portability census, BDR-110).
  • No recursive delete through a variable except the existing trap 'rm -rf "$FIX"' EXIT mktemp pattern.
  • Hermetic tests run through make test [suite=…] only.
  • Census-cited strings stay byte-identical: every CLAUDE.md "Memory registries" (Always English, always caveman) citation, the CLAUDE.global.md heading ## Memory registries (\.claude/memory/`)and the bold labelAlways English, always caveman` (doctrine-citers, LRN-166). Do not rewrap a line that holds one.
  • CLAUDE.global.md line count must not exceed 333 after the edit.
  • Worked examples use fictional 9xx IDs (LRN-073).
  • Entry text written to registries is English caveman (BDR-009).

Deviations from the spec (named for the human gate)

  1. Lock and backup: the lock is a file created under bash noclobber (open(O_EXCL)), not a mkdir dir: uutils mkdir 0.10 on this host is not atomic (5 concurrent adds lost 2-4 entries). It holds <epoch> <pid>.<RANDOM> and is removed only by its owner's token. A lock older than 30 s, or seen empty on 10 consecutive tries (holder died between create and write), is stolen by one waiter at a time (memory.lock.steal, itself noclobber, age re-read under it). Every writer (add, status, journal, upgrade) runs on a backup of its file verified by cmp (rc 2 before any write if the copy is short), restored on failure or on INT/TERM/HUP; the caller's own traps are saved and put back. No EXIT trap: a sourced lib must not own the caller's EXIT. Residuals for the gate: (a) a holder alive but slower than 30 s loses the lock to a stealer and both write (its token no longer matches, so it never removes the new lock); (b) a stealer that dies holding memory.lock.steal makes the next waiter clear it once older than 30 s; two waiters doing that at the same moment can both enter the steal section. Both need a crash or a 30 s stall; a write lost that way shows as a check culprit (duplicate ID) or a missing entry, never silently in v2.
  2. journal takes no --date: MEMORY_DATE already pins the date for tests.
  3. upgrade body wins: an Index status reaches the body only when the body has none, or when the Index says superseded/deprecated and the body does not. Every other conflicting Index status is dropped and named on stderr (memory: BDR-012: kept body shipped, dropped Index accepted, the only one on this repo).
  4. Status word: a lib-written **Status (YYYY-MM-DD…)**: line reads its leading word (status requires the text to start with one: "open, reopened by abc"); other labelled lines rank words in _MEM_WORDS order, open last ("accepted. check OPEN" = accepted). A heading candidate is its [tag] only, never the title.
  5. One classifier on v2, the lexical reader kept on v1: on a v2 registry reconcile classifies by word (memory_closed: resolved | superseded | deprecated); accepted on a blocker stays open. On a v1 registry reconcile keeps today's lexical reader verbatim: the strict parser, measured on copies of all 13 other projects' blockers, changed the open set of 4 (config — RESOLVED title suffix, game date: … · status:, zenquality and angelscar356 **Statut** :); with the v1 branch the 13 sets are identical to today.
  6. Heading dialects: mem_key accepts ## ID followed by any non-alphanumeric char (—, -, |), so status and --supersedes work on v1 hyphen and pipe files. ID allocation reads every heading level, fenced or not (### BDR-001 in trucks_at_work, a stray fence elsewhere), and a v1 add whose ID already sits in any heading is refused. status on a ### registry stays rc 2 "no entry" (loud, not silent). A v1 add --status s writes - **Status**: s as the first body line instead of a heading tag: the v1 reconcile reader never reads the entry's own heading. The em-dash shape check is v2-only. upgrade migrates the measured dialects (Task 8): only headings that fail the v2 shape are rewritten (- and | date | separators, ###), a file without frontmatter gets the template's, every blocker verdict is proven against reconcile's v1 reader (a v1-closed entry the strict reader would open gets a Status (<date>, upgrade) line; the reverse, the BLK-032..034 false-open fix, is kept and named). It still refuses what the oracle cannot prove (duplicate IDs, ## ID ADDENDUM headings: game); the banner says memory.sh check, never promises an upgrade.
  7. Journal template carries no format: 2: journal.md is not a registry (check excludes it). Contract criterion 8 says "every templates/memory/*.md": the four registry templates.
  8. awk programs: an embedded awk program counts as one statement toward the 25-logic-line limit (_mem_upgrade_text, _mem_upgrade_oracle, _mem_index_rows hold 20-30 awk lines). Splitting them would scatter one parser across files.
  9. --staged removal rule: a removed line counts only from the first entry heading down (the spec said any - line). The Index sits above the first entry, so Task 7's upgrade commit goes through memory-commit like any memory commit; the diff runs with -c diff.interHunkContext=0 --no-color --no-ext-diff --no-textconv so user git config cannot fold or hide hunks. An open code fence always counts as a culprit, even when it predates the commit (it hides headings from allocation).

Review Focus

  1. Concurrent writers. The noclobber lock is proven by T6e/T6f (red with the mkdir lock on this host) and T14i (12 writers from a stale lock). Unlock by token (T14g), empty-lock steal (T14h). Every writer restores its verified backup on failure or signal and frees the lock. Residuals named in Deviation 1.
  2. Status words in prose and titles. "fail-open", "data: OPEN", a title saying "DNS resolved", "open again, not resolved by abc": T10b/c/h/i and run-reconcile T8a/b.
  3. Index-only facts at upgrade. 13 BDR statuses, BDR-038 + BLK-019/020 + 12 LRN supersessions, 129 dates; a stale Index (BDR-012) never overwrites the body and is named. BLK-019/020 must read closed after Task 7 (superseded).
  4. v1 projects keep working. 13 other repos run this lib through ~/.claude/lib: v1 writes are lenient, check never fails on v1, --staged ignores v1, reconcile on v1 is byte-for-byte today's reader (Deviation 5), status works on hyphen and pipe headings (T10m-o).
  5. The chokepoint never blocks a legitimate commit. Only NEW culprits count (a duplicate a merge left behind blocks neither add nor a staged append: T7i-k), except an open code fence, which always blocks until fixed (T14e/f); the upgrade commit passes (Index lines sit above the first entry); a refused commit leaves nothing staged.

Task 1: lib/memory.sh, its suite and the parser fixtures

Files:

  • Create: lib/memory.sh (copy of docs/superpowers/plans/memory-v2-write/memory.sh)
  • Create: lib/tests/memory.test.sh (copy of …/memory.test.sh)
  • Create: lib/tests/fixtures/blockers-v2-status.md (copy of …/blockers-v2-status.md)
  • Create: lib/tests/fixtures/blockers-v1-dialects.md (copy of …/blockers-v1-dialects.md; used by Task 2)

Interfaces (produced, used by Tasks 2-7): memory_entry_status <file> <ID> (winning candidate: [tag] or the labelled line; rc 1 if none), memory_status_word <line> (status word or first 40 chars), memory_closed <word> (rc 0 for resolved | superseded | deprecated), memory_is_v2 <file>, memory_check [--staged] [<dir>] (prints memory: v1: <file> per v1 registry on stderr, the banner's input), memory_add, memory_status, memory_journal, memory_index, memory_upgrade. CLI: bash lib/memory.sh [-C dir] add|status|journal|index|check|upgrade …. Env: MEMORY_DATE, MEM_GREP, MEM_LOCK_TRIES.

  • Step 1: Copy the four files
cp docs/superpowers/plans/memory-v2-write/memory.sh lib/memory.sh
cp docs/superpowers/plans/memory-v2-write/memory.test.sh lib/tests/memory.test.sh
cp docs/superpowers/plans/memory-v2-write/blockers-v2-status.md lib/tests/fixtures/blockers-v2-status.md
cp docs/superpowers/plans/memory-v2-write/blockers-v1-dialects.md lib/tests/fixtures/blockers-v1-dialects.md
chmod +x lib/memory.sh lib/tests/memory.test.sh
  • Step 2: Run the suite and the static checks

Run: make test suite=lib/tests/memory.test.sh three times → each ends PASS=112 FAIL=0 and all suites green (T6e and T14i races must be stable). Run: shellcheck lib/memory.sh lib/tests/memory.test.sh && awk 'length > 80' lib/memory.sh → no output after shellcheck. Run: make test suite=lib/tests/portability-census.test.sh → green.

  • Step 3: Commit
git add lib/memory.sh lib/tests/memory.test.sh lib/tests/fixtures/blockers-v2-status.md lib/tests/fixtures/blockers-v1-dialects.md
git commit -m "feat(memory): lib/memory.sh single registry writer — add/status/journal/index/check/upgrade, shared status parser, noclobber lock"

Task 2: reconcile reads v2 status through the shared parser and classifier

Files:

  • Modify: lib/reconcile.sh (source line after RECONCILE_GREP=; reconcile_blk_current_status and reconcile_blk_open with their comments)
  • Modify: lib/tests/run-reconcile.sh (T8 block before the final summary line)
  • Modify: skills/reconcile/SKILL.md:25 and :54

Interfaces: consumes memory_is_v2, memory_entry_status, memory_status_word, memory_closed. reconcile_blk_current_status and reconcile_blk_open keep their signatures.

  • Step 1: Write the failing test — insert before the echo; echo "================ $pass GREEN line of lib/tests/run-reconcile.sh:
echo; echo "=== T8 shared parser — header [tag] + labelled lines, prose never (BLK-032..034) ==="
v2="$FIX/blockers-v2-status.md"
open_v2=$(reconcile_blk_open "$v2" | cut -f1 | sort | tr '\n' ' ')
if [ "$open_v2" = "BLK-040 BLK-041 BLK-042 BLK-043 BLK-044 " ]; then ok "T8a open = {040..044}: 032..034 and 008 closed, accepted stays open"; else no "T8a open = [$open_v2], expected {040,041,042,043,044}"; fi
case "$(reconcile_blk_current_status "$v2" BLK-034)" in
  '[resolved]') ok "T8b BLK-034 status = its own header tag, title never read";;
  *) no "T8b BLK-034 read from prose (fail-open), not the header tag";;
esac
v1d="$FIX/blockers-v1-dialects.md"
open_v1=$(reconcile_blk_open "$v1d" | cut -f1 | tr '\n' ' ')
if [ "$open_v1" = "BLK-002 " ]; then ok "T8c v1 hyphen and pipe headings still parsed"; else no "T8c v1 dialects open = [$open_v1], expected {002}"; fi
v1w=$(mktemp -d)
mkdir "$v1w/.claude" "$v1w/.claude/memory"
printf '# Blockers\n' > "$v1w/.claude/memory/blockers.md"
printf -- '- **Cause**: `x`\n' > "$v1w/b.md"
bash "$REPO/memory.sh" -C "$v1w" add blocker --title fixed \
  --body-file "$v1w/b.md" --status resolved >/dev/null 2>&1
open_v1w=$(reconcile_blk_open "$v1w/.claude/memory/blockers.md" | cut -f1)
if [ -z "$open_v1w" ]; then ok "T8d lib-written v1 blocker --status resolved reads closed"; else no "T8d lib-written v1 blocker reads open [$open_v1w]"; fi
rm -f "$v1w/.claude/memory/blockers.md" "$v1w/b.md"
rmdir "$v1w/.claude/memory" "$v1w/.claude" "$v1w"
  • Step 2: Run, expect red — make test suite=lib/tests/run-reconcile.sh → T8a and T8b red (today: 032..034 open, BLK-034 read from prose).

  • Step 3: Implement — in lib/reconcile.sh, right after the RECONCILE_GREP=… line add:

# the status parser and classifier are shared with lib/memory.sh (BDR-125 4a)
# shellcheck source=/dev/null
. "$(dirname "${BASH_SOURCE[0]}")/memory.sh"

Replace everything from the comment # --- registry status: LAST status-bearing line wins … through the closing } of reconcile_blk_open by:

# --- registry status: LAST candidate wins (the BLK-008 trap A fell into) ---
# $1 blockers file, $2 id. A v2 registry (lib/memory.sh): the entry's own
# header `[tag]` or a labelled body line, never a status word in prose or in
# the title (the BLK-032..034 false-open). A v1 registry keeps the lexical
# reader below: its dialects (title suffix `— RESOLVED`, `date: … · status:`,
# `**Statut** :`) carry status where the strict parser cannot see it.
reconcile_blk_current_status() {
  if memory_is_v2 "$1"; then memory_entry_status "$1" "$2"; return; fi
  # v1: drop ALL `## BLK-` header lines first: the range is inclusive of the
  # NEXT entry's header, and a sibling header may carry a status word.
  sed -n "/^## ${2} /,/^## BLK-/p" "$1" \
    | "$RECONCILE_GREP" -v '^## BLK-' \
    | "$RECONCILE_GREP" -iE 'status|RESOLVED|REVERTED|upstream|resolved|[^a-z]open' \
    | tail -1
}
# blockers whose CURRENT status does not close them → "id<TAB>status".
# v2: memory_closed (resolved | superseded | deprecated); v1: the substring.
reconcile_blk_open() {
  local id st v2=""
  memory_is_v2 "$1" && v2=1
  for id in $(reconcile_enumerate_ids "$1" BLK); do
    st=$(reconcile_blk_current_status "$1" "$id")
    if [ -n "$v2" ]; then
      memory_closed "$(memory_status_word "$st")" && continue
    else
      case "$st" in *RESOLVED*|*resolved*) continue ;; esac
    fi
    printf '%s\t%s\n' "$id" "$st"
  done
}

Header comment: insert one line right after line 12 (# preaches — the recursive-coherence test (run-reconcile.sh T1) reds if this is broken.): # v2 registries carry no Index at all (lib/memory.sh); v1 ones still may.

  • Step 4: Run, expect green — make test suite=lib/tests/run-reconcile.sh → 29 GREEN / 0 RED (T1-T7 unchanged, T8a/b/c/d green; T8d is red against the r2 lib, which put the status in the heading tag the v1 reader drops). make test suite=lib/tests/run-review-guards.sh → green (G4: T8 reads fixtures only).

  • Step 5: Skill lines — skills/reconcile/SKILL.md:54: → 25/25, → → 29/29,. skills/reconcile/SKILL.md:25: replace (`reconcile_oracle_*`, `reconcile_blk_current_status` = last block wins) by (`reconcile_oracle_*`, `reconcile_blk_current_status` = last candidate wins: header `[tag]` or a labelled status line on a v2 registry via `lib/memory.sh`, today's lexical reader on v1).

  • Step 6: Commit

git add lib/reconcile.sh lib/tests/run-reconcile.sh skills/reconcile/SKILL.md
git commit -m "fix(reconcile): v2 blocker status through the shared memory.sh parser and classifier — BLK-032..034 no longer false-open; v1 reader unchanged"

Task 3: memory-commit.sh refuses a staged in-place edit or new culprit (rc 6)

Files:

  • Modify: lib/memory-commit.sh (usage comment, MC_MEMORY_SH, commit_memory right after git add)

  • Modify: lib/tests/run-deterministic.sh (block before the final echo + printf 'RESULT: …')

  • Modify: lib/capitalize-commit.md (rc table)

  • Step 1: Write the failing tests — insert right before the final echo / printf 'RESULT: %d passed, %d failed\n' "$PASS" "$FAIL" lines of lib/tests/run-deterministic.sh:

echo "== check --staged chokepoint (v2 registry, phase 4a)"
d="$(new_repo)"
printf -- '---\nformat: 2\ntype: decisions_registry\nentry_prefix: BDR\n---\n\n## BDR-001 — kept (2026-10-27)\n- **Status**: accepted\n' \
  > "$d/.claude/memory/decisions.md"
git -C "$d" add -A && git -C "$d" commit -qm v2
head_before=$(git -C "$d" rev-parse HEAD)
sed 's/kept/rewritten/' "$d/.claude/memory/decisions.md" > "$d/x.tmp" \
  && cat "$d/x.tmp" > "$d/.claude/memory/decisions.md"
out="$(cd "$d" && bash "$HELPER" commit "chore(memory): bad" 2>/dev/null)"; rc=$?
staged="$(git -C "$d" diff --cached --name-only)"
if [ "$rc" -eq 6 ] && [ -z "$out" ] && [ -z "$staged" ] && [ "$(git -C "$d" rev-parse HEAD)" = "$head_before" ]; then ok "in-place edit of a v2 entry → rc 6, nothing committed, nothing staged"; else ko "rc=$rc out=[$out] staged=[$staged] — in-place edit committed or left staged"; fi
git -C "$d" checkout -q HEAD -- .claude/memory/decisions.md
printf '\n## BDR-002 — added (2026-10-27)\nbody\n' >> "$d/.claude/memory/decisions.md"
out="$(cd "$d" && bash "$HELPER" commit "chore(memory): BDR-002" 2>/dev/null)"; rc=$?
if [ "$rc" -eq 0 ] && [ -n "$out" ]; then ok "append to a v2 registry → committed"; else ko "append refused rc=$rc"; fi

(Existing tests write baseline registries with no frontmatter: v1, skipped by the check, unchanged and green.)

  • Step 2: Run, expect red — make test suite=lib/tests/run-deterministic.sh → the rc 6 test fails (today rc 0, the edit is committed).

  • Step 3: Implement — in lib/memory-commit.sh:

    • after MC_PATHS=(".claude/memory" ".claude/tasks") add MC_MEMORY_SH="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)/memory.sh";
    • in commit_memory, right after git add -- "${changed[@]}", insert:
  # Chokepoint (BDR-125 phase 4a): a staged v2 registry may only grow and
  # never gains a new culprit (duplicate ID, bad heading, open fence). v1
  # registries are skipped. Unstage on refusal so no later plain commit
  # sweeps the refused change in.
  if [ -d .claude/memory ] \
    && ! bash "$MC_MEMORY_SH" check --staged .claude/memory; then
    git reset -q -- "${changed[@]}"
    echo "memory-commit: REFUSED — memory.sh check --staged failed (above);" \
      "NOTHING committed, nothing left staged." >&2
    return 6
  fi
  • usage comment line becomes two lines: # memory-commit.sh commit "<message>" # surgical commit; exit 0 ok/no-op, 3 unsafe / # # state, 5 commit rejected, 6 check refused.

  • Step 4: Run, expect green — make test suite=lib/tests/run-deterministic.sh → RESULT: 18 passed, 0 failed.

  • Step 5: Document rc 5 and rc 6 — lib/capitalize-commit.md step 3 "Report by (rc, mem_hash)", after the rc 3 bullet:

   - rc 5                     → `git commit` rejected (hook, protected branch,
                                signing); nothing committed, surface stderr.
   - rc 6                     → `memory.sh check --staged` refused, nothing
                                committed, nothing left staged. Two causes,
                                named on stderr: a line removed inside an
                                existing v2 entry (only appends pass), or a NEW
                                culprit (duplicate ID, heading shape); an open
                                code fence counts even when it predates the
                                commit. Fix the file, then commit the fix with
                                /commit-change; never bypass the helper.
  • Step 6: Commit
git add lib/memory-commit.sh lib/tests/run-deterministic.sh lib/capitalize-commit.md
git commit -m "feat(memory): memory-commit refuses a staged in-place edit or new culprit in a v2 registry (rc 6, unstaged); rc 5/6 documented"

Task 4: v2 templates and the registry v1 banner line

Files:

  • Modify: templates/memory/{decisions,learnings,blockers,evals}.md (journal.md unchanged, Deviation 7)

  • Modify: hooks/session-start.sh (before # Version check: compare local vs remote (non-blocking))

  • Modify: lib/tests/memory.test.sh (T13, before the final echo "PASS=…")

  • Modify: agents/onboarder.md:126

  • Step 1: Write the failing test — insert before echo "PASS=$pass FAIL=$fail" in lib/tests/memory.test.sh:

# T13 templates are born v2; the session banner names a v1 project only
for t in decisions learnings blockers evals; do
  check "T13-template-$t-v2" "$(sed -n 2p "$ROOT/templates/memory/$t.md")" 'format: 2'
  check "T13b-template-$t-no-index" "$(grep -c '^## Index$' "$ROOT/templates/memory/$t.md")" 0
done
banner() { (cd "$1" && SESSION_START_OFFLINE=1 bash "$ROOT/hooks/session-start.sh" \
  </dev/null 2>/dev/null) | grep -c "${2:-registry v1}"; }
check T13c-banner-v1-v2 "$(banner "$FIX/v1h" 'registry v1: 1 file(s) (memory.sh check)')/$(banner "$FIX")" 1/0
cp "$FIX/v1h/.claude/memory/blockers.md" v1h.bak
printf -- '---\nformat: 2\n---\n' > "$FIX/v1h/.claude/memory/blockers.md"
check T13d-banner-flips-off "$(banner "$FIX/v1h")" 0
cat v1h.bak > "$FIX/v1h/.claude/memory/blockers.md"

($FIX/v1h is the v1 pipe/hyphen project T10 built; $FIX/.claude/memory is v2. T13c reads both projects in one check (1/0), red until the banner exists; T13d turns the same v1 project v2 and expects the line gone. The hook resolves memory.sh next to itself, so the test exercises $ROOT/lib/memory.sh, never the installed copy.)

  • Step 2: Run, expect red — make test suite=lib/tests/memory.test.sh → 9 checks red (the eight template checks and T13c); T13d is green before and after, it guards the flip-off once T13c is green.

  • Step 3: Templates — in each of the four registry templates: insert format: 2 as line 2 (right after the opening ---); delete ## Index, the blank line after it, the two table lines and the blank line after them; replace the <!-- Append entries below. Template: … --> comment by (shown for blockers; the heading line is indented two spaces so no line starts with ## ):

<!-- Written only by `bash ~/.claude/lib/memory.sh add blocker --title "<friction>"
--body-file <file> [--status open]` (it allocates the ID). Entry shape:

  ## BLK-NNN — <friction> [open] (YYYY-MM-DD)
  - **Friction**: <what was blocked>
  - **Real cause**: <root cause>
  - **Solution**: <workaround or fix>

Later status: `bash ~/.claude/lib/memory.sh status BLK-NNN "resolved <hash>"`.
-->

decisions → decision, <title>, [accepted], labels Decision / Why / Rejected alternatives / Reference, later status superseded by BDR-NNN; learnings → learning, <abstract pattern>, no tag, labels Pattern / Context / Future application, no "Later status" line; evals → eval, <output>, [keep], labels Output / Method / Anomalies / Action.

  • Step 4: Banner — in hooks/session-start.sh, right before # Version check: compare local vs remote (non-blocking):
# Registry v1 (BDR-125 phase 4a): a project registry without `format: 2`.
# The lib names each v1 registry on stderr (`memory: v1: <file>`).
_mem_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/memory.sh"
if [ -f "$_mem_lib" ] && [ -d .claude/memory ]; then
  _v1=$(bash "$_mem_lib" check .claude/memory 2>&1 >/dev/null \
    | grep -c '^memory: v1:' || true)
  if [ "${_v1:-0}" -gt 0 ]; then
    printf "│  ⚠️  %-44s│\n" "registry v1: ${_v1} file(s) (memory.sh check)"
  fi
  unset _v1
fi
unset _mem_lib
  • Step 5: Onboarder line — agents/onboarder.md:126: (YAML schema + empty index + inline template comment) → (YAML schema with \format: 2` + inline template comment; no Index, entries go through `lib/memory.sh`)`.

  • Step 6: Run, expect green — make test suite=lib/tests/memory.test.sh → PASS=122 FAIL=0. make test suite=lib/tests/push-guard.test.sh → green: its banner checks grep specific strings. From this task until Task 7 this repo's own banner shows registry v1: 4 file(s) (memory.sh check) (its registries are still v1); that is expected.

  • Step 7: Commit

git add templates/memory hooks/session-start.sh lib/tests/memory.test.sh agents/onboarder.md
git commit -m "feat(memory): templates born v2 (format: 2, no Index); session banner names a v1 registry"

Task 5: flows write through the lib (one WRITE section, cited everywhere)

Files: lib/capitalize-commit.md (new WRITE section), skills/capitalize/SKILL.md (STEP 2 :143, STEP 4 items 1-4, STEP 5 bullets, STEP 5B rc list), skills/feat/SKILL.md:248, skills/bugfix/SKILL.md:275, skills/hotfix/SKILL.md:234, skills/ship-feature/SKILL.md:273-274, skills/init-project/SKILL.md:301-303, agents/commit-changer.md:220-223, skills/onboard/SKILL.md S7, lib/analyze-before-plan.md:42-43 and :100-102, agents/analyzer.md:98-99, CLAUDE.global.md.

  • Step 1: The one WRITE section — in lib/capitalize-commit.md, first the intro: Inline snippet. Include at the END of any dev flow's CAPITALIZE step, AFTER the / approved registry / journal / TODO entries are written. It commits ONLY the → Inline snippet for any dev flow's CAPITALIZE step: § WRITE says how the approved / registry and journal entries are written, then the rest commits ONLY the (the two lines after it unchanged), and decide WHAT to write are unchanged and run before this snippet. Only the COMMIT / of the already-approved entries is automated here. → decide WHAT to write are unchanged and run before this snippet; § WRITE then / writes them through lib/memory.sh and the COMMIT is automated here.. Then insert before ## DO:
## WRITE (before the commit)

Registry entries and journal lines are written only by `lib/memory.sh`,
never by Edit or append; there is no `## Index` to update.

- Entry: caveman body to a scratch file, then
  `bash "$HOME/.claude/lib/memory.sh" [-C <project root>] add
  <decision|learning|blocker|eval> --title "<title>" --body-file <file>
  [--status <status>] [--supersedes <ID>]`. One call per entry; it
  allocates the ID under a lock and prints it. A blocker body quotes ≥1
  error in backticks. `-C` when the cwd is not the project root.
- Status change on an existing entry:
  `bash "$HOME/.claude/lib/memory.sh" status <ID> "<word> …"`, the text
  starting with a status word (`resolved abc1234`, `open, reopened by …`,
  `superseded by BDR-NNN`).
- Journal: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`.
- rc 2 names its reason (title chars, empty body, a status not starting
  with a status word, an open code fence in the body or the registry,
  unknown ID, lock busy): fix the input and re-run.
  • Step 2: capitalize

    • :143 (Index + bodies) → (headings + bodies).
    • STEP 4 items 1-4 (from 1. Read the target registry file. through match that file's header row).) → one item: 1. Write each approved entry per \lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; a resolved blocker: `memory.sh status "resolved "`).` Old item 5 (caveman) stays, renumbered 2.
    • STEP 5: the two bullets - Heading exists → append a bullet. / - Missing → create … → - \bash "$HOME/.claude/lib/memory.sh" journal ""` per bullet (it creates today's heading when missing).`
    • STEP 5B step 3: after the **rc 3** bullet add - **rc 5 / rc 6** → nothing committed; surface the helper's stderr; meaning and recovery in \lib/capitalize-commit.md` (rc 6: fix the registry, then /commit-change). STEP 6 says NOT committed.`
  • Step 3: flow citations (each a one-line replacement; the Language rule lines untouched):

    • feat :248 (Always append a 1-line entry to today's heading in \.claude/memory/journal.md`.) → Approved entries and the always-written 1-line journal entry: per `lib/capitalize-commit.md` § WRITE (`memory.sh add` / `memory.sh journal`).`
    • bugfix :275 → 4. Write approved entries per \lib/capitalize-commit.md` § WRITE: a new blocker `add blocker … --status resolved`, an existing one now fixed `status "resolved "`, an LRN `add learning …` (no status); the journal line `memory.sh journal`.`
    • hotfix :234 → Always append a 1-line journal entry (even trivial hotfix — journal is timeline, not signal) and any approved BLK/LRN per \lib/capitalize-commit.md` § WRITE.`
    • ship-feature :273-274 → 4. Write approved entries per \lib/capitalize-commit.md` § WRITE (`memory.sh add`, one call each; no Index to update)./5. Journal line: `memory.sh journal` (same section).`
    • init-project :301-303 → 3. Write approved entries to the registries bootstrapped at STEP 5 (in the root commit), and the journal line, per \lib/capitalize-commit.md` § WRITE.`
    • commit-changer :220-223 (Phase 4 item 2) → 2. Write each resolved entry and one journal line for the batch per \$HOME/.claude/lib/capitalize-commit.md` § WRITE (`memory.sh -C add …`, `memory.sh -C journal …`; no Index to update).`
    • onboard S7: the source text spans a line break, append to that (end of the line starting S7 — AFTER.) + newline + project's \.claude/memory/journal.md` under today's date:. Replace the tail append to that/project's `.claude/memory/journal.md` under today's date:byappend to that/project's journal (`bash "$HOME/.claude/lib/memory.sh" -C journal`):` — same two-line wrap, the quoted line text after it unchanged.
  • Step 4: analyze-before-plan + analyzer

    • lib/analyze-before-plan.md:42-43: Do NOT read the \## Index` table: it drifts (entries land in the body, the manual Index update lapses — measured 32-40% missing on a mature repo); headings cannot.→Do NOT read a `## Index` table (v1 registries may still carry one; it drifted 32-40% on a mature repo; v2 has none); headings cannot drift.`
    • :100-102: No write, no Index update, no memory mutation. → No write, no memory mutation.; Index backfill, if ever wanted, is \/prune-memory` passe D — never this snippet.→Registry writes go through `lib/memory.sh`, never this snippet.`
    • agents/analyzer.md:98-99: Index backfill or new entries are never your job → new entries or status lines are never your job (writes go through lib/memory.sh).
  • Step 5: CLAUDE.global.md (line-neutral):

    • Append-only: never rewrite past entries; curation (merge, supersede, / compress) only via \/prune-memory`.→Append-only, written only through `bash ~/.claude/lib/memory.sh` (add,/status, journal), never by Edit; curation only via `/prune-memory`.`
    • exact. Pattern \[thing] [action] [reason]. [next step].` Registries load/every session; caveman cuts ~40% of the tokens with no substance lost.→exact. Pattern `[thing] [action] [reason]. [next step].` Planning flows/read the registries; caveman cuts ~40% of every read, no substance lost.`
  • Step 6: Verify — grep -rn 'Index' skills/capitalize/SKILL.md skills/feat/SKILL.md skills/bugfix/SKILL.md skills/hotfix/SKILL.md skills/ship-feature/SKILL.md skills/init-project/SKILL.md agents/commit-changer.md → no line telling a writer to update an Index. wc -l < CLAUDE.global.md → ≤ 333. make test suite=lib/tests/doctrine-citers.test.sh and make test suite=lib/tests/effort-routing.test.sh → green.

  • Step 7: Commit

git add lib/capitalize-commit.md skills/capitalize/SKILL.md skills/feat/SKILL.md skills/bugfix/SKILL.md skills/hotfix/SKILL.md skills/ship-feature/SKILL.md skills/init-project/SKILL.md agents/commit-changer.md skills/onboard/SKILL.md lib/analyze-before-plan.md agents/analyzer.md CLAUDE.global.md
git commit -m "docs(memory): one WRITE section in capitalize-commit.md, every flow cites it; Index steps removed; doctrine names the single writer"

Task 6: /prune-memory on v2 (no § D, status through the lib, check as verify)

Files: skills/prune-memory/SKILL.md (§ A :83-85, § D :111-115, STEP 2 example, STEP 3 list, :177, STEP 4 block, report sample, failure row, :322-323), skills/prune-memory/tests/run-deterministic.sh (RED-6), new skills/prune-memory/tests/fixtures/red6-check/.claude/memory/decisions.md, git rm of skills/prune-memory/tests/fixtures/red6-orphan/.claude/memory/decisions.md, skills/prune-memory/test-prompts.json (id 1).

  • Step 1: Write the failing test — replace the whole RED-6 block (from # ---- RED-6: through its closing fi) by:
# ---- RED-6: STEP 4 verify runs memory.sh check (duplicate ID caught) --------
# v2 registries carry no Index; the structural verify is `memory.sh check`
# (heading shape, unique IDs). HOME is pinned to a sandbox whose .claude/lib
# is this repo's lib, so the run never depends on the machine's ~/.claude.
S6="$SANDBOX/red6"; mkdir -p "$S6/.claude/memory" "$S6/home/.claude"
ln -s "$HERE/../../../lib" "$S6/home/.claude/lib"
cp "$HERE/fixtures/red6-check/.claude/memory/decisions.md" \
   "$S6/.claude/memory/decisions.md"
extract_block "STEP 4" > "$S6/step4.sh"
out="$( cd "$S6" && HOME="$S6/home" bash step4.sh 2>&1 )"
if printf '%s\n' "$out" | grep -qE 'duplicate BDR-009'; then
  green 6 "verify runs memory.sh check and names the duplicate BDR-009"
else
  red 6 "verify misses the duplicate BDR-009 (no memory.sh check in STEP 4)"
fi

Fixture skills/prune-memory/tests/fixtures/red6-check/.claude/memory/decisions.md:

---
format: 2
type: decisions_registry
entry_prefix: BDR
---

# Decisions registry (BDR)

## BDR-009 — first (2026-06-01)
- **Status**: accepted

## BDR-009 — duplicate, the trap (2026-06-02)
- **Status**: accepted

git rm -q skills/prune-memory/tests/fixtures/red6-orphan/.claude/memory/decisions.md.

  • Step 2: Run, expect red — make test suite=skills/prune-memory/tests/run-deterministic.sh → RED-6: RED.

  • Step 3: SKILL.md edits

    • § A :83-85 → Decisions whose body names a successor ("superseded by <ID>", "Supersedes [[<ID>]]" on the newer one) but whose current status (\bash "$HOME/.claude/lib/memory.sh" index decision`) still reads `accepted` → propose `memory.sh status "superseded by "`.`
    • Delete § D (### D. Index drift and its two bullets).
    • STEP 2 example: → fix Index: status = "superseded by BDR-903" → → memory.sh status BDR-902 "superseded by BDR-903"; delete [D. Index drift] + (none); (all / a / b / c / d / edit <ID> / skip) → (all / a / b / c / edit <ID> / skip).
    • STEP 3 list (replacing items 1-3; old item 4 becomes 3, unchanged):
1. **Status flag updates** — `bash "$HOME/.claude/lib/memory.sh" status <ID>
   "<word> …"` appends a dated status line (text starts with a status word:
   `deprecated, no follow-up after 90 days`); the body above stays verbatim.
2. **Merges** — write the merged body to a scratch file, then
   `bash "$HOME/.claude/lib/memory.sh" add <kind> --title "<title>"
   --body-file <file> --supersedes <first source>` (next-free ID, forward
   link, the first source marked superseded); each other source:
   `memory.sh status <ID> "superseded by <new-ID>"`. Source bodies stay
   verbatim for history. Merged body:
followed by the existing merged-body sub-bullets. Delete `After each write, regenerate Index from body when rows changed.`
  • STEP 4 block: delete the PREFIX_MAP declaration, its comment and the # All body entries have Index rows; no orphans loop through its done; in their place:
# Structure: heading shape + unique IDs + no open fence (v2 registries; a
# v1 one is named and skipped). Same verify the writer runs after every add.
bash "$HOME/.claude/lib/memory.sh" check .claude/memory \
  || echo "CHECK FAILED: fix the lines above before certifying"
  • Report sample INDEX SANITY: OK → CHECK: OK; NEXT: review \git diff .claude/memory/`, then `/commit-change`` unchanged (curation edits are removals: they never go through memory-commit's chokepoint).

  • Failure row | Index sanity FAILED at STEP 4 | … → | \memory.sh check` FAILED at STEP 4 | Print its culprit lines. Do NOT auto-fix — user re-runs or hand-edits. |`.

  • :322-323 fixtures list red6-orphan → red6-check.

  • Step 4: test-prompts.json id 1 expected → "Skill runs PRECHECK (refuses if working tree dirty on .claude/memory/), audits all 5 registries for A) obsolete/superseded entries B) similar merge candidates C) bloated prose, presents the per-registry PRUNE PLAN with category-level approval gate, applies only approved changes (status lines and merges through lib/memory.sh, never hard-delete), then runs memory.sh check and the fidelity census at STEP 4."

  • Step 5: Run, expect green — make test suite=skills/prune-memory/tests/run-deterministic.sh → RED-1..7 GREEN (RED-5's journal-only sandbox has no registry, check prints nothing). grep -n 'Index' skills/prune-memory/SKILL.md → no writer step mentions an Index.

  • Step 6: Commit

git add skills/prune-memory
git commit -m "feat(prune-memory): v2 registries — § D dropped, status and merges through memory.sh, STEP 4 verify = memory.sh check"

Task 7: upgrade this repo's registries (the one curation)

Files: .claude/memory/{decisions,learnings,blockers,evals}.md (by the lib only). upgrade already transforms on a temp copy and runs its oracle before replacing any file; the registries are tracked, so no dry run.

  • Step 0: Clean memory precondition — git diff --quiet HEAD -- .claude/memory .claude/tasks || { echo "STOP: uncommitted memory or tasks; commit them first"; exit 1; }. The rollback below and the memory-commit sweep both rely on it.

  • Step 1: Upgrade in place and commit through the chokepoint

bash lib/memory.sh upgrade
bash lib/memory.sh check && echo CHECK-OK
bash "$HOME/.claude/lib/memory-commit.sh" commit "chore(memory): registries v2 — Index removed, Index-only dates and statuses materialized (memory.sh upgrade)"

Expected: four memory: upgraded … lines and one stderr line memory: BDR-012: kept body shipped, dropped Index accepted; CHECK-OK; memory-commit prints a hash (Index lines sit above the first entry, every other change is an insertion). If upgrade returns rc 2: each file is already restored from its verified backup; git checkout -- .claude/memory (safe only after Step 0) puts any upgraded sibling back, report the stderr, stop.

  • Step 2: Verify the live facts Run: bash -c '. lib/reconcile.sh; reconcile_blk_open .claude/memory/blockers.md | cut -f1 | tr "\n" " "' → exactly BLK-001 BLK-003 BLK-017 BLK-018 BLK-021 BLK-022 BLK-029 (measured on an upgraded copy 2026-10-28: 032..034 resolved, 019/020 superseded = closed). Run: bash lib/memory.sh index blocker | grep -E 'BLK-0(19|20|32|33|34)' → dates 2026-09-01 2026-09-02 2026-10-19 2026-10-21 2026-10-22, statuses superseded, superseded, resolved ×3. Run: grep -c '^## Index' .claude/memory/*.md → 0 everywhere; make test suite=lib/tests/memory.test.sh → T12 green; the session banner no longer shows registry v1.

Final verification (main loop, after Task 7)

make test all suites green; shellcheck lib/memory.sh lib/reconcile.sh lib/memory-commit.sh hooks/session-start.sh; bash lib/memory.sh check; git status --short clean except the user-owned settings.json. No other project changed: git -C <dir> status --short .claude/memory empty, and bash -c '. lib/reconcile.sh; reconcile_blk_open <dir>/.claude/memory/blockers.md' equal to the pre-branch reader, for each of:

/home/bchanot/Documents/config
/home/bchanot/Documents/faunosteo
/home/bchanot/Documents/game
/home/bchanot/Documents/game-deploy
/home/bchanot/Documents/integration_alphalink
/home/bchanot/Documents/robin_petier
/home/bchanot/Documents/zenquality
/home/bchanot/repos/bchanot/angelscar356
/home/bchanot/repos/bchanot/bchanot-cv
/home/bchanot/repos/bchanot/for_you
/home/bchanot/repos/bchanot/game-deploy
/home/bchanot/repos/bchanot/gitea-deploy
/home/bchanot/repos/bchanot/nuit-folle
/home/bchanot/repos/bchanot/trucks_at_work

(pre-branch reader: git show develop:lib/reconcile.sh > <tmp> then source <tmp>; measured 2026-10-28 on copies: 13 of 13 distinct files identical.)


Task 8: upgrade migrates every v1 dialect (user ask at the gate, 2026-10-28)

User at STEP 3: "Il faudrait un système de migration pour que les fichiers v1 deviennent des fichiers v2 pour tout harmoniser". Same files, same .claude/memory/ place, versioned and pushed with the code; v2 = format: 2 + no Index.

Files: lib/memory.sh (upgrade path only), lib/tests/memory.test.sh (new T15 block), lib/tests/fixtures/blockers-v1-dialects.md (extend if needed).

Behaviour (replaces the dialect refusal of Deviation 6 for upgrade only):

  1. No frontmatter → prepend the matching templates/memory/<name>.md frontmatter (with format: 2) and keep the file's own body verbatim below it.
  2. Heading normalization, entry headings only (^#+ *PREFIX-[0-9]+): ## ID - t, ## ID | date | t, ### ID — t, ## ID — t — date → ## ID — t (date); the date comes from the heading, else the Index row, else the first Date/date: body line, else none. The title text is kept verbatim (only separators change). IDs never change.
  3. Status preservation: before rewriting, compute every entry's open/closed verdict with the v1 lexical reader (reconcile's legacy path, blockers) and the status word (all registries); after rewriting, if the strict v2 parser would read a different verdict or no status where the legacy reader had one, append - **Status (<today>, upgrade)**: <word> to that entry.
  4. Oracle (file untouched on any failure, rc 2, culprit named): same ID set and order; every entry's verdict before == after (blockers via the legacy reader vs memory_closed, others by status word when one existed); check green; idempotent second run.
  5. upgrade no longer refuses any of the measured dialects; it refuses only what the oracle cannot prove.

Tests (T15): one fixture per dialect (hyphen, pipe, ###, title-suffix — RESOLVED, date: … · status:, **Statut** :, no frontmatter) → upgraded, check green, verdicts preserved, idempotent; a tampered case where the oracle refuses and the file stays byte-identical. Proof on copies (read-only on the real repos): upgrade on a copy of each of the 13 other projects' registries is oracle-green; report the per-repo line counts.

Out of this branch: applying it to the 13 other repos happens after the merge, one chore/memory-v2 branch per repo, user approval per repo (phase 0b pattern), committed through /commit-change (a heading rename is an in-place edit, memory-commit refuses it by design).