@windyroad/architect 0.20.3 → 0.20.4

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.20.3"
+  "version": "0.20.4"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-architect",
-  "version": "0.20.3",
+  "version": "0.20.4",
   "description": "Architecture decision enforcement for AI coding agents",
   "author": {
     "name": "Windy Road Technology",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.20.3",
+  "version": "0.20.4",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"
@@ -33,6 +33,10 @@
     ".codex-plugin/",
     "lib/",
     "!skills/*/eval/",
-    "!agents/eval/"
+    "!agents/eval/",
+    "!agents/test/",
+    "!hooks/test/",
+    "!scripts/test/",
+    "!skills/*/test/"
   ]
 }

package/agents/test/architect-codex-eval-contract.bats

@@ -1,33 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
-  EVAL_DIR="$REPO_ROOT/packages/architect/agents/eval"
-}
-
-@test "architect Codex agent eval covers required verdict classes" {
-  [ -f "$EVAL_DIR/promptfooconfig.codex.yaml" ]
-  run grep -n "PASS" "$EVAL_DIR/promptfooconfig.codex.yaml"
-  [ "$status" -eq 0 ]
-  run grep -n "ISSUES FOUND" "$EVAL_DIR/promptfooconfig.codex.yaml"
-  [ "$status" -eq 0 ]
-  run grep -n "NEEDS DIRECTION" "$EVAL_DIR/promptfooconfig.codex.yaml"
-  [ "$status" -eq 0 ]
-  run grep -n "Unratified Dependency" "$EVAL_DIR/promptfooconfig.codex.yaml"
-  [ "$status" -eq 0 ]
-}
-
-@test "architect Codex agent eval runner uses packed install and exact custom agent" {
-  run grep -n 'npm pack' "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-  run grep -n 'windyroad-architect --runtime codex --scope user' "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-  run grep -n "codex exec" "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-  run grep -n 'agents/wr-architect-agent.toml' "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-  run grep -n 'wr-architect:agent' "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-  run grep -n 'git -C "$TMP_REPO" init' "$EVAL_DIR/run-codex-agent-eval.sh"
-  [ "$status" -eq 0 ]
-}

package/agents/test/architect-needs-direction-verdict.bats

@@ -1,64 +0,0 @@
-#!/usr/bin/env bats
-# Doc-lint guard: architect agent.md must carry the NEEDS DIRECTION verdict
-# type (ADR-064) so the architect names the question + viable options for an
-# unpinned 2+-option decision instead of auto-picking or prose-asking, and the
-# main agent translates it into an AskUserQuestion.
-#
-# tdd-review: structural-permitted (justification: P176 — agent behaviour is
-# prompt-driven with no skill-invocation harness to exercise the verdict
-# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
-# Permitted Exception — ADR-052 narrows ADR-005 to exclude prose-doc greps).
-# When P176 lands, upgrade to a behavioural test per ADR-064 Confirmation item 2.
-#
-# Cross-reference:
-#   P283 (architect should AskUserQuestion when recording a new decision)
-#   ADR-064 (Architect Needs-Direction verdict; main agent owns the AskUserQuestion)
-#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
-#   @jtbd JTBD-001 (enforce governance without slowing down)
-
-setup() {
-  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  AGENT_FILE="${AGENT_DIR}/agent.md"
-}
-
-@test "agent.md carries a NEEDS DIRECTION report verdict (ADR-064)" {
-  run grep -n "Architecture Review: NEEDS DIRECTION" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md lists [Needs Direction] as an issue/verdict type" {
-  run grep -n "\[Needs Direction\]" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md has a 'When to emit Needs Direction' section citing ADR-064" {
-  run grep -n "When to emit Needs Direction" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  run grep -n "ADR-064" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md requires the main agent to translate the verdict into AskUserQuestion (not prose)" {
-  run grep -n "AskUserQuestion" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md guards the negative bound: do NOT emit Needs Direction on obvious/single-option choices" {
-  # inverse-P078 over-ask guard — the verdict must not fire when only one viable option exists
-  run grep -niE "Do NOT emit Needs Direction.*(obvious|one-viable|only-one)" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md requires Needs-Direction to name the SUBSTANCE not the grain (ADR-074)" {
-  # ADR-074 surface 1: the verdict must name the substantive choice, not a
-  # meta/grain framing question (e.g. "one ADR or two?"). Closes the P315 vector.
-  run grep -niE "Name the SUBSTANCE, not the grain" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  run grep -n "ADR-074" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md performance-review section cites ADR-026 as parent (ADR-026 Confirmation item 1)" {
-  run grep -nE "Runtime-Path Performance Review \(per ADR-026" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}

