@windyroad/itil 0.27.1 → 0.28.0-preview.304

package/skills/list-stories/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: wr-itil:list-stories
+description: List INVEST-shaped story tickets from docs/stories/ as a markdown table. Read-only display — no edits, no interaction. Optional `--rfc RFC-<NNN>` filter to surface a specific RFC's ordered story list per ADR-060 Phase 2.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+# List Stories
+
+Display the story corpus from `docs/stories/` as a markdown table. Read-only view of the story tier per ADR-060 Phase 2; this skill does not edit, transition, close, or create stories. For those operations, use the dedicated skills (`/wr-itil:capture-story`, `/wr-itil:manage-story`).
+
+Mirrors the `/wr-itil:list-problems` precedent (P071 phased-landing split per ADR-010 amended Skill Granularity rule: one skill per distinct user intent). The list-stories surface separates the read-only view from the heavyweight `/wr-itil:manage-story list` subcommand route (which is itself a candidate for phased-landing split in a future slice).
+
+## Scope
+
+Stories live under `docs/stories/<state>/STORY-<NNN>-<slug>.md` in lifecycle subdirectories:
+
+- `docs/stories/draft/*.md` — draft (captured via `/wr-itil:capture-story`; pre-INVEST-acceptance)
+- `docs/stories/accepted/*.md` — accepted (INVEST-shape verified per I10; pre-implementation)
+- `docs/stories/in-progress/*.md` — in-progress (implementation underway; auto-transitioned from accepted on first `Refs: STORY-<NNN>` commit AFTER the capture commit per ADR-060 line 292)
+- `docs/stories/done/*.md` — done (acceptance-criteria all-ticked + linked RFC closes; auto-transitioned from in-progress)
+- `docs/stories/archived/*.md` — archived (closed without completion; manual transition)
+
+Per ADR-060 I11 invariant (Phase 2 deferred): stories MUST NOT carry a WSJF field. Ordering inside an RFC is per the RFC's frontmatter `stories: [STORY-<NNN>, ...]` array (ordered = execution sequence per ADR-060 line 259), NOT per any per-story WSJF.
+
+## Argument grammar
+
+**Positional (optional)**: `--rfc RFC-<NNN>` flag-style filter. When provided, the display lists ONLY stories that trace to the named RFC, IN THE ORDER specified by the RFC's frontmatter `stories:` array per ADR-060 line 259. Without the flag, all stories across all lifecycle states are listed grouped by state.
+
+```
+/wr-itil:list-stories                    # All stories, grouped by lifecycle state
+/wr-itil:list-stories --rfc RFC-002      # Only stories under RFC-002, in execution order
+```
+
+## Steps
+
+### 1. Check `docs/stories/README.md` cache freshness
+
+Reuse the same `git log`-based freshness test as `/wr-itil:list-problems` Step 1 (per P031 — filesystem mtime is unreliable in worktrees and fresh checkouts):
+
+```bash
+readme_commit=$(git log -1 --format=%H -- docs/stories/README.md 2>/dev/null)
+if [ -z "$readme_commit" ] || \
+   git log --oneline "${readme_commit}..HEAD" -- 'docs/stories/*/*.md' ':!docs/stories/README.md' 2>/dev/null | grep -q .; then
+  echo "stale"
+fi
+```
+
+**Cache fresh** (no output AND no `--rfc` filter): read `docs/stories/README.md` directly — display the Story Rankings section + Done section as-is. Note in the output: "Using cached ranking from [timestamp in README.md]".
+
+**Cache stale OR `--rfc` filter provided OR `README.md` missing**: run the live scan in Step 2. (The filter case always live-scans because the README cache is whole-corpus ranking, not a per-RFC filtered view.)
+
+### 2. Live scan (cache-stale fallback OR filter mode)
+
+**Unfiltered live scan** — enumerate every state directory:
+
+```bash
+ls docs/stories/draft/*.md docs/stories/accepted/*.md docs/stories/in-progress/*.md docs/stories/done/*.md docs/stories/archived/*.md 2>/dev/null
+```
+
+For each story file, parse the YAML frontmatter to extract: `story-id`, `status`, `problems`, `jtbd`, `rfcs`, `story-maps`, `estimated-effort`. Read the H1 line for the title.
+
+**Filtered live scan** (`--rfc RFC-<NNN>` provided) — resolve the RFC file first, then enumerate its ordered `stories:` array:
+
+```bash
+rfc_file=$(ls docs/rfcs/RFC-<NNN>-*.md 2>/dev/null | head -1)
+[ -z "$rfc_file" ] && echo "RFC-<NNN> not found" >&2 && exit 1
+
+# Extract the ordered stories: array from RFC frontmatter
+# (Phase 2 Slice 11 extension — see ADR-060 RFC frontmatter extension)
+stories_list=$(awk '/^stories:/,/^[a-z]/' "$rfc_file" | grep -oE 'STORY-[0-9]+')
+```
+
+For each `STORY-<NNN>` in the ordered list, resolve to a file under `docs/stories/*/STORY-<NNN>-*.md` and parse the frontmatter as above. Preserve the RFC's array ordering in the output.
+
+### 3. Display
+
+**Unfiltered mode** — render lifecycle-grouped sections:
+
+```markdown
+## Draft
+
+| ID | Title | Problems | JTBD | RFCs | Story Maps |
+|----|-------|----------|------|------|------------|
+| STORY-<NNN> | <title> | <P<NNN>...> | <JTBD-<NNN>...> | <RFC-<NNN>...> | <STORY-MAP-<NNN>...> |
+
+## Accepted
+
+| ID | Title | Problems | JTBD | RFCs | Story Maps | Effort |
+|----|-------|----------|------|------|------------|--------|
+...
+
+## In Progress
+
+(same shape as Accepted)
+
+## Done
+
+| ID | Title | Done date | Driving problems |
+|----|-------|-----------|------------------|
+...
+```
+
+Omit empty sections rather than rendering empty headers. The Estimated Effort column is omitted from the Draft section because effort is deferred at capture and only required at accepted per I10 INVEST Estimable.
+
+**Filtered mode** (`--rfc RFC-<NNN>`) — render a single ordered table:
+
+```markdown
+## Stories under RFC-<NNN>
+
+(In execution order per RFC frontmatter `stories:` array.)
+
+| Order | ID | Title | Status | Effort |
+|-------|----|-------|--------|--------|
+| 1 | STORY-<NNN> | <title> | <status> | <effort> |
+| 2 | STORY-<NNN> | <title> | <status> | <effort> |
+...
+```
+
+The Order column makes the execution sequence visible — critical for the working-the-problem flow per ADR-060 line 314 ("read frontmatter `stories:` array (ordered) → pick first not-done story").
+
+### 4. Trailing suggestions
+
+After the table(s), print one short pointer depending on output:
+
+- **Filtered mode + first not-done story exists**: `Run /wr-itil:work-problem to advance the next story under RFC-<NNN> (STORY-<NNN> — <title>).` (Note: working-the-problem traversal per ADR-060 line 300-320 lands in Slice 13.)
+- **Filtered mode + all stories done**: `All stories under RFC-<NNN> are done. Run /wr-itil:manage-rfc <RFC-<NNN>> verifying to transition the RFC.`
+- **Unfiltered mode + Draft section non-empty**: `Run /wr-itil:manage-story <STORY-<NNN>> accepted to advance a draft through INVEST gates.`
+- **Unfiltered mode + only Done section non-empty**: `No active stories. Run /wr-itil:capture-story to draft a new story.`
+
+## Ownership boundary
+
+`list-stories` does not modify, rename, or commit any files. If the README.md cache is stale, list-stories performs a live scan but does NOT rewrite `docs/stories/README.md` — refreshing the cache is `/wr-itil:manage-story review`'s ownership (Slice 8 lands the review surface). The trailing-suggestion pointer surfaces this boundary.
+
+## Related
+
+- **ADR-060** — Problem-RFC-Story framework + Phase 2 amendment 2026-05-12 (story tier).
+- **ADR-060 line 259** — RFC frontmatter `stories:` ORDERED array (execution sequence).
+- **ADR-060 line 294** — `/wr-itil:list-stories` skill description with `--rfc RFC-<NNN>` filter.
+- **ADR-060 lines 300-320** — working-the-problem flow (Slice 13 lands the traversal).
+- **ADR-060 line 253** — I11 no-WSJF-leak invariant (Phase 2).
+- **P071** — phased-landing split precedent (list-problems split from manage-problem list).
+- **ADR-010 amended** — Skill Granularity rule.
+- **ADR-022** — lifecycle conventions (story lifecycle mirrors problem lifecycle).
+- **ADR-037** — contract-assertion bats pattern.
+- **P031** — git-history freshness check rationale.
+- **JTBD-008** — Decompose a Fix Into Coordinated Changes. The list view supports the working-the-problem flow that operationalises JTBD-008's "first-class entity" Desired Outcome.
+- **JTBD-006** — Progress the Backlog While I'm Away. Filtered mode (`--rfc`) feeds the AFK orchestrator's per-RFC iter dispatch (Slice 13).
+- `packages/itil/skills/list-problems/SKILL.md` — direct precedent shape.
+- `packages/itil/skills/list-incidents/SKILL.md` — sibling list-* skill at the incident tier.
+
+$ARGUMENTS

