@windyroad/jtbd 0.8.3-preview.428 → 0.8.4-preview.430

package/.claude-plugin/plugin.json

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

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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.8.3-preview.428",
+  "version": "0.8.4-preview.430",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"

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/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/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