@windyroad/itil 0.27.1 → 0.28.0-preview.304

package/skills/manage-story/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: wr-itil:manage-story
+description: Heavyweight story intake + lifecycle management following ADR-060 Phase 2. Creates and updates story tickets, transitions through draft → accepted → in-progress → done → archived lifecycle, enforces I7 + I8 trace-gate at the accepted transition, runs INVEST checks per I10 at acceptance, auto-transitions draft→in-progress on first non-capture commit and in-progress→done on all-criteria-ticked + linked RFC closes, and refreshes docs/stories/README.md per the P062 / P094 contract pattern. Companion to /wr-itil:capture-story (lightweight aside surface).
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Manage Story Skill
+
+Heavyweight story lifecycle management. Mirrors `/wr-itil:manage-rfc` shape per ADR-032 lightweight + heavyweight skill split, extended for the story-tier's INVEST-shape acceptance gate (I10) and auto-transition triggers.
+
+## Story Lifecycle
+
+Per ADR-060 Phase 2 amendment 2026-05-10 lines 200-253:
+
+| Status | Filename pattern | Meaning | Entry criteria |
+|--------|-----------------|---------|----------------|
+| **draft** | `docs/stories/draft/STORY-<NNN>-<slug>.md` | Captured (problem + JTBD traces present); skeleton body | I6 + I9 satisfied at capture |
+| **accepted** | `docs/stories/accepted/STORY-<NNN>-<slug>.md` | INVEST shape verified; ready for implementation | I7 + I8 + I10 hard-block satisfied |
+| **in-progress** | `docs/stories/in-progress/STORY-<NNN>-<slug>.md` | Implementation underway | Auto-transitioned on first non-capture commit carrying `Refs: STORY-<NNN>` |
+| **done** | `docs/stories/done/STORY-<NNN>-<slug>.md` | All acceptance criteria ticked + linked RFC closed | Auto-transitioned (triggered by RFC close-fire or by manual `manage-story <NNN> done`) |
+| **archived** | `docs/stories/archived/STORY-<NNN>-<slug>.md` | Closed without completion (scope shifted; superseded) | Manual transition only |
+
+## I-invariant enforcement at lifecycle transitions
+
+| Invariant | What it asserts | Where it fires |
+|-----------|-----------------|----------------|
+| **I6** trace-to-problem | Every story traces to ≥ 1 problem | Hard-block at `/wr-itil:capture-story` (also verified at every transition) |
+| **I7** trace-to-RFC | Every story traces to ≥ 1 RFC | Hard-block at `manage-story <NNN> accepted` (deferred from capture per ADR-060 line 291) |
+| **I8** trace-to-story-map | Every story traces to ≥ 1 story map | Hard-block at `manage-story <NNN> accepted` (deferred from capture) |
+| **I9** trace-to-JTBD | Every story traces to ≥ 1 JTBD | Hard-block at `/wr-itil:capture-story` (also verified at every transition) |
+| **I10** INVEST shape | At acceptance, INVEST behaviourally: ≥1 acceptance criterion (Testable); user-value statement (Valuable); no Blocked-by-unaccepted refs (Independent); `estimated-effort` field set (Estimable); S/M effort SHOULD; L/XL flagged decomposition-candidate (Small) | Hard-block at `manage-story <NNN> accepted` |
+| **I11** no-WSJF-leak | Phase 2: stories MUST NOT carry a WSJF field | Behavioural test at this skill (no WSJF field added/read) |
+
+**Bootstrap-exemption marker** (per ADR-060 line 339 + ADR-053 Bootstrapping precedent): the I7/I8/I9/I10 retrofit on bootstrap-migration stories rides a one-time exemption marker `<!-- bootstrap-exempt: STORY-MAP-001 migration per ADR-060 amendment 2026-05-10 -->` inline with the frontmatter. Non-bootstrap captures with the marker fail per the behavioural test.
+
+## Argument grammar
+
+```
+/wr-itil:manage-story <STORY-NNN>                    # Update flow — open the story for review
+/wr-itil:manage-story <STORY-NNN> accepted            # Transition draft → accepted (gates I7 + I8 + I10)
+/wr-itil:manage-story <STORY-NNN> in-progress         # Manual transition (auto-fires on first non-capture commit)
+/wr-itil:manage-story <STORY-NNN> done                # Transition in-progress → done (gates all-criteria-ticked + RFC closed)
+/wr-itil:manage-story <STORY-NNN> archived            # Close without completion
+/wr-itil:manage-story review                          # Re-rank all stories + refresh README
+```
+
+## Rule 6 audit (per ADR-032 + ADR-013 + ADR-060)
+
+| Decision | Resolution | Authority class |
+|----------|-----------|-----------------|
+| Story ID resolution | Mechanical: `STORY-<NNN>` regex match against `docs/stories/*/STORY-<NNN>-*.md` | silent-mechanical |
+| Lifecycle transition validation | Mechanical: state machine — draft → accepted → in-progress → done; allow draft → archived; disallow backwards | silent-mechanical |
+| I7 + I8 hard-block at accepted | Mechanical: frontmatter `rfcs:` and `story-maps:` arrays MUST be non-empty AND each ID must resolve to a file in `docs/rfcs/` and `docs/story-maps/` | silent-mechanical |
+| I10 INVEST shape check | Mechanical: `## User value` section non-empty; `## Acceptance criteria` has ≥ 1 `- [ ]` line; `estimated-effort` field set to S/M/L/XL; L/XL flagged as decomposition-candidate (advisory, not blocking per ADR-060 line 252 architect-amendment-2026-05-10 nitpick N3) | silent-mechanical |
+| INVEST shape violation | Halt-with-stderr-directive listing the missing INVEST attributes; user re-invokes after editing the story body | n/a (halt) |
+| README refresh on every transition | Mechanical: regenerate `docs/stories/README.md` Story Rankings + Done tables from FS truth; stage in same commit | silent-mechanical |
+| Reverse-trace refresh on driving artefacts | Mechanical: every transition refreshes `## Stories` section on each driving problem + JTBD + RFC + story-map via the Slice 2a/2b helpers | silent-mechanical |
+| Bootstrap-exemption marker | Mechanical: marker permitted only on stories whose frontmatter problem-trace includes the bootstrap-migration problem ID (P170); non-bootstrap stories with the marker fail at acceptance | silent-mechanical |
+
+All decisions framework-mediated per ADR-044 + P132 + inverse-P078.
+
+## Steps
+
+### 0. Preflight
+
+```bash
+wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+wr-itil-reconcile-stories docs/stories docs/problems docs/rfcs docs/jtbd > /tmp/wr-itil-stories-drift-$$.txt
+# If either reports drift, halt-and-route to the appropriate reconcile skill.
+```
+
+### 1. Parse arguments
+
+```bash
+story_id="$1"
+action="${2:-update}"  # default: update flow
+```
+
+If `$story_id` is `review`, branch to Step 9 (review flow). Otherwise validate `$story_id` matches `^STORY-[0-9]{3}$` and resolve to a file under `docs/stories/<state>/STORY-<NNN>-*.md`. If unresolved, halt with stderr directive.
+
+### 2. Read story frontmatter + body
+
+Parse YAML frontmatter (fields: `status`, `story-id`, `reported`, `decision-makers`, `problems`, `jtbd`, `rfcs`, `story-maps`, `estimated-effort`). Read body sections (`## User value`, `## Acceptance criteria`, `## Driving problem trace`, `## JTBD trace`, `## Implementation notes`, `## Dependencies`, `## Related`).
+
+### 3-6. (Update flow — bare `<STORY-NNN>`)
+
+Display the current story state. Surface any open gaps:
+- Missing/empty body sections.
+- Frontmatter trace lists that don't resolve to files.
+- Mismatched filename `<status>` subdir vs frontmatter `status:` field.
+
+Use `AskUserQuestion` for direction-setting fields (e.g. `## User value` rewrite); silent-mechanical for housekeeping (e.g. trace ID format normalisation).
+
+### 7. Status transitions
+
+#### Transition mechanics
+
+For any transition `<from> → <to>`:
+
+1. **Verify pre-transition invariants** for `<to>`:
+   - `accepted`: I7 + I8 + I10 hard-block (see § I-invariant table).
+   - `in-progress`: linked RFC status is `accepted` or `in-progress` (you can't progress a story under a proposed/closed RFC).
+   - `done`: ALL `- [ ]` checkboxes in `## Acceptance criteria` are ticked (i.e. zero unticked); linked RFC status is `closed` OR the RFC's other stories have closed (transitive closure check deferred to a per-RFC `manage-rfc done-gate` check in a future slice).
+   - `archived`: no invariants (manual close-without-completion).
+
+2. **`git mv` the file** to the new state subdir:
+   ```bash
+   git mv "docs/stories/${from_state}/STORY-${nnn}-${slug}.md" "docs/stories/${to_state}/STORY-${nnn}-${slug}.md"
+   ```
+
+3. **Edit the file** — Status field; for `accepted`, populate any deferred `## User value` / `## Acceptance criteria` / `## Implementation notes` sections via AskUserQuestion if not already filled.
+
+4. **P057 staging-trap** — after the Edit, re-stage: `git add "docs/stories/${to_state}/STORY-${nnn}-${slug}.md"`.
+
+#### Auto-transition triggers (ADR-060 line 292)
+
+The auto-transition logic fires in two contexts:
+
+- **`draft → in-progress`**: when the FIRST commit AFTER the story's capture commit lands with a `Refs: STORY-<NNN>` trailer AND a commit subject NOT prefixed with `feat(itil): capture STORY-`. Detected by a future commit-trailer-trigger hook (deferred to a hook-source slice); manual `manage-story <NNN> in-progress` invocation works in the interim.
+
+- **`in-progress → done`**: when all `- [ ]` lines in `## Acceptance criteria` are ticked AND the linked RFC is `closed`. Detected at manage-rfc close-fire (the RFC's transition triggers a sweep of its `stories:` array; each in-progress story with all-criteria-ticked auto-transitions to `done`). Manual `manage-story <NNN> done` invocation works in the interim.
+
+#### README refresh on every transition (P062 mirror)
+
+After rename + Edit + re-stage, regenerate `docs/stories/README.md` Story Rankings + Done tables in-place reflecting the new filename set and the transitioned story's new Status. Stage the refreshed README with the same commit.
+
+The "Last reviewed" line on `docs/stories/README.md` follows the same P134 truncation discipline as `docs/problems/README.md`: single most-recent fragment on line 3; soft cap ≤ 1024 bytes per fragment; hard ceiling 5120 bytes per ADR-040 Tier 3 envelope.
+
+#### Reverse trace on driving problem(s), JTBD(s), RFC(s), story-map(s) — skill-side primary surface
+
+Per ADR-060 line 270: every transition refreshes the `## Stories` section on each driving artefact inline in the same commit per ADR-014 single-commit grain.
+
+For each parent ID in the story's frontmatter:
+
+```bash
+# Problem parents
+for pid_token in $(awk '/^problems:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$story_file"); do
+  pid_num="${pid_token#P}"
+  problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
+  [ -z "$problem_file" ] && continue
+  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Stories"
+  git add "$problem_file"
+done
+
+# JTBD parents — sibling shape
+for jid in $(awk '/^jtbd:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$story_file"); do
+  jtbd_file=$(ls docs/jtbd/*/${jid}-*.md 2>/dev/null | head -1)
+  [ -z "$jtbd_file" ] && continue
+  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-jtbd-references-section.sh" "$jtbd_file" "Stories"
+  git add "$jtbd_file"
+done
+
+# RFC parents — sibling shape (after Slice 11 ships the Stories section helper)
+for rid in $(awk '/^rfcs:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$story_file"); do
+  rfc_file=$(ls docs/rfcs/${rid}-*.md 2>/dev/null | head -1)
+  [ -z "$rfc_file" ] && continue
+  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+  git add "$rfc_file"
+done
+
+# Story-map parents — manually-authored data-attribute traces per
+# architect amend finding 2 on Slice 7; NO automatic refresh here. Emit
+# advisory stderr noting unplaced-on-map state if frontmatter
+# story-maps: is non-empty.
+```
+
+The helpers are idempotent + lazy-empty per the Slice 2a/2b/Slice 11 contract.
+
+### 8. List flow (`list`)
+
+Read all `docs/stories/*/STORY-*.md` files. Extract ID, title, status, traced problems / RFCs / story-maps / JTBDs. Sort by lifecycle state (accepted > in-progress > draft > done > archived) then by `Reported` ASC. Display as markdown tables grouped by state.
+
+### 9. Review flow (`review`)
+
+Per `/wr-itil:review-problems` precedent at the story tier:
+
+1. For each story, re-validate I6 + I9 (re-resolve problem + JTBD trace files; flag missing).
+2. For each accepted/in-progress story, re-validate I7 + I8 + I10 (re-resolve RFC + story-map trace files; re-check INVEST shape; flag drift).
+3. Regenerate `docs/stories/README.md` Story Rankings + Done tables.
+4. Single commit per ADR-014; commit message names the review pass + count of drift-resolutions.
+
+### 10. Single commit per ADR-014
+
+Stage list per transition shape:
+- Renamed story file (new path)
+- README.md refresh
+- All driving problem + JTBD + RFC files whose `## Stories` section refreshed
+
+Commit message format:
+```
+feat(itil): transition STORY-<NNN> <from> → <to> — <title>
+
+Refs: STORY-<NNN>
+```
+
+Risk-gate per ADR-014: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool; fallback `/wr-risk-scorer:assess-release` via Skill tool.
+
+### 11. Report
+
+After commit, report:
+- Story ID + title + new status.
+- Action taken (transition kind + invariant gates that fired).
+- Driving artefacts touched (problem + JTBD + RFC reverse-trace refresh paths).
+- Trailing pointer: `Run /wr-itil:work-problem <P-<NNN>> to continue work on the driving problem, or /wr-itil:list-stories --rfc <RFC-<NNN>> to see the next story in the RFC's execution order.`
+
+## Composition with capture-story
+
+| Concern | manage-story | capture-story |
+|---------|--------------|---------------|
+| I6 + I9 hard-block | Re-validated at every lifecycle transition | Hard-block at capture-time |
+| I7 + I8 hard-block | **Primary surface** — fires at `manage-story <NNN> accepted` | Advisory at capture if flags provided |
+| I10 INVEST shape | **Primary surface** — fires at `manage-story <NNN> accepted` | Out of scope (capture produces skeleton) |
+| Status transitions | Owns draft → accepted → in-progress → done → archived | Out of scope (creation only) |
+| README refresh | Inline per transition (P094 mirror) | Deferred to `manage-story review` or `wr-itil-reconcile-stories` |
+| Auto-transition triggers | Fires on first non-capture commit (draft→in-progress) + criteria-ticked + RFC-closed (in-progress→done) | n/a |
+| Reverse-trace refresh on parents | Inline per transition | Inline per capture |
+| Commit grain | One commit per transition / per intake | One commit per capture |
+
+## Related
+
+- **ADR-060** — Problem-RFC-Story framework + Phase 2 amendment 2026-05-10 (story tier).
+- **ADR-060 lines 248-253** — I6-I11 story-tier invariants.
+- **ADR-060 line 252** — I10 INVEST shape (Testable/Valuable/Independent/Estimable; Small SHOULD per architect-amendment-2026-05-10 nitpick N3).
+- **ADR-060 line 292** — auto-transition triggers (draft→in-progress on first non-capture commit; in-progress→done on criteria-ticked + RFC-closed).
+- **ADR-060 line 339 + ADR-053 Bootstrapping precedent** — bootstrap-exemption marker contract for STORY-MAP-001 migration retrofit.
+- **P170** — driver problem ticket.
+- **JTBD-008** — Decompose a Fix Into Coordinated Changes. Primary persona-anchor.
+- **JTBD-001** (extended scope) — change-set-level governance composition.
+- **JTBD-006** — AFK orchestrator protection (I11 no-WSJF-leak prevents story-level competition in Step 3 selection).
+- **`docs/stories/README.md`** — story tier lifecycle index + frontmatter/body shape spec.
+- **`/wr-itil:capture-story` SKILL.md** — companion lightweight aside surface.
+- **`/wr-itil:reconcile-stories` SKILL.md** — drift detection + agent-applied edit recovery.
+- **ADR-014** — single-commit grain.
+- **ADR-022** — problem lifecycle conventions; story lifecycle mirrors.
+- **ADR-032** — governance-skill aside-invocation pattern; lightweight + heavyweight split.
+- **ADR-044** — decision delegation contract.
+- **ADR-051** — load-bearing-from-the-start; I7 + I8 + I10 ship on day one.
+- **ADR-052** — behavioural-tests default; `packages/itil/scripts/test/manage-story.bats` (P170 Phase 2 Slice 8).
+- **ADR-060 Phase 2 Slice 2a/2b/Slice 11 reverse-trace helpers** — `update-problem-references-section.sh`, `update-jtbd-references-section.sh`, `update-rfc-references-section.sh` all support `"Stories"` section-name token.
+- **manage-rfc SKILL.md** — direct precedent shape; manage-story mirrors with story-tier extensions for INVEST gate + auto-transitions.
+
+$ARGUMENTS

package/skills/manage-story/test/manage-story-contract.bats

@@ -0,0 +1,171 @@
+#!/usr/bin/env bats
+# Behavioural contract fixtures for /wr-itil:manage-story (P170 Phase 2
+# Slice 8 — ADR-060 amendment 2026-05-10 lines 200-253 + 270 + 292).
+#
+# Per ADR-052: behavioural assertions on observable SKILL contract
+# surfaces. Skill-prose behaviour for prompt-driven agents isn't
+# directly testable in bats; these tests assert presence of the
+# load-bearing identifiers in the SKILL contract (the closest in-
+# session-reachable approximation per P081 + P012).
+#
+# Behavioural surfaces under test:
+#   1. SKILL.md presence + canonical name.
+#   2. I6-I11 invariant table presence (load-bearing).
+#   3. I7 + I8 hard-block fires at accepted transition (not earlier).
+#   4. I10 INVEST shape gate names all 4 INVEST checks (Testable /
+#      Valuable / Independent / Estimable) + L/XL decomposition-
+#      candidate advisory per ADR-060 line 252 nitpick N3.
+#   5. Auto-transition triggers named: draft→in-progress on first
+#      non-capture commit; in-progress→done on criteria-ticked + RFC
+#      closed.
+#   6. Bootstrap-exemption marker contract named per ADR-060 line 339.
+#   7. Reverse-trace refresh on all 4 parent tiers (problem / JTBD /
+#      RFC / story-map) named, with story-map manual placement noted
+#      per architect amend finding 2 on Slice 7.
+#   8. No-WSJF-leak (I11) — no WSJF field in argument grammar or
+#      frontmatter handling.
+#
+# @problem P170
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes)
+# @jtbd JTBD-001 (extended scope — change-set-level governance)
+# @adr  ADR-060  (Problem-RFC-Story framework — story tier)
+# @adr  ADR-052  (Behavioural-tests-default)
+# @adr  ADR-032  (governance-skill aside-invocation pattern)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/manage-story/SKILL.md"
+}
+
+# ---------------------------------------------------------------------------
+# Surface 0: SKILL.md presence + canonical name
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "manage-story: SKILL.md frontmatter declares wr-itil:manage-story name" {
+  run grep -E '^name: wr-itil:manage-story$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 1: I6-I11 invariant table presence
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md declares I6 trace-to-problem invariant" {
+  run grep -E 'I6.*trace-to-problem|trace-to-problem.*I6' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md declares I7 trace-to-RFC invariant" {
+  run grep -E 'I7.*trace-to-RFC|trace-to-RFC.*I7' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md declares I8 trace-to-story-map invariant" {
+  run grep -E 'I8.*trace-to-story-map|trace-to-story-map.*I8' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md declares I9 trace-to-JTBD invariant" {
+  run grep -E 'I9.*trace-to-JTBD|trace-to-JTBD.*I9' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md declares I10 INVEST shape invariant" {
+  run grep -E 'I10.*INVEST|INVEST.*I10' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md declares I11 no-WSJF-leak invariant" {
+  run grep -E 'I11.*WSJF|WSJF.*I11|no-WSJF-leak' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2: I7 + I8 fire at accepted transition (not earlier)
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md states I7 + I8 hard-block fires at accepted transition" {
+  # The deferred-from-capture contract is load-bearing per ADR-060
+  # line 291 — capture-story permits absent traces; manage-story
+  # accepted gate enforces them.
+  run grep -iE 'I7.*accepted|hard-block at.*accepted|fires at.*accepted.*I7' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 3: I10 INVEST 4-axis check
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md names all 4 INVEST checks (Testable/Valuable/Independent/Estimable)" {
+  for axis in Testable Valuable Independent Estimable; do
+    run grep -i "$axis" "$SKILL_FILE"
+    [ "$status" -eq 0 ]
+  done
+}
+
+@test "manage-story: SKILL.md names L/XL decomposition-candidate advisory per ADR-060 nitpick N3" {
+  run grep -iE 'L/XL.*decomposition|decomposition.candidate|N3' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 4: Auto-transition triggers
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md names draft → in-progress auto-transition on first non-capture commit" {
+  run grep -iE 'draft.*in-progress.*first.*non-capture|first commit.*non-capture|first.*after.*capture' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md names in-progress → done auto-transition on criteria-ticked + RFC closed" {
+  run grep -iE 'in-progress.*done.*criteria.*ticked|all.*criteria.*ticked.*RFC.*closed|RFC.*closed.*all-criteria' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 5: Bootstrap-exemption marker
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md names bootstrap-exemption marker per ADR-060 line 339" {
+  run grep -iE 'bootstrap-exempt|bootstrap.exemption|ADR-053.*Bootstrapping' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 6: Reverse-trace refresh on 4 parent tiers
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md names reverse-trace refresh on problem parents via update-problem-references-section.sh" {
+  run grep -E 'update-problem-references-section\.sh.*Stories' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md names reverse-trace refresh on JTBD parents via update-jtbd-references-section.sh" {
+  run grep -E 'update-jtbd-references-section\.sh.*Stories' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md names reverse-trace refresh on RFC parents via update-rfc-references-section.sh" {
+  run grep -E 'update-rfc-references-section\.sh.*Stories' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story: SKILL.md names story-map parents as MANUAL placement (no automatic refresh per Slice 7 architect amend finding 2)" {
+  run grep -iE 'manually-authored|manual placement|no automatic refresh' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 7: I11 no-WSJF-leak — no WSJF field in argument grammar
+# ---------------------------------------------------------------------------
+
+@test "manage-story: SKILL.md argument grammar does NOT include a WSJF flag/token (I11 invariant)" {
+  # The argument grammar block — extract the fenced block following
+  # "## Argument grammar" and verify no WSJF token in it.
+  run grep -A 20 '^## Argument grammar' "$SKILL_FILE"
+  [[ "$output" != *"WSJF"* ]] && [[ "$output" != *"wsjf"* ]]
+}

package/skills/manage-story-map/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: wr-itil:manage-story-map
+description: Heavyweight story-map intake + lifecycle management following ADR-060 Phase 2. Authors backbone × ribs × slices structure on draft maps, transitions through draft → accepted → in-progress → completed → archived, re-validates I3 + I4 invariants at every transition, and refreshes docs/story-maps/README.md per the P062 / P094 contract pattern. Companion to /wr-itil:capture-story-map (lightweight aside surface).
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Manage Story Map Skill
+
+Heavyweight story-map lifecycle management. Mirrors `/wr-itil:manage-story` shape per ADR-032 lightweight + heavyweight split, applied at the story-map tier with HTML encoding.
+
+## Story-Map Lifecycle
+
+Per ADR-060 amendment 2026-05-10 lines 145-189 + encoding amendment 2026-05-12:
+
+| Status | Filename pattern | Meaning |
+|--------|-----------------|---------|
+| **draft** | `docs/story-maps/draft/STORY-MAP-<NNN>-<slug>.html` | Captured (problem + JTBD traces present); skeleton backbone |
+| **accepted** | `docs/story-maps/accepted/STORY-MAP-<NNN>-<slug>.html` | Backbone × ribs × slices authored; story references in place |
+| **in-progress** | `docs/story-maps/in-progress/STORY-MAP-<NNN>-<slug>.html` | Slices being implemented; stories transitioning |
+| **completed** | `docs/story-maps/completed/STORY-MAP-<NNN>-<slug>.html` | All slices done |
+| **archived** | `docs/story-maps/archived/STORY-MAP-<NNN>-<slug>.html` | Closed without completion |
+
+## I-invariant enforcement
+
+| Invariant | What it asserts | Where it fires |
+|-----------|-----------------|----------------|
+| **I3** trace-to-problem | Every map traces to ≥ 1 problem (ADR-060 line 187) | Hard-block at `/wr-itil:capture-story-map` + re-validated at every transition |
+| **I4** trace-to-JTBD | Every map traces to ≥ 1 JTBD (ADR-060 line 188) | Hard-block at `/wr-itil:capture-story-map` + re-validated at every transition |
+| **I5** no-WSJF-leak | Maps MUST NOT carry WSJF (ADR-060 line 189) | Behavioural test: argument grammar + frontmatter carry no WSJF |
+
+**Bootstrap-exemption marker** per ADR-060 line 339 + ADR-053 Bootstrapping precedent: STORY-MAP-001 ships with the `<!-- bootstrap-exempt -->` marker during retrofit; non-bootstrap captures with the marker fail.
+
+## Argument grammar
+
+```
+/wr-itil:manage-story-map <STORY-MAP-NNN>             # Update flow
+/wr-itil:manage-story-map <STORY-MAP-NNN> accepted     # Transition draft → accepted
+/wr-itil:manage-story-map <STORY-MAP-NNN> in-progress  # Manual transition
+/wr-itil:manage-story-map <STORY-MAP-NNN> completed    # Transition in-progress → completed
+/wr-itil:manage-story-map <STORY-MAP-NNN> archived     # Close without completion
+/wr-itil:manage-story-map review                       # Re-validate all maps + refresh README
+```
+
+No WSJF token in any grammar form (I5 invariant).
+
+## Rule 6 audit
+
+| Decision | Resolution | Authority class |
+|----------|-----------|-----------------|
+| Story-map ID resolution | Mechanical: regex match `^STORY-MAP-[0-9]{3}$` against `docs/story-maps/*/STORY-MAP-<NNN>-*.html` | silent-mechanical |
+| Lifecycle transition validation | Mechanical state machine | silent-mechanical |
+| Backbone/ribs/slices authoring | AskUserQuestion (taste) at accepted; agent applies user input as HTML edits | taste |
+| `<meta>` block updates | Mechanical: update status `<meta>` on transitions; preserve all other meta | silent-mechanical |
+| README refresh on every transition | Mechanical: regenerate `docs/story-maps/README.md` lifecycle-grouped section from FS truth | silent-mechanical |
+| Reverse-trace refresh on driving artefacts | Mechanical: refresh `## Story Maps` on problems + JTBDs via Slice 2a/2b helpers | silent-mechanical |
+
+## Steps
+
+### 0. Preflight
+
+```bash
+wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+wr-itil-reconcile-story-maps docs/story-maps > /tmp/wr-itil-story-maps-drift-$$.txt
+# Halt-and-route on drift to the appropriate reconcile skill.
+```
+
+### 1. Parse arguments + resolve story-map file
+
+```bash
+story_map_id="$1"
+action="${2:-update}"
+```
+
+If `$story_map_id == "review"`, branch to Step 8 (review flow). Otherwise resolve `docs/story-maps/<state>/STORY-MAP-<NNN>-*.html`; if unresolved, halt.
+
+### 2. Read story-map HTML
+
+Parse `<meta>` block (problems, rfcs, jtbd, adrs, status, reported, decision-makers). Read backbone structure (`<section class="backbone">` → `.rib-header` → `.rib` → `<a class="slice">` data-* attributes).
+
+### 3-6. (Update flow — bare `<STORY-MAP-NNN>`)
+
+Display current map state. Surface gaps: missing backbone ribs, slices with unresolved `data-story-id` references, mismatched `<meta name="status">` vs filename `<state>` subdir.
+
+Use AskUserQuestion for backbone authoring direction (taste class); silent-mechanical for housekeeping (status normalisation).
+
+### 7. Status transitions
+
+For any transition `<from> → <to>`:
+
+1. **Verify pre-transition invariants**:
+   - `accepted`: I3 + I4 re-validated; backbone authored with ≥ 1 rib + ≥ 1 slice; every slice `data-story-id` resolves to a `docs/stories/*/STORY-NNN-*.md` file.
+   - `in-progress`: at least one slice has `data-status="in-progress"` or `"done"`.
+   - `completed`: every slice has `data-status="done"`.
+   - `archived`: no invariants (manual close).
+
+2. **`git mv` to new state subdir + Edit `<meta name="status">`** + P057 re-stage.
+
+3. **README refresh** — regenerate `docs/story-maps/README.md` lifecycle-grouped section from FS truth. Stage in same commit.
+
+4. **Reverse-trace refresh** — for each problem + JTBD in `<meta>` block:
+
+```bash
+for pid_token in $(grep -oE '<meta name="problems" content="[^"]*"' "$map_file" | grep -oE 'P[0-9]{3}'); do
+  pid_num="${pid_token#P}"
+  problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
+  [ -z "$problem_file" ] && continue
+  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Story Maps"
+  git add "$problem_file"
+done
+
+# Same for JTBDs via update-jtbd-references-section.sh "Story Maps"
+```
+
+Per architect amend finding 2 on Slice 7: story-map HTML files do NOT carry an auto-maintained markdown reverse-trace section themselves (the `<a class="slice">` data-attribute traces are authored manually during backbone design). No reverse-trace refresh on the map itself; reverse-trace only flows OUT to problem + JTBD parents.
+
+### 8. List flow (`list`)
+
+Forward-points to `/wr-itil:list-story-maps` (read-only sibling).
+
+### 9. Review flow (`review`)
+
+Re-validate every map's I3 + I4. Regenerate README. Single commit.
+
+### 10. Single commit per ADR-014
+
+Stage: renamed map file + README + driving problem/JTBD files whose `## Story Maps` section refreshed.
+
+Commit message: `feat(itil): transition STORY-MAP-<NNN> <from> → <to> — <title>` + `Refs: STORY-MAP-<NNN>` trailer.
+
+### 11. Report
+
+Story-map ID + new status + invariants verified + parent artefacts touched + trailing pointer to `/wr-itil:list-story-maps`.
+
+## Composition with capture-story-map
+
+| Concern | manage-story-map | capture-story-map |
+|---------|------------------|-------------------|
+| I3 + I4 | Re-validated at every transition | Hard-block at capture |
+| Backbone authoring | Step 7 accepted-transition AskUserQuestion fires | Out of scope (deferred-placeholder rib only) |
+| Status transitions | draft → accepted → in-progress → completed → archived | Out of scope (creation only) |
+| README refresh | Inline per transition (P094 mirror) | Deferred to `manage-story-map review` or `reconcile-story-maps` |
+| Commit grain | One commit per intake / per transition | One commit per capture |
+
+## Related
+
+- **ADR-060** — Problem-RFC-Story framework; Phase 2 amendment 2026-05-10 lines 145-189 + encoding amendment 2026-05-12 lines 381-435.
+- **ADR-060 line 145** — I5 no-WSJF-on-maps invariant.
+- **ADR-060 line 339 + ADR-053** — bootstrap-exemption marker contract.
+- **`docs/STYLE-GUIDE.md`** — HTML style rules manage-story-map enforces.
+- **P170** — driver problem ticket.
+- **JTBD-008** — primary anchor.
+- **JTBD-302** — README-currency rule.
+- **`/wr-itil:capture-story-map`** — companion lightweight aside.
+- **`/wr-itil:reconcile-story-maps`** — drift detection + recovery.
+- **manage-story SKILL.md** — sibling at the story tier; manage-story-map mirrors with HTML-encoding adjustments (`<meta>` block parse + backbone-authoring AskUserQuestion + no I7/I8/I9/I10 — those are story-tier invariants).
+- **ADR-052** — behavioural-tests default; `packages/itil/skills/manage-story-map/test/manage-story-map-contract.bats`.
+
+$ARGUMENTS

package/skills/manage-story-map/test/manage-story-map-contract.bats

@@ -0,0 +1,63 @@
+#!/usr/bin/env bats
+# Behavioural contract fixtures for /wr-itil:manage-story-map (P170 Phase 2 Slice 4).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/manage-story-map/SKILL.md"
+}
+
+@test "manage-story-map: SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "manage-story-map: SKILL.md frontmatter declares wr-itil:manage-story-map name" {
+  run grep -E '^name: wr-itil:manage-story-map$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md declares I3 trace-to-problem invariant" {
+  run grep -E 'I3.*trace-to-problem|trace-to-problem.*I3' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md declares I4 trace-to-JTBD invariant" {
+  run grep -E 'I4.*trace-to-JTBD|trace-to-JTBD.*I4' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md declares I5 no-WSJF-leak invariant" {
+  run grep -E 'I5.*WSJF|WSJF.*I5|no-WSJF-leak' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md names 5 lifecycle states (draft / accepted / in-progress / completed / archived)" {
+  for state in draft accepted in-progress completed archived; do
+    run grep -E "${state}" "$SKILL_FILE"
+    [ "$status" -eq 0 ]
+  done
+}
+
+@test "manage-story-map: SKILL.md names bootstrap-exemption marker per ADR-060 line 339" {
+  run grep -iE 'bootstrap-exempt|ADR-053.*Bootstrapping' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md names reverse-trace refresh on problem parents via Story Maps section" {
+  run grep -E 'update-problem-references-section\.sh.*Story Maps' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md names reverse-trace refresh on JTBD parents via Story Maps section" {
+  run grep -E 'update-jtbd-references-section\.sh.*Story Maps' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: SKILL.md states map HTML files do NOT carry markdown reverse-trace section themselves (per Slice 7 architect amend finding 2)" {
+  run grep -iE 'do NOT carry.*markdown reverse-trace|authored manually|manual.*data-attribute' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-story-map: argument grammar contains no WSJF token (I5 invariant)" {
+  run grep -A 10 '^## Argument grammar' "$SKILL_FILE"
+  [[ "$output" != *"WSJF"* ]] && [[ "$output" != *"wsjf"* ]]
+}