@windyroad/itil 0.35.7-preview.365 → 0.35.7-preview.387

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.35.7-preview.365",
+  "version": "0.35.7-preview.387",
   "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 \