package/agents/test/architect-output-formatting.bats

@@ -1,26 +0,0 @@
-#!/usr/bin/env bats
-# Doc-lint guard: architect agent.md must include the output formatting rule
-# requiring human-readable titles alongside bare IDs (P032).
-#
-# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
-#
-# Cross-reference:
-#   P032 (agent output uses opaque IDs without titles)
-#   @jtbd JTBD-001 (enforce governance without slowing down)
-
-setup() {
-  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  AGENT_FILE="${AGENT_DIR}/agent.md"
-}
-
-@test "agent.md contains output formatting section" {
-  run grep -n "## Output Formatting" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md output formatting rule requires titles with IDs (P032)" {
-  run grep -n "title" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  run grep -n "Output Formatting" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}

package/agents/test/architect-performance-review.bats

@@ -1,76 +0,0 @@
-#!/usr/bin/env bats
-# Doc-lint guard: architect agent.md must include the runtime-path
-# performance-review step per ADR-023 (wr-architect agent performance
-# review scope). Closes P046 (wr-architect agent misses performance
-# implications on high-traffic endpoints).
-#
-# Structural assertion — Permitted Exception to the source-grep ban
-# (ADR-005 / P011).
-#
-# Cross-reference:
-#   P046 (wr-architect agent misses per-request performance implications)
-#   ADR-023 (wr-architect agent performance review scope)
-#   @jtbd JTBD-002 (ship with confidence)
-#   @jtbd JTBD-101 (extend the suite with clear patterns)
-
-setup() {
-  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  AGENT_FILE="${AGENT_DIR}/agent.md"
-}
-
-@test "agent.md contains a runtime-path performance review section (ADR-023)" {
-  run grep -nE "[Pp]erformance [Rr]eview|[Rr]untime-[Pp]ath" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md lists the runtime-path trigger categories (cache / throttle / rate-limit / per-request handler)" {
-  # Cache directives
-  run grep -niE "cache-control|etag|last-modified" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  # Rate limiting / throttle
-  run grep -niE "rate[- ]limit|throttl|quota" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  # Per-request handler
-  run grep -niE "per-request|per request handler" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md requires quantification: per-request cost delta (ADR-023 Confirmation criterion 2a)" {
-  run grep -niE "per-request cost delta|cost delta per request" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md requires request-frequency estimate with cited source (ADR-023)" {
-  run grep -niE "[Rr]equest[- ][Ff]requency" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  # Must require citing a source (ADR/JTBD/telemetry/worst-case)
-  run grep -niE "cite|source" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md requires product (cost x frequency) computation" {
-  run grep -niE "(cost.*frequency|frequency.*cost|aggregate load|product)" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md bans qualitative-only performance claims (ADR-023 Confirmation criterion 2b)" {
-  # The prompt must forbid phrases like "load is negligible", "microseconds only"
-  run grep -niE "(must not|MUST NOT).*(qualitative|negligible|microsecond)" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md references performance-budget ADR convention by name (ADR-023 Confirmation criterion 2c)" {
-  run grep -niE "performance[- ]budget" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md instructs a verdict against any in-scope performance-budget ADR" {
-  # Must describe what to do when a budget is present vs missing
-  run grep -niE "verdict|recommend creating|no performance budget" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md cross-references ADR-023 so readers can trace the rule's origin" {
-  run grep -n "ADR-023" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}

package/agents/test/architect-pre-edit-review-mode.bats

