@windyroad/itil 0.55.5 → 0.56.0-preview.877

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.55.5"
+  "version": "0.56.0"
 }

package/bin/wr-itil-check-rfc-has-stories

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/check-rfc-has-stories.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/check-rfc-has-stories.sh" "$@"

package/package.json

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

package/scripts/check-rfc-has-stories.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# check-rfc-has-stories.sh — ADR-089 (every RFC has at least one story).
+#
+# The load-bearing detection half of the manage-rfc `proposed -> accepted` gate:
+# an RFC must list >=1 story before it can be accepted. Exits non-zero (with a
+# stderr directive) when the RFC's `stories:` frontmatter is empty (`stories: []`)
+# or missing; exits 0 when >=1 `STORY-NNN` is listed (inline or block-list).
+#
+# This removes the pre-ADR-089 empty-stories fallback (the "atomic RFC ships with
+# stories: [] / JTBD-101 friction guard" shape). An atomic fix is now an RFC with
+# exactly one full story, never an empty list.
+#
+# Usage: check-rfc-has-stories.sh <rfc-file>
+# Exit:  0 = >=1 story; 1 = empty/missing stories; 2 = usage / file error.
+#
+# Authority: ADR-089. Driver: P404. Behavioural test: check-rfc-has-stories.bats.
+set -euo pipefail
+
+rfc="${1:-}"
+if [ -z "$rfc" ]; then
+  echo "check-rfc-has-stories: usage: check-rfc-has-stories.sh <rfc-file>" >&2
+  exit 2
+fi
+if [ ! -f "$rfc" ]; then
+  echo "check-rfc-has-stories: file not found: $rfc" >&2
+  exit 2
+fi
+
+# The frontmatter `stories:` line (first match; frontmatter is at the top).
+stories_line="$(awk '/^stories:/{print; exit}' "$rfc")"
+
+if [ -z "$stories_line" ]; then
+  echo "check-rfc-has-stories: $rfc has no 'stories:' field — an RFC must list >=1 story (ADR-089). Decompose the fix into >=1 story before accepting." >&2
+  exit 1
+fi
+
+# Reject an explicit empty inline list: `stories: []`.
+if printf '%s' "$stories_line" | grep -qE '^stories:[[:space:]]*\[[[:space:]]*\][[:space:]]*$'; then
+  echo "check-rfc-has-stories: $rfc has empty 'stories: []' — an RFC must list >=1 story (ADR-089; the empty-stories fallback is removed). An atomic fix is an RFC with exactly one full story." >&2
+  exit 1
+fi
+
+# Accept if a STORY-id appears inline on the stories: line.
+if printf '%s' "$stories_line" | grep -qE 'STORY-[0-9]'; then
+  exit 0
+fi
+
+# Accept if a YAML block-list under stories: carries >=1 STORY-id.
+if awk '
+  /^stories:/ { inblock=1; next }
+  inblock && /^[[:space:]]*-[[:space:]]*STORY-[0-9]/ { found=1 }
+  inblock && /^[^[:space:]-]/ { exit }
+  END { exit !found }
+' "$rfc"; then
+  exit 0
+fi
+
+echo "check-rfc-has-stories: $rfc 'stories:' lists no STORY- ids — an RFC must list >=1 story (ADR-089)." >&2
+exit 1

package/scripts/test/check-rfc-has-stories.bats

@@ -0,0 +1,69 @@
+#!/usr/bin/env bats
+# Behavioural test for check-rfc-has-stories.sh (ADR-089 — every RFC has >=1 story).
+# The predicate exits non-zero when an RFC's `stories:` frontmatter is empty or
+# missing (the empty-stories fallback ADR-089 removes); exit 0 when >=1 story is
+# listed. This is the load-bearing detection half of the proposed->accepted gate.
+#
+# @adr ADR-089 (every RFC has at least one story)
+# @problem P404 (implement ADR-089 + ADR-090)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="${REPO_ROOT}/packages/itil/scripts/check-rfc-has-stories.sh"
+  TMPD="$(mktemp -d)"
+}
+teardown() { rm -rf "$TMPD"; }
+
+@test "check-rfc-has-stories: empty stories: [] is REJECTED (exit non-zero + directive)" {
+  cat > "$TMPD/RFC-901-empty.proposed.md" <<'EOF'
+---
+status: proposed
+problems: [P170]
+stories: []
+---
+# RFC-901: empty
+EOF
+  run bash "$SCRIPT" "$TMPD/RFC-901-empty.proposed.md"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"stories"* ]]
+}
+
+@test "check-rfc-has-stories: missing stories: field is REJECTED" {
+  cat > "$TMPD/RFC-902-none.proposed.md" <<'EOF'
+---
+status: proposed
+problems: [P170]
+---
+# RFC-902: no stories field
+EOF
+  run bash "$SCRIPT" "$TMPD/RFC-902-none.proposed.md"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"stories"* ]]
+}
+
+@test "check-rfc-has-stories: inline >=1 story is ACCEPTED (exit 0)" {
+  cat > "$TMPD/RFC-903-ok.proposed.md" <<'EOF'
+---
+status: proposed
+problems: [P170]
+stories: [STORY-020, STORY-021]
+---
+# RFC-903: has stories
+EOF
+  run bash "$SCRIPT" "$TMPD/RFC-903-ok.proposed.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "check-rfc-has-stories: block-list >=1 story is ACCEPTED (exit 0)" {
+  cat > "$TMPD/RFC-904-block.proposed.md" <<'EOF'
+---
+status: proposed
+problems: [P170]
+stories:
+  - STORY-020
+---
+# RFC-904: block-list stories
+EOF
+  run bash "$SCRIPT" "$TMPD/RFC-904-block.proposed.md"
+  [ "$status" -eq 0 ]
+}

package/scripts/test/rfc-stories-extension.bats

@@ -124,13 +124,15 @@ EOF
 }
 
 # ---------------------------------------------------------------------------
-# Surface 2b: helper applies lazy-empty discipline (empty stories: [])
+# Surface 2b: renderer tolerates empty stories: [] on a DRAFT RFC
 # ---------------------------------------------------------------------------
 
-@test "rfc-stories-extension: helper does not reject empty stories: [] (atomic-RFC JTBD-101 friction guard)" {
-  # Atomic RFC ships with stories: []; the helper must not reject this
-  # shape (it represents a legitimate atomic-fix-adopter RFC per
-  # ADR-060 line 262 JTBD-101 friction guard).
+@test "rfc-stories-extension: renderer tolerates empty stories: [] on a draft RFC (ADR-089: enforced >=1 at accept, not at render)" {
+  # Per ADR-089 every RFC has >=1 story, but empty stories: [] is a legal
+  # TRANSIENT state on a draft/proposed RFC before the fix is scoped. The
+  # renderer must not reject it (that would block drafting); the >=1-story
+  # requirement is enforced at the manage-rfc accept gate by the
+  # check-rfc-has-stories predicate, not by this renderer.
   cat > docs/rfcs/RFC-002-atomic.proposed.md <<'EOF'
 ---
 status: proposed

package/scripts/test/working-the-problem-traversal.bats

@@ -56,12 +56,19 @@ setup() {
 }
 
 # ---------------------------------------------------------------------------
-# Surface 2: manage-problem names BOTH fallback paths
+# Surface 2: manage-problem — empty stories: [] is a legacy/back-fill state,
+# NOT a legitimate atomic fallback (ADR-089: every RFC has >=1 story). The old
+# JTBD-101-friction-guard atomic-RFC-empty-stories fallback is removed; the
+# legacy no-RFC direct-implementation fallback (a distinct path) stays.
 # ---------------------------------------------------------------------------
 
-@test "traversal: manage-problem names the atomic-RFC empty stories: [] fallback (JTBD-101 friction guard)" {
-  run grep -E 'atomic-RFC fallback|atomic RFC.*JTBD-101.*friction guard|stories: \[\].*atomic' "$MANAGE_PROBLEM"
+@test "traversal: manage-problem treats empty stories: [] as legacy/back-fill, not a legitimate atomic fallback (ADR-089)" {
+  # Positive: the ADR-089 model (>=1 story; back-fill the legacy empty-stories RFC) is named.
+  run grep -iE 'ADR-089|back-fill' "$MANAGE_PROBLEM"
   [ "$status" -eq 0 ]
+  # Negative: the old atomic-RFC empty-stories fallback legitimation is gone.
+  run grep -iE 'atomic-RFC fallback|atomic RFC.*JTBD-101.*friction guard' "$MANAGE_PROBLEM"
+  [ "$status" -ne 0 ]
 }
 
 @test "traversal: manage-problem names the legacy no-RFC direct-implementation fallback" {
@@ -89,7 +96,7 @@ setup() {
   [ "$status" -eq 0 ]
 }
 
-@test "traversal: manage-problem names Refs: RFC-NNN trailer for atomic-RFC fallback" {
+@test "traversal: manage-problem names Refs: RFC-NNN trailer for cross-cutting RFC work (no single story)" {
   run grep -E 'Refs: RFC-' "$MANAGE_PROBLEM"
   [ "$status" -eq 0 ]
 }

package/skills/manage-problem/SKILL.md

@@ -200,15 +200,15 @@ The Phase 2 working-the-problem traversal makes "implement the fix" concretely t
 1. **Read the problem's `## Fix Strategy` section** — extract referenced RFC IDs (anchor links / inline references like `RFC-NNN`). The I13 gate above has already guaranteed an RFC traces the problem; if the `## Fix Strategy` prose itself references none (a freshly auto-created RFC may not yet be cited inline), fall through to the legacy direct-implementation path (step 6 below) using the traced/auto-created RFC.
 2. **For each referenced RFC** (in the order they appear in the Fix Strategy section), read its frontmatter `stories:` array (per ADR-060 line 259, the array is ORDERED — array position IS execution sequence):
    - **Non-empty `stories:` array** (story-decomposed RFC): pick the first story whose lifecycle status is `accepted` or `in-progress` — skip `done` stories that already shipped, skip `draft` stories that aren't ready (the `manage-story <NNN> accepted` gate enforces INVEST shape; a draft story is structurally unready). Continue to step 3.
-   - **Empty `stories: []`** (atomic RFC per JTBD-101 friction guard, ADR-060 line 262): fall back to Phase 1 per-RFC iter dispatch — read the RFC body's `## Tasks` section directly; pick the first unticked task; no per-story scoping needed. Skip to step 5 (commit + trailer).
+   - **Empty `stories: []`** (a **legacy** pre-ADR-089 RFC, or one not yet decomposed): per **ADR-089** every RFC has ≥1 story — an empty `stories:` is a **back-fill** state, NOT a legitimate atomic shape. Back-fill the fix's story onto the RFC's story map (add ≥1 story, transition it `accepted` via `manage-story`), then re-traverse from step 2. The empty-stories atomic fallback is removed — do NOT close the problem on a story-less RFC.
 3. **Read the picked story's body** — `## User value` statement (INVEST Valuable), `## Acceptance criteria` (INVEST Testable observable behaviours), `## Implementation notes` (architecture sketches, library decisions). The story's frontmatter `estimated-effort` field (set at `manage-story accepted` transition per I10 INVEST Estimable) sets the appetite for the iteration.
 4. **Implement the story scope** — follow the project's standard development workflow (plan if needed, architect/JTBD review, behavioural tests per ADR-052, single-commit grain per ADR-014). Confine the implementation to the picked story's acceptance criteria; deviating into adjacent unscoped work is a scope-expansion signal — surface it via the `## Scope expansion` AskUserQuestion below.
 5. **Commit with the `Refs: STORY-<NNN>` trailer** (single-trailer vocabulary per ADR-060 line 307 + amendment 2026-05-10 nitpick N2 — same trailer verb whether the commit is the story's first implementation commit or a continuation). On the FIRST commit AFTER the capture commit (subject prefix discriminates: `feat(itil): capture STORY-NNN ...` is the capture; any other subject prefix is an implementation commit), `/wr-itil:manage-story` auto-transitions the story `draft → in-progress`. As acceptance criteria checkboxes are ticked across multiple commits, the same trailer continues to attribute the work.
 6. **Story `done` auto-transition**: when ALL acceptance-criteria checkboxes in the story body are ticked AND the linked RFC reaches `closed`, `/wr-itil:manage-story` auto-transitions the story `in-progress → done`. (When a story's RFC is still `in-progress` but the acceptance criteria are all ticked, the story stays at `in-progress` until the RFC closes — this preserves the trace coupling per ADR-060 line 309.)
-7. **Pick the next not-done story** from the RFC's `stories:` array (or the next unticked task from the RFC body for the atomic-RFC fallback path). Repeat from step 3.
+7. **Pick the next not-done story** from the RFC's `stories:` array. Repeat from step 3.
 8. **When all stories under all referenced RFCs are done** — the problem is fix-released. Include the problem doc closure in the final commit (`git mv` to `.verifying.md`, update Status) per ADR-022. Push, create changeset, release per the lean release principle.
 
-**Atomic-RFC fallback path** (step 2 empty-stories case, in detail): a Phase 1-shape problem whose Fix Strategy references RFCs that have not been decomposed into stories continues to work via the existing per-RFC iter dispatch — read the RFC body's tasks/steps section, implement each task as a single-commit per ADR-014, attribute via `Refs: RFC-<NNN>` trailer (still single-trailer vocabulary). This preserves Phase 1 atomic-fix-adopter behaviour: an adopter who hasn't adopted Phase 2 story tooling has zero new friction; their RFCs continue to ship with `stories: []` and their problems continue to close via per-RFC iter dispatch.
+**Legacy empty-stories back-fill (per ADR-089)**: a pre-ADR-089 RFC whose `stories:` is empty is a **back-fill** case, not an atomic fallback — ADR-089 requires ≥1 story, so the empty-stories atomic dispatch is removed. Decompose the fix into ≥1 story on the RFC's story map (add the story, transition it `accepted`), then traverse it via the normal story path above. The `Refs: RFC-<NNN>` trailer remains valid for **cross-cutting RFC work with no single story** (e.g. an RFC-level enforcement change spanning several files); it is no longer an atomic-empty-stories fallback. Legacy on-disk RFCs still carrying `stories: []` are surfaced for back-fill by `wr-itil-check-rfc-has-stories` at their next `manage-rfc accepted` transition.
 
 **Legacy direct-implementation path** (step 1 no-RFCs case): a Phase 1-shape Known Error whose Fix Strategy references no RFCs continues to work via the pre-Phase-2 flow — read the root cause analysis and fix strategy, implement the fix following the project's development workflow, include the problem doc closure in the fix commit (`git mv` to `.verifying.md`, update Status), push + changeset + release. This preserves backwards compatibility with all existing Known Error problems (which were captured before the RFC framework was Phase-1-graduated).
 

package/skills/manage-rfc/SKILL.md

@@ -118,7 +118,7 @@ Each transition is a `git mv` + Edit + `git add` (P057 staging trap) + README re
 
 | Transition | Checks |
 |------------|--------|
-| `proposed → accepted` | All `problems:` entries resolve. Architect re-review PASS. JTBD re-review PASS. `## Scope` populated (not "deferred"). `## Tasks` decomposed (≥ 1 task; not just deferred placeholder). |
+| `proposed → accepted` | All `problems:` entries resolve. Architect re-review PASS. JTBD re-review PASS. `## Scope` populated (not "deferred"). `## Tasks` decomposed (≥ 1 task; not just deferred placeholder). **`stories:` non-empty — run `wr-itil-check-rfc-has-stories <rfc-file>`; hard-block on non-zero exit (empty `stories: []` or missing).** Per **ADR-089** the empty-stories fallback is removed: an atomic fix is an RFC with exactly one full story; an empty `stories:` is permitted only on a `proposed`/draft RFC before the fix is scoped, never at `accepted`. |
 | `accepted → in-progress` | First commit referencing `Refs: RFC-<NNN>` exists OR is being authored in this same commit. I1 hard-block on missing/orphan trace. |
 | `in-progress → verifying` | All `## Tasks` checked. `## Verification` section drafted (release marker, user-side check, trace closure path). I1 hard-block on missing/orphan trace. |
 | `verifying → closed` | User explicitly confirms (or AFK Rule 6 fallback for evidence-based close per ADR-022 / ADR-044 framework-resolved silent dispatch). I1 advisory-with-escalation if driving problems Closed/Parked. |

package/skills/work-problem/SKILL.md

@@ -81,7 +81,7 @@ When a single ticket is the strict top, rungs 2-5 are not consulted. When multip
 Invoke `/wr-itil:manage-problem <NNN>` via the Skill tool with the selected ticket's ID as the argument. The delegated skill runs the full Working a Problem flow appropriate to the ticket's status:
 
 - **Open ticket**: investigate root cause; document findings; create reproduction test; identify workaround; auto-transition to Known Error when root cause + workaround are documented; if the fix is small, proceed straight into implementation.
-- **Known Error**: traverse problem `## Fix Strategy` → referenced RFCs → each RFC's frontmatter `stories:` array (ordered per ADR-060 line 259) → pick first not-done story (status `accepted` or `in-progress`, skipping `done` and `draft`) → implement the picked story scope. Empty `stories: []` (atomic RFC, JTBD-101 friction guard) falls back to per-RFC iter dispatch on the RFC body's tasks. No-RFC Fix Strategy (Phase 1-shape legacy problems) falls back to direct fix implementation. Each commit carries `Refs: STORY-<NNN>` (or `Refs: RFC-<NNN>` for atomic-RFC fallback / `Refs: P<NNN>` for legacy direct path). Stories auto-transition `draft → in-progress` on first non-capture commit; auto-transition `in-progress → done` on all-criteria-ticked + linked RFC closed. When all stories under all referenced RFCs are done, include the Known Error → Verification Pending `git mv` in the final commit per ADR-022. The full traversal contract lives in `/wr-itil:manage-problem` § Working a Problem → Known Error subsection (post-Phase-2 rewrite per ADR-060 lines 300-320).
+- **Known Error**: traverse problem `## Fix Strategy` → referenced RFCs → each RFC's frontmatter `stories:` array (ordered per ADR-060 line 259) → pick first not-done story (status `accepted` or `in-progress`, skipping `done` and `draft`) → implement the picked story scope. An empty `stories: []` is a legacy/back-fill state (per **ADR-089** every RFC has ≥1 story — the empty-stories atomic fallback is removed): back-fill a story onto the RFC, don't fall back to a per-RFC atomic dispatch. No-RFC Fix Strategy (Phase 1-shape legacy problems) falls back to direct fix implementation. Each commit carries `Refs: STORY-<NNN>` (or `Refs: RFC-<NNN>` for cross-cutting RFC work with no single story / `Refs: P<NNN>` for legacy direct path). Stories auto-transition `draft → in-progress` on first non-capture commit; auto-transition `in-progress → done` on all-criteria-ticked + linked RFC closed. When all stories under all referenced RFCs are done, include the Known Error → Verification Pending `git mv` in the final commit per ADR-022. The full traversal contract lives in `/wr-itil:manage-problem` § Working a Problem → Known Error subsection (post-Phase-2 rewrite per ADR-060 lines 300-320).
 
 **Why delegate rather than re-implement:** the full investigation / transition / fix / release pipeline is a long-lived, policy-governed flow that must stay on a single authoritative workflow. Re-hosting it on a sibling skill would fork the ownership contract and compound maintenance cost. The split skill (this file) owns the *selection* of the next ticket; `/wr-itil:manage-problem <NNN>` owns the *execution*.