@windyroad/itil 0.24.1-preview.277 → 0.25.0-preview.279

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/README.md

@@ -78,6 +78,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | Skill | Purpose |
 |-------|---------|
 | `/wr-itil:manage-problem` | Create, update, and close problem tickets through the Open → Known Error → Verifying → Closed lifecycle |
+| `/wr-itil:capture-problem` | Foreground-lightweight aside-invocation variant of `manage-problem` (per ADR-032 background-capture pattern + P078 capture-on-correction) — drafts a ticket scaffold without losing the operational thread when a problem signal surfaces mid-conversation |
 | `/wr-itil:work-problem` | Pick the highest-WSJF actionable ticket and work it to completion |
 | `/wr-itil:work-problems` | AFK orchestrator — batch-work the problem backlog by WSJF priority while the user is away |
 | `/wr-itil:list-problems` | Read-only display of the open and known-error backlog sorted by WSJF |

package/hooks/hooks.json

@@ -1,7 +1,11 @@
 {
   "hooks": {
     "SessionStart": [
-      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-itil wr-risk-scorer" }] }
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-itil wr-risk-scorer" }] },
+      {
+        "matcher": "startup",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-pending-questions-surface.sh" }]
+      }
     ],
     "UserPromptSubmit": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-gate.sh" }] },

package/hooks/itil-pending-questions-surface.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# wr-itil — SessionStart hook (P157, ADR-032 P157 amendment, ADR-040 precedent)
+#
+# Surfaces accumulated `outstanding_questions` entries from the AFK loop's
+# session-level queue file at .afk-run-state/outstanding-questions.jsonl
+# when the user starts a new interactive session. The queue is populated
+# between iters by /wr-itil:work-problems Step 5 / Step 2.5 / Step 2.5b
+# (P135 Phase 3 + ADR-044 6-class taxonomy schema).
+#
+# Without this hook, accumulated questions persist across session boundaries
+# unread when an AFK loop halts before its Step 2.5 / Step 2.5b emit fires
+# (manual stop, quota exhaustion, network failure). With this hook, the
+# accumulated queue surfaces deterministically on session start; the agent
+# fires AskUserQuestion in batches (<=4 per call per ADR-013 Rule 1) on the
+# user's first interactive turn and rewrites the queue file to remove
+# resolved entries.
+#
+# Wired from packages/itil/hooks/hooks.json SessionStart array with
+# matcher "startup" (per ADR-040 Option A). Silent exit if queue is missing,
+# empty, or whitespace-only per ADR-040 Mechanism step 1.
+#
+# AFK-iter cross-context-leak prevention (ADR-032 line 127): when invoked
+# inside a /wr-itil:work-problems iter subprocess (which inherits the
+# orchestrator's queue file), the orchestrator's Step 5 dispatch block sets
+# WR_SUPPRESS_PENDING_QUESTIONS=1 before each `claude -p` spawn. The hook
+# self-suppresses on that env var so the orchestrator-session queue does not
+# surface inside iter subprocess contexts.
+
+set -euo pipefail
+
+# AFK-iter self-suppress — orchestrator sets this before spawning each
+# `claude -p` subprocess so the session-level queue does not leak into iter
+# subprocess contexts. Only literal "1" suppresses; any other value (including
+# "0", unset, empty) lets the hook proceed.
+if [ "${WR_SUPPRESS_PENDING_QUESTIONS:-}" = "1" ]; then
+  exit 0
+fi
+
+QUEUE_FILE="${CLAUDE_PROJECT_DIR:-.}/.afk-run-state/outstanding-questions.jsonl"
+
+# Silent-on-no-content per ADR-040 Mechanism step 1.
+[ -f "$QUEUE_FILE" ] || exit 0
+[ -s "$QUEUE_FILE" ] || exit 0
+
+# ADR-044 6-class taxonomy precedence — lower rank value = higher priority.
+# Strings match the JSONL schema in work-problems SKILL.md Step 5 verbatim.
+rank_for_category() {
+  case "$1" in
+    deviation-approval)  echo 1 ;;
+    direction)           echo 2 ;;
+    one-time-override)   echo 3 ;;
+    silent-framework)    echo 4 ;;
+    taste)               echo 5 ;;
+    correction-followup) echo 6 ;;
+    *)                   echo 9 ;;
+  esac
+}
+
+# Parse + dedupe + rank entries. Streams TSV with rank-prefix for sort.
+# Tab-delimited columns: rank \t category \t ticket_id \t question_text
+# (where question_text falls back to rationale for deviation-approval).
+# Malformed JSON lines are silently skipped so a corrupted queue does not
+# block session start.
+ENTRIES_TSV=$(
+  while IFS= read -r line || [ -n "$line" ]; do
+    # Skip blank / whitespace-only lines.
+    [ -z "$(printf '%s' "$line" | tr -d '[:space:]')" ] && continue
+    # Skip non-JSON lines silently.
+    printf '%s' "$line" | jq -e . >/dev/null 2>&1 || continue
+    cat="$(printf '%s' "$line" | jq -r '.category // "unknown"')"
+    tid="$(printf '%s' "$line" | jq -r '.ticket_id // "—"')"
+    # Question text: standard-shape entries use .question; deviation-approval
+    # entries use .rationale (the load-bearing one-liner) since they have no
+    # .question field per the schema.
+    qtext="$(printf '%s' "$line" | jq -r '.question // .rationale // "(no question text)"')"
+    rank=$(rank_for_category "$cat")
+    printf '%s\t%s\t%s\t%s\n' "$rank" "$cat" "$tid" "$qtext"
+  done < "$QUEUE_FILE" \
+  | sort -u                       `# dedupe identical (rank+cat+tid+qtext)` \
+  | sort -t $'\t' -k1,1n -s       `# stable sort by rank ascending`
+)
+
+# Empty after dedupe / parse-skip → silent exit.
+[ -n "$ENTRIES_TSV" ] || exit 0
+
+ENTRY_COUNT=$(printf '%s\n' "$ENTRIES_TSV" | wc -l | tr -d ' ')
+
+# Emit additionalContext on stdout (ADR-040 plain-stdout shape per
+# session-start-briefing.sh precedent).
+{
+  echo "PENDING QUESTIONS FROM PRIOR AFK LOOP — accumulated outstanding_questions"
+  echo "queue (source: .afk-run-state/outstanding-questions.jsonl, ${ENTRY_COUNT} entries)."
+  echo ""
+  echo "These are direction / deviation-approval / one-time-override / silent-framework"
+  echo "/ taste / correction-followup observations queued by /wr-itil:work-problems"
+  echo "iters per ADR-044 6-class taxonomy. Surface them via AskUserQuestion batched"
+  echo "<=4 per call (sequential when >4) on the user's first interactive turn,"
+  echo "ranked deviation-approval > direction > one-time-override > silent-framework"
+  echo "> taste > correction-followup. After resolving each entry, remove the"
+  echo "matching line from the queue file by rewriting"
+  echo ".afk-run-state/outstanding-questions.jsonl with the unresolved entries"
+  echo "remaining. Empty queue → next session no-op."
+  echo ""
+  echo "| # | Category | Ticket | Question |"
+  echo "|---|----------|--------|----------|"
+  i=0
+  while IFS=$'\t' read -r _rank cat tid qtext; do
+    i=$((i + 1))
+    # Truncate question text to keep table cells bounded; agent retrieves
+    # full body from the queue file when constructing AskUserQuestion calls.
+    short_q="$(printf '%s' "$qtext" | cut -c1-160)"
+    [ "${#qtext}" -gt 160 ] && short_q="${short_q}..."
+    # Escape pipe chars in cells so the table renders.
+    short_q="${short_q//|/\\|}"
+    printf '| %d | %s | %s | %s |\n' "$i" "$cat" "$tid" "$short_q"
+  done <<< "$ENTRIES_TSV"
+  echo ""
+  if [ "$ENTRY_COUNT" -gt 4 ]; then
+    echo "Note: ${ENTRY_COUNT} entries exceeds the AskUserQuestion <=4 per-call"
+    echo "cap (ADR-013 Rule 1). Fire sequential calls — first 4 highest-ranked"
+    echo "first, then the next batch, until the queue is drained."
+  fi
+} 2>/dev/null
+
+exit 0

