@windyroad/architect 0.20.4 → 0.21.0-preview.1061

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/agents/agent.md

@@ -192,6 +192,7 @@ Issue types:
 - **[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)
 - **[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)
 
@@ -286,6 +287,23 @@ Do NOT create decisions for:
 - Reversible choices: easy to change without significant impact
 - Local choices: decisions that only affect a single component or file
 
+### A ratified decision is immutable
+
+A decision document records **one choice between options**, and its lifecycle has two phases:
+
+- **Before ratification it is mutable.** Edit it freely — rewrite the context, sharpen the outcome, add another option to the set being weighed. Nothing is fixed, because no human has confirmed anything.
+- **After ratification — `human-oversight: confirmed` — it is immutable.** The only legitimate moves are to **deprecate** it or to **supersede** it with a new decision. You do not edit its body, and no other document reaches into it.
+
+**`### Amendment` sections and the `amends:` frontmatter key are not a legitimate mechanism.** They are how a ratified decision gets rewritten without a confirm event, and how one document acquires authority over another's text. Raise `[Amendment To Ratified Decision]` when a change proposes either, and direct the author to write a new decision that supersedes instead.
+
+Do not accept these as remedies, because none of them addresses the problem:
+
+- clearing the marker to `unconfirmed` and re-ratifying — that makes the edit *confirmable*, not legitimate, and still rewrites one document's ratified text under another's change;
+- calling the edit a clarification rather than a substance change — the distinction does not exist here, because the document is closed either way;
+- citing existing `### Amendment` sections in the corpus as precedent. **They are a known defect under repair, not a pattern to follow.** Many in-force decisions carry them; that is backlog, not authority. Never cite one to justify a new amendment.
+
+Do not flag an existing amendment section that a change merely touches nearby or does not modify — this fires on a change *proposing* an amendment, not on the corpus's existing ones.
+
 ### Superseding Process
 
 When decision NNN is superseded by decision MMM:

package/hooks/architect-enforce-edit.sh

@@ -130,7 +130,7 @@ esac
 # assess. The architect-oversight-marker-discipline.sh hook remains the
 # safety net: marker-only diffs that introduce `human-oversight:
 # confirmed` still require the per-ADR session evidence marker (P348 /
