@windyroad/architect 0.21.1 → 0.21.2-preview.1079

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.21.1"
+  "version": "0.21.2"
 }

package/.codex-plugin/plugin.json

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

package/README.md

@@ -41,7 +41,7 @@ This walks you through creating an ADR in [MADR 4.0](https://adr.github.io/madr/
 /wr-architect:capture-adr
 ```
 
-The `capture-adr` skill is the foreground-lightweight aside-invocation variant of `create-adr` (per ADR-032 background-capture pattern). Use it when an architecture decision surfaces mid-conversation and you want the ADR scaffold drafted without losing the operational thread.
+The `capture-adr` skill is the foreground-lightweight aside-invocation variant of `create-adr` (per the governance-skill invocation rule background-capture pattern). Use it when an architecture decision surfaces mid-conversation and you want the ADR scaffold drafted without losing the operational thread.
 
 **Review recorded decisions that lack human oversight:**
 
@@ -49,7 +49,7 @@ The `capture-adr` skill is the foreground-lightweight aside-invocation variant o
 /wr-architect:review-decisions
 ```
 
-The `review-decisions` skill drains the set of ADRs that were recorded without a human confirming the chosen option (per ADR-066). It surfaces each decision's chosen option and alternatives via AskUserQuestion so you confirm, amend, or reject the auto-made call, then writes a `human-oversight: confirmed` marker. Detection is a token-cheap grep over ADR frontmatter; a session-start nudge reports the unoversighted count. New ADRs created through `create-adr` are born oversighted, so the unconfirmed set only shrinks.
+The `review-decisions` skill drains the set of ADRs that were recorded without a human confirming the chosen option (per the architecture human-oversight rule). It surfaces each decision's chosen option and alternatives via AskUserQuestion so you confirm, amend, or reject the auto-made call, then writes a `human-oversight: confirmed` marker. Detection is a token-cheap grep over ADR frontmatter; a session-start nudge reports the unoversighted count. New ADRs created through `create-adr` are born oversighted, so the unconfirmed set only shrinks.
 
 **Run an on-demand architecture compliance review:**
 

package/agents/agent.md

@@ -17,7 +17,7 @@ You are the Architect. You review proposed changes against the project's archite
 
 ## Your Role
 
-1. Read `docs/decisions/README.md` — the generated **Decisions Compendium**. It carries every ADR's chosen option, confirmation criteria, and relationship graph in a compact form (~40 KB vs ~1.6 MB for the full body set; ~40× reduction). **This is the routine load surface for compliance review** (per ADR-077). If `docs/decisions/README.md` does not exist, fall back to globbing `docs/decisions/*.md` (skip the absent README) — the project may predate ADR-077 or be a fresh install. If `docs/decisions/` itself does not exist, that is fine; proceed noting that no prior decisions are recorded. **Load a specific ADR's full body** (`docs/decisions/<NNN>-*.md`) **only when the compendium entry is insufficient for the current review** — deep-dive on a contested change, evolving a decision, ratifying a new ADR via `/wr-architect:create-adr`, or confirming a substance question the compendium summary does not resolve. The per-ADR body remains the authoritative substance (ADR-031); the compendium is a derived view.
+1. Read `docs/decisions/README.md` — the generated **Decisions Compendium**. It carries every ADR's chosen option, confirmation criteria, and relationship graph in a compact form (~40 KB vs ~1.6 MB for the full body set; ~40× reduction). **This is the routine load surface for compliance review** (per the decisions-compendium load rule). If `docs/decisions/README.md` does not exist, fall back to globbing `docs/decisions/*.md` (skip the absent README) — the project may predate the decisions-compendium load rule or be a fresh install. If `docs/decisions/` itself does not exist, that is fine; proceed noting that no prior decisions are recorded. **Load a specific ADR's full body** (`docs/decisions/<NNN>-*.md`) **only when the compendium entry is insufficient for the current review** — deep-dive on a contested change, evolving a decision, ratifying a new ADR via `/wr-architect:create-adr`, or confirming a substance question the compendium summary does not resolve. The per-ADR body remains the authoritative substance (the state-based problem-directory layout rule); the compendium is a derived view.
 2. Read the file(s) being edited to understand the current state and proposed change
 3. Review the proposed change against existing decisions (if any)
 4. Determine if the change requires a new decision to be documented
@@ -25,20 +25,20 @@ You are the Architect. You review proposed changes against the project's archite
 
 ## Review Mode: Pre-edit / proposed-change vs. Post-edit / applied
 
-You operate in one of two review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the P313 (Pre-edit governance-gate catch-22 — review agent withholds PASS because edits "aren't applied yet") catch-22 the gate is designed to close.
+You operate in one of two review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the pre-edit review catch-22 catch-22 the gate is designed to close.
 
 **Pre-edit mode (the default at a governance-gate firing).** The PreToolUse architect gate fires BEFORE a project-file edit lands on disk. The calling prompt describes a PROPOSED change, fix plan, RFC, ticket-body amendment, or about-to-be-made edit — the change is not yet on disk by design. Recognition signals (any one is sufficient): the prompt uses words like "proposed", "plan to", "about to", "PRE-EDIT", "PRE-EDIT alignment gate"; the prompt names the to-be-edited files but the edits are described in prose not yet applied; the prompt is an AFK orchestrator iter dispatch implementing a `## Fix Strategy` against a problem ticket; the prompt is a SKILL handing you an RFC body or story body before the implementation commit lands.
 
 In pre-edit mode:
 
-- If you receive a review request describing PROPOSED changes (not-yet-applied), classify alignment of the PROPOSAL itself. Not-yet-applied state of the proposed change is the EXPECTED baseline of a pre-edit gate. Do NOT treat "edits aren't applied yet" / "the residual old state is still live" / "the change isn't on disk yet" as ISSUES FOUND — that is the gate's design intent (P313 closes this catch-22).
+- If you receive a review request describing PROPOSED changes (not-yet-applied), classify alignment of the PROPOSAL itself. Not-yet-applied state of the proposed change is the EXPECTED baseline of a pre-edit gate. Do NOT treat "edits aren't applied yet" / "the residual old state is still live" / "the change isn't on disk yet" as ISSUES FOUND — that is the gate's design intent (the pre-edit review catch-22 closes this catch-22).
 - The ground truth you classify against is the **proposal** as described in the calling prompt (the diff sketch, the fix-strategy prose, the file-edit plan). The disk state is the legitimate "old state" the proposal is about to replace.
 - PASS the review when the proposal aligns with existing decisions, the proposal does not require a new decision the user hasn't pinned, and the proposal's substance is sound. ISSUES FOUND on a pre-edit review must cite a problem with the **proposal**, not with the not-yet-applied-ness of the proposal.
 - All other review machinery below (Decision Staleness, Existing Decision Compliance, Confirmation Criteria, New Decision Detection, Runtime-Path Performance, Decision Quality, Unratified Dependency, Needs Direction) applies normally — pre-edit mode does not relax any of those substantive checks. It constrains only the verdict-grammar around the not-yet-applied baseline.
 
 **Post-edit mode (the explicit drift-detection or applied-change review).** The calling prompt asks you to verify already-applied edits against decisions — typically a `/wr-architect:review-design` invocation against staged changes and recent commits, or a release-gate audit. Recognition signals: the prompt names "staged changes", "recent commits", "the current diff", "verify compliance", or "review the applied changes against …". In post-edit mode you may flag drift between disk state and decisions exactly as the original verdict grammar describes — the change is on disk by construction; the not-yet-applied carve-out does not apply.
 
-**Default when ambiguous.** When the calling prompt does not name the mode explicitly, default to **pre-edit mode** if a PreToolUse gate context is plausible (the prompt was likely fired by `architect-detect.sh` or an AFK iter dispatch). The pre-edit default is the safer fail-mode: a true post-edit drift will still surface as ISSUES FOUND on the substance; a true pre-edit proposal mis-classified as post-edit fires the P313 catch-22.
+**Default when ambiguous.** When the calling prompt does not name the mode explicitly, default to **pre-edit mode** if a PreToolUse gate context is plausible (the prompt was likely fired by `architect-detect.sh` or an AFK iter dispatch). The pre-edit default is the safer fail-mode: a true post-edit drift will still surface as ISSUES FOUND on the substance; a true pre-edit proposal mis-classified as post-edit fires the pre-edit review catch-22 catch-22.
 
 ## What You Check
 
@@ -79,9 +79,9 @@ Flag when a proposed change represents an undocumented decision:
 - **New script**: Does this introduce a new workflow step?
 - **Structural change**: Does this reorganize code in a way that affects how the team works?
 
-### Runtime-Path Performance Review (per ADR-026, specialised by ADR-023)
+### Runtime-Path Performance Review (per the grounded agent-output rule, specialised by the runtime-path performance review rule)
 
-This review is grounded in ADR-026 (Agent output grounding) — the parent no-ungrounded-claims principle — as specialised by ADR-023 (wr-architect performance review scope) for runtime-path changes. The qualitative-claim ban below is the ADR-026 grounding requirement applied to performance estimates.
+This review is grounded in the grounded agent-output rule — the parent no-ungrounded-claims principle — as specialised by the runtime-path performance review rule for runtime-path changes. The qualitative-claim ban below is the grounded agent-output rule grounding requirement applied to performance estimates.
 
 When a proposed change touches any of the following runtime-path surfaces, you MUST perform a per-request performance review in addition to the ADR-conformance review:
 
@@ -102,7 +102,7 @@ When a proposed change touches any of the following runtime-path surfaces, you M
 
 **Qualitative-claim ban:** You MUST NOT emit qualitative phrases like "load is negligible", "microseconds only", "no measurable impact", "minimal cost", or equivalent hedged wording without attaching the concrete numeric backing described in steps 1-3 above. A quantified estimate that is honestly "worst-case assumption, no data" is acceptable; a qualitative claim without numbers is not.
 
-**Performance-budget ADR template:** ADR-023 embeds a copy-paste template downstream projects place at `docs/decisions/<NNN>-performance-budget-<scope>.proposed.md`. When flagging a missing budget, point the user at ADR-023's Decision Outcome for the template.
+**Performance-budget ADR template:** the runtime-path performance review rule embeds a copy-paste template downstream projects place at `docs/decisions/<NNN>-performance-budget-<scope>.proposed.md`. When flagging a missing budget, point the user at the runtime-path performance review rule's Decision Outcome for the template.
 
 **When the trigger does NOT fire**, skip this review — performance review is scoped to runtime-path changes to keep review cost proportionate.
 
@@ -124,11 +124,11 @@ 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.
+- **Is `docs/decisions/README.md` (the compendium) refreshed and staged?** Per the decisions-compendium load rule, 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
 
-When referencing decision IDs (ADR-<NNN>), problem IDs (P<NNN>), or JTBD IDs in prose output, always include the human-readable title on first mention. Use the format `ADR-013 (Skill manifest in package.json)`, not bare `ADR-013`.
+When referencing decision IDs (ADR-<NNN>), problem IDs (P<NNN>), or JTBD IDs in prose output, always include the human-readable title on first mention. Use the format `the structured governance interaction rule`, not bare `the structured governance interaction rule`.
 
 ## How to Report
 
@@ -148,7 +148,7 @@ If there are issues:
 >
 > 2. ...
 
-If a new decision must be recorded but it has 2+ viable options and no pinned direction (per ADR-064 (Architect Needs-Direction verdict)):
+If a new decision must be recorded but it has 2+ viable options and no pinned direction (per the Needs-Direction handoff rule):
 
 > **Architecture Review: NEEDS DIRECTION**
 >
@@ -160,11 +160,11 @@ If a new decision must be recorded but it has 2+ viable options and no pinned di
 > - (further options as applicable; include "do nothing / status quo" where relevant)
 > - **Advisory lean (optional)**: <your recommendation + why — but do NOT auto-pick, and do NOT prose-ask>
 >
-> The main agent (or calling skill) translates this into an `AskUserQuestion` before the decision is recorded — never a prose ask. Under an AFK orchestrator that cannot ask mid-loop, the verdict queues to the iteration's `outstanding_questions` for batched return-presentation (ADR-044 (Decision-delegation contract)), never blocking or guessing.
+> The main agent (or calling skill) translates this into an `AskUserQuestion` before the decision is recorded — never a prose ask. Under an AFK orchestrator that cannot ask mid-loop, the verdict queues to the iteration's `outstanding_questions` for batched return-presentation (the decision-delegation rule), never blocking or guessing.
 
-**Name the SUBSTANCE, not the grain (ADR-074 (Confirm a decision's substance before building dependent work)).** The decision question + options MUST be the **substantive choice** — the load-bearing options the decision actually records. Do NOT substitute a meta/grain framing question (e.g. "one ADR or two?", file split, naming, ID series) for the substance. A grain question is not a decision the user needs to own; the substantive option is. If both a grain question AND a substantive choice exist, surface the substance — the grain is mechanical (decide it yourself per P132). Confirming only the grain leaves the load-bearing content unconfirmed, which is exactly the P315 failure ADR-074 closes: dependent work then gets built on an unconfirmed substantive choice and a later rejection forces rework.
+**Name the SUBSTANCE, not the grain (the ratify substance before dependent work rule).** The decision question + options MUST be the **substantive choice** — the load-bearing options the decision actually records. Do NOT substitute a meta/grain framing question (e.g. "one ADR or two?", file split, naming, ID series) for the substance. A grain question is not a decision the user needs to own; the substantive option is. If both a grain question AND a substantive choice exist, surface the substance — the grain is mechanical (decide it yourself per the mechanical-stage over-asking failure). Confirming only the grain leaves the load-bearing content unconfirmed, which is exactly the unratified dependent-work failure failure the ratify substance before dependent work rule closes: dependent work then gets built on an unconfirmed substantive choice and a later rejection forces rework.
 
-### When to emit Needs Direction (per ADR-064)
+### When to emit Needs Direction (per the Needs-Direction handoff rule)
 
 Emit **NEEDS DIRECTION** only when ALL of the following hold:
 
@@ -172,29 +172,29 @@ Emit **NEEDS DIRECTION** only when ALL of the following hold:
 2. There are **2+ viable options**.
 3. **No direction is pinned.** Direction counts as pinned — and you must NOT ask, instead reporting PASS / ISSUES FOUND and naming the pinned source — when the option is fixed by any of: a same-turn pin, a same-session pin, an accepted ADR, `RISK-POLICY.md` appetite, or a CLAUDE.md mandatory rule.
 
-Do NOT emit Needs Direction for the "obvious choice" / only-one-viable-option case (see "When NOT to flag" above) — over-firing on obvious choices is the over-ask trap CLAUDE.md P132 warns against. Needs Direction is the architect-surface instance of ADR-044 category 1 (direction-setting); `AskUserQuestion` remains a primary-agent affordance — you name the question + options, the main agent owns the ask.
+Do NOT emit Needs Direction for the "obvious choice" / only-one-viable-option case (see "When NOT to flag" above) — over-firing on obvious choices is the over-ask trap CLAUDE.md the mechanical-stage over-asking failure warns against. Needs Direction is the architect-surface instance of the decision-delegation rule category 1 (direction-setting); `AskUserQuestion` remains a primary-agent affordance — you name the question + options, the main agent owns the ask.
 
-### When to flag [Unratified Dependency] (ADR-074 (Confirm a decision's substance before building dependent work) surface 3)
+### When to flag [Unratified Dependency] (the ratify substance before dependent work rule surface 3)
 
-When the change or plan under review **explicitly cites or implements** a specific ADR (e.g. the diff/prose says "per ADR-072", a `Refs: ADR-NNN`, or it is authoring the work the ADR governs), check whether that ADR has been **ratified** before letting the change stand. You have Read/Glob/Grep (no Bash), so perform the **read-only equivalent** of `packages/architect/scripts/is-decision-unconfirmed.sh` — mirror ALL THREE halves of its "unconfirmed" definition:
+When the change or plan under review **explicitly cites or implements** a specific ADR (e.g. the diff/prose says "per the propose-fix RFC requirement", a `Refs: ADR-NNN`, or it is authoring the work the ADR governs), check whether that ADR has been **ratified** before letting the change stand. You have Read/Glob/Grep (no Bash), so perform the **read-only equivalent** of `packages/architect/scripts/is-decision-unconfirmed.sh` — mirror ALL THREE halves of its "unconfirmed" definition:
 
 1. **Frontmatter-scoped marker check.** Read the cited ADR file and inspect ONLY its YAML frontmatter (the block between the leading `---` and the next `---`). The ADR is **ratified** iff that frontmatter contains a line matching `human-oversight: confirmed` — case-insensitive, tolerating trailing whitespace (the canonical predicate greps `-iE '^human-oversight:[[:space:]]*confirmed[[:space:]]*$'`). A body mention of that string does NOT count — it must be in frontmatter.
 2. **Superseded skip.** A `*.superseded.md` ADR is retired — treat it as ratified-equivalent (do NOT flag); a newer ADR replaced it.
-3. **Rejected-pending-supersede skip** (ADR-066 amendment per P316). An ADR whose frontmatter carries BOTH `human-oversight: rejected-pending-supersede` AND `supersede-ticket: P<NNN>` is ratified-equivalent — the user has explicitly rejected the ADR and pinned a supersede in flight. Treat as ratified (do NOT flag). The marker alone (without the `supersede-ticket:` scalar) does NOT skip — it is malformed and surfaces as unratified so the un-tracked case doesn't silently rot.
+3. **Rejected-pending-supersede skip** (the architecture human-oversight rule amendment per the rejected-decision drain recurrence). An ADR whose frontmatter carries BOTH `human-oversight: rejected-pending-supersede` AND `supersede-ticket: P<NNN>` is ratified-equivalent — the user has explicitly rejected the ADR and pinned a supersede in flight. Treat as ratified (do NOT flag). The marker alone (without the `supersede-ticket:` scalar) does NOT skip — it is malformed and surfaces as unratified so the un-tracked case doesn't silently rot.
 
 Emit **ISSUES FOUND / [Unratified Dependency]** only when the cited ADR's frontmatter lacks the `confirmed` marker AND it is not superseded AND it does not carry the rejected-pending-supersede + supersede-ticket pair — action: "ratify ADR-NNN via `/wr-architect:review-decisions` before this lands." 
 
-**Key the flag on the oversight marker, NEVER on `status:`.** `status: proposed`/`accepted` and `human-oversight:` are orthogonal axes (ADR-066). Building on a **ratified** ADR is fine even when its `status` is still `proposed` — do NOT flag it. Only the *unratified* (marker-absent, non-superseded) case flags. In steady state almost every ADR is ratified (born-confirmed via `create-adr` + the review-decisions drain), so this fires on essentially nothing — do not over-scan or flag transitive/ambient dependence on governed code, only an explicit cite/implement of a specific unratified ADR (the inverse-P078 / P132 over-fire guard).
+**Key the flag on the oversight marker, NEVER on `status:`.** `status: proposed`/`accepted` and `human-oversight:` are orthogonal axes (the architecture human-oversight rule). Building on a **ratified** ADR is fine even when its `status` is still `proposed` — do NOT flag it. Only the *unratified* (marker-absent, non-superseded) case flags. In steady state almost every ADR is ratified (born-confirmed via `create-adr` + the review-decisions drain), so this fires on essentially nothing — do not over-scan or flag transitive/ambient dependence on governed code, only an explicit cite/implement of a specific unratified ADR (the inverse missed strong-correction capture failure / the mechanical-stage over-asking failure over-fire guard).
 
 Issue types:
 - **[Decision Conflict]**: Change conflicts with an accepted/proposed decision
 - **[Undocumented Decision]**: Change represents an architectural choice not covered by any existing decision
-- **[Needs Direction]**: A new decision must be recorded but has 2+ viable options with no pinned direction — name the question + options for the main agent to translate into an `AskUserQuestion` (ADR-064)
+- **[Needs Direction]**: A new decision must be recorded but has 2+ viable options with no pinned direction — name the question + options for the main agent to translate into an `AskUserQuestion` (the Needs-Direction handoff rule)
 - **[Decision Format]**: A decision file doesn't follow MADR 4.0 format
 - **[Missing Supersession]**: A new decision should supersede an old one but doesn't
 - **[Amendment To Ratified Decision]**: The change edits the body of a decision that carries `human-oversight: confirmed`, or adds an `### Amendment` section, or adds an `amends:` frontmatter key. A ratified decision is immutable — see below.
 - **[Confirmation Violation]**: New code violates a confirmation criterion of an existing decision
-- **[Unratified Dependency]**: The change/plan explicitly cites or implements an ADR that is **unratified** (its frontmatter lacks `human-oversight: confirmed`, and it is not `*.superseded.md`) — building on it before a human ratifies its substance is the P315 failure mode (ADR-074 (Confirm a decision's substance before building dependent work) enforcement surface 3)
+- **[Unratified Dependency]**: The change/plan explicitly cites or implements an ADR that is **unratified** (its frontmatter lacks `human-oversight: confirmed`, and it is not `*.superseded.md`) — building on it before a human ratifies its substance is the unratified dependent-work failure failure mode (the ratify substance before dependent work rule enforcement surface 3)
 
 ## Constraints
 
@@ -226,7 +226,7 @@ Statuses are reflected in the filename:
 - **`accepted`** (`NNN-title.accepted.md`): Validated through production use. Must be followed in new implementations.
 - **`rejected`** (`NNN-title.rejected.md`): Evaluated and determined not suitable. Preserved for institutional knowledge.
 - **`deprecated`** (`NNN-title.deprecated.md`): No longer recommended, being phased out without specific replacement.
-- **`superseded`** (`NNN-title.superseded.md`): Replaced by a newer decision. Updated with "Superseded by" note.
+- **`superseded`** (`NNN-title.superseded.md`): Replaced by a newer decision. The historical body remains unchanged.
 
 Status transitions:
 ```
@@ -309,6 +309,5 @@ Do not flag an existing amendment section that a change merely touches nearby or
 When decision NNN is superseded by decision MMM:
 1. Create new decision (MMM) with `supersedes: [NNN-old-decision-title]`
 2. Rename old decision file to `.superseded.md`
-3. Update old decision frontmatter status to `superseded`
-4. Add "Superseded by" section referencing the new decision
-5. Update `docs/decisions/README.md` if it exists
+3. Do not edit the old decision's frontmatter or body
+4. Update `docs/decisions/README.md` if it exists

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

@@ -72,7 +72,8 @@ 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)
+# Preserve the zero-padded identifier for display.
+adr_id_padded=$(echo "$base" | grep -oE '^[0-9]+')
 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
@@ -107,6 +108,9 @@ adr_status=$(awk '
         sub(/^ +/, ""); sub(/ +$/, ""); print; exit
     }
 ' "$file_path")
+case "$(basename "$file_path")" in
+    *.superseded.md) adr_status="superseded" ;;
+esac
 case "$adr_status" in
     superseded|rejected|deprecated) target_section="historical" ;;
     *) target_section="inforce" ;;
@@ -162,6 +166,12 @@ if [ "$subprocess_rc" -eq 0 ] && [ -n "$subprocess_out" ]; then
     new_entry=$(printf '%s' "$subprocess_out" | jq -r '.result // empty' 2>/dev/null)
 fi
 
+# The immutable historical ADR keeps its original frontmatter. The filename is
+# therefore authoritative when a decision is superseded.
+if [ "$adr_status" = "superseded" ] && [ -n "$new_entry" ]; then
+    new_entry=$(printf '%s\n' "$new_entry" | sed -E 's/^\*\*Status:\*\* [^|]*/**Status:** superseded /')
+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

package/hooks/architect-detect.sh

@@ -67,7 +67,7 @@ NOTE: these exclusions are READ tolerance — the architect gate skips
 user edits to these paths. They are NOT agent write targets. Never
 write project-generated artefacts (plans, audits, scratch state) under
 .claude/ — that is user-controlled config space. Project-generated
-content belongs under docs/ or directly in problem-ticket bodies (P131).
+content belongs under docs/ or directly in problem-ticket bodies.
 HOOK_OUTPUT
     mark_announced "architect" "$SESSION_ID"
   fi

package/hooks/architect-dispatch.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Fan out architect hooks from one registered hook per lifecycle event.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+EVENT="${1:-}"
+INPUT="$(cat)"
+
+tool_name() {
+  printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || true
+}
+
+run_gate() {
+  local output status
+  output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/$1")"
+  status=$?
+  [ -z "$output" ] || printf '%s\n' "$output"
+  [ "$status" -eq 0 ] || exit "$status"
+  [ -z "$output" ] || exit 0
+}
+
+run_side_effect() {
+  local output status
+  output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/$1")"
+  status=$?
+  [ -z "$output" ] || printf '%s\n' "$output"
+  return "$status"
+}
+
+case "$EVENT" in
+  session-start)
+    agent_output="$(printf '%s' "$INPUT" | node "$SCRIPT_DIR/../scripts/codex-agent.mjs" --session-start)"
+    nudge_output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/architect-oversight-nudge.sh")"
+    if [ -n "${CODEX_THREAD_ID:-}" ]; then
+      AGENT_OUTPUT="$agent_output" NUDGE_OUTPUT="$nudge_output" python3 -c '
+import json, os
+messages = []
+try:
+    message = json.loads(os.environ["AGENT_OUTPUT"]).get("systemMessage", "")
+except (json.JSONDecodeError, AttributeError):
+    message = os.environ["AGENT_OUTPUT"]
+if message:
+    messages.append(message)
+if os.environ["NUDGE_OUTPUT"]:
+    messages.append(os.environ["NUDGE_OUTPUT"])
+if messages:
+    print(json.dumps({"systemMessage": "\n".join(messages)}))
+'
+    else
+      [ -z "$agent_output" ] || printf '%s\n' "$agent_output"
+      [ -z "$nudge_output" ] || printf '%s\n' "$nudge_output"
+    fi
+    ;;
+  user-prompt)
+    detect_output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/architect-detect.sh")"
+    stale_output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/staleness-check.sh")"
+    [ -z "$detect_output" ] || printf '%s\n' "$detect_output"
+    [ -z "$stale_output" ] || printf '%s\n' "$stale_output"
+    ;;
+  pre-tool)
+    case "$(tool_name)" in
+      Edit|Write)
+        run_gate architect-enforce-edit.sh
+        run_gate architect-oversight-marker-discipline.sh
+        ;;
+      ExitPlanMode)
+        run_gate architect-plan-enforce.sh
+        ;;
+      Bash)
+        run_gate architect-readme-pairing-check.sh
+        ;;
+    esac
+    ;;
+  post-tool)
+    case "$(tool_name)" in
+      Agent)
+        run_side_effect architect-mark-reviewed.sh || true
+        run_side_effect architect-slide-marker.sh || true
+        ;;
+      collaborationspawn_agent|collaborationinterrupt_agent|spawn_agent|close_agent|multi_agent_v1__spawn_agent|multi_agent_v1__close_agent)
+        printf '%s' "$INPUT" | node "$SCRIPT_DIR/codex-agent-completion.mjs"
+        ;;
+      Edit|Write)
+        run_side_effect architect-refresh-hash.sh || true
+        run_side_effect architect-compendium-update-entry.sh || true
+        ;;
+      Bash|Skill)
+        run_side_effect architect-slide-marker.sh || true
+        ;;
+    esac
+    ;;
+esac

package/hooks/architect-oversight-marker-discipline.sh

@@ -156,7 +156,7 @@ cat <<EOF
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "deny",
-    "permissionDecisionReason": "BLOCKED: '${BASENAME}' is about to receive 'human-oversight: confirmed' but no substance-confirm evidence marker exists for this ADR in this session (P348 / ADR-066). The marker '/tmp/oversight-confirmed-<sha>-<sid>' is written by 'wr-architect-mark-oversight-confirmed <adr-path>' immediately after an AskUserQuestion lands the user's substance-confirm answer. If you are an AFK iter subprocess without AskUserQuestion access, write 'human-oversight: unconfirmed' instead — the drain (/wr-architect:review-decisions) will promote it interactively. To recover this Edit/Write: surface the substance-confirm AskUserQuestion to the user, call wr-architect-mark-oversight-confirmed with this ADR's path, then retry."
+    "permissionDecisionReason": "BLOCKED: '${BASENAME}' is about to receive 'human-oversight: confirmed' but no substance-confirm evidence marker exists for this ADR in this session. The marker '/tmp/oversight-confirmed-<sha>-<sid>' is written by 'wr-architect-mark-oversight-confirmed <adr-path>' immediately after an AskUserQuestion lands the user's substance-confirm answer. If you are an AFK iter subprocess without AskUserQuestion access, write 'human-oversight: unconfirmed' instead — the drain (/wr-architect:review-decisions) will promote it interactively. To recover this Edit/Write: surface the substance-confirm AskUserQuestion to the user, call wr-architect-mark-oversight-confirmed with this ADR's path, then retry."
   }
 }
 EOF

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

@@ -138,7 +138,7 @@ staged_compendium=$(git diff --cached --name-only 2>/dev/null \
 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."}}
+{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "architect-readme-pairing-check: '${first_adr}' is staged for commit but 'docs/decisions/README.md' is NOT. 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

package/hooks/hooks.json

@@ -2,26 +2,17 @@
   "hooks": {
     "SessionStart": [
       { "matcher": "startup", "hooks": [
-        { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/codex-agent.mjs --session-start" },
-        { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-oversight-nudge.sh" }
+        { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-dispatch.sh session-start" }
       ] }
     ],
     "UserPromptSubmit": [
-      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-detect.sh" }] },
-      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/staleness-check.sh" }] }
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-dispatch.sh user-prompt" }] }
     ],
     "PreToolUse": [
-      { "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-readme-pairing-check.sh" }] }
+      { "matcher": "Bash|Edit|Write|ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-dispatch.sh pre-tool" }] }
     ],
     "PostToolUse": [
-      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-mark-reviewed.sh" }] },
-      { "matcher": "collaborationspawn_agent|collaborationinterrupt_agent|spawn_agent|close_agent|multi_agent_v1__spawn_agent|multi_agent_v1__close_agent", "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/codex-agent-completion.mjs" }] },
-      { "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" }] }
+      { "matcher": "Agent|Bash|Edit|Skill|Write|collaborationspawn_agent|collaborationinterrupt_agent|spawn_agent|close_agent|multi_agent_v1__spawn_agent|multi_agent_v1__close_agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-dispatch.sh post-tool" }] }
     ]
   }
 }

package/hooks/lib/architect-gate.sh

@@ -61,7 +61,7 @@ check_architect_gate() {
     fi
   fi
 
-  ARCHITECT_GATE_REASON="No architect review marker found for this session. Delegate to wr-architect:agent via the Agent tool (subagent_type: 'wr-architect:agent') so the architect can review and create the marker. NOTE (P400): a verdict upgrade after an ISSUES FOUND review must be a FRESH Agent spawn of wr-architect:agent whose output leads with '**Architecture Review: PASS**' — a SendMessage resume of the same architect agent does NOT fire the marker hook, so a clean PASS from a resumed agent leaves the marker unwritten and this edit stays blocked. If you already hold a genuine PASS, assert the marker manually: touch /tmp/architect-reviewed-\$SID && rm -f /tmp/architect-reviewed-\$SID.hash (SID = newest architect-plan-reviewed-* / architect-announced-* basename)."
+  ARCHITECT_GATE_REASON="No architect review marker found for this session. Delegate to wr-architect:agent via the Agent tool (subagent_type: 'wr-architect:agent') so the architect can review and create the marker. After an ISSUES FOUND verdict, obtain the upgraded PASS from a fresh wr-architect:agent spawn: resuming the prior agent does not fire the completion hook and therefore cannot write the marker. If you already hold a genuine PASS, assert the marker manually: touch /tmp/architect-reviewed-\$SID && rm -f /tmp/architect-reviewed-\$SID.hash (SID = newest architect-plan-reviewed-* / architect-announced-* basename)."
   return 1  # No marker, deny
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.21.1",
+  "version": "0.21.2-preview.1079",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"
@@ -36,6 +36,8 @@
     "!agents/eval/",
     "!agents/test/",
     "!hooks/test/",
+    "!scripts/check-published-internal-ids.sh",
+    "!scripts/sync-codex-skills.mjs",
     "!scripts/test/",
     "!skills/*/test/"
   ]

package/scripts/generate-decisions-compendium.sh

@@ -43,7 +43,7 @@ export LC_ALL=C
 # 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
+echo "generate-decisions-compendium: DEPRECATED — the compendium is now architect-authored on every ADR edit by the 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." >&2
 
 # --- Flag parsing ----------------------------------------------------------
 # `--check` (no write): generate to a temp file and diff against the on-disk
@@ -69,7 +69,7 @@ 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
+compendium consistency hook to verify the committed compendium matches the
 current ADR bodies.
 EOF
         exit 0
@@ -229,6 +229,9 @@ emit_entry() {
     id=$(basename "$file" | grep -oE '^[0-9]+')
     title=$(get_title "$file")
     status=$(get_frontmatter_field "$file" "status")
+    case "$(basename "$file")" in
+        *.superseded.md) status="superseded" ;;
+    esac
     oversight=$(get_frontmatter_field "$file" "human-oversight")
     superseded=$(get_frontmatter_field "$file" "supersedes")
     # ADR-066 amendment (P316): when the oversight value is
@@ -312,6 +315,9 @@ in_force_files=()
 historical_files=()
 for f in "${all_files[@]}"; do
     s=$(get_frontmatter_field "$f" "status")
+    case "$(basename "$f")" in
+        *.superseded.md) s="superseded" ;;
+    esac
     case "$s" in
         proposed|accepted)
             in_force_files+=("$f")
@@ -339,7 +345,7 @@ total=$((in_force_total + historical_total))
 {
     echo "# Decisions Compendium"
     echo ""
-    echo "<!-- AUTO-GENERATED by packages/architect/scripts/generate-decisions-compendium.sh per ADR-077 — do NOT hand-edit; regenerate via \`wr-architect-generate-decisions-compendium\`. -->"
+    echo "<!-- AUTO-GENERATED by packages/architect/scripts/generate-decisions-compendium.sh under the decisions-compendium policy — do NOT hand-edit; regenerate via \`wr-architect-generate-decisions-compendium\`. -->"
     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 ""

package/scripts/mark-oversight-confirmed.sh

@@ -111,7 +111,7 @@ if [ -z "$candidates" ]; then
     echo "  NO oversight marker was written for: ${ABS_PATH}"
     echo "  The oversight-marker-discipline hook will DENY the 'human-oversight: confirmed' Edit"
     echo "  until a session announce marker exists. Start a fresh session, or point SESSION_MARKER_DIR"
-    echo "  at a dir containing a *-announced-<sid> file, then re-run this shim (P368)."
+    echo "  at a dir containing a *-announced-<sid> file, then re-run this shim."
   } >&2
   exit 0
 fi