@windyroad/jtbd 0.8.3 → 0.8.4-preview.431

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.8.3"
+  "version": "0.8.4"
 }

package/README.md

@@ -33,6 +33,14 @@ The plugin works automatically. On first use in a project without a JTBD directo
 
 This examines your existing features and asks about your user jobs, personas, and desired outcomes to generate `docs/jtbd/<persona>/persona.md` plus per-job files at `docs/jtbd/<persona>/JTBD-NNN-<title>.<status>.md`. If a legacy `docs/JOBS_TO_BE_DONE.md` exists, it is migrated into the directory structure on first run (per [ADR-008](../../docs/decisions/008-jtbd-directory-structure.proposed.md)).
 
+**Confirm jobs and personas that lack human oversight:**
+
+```
+/wr-jtbd:confirm-jobs-and-personas
+```
+
+The `confirm-jobs-and-personas` skill drains the set of jobs/personas that were recorded without a human confirming they reflect real user/business need (per [ADR-068](../../docs/decisions/068-jtbd-persona-human-oversight-marker-and-confirm-drain.proposed.md)). It surfaces each via AskUserQuestion so you confirm, amend, or reject it, then writes a `human-oversight: confirmed` marker. Detection is a token-cheap grep over `docs/jtbd/` frontmatter; a session-start nudge reports the unoversighted count. Jobs/personas created through `update-guide` are born oversighted, so the unconfirmed set only shrinks. This is the read-write oversight drain — distinct from the read-only `/wr-jtbd:review-jobs` alignment reviewer.
+
 ## How It Works
 
 | Hook | Trigger | What it does |
