@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/scripts/story-map-edit.mjs

@@ -3,7 +3,7 @@
 //
 // A map's data lives in a JSON island inside a several-hundred-line HTML file,
 // with `<` escaped as <. Editing that with an exact-match string tool is
-// error-prone enough that it does not get done: during ADR-102's own authoring
+// error-prone enough that it does not get done: during story-maps-render-from-json-through-a-canonical-template-architecture-rule's own authoring
 // every island change went through a throwaway load-mutate-save script rather
 // than the editing tool an agent normally reaches for. This command is that
 // script, made a first-class surface — state the operation, never open the JSON.
@@ -22,13 +22,13 @@
 //
 // Nothing the story file already says is settable here — status, the value
 // statement, and the problems a story closes are all read from the story at
-// render time (ADR-104). A card carries what identifies it and where it sits;
+// render time (a-story-map-card-stores-no-value-a-story-file-already-carries-architecture-rule). A card carries what identifies it and where it sits;
 // a row carries its RFC identity and its name. There are no --status, --value
 // or --badge flags, and a row's status and problems are derived from the
 // stories in it.
 //
-// @adr ADR-102 (story maps render from JSON through a canonical template)
-// @adr ADR-095 (story-map membership enforced at capture — drives add-card)
+// @adr story-maps-render-from-json-through-a-canonical-template-architecture-rule (story maps render from JSON through a canonical template)
+// @adr story-map-membership-and-story-content-completeness-are-enforced-at-capture-architecture-rule (story-map membership enforced at capture — drives add-card)
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -139,7 +139,7 @@ const OPS = {
       throw new Error(`release band "${id}" already exists on this map.`);
     }
     const band = { id, name };
-    // A row IS an RFC (ADR-103). Where a problem has proposed the row it carries
+    // A row IS an RFC (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule). Where a problem has proposed the row it carries
     // that identity; where nothing has, it renders as speculative and says so.
     if (flags.rfc && flags.rfc !== true) band.rfc = String(flags.rfc);
     if (flags.note && flags.note !== true) band.note = String(flags.note);
