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,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.