@windyroad/itil 0.47.8 → 0.47.9-preview.552

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.47.8"
+  "version": "0.47.9"
 }

package/bin/wr-itil-check-ticket-jtbd-ratification

@@ -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/check-ticket-jtbd-ratification.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/check-ticket-jtbd-ratification.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.47.8",
+  "version": "0.47.9-preview.552",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/check-ticket-jtbd-ratification.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# wr-itil — predicate: are the JTBDs cited by a problem ticket all ratified?
+# (RFC-016 / P344 — orchestrator-layer mirror of ADR-068 surface 3)
+#
+# `/wr-itil:work-problems` Step 3.5 invokes this script on the selected
+# ticket BEFORE dispatching the iter-subprocess. The per-iter JTBD review
+# subagent already catches the same class via the [Unratified Dependency]
+# verdict (ADR-068 surface 3), but only AFTER spending iter-dispatch cost.
+# This script shifts the predicate left to the orchestrator layer for the
+# cost of one grep + one shim call per cited JTBD.
+#
+# Polarity (RFC-016 § Scope — outer-script polarity INVERTED vs the inner
+# per-JTBD predicate it dispatches):
+#   exit 0 = all cited JTBDs ratified OR ticket cites none → orchestrator
+#            proceeds with the dispatch. No stdout.
+#   exit 1 = ≥1 cited JTBD unratified → orchestrator routes to Step 4
+#            user-answerable skip + queues outstanding_question.
+#            One ID per stdout line; `JTBD-NNN (unresolved)` for IDs whose
+#            per-JTBD predicate returned exit 2 (no matching file).
+#   exit 2 = ticket file missing / unreadable. No stdout; reason on stderr.
+#
+# Silent-pass on missing per-JTBD shim: when `wr-jtbd-is-job-or-persona-
+# unconfirmed` is not on PATH (degenerate adopter case per ADR-031 —
+# adopter installed @windyroad/itil without @windyroad/jtbd), the script
+# silent-passes (exit 0). The iter-subprocess JTBD subagent is the
+# authoritative second-source; orchestrator-layer pre-check is optimisation.
+#
+# Usage:
+#   check-ticket-jtbd-ratification.sh <ticket-file> [JTBD_DIR]
+#     <ticket-file> = path to a problem-ticket .md file (relative or absolute)
+#     JTBD_DIR defaults to docs/jtbd
+#
+# @rfc RFC-016 (P344 — work-problems Step 3.5 JTBD ratification predicate)
+# @adr ADR-068 (JTBD + persona human-oversight marker — surface 3 mirrored)
+# @adr ADR-074 (substance-confirm-before-build — JTBD-as-driver symmetric)
+# @adr ADR-049 (PATH shim grammar)
+# @problem P344
+
+set -uo pipefail
+
+TICKET="${1:-}"
+JTBD_DIR="${2:-docs/jtbd}"
+
+[ -n "$TICKET" ] || {
+  echo "check-ticket-jtbd-ratification: missing <ticket-file>" >&2
+  exit 2
+}
+
+[ -f "$TICKET" ] || {
+  echo "check-ticket-jtbd-ratification: no such ticket file: $TICKET" >&2
+  exit 2
+}
+
+# ADR-031 silent-pass: if the per-JTBD predicate shim is absent, the
+# orchestrator-layer pre-check cannot run. The iter-subprocess JTBD
+# subagent will catch any unratified-dep at the inner layer; this script
+# is the optimisation surface, not the authoritative gate.
+if ! command -v wr-jtbd-is-job-or-persona-unconfirmed >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Extract cited JTBD IDs from the ticket body. Match `JTBD-NNN` (with or
+# without leading zero) — the canonical citation form across Decision
+# Drivers / **JTBD**: frontmatter / **Persona**: references. Dedupe so
+# the same JTBD cited multiple times only runs the predicate once.
+cited="$(grep -oE 'JTBD-[0-9]+' "$TICKET" 2>/dev/null | sort -u || true)"
+
+[ -n "$cited" ] || exit 0   # vacuous-pass: no JTBDs cited at all
+
+unratified=""
+while IFS= read -r jtbd_id; do
+  [ -n "$jtbd_id" ] || continue
+  # Call the inner per-JTBD predicate. INNER POLARITY:
+  #   inner exit 0 = unconfirmed (build-upon guard SHOULD fire) → unratified
+  #   inner exit 1 = confirmed or superseded → ratified
+  #   inner exit 2 = not found / unparseable ref → unresolved
+  wr-jtbd-is-job-or-persona-unconfirmed "$jtbd_id" "$JTBD_DIR" >/dev/null 2>&1
+  inner_status=$?
+  case $inner_status in
+    0) unratified="${unratified}${jtbd_id}"$'\n' ;;
+    1) ;;   # ratified — silent
+    2) unratified="${unratified}${jtbd_id} (unresolved)"$'\n' ;;
+    *) unratified="${unratified}${jtbd_id} (predicate error: exit ${inner_status})"$'\n' ;;
+  esac
+done <<< "$cited"
+
+if [ -n "$unratified" ]; then
+  printf '%s' "$unratified"
+  exit 1
+fi
+
+exit 0

package/skills/work-problems/SKILL.md

@@ -292,6 +292,35 @@ Within the highest non-empty tier, select the problem with the highest WSJF scor
 
 The full selection order is therefore: **tier** (Critical-bypass → Inbound-reported → Internal), then the within-tier ladder `(WSJF desc, Known-Error-first, Effort-divisor asc, Reported-date asc, ID asc)`. <!-- REPORTED-FIRST-TIER-SOURCE: /wr-itil:work-problems SKILL.md Step 3 (ADR-076) -->
 
+### Step 3.5: JTBD ratification predicate-check (per RFC-016 / P344)
+
+After Step 3 selects a candidate ticket and before Step 4 classifies it for dispatch, predicate-check the cited JTBDs of the selected ticket. The per-iter JTBD review subagent (ADR-068 surface 3 — the `[Unratified Dependency]` verdict) catches the same class INSIDE the iter subprocess, but only after spending iter-dispatch cost (~$3-5 + 5-10 min per skip). This step shifts the predicate left to the orchestrator layer for the cost of one grep + per-JTBD shim call — analogous to how Step 0b pre-flights inbound-discovery staleness rather than letting iters discover it. Driving exemplar: 2026-05-31 session 9 iter 5 dispatched P082 against unratified JTBD-001 + JTBD-006; the iter correctly skipped per ADR-074 substance-confirm-before-build, but the per-dispatch cost was wasted.
+
+**Mechanism:**
+
+```bash
+wr-itil-check-ticket-jtbd-ratification "<selected-ticket-path>"
+predicate_exit=$?
+```
+
+`wr-itil-check-ticket-jtbd-ratification` is the ADR-049 / ADR-080 `$PATH` shim that dispatches `packages/itil/scripts/check-ticket-jtbd-ratification.sh`. The script extracts cited `JTBD-NNN` IDs from the ticket body (Decision Drivers / `**JTBD**:` / `**Persona**:` references) and delegates per-JTBD ratification to `wr-jtbd-is-job-or-persona-unconfirmed` (the ADR-068 surface 3 single-artifact predicate). Polarity is INVERTED vs the inner predicate — the outer script answers "are all cited JTBDs ratified?" rather than "is THIS one unconfirmed?". Behavioural contract asserted by `test/work-problems-step-3-5-jtbd-ratification-predicate.bats`.
+
+Exit-code routing:
+
+| `predicate_exit` | Meaning | Action |
+|---|---|---|
+| `0` | All cited JTBDs ratified, OR ticket cites no JTBDs, OR per-JTBD shim missing (ADR-031 silent-pass) | Proceed to Step 4 normally — the ticket is dispatchable. |
+| `1` | ≥1 cited JTBD unratified (or unresolved) — IDs on stdout, one per line; `JTBD-NNN (unresolved)` for inner exit-2 cases | Route the ticket to Step 4's user-answerable skip path (`skip_reason_category: user-answerable`). Queue an `outstanding_questions` entry (`category: "direction"`) naming the unratified JTBDs + ticket ID + remedy: *"Run `/wr-jtbd:confirm-jobs-and-personas` to ratify the cited jobs/personas, then re-invoke `/wr-itil:work-problems`."* Loop back to Step 3 to re-run the tier-first selection over the remaining backlog minus the skipped ticket. |
+| `2` | Ticket file missing / unreadable | Halt the loop with the structured Prior-Session State report — this is the same shape as the README-reconciliation Exit 2 halt at Step 0 (deeper repair needed, not mechanical reconciliation). |
+
+**Loopback tier preservation**: re-run the Step 3 tier-first selection over the remaining backlog minus the skipped ticket. Tier order (Critical-bypass → Inbound-reported → Internal) and within-tier WSJF ladder are preserved per ADR-076. If every actionable ticket is filtered out by Step 3.5, Step 2 stop-condition #1 (no actionable problems) fires naturally and the accumulated `outstanding_questions` entries surface at Step 2.4 gate (a) per the existing batched-`AskUserQuestion` contract.
+
+**Why orchestrator-layer, not iter-layer**: the inner per-iter JTBD subagent stays in place (defence-in-depth — the iter-layer is the authoritative second-source, not a replacement surface). The orchestrator predicate is the optimisation: cheap pre-check eliminates wasted dispatch when the answer is knowable from a `grep` + frontmatter read. The two surfaces are not redundant — they cover different failure modes (orchestrator: shift-left cost optimisation; iter: substance-confirm-before-build governance gate per ADR-074). When the orchestrator silent-passes (predicate-exit 0 via missing-shim degenerate case per ADR-031), the iter-layer still catches any unratified-dep correctly.
+
+**AFK authorisation per ADR-013 Rule 6**: this is a pure read-only predicate-check (no writes, no commits, no external comms). No `AskUserQuestion` at this step — the routing is deterministic per the table above. The user-answerable question accumulates in the queue file and surfaces at Step 2.4 gate (a) per the existing batched contract. Per ADR-044 framework-resolution boundary: routing is framework-resolved (mechanical); user input is preserved at the loop-end surface where it belongs.
+
+**Compose-with**: ADR-068 (surface 3 single-artifact predicate — mirrored to orchestrator), ADR-074 (substance-confirm-before-build — JTBD-as-driver symmetric sibling to ADR-as-driver), ADR-076 (tier-first selection preserved by the loopback), ADR-031 (degenerate adopter silent-pass when per-JTBD shim absent), ADR-049 / ADR-080 (PATH shim grammar + highest-version-wins wrapper), ADR-014 (no commit at this step — predicate is read-only). The sibling-class gap for ADRs cited as Decision Drivers (ADR-074 master class) is RFC-016 § Deferred item 1 — captured for follow-on after this Step 3.5 dogfoods.
+
 ### Step 4: Classify each problem
 
 Read the problem file and apply these deterministic rules:

