@windyroad/jtbd 0.8.3-preview.374 → 0.8.3-preview.389

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/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/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-preview.374",
+  "version": "0.8.3-preview.389",
   "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/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/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

@@ -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: