@windyroad/itil 1.2.0 → 2.0.0-preview.1111

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

@@ -0,0 +1,286 @@
+---
+name: wr-itil:capture-story-map
+description: Lightweight story-map-capture skill for aside-invocation during foreground work — mandatory leading problem-trace AND JTBD-trace per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule I3 + I4 invariants, skeleton HTML file at `docs/story-maps/draft/STORY-MAP-NNN-<slug>.html` per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule § Phase 2 encoding amendment 2026-05-12, single commit per capture, no inline README refresh. Defers full backbone/ribs/slices authoring + lifecycle transitions to /wr-itil:manage-story-map. Use when the user (or agent) wants to capture a new story-map quickly with clear problem + JTBD anchoring.
+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.
+
+
+# Capture Story Map Skill
+
+Capture a story-map (HTML artefact representing Patton's backbone × ribs × slices layout) quickly during foreground work. Lightweight aside-invocation surface that complements the heavyweight `/wr-itil:manage-story-map` flow. Mirrors `/wr-itil:capture-story` shape per the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule lightweight + heavyweight skill split, applied at the story-map tier with HTML encoding.
+
+**Related JTBDs**: the ": Decompose a Fix Into Coordinated Changes" user outcome (primary — Decompose a Fix Into Coordinated Changes; story-maps represent the journey-context decomposition), the ": Enforce Governance Without Slowing Down" user outcome (extended scope), the "Trust That the README Describes the Plugin I Just Installed" user outcome (README-currency rule for `docs/story-maps/README.md`).
+
+## When to invoke
+
+- **Decomposing a problem or RFC into a journey-shaped layout** — agent / user observes that the fix decomposes into multiple coordinated changes that map onto a user-journey backbone × ribs × slices spatial layout (per Patton's User Story Mapping). Capture the story-map BEFORE individual stories so the spatial-placement context informs story decomposition.
+- **Retrospective story-map for shipped work** — lifting an existing multi-commit decomposition into a story-map artefact (e.g. the "RFC framework bootstrap journey map" journey map retro on 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 1 + Phase 2 framework code — Slice 14 of 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).
+- **Cross-RFC journey lens** — a single story-map can reference stories from multiple RFCs (the map is a journey-context lens on the story corpus per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 317).
+
+**Use `/wr-itil:manage-story-map` instead** when:
+- The work is moving an existing story-map through its lifecycle (draft → accepted → in-progress → completed → archived).
+- The user wants to author or refine the backbone/ribs/slices structure with full intake.
+- Cross-map coordination decisions need to be captured.
+
+## Argument grammar
+
+**Positional (both mandatory)**: `<problem-trace> <jtbd-trace> <description>` where:
+- `<problem-trace>` is `P<NNN>` or `P<NNN>,P<NNN>,...`
+- `<jtbd-trace>` is `JTBD-<NNN>` or `JTBD-<NNN>,JTBD-<NNN>,...`
+
+```
+/wr-itil:capture-story-map 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 the ": Decompose a Fix Into Coordinated Changes" user outcome RFC framework Phase 1 + Phase 2 bootstrap
+/wr-itil:capture-story-map 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 the ": Decompose a Fix Into Coordinated Changes" user outcome,the ": Enforce Governance Without Slowing Down" user outcome Story map for 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 RFC framework work
+```
+
+Positional grammar mirrors `/wr-itil:capture-story` shape (footnote per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 285 phrasing — `--problem` / `--jtbd` flag-form was the ADR-exemplar but positional is the lightweight-aside grammar that Codex skills support natively).
+
+## 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 |
+|----------|-----------|-----------------|
+| Problem-trace presence | I3 hard-block — refuse on missing trace; emit deny log + halt | direction-setting |
+| Problem-trace validation | Mechanical: each `P<NNN>` exists in `docs/problems/`; dual-tolerant lookup | silent-mechanical |
+| JTBD-trace presence | I4 hard-block — refuse on missing trace; emit deny log + halt | direction-setting |
+| JTBD-trace validation | Mechanical: each `JTBD-<NNN>` resolves to a file in `docs/jtbd/` | silent-mechanical |
+| STORY-MAP ID allocation | Mechanical: `max(local, origin, history) + 1` enumerating `docs/story-maps/*/STORY-MAP-*.html` (the "AFK orchestrator preflight: get the repo into a clean state before starting" architecture rule inline collision-guard) | silent-mechanical |
+| Title kebab-slug | Mechanical: first 8-10 non-stopword tokens of description | silent-mechanical |
+| Title prose refinement | Optional taste request_user_input; silent-default to derived form | taste |
+| HTML file write | Mechanical: schema per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule § Phase 2 encoding amendment 2026-05-12 lines 381-435 | silent-mechanical |
+| Reverse-trace `## Story Maps` refresh | Mechanical: inline on driving problem + JTBD files via Slice 2a/2b helpers | silent-mechanical |
+| README refresh | Mechanical: deferred to `/wr-itil:manage-story-map review` or `<itil-plugin-root>/bin/wr-itil-reconcile-story-maps` | silent-mechanical |
+| Empty arguments | Halt-with-stderr-directive | n/a |
+
+## Steps
+
+### 0. Preflight
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-readme docs/problems > /tmp/wr-itil-drift-$$.txt
+reconcile_exit=$?
+# Halt-and-route on drift per the standard pattern.
+```
+
+### 1. Parse arguments
+
+```bash
+problem_trace="$1"; shift
+jtbd_trace="$1"; shift
+description="$*"
+```
+
+Validate `$problem_trace` matches `^P[0-9]{3}(,P[0-9]{3})*$`. Validate `$jtbd_trace` matches `^JTBD-[0-9]{3}(,JTBD-[0-9]{3})*$`. If `$description` is empty, halt with empty-arguments directive.
+
+Derive kebab-case title slug from first 8-10 non-stopword tokens of `$description`.
+
+### 2. Validate problem trace + I3 hard-block
+
+For each `P<NNN>`:
+
+```bash
+# Dual-tolerant ticket discovery (the ": docs/problems/ flat layout migration — per-state subdirs + adopter auto-migration" release design migration window).
+trace_files=$(ls docs/problems/<NNN>-*.md docs/problems/*/<NNN>-*.md 2>/dev/null)
+```
+
+**I3 hard-block** (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule, the story-map schema's `problems:` field): trace absent / malformed / unresolved → emit deny log entry to `logs/story-map-capture-denials.jsonl`, halt with stderr directive naming `/wr-itil:capture-problem` as the open-the-driving-problem-first surface.
+
+### 2.5. Validate JTBD trace + I4 hard-block
+
+For each `JTBD-<NNN>`:
+
+```bash
+jtbd_file=$(ls docs/jtbd/*/JTBD-<NNN>-*.md 2>/dev/null | head -1)
+```
+
+**I4 hard-block** (the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule, the story-map schema's `jtbd:` field): trace absent / malformed / unresolved → emit deny log + halt. Story-maps without JTBD trace are structurally meaningless per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule ("a map with no JTBD trace is structurally meaningless"; Patton's central thesis is journey-around-user-value).
+
+### 3. Compute next STORY-MAP ID
+
+Inline `max(local, origin, history) + 1` per the "AFK orchestrator preflight: get the repo into a clean state before starting" architecture rule collision-guard (architect Slice 3 design review option a — inline-only path, mirrors capture-rfc + capture-story precedent). Git history keeps deleted IDs retired without adding tombstone files:
+
+```bash
+local_max=$(ls docs/story-maps/*/STORY-MAP-*.html 2>/dev/null | sed 's|.*/STORY-MAP-||;s|-.*||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+origin_max=$(git ls-tree -r --name-only origin/main docs/story-maps/ 2>/dev/null | sed 's|.*/STORY-MAP-||;s|-.*||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+history_max=$(git log --all --name-only --format= -- docs/story-maps/ 2>/dev/null | sed 's|.*/STORY-MAP-||;s|-.*||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+next=$(printf '%03d' $(( 10#$(printf '%s\n' "${local_max:-0}" "${origin_max:-0}" "${history_max:-0}" | sort -n | tail -1) + 1 )))
+```
+
+### 4. Optional taste prompt for title
+
+Same shape as capture-story Step 4 — silent-default when unavailable.
+
+### 5. Write the story-map JSON, then render it
+
+**NEVER hand-write the HTML, and NEVER open an existing map to copy its shape.** Both maps and template drifted together once already: every map in the corpus became a vertical stack of headings — no journey columns, no release rows, no cells — because each new map was cloned from the last. The renderer owns the shape so that cannot recur.
+
+**A map is ONE file**: `docs/story-maps/draft/STORY-MAP-<NNN>-<kebab-title>.html`. Its data lives inside it, in a `<script id="story-map-data" type="application/json">` island. The renderer rewrites the presentation around that island. There is no separate source file to fall out of step with the rendered map, and the file a reader opens is the file an author edits.
+
+**There is one command and one mode.** To CREATE a map, write a file containing nothing but the data island, then render it — the renderer fills in everything around it:
+
+```bash
+# Write docs/story-maps/draft/STORY-MAP-<NNN>-<kebab-title>.html containing only:
+#   <script id="story-map-data" type="application/json">
+#   { ...the map data... }
+#   </script>
+<itil-plugin-root>/bin/wr-itil-render-story-map docs/story-maps/draft/STORY-MAP-<NNN>-<kebab-title>.html
+```
+
+**To CHANGE a map**, edit the data island in that same file and run the same command again. Creation and editing are the same operation, so there is no seed file to clean up and no bootstrap mode. Re-rendering is idempotent. Never edit the grid, the `<style>` block, or the `<meta>` block by hand — they are regenerated from the island, and a hand-edit outside it is discarded on the next render.
+
+**What a story map is.** A grid, not a list. Backbone activities are COLUMNS across the top and form the user's journey left to right. Release slices are ROWS. Task cards sit in the cells. A row read left to right is everything that ships together — that is the whole point of the artefact, and it is what a vertical stack cannot express.
+
+**JSON shape:**
+
+Extracted verbatim by `test/documented-island-renders.bats` — editing which keys
+appear here changes what that test asserts, and that binding is deliberate.
+
+<!-- documented-island:begin -->
+```json
+{
+  "storyMapId": "STORY-MAP-<NNN>",
+  "title": "<Title>",
+  "status": "draft",
+  "persona": "<persona>",
+  "reported": "<YYYY-MM-DD>",
+  "decisionMakers": "<git config user.name>",
+  "traces": { "jtbd": ["JTBD-<NNN>"] },
+  "backbone": [
+    { "id": "<slug>", "title": "A. <Activity>", "note": "<optional JTBD or gloss>" }
+  ],
+  "releases": [
+    { "id": "rfc-<nnn>", "name": "<what this release delivers>", "rfc": "RFC-<NNN>", "note": "<optional>" }
+  ],
+  "tasks": [
+    {
+      "activity": "<backbone id>", "release": "<release id>",
+      "title": "<what the persona can do>",
+      "storyId": "STORY-<NNN>", "rfc": "RFC-<NNN>", "jtbd": "JTBD-<NNN>",
+      "ref": "STORY-<NNN>, P<NNN>"
+    }
+  ]
+}
+```
+<!-- documented-island:end -->
+
+**Authoring rules:**
+
+- **The backbone must be a journey, not a list of invariants.** Activities are steps the persona walks through in sequence. "Finish a change → get it assessed → push it → get through CI → release it" is a backbone. "Leave no unscored way out", "score this change not the last one" are invariants, and a column of them is not a map.
+- At capture a map may legitimately have **columns and rows but empty cells**. That is the honest state of unbuilt work, and the renderer says so in place — a wholly empty band carries its own sentence. Do not add prose at the top explaining it.
+- **Composing a row asks two questions, in order.** A row is a release, so putting two stories in one is a claim that they ship together. Answer both before drawing it.
+
+  **1. Do they NEED to ship together?** Coupling. Is either broken, meaningless or misleading on its own? A migration and the code that depends on it need one row. Two fixes that merely arrived in the same conversation do not. *Absence of a dependency is not a reason to bundle* — it is the reason not to.
+
+  **2. SHOULD they ship together?** Economics, and this is the question that gets skipped. Batching imposes the delay of the slowest story on everything in the batch. It buys something back only when each release costs a lot to perform — so weigh the holding cost against the per-release transaction cost:
+
+  - **Producer-side cost is usually near zero here**: release is automated on merge, and this repo has shipped three times in a day. When transaction cost approaches zero the optimal batch approaches one, and bundling is pure loss.
+  - **Adopter-side cost is not zero.** Every release asks an adopter to upgrade, and upgrading has known friction. That is the real argument for a larger batch.
+  - **Watch for the story that REDUCES that cost.** It ships first and alone. Queueing your transaction-cost reducer behind other work is the expensive mistake, because it makes every later release cheaper — attack the cost, then the batch size falls out.
+  - **Cost of delay is per persona, not per story.** A gate blocking most adopters today outweighs an intermittent failure that bites across an upgrade. Name who waits, and what waiting costs each of them, before deciding the row.
+  - **Check the package boundary.** Stories in packages that version independently cannot share a release the tooling will actually produce; a row spanning them claims something no changeset emits.
+
+  The default is one story per row. Two stories share a row when the answer to question 1 is yes, or when question 2 shows a transaction cost high enough to pay for the delay. Neither is assumed.
+
+- **A row IS an RFC (the "A release row is the RFC, and the map is the approval surface" architecture rule).** A row a problem has proposed carries its `rfc`; drawing the row is what allocates the identity. There is no separate "not yet allocated" state and no `badge` field — a row's status is derived from its stories, and its label is its RFC id.
+- **Every row carries an identity, and finishing one earns no exemption (the "A story map's RFC list is derived from its release rows" architecture rule).** A row with no `rfc` renders as a defect — a red "Untraced" badge — whether or not its stories are done. Delivery cannot excuse a missing identity, because every row is delivered eventually; that reading would let work nobody proposed become legitimate by being finished.
+
+  The only exception is a row holding work that shipped **before rows carried identities**, and such a row says so explicitly with `"preRfc": true`. That set is closed. Do not add the marker to a new row: it is a statement about history, not a way to skip allocating an RFC. It appears in no example above because a row that has an `rfc` does not need it, and the example shows the normal case.
+- **A map carries no `traces.rfcs` (the "A story map's RFC list is derived from its release rows" architecture rule).** The map's RFC list is the union of its row identities, so authoring it restates the rows and drifts from them the moment one changes.
+- `storyId` / `rfc` / `jtbd` are optional per task and emit the `data-*` reference layer that reverse-trace and the story-map queries consume. Omit them until stories exist; add them as stories are captured onto the map.
+- **Author nothing a story file already says (the "A story map card stores no value a story file already carries" architecture rule).** A story's lifecycle state, its value statement, and the problems it closes are all read from the story when the map renders — so a transition needs no map edit and does not re-open the map's ratification. There are no `storyStatus`, `value` or row-level `problems` fields, and no `--status` or `--value` flags. A row's problems are the union of its stories'; a map's are the union of its rows'.
+- **A map carries no decision trace (the "A story map carries no decision trace" architecture rule).** There is no `traces.adrs`. A decision constrains how something is built, and the thing built is the story — so a decision reference belongs on the story (`adrs:` in its frontmatter), not on the lens drawn over it.
+- **Write no prose the grid already carries.** There is no `lead` and no `traceProse`. A map is a title, a grid, and the jobs it is drawn for. Where a column or a row needs a note, both carry a `note` field — put it next to the thing it describes, not in a paragraph at the top restating the picture below it. Six kinds of duplication were removed from this format for exactly this reason; the seventh will be whatever gets added back.
+- **Prefer the edit command over hand-editing the island** for structural changes — it validates against the map's own backbone and bands, names what is available when you get an id wrong, and leaves the file untouched on failure:
+
+```bash
+<itil-plugin-root>/bin/wr-itil-story-map-edit <map.html> add-card     --story STORY-<NNN> --activity <id> --release <id> --title "..." [--ref "..."]
+<itil-plugin-root>/bin/wr-itil-story-map-edit <map.html> move-card    --story STORY-<NNN> [--activity <id>] [--release <id>]
+<itil-plugin-root>/bin/wr-itil-story-map-edit <map.html> remove-card  --story STORY-<NNN>
+<itil-plugin-root>/bin/wr-itil-story-map-edit <map.html> add-band     --id <id> --name "..." [--rfc RFC-<NNN>] [--note "..."]
+<itil-plugin-root>/bin/wr-itil-story-map-edit <map.html> add-activity --id <id> --title "..." [--note "..."]
+```
+
+Hand-editing the island still works — the renderer reads whatever is there — but the command is the safer path and the one to reach for by default.
+- Every task needs `activity` and `release` matching an `id` in `backbone` / `releases`, or it renders nowhere.
+- Presentation is not yours to set. There is no CSS in the JSON and no inline `style` anywhere; the template is the only styling source.
+- Escape a literal `<` in any string as `\\u003c`. A raw `</script>` inside the island terminates the block early — in the renderer and in a browser — and the renderer will refuse the file rather than emit a truncated map.
+
+**Born unconfirmed (the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule).** Do NOT author `humanOversight` at all: the renderer treats an absent field as `unconfirmed`, so writing it is writing the default, and the field exists so that `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed` can set `confirmed` — which an agent must never hand-write (the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem). The `<meta name="human-oversight">` tag is a projection the renderer regenerates from the island; never author it directly (the "Story maps render from JSON through a canonical template" architecture rule). The map is NOT ratified until a human confirms it via `/wr-itil:manage-story-map <NNN> ratify`, which writes `confirmed` + an `oversight-hash` fingerprint through `<itil-plugin-root>/bin/wr-itil-mark-story-oversight-confirmed`. Until then `<itil-plugin-root>/bin/wr-itil-detect-unratified-stories-maps` surfaces it and an RFC may not reference its stories (`<itil-plugin-root>/bin/wr-itil-check-rfc-stories-ratified`).
+
+**What re-opens ratification, and what does not (the "A release row is the RFC, and the map is the approval surface" architecture rule).** A later edit to the map's SUBSTANCE — 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 field list — drifts the fingerprint and silently re-opens ratification. Release rows and the cards in them sit OUTSIDE the basis, so drawing a row or adding a story to one changes nothing. Presentation is outside it too: restyling the shared template cannot revoke an approval. Do NOT hand-write `confirmed` — born-unconfirmed is the load-bearing default.
+
+### 6. Single commit — `## Story Maps` reverse-trace refresh
+
+**Stage list**: the map `.html` (it carries its own data island) AND, on a repository's first map, the shared `docs/story-maps/story-map.css` the renderer places beside them, PLUS driving problem files (refresh `## Story Maps` section via `update-problem-references-section.sh <file> "Story Maps"`) PLUS driving JTBD files (refresh `## Story Maps` section via `update-jtbd-references-section.sh <file> "Story Maps"`). Do NOT stage `docs/story-maps/README.md` (deferred).
+
+```bash
+for pid_token in $(echo "$problem_trace" | tr ',' ' '); 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
+
+for jid_token in $(echo "$jtbd_trace" | tr ',' ' '); do
+  jtbd_file=$(ls docs/jtbd/*/${jid_token}-*.md 2>/dev/null | head -1)
+  [ -z "$jtbd_file" ] && continue
+  <itil-plugin-root>/bin/wr-itil-update-jtbd-references-section "$jtbd_file" "Story Maps"
+  git add "$jtbd_file"
+done
+
+git add docs/story-maps/draft/STORY-MAP-<NNN>-<slug>.html
+```
+
+Commit message:
+
+```
+feat(itil): capture STORY-MAP-<NNN> <title>
+
+Refs: STORY-MAP-<NNN>
+```
+
+### 7. Report
+
+After commit, report:
+- New story-map file path + ID.
+- Traced problems + JTBDs.
+- Trailing pointer: `Run /wr-itil:manage-story-map <STORY-MAP-<NNN>> next to author backbone/ribs/slices structure and advance draft → accepted; refresh docs/story-maps/README.md.`
+
+## Composition with manage-story-map
+
+| Concern | manage-story-map | capture-story-map |
+|---------|------------------|-------------------|
+| I3 + I4 enforcement | Re-validated at every lifecycle transition | Hard-block at capture-time |
+| I5 no-WSJF-leak | Behavioural test asserts no WSJF field at every transition | Already absent at capture (frontmatter has no WSJF) |
+| Backbone/ribs/slices authoring | Step 7-9 author the spatial layout | Deferred-placeholder pattern; one rib placeholder only |
+| Status transitions | draft → accepted → in-progress → completed → archived | Out of scope (creation only) |
+| README refresh | Inline per transition | Deferred to `/wr-itil:manage-story-map review` or `<itil-plugin-root>/bin/wr-itil-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 + encoding amendment 2026-05-12.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule lines 145-189** — story-map tier spec + I3-I5 invariants.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule lines 381-435** — HTML encoding schema (the source-of-truth for the file template).
+- **`docs/STYLE-GUIDE.md`** — story-map HTML style rules (prohibited inline `style=""` on data-bearing elements).
+- **`docs/VOICE-AND-TONE.md`** — story-map prose guidance (HTML content section).
+- **`docs/story-maps/README.md`** — story-map tier lifecycle index + schema spec.
+- **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 "Trust That the README Describes the Plugin I Just Installed" user outcome** — Trust That the README Describes the Plugin I Just Installed (README-currency rule for `docs/story-maps/README.md`).
+- **the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule** — governance-skill aside-invocation pattern.
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — bin/ on PATH; `<itil-plugin-root>/bin/wr-itil-reconcile-story-maps` shim ships in Slice 5.
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default. Bats at `<itil-plugin-root>/skills/capture-story-map/test/capture-story-map-behavioural.bats`.
+- **Capture-story precedent** — `<itil-plugin-root>/skills/capture-story/SKILL.md` — sibling skill at the story tier; capture-story-map mirrors with story-map-tier extensions (HTML encoding, no optional --rfc / --story-map flags).
+
+$ARGUMENTS

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Capture Story Map"
+  short_description: "Capture an approved journey map for delivery planning."

package/skills-codex/check-upstream-responses/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: wr-itil:check-upstream-responses
+description: Poll upstream issues and pull requests we've filed via `/wr-itil:report-upstream` and surface new comments or reviews, state changes, or label changes since last check. Reads `## Reported Upstream` back-link sections in local problem tickets, queries GitHub read-only, diffs against `docs/problems/.outbound-responses-cache.json`, and appends an audit-log entry to `docs/audits/outbound-responses-log.md`. Outbound symmetric counterpart to the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule's inbound discovery pipeline (the "No process for issue reporters to check for responses — symmetric gap to inbound discovery" problem Phase 1).
+allowed-tools: Read, Edit, Write, Bash, Glob, Grep
+---
+
+<!-- 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.
+
+
+# Check Upstream Responses — Outbound Response-Check Skill
+
+Poll the upstream issues we have filed via `/wr-itil:report-upstream` and surface new responses (comments, state changes, label changes) since the last check. This skill closes the outbound half of the feedback loop that the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule's inbound assessment pipeline opens — together they form the bidirectional cross-repo coordination surface the ": Connect Agents Across Repos to Collaborate" user outcome names.
+
+This is **Phase 1** of the "No process for issue reporters to check for responses — symmetric gap to inbound discovery" problem. Phase 1 covers the **us-as-upstream-reporter** half (we polling our own filed-upstream reports). Phase 2 — the external-reporter-as-our-reporter half (plugin users polling responses to reports they filed against this repo) — is deferred to a separate iter.
+
+## Scope
+
+In scope:
+- Scan `docs/problems/**/*.md` for `## Reported Upstream` back-link sections (the contract section written by `/wr-itil:report-upstream` Step 7 — see [the "Cross-project problem-reporting contract — `report-upstream` skill in `@windyroad/itil`" architecture rule](../../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) Step 7).
+- For each ticket with a back-link, extract the `- **URL**:` line and poll the upstream artefact. Read the `- **Disclosure path**:` line to pick the subcommand: any pull-request path uses `gh pr view` plus a read-only `gh api` call for inline review comments; anything else, **including an absent line**, uses `gh issue view`. Absent means a ticket written before the "Prefer an upstream pull request over an issue when the upstream accepts pull requests" architecture rule, which could only have been filed as a public issue — so it is read as an issue, with no probe.
+- Diff against `docs/problems/.outbound-responses-cache.json` (cache file mirroring the inbound `.upstream-cache.json` shape per the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule § "Cache files live under docs/problems/").
+- Surface five response classes: NEW (new comments, reviews, or other upstream activity), STATE (state change), LABEL (label change), NONE (no change), FAIL (gh poll error).
+- Update the cache file with the latest seen state.
+- Append a timestamped pass entry to `docs/audits/outbound-responses-log.md` (audit-log mirroring `docs/audits/inbound-discovery-log.md` per the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule's audit-log surface contract).
+
+Out of scope:
+- Posting comments back to the upstream issue or pull request. The skill is **read-only externally** — does not trip the "External-comms gate — voice-tone + risk/leak evaluators on shared PreToolUse surface" architecture rule's external-comms gate.
+- Auto-transitioning local ticket lifecycle based on upstream state change (that is the "Problem 080: No bidirectional update of upstream-reported problems — local lifecycle transitions never propagate back to the reporter" problem's bidirectional update axis, separate).
+- Polling against the inbound-discovery channels (`docs/problems/.upstream-channels.json`). That is the inverse axis, owned by `/wr-itil:review-problems` Step 4.5 per the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule.
+- Phase 2 external-reporter-as-our-reporter surface (deferred).
+
+## Invocation
+
+```
+/wr-itil:check-upstream-responses
+  [--problems-dir <dir>]   default: docs/problems
+  [--cache-file <path>]    default: <problems-dir>/.outbound-responses-cache.json
+  [--audit-log <path>]     default: docs/audits/outbound-responses-log.md
+  [--ticket P<NNN>]        restrict polling to one ticket
+  [--force-recheck]        ignore cache; treat all as new
+```
+
+`/wr-itil:work-problems` Step 0d pre-flights this skill when the outbound-responses cache is stale or missing AND back-link tickets exist (sibling to Step 0b inbound cache check per the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule Confirmation #5; the "manage-problem has no cadence for checking upstream-bound tickets" problem closed the cadence gap). Direct user invocation remains a first-class surface.
+
+## AFK behaviour
+
+This skill is **AFK-safe by construction**:
+
+- Read-only `gh issue view`, `gh pr view`, and pull-request review-comment `gh api` calls — none fires the "External-comms gate — voice-tone + risk/leak evaluators on shared PreToolUse surface" architecture rule's external-comms gate.
+- No `request_user_input` calls — five flag-based knobs (`--problems-dir`, `--cache-file`, `--audit-log`, `--ticket`, `--force-recheck`) are the user-direction surface per CLAUDE.md `act on obvious, request_user_input for ambiguous, NEVER prose-ask` (the "Problem 085: Assistant asks for input when the next step is obvious, AND uses prose asks instead of request_user_input when input is actually needed" problem).
+- Partial-failure exit code (2) lets AFK orchestrators distinguish "some upstream URLs were unreachable" from "everything broke" without halting the loop.
+
+## Steps
+
+### 1. Run the diagnose+act script
+
+Invoke the helper:
+
+```bash
+<itil-plugin-root>/bin/wr-itil-check-upstream-responses
+```
+
+The `<itil-plugin-root>/bin/wr-itil-check-upstream-responses` command is a `$PATH`-resolved shim shipped in `<itil-plugin-root>/bin/` that dispatches the canonical `<itil-plugin-root>/scripts/check-upstream-responses.sh` body. Per [the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule](../../../../docs/decisions/049-plugin-script-resolution-via-bin-on-path.proposed.md) — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
+The script:
+
+1. Walks `<problems-dir>` (both flat layout `<NNN>-*.<state>.md` AND per-state subdir layout `<state>/<NNN>-*.md` per the ": docs/problems/ flat layout migration — per-state subdirs + adopter auto-migration" release design dual-tolerant migration).
+2. For each ticket file, extracts the `## Reported Upstream` URL line. Tickets without that section are silently skipped.
+3. For each URL, calls `gh issue view --json comments,state,labels,updatedAt` or `gh pr view --json comments,reviews,state,labels,updatedAt` (chosen by the disclosure path). Pull requests also fetch inline review comments through `gh api`. The response count and response-specific timestamp combine all three response surfaces; parent metadata changes do not masquerade as review activity. A merged pull request reports `state=MERGED`, distinct from `CLOSED`, so a rejected one is not recorded as a resolution.
+4. Compares the response against the cached entry for that ticket and emits one of: NEW / STATE / LABEL / NONE / FAIL.
+5. Updates the cache file and appends an audit-log entry.
+
+Exit codes:
+
+- `0` — success. Cache and audit-log have been updated. Per-ticket lines printed to stdout.
+- `1` — error (problems-dir missing, malformed cache, malformed CLI args, jq missing).
+- `2` — partial. Some upstream polls failed; the successful ones are still written to cache + audit-log.
+
+### 2. Summarise the response classes inline
+
+Read the stdout output and summarise the response classes in chat for the user. The audit-log is the durable surface — the agent's inline summary is the in-session affordance. Do NOT re-dump the full stdout; lead with the most-important classes:
+
+- STATE changes (upstream state OPEN → CLOSED / REOPENED) — most actionable; usually a verification signal.
+- NEW responses or activity — second-most actionable; may carry comments, reviews, inline review comments, follow-up questions, or fix confirmation. A zero response delta means an existing response was edited.
+- LABEL changes — informational; signals maintainer triage activity.
+- NONE — quiet; only mention the count, not each ticket.
+- FAIL — call out per-ticket reasons so the user can investigate (URL changed, repo renamed, auth issue).
+
+### 3. Commit per the "Governance Skills Commit Their Own Completed Work" architecture rule
+
+The cache file and audit-log file ride a single commit:
+
+```bash
+git add docs/problems/.outbound-responses-cache.json docs/audits/outbound-responses-log.md
+git commit -m "chore(problems): check upstream responses — <N> polled, <M> new"
+```
+
+See [the "Governance Skills Commit Their Own Completed Work" architecture rule](../../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md) commit-message-convention table for the canonical row.
+
+If the cumulative pipeline risk lands above appetite and `request_user_input` is unavailable, apply the [the "Structured User Interaction for Governance-Skill Decisions" architecture rule](../../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) Rule 6 non-interactive fail-safe: skip the commit and report the uncommitted state.
+
+## When invoked
+
+Three invocation surfaces:
+
+1. **Direct user invocation** — `/wr-itil:check-upstream-responses` (or with flags). The default user-facing surface.
+2. **AFK orchestrator pre-flight** — `/wr-itil:work-problems` Step 0d invokes this skill when the outbound-responses cache is stale, missing, or has `last_checked: null` AND back-link tickets exist, mirroring Step 0b's inbound staleness check per the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule Confirmation #5. Cache TTL defaults to 86400s (24h) symmetric with the inbound axis. the "manage-problem has no cadence for checking upstream-bound tickets" problem closed the cadence gap.
+3. **Manual investigation during a problem-management session** — when a maintainer wants to see if any upstream reports moved before transitioning a `verifying` ticket back to `closed`. Foreground synchronous; the maintainer reads the inline summary and decides next steps.
+
+## Confirmation
+
+<!-- OUTBOUND-RESPONSES-STALENESS-CONTRACT-SOURCE: <itil-plugin-root>/skills/check-upstream-responses/SKILL.md ## Confirmation -->
+
+This skill's contract holds when:
+
+1. The script `<itil-plugin-root>/scripts/check-upstream-responses.sh` is read-only externally — `gh issue view`, `gh pr view`, and a pull-request review-comment `gh api` read only; it makes no comment, create, edit, close, or write API call.
+2. The script extracts the URL from `## Reported Upstream` sections matching the format `- **URL**: <url>` per the "Cross-project problem-reporting contract — `report-upstream` skill in `@windyroad/itil`" architecture rule Step 7's back-link contract.
+3. After a successful pass, the cache file exists, is valid JSON, and contains a `tickets.<P<NNN>>` entry for every polled ticket.
+4. After a successful pass, the audit-log file exists and has a new `## YYYY-MM-DDTHH:MM:SSZ` heading appended.
+5. The skill is AFK-safe: zero `request_user_input` calls, zero external-comms gate triggers.
+6. The exit code distinguishes success (0), error (1), and partial failure (2) so AFK orchestrators can branch correctly.
+7. **Staleness contract (the "manage-problem has no cadence for checking upstream-bound tickets" problem)**: TTL defaults to 86400s (24h) symmetric with the inbound axis. Override via `ttl_seconds` field in the cache file. The Step 0d pre-flight helper at `<itil-plugin-root>/lib/check-outbound-responses-staleness.sh` MUST stay symmetric with this contract — any change to TTL semantics MUST update the helper, the Step 0d SKILL block in `/wr-itil:work-problems`, and this Confirmation #7 in the same commit.
+
+## ADR alignment
+
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — governance skills commit their own work. Cache file + audit-log ride a single commit per pass. the "Governance Skills Commit Their Own Completed Work" architecture rule's commit-message-convention table is amended in the same commit as this skill ships to add the canonical row.
+- **the "Cross-project problem-reporting contract — `report-upstream` skill in `@windyroad/itil`" architecture rule** — cross-project problem-reporting contract. The `## Reported Upstream` back-link section (Step 7) is the source of truth this skill reads. the "Cross-project problem-reporting contract — `report-upstream` skill in `@windyroad/itil`" architecture rule's Confirmation section is amended in the same commit to record that the back-link section's URL field is now a load-bearing contract surface for two skills (one writes, one reads).
+- **the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule** — problem-ticket directory layout. Cache file lives under `docs/problems/` per the same precedent that placed `.upstream-cache.json` and `.upstream-channels.json` there for the inbound axis.
+- **the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule** — governance skill invocation patterns. Foreground synchronous; no subagent dispatch needed.
+- **the "Skill testing strategy — contract-assertion bats companion to" architecture rule** — skill testing strategy. Behavioural bats at `<itil-plugin-root>/scripts/test/check-upstream-responses.bats` (script-level) covers the contract.
+- **the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule** — progressive disclosure. Per-row stdout output ≤ 150 bytes; the agent expands per-ticket detail on demand.
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — bin shim. Script invoked as `<itil-plugin-root>/bin/wr-itil-check-upstream-responses`, not via repo-relative `bash <path>`.
+- **the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule** — inbound upstream-report discovery + assessment pipeline. This skill is the outbound symmetric counterpart; the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule `## Related` is amended in the same commit to forward-point at this skill.
+
+## Related
+
+- `<itil-plugin-root>/scripts/check-upstream-responses.sh` — the diagnose+act script body.
+- `<itil-plugin-root>/scripts/test/check-upstream-responses.bats` — behavioural bats covering the script contract.
+- `<itil-plugin-root>/skills/report-upstream/SKILL.md` — the writer of the `## Reported Upstream` section this skill reads.
+- `<itil-plugin-root>/skills/review-problems/SKILL.md` — the inbound axis sibling (Step 4.5 inbound-discovery pass per the "Inbound upstream-report discovery + assessment pipeline (peer of )" architecture rule).
+- `docs/audits/inbound-discovery-log.md` — inbound audit-log; symmetric peer of `docs/audits/outbound-responses-log.md`.
+- `docs/problems/.upstream-cache.json` — inbound cache; symmetric peer of `docs/problems/.outbound-responses-cache.json`.
+- `docs/decisions/024-cross-project-problem-reporting-contract.proposed.md` — outbound contract; back-link section is the source of truth.
+- `docs/decisions/062-inbound-upstream-report-discovery-assessment-pipeline.proposed.md` — inbound discovery; this skill is the outbound counterpart.
+- **the "No process for issue reporters to check for responses — symmetric gap to inbound discovery" problem** (`docs/problems/open/249-no-process-for-reporters-to-check-for-responses-symmetric-to-inbound-discovery.md`) — driver ticket. Phase 1 (us-as-upstream-reporter) ships here; Phase 2 (external-reporter-as-our-reporter) deferred.
+- **the "Problem 080: No bidirectional update of upstream-reported problems — local lifecycle transitions never propagate back to the reporter" problem** (`docs/problems/open/080-no-bidirectional-update-of-upstream-reported-problems.md`) — inverse axis (we push local status BACK to upstream issues we ingested). Composes with this skill.
+- **the "Inbound-discovery ack comments are bureaucratic, not verdict-shaped ( violation)" problem** — inbound discovery ack-comment shape gap (verdict-shaped acks). Inverse-shape sibling on the inbound axis.
+- **the ": Connect Agents Across Repos to Collaborate" user outcome** — Connect Agents Across Repos to Collaborate (primary anchor).
+- **the ": Progress the Backlog While I'm Away" user outcome** — Progress the Backlog While I'm Away (AFK-safe).
+- **the ": Enforce Governance Without Slowing Down" user outcome** — Enforce Governance Without Slowing Down (eliminates manual upstream polling).
+- **the "Restore Service Fast with an Audit Trail" user outcome** — Restore Service Fast with an Audit Trail (audit-log replay).
+- **the "Run Pre-Flight Governance Checks Before Release or Handover" user outcome** — Run Pre-Flight Governance Checks Before Release or Handover (state-change signals before retro / release).

package/skills-codex/check-upstream-responses/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Check Upstream Responses"
+  short_description: "Poll reported upstream issues and pull requests."