From 90d5f96c955295969670962f77a510c8a0a7e5b2 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 28 Oct 2026 10:36:29 +0100 Subject: [PATCH] =?UTF-8?q?docs(plan):=20memory=20v2=20write=20side=20?= =?UTF-8?q?=E2=80=94=207=20tasks=20+=20proven=20reference=20lib,=20suite,?= =?UTF-8?q?=20fixture?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plans/2026-10-27-memory-v2-write.md | 525 ++++++++++++++++++ .../memory-v2-write/blockers-v2-status.md | 49 ++ .../plans/memory-v2-write/memory.sh | 478 ++++++++++++++++ .../plans/memory-v2-write/memory.test.sh | 273 +++++++++ 4 files changed, 1325 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-27-memory-v2-write.md create mode 100644 docs/superpowers/plans/memory-v2-write/blockers-v2-status.md create mode 100644 docs/superpowers/plans/memory-v2-write/memory.sh create mode 100644 docs/superpowers/plans/memory-v2-write/memory.test.sh diff --git a/docs/superpowers/plans/2026-10-27-memory-v2-write.md b/docs/superpowers/plans/2026-10-27-memory-v2-write.md new file mode 100644 index 0000000..f781f24 --- /dev/null +++ b/docs/superpowers/plans/2026-10-27-memory-v2-write.md @@ -0,0 +1,525 @@ +# 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 serves memory.sh and reconcile, 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 `, verbs, rc 2 + named reason). The awk status parser lives once in `_MEM_AWK` and is shared by `index`, `upgrade` and `lib/reconcile.sh`. Writers serialize through a noclobber lock file in the git common dir. `memory-commit.sh` runs `check --staged` as the chokepoint. + +**Tech Stack:** bash 5, POSIX awk (no gawk-only features, no `{n}` intervals), 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 before this plan was written):** `docs/superpowers/plans/memory-v2-write/` holds `memory.sh`, `memory.test.sh` and `blockers-v2-status.md`. They were run in a mock repo: suite `PASS=72 FAIL=0` five runs in a row, shellcheck clean, no line over 80 chars; `upgrade` on a copy of this repo's live registries is oracle-green, `check`-green, idempotent, and its diff passes `check --staged`. Task 1 copies them; 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 (an embedded awk program counts as one statement), ≤ 5 locals, ≤ 5 params, lines ≤ 80 chars in `lib/*.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 label `**Always English, always caveman**` (doctrine-citers, LRN-166). Single-line fixed strings: 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 (found while proving the reference) + +- Lock = a file created under bash noclobber, not a `mkdir` dir: uutils `mkdir` 0.10 on this host is not atomic (5 concurrent adds lost 2-4 entries). Same path (`/memory.lock`), same 30 s steal. +- `journal` takes no `--date` flag: `MEMORY_DATE` already pins the date for tests; YAGNI. +- `upgrade` writes an Index status into the body only when the body has none, or when the Index says superseded/deprecated and the body does not. Otherwise the body wins: the Index is the stale copy (BDR-012: Index accepted, body shipped). Status words rank in `_MEM_WORDS` order with `open` last, measured on the live registries: identical verdicts to today's reconcile on every blocker except BLK-032..034. + +## Review Focus + +1. **Concurrent writers.** Two sessions capitalizing at once must get two IDs; a lock that is not atomic loses entries silently. Found while proving the reference: `mkdir` from uutils coreutils 0.10 (this host) is NOT atomic, two concurrent `mkdir` both succeed; the lock uses bash noclobber (`open(O_EXCL)`). T6e/T6f are the flip test (they were red with the mkdir lock). +2. **Status words in prose.** A Solution line saying "fail-open" or "`data:` OPEN" must never reopen a resolved blocker; "accepted. Behavioral check OPEN" must read accepted. Covered by T10b/c/e and run-reconcile T8. +3. **Index-only facts lost at upgrade.** 13 BDR statuses, 2 BDR + 2 BLK + 12 LRN supersessions and ~130 dates live only in Index rows today; a stale Index status (BDR-012 says accepted, body says shipped) must NOT overwrite the body. The upgrade oracle refuses on any loss; T9e pins the stale case. +4. **v1 projects keep working.** 13 other repos on this machine run this lib through `~/.claude/lib`; a v1 registry is written leniently, `check` never fails on it, `--staged` ignores it, memory-commit keeps committing it. T7e/f and the memory-commit v1 test pin this. +5. **The chokepoint must not block the upgrade commit itself.** Removing the Index (lines before the first entry) and inserting Date/Status lines are not "removed lines inside an entry". Proven on the live copy; Task 7 commits it through memory-commit.sh. + +--- + +### Task 1: lib/memory.sh, its suite and the parser fixture + +**Files:** +- Create: `lib/memory.sh` (copy of `docs/superpowers/plans/memory-v2-write/memory.sh`) +- Create: `lib/tests/memory.test.sh` (copy of `docs/superpowers/plans/memory-v2-write/memory.test.sh`) +- Create: `lib/tests/fixtures/blockers-v2-status.md` (copy of `docs/superpowers/plans/memory-v2-write/blockers-v2-status.md`) + +**Interfaces:** +- Produces (sourceable, used by Tasks 2-7): `memory_entry_status ` (winning candidate line, rc 1 if none), `memory_status_word ` (status word or first 40 chars), `memory_check [--staged] []` (rc 2 on a culprit), `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 three files** + +```bash +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 +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` → expected last lines `PASS=72 FAIL=0` and `all suites green`. Run it three times (the race test T6e 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** + +```bash +git add lib/memory.sh lib/tests/memory.test.sh lib/tests/fixtures/blockers-v2-status.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 status through the shared parser + +**Files:** +- Modify: `lib/reconcile.sh:57-67` (`reconcile_blk_current_status`) and its header comment `:8-12` +- Modify: `lib/tests/run-reconcile.sh` (new T8 block before the final summary line) +- Modify: `skills/reconcile/SKILL.md:25` + +**Interfaces:** +- Consumes: `memory_entry_status` from Task 1. +- Produces: `reconcile_blk_current_status ` unchanged signature, now prints the winning candidate line (empty when none). + +- [ ] **Step 1: Write the failing test** — insert before the `echo; echo "================ $pass GREEN` line of `lib/tests/run-reconcile.sh`: + +```bash +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-041 BLK-042 " ]; then ok "T8a open = {041,042}: 032..034, 008, 040 read resolved/accepted"; else no "T8a open = [$open_v2], expected {041,042}"; fi +case "$(reconcile_blk_current_status "$v2" BLK-034)" in + *'[resolved]'*) ok "T8b BLK-034 status = its own header tag";; + *) no "T8b BLK-034 read from prose (fail-open), not the header tag";; +esac +``` + +- [ ] **Step 2: Run it, expect red** + +Run: `make test suite=lib/tests/run-reconcile.sh` → `RED ✗ T8a open = [BLK-032 BLK-033 BLK-034 BLK-040 BLK-041 BLK-042 ]…` (exact list may differ; it must be red). + +- [ ] **Step 3: Delegate the parser** — in `lib/reconcile.sh`, after the `RECONCILE_GREP=` line add: + +```bash +# the status parser is shared with lib/memory.sh (BDR-125 phase 4a) +# shellcheck source=/dev/null +. "$(dirname "${BASH_SOURCE[0]}")/memory.sh" +``` + +and replace the whole `reconcile_blk_current_status` function and the two comment lines above it with: + +```bash +# --- registry status: LAST candidate wins (the BLK-008 trap A fell into) --- +# $1 blockers file, $2 id. Echoes the winning status line: the entry's own +# header `[tag]` or a labelled body line (lib/memory.sh); a status word in +# prose is never read (the BLK-032..034 false-open). Empty when none. +reconcile_blk_current_status() { + memory_entry_status "$1" "$2" +} +``` + +In the 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** + +Run: `make test suite=lib/tests/run-reconcile.sh` → `T8a`, `T8b` green, T1-T7 still green, `0 RED`. +Run: `make test suite=lib/tests/run-review-guards.sh` → green (G4: run-reconcile must not read `.claude/memory`; T8 reads the fixture). + +- [ ] **Step 5: Skill line** — `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, via `lib/memory.sh`) `` + +- [ ] **Step 6: Commit** + +```bash +git add lib/reconcile.sh lib/tests/run-reconcile.sh skills/reconcile/SKILL.md +git commit -m "fix(reconcile): blocker status through the shared memory.sh parser — BLK-032..034 no longer false-open" +``` + +--- + +### Task 3: memory-commit.sh refuses a staged in-place edit (rc 6) + +**Files:** +- Modify: `lib/memory-commit.sh` (header usage comment, `commit_memory` between `git add` and `git diff --cached --quiet`) +- Modify: `lib/tests/run-deterministic.sh` (two new tests before the summary) +- Modify: `lib/capitalize-commit.md` (rc table) + +**Interfaces:** +- Consumes: `bash lib/memory.sh check --staged .claude/memory`. +- Produces: `memory-commit.sh commit` rc 6 = check refused, nothing committed. + +- [ ] **Step 1: Write the failing tests** — read `lib/tests/run-deterministic.sh` first (helpers `new_repo`, `ok`, `ko`, `HELPER`); append before its final summary block: + +```bash +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) +printf -- '---\nformat: 2\ntype: decisions_registry\nentry_prefix: BDR\n---\n\n## BDR-001 — rewritten (2026-10-27)\n- **Status**: accepted\n' \ + > "$d/.claude/memory/decisions.md" +out="$(cd "$d" && bash "$HELPER" commit "chore(memory): bad" 2>/dev/null)"; rc=$? +if [ "$rc" -eq 6 ] && [ -z "$out" ] && [ "$(git -C "$d" rev-parse HEAD)" = "$head_before" ]; then ok "in-place edit of a v2 entry → rc 6, nothing committed"; else ko "rc=$rc out=[$out] — in-place edit was committed or wrong rc"; 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 +``` + +(The existing tests write `baseline` registries with no frontmatter: v1, `check` skips them, they must stay green unchanged.) + +- [ ] **Step 2: Run, expect red** + +Run: `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`: + - under `MC_PATHS=(...)` add: + +```bash +MC_MEMORY_SH="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)/memory.sh" +``` + + - in `commit_memory`, right after `git add -- "${changed[@]}"`, insert: + +```bash + # Chokepoint (BDR-125 phase 4a): a staged v2 registry may only grow. An + # in-place rewrite of an existing entry is curation: /prune-memory, then + # /commit-change. v1 registries are skipped by the check. + if [ -d .claude/memory ] \ + && ! bash "$MC_MEMORY_SH" check --staged .claude/memory; then + echo "memory-commit: REFUSED — memory.sh check --staged failed (above);" \ + "NOTHING committed, the scoped paths stay staged." >&2 + return 6 + fi +``` + + - header usage line becomes `# memory-commit.sh commit "" # surgical commit; exit 0 ok/no-op, 3 unsafe state, 5 commit rejected, 6 check --staged refused` + +- [ ] **Step 4: Run, expect green** + +Run: `make test suite=lib/tests/run-deterministic.sh` → all green including the two new ones. + +- [ ] **Step 5: Document rc 5 and rc 6** — in `lib/capitalize-commit.md` step 3 "Report by (rc, mem_hash)", after the `rc 3` bullet add: + +``` + - rc 5 → `git commit` rejected (hook, protected branch, + signing); nothing committed, surface stderr. + - rc 6 → `memory.sh check --staged` refused: a staged + v2 registry rewrites an existing entry line + (only appends pass). Curation goes through + /prune-memory then /commit-change; surface + the culprit lines, never bypass the helper. +``` + +- [ ] **Step 6: Commit** + +```bash +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 of a v2 registry (rc 6); rc 5/6 documented" +``` + +--- + +### Task 4: v2 templates and the registry v1 banner line + +**Files:** +- Modify: `templates/memory/{decisions,learnings,blockers,evals}.md` +- Modify: `hooks/session-start.sh` (after the CLAUDE.global.md line-count guard, before `# Version check`) +- Modify: `lib/tests/memory.test.sh` (T13, before the final `echo "PASS=…"`) +- Modify: `agents/onboarder.md:126` (template description) + +- [ ] **Step 1: Write the failing test** — insert before `echo "PASS=$pass FAIL=$fail"` in `lib/tests/memory.test.sh`: + +```bash +# 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); } +check T13c-banner-v1 "$(banner "$FIX/v1-proj" | grep -c 'registry v1: 1 file')" 1 +check T13d-banner-v2 "$(banner "$FIX" | grep -c 'registry v1')" 0 +``` + +and, just above it, the v1 fixture project: + +```bash +mkdir -p "$FIX/v1-proj/.claude/memory" +printf '# Decisions\n\n## BDR-001 - legacy\n' > "$FIX/v1-proj/.claude/memory/decisions.md" +``` + +- [ ] **Step 2: Run, expect red** — `make test suite=lib/tests/memory.test.sh` → T13 checks fail. + +- [ ] **Step 3: Templates** — in each of the four templates: insert `format: 2` as line 2 (right after the opening `---`); delete the `## Index` heading, the blank line after it, the two table lines and the blank line after them; replace the `` comment by this shape (per file, adapt the kind, title word and body labels already in that template; the heading line is indented two spaces so no line starts with `## `): + +``` + +``` + +Kinds and labels: decisions → `decision`, ``, `[accepted]`, labels Decision / Why / Rejected alternatives / Reference; learnings → `learning`, `<abstract pattern>`, no status, labels Pattern / Context / Future application; evals → `eval`, `<output>`, `[keep]`, labels Output / Method / Anomalies / Action. `journal.md` template unchanged. + +- [ ] **Step 4: Banner** — in `hooks/session-start.sh`, after the `fi` that closes the CLAUDE.global.md line-count guard, insert: + +```bash +# Registry v1 (BDR-125 phase 4a): a project registry without `format: 2`. +if [ -n "$REPO_DIR" ] && [ -d .claude/memory ]; then + _v1=$(bash "$REPO_DIR/lib/memory.sh" check .claude/memory 2>&1 >/dev/null \ + | grep -c '^memory: v1: ' || true) + if [ "${_v1:-0}" -gt 0 ]; then + _v1_line="registry v1: ${_v1} file(s), see memory.sh upgrade" + printf "│ ⚠️ %-44s│\n" "${_v1_line:0:44}" + fi + unset _v1 _v1_line +fi +``` + +- [ ] **Step 5: Onboarder line** — `agents/onboarder.md:126`, replace `(YAML schema + empty index + inline template comment)` by `(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` → `FAIL=0`; `make test suite=lib/tests/push-guard.test.sh` → green (banner unchanged for this repo, which is v1 until Task 7: if push-guard counts banner lines exactly, read its T44-T46 and confirm none breaks; the new line appears only in a project with a v1 registry). + +- [ ] **Step 7: Commit** + +```bash +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 (capitalize, CAPITALIZE steps, analyzer, doctrine) + +**Files (one edit each, exact text below):** +- `skills/capitalize/SKILL.md` STEP 2 (`:143`), STEP 4 items 1-4 (`:247-255`), STEP 5 (`:267-273`) +- `skills/feat/SKILL.md:248` +- `skills/bugfix/SKILL.md:275` +- `skills/hotfix/SKILL.md:234` (+ the two proposal bullets `:228-229` unchanged) +- `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 (`:1181-1183`) +- `lib/analyze-before-plan.md:42-43` and `:100-102` +- `agents/analyzer.md:98-99` +- `CLAUDE.global.md` § Memory registries (two sentences) + +The one canonical write instruction (W) used below: + +> W = Write each approved entry's caveman body to a scratch file, then `bash "$HOME/.claude/lib/memory.sh" add <decision|learning|blocker|eval> --title "<title>" --body-file <file> [--status <status>]` (one call per entry; it allocates the ID and prints it; never Edit or append to a registry, there is no Index to update). A status change on an existing entry: `bash "$HOME/.claude/lib/memory.sh" status <ID> "<text>"`. The journal line: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`. + +- [ ] **Step 1: capitalize** + - `:143` `(Index + bodies)` → `(headings + bodies)`. + - STEP 4 items 1-4 (from `1. Read the target registry file.` through the Index-row item ending `match that file's header row).`) become: + +``` +1. Body to a scratch file, then `bash "$HOME/.claude/lib/memory.sh" add + <decision|learning|blocker|eval> --title "<title>" --body-file <file> + [--status <status>] [--supersedes <ID>]`: it allocates the next ID from + the headings under a lock, appends at the end, prints the ID. Never Edit + or append to a registry by hand; there is no Index to update. +2. A status change on an existing entry (a blocker now resolved): + `bash "$HOME/.claude/lib/memory.sh" status <ID> "<text>"`. +3. A refusal (rc 2) names its reason (title chars, empty body, a blocker + body without one backtick-quoted error): fix the input, re-run. +``` + + Old item 5 (caveman) stays, renumbered 4. + - STEP 5: replace the two bullets `- Heading exists → append a bullet.` / `- Missing → create …` by `- \`bash "$HOME/.claude/lib/memory.sh" journal "<line>"\` (one call per bullet; it creates today's heading when missing).` + +- [ ] **Step 2: feat** `:248` (`Always append a 1-line entry to today's heading in \`.claude/memory/journal.md\`.`) → two lines, the **Language rule** line after them untouched: + +``` +Approved entries: caveman body to a scratch file, then `bash "$HOME/.claude/lib/memory.sh" add <decision|learning> --title "<title>" --body-file <file>` (one call each; it allocates the ID; never Edit a registry). + +Always append a 1-line entry: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`. +``` + +- [ ] **Step 3: bugfix** `:275` → `4. Write approved entries with \`bash "$HOME/.claude/lib/memory.sh" add <kind> --title … --body-file <file> --status resolved\` (one call each, it allocates the ID; an existing blocker now fixed: \`memory.sh status <ID> "resolved <hash>"\`). Journal line: \`bash "$HOME/.claude/lib/memory.sh" journal "<line>"\`.` + +- [ ] **Step 4: hotfix** `:234` → `Always append a 1-line entry with \`bash "$HOME/.claude/lib/memory.sh" journal "<line>"\` (even trivial hotfix — journal is timeline, not signal). A proposed BLK/LRN, once approved: \`bash "$HOME/.claude/lib/memory.sh" add <blocker|learning> --title … --body-file <file>\`.` + +- [ ] **Step 5: ship-feature** `:273-274` → +``` +4. Write approved entries with `bash "$HOME/.claude/lib/memory.sh" add <kind> --title "<title>" --body-file <file> [--status <s>]`, one call each (it allocates the ID; no Index to update). +5. Journal line: `bash "$HOME/.claude/lib/memory.sh" journal "<line>"`. +``` + +- [ ] **Step 6: init-project** `:301-303` → `3. Write approved entries to the registries bootstrapped at STEP 5 (in the root commit) with \`bash "$HOME/.claude/lib/memory.sh" add <kind> --title … --body-file <file>\`, one call each; journal line with \`bash "$HOME/.claude/lib/memory.sh" journal "<line>"\`.` + +- [ ] **Step 7: commit-changer** `:220-223` (item 2 of Phase 4) → +``` +2. Write each resolved entry with `bash "$HOME/.claude/lib/memory.sh" add + <decision|learning|blocker|eval> --title "<title>" --body-file <file>` + (one call each; it allocates the ID, no Index to update), then one + journal line for the batch: `bash "$HOME/.claude/lib/memory.sh" journal + "<summary>"`. +``` + +- [ ] **Step 8: onboard S7** — replace `append to that project's \`.claude/memory/journal.md\` under today's date:` by `append to that project's journal with \`bash "$HOME/.claude/lib/memory.sh" -C <ROOT> journal\`:` (the quoted line text after it unchanged). + +- [ ] **Step 9: 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.` and `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 10: CLAUDE.global.md** (line-neutral): + - `Append-only: never rewrite past entries; curation (merge, supersede,\ncompress) only via \`/prune-memory\`.` → `Append-only, written only through \`bash ~/.claude/lib/memory.sh\` (add,\nstatus, journal), never by Edit; curation only via \`/prune-memory\`.` + - `exact. Pattern \`[thing] [action] [reason]. [next step].\` Registries load\nevery session; caveman cuts ~40% of the tokens with no substance lost.` → `exact. Pattern \`[thing] [action] [reason]. [next step].\` Planning flows\nread the registries; caveman cuts ~40% of every read, no substance lost.` + +- [ ] **Step 11: Verify** +Run: `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. +Run: `wc -l < CLAUDE.global.md` → ≤ 333. +Run: `make test suite=lib/tests/doctrine-citers.test.sh` and `make test suite=lib/tests/effort-routing.test.sh` → green (no rewrap of a census string; every `route(phase="apply") … memory-commit` line untouched). + +- [ ] **Step 12: Commit** + +```bash +git add 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): every writer goes through lib/memory.sh; Index steps removed; doctrine names the single writer" +``` + +--- + +### Task 6: /prune-memory on v2 (no § D, status through the lib, check as verify) + +**Files:** +- Modify: `skills/prune-memory/SKILL.md` (`:83-85`, `:111-115`, `:130`, `:141-143`, `:153-158`, `:177`, STEP 4 block `:190-206`, report `:274`, failure row `:305`, `:322-323`) +- Modify: `skills/prune-memory/tests/run-deterministic.sh` (RED-6 rewritten) +- Create: `skills/prune-memory/tests/fixtures/red6-check/.claude/memory/decisions.md` +- Delete: `skills/prune-memory/tests/fixtures/red6-orphan/.claude/memory/decisions.md` (`git rm`) +- Modify: `skills/prune-memory/test-prompts.json` (id 1 `expected`) + +- [ ] **Step 1: Write the failing test** — replace the whole RED-6 block (from `# ---- RED-6:` through its closing `fi`) in `skills/prune-memory/tests/run-deterministic.sh` by: + +```bash +# ---- 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 +``` + +Create `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`. In the suite header comment, `RED-2/RED-6 execute the REAL bash blocks` stays true. + +- [ ] **Step 2: Run, expect red** — `make test suite=skills/prune-memory/tests/run-deterministic.sh` → `RED-6: RED`. + +- [ ] **Step 3: SKILL.md edits** + - § A bullet `:83-85`: `Decisions whose body contains "superseded by <ID>" but Index row still says \`accepted\` → propose Index row fix to \`superseded by <that-ID>\`.` → `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 <ID> "superseded by <that-ID>"\`.` + - Delete § D (`### D. Index drift` and its two bullets, `:111-115`). + - STEP 2 example: `→ fix Index: status = "superseded by BDR-903"` → `→ memory.sh status BDR-902 "superseded by BDR-903"`; delete the `[D. Index drift]` + `(none)` lines; `Approve per category? (all / a / b / c / d / edit <ID> / skip)` → `(all / a / b / c / edit <ID> / skip)`. + - STEP 3 list becomes: + +``` +1. **Status flag updates** — `bash "$HOME/.claude/lib/memory.sh" status <ID> + "<text>"` appends a dated status line; 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 (Reference lines, caveman pass, frontmatter fields) and the existing item 4 renumbered 3 (inline caveman compression, unchanged). 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`), and put in their place: + +```bash +# Structure: heading shape + unique IDs (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`. + - Failure table row `| Index sanity FAILED at STEP 4 | Print exact missing/orphan IDs. …` → `| \`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 all GREEN (RED-5 still green: its journal-only sandbox has no registry, `check` prints nothing). +Run: `grep -n 'Index' skills/prune-memory/SKILL.md` → no writer step mentions an Index. + +- [ ] **Step 6: Commit** + +```bash +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:** +- Modify: `.claude/memory/{decisions,learnings,blockers,evals}.md` (by the lib only) + +- [ ] **Step 1: Dry run on a copy** — + +```bash +d=$(mktemp -d); mkdir -p "$d/.claude/memory"; cp .claude/memory/*.md "$d/.claude/memory/" +bash lib/memory.sh -C "$d" upgrade && bash lib/memory.sh -C "$d" check && echo DRY-OK +``` +Expected: four `memory: upgraded …` lines, `DRY-OK`. + +- [ ] **Step 2: Upgrade in place and commit through the chokepoint** + +```bash +bash lib/memory.sh upgrade +bash lib/memory.sh check && echo CHECK-OK +bash lib/memory.sh index blocker | grep -E 'BLK-03[234]' +bash "$HOME/.claude/lib/memory-commit.sh" commit "chore(memory): registries v2 — Index removed, Index-only dates and statuses materialized (memory.sh upgrade)" +``` +Expected: `CHECK-OK`; BLK-032..034 rows read `resolved` with a date; memory-commit prints a hash (rc 0: the Index lines sit before the first entry, every other change is an insertion). + +- [ ] **Step 3: Verify the live facts** +Run: `make test suite=lib/tests/memory.test.sh` → T12 (live check) green. +Run: `bash -c '. lib/reconcile.sh; reconcile_blk_open .claude/memory/blockers.md | cut -f1 | tr "\n" " "'` → `BLK-001 BLK-003 BLK-017 BLK-018 BLK-021 BLK-022 BLK-029 ` (no 032..034). +Run: `grep -c '^## Index' .claude/memory/*.md` → 0 everywhere. + +--- + +## 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; no file outside this repo changed (`git -C <proj> status --short .claude/memory` empty for the projects listed in the spec § 2.4 note). diff --git a/docs/superpowers/plans/memory-v2-write/blockers-v2-status.md b/docs/superpowers/plans/memory-v2-write/blockers-v2-status.md new file mode 100644 index 0000000..095c611 --- /dev/null +++ b/docs/superpowers/plans/memory-v2-write/blockers-v2-status.md @@ -0,0 +1,49 @@ +--- +format: 2 +type: blockers_registry +entry_prefix: BLK +--- + +# Status parser fixture: BLK-032..034 as written 2026-10-27 (false-open +# before phase 4a), BLK-008 compound (frozen snapshot), BLK-040..042 shapes. + +## BLK-008 — gstack ./setup fails on Ubuntu 26.04 — Playwright chromium unsupported + +- **Date**: 2026-06-23 +- **Friction**: fresh Ubuntu 26.04, `make install` / `make plugin` → "Failed to install browsers / ERROR: Playwright does not support chromium on ubuntu26.04-x64" → "GStack ./setup failed". Non-fatal in our wrapper (warn only) but gstack's browser (`/browse`, `/qa`, design screenshots) is silently dead once gstack is enabled. +- **Real cause**: Playwright 1.58.2 (pinned in the gstack submodule) registry lists `ubuntu20.04/22.04/24.04` only; 26.04 released later → not in list → `getHostPlatform` errors. Pure OS-newness, not an install bug. +- **Solution**: gated `export PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64` (ubuntu >24.04 only) before gstack setup + persisted to `.bashrc` for runtime. Playwright then pulls a Chrome-for-Testing fallback build for ubuntu24.04. Verified on 26.04: `ldd` resolves all libs + real headless render OK. +- **Status**: resolved (commit 211c7d4). Residual: exact rev 1208 launch not in-session-tested (sandbox download hung at extraction); proved via sibling rev 1228 same-platform CfT build. Confirm on next real `make plugin`. Proper upstream fix = gstack bumps Playwright to a version that lists ubuntu26.04. See [[LRN-038]]. + +- **2026-06-23 UPDATE — Solution REVERTED, status downgraded to UPSTREAM/open** (commit b9c3937): the `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE` solution above does NOT work on 26.04. The fallback build downloads to 100% then HANGS at extraction (chrome binary never appears, no headless-shell download starts; reproduced on real machine + sandbox) → turned a 0.5s fast-fail into an install-blocking hang (user Ctrl+C). Reverted to the fast-fail (non-fatal; gstack OFF by default, browser only for /browse,/qa,screenshots). The earlier "verified ldd + headless render" was an isolated test on a sibling already-extracted build (rev 1228) — it masked the rev-1208 install-path hang. **Real fix = upstream**: gstack bumps Playwright to a version that lists ubuntu26.04. Until then gstack's browser is unavailable on 26.04, install completes cleanly. See [[LRN-038]] correction. + +- **2026-06-23 FINAL — RESOLVED** (commit 3b8ffb1): gstack browser now works on Ubuntu 26.04. Two layers fixed: (1) bumped gstack's pinned Playwright 1.58.2 → 1.61 (`bun add playwright@latest` in the submodule; 1.61 ships a native ubuntu26.04 build — chromium rev 1228), automated in the installer (`gstack_bump_playwright_if_unsupported`, idempotent, OS-gated); (2) `GSTACK_CHROMIUM_NO_SANDBOX=1` to work around the AppArmor userns restriction (`sysctl kernel.apparmor_restrict_unprivileged_userns=1`), persisted to `.bashrc` + installer Step 9 (sysctl-gated). Verified end-to-end: `browse goto https://example.com` → "Navigated (200)". Caveat: the Playwright bump is a local submodule edit, reset by `git submodule update`, re-applied by the next install. See [[BDR-029]], [[LRN-040]]. + +--- + +## BLK-032 — Main loop pinned on Fable in long sessions: session model Fable 1M + downgrade cap 120k + prompt rule `plan` → inline code on Fable xhigh [resolved] +- **Cause**: `~/.claude/settings.json` `"model": "claude-fable-5-1[1m]"` (every session starts on Fable); model-router never moves main above the session model, moves DOWN only under `downgradeMaxTokens` 120000 (LRN-204 cold read) → a long session (faunosteo R4.x, context > 120k) never reaches `implement`/sonnet; prompt rule `(plan|design|architecture…)` → phase plan = best/xhigh each turn ("plan §B.1.7"). No doctrine ceiling: CLAUDE.md allows inline work "doable in a few tool calls", BDR-115 "pin = default, never ceiling". +- **User policy 2026-10-19**: session model Opus 5.5; sonnet writes, opus decides what to write; Fable only for orchestrator reflection/plans and the important audits (security, functional), other judges opus. → next `/feat`: settings model, `judge` split, ceiling rule in CLAUDE.md, BDR superseding part of BDR-066 / BDR-115. Links [[BDR-066]], [[BDR-107]], [[BDR-115]], [[LRN-204]]. + +- **Solution (2026-10-23)**: feat A+B (BDR-123) + feat C 786ee13 (feature/router-keyword-cap): keyword prompt rules, `ultrathink` floor, derived `orchestrate` dispatch write effort-only routes (`effortRoute`, `belowRun` pattern) → never lift main above session model; held best-tier run keeps its model (per-axis fall-through); `mainModelSlot` drops `turnFloor`. Fable on main only via skill row, `route` tool, `/route`. Docs d2d590f. Links [[LRN-226]], [[EVAL-048]]. + +## BLK-033 — Guardrails residuals: probe trusted plan `supabase.url`, redirects free of budget, unread bodies read CLOSED; rules 5 FP / 7 misses [resolved] +- **Friction**: GATE 2 of the a11y split (f586304) left a MEDIUM + 3 LOW on probe.py, opus review left Minors on the rules. Parked in TODO, fixed via `/bugfix` 2026-10-20/21. +- **Cause**: `supabase.url` read from the plan w/o `_http_url` → planted SUPABASE_URL would receive GUARDRAILS_ANON_KEY / JWT2, `file://` read CLOSED; `_SameHost` redirector followed hops w/o charging `session.budget`; `_rows_state` collapsed non-200 / empty / >1 MB / non-JSON into CLOSED (unobserved = CLOSED, breaks LRN-220); plan r2 mapped budget exhaustion on `str(URLError)`, which wraps the reason → never matched. Rules: SENSITIVE_KEY on metadata names (`token_type`, `has_password`), 403 on first map candidate stopped the walk, hydrated scan read whole route file, NOSQL `$where` fired on GraphQL `_bool_exp`; misses: Go backtick Sprintf, `rf`/triple-quoted f-strings, `sql|db|trx.raw`, empty `.select()`, multi-line hidden input, Rust `{}` shell arg, `"sources"` map head. +- **Solution**: 5a98c2c (`_BudgetExhausted(URLError)` + `BUDGET_EXHAUSTED` constant, `_SameHost(session)` charges per hop, `_rows_state` rows|empty|unreadable → SKIPPED, `_map_outcome` full candidate walk, `data:` OPEN w/o decoding, `printable` on remote strings, `_safe_text` in scanner, rule fixes + mutant per language variant) + 633faa2 (checks.md: `IN (…)` placeholder list flagged, judged by hand). Plan r3 after 2 challenge rounds, contract 22 oracles MET, verifier CONFORME, auditor PASS. Suites probe 84, scan 241. +- **Residual** (LOW, parked in TODO): table names not `IDENT.fullmatch`-checked per table (`/` → path walk on the approved host); `printable` lets Unicode bidi/format controls through. Links [[LRN-219]], [[LRN-220]], [[LRN-222]], [[LRN-223]]. + +## BLK-034 — mods.test.sh red on CLI 2.1.306: whole-output `warning` grep caught the advisory plugin-directory section [resolved] +- **Friction**: `make test suite=lib/tests/mods.test.sh` → `FAIL model-router: validate printed a warning`, pre-existing on develop (git archive baseline), surfaced as feat B criterion 8 (NEED-DECISION, BDR-123 run). +- **Cause**: CLI 2.1.306 `claude plugin validate` prints "Plugin directory checks" section (submission catalogue): `⚠ Found 1 plugin directory warning:` ICON_MISSING, `--json` `directory.findings[].blocking: false`. mods.test.sh:57 grepped whole output for `warning` (also matched hooks notes quoting register.ts identifiers, checkout paths). Prose scraping of a CLI with an exit-code contract: `--strict` → per-file warnings rc 1, directory findings rc only under `--profile directory`. +- **Solution**: 801992a (bugfix/mods-validate-advisory). Helper `validate_strict` = rc of `claude plugin validate --strict`; check_cli + positive control share it; control = scratch manifests `{"name":"warnfix"}` (rc 1) / cleanfix with version+description+author (rc 0) under script-level `mktemp -d`. Plan r3 after 3 lenses + 1 re-challenge (sed range on closing marker killed: CLI prints it only when findings > 0, fail-open to EOF). GATE 0 7/7, verifier ECARTS(2) = out-of-scope routing.json dialog write only, auditor PASS. +- **Residual**: 3 historical contracts carry old scrape as CHECK oracle (`.claude/tasks/contracts/2026-10-08-model-router-w1a-1533.md:22`, `2026-10-08-model-router-floor-1835.md:22`, `2026-10-09-model-router-tiers-1237.md:23`), left unedited; re-run fails on ICON_MISSING, not a model-router regression. Unverified: whether `--strict` escalates `advice[]`. Links [[LRN-225]], [[BDR-123]]. + +## BLK-040 — accepted with an open check +- **Status**: accepted. Behavioral check OPEN: `x` must ask first. + +## BLK-041 — "Use when [triggers]" mid-title bracket +- **Status**: open. `y` pending. + +## BLK-042 — no status anywhere +- **Solution**: fail-open guard, `data:` OPEN in prose. diff --git a/docs/superpowers/plans/memory-v2-write/memory.sh b/docs/superpowers/plans/memory-v2-write/memory.sh new file mode 100644 index 0000000..85ac453 --- /dev/null +++ b/docs/superpowers/plans/memory-v2-write/memory.sh @@ -0,0 +1,478 @@ +#!/usr/bin/env bash +# lib/memory.sh — the single writer and reader of the .claude/memory +# registries (BDR-125 phase 4a). Sourceable; every verb takes an optional +# leading `-C <dir>` (a dispatched agent's cwd is the session's, never the +# project's): +# add <kind> --title <t> --body-file <f> [--status <s>] [--supersedes <ID>] +# append one entry, next ID from the headings, under the +# lock; the new ID is the only stdout line +# status <ID> <text> append `- **Status (<date>)**: <text>` to the entry +# journal <line> append `- <line>` under today's `## YYYY-MM-DD` +# index [<kind>] ID | Date | Title | Status, from headings and bodies +# check [--staged] [<memory-dir>] heading shape, unique IDs, no Index in +# a v2 file (v1 reported, never failed); --staged: no line +# removed inside an existing entry of a staged v2 registry +# upgrade [<memory-dir>] v1 → v2: Index-only dates and statuses become +# body lines, `format: 2`, `## Index` removed, oracle first +# <kind> = decision | learning | blocker | eval. MEMORY_DATE overrides today. +# Status of an entry: the last candidate wins. A candidate is the heading's +# trailing `[tag]`, or a body line whose bold label names Status, Resolution, +# Action, UPDATE or FINAL (v1: `Status:`), holding a status word. A word in +# prose is never one (the BLK-032..034 false-open). Words rank in +# _MEM_WORDS order, `open` last: "accepted, check OPEN" reads accepted. +# Lock: <git-common-dir>/memory.lock created under noclobber (flock(1) is +# absent on macOS), a lock older than 30 s is stolen. Registry headings +# are scanned outside ``` fences only. + +MEM_GREP="${MEM_GREP:-/usr/bin/grep}" +_MEM_WORDS='resolved superseded deprecated upstream accepted implemented' +_MEM_WORDS+=' shipped proposed keep correct deprecate open' +_MEM_AWK=' +function mem_word(s, t, i, n, w) { + t = tolower(s); n = split(MEMW, w, " ") + for (i = 1; i <= n; i++) + if (t ~ ("(^|[^a-z])" w[i] "([^a-z]|$)")) return w[i] + return "" } +function mem_tag(line) { + if (!match(line, /\[[^]]*\]( \([0-9-]+\))? *$/)) return "" + return mem_word(substr(line, RSTART)) } +function mem_cand(line, lab) { + if (line ~ /^- \*\*[^*]+\*\*/) { + lab = line; sub(/^- \*\*/, "", lab); sub(/\*\*.*/, "", lab) + return tolower(lab) ~ /status|resolution|action|update|final/ \ + && mem_word(line) != "" } + return line ~ /^(- )?[Ss]tatus:/ && mem_word(line) != "" } +function mem_key(line, key) { + return line == "## " key || index(line, "## " key " — ") == 1 } +' + +_mem_date() { printf '%s\n' "${MEMORY_DATE:-$(date +%F)}"; } + +_mem_kind() { # <kind> → "<file> <PREFIX>", rc 2 when unknown + case "$1" in + decision) echo "decisions.md BDR" ;; + learning) echo "learnings.md LRN" ;; + blocker) echo "blockers.md BLK" ;; + eval) echo "evals.md EVAL" ;; + *) echo "memory: unknown kind: $1 (decision|learning|blocker|eval)" >&2 + return 2 ;; + esac +} + +_mem_id_file() { # <ID> → its registry path, rc 2 when the prefix is unknown + case "$1" in + BDR-[0-9]*) echo .claude/memory/decisions.md ;; + LRN-[0-9]*) echo .claude/memory/learnings.md ;; + BLK-[0-9]*) echo .claude/memory/blockers.md ;; + EVAL-[0-9]*) echo .claude/memory/evals.md ;; + *) echo "memory: not an entry ID: $1" >&2; return 2 ;; + esac +} + +_mem_is_v2() { # <file> → rc 0 when the frontmatter carries `format: 2` + awk 'NR == 1 && $0 != "---" { exit } + NR > 1 && $0 == "---" { exit } + $0 == "format: 2" { v2 = 1; exit } + END { exit !v2 }' "$1" +} + +_mem_has_id() { # <file> <ID> → rc 0 when a heading carries the ID + awk -v k="$2" "$_MEM_AWK"' + /^```/ { fence = !fence; next } + !fence && mem_key($0, k) { found = 1; exit } + END { exit !found }' "$1" +} + +_mem_next_id() { # <file> <PREFIX> → max heading ID + 1, zero-padded + awk -v p="$2" ' + /^```/ { fence = !fence; next } + !fence && match($0, "^## " p "-[0-9]+") { + n = substr($0, length(p) + 5, RLENGTH - length(p) - 4) + 0 + if (n > m) m = n } + END { printf "%s-%03d\n", p, m + 1 }' "$1" +} + +memory_entry_status() { # <file> <ID> → winning candidate line, rc 1 if none + awk -v k="$2" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"' + /^```/ { fence = !fence; next } + fence { next } + /^## / { if (on) exit + if (mem_key($0, k)) { on = 1; if (mem_tag($0) != "") last = $0 } + next } + on && mem_cand($0) { last = $0 } + END { if (last == "") exit 1; print last }' "$1" +} + +memory_status_word() { # <line> → its status word, else its first 40 chars + awk -v MEMW="$_MEM_WORDS" "$_MEM_AWK"' + { w = mem_word($0); print (w != "" ? w : substr($0, 1, 40)) }' <<< "$1" +} + +_mem_lock_dir() { # → the lock path for the current repository + local d + if d=$(git rev-parse --git-common-dir 2>/dev/null); then + echo "$d/memory.lock"; return + fi + echo "${TMPDIR:-/tmp}/memory-$(pwd | cksum | cut -d' ' -f1).lock" +} + +_mem_lock() { # <lock file> → rc 0 held, rc 2 after MEM_LOCK_TRIES waits + # noclobber = open(O_EXCL) by bash itself: mkdir is not atomic under + # uutils coreutils 0.10 (two concurrent mkdir both succeed) + local lock="$1" tries=0 now t + until (set -C; date +%s > "$lock") 2>/dev/null; do + now=$(date +%s); t=$(cat "$lock" 2>/dev/null) + case "$t" in ''|*[!0-9]*) t=$now ;; esac # holder still writing it + if [ $((now - t)) -gt 30 ]; then rm -f "$lock"; continue; fi + tries=$((tries + 1)) + [ "$tries" -lt "${MEM_LOCK_TRIES:-50}" ] \ + || { echo "memory: lock busy: $lock" >&2; return 2; } + sleep 0.2 + done +} + +_mem_unlock() { rm -f "$1"; } + +_mem_locked() { # <fn> [args…] → run fn under the lock, its rc + local lock rc + lock=$(_mem_lock_dir) + _mem_lock "$lock" || return 2 + "$@"; rc=$? + _mem_unlock "$lock" + return "$rc" +} + +_mem_one_line() { # <what> <text> → rc 2 when empty or multi-line + case "$2" in + ''|*$'\n'*) echo "memory: $1 must be one non-empty line" >&2; return 2 ;; + esac +} + +_mem_insert() { # <file> <key> <line> → line ends the section, rc 1 if absent + local tmp + tmp=$(mktemp) || { echo "memory: no temp file" >&2; return 2; } + awk -v k="$2" -v ins="$3" "$_MEM_AWK"' + function flush( i) { print ins; for (i = 1; i <= n; i++) print buf[i] + n = 0; done = 1 } + /^```/ { fence = !fence } + on && !fence && /^## / { flush(); on = 0 } + !done && !on && !fence && mem_key($0, k) { on = 1; print; next } + on { if ($0 == "" || $0 == "---") { buf[++n] = $0; next } + for (i = 1; i <= n; i++) print buf[i]; n = 0; print; next } + { print } + END { if (on) flush(); exit !done }' "$1" > "$tmp" + case $? in + 0) cat "$tmp" > "$1" || { rm -f "$tmp"; return 2; } ;; + *) rm -f "$tmp"; return 1 ;; + esac + rm -f "$tmp" +} + +memory_status() { # <ID> <text> + local file + _mem_one_line "status text" "$2" || return 2 + file=$(_mem_id_file "$1") || return 2 + _mem_has_id "$file" "$1" \ + || { echo "memory: no entry $1 in $file" >&2; return 2; } + _mem_locked _mem_insert "$file" "$1" "- **Status ($(_mem_date))**: $2" \ + || { echo "memory: $1 status not written" >&2; return 2; } +} + +_mem_journal_locked() { # <file> <date> <line> + _mem_insert "$1" "$2" "$3" + case $? in + 1) printf '\n## %s\n%s\n' "$2" "$3" >> "$1" ;; + 0) return 0 ;; + *) return 2 ;; + esac +} + +memory_journal() { # <line> → `- <line>` under today's heading + local file=.claude/memory/journal.md line="$1" + _mem_one_line "journal line" "$line" || return 2 + [ -f "$file" ] || { echo "memory: no $file" >&2; return 2; } + case "$line" in '- '*) ;; *) line="- $line" ;; esac + _mem_locked _mem_journal_locked "$file" "$(_mem_date)" "$line" \ + || { echo "memory: journal line not written" >&2; return 2; } +} + +_mem_add_valid() { # <PREFIX> <title> <body-file> <status> <supersedes> + _mem_one_line title "$2" || return 2 + case "$2$4" in *'['*|*']'*|*'|'*) + echo "memory: title and status take no [ ] |" >&2; return 2 ;; + esac + [ "${#2}" -le 160 ] || { echo "memory: title over 160 chars" >&2; return 2; } + case "$4" in *$'\n'*) _mem_one_line status "$4"; return 2 ;; esac + [ -s "$3" ] || { echo "memory: empty or missing body: $3" >&2; return 2; } + if [ "$1" = BLK ] && ! "$MEM_GREP" -q '`' "$3"; then + echo "memory: a blocker body quotes ≥1 error in backticks" >&2; return 2 + fi + case "$5" in ''|"$1"-[0-9]*) ;; *) + echo "memory: --supersedes takes a $1 ID: $5" >&2; return 2 ;; + esac +} + +_mem_entry_text() { # <title> <body-file> <status> <supersedes> → stdout + local tag="" + [ -z "$3" ] || tag=" [$3]" + printf '%s%s (%s)\n' "$1" "$tag" "$(_mem_date)" + awk '{ l[NR] = $0 } END { n = NR; while (n > 0 && l[n] == "") n-- + for (i = 1; i <= n; i++) print l[i] }' "$2" + [ -z "$4" ] || printf 'Supersedes [[%s]].\n' "$4" +} + +_mem_add_locked() { # <file> <PREFIX> <entry-file> <supersedes> + local id bak rc=0 + id=$(_mem_next_id "$1" "$2") + bak=$(mktemp) || { echo "memory: no temp file" >&2; return 2; } + cat "$1" > "$bak" + { printf '\n## %s — ' "$id"; cat "$3"; } >> "$1" || rc=2 + if [ "$rc" = 0 ] && [ -n "$4" ]; then + _mem_insert "$1" "$4" "- **Status ($(_mem_date))**: superseded by $id" \ + || rc=2 + fi + if [ "$rc" = 0 ] && _mem_is_v2 "$1"; then memory_check_file "$1" || rc=2; fi + if [ "$rc" != 0 ]; then + cat "$bak" > "$1"; echo "memory: add refused, $1 restored" >&2 + else echo "$id"; fi + rm -f "$bak" + return "$rc" +} + +memory_add() { # <kind> <title> <body-file> <status> <supersedes> + local spec file entry rc + spec=$(_mem_kind "$1") || return 2 + file=".claude/memory/${spec% *}" + _mem_add_valid "${spec#* }" "$2" "$3" "$4" "$5" || return 2 + [ -f "$file" ] || { echo "memory: no registry: $file" >&2; return 2; } + [ -z "$5" ] || _mem_has_id "$file" "$5" \ + || { echo "memory: no entry $5 in $file" >&2; return 2; } + _mem_is_v2 "$file" || echo "memory: v1 registry (no format: 2): $file" >&2 + entry=$(mktemp) || { echo "memory: no temp file" >&2; return 2; } + _mem_entry_text "$2" "$3" "$4" "$5" > "$entry" + _mem_locked _mem_add_locked "$file" "${spec#* }" "$entry" "$5"; rc=$? + rm -f "$entry" + return "$rc" +} + +_mem_add_cli() { # <kind> --title t --body-file f [--status s] [--supersedes I] + local kind="${1:-}" title="" body="" st="" sup="" + [ $# -gt 0 ] && shift + while [ $# -gt 0 ]; do + [ $# -ge 2 ] || { echo "memory: add: $1 needs a value" >&2; return 2; } + case "$1" in + --title) title="$2" ;; + --body-file) body="$2" ;; + --status) st="$2" ;; + --supersedes) sup="$2" ;; + *) echo "memory: add: unknown option: $1" >&2; return 2 ;; + esac + shift 2 + done + memory_add "$kind" "$title" "$body" "$st" "$sup" +} + +_mem_prefix() { # <file> → the frontmatter entry_prefix, rc 2 when none + local p + p=$(awk 'NR > 1 && $0 == "---" { exit } + sub(/^entry_prefix: /, "") { print; exit }' "$1") + [ -n "$p" ] || { echo "memory: $1: no entry_prefix" >&2; return 2; } + echo "$p" +} + +memory_check_file() { # <file> → rc 2 with each culprit line named + local p + p=$(_mem_prefix "$1") || return 2 + awk -v p="$p" -v f="$1" ' + /^```/ { fence = !fence; next } + fence { next } + $0 == "## Index" { print f ":" NR ": ## Index in a v2 registry"; bad = 1 } + !match($0, "^## " p "-[0-9]") { next } + !match($0, "^## " p "-[0-9][0-9][0-9]+ — .") { + print f ":" NR ": heading shape: " $0; bad = 1; next } + seen[$2]++ { print f ":" NR ": duplicate " $2; bad = 1 } + END { exit bad ? 2 : 0 }' "$1" | sed 's/^/memory: /' >&2 + return "${PIPESTATUS[0]}" +} + +_MEM_REGISTRIES='decisions learnings blockers evals' + +memory_check() { # [--staged] [<memory-dir>] → rc 2 on any culprit + local staged="" dir f rc=0 + [ "${1:-}" = --staged ] && { staged=1; shift; } + dir="${1:-.claude/memory}" + for f in $_MEM_REGISTRIES; do + f="$dir/$f.md" + [ -f "$f" ] || continue + if ! _mem_is_v2 "$f"; then echo "memory: v1: $f" >&2; continue; fi + memory_check_file "$f" || rc=2 + [ -z "$staged" ] || _mem_check_staged "$f" || rc=2 + done + return "$rc" +} + +_mem_check_staged() { # <file> → rc 2 when a staged hunk removes an entry line + local first + git cat-file -e "HEAD:./$1" 2>/dev/null || return 0 + first=$(git show "HEAD:./$1" | awk '/^```/ { fence = !fence; next } + !fence && /^## (BDR|LRN|BLK|EVAL)-[0-9]/ { print NR; exit }') + [ -n "$first" ] || return 0 + git diff --cached -U0 -- "$1" | awk -v first="$first" -v f="$1" ' + /^@@ / { split($2, a, ","); start = substr(a[1], 2) + 0 + cnt = (2 in a) ? a[2] + 0 : 1 + if (cnt > 0 && start + cnt - 1 >= first) { + print "memory: " f ": line " start " removed inside an entry" \ + " (curation: /prune-memory then /commit-change)" + bad = 1 } } + END { exit bad ? 2 : 0 }' >&2 +} + +_mem_index_rows() { # <file> <PREFIX> → "ID | date | title | word" rows + awk -v p="$2" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"' + function row() { if (id != "") print "| " id " | " d " | " t " | " s " |" } + /^```/ { fence = !fence; next } + fence { next } + /^## / { row(); id = "" + if (!match($0, "^## " p "-[0-9]+")) next + id = $2; t = $0; sub(/^## [^ ]+( — )?/, "", t); d = ""; s = mem_tag(t) + if (match(t, / \([0-9-]+\) *$/)) { + d = substr(t, RSTART + 2, RLENGTH - 3); t = substr(t, 1, RSTART - 1) } + else if (match(t, / — [0-9][0-9][0-9][0-9]-[0-9-]+ *$/)) { + d = substr(t, RSTART + 5); t = substr(t, 1, RSTART - 1) } + sub(/ \[[^]]*\] *$/, "", t); gsub(/\|/, "/", t); next } + id == "" { next } + d == "" && sub(/^- \*\*Date\*\*: */, "") { d = substr($0, 1, 10) } + mem_cand($0) { s = mem_word($0) } + END { row() }' "$1" +} + +memory_index() { # [<kind>] → one table per registry + local kinds="decision learning blocker eval" k spec file + [ -z "${1:-}" ] || kinds="$1" + for k in $kinds; do + spec=$(_mem_kind "$k") || return 2 + file=".claude/memory/${spec% *}" + [ -f "$file" ] || continue + printf '%s\n\n| ID | Date | Title | Status |\n|---|---|---|---|\n' "$file" + _mem_index_rows "$file" "${spec#* }" + echo + done +} + +_mem_index_table() { # <file> → "ID<TAB>date<TAB>last column" per Index row + awk '$0 == "## Index" { on = 1; next } + on && /^## / { exit } + on && /^\| *[A-Z]+-[0-9]+ *\|/ { + n = split($0, c, "|") + for (i = 2; i < n; i++) gsub(/^ +| +$/, "", c[i]) + print c[2] "\t" c[3] "\t" c[n - 1] }' "$1" +} + +_mem_upgrade_text() { # <rows> <file> <PREFIX> → the v2 text on stdout + awk -v p="$3" -v today="$(_mem_date)" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"' + function need(i, c, w) { + c = col[i]; w = mem_word(c) + if (p == "EVAL" || w == "") return "" + if (p == "LRN") return c ~ /^superseded by/ ? c : "" + if (st[i] == "" || (w ~ /^(superseded|deprecated)$/ && st[i] != w)) + return c + return "" } + function flush( i, s) { + if (cur != "" && (s = need(cur)) != "") + print "- **Status (" today ", upgrade)**: " s + for (i = 1; i <= n; i++) print buf[i] + n = 0 } + FNR == 1 { pass++ } + pass == 1 { split($0, r, "\t"); dt[r[1]] = r[2]; col[r[1]] = r[3]; next } + pass == 2 { split($0, r, / \| /); sub(/^\| /, "", r[1]) + sub(/ \|$/, "", r[4]); hd[r[1]] = r[2] != ""; st[r[1]] = r[4] + next } + FNR == 1 { print; print "format: 2"; next } + /^```/ { fence = !fence } + $0 == "## Index" { skip = 1; next } + skip { if (/^\|/) { tbl = 1; next } + if (!tbl || $0 == "") { if (tbl) skip = 0; next } + skip = 0 } + !fence && /^## / { flush(); split($0, w, " ") + cur = (w[2] in col) ? w[2] : ""; print + if (cur != "" && !hd[cur] && dt[cur] != "") print "- **Date**: " dt[cur] + next } + cur != "" && ($0 == "" || $0 == "---") { buf[++n] = $0; next } + { for (i = 1; i <= n; i++) print buf[i]; n = 0; print } + END { flush() }' "$1" <(_mem_index_rows "$2" "$3") "$2" +} + +_mem_upgrade_oracle() { # <old> <new> <PREFIX> <rows> → rc 2 on a lost fact + local o n + [ "$("$MEM_GREP" -E "^## $3-[0-9]" "$1")" \ + = "$("$MEM_GREP" -E "^## $3-[0-9]" "$2")" ] \ + || { echo "memory: upgrade changed a heading: $1" >&2; return 2; } + memory_check_file "$2" || return 2 + o=$(_mem_index_rows "$1" "$3"); n=$(_mem_index_rows "$2" "$3") + awk -F'\t' -v p="$3" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"' + function f(s, k) { split(s, a, / \| /); return a[k] } + FNR == 1 { pass++ } + pass == 1 { dt[$1] = $2; col[$1] = $3; next } + { id = f($0, 1); sub(/^\| /, "", id) } + pass == 2 { old[id] = f($0, 4); sub(/ \|$/, "", old[id]); next } + !(id in col) { next } + { d = f($0, 2); s = f($0, 4); sub(/ \|$/, "", s); w = mem_word(col[id]) + if (p == "LRN" && col[id] !~ /^superseded by/) w = "" + if (p == "EVAL") w = "" + want = (w ~ /^(superseded|deprecated)$/ || old[id] == "") ? w : old[id] + if (dt[id] != "" && d == "") bad = bad " " id ":date" + if (want != "" && s != want) bad = bad " " id ":" s "!=" want } + END { if (bad != "") { print "memory: upgrade lost:" bad; exit 2 } }' \ + "$4" <(printf '%s\n' "$o") <(printf '%s\n' "$n") >&2 +} + +_mem_upgrade_file() { # <file> → rc 0 upgraded or already v2, rc 2 refused + local p rows new rc=0 first + IFS= read -r first < "$1" + [ "$first" = --- ] \ + || { echo "memory: $1: no frontmatter, not upgraded" >&2; return 2; } + _mem_is_v2 "$1" && { echo "memory: $1 already v2" >&2; return 0; } + p=$(_mem_prefix "$1") || return 2 + rows=$(mktemp) || { echo "memory: no temp file" >&2; return 2; } + new=$(mktemp) || { rm -f "$rows"; echo "memory: no temp file" >&2; return 2; } + _mem_index_table "$1" > "$rows" + { _mem_upgrade_text "$rows" "$1" "$p" > "$new" \ + && _mem_upgrade_oracle "$1" "$new" "$p" "$rows" \ + && cat "$new" > "$1"; } || rc=2 + rm -f "$rows" "$new" + [ "$rc" = 0 ] && echo "memory: upgraded $1" + [ "$rc" = 0 ] || echo "memory: $1 left as it was" >&2 + return "$rc" +} + +memory_upgrade() { # [<memory-dir>] → every template-born registry to v2 + local dir="${1:-.claude/memory}" f rc=0 + for f in $_MEM_REGISTRIES; do + [ -f "$dir/$f.md" ] || continue + _mem_upgrade_file "$dir/$f.md" || rc=2 + done + return "$rc" +} + +_memory_main() { + set -uo pipefail + if [ "${1:-}" = "-C" ]; then + cd "${2:-}" 2>/dev/null \ + || { echo "memory: no dir ${2:-}" >&2; return 2; } + shift 2 + fi + case "${1:-}:$#" in + add:*) shift; _mem_add_cli "$@" ;; + status:3) memory_status "$2" "$3" ;; + journal:2) memory_journal "$2" ;; + index:[12]) memory_index "${2:-}" ;; + check:*) shift; memory_check "$@" ;; + upgrade:[12]) memory_upgrade "${2:-}" ;; + *) echo "usage: memory.sh [-C dir] add <kind> --title t --body-file f" \ + "[--status s] [--supersedes ID] | status <ID> <text> | journal" \ + "<line> | index [kind] | check [--staged] [dir] | upgrade [dir]" >&2 + return 2 ;; + esac +} + +if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _memory_main "$@"; fi diff --git a/docs/superpowers/plans/memory-v2-write/memory.test.sh b/docs/superpowers/plans/memory-v2-write/memory.test.sh new file mode 100644 index 0000000..a0b12b9 --- /dev/null +++ b/docs/superpowers/plans/memory-v2-write/memory.test.sh @@ -0,0 +1,273 @@ +#!/usr/bin/env bash +# lib/tests/memory.test.sh — lib/memory.sh (add / status / journal / index / +# check / upgrade) and the shared status parser. Hermetic fixtures under one +# mktemp dir with its own git repo; flip-tests first (LRN-096), then the +# real check on this repo's registries. +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +MEM="${MEM_UNDER_TEST:-$ROOT/lib/memory.sh}" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } +FIX=$(mktemp -d); trap 'rm -rf "$FIX"' EXIT +cd "$FIX" || exit 1 +git init -q . && git config user.email t@t && git config user.name t +export MEMORY_DATE=2026-10-27 +mkdir -p .claude/memory +reg() { # <file> <type> <PREFIX> <title> → a v2 registry with no entry + printf -- '---\nformat: 2\ntype: %s\nentry_prefix: %s\n---\n\n# %s\n' \ + "$2" "$3" "$4" > ".claude/memory/$1" +} +reg decisions.md decisions_registry BDR 'Decisions registry (BDR)' +reg learnings.md learnings_registry LRN 'Learnings registry (LRN)' +reg blockers.md blockers_registry BLK 'Blockers registry (BLK)' +reg evals.md evals_registry EVAL 'Evals registry (EVAL)' +printf -- '---\ntype: journal\n---\n\n# Journal\n\n## 2026-10-26\n- old\n' \ + > .claude/memory/journal.md +B=.claude/memory/blockers.md +printf -- "- **Friction**: \`make\` red\n- **Cause**: x\n\n" > body.md + +# T1 add: next ID from headings, canonical heading, ID alone on stdout +out=$(bash "$MEM" add blocker --title 'make red' --body-file body.md \ + --status open) +check T1-first-id "$out" BLK-001 +check T1b-heading "$(grep -c '^## BLK-001 — make red \[open\] (2026-10-27)$' "$B")" 1 +check T1c-body-trimmed "$(tail -1 "$B")" '- **Cause**: x' +check T1d-second-id "$(bash "$MEM" add blocker --title 'two' --body-file body.md)" BLK-002 +check T1e-check-green "$(bash "$MEM" check; echo $?)" 0 +check T1f-index-row "$(bash "$MEM" index blocker | grep -c '^| BLK-001 | 2026-10-27 | make red | open |$')" 1 + +# T2 add refuses, rc 2, registry unchanged +sum=$(cksum < "$B") +refused() { # <name> <add args…> → the add is rc 2 + local name="$1"; shift + bash "$MEM" add "$@" >/dev/null 2>&1 + check "T2-$name" "$?" 2 +} +refused kind unknown --title t --body-file body.md +refused bracket blocker --title 'a[b]' --body-file body.md +refused pipe blocker --title 'a|b' --body-file body.md +refused no-body blocker --title t --body-file missing.md +refused status-bracket blocker --title t --body-file body.md --status 'a]' +refused cross-prefix blocker --title t --body-file body.md --supersedes LRN-001 +refused unknown-sup blocker --title t --body-file body.md --supersedes BLK-099 +refused no-value blocker --title t --body-file +refused bad-option blocker --title t --body-file body.md --bogus x +printf 'no backtick here\n' > plain.md +bash "$MEM" add blocker --title t --body-file plain.md 2>/dev/null +check T2b-blocker-needs-backtick "$?" 2 +check T2c-unchanged "$(cksum < "$B")" "$sum" +bash "$MEM" add learning --title t --body-file plain.md >/dev/null +check T2d-learning-without-backtick "$?" 0 + +# T3 status: a dated line ends the entry, before the next heading's blank +bash "$MEM" status BLK-001 'resolved abc1234' +check T3-rc "$?" 0 +check T3b-placed "$(awk '/^## BLK-001/{on=1} on && /^- \*\*Status/{print; exit}' "$B")" \ + '- **Status (2026-10-27)**: resolved abc1234' +check T3c-before-next "$(awk '/Status \(2026-10-27\)/{getline n; print n; exit}' "$B")" '' +bash "$MEM" status BLK-002 'upstream, open' +check T3d-at-eof "$(tail -1 "$B")" '- **Status (2026-10-27)**: upstream, open' +bash "$MEM" status BLK-404 x 2>/dev/null +check T3e-unknown-id "$?" 2 +bash "$MEM" status BLK-001 "$(printf 'a\nb')" 2>/dev/null +check T3f-multi-line "$?" 2 + +# T4 journal: appended under today, heading created once, old date untouched +J=.claude/memory/journal.md +bash "$MEM" journal 'first' +bash "$MEM" journal '- second' +check T4-heading-once "$(grep -c '^## 2026-10-27$' "$J")" 1 +check T4b-order "$(tail -2 "$J" | tr '\n' '|')" '- first|- second|' +check T4c-old-kept "$(sed -n '/^## 2026-10-26$/,/^$/p' "$J" | grep -c '^- old$')" 1 +bash "$MEM" journal "$(printf 'a\nb')" 2>/dev/null +check T4d-multi-line "$?" 2 + +# T5 --supersedes: forward link on the new entry, status line on the old one +L=.claude/memory/learnings.md +new=$(bash "$MEM" add learning --title 'better' --body-file plain.md \ + --supersedes LRN-001) +check T5-id "$new" LRN-002 +check T5b-forward "$(tail -1 "$L")" 'Supersedes [[LRN-001]].' +word() { # <file> <ID> → the entry's status word, through the lib + # shellcheck source=/dev/null + (. "$MEM"; memory_status_word "$(memory_entry_status "$1" "$2")") +} +check T5c-old-status "$(word "$L" LRN-001)" superseded +check T5d-index "$(bash "$MEM" index learning | grep -c '^| LRN-001 | 2026-10-27 | t | superseded |$')" 1 + +# T6 lock: a held lock refuses, a stale one is stolen, concurrent adds get +# distinct IDs +lock="$(git rev-parse --git-common-dir)/memory.lock" +date +%s > "$lock" +sum=$(cksum < .claude/memory/evals.md) +MEM_LOCK_TRIES=2 bash "$MEM" add eval --title t --body-file plain.md 2>/dev/null +check T6-held-rc "$?" 2 +check T6b-held-unchanged "$(cksum < .claude/memory/evals.md)" "$sum" +echo $(( $(date +%s) - 60 )) > "$lock" +check T6c-stale-stolen "$(bash "$MEM" add eval --title t --body-file plain.md)" EVAL-001 +check T6d-lock-released "$([ -e "$lock" ] && echo held || echo free)" free +for i in 1 2 3 4 5; do + bash "$MEM" add decision --title "d$i" --body-file plain.md > "out$i" & +done +wait +check T6e-distinct "$(cat out1 out2 out3 out4 out5 | sort -u | wc -l | tr -d ' ')" 5 +check T6f-max "$(cat out1 out2 out3 out4 out5 | sort | tail -1)" BDR-005 +check T6g-check-green "$(bash "$MEM" check; echo $?)" 0 + +# T7 check: shape, duplicate, Index in v2 are rc 2; v1 is named, not failed +cp .claude/memory/decisions.md d.bak +printf '\n## BDR-005 — again\nx\n' >> .claude/memory/decisions.md +err=$(bash "$MEM" check 2>&1 >/dev/null); rc=$? +check T7-duplicate-rc "$rc" 2 +check T7b-duplicate-named "$(printf '%s\n' "$err" | grep -c 'duplicate BDR-005')" 1 +cat d.bak > .claude/memory/decisions.md +printf '\n## BDR-7 — short\nx\n' >> .claude/memory/decisions.md +bash "$MEM" check 2>/dev/null +check T7c-shape-rc "$?" 2 +cat d.bak > .claude/memory/decisions.md +printf '\n## Index\n' >> .claude/memory/decisions.md +bash "$MEM" check 2>/dev/null +check T7d-index-in-v2-rc "$?" 2 +cat d.bak > .claude/memory/decisions.md +mkdir v1 && printf '# Decisions\n\n## BDR-001 - legacy\n' > v1/decisions.md +err=$(bash "$MEM" check v1 2>&1 >/dev/null); rc=$? +check T7e-v1-rc "$rc" 0 +check T7f-v1-named "$(printf '%s\n' "$err" | grep -c '^memory: v1: v1/decisions.md$')" 1 + +# T8 check --staged: an append passes, a removed entry line is rc 2 +git add -A && git commit -qm base +bash "$MEM" add blocker --title three --body-file body.md >/dev/null +git add "$B" +check T8-append-staged "$(bash "$MEM" check --staged; echo $?)" 0 +git commit -qm three +sed 's/^## BLK-001 — make red/## BLK-001 — make RED/' "$B" > b.tmp \ + && cat b.tmp > "$B" +git add "$B" +err=$(bash "$MEM" check --staged 2>&1 >/dev/null); rc=$? +check T8b-removed-line-rc "$rc" 2 +check T8c-named "$(printf '%s\n' "$err" | grep -c 'removed inside an entry')" 1 +git checkout -q HEAD -- "$B" + +# T9 upgrade: Index-only dates and statuses become body lines, the marker +# lands, the Index goes, headings untouched; idempotent; refusals keep the file +mkdir -p up/.claude/memory && cd up || exit 1 +cat > .claude/memory/decisions.md <<'EOF' +--- +type: decisions_registry +entry_prefix: BDR +--- + +# Decisions registry (BDR) + +## Index + +| ID | Date | Title | Status | +|----|------|-------|--------| +| BDR-001 | 2026-01-01 | kept | accepted | +| BDR-002 | 2026-01-02 | stale index | accepted | +| BDR-003 | 2026-01-03 | gone | superseded by BDR-004 | +| BDR-004 | 2026-01-04 | no status | accepted | + +--- + +## BDR-001 — kept (2026-01-01) +- **Status**: accepted + +## BDR-002 — stale index +- **Date**: 2026-01-02 +- **Status**: shipped + +## BDR-003 — gone +- **Status**: accepted + +## BDR-004 — no status +body +EOF +cat > .claude/memory/learnings.md <<'EOF' +--- +type: learnings_registry +entry_prefix: LRN +--- + +# Learnings registry (LRN) + +## Index + +| ID | Date | Pattern | Applies to | +|----|------|---------|------------| +| LRN-001 | 2026-02-01 | old | superseded by LRN-002 | +| LRN-002 | 2026-02-02 | new | any shell | + +## LRN-001 — old +x + +## LRN-002 — new +y +EOF +D=.claude/memory/decisions.md +heads=$(grep '^## BDR-' "$D") +bash "$MEM" upgrade >/dev/null 2>&1 +check T9-rc "$?" 0 +check T9b-marker "$(sed -n 2p "$D")" 'format: 2' +check T9c-no-index "$(grep -c '^## Index$\|^| BDR-' "$D")" 0 +check T9d-headings-same "$(grep '^## BDR-' "$D")" "$heads" +check T9e-index-out "$(bash "$MEM" index decision | sed -n '5,8p' | tr '\n' '#')" \ + '| BDR-001 | 2026-01-01 | kept | accepted |#| BDR-002 | 2026-01-02 | stale index | shipped |#| BDR-003 | 2026-01-03 | gone | superseded |#| BDR-004 | 2026-01-04 | no status | accepted |#' +check T9f-lrn-superseded "$(bash "$MEM" index learning | grep -c '^| LRN-001 | 2026-02-01 | old | superseded |$')" 1 +check T9g-lrn-applies-dropped "$(grep -c 'any shell' .claude/memory/learnings.md)" 0 +check T9h-check-green "$(bash "$MEM" check; echo $?)" 0 +sum=$(cksum < "$D") +bash "$MEM" upgrade >/dev/null 2>&1 +check T9i-idempotent "$(cksum < "$D")" "$sum" +cat > .claude/memory/blockers.md <<'EOF' +--- +type: blockers_registry +entry_prefix: BLK +--- + +## Index + +| ID | Date | Friction | Status | +|----|------|----------|--------| +| BLK-001 | 2026-03-01 | dup | open | + +## BLK-001 — dup +- **Status**: open + +## BLK-001 — dup again +EOF +sum=$(cksum < .claude/memory/blockers.md) +bash "$MEM" upgrade >/dev/null 2>&1 +check T9j-oracle-refuses "$?" 2 +check T9k-refused-untouched "$(cksum < .claude/memory/blockers.md)" "$sum" +printf '# Evals\n\n## EVAL-001 | 2026 | pipe dialect\n' > .claude/memory/evals.md +bash "$MEM" upgrade >/dev/null 2>&1 +check T9l-no-frontmatter-rc "$?" 2 +check T9m-dialect-untouched "$(sed -n 1p .claude/memory/evals.md)" '# Evals' +cd "$FIX" || exit 1 + +# T10 parser: header tag and labelled lines only, last wins, open ranks last +cp "$ROOT/lib/tests/fixtures/blockers-v2-status.md" st.md +check T10-header-tag "$(word st.md BLK-032)" resolved +check T10b-prose-open-ignored "$(word st.md BLK-033)" resolved +check T10c-fail-open-ignored "$(word st.md BLK-034)" resolved +check T10d-final-wins "$(word st.md BLK-008)" resolved +check T10e-accepted-before-open "$(word st.md BLK-040)" accepted +check T10f-mid-title-bracket "$(word st.md BLK-041)" open +# shellcheck source=/dev/null +(. "$MEM"; memory_entry_status st.md BLK-042) >/dev/null +check T10g-no-candidate-rc "$?" 1 + +# T11 -C runs from elsewhere +check T11-dash-C "$(cd / && bash "$MEM" -C "$FIX" index blocker | grep -c '^| BLK-00')" 3 +bash "$MEM" -C /nonexistent check 2>/dev/null +check T11b-bad-dir "$?" 2 +bash "$MEM" frobnicate 2>/dev/null +check T11c-usage "$?" 2 + +# T12 this repo's registries pass the check +check T12-live-check "$(bash "$MEM" -C "$ROOT" check >/dev/null 2>&1; echo $?)" 0 + +echo "PASS=$pass FAIL=$fail" +[ "$fail" -eq 0 ]