@@ -176,7 +176,7 @@ function usage() {
   console.error('    | story-map-edit.mjs <map.html> --json -');
   console.error('');
   console.error('Status, value and problems are derived from the story files at');
-  console.error('render time and are not settable here (ADR-104).');
+  console.error('render time and are not settable here (a-story-map-card-stores-no-value-a-story-file-already-carries-architecture-rule).');
 }
 
 /** Read an operation as a JSON object on stdin.

package/scripts/story-map-edit.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# Bash entry point for the story-map card editor, so the ADR-049/ADR-080 shim
+# Bash entry point for the story-map card editor, so the plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule/highest-version-wins-shim-wrapper-for-plugin-scaffold-template-shims-architecture-rule shim
 # machinery (which resolves `scripts/<NAME>.sh`) reaches the Node implementation.
 #
 # Usage: wr-itil-story-map-edit <map.html> <operation> [flags]
 #
-# @adr ADR-102 (story maps render from JSON through a canonical template)
-# @adr ADR-049 (plugin scripts resolve via bin/ on $PATH)
+# @adr story-maps-render-from-json-through-a-canonical-template-architecture-rule (story maps render from JSON through a canonical template)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin scripts resolve via bin/ on $PATH)
 set -euo pipefail
 exec node "$(cd "$(dirname "$0")" && pwd)/story-map-edit.mjs" "$@"

package/scripts/story-map-query.mjs

@@ -4,7 +4,7 @@
 // story-map-query.sh, which owns the single hash definition. Nothing here
 // hashes anything; see that wrapper's header for why.
 //
-// Reads the data island, never the rendered grid. Under ADR-102 the grid is a
+// Reads the data island, never the rendered grid. Under story-maps-render-from-json-through-a-canonical-template-architecture-rule the grid is a
 // projection regenerated from the island, so a map edited but not yet
 // re-rendered would answer with stale content if this scraped the markup — and
 // would disagree with the oversight hash, which is island-scoped.
@@ -19,14 +19,14 @@
 //                            and which maps could not answer
 //   unratified               only the maps needing ratification, with a reason
 //
-// @adr ADR-102 (story maps render from JSON through a canonical template)
-// @adr ADR-090 (drift-invalidated human-oversight marker)
+// @adr story-maps-render-from-json-through-a-canonical-template-architecture-rule (story maps render from JSON through a canonical template)
+// @adr story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule (drift-invalidated human-oversight marker)
 
 import { readFileSync } from 'node:fs';
 
 const ISLAND_OPEN = '<script id="story-map-data" type="application/json">';
 
-/** Read the authored data. Falls through to null for a pre-ADR-102 map, which
+/** Read the authored data. Falls through to null for a pre-story-maps-render-from-json-through-a-canonical-template-architecture-rule map, which
  *  has no island — mirroring _oversight_hashable's own fallthrough rather than
  *  inventing a second rule about what counts as a map. */
 function island(path) {
@@ -157,7 +157,7 @@ const OPS = {
   list: (maps) => maps.map(summary),
 
   get(maps, [id]) {
-    if (!id) throw new Error('get needs a story-map id, e.g. STORY-MAP-002');
+    if (!id) throw new Error('get needs a story-map id, e.g. take-a-problem-from-noticed-to-resolved-journey-map-journey-map');
     const m = maps.find((x) => x.data.storyMapId === id);
     if (!m) throw new Error(`no story map ${id} in this corpus`);
     return {
@@ -172,7 +172,7 @@ const OPS = {
   },
 
   'find-story': (maps, [storyId]) => {
-    if (!storyId) throw new Error('find-story needs a story id, e.g. STORY-047');
+    if (!storyId) throw new Error('find-story needs a story id, e.g. gate-the-correction-nudge-on-prompt-authorship-delivery-story');
     const hits = [];
     for (const m of maps) {
       for (const t of m.data.tasks ?? []) {
@@ -191,7 +191,7 @@ const OPS = {
   },
 
   'find-rfc': (maps, [rfcId]) => {
-    if (!rfcId) throw new Error('find-rfc needs an RFC id, e.g. RFC-062');
+    if (!rfcId) throw new Error('find-rfc needs an RFC id, e.g. example-release-design-release-design');
     const hits = [];
     for (const m of maps) {
       for (const row of m.data.releases ?? []) {
@@ -229,7 +229,7 @@ const OPS = {
    *  Do not normalise this back to an array.
    */
   'find-problem': (maps, [pid]) => {
-    if (!pid) throw new Error('find-problem needs a problem id, e.g. P508');
+    if (!pid) throw new Error('find-problem needs a problem id, e.g. the-fix-proposal-still-instantiates-a-standalone-rfc-document-after-made-it-a-release-row-problem');
     const hits = [];
     // A map with no authored island cannot be read at all.
     const unanswerable = (maps.islandless ?? []).map((m) => ({

package/scripts/story-map-query.sh

@@ -17,9 +17,9 @@
 # story-map-edit reads an operation FROM stdin under `--json -`. The asymmetry
 # is deliberate; do not assume symmetry between the two.
 #
-# @adr ADR-102 (story maps render from JSON through a canonical template)
-# @adr ADR-090 (drift-invalidated human-oversight marker)
-# @adr ADR-049 (plugin scripts resolve via bin/ on $PATH)
+# @adr story-maps-render-from-json-through-a-canonical-template-architecture-rule (story maps render from JSON through a canonical template)
+# @adr story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule (drift-invalidated human-oversight marker)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin scripts resolve via bin/ on $PATH)
 
 set -uo pipefail
 

package/scripts/update-jtbd-references-section.sh

@@ -6,11 +6,11 @@
 # JTBD-NNN-*.md files. Mirror of update-problem-references-section.sh
 # with jtbd: frontmatter / data-jtbd attribute extraction.
 #
-# Per ADR-060 § Phase 2 encoding amendment 2026-05-12 architect
+# Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 2 encoding amendment 2026-05-12 architect
 # finding 4: no per-section-name branching; lookup-table dispatch.
 #
-# @adr ADR-060 (Phase 2 encoding amendment 2026-05-12)
-# @problem P170 (Phase 2 Slice 2b)
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 2 encoding amendment 2026-05-12)
+# @problem 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 2b)
 
 set -uo pipefail
 
@@ -38,13 +38,13 @@ SECTION_MODE["Stories"]="markdown-frontmatter-jtbd"
 SECTION_ID_PATTERN["Stories"]="STORY-[0-9]+"
 SECTION_ID_PREFIX["Stories"]=""
 
-# P170 Phase 4 P4.1 — Related problems reverse-trace from problem
+# 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 4 P4.1 — Related problems reverse-trace from problem
 # tickets that cite this JTBD in their `jtbd:` frontmatter array.
-# Per ADR-060 § Phase 3 + Phase 4 in-scope amendment (2026-05-13)
+# Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 3 + Phase 4 in-scope amendment (2026-05-13)
 # P4.1 + JTBD finding F5: lookup-table row addition (no per-section
-# branching). Searches per-state subdirs (RFC-002 layout) via the
+# branching). Searches per-state subdirs (docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design layout) via the
 # `*/` glob segment; the flat-layout half is intentionally omitted
-# because Phase 4 ships after RFC-002 T5 has completed migration.
+# because Phase 4 ships after docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design T5 has completed migration.
 # Problem-ticket filenames are `<NNN>-<title>.md` without the `P`
 # prefix; render-prefix "P" produces the canonical `P<NNN>` form
 # for the rendered table row.
@@ -69,7 +69,7 @@ declare -a matched_ids=() matched_titles=() matched_statuses=()
 extract_from_markdown_frontmatter_jtbd() {
   local file="$1"
   # YAML frontmatter `jtbd:` array OR body-field `**JTBD**:` line.
-  # Problem tickets use body-field convention (per existing P170 / P189
+  # Problem tickets use body-field convention (per existing 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 / agent-invents-deferred-framing-on-tracked-phases-without-user-deferral-direction-projects-fictional-out-of-scope-onto-in-scope-work-problem
   # schema); RFCs / Stories / Story Maps use frontmatter `jtbd:` arrays.
   # Phase 4 P4.2: capture-problem skeleton uses body field `**JTBD**:`
   # per the existing convention; frontmatter migration is deferred to

package/scripts/update-problem-references-section.sh

@@ -8,7 +8,7 @@
 # attributes (story-maps) or YAML frontmatter `problems:` list
 # (stories + RFCs).
 #
-# Per ADR-060 § Phase 2 encoding amendment 2026-05-12 architect
+# Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 2 encoding amendment 2026-05-12 architect
 # finding 4: the helper body MUST NOT carry per-section-name
 # branching; `<section-name>` is a positional argument; the only
 # branch in the helper body is the per-input-extension dispatch
@@ -20,8 +20,8 @@
 #
 # Supersedes/absorbs the single-purpose
 # `packages/itil/scripts/update-problem-rfcs-section.sh` for the
-# `## RFCs` section per ADR-060 amendment 2026-05-12 § Phase 2
-# commit-grain decomposition + ADR-010 forwarder pattern. The old
+# `## RFCs` section per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule amendment 2026-05-12 § Phase 2
+# commit-grain decomposition + rename-wr-problem-plugin-to-wr-itil-architecture-rule forwarder pattern. The old
 # single-purpose helper stays as a thin shim during the deprecation
 # window for back-compat with any pinned callers.
 #
@@ -33,7 +33,7 @@
 #   - Story Maps → docs/story-maps/*/*.html (data-attribute extraction)
 #   - Stories    → docs/stories/*/*.md (frontmatter `problems:` extraction)
 #
-# Lazy-empty discipline (per JTBD-101 atomic-fix-adopter friction
+# Lazy-empty discipline (per extend-the-suite-with-new-plugins-user-outcome atomic-fix-adopter friction
 # guard + sibling pattern from update-problem-rfcs-section.sh): if
 # zero artefacts trace the problem, the `## <section-name>` section
 # is REMOVED entirely from the ticket file.
@@ -42,13 +42,13 @@
 # diff). Section placement: between `## Related` and `## Fix Released`
 # (or at EOF if neither present), mirroring the RFC-section convention.
 #
-# @adr ADR-060 (Phase 2 encoding amendment 2026-05-12 — architect
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 2 encoding amendment 2026-05-12 — architect
 #   finding 4: no per-section-name branching; per-extension dispatch
 #   via lookup table)
-# @adr ADR-014 (called by capture/manage skills to ride single-purpose
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (called by capture/manage skills to ride single-purpose
 #   commit grain)
-# @adr ADR-052 (behavioural bats coverage in test/)
-# @problem P170 (Phase 2 Slice 2 deliverable)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural bats coverage in test/)
+# @problem 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 2 deliverable)
 
 set -uo pipefail
 
@@ -125,8 +125,8 @@ declare -a matched_statuses=()
 extract_from_markdown_frontmatter() {
   local file="$1"
   # Read frontmatter problems: list. Match formats:
-  #   problems: [P200, P201]
-  #   problems: ["P200", "P201"]
+  #   problems: [wr-voice-tone-agent-returns-blanket-fail-when-docs-voice-and-tone-md-is-missing-problem, windyroad-tdd-hook-only-recognises-same-dir-or-tests-test-associations-problem]
+  #   problems: ["wr-voice-tone-agent-returns-blanket-fail-when-docs-voice-and-tone-md-is-missing-problem", "windyroad-tdd-hook-only-recognises-same-dir-or-tests-test-associations-problem"]
   local problems_line
   problems_line=$(awk '/^---$/{f=!f;next} f && /^problems:/' "$file" | head -1)
   if [ -z "$problems_line" ]; then
@@ -137,7 +137,7 @@ extract_from_markdown_frontmatter() {
 
 extract_from_html_data_attribute() {
   local file="$1"
-  # Read <meta name="problems" content="P200,P201">
+  # Read <meta name="problems" content="wr-voice-tone-agent-returns-blanket-fail-when-docs-voice-and-tone-md-is-missing-problem,windyroad-tdd-hook-only-recognises-same-dir-or-tests-test-associations-problem">
   local problems_line
   problems_line=$(grep -E '<meta[[:space:]]+name="problems"[[:space:]]+content="[^"]+"' "$file" | head -1)
   if [ -z "$problems_line" ]; then
@@ -265,7 +265,7 @@ if [ -n "$new_section" ]; then
     tmp_file2="$(mktemp)"
     # Pass the multi-line section via a file: awk -v rejects embedded newlines
     # on BSD awk (macOS), so getline keeps it portable across BSD awk + gawk
-    # (proven in effort-tally.sh --write, commit 1c967ba0; P392). new_section
+    # (proven in effort-tally.sh --write, commit 1c967ba0; blessed-replace-section-awk-v-section-multiline-idiom-fails-on-bsd-awk-macos-problem). new_section
     # ends in a single \n, matching the prior `printf "%s\n", section` output.
     section_file="$(mktemp)"
     printf '%s' "$new_section" > "$section_file"

package/scripts/update-problem-rfcs-section.sh

@@ -7,8 +7,8 @@
 #
 # Called inline by `/wr-itil:capture-rfc` Step 6 and `/wr-itil:manage-rfc`
 # Step 7 (transitions) + Step 9 (review re-rank) so the cross-tier
-# reverse-trace is current at every commit per ADR-014 single-commit
-# grain. Closes ADR-060 Phase 1 item 10 + Confirmation criterion 3
+# reverse-trace is current at every commit per governance-skills-commit-their-own-completed-work-architecture-rule single-commit
+# grain. Closes problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule Phase 1 item 10 + Confirmation criterion 3
 # (skill-side primary surface; architect Q1 + Q3 verdicts).
 #
 # Usage:
@@ -16,7 +16,7 @@
 #
 # Default <rfcs-dir> is `docs/rfcs`.
 #
-# Lazy-empty discipline (per JTBD-101 atomic-fix-adopter friction
+# Lazy-empty discipline (per extend-the-suite-with-new-plugins-user-outcome atomic-fix-adopter friction
 # guard + architect Q3 verdict): if zero RFCs trace this problem, the
 # `## RFCs` section is REMOVED entirely. Atomic-fix tickets with no
 # RFC trace stay free of empty-table noise.
@@ -25,7 +25,7 @@
 #
 # Section placement (per architect Q3 verdict):
 #   - Before `## Fix Released` if present (closure section stays at tail
-#     per ADR-022 trailing-audit-artefact convention).
+#     per problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule trailing-audit-artefact convention).
 #   - Else at EOF.
 #
 # Output:
@@ -33,16 +33,16 @@
 #     update; otherwise leaves the file untouched.
 #   - Emits exit 0 always (caller skills don't need defensive handling).
 #
-# @adr ADR-060 (Phase 1 item 10 + Confirmation criterion 3 — auto-
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 1 item 10 + Confirmation criterion 3 — auto-
 #   maintained reverse trace; architect Q3 — table format, lazy empty,
 #   between `## Related` and `## Fix Released`)
-# @adr ADR-014 (called by capture-rfc Step 6 + manage-rfc Step 7+9
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (called by capture-rfc Step 6 + manage-rfc Step 7+9
 #   to ride the same single-purpose commit)
-# @adr ADR-022 (`## Fix Released` is the trailing closure section;
+# @adr problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule (`## Fix Released` is the trailing closure section;
 #   `## RFCs` precedes it)
-# @adr ADR-052 (behavioural bats coverage in
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural bats coverage in
 #   packages/itil/scripts/test/update-problem-rfcs-section.bats)
-# @problem P170
+# @problem 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
 
 set -uo pipefail
 

package/scripts/update-rfc-commits-section.sh

@@ -2,20 +2,20 @@
 # packages/itil/scripts/update-rfc-commits-section.sh
 #
 # Renders an RFC's `## Commits` section as a DERIVED VIEW from the git history
-# (P378/RFC-030 Piece 1; ADR-085). The commit log is the source of truth; the
+# (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem/rfc-lifecycle-self-maintenance-release-design Piece 1; the-rfc-commits-section-is-a-git-log-derived-view-rendered-skill-side-architecture-rule). The commit log is the source of truth; the
 # section is a projection of `git log --grep "Refs: RFC-NNN"`. Because nothing
 # is written per-commit, there is no post-commit working-tree edit and no
-# ADR-014 grain problem — the section is regenerated skill-side (manage-rfc on
+# governance-skills-commit-their-own-completed-work-architecture-rule grain problem — the section is regenerated skill-side (manage-rfc on
 # every transition/review; reconcile-rfcs) exactly like docs/problems/README.md
-# is a rendered index (ADR-031 precedent).
+# is a rendered index (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule precedent).
 #
 # Usage: update-rfc-commits-section.sh <rfc-file>
 # Idempotent: rewriting a current section is a byte-stable no-op.
 #
-# @adr ADR-085 (RFC ## Commits is a git-log-derived view, rendered skill-side)
-# @adr ADR-031 (rendered-index precedent) ADR-014 (why not a post-commit hook)
-# @problem P378
-# @rfc RFC-030
+# @adr the-rfc-commits-section-is-a-git-log-derived-view-rendered-skill-side-architecture-rule (RFC ## Commits is a git-log-derived view, rendered skill-side)
+# @adr problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule (rendered-index precedent) governance-skills-commit-their-own-completed-work-architecture-rule (why not a post-commit hook)
+# @problem rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem
+# @rfc rfc-lifecycle-self-maintenance-release-design
 
 set -uo pipefail
 

package/scripts/update-rfc-references-section.sh

@@ -7,13 +7,13 @@
 #   - ## Story Maps : sources docs/story-maps/*/*.html via data attributes
 #   - ## Stories    : forward-trace from RFC's own frontmatter `stories:`
 #
-# Per ADR-060 § Phase 2 encoding amendment 2026-05-12 architect finding 4:
+# Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 2 encoding amendment 2026-05-12 architect finding 4:
 # no per-section-name branching in body; lookup-table-driven dispatch.
 #
 # Usage: update-rfc-references-section.sh <rfc-file> <section-name>
 #
-# @adr ADR-060 (Phase 2 encoding amendment 2026-05-12)
-# @problem P170 (Phase 2 Slice 2b)
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 2 encoding amendment 2026-05-12)
+# @problem 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 2b)
 
 set -uo pipefail
 

package/scripts/update-story-references-section.sh

@@ -5,11 +5,11 @@
 # table supports ## RFCs, ## Story Maps sections on STORY-NNN-*.md
 # files (a story's parent RFC + parent story-map traces).
 #
-# Per ADR-060 § Phase 2 encoding amendment 2026-05-12 architect
+# Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 2 encoding amendment 2026-05-12 architect
 # finding 4: no per-section-name branching; lookup-table dispatch.
 #
-# @adr ADR-060 (Phase 2 encoding amendment 2026-05-12)
-# @problem P170 (Phase 2 Slice 2b)
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 2 encoding amendment 2026-05-12)
+# @problem 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 2b)
 
 set -uo pipefail
 
@@ -49,11 +49,11 @@ extract_from_markdown_frontmatter_stories() {
 
 extract_from_html_data_story_id() {
   local file="$1"
-  # Story maps reference stories via <a data-story-id="STORY-NNN"> per ADR-060
+  # Story maps reference stories via <a data-story-id="STORY-NNN"> per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule
   # amendment schema; grep on the literal attribute match.
   # Two spellings carry the same fact, and a rendered map carries BOTH: the
   # card as data-story-id="X", and the authored island entry as "storyId": "X".
-  # Pre-ADR-102 maps have only the first; a map edited but not yet re-rendered
+  # Pre-story-maps-render-from-json-through-a-canonical-template-architecture-rule maps have only the first; a map edited but not yet re-rendered
   # has only the second. Matching both covers every state. The alternation is
   # boolean per file, so a map carrying both spellings is not double-listed.
   grep -qE "data-story-id=\"${story_id}\"|\"storyId\"[[:space:]]*:[[:space:]]*\"${story_id}\"" "$file"

package/scripts/verify-iter-summary.sh

@@ -2,7 +2,7 @@
 # verify-iter-summary.sh — detect ITERATION_SUMMARY over-claim against
 # on-disk ADR Confirmation state.
 #
-# Closes P335: AFK iter subprocess over-claims completion in ITERATION_SUMMARY
+# Closes afk-iter-subprocesses-can-over-claim-completion-in-their-iteration-summary-orchestrator-trusts-the-claim-but-on-disk-state-contradicts-it-problem: AFK iter subprocess over-claims completion in ITERATION_SUMMARY
 # while on-disk Confirmation `[ ]` boxes remain. Step 6.75 of work-problems
 # dispatches this script between iter completion and Step 7 loop-back.
 #
@@ -17,7 +17,7 @@
 #           section
 #   2 = invocation error (missing args, missing notes file, bad sha)
 #
-# Per ADR-049, this script is invoked via the PATH shim
+# Per plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule, this script is invoked via the PATH shim
 # `wr-itil-verify-iter-summary` from SKILL.md prose — never via the
 # repo-relative `packages/itil/scripts/...` path.
 
@@ -63,7 +63,7 @@ fi
 #   - "all <something> green|complete|done|checked|ticked"
 #   - "every <something> green|complete|done|checked|ticked"
 #   - "all (Confirmation|criteria) items <complete|green|done|ticked>"
-#   - "(a)-(<letter>) green|complete|all"  (the ADR-077 witness shape)
+#   - "(a)-(<letter>) green|complete|all"  (the generated-docs-decisions-readme-md-compendium-as-token-cheap-load-surface-for-routine-architect-agent-compliance-architecture-rule witness shape)
 #   - "Confirmation items (a)-(<letter>) all green at source"
 has_signal=0
 if echo "$combined" | grep -qiE '(all|every)[[:space:]]+[^.]{0,80}(green|complete|done|checked|ticked|landed)' ; then

package/skills/capture-problem/REFERENCE.md

@@ -1,18 +1,18 @@
 # `/wr-itil:capture-problem` Reference
 
-This file hosts the rationale, edge cases, contract trade-offs, and ADR cross-references for the `/wr-itil:capture-problem` skill. SKILL.md is the runtime contract (~150 lines, on-topic per ADR-038 progressive disclosure); this REFERENCE.md is the on-demand expansion for maintainers and curious users.
+This file hosts the rationale, edge cases, contract trade-offs, and ADR cross-references for the `/wr-itil:capture-problem` skill. SKILL.md is the runtime contract (~150 lines, on-topic per the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule progressive disclosure); this REFERENCE.md is the on-demand expansion for maintainers and curious users.
 
 ## Why a separate skill?
 
-The `/wr-itil:manage-problem` flow is ~10 turns of agent work for a full new-problem intake: Step 0 README reconciliation preflight, Step 2 wide-net duplicate grep + AskUserQuestion branch, Step 3 next-ID, Step 4 information-gathering AskUserQuestion, Step 4b multi-concern split AskUserQuestion, Step 5 ticket file write + P094 README refresh, Step 11 commit gate.
+The `/wr-itil:manage-problem` flow is ~10 turns of agent work for a full new-problem intake: Step 0 README reconciliation preflight, Step 2 wide-net duplicate grep + AskUserQuestion branch, Step 3 next-ID, Step 4 information-gathering AskUserQuestion, Step 4b multi-concern split AskUserQuestion, Step 5 ticket file write + the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem README refresh, Step 11 commit gate.
 
 That cost is correct for the canonical new-problem path — the user wants to walk the flow, see duplicate-match prompts, and place the ticket in the WSJF ranking immediately.
 
-It is wrong for the **aside-invocation** use case. P155 surfaced three repeating patterns where the heavyweight cost is load-bearing friction:
+It is wrong for the **aside-invocation** use case. the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem surfaced three repeating patterns where the heavyweight cost is load-bearing friction:
 
 1. **Mid-AFK-iter sibling-findings**: agent observes a tangential ticket-worthy issue. The 10-turn ceremony breaks iter cadence — observation gets buried in `notes` field of `ITERATION_SUMMARY` and ~50% never reach the backlog.
 2. **User-initiated rapid captures**: user says "btw, this is broken too — capture it". The 10-turn ceremony breaks conversational flow.
-3. **AFK orchestrator main turn captures**: user-driven mid-loop interjections (P151 / P152 / P154 in the session that surfaced P155). Each capture took 5-15 minutes wall-clock through the heavyweight flow.
+3. **AFK orchestrator main turn captures**: user-driven mid-loop interjections (the "Published skills reference repo-relative script paths — adopter `bash` invocations hard-fail at Step 0" problem / the "No pressure or nudge for keeping documentation up to date — README narrative drifts from package behaviour silently because no gate, hook, or advisory applies pressure on doc-content currency" problem / the "namespace-prefix detector must run against npm pack output not source tree — source-tree advisory misses publish-manifest drift class (broken-shim regression caught only after production ship)" problem in the session that surfaced the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem). Each capture took 5-15 minutes wall-clock through the heavyweight flow.
 
 `/wr-itil:capture-problem` is the source-side fix: a lightweight skill with a deferred-placeholder pattern that captures the observation in ~3-4 turns and routes the deferred re-rating + README refresh through `/wr-itil:review-problems` at a time of the user's choosing.
 
@@ -20,25 +20,25 @@ It is wrong for the **aside-invocation** use case. P155 surfaced three repeating
 
 ### Capture-time false-positives are cheaper than false-negatives
 
-P155 line 24: "capture-time false-positives (creating a duplicate that gets merged later) are cheaper than capture-time false-negatives (losing the observation entirely)."
+the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem line 24: "capture-time false-positives (creating a duplicate that gets merged later) are cheaper than capture-time false-negatives (losing the observation entirely)."
 
 This is the structural rationale for:
 - **3-keyword cap on the duplicate-grep** — wider grep would surface more matches but force the user to either (a) add an AskUserQuestion branch (which capture-problem doesn't have) or (b) ignore the matches and proceed silently. A 3-keyword cap keeps the match list short and audit-able in the report.
 - **Title-only filename match** — body-content matches would be too noisy at the conservative threshold. Files whose filenames have zero overlap but whose bodies mention a keyword are almost always different tickets that happen to discuss similar topics. False-positive cost would dominate.
 - **No halt-on-match** — even when matches are found, capture proceeds. The duplicate gets resolved at next `/wr-itil:review-problems` (where the full-rank scan can detect and merge actual duplicates with the user in the loop).
 
-### README refresh: inline (P199 Option 2 amendment, 2026-06-05)
+### README refresh: inline (the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem Option 2 amendment, 2026-06-05)
 
-Capture-problem stages `docs/problems/README.md` inline at Step 6, mirroring `/wr-itil:manage-problem` Step 5 P094 (refresh-on-create) + P134 (last-reviewed rotation). The previously-load-bearing "Deferred-README-refresh contract" was reversed by user direction recorded in P199 on 2026-05-31, then implemented on 2026-06-05.
+Capture-problem stages `docs/problems/README.md` inline at Step 6, mirroring `/wr-itil:manage-problem` Step 5 the "Problem 094: `/wr-itil:manage-problem` does not refresh `docs/problems/README.md` on ticket creation" problem (refresh-on-create) + the "`docs/problems/README.md` line 3 narrative-blob accumulator bloat — sibling to (briefing tier 3) on a different surface" problem (last-reviewed rotation). The previously-load-bearing "Deferred-README-refresh contract" was reversed by user direction recorded in the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem on 2026-05-31, then implemented on 2026-06-05.
 
 **Rationale for the reversal** (user direction):
-- The P165 README-refresh-discipline hook (shipped after the initial capture-problem design) blocks every capture commit that does not stage README. The P262 workaround (a `RISK_BYPASS: capture-deferred-readme` trailer) cleared the gate but kept the README transiently stale by design — a contract that always felt half-superseded by P165 reality.
+- The "README-refresh enforcement gap — iter subprocess commits can land a `.verifying.md` rename without staging the corresponding Verification Queue row in `docs/problems/README.md`" problem README-refresh-discipline hook (shipped after the initial capture-problem design) blocks every capture commit that does not stage README. The "README-refresh hook conflicts with capture-problem SKILL's deferred-README-refresh contract — hook wins; SKILL needs update OR hook needs carve-out" problem workaround (a `RISK_BYPASS: capture-deferred-readme` trailer) cleared the gate but kept the README transiently stale by design — a contract that always felt half-superseded by the "README-refresh enforcement gap — iter subprocess commits can land a `.verifying.md` rename without staging the corresponding Verification Queue row in `docs/problems/README.md`" problem reality.
 - Option 2 acknowledges reality: stage the README. The cost is one mechanical render-and-stage primitive (already proven in `/wr-itil:manage-problem`); the capture-time speed distinction from manage-problem comes from the wide-net duplicate grep + AskUserQuestion branches that capture-problem skips, not the README skip.
 - The `RISK_BYPASS: capture-deferred-readme` trailer is dropped from emission. The allow-list entry in `packages/itil/hooks/lib/readme-refresh-detect.sh::_README_REFRESH_BYPASS_TRAILERS` is retained as inert dead code for adopter compatibility (minimal-change discipline).
 
 **Trade-off table (post-amendment)**:
 
-| Surface | manage-problem | capture-problem (post-P199) |
+| Surface | manage-problem | capture-problem (post-the "capture-problem → manage-problem same-session halts at Step 0 reconcile (HALT_ROUTE_RECONCILE on deferred-refresh seam)" problem) |
 |---------|----------------|------------------------------|
 | README authoritativeness | Always current at commit boundary | Always current at commit boundary |
 | Capture-time turn cost | +1-2 turns (regenerate + stage) | +1-2 turns (same primitive) |
@@ -51,14 +51,14 @@ The on-disk ticket inventory remains the source of truth; `/wr-itil:list-problem
 
 ### No AskUserQuestion at all
 
-Architect Q4 + JTBD review confirmed: capture-problem is a **mechanical-stage skill** per ADR-044's framework-resolution boundary. Every potentially-interactive decision is framework-mediated:
+Architect Q4 + JTBD review confirmed: capture-problem is a **mechanical-stage skill** per the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule's framework-resolution boundary. Every potentially-interactive decision is framework-mediated:
 
 - **Duplicate-check**: false-positive bias > false-negative bias. Mechanical rule: list matches, proceed regardless.
 - **Priority**: framework-policy default `3 (Medium) — Impact 3 × Likelihood 1`, flagged for re-rate. Re-rating is mandatory before the ticket is worked, so no ticket gets ranked on a wrong default.
 - **Effort**: framework-policy default `M`, flagged for re-rate. Same re-rating contract as Priority.
 - **Multi-concern split**: out of scope. The user invoking capture-problem with a multi-concern observation gets one ticket with the full description as the body; they re-route to `/wr-itil:manage-problem` for the structured split.
 
-This mirrors the mechanical-stage carve-out pattern documented in CLAUDE.md (P132 / inverse-P078 trap): when a SKILL contract names a stage as mechanical, do not ask. Per-action consent gates re-ask decisions the user already made and silently undo the load-bearing UX investment.
+This mirrors the mechanical-stage carve-out pattern documented in CLAUDE.md (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 trap): when a SKILL contract names a stage as mechanical, do not ask. Per-action consent gates re-ask decisions the user already made and silently undo the load-bearing UX investment.
 
 ## Edge cases
 
@@ -78,7 +78,7 @@ This is a degenerate case — real captures carry meaningful first-tokens — bu
 
 The next-ID formula uses `git ls-tree origin/main` to read the remote-tracking ref without requiring a fetch. If a parallel session minted the same ID for a different problem and pushed it before this session captures, the local read sees the higher origin ID and increments past it.
 
-If the local session has not fetched recently and origin has captures the local doesn't see, the formula may still collide. The renumber audit log line in Step 7 captures the resolution. P040 incident applies.
+If the local session has not fetched recently and origin has captures the local doesn't see, the formula may still collide. The renumber audit log line in Step 7 captures the resolution. the "Problem 040: work-problems does not fetch origin before starting" problem incident applies.
 
 ### Cross-skill marker ordering
 
@@ -86,9 +86,9 @@ The `/tmp/manage-problem-grep-${SESSION_ID}` create-gate marker is shared betwee
 
 This means a session that does `manage-problem` once then `capture-problem` three times has the marker set after the first manage-problem grep, and all three captures land without re-running the grep + mark sequence. capture-problem still runs its own minimal-grep in Step 2 (because the conservative threshold + report-listing is part of the contract), but the marker write is a no-op.
 
-### P057 staging-trap
+### the "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem staging-trap
 
-Not applicable. capture-problem only Writes a new file; it does not `git mv` an existing one. The P057 rule (re-stage after Edit on a `git mv`-d file) is irrelevant to this skill.
+Not applicable. capture-problem only Writes a new file; it does not `git mv` an existing one. The "Problem 057: `git mv` + Edit + `git add` staging-ordering trap drops content edits from the commit" problem rule (re-stage after Edit on a `git mv`-d file) is irrelevant to this skill.
 
 ### Multi-concern descriptions
 
@@ -108,7 +108,7 @@ Heavyweight intake counterpart. Shares the create-gate marker with capture-probl
 
 ### `/wr-itil:work-problems` (AFK orchestrator)
 
-Iter subprocesses can invoke capture-problem to capture sibling-findings without breaking iter cadence. The AFK carve-out in ADR-032 (line 85) excludes the **background-capture** variant from AFK contexts; the **foreground-lightweight-capture** variant introduced by this skill is fine inside iter subprocesses because it has no `Agent(run_in_background: true)` invocation — it's a normal foreground-synchronous skill that happens to do less work than manage-problem.
+Iter subprocesses can invoke capture-problem to capture sibling-findings without breaking iter cadence. The AFK carve-out in the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule (line 85) excludes the **background-capture** variant from AFK contexts; the **foreground-lightweight-capture** variant introduced by this skill is fine inside iter subprocesses because it has no `Agent(run_in_background: true)` invocation — it's a normal foreground-synchronous skill that happens to do less work than manage-problem.
 
 ### `/wr-itil:capture-problem` callers
 
@@ -116,24 +116,24 @@ The intended invocation surface is `/wr-itil:capture-problem <description>`. The
 
 ## Related ADRs
 
-- **ADR-009** — gate-marker-lifecycle (per-session /tmp markers; capture-problem reuses the manage-problem marker).
-- **ADR-013** — structured user interaction (Rule 6 fail-safe; capture-problem has no AskUserQuestion branches so Rule 6 is trivially satisfied).
-- **ADR-014** — governance skills commit their own work (capture-problem owns its commit).
-- **ADR-022** — verification-pending status (out of scope for capture-problem; status transitions live in transition-problem).
-- **ADR-031** — problem-ticket directory layout (capture-problem matches current flat-layout production reality; auto-migration is a future ADR-031 follow-up).
-- **ADR-032** — governance skill invocation patterns (this skill's parent ADR; foreground-lightweight-capture variant amendment 2026-05-03).
-- **ADR-038** — progressive disclosure (SKILL.md + REFERENCE.md split shape).
-- **ADR-044** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
-- **ADR-049** — bin/ on PATH (capture-problem reuses existing `wr-itil-reconcile-readme` shim; no new shim).
-- **ADR-052** — behavioural-tests-default for skill testing (capture-problem's bats fixtures exercise primitives, not SKILL.md prose).
+- **the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule** — gate-marker-lifecycle (per-session /tmp markers; capture-problem reuses the manage-problem marker).
+- **the "Structured User Interaction for Governance-Skill Decisions" architecture rule** — structured user interaction (Rule 6 fail-safe; capture-problem has no AskUserQuestion branches so Rule 6 is trivially satisfied).
+- **the "Governance Skills Commit Their Own Completed Work" architecture rule** — governance skills commit their own work (capture-problem owns its commit).
+- **the "Problem lifecycle — add a Verification Pending status between Known Error and Closed" architecture rule** — verification-pending status (out of scope for capture-problem; status transitions live in transition-problem).
+- **the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule** — problem-ticket directory layout (capture-problem matches current flat-layout production reality; auto-migration is a future the "Problem-ticket directory layout — per-state subdirectories under `docs/problems/`" architecture rule follow-up).
+- **the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule** — governance skill invocation patterns (this skill's parent ADR; foreground-lightweight-capture variant amendment 2026-05-03).
+- **the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule** — progressive disclosure (SKILL.md + REFERENCE.md split shape).
+- **the "— Decision-Delegation Contract: when agents act on the framework vs ask the user" architecture rule** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — bin/ on PATH (capture-problem reuses existing `wr-itil-reconcile-readme` shim; no new shim).
+- **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests-default for skill testing (capture-problem's bats fixtures exercise primitives, not SKILL.md prose).
 
 ## Related problems
 
-- **P014** — parent / master tracker.
-- **P078** — capture-on-correction OFFER; depends on capture-problem.
-- **P088** — settled the user-direction-scoped decision: capture-problem + capture-adr are shippable; capture-retro is deferred.
-- **P119** — manage-problem create-gate; capture-problem composes with the same marker.
-- **P148** — Tickets Deferred retro section (legacy when capture-problem ships).
-- **P155** — driver ticket.
-- **P156** — sibling capture-adr.
-- **P157** — sibling pending-questions-surface hook.
+- **the "Problem 014: No lightweight aside invocation for governance skills (problems, retros, ADRs)" problem** — parent / master tracker.
+- **the "Problem 078: Assistant does not offer to capture a problem ticket when the user delivers strong-signal correction" problem** — capture-on-correction OFFER; depends on capture-problem.
+- **the "Problem 088: run-retro cannot see the full session context when invoked as a subagent, subprocess, or from any non-parent-session surface — 's fix is partially blind" problem** — settled the user-direction-scoped decision: capture-problem + capture-adr are shippable; capture-retro is deferred.
+- **the "Agent bypasses `/wr-itil:manage-problem` Step 2 duplicate-check by writing tickets directly to `docs/problems/`" problem** — manage-problem create-gate; capture-problem composes with the same marker.
+- **the "Agent defers ticket creation to retro summary "Tickets Deferred" section instead of immediately invoking `/wr-itil:manage-problem` — observations could be lost if user is in a rush" problem** — Tickets Deferred retro section (legacy when capture-problem ships).
+- **the "Ship `/wr-itil:capture-problem` skill — lightweight aside-invocation surface for problem capture during foreground work" problem** — driver ticket.
+- **the "Ship `/wr-architect:capture-adr` skill — lightweight aside-invocation surface for ADR capture during foreground work" problem** — sibling capture-adr.
+- **the "Ship pending-questions-surface hook — auto-surface accumulated `outstanding_questions` from `.afk-run-state/outstanding-questions.jsonl` at session start when user returns interactive" problem** — sibling pending-questions-surface hook.