@windyroad/itil 0.35.7 → 0.35.8-preview.393

package/.claude-plugin/plugin.json

@@ -484,5 +484,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.35.7"
+  "version": "0.35.8"
 }

package/README.md

@@ -56,7 +56,7 @@ Supports creating new problems, updating root cause analysis, transitioning stat
 
 Supports declaring new incidents, recording evidence-first observations and hypotheses, logging mitigation attempts, transitioning lifecycle (Investigating → Mitigating → Restored → Closed), and automatically handing off to `manage-problem` when service is restored.
 
-See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for the incident-vs-problem split and [JTBD-201](../../docs/jtbd/tech-lead/JTBD-201-restore-service-fast.proposed.md) for the job this serves.
+See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for the incident-vs-problem split.
 
 ## How It Works
 
@@ -86,7 +86,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:review-problems` | Re-rate every open and known-error ticket and refresh the WSJF ranking | Experimental |
 | `/wr-itil:reconcile-readme` | Detect and correct drift between `docs/problems/README.md` and on-disk ticket inventory | Experimental |
 | `/wr-itil:report-upstream` | Report a local problem as a structured issue against an upstream repository (ADR-024) | Experimental |
-| `/wr-itil:check-upstream-responses` | Poll upstream issues we filed via `/wr-itil:report-upstream` and surface new comments / state changes / label changes since last check (P249 Phase 1; outbound symmetric counterpart to ADR-062 inbound discovery; serves [JTBD-004](../../docs/jtbd/solo-developer/JTBD-004-connect-agents.proposed.md)) | Experimental |
+| `/wr-itil:check-upstream-responses` | Poll upstream issues we filed via `/wr-itil:report-upstream` and surface new comments / state changes / label changes since last check (P249 Phase 1; outbound symmetric counterpart to ADR-062 inbound discovery) | Experimental |
 | `/wr-itil:capture-rfc` | Lightweight RFC-capture skill — mandatory problem-trace per ADR-060 I1 invariant; opens a coordinated multi-commit change traceable to ≥ 1 driving problem (Phase 1 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |
 | `/wr-itil:manage-rfc` | Heavyweight RFC intake + lifecycle management — proposed → accepted → in-progress → verifying → closed; sibling to `manage-problem` at the RFC tier (ADR-060) | Experimental |
 | `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |
@@ -102,27 +102,6 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:mitigate-incident` / `/wr-itil:restore-incident` / `/wr-itil:close-incident` / `/wr-itil:link-incident` | Incident lifecycle transitions (ADR-011) | Experimental |
 | `/wr-itil:scaffold-intake` | Scaffold OSS intake surfaces (`.github/ISSUE_TEMPLATE/`, `SECURITY.md`, `SUPPORT.md`, `CONTRIBUTING.md`) for downstream adopters (ADR-036) | Experimental |
 
-## Jobs to be Done
-
-This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
-
-### Plugin user
-
-- **[JTBD-301 Report a Problem Without Pre-Classifying It](../../docs/jtbd/plugin-user/JTBD-301-report-problem-without-pre-classifying.proposed.md)** — adopters who hit a problem with an installed `@windyroad/*` plugin describe what they observed; `/wr-itil:scaffold-intake` provisions the intake template downstream so triage decides the category, not the reporter.
-
-### Tech lead / consultant
-
-- **[JTBD-201 Restore Service Fast with an Audit Trail](../../docs/jtbd/tech-lead/JTBD-201-restore-service-fast.proposed.md)** — the manage-incident skill carries an evidence-first lifecycle (investigating → mitigating → restored → closed), with handoff to manage-problem for the root-cause work.
-
-### Solo developer
-
-- **[JTBD-006 Progress the Backlog While I'm Away](../../docs/jtbd/solo-developer/JTBD-006-work-backlog-afk.proposed.md)** — `/wr-itil:work-problems` is the AFK orchestrator that loops through the WSJF-ranked backlog, working tickets without interactive input until quota or a stop condition fires.
-- **[JTBD-008 Decompose a Fix Into Coordinated Changes](../../docs/jtbd/solo-developer/JTBD-008-decompose-fix-into-coordinated-changes.proposed.md)** — `/wr-itil:capture-rfc` + `/wr-itil:manage-rfc` are the capture-time decomposition surface for multi-commit coordinated changes traced to a driving problem (Phase 1); `/wr-itil:capture-story` is the INVEST-shaped sub-workstream surface for individual slices under those coordinated changes (Phase 2 — story tier). The I1 trace-to-problem invariant is gate-enforced at capture-rfc time; I6 + I9 problem-and-JTBD-trace invariants are gate-enforced at capture-story time (P170 / ADR-060).
-
-### Plugin user (currency anchor)
-
-- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
-
 ## Updating and Uninstalling
 
 ```bash

package/bin/wr-itil-effort-tally

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical effort-tally script.
+exec "$(dirname "$0")/../scripts/effort-tally.sh" "$@"

package/hooks/itil-readme-refresh-discipline.sh

@@ -92,8 +92,10 @@ command_invokes_git_commit "$COMMAND" || exit 0
 
 # Run detection. Helper echoes offending ticket path on stdout when
 # detected; returns 1 in that case. Returns 0 (allow) on no-trap,
-# bypass env, or fail-open (non-git tree, parse error).
-TRAPPED_TICKET=$(detect_readme_refresh_required 2>/dev/null) && exit 0
+# bypass env, a registered RISK_BYPASS commit-message trailer (P265 —
+# `$COMMAND` is threaded in so the helper can inspect the trailer), or
+# fail-open (non-git tree, parse error).
+TRAPPED_TICKET=$(detect_readme_refresh_required "$COMMAND" 2>/dev/null) && exit 0
 
 # Extract the leading ticket-ID digits from the basename so the deny
 # names the ticket as `P<NNN>` rather than the full descriptive path

package/hooks/lib/readme-refresh-detect.sh

@@ -42,6 +42,16 @@
 #     `.claude/settings.json` env field or shell `export` before
 #     launching `claude` — inline-prefix syntax (`VAR=1 git commit ...`)
 #     does NOT propagate from a Bash subshell to PreToolUse hooks (P173).
+#   - Registered `RISK_BYPASS: <token>` commit-message trailer (P265) →
+#     return 0 (allow). Narrow allow-list (currently only
+#     `adr-031-migration`, the standalone ADR-031 layout-migration
+#     commit, which is a rename-only change that legitimately stages no
+#     README refresh). The trailer is read from the live `git commit`
+#     command string at PreToolUse time (the commit message is not yet
+#     written), matching the sibling `risk-score-commit-gate.sh`
+#     recognition (P170 T11) so one logical migration commit clears both
+#     gates. Registry of record: ADR-014 commit-message bypass-token
+#     table.
 #
 # Narrative-only short-circuit (P230):
 #   - When all staged ticket edits are purely narrative — no
@@ -101,21 +111,74 @@
 #              shape — per-invocation deterministic, no markers).
 #   P141     — sibling changeset-discipline helper (same shape).
 #   P165     — this helper.
+#   P265     — RISK_BYPASS trailer allow-list bypass (this addition).
+
+# Allow-list of registered RISK_BYPASS commit-message trailer tokens
+# (P265). A policy-authorised commit may carry `RISK_BYPASS: <token>` in
+# its message body; when <token> is registered here, the README-refresh
+# gate allows the commit even though no README refresh is staged. The
+# allow-list keeps the bypass narrow and auditable — a generic
+# `RISK_BYPASS:` match would let any commit self-exempt.
+#
+# Registered tokens:
+#   adr-031-migration — the standalone per-state-subdir layout-migration
+#     commit written by lib/migrate-problems-layout.sh. It is a pure
+#     rename (no README content change — the table references tickets by
+#     ID, not path), so requiring a README refresh would deadlock the
+#     migration (P265). The same token clears the sibling
+#     risk-score-commit-gate.sh (P170 T11); both gates recognise it via
+#     the identical grep below so one logical migration commit clears
+#     both. Registry of record: ADR-014 commit-message bypass-token table.
+_README_REFRESH_BYPASS_TRAILERS=("adr-031-migration")
+
+# Returns 0 if the given `git commit` command string carries a
+# registered RISK_BYPASS trailer from the allow-list above. The grep
+# pattern is kept byte-identical to risk-score-commit-gate.sh so both
+# commit gates recognise the token the same way (P265 architect verdict).
+_readme_refresh_command_has_bypass_trailer() {
+  local command="${1:-}"
+  [ -n "$command" ] || return 1
+  local token
+  for token in "${_README_REFRESH_BYPASS_TRAILERS[@]}"; do
+    if printf '%s' "$command" \
+        | grep -qE "RISK_BYPASS:[[:space:]]*${token}([^A-Za-z0-9_-]|\$)"; then
+      return 0
+    fi
+  done
+  return 1
+}
 
 # Detect whether the current staged set requires a README refresh that
 # is not staged.
 #
+# $1 (optional) — the `git commit` command string. Inspected for a
+#   registered RISK_BYPASS trailer (P265). Empty/absent → no trailer
+#   bypass (fail-safe; preserves pre-P265 behaviour for any caller that
+#   does not thread the command through).
+#
 # Echoes the offending ticket path on stdout when detected.
 #
 # Returns:
-#   0 — no change required, or BYPASS env set, or fail-open (allow)
+#   0 — no change required, BYPASS env set, a registered RISK_BYPASS
+#       trailer is present, or fail-open (allow)
 #   1 — ticket change staged + README not staged (caller should deny)
 detect_readme_refresh_required() {
+  local command="${1:-}"
+
   # Bypass via env var — single most-common legitimate escape.
   if [ "${BYPASS_README_REFRESH_GATE:-}" = "1" ]; then
     return 0
   fi
 
+  # Bypass via registered RISK_BYPASS commit-message trailer (P265).
+  # The ADR-031 layout-migration commit is a rename-only change that
+  # legitimately stages no README refresh; its `RISK_BYPASS:
+  # adr-031-migration` trailer carries the policy authorisation
+  # (ADR-031 § Backward Compatibility + ADR-013 Rule 6).
+  if _readme_refresh_command_has_bypass_trailer "$command"; then
+    return 0
+  fi
+
   # Fail-open if not inside a git working tree.
   git rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
 

package/hooks/test/itil-readme-refresh-discipline.bats

@@ -526,3 +526,58 @@ EOF
   [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
   [ "${#output}" -eq 0 ]
 }
+
+# --- P265: RISK_BYPASS commit-message trailer allow-list bypass ---
+#
+# The ADR-031 layout-migration commit (lib/migrate-problems-layout.sh)
+# is a pure rename (flat docs/problems/NNN-*.<state>.md → per-state
+# subdir docs/problems/<state>/NNN-*.md) that legitimately stages NO
+# README refresh — the rename does not change README content (the table
+# references tickets by ID, not path). Its `RISK_BYPASS: adr-031-migration`
+# trailer (written via sequential `-m` paragraphs, so the literal token
+# appears in the `git commit` command argv) carries the policy
+# authorisation (ADR-031 § Backward Compatibility + ADR-013 Rule 6).
+# The hook must allow such commits silently. The bypass is an allow-list:
+# only the registered token bypasses; an unregistered RISK_BYPASS token
+# still denies. The recognition grep is kept identical to the sibling
+# risk-score-commit-gate.sh (P170 T11 precedent) so both commit gates
+# recognise the token the same way.
+
+@test "P265 allow: migration rename + RISK_BYPASS: adr-031-migration trailer → allow silently" {
+  echo "# Problem 999 flat" > docs/problems/999-mig.open.md
+  git add docs/problems/999-mig.open.md
+  git -c commit.gpgsign=false commit --quiet -m "seed flat ticket"
+  git mv docs/problems/999-mig.open.md docs/problems/open/999-mig.md
+  run run_bash_hook "git commit -m 'docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)' -m 'RISK_BYPASS: adr-031-migration'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  # Bypass is an allow path — silent per ADR-045 Pattern 1.
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P265 deny: same migration rename WITHOUT the trailer still denies (negative control)" {
+  echo "# Problem 999 flat" > docs/problems/999-mig.open.md
+  git add docs/problems/999-mig.open.md
+  git -c commit.gpgsign=false commit --quiet -m "seed flat ticket"
+  git mv docs/problems/999-mig.open.md docs/problems/open/999-mig.md
+  run run_bash_hook "git commit -m 'docs(problems): auto-migrate'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P265 deny: unregistered RISK_BYPASS token does NOT bypass (allow-list scope)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'feat' -m 'RISK_BYPASS: some-other-thing'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P265 allow: registered trailer bypasses a newly-staged ticket too (bypass is staged-shape-agnostic)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'docs(problems): auto-migrate' -m 'RISK_BYPASS: adr-031-migration'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}

package/package.json

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

package/scripts/effort-tally.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# wr-itil — per-ticket effort tally from AFK iteration cost metadata (ADR-067, P248)
+#
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — AFK actuals feed WSJF calibration)
+# @jtbd JTBD-202 (Run Pre-Flight Governance Checks — structured, auditable effort tally)
+#
+# Attributes `.afk-run-state/iter*.json` actuals back to their source ticket
+# (the `pNNN` token in the filename) and emits one tally line per ticket in the
+# `## Effort Tally` schema. The reusable core shared by:
+#   - the backfill (seed historical tickets — ADR-067 Decision Outcome item 4)
+#   - go-forward per-iter append (work-problems — ADR-067 item 2)
+#
+# Authority hierarchy (P089 Gap 2 — load-bearing): `total_cost_usd` is the
+# AUTHORITATIVE actual (session-cumulative by CLI contract; reliable token-spend
+# proxy). `duration_ms` is reliable wall-clock. Raw `usage.*` token counts are
+# BEST-EFFORT (undercount when a subprocess exits on a background-ack turn) and
+# are emitted with a `~` best-effort marker.
+#
+# Usage:
+#   effort-tally.sh [AFK_DIR]
+#     AFK_DIR defaults to .afk-run-state
+#
+# Output (stdout): one line per ticket, sorted by descending cost:
+#   P<NNN> | iters=<N> | cost_usd=<authoritative> | minutes=<reliable> | tokens=~<best-effort>M
+# Always exits 0.
+
+set -euo pipefail
+
+AFK_DIR="${1:-.afk-run-state}"
+[ -d "$AFK_DIR" ] || exit 0
+
+python3 - "$AFK_DIR" <<'PY'
+import json, glob, os, re, sys
+from collections import defaultdict
+
+afk_dir = sys.argv[1]
+
+def cost_obj(d):
+    """Return the dict carrying total_cost_usd, whether d is a dict or an event list."""
+    if isinstance(d, dict):
+        return d if d.get("total_cost_usd") is not None else None
+    if isinstance(d, list):
+        for item in reversed(d):
+            if isinstance(item, dict) and item.get("total_cost_usd") is not None:
+                return item
+    return None
+
+agg = defaultdict(lambda: {"cost": 0.0, "dur_ms": 0, "tokens": 0, "iters": 0})
+for path in glob.glob(os.path.join(afk_dir, "*.json")):
+    m = re.search(r'p(\d{3})', os.path.basename(path))
+    if not m:
+        continue
+    tid = "P" + m.group(1)
+    try:
+        with open(path) as fh:
+            d = json.load(fh)
+    except Exception:
+        continue
+    o = cost_obj(d)
+    if not o:
+        continue
+    a = agg[tid]
+    a["cost"] += float(o.get("total_cost_usd") or 0)
+    a["dur_ms"] += int(o.get("duration_ms") or 0)
+    u = o.get("usage") or {}
+    a["tokens"] += sum(int(u.get(k) or 0) for k in
+                       ("input_tokens", "output_tokens",
+                        "cache_creation_input_tokens", "cache_read_input_tokens"))
+    a["iters"] += 1
+
+for tid, a in sorted(agg.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+    print(f"{tid} | iters={a['iters']} | cost_usd={a['cost']:.2f} | "
+          f"minutes={a['dur_ms']/60000:.1f} | tokens=~{a['tokens']/1e6:.1f}M")
+PY

package/scripts/test/effort-tally.bats

@@ -0,0 +1,79 @@
+#!/usr/bin/env bats
+
+# ADR-067 / P248: effort-tally.sh attributes .afk-run-state/iter*.json actuals
+# back to their source ticket (pNNN filename token) and emits the per-ticket
+# tally. Behavioural — exercises the script against fixture iter-JSON trees.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/itil/scripts/effort-tally.sh"
+  DIR="$(mktemp -d)"
+  mkdir -p "$DIR/.afk-run-state"
+}
+
+teardown() { rm -rf "$DIR"; }
+
+mk_iter() { # mk_iter <filename> <cost> <duration_ms> <input_tokens>
+  cat > "$DIR/.afk-run-state/$1" <<EOF
+{"total_cost_usd": $2, "duration_ms": $3, "usage": {"input_tokens": $4, "output_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}}
+EOF
+}
+
+@test "attributes a single iter to its ticket via the pNNN filename token" {
+  mk_iter "iter1-p087.json" 12.50 600000 1000000
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"P087"* ]]
+  [[ "$output" == *"cost_usd=12.50"* ]]
+  [[ "$output" == *"minutes=10.0"* ]]
+}
+
+@test "sums multiple iters for the same ticket" {
+  mk_iter "iter1-p087.json" 10.00 300000 500000
+  mk_iter "iter2-p087.json" 5.00 300000 500000
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [[ "$output" == *"P087 | iters=2 | cost_usd=15.00"* ]]
+}
+
+@test "authoritative cost comes from total_cost_usd; tokens flagged best-effort with ~" {
+  mk_iter "iter1-p100.json" 7.00 60000 2000000
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [[ "$output" == *"cost_usd=7.00"* ]]
+  [[ "$output" == *"tokens=~2.0M"* ]]
+}
+
+@test "tickets are sorted by descending cost" {
+  mk_iter "iter1-p010.json" 3.00 60000 100000
+  mk_iter "iter1-p020.json" 30.00 60000 100000
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  # P020 (30.00) must appear before P010 (3.00)
+  [[ "$(echo "$output" | grep -n P020 | cut -d: -f1)" -lt "$(echo "$output" | grep -n P010 | cut -d: -f1)" ]]
+}
+
+@test "handles JSON-array (event-stream) shape, not just a single object" {
+  cat > "$DIR/.afk-run-state/iter1-p050.json" <<'EOF'
+[{"type":"system"},{"type":"result","total_cost_usd":9.00,"duration_ms":120000,"usage":{"input_tokens":3000000,"output_tokens":0,"cache_creation_input_tokens":0,"cache_read_input_tokens":0}}]
+EOF
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [[ "$output" == *"P050"* ]]
+  [[ "$output" == *"cost_usd=9.00"* ]]
+}
+
+@test "files without a pNNN token are ignored" {
+  mk_iter "drain-push.json" 99.00 60000 100000
+  cp "$DIR/.afk-run-state/drain-push.json" "$DIR/.afk-run-state/work-problems-session-totals.json"
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [ -z "$output" ]
+}
+
+@test "files without total_cost_usd are skipped" {
+  echo '{"pid": 1234, "start": 999}' > "$DIR/.afk-run-state/iter1-p077.json"
+  run bash "$SCRIPT" "$DIR/.afk-run-state"
+  [ -z "$output" ]
+}
+
+@test "missing afk dir exits 0 with no output" {
+  run bash "$SCRIPT" "$DIR/nonexistent"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/skills/work-problems/SKILL.md

@@ -317,6 +317,14 @@ IDLE_TIMEOUT_S="${WORK_PROBLEMS_IDLE_TIMEOUT_S:-3600}"
 # into iter subprocesses' first turn.
 export WR_SUPPRESS_PENDING_QUESTIONS=1
 
+# AFK-iter oversight-nudge suppression (ADR-066): the architect plugin's
+# SessionStart oversight nudge ("N decisions lack human oversight — run
+# /wr-architect:review-decisions") is an interactive batch-confirm prompt. It
+# must NOT fire into an absent-user iter subprocess. architect-oversight-nudge.sh
+# self-suppresses when this env var is set — same discipline as the
+# pending-questions guard above (JTBD-006 friction guard).
+export WR_SUPPRESS_OVERSIGHT_NUDGE=1
+
 claude -p \
   --permission-mode bypassPermissions \
   --output-format json \