From 93a8e19c66833f80395e132060c176073ded7e07 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 11 Nov 2026 02:28:53 +0100 Subject: [PATCH] fix(handover): read blocker statuses through the shared reader MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- agents/client-handover-writer.md | 13 ++- agents/handover-doc-writer.md | 38 ++++++-- lib/reconcile.sh | 28 ++++++ lib/tests/handover-memory-contract.test.sh | 105 +++++++++++++++++++++ 4 files changed, 177 insertions(+), 7 deletions(-) create mode 100644 lib/tests/handover-memory-contract.test.sh diff --git a/agents/client-handover-writer.md b/agents/client-handover-writer.md index b4d84ce..ff81579 100644 --- a/agents/client-handover-writer.md +++ b/agents/client-handover-writer.md @@ -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 `/.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: + When the synthesize `MEMORY:` value was not `unreadable BLK: none`, + add the bullet: + - Memory: + For unreadable IDs, give the remedy: `bash ~/.claude/lib/memory.sh -C + status ", …"` (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 diff --git a/agents/handover-doc-writer.md b/agents/handover-doc-writer.md index 2c981d0..baf2714 100644 --- a/agents/handover-doc-writer.md +++ b/agents/handover-doc-writer.md @@ -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-.md`, ending the file with the line `DRAFT COMPLETE — 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: +PHASE CLUSTERS: +WORDS: §1= §2= §3= §4= §5= §6= +MEMORY: unreadable BLK: | no blockers file | reader unavailable +``` + --- ## STEP 9 — LOAD MEMORY REGISTRIES ```bash -MEMORY_DIR=".claude/memory" +ROOT="" +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 `IDopenword` are the open blockers for §5. Rows +`IDunreadable…` 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 diff --git a/lib/reconcile.sh b/lib/reconcile.sh index 383cf36..47c88df 100644 --- a/lib/reconcile.sh +++ b/lib/reconcile.sh @@ -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 → "idopen|unreadableword 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) --- diff --git a/lib/tests/handover-memory-contract.test.sh b/lib/tests/handover-memory-contract.test.sh new file mode 100644 index 0000000..4317393 --- /dev/null +++ b/lib/tests/handover-memory-contract.test.sh @@ -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 : 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: ')" 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() { # + awk '/^## STEP 9/ {s=1; next} s && /^## / {exit} + s && /^```bash/ {b=1; next} b && /^```/ {exit} b' "$HDW" \ + | sed -e "s||$1|" \ + -e "s|\$HOME/\.claude/lib|$2|" >"$3" +} +run_step9() { mkscript "$1" "$2" "$WORK/step9.sh"; bash "$WORK/step9.sh" 2>&1; } +# row : the row of one blocker, empty when absent +row() { printf '%s\n' "$1" | grep "^$2 " || true; } +TAB="$(printf '\t')" +# fixture : 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