@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills-codex/list-stories/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: wr-itil:list-stories
+description: List INVEST-shaped story tickets from docs/stories/ as a markdown table. Read-only display — no edits, no interaction. Optional `--rfc RFC-<NNN>` filter to surface a specific RFC's ordered story list per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 2.
+allowed-tools: Read, 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.
+
+
+# List Stories
+
+Display the story corpus from `docs/stories/` as a markdown table. Read-only view of the story tier per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 2; this skill does not edit, transition, close, or create stories. For those operations, use the dedicated skills (`/wr-itil:capture-story`, `/wr-itil:manage-story`).
+
+Mirrors the `/wr-itil:list-problems` precedent (the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem phased-landing split per the "Rename `wr-problem` Plugin to `wr-itil`" architecture rule amended Skill Granularity rule: one skill per distinct user intent). The list-stories surface separates the read-only view from the heavyweight `/wr-itil:manage-story list` subcommand route (which is itself a candidate for phased-landing split in a future slice).
+
+## Scope
+
+Stories live under `docs/stories/<state>/STORY-<NNN>-<slug>.md` in lifecycle subdirectories:
+
+- `docs/stories/draft/*.md` — draft (captured via `/wr-itil:capture-story`; pre-INVEST-acceptance)
+- `docs/stories/accepted/*.md` — accepted (INVEST-shape verified per I10; pre-implementation)
+- `docs/stories/in-progress/*.md` — in-progress (implementation underway; auto-transitioned from accepted on first `Refs: STORY-<NNN>` commit AFTER the capture commit per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 292)
+- `docs/stories/done/*.md` — done (acceptance-criteria all-ticked + linked RFC closes; auto-transitioned from in-progress)
+- `docs/stories/archived/*.md` — archived (closed without completion; manual transition)
+
+Per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule I11 invariant (Phase 2 deferred): stories MUST NOT carry a WSJF field. Legacy RFC files retain their ordered frontmatter `stories:` array. Under the "A release row is the RFC, and the map is the approval surface" architecture rule, newer RFCs are release rows and their story sequence comes from the row's cards on the map, NOT from per-story WSJF.
+
+## Argument grammar
+
+**Positional (optional)**: `--rfc RFC-<NNN>` flag-style filter. When provided, the display lists ONLY stories that trace to the named RFC, IN THE ORDER specified by the RFC's frontmatter `stories:` array per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 259. Without the flag, all stories across all lifecycle states are listed grouped by state.
+
+```
+/wr-itil:list-stories                    # All stories, grouped by lifecycle state
+/wr-itil:list-stories --rfc the ": docs/problems/ flat layout migration — per-state subdirs + adopter auto-migration" release design      # Only stories under the ": docs/problems/ flat layout migration — per-state subdirs + adopter auto-migration" release design, in execution order
+```
+
+## Steps
+
+### 1. Check `docs/stories/README.md` cache freshness
+
+Reuse the same `git log`-based freshness test as `/wr-itil:list-problems` Step 1 (per the "Problem 031: `manage-problem work` incorrectly determines cache is fresh" problem — filesystem mtime is unreliable in worktrees and fresh checkouts):
+
+```bash
+readme_commit=$(git log -1 --format=%H -- docs/stories/README.md 2>/dev/null)
+if [ -z "$readme_commit" ] || \
+   git log --oneline "${readme_commit}..HEAD" -- 'docs/stories/*/*.md' ':!docs/stories/README.md' 2>/dev/null | grep -q .; then
+  echo "stale"
+fi
+```
+
+**Cache fresh** (no output AND no `--rfc` filter): read `docs/stories/README.md` directly — display the Story Rankings section + Done section as-is. Note in the output: "Using cached ranking from [timestamp in README.md]".
+
+**Cache stale OR `--rfc` filter provided OR `README.md` missing**: run the live scan in Step 2. (The filter case always live-scans because the README cache is whole-corpus ranking, not a per-RFC filtered view.)
+
+### 2. Live scan (cache-stale fallback OR filter mode)
+
+**Unfiltered live scan** — enumerate every state directory:
+
+```bash
+ls docs/stories/draft/*.md docs/stories/accepted/*.md docs/stories/in-progress/*.md docs/stories/done/*.md docs/stories/archived/*.md 2>/dev/null
+```
+
+For each story file, parse the YAML frontmatter to extract: `story-id`, `status`, `problems`, `jtbd`, `rfcs`, `story-maps`, `estimated-effort`. Read the H1 line for the title.
+
+**Filtered live scan** (`--rfc RFC-<NNN>` provided) — resolve a legacy RFC file first; if absent, resolve the release row through the canonical map query:
+
+```bash
+shopt -s nullglob
+rfc_files=(docs/rfcs/RFC-<NNN>-*.md)
+rfc_file="${rfc_files[0]:-}"
+shopt -u nullglob
+
+if [ -n "$rfc_file" ]; then
+  stories_list=$(awk '/^stories:/,/^[a-z]/' "$rfc_file" | grep -oE 'STORY-[0-9]+')
+else
+  rfc_rows=$(<itil-plugin-root>/bin/wr-itil-story-map-query find-rfc RFC-<NNN>)
+  [ "$rfc_rows" = "[]" ] && echo "RFC-<NNN> not found" >&2 && exit 1
+  stories_list=$(grep -oE 'STORY-[0-9]+' <<< "$rfc_rows" | awk '!seen[$0]++')
+fi
+```
+
+For each `STORY-<NNN>` in the ordered list, resolve to a file under `docs/stories/*/STORY-<NNN>-*.md` and parse the frontmatter as above. Preserve the legacy array or map-row card ordering in the output.
+
+### 3. Display
+
+**Unfiltered mode** — render lifecycle-grouped sections:
+
+```markdown
+## Draft
+
+| ID | Title | Problems | JTBD | RFCs | Story Maps |
+|----|-------|----------|------|------|------------|
+| STORY-<NNN> | <title> | <P<NNN>...> | <JTBD-<NNN>...> | <RFC-<NNN>...> | <STORY-MAP-<NNN>...> |
+
+## Accepted
+
+| ID | Title | Problems | JTBD | RFCs | Story Maps | Effort | Accepted by |
+|----|-------|----------|------|------|------------|--------|-------------|
+...
+
+## In Progress
+
+(same shape as Accepted)
+
+## Done
+
+| ID | Title | Done date | Driving problems |
+|----|-------|-----------|------------------|
+...
+```
+
+Omit empty sections rather than rendering empty headers. The Estimated Effort column is omitted from the Draft section because effort is deferred at capture and only required at accepted per I10 INVEST Estimable.
+
+**The `Approved by` column (the "A release row is the RFC, and the map is the approval surface" architecture rule, Accepted + In Progress sections only).** A story carries no oversight field; approval is its map's. Name the ratified map that approves it, since that is what the human actually looked at, and leave the column empty when no map in the story's `story-maps:` field is ratified. Derive it with `story_is_approved` — never by reading a `human-oversight:` line off the story, which no longer exists.
+
+**Filtered mode** (`--rfc RFC-<NNN>`) — render a single ordered table:
+
+```markdown
+## Stories under RFC-<NNN>
+
+(In execution order per RFC frontmatter `stories:` array.)
+
+| Order | ID | Title | Status | Effort |
+|-------|----|-------|--------|--------|
+| 1 | STORY-<NNN> | <title> | <status> | <effort> |
+| 2 | STORY-<NNN> | <title> | <status> | <effort> |
+...
+```
+
+The Order column makes the execution sequence visible — critical for the working-the-problem flow per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 314 ("read frontmatter `stories:` array (ordered) → pick first not-done story").
+
+### 4. Trailing suggestions
+
+After the table(s), print one short pointer depending on output:
+
+- **Filtered mode + first not-done story exists**: `Run /wr-itil:work-problem to advance the next story under RFC-<NNN> (STORY-<NNN> — <title>).` (Note: working-the-problem traversal per the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 300-320 lands in Slice 13.)
+- **Filtered mode + all stories done**: `All stories under RFC-<NNN> are done. Run /wr-itil:manage-rfc <RFC-<NNN>> verifying to transition the RFC.`
+- **Unfiltered mode + Draft section non-empty**: `Run /wr-itil:manage-story <STORY-<NNN>> accepted to advance a draft through INVEST gates.`
+- **Unfiltered mode + only Done section non-empty**: `No active stories. Run /wr-itil:capture-story to draft a new story.`
+
+## Ownership boundary
+
+`list-stories` does not modify, rename, or commit any files. If the README.md cache is stale, list-stories performs a live scan but does NOT rewrite `docs/stories/README.md` — refreshing the cache is `/wr-itil:manage-story review`'s ownership (Slice 8 lands the review surface). The trailing-suggestion pointer surfaces this boundary.
+
+## Related
+
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule** — Problem-RFC-Story framework + Phase 2 amendment 2026-05-12 (story tier).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 259** — RFC frontmatter `stories:` ORDERED array (execution sequence).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 294** — `/wr-itil:list-stories` skill description with `--rfc RFC-<NNN>` filter.
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule lines 300-320** — working-the-problem flow (Slice 13 lands the traversal).
+- **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule line 253** — I11 no-WSJF-leak invariant (Phase 2).
+- **the "Problem 071: Argument-based skill subcommands are not discoverable in Codex autocomplete" problem** — phased-landing split precedent (list-problems split from manage-problem list).
+- **the "Rename `wr-problem` Plugin to `wr-itil`" architecture rule amended** — Skill Granularity rule.
+- **the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule** — lifecycle conventions (story lifecycle mirrors problem lifecycle).
+- **the "Skill testing strategy — contract-assertion bats companion to" architecture rule** — contract-assertion bats pattern.
+- **the "Problem 031: `manage-problem work` incorrectly determines cache is fresh" problem** — git-history freshness check rationale.
+- **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes. The list view supports the working-the-problem flow that operationalises the ": Decompose a Fix Into Coordinated Changes" user outcome's "first-class entity" Desired Outcome.
+- **the ": Progress the Backlog While I'm Away" user outcome** — Progress the Backlog While I'm Away. Filtered mode (`--rfc`) feeds the AFK orchestrator's per-RFC iter dispatch (Slice 13).
+- `<itil-plugin-root>/skills/list-problems/SKILL.md` — direct precedent shape.
+- `<itil-plugin-root>/skills/list-incidents/SKILL.md` — sibling list-* skill at the incident tier.
+
+$ARGUMENTS

package/skills-codex/list-stories/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: List Stories"
+  short_description: "List delivery stories and lifecycle state."

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

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

package/skills-codex/list-story-maps/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: List Story Maps"
+  short_description: "List story maps, traces, and approval state."