fix(handover): read blocker statuses through the shared reader

STEP 9 parsed blocker statuses by hand from a cwd-relative dir, so §5
could list closed blockers or drop open ones (BLK-032..034 class).
New reconcile_blk_classify (strict v2, single-word v1, never the Index)
rooted on the PACKAGE root; unreadable entries are flagged via a
mandatory SYNTH REPORT MEMORY line relayed to the user.
This commit is contained in:
bchanot committed 2026-11-11 02:28:53 +01:00
1 parent ab7cada20b
commit 93a8e19c66
4 files changed
+177 -7

No files matched your search

+12 -1
View File
@@ -1150,7 +1150,12 @@ PACKAGE:
Parse its `SYNTH REPORT`: `STATUS: BLOCKED` → surface verbatim, stop (do
not patch the PACKAGE silently); malformed/mute → retry ONCE fresh, then
escalate. `STATUS: DONE` → THEN render:
escalate. `STATUS: DONE` with no `MEMORY:` line is malformed (same
retry-once path); so is `MEMORY: no blockers file` or `MEMORY: reader
unavailable` while `<root>/.claude/memory/blockers.md` exists (a
mis-parsed root or a broken lib, never a quiet empty §5). Any `MEMORY:`
value other than `unreadable BLK: none` is printed to the user before
the render and repeated in 9.7. `STATUS: DONE` → THEN render:
```
Agent(subagent_type="handover-doc-writer")
@@ -1190,6 +1195,12 @@ Parse the returned `HANDOVER-DOC REPORT`:
markers left in NAP, deploy chapter included/skipped).
Re-run PUSH STATE READ right before printing, then add the bullet:
- Push: <state>
When the synthesize `MEMORY:` value was not `unreadable BLK: none`,
add the bullet:
- Memory: <value>
For unreadable IDs, give the remedy: `bash ~/.claude/lib/memory.sh -C
<root> status <ID> "<word>, …"` (a status word, e.g. resolved or
open), then re-run.
- `STATUS: BLOCKED` → surface the report verbatim (including which
PACKAGE field the doc-writer flagged) and stop — do not retry or
patch the PACKAGE silently. Re-run PUSH STATE READ and add the same
+32 -6
View File
@@ -54,8 +54,7 @@ The parent dispatches this agent TWICE, with the FULL PACKAGE both times
the chapters (§1-§6 full, §7/§8 stubs) into the RUN-SCOPED DRAFT
`.audit/handover-draft-<RUNID>.md`, ending the file with the line
`DRAFT COMPLETE — RUNID: <RUNID>`. Then emits a `SYNTH REPORT`
(`STATUS: DONE | BLOCKED`, RUNID, phase-cluster count, per-chapter word
counts) and STOPS — STEP 13-16, the final MD, HTML and PDF are NEVER
(template below, `MEMORY:` line mandatory on DONE) and STOPS — STEP 13-16, the final MD, HTML and PDF are NEVER
this mode's job.
- **`MODE: render`** — runs on its sonnet row (frontmatter = off-state floor). FIRST loads the
draft: absent file, RUNID mismatch, or missing `DRAFT COMPLETE` sentinel
@@ -65,21 +64,48 @@ The parent dispatches this agent TWICE, with the FULL PACKAGE both times
REPORT`. `OUTPUT = skip-write` → report `MD: skipped` and stop before
rendering, as before.
The synthesize mode ends with:
```
SYNTH REPORT
STATUS: DONE | BLOCKED
RUNID: <RUNID>
PHASE CLUSTERS: <n>
WORDS: §1=<n> §2=<n> §3=<n> §4=<n> §5=<n> §6=<n>
MEMORY: unreadable BLK: <IDs comma-separated | none> | no blockers file | reader unavailable
```
---
## STEP 9 — LOAD MEMORY REGISTRIES
```bash
MEMORY_DIR=".claude/memory"
ROOT="<PROJECT root from the PACKAGE>"
MEMORY_DIR="$ROOT/.claude/memory"
test -d "$MEMORY_DIR" || MEMORY_DIR=""
# Blocker statuses through the shared reader (BDR-129): never parsed by hand.
B="$MEMORY_DIR/blockers.md"
if [ -z "$MEMORY_DIR" ] || [ ! -f "$B" ]; then echo "blockers: no-file"
elif . "$HOME/.claude/lib/reconcile.sh"; then reconcile_blk_classify "$B"
else echo "blockers: reader-unavailable"; fi
```
If memory dir exists, read each file (full contents, parse manually):
Rows `ID<TAB>open<TAB>word` are the open blockers for §5. Rows
`ID<TAB>unreadable<TAB>…` are kept out of §5; their IDs go on the
SYNTH REPORT `MEMORY:` line. `blockers: no-file` → no blocker in §5,
`MEMORY: no blockers file`. `blockers: reader-unavailable` → no blocker
in §5, `MEMORY: reader unavailable`.
If memory dir exists, read each file in full for the narrative fields
(titles, decisions, why, alternatives, cause, solution, journal
summaries). A blocker's status is never taken from the file's prose,
only from the reader above:
- `decisions.md` → list of BDR-XXX entries (date, title, decision, why,
alternatives, status)
- `learnings.md` → LRN-XXX entries
- `blockers.md` → BLK-XXX entries (open vs resolved)
- `blockers.md` → BLK-XXX entries: open/unreadable from the reader
above, narrative from the file
- `journal.md` → date headings + 3-5 line session summaries
- `evals.md` → EVAL-XXX entries
@@ -315,7 +341,7 @@ End with two callouts:
[Action-only checklist for the client. Pull from:
**`.claude/audits/HUMAN-ACTIONS.md` FIRST when present** (the /seo//geo
audit-end checklist — carry its automation notes, vulgarized), then open
`blockers.md` entries, ongoing-monitoring items, external platforms to
blockers from STEP 9 (unreadable ones excluded), ongoing-monitoring items, external platforms to
claim, content updates only the client can make, deploy steps if
self-hosted. If any axis passed via the code-ceiling rule, its
unlocking user actions appear HERE with their expected score gain
+28
View File
@@ -31,6 +31,8 @@
# parser on v2, legacy lexical reader on v1
# reconcile_blk_open — blockers whose CURRENT status is not closed
# (resolved | superseded | deprecated on v2)
# reconcile_blk_classify — blockers for a client deliverable: open
# (word) | unreadable, closed omitted
# reconcile_verdict — pure kernel: declared checkbox × real fact
# → verdict
# reconcile_deferrals — lexical deferral sweep (honest limit)
@@ -105,6 +107,32 @@ reconcile_blk_open() {
printf '%s\t%s\n' "$id" "$st"
done
}
# blockers for a client deliverable → "id<TAB>open|unreadable<TAB>word or
# line"; closed ones are omitted. A status no reader maps to exactly one
# known word is unreadable, never open (BDR-129, BDR-133): v2 strict word,
# v1 the single word of a status/statut label (_mem_v1_word: prose, mixed
# or negated lines give none). Entries under a heading the enumerator
# cannot see (`### BLK-`) are unreadable too.
reconcile_blk_classify() {
local id st w v2=""
memory_is_v2 "$1" && v2=1
for id in $(reconcile_enumerate_ids "$1" BLK); do
st=$(reconcile_blk_current_status "$1" "$id")
if [ -n "$v2" ]; then w=$(memory_status_word "$st")
else w=$(_mem_v1_word "$st"); fi
[ -n "$st" ] || w=""
memory_closed "$w" && continue
case " $_MEM_WORDS " in
*" $w "*)
[ -n "$w" ] && { printf '%s\topen\t%s\n' "$id" "$w"; continue; } ;;
esac
printf '%s\tunreadable\t%s\n' "$id" "${st:0:80}"
done
MEM_GREP="$RECONCILE_GREP" _mem_heading_ids "$1" BLK | sort -u \
| comm -23 - <(reconcile_enumerate_ids "$1" BLK) \
| while read -r id; do printf '%s\tunreadable\theading level\n' "$id"; done
return 0
}
# --- pure reconciliation kernel: declared checkbox × real fact → verdict
# (no git, fully testable) ---
+105
View File
@@ -0,0 +1,105 @@
#!/usr/bin/env bash
# lib/tests/handover-memory-contract.test.sh — handover-doc-writer STEP 9
# reads blocker statuses through reconcile_blk_classify, never by hand
# (BDR-129, BDR-133; BUGS-FOUND G5). HM1/HM2 census the prompts, HM3 runs
# the SHIPPED STEP 9 block on printf-built fixtures under one mktemp -d.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
HDW="$ROOT/agents/handover-doc-writer.md"
CHW="$ROOT/agents/client-handover-writer.md"
WORK="$(mktemp -d)" || exit 1; trap 'rm -rf "$WORK"' EXIT
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; }
# has <file> <fixed string>: 1 when the file contains it, else 0
has() { if grep -qF -- "$2" "$1"; then echo 1; else echo 0; fi; }
# --- HM1: handover-doc-writer census
check HM1-classify "$(has "$HDW" 'reconcile_blk_classify')" 1
check HM1-memory-line "$(has "$HDW" 'MEMORY: unreadable BLK:')" 1
check HM1-reader-unavailable "$(has "$HDW" 'reader-unavailable')" 1
check HM1-synth-fence "$(grep -c '^SYNTH REPORT$' "$HDW")" 1
check HM1-no-manual "$(has "$HDW" 'parse manually')" 0
check HM1-no-relative "$(has "$HDW" 'MEMORY_DIR=".claude/memory"')" 0
check HM1-no-bash-c "$(has "$HDW" 'bash -c')" 0
# --- HM2: client-handover-writer census
check HM2-memory-parse "$(has "$CHW" 'with no `MEMORY:` line is malformed')" 1
check HM2-report-bullet "$(has "$CHW" '- Memory: <value>')" 1
check HM2-remedy "$(has "$CHW" 'memory.sh -C')" 1
# --- HM3: run the shipped STEP 9 block
# first fenced bash block under `## STEP 9`, with the two placeholders
# (project root, lib dir) substituted
mkscript() { # <project root> <lib dir> <out file>
awk '/^## STEP 9/ {s=1; next} s && /^## / {exit}
s && /^```bash/ {b=1; next} b && /^```/ {exit} b' "$HDW" \
| sed -e "s|<PROJECT root from the PACKAGE>|$1|" \
-e "s|\$HOME/\.claude/lib|$2|" >"$3"
}
run_step9() { mkscript "$1" "$2" "$WORK/step9.sh"; bash "$WORK/step9.sh" 2>&1; }
# row <out> <id>: the row of one blocker, empty when absent
row() { printf '%s\n' "$1" | grep "^$2 " || true; }
TAB="$(printf '\t')"
# fixture <name> <body, \n escapes>: a project root with blockers.md
fixture() {
mkdir -p "$WORK/$1/.claude/memory" || exit 1
printf '%b' "$2" >"$WORK/$1/.claude/memory/blockers.md" || exit 1
}
LIB="$ROOT/lib"
# (a) v1: no `format: 2`; the Index claims open, the body decides
V1='# Blockers\n\n## Index\n| ID | Status |\n|---|---|\n| BLK-001 | open |\n\n'
V1+='## BLK-001 — a\n- **Statut** : resolved\n\n'
V1+='## BLK-002 — b\n- **Statut** : upstream\n\n'
V1+='## BLK-003 — c\n- **Status**: superseded by BLK-002\n\n'
V1+='## BLK-004 — d\nno status here\n\n'
V1+='## BLK-005 — e\n- **Status**: closed\n\n'
V1+='## BLK-006 — f\n- **Statut** : upstream (superseded by #42)\n\n'
V1+='## BLK-007 — g\n- **Statut** : open (not resolved)\n\n'
V1+='## BLK-008 — h\n- **Statut** : unresolved\n\n'
V1+='## BLK-010 — i\n- **Status**: open\n\n'
V1+='### BLK-009 — j\n- **Status**: open\n'
fixture v1 "$V1"
out=$(run_step9 "$WORK/v1" "$LIB")
check HM3a-resolved-absent "$(row "$out" BLK-001)" ""
check HM3a-upstream "$(row "$out" BLK-002)" "BLK-002${TAB}open${TAB}upstream"
check HM3a-superseded-absent "$(row "$out" BLK-003)" ""
check HM3a-no-status "$(row "$out" BLK-004 | cut -f1,2)" \
"BLK-004${TAB}unreadable"
check HM3a-closed-word "$(row "$out" BLK-005 | cut -f1,2)" \
"BLK-005${TAB}unreadable"
check HM3a-mixed "$(row "$out" BLK-006 | cut -f1,2)" \
"BLK-006${TAB}unreadable"
check HM3a-negated "$(row "$out" BLK-007)" "BLK-007${TAB}open${TAB}open"
check HM3a-unresolved "$(row "$out" BLK-008 | cut -f1,2)" \
"BLK-008${TAB}unreadable"
check HM3a-open "$(row "$out" BLK-010)" "BLK-010${TAB}open${TAB}open"
check HM3a-heading-level "$(row "$out" BLK-009)" \
"BLK-009${TAB}unreadable${TAB}heading level"
# (b) v2: the heading tag or a labelled line decides, never Solution prose
V2='---\nformat: 2\n---\n# Blockers\n\n'
V2+='## BLK-001 — t [open]\n- **Solution**: resolved the issue partially\n\n'
V2+='## BLK-002 — u [open]\n- **Status (2026-11-01)**: resolved\n\n'
V2+='## BLK-003 — v [upstream]\n\n'
V2+='## BLK-004 — w\nplain prose, no status\n'
fixture v2 "$V2"
out=$(run_step9 "$WORK/v2" "$LIB")
check HM3b-open "$(row "$out" BLK-001)" "BLK-001${TAB}open${TAB}open"
check HM3b-resolved-absent "$(row "$out" BLK-002)" ""
check HM3b-upstream "$(row "$out" BLK-003)" "BLK-003${TAB}open${TAB}upstream"
check HM3b-no-status "$(row "$out" BLK-004 | cut -f1,2)" \
"BLK-004${TAB}unreadable"
# (c) no blockers.md
mkdir -p "$WORK/none/.claude/memory" || exit 1
check HM3c-no-file "$(run_step9 "$WORK/none" "$LIB")" "blockers: no-file"
# (d) lib dir without reconcile.sh
mkdir -p "$WORK/emptylib" || exit 1
check HM3d-reader-unavailable "$(run_step9 "$WORK/v2" "$WORK/emptylib" \
| tail -1)" "blockers: reader-unavailable"
printf 'handover-memory-contract: %d passed, %d failed\n' "$pass" "$fail"
[ "$fail" -eq 0 ] || exit 1