@@ -41,6 +49,7 @@ This examines your existing features and asks about your user jobs, personas, an
 | `jtbd-enforce-edit.sh` | Edit or Write | Blocks edits until the JTBD agent has reviewed |
 | `jtbd-mark-reviewed.sh` | Agent completes | Marks the review as done (TTL: 3600s) |
 | `jtbd-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 |
+| `jtbd-oversight-nudge.sh` | Session start | Reports how many jobs/personas lack human oversight and points to `/wr-jtbd:confirm-jobs-and-personas`; silent when none, and self-suppressed inside AFK iterations |
 
 ## Agent
 
@@ -50,22 +59,6 @@ The `wr-jtbd:agent` reads your `docs/jtbd/` directory and reviews proposed UI ch
 - Persona definitions and constraints
 - Screen-to-job mappings
 
-## 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.
-
-### Solo developer
-
-- **[JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md)** — JTBD review fires automatically on every UI edit; manual review is replaced by an agent reading the persona files the project already maintains.
-
-### 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)** — `/wr-jtbd:review-jobs` produces an on-demand alignment report against documented jobs, attachable to a release note or handover doc.
-
-### 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

@@ -44,6 +44,22 @@ All review criteria come from the JTBD documentation. Read the docs first and ap
 - If the change involves API interactions, do the actions align with the job's expected flow?
 - Are new actions documented in the relevant job's action list?
 
+### Unratified Dependency (build-upon guard — ADR-068 enforcement surface 3)
+
+When the change or plan under review **explicitly cites, implements, or serves** a specific persona or job — an `@jtbd JTBD-NNN` annotation, a `persona: <name>` reference, or it is authoring that artifact's own flow — check whether that persona/job has been **ratified** (carries `human-oversight: confirmed` in its frontmatter) before letting the change stand. You have `Bash`, so run the predicate by **exit code** (you do NOT need to grep frontmatter yourself):
+
+```bash
+wr-jtbd-is-job-or-persona-unconfirmed <persona-name | JTBD-NNN>
+```
+
+- **Exit 0** (frontmatter lacks the marker AND the artifact is not superseded) → the artifact is **unratified**. Emit **ISSUES FOUND / [Unratified Dependency]** with action: "ratify `<persona | JTBD-NNN>` via `/wr-jtbd:confirm-jobs-and-personas` before this lands." (The predicate prints the resolved path on stdout.)
+- **Exit 1** (ratified, or superseded) → do NOT flag.
+- **Exit 2** (ref not found) → the change cites a persona/job that does not exist; that is a separate Job Gap / Persona Mismatch, not an Unratified Dependency.
+
+**Key the flag on the oversight marker, NEVER on `status:`.** `status: proposed`/`accepted` and `human-oversight:` are orthogonal axes (ADR-066). Building on a **ratified** job whose `status` is still `proposed` is fine — do NOT flag it; only the *unratified* (marker-absent, non-superseded) case flags.
+
+**Bound to explicit cite/implement — NOT ambient alignment.** You already match every change to a job ID for the PASS verdict (see Job Alignment above); the `[Unratified Dependency]` flag must NOT fire on that mere match — only on an **explicit** dependency the change names. This is the inverse-P078 / P132 over-fire guard. Note: the JTBD unratified set is currently large (the P288 drain is in progress), so unlike the architect surface this will fire more often until that drain completes — that is the intended forcing function, not noise. The `developer`-persona jobs still pending the P288 drain (e.g. `JTBD-001`) are the canonical first-fire cases — the `developer` persona itself was ratified via P289.
+
 ## Output Formatting
 
 When referencing JTBD IDs, problem IDs (P<NNN>), or ADR IDs in prose output, always include the human-readable title on first mention. Use the format `JTBD-001 (Enforce Governance Without Slowing Down)`, not bare `JTBD-001`.
@@ -59,11 +75,11 @@ If there are misalignments or gaps:
 
 > **JTBD Review: ISSUES FOUND**
 >
-> 1. **[Job Gap / Persona Mismatch / Missing Annotation]**
+> 1. **[Job Gap / Persona Mismatch / Missing Annotation / Unratified Dependency]**
 >    - **File**: `path`, Line ~N
->    - **Issue**: What is misaligned
+>    - **Issue**: What is misaligned (for **Unratified Dependency**: the change builds on `<persona | JTBD-NNN>` which lacks `human-oversight: confirmed`)
 >    - **Job**: Which job is affected (or "no matching job")
->    - **Fix**: Suggested resolution (update JTBD doc, adjust UI, add annotation)
+>    - **Fix**: Suggested resolution (update JTBD doc, adjust UI, add annotation; for **Unratified Dependency**: ratify via `/wr-jtbd:confirm-jobs-and-personas` before this lands)
 >
 > 2. ...
 

package/agents/test/jtbd-unratified-dependency-verdict.bats

@@ -0,0 +1,62 @@
+#!/usr/bin/env bats
+# Doc-lint guard: jtbd agent.md must carry the [Unratified Dependency] verdict
+# (ADR-068 enforcement surface 3 / RFC-011 / P323) — flag a change or plan that
+# explicitly cites/implements/serves a persona or job lacking `human-oversight:
+# confirmed` (unratified, non-superseded), keyed on the oversight marker NOT
+# `status:`. The JTBD twin of the architect side's surface 3 (RFC-010 / P318).
+#
+# 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). When P176 lands, upgrade to a behavioural test that
+# feeds the agent a change citing an unratified persona/job and asserts the
+# verdict. The single-artifact predicate IS behaviourally tested today — see
+# packages/jtbd/scripts/test/is-job-or-persona-unconfirmed.bats.
+#
+# Cross-reference:
+#   ADR-068 (JTBD oversight marker + drain — surface 3 amendment 2026-05-27)
+#   ADR-074 (Confirm a decision's substance before building dependent work)
+#   ADR-066 (oversight marker; orthogonal status/oversight axes)
+#   RFC-011 / P323 (this enforcement surface); RFC-010 / P318 (the ADR-side twin)
+#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
+#   @jtbd JTBD-202 (pre-flight governance checks) / JTBD-101 (extend the suite)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md lists [Unratified Dependency] as a verdict/issue type (ADR-068 surface 3)" {
+  run grep -n '\[Unratified Dependency\]' "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md has an 'Unratified Dependency (build-upon guard' section citing ADR-068" {
+  run grep -niE "Unratified Dependency \(build-upon guard" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "ADR-068" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md keys the flag on the oversight marker, NOT on status (orthogonal axes)" {
+  # ADR-066 / user correction 2026-05-27: building on a ratified-but-proposed job is fine.
+  run grep -niE "NEVER on .?status|not .?\`?status|orthogonal" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md invokes the predicate by exit code (the jtbd agent has Bash; not a prose-grep mirror)" {
+  run grep -n "wr-jtbd-is-job-or-persona-unconfirmed" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "exit code|exit 0|exit 1" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md guards against over-firing on ambient alignment (inverse-P078 / explicit cite)" {
+  run grep -niE "explicit(ly)? cite|ambient alignment|over-?fire|NOT fire on that mere match" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md routes the fix to /wr-jtbd:confirm-jobs-and-personas (the surface-2 drain)" {
+  run grep -n "/wr-jtbd:confirm-jobs-and-personas" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/bin/wr-jtbd-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/bin/wr-jtbd-is-job-or-persona-unconfirmed

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

package/hooks/hooks.json

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

package/hooks/jtbd-oversight-nudge.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# wr-jtbd — SessionStart hook (ADR-068)
+#
+# Surfaces a one-line nudge when jobs/personas lack the human-oversight marker,
+# so the user can drain them via /wr-jtbd:confirm-jobs-and-personas. Sibling of
+# packages/architect/hooks/architect-oversight-nudge.sh (ADR-066); same shape as
+# the ADR-040 session-start surface.
+#
+# Detection is token-cheap: delegates to detect-unoversighted.sh (a grep over
+# docs/jtbd/ frontmatter — no body reads, no per-file LLM call). Silent when the
+# unoversighted count is zero (steady state once the set is drained).
+#
+# AFK self-suppress: shares the suite-wide WR_SUPPRESS_OVERSIGHT_NUDGE guard with
+# the architect oversight nudge (ADR-068 § shared cross-plugin contracts). AFK
+# orchestrators export it once (work-problems Step 5) and every oversight nudge
+# self-suppresses — so this interactive batch-confirm nudge never fires into an
+# absent-user subprocess (JTBD-006 friction guard). Only the literal "1" suppresses.
+
+set -euo pipefail
+
+if [ "${WR_SUPPRESS_OVERSIGHT_NUDGE:-}" = "1" ]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+JTBD_DIR="$PROJECT_DIR/docs/jtbd"
+
+[ -d "$JTBD_DIR" ] || exit 0
+
+DETECT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/scripts/detect-unoversighted.sh"
+[ -x "$DETECT" ] || DETECT="$(dirname "$0")/../scripts/detect-unoversighted.sh"
+
+COUNT="$(bash "$DETECT" "$JTBD_DIR" 2>/dev/null | grep -c . || true)"
+COUNT="${COUNT:-0}"
+
+[ "$COUNT" -gt 0 ] 2>/dev/null || exit 0
+
+if [ "$COUNT" -eq 1 ]; then
+  echo "[wr-jtbd] 1 job/persona lacks human oversight — run /wr-jtbd:confirm-jobs-and-personas to confirm it."
+else
+  echo "[wr-jtbd] $COUNT jobs/personas lack human oversight — run /wr-jtbd:confirm-jobs-and-personas to confirm them."
+fi

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env bats
+
+# ADR-068: jtbd-oversight-nudge.sh (SessionStart) emits a one-line nudge when
+# jobs/personas lack the human-oversight marker, is silent when none do, and
+# self-suppresses under the shared AFK guard (WR_SUPPRESS_OVERSIGHT_NUDGE=1).
+# Behavioural — exercises the hook against fixture docs/jtbd/ trees.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/jtbd/hooks/jtbd-oversight-nudge.sh"
+  PLUGIN_ROOT="$REPO_ROOT/packages/jtbd"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/jtbd/solo-developer"
+}
+
+teardown() { rm -rf "$DIR"; }
+
+mk_unmarked() {
+  mkdir -p "$(dirname "$DIR/docs/jtbd/$1")"
+  { echo "---"; echo "status: proposed"; echo "date-created: 2026-05-25"; echo "---"; echo "# $1"; } \
+    > "$DIR/docs/jtbd/$1"
+}
+mk_marked() {
+  mkdir -p "$(dirname "$DIR/docs/jtbd/$1")"
+  { echo "---"; echo "status: proposed"; echo "human-oversight: confirmed"; echo "---"; echo "# $1"; } \
+    > "$DIR/docs/jtbd/$1"
+}
+
+@test "emits a count line when there are unoversighted jobs/personas" {
+  mk_unmarked "solo-developer/persona.md"
+  mk_unmarked "solo-developer/JTBD-001-foo.proposed.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"2 jobs/personas lack human oversight"* ]]
+  [[ "$output" == *"/wr-jtbd:confirm-jobs-and-personas"* ]]
+}
+
+@test "uses singular wording for exactly one unoversighted artifact" {
+  mk_unmarked "solo-developer/persona.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [[ "$output" == *"1 job/persona lacks human oversight"* ]]
+}
+
+@test "silent when every job/persona is confirmed" {
+  mk_marked "solo-developer/persona.md"
+  run env CLAUDE_PROJECT_DIR="$DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "shared AFK guard suppresses the nudge entirely" {
+  mk_unmarked "solo-developer/persona.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 "solo-developer/persona.md"
+  mk_unmarked "solo-developer/JTBD-001-foo.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/jtbd 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/jtbd",
-  "version": "0.8.3",
+  "version": "0.8.4-preview.431",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
+    "scripts/",
     ".claude-plugin/",
     "lib/"
   ]

