docs(plan): memory v2 write r2 — challenge round 1 addressed (one classifier, dialect-tolerant key, ENVIRON, fences, new-culprits-only)

This commit is contained in:
bchanot committed 2026-10-28 11:59:28 +01:00
1 parent 90d5f96c95
commit c1de516b27
6 files changed
+508 -329

No files matched your search

@@ -0,0 +1,10 @@
# Blockers
## BLK-001 - hyphen dialect, resolved
- **Status**: resolved
## BLK-002 | 2026-05-18 | pipe dialect, open
Status: open
## BLK-003 | 2026-05-19 | pipe dialect, resolved
Status: resolved.
@@ -47,3 +47,10 @@ entry_prefix: BLK
## BLK-042 — no status anywhere
- **Solution**: fail-open guard, `data:` OPEN in prose.
## BLK-043 — DNS resolved to stale IP after failover [open] (2026-10-28)
- **Friction**: `dig` answers the old address.
## BLK-044 — reopened after a regression [resolved] (2026-10-28)
- **Cause**: `abc` reverted the fix.
- **Status (2026-10-28)**: open again, not resolved by abc
+212 -102
View File
@@ -6,25 +6,34 @@
# 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
# status <ID> <text> append `- **Status (<date>)**: <text>` to the entry;
# <text> starts with a status word ("open, reopened by …")
# 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
# check [--staged] [<memory-dir>] heading shape, unique IDs, no Index,
# no open fence in a v2 file (v1 reported, never failed);
# --staged: only NEW culprits vs HEAD, no line removed
# inside an entry, no v2 registry deleted or downgraded
# 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.
# prose (title included) is never one (the BLK-032..034 false-open). A dated
# `**Status (YYYY-MM-DD…)**:` line reads its leading word; other lines rank
# words in _MEM_WORDS order, `open` last: "accepted, check OPEN" = accepted.
# Closed = resolved | superseded | deprecated (memory_closed).
# 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.
# are scanned outside ``` fences only; free text reaches awk through
# ENVIRON, never `-v` (which expands backslash escapes).
MEM_GREP="${MEM_GREP:-/usr/bin/grep}"
_MEM_TABLE='decision decisions BDR
learning learnings LRN
blocker blockers BLK
eval evals EVAL'
_MEM_WORDS='resolved superseded deprecated upstream accepted implemented'
_MEM_WORDS+=' shipped proposed keep correct deprecate open'
_MEM_AWK='
@@ -33,43 +42,65 @@ function mem_word(s, t, i, n, w) {
for (i = 1; i <= n; i++)
if (t ~ ("(^|[^a-z])" w[i] "([^a-z]|$)")) return w[i]
return "" }
function mem_lead(s, v, i, n, w) {
v = s; sub(/^[^:]*\*\*: */, "", v); v = tolower(v)
sub(/[^a-z].*$/, "", v); n = split(MEMW, w, " ")
for (i = 1; i <= n; i++) if (v == w[i]) return v
return "" }
function mem_lineword(s, w) {
if (s ~ /^- \*\*Status \([0-9]/ && (w = mem_lead(s)) != "") return w
return mem_word(s) }
function mem_tag(line) {
if (!match(line, /\[[^]]*\]( \([0-9-]+\))? *$/)) return ""
return mem_word(substr(line, RSTART)) }
if (mem_word(substr(line, RSTART)) == "") return ""
line = substr(line, RSTART); sub(/\].*$/, "]", line); return line }
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 }
if (tolower(lab) !~ /status|resolution|action|update|final/) return ""
return mem_lineword(line) }
if (line ~ /^(- )?[Ss]tatus:/) return mem_word(line)
return "" }
function mem_key(line, key, c) {
if (index(line, "## " key) != 1) return 0
c = substr(line, length(key) + 4, 1)
return c == "" || c !~ /[0-9A-Za-z]/ }
function mem_want(p, c, st, w) {
w = mem_word(c)
if (p == "EVAL" || w == "") return ""
if (p == "LRN") return c ~ /^superseded by/ ? c : ""
if (st == "" || (w ~ /^(superseded|deprecated)$/ && st != w)) return c
return "" }
'
_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_row() { # <column 1|2|3> <value> → "kind file PREFIX", rc 2 if none
awk -v c="$1" -v v="$2" '$c == v { print; f = 1; exit }
END { exit f ? 0 : 2 }' <<< "$_MEM_TABLE"
}
_mem_names() { local k f p; while read -r k f p; do echo "$f"; done \
<<< "$_MEM_TABLE"; }
_mem_kind() { # <kind> → "<file>.md <PREFIX>", rc 2 when unknown
local row file prefix
row=$(_mem_row 1 "$1") || {
echo "memory: unknown kind: $1 (decision|learning|blocker|eval)" >&2
return 2; }
read -r _ file prefix <<< "$row"
echo "$file.md $prefix"
}
_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
local row file
row=$(_mem_row 3 "${1%%-[0-9]*}") \
|| { echo "memory: not an entry ID: $1" >&2; return 2; }
read -r _ file _ <<< "$row"
echo ".claude/memory/$file.md"
}
_mem_is_v2() { # <file> → rc 0 when the frontmatter carries `format: 2`
memory_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 }
@@ -77,7 +108,8 @@ _mem_is_v2() { # <file> → rc 0 when the frontmatter carries `format: 2`
}
_mem_has_id() { # <file> <ID> → rc 0 when a heading carries the ID
awk -v k="$2" "$_MEM_AWK"'
MEM_K="$2" awk "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"] }
/^```/ { fence = !fence; next }
!fence && mem_key($0, k) { found = 1; exit }
END { exit !found }' "$1"
@@ -92,23 +124,32 @@ _mem_next_id() { # <file> <PREFIX> → max heading ID + 1, zero-padded
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"'
memory_entry_status() { # <file> <ID> → the winning candidate, rc 1 if none
# a heading candidate prints its `[tag]` only, never the title
MEM_K="$2" awk -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"] }
/^```/ { fence = !fence; next }
fence { next }
/^## / { if (on) exit
if (mem_key($0, k)) { on = 1; if (mem_tag($0) != "") last = $0 }
if (mem_key($0, k)) { on = 1; t = mem_tag($0)
if (t != "") last = t }
next }
on && mem_cand($0) { last = $0 }
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_L="$1" awk -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
BEGIN { s = ENVIRON["MEM_L"]; w = mem_lineword(s)
print (w != "" ? w : substr(s, 1, 40)) }'
}
_mem_lock_dir() { # → the lock path for the current repository
memory_closed() { # <status word> → rc 0 when it closes the entry
case "$1" in resolved|superseded|deprecated) return 0 ;; esac
return 1
}
_mem_lock_path() { # → the lock file for the current repository
local d
if d=$(git rev-parse --git-common-dir 2>/dev/null); then
echo "$d/memory.lock"; return
@@ -123,7 +164,10 @@ _mem_lock() { # <lock file> → rc 0 held, rc 2 after MEM_LOCK_TRIES waits
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
if [ $((now - t)) -gt 30 ]; then # steal: rename first, never rm shared
mv "$lock" "$lock.stale.$$" 2>/dev/null && rm -f "$lock.stale.$$"
continue
fi
tries=$((tries + 1))
[ "$tries" -lt "${MEM_LOCK_TRIES:-50}" ] \
|| { echo "memory: lock busy: $lock" >&2; return 2; }
@@ -135,9 +179,11 @@ _mem_unlock() { rm -f "$1"; }
_mem_locked() { # <fn> [args…] → run fn under the lock, its rc
local lock rc
lock=$(_mem_lock_dir)
lock=$(_mem_lock_path)
_mem_lock "$lock" || return 2
trap '_mem_unlock "$lock"; exit 130' INT TERM HUP
"$@"; rc=$?
trap - INT TERM HUP
_mem_unlock "$lock"
return "$rc"
}
@@ -151,7 +197,8 @@ _mem_one_line() { # <what> <text> → rc 2 when empty or multi-line
_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"'
MEM_K="$2" MEM_INS="$3" awk "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"]; ins = ENVIRON["MEM_INS"] }
function flush( i) { print ins; for (i = 1; i <= n; i++) print buf[i]
n = 0; done = 1 }
/^```/ { fence = !fence }
@@ -168,14 +215,28 @@ _mem_insert() { # <file> <key> <line> → line ends the section, rc 1 if absent
rm -f "$tmp"
}
_mem_status_text() { # <text> → rc 2 unless it starts with a status word
local w
w=$(tr '[:upper:]' '[:lower:]' <<< "${1%%[^A-Za-z]*}")
case " $_MEM_WORDS " in *" $w "*) [ -n "$w" ] && return 0 ;; esac
echo "memory: status text starts with a status word: $_MEM_WORDS" >&2
return 2
}
memory_status() { # <ID> <text>
local file
local file rc
_mem_one_line "status text" "$2" || return 2
_mem_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; }
[ -f "$file" ] || { echo "memory: no registry: $file" >&2; return 2; }
_mem_locked _mem_insert "$file" "$1" "- **Status ($(_mem_date))**: $2"
rc=$?
case "$rc" in
0) return 0 ;;
1) echo "memory: no entry $1 in $file" >&2 ;;
*) echo "memory: $1 status not written" >&2 ;;
esac
return 2
}
_mem_journal_locked() { # <file> <date> <line>
@@ -204,6 +265,8 @@ _mem_add_valid() { # <PREFIX> <title> <body-file> <status> <supersedes>
[ "${#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; }
awk '/^```/ { n++ } END { exit n % 2 }' "$3" \
|| { echo "memory: body leaves a code fence open" >&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
@@ -222,18 +285,22 @@ _mem_entry_text() { # <title> <body-file> <status> <supersedes> → stdout
}
_mem_add_locked() { # <file> <PREFIX> <entry-file> <supersedes>
local id bak rc=0
id=$(_mem_next_id "$1" "$2")
local f="$1" id bak rc=0
id=$(_mem_next_id "$f" "$2")
bak=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
cat "$1" > "$bak"
{ printf '\n## %s — ' "$id"; cat "$3"; } >> "$1" || rc=2
cat "$f" > "$bak"
trap 'cat "$bak" > "$f"; rm -f "$bak"; _mem_unlock "$(_mem_lock_path)"
exit 130' INT TERM HUP
{ printf '\n## %s — ' "$id"; cat "$3"; } >> "$f" || rc=2
if [ "$rc" = 0 ] && [ -n "$4" ]; then
_mem_insert "$1" "$4" "- **Status ($(_mem_date))**: superseded by $id" \
_mem_insert "$f" "$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 ] && memory_is_v2 "$f"; then
memory_check_file "$f" "$bak" || rc=2
fi
if [ "$rc" != 0 ]; then
cat "$bak" > "$1"; echo "memory: add refused, $1 restored" >&2
cat "$bak" > "$f"; echo "memory: add refused, $f restored" >&2
else echo "$id"; fi
rm -f "$bak"
return "$rc"
@@ -247,7 +314,7 @@ memory_add() { # <kind> <title> <body-file> <status> <supersedes>
[ -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
memory_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=$?
@@ -280,75 +347,109 @@ _mem_prefix() { # <file> → the frontmatter entry_prefix, rc 2 when none
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" '
_mem_culprits() { # <file> <PREFIX> → "<line>\t<reason>" per culprit
awk -v p="$2" '
/^```/ { fence = !fence; next }
fence { next }
$0 == "## Index" { print f ":" NR ": ## Index in a v2 registry"; bad = 1 }
$0 == "## Index" { print NR "\t## Index in a v2 registry" }
!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]}"
print NR "\theading shape: " $0; next }
seen[$2]++ { print NR "\tduplicate " $2 }
END { if (fence) print NR "\tcode fence open at end of file" }' "$1"
}
_MEM_REGISTRIES='decisions learnings blockers evals'
memory_check_file() { # <file> [<reference>] [<name>] → rc 2 on a culprit
# with a reference, only culprits absent from it count (a duplicate a
# merge left behind never blocks the next append)
local p ref="${2:-/dev/null}" name="${3:-$1}"
p=$(_mem_prefix "$1") || return 2
[ -s "$ref" ] || ref=/dev/null
awk -F'\t' -v f="$name" '
FILENAME == ARGV[1] { old[$2]++; next }
old[$2]-- > 0 { next }
{ print "memory: " f ":" $1 ": " $2; bad = 1 }
END { exit bad ? 2 : 0 }' \
<(_mem_culprits "$ref" "$p") <(_mem_culprits "$1" "$p") >&2
}
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
for f in $(_mem_names); do
f="$dir/$f.md"
if [ -n "$staged" ]; then _mem_check_staged "$f" || rc=2; continue; fi
[ -f "$f" ] || continue
if ! _mem_is_v2 "$f"; then echo "memory: v1: $f" >&2; continue; fi
if ! memory_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 }')
_mem_blob() { # <rev:path> <out file> → rc 1 when the blob is absent
git cat-file -e "$1" 2>/dev/null && git show "$1" > "$2"
}
_mem_check_staged() { # <file> → rc 2 on a new culprit or a lost v2 file
local h s rc=0
h=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
s=$(mktemp) || { rm -f "$h"; echo "memory: no temp file" >&2; return 2; }
_mem_blob "HEAD:./$1" "$h" || : > "$h"
_mem_blob ":./$1" "$s" || : > "$s"
if [ -s "$h" ] && memory_is_v2 "$h" && ! { [ -s "$s" ] && memory_is_v2 "$s"; }
then
echo "memory: $1: staged deletion, emptying or loss of format: 2" >&2
rc=2
elif [ -s "$s" ] && memory_is_v2 "$s"; then
memory_check_file "$s" "$h" "$1" || rc=2
_mem_removed_lines "$1" "$h" || rc=2
fi
rm -f "$h" "$s"
return "$rc"
}
_mem_removed_lines() { # <file> <HEAD copy> → rc 2 when a hunk removes an
local p first # entry line (an Index sits above the first entry)
[ -s "$2" ] || return 0
p=$(_mem_prefix "$2" 2>/dev/null) || return 0
first=$(awk -v p="$p" '/^```/ { fence = !fence; next }
!fence && match($0, "^## " p "-[0-9]") { print NR; exit }' "$2")
[ -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)"
" (fix it, then commit with /commit-change)"
bad = 1 } }
END { exit bad ? 2 : 0 }' >&2
}
_mem_index_rows() { # <file> <PREFIX> → "ID | date | title | word" rows
_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)
id = $2; t = $0; sub(/^## [^ ]+( — )?/, "", t); d = ""
s = mem_word(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) }
d = substr(t, RSTART); t = substr(t, 1, RSTART - 1)
sub(/^ — /, "", d) }
sub(/ \[[^]]*\] *$/, "", t); gsub(/\|/, "/", t); next }
id == "" { next }
d == "" && sub(/^- \*\*Date\*\*: */, "") { d = substr($0, 1, 10) }
mem_cand($0) { s = mem_word($0) }
(w = mem_cand($0)) != "" { s = w }
END { row() }' "$1"
}
memory_index() { # [<kind>] → one table per registry
local kinds="decision learning blocker eval" k spec file
[ -z "${1:-}" ] || kinds="$1"
local kinds k spec file
kinds=${1:-$(awk '{ print $1 }' <<< "$_MEM_TABLE")}
for k in $kinds; do
spec=$(_mem_kind "$k") || return 2
file=".claude/memory/${spec% *}"
@@ -370,21 +471,18 @@ _mem_index_table() { # <file> → "ID<TAB>date<TAB>last column" per Index row
_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)) != "")
function flush( i, s, w) {
w = mem_word(col[cur])
if (cur != "" && (s = mem_want(p, col[cur], st[cur])) != "")
print "- **Status (" today ", upgrade)**: " s
else if (cur != "" && w != "" && p !~ /^(LRN|EVAL)$/ && w != st[cur])
print "memory: " cur ": kept body " st[cur] ", dropped Index " \
col[cur] > "/dev/stderr"
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])
FILENAME == ARGV[1] { split($0, r, "\t"); dt[r[1]] = r[2]
col[r[1]] = r[3]; next }
FILENAME == ARGV[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 }
@@ -411,27 +509,39 @@ _mem_upgrade_oracle() { # <old> <new> <PREFIX> <rows> → rc 2 on a lost fact
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 }
FILENAME == ARGV[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 }
FILENAME == ARGV[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]
{ d = f($0, 2); s = f($0, 4); sub(/ \|$/, "", s)
m = mem_want(p, col[id], old[id])
want = m != "" ? mem_word(m) : 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
_mem_upgrade_ready() { # <file> → rc 0 upgradable, 1 already v2, 2 refused
local first p
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; }
memory_is_v2 "$1" && { echo "memory: $1 already v2" >&2; return 1; }
p=$(_mem_prefix "$1") || return 2
awk -v p="$p" '/^```/ { fence = !fence; next }
!fence && match($0, "^## " p "-[0-9]+") \
&& substr($0, RLENGTH + 1) !~ /^( — |$)/ {
print "memory: " FILENAME ": heading dialect \"" \
substr($0, RLENGTH + 1, 3) "\": not upgraded"; bad = 1; exit }
END { exit bad ? 2 : 0 }' "$1" >&2
}
_mem_upgrade_file() { # <file> → rc 0 upgraded or already v2, rc 2 refused
local p rows new rc=0
_mem_upgrade_ready "$1"; rc=$?
[ "$rc" = 1 ] && return 0
[ "$rc" = 0 ] || return 2
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; }
@@ -447,7 +557,7 @@ _mem_upgrade_file() { # <file> → rc 0 upgraded or already v2, rc 2 refused
memory_upgrade() { # [<memory-dir>] → every template-born registry to v2
local dir="${1:-.claude/memory}" f rc=0
for f in $_MEM_REGISTRIES; do
for f in $(_mem_names); do
[ -f "$dir/$f.md" ] || continue
_mem_upgrade_file "$dir/$f.md" || rc=2
done
@@ -5,7 +5,7 @@
# real check on this repo's registries.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
MEM="${MEM_UNDER_TEST:-$ROOT/lib/memory.sh}"
MEM="$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; }
@@ -59,6 +59,9 @@ 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
printf 'x\n```\nopen fence\n' > fence.md
bash "$MEM" add learning --title f --body-file fence.md 2>/dev/null
check T2e-open-fence-body "$?" 2
# T3 status: a dated line ends the entry, before the next heading's blank
bash "$MEM" status BLK-001 'resolved abc1234'
@@ -72,6 +75,11 @@ 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
bash "$MEM" status BLK-001 'reopened by abc' 2>/dev/null
check T3g-needs-status-word "$?" 2
bash "$MEM" status BLK-002 'open \b \n \| kept'
check T3h-backslash-verbatim "$(tail -1 "$B")" \
'- **Status (2026-10-27)**: open \b \n \| kept'
# T4 journal: appended under today, heading created once, old date untouched
J=.claude/memory/journal.md
@@ -82,6 +90,8 @@ 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
bash "$MEM" journal 'grep \bword\b w/ \n'
check T4e-backslash-verbatim "$(tail -1 "$J")" '- grep \bword\b w/ \n'
# T5 --supersedes: forward link on the new entry, status line on the old one
L=.claude/memory/learnings.md
@@ -134,6 +144,21 @@ 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
printf '\n## BDR-006 — fenced\n```\nx\n' >> .claude/memory/decisions.md
err=$(bash "$MEM" check 2>&1 >/dev/null); rc=$?
check T7g-open-fence-rc "$rc" 2
check T7h-open-fence-named "$(printf '%s\n' "$err" | grep -c 'fence open at end')" 1
cat d.bak > .claude/memory/decisions.md
# a duplicate a merge left behind blocks neither add nor a staged append
printf '\n## BDR-005 — merged twice (2026-10-27)\nx\n' >> .claude/memory/decisions.md
check T7i-dup-still-adds "$(bash "$MEM" add decision --title after --body-file plain.md)" BDR-006
check T7j-dup-still-reported "$(bash "$MEM" check >/dev/null 2>&1; echo $?)" 2
git add -A && git commit -qm dup
bash "$MEM" add decision --title later --body-file plain.md >/dev/null
git add .claude/memory/decisions.md
check T7k-dup-staged-append "$(bash "$MEM" check --staged >/dev/null 2>&1; echo $?)" 0
git reset -q
cat d.bak > .claude/memory/decisions.md
# T8 check --staged: an append passes, a removed entry line is rc 2
git add -A && git commit -qm base
@@ -148,6 +173,12 @@ 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"
cp "$B" b.keep
sed '/^format: 2$/d' b.keep > "$B" && git add "$B"
check T8d-downgrade-refused "$(bash "$MEM" check --staged >/dev/null 2>&1; echo $?)" 2
git rm -q --cached "$B"
check T8e-deletion-refused "$(bash "$MEM" check --staged >/dev/null 2>&1; echo $?)" 2
git reset -q && cat b.keep > "$B"
# T9 upgrade: Index-only dates and statuses become body lines, the marker
# lands, the Index goes, headings untouched; idempotent; refusals keep the file
@@ -168,6 +199,7 @@ entry_prefix: BDR
| 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-005 | 2026-01-05 | suffix date | accepted |
---
@@ -183,6 +215,9 @@ entry_prefix: BDR
## BDR-004 — no status
body
## BDR-005 — suffix date — 2026-01-05
- **Status**: accepted
EOF
cat > .claude/memory/learnings.md <<'EOF'
---
@@ -207,13 +242,17 @@ y
EOF
D=.claude/memory/decisions.md
heads=$(grep '^## BDR-' "$D")
bash "$MEM" upgrade >/dev/null 2>&1
check T9-rc "$?" 0
err=$(bash "$MEM" upgrade 2>&1 >/dev/null); rc=$?
check T9-rc "$rc" 0
check T9n-dropped-named "$(printf '%s\n' "$err" | grep -c '^memory: BDR-002: kept body shipped, dropped Index accepted$')" 1
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 |#'
for loc in C en_US.UTF-8; do
check "T9r-suffix-date-$loc" "$(LC_ALL=$loc bash "$MEM" index decision | grep -c '^| BDR-005 | 2026-01-05 | suffix date | accepted |$')" 1
done
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
@@ -245,6 +284,15 @@ printf '# Evals\n\n## EVAL-001 | 2026 | pipe dialect\n' > .claude/memory/evals.m
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'
printf -- '---\ntype: evals_registry\nentry_prefix: EVAL\n---\n\n## Index\n\n| ID | Date | Output | Action |\n|----|------|--------|--------|\n\n## EVAL-001 - hyphen dialect\nx\n' \
> .claude/memory/evals.md
err=$(bash "$MEM" upgrade 2>&1 >/dev/null)
check T9o-hyphen-refused "$(printf '%s\n' "$err" | grep -c 'heading dialect " - ": not upgraded')" 1
printf -- '---\ntype: evals_registry\nentry_prefix: EVAL\n---\n\n## Index\n\n| ID | Date | Output | Action |\n|----|------|--------|--------|\n\n## EVAL-001 — empty index (2026-04-01)\nx\n' \
> .claude/memory/evals.md
bash "$MEM" upgrade >/dev/null 2>&1
check T9p-empty-index-upgraded "$(sed -n 2p .claude/memory/evals.md)" 'format: 2'
check T9q-empty-index-heading "$(grep -c '^## EVAL-001 — empty index' .claude/memory/evals.md)" 1
cd "$FIX" || exit 1
# T10 parser: header tag and labelled lines only, last wins, open ranks last
@@ -255,6 +303,22 @@ 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
check T10h-title-prose-ignored "$(word st.md BLK-043)" open
check T10i-dated-lead-word "$(word st.md BLK-044)" open
# shellcheck source=/dev/null
check T10j-tag-only "$(. "$MEM"; memory_entry_status st.md BLK-043)" '[open]'
closed() { # <word> → yes when memory_closed accepts it
# shellcheck source=/dev/null
(. "$MEM"; memory_closed "$1") && echo yes || echo no; }
check T10k-closed "$(closed resolved)$(closed superseded)$(closed deprecated)" yesyesyes
check T10l-not-closed "$(closed accepted)$(closed open)$(closed upstream)" nonono
mkdir -p v1h/.claude/memory
printf '# Blockers\n\n## BLK-001 - hyphen\n- **Status**: resolved\n\n## BLK-002 | 2026-05-18 | pipe\nStatus: open\n' \
> v1h/.claude/memory/blockers.md
check T10m-hyphen-dialect "$(word v1h/.claude/memory/blockers.md BLK-001)" resolved
check T10n-pipe-dialect "$(word v1h/.claude/memory/blockers.md BLK-002)" open
bash "$MEM" -C v1h status BLK-002 'resolved by abc' 2>/dev/null
check T10o-status-on-v1-pipe "$(word v1h/.claude/memory/blockers.md BLK-002)" resolved
# shellcheck source=/dev/null
(. "$MEM"; memory_entry_status st.md BLK-042) >/dev/null
check T10g-no-candidate-rc "$?" 1