@windyroad/architect 0.10.0 → 0.11.0-preview.443

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.10.0"
+  "version": "0.11.0"
 }

package/agents/agent.md

@@ -107,6 +107,7 @@ When a change includes a new or modified decision file in `docs/decisions/`:
 - Does it list at least 2 considered options with pros/cons?
 - Does it include reassessment criteria?
 - If it supersedes another decision, is the old decision properly updated?
+- **Is `docs/decisions/README.md` (the compendium) refreshed and staged?** Per ADR-077, the compendium is the architect agent's routine load surface and MUST be regenerated whenever an ADR body changes. Skills (`/wr-architect:create-adr`, `/wr-architect:capture-adr`, `/wr-architect:review-decisions`) regenerate it automatically; off-skill hand-edits and bulk renames must regenerate it explicitly. Flag any change that touches `docs/decisions/<NNN>-*.md` without also staging a fresh `docs/decisions/README.md`. Recovery is mechanical: `wr-architect-generate-decisions-compendium && git add docs/decisions/README.md`. The `architect-compendium-refresh-discipline.sh` commit-time hook is the safety-net backstop, not the primary mechanism.
 
 ## Output Formatting
 

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

@@ -0,0 +1,113 @@
+#!/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

package/hooks/hooks.json

@@ -8,7 +8,8 @@
     ],
     "PreToolUse": [
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-enforce-edit.sh" }] },
-      { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-plan-enforce.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" }] }
     ],
     "PostToolUse": [
       { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-mark-reviewed.sh" }] },

package/package.json

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

package/scripts/generate-decisions-compendium.sh

@@ -23,14 +23,51 @@
 
 set -uo pipefail
 
+# --- 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.
+CHECK_MODE=0
+case "${1:-}" in
+    --check)
+        CHECK_MODE=1
+        shift
+        ;;
+    --help|-h)
+        cat <<'EOF'
+Usage: generate-decisions-compendium.sh [--check] [decisions_dir]
+
+Without --check: regenerates <decisions_dir>/README.md from the per-ADR
+bodies. Idempotent — same in-force ADR set produces byte-identical output.
+
+With --check: generates to a temp file and diffs against the existing
+<decisions_dir>/README.md. Exits 0 if up-to-date, 1 if stale (with a
+diff hint), 2 on directory error. Does NOT modify any file. Used by the
+ADR-077 enforcement hook to verify the committed compendium matches the
+current ADR bodies.
+EOF
+        exit 0
+        ;;
+esac
+
 DECISIONS_DIR="${1:-docs/decisions}"
-COMPENDIUM="$DECISIONS_DIR/README.md"
+TARGET_COMPENDIUM="$DECISIONS_DIR/README.md"
 
 if [ ! -d "$DECISIONS_DIR" ]; then
     echo "generate-decisions-compendium: decisions directory not found: $DECISIONS_DIR" >&2
     exit 2
 fi
 
+# In check mode, redirect generation to a temp file so the on-disk
+# compendium is never mutated.
+if [ "$CHECK_MODE" = "1" ]; then
+    COMPENDIUM=$(mktemp -t architect-compendium-check.XXXXXX)
+    trap 'rm -f "$COMPENDIUM"' EXIT
+else
+    COMPENDIUM="$TARGET_COMPENDIUM"
+fi
+
 # --- Field extractors ------------------------------------------------------
 
 # Read a frontmatter scalar field (single line `key: value`).
@@ -214,16 +251,48 @@ emit_entry() {
 
 # Collect + sort ADR files. README.md and any sibling -history.md / -summary.md
 # style files (future P194 etc.) are excluded.
-files=()
+#
+# Status sectioning (ADR-077 amended 2026-05-30): the compendium is split
+# into two sections so the architect agent's routine load reads in-force
+# decisions first and historical decisions second.
+#   - In-force (proposed + accepted): the current rules to follow.
+#   - Historical (superseded + rejected + deprecated): direction for what NOT
+#     to do — useful when reviewing a proposed change that re-treads a path
+#     that was tried and rejected, or that conflicts with a superseded
+#     decision's still-valid intent.
+# Both sections sort by ID ascending; the status badge on each entry tells
+# the agent which kind it is.
+all_files=()
 while IFS= read -r f; do
-    files+=("$f")
+    all_files+=("$f")
 done < <(find "$DECISIONS_DIR" -maxdepth 1 -type f -name '*.md' \
             ! -name 'README.md' \
             ! -name '*-history.md' \
             ! -name '*-summary.md' \
             2>/dev/null | sort)
 
-total=${#files[@]}
+in_force_files=()
+historical_files=()
+for f in "${all_files[@]}"; do
+    s=$(get_frontmatter_field "$f" "status")
+    case "$s" in
+        proposed|accepted)
+            in_force_files+=("$f")
+            ;;
+        superseded|rejected|deprecated)
+            historical_files+=("$f")
+            ;;
+        *)
+            # Unknown status: surface as in-force so it isn't silently dropped;
+            # the badge will show "?" and a reviewer can correct the source.
+            in_force_files+=("$f")
+            ;;
+    esac
+done
+
+in_force_total=${#in_force_files[@]}
+historical_total=${#historical_files[@]}
+total=$((in_force_total + historical_total))
 
 # Header is deterministic — NO timestamp, NO date. The compendium must be
 # idempotent (same input bodies => byte-identical output) so the ADR-077
@@ -237,14 +306,58 @@ total=${#files[@]}
     echo ""
     echo "Compact rendered index of every ADR's chosen option, confirmation criteria, and relationship graph. **Authoritative substance lives in the per-ADR body** (\`<NNN>-<slug>.<status>.md\`); this compendium is a derived view for routine \`wr-architect:agent\` compliance review."
     echo ""
+    echo "**Two sections:**"
+    echo ""
+    echo "- **In-force decisions** (\`proposed\` + \`accepted\`) — the current rules to follow."
+    echo "- **Historical decisions** (\`superseded\` + \`rejected\` + \`deprecated\`) — direction for what NOT to do. Useful when reviewing a proposed change that re-treads a path already tried, or that conflicts with a superseded decision's still-valid intent. The status badge on each entry says which kind it is."
+    echo ""
     echo "For deep-dive — creating, evolving, ratifying, or contesting a decision — open the per-ADR file directly. \`/wr-architect:create-adr\`, \`/wr-architect:capture-adr\`, and \`/wr-architect:review-decisions\` all keep the full body in scope. Decision Drivers, Considered Options bodies, Pros and Cons, Consequences narrative, and Reassessment Criteria are intentionally NOT in this routine view — they live in the per-ADR body."
     echo ""
-    echo "**Total ADRs:** ${total}"
+    echo "**Total ADRs:** ${total} (${in_force_total} in-force, ${historical_total} historical)"
     echo ""
     echo "---"
-    for f in "${files[@]}"; do
+    echo ""
+    echo "## In-force decisions"
+    echo ""
+    echo "_${in_force_total} ADRs. These are the current rules. The architect agent reads this section first for routine compliance review._"
+    for f in "${in_force_files[@]}"; do
         emit_entry "$f"
     done
+    if [ "$historical_total" -gt 0 ]; then
+        echo ""
+        echo "---"
+        echo ""
+        echo "## Historical decisions"
+        echo ""
+        echo "_${historical_total} ADRs. These were tried and superseded, rejected, or deprecated. Read them as direction for what NOT to do, or to understand the lineage of an in-force decision. Do not enforce them as current rules._"
+        for f in "${historical_files[@]}"; do
+            emit_entry "$f"
+        done
+    fi
 } > "$COMPENDIUM"
 
-echo "generate-decisions-compendium: wrote $COMPENDIUM (${total} ADRs)" >&2
+if [ "$CHECK_MODE" = "1" ]; then
+    # Check mode: diff temp against target. Idempotency contract holds only
+    # when both files exist; treat absence as "stale" (drift detected).
+    if [ ! -f "$TARGET_COMPENDIUM" ]; then
+        echo "generate-decisions-compendium: compendium MISSING — $TARGET_COMPENDIUM does not exist" >&2
+        echo "  run: wr-architect-generate-decisions-compendium" >&2
+        exit 1
+    fi
+    if cmp -s "$COMPENDIUM" "$TARGET_COMPENDIUM"; then
+        echo "generate-decisions-compendium: compendium up-to-date (${total} ADRs — ${in_force_total} in-force, ${historical_total} historical)" >&2
+        exit 0
+    fi
+    {
+        echo "generate-decisions-compendium: compendium IS STALE relative to ADR bodies"
+        echo "  expected (fresh generator output): $COMPENDIUM"
+        echo "  actual   (on disk):                $TARGET_COMPENDIUM"
+        echo "  run: wr-architect-generate-decisions-compendium && git add $TARGET_COMPENDIUM"
+        echo ""
+        echo "diff (first 40 lines):"
+        diff "$TARGET_COMPENDIUM" "$COMPENDIUM" 2>/dev/null | head -40
+    } >&2
+    exit 1
+fi
+
+echo "generate-decisions-compendium: wrote $COMPENDIUM (${total} ADRs total — ${in_force_total} in-force, ${historical_total} historical)" >&2

package/skills/capture-adr/SKILL.md

@@ -137,12 +137,22 @@ The numbered-options placeholder (`1. Option A (chosen) ...` + `2. (deferred ...
 
 Single `Write` to `docs/decisions/<NNN>-<kebab-title>.proposed.md`.
 
+### 4.5. Refresh the decisions compendium (ADR-077)
+
+After the ADR skeleton lands, regenerate `docs/decisions/README.md` so the architect-agent routine load surface includes the new entry:
+
+```bash
+wr-architect-generate-decisions-compendium
+```
+
+The compendium is the architect agent's primary load surface per ADR-077; capture-adr owns keeping it fresh (skills + agent are PRIMARY; the `architect-compendium-refresh-discipline.sh` hook is the safety-net backstop). The next step stages both files together.
+
 ### 5. Commit per ADR-014 — single commit, no architect-review handoff
 
-**Stage list**: ONLY the new ADR file.
+**Stage list**: the new ADR file AND the refreshed compendium (ADR-077 — both move in the same commit so the architect-compendium-refresh-discipline hook passes).
 
 ```bash
-git add docs/decisions/<NNN>-<kebab-title>.proposed.md
+git add docs/decisions/<NNN>-<kebab-title>.proposed.md docs/decisions/README.md
 ```
 
 Satisfy the commit gate per ADR-014 — same two-path pattern as `manage-problem` Step 11 / `capture-problem` Step 6:

package/skills/create-adr/SKILL.md

@@ -207,6 +207,15 @@ oversight-date: YYYY-MM-DD   # today
 
 This is the load-bearing born-confirmed gate: an ADR recorded through create-adr enters the world already human-oversighted (it does not appear in `/wr-architect:review-decisions`' unoversighted set). Do NOT write the marker if the user has not confirmed (rejected / still-iterating ADRs stay unmarked). The marker is orthogonal to `status:` — a `proposed` ADR can be `human-oversight: confirmed`.
 
+**Refresh the decisions compendium (ADR-077).** After the ADR file is written and any born-confirmed marker is applied, regenerate `docs/decisions/README.md` so the architect-agent routine load surface includes the new entry. Run:
+
+```bash
+wr-architect-generate-decisions-compendium
+git add docs/decisions/README.md
+```
+
+The compendium is the architect agent's primary load surface per ADR-077; skills own keeping it fresh. The `architect-compendium-refresh-discipline.sh` PreToolUse hook is the safety-net backstop — it will DENY a commit that stages the new `docs/decisions/<NNN>-*.md` without a matching `docs/decisions/README.md`. Regenerating here makes that hook a no-op on the happy path.
+
 ### 6. Handle supersession (if applicable)
 
 If the user mentions this decision replaces an existing one: