@windyroad/itil 0.30.4 → 0.31.0-preview.323

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.30.4",
+  "version": "0.31.0-preview.323",
   "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

@@ -555,6 +555,18 @@ After the iteration's commit lands but before starting the next iteration, check
 1. Run `npm run push:watch` (push + wait for CI to pass).
 2. If `.changeset/` is non-empty after push, run `npm run release:watch` (merge the release PR + wait for npm publish).
 3. Resume the loop only after the release lands on npm.
+4. **Post-release cache refresh (P233)**: if step 2 actually ran AND succeeded (a release shipped to npm), chain `/install-updates` to refresh the plugin cache before the next iter dispatches. Skipped when step 2 was a no-op (empty `.changeset/` after push; no new plugin version exists). See the **Post-release cache refresh** subsection below for the full contract.
+
+**Post-release cache refresh (P233) — fires only after within-appetite Drain action step 4 (above):**
+
+After a successful release-cadence drain has shipped a new plugin version to npm, the orchestrator chains `/install-updates` to refresh the plugin cache before the next iter dispatches. Empirical evidence in `docs/briefing/afk-subprocess.md` ("Just-shipped gate-class hooks DON'T protect the immediate-next iter" entry) confirms iter subprocesses re-resolve plugin cache on spawn — so a just-shipped gate-class hook is inactive in the next iter unless the cache is refreshed first. The orchestrator IS the "restart" boundary for the next iter subprocess (each subprocess is a fresh `claude -p` per ADR-032 + `afk-subprocess-mechanics.md`); the cache refresh between release:watch and next-iter dispatch is the load-bearing step.
+
+- **Conditional on actual release**: only fires when `release:watch` actually published (step 2 of the Drain action above ran AND returned success). Skipped when `push:watch` ran alone (empty `.changeset/`; no new plugin version). Without this guard, every iter burns wall-clock + npm-API noise on a no-op cache refresh.
+- **Non-blocking on /install-updates failure**: if `/install-updates` fails (transient marketplace fetch error, P106-class quirk re-emergence, cache-miss + Non-interactive fallback dry-run), the orchestrator logs the failure and continues the loop. Degrades to current behaviour — cache stays stale; next iter may recur the just-shipped issue, equivalent to pre-amendment behaviour. The cache-refresh chain MUST NOT halt the loop on `/install-updates` failure under any circumstance.
+- **Policy authorisation (ADR-013 Rule 5)**: rides the same Rule 5 silent-proceed that already covers `push:watch` / `release:watch` in the drain — the post-release cache refresh is mechanically downstream of release and shares its authorisation. Composes with P106's claude-plugin-install no-op-when-already-installed factor (the chained `/install-updates` handles the uninstall+install dance per P106).
+- **Mid-loop ask discipline (P130) preserved**: if `/install-updates` Step 5b/5c consent gate fires (cache miss / scope delta / `INSTALL_UPDATES_RECONFIRM=1`), the orchestrator main turn treats this AS the **Non-interactive fallback** documented in `scripts/repo-local-skills/install-updates/SKILL.md` "Non-interactive fallback" subsection — log the dry-run output, do not interrupt the loop. The orchestrator's `.claude/.install-updates-consent` is normally present (install-updates Step 5a cache hit) so the gate fires silently. **ADR-044 framework-resolution boundary** authorises this AskUserQuestion-available-but-forbidden routing: invocation between iters is a mechanical-stage transition the framework has resolved; surfacing it to the user would dilute the Step 2.5b accumulated-question discipline.
+
+**Composition with the Above-appetite branch (below)**: the cache refresh is anchored to the within-appetite Drain action step 4 — it does NOT fire after the above-appetite Rule 5 halt (no release shipped → nothing to refresh) and it does NOT fire mid-loop in the above-appetite auto-apply loop. When the auto-apply loop converges and re-enters the within-appetite Drain action, the cache refresh fires there per step 4. The chain's site is the Drain action only.
 
 **Failure handling (P140)**: When `push:watch` or `release:watch` reports a CI failure or publish failure, the orchestrator follows a diagnose-then-classify routing — fix-and-continue for the documented mechanically-fixable allow-list, halt for everything else. The previous uniform halt rule converted mechanically-fixable failures (1-line stale-grep-string updates, transient flakes) into ~45min queue stalls, regressing JTBD-006 "Progress the Backlog While I'm Away" without any governance benefit.
 
@@ -665,6 +677,7 @@ When `AskUserQuestion` is unavailable or the user is AFK, the skill (and the del
 | Commit when risk within appetite | Auto-commit (manage-problem step 9e fallback) |
 | Commit when risk above appetite | Skip commit, report uncommitted state |
 | Pipeline risk at appetite (push or release = 4/25) | Drain release queue (`push:watch` then `release:watch`) before next iteration — per ADR-018 (Step 6.5) |
+| Post-release plugin cache refresh between iters (P233) | After a successful within-appetite Drain action shipped a release to npm, chain `/install-updates` to refresh the plugin cache before the next iter dispatches. Conditional on actual release (skipped when `push:watch` ran alone with no changeset); non-blocking on `/install-updates` failure (degrades to cache-stays-stale, equivalent to pre-amendment behaviour). Mid-loop ask discipline preserved by treating any `/install-updates` AskUserQuestion surface AS the Non-interactive fallback dry-run path. Per ADR-013 Rule 5 + ADR-044 + P130 + P106 + P233 (Step 6.5 Post-release cache refresh subsection). |
 | CI failure during Step 6.5 drain (within-appetite branch) | Diagnose via `gh run view --log-failed`, classify against the closed fixable-in-iter allow-list (P081-class stale-grep-string, hook stub mismatch, test ID drift, environmental flake), fix-and-continue for fixable classes (each retry rides its own ADR-014 commit gate), 3-retry cap per iteration, halt for unrecoverable classes. Ambiguous classification defaults to halt. ADR-013 Rule 5 policy-authorised. Per ADR-026 grounding + ADR-044 framework-resolution boundary + P140 (Step 6.5 Failure handling). |
 | Pipeline risk above appetite (push or release >= 5/25) | Auto-apply scorer remediations incrementally (ADR-042 Rule 2). The agent reads suggestions and decides what to do. Re-score after each apply; drain when within appetite. **Never release above appetite** (ADR-042 Rule 1) — no AskUserQuestion shortcut. Halt the loop with `outcome: halted-above-appetite` if the loop exhausts without convergence (ADR-042 Rule 5). Verification Pending commits excluded from auto-revert (Rule 2b). Per ADR-042 (Step 6.5 Above-appetite branch). |
 | Origin diverged before start | Pull `--ff-only` if trivial; stop with report (`git log HEAD..origin/<base>` and reverse) if non-fast-forward — per ADR-019 (Step 0) |

package/skills/work-problems/test/work-problems-step-6-5-cache-refresh-chain.bats

@@ -0,0 +1,174 @@
+#!/usr/bin/env bats
+
+# P233: /wr-itil:work-problems Step 6.5 Drain action must chain
+# /install-updates AFTER successful release:watch so the next iter
+# subprocess loads the just-shipped plugin from cache rather than the
+# pre-release cached version.
+#
+# Empirical driver (briefing/afk-subprocess.md:18): iter subprocesses
+# re-resolve plugin cache on spawn; without cache refresh between
+# release:watch and next-iter dispatch, the just-shipped hook is
+# inactive in the next iter — defeating the "ship a hook to prevent
+# recurrence" pattern for the immediate-next-iter case.
+#
+# Doc-lint contract assertions per ADR-037 Permitted Exception
+# (contract-assertion class — same shape as the P140 / P130 / P126 / P135
+# sibling fixtures). The asserted prose IS the load-bearing policy
+# surface — the chained invocation is documentation-only (the orchestrator
+# is a prose-driven agent, not a script); the SKILL.md is the contract.
+# Behavioural assertion would require a fixture project + real claude -p
+# subprocess that observes a freshly-installed plugin — outside scope.
+#
+# @problem P233
+# @adr ADR-013 (Rule 5 — policy-authorised silent action; chains the
+#       same authorisation that covers push:watch / release:watch)
+# @adr ADR-014 (one-commit-per-iter; this edit lands in one commit)
+# @adr ADR-018 (inter-iteration release cadence; this refines its
+#       Drain action sub-block with the post-release cache refresh)
+# @adr ADR-030 (repo-local skills — install-updates is the chained
+#       skill)
+# @adr ADR-037 (skill-testing strategy — contract-assertion class)
+# @adr ADR-044 (decision-delegation contract — framework-resolution
+#       boundary; install-updates' AskUserQuestion-bearing branches
+#       fall through to its Non-interactive fallback under P130)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — primary;
+#       outcome 7 "risk never silently accumulates across AFK iterations"
+#       extends to "just-shipped hooks effective on next iter")
+# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — composes;
+#       just-shipped governance hooks become effective immediately,
+#       not after manual /install-updates re-run)
+# @jtbd JTBD-007 (Keep Plugins Current Across Projects — persona-level
+#       currency anchor that JTBD-006's AFK use case extends)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_MD="$REPO_ROOT/packages/itil/skills/work-problems/SKILL.md"
+}
+
+@test "work-problems P233: SKILL.md exists" {
+  [ -f "$SKILL_MD" ]
+}
+
+# ── Cache-refresh chain identity ───────────────────────────────────────────
+
+@test "work-problems P233: Step 6.5 Drain action carries a post-release cache-refresh subsection citing P233" {
+  # The amendment must self-identify so future readers tracing back from
+  # the ticket find the load-bearing prose without keyword-guessing.
+  run grep -nE 'cache.refresh.*P233|P233.*cache.refresh|post.release.cache.*P233|P233.*post.release.cache' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: Drain action chains /install-updates after successful release:watch" {
+  # Core contract: after release:watch returns success, the orchestrator
+  # invokes /install-updates to refresh the plugin cache. Without this
+  # chain, the next iter subprocess loads the pre-release cached version
+  # (P233's empirical root cause).
+  run grep -nE '/install-updates|install-updates skill' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: cache-refresh is conditional on actual release (skipped when no changeset)" {
+  # The chain MUST NOT fire when release:watch was a no-op (empty
+  # .changeset/ after push). No new plugin version exists → nothing to
+  # refresh. Without this guard, the orchestrator burns wall-clock and
+  # noise on a no-op /install-updates invocation every iter.
+  run grep -niE 'only.*release.*actually|when.*release.*shipped|skip.*when.*no.changeset|conditional on.*release' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: cache-refresh is non-blocking on /install-updates failure" {
+  # If /install-updates fails (cache miss + non-interactive fallback,
+  # marketplace fetch error, transient flake), the orchestrator MUST NOT
+  # halt the loop. Degrades to current behaviour — cache stays stale;
+  # equivalent to pre-amendment behaviour. Loop continues.
+  run grep -niE 'non.blocking.*install.updates|install.updates.*non.blocking|do not halt.*install.updates|install.updates.*failure.*continue' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── Empirical evidence citation ────────────────────────────────────────────
+
+@test "work-problems P233: cache-refresh subsection cites briefing/afk-subprocess.md evidence" {
+  # The architect FLAG resolution required the evidence that subprocesses
+  # re-resolve cache on spawn (rather than inherit parent-resolved
+  # plugins). The briefing entry is dispositive — cite it inline so
+  # future readers don't re-litigate the question.
+  run grep -nE 'afk-subprocess|briefing.*subprocess.*cache' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── ADR-013 Rule 5 policy authorisation ────────────────────────────────────
+
+@test "work-problems P233: cache-refresh chain rides ADR-013 Rule 5 (same authorisation as push:watch / release:watch)" {
+  # The chain MUST be silent — invocation between iters is a mechanical
+  # post-release step the framework has resolved. Same ADR-013 Rule 5
+  # citation already covers push:watch / release:watch in the within-
+  # appetite drain; the cache-refresh extends the same authorisation.
+  run grep -nE 'ADR-013 Rule 5|Rule 5 policy-authorised|policy-authorised.*ADR-013' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── Mid-loop ask discipline preservation (P130) ────────────────────────────
+
+@test "work-problems P233: cache-refresh prose cites install-updates Non-interactive fallback for AskUserQuestion routing" {
+  # If install-updates' Step 5b/5c consent gate fires (cache miss /
+  # scope delta / INSTALL_UPDATES_RECONFIRM=1), the orchestrator main
+  # turn MUST NOT surface AskUserQuestion mid-loop per P130. Cite the
+  # install-updates Non-interactive fallback as the routing.
+  run grep -niE 'Non.interactive fallback|non-interactive fallback' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: cache-refresh prose cites ADR-044 framework-resolution boundary for AskUserQuestion-available-but-forbidden routing" {
+  # Architect advisory: cite ADR-044 alongside the Non-interactive
+  # fallback ref so future readers can trace the "AskUserQuestion-
+  # available-but-forbidden" reasoning back to the framework-resolution
+  # boundary — not just the install-updates-side dry-run mechanic.
+  run grep -nE 'ADR-044' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── Composition with above-appetite branch ─────────────────────────────────
+
+@test "work-problems P233: cache-refresh fires only after within-appetite Drain action (not after above-appetite Rule 5 halt)" {
+  # Above-appetite Rule 5 halt terminates without a release; no cache
+  # refresh fires. Within-appetite convergence loops back to Drain
+  # action; cache refresh fires there. The prose must not place the
+  # chain inside the above-appetite branch.
+  run grep -niE 'within.appetite.*drain.*cache|cache.refresh.*within.appetite|after.*drain.*action' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── Non-Interactive Decision Making table row ──────────────────────────────
+
+@test "work-problems P233: Decision Making table carries a post-release cache-refresh row" {
+  # The decision table is the AFK reader's quick-reference; without a
+  # row here the cache-refresh chain is buried in Step 6.5.
+  run grep -nE '\|.*[Pp]ost.release cache|\|.*[Cc]ache refresh|\|.*[Pp]lugin cache refresh' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: Decision Making table row cites P233" {
+  # Per ADR-037 doc-lint pattern + existing P140 / P126 / P135 sibling
+  # rows — every Decision Making table row that documents a P-driven
+  # refinement cites the driver ticket.
+  run grep -nE '\|.*cache refresh.*P233|\|.*P233.*cache refresh|\|.*post.release.*P233|\|.*P233.*post.release' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+# ── Composition cross-references ───────────────────────────────────────────
+
+@test "work-problems P233: cache-refresh prose cross-references P106 (claude plugin install no-op-when-already-installed)" {
+  # P106 is the compounding factor that makes /install-updates' explicit
+  # uninstall + install dance necessary (vs. naive claude plugin
+  # install which silent-no-ops). Cite it so future readers don't try
+  # to simplify the chain.
+  run grep -nE 'P106' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems P233: cache-refresh prose cross-references P130 (orchestrator main-turn ask discipline preserved)" {
+  # P130 is the constraint the Non-interactive fallback routing exists
+  # to satisfy. Citation makes the dependency auditable.
+  run grep -nE 'P130' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}