@windyroad/itil 0.50.1-preview.709 → 0.50.2

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.50.1"
+  "version": "0.50.2"
 }

package/package.json

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

package/scripts/derive-release-vehicle.sh

@@ -24,11 +24,23 @@
 #     merge-commit: <SHA>
 #     release-date: <YYYY-MM-DD>
 #
+# De-facto-released variant (P361, exit 0) when the changeset is present in
+# .changeset/ but its code already shipped with a sibling release:
+#   RELEASE_VEHICLE:
+#     changeset: .changeset/<name>.md
+#     status: de-facto-released (attribution pending)
+#     fix-commit: <SHA>
+#     shipped-with-version-packages-commit: <SHA>
+#     release-date: <YYYY-MM-DD>
+#     note: ...
+#
 # Exit codes:
-#   0 = OK (full citation emitted)
+#   0 = OK (full citation emitted, OR de-facto-released graduated-holding
+#       changeset whose code already shipped with a sibling release — P361)
 #   1 = ticket file not found
 #   2 = no changeset reference in ticket body
-#   3 = changeset still present in working tree (unreleased)
+#   3 = changeset present in working tree AND not de-facto-released
+#       (genuinely unreleased)
 #   4 = deletion commit found but no merge PR / merge commit resolvable
 #
 # @problem P267 — Codify derive-release-vehicle.sh helper for K→V release-
@@ -36,6 +48,14 @@
 #                 fragile to wrong-release-cited errors when sessions
 #                 pre-apply transitions across sibling tickets (observed
 #                 2026-05-18 P250 K→V cited P247's release refs).
+# @problem P361 — exit-3 "unreleased" false positive on ADR-061 graduated
+#                 holding changesets; helper now distinguishes "attribution
+#                 pending" (de-facto-released, exit 0) from "code unreleased"
+#                 (exit 3) via an add-commit ancestry test against the latest
+#                 version-packages commit.
+# @adr ADR-061 (dogfood graduation criteria — held changeset reinstated to
+#               .changeset/ awaiting attribution after its code shipped; the
+#               de-facto-released exit-0 path)
 # @adr ADR-049 (bin/ on PATH shim — adopter-safe script resolution; helper
 #               is invoked as `wr-itil-derive-release-vehicle`)
 # @adr ADR-022 (Verifying lifecycle — citation supports the K→V transition's
@@ -58,10 +78,10 @@ USAGE: derive-release-vehicle.sh <ticket-id> [<problems-dir>]
   <problems-dir> — defaults to ./docs/problems
 
 Exit codes:
-  0  ok (full citation emitted)
+  0  ok (full citation, OR de-facto-released graduated-holding changeset — P361)
   1  ticket file not found
   2  no changeset reference in ticket body
-  3  changeset still present in working tree (unreleased)
+  3  changeset present in working tree AND not de-facto-released (unreleased)
   4  deletion commit found but no merge PR / merge commit resolvable
 EOF
 }
@@ -112,7 +132,55 @@ fi
 
 # ── Released?  Changeset must be ABSENT from working tree (deleted by
 #    chore: version packages) AND have a deletion commit in git history. ────
+# Exception (P361 / ADR-061 Rule 5 + P359): a changeset can be reinstated to
+# .changeset/ awaiting changelog attribution AFTER its code already de-facto
+# shipped with a sibling release (held code ships with any sibling release —
+# P359). Present-in-tree therefore does NOT always mean unreleased. Before
+# exiting 3, test whether the commit that originally ADDED this changeset is
+# an ancestor of the latest published "chore: version packages" commit; if so
+# the fix code shipped → emit a de-facto-released citation (exit 0). A
+# genuinely-unreleased fresh changeset has its add-commit NEWER than the last
+# bump, so the is-ancestor test is false and it correctly stays exit 3.
 if [ -f "$CHANGESET_PATH" ]; then
+  # Oldest Add of the path = the original fix commit. Robust to the
+  # hold→graduate `git mv`, which (without rename detection) records a later
+  # Add at the same path; `tail -1` selects the original.
+  ADD_SHA="$(
+    git log --diff-filter=A --format='%H' -- "$CHANGESET_PATH" 2>/dev/null \
+      | tail -1
+  )"
+
+  # Resolve the published-history ref (same ladder used for merge resolution).
+  DEFACTO_REF=""
+  for ref in origin/main main HEAD; do
+    if git rev-parse --verify "$ref" >/dev/null 2>&1; then
+      DEFACTO_REF="$ref"
+      break
+    fi
+  done
+
+  LATEST_VERSION_BUMP=""
+  if [ -n "$DEFACTO_REF" ]; then
+    LATEST_VERSION_BUMP="$(
+      git log --grep='^chore: version packages' --format='%H' -1 "$DEFACTO_REF" 2>/dev/null
+    )"
+  fi
+
+  if [ -n "$ADD_SHA" ] && [ -n "$LATEST_VERSION_BUMP" ] \
+     && git merge-base --is-ancestor "$ADD_SHA" "$LATEST_VERSION_BUMP" 2>/dev/null; then
+    RELEASE_DATE="$(git log -1 --format='%cs' "$LATEST_VERSION_BUMP" 2>/dev/null)"
+    cat <<EOF
+RELEASE_VEHICLE:
+  changeset: $CHANGESET_PATH
+  status: de-facto-released (attribution pending)
+  fix-commit: $ADD_SHA
+  shipped-with-version-packages-commit: $LATEST_VERSION_BUMP
+  release-date: $RELEASE_DATE
+  note: changeset present in .changeset/ awaiting changelog attribution (ADR-061 holding-graduation); code already shipped with a sibling release (P359).
+EOF
+    exit 0
+  fi
+
   echo "ERROR: changeset $CHANGESET_PATH still present in working tree (unreleased)" >&2
   exit 3
 fi

package/scripts/test/derive-release-vehicle.bats

@@ -21,10 +21,11 @@
 #     release-date: <YYYY-MM-DD>
 #
 # Exit codes:
-#   0 = OK (full citation emitted)
+#   0 = OK (full citation emitted, OR de-facto-released graduated-holding
+#       changeset whose code already shipped with a sibling release — P361)
 #   1 = ticket file not found
 #   2 = no changeset reference in ticket body
-#   3 = changeset not yet deleted (unreleased)
+#   3 = changeset still present AND not de-facto-released (genuinely unreleased)
 #   4 = deletion commit found but no merge PR / merge commit resolvable
 #
 # @adr ADR-049 (bin/ on PATH shim — adopter-safe script resolution)
@@ -124,6 +125,102 @@ EOF
   echo "$output" | grep -qi "unreleased\|not.*delet"
 }
 
+# ── Exit 0: de-facto-released graduated-holding changeset (P361) ─────────────
+
+@test "derive-release-vehicle: graduated holding changeset whose code shipped with a sibling release → exit 0 de-facto-released" {
+  # P361 / ADR-061 Rule 5 + P359: a changeset can be reinstated to
+  # .changeset/ awaiting changelog attribution AFTER its code already shipped
+  # with a sibling release. Present-in-tree must NOT read as unreleased.
+  cat > .changeset/p211-graduated.md <<'EOF'
+---
+'@windyroad/itil': patch
+---
+
+P211 fix — held then graduated.
+EOF
+  cat > docs/problems/verifying/211-graduated.md <<'EOF'
+# Problem 211: Graduated
+
+**Status**: Known Error
+
+## Fix Strategy
+
+Ship via `.changeset/p211-graduated.md`.
+EOF
+  git add .
+  git commit -q -m "feat(itil): P211 fix + changeset"   # commit A — the fix
+
+  # Hold it out of the active release queue (ADR-042 Rule 7).
+  mkdir -p docs/changesets-holding
+  git mv .changeset/p211-graduated.md docs/changesets-holding/p211-graduated.md
+  git commit -q -m "chore(itil): hold P211 changeset (above-appetite)"
+
+  # A sibling release ships AFTER the fix landed (P359: code ships regardless).
+  cat > .changeset/p999-sibling.md <<'EOF'
+---
+'@windyroad/itil': patch
+---
+
+Sibling fix.
+EOF
+  git add .changeset/p999-sibling.md
+  git commit -q -m "feat(itil): sibling fix + changeset"
+  git rm -q .changeset/p999-sibling.md
+  git commit -q -m "chore: version packages"   # the published release bump
+
+  # Graduate the held changeset back to .changeset/ awaiting attribution.
+  mkdir -p .changeset
+  git mv docs/changesets-holding/p211-graduated.md .changeset/p211-graduated.md
+  git commit -q -m "chore(itil): graduate P211 changeset"
+
+  run "$SCRIPT" P211 docs/problems
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qi "de-facto-released"
+  echo "$output" | grep -q "changeset: .changeset/p211-graduated.md"
+}
+
+@test "derive-release-vehicle: fresh changeset added AFTER the last release → still exit 3 (not a false de-facto-released)" {
+  # Guard: a prior release exists, but THIS changeset was added afterwards —
+  # its code has NOT shipped. Its add-commit is a DESCENDANT of the last
+  # version bump, so the is-ancestor discriminator must keep it at exit 3.
+  cat > .changeset/p888-old.md <<'EOF'
+---
+'@windyroad/itil': patch
+---
+
+Old fix that did ship.
+EOF
+  git add .changeset/p888-old.md
+  git commit -q -m "feat(itil): old fix + changeset"
+  git rm -q .changeset/p888-old.md
+  git commit -q -m "chore: version packages"   # prior release
+
+  # Now add a NEW changeset AFTER the release — genuinely unreleased.
+  mkdir -p .changeset
+  cat > .changeset/p889-fresh.md <<'EOF'
+---
+'@windyroad/itil': patch
+---
+
+Fresh fix, not yet released.
+EOF
+  cat > docs/problems/known-error/889-fresh.md <<'EOF'
+# Problem 889: Fresh
+
+**Status**: Known Error
+
+## Fix Strategy
+
+Ship via `.changeset/p889-fresh.md`.
+EOF
+  git add .
+  git commit -q -m "feat(itil): fresh fix + changeset"
+
+  run "$SCRIPT" P889 docs/problems
+  [ "$status" -eq 3 ]
+  echo "$output" | grep -qi "unreleased"
+}
+
 # ── Exit 0: happy path — full citation emitted ──────────────────────────────
 
 @test "derive-release-vehicle: happy path — full citation block on stdout" {

package/skills/work-problems/SKILL.md

@@ -176,7 +176,7 @@ The helper returns one of five outcomes (contract documented at `packages/itil/l
 | `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.
+**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. **If the pre-flight subprocess exits non-zero OR returns `is_error: true`**, apply the non-blocking revert-and-proceed contract in "Step 0 pre-flight subprocess failure handling (P358)" below — do NOT halt the loop (a failed pre-flight is a non-load-bearing cache-refresh dependency, NOT an iter).
 
 **Iter-summary annotation**:
 
@@ -222,7 +222,7 @@ The helper returns one of five outcomes (contract documented at `packages/itil/l
 
 The intersection is the actual signal: "there is work to do AND the cadence has slipped".
 
-**Pre-flight dispatch shape**: when promoted (`no-readme` or `stale-readme`), dispatch a single `claude -p --permission-mode bypassPermissions --output-format json` subprocess that invokes `/wr-itil:review-problems` (per P084 + ADR-032 subprocess isolation). Reuse the Step 5 subprocess wrapper verbatim — same flag set, same idle-timeout SIGTERM poll loop, same retro-on-exit contract. The subprocess runs the full Step 2 + Step 2.5 + Step 4 + Step 5 re-rate + README refresh + commit; the orchestrator reads the freshly-refreshed README at Step 1.
+**Pre-flight dispatch shape**: when promoted (`no-readme` or `stale-readme`), dispatch a single `claude -p --permission-mode bypassPermissions --output-format json` subprocess that invokes `/wr-itil:review-problems` (per P084 + ADR-032 subprocess isolation). Reuse the Step 5 subprocess wrapper verbatim — same flag set, same idle-timeout SIGTERM poll loop, same retro-on-exit contract. The subprocess runs the full Step 2 + Step 2.5 + Step 4 + Step 5 re-rate + README refresh + commit; the orchestrator reads the freshly-refreshed README at Step 1. **If the pre-flight subprocess exits non-zero OR returns `is_error: true`**, apply the non-blocking revert-and-proceed contract in "Step 0 pre-flight subprocess failure handling (P358)" below — do NOT halt the loop (a failed pre-flight is a non-load-bearing cache-refresh dependency, NOT an iter).
 
 **ADR-079 composition note**: Step 0c dispatches `/wr-itil:review-problems` which includes Step 4.6 relevance-close per ADR-079 — relevance-close fires as a side-effect of the auto-dispatch. This is desirable: relevance closes accumulate the same way deferred placeholders do, and the AND-trigger reasonably gates both pieces of work.
 
@@ -266,7 +266,7 @@ The helper returns one of five outcomes (contract documented at `packages/itil/l
 | `ttl-expiry age=<N>s ttl=<M>s`    | Dispatch `/wr-itil:check-upstream-responses` as a pre-flight iter. Cache stale; the skill polls each back-linked upstream URL, diffs against the cache, and emits STATE / NEW / LABEL / NONE / FAIL per back-link ticket. |
 | `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:check-upstream-responses` (per P084 + ADR-032 subprocess isolation). Reuse the Step 5 subprocess wrapper verbatim — same flag set, same idle-timeout SIGTERM poll loop. The subprocess runs the full check-upstream-responses Step 1 + Step 2 + Step 3 pipeline; the cache file `docs/problems/.outbound-responses-cache.json` + audit-log `docs/audits/outbound-responses-log.md` are refreshed in its own commit per ADR-014 (check-upstream-responses' SKILL.md Step 3 commit grain). After the subprocess completes, the orchestrator proceeds 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:check-upstream-responses` (per P084 + ADR-032 subprocess isolation). Reuse the Step 5 subprocess wrapper verbatim — same flag set, same idle-timeout SIGTERM poll loop. The subprocess runs the full check-upstream-responses Step 1 + Step 2 + Step 3 pipeline; the cache file `docs/problems/.outbound-responses-cache.json` + audit-log `docs/audits/outbound-responses-log.md` are refreshed in its own commit per ADR-014 (check-upstream-responses' SKILL.md Step 3 commit grain). After the subprocess completes, the orchestrator proceeds to Step 1. **If the pre-flight subprocess exits non-zero OR returns `is_error: true`**, apply the non-blocking revert-and-proceed contract in "Step 0 pre-flight subprocess failure handling (P358)" below — do NOT halt the loop (a failed pre-flight is a non-load-bearing cache-refresh dependency, NOT an iter).
 
 **Iter-summary annotation**:
 
@@ -285,7 +285,23 @@ The annotation pre-empts the "surprise heavy iter" perception JTBD-006 expects a
 <!-- @jtbd JTBD-006 (Progress the Backlog While I'm Away — AFK orchestrator pre-flights check-upstream-responses so outbound STATE/NEW deltas surface without manual polling) -->
 <!-- @jtbd JTBD-004 (Connect Agents Across Repos to Collaborate — closes the outbound symmetric feedback loop) -->
 
-After Step 0d completes (whether dispatched or silent-passed), proceed to Step 1.
+After Step 0d completes (whether dispatched or silent-passed), proceed to the shared pre-flight failure-handling contract below, then to Step 1.
+
+### Step 0 pre-flight subprocess failure handling (P358 — non-blocking revert-and-proceed)
+
+Step 0b / Step 0c / Step 0d (and **any future Step 0x pre-flight** that reuses the Step 5 `claude -p` subprocess wrapper) dispatch a `/wr-itil:review-problems` or `/wr-itil:check-upstream-responses` **pre-flight subprocess** "same shape as Step 5". That phrase imports the Step 5 *dispatch mechanism* (the `claude -p --output-format json` wrapper + the idle-timeout SIGTERM poll loop), but the **failure semantics are NOT shared** — and the prior prose left this implicit, which P358 surfaced. Step 5's exit-code semantics HALT the loop on non-zero exit / `is_error: true` because **the iter IS the loop body unit** — its failure is the loop's failure. A **pre-flight is a non-load-bearing cache-refresh dependency**, not an iteration of the loop body: Step 1's backlog scan reads whatever `docs/problems/README.md` already exists (freshly-refreshed or slightly-stale), so a failed pre-flight degrades to "cache not refreshed this pass" — never to "halt the loop".
+
+**Contract — a pre-flight subprocess that exits non-zero OR returns `is_error: true` is NON-BLOCKING** (general rule; every Step 0x pre-flight inherits it):
+
+1. **Revert any dirty working-tree state the failed pre-flight left.** The dispatched skill commits its own refresh per ADR-014 (review-problems' Slice E grain / check-upstream-responses' Step 3 grain) — it commits end-to-end or not at all. A subprocess that died mid-refresh may leave an **UNSTAGED** partial write across any path the dispatched skill is contractually allowed to touch: the staleness cache (`docs/problems/.upstream-cache.json` for 0b, `docs/problems/.outbound-responses-cache.json` for 0d), the audit log (`docs/audits/inbound-discovery-log.md` for 0b, `docs/audits/outbound-responses-log.md` for 0d), AND `docs/problems/README.md` + re-rated ticket bodies (0c). Revert the whole contractually-touchable set — not just the cache JSON — so a half-written README or audit-log is also restored. Revert each path **independently** (`git checkout -- docs/problems/ 2>/dev/null; git checkout -- docs/audits/ 2>/dev/null`) rather than as a combined `git checkout -- docs/problems/ docs/audits/` pathspec: the combined form errors and reverts NOTHING when `docs/audits/` is absent (a fresh adopter repo that has never run inbound/outbound discovery), whereas the per-path form tolerates the missing directory and still reverts the dirty `docs/problems/` write. Do NOT commit a partial write: a half-refreshed cache/README is worse than a stale-but-coherent one. If the dead pre-flight somehow left **STAGED** residue (it should not — the pre-flight owns its commit end-to-end), `git reset` (unstage) it first, then revert, so the orchestrator's own subsequent Step 1+ gate flow is not contaminated by a dead subprocess's index (mirrors the ADR-009 no-trust-window-extension reasoning — a dead `is_error: true` subprocess MUST NOT seed the parent's commit).
+2. **Log a one-line iter-summary annotation** naming the failed pre-flight + the failure class: `Step 0<b|c|d> pre-flight FAILED (<exit-code | is_error class>) — reverted partial cache write, proceeding to Step 1 with existing README`. Preserves the JTBD-006 audit-trail outcome (the silent degradation becomes observable rather than invisible).
+3. **Proceed to Step 1.** The pre-flight failure does NOT halt the loop and does NOT count against the Step 0 prior-session-state Branch 3 detection (step 1 above restored a clean tree, so the iter dispatches that follow start from a clean state).
+
+**`is_error: true` sub-class note (reconciles P358 with the Step 5 taxonomy).** A pre-flight subprocess failure is the SAME `is_error: true` family the Step 5 exit-code semantics taxonomise (P261 SALVAGE / P214 HALT) — **including** the `socket connection was closed unexpectedly` variant (an `is_error: true` shape that routes to the Step 5 catch-all advisory). The load-bearing distinction P358 surfaces is **orthogonal to the SALVAGE-vs-HALT axis**: that axis is scoped to **iters** (the loop body); pre-flights have their own non-blocking failure contract. The Step 5 SALVAGE branch does **NOT** apply to a pre-flight even when the pre-flight left staged work — a pre-flight is not an iteration whose work the orchestrator salvages-and-commits; its job is a cache refresh the dispatched skill owns end-to-end. Pre-flight failure is therefore ALWAYS the revert-and-proceed branch above, never SALVAGE.
+
+**AFK authorisation per ADR-013 Rule 6**: revert-and-proceed is a deterministic, non-interactive recovery — no `AskUserQuestion`. Reverting an unstaged partial write is fully reversible (the next loop pass re-attempts the refresh) and policy-authorised (ADR-019 preflight-reconciliation "leave the tree clean" precedent). Mirrors the P121 SIGTERM Rule-6 posture.
+
+**Compose-with**: ADR-032 § "Pre-flight subprocess failure handling — non-blocking revert-and-proceed (P358 amendment)" (the architectural record + the iter-vs-pre-flight failure-semantics distinction), Step 5 exit-code semantics (the iter-failure HALT contract this is distinguished from), ADR-019 (preflight-reconciliation clean-tree surface), ADR-009 (no-trust-window-extension — the `git reset` of any staged residue), ADR-013 Rule 6 (non-interactive recovery), P358 (driver ticket). This is a fourth symmetric pre-flight surface alongside the three "Staleness contract drift" clauses (lines for Step 0b/0c/0d) — a future Step 0x pre-flight inherits this failure rule by construction; do NOT re-derive a step-specific copy.
 
 ### Step 1: Scan the backlog
 

package/skills/work-problems/test/work-problems-preflight-failure-handling.bats

@@ -0,0 +1,248 @@
+#!/usr/bin/env bats
+# tdd-review: structural-permitted (justification: the doc-lint slice below
+# asserts SKILL.md / ADR-032 prose contract — SKILL.md is the contract
+# document per ADR-037 Permitted Exception; these guards catch prose drift
+# away from the behavioural revert-and-proceed contract exercised above. The
+# load-bearing core of this fixture is behavioural per ADR-052. harness-gap P012)
+#
+# Behavioural test: work-problems Step 0 PRE-FLIGHT subprocess failure handling
+# (P358). Step 0b / 0c / 0d dispatch a /wr-itil:review-problems (or
+# check-upstream-responses) pre-flight subprocess "same shape as Step 5". But a
+# pre-flight is a NON-load-bearing cache-refresh dependency, NOT an iter (the
+# loop body). When a pre-flight subprocess exits non-zero OR returns
+# `is_error: true` (e.g. `API Error: The socket connection was closed
+# unexpectedly`), the orchestrator's contract is NON-BLOCKING:
+#   (1) revert any dirty (unstaged) partial cache/audit/README write the
+#       pre-flight left (`git checkout -- docs/problems/ docs/audits/`);
+#   (1b) if a dead pre-flight left STAGED residue, `git reset` then revert
+#        (ADR-009 no-trust-window-extension — a dead is_error:true subprocess
+#        must not seed the parent's commit);
+#   (2) log a one-line annotation;
+#   (3) proceed to Step 1 with the existing README.
+# This is ORTHOGONAL to the Step 5 iter SALVAGE-vs-HALT axis (P261 / P214):
+# that axis classifies an *iter's* is_error:true; this fixture classifies the
+# *pre-flight role* — which NEVER salvages and NEVER halts the loop.
+#
+# The fake `claude` shim below re-creates the production shape: it dirties an
+# unstaged cache file in the repo, then emits an is_error:true socket-closed
+# JSON envelope (no commit). The harness re-implements the orchestrator's
+# pre-flight failure contract (faithful to SKILL.md § "Step 0 pre-flight
+# subprocess failure handling (P358)") and asserts the revert-and-proceed
+# outcome across the input shapes. Adopters who copy the SKILL.md pre-flight
+# block into their orchestrator should observe the same outcomes.
+#
+# @problem P358
+# @rfc RFC-024
+# @jtbd JTBD-006
+#
+# Cross-reference:
+#   P358 (claude -p subprocess dispatch socket-closed; pre-flight is_error
+#     handling gap) — driver ticket
+#   RFC-024 (work-problems pre-flight subprocess failure handling) — fix vehicle
+#   ADR-032 (governance skill invocation patterns — § "Pre-flight subprocess
+#     failure handling — non-blocking revert-and-proceed (P358 amendment)") —
+#     the iter-vs-pre-flight failure-semantics distinction this fixture pins
+#   ADR-009 (gate-marker / no-trust-window-extension — staged residue git reset)
+#   ADR-019 (preflight clean-tree reconciliation surface)
+#   P261 / P214 (the iter is_error:true SALVAGE/HALT axis this is orthogonal to)
+#   ADR-037 / ADR-052 (skill testing strategy — behavioural default; doc-lint
+#     contract assertion is the Permitted Exception, marked above)
+
+setup() {
+  TEST_TMP="$(mktemp -d)"
+  FAKE_BIN="${TEST_TMP}/bin"
+  mkdir -p "$FAKE_BIN"
+
+  # Fake `claude` binary simulating a pre-flight subprocess of the socket-closed
+  # class: it leaves a dirty (UNSTAGED by default) partial cache write in the
+  # CWD git repo, then emits an is_error:true JSON envelope carrying the
+  # socket-closed error string in `.result`. No commit. This matches the
+  # 2026-06-10 P358 shape: a /wr-itil:review-problems pre-flight that partially
+  # refreshed docs/problems/.upstream-cache.json then died with
+  # `API Error: The socket connection was closed unexpectedly`.
+  cat > "$FAKE_BIN/claude" <<'FAKE_EOF'
+#!/usr/bin/env bash
+# Test fake for work-problems Step 0 pre-flight failure-handling fixture.
+# Dirties a partial cache write, then emits is_error:true socket-closed JSON.
+mkdir -p docs/problems
+printf 'partial-refresh-mid-die\n' >> docs/problems/.upstream-cache.json
+if [ "${FAKE_STAGE_RESIDUE:-0}" = "1" ]; then
+  git add docs/problems/.upstream-cache.json 2>/dev/null || true
+fi
+if [ "${FAKE_EXIT:-0}" != "0" ]; then
+  printf '%s\n' '{"is_error":true,"result":"subprocess crashed"}'
+  exit "${FAKE_EXIT}"
+fi
+printf '%s\n' '{"is_error":true,"result":"API Error: The socket connection was closed unexpectedly. For more information, pass `verbose: true`","total_cost_usd":0.0,"duration_ms":727000}'
+FAKE_EOF
+  chmod +x "$FAKE_BIN/claude"
+  export PATH="$FAKE_BIN:$PATH"
+
+  # A throwaway git repo so dirty-detection + the revert are real. Seed a
+  # committed clean cache so the partial write is observably a dirty delta.
+  REPO="${TEST_TMP}/repo"
+  mkdir -p "$REPO/docs/problems"
+  git -C "$REPO" init -q
+  git -C "$REPO" config user.email "test@example.com"
+  git -C "$REPO" config user.name "Test"
+  printf 'clean-cache\n' > "$REPO/docs/problems/.upstream-cache.json"
+  git -C "$REPO" add docs/problems/.upstream-cache.json
+  git -C "$REPO" commit -q -m "root: clean cache"
+
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+  ADR_FILE="$(cd "${SKILL_DIR}/../../../.." && pwd)/docs/decisions/032-governance-skill-invocation-patterns.proposed.md"
+}
+
+teardown() {
+  if [ -n "${TEST_TMP:-}" ] && [ -d "$TEST_TMP" ]; then
+    rm -rf "$TEST_TMP"
+  fi
+}
+
+# Faithful re-implementation of SKILL.md § "Step 0 pre-flight subprocess failure
+# handling (P358)". Consumes the pre-flight JSON envelope + the pre-flight exit
+# code + the repo working-tree state, applies the non-blocking revert-and-proceed
+# contract, and returns the orchestrator's decision. KEY PROPERTY: a pre-flight
+# NEVER halts the loop and NEVER salvages — it reverts and proceeds.
+preflight_failure_outcome() {
+  local json="$1"
+  local exit_code="$2"
+  local repo="$3"
+
+  local is_error
+  is_error=$(printf '%s' "$json" | python3 -c 'import json,sys; print(str(json.load(sys.stdin).get("is_error")).lower())' 2>/dev/null || echo unknown)
+
+  # Pre-flight succeeded (exit 0 AND is_error:false) → cache refreshed; proceed.
+  if [ "$exit_code" = "0" ] && [ "$is_error" = "false" ]; then
+    printf 'DECISION=PROCEED reason=preflight-ok\n'
+    return 0
+  fi
+
+  # Pre-flight FAILED (non-zero exit OR is_error:true) → NON-BLOCKING contract.
+  # Step 1b: if the dead pre-flight left STAGED residue, unstage it first
+  # (ADR-009 — a dead is_error:true subprocess must not seed the parent index).
+  if [ -n "$(git -C "$repo" diff --cached --name-only)" ]; then
+    git -C "$repo" reset -q
+  fi
+  # Step 1: revert the whole contractually-touchable path set (not just cache).
+  # Per-path tolerant — a COMBINED `git checkout -- A B` errors and reverts
+  # NOTHING when B is absent (e.g. docs/audits/ on a fresh adopter repo), so
+  # revert each path independently.
+  git -C "$repo" checkout -- docs/problems/ 2>/dev/null || true
+  git -C "$repo" checkout -- docs/audits/ 2>/dev/null || true
+  # Step 3: proceed to Step 1 (never halt).
+  printf 'DECISION=PROCEED reason=preflight-failed-reverted\n'
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Behavioural cases (the load-bearing core per ADR-052).
+# ---------------------------------------------------------------------------
+
+@test "P358: pre-flight is_error:true (socket-closed) + unstaged partial write -> revert + PROCEED (never halt)" {
+  export FAKE_STAGE_RESIDUE=0 FAKE_EXIT=0
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "PREFLIGHT" < /dev/null )
+  # The fake left a dirty partial cache write.
+  run git -C "$REPO" status --porcelain docs/problems/.upstream-cache.json
+  [ -n "$output" ]
+  run preflight_failure_outcome "$json" 0 "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=PROCEED"* ]]
+  [[ "$output" == *"preflight-failed-reverted"* ]]
+  # The dirty partial write was reverted — tree is clean again.
+  run git -C "$REPO" status --porcelain
+  [ -z "$output" ]
+  # The committed clean cache content survived (revert restored it).
+  run cat "$REPO/docs/problems/.upstream-cache.json"
+  [[ "$output" == "clean-cache" ]]
+}
+
+@test "P358: pre-flight non-zero exit -> revert + PROCEED (non-blocking; not a loop halt)" {
+  export FAKE_STAGE_RESIDUE=0 FAKE_EXIT=1
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "PREFLIGHT" < /dev/null || true )
+  run preflight_failure_outcome "$json" 1 "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=PROCEED"* ]]
+  # Crucially NOT a HALT — a pre-flight failure does not stop the loop.
+  [[ "$output" != *"HALT"* ]]
+  run git -C "$REPO" status --porcelain
+  [ -z "$output" ]
+}
+
+@test "P358: pre-flight left STAGED residue -> git reset then revert (ADR-009 no-seed-parent-index)" {
+  export FAKE_STAGE_RESIDUE=1 FAKE_EXIT=0
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "PREFLIGHT" < /dev/null )
+  # The fake STAGED the partial write.
+  run git -C "$REPO" diff --cached --name-only
+  [[ "$output" == *".upstream-cache.json"* ]]
+  run preflight_failure_outcome "$json" 0 "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=PROCEED"* ]]
+  # Staged residue was unstaged AND reverted — index + tree both clean.
+  run git -C "$REPO" diff --cached --name-only
+  [ -z "$output" ]
+  run git -C "$REPO" status --porcelain
+  [ -z "$output" ]
+}
+
+@test "P358: pre-flight success (exit 0 + is_error:false) -> PROCEED without revert" {
+  # Hand-build a clean success envelope (the fake always fails by design).
+  local json='{"is_error":false,"result":"refreshed"}'
+  run preflight_failure_outcome "$json" 0 "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=PROCEED"* ]]
+  [[ "$output" == *"preflight-ok"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Doc-lint contract assertions (Permitted Exception per ADR-037; structural
+# slice marked at top of file per ADR-052 Surface 2). These guard the SKILL.md
+# / ADR-032 prose against drift away from the behavioural contract above.
+# ---------------------------------------------------------------------------
+
+@test "P358: SKILL.md documents the Step 0 pre-flight failure-handling subsection" {
+  run grep -niE "pre-flight subprocess failure handling.{0,40}P358|Step 0 pre-flight subprocess failure" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P358: SKILL.md pre-flight contract names the non-blocking revert-and-proceed rule" {
+  run grep -niE "non-?blocking" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "revert.{0,40}(proceed|partial)|proceed to Step 1 with the existing" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P358: SKILL.md distinguishes pre-flight (cache-refresh dependency) from iter (loop body)" {
+  run grep -niE "non-load-bearing cache-refresh dependency" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "iter IS the loop body|the iter is the loop body" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P358: SKILL.md pre-flight forward-pointer fires in the 0b/0c/0d dispatch paragraphs" {
+  # At least three "do NOT halt the loop (a failed pre-flight ...)" pointers.
+  run bash -c "grep -ciE 'do NOT halt the loop .a failed pre-flight' '$SKILL_FILE'"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 3 ]
+}
+
+@test "P358: SKILL.md pre-flight contract cites P358" {
+  run grep -nE "P358" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P358: ADR-032 carries the pre-flight failure-handling P358 amendment" {
+  run grep -niE "Pre-flight subprocess failure handling.{0,60}P358 amendment" "$ADR_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P358: ADR-032 amendment names the iter-vs-pre-flight failure-semantics axis as orthogonal to SALVAGE/HALT" {
+  run grep -niE "orthogonal" "$ADR_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "No SALVAGE for a pre-flight|SALVAGE branch does NOT apply to a pre-flight" "$ADR_FILE"
+  [ "$status" -eq 0 ]
+}