package/skills/list-stories/test/list-stories-contract.bats

@@ -0,0 +1,127 @@
+#!/usr/bin/env bats
+# Behavioural contract fixtures for /wr-itil:list-stories (P170 Phase 2 Slice 10).
+#
+# Per ADR-037 + ADR-052: behavioural tests over structural prose-grep.
+# These tests exercise the read-only display surface contract — read
+# story files, render markdown tables, no edits.
+#
+# Behavioural surfaces under test:
+#   1. SKILL.md presence + canonical name (minimum discoverability).
+#   2. Read-only contract — no Write/Edit tools in frontmatter.
+#   3. Lifecycle enumeration — list-stories enumerates all five state
+#      subdirectories (draft / accepted / in-progress / done / archived).
+#   4. RFC-filter ordering — when --rfc filter is provided, ordering
+#      follows the RFC frontmatter `stories:` array, not lexical /
+#      filesystem order.
+#
+# @problem P170
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes — list view
+#                  supports the working-the-problem flow's per-RFC iter
+#                  dispatch in Slice 13)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — filtered mode
+#                  feeds the AFK orchestrator)
+# @adr  ADR-060  (Problem-RFC-Story framework — story tier line 294
+#                  list-stories description)
+# @adr  ADR-037  (Skill testing strategy — contract bats)
+# @adr  ADR-052  (Behavioural-tests-default)
+# @adr  ADR-010  (Amended skill granularity — phased-landing split
+#                  precedent from list-problems / P071)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/list-stories/SKILL.md"
+
+  TMPROOT=$(mktemp -d)
+  ORIG_DIR="$PWD"
+  cd "$TMPROOT"
+  # Set up minimal story corpus fixture
+  mkdir -p docs/stories/draft docs/stories/accepted docs/stories/in-progress docs/stories/done docs/stories/archived
+  mkdir -p docs/rfcs
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TMPROOT"
+}
+
+# ---------------------------------------------------------------------------
+# Surface 0: SKILL.md exists with correct name (minimum discoverability)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "list-stories: SKILL.md frontmatter declares wr-itil:list-stories name" {
+  run grep -E '^name: wr-itil:list-stories$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 1: Read-only contract — no Write/Edit in allowed-tools
+# (ADR-010 phased-landing split rule: list-* skills are pure read views)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: SKILL.md allowed-tools does NOT include Write or Edit" {
+  # Behavioural: extract the allowed-tools line and check it omits the
+  # write tools. The list-* family is read-only by contract per ADR-010.
+  run grep '^allowed-tools:' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"Write"* ]]
+  [[ "$output" != *"Edit"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2: Lifecycle enumeration — all 5 state subdirectories
+# (story lifecycle per ADR-060 mirrors problem lifecycle ADR-022)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: SKILL.md names all 5 lifecycle state subdirectories" {
+  # The Scope section enumerates the lifecycle states. Without all five,
+  # the list view would miss stories in some lifecycle state silently —
+  # a behavioural defect not a prose preference.
+  for state in draft accepted in-progress done archived; do
+    run grep -E "docs/stories/${state}" "$SKILL_FILE"
+    [ "$status" -eq 0 ]
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Surface 3: --rfc filter ordering follows RFC frontmatter `stories:` array
+# (load-bearing for the working-the-problem flow per ADR-060 line 314)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: --rfc filter mode enumerates stories via RFC frontmatter stories array" {
+  # The SKILL.md filter-mode pseudocode reads the RFC's frontmatter and
+  # extracts STORY-NNN tokens in order. This is the load-bearing
+  # behaviour for Slice 13's working-the-problem traversal — verify
+  # the SKILL prescribes RFC-frontmatter-driven order, not filesystem
+  # / lexical order.
+  run grep -E 'stories_list.*RFC|stories: array|RFC frontmatter' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 4: Cache-freshness check pattern — same git log shape as list-problems
+# (P031: filesystem mtime unreliable in worktrees; git history is authoritative)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: SKILL.md uses git log cache-freshness pattern per P031" {
+  run grep -E 'git log -1 --format=%H -- docs/stories/README\.md' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 5: No-WSJF-leak — I11 invariant
+# (ADR-060 line 253: stories MUST NOT carry a WSJF field in Phase 2)
+# ---------------------------------------------------------------------------
+
+@test "list-stories: SKILL.md does NOT render a WSJF column (I11 invariant)" {
+  # Phase 2 invariant: no story-level WSJF. The display tables must
+  # not include a WSJF column header. This is a behavioural contract
+  # at the SKILL output surface, not a prose-grep.
+  # The output tables specified in SKILL.md should have NO 'WSJF' header.
+  # Find any markdown table header line and verify none include WSJF.
+  run grep -E '^\| WSJF\b|\| WSJF \|' "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}

package/skills/list-story-maps/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: wr-itil:list-story-maps
+description: List story-map artefacts from docs/story-maps/ as a markdown table. Read-only display — no edits, no interaction. Renders <meta> block data (problems / rfcs / jtbd / status) from each HTML map per ADR-060 § Phase 2 encoding amendment 2026-05-12.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+# List Story Maps
+
+Display the story-map corpus from `docs/story-maps/` as a markdown table. Read-only view per ADR-060 Phase 2; does not edit, transition, or create maps.
+
+Mirrors `/wr-itil:list-stories` precedent (P071 phased-landing split per ADR-010). I5 invariant: story-maps MUST NOT carry WSJF (no Story Rankings table — maps are planning artefacts, not work items per ADR-060 line 145).
+
+## Scope
+
+Story-maps live under `docs/story-maps/<state>/STORY-MAP-<NNN>-<slug>.html`:
+- `draft/` — captured (problem + JTBD traces present); pre-acceptance authoring
+- `accepted/` — backbone/ribs/slices authored; ready for implementation dispatch
+- `in-progress/` — slices being implemented; stories transitioning
+- `completed/` — all slices done
+- `archived/` — closed without completion
+
+## Argument grammar
+
+No arguments (read-only display).
+
+## Steps
+
+### 1. Check `docs/story-maps/README.md` cache freshness
+
+```bash
+readme_commit=$(git log -1 --format=%H -- docs/story-maps/README.md 2>/dev/null)
+if [ -z "$readme_commit" ] || \
+   git log --oneline "${readme_commit}..HEAD" -- 'docs/story-maps/*/*.html' ':!docs/story-maps/README.md' 2>/dev/null | grep -q .; then
+  echo "stale"
+fi
+```
+
+**Cache fresh**: read `docs/story-maps/README.md` directly. **Cache stale**: live-scan in Step 2.
+
+### 2. Live scan
+
+Enumerate each lifecycle subdir:
+
+```bash
+ls docs/story-maps/draft/*.html docs/story-maps/accepted/*.html docs/story-maps/in-progress/*.html docs/story-maps/completed/*.html docs/story-maps/archived/*.html 2>/dev/null
+```
+
+For each map file, parse the `<meta>` block to extract: `story-map-id`, `status`, `problems`, `rfcs`, `jtbd`. Use `xmllint --xpath` when available; fall back to `grep` on `<meta>` lines:
+
+```bash
+status=$(xmllint --xpath 'string(//meta[@name="status"]/@content)' "$map" 2>/dev/null || \
+         grep -oE '<meta name="status" content="[^"]*"' "$map" | grep -oE 'content="[^"]*"' | sed 's/content="//;s/"$//')
+```
+
+### 3. Display
+
+Render lifecycle-grouped sections:
+
+```markdown
+## Draft
+
+| ID | Title | Problems | RFCs | JTBD |
+|----|-------|----------|------|------|
+| STORY-MAP-<NNN> | <title> | <P<NNN>...> | <RFC-<NNN>...> | <JTBD-<NNN>...> |
+
+## Accepted / In Progress / Completed / Archived
+
+(same shape; sections omitted when empty)
+```
+
+NO WSJF column per I5. NO ranking table per the "story-maps are planning artefacts, not work items" principle (ADR-060 line 145).
+
+### 4. Trailing suggestions
+
+- Draft section non-empty: `Run /wr-itil:manage-story-map <STORY-MAP-<NNN>> accepted to author backbone/ribs/slices and advance the draft.`
+- In-progress section non-empty: `Run /wr-itil:list-stories --rfc <RFC-<NNN>> to see the next story under each in-progress map's referenced RFC.`
+- All sections empty: `No story maps captured yet. Run /wr-itil:capture-story-map <P-<NNN>> <JTBD-<NNN>> <description> to capture the first.`
+
+## Ownership boundary
+
+Does not modify, rename, or commit files. Cache-stale path performs live scan only; never rewrites `docs/story-maps/README.md` — refresh is `/wr-itil:manage-story-map review`'s ownership.
+
+## Related
+
+- **ADR-060** — Problem-RFC-Story framework; Phase 2 amendment lines 145-189 (story-map tier spec).
+- **ADR-060 line 145** — story-maps are planning artefacts; no WSJF (I5).
+- **ADR-060 lines 381-435** — HTML encoding schema; `<meta>` block parse target.
+- **`docs/story-maps/README.md`** — story-map directory index.
+- **`/wr-itil:list-stories`** — sibling read-only display at the story tier.
+- **`/wr-itil:list-problems`** — sibling at the problem tier (P071 precedent).
+- **JTBD-008** — Decompose a Fix Into Coordinated Changes.
+
+$ARGUMENTS

package/skills/list-story-maps/test/list-story-maps-contract.bats

@@ -0,0 +1,46 @@
+#!/usr/bin/env bats
+# Behavioural contract fixtures for /wr-itil:list-story-maps (P170 Phase 2 Slice 6).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/list-story-maps/SKILL.md"
+}
+
+@test "list-story-maps: SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "list-story-maps: SKILL.md frontmatter declares wr-itil:list-story-maps name" {
+  run grep -E '^name: wr-itil:list-story-maps$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "list-story-maps: SKILL.md allowed-tools does NOT include Write or Edit (read-only contract)" {
+  run grep '^allowed-tools:' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"Write"* ]]
+  [[ "$output" != *"Edit"* ]]
+}
+
+@test "list-story-maps: SKILL.md names all 5 lifecycle state subdirectories" {
+  for state in draft accepted in-progress completed archived; do
+    run grep -E "docs/story-maps/${state}|${state}/" "$SKILL_FILE"
+    [ "$status" -eq 0 ]
+  done
+}
+
+@test "list-story-maps: SKILL.md does NOT render a WSJF column (I5 invariant)" {
+  # Story-maps are planning artefacts, not work items — no WSJF per ADR-060 line 145.
+  run grep -E '^\| WSJF\b|\| WSJF \|' "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "list-story-maps: SKILL.md names <meta> block parse target per ADR-060 lines 381-435" {
+  run grep -E '<meta name=|xmllint.*meta' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "list-story-maps: SKILL.md uses git log cache-freshness pattern per P031" {
+  run grep -E 'git log -1 --format=%H -- docs/story-maps/README\.md' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/manage-problem/SKILL.md

@@ -166,10 +166,23 @@ What "work" means depends on the problem's status:
 8. If the fix is small enough, continue straight to implementing it (becoming a Known Error → Closed flow in one session)
 
 **Known Error (root cause confirmed, fix path clear):**
-1. Read the root cause analysis and fix strategy
-2. Implement the fix following the project's development workflow (plan if needed, architect review, tests, etc.)
-3. Include the problem doc closure in the fix commit (`git mv` to `.closed.md`, update Status)
-4. Push, create changeset, release per the lean release principle
+
+The Phase 2 working-the-problem traversal makes "implement the fix" concretely traceable via stories (per ADR-060 lines 300-320). Replaces the prior vague "implement the fix following the project's development workflow" with a deterministic problem → RFC → story dispatch:
+
+1. **Read the problem's `## Fix Strategy` section** — extract referenced RFC IDs (anchor links / inline references like `RFC-NNN`). If no RFCs are referenced, the problem is non-decomposed Phase 1 work: fall through to the legacy direct-implementation path (step 6 below).
+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).
+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.
+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 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).
 
 **Scope expansion during work:** If investigation or architect review reveals that the problem's scope has grown significantly (e.g., effort re-sized from S to L, additional files discovered), use `AskUserQuestion` before continuing:
 - Option 1: `Continue with expanded scope` — keep working this problem at its new size
