chore(contract): memory-v2-minors plan r3 + contract

This commit is contained in:
bchanot committed 2026-11-01 11:39:59 +01:00
1 parent 48ade8f405
commit 6edf781a1a
2 files changed
+180

No files matched your search

@@ -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 <repo> 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
@@ -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 <N> 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: <file>: 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: <paths>` 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 <repo> 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: <path> (blob <oid>; restore: git
update-index --cacheinfo 100644,<oid>,<path>)` 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.