@windyroad/architect 0.7.4 → 0.8.0-preview.387

package/.claude-plugin/plugin.json

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

package/README.md

@@ -43,6 +43,22 @@ This walks you through creating an ADR in [MADR 4.0](https://adr.github.io/madr/
 
 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.
 
+**Review recorded decisions that lack human oversight:**
+
+```
+/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.
+
+**Run an on-demand architecture compliance review:**
+
+```
+/wr-architect:review-design
+```
+
+The `review-design` skill checks staged changes and recent commits against the existing ADRs in `docs/decisions/` — a pre-flight you can run before editing architecture-bearing files or cutting a release, without waiting for the per-edit gate.
+
 ## How It Works
 
 | Hook | Trigger | What it does |
@@ -53,6 +69,7 @@ The `capture-adr` skill is the foreground-lightweight aside-invocation variant o
 | `architect-mark-reviewed.sh` | Agent completes | Marks the review as done (TTL: 3600s) |
 | `architect-refresh-hash.sh` | After edit | Refreshes the content hash so the next edit triggers a fresh review |
 | `architect-slide-marker.sh` | Agent or Bash | Slides the review marker forward across non-edit operations so an active review session is not invalidated by intervening Bash or sub-agent calls |
+| `architect-oversight-nudge.sh` | Session start | Reports how many recorded decisions lack human oversight and points to `/wr-architect:review-decisions`; silent when none, and self-suppressed inside AFK iterations |
 
 ## Agent
 
@@ -62,26 +79,6 @@ The `wr-architect:agent` reviews proposed changes against existing decisions in
 - Whether a new ADR should be created
 - Whether existing decisions are stale and need reassessment
 
-## Jobs to be Done
-
-This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
-
-### Tech lead / consultant
-
-- **[JTBD-202 Run Pre-Flight Governance Checks Before Release or Handover](../../docs/jtbd/tech-lead/JTBD-202-pre-flight-governance-check.proposed.md)** — architect review is available via `/wr-architect:review-design` for on-demand pre-flight, and via `wr-architect:agent` for automatic review on every edit.
-
-### Solo developer
-
-- **[JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md)** — architecture decisions are reviewed automatically; the agent reads the project's existing ADRs without needing to be told what to look for.
-
-### Plugin developer
-
-- **[JTBD-101 Extend the Suite with New Plugins](../../docs/jtbd/plugin-developer/JTBD-101-extend-suite.proposed.md)** — `/wr-architect:create-adr` is the canonical surface for documenting structural decisions in MADR 4.0 format so contributors learn the "why" behind existing patterns.
-
-### Plugin user
-
-- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
-
 ## Updating and Uninstalling
 
 ```bash

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/bin/wr-architect-detect-unoversighted

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

package/hooks/architect-oversight-nudge.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# wr-architect — SessionStart hook (ADR-066)
+#
+# Surfaces a one-line nudge when recorded decisions (ADRs) lack the
+# human-oversight marker, so the user can drain them via
+# /wr-architect:review-decisions. Modelled on the ADR-040 session-start
+# briefing surface and packages/itil/hooks/itil-pending-questions-surface.sh.
+#
+# Detection is token-cheap: it delegates to detect-unoversighted.sh (a grep
+# over ADR frontmatter — no body reads, no per-ADR LLM call). Silent when the
+# unoversighted count is zero (steady state once the set is drained).
+#
+# AFK self-suppress (JTBD-006 friction guard): AFK orchestrators set
+# WR_SUPPRESS_OVERSIGHT_NUDGE=1 before spawning each `claude -p` iteration so
+# this interactive batch-confirm nudge never fires into an absent-user
+# subprocess (the same discipline itil-pending-questions-surface.sh applies
+# with WR_SUPPRESS_PENDING_QUESTIONS). Only the literal "1" suppresses.
+
+set -euo pipefail
+
+if [ "${WR_SUPPRESS_OVERSIGHT_NUDGE:-}" = "1" ]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DECISIONS_DIR="$PROJECT_DIR/docs/decisions"
+
+# Silent when this project has no decision records.
+[ -d "$DECISIONS_DIR" ] || exit 0
+
+DETECT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/detect-unoversighted.sh"
+[ -x "$DETECT" ] || DETECT="$(dirname "$0")/../scripts/detect-unoversighted.sh"
+
+# Count unoversighted ADRs. `grep -c .` counts non-empty lines; tolerate the
+# detector printing nothing (count 0).
+COUNT="$(bash "$DETECT" "$DECISIONS_DIR" 2>/dev/null | grep -c . || true)"
+COUNT="${COUNT:-0}"
+
+# Silent-on-no-content per ADR-040 Mechanism step 1.
+[ "$COUNT" -gt 0 ] 2>/dev/null || exit 0
+
+if [ "$COUNT" -eq 1 ]; then
+  echo "[wr-architect] 1 recorded decision lacks human oversight — run /wr-architect:review-decisions to confirm it."
+else
+  echo "[wr-architect] $COUNT recorded decisions lack human oversight — run /wr-architect:review-decisions to confirm them."
+fi

package/hooks/hooks.json

@@ -1,5 +1,8 @@
 {
   "hooks": {
+    "SessionStart": [
+      { "matcher": "startup", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-oversight-nudge.sh" }] }
+    ],
     "UserPromptSubmit": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/architect-detect.sh" }] }
     ],

package/hooks/test/architect-oversight-nudge.bats

@@ -0,0 +1,70 @@
+#!/usr/bin/env bats
+
+# ADR-066: architect-oversight-nudge.sh (SessionStart) emits a one-line nudge
+# when ADRs lack the human-oversight marker, is silent when none do, and
+# self-suppresses under the AFK guard (WR_SUPPRESS_OVERSIGHT_NUDGE=1) so the
+# interactive batch-confirm never fires into an absent-user iteration (JTBD-006).
+# Behavioural — exercises the hook against fixture trees and asserts on stdout.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/architect/hooks/architect-oversight-nudge.sh"
+  PLUGIN_ROOT="$REPO_ROOT/packages/architect"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/decisions"
+}
+
+teardown() {
+  rm -rf "$DIR"
+}
+
+mk_unmarked() {
+  { echo "---"; echo "status: \"proposed\""; echo "date: 2026-05-25"; echo "---"; echo "# $1"; } \
+    > "$DIR/docs/decisions/$1"
+}
+mk_marked() {
+  { echo "---"; echo "status: \"proposed\""; echo "date: 2026-05-25"; echo "human-oversight: confirmed"; echo "---"; echo "# $1"; } \
+    > "$DIR/docs/decisions/$1"
+}
+
+@test "emits a count line when there are unoversighted ADRs" {
+  mk_unmarked "010-a.proposed.md"
+  mk_unmarked "011-b.proposed.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"2 recorded decisions lack human oversight"* ]]
+  [[ "$output" == *"/wr-architect:review-decisions"* ]]
+}
+
+@test "uses singular wording for exactly one unoversighted ADR" {
+  mk_unmarked "010-a.proposed.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"1 recorded decision lacks human oversight"* ]]
+}
+
+@test "silent when every ADR is confirmed" {
+  mk_marked "010-a.proposed.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "AFK guard suppresses the nudge entirely" {
+  mk_unmarked "010-a.proposed.md"
+  run env WR_SUPPRESS_OVERSIGHT_NUDGE=1 CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "guard value other than 1 does not suppress" {
+  mk_unmarked "010-a.proposed.md"
+  mk_unmarked "011-b.proposed.md"
+  run env WR_SUPPRESS_OVERSIGHT_NUDGE=0 CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"lack human oversight"* ]]
+}
+
+@test "silent when project has no docs/decisions dir" {
+  run env CLAUDE_PROJECT_DIR="$DIR/empty" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.7.4",
+  "version": "0.8.0-preview.387",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
+    "scripts/",
     ".claude-plugin/",
     "lib/"
   ]

package/scripts/detect-unoversighted.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# wr-architect — detect ADRs lacking the human-oversight marker (ADR-066)
+#
+# Token-cheap detection: greps each ADR's YAML frontmatter for the presence of
+# `human-oversight: confirmed`. No body reads, no per-ADR LLM call. An ADR is
+# "unoversighted" when its frontmatter does not carry that marker line (or has
+# no frontmatter at all).
+#
+# Usage:
+#   detect-unoversighted.sh [DECISIONS_DIR]
+#     DECISIONS_DIR defaults to docs/decisions
+#
+# Output: one unoversighted ADR file path per line, sorted. Empty output = the
+# whole set is confirmed. Callers derive the count with `grep -c .` / `wc -l`.
+# Always exits 0 (it is a detector, not a gate).
+#
+# Consumed by: architect-oversight-nudge.sh (SessionStart count) and
+# /wr-architect:review-decisions (the drain list). Marker contract: ADR-066.
+
+set -euo pipefail
+
+DECISIONS_DIR="${1:-docs/decisions}"
+
+[ -d "$DECISIONS_DIR" ] || exit 0
+
+# Match both the flat layout (docs/decisions/*.md) and any per-state subdir
+# layout an adopter might introduce later (docs/decisions/*/*.md). README is
+# never a decision record.
+shopt -s nullglob
+for f in "$DECISIONS_DIR"/*.md "$DECISIONS_DIR"/*/*.md; do
+  base="$(basename "$f")"
+  [ "$base" = "README.md" ] && continue
+  # Superseded decisions are retired — a newer ADR replaced them. Confirming a
+  # dead decision has no value, so they are not part of the "needs oversight"
+  # set (keeps the nudge count and the drain queue focused on live decisions).
+  case "$base" in *.superseded.md) continue ;; esac
+
+  # Extract the frontmatter block: lines between the leading `---` and the
+  # next `---`. If line 1 is not `---`, the file has no frontmatter and the
+  # awk prints nothing → treated as unoversighted.
+  fm="$(awk '
+    NR==1 && $0 != "---" { exit }
+    NR==1 { next }
+    /^---[[:space:]]*$/ { exit }
+    { print }
+  ' "$f")"
+
+  if ! printf '%s\n' "$fm" | grep -qiE '^human-oversight:[[:space:]]*confirmed[[:space:]]*$'; then
+    echo "$f"
+  fi
+done | sort