@@ -181,6 +194,31 @@ What "work" means depends on the problem's status:
 
 ## Steps
 
+### 0a. Auto-migrate adopter layout (P170 / RFC-002 / ADR-031)
+
+Before the README-reconciliation preflight (Step 0) and any other layout-dependent logic, source the shared shell migration routine and call the idempotent entrypoint:
+
+```bash
+# Source the synced copy from this package's lib/ (canonical lives at
+# packages/shared/lib/migrate-problems-layout.sh per ADR-017 sync pattern).
+source packages/itil/lib/migrate-problems-layout.sh
+migrate_problems_to_per_state_layout "$PWD"
+```
+
+The routine is **idempotent and partial-migration-safe**. It no-ops when no flat-layout files (`docs/problems/*.<state>.md` at the top level of `docs/problems/`) are detected — the common case in this monorepo (post-Slice-5 T5a 2026-05-10) and in freshly-migrated adopter repos.
+
+On a flat-layout adopter repo (first invocation post-update — JTBD-101 plugin-developer auto-migration path), the routine:
+
+1. Creates the five state subdirectories (`docs/problems/open/`, `/known-error/`, `/verifying/`, `/parked/`, `/closed/`).
+2. Runs `git mv docs/problems/<NNN>-<slug>.<state>.md docs/problems/<state>/<NNN>-<slug>.md` for every existing ticket. `nullglob` is enabled so partial-migration tails don't trip on literal-glob expansion.
+3. Emits a standalone commit (per ADR-031 § Backward Compatibility line 124 "not folded into other work — so adopters can audit / revert in isolation") with subject `docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)` and footer trailer `RISK_BYPASS: adr-031-migration` (recognised by the commit-gate hook per T11; allows the migration to skip the full risk-score overhead while preserving the audit trail).
+
+**AFK authorisation per ADR-013 Rule 6**: this fires unconditionally even in AFK / non-interactive / orchestrated mode. Pure-rename + pure-mkdir + standalone-commit actions are policy-authorised under ADR-019 precedent — they are fully reversible (`git revert`), have no external-comms surface, no secrets, no destructive overwrite. No `AskUserQuestion` gate.
+
+**First-fire signal (JTBD-006 AFK transparency per T8 jtbd-review nitpick c)**: the routine emits a single stderr line `migrate-problems-layout: relocated N tickets to per-state subdirs (ADR-031)` on the migrating invocation; silent on no-op re-invocations.
+
+After Step 0a completes (whether no-op or migration), proceed to Step 0 README reconciliation preflight. The reconcile-readme script reads the post-migration layout; the in-flow Step 5 / Step 7 README refresh paths re-render the README from the per-state subdir shape.
+
 ### 0. README reconciliation preflight (P118)
 
 Before parsing the request, run the diagnose-only reconciliation check. The contract here catches **cross-session drift** that per-operation refresh paths (P094 refresh-on-create + P062 refresh-on-transition) cannot retroactively see — if any past session committed a ticket change without staging the README refresh, the next manage-problem invocation reads a stale README that lies about what is open / verifying / closed.