package/scripts/detect-unoversighted.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# wr-jtbd — detect jobs/personas lacking the human-oversight marker (ADR-068)
+#
+# @jtbd JTBD-202 (Run Pre-Flight Governance Checks — oversight state of the JTBD corpus)
+# @jtbd JTBD-101 (Extend the Suite with New Plugins — reusable adopter-portable primitive)
+#
+# Sibling of packages/architect/scripts/detect-unoversighted.sh (ADR-066). Token-cheap:
+# greps each job/persona's YAML frontmatter for `human-oversight: confirmed`. No body
+# reads, no per-file LLM call. A file is "unoversighted" when its frontmatter does not
+# carry that marker (or has no frontmatter).
+#
+# Usage:
+#   detect-unoversighted.sh [JTBD_DIR]
+#     JTBD_DIR defaults to docs/jtbd
+#
+# Output: one unoversighted job/persona file path per line, sorted. Empty output = the
+# whole set is confirmed. Always exits 0 (it is a detector, not a gate).
+#
+# Consumed by: jtbd-oversight-nudge.sh (SessionStart count) and
+# /wr-jtbd:confirm-jobs-and-personas (the drain list). Marker contract: ADR-068 (= ADR-066 field).
+
+set -euo pipefail
+
+JTBD_DIR="${1:-docs/jtbd}"
+[ -d "$JTBD_DIR" ] || exit 0
+
+# JTBD layout (ADR-008): docs/jtbd/<persona>/persona.md + docs/jtbd/<persona>/JTBD-NNN-*.md,
+# with docs/jtbd/README.md as the top-level index. Match the per-persona files; README is
+# never a job/persona record.
+shopt -s nullglob
+for f in "$JTBD_DIR"/*/*.md "$JTBD_DIR"/*.md; do
+  base="$(basename "$f")"
+  [ "$base" = "README.md" ] && continue
+  # Superseded artifacts (if an adopter uses a .superseded.md suffix) are retired.
+  case "$base" in *.superseded.md) continue ;; esac
+
+  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/is-job-or-persona-unconfirmed.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# wr-jtbd — predicate: is a referenced persona or job unconfirmed? (ADR-068 surface 3)
+#
+# Single-artifact sibling of detect-unoversighted.sh (ADR-068). Where the
+# detector LISTS the whole unoversighted set and always exits 0, this answers
+# ONE question for ONE persona/job via its EXIT CODE — for the build-upon guard
+# the wr-jtbd:agent runs (the [Unratified Dependency] verdict, RFC-011 / P323).
+# The JTBD twin of packages/architect/scripts/is-decision-unconfirmed.sh
+# (ADR-074). A separate script (not a mode flag on the detector) keeps the
+# detector's "always exit 0, path-list on stdout" contract intact.
+#
+# "Unconfirmed" mirrors detect-unoversighted.sh EXACTLY:
+#   - the artifact's frontmatter lacks `human-oversight: confirmed`, AND
+#   - the artifact 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-job-or-persona-unconfirmed.bats fails if these two drift.
+#
+# Usage:
+#   is-job-or-persona-unconfirmed.sh <ref> [JTBD_DIR]
+#     <ref> = JTBD-NNN | NNN | <persona-name> | path/to/<file>.md
+#     JTBD_DIR defaults to docs/jtbd
+#
+# Ref resolution (ADR-008 layout: docs/jtbd/<persona>/persona.md +
+# docs/jtbd/<persona>/JTBD-NNN-*.md):
+#   - a path to an existing file        → that file
+#   - JTBD-NNN or a bare NNN            → docs/jtbd/*/JTBD-NNN-*.md (first match)
+#   - anything else (a persona name)   → docs/jtbd/<name>/persona.md
+#
+# 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:-}"
+JTBD_DIR="${2:-docs/jtbd}"
+
+[ -n "$REF" ] || { echo "is-job-or-persona-unconfirmed: missing <ref>" >&2; exit 2; }
+
+# ── Resolve the persona/job file ──────────────────────────────────────────
+file=""
+if [ -f "$REF" ]; then
+  file="$REF"
+elif printf '%s' "$REF" | grep -qiE 'JTBD-?[0-9]+|^[0-9]+$'; then
+  # Job ref: JTBD-NNN or a bare numeric. Match the per-persona job file.
+  num="$(printf '%s' "$REF" | grep -oE '[0-9]+' | head -1)"
+  [ -n "$num" ] || { echo "is-job-or-persona-unconfirmed: cannot parse job id from '$REF'" >&2; exit 2; }
+  shopt -s nullglob
+  for cand in "$JTBD_DIR"/*/JTBD-"$num"-*.md "$JTBD_DIR"/*/"$num"-*.md; do
+    file="$cand"; break
+  done
+  shopt -u nullglob
+else
+  # Persona-name ref → the persona's persona.md.
+  cand="$JTBD_DIR/$REF/persona.md"
+  [ -f "$cand" ] && file="$cand"
+fi
+
+[ -n "$file" ] && [ -f "$file" ] || {
+  echo "is-job-or-persona-unconfirmed: no persona/job file for '$REF' under $JTBD_DIR" >&2
+  exit 2
+}
+
+base="$(basename "$file")"
+
+# Superseded artifacts are retired — a newer job/persona replaced them. The
+# build-upon guard does not fire (mirror of detect-unoversighted.sh's 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/detect-unoversighted.bats

