@windyroad/itil 0.30.2-preview.317 → 0.30.3-preview.319

package/.claude-plugin/plugin.json

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

package/bin/wr-itil-plugin-exercise-index

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/plugin-exercise-index.sh" "$@"

package/bin/wr-itil-skill-invocations

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/skill-invocations.sh" "$@"

package/hooks/hooks.json

@@ -52,7 +52,8 @@
       }
     ],
     "Stop": [
-      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-review.sh" }] }
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-assistant-output-review.sh" }] },
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-mid-loop-ask-detect.sh" }] }
     ]
   }
 }

package/hooks/itil-mid-loop-ask-detect.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# P132 Phase 2b — wr-itil Stop hook.
+#
+# Detects orchestrator main-turn `AskUserQuestion` calls fired mid-loop
+# inside `/wr-itil:work-problems` — the regression class P132 captures
+# (2026-05-17 reopen evidence: orchestrator asked iter-target selection
+# between iters 3 and 4; halted the AFK loop for hours of user time).
+#
+# Detection signal (all three must hold):
+#   1. Last assistant turn in the transcript contains an
+#      AskUserQuestion tool_use.
+#   2. Earlier in the transcript an assistant message issued a `Skill`
+#      tool_use to `wr-itil:work-problems` (orchestrator activation).
+#   3. No `ALL_DONE` or `## Work Problems Summary` terminal marker has
+#      been emitted since the orchestrator activated (the orchestrator
+#      is still mid-loop, not in its post-loop wrap-up).
+#
+# When all three match the hook emits a structured `stopReason`
+# advisory citing P130 + the Mid-loop ask discipline subsection of
+# `packages/itil/skills/work-problems/SKILL.md`. Advisory ONLY — the
+# hook NEVER blocks. The next assistant turn reads the stopReason in
+# its context and self-corrects (queue the question to
+# outstanding_questions and continue iterating).
+#
+# Mirrors the sibling `itil-assistant-output-review.sh` Stop hook
+# precedent (P085 prose-ask detection) on transcript-extraction shape
+# and stopReason emit format.
+#
+# References:
+#   P132     — this hook (Phase 2b structural enforcement).
+#   P130     — orchestrator presence-aware dispatch; named in advisory.
+#   ADR-013  — Rule 1 (interactive default) + Rule 6 (AFK fail-safe).
+#   ADR-044  — framework-resolution boundary; named in advisory.
+#   ADR-045  — hook injection budget; advisory honour-system band.
+#   ADR-052  — behavioural tests default.
+#   ADR-005  — plugin testing strategy.
+
+# Per-surface configuration. Extending coverage to other orchestrators
+# (run-retro Step 4b Stage 1, /install-updates Step 6a) is a future
+# Phase 2c/2d variant — copy this hook + retarget these two vars.
+ORCHESTRATOR_SKILL="wr-itil:work-problems"
+TERMINAL_MARKER_RE='ALL_DONE|## Work Problems Summary'
+
+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 inspect. Exit clean — hook is advisory, never blocking.
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Empty transcript → silent exit.
+[ -s "$TRANSCRIPT_PATH" ] || exit 0
+
+# Identify the LAST assistant turn. Each transcript line is a JSON
+# object {type, message, ...}; assistant turns have type=="assistant".
+# Malformed lines are silently tolerated by jq's `-c` + `2>/dev/null`.
+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
+
+# Signal 1: last assistant turn contains AskUserQuestion tool_use.
+if ! echo "$LAST_ASSISTANT" | jq -e '
+  .message.content
+  | if type == "array" then
+      map(select(.type == "tool_use" and .name == "AskUserQuestion")) | length > 0
+    else false end
+' >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Signal 2: any earlier assistant message contains a Skill tool_use to
+# the configured orchestrator skill. Iterate every assistant line; on
+# the first match set ORCH_LINE_NUM to its 1-based line index.
+ORCH_LINE_NUM=0
+LINE_NUM=0
+while IFS= read -r line || [ -n "$line" ]; do
+  LINE_NUM=$((LINE_NUM + 1))
+  # Skip non-assistant + malformed lines.
+  echo "$line" | grep -qE '"type"[[:space:]]*:[[:space:]]*"assistant"' || continue
+  echo "$line" | jq -e . >/dev/null 2>&1 || continue
+  if echo "$line" | jq -e --arg s "$ORCHESTRATOR_SKILL" '
+    .message.content
+    | if type == "array" then
+        map(select(.type == "tool_use" and .name == "Skill" and (.input.skill // .input.skillName // "") == $s)) | length > 0
+      else false end
+  ' >/dev/null 2>&1; then
+    ORCH_LINE_NUM=$LINE_NUM
+    break
+  fi
+done < "$TRANSCRIPT_PATH"
+
+if [ "$ORCH_LINE_NUM" -eq 0 ]; then
+  exit 0
+fi
+
+# Signal 3: no terminal marker emitted AFTER orchestrator activation.
+# Scan lines strictly after ORCH_LINE_NUM up to the line BEFORE the
+# last assistant turn (the AskUserQuestion turn itself shouldn't be
+# considered a terminal-marker source — its content is a tool_use, not
+# the orchestrator's final summary). If the AskUserQuestion turn IS
+# the same turn that emits ALL_DONE, that's structurally implausible
+# (you don't ask while wrapping up) — the conservative read is to
+# scan up to and including all prior turns.
+TOTAL_LINES=$(wc -l < "$TRANSCRIPT_PATH" | tr -d ' ')
+# Slice: from ORCH_LINE_NUM+1 to TOTAL_LINES-1 (exclude the final
+# assistant turn carrying the AskUserQuestion). Edge case: if the
+# orchestrator-activation line IS the last-assistant line, the
+# AskUserQuestion would be in the same turn as the Skill call —
+# impossible in practice. In that degenerate case the slice is empty
+# and no terminal marker is seen → advise.
+SLICE_END=$((TOTAL_LINES - 1))
+TERMINAL_SEEN="no"
+if [ "$SLICE_END" -ge "$ORCH_LINE_NUM" ]; then
+  if sed -n "$((ORCH_LINE_NUM + 1)),${SLICE_END}p" "$TRANSCRIPT_PATH" \
+       | grep -qE "$TERMINAL_MARKER_RE" 2>/dev/null; then
+    TERMINAL_SEEN="yes"
+  fi
+fi
+
+if [ "$TERMINAL_SEEN" = "yes" ]; then
+  exit 0
+fi
+
+# All three signals present → emit advisory stopReason. The next
+# assistant turn reads this in its context and self-corrects.
+# Voice-tone target ~600 bytes; ADR-045 honour-system slack < 1000.
+jq -n '{
+  stopReason: (
+    "MID-LOOP ASK DETECTED: AskUserQuestion fired inside /wr-itil:work-problems orchestrator main turn. " +
+    "Per P130 + Mid-loop ask discipline subsection of work-problems SKILL.md, mid-loop AskUserQuestion is " +
+    "forbidden except at framework-prescribed halt points (Step 0 session-continuity, Step 2.5/2.5b loop-end emit, " +
+    "Step 6.5 above-appetite Rule 5 / CI failure, Step 6.75 dirty halt). " +
+    "If at a halt point, this advisory is inapplicable. " +
+    "If mid-loop, queue the question to outstanding_questions and continue iterating. " +
+    "See ADR-044 framework-resolution boundary."
+  )
+}'
+
+exit 0

package/hooks/test/itil-mid-loop-ask-detect.bats

@@ -0,0 +1,220 @@
+#!/usr/bin/env bats
+
+# P132 Phase 2b: itil-mid-loop-ask-detect.sh Stop hook detects
+# orchestrator main-turn AskUserQuestion calls fired mid-loop inside
+# /wr-itil:work-problems — the regression class P132 captures
+# (2026-05-17 reopen: orchestrator asked iter-target selection between
+# iters 3 and 4; halted the loop for hours of AFK time).
+#
+# Detection signal:
+#   1. Last assistant turn contains an AskUserQuestion tool_use
+#   2. Earlier transcript contains a Skill tool_use to wr-itil:work-problems
+#   3. No `ALL_DONE` / `## Work Problems Summary` marker has been emitted
+#      since the skill activation (mid-loop, not post-loop wrap)
+#
+# When all three match the hook emits a structured `stopReason`
+# advisory citing P130 + the Mid-loop ask discipline subsection of
+# work-problems SKILL.md. Advisory only — never blocks. Mirrors the
+# itil-assistant-output-review.sh Stop hook precedent (P085 prose-ask
+# detection) but on a different signal class.
+#
+# Per ADR-005 / ADR-052 — bats live under packages/<plugin>/hooks/test/
+# and assert behaviour on emitted JSON, not source-content. Per
+# feedback_behavioural_tests.md (P081) — no source-grep on hook text.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/itil/hooks/itil-mid-loop-ask-detect.sh"
+  TMPDIR_="$(mktemp -d)"
+  TRANSCRIPT="$TMPDIR_/transcript.jsonl"
+}
+
+teardown() {
+  rm -rf "$TMPDIR_"
+}
+
+# Helper: emit the JSONL transcript line for an assistant turn
+# containing a Skill tool_use to wr-itil:work-problems.
+emit_orchestrator_activation() {
+  cat <<'JSON'
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Skill","input":{"skill":"wr-itil:work-problems"}}]}}
+JSON
+}
+
+# Helper: emit a benign assistant text turn (no tool_use).
+emit_text_turn() {
+  local text="$1"
+  printf '{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":%s}]}}\n' \
+    "$(printf '%s' "$text" | jq -Rs .)"
+}
+
+# Helper: emit an assistant turn containing an AskUserQuestion tool_use.
+emit_ask_turn() {
+  local header="${1:-Next problem}"
+  cat <<JSON
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"AskUserQuestion","input":{"questions":[{"question":"Pick next iter","header":"${header}","options":[{"label":"A","description":"x"},{"label":"B","description":"y"}]}]}}]}}
+JSON
+}
+
+run_hook() {
+  echo "{\"session_id\":\"mid-loop-test\",\"transcript_path\":$(printf '%s' "$TRANSCRIPT" | jq -Rs .)}" | bash "$HOOK"
+}
+
+# --- Positive detection ---
+
+@test "detect: orchestrator activation + final AskUserQuestion + no terminal marker emits stopReason" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 1 complete. Dispatching iter 2."
+    emit_text_turn "Iter 2 complete. Dispatching iter 3."
+    emit_ask_turn "Pick next iter"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}
+
+@test "detect: stopReason cites P130 + framework-prescribed halt points" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 1 done."
+    emit_ask_turn "Next problem"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"P130"* ]]
+  [[ "$output" == *"halt point"* ]]
+  [[ "$output" == *"outstanding_questions"* ]]
+}
+
+@test "detect: stopReason cites ADR-044 framework-resolution boundary" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 1 done."
+    emit_ask_turn "Pick"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"ADR-044"* ]]
+}
+
+# --- Negative paths: silent exit ---
+
+@test "allow: transcript with no orchestrator activation exits silently" {
+  # User asked a question outside /wr-itil:work-problems context;
+  # AskUserQuestion in this case is unrelated to mid-loop discipline.
+  {
+    printf '{"type":"user","message":{"role":"user","content":"help me design a feature"}}\n'
+    emit_text_turn "Two paths come to mind."
+    emit_ask_turn "Design choice"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: orchestrator activated then ALL_DONE emitted (post-loop wrap)" {
+  # The orchestrator has emitted its terminal summary; subsequent
+  # AskUserQuestion is post-loop interactive follow-up, not mid-loop.
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 1 complete."
+    emit_text_turn "## Work Problems Summary
+All iters complete.
+ALL_DONE"
+    emit_ask_turn "Follow-up question"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: orchestrator activated then Work Problems Summary header emitted (post-loop)" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "## Work Problems Summary
+
+Completed: 3 iters."
+    emit_ask_turn "Next steps?"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: last assistant turn does not contain AskUserQuestion" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 2 dispatched."
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: missing transcript_path exits silently" {
+  run bash -c 'echo "{\"session_id\":\"sid\"}" | bash "$1"' -- "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: non-existent transcript file exits silently" {
+  run bash -c "echo '{\"session_id\":\"sid\",\"transcript_path\":\"/tmp/does-not-exist-$RANDOM\"}' | bash '$HOOK'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: empty transcript exits silently" {
+  : > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"stopReason"* ]]
+}
+
+@test "allow: malformed JSONL lines do not crash the hook" {
+  {
+    echo "not-json"
+    emit_orchestrator_activation
+    emit_text_turn "Iter 2"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  # Either silent OR stopReason — but never a crash. We assert no
+  # non-zero exit; the silent-vs-stopReason split is incidental here.
+}
+
+# --- Advisory budget per ADR-045 ---
+
+@test "advisory output stays under ADR-045 800-byte honour-system band" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    emit_text_turn "Iter 1 done."
+    emit_ask_turn "Pick"
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+  [ "${#output}" -lt 1000 ]
+}
+
+# --- Distinguishing-marker: tool_name for AskUserQuestion --
+
+@test "detect: matches even when AskUserQuestion is intermixed with text blocks" {
+  {
+    printf '{"type":"user","message":{"role":"user","content":"/wr-itil:work-problems"}}\n'
+    emit_orchestrator_activation
+    cat <<'JSON'
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Two iter targets are tied on WSJF:"},{"type":"tool_use","name":"AskUserQuestion","input":{"questions":[{"question":"Pick next iter","header":"Next iter","options":[{"label":"P132","description":"x"},{"label":"P130","description":"y"}]}]}}]}}
+JSON
+  } > "$TRANSCRIPT"
+  run run_hook
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stopReason"* ]]
+}

package/package.json

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