@windyroad/architect 0.9.0-preview.416 → 0.9.1-preview.423

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.9.0"
+  "version": "0.9.1"
 }

package/agents/agent.md

@@ -136,7 +136,7 @@ If a new decision must be recorded but it has 2+ viable options and no pinned di
 >
 > 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>
+> - **Decision question**: <the substantive 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)
@@ -144,6 +144,8 @@ If a new decision must be recorded but it has 2+ viable options and no pinned di
 >
 > 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.
 
+**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.
+
 ### When to emit Needs Direction (per ADR-064)
 
 Emit **NEEDS DIRECTION** only when ALL of the following hold:

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

@@ -49,6 +49,15 @@ setup() {
   [ "$status" -eq 0 ]
 }
 
+@test "agent.md requires Needs-Direction to name the SUBSTANCE not the grain (ADR-074)" {
+  # ADR-074 surface 1: the verdict must name the substantive choice, not a
+  # meta/grain framing question (e.g. "one ADR or two?"). Closes the P315 vector.
+  run grep -niE "Name the SUBSTANCE, not the grain" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "ADR-074" "$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/bin/wr-architect-is-decision-unconfirmed

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical is-decision-unconfirmed script.
+exec "$(dirname "$0")/../scripts/is-decision-unconfirmed.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.9.0-preview.416",
+  "version": "0.9.1-preview.423",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"

package/scripts/is-decision-unconfirmed.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# wr-architect — predicate: is a referenced decision unconfirmed? (ADR-074)
+#
+# Single-ADR sibling of detect-unoversighted.sh (ADR-066). Where the detector
+# LISTS the whole unoversighted set and always exits 0, this answers ONE
+# question for ONE ADR via its EXIT CODE — for the ADR-074 build-upon guard at
+# the propose-fix surface (/wr-itil:manage-problem + /wr-itil:work-problems).
+# A separate script (not a mode flag on the detector) keeps the detector's
+# "always exit 0, path-list on stdout" contract intact (architect verdict
+# 2026-05-27).
+#
+# "Unconfirmed" mirrors detect-unoversighted.sh EXACTLY:
+#   - the ADR's frontmatter lacks `human-oversight: confirmed`, AND
+#   - the ADR is not superseded.
+# CANONICAL SHAPE: detect-unoversighted.sh. Keep the frontmatter-extraction
+# awk block + the `human-oversight: confirmed` grep + the superseded skip in
+# sync with that script. The `@test "agrees with detect-unoversighted ..."`
+# case in test/is-decision-unconfirmed.bats fails if these two drift.
+#
+# Usage:
+#   is-decision-unconfirmed.sh <adr-ref> [DECISIONS_DIR]
+#     <adr-ref> = ADR-NNN | NNN | path/to/NNN-title.<state>.md
+#     DECISIONS_DIR defaults to docs/decisions
+#
+# Exit codes:
+#   0 = unconfirmed — the build-upon guard SHOULD fire. Prints the resolved path.
+#   1 = confirmed OR superseded — guard should NOT fire. No stdout.
+#   2 = not found / unparseable ref. No stdout; reason on stderr.
+
+set -uo pipefail
+
+REF="${1:-}"
+DECISIONS_DIR="${2:-docs/decisions}"
+
+[ -n "$REF" ] || { echo "is-decision-unconfirmed: missing <adr-ref>" >&2; exit 2; }
+
+# ── Resolve the ADR file ──────────────────────────────────────────────────
+file=""
+if [ -f "$REF" ]; then
+  file="$REF"
+else
+  # Extract the leading numeric ID from ADR-NNN / NNN.
+  num="$(printf '%s' "$REF" | grep -oE '[0-9]+' | head -1)"
+  [ -n "$num" ] || { echo "is-decision-unconfirmed: cannot parse ADR id from '$REF'" >&2; exit 2; }
+  # Match flat (docs/decisions/NNN-*.md) + per-state subdir (docs/decisions/*/NNN-*.md)
+  # layouts; first match wins.
+  shopt -s nullglob
+  for cand in "$DECISIONS_DIR"/"$num"-*.md "$DECISIONS_DIR"/*/"$num"-*.md; do
+    file="$cand"; break
+  done
+  shopt -u nullglob
+fi
+
+[ -n "$file" ] && [ -f "$file" ] || {
+  echo "is-decision-unconfirmed: no decision file for '$REF' under $DECISIONS_DIR" >&2
+  exit 2
+}
+
+base="$(basename "$file")"
+
+# Superseded decisions are retired — a newer ADR replaced them. The build-upon
+# guard does not fire (mirror of detect-unoversighted.sh's superseded skip).
+case "$base" in *.superseded.md) exit 1 ;; esac
+
+# Extract the frontmatter block (mirror of detect-unoversighted.sh): lines
+# between the leading `---` and the next `---`. No leading `---` ⇒ no
+# frontmatter ⇒ treated as unconfirmed.
+fm="$(awk '
+  NR==1 && $0 != "---" { exit }
+  NR==1 { next }
+  /^---[[:space:]]*$/ { exit }
+  { print }
+' "$file")"
+
+if printf '%s\n' "$fm" | grep -qiE '^human-oversight:[[:space:]]*confirmed[[:space:]]*$'; then
+  exit 1   # confirmed — OK to build on
+fi
+
+# Unconfirmed — the build-upon guard SHOULD fire. Name the file for the guard.
+echo "$file"
+exit 0

package/scripts/test/is-decision-unconfirmed.bats

@@ -0,0 +1,108 @@
+#!/usr/bin/env bats
+
+# ADR-074: is-decision-unconfirmed.sh is the single-ADR predicate for the
+# build-upon guard (manage-problem / work-problems propose-fix surface). It
+# answers "is this referenced decision unconfirmed?" via its EXIT CODE, where
+# "unconfirmed" mirrors detect-unoversighted.sh EXACTLY (frontmatter lacks
+# `human-oversight: confirmed`, and the ADR is not superseded).
+#
+# Behavioural — exercises the script against fixture trees and asserts on its
+# exit code + stdout, not its source text (ADR-052).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/architect/scripts/is-decision-unconfirmed.sh"
+  DETECT="$REPO_ROOT/packages/architect/scripts/detect-unoversighted.sh"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/decisions"
+}
+
+teardown() {
+  rm -rf "$DIR"
+}
+
+# mk <filename> <status> [extra-frontmatter-lines...]
+mk() {
+  local name="$1"; local status="$2"; shift 2
+  {
+    echo "---"
+    echo "status: \"$status\""
+    echo "date: 2026-05-27"
+    for line in "$@"; do echo "$line"; done
+    echo "---"
+    echo "# $name"
+  } > "$DIR/docs/decisions/$name"
+}
+
+@test "proposed ADR without the marker is unconfirmed (exit 0, prints path)" {
+  mk "100-no-marker.proposed.md" "proposed"
+  run bash "$SCRIPT" "ADR-100" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"100-no-marker.proposed.md"* ]]
+}
+
+@test "proposed ADR carrying human-oversight: confirmed is confirmed (exit 1, no stdout)" {
+  mk "101-confirmed.proposed.md" "proposed" "human-oversight: confirmed" "oversight-date: 2026-05-27"
+  run bash "$SCRIPT" "ADR-101" "$DIR/docs/decisions"
+  [ "$status" -eq 1 ]
+  [ -z "$output" ]
+}
+
+@test "accepted ADR without the marker is still unconfirmed (exit 0)" {
+  mk "102-accepted-no-marker.accepted.md" "accepted"
+  run bash "$SCRIPT" "ADR-102" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+}
+
+@test "superseded ADR (even without marker) does NOT fire the guard (exit 1)" {
+  mk "103-retired.superseded.md" "superseded"
+  run bash "$SCRIPT" "ADR-103" "$DIR/docs/decisions"
+  [ "$status" -eq 1 ]
+}
+
+@test "a bare numeric ref resolves" {
+  mk "104-bare-num.proposed.md" "proposed"
+  run bash "$SCRIPT" "104" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"104-bare-num.proposed.md"* ]]
+}
+
+@test "a direct path ref resolves" {
+  mk "105-by-path.proposed.md" "proposed"
+  run bash "$SCRIPT" "$DIR/docs/decisions/105-by-path.proposed.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "a per-state subdir layout resolves" {
+  mkdir -p "$DIR/docs/decisions/proposed"
+  {
+    echo "---"; echo "status: \"proposed\""; echo "date: 2026-05-27"; echo "---"; echo "# subdir"
+  } > "$DIR/docs/decisions/proposed/106-subdir.md"
+  run bash "$SCRIPT" "ADR-106" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"106-subdir.md"* ]]
+}
+
+@test "an unknown ADR ref exits 2 (not found)" {
+  run bash "$SCRIPT" "ADR-999" "$DIR/docs/decisions"
+  [ "$status" -eq 2 ]
+}
+
+@test "an unparseable ref exits 2" {
+  run bash "$SCRIPT" "not-an-adr" "$DIR/docs/decisions"
+  [ "$status" -eq 2 ]
+}
+
+@test "agrees with detect-unoversighted on the same fixture (sync guard)" {
+  # The two scripts share the frontmatter/marker/superseded shape. This guard
+  # fails if a future edit drifts one from the other.
+  mk "110-unconfirmed.proposed.md" "proposed"
+  mk "111-confirmed.proposed.md" "proposed" "human-oversight: confirmed" "oversight-date: 2026-05-27"
+  detect_out="$(bash "$DETECT" "$DIR/docs/decisions")"
+  # 110 is in the detector's unoversighted list AND the predicate exits 0.
+  [[ "$detect_out" == *"110-unconfirmed.proposed.md"* ]]
+  run bash "$SCRIPT" "ADR-110" "$DIR/docs/decisions"; [ "$status" -eq 0 ]
+  # 111 is NOT in the detector's list AND the predicate exits 1.
+  [[ "$detect_out" != *"111-confirmed.proposed.md"* ]]
+  run bash "$SCRIPT" "ADR-111" "$DIR/docs/decisions"; [ "$status" -eq 1 ]
+}