-# ADR-066 amendment 2026-06-02). Mixed marker+body diffs, status:/date:
+# ADR-110). Mixed marker+body diffs, status:/date:
 # changes, and pure body changes fall through to the normal gate.
 case "$FILE_PATH" in
   */docs/decisions/*.md|docs/decisions/*.md)

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # architect-oversight-marker-discipline.sh — PreToolUse:Edit|Write hook
-# (P348 / ADR-066 amendment 2026-06-02). Denies Edit/Write operations that
+# (P348 / ADR-110). Denies Edit/Write operations that
 # introduce `human-oversight: confirmed` into a docs/decisions/ ADR's
 # frontmatter unless a session-scoped evidence marker proves the user has
 # substance-confirmed THAT specific ADR via AskUserQuestion.

package/hooks/lib/marker-only-diff.sh

@@ -22,7 +22,7 @@
 # architect-oversight-marker-discipline.sh (and JTBD sibling) hooks remain
 # active as the safety net: a marker-only diff that introduces
 # `human-oversight: confirmed` still requires the per-ADR session evidence
-# marker (P348 / ADR-066 amendment 2026-06-02).
+# marker (P348 / ADR-110).
 #
 # Conservative boundary: any non-empty line outside the marker grammar
 # (frontmatter delimiters that shift position, status:/date: changes, body

package/package.json

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

package/scripts/check-amends-backreference.sh

@@ -2,9 +2,9 @@
 # check-amends-backreference.sh — load-bearing detector for lockstep-amendment drift.
 #
 # An ADR that declares `amends: [ADR-NNN, ...]` is asserting that it changed those
-# decisions' meaning. A reader who lands on the AMENDED ADR must be able to find
-# that out from the amended ADR itself — otherwise the old text reads as current
-# and the amendment is invisible from the only direction that matters.
+# decisions' meaning. While the target remains mutable, a reader who lands on it
+# must be able to discover the amendment. Confirmed targets are immutable under
+# ADR-116, so legacy amendment debt must not force an in-place back-reference.
 #
 # This checks the back-reference exists: for every `amends:` entry, the amended
 # ADR's body must mention the amending ADR by ID. Cheap, mechanical, and it fires
@@ -41,6 +41,7 @@ for f in "$dir"/[0-9]*.md; do
       missing="$missing\n  $self declares amends: $target, which does not resolve in $dir"
       continue
     fi
+    awk 'NR==1&&$0=="---"{fm=1;next} fm&&/^---[[:space:]]*$/{exit} fm&&tolower($0)~/^human-oversight:[[:space:]]*confirmed[[:space:]]*$/{found=1} END{exit !found}' "$tf" && continue
     grep -qF "$self" "$tf" || \
       missing="$missing\n  $(basename "$tf") is amended by $self but never mentions it — a reader of the amended decision cannot discover the amendment"
   done

package/scripts/mark-oversight-confirmed.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # wr-architect — mark a decision/ADR's human-oversight: confirmed marker write
-# as user-substance-confirmed (P348 / ADR-066 amendment 2026-06-02).
+# as user-substance-confirmed (P348 / ADR-110).
 #
 # Companion to the architect-oversight-marker-discipline.sh PreToolUse hook
 # (also P348). SKILLs invoke this script AFTER an AskUserQuestion lands the

package/skills/capture-adr/SKILL.md

@@ -217,7 +217,7 @@ The trailing pointer is **not optional** — it is the user-visible signal that
 
 **Confirm-every-ADR gate (ADR-064):** a capture-adr ADR is recorded `proposed` with derived substance but WITHOUT human review of that substance. It must NOT be promoted to `accepted` until a human has ratified the derived content via `/wr-architect:review-decisions` (or a `/wr-architect:create-adr` review-and-confirm pass). Capture records the decision quickly; the ratification — not the capture — is what gives it human oversight. This is prong 1 of P283 (lift auto-/quick-recorded decisions to human-confirmed before they stand).
 
-**Oversight marker discipline (ADR-066 amendment 2026-06-02 / P348).** A capture-adr ADR MUST be born `human-oversight: unconfirmed` — NOT `confirmed`. Capture is the AFK-friendly aside surface; there is no substance-confirm `request_user_input` pass in this flow, so `confirmed` would be a hollow marker (the P348 bug class). The `architect-oversight-marker-discipline.sh` PreToolUse hook will DENY any Edit/Write that introduces `human-oversight: confirmed` without a matching session-scoped evidence marker. The frontmatter (Step 3 above) MUST include `human-oversight: unconfirmed` so the ADR enters the world honestly self-identified as needing user confirmation. The drain (`/wr-architect:review-decisions`) and a `/wr-architect:create-adr <NNN>` review pass are the surfaces that legitimately promote it to `confirmed` via `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` + the gated marker write.
+**Oversight marker discipline (ADR-110 / P348).** A capture-adr ADR MUST be born `human-oversight: unconfirmed` — NOT `confirmed`. Capture is the AFK-friendly aside surface; there is no substance-confirm `request_user_input` pass in this flow, so `confirmed` would be a hollow marker (the P348 bug class). The `architect-oversight-marker-discipline.sh` PreToolUse hook will DENY any Edit/Write that introduces `human-oversight: confirmed` without a matching session-scoped evidence marker. The frontmatter (Step 3 above) MUST include `human-oversight: unconfirmed` so the ADR enters the world honestly self-identified as needing user confirmation. The drain (`/wr-architect:review-decisions`) and a `/wr-architect:create-adr <NNN>` review pass are the surfaces that legitimately promote it to `confirmed` via `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` + the gated marker write.
 
 ## Composition with create-adr
 

package/skills/create-adr/SKILL.md

@@ -262,7 +262,7 @@ options:
   - ...one entry per considered option
 ```
 
-**Born-confirmed marker write (ADR-066 — tightened by P340 amendment + structurally gated by P348 amendment 2026-06-02).** The marker write fires ONLY when the substance-confirm answer specifies a substantive option from the considered-options set AND that option matches the option the draft was authored against. On a substantive match, IMMEDIATELY call the marker-evidence helper THEN insert the two lines:
+**Born-confirmed marker write (ADR-066 — tightened by P340 amendment + structurally gated by ADR-110).** The marker write fires ONLY when the substance-confirm answer specifies a substantive option from the considered-options set AND that option matches the option the draft was authored against. On a substantive match, IMMEDIATELY call the marker-evidence helper THEN insert the two lines:
 
 ```bash
 bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh" docs/decisions/<NNN>-<slug>.proposed.md
@@ -273,7 +273,7 @@ human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-The `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` call writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `architect-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. AFK iter subprocesses spawned via `claude -p` have no `request_user_input` access; they MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-066 amendment 2026-06-02), which the drain (`/wr-architect:review-decisions`) later promotes interactively. Calling the helper without a real user substance-confirm event is the P348 hollow-marker bug — every legitimate marker write traces back to an `request_user_input` answer in the same turn.
+The `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` call writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `architect-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. AFK iter subprocesses spawned via `claude -p` have no `request_user_input` access; they MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-110), which the drain (`/wr-architect:review-decisions`) later promotes interactively. Calling the helper without a real user substance-confirm event is the P348 hollow-marker bug — every legitimate marker write traces back to an `request_user_input` answer in the same turn.
 
 **ADR-013 Rule 6 carve-out audit (P352, 2026-06-06 amendment)**: the universal AFK default is queue-and-continue. This Step 5 substance-confirm HALT-and-write-`human-oversight: unconfirmed` shape is a documented carve-out, authorised by **ADR-074** (Confirm decision substance before building dependent work). Rationale: an ADR with `human-oversight: confirmed` enters the world born-confirmed (it does not appear in `/wr-architect:review-decisions`' unoversighted set), so dependent work — every implementation that cites this ADR as authority — would be built on substance that was never user-affirmed. AFK writing `human-oversight: unconfirmed` IS the queue-and-continue shape: the loop continues; the substance-confirm decision is queued to the next interactive drain. Persona-correct for JTBD-006 ("queued for my return, not guessed at"); the carve-out is from the auto-confirm shape, not from queue-and-continue itself.