package/skills/manage-problem/test/manage-problem-auto-migrate-step.bats

@@ -0,0 +1,53 @@
+#!/usr/bin/env bats
+
+# P170 / RFC-002 / ADR-031 Open-Execution Q1 resolution: manage-problem
+# SKILL.md wires the shared migration routine at Step 0a (before
+# Step 0 README reconciliation preflight). Doc-lint structural test —
+# the wiring is a SKILL.md preamble integration point; behavioural
+# assertions for the routine itself live at
+# packages/shared/test/sync-migrate-problems-layout.bats (T7) and the
+# end-to-end behavioural fixture
+# packages/itil/skills/manage-problem/test/manage-problem-auto-migrate.bats (T10).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_MD="$REPO_ROOT/packages/itil/skills/manage-problem/SKILL.md"
+}
+
+@test "manage-problem: SKILL.md declares Step 0a auto-migrate (T8 wiring point)" {
+  run grep -E '^### 0a\.|^## Step 0a|Step 0a:' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md Step 0a cites P170 / RFC-002 / ADR-031" {
+  run grep -F 'P170' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'ADR-031' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md Step 0a sources packages/itil/lib/migrate-problems-layout.sh" {
+  run grep -F 'packages/itil/lib/migrate-problems-layout.sh' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md Step 0a calls migrate_problems_to_per_state_layout entrypoint" {
+  run grep -F 'migrate_problems_to_per_state_layout' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md Step 0a fires before Step 0 README reconciliation" {
+  # Assert the literal line order in the file: Step 0a appears before
+  # the existing Step 0 README reconciliation heading.
+  local step_0a_line step_0_line
+  step_0a_line=$(grep -nE '^### 0a\.|^## Step 0a|Step 0a:' "$SKILL_MD" | head -1 | cut -d: -f1)
+  step_0_line=$(grep -nE '^### 0\. README' "$SKILL_MD" | head -1 | cut -d: -f1)
+  [ -n "$step_0a_line" ]
+  [ -n "$step_0_line" ]
+  [ "$step_0a_line" -lt "$step_0_line" ]
+}
+
+@test "manage-problem: SKILL.md Step 0a cites ADR-013 Rule 6 (AFK auto-fire authorisation)" {
+  run grep -F 'ADR-013' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}