package/hooks/test/itil-pending-questions-surface.bats

@@ -0,0 +1,307 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for itil-pending-questions-surface.sh (P157).
+#
+# SessionStart hook that reads the AFK-loop-accumulated outstanding-questions
+# JSONL queue at .afk-run-state/outstanding-questions.jsonl, ranks entries
+# per ADR-044 6-class taxonomy, and emits an additionalContext directive on
+# stdout for the agent to surface via AskUserQuestion (batched <=4).
+#
+# Per ADR-052 (behavioural-tests-default), these tests exercise the hook's
+# observable stdout / exit-code behaviour against fixture queue files —
+# NOT the prose contents of the script itself.
+#
+# Behavioural surfaces under test:
+#   1. Silent-on-no-content per ADR-040 Mechanism step 1 — missing or empty
+#      queue file produces zero stdout and exits 0.
+#   2. Non-empty queue produces additionalContext naming the entries.
+#   3. ADR-044 6-class precedence — when multiple categories present,
+#      deviation-approval ranks first; correction-followup ranks last.
+#   4. Deduplication — identical entries (same category + question + ticket_id)
+#      collapse to one.
+#   5. Batching directive — when N > 4, output names the AskUserQuestion
+#      batched-call cap.
+#   6. Cleanup directive — output instructs the agent to truncate resolved
+#      entries from the queue file.
+#   7. AFK-iter cross-context-leak prevention — WR_SUPPRESS_PENDING_QUESTIONS=1
+#      env var forces silent exit even when queue is non-empty.
+#
+# @problem P157
+# @jtbd JTBD-006 (progress backlog while AFK — surface accumulated questions
+#                  on session resume)
+# @jtbd JTBD-001 (enforce governance without slowing down — direction-class
+#                  observations resolve before user begins foreground work)
+# @jtbd JTBD-101 (extend the suite — sibling SessionStart hook reuses
+#                  ADR-040 silent-on-no-content shape)
+# @adr ADR-032 (governance skill invocation patterns — P157 amendment for
+#                JSONL-queue SessionStart variant)
+# @adr ADR-040 (session-start briefing surface — SessionStart precedent +
+#                silent-on-no-content shape)
+# @adr ADR-044 (decision-delegation contract — 6-class taxonomy precedence)
+# @adr ADR-052 (behavioural-tests-default — these tests exercise hook
+#                stdout / exit-code, not script prose)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK_SCRIPT="${REPO_ROOT}/packages/itil/hooks/itil-pending-questions-surface.sh"
+
+  TMPROOT=$(mktemp -d)
+  mkdir -p "$TMPROOT/.afk-run-state"
+  QUEUE_FILE="$TMPROOT/.afk-run-state/outstanding-questions.jsonl"
+
+  export CLAUDE_PROJECT_DIR="$TMPROOT"
+  unset WR_SUPPRESS_PENDING_QUESTIONS
+}
+
+teardown() {
+  rm -rf "$TMPROOT"
+  unset CLAUDE_PROJECT_DIR WR_SUPPRESS_PENDING_QUESTIONS
+}
+
+# ---------------------------------------------------------------------------
+# Existence — minimum surface required for hooks.json to wire it up.
+# ---------------------------------------------------------------------------
+
+@test "hook script exists and is executable" {
+  [ -f "$HOOK_SCRIPT" ]
+  [ -x "$HOOK_SCRIPT" ]
+}
+
+@test "hooks.json registers the SessionStart hook with matcher startup" {
+  HOOKS_JSON="${REPO_ROOT}/packages/itil/hooks/hooks.json"
+  run jq -r '.hooks.SessionStart[] | select(.matcher == "startup") | .hooks[].command' "$HOOKS_JSON"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF 'itil-pending-questions-surface.sh'
+}
+
+# ---------------------------------------------------------------------------
+# Silent-on-no-content per ADR-040 Mechanism step 1.
+# ---------------------------------------------------------------------------
+
+@test "missing queue file: silent exit 0" {
+  # No queue file at all (typical state for projects that have never run AFK).
+  rm -f "$QUEUE_FILE"
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "empty queue file: silent exit 0" {
+  : > "$QUEUE_FILE"
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "queue with only whitespace lines: silent exit 0" {
+  printf '\n   \n\t\n' > "$QUEUE_FILE"
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ---------------------------------------------------------------------------
+# Non-empty queue → additionalContext emitted.
+# ---------------------------------------------------------------------------
+
+@test "single entry: additionalContext names the question and ticket_id" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Pick A or B for the storage layer?","context":"iter1 P200","ticket_id":"P200"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF 'Pick A or B for the storage layer?'
+  echo "$output" | grep -qF 'P200'
+}
+
+@test "single entry: output cites the queue file path so user can inspect" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q1","context":"c1","ticket_id":"P201"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF '.afk-run-state/outstanding-questions.jsonl'
+}
+
+# ---------------------------------------------------------------------------
+# ADR-044 6-class precedence ordering.
+# ---------------------------------------------------------------------------
+
+@test "ranking: deviation-approval ranks first among mixed categories" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"correction-followup","question":"low-rank Q","context":"c","ticket_id":"P301"}
+{"category":"direction","question":"mid-rank Q","context":"c","ticket_id":"P302"}
+{"category":"deviation-approval","existing_decision":"ADR-001","contradicting_evidence":"ev","proposed_shape":"amend","rationale":"r","ticket_id":"P303"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  # The deviation-approval entry's rationale must appear before the direction Q
+  # in the output (precedence: deviation-approval > direction > correction-followup).
+  DEVIATION_LINE=$(echo "$output" | grep -n 'P303' | head -1 | cut -d: -f1)
+  DIRECTION_LINE=$(echo "$output" | grep -n 'mid-rank Q' | head -1 | cut -d: -f1)
+  CORRECTION_LINE=$(echo "$output" | grep -n 'low-rank Q' | head -1 | cut -d: -f1)
+  [ -n "$DEVIATION_LINE" ]
+  [ -n "$DIRECTION_LINE" ]
+  [ -n "$CORRECTION_LINE" ]
+  [ "$DEVIATION_LINE" -lt "$DIRECTION_LINE" ]
+  [ "$DIRECTION_LINE" -lt "$CORRECTION_LINE" ]
+}
+
+@test "ranking: full 6-class precedence is deviation > direction > one-time > silent-framework > taste > correction" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"taste","question":"q-taste","context":"c","ticket_id":"P401"}
+{"category":"correction-followup","question":"q-correction","context":"c","ticket_id":"P402"}
+{"category":"silent-framework","question":"q-silent","context":"c","ticket_id":"P403"}
+{"category":"one-time-override","question":"q-onetime","context":"c","ticket_id":"P404"}
+{"category":"direction","question":"q-direction","context":"c","ticket_id":"P405"}
+{"category":"deviation-approval","existing_decision":"ADR-X","contradicting_evidence":"ev","proposed_shape":"amend","rationale":"q-deviation","ticket_id":"P406"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  # Capture the line number of each category-tagged ticket marker; assert order.
+  L1=$(echo "$output" | grep -n 'P406' | head -1 | cut -d: -f1)
+  L2=$(echo "$output" | grep -n 'q-direction' | head -1 | cut -d: -f1)
+  L3=$(echo "$output" | grep -n 'q-onetime' | head -1 | cut -d: -f1)
+  L4=$(echo "$output" | grep -n 'q-silent' | head -1 | cut -d: -f1)
+  L5=$(echo "$output" | grep -n 'q-taste' | head -1 | cut -d: -f1)
+  L6=$(echo "$output" | grep -n 'q-correction' | head -1 | cut -d: -f1)
+  [ "$L1" -lt "$L2" ]
+  [ "$L2" -lt "$L3" ]
+  [ "$L3" -lt "$L4" ]
+  [ "$L4" -lt "$L5" ]
+  [ "$L5" -lt "$L6" ]
+}
+
+# ---------------------------------------------------------------------------
+# Deduplication of identical entries.
+# ---------------------------------------------------------------------------
+
+@test "dedup: identical entries (same category+question+ticket_id) collapse to one" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Same Q","context":"c","ticket_id":"P500"}
+{"category":"direction","question":"Same Q","context":"c","ticket_id":"P500"}
+{"category":"direction","question":"Same Q","context":"different-context-different-iter","ticket_id":"P500"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  # "Same Q" should appear exactly once in the output (after dedup).
+  COUNT=$(echo "$output" | grep -cF 'Same Q')
+  [ "$COUNT" -eq 1 ]
+}
+
+@test "dedup: different question text on same ticket survives as two entries" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Question one","context":"c","ticket_id":"P501"}
+{"category":"direction","question":"Question two","context":"c","ticket_id":"P501"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF 'Question one'
+  echo "$output" | grep -qF 'Question two'
+}
+
+# ---------------------------------------------------------------------------
+# Batching directive — names the AskUserQuestion <=4 cap when N > 4.
+# ---------------------------------------------------------------------------
+
+@test "batching: output names AskUserQuestion when entries present" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q1","context":"c","ticket_id":"P600"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qiE 'AskUserQuestion'
+}
+
+@test "batching: directive cites the <=4-per-call cap" {
+  # 5 entries should trigger the batching note since AskUserQuestion caps at 4.
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q1","context":"c","ticket_id":"P601"}
+{"category":"direction","question":"Q2","context":"c","ticket_id":"P602"}
+{"category":"direction","question":"Q3","context":"c","ticket_id":"P603"}
+{"category":"direction","question":"Q4","context":"c","ticket_id":"P604"}
+{"category":"direction","question":"Q5","context":"c","ticket_id":"P605"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qE '(<=|≤|max(imum)?[ -]?)4|four'
+}
+
+# ---------------------------------------------------------------------------
+# Cleanup-on-resolve directive.
+# ---------------------------------------------------------------------------
+
+@test "cleanup: output instructs the agent to remove resolved entries from the queue" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q1","context":"c","ticket_id":"P700"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  # The cleanup directive must instruct removing resolved entries from the
+  # queue file. Match on the load-bearing words rather than exact phrasing.
+  echo "$output" | grep -qiE '(remove|delete|truncat|clear).*queue|outstanding-questions\.jsonl'
+}
+
+# ---------------------------------------------------------------------------
+# AFK-iter cross-context-leak prevention (architect Note 2).
+# ---------------------------------------------------------------------------
+
+@test "WR_SUPPRESS_PENDING_QUESTIONS=1 forces silent exit even when queue non-empty" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q-should-not-leak","context":"c","ticket_id":"P800"}
+JSONL
+  export WR_SUPPRESS_PENDING_QUESTIONS=1
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "WR_SUPPRESS_PENDING_QUESTIONS=0 does NOT suppress (only =1 does)" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{"category":"direction","question":"Q-must-surface","context":"c","ticket_id":"P801"}
+JSONL
+  export WR_SUPPRESS_PENDING_QUESTIONS=0
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF 'Q-must-surface'
+}
+
+@test "work-problems Step 5 dispatch block exports WR_SUPPRESS_PENDING_QUESTIONS=1 before claude -p" {
+  # The orchestrator MUST set WR_SUPPRESS_PENDING_QUESTIONS=1 before each
+  # iter subprocess spawn so the queue does not surface inside iter contexts
+  # (cross-context leak per ADR-032 line 127).
+  WP_SKILL="${REPO_ROOT}/packages/itil/skills/work-problems/SKILL.md"
+  [ -f "$WP_SKILL" ]
+  # Find the export line; it must come before the "claude -p" dispatch line in
+  # the same Step 5 dispatch block.
+  EXPORT_LINE=$(grep -n 'export WR_SUPPRESS_PENDING_QUESTIONS=1' "$WP_SKILL" | head -1 | cut -d: -f1)
+  CLAUDE_P_LINE=$(grep -n '^claude -p \\$' "$WP_SKILL" | head -1 | cut -d: -f1)
+  [ -n "$EXPORT_LINE" ]
+  [ -n "$CLAUDE_P_LINE" ]
+  [ "$EXPORT_LINE" -lt "$CLAUDE_P_LINE" ]
+}
+
+# ---------------------------------------------------------------------------
+# Malformed input — silent skip, do not crash the SessionStart hook chain.
+# ---------------------------------------------------------------------------
+
+@test "malformed JSON line: skipped silently, well-formed lines still surface" {
+  cat > "$QUEUE_FILE" <<'JSONL'
+{not valid json at all
+{"category":"direction","question":"Valid Q","context":"c","ticket_id":"P900"}
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qF 'Valid Q'
+}
+
+@test "all-malformed queue: silent exit 0 (do not block session start)" {
+  # Defensive — if the queue file is corrupted, the hook MUST NOT prevent
+  # the session from starting. SessionStart hook failures cascade into
+  # "session won't start" UX which is far worse than missing one surfacing.
+  cat > "$QUEUE_FILE" <<'JSONL'
+{not json
+also not json
+JSONL
+  run "$HOOK_SCRIPT"
+  [ "$status" -eq 0 ]
+}

package/package.json

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

package/skills/capture-problem/REFERENCE.md

@@ -0,0 +1,137 @@
+# `/wr-itil:capture-problem` Reference
+
+This file hosts the rationale, edge cases, contract trade-offs, and ADR cross-references for the `/wr-itil:capture-problem` skill. SKILL.md is the runtime contract (~150 lines, on-topic per ADR-038 progressive disclosure); this REFERENCE.md is the on-demand expansion for maintainers and curious users.
+
+## Why a separate skill?
+
+The `/wr-itil:manage-problem` flow is ~10 turns of agent work for a full new-problem intake: Step 0 README reconciliation preflight, Step 2 wide-net duplicate grep + AskUserQuestion branch, Step 3 next-ID, Step 4 information-gathering AskUserQuestion, Step 4b multi-concern split AskUserQuestion, Step 5 ticket file write + P094 README refresh, Step 11 commit gate.
+
+That cost is correct for the canonical new-problem path — the user wants to walk the flow, see duplicate-match prompts, and place the ticket in the WSJF ranking immediately.
+
+It is wrong for the **aside-invocation** use case. P155 surfaced three repeating patterns where the heavyweight cost is load-bearing friction:
+
+1. **Mid-AFK-iter sibling-findings**: agent observes a tangential ticket-worthy issue. The 10-turn ceremony breaks iter cadence — observation gets buried in `notes` field of `ITERATION_SUMMARY` and ~50% never reach the backlog.
+2. **User-initiated rapid captures**: user says "btw, this is broken too — capture it". The 10-turn ceremony breaks conversational flow.
+3. **AFK orchestrator main turn captures**: user-driven mid-loop interjections (P151 / P152 / P154 in the session that surfaced P155). Each capture took 5-15 minutes wall-clock through the heavyweight flow.
+
+`/wr-itil:capture-problem` is the source-side fix: a lightweight skill with a deferred-placeholder pattern that captures the observation in ~3-4 turns and routes the deferred re-rating + README refresh through `/wr-itil:review-problems` at a time of the user's choosing.
+
+## Contract trade-offs
+
+### Capture-time false-positives are cheaper than false-negatives
+
+P155 line 24: "capture-time false-positives (creating a duplicate that gets merged later) are cheaper than capture-time false-negatives (losing the observation entirely)."
+
+This is the structural rationale for:
+- **3-keyword cap on the duplicate-grep** — wider grep would surface more matches but force the user to either (a) add an AskUserQuestion branch (which capture-problem doesn't have) or (b) ignore the matches and proceed silently. A 3-keyword cap keeps the match list short and audit-able in the report.
+- **Title-only filename match** — body-content matches would be too noisy at the conservative threshold. Files whose filenames have zero overlap but whose bodies mention a keyword are almost always different tickets that happen to discuss similar topics. False-positive cost would dominate.
+- **No halt-on-match** — even when matches are found, capture proceeds. The duplicate gets resolved at next `/wr-itil:review-problems` (where the full-rank scan can detect and merge actual duplicates with the user in the loop).
+
+### Deferred-README-refresh contract
+
+Capture-problem skips the P094 inline README refresh that `/wr-itil:manage-problem` Step 5 performs. The trade-off:
+
+| Surface | Inline refresh (manage-problem) | Deferred refresh (capture-problem) |
+|---------|---------------------------------|-------------------------------------|
+| README authoritativeness | Always current at commit boundary | Lags new captures until next review |
+| Capture-time turn cost | +1-2 turns (regenerate + stage) | 0 turns |
+| WSJF ranking visibility | Immediate | Pending review |
+| Audit trail (commit) | One commit covers ticket + README | One commit covers ticket only |
+| README staleness window | None | Bounded by next review invocation |
+
+The deferred contract is acceptable because:
+
+1. **The on-disk ticket inventory remains the source of truth**. README.md is a derived view — consumers that need WSJF rankings can re-derive from the ticket files (and `/wr-itil:list-problems` does exactly that on cache-stale fallback).
+2. **The trailing pointer in Step 7 is the user-visible signal** that the README is transiently stale. The user has explicit instructions for how to reconcile.
+3. **`/wr-itil:review-problems` Step 9b's auto-transition pass already re-rates deferred-placeholder tickets** (the literal string `(deferred — re-rate at next /wr-itil:review-problems)` is the keying signal). One review pass folds all captured-but-not-rated tickets into the ranking.
+
+The bound on the staleness window is "until the next `/wr-itil:review-problems` invocation". For sessions that capture and never review, the README stays stale — but the on-disk inventory is always correct, and the next session-start `wr-itil-reconcile-readme` preflight catches drift if it propagates beyond a single session.
+
+### No AskUserQuestion at all
+
+Architect Q4 + JTBD review confirmed: capture-problem is a **mechanical-stage skill** per ADR-044's framework-resolution boundary. Every potentially-interactive decision is framework-mediated:
+
+- **Duplicate-check**: false-positive bias > false-negative bias. Mechanical rule: list matches, proceed regardless.
+- **Priority**: framework-policy default `3 (Medium) — Impact 3 × Likelihood 1`, flagged for re-rate. Re-rating is mandatory before the ticket is worked, so no ticket gets ranked on a wrong default.
+- **Effort**: framework-policy default `M`, flagged for re-rate. Same re-rating contract as Priority.
+- **Multi-concern split**: out of scope. The user invoking capture-problem with a multi-concern observation gets one ticket with the full description as the body; they re-route to `/wr-itil:manage-problem` for the structured split.
+
+This mirrors the mechanical-stage carve-out pattern documented in CLAUDE.md (P132 / inverse-P078 trap): when a SKILL contract names a stage as mechanical, do not ask. Per-action consent gates re-ask decisions the user already made and silently undo the load-bearing UX investment.
+
+## Edge cases
+
+### Empty `$ARGUMENTS`
+
+Halt-with-stderr-directive. capture-problem requires a description; without one there is nothing to capture. The directive points the user to `/wr-itil:manage-problem`, which has Step 4 AskUserQuestion gathering for missing fields.
+
+AFK orchestrators MUST NOT invoke capture-problem with empty arguments — caller-side contract. The Rule 6 audit makes this explicit so AFK-iter writers don't accidentally introduce a halt mid-loop.
+
+### Description is a kebab-stopword soup
+
+If the description's first 8-10 tokens are entirely stopwords (e.g. "the and of to in"), the slug derivation falls back to the full description hash modulo a short integer. The resulting slug is non-meaningful but unique; the user re-titles at next investigation.
+
+This is a degenerate case — real captures carry meaningful first-tokens — but the fallback prevents a malformed empty-slug filename.
+
+### ID collision with origin
+
+The next-ID formula uses `git ls-tree origin/main` to read the remote-tracking ref without requiring a fetch. If a parallel session minted the same ID for a different problem and pushed it before this session captures, the local read sees the higher origin ID and increments past it.
+
+If the local session has not fetched recently and origin has captures the local doesn't see, the formula may still collide. The renumber audit log line in Step 7 captures the resolution. P040 incident applies.
+
+### Cross-skill marker ordering
+
+The `/tmp/manage-problem-grep-${SESSION_ID}` create-gate marker is shared between `manage-problem` and `capture-problem`. Whichever fires first writes the marker; subsequent calls are idempotent (`: > FILE`).
+
+This means a session that does `manage-problem` once then `capture-problem` three times has the marker set after the first manage-problem grep, and all three captures land without re-running the grep + mark sequence. capture-problem still runs its own minimal-grep in Step 2 (because the conservative threshold + report-listing is part of the contract), but the marker write is a no-op.
+
+### P057 staging-trap
+
+Not applicable. capture-problem only Writes a new file; it does not `git mv` an existing one. The P057 rule (re-stage after Edit on a `git mv`-d file) is irrelevant to this skill.
+
+### Multi-concern descriptions
+
+If the user supplies a multi-concern description (e.g. "checkout flow leaks tokens AND the price calculator rounds wrong"), capture-problem creates ONE ticket with both observations in the description body. Re-routing to `/wr-itil:manage-problem` for the structured split (Step 4b) is a deliberate design choice — the heavyweight flow owns the multi-concern decision because the split prompt requires user input to confirm boundaries.
+
+The user can manually `/wr-itil:manage-problem <NNN>` later to split a captured multi-concern ticket if needed.
+
+## Composition with the rest of the suite
+
+### `/wr-itil:review-problems`
+
+Handles the deferred re-rating + README refresh. Step 9b's auto-transition pass keys off the deferred-placeholder string and surfaces captured tickets for re-rating. The README refresh in Step 9e regenerates the table covering all captured-but-not-rated tickets in one pass.
+
+### `/wr-itil:manage-problem`
+
+Heavyweight intake counterpart. Shares the create-gate marker with capture-problem. The two skills are designed to coexist — neither supersedes the other. A user who starts with capture-problem and decides they want the structured intake flow re-invokes manage-problem on the captured ticket ID to flesh out the placeholders.
+
+### `/wr-itil:work-problems` (AFK orchestrator)
+
+Iter subprocesses can invoke capture-problem to capture sibling-findings without breaking iter cadence. The AFK carve-out in ADR-032 (line 85) excludes the **background-capture** variant from AFK contexts; the **foreground-lightweight-capture** variant introduced by this skill is fine inside iter subprocesses because it has no `Agent(run_in_background: true)` invocation — it's a normal foreground-synchronous skill that happens to do less work than manage-problem.
+
+### `/wr-itil:capture-problem` callers
+
+The intended invocation surface is `/wr-itil:capture-problem <description>`. The description must be a non-empty free-text payload; the skill does not branch on description shape.
+
+## Related ADRs
+
+- **ADR-009** — gate-marker-lifecycle (per-session /tmp markers; capture-problem reuses the manage-problem marker).
+- **ADR-013** — structured user interaction (Rule 6 fail-safe; capture-problem has no AskUserQuestion branches so Rule 6 is trivially satisfied).
+- **ADR-014** — governance skills commit their own work (capture-problem owns its commit).
+- **ADR-022** — verification-pending status (out of scope for capture-problem; status transitions live in transition-problem).
+- **ADR-031** — problem-ticket directory layout (capture-problem matches current flat-layout production reality; auto-migration is a future ADR-031 follow-up).
+- **ADR-032** — governance skill invocation patterns (this skill's parent ADR; foreground-lightweight-capture variant amendment 2026-05-03).
+- **ADR-038** — progressive disclosure (SKILL.md + REFERENCE.md split shape).
+- **ADR-044** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **ADR-049** — bin/ on PATH (capture-problem reuses existing `wr-itil-reconcile-readme` shim; no new shim).
+- **ADR-052** — behavioural-tests-default for skill testing (capture-problem's bats fixtures exercise primitives, not SKILL.md prose).
+
+## Related problems
+
+- **P014** — parent / master tracker.
+- **P078** — capture-on-correction OFFER; depends on capture-problem.
+- **P088** — settled the user-direction-scoped decision: capture-problem + capture-adr are shippable; capture-retro is deferred.
+- **P119** — manage-problem create-gate; capture-problem composes with the same marker.
+- **P148** — Tickets Deferred retro section (legacy when capture-problem ships).
+- **P155** — driver ticket.
+- **P156** — sibling capture-adr.
+- **P157** — sibling pending-questions-surface hook.

package/skills/capture-problem/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: wr-itil:capture-problem
+description: Lightweight problem-capture skill for aside-invocation during foreground work — minimal duplicate-check, skeleton ticket file, single commit per capture, no inline README refresh. Defers full duplicate analysis and README refresh to /wr-itil:review-problems. Use this when the user (or agent mid-iter) wants to capture an observation quickly without disrupting current task flow. For full-intake new-problem creation, use /wr-itil:manage-problem.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Capture Problem Skill
+
+Capture a problem ticket quickly during foreground work. Lightweight aside-invocation surface that complements the heavyweight `/wr-itil:manage-problem` flow. See `REFERENCE.md` in this directory for rationale, edge cases, contract trade-offs, and the ADR-032 foreground-lightweight-capture amendment.
+
+This skill is the foreground-lightweight-capture variant of `/wr-itil:manage-problem`'s new-problem path per ADR-032 (P155 amendment, 2026-05-03). The deferred background-capture variant named in ADR-032's original taxonomy remains deferred per P088 settlement.
+
+## When to invoke
+
+- **Mid-iter sibling-finding**: agent observes a tangential ticket-worthy issue while working on a different problem and cannot afford the 10-turn `/wr-itil:manage-problem` ceremony.
+- **User-initiated rapid capture**: user says "btw, this is broken too — capture it" during retros, code reviews, or correction conversations.
+- **AFK orchestrator main turn captures**: orchestrator captures user-driven mid-loop observations without breaking the iter cadence.
+
+**Use `/wr-itil:manage-problem` instead** when:
+- The user wants to walk the full intake flow (priority discussion, multi-concern split, immediate WSJF placement).
+- The capture is large enough that deferred-investigation placeholders are unhelpful (the description IS the full ticket body).
+- The capture needs to ride alongside an immediate fix (`fix(scope): ... (closes P<NNN>)` shape — manage-problem's Step 7 transition + Step 11 commit handles this; capture-problem does not).
+
+## Rule 6 audit (per ADR-032 + ADR-013)
+
+This skill has **zero AskUserQuestion branches** by design. Each potentially-interactive decision is framework-mediated per ADR-044:
+
+| Decision | Resolution |
+|----------|-----------|
+| Duplicate-check | Mechanical 3-keyword title-only grep; matches listed in report; capture proceeds regardless. False-positives are cheaper than false-negatives (P155 line 24). |
+| Priority default | Framework-policy: `3 (Medium) — Impact 3 × Likelihood 1` flagged "deferred — re-rate at next /wr-itil:review-problems". |
+| Effort default | Framework-policy: `M` flagged "deferred — re-rate at next /wr-itil:review-problems". |
+| Multi-concern split | Out of scope: capture-problem creates one ticket per invocation. Multi-concern observations route to `/wr-itil:manage-problem` (its Step 4b owns the split). |
+| Empty `$ARGUMENTS` | Halt-with-stderr-directive: print "capture-problem requires a description in $ARGUMENTS — invoke /wr-itil:manage-problem instead for the full intake flow" and exit. AFK orchestrators MUST NOT invoke capture-problem with empty arguments — caller-side contract. |
+
+Per ADR-013 Rule 6 fail-safe: every branch above resolves without user input, so AFK and interactive contexts behave identically.
+
+## Steps
+
+### 0. README reconciliation preflight (P118)
+
+Same as `/wr-itil:manage-problem` Step 0 — diagnose-only check. Halt-and-route on Exit 1 (committed cross-session drift); INLINE_REFRESH carve-out (P149) preserved. capture-problem itself does NOT refresh README.md (see Step 6); the preflight is purely a fail-fast on pre-existing drift.
+
+```bash
+wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+reconcile_exit=$?
+if [ "$reconcile_exit" -eq 1 ]; then
+  wr-itil-classify-readme-drift /tmp/wr-itil-drift-$$.txt docs/problems
+  classify_exit=$?
+  rm -f /tmp/wr-itil-drift-$$.txt
+  # classify_exit 0 (INLINE_REFRESH): proceed (no inline refresh in this skill).
+  # classify_exit 1 (HALT_ROUTE_RECONCILE): halt; invoke /wr-itil:reconcile-readme.
+  # classify_exit 2 (parse error): conservative halt-and-route.
+fi
+```
+
+### 1. Parse the description from `$ARGUMENTS`
+
+The description is the full free-text payload from `$ARGUMENTS`. Empty arguments halts per the Rule 6 audit above.
+
+Derive a kebab-case title slug from the first 8-10 non-stopword tokens of the description (matching the existing `manage-problem` slug derivation pattern).
+
+### 2. Minimal-grep duplicate check (3-keyword title-only)
+
+Extract up to **3 distinct kebab-cased non-stopword keywords** from the description. Grep the **filenames** of `docs/problems/*.md` (NOT bodies — title-only is the conservative threshold per architect verdict on Q1):
+
+```bash
+match_count=$(ls docs/problems/*.md 2>/dev/null \
+              | grep -ciE 'kw1|kw2|kw3' || true)
+```
+
+The **3-keyword cap** is a hard-coded constant. Do NOT make it env-overridable — the conservative threshold rationale (P155 line 24) is structural to the design, not a tunable knob.
+
+**Title-only**: file bodies are intentionally NOT scanned. Body-content matches would either (a) over-prompt (capture-problem has no AskUserQuestion to surface them) or (b) get silently swallowed. Title-only matches preserve the conservative-threshold contract.
+
+If matches are found: list them in the final report. **Do NOT halt or branch.** Capture proceeds. The user can resolve duplicates at the next `/wr-itil:review-problems` invocation (or invoke `/wr-itil:manage-problem` directly if the duplicate-check shape needs a structured branch).
+
+**After the grep completes**, write the per-session create-gate marker so the `PreToolUse:Write` hook (P119) permits the subsequent Write of the new `.open.md` file:
+
+```bash
+source packages/itil/hooks/lib/session-id.sh
+source packages/itil/hooks/lib/create-gate.sh
+sid=$(get_current_session_id) && mark_step2_complete "$sid"
+```
+
+The marker is shared between `manage-problem` and `capture-problem` per ADR-032 amendment — same `/tmp/manage-problem-grep-${SESSION_ID}` path, idempotent across cross-skill ordering.
+
+### 3. Compute the next ID
+
+Same P056-safe local_max + origin_max formula as `/wr-itil:manage-problem` Step 3:
+
+```bash
+local_max=$(ls docs/problems/*.md 2>/dev/null | sed 's/.*\///' | grep -oE '^[0-9]+' | sort -n | tail -1)
+origin_max=$(git ls-tree --name-only origin/main docs/problems/ 2>/dev/null | sed 's|^docs/problems/||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n${origin_max:-0}" | sort -n | tail -1) + 1 )))
+```
+
+Log the renumber decision in the operation report if origin and local diverged.
+
+### 4. Skeleton-fill the ticket
+
+**File path**: `docs/problems/<NNN>-<kebab-title>.open.md`
+
+**Template** (deferred-placeholder pattern — flag every section the capture didn't fill):
+
+```markdown
+# Problem <NNN>: <Title>
+
+**Status**: Open
+**Reported**: <YYYY-MM-DD>
+**Priority**: 3 (Medium) — Impact: 3 x Likelihood: 1 (deferred — re-rate at next /wr-itil:review-problems)
+**Effort**: M (deferred — re-rate at next /wr-itil:review-problems)
+
+## Description
+
+<full description from $ARGUMENTS>
+
+## Symptoms
+
+(deferred to investigation)
+
+## Workaround
+
+(deferred to investigation)
+
+## Impact Assessment
+
+- **Who is affected**: (deferred to investigation)
+- **Frequency**: (deferred to investigation)
+- **Severity**: (deferred to investigation)
+- **Analytics**: (deferred to investigation)
+
+## Root Cause Analysis
+
+### Investigation Tasks
+
+- [ ] Re-rate Priority and Effort at next /wr-itil:review-problems
+- [ ] Investigate root cause
+- [ ] Create reproduction test
+
+## Dependencies
+
+- **Blocks**: (none)
+- **Blocked by**: (none)
+- **Composes with**: (none)
+
+## Related
+
+(captured via /wr-itil:capture-problem; expand at next investigation)
+```
+
+The deferred-placeholder pattern is load-bearing — `/wr-itil:review-problems` keys off the literal string `(deferred — re-rate at next /wr-itil:review-problems)` to surface captured tickets for re-rating.
+
+### 5. Write the file
+
+Single `Write` to `docs/problems/<NNN>-<kebab-title>.open.md`. The P119 PreToolUse hook permits the Write because Step 2 set the marker.
+
+### 6. Commit per ADR-014 — single commit, no README refresh
+
+**Stage list**: ONLY the new ticket file. **Do NOT** stage `docs/problems/README.md`. The deferred-README-refresh contract is the load-bearing distinction from `/wr-itil:manage-problem` — capture-time speed depends on skipping the regenerate-and-stage cycle.
+
+```bash
+git add docs/problems/<NNN>-<kebab-title>.open.md
+```
+
+Satisfy the commit gate per ADR-014 — same two-path pattern as manage-problem Step 11:
+
+- **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool.
+- **Fallback**: invoke `/wr-risk-scorer:assess-release` via the Skill tool when the subagent type is unavailable in the current tool surface.
+
+Commit message:
+
+```
+docs(problems): capture P<NNN> <title>
+```
+
+The `capture` verb in the message is the audit signal that this ticket landed via the lightweight aside path (vs. `open` for manage-problem's full intake).
+
+### 7. Report
+
+After the commit, report:
+
+- The new ticket file path and ID.
+- The list of duplicate matches found (if any). If matches found, name them and remind the user to merge at next `/wr-itil:review-problems` if appropriate.
+- Trailing pointer: `Run /wr-itil:review-problems next to fold P<NNN> into the WSJF rankings, re-rate the deferred placeholders, and refresh docs/problems/README.md.`
+
+The trailing pointer is **not optional** — it is the user-visible signal that the README is transiently stale and how to reconcile it. Drift here re-opens the deferred-README-refresh contract gap.
+
+## Composition with manage-problem
+
+| Concern | manage-problem | capture-problem |
+|---------|----------------|-----------------|
+| Duplicate-check | Wide-net grep + AskUserQuestion branch on matches | 3-keyword title-only grep, list-only (no branch) |
+| Multi-concern split | Step 4b AskUserQuestion | Out of scope (one ticket per invocation) |
+| Skeleton-fill | Full-intake; AskUserQuestion for missing fields | Deferred-placeholder pattern; no AskUserQuestion |
+| README refresh | P094 inline (regenerate + stage in same commit) | Deferred to next `/wr-itil:review-problems` |
+| Status transitions | Step 7 owns Open → Known Error → Verifying → Closed | Out of scope (creation only) |
+| Commit grain | One commit per intake (or per split-concern set) | One commit per capture |
+| Use case | Full-intake new problem; user wants to walk the flow | Aside-invocation; capture-and-continue |
+
+The two skills share the `/tmp/manage-problem-grep-${SESSION_ID}` create-gate marker per P119 — calling either skill's Step 2 grep + mark sequence permits new ticket Writes for the rest of the session, regardless of which skill landed first.
+
+## Related
+
+- **P155** (`docs/problems/155-ship-capture-problem-skill.open.md`) — driver ticket.
+- **P014** (`docs/problems/014-aside-invocation-for-governance-skills.open.md`) — parent / master tracker.
+- **P078** — capture-on-correction OFFER pattern; depends on capture-problem shipping.
+- **P119** — manage-problem create-gate hook; capture-problem composes with the same marker.
+- **ADR-032** (`docs/decisions/032-governance-skill-invocation-patterns.proposed.md`) — foreground-lightweight-capture variant amendment.
+- **ADR-038** — progressive-disclosure pattern (SKILL.md + REFERENCE.md split).
+- **ADR-044** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **ADR-049** — bin/ on PATH; capture-problem reuses the existing `wr-itil-reconcile-readme` shim.
+- **ADR-052** — behavioural-tests-default for skill testing.
+- `packages/itil/skills/manage-problem/SKILL.md` — heavyweight intake counterpart.
+- `packages/itil/skills/review-problems/SKILL.md` — re-rates the deferred placeholders + refreshes README.md.
+
+$ARGUMENTS

package/skills/capture-problem/test/capture-problem.bats

@@ -0,0 +1,300 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for /wr-itil:capture-problem (P155).
+#
+# Per ADR-052 (Behavioural-tests-default for skill testing), these tests
+# exercise the load-bearing primitives the skill dispatches and assert
+# observable state — NOT the prose contents of SKILL.md.
+#
+# Behavioural surfaces under test:
+#   1. P119 create-gate composition — capture-problem must source the
+#      session-id + create-gate helpers and call mark_step2_complete
+#      before the Write so the PreToolUse hook permits the new ticket
+#      file to land. Test simulates the helper-sourcing sequence and
+#      asserts the marker file lands in /tmp.
+#   2. Skeleton-fill ticket shape — captured ticket has Description from
+#      $ARGUMENTS plus the deferred-placeholder fields the skill
+#      prescribes. Test runs the skeleton-fill command sequence against
+#      a fixture description and asserts the resulting file's sections.
+#   3. Next-ID computation — capture-problem reuses the manage-problem
+#      Step 3 P056-safe local_max + origin_max formula. Test runs the
+#      formula against a fixture problems directory and asserts the
+#      computed next ID matches the expected zero-padded value.
+#   4. Conservative title-only duplicate-grep — 3-keyword cap, filename
+#      matches only (NOT body). Test runs the grep pattern against a
+#      fixture and asserts the conservative match shape.
+#
+# @problem P155
+# @jtbd JTBD-001 (enforce governance without slowing down — lightweight
+#                  capture path)
+# @jtbd JTBD-006 (progress backlog while AFK — sibling-finding capture
+#                  in iter subprocesses)
+# @jtbd JTBD-101 (extend the suite — discoverable / on /  autocomplete)
+# @adr ADR-032 (governance skill invocation patterns — foreground-
+#                lightweight-capture variant)
+# @adr ADR-038 (progressive disclosure — SKILL.md + REFERENCE.md split)
+# @adr ADR-049 (bin/ on PATH — capture-problem reuses existing
+#                wr-itil-reconcile-readme shim, no new shim needed)
+# @adr ADR-052 (behavioural-tests-default — these tests exercise
+#                primitives, not SKILL.md prose)
+# @adr ADR-119 (manage-problem create-gate — capture-problem composes
+#                with the same per-session marker)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_DIR="${REPO_ROOT}/packages/itil/skills/capture-problem"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+  REF_FILE="${SKILL_DIR}/REFERENCE.md"
+  CREATE_GATE_LIB="${REPO_ROOT}/packages/itil/hooks/lib/create-gate.sh"
+
+  # Fresh per-test scratch directory and SESSION_ID.
+  TMPROOT=$(mktemp -d)
+  TEST_SESSION_ID="capture-problem-bats-$BATS_TEST_NUMBER-$$"
+  MARKER_PATH="/tmp/manage-problem-grep-${TEST_SESSION_ID}"
+  rm -f "$MARKER_PATH"
+}
+
+teardown() {
+  rm -rf "$TMPROOT"
+  rm -f "$MARKER_PATH"
+}
+
+# ---------------------------------------------------------------------------
+# Existence / wiring tests — minimum surface required for the skill to be
+# discoverable. Not structural prose-greps; these assert artefacts exist.
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: SKILL.md and REFERENCE.md both exist (ADR-038 split)" {
+  [ -f "$SKILL_FILE" ]
+  [ -f "$REF_FILE" ]
+}
+
+@test "capture-problem: SKILL.md frontmatter declares wr-itil:capture-problem name" {
+  # Discoverable on / autocomplete depends on the canonical name.
+  # ADR-032 names this skill; ADR-010-amended skill-granularity rule.
+  run grep -E '^name: wr-itil:capture-problem$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# P119 create-gate composition — load-bearing behavioural primitive.
+# capture-problem must call mark_step2_complete before any Write of a new
+# ticket file, otherwise the PreToolUse:Write hook denies the Write.
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: mark_step2_complete writes marker the P119 hook checks" {
+  # Source the helper the skill prescribes; call the canonical mark
+  # function; assert the marker file lands at the path the hook reads.
+  source "$CREATE_GATE_LIB"
+  mark_step2_complete "$TEST_SESSION_ID"
+  [ -f "$MARKER_PATH" ]
+}
+
+@test "capture-problem: check_create_gate returns 0 after mark_step2_complete" {
+  # Composes with manage-problem-enforce-create.sh which uses
+  # check_create_gate $SESSION_ID — exit 0 means "permit Write".
+  source "$CREATE_GATE_LIB"
+  run check_create_gate "$TEST_SESSION_ID"
+  [ "$status" -ne 0 ]    # before mark — denied
+  mark_step2_complete "$TEST_SESSION_ID"
+  run check_create_gate "$TEST_SESSION_ID"
+  [ "$status" -eq 0 ]    # after mark — permitted
+}
+
+@test "capture-problem: mark_step2_complete is idempotent across cross-skill order" {
+  # Whether manage-problem fires first then capture-problem, or vice
+  # versa, the marker mechanic is a no-op after the first call.
+  source "$CREATE_GATE_LIB"
+  mark_step2_complete "$TEST_SESSION_ID"
+  mark_step2_complete "$TEST_SESSION_ID"
+  mark_step2_complete "$TEST_SESSION_ID"
+  [ -f "$MARKER_PATH" ]
+}
+
+# ---------------------------------------------------------------------------
+# Next-ID computation — capture-problem reuses manage-problem Step 3 formula
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: next-ID formula is P056-safe (origin/local max + 1)" {
+  # Build a fixture problems directory with mixed status suffixes.
+  # The formula must pick the max ID across all suffixes and zero-pad.
+  mkdir -p "$TMPROOT/docs/problems"
+  : > "$TMPROOT/docs/problems/001-foo.closed.md"
+  : > "$TMPROOT/docs/problems/042-bar.open.md"
+  : > "$TMPROOT/docs/problems/099-baz.known-error.md"
+  : > "$TMPROOT/docs/problems/107-qux.verifying.md"
+
+  # Mirror manage-problem Step 3 local-max formula exactly.
+  local_max=$(ls "$TMPROOT/docs/problems"/*.md 2>/dev/null \
+              | sed 's/.*\///' \
+              | grep -oE '^[0-9]+' \
+              | sort -n | tail -1)
+  [ "$local_max" = "107" ]
+
+  # No origin available in the fixture; default to 0 then increment.
+  next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n0" | sort -n | tail -1) + 1 )))
+  [ "$next" = "108" ]
+}
+
+@test "capture-problem: next-ID handles empty problems dir (first ticket)" {
+  mkdir -p "$TMPROOT/docs/problems"
+  local_max=$(ls "$TMPROOT/docs/problems"/*.md 2>/dev/null \
+              | sed 's/.*\///' \
+              | grep -oE '^[0-9]+' \
+              | sort -n | tail -1)
+  next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n0" | sort -n | tail -1) + 1 )))
+  [ "$next" = "001" ]
+}
+
+# ---------------------------------------------------------------------------
+# Conservative duplicate-grep — title-only filename match, 3-keyword cap.
+# Architect Q1 verdict: title-only because conservative threshold rationale
+# (P155 line 24) — false-positives on body text would either over-prompt
+# or be silently swallowed (capture-problem has no AskUserQuestion).
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: duplicate-grep matches kebab-cased keywords in filenames" {
+  mkdir -p "$TMPROOT/docs/problems"
+  : > "$TMPROOT/docs/problems/050-checkpoint-stuck-saving.open.md"
+  : > "$TMPROOT/docs/problems/051-foul-drawn-garbled.closed.md"
+
+  # Description: "checkpoint stuck on save retry" — extract 3 kebab tokens.
+  # Title-only grep against filenames; bodies are NOT scanned (conservative).
+  match_count=$(ls "$TMPROOT/docs/problems"/*.md \
+                | grep -ciE 'checkpoint|stuck|save' || true)
+  [ "$match_count" -ge 1 ]
+}
+
+@test "capture-problem: duplicate-grep does NOT match keywords in body content (title-only)" {
+  mkdir -p "$TMPROOT/docs/problems"
+  # File whose title has zero overlap but whose body mentions checkpoint
+  cat > "$TMPROOT/docs/problems/060-unrelated.open.md" <<'EOF'
+# Unrelated ticket
+Body mentions checkpoint somewhere but title doesn't.
+EOF
+
+  # Title-only grep on filenames must NOT match.
+  match_count=$(ls "$TMPROOT/docs/problems"/*.md \
+                | grep -ciE 'checkpoint' || true)
+  [ "$match_count" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Skeleton-fill ticket shape — capture-problem writes a deferred-placeholder
+# ticket. Default Priority and Effort are flagged for re-rate at next review.
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: skeleton-filled ticket carries the deferred-placeholder pattern" {
+  mkdir -p "$TMPROOT/docs/problems"
+  TITLE="example-aside-finding"
+  ID="200"
+  TODAY=$(date -u +%Y-%m-%d)
+  DESCRIPTION="Quick observation worth a ticket but not blocking."
+
+  # Mirror the SKILL.md skeleton-fill template.
+  cat > "$TMPROOT/docs/problems/${ID}-${TITLE}.open.md" <<EOF
+# Problem ${ID}: ${TITLE}
+
+**Status**: Open
+**Reported**: ${TODAY}
+**Priority**: 3 (Medium) — Impact: 3 x Likelihood: 1 (deferred — re-rate at next /wr-itil:review-problems)
+**Effort**: M (deferred — re-rate at next /wr-itil:review-problems)
+
+## Description
+
+${DESCRIPTION}
+
+## Symptoms
+
+(deferred to investigation)
+
+## Workaround
+
+(deferred to investigation)
+
+## Impact Assessment
+
+- **Who is affected**: (deferred to investigation)
+- **Frequency**: (deferred to investigation)
+- **Severity**: (deferred to investigation)
+- **Analytics**: (deferred to investigation)
+
+## Root Cause Analysis
+
+### Investigation Tasks
+
+- [ ] Re-rate Priority and Effort at next /wr-itil:review-problems
+- [ ] Investigate root cause
+- [ ] Create reproduction test
+
+## Dependencies
+
+- **Blocks**: (none)
+- **Blocked by**: (none)
+- **Composes with**: (none)
+
+## Related
+
+(captured via /wr-itil:capture-problem; expand at next investigation)
+EOF
+
+  # Behavioural assertions: ticket file has the load-bearing fields.
+  TICKET="$TMPROOT/docs/problems/${ID}-${TITLE}.open.md"
+  [ -f "$TICKET" ]
+  run grep -F '**Status**: Open' "$TICKET"
+  [ "$status" -eq 0 ]
+  # Description survives verbatim
+  run grep -F "$DESCRIPTION" "$TICKET"
+  [ "$status" -eq 0 ]
+  # Deferred placeholders flag re-rating
+  run grep -F 'deferred — re-rate at next /wr-itil:review-problems' "$TICKET"
+  [ "$status" -eq 0 ]
+  # Investigation Tasks nudges user to re-rate
+  run grep -F 'Re-rate Priority and Effort at next /wr-itil:review-problems' "$TICKET"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Skill-allowed-tools surface contract — capture-problem MUST NOT carry
+# AskUserQuestion (per design Q4 + ADR-044 framework-mediated mechanical-
+# stage decisions). This is observable from the frontmatter declaration
+# the runtime consumes.
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: allowed-tools omits AskUserQuestion (no interactive branches)" {
+  # The skill's contract is NO AskUserQuestion at all — duplicate-check,
+  # priority-default, effort-default are framework-mediated mechanical
+  # stages per ADR-044. AskUserQuestion in allowed-tools would let
+  # future drift sneak prompts back in.
+  run grep -E '^allowed-tools:' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -E '^allowed-tools:.*AskUserQuestion' "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "capture-problem: allowed-tools includes Bash (for create-gate marker write)" {
+  # mark_step2_complete via Bash is the load-bearing primitive — without
+  # Bash in allowed-tools the skill cannot satisfy P119.
+  run grep -E '^allowed-tools:.*Bash' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "capture-problem: allowed-tools includes Write (for new ticket file)" {
+  run grep -E '^allowed-tools:.*Write' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Deferred-README-refresh contract — distinguishing capture-problem from
+# manage-problem. capture-problem must NOT stage docs/problems/README.md
+# in its commit (deferred to /wr-itil:review-problems).
+# ---------------------------------------------------------------------------
+
+@test "capture-problem: SKILL.md prescribes deferred README refresh (no inline P094 block)" {
+  # The contract distinction from manage-problem: capture-problem does
+  # NOT regenerate README.md inline; it defers to /wr-itil:review-problems.
+  # This is a behavioural primitive — a future maintainer who copies the
+  # P094 block over would break the lightweight-capture promise.
+  # Asserts the SKILL.md names the deferred contract explicitly.
+  run grep -F '/wr-itil:review-problems' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/SKILL.md

@@ -244,6 +244,15 @@ ITER_JSON=$(mktemp)
 DISPATCH_START_EPOCH=$(date +%s)
 IDLE_TIMEOUT_S="${WORK_PROBLEMS_IDLE_TIMEOUT_S:-3600}"
 
+# AFK-iter cross-context-leak guard (ADR-032 P157 amendment, line 127):
+# the orchestrator-session pending-questions queue at
+# .afk-run-state/outstanding-questions.jsonl is for surfacing on the user's
+# next interactive session — NOT inside iter subprocess contexts. The
+# itil-pending-questions-surface.sh SessionStart hook self-suppresses when
+# this env var is set so the orchestrator's accumulated queue does not leak
+# into iter subprocesses' first turn.
+export WR_SUPPRESS_PENDING_QUESTIONS=1
+
 claude -p \
   --permission-mode bypassPermissions \
   --output-format json \