From 6edf781a1abceead30dbd404bb775f90c0f83046 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 1 Nov 2026 11:39:59 +0100 Subject: [PATCH] chore(contract): memory-v2-minors plan r3 + contract --- .../2026-10-31-memory-v2-minors-0400.md | 31 ++++ .../plans/2026-10-31-memory-v2-minors-0400.md | 149 ++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 .claude/tasks/contracts/2026-10-31-memory-v2-minors-0400.md create mode 100644 .claude/tasks/plans/2026-10-31-memory-v2-minors-0400.md diff --git a/.claude/tasks/contracts/2026-10-31-memory-v2-minors-0400.md b/.claude/tasks/contracts/2026-10-31-memory-v2-minors-0400.md new file mode 100644 index 0000000..a60b7f4 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-31-memory-v2-minors-0400.md @@ -0,0 +1,31 @@ +# CONTRACT — memory-v2-minors + +## REQUEST (verbatim — IMMUTABLE) +Phase 4a parked minors (ledger `.superpowers/sdd/2026-10-27-memory-v2-write/progress.md`): empty `memory.lock.steal` never stale (manual rm); `## Index` comment-edge mismatch; `upgrade` header doc lacks the non-table refusal; memory-commit rc 6 message misleading on a v1→v2 heading-rewrite upgrade; labelled "not resolved yet" reads resolved on v2; body `## ` line splits an entry (refuse at add); `-C` + relative `--body-file` (say absolute in § WRITE); tour/deploy/audit-delta § WRITE pointer; reconcile.sh:24-25 and :41-42 stale comments; `_mem_blob` → `git cat-file blob`; evals template "Later status" line; partial stage dropped on rc 6; 39 pre-existing >80-char lines in reconcile.sh / memory-commit.sh. + +## CLARIFICATIONS +- 2026-10-31 user: a status word negated by not/no/never/pas (same clause: no `, ; . : ( ) ->` between, at most one word between) is ignored; `memory.sh add` refuses a body holding an unfenced `## ` line; rc 6 keeps today's reset and names the paths whose partial stage was dropped. +- Scope split (main loop): this contract = the code half (plan A1-A9). The doc half (`-C` + `--body-file` in § WRITE, tour/deploy/audit-delta pointer, evals template "Later status") is a separate /feat. +- Plan r3: `.claude/tasks/plans/2026-10-31-memory-v2-minors-0400.md` (block T17, not T16; § R3 overrides r2). +- 2026-11-01 user: A2 (Index comment-edge) and A7 (rc 6 upgrade wording) dropped as moot (0 `## Index` left outside faunosteo). + +## ACCEPTANCE CRITERIA +1. The memory suite and the memory-commit deterministic suite are green and hold the new checks (T17-steal-empty-dead, T17-steal-empty-fresh, T17-negated-status, T17-upgrade-negated-refused, T17-add-body-heading-refused, T17-add-body-heading-fenced, T17-blob-absent, T17-blob-read-error; run-deterministic "rc 6 names a dropped partial stage"). + CHECK: cd /home/bchanot/Documents/claude && a=$(make test suite=lib/tests/memory.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'FAIL=0' && b=$(make test suite=lib/tests/run-deterministic.sh 2>&1) && printf '%s\n' "$b" | grep -q 'all suites green' && for n in T17-steal-empty-dead T17-steal-empty-fresh T17-negated-status T17-upgrade-negated-refused T17-add-body-heading-refused T17-add-body-heading-fenced T17-blob-absent T17-blob-read-error; do grep -q "$n" lib/tests/memory.test.sh || exit 1; done && grep -q 'partial stage dropped on' lib/tests/run-deterministic.sh && echo MINORS-OK + EXPECT: MINORS-OK + EVIDENCE: MET exit=0 marker-found :: MINORS-OK +2. reconcile suite green; lib/memory.sh, lib/memory-commit.sh and lib/reconcile.sh are shellcheck-clean and hold no line over 80 columns. + CHECK: cd /home/bchanot/Documents/claude && r=$(make test suite=lib/tests/run-reconcile.sh 2>&1) && printf '%s\n' "$r" | grep -q ' 0 RED' && shellcheck lib/memory.sh lib/memory-commit.sh lib/reconcile.sh && [ "$(LC_ALL=C awk 'length($0) > 80' lib/memory.sh lib/memory-commit.sh lib/reconcile.sh | wc -l)" = 0 ] && echo LIB-LINT-OK + EXPECT: LIB-LINT-OK + EVIDENCE: MET exit=0 marker-found :: LIB-LINT-OK +3. Real data: `memory.sh -C index` over the 14 repos holding registries is identical before and after, except robin_petier EVAL-005 (`accepted` → `keep`, expected) and any other move named in the report. Judged by the verifier from the main loop's replay. +4. Each fix check fails on develop's lib (T17-negated-status: at least the r3 biting cases); the over-reach guards (T17-steal-empty-fresh, T17-add-body-heading-fenced) fail on their named mutant instead (`-mmin +0`, fence-blind scan). Executor reports the controls; judged by the verifier. + +5. The reflow (plan A9) changes no behaviour: `declare -f` / `declare -p RECONCILE_DEFER_RE` of reconcile.sh and memory-commit.sh are byte-identical before and after (executor reports the diff). Judged by the verifier. + +## FILE SCOPE +- lib/memory.sh +- lib/memory-commit.sh +- lib/reconcile.sh +- lib/tests/memory.test.sh +- lib/tests/run-deterministic.sh diff --git a/.claude/tasks/plans/2026-10-31-memory-v2-minors-0400.md b/.claude/tasks/plans/2026-10-31-memory-v2-minors-0400.md new file mode 100644 index 0000000..c096c5c --- /dev/null +++ b/.claude/tasks/plans/2026-10-31-memory-v2-minors-0400.md @@ -0,0 +1,149 @@ +# /feat memory-v2-minors (code) — PLAN r3 (r3 overrides r2 where they differ: see § R3) + +r2 2026-10-31 after 3 lenses: robustness FATAL(5), correctness CONCERNS(4), +simplicity CONCERNS(2). User picks 2026-10-31: (a) negated status word ignored, +scope = same clause (no `, ; . : ( ) ->` between negator and word, at most one word +between); (b) `memory.sh add` refuses an unfenced body `## ` line; (c) rc 6 keeps +today's reset (nothing left staged) and NAMES the paths whose partial stage was lost. + +FEAT: phase 4a parked minors, code half — 5 files: lib/memory.sh, +lib/memory-commit.sh, lib/reconcile.sh, lib/tests/memory.test.sh, +lib/tests/run-deterministic.sh. Doc half (capitalize-commit § WRITE `-C` + +absolute `--body-file`, tour/deploy/audit-delta pointers, evals template "Later +status") = separate /feat. + +## Plan (two commits: C1 behaviour A1-A8, C2 cosmetic A9) +- [ ] A1 `_mem_steal`: an EMPTY `memory.lock.steal` (stealer killed between its + noclobber create and its `date` write) is dead when older than 60 s: + `"$MEM_FIND" "$g" -prune -mmin +1` with `MEM_FIND="${MEM_FIND:-/usr/bin/find}"` + pinned like MEM_GREP (the harness shell wraps `find` in a function; GNU and BSD + `-mmin +1` both mean > 60 s; not POSIX, present on GNU/BSD/busybox). A non-empty + steal file keeps the 30 s rule. Header lines 35-38 gain the dead-stealer rule. + `shortcut:` comment on the pre-existing check-then-rm window (another waiter may + remove + a new stealer recreate between the read and `rm -f "$g"`; upgrade path + = compare content just before rm). +- [ ] A2 ONE Index-section walker. `_mem_index_table` becomes the single reader of + the `## Index` span with the gate's bounds (skip `` lines and blocks; + the span ends at `^#`, `^---$`, or a blank line after the table) and returns rc 1 + when the span holds a non-table line. `_mem_upgrade_ready` calls it (`> /dev/null`) + and `_mem_index_only_table` is deleted. The Index remover inside + `_mem_upgrade_text` (~576-580) uses the SAME bounds (shared `_MEM_AWK` function + `mem_index_span(line)` or equivalent state machine), so the gate, the row source + and the remover cannot disagree. +- [ ] A3 header (lines 17-26, `upgrade`): "a `## Index` that is not a table is + refused (rc 2)". +- [ ] A4 ONE negation-aware occurrence test in `_MEM_AWK` (`mem_has(t, w)`): an + occurrence of status word w counts unless a negator `not|no|never|pas` precedes + it in the same clause — no `,` `;` `.` `:` `(` `)` `->` between them — with at + most one word between. The next non-negated occurrence still counts. Used by + `mem_word` AND `_mem_v1_word` (pass `$_MEM_AWK` in), so a v1 `Status: not + resolved yet` has no closed word and the upgrade refuses it (named), never writes + `resolved`. +- [ ] A5 `memory_add`: refuse (rc 2, nothing written, before the lock) a body holding + a `^## ` line outside a ``` fence: `memory: add: body line starts with "## ": + use "###" or indent it`. A fenced `## ` line is accepted. +- [ ] A6 `_mem_blob`: `git cat-file blob "$1" > "$2" 2>/dev/null || return 1` + (git exits 128 on an absent path; the function keeps rc 1). Header comment: + "rc 1 when absent, out file empty". Drop the two `|| : > "$h"` / `|| : > "$s"` + fallbacks only if the out file is provably empty on failure (it is: `>` truncates + first); keep behaviour identical. +- [ ] A7 `_mem_check_staged`: when HEAD's file is v1 and the staged one is v2, print + ONCE per file `memory: : v1 → v2 upgrade — heading rewrites are expected; + commit it with /commit-change`, and per removed hunk keep "fix it" wording unless + the removed HEAD line at `start` is an entry heading (`^#+ *PREFIX-[0-9]`), whose + line then says `heading rewritten by the upgrade`. A body line removed in the + same commit still says "fix it". +- [ ] A8 memory-commit.sh rc 6 (user pick c): keep `git reset -q -- "${changed[@]}"`. + Before `git add`, record the changed paths that already had a staged change + differing from HEAD (`git diff --cached --name-only -- "${changed[@]}"`); on + refusal, stderr adds `memory-commit: partial stage dropped on: ` when that + list is non-empty. "nothing left staged" stays true. Comments unchanged in meaning. +- [ ] A9 (commit C2, cosmetic only): reconcile.sh stale comments (lines 24-25: + status = lib/memory.sh shared parser on v2, legacy lexical on v1, "not closed" = + resolved|superseded|deprecated; line 41-42: `## ID` headings only, v1 `###` + entries invisible); reflow every line > 80 BYTES in reconcile.sh (32) and + memory-commit.sh (7, two hold em-dashes) without behaviour change. + RECONCILE_DEFER_RE value must stay byte-identical (assert: sourced value before + == after). +- [ ] Tests, lib/tests/memory.test.sh new block **T17** (T16 exists): + T17-steal-empty-dead: plant a stale lock (`echo "$(( $(date +%s) - 60 )) dead.1" > + "$lock"`), an empty `.steal` with `touch -t 202001010000`; an add → rc 0, `.steal` + gone, lock released. + T17-steal-empty-fresh: same stale lock, fresh empty `.steal`, `MEM_LOCK_TRIES=3` + → rc 2 "lock busy", `.steal` still there, registry byte-identical. Negative + control = the `-mmin +0` mutant (fails this check), not develop. + T17-index-comment-row: Index with a multi-line comment holding `| BDR-009 | … |`, + then the real table, then a blank line and a stray `| X |` line: rows = only the + real table; the UPGRADED file holds no `|` row and no `-->` above the first entry. + T17-negated-status: `not resolved yet` → none; `open, not resolved yet` → open; + `never superseded` → none; `resolved, not open` → resolved; `no repro, + resolved` → resolved; `not yet resolved` → none; `(JS off -> no dialog), + accepted` → accepted. Run once under `/usr/bin/mawk` via a PATH shim (BWK-class + awk) when present. + T17-upgrade-negated-refused (T15-style v1 fixture `Status: not resolved yet` + under a v1 reader that reads it closed): upgrade rc 2, file byte-identical, ID + named, no `upgrade)` line. + T17-add-body-heading-refused: rc 2, registry byte-identical, message names the + line. T17-add-body-heading-fenced: accepted (over-reach guard; negative control + = a fence-blind scan mutant). + T17-blob-absent: pre-filled out file, absent path → rc 1, out file empty. + T17-upgrade-staged-message: staged v1→v2 upgrade → the once-per-file line + the + heading wording; plus a body line removed in the same staged diff still says + "fix it". + lib/tests/run-deterministic.sh: "rc 6 names a dropped partial stage": stage + version A of a v2 registry edit, write culprit version B to the worktree, + commit → rc 6, stderr names the path, the index holds neither A nor B (nothing + left staged). + +## Real-data proof (main loop, before merge-ready) +`memory.sh -C index` before/after A4 over every registry of the 12 repos +holding one (Documents/{claude,config,faunosteo,game,integration_alphalink, +robin_petier,zenquality}, repos/bchanot/{angelscar356,bchanot-cv,for_you,game-deploy, +gitea-deploy,nuit-folle,trucks_at_work}); expected move: robin_petier EVAL-005 +`accepted` → `keep` (its `**Action**: keep, … A guard is not accepted until …` is a +real misread today); any other move is reported, not waived. + +## Contract criterion 4 amendment +"Each fix check fails on develop's lib; the over-reach guards (T17-steal-empty-fresh, +T17-add-body-heading-fenced) fail on their named mutant instead." + +## Disposition +Honors BDR-129 (single writer, ONE shared parser: A2 one walker, A4 one negation +test for both readers), LRN-237 (oracle not sharing a narrowed reader blindly; assert +on the upgraded entry; real-data replay across repos), LRN-244 (no new stream over a +rewritten file), LRN-096 (each check bites). + +## R3 (2026-11-01, confirmation robustness CONCERNS(4) folded, no further pass) +User pick 2026-11-01: A2 and A7 DROPPED (closed as moot: 0 `## Index` left in the 14 +registry repos except faunosteo, whose upgrade passes the oracle on a copy). A3 stays. +Delete from the plan and tests: A2, A7, T17-index-comment-row, +T17-upgrade-staged-message. Changes to the kept items: +- A1: dead = `[ -n "$("$MEM_FIND" "$g" -prune -empty -mmin +1 2>/dev/null)" ]` + (find exits 0 either way: stdout decides; stderr silenced for a vanished file). + `shortcut:` upgrade path = inode/mtime re-check just before rm (content cannot tell + two empty files apart). +- A4: a "word" = a maximal `[a-z0-9]` run; boundaries `, ; . : ( ) ->` plus `→` and + `—`. No ERE interval expressions in `mem_has` (old BWK awks read `{0,1}` literally): + count words with a loop. Refusal wording in `_mem_repair_one`: "v1 closed by an + unlabelled, mixed or negated line". T17-negated-status adds biting cases: + `not reproduced but resolved` → resolved (two words between), `not reproducible -> + resolved` → resolved, `not; resolved` → resolved, `not → resolved` → resolved, + `never — superseded` → superseded. The mawk run prints `SKIP mawk absent` when + /usr/bin/mawk is missing and is called a "mawk run" (not BWK coverage). +- A6: keep `git cat-file -e` for absent (rc 1); a failing `git cat-file blob` after a + successful `-e` → rc 2; `_mem_check_staged` refuses (rc 2, named) on rc 2 instead of + treating the file as new. T17-blob-absent asserts rc 1 + empty out; add + T17-blob-read-error (a `git` PATH shim failing `cat-file blob` only → rc 2, check + refuses). +- A8: list = paths in `git diff --cached --name-only` (index≠HEAD) ∩ `git diff + --name-only` (index≠worktree), computed before `git add`; for each, stderr + `memory-commit: partial stage dropped on: (blob ; restore: git + update-index --cacheinfo 100644,,)` with the oid from `git ls-files -s`. + The run-deterministic case asserts that literal line for the staged path, and that + a FULLY staged file (index = worktree) is not listed. +- A9: proof = `bash -c '. lib/reconcile.sh; declare -f; declare -p + RECONCILE_DEFER_RE'` (and the same for memory-commit.sh functions) byte-identical + before and after the reflow; any intended string split reviewed by hand. +- Real-data replay: 14 repos (not 12). +- awk state in `_MEM_AWK` helpers is namespaced (`_nx_*`) or kept local (function + params): no new bare globals.