@windyroad/architect 0.16.0 → 0.17.0-preview.692

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.16.0"
+  "version": "0.17.0"
 }

package/hooks/architect-compendium-update-entry.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# architect-compendium-update-entry.sh — PostToolUse:Edit|Write hook.
+#
+# ADR-078 Phase 1, Option 9 (architect-on-edit writes README entry directly).
+# RFC-014 Story A. Closes P337 structurally: every edit to a per-ADR body
+# triggers a same-hook re-authoring of that ADR's entry in the decisions
+# compendium (docs/decisions/README.md), so body↔compendium drift becomes
+# impossible by construction rather than detectable-and-fixable.
+#
+# Mechanism:
+#   1. Fires on Edit/Write events whose file_path is docs/decisions/<NNN>-*.md
+#      (excludes README.md and any -history.md / -summary.md sibling).
+#   2. Spawns a `claude -p` subprocess invoking wr-architect:agent with the
+#      just-edited ADR body + the current README entry for that ADR-ID (or an
+#      empty string when the ADR is new). The architect emits the updated
+#      compendium entry shape (### ADR-NNN header + Status/Oversight/Supersedes
+#      badges + **Decides:** + **Confirmation:** + **Related:**).
+#   3. Captures the architect's emit from the subprocess JSON `.result` field;
+#      replaces the existing entry block for that ADR-ID in-place, or inserts a
+#      new one in numeric-sort order under the correct section (in-force for
+#      proposed/accepted; historical for superseded/rejected/deprecated).
+#   4. Stages docs/decisions/README.md so it lands in the same commit as the
+#      ADR body change (paired by architect-readme-pairing-check.sh — Story B).
+#
+# Failure mode (ADR-078 Confirmation criterion l): if the subprocess fails
+# (network, quota, model error) or emits nothing usable, the hook logs a
+# warning to stderr and leaves README unchanged (degraded mode). It does NOT
+# block the body edit (exit 0). The stale README is then caught by Story B's
+# pre-commit pairing check on the next `git commit`, surfacing the failure for
+# manual recovery via `wr-architect-generate-decisions-compendium`.
+#
+# Opt-out (ADR-078 Confirmation criterion k): set
+# ARCHITECT_AUTO_UPDATE_COMPENDIUM=0 to suppress the hook entirely (for
+# API-cost-sensitive adopter setups). The hook self-suppresses with a stderr
+# message directing the user to the manual generator.
+#
+# The compendium is no longer generator-derived (ADR-077 criterion b/g/h
+# retired by ADR-078); the generator script is kept as a one-release-cycle
+# backstop only (RFC-014 Story C). ADR-031 authoritative-state is preserved:
+# the per-ADR body remains the source of truth; this entry is a derived view.
+
+set -uo pipefail
+
+# --- Opt-out (criterion k) -------------------------------------------------
+if [ "${ARCHITECT_AUTO_UPDATE_COMPENDIUM:-1}" = "0" ]; then
+    echo "architect-compendium-update-entry: ARCHITECT_AUTO_UPDATE_COMPENDIUM=0 — hook suppressed. Refresh the compendium manually with: wr-architect-generate-decisions-compendium && git add docs/decisions/README.md" >&2
+    exit 0
+fi
+
+# PostToolUse input arrives on stdin as JSON.
+input=$(cat)
+
+tool_name=$(printf '%s' "$input" | jq -r '.tool_name // ""' 2>/dev/null)
+case "$tool_name" in
+    Edit|Write|MultiEdit) ;;
+    *) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+[ -n "$file_path" ] || exit 0
+
+# Path gate: only docs/decisions/<NNN>-*.md ADR bodies. Exclude README and the
+# non-ADR sibling files the generator also excludes.
+base=$(basename "$file_path")
+case "$file_path" in
+    */docs/decisions/*|docs/decisions/*) ;;
+    *) exit 0 ;;
+esac
+case "$base" in
+    README.md|*-history.md|*-summary.md) exit 0 ;;
+esac
+# Must be a numbered ADR file (NNN-...).
+echo "$base" | grep -qE '^[0-9]+-' || exit 0
+
+adr_id_padded=$(echo "$base" | grep -oE '^[0-9]+')   # zero-padded form for display (ADR-049)
+adr_id=$((10#$adr_id_padded))                        # numeric form for sort comparison (49)
+
+# Resolve repo root so the README path + git staging are stable regardless of
+# the hook's runtime CWD (P191 project-root anchoring).
+project_dir="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$project_dir" ]; then
+    project_dir=$(git rev-parse --show-toplevel 2>/dev/null) || project_dir="$PWD"
+fi
+readme="$project_dir/docs/decisions/README.md"
+
+# The edited ADR body must exist on disk (the Write/Edit already landed —
+# PostToolUse fires after the tool succeeds).
+if [ ! -f "$file_path" ]; then
+    # Try the project-root-relative path if file_path was relative.
+    if [ -f "$project_dir/$file_path" ]; then
+        file_path="$project_dir/$file_path"
+    else
+        echo "architect-compendium-update-entry: edited ADR body not found ($file_path) — leaving compendium unchanged" >&2
+        exit 0
+    fi
+fi
+[ -f "$readme" ] || {
+    echo "architect-compendium-update-entry: compendium not found ($readme) — leaving unchanged (run wr-architect-generate-decisions-compendium to bootstrap)" >&2
+    exit 0
+}
+
+# --- Determine target section from the ADR's status ------------------------
+adr_status=$(awk '
+    /^---$/ { fm = !fm; if (!fm) exit; next }
+    fm && /^status:/ {
+        sub(/^status: */, ""); gsub(/^["'"'"']|["'"'"']$/, "")
+        sub(/^ +/, ""); sub(/ +$/, ""); print; exit
+    }
+' "$file_path")
+case "$adr_status" in
+    superseded|rejected|deprecated) target_section="historical" ;;
+    *) target_section="inforce" ;;
+esac
+
+# --- Extract the current README entry block for this ADR-ID -----------------
+# Block = the `### ADR-<id> —` line and following lines up to the next
+# `### ` / `## ` / `---` / EOF. Empty when the ADR is new.
+current_entry=$(awk -v id="$adr_id" '
+    function bid(l,   s){ s=l; sub(/^### ADR-/,"",s); return s+0 }
+    {
+        if ($0 ~ /^### ADR-[0-9]+/) { cap = (bid($0)==id) ? 1 : 0; if (cap) { print; next } }
+        else if ($0 ~ /^### / || $0 ~ /^## / || $0 ~ /^---[[:space:]]*$/) { cap = 0 }
+        if (cap) print
+    }
+' "$readme")
+
+# --- Spawn the architect subprocess (claude -p) ----------------------------
+adr_body=$(cat "$file_path")
+prompt=$(cat <<PROMPT
+You are the wr-architect compendium-entry author. Re-author the single
+docs/decisions/README.md compendium entry for ADR-${adr_id_padded} from its
+current body. Emit ONLY the entry block — no preamble, no code fence, no
+trailing commentary. The entry shape is exactly:
+
+### ADR-${adr_id_padded} — <title>
+**Status:** <status> | **Oversight:** <human-oversight> [| **Supersedes:** <list>]
+**Decides:** <one or two sentence semantic TL;DR of the Decision Outcome — what was decided and why, in plain prose>
+**Confirmation:** <short "; "-joined digest of the Confirmation criteria>
+**Related:** <deduped ADR-NNN list from the Related section and inline mentions>
+
+Omit the Supersedes badge when the body has no supersedes. Omit any of the
+Decides / Confirmation / Related lines only when the body genuinely has no such
+content. Keep the whole entry compact (a few lines) — it is a routine-load
+index surface, not the full body.
+
+--- CURRENT COMPENDIUM ENTRY (may be empty if the ADR is new) ---
+${current_entry}
+
+--- ADR BODY ---
+${adr_body}
+PROMPT
+)
+
+# Capture the architect's emit. `claude -p --output-format json` returns a JSON
+# envelope with a `.result` string. PATH-resolved `claude` (so bats fixtures can
+# stub it with a fixed-response shim placed first on PATH — RFC-014 SQ-014-1).
+subprocess_out=$(printf '%s' "$prompt" | claude -p --output-format json 2>/dev/null)
+subprocess_rc=$?
+
+new_entry=""
+if [ "$subprocess_rc" -eq 0 ] && [ -n "$subprocess_out" ]; then
+    new_entry=$(printf '%s' "$subprocess_out" | jq -r '.result // empty' 2>/dev/null)
+fi
+
+# Degraded mode (criterion l): no usable emit → warn + leave README unchanged,
+# do NOT block the edit.
+if [ -z "$new_entry" ] || ! printf '%s' "$new_entry" | grep -qE '^### ADR-[0-9]+'; then
+    echo "architect-compendium-update-entry: architect subprocess produced no usable entry for ADR-${adr_id} (degraded mode) — compendium left unchanged. The pre-commit pairing check will surface this; recover with wr-architect-generate-decisions-compendium && git add docs/decisions/README.md" >&2
+    exit 0
+fi
+
+# --- Apply the entry: delete any existing block, then insert sorted ---------
+tmp_entry=$(mktemp -t architect-entry.XXXXXX)
+tmp_readme=$(mktemp -t architect-readme.XXXXXX)
+trap 'rm -f "$tmp_entry" "$tmp_readme"' EXIT
+printf '%s\n' "$new_entry" > "$tmp_entry"
+
+# Pass 1 — remove any existing block for this ADR-ID (and the single blank line
+# that precedes it), collapsing blank runs so deletion leaves no double-gap.
+awk -v id="$adr_id" '
+    function bid(l,   s){ s=l; sub(/^### ADR-/,"",s); return s+0 }
+    {
+        if ($0 ~ /^### ADR-[0-9]+/) {
+            if (bid($0)==id) { skipping=1; pendingblank=0; next }
+            skipping=0
+            if (pendingblank) { print ""; pendingblank=0 }
+            print; next
+        }
+        if (skipping) {
+            if ($0 ~ /^### / || $0 ~ /^## / || $0 ~ /^---[[:space:]]*$/) { skipping=0 }
+            else next
+        }
+        if ($0 ~ /^[[:space:]]*$/) { pendingblank=1; next }
+        if (pendingblank) { print ""; pendingblank=0 }
+        print
+    }
+    END { if (pendingblank) print "" }
+' "$readme" > "$tmp_readme"
+
+# Pass 2 — insert the new block in numeric-sort order within the target section.
+awk -v id="$adr_id" -v section="$target_section" -v entryfile="$tmp_entry" '
+    function bid(l,   s){ s=l; sub(/^### ADR-/,"",s); return s+0 }
+    BEGIN {
+        while ((getline l < entryfile) > 0) entry = (entry=="" ? l : entry "\n" l)
+        insec=0; done=0
+    }
+    /^## In-force decisions/   { insec=(section=="inforce") }
+    /^## Historical decisions/ { insec=(section=="historical") }
+    {
+        if (!done && insec && $0 ~ /^### ADR-[0-9]+/ && bid($0) > id) {
+            print entry; print ""; done=1
+        }
+        else if (!done && insec && ($0 ~ /^---[[:space:]]*$/ || ($0 ~ /^## / && $0 !~ /In-force decisions|Historical decisions/))) {
+            print entry; print ""; done=1; insec=0
+        }
+        print
+    }
+    END { if (!done) { print ""; print entry } }
+' "$tmp_readme" > "$readme"
+
+# Stage the compendium so it lands in the same commit as the ADR body change.
+( cd "$project_dir" && git add docs/decisions/README.md 2>/dev/null ) || \
+    echo "architect-compendium-update-entry: git add docs/decisions/README.md failed (not a git repo or staging error) — stage it manually before commit" >&2
+
+echo "architect-compendium-update-entry: refreshed compendium entry for ADR-${adr_id} (${target_section})" >&2
+exit 0

package/hooks/architect-readme-pairing-check.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# architect-readme-pairing-check.sh — PreToolUse:Bash hook.
+#
+# ADR-078 Phase 1, Option 9. RFC-014 Story B. The structural replacement for
+# the retired architect-compendium-refresh-discipline.sh: instead of comparing
+# the staged compendium against PROGRAMMATIC generator output (which no longer
+# holds under architect-authored entries), this hook asserts a simpler, robust
+# invariant — every commit that stages a `docs/decisions/<NNN>-*.md` ADR body
+# change MUST also stage `docs/decisions/README.md`.
+#
+# Under Option 9 the PostToolUse architect-compendium-update-entry.sh hook
+# (Story A) re-authors + stages the README entry on every ADR body edit, so a
+# commit that touches a body but NOT the README means Story A did not run (or
+# ran in degraded mode after a subprocess failure). Denying surfaces that for
+# manual recovery: re-run the edit (re-triggers Story A) or regenerate via
+# `wr-architect-generate-decisions-compendium && git add docs/decisions/README.md`.
+#
+# Replaces ADR-077 Confirmation criterion (g) (the generator-output drift gate /
+# bats test 2145). See ADR-078 § "Drift safety under Option 9".
+#
+# Allow paths (exit 0 silently per ADR-045 Pattern 1):
+#   - tool_name != "Bash"
+#   - command's leading effective executable is not `git commit`
+#   - `RISK_BYPASS: architect-compendium-deferred` token present in command
+#   - BYPASS_COMPENDIUM_REFRESH_GATE=1 (batch/migration parity)
+#   - staged set has no `docs/decisions/<NNN>-*.md` ADR body change
+#   - staged set already includes `docs/decisions/README.md`
+#
+# Deny path (exit 2 with PreToolUse deny JSON on stderr):
+#   - ADR body staged but README not staged
+
+set -uo pipefail
+
+# PreToolUse input arrives on stdin as JSON.
+input=$(cat)
+
+tool_name=$(printf '%s' "$input" | jq -r '.tool_name // ""' 2>/dev/null)
+[ "$tool_name" = "Bash" ] || exit 0
+
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)
+[ -n "$command" ] || exit 0
+
+# Only fire on `git commit` invocations. Leading-executable check (P268
+# pattern): a bare substring match would catch unrelated commands that mention
+# "git commit" (grep/sed/cat). Strip leading whitespace + env assignments, then
+# require the first effective tokens to be `git commit`.
+echo "$command" | awk '
+    {
+        sub(/^[[:space:]]+/, "")
+        while ($0 ~ /^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/) {
+            sub(/^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/, "")
+        }
+        if ($0 ~ /^git[[:space:]]+commit([[:space:]]|$)/) exit 0
+        exit 1
+    }
+' || exit 0
+
+# Allow-list bypass token (parity with the retired refresh-discipline hook and
+# ADR-014 commit-message bypass shape).
+if echo "$command" | grep -qF 'RISK_BYPASS: architect-compendium-deferred'; then
+    exit 0
+fi
+
+# Env-var bypass for batch/migration cases.
+if [ "${BYPASS_COMPENDIUM_REFRESH_GATE:-0}" = "1" ]; then
+    exit 0
+fi
+
+# Resolve repo root so the git plumbing is path-stable.
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$repo_root" || exit 0
+
+# Inspect the staged set. ADR bodies are docs/decisions/<NNN>-*.md (exclude the
+# README itself and the -history / -summary siblings).
+staged_adrs=$(git diff --cached --name-only 2>/dev/null \
+    | awk '/^docs\/decisions\/[0-9]+-.*\.md$/ { print }' \
+    | head -20)
+[ -n "$staged_adrs" ] || exit 0
+
+staged_compendium=$(git diff --cached --name-only 2>/dev/null \
+    | awk '/^docs\/decisions\/README\.md$/ { print }')
+
+if [ -z "$staged_compendium" ]; then
+    first_adr=$(echo "$staged_adrs" | head -1)
+    cat >&2 <<EOF
+{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "architect-readme-pairing-check: '${first_adr}' is staged for commit but 'docs/decisions/README.md' is NOT. Under ADR-078 Option 9 every ADR body change must be paired with its compendium entry refresh (the architect-compendium-update-entry PostToolUse hook does this automatically — if README is unstaged the hook did not run or hit degraded mode). Recover: re-run the ADR edit to re-trigger the hook, OR run 'wr-architect-generate-decisions-compendium && git add docs/decisions/README.md'. Intentional follow-up split: append 'RISK_BYPASS: architect-compendium-deferred' to the commit message. Batch/migration: set BYPASS_COMPENDIUM_REFRESH_GATE=1."}}
+EOF
+    exit 2
+fi
+
+# Both staged — pairing satisfied. (No generator-output comparison: the README
+# is architect-authored under Option 9, not generator-derived.)
+exit 0

package/hooks/hooks.json

@@ -10,11 +10,12 @@
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-enforce-edit.sh" }] },
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-oversight-marker-discipline.sh" }] },
       { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-plan-enforce.sh" }] },
-      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-compendium-refresh-discipline.sh" }] }
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-readme-pairing-check.sh" }] }
     ],
     "PostToolUse": [
       { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-mark-reviewed.sh" }] },
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-refresh-hash.sh" }] },
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-compendium-update-entry.sh" }] },
       { "matcher": "Agent|Bash|Skill", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-slide-marker.sh" }] }
     ]
   }

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

@@ -0,0 +1,241 @@
+#!/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 "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 ]
+}

package/hooks/test/architect-readme-pairing-check.bats

@@ -0,0 +1,90 @@
+#!/usr/bin/env bats
+
+# Behavioural tests for architect-readme-pairing-check.sh (RFC-014 Story B,
+# ADR-078 Phase 1 / Option 9). Exercises the hook against a real staged git
+# index; asserts on its PreToolUse allow/deny decision (exit code + deny JSON).
+# Behavioural — no grep on hook source (feedback_behavioural_tests).
+
+setup() {
+  HOOK="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/architect-readme-pairing-check.sh"
+  REPO="$(mktemp -d)"
+  cd "$REPO"
+  git init -q
+  git config user.email t@e.x
+  git config user.name t
+  mkdir -p docs/decisions
+  echo "# compendium" > docs/decisions/README.md
+  echo "# adr 049" > docs/decisions/049-x.proposed.md
+  git add -A && git commit -q -m init
+}
+
+teardown() {
+  cd /
+  rm -rf "$REPO"
+}
+
+# Run the hook with a synthetic `git commit` Bash PreToolUse payload.
+run_commit_hook() {
+  local cmd="${1:-git commit -m wip}"
+  echo "{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"$cmd\"}}" | bash "$HOOK"
+}
+
+@test "denies commit when an ADR body is staged without README (criterion 1)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"049-x.proposed.md"* ]]
+}
+
+@test "permits commit when ADR body AND README are both staged (criterion 2)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  echo "# compendium refreshed" > docs/decisions/README.md
+  git add docs/decisions/049-x.proposed.md docs/decisions/README.md
+  run run_commit_hook
+  [ "$status" -eq 0 ]
+}
+
+@test "permits commit when only README is staged (compendium-only edit) (criterion 3)" {
+  echo "# compendium refreshed" > docs/decisions/README.md
+  git add docs/decisions/README.md
+  run run_commit_hook
+  [ "$status" -eq 0 ]
+}
+
+@test "permits commit when no ADR-touching change is staged (criterion 4)" {
+  echo "x" > unrelated.txt
+  git add unrelated.txt
+  run run_commit_hook
+  [ "$status" -eq 0 ]
+}
+
+@test "deny message names the unpaired ADR file + recovery directive (criterion 5)" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"049-x.proposed.md"* ]]
+  [[ "$output" == *"wr-architect-generate-decisions-compendium"* ]]
+}
+
+@test "allows non-commit Bash commands silently" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "git status"
+  [ "$status" -eq 0 ]
+}
+
+@test "RISK_BYPASS token permits an intentional split" {
+  echo "# adr 049 edited" > docs/decisions/049-x.proposed.md
+  git add docs/decisions/049-x.proposed.md
+  run run_commit_hook "git commit -m 'wip RISK_BYPASS: architect-compendium-deferred'"
+  [ "$status" -eq 0 ]
+}
+
+@test "registered in hooks.json as PreToolUse Bash (criterion 6)" {
+  HOOKS_JSON="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/hooks.json"
+  run jq -e '.hooks.PreToolUse[] | select(.matcher=="Bash") | .hooks[] | select(.command | test("architect-readme-pairing-check"))' "$HOOKS_JSON"
+  [ "$status" -eq 0 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.16.0",
+  "version": "0.17.0-preview.692",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"

package/scripts/generate-decisions-compendium.sh

@@ -34,11 +34,25 @@ set -uo pipefail
 # truncation — both halves are needed to close P334.
 export LC_ALL=C
 
+# --- ADR-078 (Option 9) deprecation notice (Confirmation criterion j) -------
+# ADR-078 retires this generator as the load-bearing primary path. The
+# compendium is now architect-authored per-edit by the PostToolUse hook
+# `architect-compendium-update-entry.sh` (RFC-014 Story A); body↔compendium
+# pairing is enforced at commit by `architect-readme-pairing-check.sh`
+# (Story B). This script remains a one-release-cycle backstop / bootstrap +
+# offline-reproducibility tool only, to be removed after one
+# @windyroad/architect minor-version cycle (RFC-014 Story C). The notice fires
+# on every invocation per ADR-078 Confirmation criterion (j).
+echo "generate-decisions-compendium: DEPRECATED per ADR-078 (Option 9) — the compendium is now architect-authored on every ADR edit (architect-compendium-update-entry.sh PostToolUse hook). This script is a backstop/bootstrap tool only and will be removed after one @windyroad/architect minor-version cycle (RFC-014 Story C)." >&2
+
 # --- Flag parsing ----------------------------------------------------------
 # `--check` (no write): generate to a temp file and diff against the on-disk
 # compendium. Exit 0 if byte-identical, 1 if drift, 2 if directory missing.
-# Used by the architect-compendium-refresh-discipline.sh enforcement hook
-# (Slice 2) to verify the staged compendium matches the working-tree ADRs.
+# Formerly used by the retired architect-compendium-refresh-discipline.sh
+# enforcement hook (Story D, ADR-078) to verify the staged compendium matched
+# the working-tree ADRs. Under Option 9 the compendium is architect-authored,
+# so --check no longer has a live caller; it is retained for the backstop /
+# offline-reproducibility window only.
 CHECK_MODE=0
 case "${1:-}" in
     --check)

package/scripts/test/generate-decisions-compendium.bats

@@ -53,10 +53,15 @@ mk_adr() {
 # --- ADR-077 (g) drift-detection contract on the live committed state -------
 
 @test "committed compendium matches generator output (CI drift gate)" {
-  # This is the load-bearing assertion from ADR-077 (g): the committed
-  # docs/decisions/README.md MUST match what the generator produces from
-  # the current docs/decisions/<NNN>-*.md bodies. If this fails in CI, the
-  # safety-net hook either failed open or was bypassed.
+  # RETIRED per ADR-078 (Option 9) / RFC-014 Story C (test 2145). Under
+  # architect-on-edit authoring the committed docs/decisions/README.md is
+  # LLM-authored and intentionally no longer byte-matches programmatic
+  # generator output, so this idempotency/drift assertion no longer holds.
+  # Replacement enforcement: the architect-readme-pairing-check.sh pre-commit
+  # hook (Story B) asserts body↔README pairing at commit time. Removed entirely
+  # with the generator script after the backstop window (ADR-078 reassessment
+  # 2026-08-30).
+  skip "test 2145 retired per ADR-078 Option 9 — compendium is architect-authored, not generator-derived (RFC-014 Story C; pairing enforced by architect-readme-pairing-check.sh)"
   cd "$REPO_ROOT"
   run bash "$SCRIPT" --check docs/decisions
   [ "$status" -eq 0 ]

package/hooks/architect-compendium-refresh-discipline.sh

@@ -1,113 +0,0 @@
-#!/usr/bin/env bash
-# architect-compendium-refresh-discipline.sh — PreToolUse:Bash hook
-# (safety net per ADR-077). Denies `git commit` invocations whose staged
-# set includes a `docs/decisions/<NNN>-*.md` ADR change but does NOT also
-# stage a refreshed `docs/decisions/README.md` compendium that matches
-# the current ADR bodies.
-#
-# Per ADR-077: the architect agent and the architect skills
-# (`/wr-architect:create-adr`, `/wr-architect:capture-adr`,
-# `/wr-architect:review-decisions`) are the PRIMARY mechanism for keeping
-# the compendium fresh — they invoke `wr-architect-generate-decisions-compendium`
-# at the right point in their flows. This hook is the SAFETY NET: it
-# catches edits that bypass those flows (hand-edits via Edit/Write tools,
-# off-skill bulk renames, direct file modifications). Mirrors the
-# P165 `itil-readme-refresh-discipline.sh` pattern at the decisions surface.
-#
-# Allow paths (exit 0 silently per ADR-045 Pattern 1):
-#   - tool_name != "Bash"
-#   - command's leading effective executable is not `git commit`
-#   - `RISK_BYPASS: architect-compendium-deferred` token present in command
-#     (intentional follow-up refresh; same allow-list shape as the P165 +
-#     ADR-014 commit-message bypass-token pattern)
-#   - staged set has no `docs/decisions/<NNN>-*.md` ADR change
-#
-# Deny paths (exit 2 with PreToolUse deny JSON on stderr):
-#   - ADR staged but compendium not staged
-#   - both staged but staged compendium does not match generator output
-#     against current working-tree ADR bodies
-#
-# Recovery is mechanical per ADR-013 Rule 1:
-#     wr-architect-generate-decisions-compendium && git add docs/decisions/README.md
-#
-# Override (legitimate intentional split):
-#     append "RISK_BYPASS: architect-compendium-deferred" to the commit message
-#
-# Cross-ref: ADR-077 Confirmation item (h). See also packages/itil/hooks/itil-readme-refresh-discipline.sh
-# for the P165 sibling pattern.
-
-set -uo pipefail
-
-# PreToolUse input arrives on stdin as JSON.
-input=$(cat)
-
-# Tool gate: only Bash.
-tool_name=$(printf '%s' "$input" | jq -r '.tool_name // ""' 2>/dev/null)
-[ "$tool_name" = "Bash" ] || exit 0
-
-# Extract the command.
-command=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)
-[ -n "$command" ] || exit 0
-
-# Only fire on `git commit` invocations. Leading-executable check (P268
-# pattern): substring "git commit" anywhere can match unrelated commands
-# (e.g. grep / sed / cat with that literal). We check the first effective
-# token sequence: optional env-var assignments + optional `git`-aliasing
-# wrappers (none in this codebase) + the literal `git commit`.
-echo "$command" | awk '
-    {
-        # Strip leading whitespace and env assignments (FOO=bar).
-        sub(/^[[:space:]]+/, "")
-        while ($0 ~ /^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/) {
-            sub(/^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+/, "")
-        }
-        # Match git followed by commit.
-        if ($0 ~ /^git[[:space:]]+commit\b/) exit 0
-        exit 1
-    }
-' || exit 0
-
-# Allow-list bypass token. Same shape as P165 and ADR-014.
-if echo "$command" | grep -qF 'RISK_BYPASS: architect-compendium-deferred'; then
-    exit 0
-fi
-
-# Env-var bypass for batch/migration cases (parity with BYPASS_README_REFRESH_GATE).
-if [ "${BYPASS_COMPENDIUM_REFRESH_GATE:-0}" = "1" ]; then
-    exit 0
-fi
-
-# Resolve repo root so subsequent git plumbing is path-stable.
-repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
-cd "$repo_root" || exit 0
-
-# Inspect the staged set.
-staged_adrs=$(git diff --cached --name-only 2>/dev/null \
-    | awk '/^docs\/decisions\/[0-9]+-.*\.md$/ { print }' \
-    | head -20)
-[ -n "$staged_adrs" ] || exit 0
-
-staged_compendium=$(git diff --cached --name-only 2>/dev/null \
-    | awk '/^docs\/decisions\/README\.md$/ { print }')
-
-if [ -z "$staged_compendium" ]; then
-    # ADR staged but compendium not staged. Deny.
-    first_adr=$(echo "$staged_adrs" | head -1)
-    cat >&2 <<EOF
-{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "architect-compendium-refresh-discipline: '${first_adr}' is staged for commit but 'docs/decisions/README.md' is NOT. The compendium is the architect agent's routine load surface (ADR-077). Run: wr-architect-generate-decisions-compendium && git add docs/decisions/README.md. Intentional follow-up split: append 'RISK_BYPASS: architect-compendium-deferred' to the commit message. Batch/migration: set BYPASS_COMPENDIUM_REFRESH_GATE=1."}}
-EOF
-    exit 2
-fi
-
-# Both staged. Verify the staged compendium matches generator output for the
-# current ADR bodies (working tree). The --check mode generates to temp, no
-# mutation. Exit 0 => match; exit 1 => stale.
-if ! wr-architect-generate-decisions-compendium --check >/dev/null 2>&1; then
-    cat >&2 <<EOF
-{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "architect-compendium-refresh-discipline: 'docs/decisions/README.md' is staged but does NOT match the current ADR bodies (stale compendium). Run: wr-architect-generate-decisions-compendium && git add docs/decisions/README.md to refresh, then re-commit. Intentional follow-up split: append 'RISK_BYPASS: architect-compendium-deferred' to the commit message."}}
-EOF
-    exit 2
-fi
-
-# All clear.
-exit 0