@@ -1,50 +0,0 @@
-#!/usr/bin/env bats
-# Doc-lint guard: architect agent.md must carry an explicit pre-edit /
-# proposed-change review-mode carve-out so the agent classifies alignment
-# of the PROPOSAL when the calling prompt describes a not-yet-applied
-# change, instead of mis-classifying not-yet-applied state as ISSUES FOUND
-# (P313 catch-22: gate blocks edits; reviewer wants edits done first).
-#
-# tdd-review: structural-permitted (justification: P176 — agent behaviour is
-# prompt-driven with no skill-invocation harness to exercise the verdict
-# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
-# Permitted Exception — ADR-052 narrows ADR-005 to exclude prose-doc greps).
-# When P176 lands, upgrade to a behavioural test that feeds the agent a
-# pre-edit proposal and asserts the PASS verdict.
-#
-# Cross-reference:
-#   P313 (Pre-edit governance-gate catch-22 — pass withheld pending edits)
-#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
-#   @jtbd JTBD-001 (Enforce Governance Without Slowing Down — preserves the
-#                   under-60-second review outcome by removing the redundant
-#                   re-delegation the catch-22 currently forces)
-
-setup() {
-  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  AGENT_FILE="${AGENT_DIR}/agent.md"
-}
-
-@test "agent.md carries a Review Mode section distinguishing pre-edit from post-edit (P313)" {
-  run grep -nE "^## Review Mode: Pre-edit / proposed-change vs\. Post-edit / applied" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md classifies alignment of the PROPOSAL in pre-edit mode (P313 verbatim core sentence)" {
-  run grep -nE "classify alignment of the PROPOSAL itself" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md treats not-yet-applied state as the EXPECTED baseline of a pre-edit gate (P313)" {
-  run grep -nE "EXPECTED baseline of a pre-edit gate" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md explicitly rejects 'edits aren't applied yet' as a valid ISSUES FOUND substance (P313)" {
-  run grep -nE "Do NOT treat .edits aren't applied yet" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md cites P313 as the catch-22 closure (audit-trail)" {
-  run grep -nE "P313" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}

package/agents/test/architect-unratified-dependency-verdict.bats

