@windyroad/architect 0.7.4 → 0.8.0

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.7.4"
+  "version": "0.8.0"
 }

package/agents/agent.md

@@ -62,7 +62,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-023)
+### Runtime-Path Performance Review (per ADR-026, specialised by ADR-023)
+
+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.
 
 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:
 
@@ -128,9 +130,34 @@ 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)):
+
+> **Architecture Review: NEEDS DIRECTION**
+>
+> A decision must be recorded but the option is not pinned — the user, not the agent, owns this choice.
+>
+> - **Decision question**: <the question to settle, in one line>
+> - **Option A** — <name + one-line, grounded in what you read>
+> - **Option B** — <name + one-line, grounded in what you read>
+> - (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.
+
+### When to emit Needs Direction (per ADR-064)
+
+Emit **NEEDS DIRECTION** only when ALL of the following hold:
+
+1. The change requires recording a new decision (you would otherwise flag `[Undocumented Decision]`).
+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.
+
 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)
 - **[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
 - **[Confirmation Violation]**: New code violates a confirmation criterion of an existing decision

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

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

package/package.json

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

package/skills/capture-adr/SKILL.md

@@ -168,6 +168,8 @@ After the commit, report:
 
 The trailing pointer is **not optional** — it is the user-visible signal that the skeleton needs canonical expansion before acceptance review.
 
+**Confirm-every-ADR gate (ADR-064):** a capture-adr skeleton is recorded `proposed` with a pre-pinned decision but WITHOUT human review of the options. It must NOT be promoted to `accepted` until it has been through a `/wr-architect:create-adr` (or equivalent) `AskUserQuestion` review-and-confirm pass. Capture records the decision quickly; the confirm — 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).
+
 ## Composition with create-adr
 
 | Concern | create-adr | capture-adr |

package/skills/create-adr/SKILL.md

@@ -8,6 +8,10 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 
 Create a new ADR in `docs/decisions/` following MADR 4.0 format. The wr-architect:agent reviews these files to enforce architectural compliance.
 
+## Needs-Direction handoff + confirm-every-ADR (ADR-064)
+
+When a `wr-architect:agent` review returns a **NEEDS DIRECTION** verdict (a new decision with 2+ viable options and no pinned direction, per ADR-064), the option choice is the user's, not the agent's — this skill is the translation surface. The architect's named question + options become the Step 2 cat-1 `AskUserQuestion` calls (Considered Options / Decision Outcome), and the Step 5 confirm is the load-bearing **review-and-confirm-every-ADR** gate: an ADR must not stand as a human-oversighted decision (reach `accepted`) without that confirm pass. A `/wr-architect:capture-adr` skeleton — zero-ask precisely because its decision was pre-pinned in `$ARGUMENTS` — must be run through this skill's confirm before promotion to `accepted`. When direction IS already pinned (same-turn / same-session / accepted ADR / RISK-POLICY.md / CLAUDE.md mandatory rule), act on it — do not re-ask (P132 inverse-P078 guard).
+
 ## Steps
 
 ### 1. Discover existing decisions