@windyroad/architect 0.14.1-preview.521 → 0.15.0

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.14.1"
+  "version": "0.15.0"
 }

package/bin/wr-architect-mark-oversight-confirmed

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/mark-oversight-confirmed.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/mark-oversight-confirmed.sh" "$@"

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

@@ -0,0 +1,163 @@
+#!/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
+# 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.
+#
+# P348 captured AFK iter subprocesses silently writing `human-oversight:
+# confirmed` without any user confirmation event — contradicting ADR-066's
+# write-once-permanent-on-substance-confirm contract and JTBD-006's audit-
+# trail outcome. This hook is the structural guard. The discipline-prose
+# already in /wr-architect:create-adr (substance-confirm at Step 5,
+# P340-tightened by ADR-066 Amendment 2026-05-31) is the SKILL-level
+# expression; this hook elevates it to a structurally enforced boundary
+# AFK iter subprocesses cannot bypass.
+#
+# Allow paths (exit 0 silently per ADR-045 Pattern 1):
+#   - tool_name not Edit|Write
+#   - file outside the project root (P004)
+#   - file not under docs/decisions/
+#   - file not a `.md` (README, changelogs, etc.)
+#   - the Edit/Write does NOT introduce the literal frontmatter line
+#     `human-oversight: confirmed` (e.g. introduces `unconfirmed` or
+#     `rejected-pending-supersede`, leaves the marker untouched, etc.)
+#   - the session-scoped marker `/tmp/oversight-confirmed-<sha>-<sid>`
+#     exists for THIS specific ADR path under THIS session ID
+#
+# Deny path (PreToolUse deny JSON, hook exit 0):
+#   - all of: docs/decisions/*.md, the change introduces
+#     `human-oversight: confirmed`, AND no matching marker for this ADR
+#     under this session
+#
+# Recovery (mechanical per ADR-013 Rule 1):
+#   The SKILL flow that hosts the substance-confirm AskUserQuestion calls
+#   `wr-architect-mark-oversight-confirmed <adr-path>` immediately after
+#   the user's answer lands. The next Edit/Write of that ADR is then
+#   allowed. AFK iter subprocesses MUST instead write
+#   `human-oversight: unconfirmed` (new enum value per ADR-066 amendment
+#   2026-06-02), which the drain (/wr-architect:review-decisions) later
+#   promotes interactively.
+#
+# Resolution (ADR-049 amended): PATH-shim grammar — the SKILL invokes
+# `wr-architect-mark-oversight-confirmed`, which resolves through the
+# highest-version-wins shim wrapper.
+#
+# @adr ADR-066 (human-oversight marker — write-once-permanent contract)
+# @adr ADR-068 (sibling JTBD/persona contract)
+# @adr ADR-049 (PATH shim resolution for invocation)
+# @adr ADR-050 (multi-SID candidate enumeration for marker write)
+# @adr ADR-045 (Pattern 1 silent-on-pass PreToolUse)
+# @adr ADR-013 (Rule 6 fail-safe-defer in non-interactive contexts)
+# @problem P348 (iter subprocesses set human-oversight: confirmed without user event)
+
+set -uo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || TOOL_NAME=""
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || FILE_PATH=""
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null) || SESSION_ID=""
+
+# Tool gate: only Edit and Write.
+case "$TOOL_NAME" in
+  Edit|Write) ;;
+  *) exit 0 ;;
+esac
+
+# Missing inputs — allow (fail-open is acceptable here because the
+# architect-enforce-edit gate is the outer perimeter that catches missing
+# session_id with fail-closed deny; this discipline is a refinement).
+[ -n "$FILE_PATH" ] || exit 0
+[ -n "$SESSION_ID" ] || exit 0
+
+# P004: only gate files inside the project root.
+case "$FILE_PATH" in
+  /*)
+    case "$FILE_PATH" in
+      "$PWD"/*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
+# Scope: only docs/decisions/<NNN>-*.md and per-state subdir layouts.
+case "$FILE_PATH" in
+  */docs/decisions/*.md|docs/decisions/*.md) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+# Skip README + non-ADR auxiliary files.
+case "$BASENAME" in
+  README.md) exit 0 ;;
+esac
+
+# Extract the candidate new-content. For Write, that's the full
+# `tool_input.content`. For Edit, that's `tool_input.new_string`.
+case "$TOOL_NAME" in
+  Write)
+    NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null) || NEW_CONTENT=""
+    OLD_CONTENT=""
+    if [ -f "$FILE_PATH" ]; then
+      OLD_CONTENT=$(cat "$FILE_PATH" 2>/dev/null) || OLD_CONTENT=""
+    fi
+    ;;
+  Edit)
+    NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null) || NEW_CONTENT=""
+    OLD_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.old_string // empty' 2>/dev/null) || OLD_CONTENT=""
+    ;;
+esac
+
+# Does the new content introduce `human-oversight: confirmed`?
+# Token-cheap grep — single literal line, case-insensitive, tolerant of
+# trailing whitespace (mirroring detect-unoversighted.sh's match grammar).
+MARKER_RE='^[[:space:]]*human-oversight:[[:space:]]*confirmed[[:space:]]*$'
+
+if ! echo "$NEW_CONTENT" | grep -qiE "$MARKER_RE"; then
+  exit 0  # new content does not contain the confirmed marker → allow
+fi
+
+# If the OLD content already had the marker, this Edit/Write is not
+# INTRODUCING it (could be reformatting or a no-op on this line). Allow.
+if [ -n "$OLD_CONTENT" ] && echo "$OLD_CONTENT" | grep -qiE "$MARKER_RE"; then
+  exit 0
+fi
+
+# Now we know: the change INTRODUCES `human-oversight: confirmed`. Require
+# the session-scoped evidence marker for THIS ADR's absolute path.
+abs_dir=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd) || abs_dir=""
+if [ -n "$abs_dir" ]; then
+  ABS_PATH="$abs_dir/$(basename "$FILE_PATH")"
+else
+  ABS_PATH="$FILE_PATH"
+fi
+
+if command -v sha256sum >/dev/null 2>&1; then
+  PATH_HASH=$(printf '%s' "$ABS_PATH" | sha256sum | cut -d' ' -f1 | cut -c1-16)
+elif command -v shasum >/dev/null 2>&1; then
+  PATH_HASH=$(printf '%s' "$ABS_PATH" | shasum -a 256 | cut -d' ' -f1 | cut -c1-16)
+else
+  # No hashing tool available — fail-open. Unrealistic on macOS/Linux but
+  # do not block the user over an environment edge case.
+  exit 0
+fi
+
+MARKER_DIR="${SESSION_MARKER_DIR:-/tmp}"
+MARKER="$MARKER_DIR/oversight-confirmed-${PATH_HASH}-${SESSION_ID}"
+
+if [ -f "$MARKER" ]; then
+  exit 0  # evidence present → allow
+fi
+
+# Deny.
+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."
+  }
+}
+EOF
+exit 0

package/hooks/hooks.json

@@ -8,6 +8,7 @@
     ],
     "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-compendium-refresh-discipline.sh" }] }
     ],

package/hooks/test/architect-oversight-marker-discipline.bats

@@ -0,0 +1,210 @@
+#!/usr/bin/env bats
+
+# P348 / ADR-066 amendment 2026-06-02: architect-oversight-marker-discipline.sh
+# is a PreToolUse:Edit|Write hook that denies any Edit/Write that introduces
+# `human-oversight: confirmed` into a docs/decisions/ ADR's frontmatter unless
+# a session-scoped evidence marker `/tmp/oversight-confirmed-<sha>-<sid>`
+# exists for THAT specific ADR under THIS session.
+#
+# Behavioural — exercises the hook with constructed PreToolUse stdin JSON
+# payloads under SESSION_MARKER_DIR sandboxing, asserts on stdout+exit.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/architect/hooks/architect-oversight-marker-discipline.sh"
+  MARK_SCRIPT="$REPO_ROOT/packages/architect/scripts/mark-oversight-confirmed.sh"
+
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/decisions"
+  MARK_DIR="$(mktemp -d)"
+  export SESSION_MARKER_DIR="$MARK_DIR"
+
+  ORIG_DIR="$PWD"
+  cd "$DIR"
+
+  SID="discipline-test-$$"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$DIR" "$MARK_DIR"
+  unset SESSION_MARKER_DIR
+}
+
+# Helper: compute the marker path the hook expects for an ADR file.
+expected_marker() {
+  local f="$1"
+  local abs_dir abs path_hash
+  abs_dir="$(cd "$(dirname "$f")" && pwd)"
+  abs="$abs_dir/$(basename "$f")"
+  if command -v sha256sum >/dev/null 2>&1; then
+    path_hash=$(printf '%s' "$abs" | sha256sum | cut -d' ' -f1 | cut -c1-16)
+  else
+    path_hash=$(printf '%s' "$abs" | shasum -a 256 | cut -d' ' -f1 | cut -c1-16)
+  fi
+  printf '%s/oversight-confirmed-%s-%s\n' "$MARK_DIR" "$path_hash" "$SID"
+}
+
+mk_existing_adr() {
+  local name="$1"; shift
+  {
+    echo "---"
+    echo "status: \"proposed\""
+    echo "date: 2026-06-02"
+    for line in "$@"; do echo "$line"; done
+    echo "---"
+    echo "# $name"
+  } > "$DIR/docs/decisions/$name"
+}
+
+# ── Positive paths (marker present → allow) ──────────────────────────────
+
+@test "Write introducing 'human-oversight: confirmed' with marker present is allowed" {
+  mk_existing_adr "200-unconfirmed.proposed.md"
+  adr="$DIR/docs/decisions/200-unconfirmed.proposed.md"
+  : > "$(expected_marker "$adr")"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# 200-unconfirmed\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "Edit introducing 'human-oversight: confirmed' with marker present is allowed" {
+  mk_existing_adr "201-pending.proposed.md"
+  adr="$DIR/docs/decisions/201-pending.proposed.md"
+  : > "$(expected_marker "$adr")"
+  old='date: 2026-06-02'
+  new=$'date: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Negative paths (no marker → deny) ───────────────────────────────────
+
+@test "Write introducing 'human-oversight: confirmed' WITHOUT marker is denied" {
+  mk_existing_adr "210-orphan.proposed.md"
+  adr="$DIR/docs/decisions/210-orphan.proposed.md"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# 210-orphan\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *'"permissionDecision": "deny"'* ]]
+  [[ "$output" == *"BLOCKED"* ]]
+  [[ "$output" == *"oversight-confirmed-"* ]]
+  [[ "$output" == *"wr-architect-mark-oversight-confirmed"* ]]
+}
+
+@test "Edit introducing 'human-oversight: confirmed' WITHOUT marker is denied" {
+  mk_existing_adr "211-no-evidence.proposed.md"
+  adr="$DIR/docs/decisions/211-no-evidence.proposed.md"
+  old='date: 2026-06-02'
+  new=$'date: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [[ "$output" == *'"permissionDecision": "deny"'* ]]
+}
+
+# ── AFK-unconfirmed-write path (no marker required) ──────────────────────
+
+@test "Write introducing 'human-oversight: unconfirmed' is allowed without marker (AFK path)" {
+  mk_existing_adr "220-afk.proposed.md"
+  adr="$DIR/docs/decisions/220-afk.proposed.md"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: unconfirmed\n---\n\n# 220-afk\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "Write introducing rejected-pending-supersede is allowed without marker" {
+  mk_existing_adr "221-rejected.proposed.md"
+  adr="$DIR/docs/decisions/221-rejected.proposed.md"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: rejected-pending-supersede\nsupersede-ticket: P999\n---\n\n# 221-rejected\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Scope / non-fire paths ────────────────────────────────────────────────
+
+@test "Edit to a non-ADR path (src/index.ts) exits 0 silently" {
+  mkdir -p "$DIR/src"
+  echo "// stub" > "$DIR/src/index.ts"
+  json=$(jq -nc --arg p "$DIR/src/index.ts" --arg s "$SID" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:"// stub",new_string:"// human-oversight: confirmed"}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "Edit to docs/decisions/README.md exits 0 silently" {
+  echo "# index" > "$DIR/docs/decisions/README.md"
+  adr="$DIR/docs/decisions/README.md"
+  new=$'# index\nhuman-oversight: confirmed'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:"# index",new_string:$n}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "Edit whose new content lacks the marker exits 0 silently" {
+  mk_existing_adr "230-unrelated.proposed.md"
+  adr="$DIR/docs/decisions/230-unrelated.proposed.md"
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:"# 230-unrelated",new_string:"# 230 renamed"}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "Write whose OLD content already had the marker (re-stamp / no-op) is allowed without re-evidencing" {
+  # Pre-existing ADR already carries the marker; new content keeps it.
+  mk_existing_adr "240-already.proposed.md" "human-oversight: confirmed" "oversight-date: 2026-05-30"
+  adr="$DIR/docs/decisions/240-already.proposed.md"
+  new_content=$'---\nstatus: "accepted"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-05-30\n---\n\n# 240-already\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── End-to-end: mark-oversight-confirmed.sh + the hook ──────────────────
+
+@test "mark-oversight-confirmed.sh writes a marker that satisfies the hook" {
+  mk_existing_adr "250-e2e.proposed.md"
+  adr="$DIR/docs/decisions/250-e2e.proposed.md"
+  # Seed an announce marker so candidate enumeration finds the SID.
+  : > "$MARK_DIR/architect-announced-$SID"
+  bash "$MARK_SCRIPT" "$adr"
+  # The mark script writes under every candidate; the hook's expected marker
+  # filename for our SID must now exist.
+  [ -f "$(expected_marker "$adr")" ]
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# 250-e2e\n'
+  json=$(jq -nc --arg p "$adr" --arg s "$SID" --arg c "$new_content" \
+    '{tool_name:"Write",session_id:$s,tool_input:{file_path:$p,content:$c}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Non-Edit/Write tool calls always exit 0 silently ────────────────────
+
+@test "tool_name=Bash exits 0 silently regardless of file path" {
+  json=$(jq -nc --arg s "$SID" \
+    '{tool_name:"Bash",session_id:$s,tool_input:{command:"echo human-oversight: confirmed"}}')
+  run bash -c "echo '$json' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/package.json

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

package/scripts/mark-oversight-confirmed.sh

@@ -0,0 +1,108 @@
+#!/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).
+#
+# Companion to the architect-oversight-marker-discipline.sh PreToolUse hook
+# (also P348). SKILLs invoke this script AFTER an AskUserQuestion lands the
+# user's substance-confirm answer for a specific ADR; the script writes the
+# evidence marker that the hook reads to permit the subsequent Edit/Write
+# that introduces `human-oversight: confirmed` into that ADR's frontmatter.
+#
+# Why the marker is required:
+#   ADR-066 establishes that `human-oversight: confirmed` is a write-once-
+#   permanent durable record. ADR-074 + P340 tighten the substance-confirm
+#   semantics: the marker MAY ONLY land in response to a user answer that
+#   selects a specific option. AFK iter subprocesses have no AskUserQuestion
+#   access (ADR-013 Rule 6 fail-safe-defer territory), so they MUST NOT write
+#   the `confirmed` value — they write `human-oversight: unconfirmed` instead,
+#   which the drain (/wr-architect:review-decisions) later promotes. The hook
+#   enforces the boundary structurally; this script is the evidence-write
+#   side that legitimate substance-confirm flows use.
+#
+# Marker convention:
+#   /tmp/oversight-confirmed-<sha256-of-path>-<session-id>
+#   Written under EVERY recent candidate session SID per ADR-050 Option C
+#   (concurrent orchestrator + subprocess sessions in the same project, the
+#   per-machine runtime-sid marker is last-writer-wins). The PreToolUse hook
+#   reads the SID from its stdin JSON; marking under every candidate
+#   guarantees a matching marker exists whichever SID the hook reads.
+#
+# Usage:
+#   wr-architect-mark-oversight-confirmed <artefact-path>
+#     <artefact-path> — the ADR file path the user just substance-confirmed.
+#                       The script computes sha256 of the absolute path.
+#
+# Exit codes:
+#   0 — marker(s) written for at least one candidate SID, OR no candidate
+#       SID was discoverable (cold-path: no announce markers yet). The
+#       latter is a no-op so SKILL flows do not crash before any hook has
+#       fired in the session.
+#   2 — bad argument (missing or empty artefact-path).
+#
+# @adr ADR-066 (human-oversight marker)
+# @adr ADR-049 (PATH shim grammar)
+# @adr ADR-050 (multi-SID candidate enumeration)
+# @adr ADR-013 (Rule 6 fail-safe-defer in non-interactive contexts)
+# @problem P348 (iter subprocesses set human-oversight: confirmed without user event)
+
+set -uo pipefail
+
+ARTEFACT_PATH="${1:-}"
+
+if [ -z "$ARTEFACT_PATH" ]; then
+  echo "wr-architect-mark-oversight-confirmed: missing <artefact-path>" >&2
+  exit 2
+fi
+
+# Normalize to absolute path so the hash is stable regardless of CWD.
+# `cd $(dirname)` works whether the file exists or not (basename + abs dir).
+abs_dir="$(cd "$(dirname "$ARTEFACT_PATH")" 2>/dev/null && pwd)" || abs_dir=""
+if [ -n "$abs_dir" ]; then
+  ABS_PATH="$abs_dir/$(basename "$ARTEFACT_PATH")"
+else
+  ABS_PATH="$ARTEFACT_PATH"
+fi
+
+# Path hash — use shasum/sha256sum portably (macOS ships shasum; Linux usually
+# has both). First 16 hex chars are plenty for unique marker filenames.
+if command -v sha256sum >/dev/null 2>&1; then
+  PATH_HASH=$(printf '%s' "$ABS_PATH" | sha256sum | cut -d' ' -f1 | cut -c1-16)
+elif command -v shasum >/dev/null 2>&1; then
+  PATH_HASH=$(printf '%s' "$ABS_PATH" | shasum -a 256 | cut -d' ' -f1 | cut -c1-16)
+else
+  echo "wr-architect-mark-oversight-confirmed: no sha256 tool available" >&2
+  exit 2
+fi
+
+MARKER_DIR="${SESSION_MARKER_DIR:-/tmp}"
+WINDOW_MINS="${SESSION_CANDIDATE_WINDOW_MINS:-1440}"
+
+# Candidate SID enumeration — recent announce markers across all systems
+# within the mtime window. Mirrors get_candidate_session_ids in
+# packages/itil/hooks/lib/session-id.sh; inlined here so this script is
+# self-contained (no cross-plugin lib source — architect must not depend on
+# itil-internal helpers per ADR-002 plugin packaging).
+candidates=$(
+  {
+    # Env-var fast path. Not exported in agent contexts today, but if a
+    # future Claude Code release adds it, this branch picks it up for free.
+    if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+      echo "$CLAUDE_SESSION_ID"
+    fi
+    # Recent announce markers.
+    find "$MARKER_DIR" -maxdepth 1 -name '*-announced-*' -mmin "-${WINDOW_MINS}" 2>/dev/null \
+      | sed 's|.*/||; s/.*-announced-//'
+  } | awk 'NF && !seen[$0]++'
+)
+
+# No candidate SID — cold path. Exit 0 so SKILL flows do not crash before any
+# hook has fired this session. The subsequent Write deny will naturally
+# surface the missing-marker case to the agent.
+[ -n "$candidates" ] || exit 0
+
+while IFS= read -r sid; do
+  [ -n "$sid" ] || continue
+  : > "$MARKER_DIR/oversight-confirmed-${PATH_HASH}-${sid}"
+done <<< "$candidates"
+
+exit 0