@@ -0,0 +1,85 @@
+#!/usr/bin/env bats
+
+# ADR-068: detect-unoversighted.sh prints jobs/personas whose frontmatter lacks the
+# `human-oversight: confirmed` marker. Behavioural — exercises the script against
+# fixture docs/jtbd/<persona>/ trees and asserts on stdout.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/jtbd/scripts/detect-unoversighted.sh"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/jtbd/solo-developer"
+}
+
+teardown() { rm -rf "$DIR"; }
+
+mk() { # mk <relpath under docs/jtbd> <extra frontmatter lines...>
+  local rel="$1"; shift
+  mkdir -p "$(dirname "$DIR/docs/jtbd/$rel")"
+  {
+    echo "---"
+    echo "status: proposed"
+    echo "date-created: 2026-05-25"
+    for line in "$@"; do echo "$line"; done
+    echo "---"
+    echo "# $rel"
+  } > "$DIR/docs/jtbd/$rel"
+}
+
+@test "a job without the marker is reported" {
+  mk "solo-developer/JTBD-001-foo.proposed.md"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"JTBD-001-foo.proposed.md"* ]]
+}
+
+@test "a persona file without the marker is reported" {
+  mk "solo-developer/persona.md"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" == *"solo-developer/persona.md"* ]]
+}
+
+@test "a job carrying human-oversight: confirmed is NOT reported" {
+  mk "solo-developer/JTBD-002-bar.proposed.md" "human-oversight: confirmed" "oversight-date: 2026-05-25"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" != *"JTBD-002-bar.proposed.md"* ]]
+}
+
+@test "the top-level docs/jtbd/README.md is never reported" {
+  echo "# JTBD index" > "$DIR/docs/jtbd/README.md"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" != *"README.md"* ]]
+}
+
+@test "a per-persona README is also excluded" {
+  echo "# persona index" > "$DIR/docs/jtbd/solo-developer/README.md"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" != *"README.md"* ]]
+}
+
+@test "a file with no frontmatter counts as unoversighted" {
+  mkdir -p "$DIR/docs/jtbd/tech-lead"
+  echo "# bare persona, no frontmatter" > "$DIR/docs/jtbd/tech-lead/persona.md"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" == *"tech-lead/persona.md"* ]]
+}
+
+@test "marker match is case-insensitive and tolerant of trailing space" {
+  mk "solo-developer/JTBD-003-baz.proposed.md" "human-oversight:   confirmed   "
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [[ "$output" != *"JTBD-003-baz.proposed.md"* ]]
+}
+
+@test "missing jtbd dir exits 0 with no output" {
+  run bash "$SCRIPT" "$DIR/docs/nonexistent"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "fully-confirmed corpus produces empty output" {
+  mk "solo-developer/persona.md" "human-oversight: confirmed"
+  mk "solo-developer/JTBD-001-foo.proposed.md" "human-oversight: confirmed"
+  run bash "$SCRIPT" "$DIR/docs/jtbd"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/scripts/test/is-job-or-persona-unconfirmed.bats

@@ -0,0 +1,126 @@
+#!/usr/bin/env bats
+
+# ADR-068 surface 3 / RFC-011 / P323: is-job-or-persona-unconfirmed.sh is the
+# single-artifact predicate for the JTBD build-upon guard (the wr-jtbd:agent
+# [Unratified Dependency] verdict). It answers "is this referenced persona or
+# job unconfirmed?" via its EXIT CODE, where "unconfirmed" mirrors
+# detect-unoversighted.sh EXACTLY (frontmatter lacks `human-oversight:
+# confirmed`, and the artifact is not superseded). The JTBD twin of the
+# architect side's is-decision-unconfirmed.sh (ADR-074).
+#
+# 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/jtbd/scripts/is-job-or-persona-unconfirmed.sh"
+  DETECT="$REPO_ROOT/packages/jtbd/scripts/detect-unoversighted.sh"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/docs/jtbd"
+}
+
+teardown() {
+  rm -rf "$DIR"
+}
+
+# mk_persona <persona-name> <confirmed?yes|no>
+mk_persona() {
+  local name="$1"; local confirmed="$2"
+  mkdir -p "$DIR/docs/jtbd/$name"
+  {
+    echo "---"
+    echo "name: $name"
+    echo "description: test persona $name"
+    [ "$confirmed" = "yes" ] && { echo "human-oversight: confirmed"; echo "oversight-date: 2026-05-27"; }
+    echo "---"
+    echo "# $name"
+  } > "$DIR/docs/jtbd/$name/persona.md"
+}
+
+# mk_job <persona-name> <NNN> <slug> <confirmed?yes|no> [state]
+mk_job() {
+  local persona="$1"; local num="$2"; local slug="$3"; local confirmed="$4"; local state="${5:-proposed}"
+  mkdir -p "$DIR/docs/jtbd/$persona"
+  {
+    echo "---"
+    echo "status: $state"
+    echo "job-id: $slug"
+    echo "persona: $persona"
+    [ "$confirmed" = "yes" ] && { echo "human-oversight: confirmed"; echo "oversight-date: 2026-05-27"; }
+    echo "---"
+    echo "# $slug"
+  } > "$DIR/docs/jtbd/$persona/JTBD-$num-$slug.md"
+}
+
+@test "persona without the marker is unconfirmed (exit 0, prints path)" {
+  mk_persona "solo-developer" "no"
+  run bash "$SCRIPT" "solo-developer" "$DIR/docs/jtbd"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"solo-developer/persona.md"* ]]
+}
+
+@test "persona carrying human-oversight: confirmed is confirmed (exit 1, no stdout)" {
+  mk_persona "tech-lead" "yes"
+  run bash "$SCRIPT" "tech-lead" "$DIR/docs/jtbd"
+  [ "$status" -eq 1 ]
+  [ -z "$output" ]
+}
+
+@test "job (JTBD-NNN) without the marker is unconfirmed (exit 0, prints path)" {
+  mk_job "solo-developer" "001" "enforce-governance" "no"
+  run bash "$SCRIPT" "JTBD-001" "$DIR/docs/jtbd"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"JTBD-001-enforce-governance.md"* ]]
+}
+
+@test "job carrying the marker is confirmed (exit 1)" {
+  mk_job "tech-lead" "201" "restore-service-fast" "yes"
+  run bash "$SCRIPT" "JTBD-201" "$DIR/docs/jtbd"
+  [ "$status" -eq 1 ]
+}
+
+@test "superseded job (even without marker) does NOT fire the guard (exit 1)" {
+  mkdir -p "$DIR/docs/jtbd/solo-developer"
+  {
+    echo "---"; echo "status: superseded"; echo "persona: solo-developer"; echo "---"; echo "# retired"
+  } > "$DIR/docs/jtbd/solo-developer/JTBD-009-retired.superseded.md"
+  run bash "$SCRIPT" "JTBD-009" "$DIR/docs/jtbd"
+  [ "$status" -eq 1 ]
+}
+
+@test "a bare numeric job ref resolves" {
+  mk_job "solo-developer" "002" "ship-with-confidence" "no"
+  run bash "$SCRIPT" "002" "$DIR/docs/jtbd"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"JTBD-002-ship-with-confidence.md"* ]]
+}
+
+@test "a direct path ref resolves" {
+  mk_persona "plugin-user" "no"
+  run bash "$SCRIPT" "$DIR/docs/jtbd/plugin-user/persona.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "an unknown persona name exits 2 (not found)" {
+  run bash "$SCRIPT" "ghost-persona" "$DIR/docs/jtbd"
+  [ "$status" -eq 2 ]
+}
+
+@test "an unknown job ref exits 2 (not found)" {
+  run bash "$SCRIPT" "JTBD-999" "$DIR/docs/jtbd"
+  [ "$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_persona "solo-developer" "no"
+  mk_persona "tech-lead" "yes"
+  detect_out="$(bash "$DETECT" "$DIR/docs/jtbd")"
+  # solo-developer is in the detector's unoversighted list AND the predicate exits 0.
+  [[ "$detect_out" == *"solo-developer/persona.md"* ]]
+  run bash "$SCRIPT" "solo-developer" "$DIR/docs/jtbd"; [ "$status" -eq 0 ]
+  # tech-lead is NOT in the detector's list AND the predicate exits 1.
+  [[ "$detect_out" != *"tech-lead/persona.md"* ]]
+  run bash "$SCRIPT" "tech-lead" "$DIR/docs/jtbd"; [ "$status" -eq 1 ]
+}

package/skills/confirm-jobs-and-personas/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: wr-jtbd:confirm-jobs-and-personas
+description: Drain the set of Jobs To Be Done and personas that lack human oversight. Surfaces each auto-derived job/persona via AskUserQuestion so a human confirms, amends, or rejects it, then writes the human-oversight marker. Use when the session-start nudge reports jobs/personas lack oversight, or any time you want to review the documented JTBD corpus. This is the read-write oversight drain — distinct from /wr-jtbd:review-jobs (the read-only alignment reviewer).
+allowed-tools: Read, Glob, Grep, Bash, Edit, AskUserQuestion
+---
+
+# Confirm Jobs and Personas — human-oversight drain
+
+Lift auto-derived Jobs To Be Done and personas to human decisions. Documented jobs/personas are load-bearing: the JTBD edit gate reviews every project change against `docs/jtbd/`, so a job or persona that was agent-derived without a human confirming it reflects real need propagates wrong alignment verdicts. This skill drains the **unoversighted set** (jobs/personas lacking `human-oversight: confirmed`, per ADR-068): it surfaces each via `AskUserQuestion`, and writes the oversight marker only when a human confirms.
+
+This is the P288 / ADR-068 drain surface — the JTBD sibling of `/wr-architect:review-decisions`. It is **read-write** (writes the marker on confirm). It is NOT the same as `/wr-jtbd:review-jobs`, which is a read-only alignment review ("do my changes trace to documented jobs?"); this skill confirms the jobs/personas themselves.
+
+## When to use
+
+- The session-start nudge reported `N jobs/personas lack human oversight`.
+- Pre-handover / pre-release: confirm the JTBD corpus reflects real user/business need.
+- After an `update-guide` run or agent-derived job/persona authoring landed files without confirmation.
+- Any focused sitting — designed for **batches over multiple sittings**, not one blocking pass.
+
+## How it works
+
+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
+
+```bash
+wr-jtbd-detect-unoversighted docs/jtbd
+```
+
+The `wr-jtbd-detect-unoversighted` command is a `$PATH`-resolved shim (ADR-049) dispatching `packages/jtbd/scripts/detect-unoversighted.sh`. It prints one unoversighted job/persona path per line (README excluded; token-cheap grep over frontmatter — no body reads). Empty output → the corpus is fully confirmed; report and stop.
+
+### Step 2: Cluster + order
+
+Read **only the frontmatter + title + Job Statement / persona "Who" section** of each unoversighted file (not full bodies — keep it cheap). Group by persona directory and order **load-bearing first**: personas before their jobs (a persona frames its jobs), and jobs that other artifacts (problems, RFCs, READMEs) cite most heavily before narrow ones.
+
+### Step 3: Present each via AskUserQuestion (batched)
+
+For each job/persona in the ordered queue, surface it as an `AskUserQuestion` (cap **4 per call** per ADR-013 Rule 1; issue further calls sequentially):
+
+- **Question**: the job statement (for a JTBD) or the persona definition (who they are + key constraints), in one line.
+- **Context**: grounded in what the file actually says (per ADR-026) — the persona served, the desired outcomes, any cited problems/RFCs.
+- **Options** per artifact:
+  - **Confirm** — the job/persona accurately reflects real need; write the marker.
+  - **Amend** — mostly right but needs a change; capture it, apply it to the file, then write the marker.
+  - **Reject** — the auto-derived job/persona does not reflect real need; do NOT write the marker. Note the rework (a `wr-jtbd:update-guide` rewrite, or retirement).
+  - **Defer** — skip this sitting; leave unoversighted for later.
+
+This is a genuine human-decision surface (the point of P288/ADR-068) — `AskUserQuestion` is correct here, 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 file's frontmatter (insert after the `status:`/`date-created:` line if absent; never duplicate). For Amend, apply the directed change first. Edits go through the standard JTBD / architect edit gate per ADR-014.
+- **Reject**: leave the marker absent; record the rework.
+- **Defer**: no write.
+
+**Unoversighted ≠ unusable** (ADR-068): an unconfirmed job/persona stays fully readable and review-anchorable. The marker records provenance; it never quarantines the doc or blocks reviews from reading it.
+
+### Step 5: Commit + report
+
+Commit the confirmed/amended files per ADR-014 (one commit per drain sitting is acceptable). Report: confirmed / amended / rejected / deferred counts, 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 job/persona carries the marker permanently and is excluded from future runs (ADR-009). Write-once **except** when the job statement / persona definition is materially rewritten — a material amend clears the marker for re-confirmation (ADR-068 Reassessment).
+- **AFK** — interactive by construction (the confirm IS the human decision); not dispatched in AFK iteration subprocesses. The session-start nudge self-suppresses there (`WR_SUPPRESS_OVERSIGHT_NUDGE=1`).
+- **Born-confirmed going forward** — `/wr-jtbd:update-guide` writes the marker when the user confirms a new/edited job or persona, so new artifacts enter the set already oversighted and the unoversighted count only shrinks.
+
+## Related
+
+- **ADR-068** — this drain + the marker + detector + nudge. **ADR-066 / P283** — the architect precedent this mirrors.
+- **ADR-008** — JTBD directory structure (the marker is additive to its frontmatter contract).
+- **ADR-009** — never-re-ask persistent-marker principle. **ADR-013 / ADR-044** — structured user interaction + decision-delegation taxonomy.
+- `packages/jtbd/skills/review-jobs/SKILL.md` — the read-only alignment reviewer (distinct from this drain).
+- `packages/jtbd/skills/update-guide/SKILL.md` — born-confirmed write site.

package/skills/update-guide/SKILL.md

@@ -80,7 +80,7 @@ description: <one-line description>
 <bullet list of frustrations this product addresses>
 ```
 
-Use kebab-case for the directory name (e.g., `solo-developer`, `tech-lead`).
+Use kebab-case for the directory name (e.g., `developer`, `tech-lead`).
 
 ### 4. Confirm personas with the user
 
@@ -89,6 +89,15 @@ 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:
+
+```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.
+
 ### 5. Draft jobs
 
 For each job (3-8 per persona), create a file at
@@ -135,6 +144,15 @@ 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:
+
+```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`.
+
 ### 7. Generate README.md index
 
 Write `docs/jtbd/README.md` with tables grouping jobs by persona and status: