@windyroad/itil 0.18.1 → 0.19.0

package/.claude-plugin/plugin.json

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

package/hooks/hooks.json

@@ -2,6 +2,12 @@
   "hooks": {
     "SessionStart": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-itil wr-risk-scorer" }] }
+    ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-gate.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-review.sh" }] }
     ]
   }
 }

package/hooks/itil-assistant-output-gate.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# P085 / ADR-013 / ADR-038: itil UserPromptSubmit gate.
+#
+# When the incoming user prompt contains a direction-pinning signal
+# (yes / go ahead / just do it / act now / proceed / ...), inject a
+# MANDATORY reminder so the assistant acts instead of surfacing a
+# prose consent gate. Once-per-session full block; terse reminder on
+# subsequent direction-pin prompts.
+#
+# Companion: itil-assistant-output-review.sh (Stop hook) catches any
+# prose-ask that slipped through on the way out.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/session-marker.sh
+source "$SCRIPT_DIR/lib/session-marker.sh"
+# shellcheck source=lib/detectors.sh
+source "$SCRIPT_DIR/lib/detectors.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+
+# Guard: if the prompt carries no direction-pinning signal, do nothing.
+# Burning the announcement marker on non-direction prompts would waste
+# the once-per-session budget on no-op context.
+if [ -z "$PROMPT" ] || ! echo "$PROMPT" | detect_direction_pin >/dev/null; then
+  exit 0
+fi
+
+if has_announced "itil-assistant-gate" "$SESSION_ID"; then
+  cat <<'HOOK_OUTPUT'
+MANDATORY: direction pinned. Act on obvious next step; use AskUserQuestion tool for genuine ambiguity; NEVER prose-ask. See ADR-013.
+HOOK_OUTPUT
+else
+  cat <<'HOOK_OUTPUT'
+INSTRUCTION: MANDATORY — act on obvious decisions; NEVER prose-ask.
+DETECTED: incoming user prompt contains a direction-pinning signal
+(yes / go / proceed / act / just do it / ...).
+
+NON-OPTIONAL RULES:
+
+1. If the next step is obvious from the user's direction, session
+   context, or RISK-POLICY.md appetite, ACT. Do NOT surface a consent
+   gate. Do NOT ask "Want me to...?" or "Should I...?".
+
+2. If the decision is genuinely ambiguous (multiple-valid-paths, none
+   clearly better per direction/policy), use the AskUserQuestion tool.
+   Never prose-ask. Prose questions are unanswerable under AFK
+   notifications and violate ADR-013 Rule 1.
+
+3. Canonical prose-ask phrasings to AVOID in your next response:
+   "Want me to", "Should I", "Would you like me to", "Shall we",
+   "Let me know if", "Do you want to", "Option A or Option B?",
+   "(a) / (b) / (c)?". If one of these is about to appear at the end
+   of your turn, stop and re-route via AskUserQuestion or just act.
+
+4. The combined rule: obvious default => act; genuine ambiguity =>
+   AskUserQuestion tool; NEVER prose-ask.
+
+See:
+- ~/.claude/projects/.../memory/feedback_act_on_obvious_decisions.md
+- docs/decisions/013-structured-user-interaction-for-governance-decisions.*.md
+- Companion Stop hook (itil-assistant-output-review.sh) scans your
+  emitted turn for the patterns above and nudges if any slip through.
+HOOK_OUTPUT
+  mark_announced "itil-assistant-gate" "$SESSION_ID"
+fi
+
+exit 0

package/hooks/itil-assistant-output-review.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# P085 / ADR-013: itil Stop hook.
+#
+# Reads the last assistant turn from transcript_path on stdin and scans
+# for canonical prose-ask phrasings. If a prose-ask is detected (and
+# the turn does NOT contain an AskUserQuestion tool_use call), emits
+# a stopReason nudge instructing the assistant to re-emit via
+# AskUserQuestion — or act, if the decision was obvious.
+#
+# Stop hooks cannot rewrite the emitted turn; the nudge biases the
+# next turn. Pairs with UserPromptSubmit gate for defence in depth.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/detectors.sh
+source "$SCRIPT_DIR/lib/detectors.sh"
+
+INPUT=$(cat)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || echo "")
+
+# Graceful fallback: no transcript_path or file missing means nothing
+# to review. Exit clean — the hook is advisory, never blocking.
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Extract the last assistant turn's concatenated text content. Claude
+# Code transcript format: JSONL, each line a {type, message} object;
+# assistant `message.content` is an array of content blocks (text,
+# tool_use, thinking, ...). We want the concatenation of `text` blocks
+# from the last `type: assistant` line.
+LAST_ASSISTANT=$(grep -E '"type"[[:space:]]*:[[:space:]]*"assistant"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -n 1 || true)
+if [ -z "$LAST_ASSISTANT" ]; then
+  exit 0
+fi
+
+# If the last assistant turn used AskUserQuestion, the assistant chose
+# the structured path — don't nudge.
+if echo "$LAST_ASSISTANT" | jq -e '.message.content | map(select(.type == "tool_use" and .name == "AskUserQuestion")) | length > 0' >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Concatenate every text block in the turn.
+ASSISTANT_TEXT=$(echo "$LAST_ASSISTANT" | jq -r '
+  .message.content
+  | if type == "array" then map(select(.type == "text") | .text) | join("\n")
+    elif type == "string" then .
+    else "" end
+' 2>/dev/null || echo "")
+
+if [ -z "$ASSISTANT_TEXT" ]; then
+  exit 0
+fi
+
+# Scan for prose-ask patterns. If none match, exit silently.
+MATCH=$(echo "$ASSISTANT_TEXT" | detect_prose_ask 2>/dev/null) || true
+if [ -z "$MATCH" ]; then
+  exit 0
+fi
+
+# Emit stopReason. Structured JSON so Claude Code injects the nudge
+# into the next assistant context. The user does not see this — the
+# next turn does.
+jq -n --arg match "$MATCH" '{
+  stopReason: (
+    "PROSE-ASK DETECTED in your last turn (pattern: \"" + $match + "\"). " +
+    "If the decision is obvious from direction / policy / session context, ACT — do not ask. " +
+    "If genuinely ambiguous, re-emit via the AskUserQuestion tool. " +
+    "Never prose-ask. See ADR-013 Rule 1 + feedback_act_on_obvious_decisions.md."
+  )
+}'
+
+exit 0

package/hooks/lib/detectors.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# P085 detector registry: assistant-output-gate + assistant-output-review.
+#
+# Two detection functions sharing a single library so the UserPromptSubmit
+# pre-generation reminder (gate) and the Stop post-hoc review use the
+# same canonical phrasing list — one place to update when a new prose-ask
+# pattern lands.
+#
+# Composition: this registry is the shape P078 (correction->ticket) and
+# future itil assistant-output validators extend. Each detector is a
+# pure function — takes text on stdin or as $1, exits 0 on match,
+# non-zero on no-match.
+
+# Canonical prose-ask phrasings — the patterns that should be emitted
+# via AskUserQuestion instead. Extracted from P085 ticket + memory
+# feedback_act_on_obvious_decisions.md.
+#
+# Case-insensitive, anchored to word boundaries where meaningful.
+# Grep -E extended regex. Each entry is a separate alternation group
+# in case future detectors want to report which phrase matched.
+PROSE_ASK_PATTERNS=(
+  'Want me to'
+  'Should I\b'
+  'Would you like me to'
+  'Shall we\b'
+  'Shall I\b'
+  'Let me know if'
+  'Do you want (me )?to'
+  'Do you want to'
+  'Option [A-Z][:.]? .*Option [A-Z]'
+  '\([a-c]\).*\([a-c]\).*\([a-c]\)'
+  '\([a-c]\) ?/ ?\([a-c]\)'
+  '\(1\) .*\(2\)'
+  'Which (do you|option|one|path) .*\?'
+)
+
+# Direction-pinning patterns — signals in the user's incoming prompt
+# that the next step is obvious and the assistant should act, not ask.
+# Extracted from feedback_act_on_obvious_decisions.md.
+DIRECTION_PIN_PATTERNS=(
+  '\byes\b'
+  '\bgo ahead\b'
+  '\bjust do it\b'
+  '\bjust go\b'
+  '\bproceed\b'
+  '\bact now\b'
+  '\bact on\b'
+  '\bdo it\b'
+  '\bmake it so\b'
+  '\bdrain\b'
+  '\bship it\b'
+)
+
+# detect_prose_ask: scans text on stdin for canonical prose-ask
+# phrasings. Exits 0 if any pattern matches, 1 otherwise. Writes the
+# first matched phrase to stdout (for observability in the Stop hook
+# stopReason).
+#
+# Usage:
+#   if echo "$text" | detect_prose_ask > /dev/null; then ... fi
+detect_prose_ask() {
+  local text
+  text=$(cat)
+  local pattern
+  for pattern in "${PROSE_ASK_PATTERNS[@]}"; do
+    if echo "$text" | grep -Eqi -- "$pattern"; then
+      echo "$pattern"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# detect_direction_pin: scans text on stdin for direction-pinning
+# signals. Exits 0 if any pattern matches, 1 otherwise.
+#
+# Usage:
+#   if echo "$prompt" | detect_direction_pin > /dev/null; then ... fi
+detect_direction_pin() {
+  local text
+  text=$(cat)
+  local pattern
+  for pattern in "${DIRECTION_PIN_PATTERNS[@]}"; do
+    if echo "$text" | grep -Eqi -- "$pattern"; then
+      echo "$pattern"
+      return 0
+    fi
+  done
+  return 1
+}

package/hooks/lib/session-marker.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Shared session-announcement marker helpers (P095 / ADR-038).
+#
+# Used by UserPromptSubmit hooks to gate verbose MANDATORY instruction
+# prose behind a once-per-session check. First prompt of a session emits
+# the full block AND calls mark_announced; subsequent prompts see the
+# marker via has_announced and emit only a terse reminder.
+#
+# Why no TTL or drift check (unlike review-gate.sh): announcement is
+# bookkeeping for prose verbosity, not enforcement. PreToolUse gates
+# still block unauthorised edits regardless of announcement state; the
+# delegated agent re-reads policy when it runs. Extending the marker's
+# lifetime across policy changes mid-session is safe — the gate, not
+# the announcement, is load-bearing.
+#
+# Marker path convention: /tmp/${SYSTEM}-announced-${SESSION_ID}
+# (mirrors the /tmp/${SYSTEM}-reviewed-${SESSION_ID} convention from
+# style-guide/voice-tone/risk-scorer review-gate.sh; the -announced-
+# suffix distinguishes announcement markers from clearance markers).
+#
+# Empty SESSION_ID fallback: has_announced returns 1 (not announced,
+# full block emits) and mark_announced is a no-op (no file written).
+# This covers manual hook invocation, test harnesses, and any rare
+# case where Claude Code does not pass a session_id on stdin.
+
+# Returns 0 if the hook for SYSTEM has already announced in SESSION_ID,
+# 1 otherwise. Empty SESSION_ID => returns 1 (never announced).
+#
+# Usage: has_announced "architect" "$SESSION_ID"
+has_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 1
+  [ -f "/tmp/${SYSTEM}-announced-${SESSION_ID}" ]
+}
+
+# Writes the announcement marker for SYSTEM in SESSION_ID. Empty
+# SESSION_ID => no-op. Safe to call more than once per session.
+#
+# Usage: mark_announced "architect" "$SESSION_ID"
+mark_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 0
+  : > "/tmp/${SYSTEM}-announced-${SESSION_ID}"
+}

package/hooks/test/itil-assistant-output-gate.bats

@@ -0,0 +1,114 @@
+#!/usr/bin/env bats
+
+# P085: itil-assistant-output-gate.sh UserPromptSubmit hook must detect
+# when the user's incoming prompt pins a direction / confirms a prior
+# ask / issues an act-verb, and inject a once-per-session MANDATORY
+# reminder instructing the assistant to act without asking — or use
+# AskUserQuestion for genuine ambiguity — and NEVER prose-ask.
+#
+# Per ADR-038: full block emits once per session; subsequent prompts
+# emit a terse reminder (<250 bytes) that keeps the MANDATORY signal,
+# the gate name, and the AskUserQuestion affordance.
+#
+# Per feedback_behavioural_tests.md (P081): these are behavioural
+# assertions — they simulate the hook's payload on stdin and assert
+# on what the hook emits, not on the source text of the hook file.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/itil/hooks/itil-assistant-output-gate.sh"
+  SID="itil-gate-test-$$-$RANDOM"
+}
+
+teardown() {
+  rm -f "/tmp/itil-assistant-gate-announced-${SID}"
+  rm -f "/tmp/itil-assistant-gate-announced-${SID}-alt"
+}
+
+run_hook() {
+  local sid="$1"
+  local prompt="$2"
+  echo "{\"session_id\":\"$sid\",\"prompt\":$(printf '%s' "$prompt" | jq -Rs .)}" | bash "$HOOK"
+}
+
+@test "gate: emits full MANDATORY block on first direction-pin prompt" {
+  run run_hook "$SID" "yes, update P084 and verify the subagent tools thing"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY"* ]]
+  [[ "$output" == *"AskUserQuestion"* ]]
+  [[ "$output" == *"obvious"* ]] || [[ "$output" == *"act"* ]]
+}
+
+@test "gate: writes the announcement marker on first emission" {
+  run run_hook "$SID" "go ahead and do it"
+  [ "$status" -eq 0 ]
+  [ -f "/tmp/itil-assistant-gate-announced-${SID}" ]
+}
+
+@test "gate: second direction-pin prompt in same session emits terse reminder only" {
+  run_hook "$SID" "yes, please proceed" >/dev/null
+  # Second prompt also pins direction (required for the gate to fire).
+  run run_hook "$SID" "yes, go ahead"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -lt 250 ]
+  [[ "$output" == *"AskUserQuestion"* ]]
+  # Full block is NOT re-emitted
+  [[ "$output" != *"Canonical prose-ask phrasings"* ]]
+}
+
+@test "gate: terse reminder preserves MANDATORY / REQUIRED signal word" {
+  run_hook "$SID" "yes" >/dev/null
+  run run_hook "$SID" "act on this"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"MANDATORY"* ]] || [[ "$output" == *"REQUIRED"* ]] || [[ "$output" == *"NON-OPTIONAL"* ]]
+}
+
+@test "gate: different session_id re-emits the full block" {
+  run_hook "$SID" "yes" >/dev/null
+  local SID2="${SID}-alt"
+  run run_hook "$SID2" "yes"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  rm -f "/tmp/itil-assistant-gate-announced-${SID2}"
+}
+
+@test "gate: empty session_id emits the full block and writes no marker" {
+  run run_hook "" "yes, go"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  [ ! -f "/tmp/itil-assistant-gate-announced-" ]
+}
+
+@test "gate: non-direction-pinning prompt does not emit a block" {
+  # A conversational prompt with no direction/act-verb/yes signal
+  # should not burn the session-marker budget.
+  run run_hook "$SID" "what does ADR-013 say about ambiguous decisions?"
+  [ "$status" -eq 0 ]
+  # May emit a short neutral note OR nothing, but must not emit the
+  # full MANDATORY block on a non-direction prompt.
+  [[ "$output" != *"MANDATORY: act"* ]] || [ "${#output}" -lt 250 ]
+  # Must not have written the announcement marker either.
+  [ ! -f "/tmp/itil-assistant-gate-announced-${SID}" ]
+}
+
+@test "gate: direction-pin via 'act now' verb triggers the block" {
+  run run_hook "$SID" "act now and close the ticket"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY"* ]]
+}
+
+@test "gate: direction-pin via 'just do it' triggers the block" {
+  run run_hook "$SID" "just do it"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY"* ]]
+}
+
+@test "gate: terse reminder references AskUserQuestion" {
+  run_hook "$SID" "yes" >/dev/null
+  run run_hook "$SID" "proceed"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"AskUserQuestion"* ]]
+}

package/hooks/test/itil-assistant-output-review.bats

@@ -0,0 +1,136 @@
+#!/usr/bin/env bats
+
+# P085: itil-assistant-output-review.sh Stop hook reads the last
+# assistant turn from the transcript at `transcript_path` on stdin and
+# scans for canonical prose-ask phrasings ("Want me to", "Should I",
+# "Option A or Option B", etc.). When a prose-ask is detected, the
+# hook emits a stopReason JSON object with a nudge instructing the
+# assistant to re-emit via AskUserQuestion (or to act, if the decision
+# was obvious). Clean turns pass silently (no stopReason field).
+#
+# The Stop hook cannot rewrite the emitted turn — only nudge the next
+# turn — so its job is post-hoc detection + durable signal, per the
+# architect verdict for P085.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/itil/hooks/itil-assistant-output-review.sh"
+  TMPDIR_="$(mktemp -d)"
+  TRANSCRIPT="$TMPDIR_/transcript.jsonl"
+}
+
+teardown() {
+  rm -rf "$TMPDIR_"
+}
+
+# Writes a JSONL transcript with a user message followed by an
+# assistant message. Claude Code transcript format: each line is a
+# JSON object with `type: user|assistant` and `message.content` being
+# either a string or an array of content blocks (text/tool_use).
+write_transcript() {
+  local user_text="$1"
+  local assistant_text="$2"
+  {
+    printf '{"type":"user","message":{"role":"user","content":%s}}\n' "$(printf '%s' "$user_text" | jq -Rs .)"
+    printf '{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":%s}]}}\n' "$(printf '%s' "$assistant_text" | jq -Rs .)"
+  } > "$TRANSCRIPT"
+}
+
+run_hook() {
+  echo "{\"session_id\":\"stop-test\",\"transcript_path\":$(printf '%s' "$TRANSCRIPT" | jq -Rs .)}" | bash "$HOOK"
+}
+
+@test "review: 'Want me to' in assistant text triggers stopReason nudge" {
+  write_transcript "update the ticket" "Done. Want me to also commit now or wait?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+  [[ "$output" == *"AskUserQuestion"* ]]
+}
+
+@test "review: 'Should I' in assistant text triggers stopReason nudge" {
+  write_transcript "look at this" "I see the issue. Should I fix it now or wait for review?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: 'Would you like me to' triggers stopReason nudge" {
+  write_transcript "ok" "Ticket updated. Would you like me to open a PR next?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: 'Option A or Option B' triggers stopReason nudge" {
+  write_transcript "plan this" "Two paths: Option A: do it inline. Or Option B: split into two commits. Which do you prefer?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: '(a) / (b) / (c)?' triggers stopReason nudge" {
+  write_transcript "go" "Three choices: (a) ship now, (b) wait for review, or (c) add tests first?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: clean informative turn does not trigger stopReason" {
+  write_transcript "what changed" "The last commit added three files: detectors.sh, gate.sh, and review.sh. No new decisions were introduced."
+  run run_hook
+  [ "$status" -eq 0 ]
+  # Clean output: either empty or a JSON object WITHOUT stopReason.
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "review: assistant turn containing AskUserQuestion tool_use does NOT flag" {
+  # If the assistant used the AskUserQuestion tool, that's the compliant
+  # path — we must not nudge them for using prose inside the tool's
+  # rendered question text (the tool surface is structured).
+  {
+    printf '{"type":"user","message":{"role":"user","content":"plan this"}}\n'
+    cat <<'JSON'
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Here is the choice:"},{"type":"tool_use","name":"AskUserQuestion","input":{"question":"Which option?","options":[{"label":"A"},{"label":"B"}]}}]}}
+JSON
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "review: missing transcript_path exits cleanly without error" {
+  run bash -c 'echo "{\"session_id\":\"sid\"}" | bash "$1"' -- "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "review: non-existent transcript file exits cleanly without error" {
+  run bash -c "echo '{\"session_id\":\"sid\",\"transcript_path\":\"/tmp/does-not-exist-$RANDOM\"}' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "review: ask-when-obvious pattern triggers stopReason" {
+  # Prior user message pins direction ("yes, update the ticket"), next
+  # assistant turn ends with a question mark on an obvious-next-step.
+  # This is Facet A of P085 — asking when the answer is obvious.
+  write_transcript "yes, update the ticket with the findings" "Updated. Want me to commit and close the ticket now, or leave it open for review?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: 'Shall we' triggers stopReason nudge" {
+  write_transcript "look at options" "That's one route. Shall we go with it?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "review: 'Do you want to' triggers stopReason nudge" {
+  write_transcript "plan" "I can split into two PRs. Do you want to go that route?"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}

package/package.json

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

package/skills/work-problems/SKILL.md

@@ -36,6 +36,29 @@ Before opening the work loop, reconcile local state with origin so the orchestra
 
 **Cross-cutting**: this rule applies to every AFK orchestrator skill. The next-ID collision guard (ADR-019 confirmation criterion 2) belongs in the ticket-creator skills (`manage-problem` and `wr-architect:create-adr`), not here — see the related problem ticket for that work.
 
+#### Session-continuity detection pass (per P109)
+
+After the fetch/divergence check, Step 0 MUST run a session-continuity detection pass. The divergence check handles "did origin move under us"; this pass handles the distinct failure mode "did the prior session leave partial work that changes what iter 1 should do". A prior AFK subprocess can exit mid-ticket (quota 429, user-cancel, subprocess crash) and leave observable state in the working tree that the orchestrator must classify before opening the work loop.
+
+**Signals to enumerate** (each maps to one `git status --porcelain` / filesystem / `git worktree` probe):
+
+| Signal | Detection |
+|---|---|
+| Untracked `docs/decisions/*.proposed.md` | `git status --porcelain docs/decisions/` filtered for `??` entries ending `.proposed.md` — drafted but unlanded ADRs from a prior iter. |
+| Untracked `docs/problems/*.md` | `git status --porcelain docs/problems/` filtered for `??` entries ending `.md` — drafted but unlanded problem tickets. |
+| `.afk-run-state/iter-*.json` error markers | Files under `.afk-run-state/` containing `"is_error": true` OR `"api_error_status" >= 400` — prior iteration hit quota or API error; its work is likely partial. Success files (`"is_error": false`) are ignored. Contract source: ADR-032 subprocess artefact. |
+| Stale `.claude/worktrees/*` dirs + matching `claude/*` branches | `git worktree list` filtered on `claude/*` branches adjacent to `.claude/worktrees/*` directories — prior subagent worktrees that were not cleaned up. Detection only — mutation (cleanup) is out of scope and requires a separate ADR. |
+| Uncommitted modifications to SKILL.md / source / ADR files | `git status --porcelain` filtered for `M ` / ` M` entries on `packages/*/skills/*/SKILL.md`, `packages/*/hooks/*`, `docs/decisions/*.proposed.md`, or other source paths the prior session was mid-authoring. |
+
+**Classification**: when any signal is present, build a structured Prior-Session State report listing each hit (signal category, path, one-line summary). An empty signal set means clean pass-through to Step 1.
+
+**Routing on interactive-vs-AFK (per ADR-013 Rule 1 / Rule 6):**
+
+- **Interactive** (`AskUserQuestion` is available AND the loop was not started in AFK mode): prompt the user with the Prior-Session State report and four options — **Resume the prior work** (land the drafted files as iter 1), **Discard the draft** and restart from scratch, **Leave-and-lower-priority** (skip the dirty paths and work the next backlog item that doesn't touch them), **Halt the loop** (too much dirty state to proceed non-interactively). Route the chosen branch before opening Step 1.
+- **Non-interactive / AFK** (default for this skill per JTBD-006): do NOT call `AskUserQuestion`. Halt the loop with the structured Prior-Session State report in the AFK summary. Per ADR-013 Rule 6 fail-safe: ambiguous session-continuity state requires user input; non-interactive recovery would mask the bug this check is meant to surface. This matches Step 6.75's "dirty for unknown reason → halt" stance at the Step 0 layer — the orchestrator does not silently proceed past partial work.
+
+Step 6.75 treats a Step-0-resolved-with-user-confirmation state as `dirty-for-known-reason`: if the interactive branch's Resume option landed the drafted ADR as iter 1, the iter's commit clears the dirty state and the rest of the loop proceeds normally.
+
 ### Step 1: Scan the backlog
 
 Read `docs/problems/README.md` if it exists and is fresh (check via git history — see manage-problem step 9 for the cache freshness check). If stale or missing, scan all `.open.md` and `.known-error.md` files in `docs/problems/`, extract their WSJF scores, and rank them.
@@ -339,6 +362,7 @@ When `AskUserQuestion` is unavailable or the user is AFK, the skill (and the del
 | Pipeline risk at appetite (push or release = 4/25) | Drain release queue (`push:watch` then `release:watch`) before next iteration — per ADR-018 (Step 6.5) |
 | Pipeline risk above appetite (push or release >= 5/25) | Auto-apply scorer remediations incrementally (ADR-042 Rule 2). The agent reads suggestions and decides what to do. Re-score after each apply; drain when within appetite. **Never release above appetite** (ADR-042 Rule 1) — no AskUserQuestion shortcut. Halt the loop with `outcome: halted-above-appetite` if the loop exhausts without convergence (ADR-042 Rule 5). Verification Pending commits excluded from auto-revert (Rule 2b). Per ADR-042 (Step 6.5 Above-appetite branch). |
 | Origin diverged before start | Pull `--ff-only` if trivial; stop with report (`git log HEAD..origin/<base>` and reverse) if non-fast-forward — per ADR-019 (Step 0) |
+| Prior-session partial work detected at start (session-continuity dirty: untracked `docs/decisions/*.proposed.md` / `docs/problems/*.md`, `.afk-run-state/iter-*.json` with `is_error: true` or `api_error_status >= 400`, stale `.claude/worktrees/*`, uncommitted SKILL.md/source/ADR edits) | Halt the loop with a structured Prior-Session State report in the AFK summary. Do NOT attempt non-interactive resume. Interactive invocations prompt via `AskUserQuestion` with 4 options (resume / discard / leave-and-lower-priority / halt). Per P109 + ADR-013 Rule 6 (Step 0 session-continuity detection pass). |
 | Fix verification needed | Skip problem, add to "needs verification" list |
 | Stop-condition #2 with user-answerable skip-reasons | Emit Outstanding Design Questions table in summary (do NOT call AskUserQuestion). The persona is AFK by definition — per JTBD-006 and ADR-013 Rule 6 — so the table is the default. Interactive invocations may batch up to 4 questions through AskUserQuestion instead — per ADR-013 Rule 1 (Step 2.5). |
 | Unexpected dirty state between iterations | Halt the loop. Report the `git status --porcelain` output, the last iteration's reported outcome, and the divergence — per P036 (Step 6.75). Do NOT attempt non-interactive recovery. |
@@ -416,6 +440,7 @@ When every skipped ticket is in the `upstream-blocked` category (stop-condition
 - **P083** (`docs/problems/083-work-problems-iteration-worker-prompt-does-not-forbid-schedulewakeup.open.md`) — iteration prompt body forbids `ScheduleWakeup`. Applies equally to subprocess-dispatched iterations.
 - **P036** — inter-iteration verification (Step 6.75); remains in the orchestrator's main turn.
 - **P040** — origin-fetch preflight (Step 0); unchanged.
+- **P109** — session-continuity detection pass added to Step 0 after the fetch/divergence check. Enumerates five signals (untracked `docs/decisions/*.proposed.md`, untracked `docs/problems/*.md`, `.afk-run-state/iter-*.json` error markers, stale `.claude/worktrees/*` dirs, uncommitted SKILL.md/source/ADR edits). Routes interactive via `AskUserQuestion` with 4 options, AFK via halt-with-report per ADR-013 Rule 6.
 - **P041** — release-cadence drain (Step 6.5); remains in the orchestrator's main turn.
 - **P053** — Outstanding Design Questions surfacing at stop-condition #2 (Step 2.5); fed by the iteration subagent's `outstanding_questions` field.
 - **ADR-013** (`docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md`) — Rule 6 non-interactive fail-safe applies to every iteration-subagent decision surface.

package/skills/work-problems/test/work-problems-preflight-session-continuity.bats

@@ -0,0 +1,139 @@
+#!/usr/bin/env bats
+# Contract-assertion bats for work-problems Step 0 session-continuity
+# detection (the extension per P109).
+#
+# Per ADR-037 SKILL.md is a contract document; these assertions check the
+# contract strings the skill prose authoritatively pins for the Step 0
+# session-continuity detection pass. Follows the split pattern established
+# by work-problems-preflight.bats (fetch/divergence assertions) — this file
+# covers the second invariant family: prior-session partial-work signals +
+# interactive/AFK routing.
+#
+# Cross-reference:
+#   @problem P109 (work-problems preflight does not detect prior-session partial-work state)
+#   ADR-019 (AFK orchestrator preflight — extension scope)
+#   ADR-013 (structured user interaction — Rule 1 interactive, Rule 6 non-interactive fail-safe)
+#   ADR-032 (governance skill invocation patterns — .afk-run-state/iter-*.json contract)
+#   ADR-037 (skill testing strategy — contract-assertion framing)
+#   @jtbd JTBD-006 (Progress the Backlog While I'm Away — session-continuity detection belongs in Step 0)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "SKILL.md Step 0 cites P109 (session-continuity driver)" {
+  # Contract criterion: the extension is traceable to its driver ticket.
+  run grep -n "P109" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 names the session-continuity detection pass" {
+  # Contract criterion: the new detection pass is named as a discrete
+  # concept in the Step 0 prose (not buried under the divergence check).
+  run grep -niE "session.continuity" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates untracked docs/decisions/*.proposed.md signal" {
+  # Contract criterion: drafted-but-unlanded ADRs are one of the signals
+  # the session-continuity detection pass MUST enumerate.
+  run grep -nE "docs/decisions/\*\.proposed\.md|docs/decisions/.*\.proposed\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates untracked docs/problems/*.md signal" {
+  # Contract criterion: drafted-but-unlanded problem tickets are enumerated
+  # as one of the session-continuity signals. The preflight section already
+  # references docs/problems/ for the scan surface; the test checks that
+  # the Preflight section names untracked problem files as a detection
+  # signal (not merely the backlog-scan surface).
+  run grep -niE "untracked.*docs/problems|docs/problems/.*untracked" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates .afk-run-state/iter-*.json error signal" {
+  # Contract criterion: the .afk-run-state/iter-*.json subprocess artefacts
+  # (per ADR-032) with is_error: true or api_error_status >= 400 are named
+  # as a signal.
+  run grep -nE "\.afk-run-state/iter-\*\.json|\.afk-run-state/iter-.*\.json" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 names the is_error / api_error_status fields" {
+  # Contract criterion: the specific JSON fields the detection pass reads
+  # are named verbatim so the contract is unambiguous.
+  run grep -niE "is_error.*true|api_error_status" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates stale .claude/worktrees signal" {
+  # Contract criterion: stale subagent worktrees are a detection signal.
+  # Detection only (not cleanup/mutation — per P109 scope boundary).
+  run grep -nE "\.claude/worktrees" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates git worktree list signal for claude/* branches" {
+  # Contract criterion: git worktree list is the detection mechanism for
+  # claude/* branches adjacent to the .claude/worktrees/ dir check.
+  run grep -niE "git worktree list" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 enumerates uncommitted SKILL.md / source / ADR edits signal" {
+  # Contract criterion: mid-authoring source edits are a detection signal.
+  run grep -niE "uncommitted.*(SKILL\.md|source|ADR)|(SKILL\.md|source|ADR).*uncommitted" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 routes interactive via AskUserQuestion" {
+  # Contract criterion per ADR-013 Rule 1: the interactive branch uses
+  # AskUserQuestion.
+  run grep -nE "AskUserQuestion" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 interactive branch names the 4 option categories" {
+  # Contract criterion: the AskUserQuestion 4-option shape is pinned so
+  # adopters know the branch set. Resume / discard / leave-and-lower-priority / halt.
+  run grep -niE "resume" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "discard" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "leave.*lower.priority|leave.and.lower.priority" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 routes AFK via halt-with-report per ADR-013 Rule 6" {
+  # Contract criterion per ADR-013 Rule 6: the non-interactive / AFK branch
+  # halts with a report rather than silently choosing.
+  run grep -niE "halt.with.report|halt with report|Rule 6 fail.safe" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 cites ADR-013 Rule 6 for AFK fail-safe" {
+  # Contract criterion: ADR-013 Rule 6 is named as the authority for the
+  # non-interactive halt branch.
+  run grep -nE "ADR-013.*Rule 6|Rule 6.*ADR-013" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 0 emits a structured Prior-Session State report" {
+  # Contract criterion: the AFK halt branch surfaces a structured report,
+  # not a free-text prose blurb — so the user can act on it on return.
+  run grep -niE "Prior.Session State" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Non-Interactive Decision Making table covers session-continuity" {
+  # Contract criterion: the decision-matrix section surfaces the new branch
+  # so adopters of the skill can find the AFK default without reading
+  # Step 0 prose in full.
+  run grep -niE "Prior.session partial.work|session.continuity.*dirty|Prior-Session State.*AFK" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/test/work-problems-step-5-delegation.bats

@@ -213,3 +213,35 @@ setup() {
   run grep -nE "ADR-014" "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
+
+# @problem P083
+# @jtbd JTBD-006
+# @jtbd JTBD-001
+# @jtbd JTBD-101
+# @jtbd JTBD-201
+#
+# STRUCTURAL: tests the SKILL.md content contract per ADR-037's Permitted
+# Exception (doc-lint contract assertion against the contract document itself)
+# — same rationale already covered by the file-header block above. Behavioural
+# alternative would require simulating a `claude -p` iteration subprocess with
+# a large task and observing tool-call traces for absence of ScheduleWakeup;
+# that harness is not yet available at the skill layer (see P081 retrofit path).
+@test "SKILL.md Step 5 iteration prompt forbids ScheduleWakeup (P083 — synchronous-handoff contract)" {
+  # P083 (2026-04-21): AFK iter 5 observed an iteration worker call ScheduleWakeup
+  # mid-task, abandoning the synchronous-handoff contract (no ITERATION_SUMMARY
+  # returned; uncommitted work left in tree; Step 6.75 halted the loop on
+  # dirty-for-unknown-reason). The Step 5 iteration prompt body MUST explicitly
+  # forbid ScheduleWakeup so LLM-driven workers do not reach for time-deferring
+  # primitives — iteration workers are synchronous by contract (ADR-032 AFK
+  # iteration-isolation wrapper). Regression guard for the 260768f clause.
+  run grep -niE "Do NOT use .?ScheduleWakeup|ScheduleWakeup.{0,80}(must not|not.{0,10}self-reschedule)|not.{0,10}self-reschedule" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 ScheduleWakeup forbidding clause cites P083" {
+  # The forbidding clause must cite P083 inline so the contract document is
+  # self-documenting — a future contributor removing the clause reads the
+  # P083 reference and understands why it exists before deleting it.
+  run grep -nE "ScheduleWakeup.{0,120}P083|P083.{0,120}ScheduleWakeup" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}