package/skills/capture-adr/SKILL.md

@@ -73,6 +73,7 @@ Log the renumber decision in the operation report if origin and local diverged.
 ---
 status: "proposed"
 date: <YYYY-MM-DD>
+human-oversight: unconfirmed
 decision-makers: [unspecified — fill at canonical review]
 consulted: []
 informed: []
@@ -180,6 +181,8 @@ The trailing pointer is **not optional** — it is the user-visible signal that
 
 **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).
 
+**Oversight marker discipline (ADR-066 amendment 2026-06-02 / P348).** A capture-adr skeleton MUST be born `human-oversight: unconfirmed` — NOT `confirmed`. Capture is the AFK-friendly aside surface; there is no substance-confirm `AskUserQuestion` 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 skeleton (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 the canonical-expansion path (`/wr-architect:create-adr <NNN>`) are the surfaces that legitimately promote it to `confirmed` via `wr-architect-mark-oversight-confirmed` + the gated marker write.
+
 ## Composition with create-adr
 
 | Concern | create-adr | capture-adr |

package/skills/create-adr/SKILL.md

@@ -225,13 +225,19 @@ options:
   - ...one entry per considered option
 ```
 
-**Born-confirmed marker write (ADR-066 — tightened by P340 amendment).** 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, insert immediately after the `date:` line:
+**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:
+
+```bash
+wr-architect-mark-oversight-confirmed docs/decisions/<NNN>-<slug>.proposed.md
+```
 
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
+The `wr-architect-mark-oversight-confirmed` 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 `AskUserQuestion` 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 `AskUserQuestion` answer in the same turn.
+
 **Mismatch handling.** If the substance-confirm answer selects a DIFFERENT option than the draft was authored against:
 
 - DO NOT write the marker.