@windyroad/itil 0.29.0 → 0.30.0

package/.claude-plugin/plugin.json

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

package/lib/check-upstream-cache-staleness.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Inbound-discovery cache staleness check — Step 0b of /wr-itil:work-problems.
+# ADR-062 § JTBD-006 driver: work-problems should pre-flight
+# /wr-itil:review-problems when the upstream inbound-discovery cache is stale
+# or missing, so AFK loops keep upstream-reported problems visible without
+# the maintainer remembering to invoke review-problems first.
+#
+# The staleness comparison MUST stay symmetric with review-problems Step 4.5b's
+# branches (first-run / TTL-expiry / cache-fresh). Drift here re-opens the
+# inbound-discovery staleness contract — any change to TTL semantics MUST
+# update both this helper and packages/itil/skills/review-problems/SKILL.md
+# Step 4.5b in the same commit.
+# <!-- INBOUND-CACHE-STALENESS-CONTRACT-SOURCE: packages/itil/skills/review-problems/SKILL.md Step 4.5b -->
+#
+# Source this file, then call `should_promote_inbound_discovery_preflight`:
+#   . packages/itil/lib/check-upstream-cache-staleness.sh
+#   reason="$(should_promote_inbound_discovery_preflight "$PWD")"
+#
+# Output (one of):
+#   no-channels-config           → channels-config absent; skip silently.
+#                                  Downstream-adopter non-obligation per
+#                                  ADR-062 § Downstream-adopter contract.
+#   first-run-cache-absent       → channels-config present, cache file absent.
+#                                  Dispatch review-problems.
+#   first-run-last-checked-null  → cache present but last_checked is null.
+#                                  Dispatch review-problems.
+#   fresh-within-ttl             → cache within TTL; silent-pass.
+#   ttl-expiry age=<N>s ttl=<M>s → cache older than TTL; dispatch.
+#
+# Dependencies: bash 4+, jq, python3 (for ISO-8601 parsing — portable across
+# Linux/BSD date implementations).
+
+should_promote_inbound_discovery_preflight() {
+  local repo_root="${1:-$PWD}"
+  local channels_file="$repo_root/docs/problems/.upstream-channels.json"
+  local cache_file="$repo_root/docs/problems/.upstream-cache.json"
+
+  if [ ! -f "$channels_file" ]; then
+    echo "no-channels-config"
+    return 0
+  fi
+
+  local ttl_seconds
+  ttl_seconds="$(jq -r '.ttl_seconds // 86400' "$channels_file")"
+
+  if [ ! -f "$cache_file" ]; then
+    echo "first-run-cache-absent"
+    return 0
+  fi
+
+  local last_checked
+  last_checked="$(jq -r '.last_checked // ""' "$cache_file")"
+
+  if [ -z "$last_checked" ] || [ "$last_checked" = "null" ]; then
+    echo "first-run-last-checked-null"
+    return 0
+  fi
+
+  local last_checked_epoch now_epoch cache_age
+  last_checked_epoch="$(python3 -c "import datetime,sys; ts=sys.argv[1].replace('Z','+00:00'); print(int(datetime.datetime.fromisoformat(ts).timestamp()))" "$last_checked" 2>/dev/null || echo "0")"
+  now_epoch="$(date +%s)"
+  cache_age=$((now_epoch - last_checked_epoch))
+
+  if [ "$cache_age" -gt "$ttl_seconds" ]; then
+    echo "ttl-expiry age=${cache_age}s ttl=${ttl_seconds}s"
+    return 0
+  fi
+
+  echo "fresh-within-ttl"
+  return 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.29.0",
+  "version": "0.30.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

@@ -145,7 +145,46 @@ On a flat-layout adopter repo (first invocation post-update — JTBD-101 plugin-
 
 **First-fire signal**: the routine emits a single stderr line on the migrating invocation; silent on no-op re-invocations.
 
-After Step 0a completes (whether no-op or migration), proceed to Step 1 backlog scan. The dual-tolerant glob at Step 1 (RFC-002 transitional window) continues to match both layouts; post-T6 (single-pattern collapse), Step 1 will tighten to per-state only and the migration commit ensures the adopter tree matches.
+After Step 0a completes (whether no-op or migration), proceed to Step 0b's inbound-discovery pre-flight check. The dual-tolerant glob at Step 1 (RFC-002 transitional window) continues to match both layouts; post-T6 (single-pattern collapse), Step 1 will tighten to per-state only and the migration commit ensures the adopter tree matches.
+
+### Step 0b: Upstream inbound-discovery pre-flight (per ADR-062 § JTBD-006 driver)
+
+After Step 0a's auto-migrate and before Step 1's backlog scan, check whether the upstream inbound-discovery cache is fresh. ADR-062 § Decision Drivers names `/wr-itil:work-problems` as the surface that should keep inbound reports visible during AFK loops; the TTL self-healing branch inside `/wr-itil:review-problems` Step 4.5b only fires if review-problems is entered. This step closes that gap by pre-flighting `/wr-itil:review-problems` when the cache is stale or missing.
+
+**Mechanism:**
+
+```bash
+source packages/itil/lib/check-upstream-cache-staleness.sh
+preflight_reason="$(should_promote_inbound_discovery_preflight "$PWD")"
+```
+
+The helper returns one of five outcomes (contract documented at `packages/itil/lib/check-upstream-cache-staleness.sh` + asserted by `packages/itil/skills/work-problems/test/work-problems-step-0b-cache-staleness-behavioural.bats`):
+
+| `preflight_reason`                | Action                                                                                                |
+|-----------------------------------|--------------------------------------------------------------------------------------------------------|
+| `no-channels-config`              | Silent-pass. Downstream-adopter non-obligation per ADR-062 § Downstream-adopter contract. Proceed to Step 1. |
+| `first-run-cache-absent`          | Dispatch `/wr-itil:review-problems` as a pre-flight iter via the standard `claude -p` subprocess wrapper (same shape as Step 5; see Step 5 for the subprocess invocation contract). |
+| `first-run-last-checked-null`     | Same as `first-run-cache-absent` — cache schema present but never populated.                          |
+| `ttl-expiry age=<N>s ttl=<M>s`    | Dispatch `/wr-itil:review-problems` as a pre-flight iter. Cache is stale; review-problems' Step 4.5b's TTL-expiry auto-recheck branch fires inside the dispatched subprocess and refreshes the cache + audit-log + README. |
+| `fresh-within-ttl`                | Silent-pass per ADR-013 Rule 5 + P132 mechanical-stage carve-out. Proceed to Step 1.                  |
+
+**Pre-flight dispatch shape**: when promoted, dispatch a single `claude -p --permission-mode bypassPermissions --output-format json` subprocess that invokes `/wr-itil:review-problems` (per P084 + ADR-032 subprocess isolation). The subprocess runs the full Step 4.5 inbound-discovery + assessment pipeline; the cache + `docs/audits/inbound-discovery-log.md` + `docs/problems/README.md` are refreshed in its own commit per ADR-014 (review-problems' Slice E commit grain). After the subprocess completes, the orchestrator reads the freshly-refreshed README at Step 1.
+
+**Iter-summary annotation**:
+
+- Channels-config absent: `Step 0b skipped — no upstream-channels.json (downstream-adopter non-obligation)`.
+- Cache fresh: `Step 0b skipped — upstream inbound-discovery cache fresh within TTL`.
+- Pre-flight ran: `Step 0b pre-flighted /wr-itil:review-problems — reason=<preflight_reason>, <N> reports discovered, <M> local tickets created`.
+
+The annotation pre-empts the "surprise heavy iter" perception JTBD-006 expects auditability for — a maintainer running multiple short AFK loops within a 24h window will hit `fresh-within-ttl` on subsequent invocations and see the cache-fresh annotation, confirming the system's silent-pass discipline rather than wondering whether the check ran at all.
+
+**AFK authorisation per ADR-013 Rule 6**: review-problems' Step 4.5 pipeline is itself AFK-safe — branch decisions are mechanical per P132 / ADR-044 category 4 silent framework action; external-comms gates on verdict/acknowledgement/pushback comments silent-pass on low-risk verdicts per ADR-028 + the `wr-risk-scorer:external-comms` subagent's *"policy-authorised drafts proceed silently"* contract (`packages/risk-scorer/agents/external-comms.md` § PASS Output); gate-denial sub-branches fail-soft and retry on the next discovery pass. No new user-attention surface introduced at the Step 0b promotion point.
+
+**Compose-with**: ADR-014 (review-problems' Slice E commit grain holds — the pre-flight subprocess emits its own commit; orchestrator-main-turn does not commit Step 0b), ADR-013 Rule 5/6 (silent-pass + AFK fail-safe — both honored), P084 + P077 (subprocess isolation reuse — same `claude -p` wrapper as Step 5), ADR-019 (preflight surface — Step 0b is the natural extension of "reconcile state before opening the loop"), P132 (mechanical-stage carve-out — no `AskUserQuestion` at the promotion point). Mid-loop ticket creation by Step 4.5e's safe-and-valid branch enters the WSJF queue Step 1 reads on the same invocation — natural absorption, no deadlock; the pre-flight commit lands before Step 1's README read.
+
+**Staleness contract drift**: the staleness comparison MUST stay symmetric with `/wr-itil:review-problems` Step 4.5b's branches (first-run / TTL-expiry / cache-fresh). Drift here re-opens the inbound-discovery staleness contract — any change to TTL semantics MUST update both this Step 0b helper and review-problems Step 4.5b in the same commit. <!-- INBOUND-CACHE-STALENESS-CONTRACT-SOURCE: packages/itil/skills/review-problems/SKILL.md Step 4.5b -->
+
+After Step 0b completes (whether dispatched or silent-passed), proceed to Step 1.
 
 ### Step 1: Scan the backlog
 
@@ -157,7 +196,7 @@ Exclude:
 - `.closed.md` files (done)
 - `.parked.md` files (blocked on upstream)
 - `.verifying.md` files (Verification Pending — fix released, awaiting user verification per ADR-022; surfaced in the Verification Queue section, never in dev-work ranking)
-- Problems with no WSJF score (need a review first — run `/wr-itil:manage-problem review` as the first iteration if scores are missing)
+- Problems with no WSJF score (need a review first — run `/wr-itil:review-problems` as the first iteration if scores are missing)
 
 ### Step 2: Check stop conditions
 
@@ -668,7 +707,7 @@ The orchestrator MUST NOT call `AskUserQuestion` between iterations except at th
 
 ## Edge Cases
 
-**Review needed first**: If no problems have WSJF scores, run `/wr-itil:manage-problem review` as the first iteration to score everything, then proceed to the work loop.
+**Review needed first**: If no problems have WSJF scores, run `/wr-itil:review-problems` as the first iteration to score everything, then proceed to the work loop. (Independent of Step 0b's inbound-discovery pre-flight, which fires on cache staleness regardless of WSJF-score state.)
 
 **Scope creep during investigation**: If investigating an open problem reveals the scope is larger than expected (effort re-sized from S to L, or L to XL), save findings to the problem file, update the WSJF score, and move to the next problem. Don't sink unlimited effort into one problem during AFK mode — the user can decide when they return.
 

package/skills/work-problems/test/work-problems-step-0b-cache-staleness-behavioural.bats

@@ -0,0 +1,138 @@
+#!/usr/bin/env bats
+
+# Step 0b behavioural fixture per ADR-062 § JTBD-006 driver:
+# work-problems pre-flights /wr-itil:review-problems when the
+# upstream inbound-discovery cache is stale or missing. The
+# staleness decision lives in
+# `packages/itil/lib/check-upstream-cache-staleness.sh::should_promote_inbound_discovery_preflight`
+# so the SKILL.md Step 0b prose is a thin source-and-call wrapper
+# around a behaviorally-testable shell function (P081 / user
+# feedback: prefer behavioural over structural-grep tests).
+#
+# Cases covered:
+#   1. No channels-config file → "no-channels-config" (downstream-adopter non-obligation, ADR-062 § Downstream-adopter contract).
+#   2. Channels-config present, cache file absent → "first-run-cache-absent".
+#   3. Channels-config present, cache present, last_checked null → "first-run-last-checked-null".
+#   4. Channels-config present, cache fresh within TTL → "fresh-within-ttl".
+#   5. Channels-config present, cache older than TTL → "ttl-expiry" (with age + ttl in the reason).
+#   6. Custom ttl_seconds in channels-config is respected (not hardcoded default).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  HELPER="$REPO_ROOT/packages/itil/lib/check-upstream-cache-staleness.sh"
+
+  FIXTURE="$(mktemp -d)"
+  mkdir -p "$FIXTURE/docs/problems"
+}
+
+teardown() {
+  rm -rf "$FIXTURE"
+}
+
+@test "helper exists at the contracted path" {
+  [ -f "$HELPER" ]
+}
+
+@test "case 1: no channels-config → no-channels-config" {
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-channels-config" ]
+}
+
+@test "case 2: channels-config present, cache absent → first-run-cache-absent" {
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [], "ttl_seconds": 86400 }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "first-run-cache-absent" ]
+}
+
+@test "case 3: cache present, last_checked null → first-run-last-checked-null" {
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [], "ttl_seconds": 86400 }
+EOF
+  cat > "$FIXTURE/docs/problems/.upstream-cache.json" <<'EOF'
+{ "last_checked": null, "channels": [] }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "first-run-last-checked-null" ]
+}
+
+@test "case 4: cache fresh within TTL → fresh-within-ttl (silent-pass)" {
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [], "ttl_seconds": 86400 }
+EOF
+  # last_checked 1 hour ago — well within 24h TTL.
+  local recent_iso
+  recent_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.upstream-cache.json" <<EOF
+{ "last_checked": "$recent_iso", "channels": [] }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "fresh-within-ttl" ]
+}
+
+@test "case 5: cache older than TTL → ttl-expiry with age + ttl in the reason" {
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [], "ttl_seconds": 86400 }
+EOF
+  # last_checked 2 days ago — past 24h TTL.
+  local stale_iso
+  stale_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=2)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.upstream-cache.json" <<EOF
+{ "last_checked": "$stale_iso", "channels": [] }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  # Format: "ttl-expiry age=<N>s ttl=<M>s"
+  [[ "$output" =~ ^ttl-expiry\ age=[0-9]+s\ ttl=86400s$ ]]
+}
+
+@test "case 6: custom ttl_seconds is honored (not hardcoded default)" {
+  # 1-hour TTL; last_checked 90 minutes ago → stale under the custom TTL,
+  # but would be FRESH under the 86400s default. Confirms the helper reads
+  # ttl_seconds from channels-config rather than hardcoding 86400.
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [], "ttl_seconds": 3600 }
+EOF
+  local mid_iso
+  mid_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(minutes=90)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.upstream-cache.json" <<EOF
+{ "last_checked": "$mid_iso", "channels": [] }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [[ "$output" =~ ^ttl-expiry\ age=[0-9]+s\ ttl=3600s$ ]]
+}
+
+@test "case 7: missing ttl_seconds field defaults to 86400 (24h)" {
+  cat > "$FIXTURE/docs/problems/.upstream-channels.json" <<'EOF'
+{ "channels": [] }
+EOF
+  # last_checked 1 hour ago — fresh under the default 86400s TTL.
+  local recent_iso
+  recent_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.upstream-cache.json" <<EOF
+{ "last_checked": "$recent_iso", "channels": [] }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_inbound_discovery_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "fresh-within-ttl" ]
+}