@@ -1,55 +0,0 @@
-#!/usr/bin/env bats
-# Doc-lint guard: architect agent.md must carry the [Unratified Dependency]
-# verdict (ADR-074 enforcement surface 3 / RFC-010 / P318) — flag a change or
-# plan that explicitly cites/implements an ADR lacking `human-oversight:
-# confirmed` (unratified, non-superseded), keyed on the oversight marker NOT
-# `status:`. Closes the residual P315 foreground gap at the architect-review
-# surface (the ITIL propose-fix surface is covered by RFC-008).
-#
-# tdd-review: structural-permitted (justification: P176 — agent behaviour is
-# prompt-driven with no skill-invocation harness to exercise the verdict
-# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
-# Permitted Exception). When P176 lands, upgrade to a behavioural test that
-# feeds the agent a change citing an unratified ADR and asserts the verdict.
-#
-# Cross-reference:
-#   ADR-074 (Confirm a decision's substance before building dependent work — surface 3)
-#   ADR-066 (oversight marker; orthogonal status/oversight axes; the "unconfirmed" definition)
-#   RFC-010 / P318 (this enforcement surface)
-#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
-#   @jtbd JTBD-002 (ship with confidence) / JTBD-001 (enforce governance without slowing down)
-
-setup() {
-  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  AGENT_FILE="${AGENT_DIR}/agent.md"
-}
-
-@test "agent.md lists [Unratified Dependency] as an issue/verdict type (ADR-074 surface 3)" {
-  run grep -n '\[Unratified Dependency\]' "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md has a 'When to flag [Unratified Dependency]' section citing ADR-074" {
-  run grep -niE "When to flag \[Unratified Dependency\]" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  run grep -n "ADR-074" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md keys the flag on the oversight marker, NOT on status (orthogonal axes)" {
-  # ADR-066 / user correction 2026-05-27: building on a ratified-but-proposed ADR is fine.
-  run grep -niE "NEVER on .?status|not .?\`?status|orthogonal" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md scopes the marker check to frontmatter + skips superseded (mirrors is-decision-unconfirmed.sh)" {
-  run grep -niE "frontmatter" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-  run grep -niE "superseded" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}
-
-@test "agent.md guards against over-firing on transitive/ambient dependence (inverse-P078)" {
-  run grep -niE "explicit(ly)? cite|over-?(fire|scan)|transitive" "$AGENT_FILE"
-  [ "$status" -eq 0 ]
-}

package/hooks/test/architect-compendium-update-entry.bats

@@ -1,299 +0,0 @@
-#!/usr/bin/env bats
-
-# Behavioural tests for architect-compendium-update-entry.sh (RFC-014 Story A,
-# ADR-078 Phase 1 / Option 9). Exercises the hook against fixture compendium
-# trees; asserts on its side-effects (README mutation, staging, exit code) and
-# stderr signals — never on hook source content (feedback_behavioural_tests).
-#
-# The `claude -p` subprocess is stubbed with a PATH-priority fake-claude shim
-# (RFC-014 SQ-014-1) that emits a fixed-shape `{"result": "<entry>"}` envelope
-# for whichever ADR-ID appears in the prompt. Real-subprocess integration is
-# out of scope for Phase 1.
-
-setup() {
-  HOOK="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/architect-compendium-update-entry.sh"
-  PROJ="$(mktemp -d)"
-  mkdir -p "$PROJ/docs/decisions"
-  ( cd "$PROJ" && git init -q && git config user.email t@e.x && git config user.name t )
-
-  # PATH-priority fake-claude shim: emits a {"result": "<entry>"} envelope with
-  # an entry block for the ADR-ID found in the prompt. Marker text STUBBED-<id>
-  # makes the emitted Decides line assertable.
-  SHIMDIR="$(mktemp -d)"
-  cat > "$SHIMDIR/claude" <<'SHIM'
-#!/usr/bin/env bash
-prompt=$(cat)
-id=$(printf '%s' "$prompt" | grep -oE 'ADR-[0-9]+' | head -1 | sed 's/ADR-//')
-entry="### ADR-${id} — Stub Title
-**Status:** proposed | **Oversight:** confirmed
-**Decides:** STUBBED-${id} decision body.
-**Confirmation:** stub crit a; stub crit b
-**Related:** ADR-001"
-jq -cn --arg r "$entry" '{result:$r}'
-SHIM
-  chmod +x "$SHIMDIR/claude"
-
-  # Failing shim variant: exits non-zero, emits nothing (degraded-mode tests).
-  FAILSHIMDIR="$(mktemp -d)"
-  cat > "$FAILSHIMDIR/claude" <<'SHIM'
-#!/usr/bin/env bash
-cat >/dev/null
-exit 7
-SHIM
-  chmod +x "$FAILSHIMDIR/claude"
-
-  ORIG_PATH="$PATH"
-  export PATH="$SHIMDIR:$PATH"
-}
-
-teardown() {
-  export PATH="$ORIG_PATH"
-  rm -rf "$PROJ" "$SHIMDIR" "$FAILSHIMDIR"
-}
-
-# Writes a minimal compendium README with one in-force section (ADRs 003, 049,
-# 051) and one historical section (ADR 010). Stable fixture for placement tests.
-mk_readme() {
-  cat > "$PROJ/docs/decisions/README.md" <<'EOF'
-# Decisions Compendium
-
-Intro prose.
-
----
-
-## In-force decisions
-
-_3 ADRs._
-
-### ADR-003 — Three
-**Status:** proposed | **Oversight:** confirmed
-**Decides:** Decides three.
-
-### ADR-049 — FortyNine
-**Status:** accepted | **Oversight:** confirmed
-**Decides:** Decides forty-nine.
-
-### ADR-051 — FiftyOne
-**Status:** proposed | **Oversight:** confirmed
-**Decides:** Decides fifty-one.
-
----
-
-## Historical decisions
-
-_1 ADR._
-
-### ADR-010 — Ten
-**Status:** superseded | **Oversight:** confirmed
-**Decides:** Decides ten.
-EOF
-}
-
-# mk_adr <nnn> <status> <title>
-mk_adr() {
-  local nnn="$1" status="$2" title="$3"
-  cat > "$PROJ/docs/decisions/${nnn}-slug.${status}.md" <<EOF
----
-status: "$status"
-date: 2026-06-09
-human-oversight: confirmed
----
-
-# $title
-
-## Decision Outcome
-
-Chosen option: **"$title impl"**, because reasons.
-
-## Confirmation
-
-- (a) first
-- (b) second
-
-## Related
-
-- Relates to [ADR-001](001-foo.proposed.md)
-EOF
-  echo "$PROJ/docs/decisions/${nnn}-slug.${status}.md"
-}
-
-run_hook() {
-  local fp="$1"
-  echo "{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"$fp\"},\"session_id\":\"s1\"}" \
-    | CLAUDE_PROJECT_DIR="$PROJ" bash "$HOOK"
-}
-
-@test "fires on Edit to a numbered ADR body and refreshes its entry in-place (criterion 1+4)" {
-  mk_readme
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]
-  # In-place replacement: the entry now carries the stubbed Decides marker...
-  grep -q 'STUBBED-049 decision body' "$PROJ/docs/decisions/README.md"
-  # ...and there is exactly ONE ADR-049 header (no duplicate).
-  [ "$(grep -c '^### ADR-049 ' "$PROJ/docs/decisions/README.md")" -eq 1 ]
-}
-
-@test "produces an observable stderr signal on every invocation (criterion 2)" {
-  mk_readme
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  run run_hook "$fp"
-  [[ "$output" == *"architect-compendium-update-entry"* ]]
-}
-
-@test "emits the expected entry shape with a Decides line (criterion 3)" {
-  mk_readme
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  run_hook "$fp"
-  grep -qE '^\*\*Decides:\*\* STUBBED-049' "$PROJ/docs/decisions/README.md"
-}
-
-@test "inserts a new ADR entry in numeric-sort order within in-force (criterion 5)" {
-  mk_readme
-  fp=$(mk_adr "050" "proposed" "Fifty")
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]
-  # ADR-050 must appear between ADR-049 and ADR-051 in the in-force section.
-  line049=$(grep -n '^### ADR-049 ' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  line050=$(grep -n '^### ADR-050 ' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  line051=$(grep -n '^### ADR-051 ' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  [ -n "$line050" ]
-  [ "$line049" -lt "$line050" ]
-  [ "$line050" -lt "$line051" ]
-}
-
-@test "routes a superseded ADR's entry into the historical section (criterion 6)" {
-  mk_readme
-  fp=$(mk_adr "012" "superseded" "Twelve")
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]
-  # ADR-012 must land AFTER the Historical-decisions header, not in In-force.
-  hist=$(grep -n '^## Historical decisions' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  line012=$(grep -n '^### ADR-012 ' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  [ -n "$line012" ]
-  [ "$line012" -gt "$hist" ]
-}
-
-@test "migrates an entry from in-force to historical when status flips (criterion 6)" {
-  mk_readme
-  # ADR-049 currently renders in the in-force fixture section; re-author it as
-  # superseded — the hook must remove the in-force block and place it historical.
-  fp=$(mk_adr "049" "superseded" "FortyNine")
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]
-  # Exactly one ADR-049 entry, and it is now below the Historical header.
-  [ "$(grep -c '^### ADR-049 ' "$PROJ/docs/decisions/README.md")" -eq 1 ]
-  hist=$(grep -n '^## Historical decisions' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  line049=$(grep -n '^### ADR-049 ' "$PROJ/docs/decisions/README.md" | cut -d: -f1)
-  [ "$line049" -gt "$hist" ]
-}
-
-@test "stages docs/decisions/README.md after refresh (criterion: same-commit pairing)" {
-  mk_readme
-  ( cd "$PROJ" && git add -A && git commit -q -m init )
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  run_hook "$fp"
-  # README must be in the staged set.
-  ( cd "$PROJ" && git diff --cached --name-only ) | grep -q 'docs/decisions/README.md'
-}
-
-@test "subprocess failure leaves README unchanged + does NOT block the edit (criterion 7)" {
-  mk_readme
-  before=$(cat "$PROJ/docs/decisions/README.md")
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  export PATH="$FAILSHIMDIR:$ORIG_PATH"
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]                       # does not block the body edit
-  after=$(cat "$PROJ/docs/decisions/README.md")
-  [ "$before" = "$after" ]                  # README unchanged (degraded mode)
-  [[ "$output" == *"degraded mode"* ]]
-}
-
-@test "opt-out ARCHITECT_AUTO_UPDATE_COMPENDIUM=0 self-suppresses (criterion 8)" {
-  mk_readme
-  before=$(cat "$PROJ/docs/decisions/README.md")
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  run bash -c "echo '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"$fp\"}}' | ARCHITECT_AUTO_UPDATE_COMPENDIUM=0 CLAUDE_PROJECT_DIR='$PROJ' bash '$HOOK'"
-  [ "$status" -eq 0 ]
-  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]
-  [[ "$output" == *"ARCHITECT_AUTO_UPDATE_COMPENDIUM=0"* ]]
-}
-
-@test "ignores README.md edits (no self-recursion)" {
-  mk_readme
-  before=$(cat "$PROJ/docs/decisions/README.md")
-  run run_hook "$PROJ/docs/decisions/README.md"
-  [ "$status" -eq 0 ]
-  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]
-}
-
-@test "ignores non-decisions file edits" {
-  mk_readme
-  echo "x" > "$PROJ/other.ts"
-  run run_hook "$PROJ/other.ts"
-  [ "$status" -eq 0 ]
-}
-
-@test "fail-closed guard: rejects a subprocess entry that injects spurious ADR ids/sections — restores README, degraded, unstaged (P367)" {
-  mk_readme
-  ( cd "$PROJ" && git add -A && git commit -q -m init )
-  before=$(cat "$PROJ/docs/decisions/README.md")
-  fp=$(mk_adr "049" "accepted" "FortyNine")
-  # Malformed shim: valid header for the edited id, but ALSO injects an
-  # unrelated ADR-999 header and a spurious '## ' section — the additive
-  # corruption shape empirically reproduced for P367.
-  BADDIR="$(mktemp -d)"
-  cat > "$BADDIR/claude" <<'SHIM'
-#!/usr/bin/env bash
-cat >/dev/null
-entry="### ADR-049 — Hijacked
-**Status:** accepted | **Oversight:** confirmed
-**Decides:** body.
-
-## Injected section
-
-### ADR-999 — Sneaky"
-jq -cn --arg r "$entry" '{result:$r}'
-SHIM
-  chmod +x "$BADDIR/claude"
-  export PATH="$BADDIR:$ORIG_PATH"
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]                                          # never blocks the body edit
-  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]    # restored unchanged
-  ! grep -q 'ADR-999' "$PROJ/docs/decisions/README.md"         # no injected id survives
-  [[ "$output" == *"guard"* ]]                                 # observable degraded signal
-  # README left in its committed state — no corrupted blob staged.
-  ( cd "$PROJ" && git diff --cached --quiet -- docs/decisions/README.md )
-  rm -rf "$BADDIR"
-}
-
-@test "fail-closed guard: rejects an emit for the wrong ADR id (edited id absent) — restores, degraded (P367)" {
-  mk_readme
-  before=$(cat "$PROJ/docs/decisions/README.md")
-  fp=$(mk_adr "050" "proposed" "Fifty")          # NEW adr — not yet in the compendium
-  # Shim emits an entry for the WRONG id (049, which already exists) instead of
-  # the edited 050: the edited id never lands and 049 is duplicated.
-  WRONGDIR="$(mktemp -d)"
-  cat > "$WRONGDIR/claude" <<'SHIM'
-#!/usr/bin/env bash
-cat >/dev/null
-entry="### ADR-049 — WrongId
-**Status:** proposed | **Oversight:** confirmed
-**Decides:** body."
-jq -cn --arg r "$entry" '{result:$r}'
-SHIM
-  chmod +x "$WRONGDIR/claude"
-  export PATH="$WRONGDIR:$ORIG_PATH"
-  run run_hook "$fp"
-  [ "$status" -eq 0 ]
-  [ "$before" = "$(cat "$PROJ/docs/decisions/README.md")" ]    # restored unchanged
-  ! grep -q '^### ADR-050' "$PROJ/docs/decisions/README.md"    # edited id never landed
-  [[ "$output" == *"guard"* ]]
-  rm -rf "$WRONGDIR"
-}
-
-@test "registered in hooks.json on PostToolUse Edit|Write (criterion 9)" {
-  HOOKS_JSON="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/hooks.json"
-  run jq -e '.hooks.PostToolUse[] | select(.matcher | test("Edit")) | .hooks[] | select(.command | test("architect-compendium-update-entry"))' "$HOOKS_JSON"
-  [ "$status" -eq 0 ]
-}