@windyroad/itil 1.2.0 → 2.0.0-preview.1111

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

@@ -0,0 +1,284 @@
+---
+name: wr-itil:manage-story
+description: Heavyweight story intake + lifecycle management following the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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-detects accepted→in-progress on the first implementing commit and in-progress→done on all-criteria-ticked + linked RFC closes (per the "A story cannot be implemented while in draft — implementation requires accepted" architecture rule a draft story is NEVER implementable — draft→in-progress is removed; the itil-no-implement-draft-gate blocks implementing a draft story), and refreshes docs/stories/README.md per the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem / the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem contract pattern. Companion to /wr-itil:capture-story (lightweight aside surface).
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Manage Story Skill
+
+Heavyweight story lifecycle management. Mirrors `/wr-itil:manage-rfc` shape per the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule lightweight + heavyweight skill split, extended for the story-tier's INVEST-shape acceptance gate (I10) and auto-transition triggers.
+
+## Story Lifecycle
+
+Per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 2 amendment 2026-05-10 lines 200-253:
+
+| Status | Filename pattern | Meaning | Entry criteria |
+|--------|-----------------|---------|----------------|
+| **draft** | `docs/stories/draft/STORY-<NNN>-<slug>.md` | Content-complete (map membership + real user value + ≥1 real acceptance criterion per the "Story-map membership and story-content completeness are enforced at capture" architecture rule) but not yet accepted — `estimated-effort`/Small unset, I7 RFC trace absent, ratification pending | I6 + I8 + I9 + content floor satisfied at capture |
+| **accepted** | `docs/stories/accepted/STORY-<NNN>-<slug>.md` | INVEST shape verified; ratified; ready for implementation | I7 + I8 + I10 + I12 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 the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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) |
+| **I12** approval | Every story is approved before it is implementable — by its story map's ratification (the "A release row is the RFC, and the map is the approval surface" architecture rule). A story carries no marker of its own, and a leftover one approves nothing | Hard-block at `manage-story <NNN> accepted`; re-asserted at the commit locus by `itil-no-implement-draft-gate` |
+
+**Bootstrap-exemption marker** (per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 339 + the "`@windyroad/*` plugin / skill / agent / hook maturity taxonomy" architecture rule Bootstrapping precedent): the I7/I8/I9/I10 retrofit on bootstrap-migration stories rides a one-time exemption marker `<!-- bootstrap-exempt: the "RFC framework bootstrap journey map" journey map migration per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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
+#  (no `ratify` action — the "A release row is the RFC, and the map is the approval surface" architecture rule: approval is the map's, see /wr-itil:manage-story-map <NNN> ratify)
+```
+
+## Rule 6 audit (per the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule + the "Structured User Interaction for Governance-Skill Decisions" architecture rule + the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule)
+
+| 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. Each map ID resolves to `docs/story-maps/`; each RFC resolves either to a legacy file in `docs/rfcs/` or to a release row containing this story via `<itil-plugin-root>/bin/wr-itil-story-map-query find-rfc` | 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 the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 252 architect-amendment-2026-05-10 nitpick N3) | silent-mechanical |
+| I12 approval at accepted | Mechanical: `story_is_approved` passes — every map in the story's `story-maps:` field is ratified (the "A release row is the RFC, and the map is the approval surface" architecture rule). The story itself carries no oversight field. Never an `request_user_input`: the predicate is fully framework-resolved, and a story that fails it is HELD until its map is ratified, not asked about | 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 (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem); non-bootstrap stories with the marker fail at acceptance | silent-mechanical |
+
+All decisions framework-mediated per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule + the "Agents over-ask in interactive sessions — conflating mechanical-stages with user-interactive-stages of multi-stage skill contracts (inverse-)" problem + inverse-the "Problem 078: Assistant does not offer to capture a problem ticket when the user delivers strong-signal correction" problem.
+
+## Steps
+
+### 0. Preflight
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+<itil-plugin-root>/bin/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 `request_user_input` 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 + **I12** hard-block (see § I-invariant table). For I7, a legacy RFC file satisfies resolution as before. Otherwise `<itil-plugin-root>/bin/wr-itil-story-map-query find-rfc <RFC-ID>` must return a release row whose `stories` contains this story; a row with no matching card fails because the row is the RFC under the "A release row is the RFC, and the map is the approval surface" architecture rule.
+
+     **I12 — the approval gate (the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule / the "A story cannot be implemented while in draft — implementation requires accepted" architecture rule / the "A release row is the RFC, and the map is the approval surface" architecture rule; the hole the "The story `accepted` gate names ratification but no surface enforces it" problem named).** A story reaches `accepted` only when it is approved. Under the "A release row is the RFC, and the map is the approval surface" architecture rule the map is the approval surface, so resolve in this order:
+
+     1. Every map in the story's `story-maps:` field is ratified? I12 satisfied; proceed.
+     2. Otherwise HALT. Do not accept. Interactively, ratify the **map** (§ 7.5), which approves every story on it at once. Under AFK, leave the story in `draft` and queue the map's ratification to `outstanding_questions`; do NOT ask about it. Never write an oversight field onto the story — the marker writer refuses story paths, and there is no story-level approval to write.
+
+   - `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 request_user_input if not already filled.
+
+4. **the "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem staging-trap** — after the Edit, re-stage: `git add "docs/stories/${to_state}/STORY-${nnn}-${slug}.md"`.
+
+5. **No ratify write here (the "A release row is the RFC, and the map is the approval surface" architecture rule).** A story transition never writes an oversight marker, because a story has none — `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed` refuses a story path. Approval is its map's, derived at read time from `story-maps:`, so nothing in this transition can grant or revoke it.
+
+   The write-ordering hazard this step used to guard is now a MAP concern only: when ratifying a map, the marker write must come after every substance write to that map and the file must be re-staged afterwards, or the marker records a hash of content that no longer exists. See `/wr-itil:manage-story-map <NNN> ratify`.
+
+#### Auto-transition triggers (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 292)
+
+The auto-transition logic fires in two contexts:
+
+- **`accepted → in-progress`**: when the FIRST implementing commit lands with a `Refs: STORY-<NNN>` trailer AND a commit subject NOT prefixed with `feat(itil): capture STORY-`, on a story that is already `accepted`. **Per the "A story cannot be implemented while in draft — implementation requires accepted" architecture rule a `draft` story is NEVER implementable — there is NO `draft → in-progress` transition**; the `itil-no-implement-draft-gate` PreToolUse hook blocks a commit referencing a draft story (accept it first). **Detected by `itil-commit-trailer-transition-advisory.sh`** (PostToolUse:Bash; the "RFC lifecycle is not self-maintaining — it leans on human memory" problem/the ": RFC lifecycle self-maintenance" release design Piece 2). Per the "Governance Skills Commit Their Own Completed Work" architecture rule the hook DETECTS + emits a stderr advisory; it does NOT perform the `git mv` (that would land outside the commit grain). The transition is performed by `manage-story <NNN> in-progress` (run on the advisory) or by an AFK orchestrator acting on it.
+
+- **`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 (the "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem 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.
+
+Update the "Last reviewed" line on `docs/stories/README.md` per the **inline the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem rotation mechanism** below. The mechanism is inlined here at the execution site (not deferred via cross-reference to `manage-problem` SKILL.md Step 5) so a single-pass agent reading this Step does not silently skip the archive step. **Skipping the BEFORE-rewrite archive step destroys the displaced fragment and re-opens the "transition-problem SKILL Step 7 Last-reviewed rotation silently skipped across iters" problem** (origin failure mode: iter-7 + iter-8 of 2026-05-30's AFK work-problems session silently skipped the equivalent rotation on `docs/problems/README.md` in 2 of 9 transition-bearing iters). The mechanism MUST execute IN ORDER:
+
+1. **Read** line 3 of `docs/stories/README.md`: `awk 'NR==3' docs/stories/README.md` (`head -3 | tail -1` or `sed -n '3p'` are acceptable equivalents).
+2. **Append-if-non-empty (BEFORE step 3, not after)** — if line 3 is non-empty AND not a same-session same-verb near-duplicate of the new fragment, append the existing line 3 verbatim to `docs/stories/README-history.md` (created on first rotation) under a `## YYYY-MM-DD` heading. Run this BEFORE the Edit-tool rewrite in step 3 — Edit's replace pattern destroys the displaced content otherwise.
+3. **Rewrite** line 3 of `docs/stories/README.md` with the new fragment of form `> Last reviewed: YYYY-MM-DD **<event>** — <one-line summary>` (e.g. `STORY-<NNN> <status> — <one-line summary>`). Soft cap ≤ 1024 bytes per fragment; hard ceiling 5120 bytes per the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule Tier 3 envelope.
+4. **Stage both** — `git add docs/stories/README.md docs/stories/README-history.md` so the same single commit per the "Governance Skills Commit Their Own Completed Work" architecture rule captures both files.
+
+Canonical rationale anchor: `manage-problem` SKILL.md Step 5 § Last-reviewed line discipline (the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem). The discipline applies identically across `docs/problems/README.md`, `docs/rfcs/README.md`, and `docs/stories/README.md` (only the target index path differs). The cross-reference is preserved for the "why"; the "what" is inlined above for execution-time legibility per the "transition-problem SKILL Step 7 Last-reviewed rotation silently skipped across iters" problem.
+
+#### Reverse trace on driving problem(s), JTBD(s), RFC(s), story-map(s) — skill-side primary surface
+
+Per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 270: every transition refreshes the `## Stories` section on each driving artefact inline in the same commit per the "Governance Skills Commit Their Own Completed Work" architecture rule 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
+  <itil-plugin-root>/bin/wr-itil-update-problem-references-section "$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
+  <itil-plugin-root>/bin/wr-itil-update-jtbd-references-section "$jtbd_file" "Stories"
+  git add "$jtbd_file"
+done
+
+# Legacy RFC parents only. Row-backed RFCs have no markdown parent; the card
+# in the release row is their reverse trace and is checked by I7 above.
+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
+  <itil-plugin-root>/bin/wr-itil-update-rfc-references-section "$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.
+
+### 7.5. There is no per-story ratify (the "A release row is the RFC, and the map is the approval surface" architecture rule)
+
+**`ratify` is not a story subcommand.** A story carries no oversight marker, so there is nothing to write, and `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed` exits 2 on a story path. Approval is its story map's: **`/wr-itil:manage-story-map <NNN> ratify`** approves every story on that map at once, including stories added later.
+
+Approval is still a precondition of `accepted` (I12) and still drift-invalidated — but at the map tier. A change to the map's activity columns, its identity, its prose or its traces re-opens it. Drawing a release row, putting a story in one, or editing a story's body does not.
+
+> Until the "A release row is the RFC, and the map is the approval surface" architecture rule this section ratified a single story. The clause "orthogonal to the `status:` lifecycle" was ambiguous between "ratification is not itself a status" (what it meant) and "ratification is not a precondition of any status" (what it read like); an agent acting on the second reading accepted and implemented an unratified story believing it compliant — the "The story `accepted` gate names ratification but no surface enforces it" problem failure, 2026-07-26. That hole is closed differently now: there is one approval surface, and the commit gate reads it directly.
+
+**AFK (the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6):** if `request_user_input` is unavailable, do NOT auto-ratify a map (hollow marker, the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem). Leave it unratified for the `/wr-itil:work-problems` Step 2.4 drain. **No carve-outs** — the "An AFK loop may accept and implement a story that only decomposes already-ratified substance" architecture rule's AFK pure-decomposition exception is retired, because capturing a story no longer re-opens its map's approval and the deadlock it worked around is gone.
+
+### 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 the "Governance Skills Commit Their Own Completed Work" architecture rule; commit message names the review pass + count of drift-resolutions.
+
+### 10. Single commit per the "Governance Skills Commit Their Own Completed Work" architecture rule
+
+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 the "Governance Skills Commit Their Own Completed Work" architecture rule: delegate to subagent type `wr-risk-scorer:pipeline` via the native Codex subagent tool; fallback `/wr-risk-scorer:assess-release` via installed skill invocation.
+
+### 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 (the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem mirror) | Deferred to `manage-story review` or `<itil-plugin-root>/bin/wr-itil-reconcile-stories` |
+| Auto-transition triggers | Fires on first implementing commit against an ACCEPTED story (accepted→in-progress; draft→in-progress REMOVED per the "A story cannot be implemented while in draft — implementation requires accepted" architecture rule) + criteria-ticked + RFC-closed (in-progress→done) | n/a |
+| Reverse-trace refresh on parents | Inline for problems, JTBDs and legacy RFC files; row-backed RFCs use the map card | Same |
+| Commit grain | One commit per transition / per intake | One commit per capture |
+
+## Related
+
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule** — Problem-RFC-Story framework + Phase 2 amendment 2026-05-10 (story tier).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule lines 248-253** — I6-I11 story-tier invariants.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 252** — I10 INVEST shape (Testable/Valuable/Independent/Estimable; Small SHOULD per architect-amendment-2026-05-10 nitpick N3).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 292** — auto-transition triggers (**amended by the "A story cannot be implemented while in draft — implementation requires accepted" architecture rule**: draft→in-progress REMOVED — a draft story is blocked from implementation by the itil-no-implement-draft-gate; accepted→in-progress on the first implementing commit; in-progress→done on criteria-ticked + RFC-closed).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 339 + the "`@windyroad/*` plugin / skill / agent / hook maturity taxonomy" architecture rule Bootstrapping precedent** — bootstrap-exemption marker contract for the "RFC framework bootstrap journey map" journey map migration retrofit.
+- **the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem** — driver problem ticket.
+- **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes. Primary persona-anchor.
+- **the ": Enforce Governance Without Slowing Down" user outcome** (extended scope) — change-set-level governance composition.
+- **the ": Progress the Backlog While I'm Away" user outcome** — 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.
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — single-commit grain.
+- **the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule** — problem lifecycle conventions; story lifecycle mirrors.
+- **the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule** — governance-skill aside-invocation pattern; lightweight + heavyweight split.
+- **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule** — decision delegation contract.
+- **the "`@windyroad/*` plugin READMEs anchor on JTBD job IDs with load-bearing commit-hook + prose-woven framing" architecture rule** — load-bearing-from-the-start; I7 + I8 + I10 ship on day one.
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default; `<itil-plugin-root>/scripts/test/manage-story.bats` (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 8).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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-codex/manage-story/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Manage Story"
+  short_description: "Manage traced delivery-story lifecycle."

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

@@ -0,0 +1,198 @@
+---
+name: wr-itil:manage-story-map
+description: Heavyweight story-map intake + lifecycle management following the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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 "Problem 062: `manage-problem` does not refresh `docs/problems/README.md` on single-ticket transitions; fast-path cache goes stale silently" problem / the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem contract pattern. Companion to /wr-itil:capture-story-map (lightweight aside surface).
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Manage Story Map Skill
+
+Heavyweight story-map lifecycle management. Mirrors `/wr-itil:manage-story` shape per the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule lightweight + heavyweight split, applied at the story-map tier with HTML encoding.
+
+## Story-Map Lifecycle
+
+Per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule 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 (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule, the story-map schema's `problems:` field) | Hard-block at `/wr-itil:capture-story-map` + re-validated at every transition |
+| **I4** trace-to-JTBD | Every map traces to ≥ 1 JTBD (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule, the story-map schema's `jtbd:` field) | Hard-block at `/wr-itil:capture-story-map` + re-validated at every transition |
+| **I5** no-WSJF-leak | Maps MUST NOT carry WSJF (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule, the no-WSJF-on-maps invariant) | Behavioural test: argument grammar + frontmatter carry no WSJF |
+
+**Bootstrap-exemption marker** per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 339 + the "`@windyroad/*` plugin / skill / agent / hook maturity taxonomy" architecture rule Bootstrapping precedent: the "RFC framework bootstrap journey map" journey map 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 <STORY-MAP-NNN> ratify       # the "A release row is the RFC, and the map is the approval surface" architecture rule: confirm the map — approves every story on it
+/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 | request_user_input (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
+<itil-plugin-root>/bin/wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+<itil-plugin-root>/bin/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, status, reported, decision-makers) — no `adrs`, and `problems`/`rfcs` are DERIVED, so they carry content the island does not. Read backbone structure from the grid's `<th class="act" scope="col">` columns and `<th class="slice" scope="row">` rows.
+
+### 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 request_user_input 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">`** + the "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem 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
+  <itil-plugin-root>/bin/wr-itil-update-problem-references-section "$problem_file" "Story Maps"
+  git add "$problem_file"
+done
+
+# Same for JTBDs via <itil-plugin-root>/bin/wr-itil-update-jtbd-references-section "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.
+
+### 7.5. Ratification flow (`ratify`) — the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule / the "A release row is the RFC, and the map is the approval surface" architecture rule / the ": Ratify the story map and its stories after any change" delivery story
+
+`ratify` is **orthogonal to the status lifecycle** — a map can be ratified at any status. It confirms human oversight of **the map**, and under the "A release row is the RFC, and the map is the approval surface" architecture rule that approves every story on it, including stories added later; stories are never ratified individually. Ratification is **drift-invalidated** (the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule lineage, NOT the ": Human-oversight marker + `/wr-architect:review-decisions` drain for recorded decisions" architecture rule write-once), but only a **substance** edit re-opens it: the map's own substance as the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule defines it — its journey, its identity, and what it traces to. `oversight_map_substance_keys()` is the authoritative field list; this page deliberately does not restate it. Release rows, the cards in them, story-body edits and template restyling all sit outside the fingerprint basis and change nothing. This is the ": Ratify the story map and its stories after any change" delivery story surface.
+
+**Born-confirmed discipline (the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem).** Before any marker write, `export CODEX_THREAD_ID` from the transcript path — the marker shim silently no-ops on an empty SID. Every `confirmed` marker MUST be backed by a same-turn human confirm event; never write `confirmed` without the `request_user_input` below (a hollow marker is the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem bug).
+
+**Ratify the map; its stories follow (the ": Ratify the story map and its stories after any change" delivery story UX, amended by the "A release row is the RFC, and the map is the approval surface" architecture rule):**
+
+1. **Ratify the map.** Present the map's path/URL + a self-contained briefing of what it is — the JTBD it serves, its backbone activities, its release slices — briefing the substance BEFORE any ID (the "agent surfaces decisions to user using opaque IDs (P-numbers, ADR-numbers, JTBD-numbers) without explaining what they mean — empathy gap" problem; the user may be on a device with no repo access). Then `request_user_input` with exactly two options:
+   - **Ratify** — the map is correct as-is.
+   - **(type something)** — free-text; treat the response as a change request, apply it as a map edit, and re-present. Do NOT ratify a map the user just amended — the edit drifts the fingerprint; loop back to re-brief.
+
+   On **Ratify**: run `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed <map-file>` (writes `confirmed` + the fingerprint). The map is now ratified.
+
+2. **Do NOT ratify the stories at all (the "A release row is the RFC, and the map is the approval surface" architecture rule).** Ratifying the map approves every story on it, so there is nothing left to do: no per-story marker, no per-story `request_user_input`, and no oversight field written onto a story. `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed` refuses a story path outright. Test a story's approval with `story_is_approved`, which derives it from the story's `story-maps:` field.
+
+3. **AFK / non-interactive (the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6).** When `request_user_input` is unavailable, do NOT auto-ratify — that would forge a hollow marker (the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem). Leave the artefacts unratified; they surface in the `/wr-itil:work-problems` Step 2.4 drain for the next interactive session.
+
+4. **Single commit** — stage the map + the README refresh; commit per the "Governance Skills Commit Their Own Completed Work" architecture rule. No story file changes: ratifying a map approves its stories without touching them.
+
+**Why the map:** an RFC may reference only approved stories (`<itil-plugin-root>/bin/wr-itil-check-rfc-stories-ratified`), and a story is only meaningful inside its map — which is why the "A release row is the RFC, and the map is the approval surface" architecture rule makes the map the single approval surface rather than ratifying at both tiers.
+
+**Reuse offers approved stories only (the ": Reuse stories already on the map" delivery story).** When decomposing a fix, existing map stories the fix touches are offered for **reuse** — referenced by an additional slice card / `data-story-id`, NOT duplicated as a new file; the reused story's `rfcs:` reverse-trace picks up the new RFC. Only **approved** stories (test with `story_is_approved`, which honours the "A release row is the RFC, and the map is the approval surface" architecture rule map inheritance) are offered for reuse; an unapproved story needs its map ratified (§ 7) before an RFC can reference it.
+
+**Re-slicing does NOT re-open ratification (the ": Slice the fix's stories into releases" delivery story, amended by the "A release row is the RFC, and the map is the approval surface" architecture rule).** Grouping stories into ordered release rows (Release 1 walking skeleton → Release 2 …) is authored as release-row and card edits on the map. **Composing a row asks the two questions in `/wr-itil:capture-story-map` — do these stories NEED to ship together, and SHOULD they — and re-slicing is where the second one usually gets skipped: rows drawn once are rarely re-examined against the cost of delay they now impose.**  deferred phases stay first-class cards (visible, competing for priority), never buried. Rows and cards sit OUTSIDE the fingerprint basis, so re-slicing is silent — scheduling is not what the human approved. What DOES re-open a map's approval: a change to the map's own substance — see `oversight_map_substance_keys()`. *(This sentence enumerated five of the seven keys until 2026-08-08, omitting `storyMapId` and `secondaryPersona`. It is the under-enumeration half of that day's drift: it told a maintainer mid-re-slice that a secondary-persona edit was safe when it re-opens approval.)* The fingerprint handles it either way; no explicit marker reset is needed.
+
+### 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 the "Governance Skills Commit Their Own Completed Work" architecture rule
+
+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 request_user_input 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 (the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem mirror) | Deferred to `manage-story-map review` or `reconcile-story-maps` |
+| Commit grain | One commit per intake / per transition | One commit per capture |
+
+## Related
+
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule** — Problem-RFC-Story framework; Phase 2 amendment 2026-05-10 (story-map frontmatter schema + the I3/I4/I5 invariants) + encoding amendment 2026-05-12.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule**, the no-WSJF-on-maps invariant — I5.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule**, the ordered `stories:` array on an RFC, **+ the "`@windyroad/*` plugin / skill / agent / hook maturity taxonomy" architecture rule** — bootstrap-exemption marker contract.
+
+  (Line-number citations were removed here: they are positional, and the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule has been amended enough times that every one of them pointed at the wrong line.)
+- **`docs/STYLE-GUIDE.md`** — HTML style rules manage-story-map enforces.
+- **the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem** — driver problem ticket.
+- **the ": Decompose a Fix Into Coordinated Changes" user outcome** — primary anchor.
+- **the "Trust That the README Describes the Plugin I Just Installed" user outcome** — 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 request_user_input + no I7/I8/I9/I10 — those are story-tier invariants).
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default; `<itil-plugin-root>/skills/manage-story-map/test/manage-story-map-contract.bats`.
+
+$ARGUMENTS

package/skills-codex/manage-story-map/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Manage Story Map"
+  short_description: "Manage story-map content, lifecycle, and approval."