package/skills/work-problems/test/work-problems-step-3-5-jtbd-ratification-predicate.bats

@@ -0,0 +1,191 @@
+#!/usr/bin/env bats
+
+# Step 3.5 behavioural fixture per RFC-016 + P344:
+# work-problems orchestrator predicate-checks the cited JTBDs of the
+# selected ticket BEFORE dispatching the iter-worker. The predicate
+# decision lives in `packages/itil/scripts/check-ticket-jtbd-ratification.sh`
+# so the SKILL.md Step 3.5 prose is a thin source-and-call wrapper around
+# a behaviorally-testable shell script (P081 / user feedback: prefer
+# behavioural over structural-grep tests).
+#
+# Polarity (RFC-016 § Scope):
+#   exit 0 = all cited JTBDs ratified (or none cited) → orchestrator proceeds
+#            with the dispatch
+#   exit 1 = ≥1 cited JTBD unratified; one ID per stdout line, `(unresolved)`
+#            tag for the per-JTBD predicate's exit-2 cases → orchestrator
+#            routes to user-answerable skip + queues outstanding_question
+#   exit 2 = ticket file missing / unreadable → halt
+#
+# Cases covered (per RFC-016 § Verification + § Tasks bats coverage):
+#   1. Helper exists at the contracted PATH-shim location.
+#   2. Ticket cites no JTBDs at all → exit 0 (vacuous-pass).
+#   3. Ticket cites a ratified JTBD (frontmatter `human-oversight: confirmed`)
+#      → exit 0.
+#   4. Ticket cites an unratified JTBD → exit 1 + ID on stdout.
+#   5. Ticket cites an unresolved JTBD ID (no matching JTBD file) → exit 1
+#      + `(unresolved)` tag.
+#   6. Ticket file missing → exit 2.
+#   7. Missing per-JTBD predicate shim → silent-pass exit 0 (ADR-031
+#      degenerate adopter case).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SHIM="$REPO_ROOT/packages/itil/bin/wr-itil-check-ticket-jtbd-ratification"
+
+  FIXTURE="$(mktemp -d)"
+  mkdir -p "$FIXTURE/docs/jtbd/developer"
+  mkdir -p "$FIXTURE/docs/problems/open"
+
+  # Shim search PATH: put the real per-JTBD predicate shim on PATH so the
+  # helper can dispatch it. The helper resolves shims through PATH per
+  # ADR-049 — no source-relative paths.
+  export PATH="$REPO_ROOT/packages/jtbd/bin:$PATH"
+}
+
+teardown() {
+  rm -rf "$FIXTURE"
+}
+
+@test "shim exists at the contracted PATH location" {
+  [ -f "$SHIM" ]
+  [ -x "$SHIM" ]
+}
+
+@test "case 1: ticket cites no JTBDs → exit 0 (vacuous-pass)" {
+  cat > "$FIXTURE/docs/problems/open/999-no-jtbds.md" <<'EOF'
+# Problem 999: ticket with no JTBD citations
+
+**Status**: Open
+
+## Description
+
+This ticket has no Decision Drivers section and no JTBD citations.
+EOF
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/999-no-jtbds.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "case 2: ticket cites a ratified JTBD → exit 0" {
+  cat > "$FIXTURE/docs/jtbd/developer/JTBD-501-ratified.md" <<'EOF'
+---
+human-oversight: confirmed
+---
+
+# JTBD-501: A ratified job
+EOF
+  cat > "$FIXTURE/docs/problems/open/998-cites-ratified.md" <<'EOF'
+# Problem 998: cites a ratified JTBD
+
+## Decision Drivers
+
+- JTBD-501 — A ratified job
+EOF
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/998-cites-ratified.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "case 3: ticket cites an unratified JTBD → exit 1 + ID stdout" {
+  # Unratified = no `human-oversight: confirmed` frontmatter.
+  cat > "$FIXTURE/docs/jtbd/developer/JTBD-502-unratified.md" <<'EOF'
+---
+status: proposed
+---
+
+# JTBD-502: An unratified job (no human-oversight: confirmed)
+EOF
+  cat > "$FIXTURE/docs/problems/open/997-cites-unratified.md" <<'EOF'
+# Problem 997: cites an unratified JTBD
+
+## Decision Drivers
+
+- JTBD-502 — An unratified job
+EOF
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/997-cites-unratified.md"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"JTBD-502"* ]]
+}
+
+@test "case 4: ticket cites an unresolved JTBD ID → exit 1 + (unresolved) tag" {
+  cat > "$FIXTURE/docs/problems/open/996-cites-unresolved.md" <<'EOF'
+# Problem 996: cites an unresolved JTBD ID
+
+## Decision Drivers
+
+- JTBD-999 — Does not exist
+EOF
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/996-cites-unresolved.md"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"JTBD-999"* ]]
+  [[ "$output" == *"(unresolved)"* ]]
+}
+
+@test "case 5: ticket file missing → exit 2" {
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/nonexistent.md"
+  [ "$status" -eq 2 ]
+}
+
+@test "case 6: missing per-JTBD predicate shim → silent-pass exit 0" {
+  # Strip ALL per-JTBD predicate shim locations from PATH (source-repo
+  # packages/jtbd/bin AND the global plugin install cache); degenerate
+  # adopter case (ADR-031). The helper should silent-pass (exit 0) rather
+  # than fail.
+  cat > "$FIXTURE/docs/problems/open/995-cites-unratified.md" <<'EOF'
+# Problem 995: cites an unratified JTBD but shim is missing
+
+## Decision Drivers
+
+- JTBD-502 — An unratified job
+EOF
+  cd "$FIXTURE"
+  # Strip every PATH entry that exposes wr-jtbd-is-job-or-persona-unconfirmed.
+  # Both packages/jtbd/bin (source-repo) and ~/.claude/plugins/cache/.../bin
+  # (plugin install) must go.
+  STRIPPED_PATH=""
+  while IFS= read -r entry; do
+    [ -z "$entry" ] && continue
+    if [ -x "$entry/wr-jtbd-is-job-or-persona-unconfirmed" ]; then
+      continue
+    fi
+    STRIPPED_PATH="${STRIPPED_PATH}${entry}:"
+  done < <(printf '%s' "$PATH" | tr ':' '\n')
+  PATH="${STRIPPED_PATH%:}" run "$SHIM" "docs/problems/open/995-cites-unratified.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "case 7: ticket cites multiple JTBDs, one unratified → exit 1 + unratified ID only" {
+  cat > "$FIXTURE/docs/jtbd/developer/JTBD-503-ratified.md" <<'EOF'
+---
+human-oversight: confirmed
+---
+
+# JTBD-503: A ratified job
+EOF
+  cat > "$FIXTURE/docs/jtbd/developer/JTBD-504-unratified.md" <<'EOF'
+---
+status: proposed
+---
+
+# JTBD-504: An unratified job
+EOF
+  cat > "$FIXTURE/docs/problems/open/994-cites-mixed.md" <<'EOF'
+# Problem 994: cites both ratified and unratified JTBDs
+
+## Decision Drivers
+
+- JTBD-503 — A ratified job
+- JTBD-504 — An unratified job
+EOF
+  cd "$FIXTURE"
+  run "$SHIM" "docs/problems/open/994-cites-mixed.md"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"JTBD-504"* ]]
+  # Ratified IDs are NOT echoed — only the unratified set.
+  [[ "$output" != *"JTBD-503"* ]]
+}