package/skills/manage-rfc/SKILL.md

@@ -157,6 +157,18 @@ The helper (`packages/itil/scripts/update-problem-rfcs-section.sh`) is idempoten
 
 The trailer hook (`itil-rfc-trailer-advisory.sh`) sits on top of this skill-side contract as a drift-detection backstop for ARBITRARY commits (e.g. `feat(...)` commits with `Refs: RFC-<NNN>` trailers authored outside the RFC skills) — it never auto-fixes; it advises.
 
+#### Forward trace — `## Stories` body section (Phase 2)
+
+Per ADR-060 line 270 + line 296: every transition that touches the RFC body refreshes the RFC's own `## Stories` body section from its frontmatter `stories:` array. The forward-trace surface renders the ordered execution sequence as inline links to the story files, lazy-empty when `stories: []` (atomic RFC — JTBD-101 friction guard). The helper is the Slice 2b sibling `update-rfc-references-section.sh`:
+
+```bash
+bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+```
+
+Idempotent + lazy-empty per the Slice 2a/2b contract. Run after the rename + frontmatter edit so the section reflects the post-transition `stories:` shape. Stage the RFC file (already staged for the lifecycle transition; the helper modifies the same file in-place).
+
+This composes with the existing `## Story Maps` refresh that the same helper handles via `update-rfc-references-section.sh "$rfc_file" "Story Maps"` — when the RFC traces story-maps via the `story-maps:` frontmatter field (Phase 2+).
+
 ### 8. List flow (`list`)
 
 Read all `.proposed.md`, `.accepted.md`, `.in-progress.md` files in `docs/rfcs/`. Extract ID, title, status, traced problems. Sort by Status priority (Accepted > In-Progress > Proposed) then by `Reported` ASC. Display as a markdown table.