@windyroad/itil 0.19.0-preview.192 → 0.19.1-preview.194

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.19.0-preview.192",
+  "version": "0.19.1-preview.194",
   "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

@@ -158,13 +158,15 @@ PROMPT_EOF
 claude -p \
   --permission-mode bypassPermissions \
   --output-format json \
-  "$ITERATION_PROMPT"
+  "$ITERATION_PROMPT" \
+  < /dev/null
 ```
 
 **Flag rationale:**
 
 - `--permission-mode bypassPermissions` — handles non-interactive permission prompts. Without this, Bash/Edit/Write calls inside the subprocess halt on approval prompts (no TTY). Alternative modes (`acceptEdits`, `auto`, `dontAsk`) are acceptable if adopters need narrower permission scopes; `bypassPermissions` is the broadest and the empirically-verified path.
 - `--output-format json` — deterministic structured output. The subprocess's final agent message lands in the JSON response's `.result` field; orchestrator extracts `ITERATION_SUMMARY` from that field. Plain-text output would require fragile scraping.
+- `< /dev/null` — explicit stdin-closed redirect (P089 Gap 1). Without this, `claude -p` waits up to 3s for stdin data in non-TTY contexts and then prints `Warning: no stdin data received in 3s, proceeding without it. If piping from a slow command, redirect stdin explicitly: < /dev/null to skip, or wait longer.` to stderr. The warning is on stderr — if the caller separates stderr and stdout streams, the warning is harmless. But the orchestrator captures via `2>&1` (required because the CLI emits progress prose on stderr that must not interleave between JSON responses when multiple invocations chain). Under the `2>&1` merge the stderr warning prefixes the stdout JSON and breaks `jq` / `json.load` / `JSON.parse` extraction at "line 1, column 1: Expecting value". The redirect suppresses the warning at source. First observed AFK-iter-7 iter 1 (2026-04-21); workaround is the Anthropic CLI help's own suggestion.
 
 **No per-iteration budget cap.** The dispatch deliberately omits `--max-budget-usd`. Per user direction 2026-04-21: the natural stop condition for an AFK loop is quota exhaustion, not an arbitrary per-iteration dollar cap. A cap would halt iterations before quota is actually exhausted, wasting remaining budget. Runaway-iteration risk is bounded by quota + the orchestrator's Step 6.75 halt on unexpected dirty state + exit-code handling below.
 
@@ -224,6 +226,13 @@ SESSION_CACHE_READ_TOKENS=$(( ${SESSION_CACHE_READ_TOKENS:-0} + ITER_CACHE_READ
 
 Do NOT extract `session_id`, `model`, `stop_reason`, `permission_denials`, `uuid`, or any other field from the JSON response. Those are subprocess-envelope fields that serve no user-visible purpose and risk leaking subprocess-internal identifiers into orchestrator output.
 
+**Authority hierarchy (P089 Gap 2).** `total_cost_usd` and `usage.*` do NOT have the same reliability envelope — treat them accordingly when aggregating:
+
+- `.total_cost_usd` is **authoritative for dollar cost** — cumulative across the subprocess's entire lifetime by contract. Use it as the sole source of truth for the Session Cost "Total cost (USD)" column and any cost-based stop condition.
+- `.usage.*` token fields are **best-effort approximate** — the Anthropic CLI returns the final API response envelope, which is per-turn by construction. When the subprocess exits on a normal final turn the fields accumulate real usage; when the subprocess exits via a background-task completion-notification ack (a closing turn that only acknowledges a backgrounded task finished), the fields reflect ONLY that final ack turn and undercount dramatically. Detectable anomaly shape: the subprocess reports a final-turn-sized usage (handful of input tokens, hundreds of output tokens) alongside a wall-clock duration from the Bash wrapper's own timer that is orders of magnitude larger than the JSON's `duration_ms` field — the cumulative dollar cost still matches real spend, so the mismatch is self-evident on inspection.
+
+Aggregation rule: sum `.total_cost_usd` into the session total and trust it; sum `.usage.*` into the session totals for cache-reuse ratio reasoning but label them best-effort in the Session Cost table. This asymmetry is correct-by-CLI-contract (cost is a session cumulative; usage is a per-response envelope); the orchestrator documents the asymmetry so adopters do not silently under-count tokens. First observed AFK-iter-7 iter 5 (2026-04-21): 1071s wall-clock / 60+ tool-use subprocess returned `duration_ms: 8546, num_turns: 1, usage.* ≈ 137K tokens, total_cost_usd: 6.08` — cost cumulative and correct, tokens reflecting only the final ack turn.
+
 **Exit-code semantics.** `claude -p` exits non-zero when the subprocess fails hard — subprocess crash, auth failure, unresolvable permission denial, API/quota exhaustion. The orchestrator reads the exit code BEFORE parsing `.result`:
 
 - Exit 0 → parse `ITERATION_SUMMARY` from `.result` field; proceed to Step 6.
@@ -414,6 +423,8 @@ The skill should produce a final summary when the loop ends:
 
 Extracted from each iteration subprocess's `claude -p --output-format json` response (source: measured-actual, not estimated — per ADR-026 grounding). Renders identically in interactive and AFK modes; no decision branch, so output-side only. Cache-read column surfaces the warm-cache-reuse signal observed across subsequent subprocess invocations in the same Bash session.
 
+**Authority note (per P089 Gap 2 — see Step 5 Authority hierarchy):** the "Total cost (USD)" column is authoritative (CLI reports `.total_cost_usd` as a session cumulative). The token columns are **best-effort** — they accumulate each iteration's `.usage.*` response fields, which reflect only the final-turn API envelope and can undercount when a subprocess exits via a background-task completion-notification ack. Cost-based reasoning trusts the cost column; token-based reasoning (cache-reuse ratios, cost-envelope calibration) reads the token columns with that caveat in mind.
+
 | Metric | Value |
 |--------|-------|
 | Iterations run | 3 |
@@ -434,6 +445,7 @@ When every skipped ticket is in the `upstream-blocked` category (stop-condition
 
 ## Related
 
+- **P089** (`docs/problems/089-work-problems-step-5-dispatch-robustness-stdin-warning-and-cost-metadata-edge-case.verifying.md`) — driver for Step 5's `< /dev/null` dispatch redirect and the Per-iteration cost metadata "Authority hierarchy" paragraph. Gap 1: stdin warning contaminated stderr-merged JSON captures; closed by adding `< /dev/null` to the canonical dispatch command. Gap 2: `.usage.*` undercounts when subprocess exits via a background-task completion ack while `.total_cost_usd` stays cumulative-authoritative; closed by documenting the authority hierarchy in Step 5 and the Session Cost output section so adopters trust cost and label token totals best-effort.
 - **P086** (`docs/problems/086-afk-iteration-subprocess-does-not-run-retro-before-returning.verifying.md`) — driver for Step 5's retro-on-exit clause. Iteration subprocesses exit without running retro, so per-iteration friction (hook misbehaviour, repeat-workaround patterns, pipeline instability) evaporates on exit. Fix: iteration prompt body names `/wr-retrospective:run-retro` as a closing step before `ITERATION_SUMMARY` emission; retro runs inside the subprocess so Step 2b pipeline-instability scan has the full tool-call history; run-retro commits its own work per ADR-014; orchestrator picks up retro-created tickets on the next Step 1 scan.
 - **P084** (`docs/problems/084-work-problems-iteration-worker-has-no-agent-tool-so-architect-jtbd-gates-block.open.md`) — driver for Step 5's subprocess-boundary dispatch. Supersedes P077's Agent-tool dispatch on the same Step 5 surface because Agent-tool-spawned subagents cannot themselves invoke Agent (platform restriction), which prevents governance gate markers from being set inside the iteration worker.
 - **P077** (`docs/problems/077-work-problems-step-5-does-not-delegate-to-subagent.verifying.md`) — parent amendment. Established the AFK iteration-isolation wrapper sub-pattern and the `ITERATION_SUMMARY` return contract. P084 is the refinement that swaps the spawn mechanism; the isolation intent and return contract are preserved verbatim.

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

@@ -245,3 +245,89 @@ setup() {
   run grep -nE "ScheduleWakeup.{0,120}P083|P083.{0,120}ScheduleWakeup" "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
+
+# @problem P089
+# @jtbd JTBD-006
+#
+# STRUCTURAL: tests the SKILL.md content contract per ADR-037's Permitted
+# Exception (doc-lint contract assertion against the contract document
+# itself). Behavioural alternative would require spawning a real `claude -p`
+# subprocess from a non-TTY context, observing that the JSON response parses
+# cleanly, and asserting `jq` does not error on a stderr-merged capture —
+# that harness sits outside the skill layer and depends on the Anthropic
+# CLI binary. Contract assertion is the named permitted pattern.
+@test "SKILL.md Step 5 dispatch command redirects stdin (< /dev/null) to suppress stdin warning (P089 Gap 1)" {
+  # P089 Gap 1 (2026-04-21, AFK-iter-7 iter 1): the shipped dispatch command
+  # without an explicit stdin redirect causes `claude -p` to emit
+  # `Warning: no stdin data received in 3s, proceeding without it...` to
+  # stderr after a 3s wait. When the orchestrator captures the subprocess
+  # with `2>&1` (required for structured parse), that warning prepends to
+  # stdout and corrupts `jq` / `json.load` / `JSON.parse` extraction of
+  # `.result` and cost metadata. The `claude -p` CLI help explicitly
+  # suggests `< /dev/null` as the workaround. Regression guard ensures the
+  # redirect stays in the canonical dispatch block adopters copy.
+  run grep -nE '< /dev/null|< ?/dev/null' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 explains stdin warning is on stderr (becomes stdout problem under 2>&1 capture)" {
+  # Architect advisory (2026-04-22): the prose around the `< /dev/null`
+  # redirect must state that the warning is emitted to stderr (not stdout)
+  # so adopters who capture stderr separately understand they do not need
+  # the redirect. This prevents cargo-culting the redirect in environments
+  # where stdout and stderr are consumed independently.
+  run grep -niE "stderr.{0,120}(2>&1|merge|capture)|warning.{0,60}stderr|stderr.{0,60}warning" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# @problem P089
+# @jtbd JTBD-006
+#
+# STRUCTURAL: same Permitted Exception rationale — behavioural alternative
+# would require a subprocess that internally spawns a background task,
+# receives its completion notification, and returns a final-turn ack;
+# the observation is a runtime contract of the Anthropic CLI and harness
+# instrumentation sits outside the skill layer.
+@test "SKILL.md Per-iteration cost metadata block names total_cost_usd as authoritative (P089 Gap 2)" {
+  # P089 Gap 2 (2026-04-21, AFK-iter-7 iter 5): subprocess ran 1071s wall-clock
+  # with 60+ tool uses; JSON returned `duration_ms: 8546, num_turns: 1,
+  # usage.* = ~137K tokens, total_cost_usd: 6.08`. Cost was cumulative-
+  # authoritative; usage.* reflected only the final-turn ack after a
+  # background-task completion notification. The SKILL.md must name the
+  # authority hierarchy explicitly so Session Cost consumers treat
+  # total_cost_usd as the trusted dollar signal and usage.* as best-effort
+  # approximate.
+  run grep -niE "total_cost_usd.{0,80}authoritative|authoritative.{0,80}total_cost_usd|total_cost_usd.{0,40}cumulative" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Per-iteration cost metadata block flags usage.* as best-effort under early-ack anomaly (P089 Gap 2)" {
+  # The asymmetry between cumulative total_cost_usd and per-turn usage.*
+  # must be documented so contributors do not assume summing usage fields
+  # yields a total-tokens number matching real cost. Detection criterion
+  # (1-turn-short + duration_ms << wall-clock) is stated descriptively per
+  # architect option-b (keeps num_turns off the extracted field list).
+  run grep -niE "usage\\.\\*.{0,120}(best.?effort|approximate|final.?turn|under.?count|partial)|best.?effort.{0,120}usage|final.?turn.{0,120}usage" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Session Cost output section notes tokens are best-effort under the early-ack anomaly (P089 Gap 2)" {
+  # The Session Cost table renders to the user on every ALL_DONE. If token
+  # columns silently undercount when a subprocess exits via background-task
+  # ack, the user's cost envelope is wrong without any caveat. The output
+  # section must carry a short note that the token totals are best-effort
+  # while total-cost is authoritative — this is the observability contract
+  # visible to the end user, not just an internal implementation detail.
+  # The note can live inline in the table footer or in the prose around
+  # the table.
+  run grep -niE "tokens.{0,120}(best.?effort|approximate|undercount|may reflect)|total.?cost.{0,120}authoritative" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Related section cites P089 (Step 5 dispatch robustness)" {
+  # P089 documents the two gaps fixed by the < /dev/null redirect and the
+  # authority hierarchy paragraph. The Related section must cite it so the
+  # contract document remains self-documenting.
+  run grep -nE "P089" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}