package/scripts/test/detect-unoversighted.bats

@@ -0,0 +1,99 @@
+#!/usr/bin/env bats
+
+# ADR-066: detect-unoversighted.sh prints ADRs whose frontmatter lacks the
+# `human-oversight: confirmed` marker. Behavioural — exercises the script
+# against fixture trees and asserts on its stdout, not its source text.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/architect/scripts/detect-unoversighted.sh"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/decisions"
+}
+
+teardown() {
+  rm -rf "$DIR"
+}
+
+mk() { # mk <filename> <frontmatter-extra-lines...>
+  local name="$1"; shift
+  {
+    echo "---"
+    echo "status: \"proposed\""
+    echo "date: 2026-05-25"
+    for line in "$@"; do echo "$line"; done
+    echo "---"
+    echo "# $name"
+  } > "$DIR/docs/decisions/$name"
+}
+
+@test "an ADR without the marker is reported" {
+  mk "010-no-marker.proposed.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"010-no-marker.proposed.md"* ]]
+}
+
+@test "an ADR carrying human-oversight: confirmed is NOT reported" {
+  mk "011-confirmed.proposed.md" "human-oversight: confirmed" "oversight-date: 2026-05-25"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"011-confirmed.proposed.md"* ]]
+}
+
+@test "marker match is case-insensitive and tolerant of trailing space" {
+  mk "012-spacey.proposed.md" "human-oversight:   confirmed   "
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" != *"012-spacey.proposed.md"* ]]
+}
+
+@test "README.md is never reported" {
+  echo "# index" > "$DIR/docs/decisions/README.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" != *"README.md"* ]]
+}
+
+@test "superseded ADRs are excluded even without the marker" {
+  mk "013-old.superseded.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" != *"013-old.superseded.md"* ]]
+}
+
+@test "a file with no frontmatter counts as unoversighted" {
+  echo "# bare ADR, no frontmatter" > "$DIR/docs/decisions/014-bare.proposed.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" == *"014-bare.proposed.md"* ]]
+}
+
+@test "a body line that looks like the marker does not count (frontmatter only)" {
+  {
+    echo "---"
+    echo "status: \"proposed\""
+    echo "date: 2026-05-25"
+    echo "---"
+    echo "# 015"
+    echo "human-oversight: confirmed"   # in body, not frontmatter
+  } > "$DIR/docs/decisions/015-body-trick.proposed.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" == *"015-body-trick.proposed.md"* ]]
+}
+
+@test "accepted ADRs are in scope (oversight is orthogonal to status)" {
+  mk "016-shipped.accepted.md"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [[ "$output" == *"016-shipped.accepted.md"* ]]
+}
+
+@test "missing decisions dir exits 0 with no output" {
+  run bash "$SCRIPT" "$DIR/docs/nonexistent"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "fully-confirmed set produces empty output" {
+  mk "017-a.proposed.md" "human-oversight: confirmed"
+  mk "018-b.accepted.md" "human-oversight: confirmed"
+  run bash "$SCRIPT" "$DIR/docs/decisions"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

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
@@ -194,6 +198,15 @@ Present the written ADR and use AskUserQuestion to ask:
 
 Apply any feedback by editing the file.
 
+**Born-confirmed write (ADR-066).** Once the user confirms the ADR via this AskUserQuestion pass, write the human-oversight marker into the frontmatter — insert immediately after the `date:` line:
+
+```yaml
+human-oversight: confirmed
+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`.
+
 ### 6. Handle supersession (if applicable)
 
 If the user mentions this decision replaces an existing one:

package/skills/review-decisions/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: wr-architect:review-decisions
+description: Drain the set of recorded decisions (ADRs) that lack human oversight. Surfaces each unconfirmed ADR's chosen option and alternatives via AskUserQuestion so a human confirms, amends, or rejects the auto-made call, then writes the human-oversight marker. Use when the session-start nudge reports decisions lack oversight, or any time you want to review recorded decisions.
+allowed-tools: Read, Glob, Grep, Bash, Edit, AskUserQuestion
+---
+
+# Review Decisions — human-oversight drain
+
+Lift auto-made architecture decisions to human decisions. Many ADRs were recorded autocratically — the architect proposed an option and it stood without a human picking it. This skill drains the **unoversighted set** (ADRs lacking `human-oversight: confirmed` in frontmatter, per ADR-066): it surfaces each decision's chosen option + the alternatives via `AskUserQuestion`, and writes the oversight marker only when a human confirms.
+
+This is the P283 prong-2 drain surface. It is the eat-our-own-dogfood loop: confirming a decision is itself a human decision, so it goes through `AskUserQuestion`.
+
+## When to use
+
+- The session-start nudge reported `N decisions lack human oversight`.
+- Pre-handover / pre-release: confirm the recorded decision set reflects human intent.
+- After a batch of AFK-recorded ADRs: review what landed without interactive confirmation.
+- Any focused sitting — the drain is designed for **batches over multiple sittings**, not one blocking pass.
+
+## How it works
+
+Each run drains as many ADRs as the user has appetite for, in topic-clustered batches. The marker persists (ADR-009 never-re-ask principle), so a partially-drained set resumes cleanly on the next run.
+
+### Step 1: Enumerate the unoversighted set
+
+Run the detector (token-cheap — grep over frontmatter, no body reads):
+
+```bash
+wr-architect-detect-unoversighted docs/decisions
+```
+
+The `wr-architect-detect-unoversighted` command is a `$PATH`-resolved shim (ADR-049 naming grammar) dispatching `packages/architect/scripts/detect-unoversighted.sh`. It prints one unoversighted ADR path per line (superseded ADRs are excluded — a retired decision needs no confirmation). Empty output → the set is fully drained; report "all recorded decisions carry human oversight" and stop.
+
+### Step 2: Cluster + order
+
+Read **only the frontmatter + title + Decision Outcome** of each unoversighted ADR (not full bodies — keep it cheap). Group by topic cluster (e.g. release-cadence, governance-gates, AFK-orchestration, decision-recording) and order **load-bearing first**: ADRs that other ADRs cite as parents, that are `accepted` (already shipped — highest drift cost if the auto-pick was wrong), or that govern a hook/gate the user interacts with daily. Defer narrow / low-coupling ADRs.
+
+### Step 3: Present each decision via AskUserQuestion (batched)
+
+For each ADR in the ordered queue, surface the decision as an `AskUserQuestion` (cap **4 ADRs per call** per ADR-013 Rule 1; issue further calls sequentially). For each ADR:
+
+- **Question**: the decision the ADR records (its Decision Outcome, in one line).
+- **Context**: the chosen option + the alternatives the ADR considered (grounded in the ADR's Considered Options section per ADR-026), and any cited parent ADRs.
+- **Options** (per ADR):
+  - **Confirm** — the recorded decision is correct; write the marker.
+  - **Amend** — the decision is mostly right but needs a change; capture the change, apply it to the ADR body, then write the marker.
+  - **Reject / supersede** — the auto-made pick is wrong; do NOT write the marker. Note the rework needed (a follow-up `/wr-architect:create-adr` supersede, or a problem ticket).
+  - **Defer** — skip this sitting; leave unoversighted for a later run.
+
+This is a genuine human-decision surface (the whole point of P283) — `AskUserQuestion` is correct here and is NOT over-asking. Do not auto-confirm; do not prose-ask.
+
+### Step 4: Apply the outcome
+
+- **Confirm / Amend**: write `human-oversight: confirmed` + `oversight-date: <today, YYYY-MM-DD>` into the ADR's frontmatter (insert after the `date:` line if absent; never duplicate). For Amend, apply the directed body change first. Both edits go through the standard architect / JTBD edit gate per ADR-014.
+- **Reject / supersede**: leave the marker absent. Record the rework (follow-up create-adr supersede or `/wr-itil:capture-problem`).
+- **Defer**: no write.
+
+### Step 5: Commit + report
+
+Commit the confirmed/amended ADRs per ADR-014 (one commit for the sitting's drained batch is acceptable — the unit of work is "this drain sitting"). Report: how many confirmed / amended / rejected / deferred, and the remaining unoversighted count (re-run the detector). The session-start nudge count drops by the number confirmed.
+
+## Notes
+
+- **Never re-ask** — a confirmed ADR carries the marker permanently and is excluded from future runs (ADR-009 never-re-ask principle). The marker is write-once **except** when an ADR is materially amended after confirmation (the Decision Outcome is rewritten) — a supersede/amend clears it for re-confirmation per ADR-066 Reassessment.
+- **AFK** — this skill is interactive by construction (the confirm IS the human decision). It is not dispatched inside AFK iteration subprocesses; the session-start nudge self-suppresses there (`WR_SUPPRESS_OVERSIGHT_NUDGE=1`) so the drain is never half-run by an absent user.
+- **Born-confirmed going forward** — `/wr-architect:create-adr` writes the marker at its Step 5 confirm, so new ADRs enter the set already oversighted and the unoversighted count only shrinks.
+
+## Related
+
+- **ADR-066** — the oversight marker + this drain skill + the detector + the nudge.
+- **ADR-064** — the architect Needs-Direction verdict; the main agent owns `AskUserQuestion` (this skill is that ownership applied to the existing set).
+- **ADR-009** — never-re-ask persistent-marker principle (the marker, not its TTL/drift lifecycle).
+- **ADR-013 / ADR-044** — structured user interaction + decision-delegation taxonomy.
+- **P283** — driving problem ticket (prong 2).