@windyroad/jtbd 0.11.0-preview.521 → 0.12.0

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.11.0"
+  "version": "0.12.0"
 }

package/bin/wr-jtbd-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/hooks.json

@@ -7,7 +7,8 @@
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-eval.sh" }] }
     ],
     "PreToolUse": [
-      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-enforce-edit.sh" }] }
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-enforce-edit.sh" }] },
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-oversight-marker-discipline.sh" }] }
     ],
     "PostToolUse": [
       { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/jtbd-mark-reviewed.sh" }] },

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# jtbd-oversight-marker-discipline.sh — PreToolUse:Edit|Write hook
+# (P348 / ADR-068 amendment 2026-06-02). JTBD-side sibling of
+# architect-oversight-marker-discipline.sh. Denies Edit/Write operations
+# that introduce `human-oversight: confirmed` into a docs/jtbd/ artefact's
+# (persona.md or JTBD-NNN-*.md) frontmatter unless a session-scoped
+# evidence marker proves the user has substance-confirmed THAT specific
+# artefact via AskUserQuestion.
+#
+# P348 captured AFK iter subprocesses silently writing `human-oversight:
+# confirmed` without any user confirmation event. ADR-068 mirrors ADR-066's
+# marker contract on the JTBD/persona surface, and JTBD-006's audit-trail
+# outcome + JTBD-201/202's auditability constraints depend on the marker
+# being honest. This hook is the structural guard.
+#
+# 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/jtbd/
+#   - file not a `.md` (README, etc.)
+#   - basename README.md
+#   - the Edit/Write does NOT introduce `human-oversight: confirmed`
+#   - the session-scoped marker `/tmp/oversight-confirmed-<sha>-<sid>`
+#     exists for THIS specific JTBD/persona path under THIS session
+#
+# Deny path (PreToolUse deny JSON, hook exit 0):
+#   - all of: docs/jtbd/**/*.md, the change introduces
+#     `human-oversight: confirmed`, AND no matching marker for this
+#     artefact under this session
+#
+# Recovery (mechanical per ADR-013 Rule 1):
+#   The SKILL flow that hosts the substance-confirm AskUserQuestion calls
+#   `wr-jtbd-mark-oversight-confirmed <jtbd-or-persona-path>` immediately
+#   after the user's answer lands. AFK iter subprocesses MUST instead write
+#   `human-oversight: unconfirmed` (new enum value per ADR-068 amendment
+#   2026-06-02), which the drain (/wr-jtbd:confirm-jobs-and-personas)
+#   later promotes interactively.
+#
+# @adr ADR-068 (JTBD/persona human-oversight marker)
+# @adr ADR-066 (parent contract — architect surface)
+# @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=""
+
+case "$TOOL_NAME" in
+  Edit|Write) ;;
+  *) exit 0 ;;
+esac
+
+[ -n "$FILE_PATH" ] || exit 0
+[ -n "$SESSION_ID" ] || exit 0
+
+case "$FILE_PATH" in
+  /*)
+    case "$FILE_PATH" in
+      "$PWD"/*) ;;
+      *) exit 0 ;;
+    esac
+    ;;
+esac
+
+# Scope: docs/jtbd/**/*.md. Personas live at docs/jtbd/<persona>/persona.md;
+# jobs live at docs/jtbd/<persona>/JTBD-NNN-*.md. Both are valid targets.
+case "$FILE_PATH" in
+  */docs/jtbd/*.md|docs/jtbd/*.md) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+case "$BASENAME" in
+  README.md) exit 0 ;;
+esac
+
+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
+
+MARKER_RE='^[[:space:]]*human-oversight:[[:space:]]*confirmed[[:space:]]*$'
+
+if ! echo "$NEW_CONTENT" | grep -qiE "$MARKER_RE"; then
+  exit 0
+fi
+
+if [ -n "$OLD_CONTENT" ] && echo "$OLD_CONTENT" | grep -qiE "$MARKER_RE"; then
+  exit 0
+fi
+
+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
+  exit 0
+fi
+
+MARKER_DIR="${SESSION_MARKER_DIR:-/tmp}"
+MARKER="$MARKER_DIR/oversight-confirmed-${PATH_HASH}-${SESSION_ID}"
+
+if [ -f "$MARKER" ]; then
+  exit 0
+fi
+
+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 JTBD/persona in this session (P348 / ADR-068). The marker '/tmp/oversight-confirmed-<sha>-<sid>' is written by 'wr-jtbd-mark-oversight-confirmed <artefact-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-jtbd:confirm-jobs-and-personas) will promote it interactively. To recover this Edit/Write: surface the substance-confirm AskUserQuestion to the user, call wr-jtbd-mark-oversight-confirmed with this artefact's path, then retry."
+  }
+}
+EOF
+exit 0

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

@@ -0,0 +1,184 @@
+#!/usr/bin/env bats
+
+# P348 / ADR-068 amendment 2026-06-02: jtbd-oversight-marker-discipline.sh
+# is the JTBD-side sibling of architect-oversight-marker-discipline.sh.
+# Denies Edit/Write that introduces `human-oversight: confirmed` into a
+# docs/jtbd/ artefact's frontmatter unless a session-scoped evidence marker
+# proves the user has substance-confirmed THAT artefact.
+#
+# Behavioural — exercises the hook with constructed PreToolUse stdin JSON
+# payloads under SESSION_MARKER_DIR sandboxing.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/jtbd/hooks/jtbd-oversight-marker-discipline.sh"
+  MARK_SCRIPT="$REPO_ROOT/packages/jtbd/scripts/mark-oversight-confirmed.sh"
+
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/jtbd/developer"
+  MARK_DIR="$(mktemp -d)"
+  export SESSION_MARKER_DIR="$MARK_DIR"
+
+  ORIG_DIR="$PWD"
+  cd "$DIR"
+
+  SID="jtbd-discipline-test-$$"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$DIR" "$MARK_DIR"
+  unset SESSION_MARKER_DIR
+}
+
+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_artefact() {
+  local subpath="$1"; shift
+  local dir
+  dir="$(dirname "$DIR/docs/jtbd/$subpath")"
+  mkdir -p "$dir"
+  {
+    echo "---"
+    echo "status: \"proposed\""
+    echo "date: 2026-06-02"
+    for line in "$@"; do echo "$line"; done
+    echo "---"
+    echo "# $(basename "$subpath" .md)"
+  } > "$DIR/docs/jtbd/$subpath"
+}
+
+# ── Positive paths ───────────────────────────────────────────────────────
+
+@test "Write introducing 'human-oversight: confirmed' to a JTBD with marker present is allowed" {
+  mk_existing_artefact "developer/JTBD-300-test.proposed.md"
+  art="$DIR/docs/jtbd/developer/JTBD-300-test.proposed.md"
+  : > "$(expected_marker "$art")"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# JTBD-300\n'
+  json=$(jq -nc --arg p "$art" --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 to a persona introducing the marker with evidence is allowed" {
+  mk_existing_artefact "developer/persona.md"
+  art="$DIR/docs/jtbd/developer/persona.md"
+  : > "$(expected_marker "$art")"
+  old='date: 2026-06-02'
+  new=$'date: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02'
+  json=$(jq -nc --arg p "$art" --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 ───────────────────────────────────────────────────────
+
+@test "Write introducing 'human-oversight: confirmed' to a JTBD WITHOUT marker is denied" {
+  mk_existing_artefact "developer/JTBD-310-orphan.proposed.md"
+  art="$DIR/docs/jtbd/developer/JTBD-310-orphan.proposed.md"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# JTBD-310\n'
+  json=$(jq -nc --arg p "$art" --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" == *"wr-jtbd-mark-oversight-confirmed"* ]]
+  [[ "$output" == *"/wr-jtbd:confirm-jobs-and-personas"* ]]
+}
+
+@test "Edit introducing the marker to persona WITHOUT marker is denied" {
+  mk_existing_artefact "tech-lead/persona.md"
+  art="$DIR/docs/jtbd/tech-lead/persona.md"
+  old='date: 2026-06-02'
+  new=$'date: 2026-06-02\nhuman-oversight: confirmed'
+  json=$(jq -nc --arg p "$art" --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 ────────────────────────────────────────────────
+
+@test "Write introducing 'human-oversight: unconfirmed' is allowed without marker (AFK path)" {
+  mk_existing_artefact "developer/JTBD-320-afk.proposed.md"
+  art="$DIR/docs/jtbd/developer/JTBD-320-afk.proposed.md"
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: unconfirmed\n---\n\n# JTBD-320-afk\n'
+  json=$(jq -nc --arg p "$art" --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-JTBD path exits 0 silently even with the marker line" {
+  mkdir -p "$DIR/src"
+  echo "// stub" > "$DIR/src/foo.ts"
+  json=$(jq -nc --arg p "$DIR/src/foo.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/jtbd/README.md exits 0 silently" {
+  echo "# index" > "$DIR/docs/jtbd/README.md"
+  art="$DIR/docs/jtbd/README.md"
+  new=$'# index\nhuman-oversight: confirmed'
+  json=$(jq -nc --arg p "$art" --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_artefact "developer/JTBD-330-rename.proposed.md"
+  art="$DIR/docs/jtbd/developer/JTBD-330-rename.proposed.md"
+  json=$(jq -nc --arg p "$art" --arg s "$SID" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:"# JTBD-330-rename",new_string:"# JTBD-330 renamed"}}')
+  run bash -c "echo '$(echo "$json" | sed "s/'/'\\\\''/g")' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── End-to-end ───────────────────────────────────────────────────────────
+
+@test "mark-oversight-confirmed.sh writes a marker that satisfies the JTBD hook" {
+  mk_existing_artefact "developer/JTBD-340-e2e.proposed.md"
+  art="$DIR/docs/jtbd/developer/JTBD-340-e2e.proposed.md"
+  : > "$MARK_DIR/jtbd-announced-$SID"
+  bash "$MARK_SCRIPT" "$art"
+  [ -f "$(expected_marker "$art")" ]
+  new_content=$'---\nstatus: "proposed"\ndate: 2026-06-02\nhuman-oversight: confirmed\noversight-date: 2026-06-02\n---\n\n# JTBD-340-e2e\n'
+  json=$(jq -nc --arg p "$art" --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 "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/jtbd",
-  "version": "0.11.0-preview.521",
+  "version": "0.12.0",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"

package/scripts/mark-oversight-confirmed.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# wr-jtbd — mark a JTBD/persona's human-oversight: confirmed marker write as
+# user-substance-confirmed (P348 / ADR-068 amendment 2026-06-02).
+#
+# JTBD-side sibling of packages/architect/scripts/mark-oversight-confirmed.sh.
+# Companion to jtbd-oversight-marker-discipline.sh (also P348). SKILLs invoke
+# this script AFTER an AskUserQuestion lands the user's substance-confirm
+# answer for a specific job or persona; the script writes the evidence marker
+# that the hook reads to permit the subsequent Edit/Write that introduces
+# `human-oversight: confirmed` into that artefact's frontmatter.
+#
+# Why the marker is required:
+#   ADR-068 mirrors ADR-066's `human-oversight: confirmed` marker contract on
+#   the JTBD/persona surface. P348 captured iter subprocesses silently
+#   writing the `confirmed` value without a user confirmation event,
+#   contradicting JTBD-006's audit-trail outcome and JTBD-201/202's
+#   auditability persona constraints. The hook enforces the boundary
+#   structurally; this script is the evidence-write side that legitimate
+#   substance-confirm flows use.
+#
+# AFK iter subprocesses with no AskUserQuestion access MUST write
+# `human-oversight: unconfirmed` instead (the new enum value codified in
+# ADR-068 amendment 2026-06-02), which the drain
+# (/wr-jtbd:confirm-jobs-and-personas) later promotes.
+#
+# Marker convention:
+#   /tmp/oversight-confirmed-<sha256-of-path>-<session-id>
+#   Shared marker namespace with the architect hook — both hooks consume the
+#   same marker file shape. Written under EVERY recent candidate session SID
+#   per ADR-050 Option C.
+#
+# Usage:
+#   wr-jtbd-mark-oversight-confirmed <artefact-path>
+#     <artefact-path> — the JTBD or persona file path the user just
+#                       substance-confirmed.
+#
+# Exit codes:
+#   0 — marker(s) written for at least one candidate SID, OR no candidate
+#       SID was discoverable (cold-path: no announce markers yet).
+#   2 — bad argument (missing or empty artefact-path).
+#
+# @adr ADR-068 (JTBD/persona 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-jtbd-mark-oversight-confirmed: missing <artefact-path>" >&2
+  exit 2
+fi
+
+# Normalize to absolute path so the hash is stable regardless of CWD.
+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 — sha256, first 16 hex chars. Portable across macOS (shasum) and
+# Linux (sha256sum / shasum).
+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-jtbd-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. Inlined for plugin self-containment (no cross-
+# plugin lib source — jtbd must not depend on architect-internal helpers
+# per ADR-002 plugin packaging).
+candidates=$(
+  {
+    if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+      echo "$CLAUDE_SESSION_ID"
+    fi
+    find "$MARKER_DIR" -maxdepth 1 -name '*-announced-*' -mmin "-${WINDOW_MINS}" 2>/dev/null \
+      | sed 's|.*/||; s/.*-announced-//'
+  } | awk 'NF && !seen[$0]++'
+)
+
+[ -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/update-guide/SKILL.md

@@ -89,14 +89,18 @@ Use AskUserQuestion to present the drafted personas and ask:
 - Any missing user segments?
 - Any constraints or pain points to add?
 
-**Born-confirmed write (ADR-068).** Once the user confirms a persona via this AskUserQuestion pass, write the human-oversight marker into that persona's frontmatter — insert after the `description:` line:
+**Born-confirmed write (ADR-068 — structurally gated by P348 amendment 2026-06-02).** Once the user confirms a persona via this AskUserQuestion pass, IMMEDIATELY call the marker-evidence helper THEN insert the two lines into that persona's frontmatter — after the `description:` line:
+
+```bash
+wr-jtbd-mark-oversight-confirmed docs/jtbd/<persona-name>/persona.md
+```
 
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-This is the born-confirmed gate: a persona authored through update-guide enters the world already human-oversighted (it does not appear in `/wr-jtbd:confirm-jobs-and-personas`' unoversighted set). Do NOT write the marker for a persona the user has not confirmed. The marker is orthogonal to status.
+The `wr-jtbd-mark-oversight-confirmed` call writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `jtbd-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. This is the load-bearing born-confirmed gate: a persona authored through update-guide enters the world human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a persona the user has not confirmed. AFK iter subprocesses spawned via `claude -p` have no `AskUserQuestion` access; they MUST write `human-oversight: unconfirmed` (the AFK fallback enum value codified in ADR-068 amendment 2026-06-02), which the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes interactively. The marker is orthogonal to status.
 
 ### 5. Draft jobs
 
@@ -144,14 +148,18 @@ Use AskUserQuestion to present the drafted jobs and ask:
 - Do the job statements ring true?
 - Any missing jobs or user flows?
 
-**Born-confirmed write (ADR-068).** Once the user confirms a job via this AskUserQuestion pass, write the human-oversight marker into that job's frontmatter — insert after the `date-created:` line:
+**Born-confirmed write (ADR-068 — structurally gated by P348 amendment 2026-06-02).** Once the user confirms a job via this AskUserQuestion pass, IMMEDIATELY call the marker-evidence helper THEN insert the two lines into that job's frontmatter — after the `date-created:` line:
+
+```bash
+wr-jtbd-mark-oversight-confirmed docs/jtbd/<persona-name>/JTBD-NNN-<kebab-title>.proposed.md
+```
 
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-A job authored through update-guide is born human-oversighted, so the `/wr-jtbd:confirm-jobs-and-personas` unoversighted set only ever shrinks. Do NOT write the marker for a job the user has not confirmed (drafted-but-unconfirmed jobs stay unmarked). The marker is orthogonal to `status:` — a `proposed` job can be `human-oversight: confirmed`.
+Without the `wr-jtbd-mark-oversight-confirmed` call, the `jtbd-oversight-marker-discipline.sh` PreToolUse hook will DENY the marker write. A job authored through update-guide is born human-oversighted ONLY because the helper above paired the user's substance-confirm answer to the marker write. Do NOT write the marker for a job the user has not confirmed. AFK iter subprocesses MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-068 amendment 2026-06-02); the drain (`/wr-jtbd:confirm-jobs-and-personas`) later promotes it interactively. The marker is orthogonal to `status:`.
 
 ### 7. Generate README.md index