@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/lib/migrate-problems-layout.sh

@@ -1,15 +1,15 @@
 #!/usr/bin/env bash
 # Canonical shared migration routine — adopter `docs/problems/` flat → per-state subdir.
-# P170 / RFC-002 / ADR-031 (accepted 2026-05-12).
+# 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 / docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design / problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule (accepted 2026-05-12).
 #
-# Adopter repos that installed `@windyroad/itil` before ADR-031 acceptance
+# Adopter repos that installed `@windyroad/itil` before problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule acceptance
 # carry the flat-layout `docs/problems/<NNN>-<slug>.<state>.md` shape. The
 # `manage-problem` and `work-problems` skills source this file at Step 1
-# (ADR-032 foreground-synchronous) and call `migrate_problems_to_per_state_layout`
+# (governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule foreground-synchronous) and call `migrate_problems_to_per_state_layout`
 # before any layout-dependent logic, so adopter trees auto-migrate on first
 # invocation post-update.
 #
-# Distribution: ADR-017 sync pattern. Canonical lives at
+# Distribution: shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule sync pattern. Canonical lives at
 #   packages/shared/lib/migrate-problems-layout.sh
 # Synced into each consumer's lib/ (currently only `packages/itil/lib/`)
 # by `scripts/sync-migrate-problems-layout.sh`. Drift is asserted by
@@ -51,9 +51,9 @@ detect_flat_layout() {
 # Idempotent + partial-migration-safe entrypoint.
 # Returns 0 when already-migrated (no-op) OR migration completed cleanly.
 # Returns non-zero on git failure. Writes a standalone commit with
-# subject `docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)`
+# subject `docs(problems): auto-migrate to per-state subdirectory layout (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule)`
 # and a footer `RISK_BYPASS: adr-031-migration` trailer recognised by the
-# commit-gate hook (T11). Standalone-commit grain per ADR-031 §
+# commit-gate hook (T11). Standalone-commit grain per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule §
 # Backward Compatibility (line 124).
 migrate_problems_to_per_state_layout() {
   local repo_root="${1:-$PWD}"
@@ -103,12 +103,12 @@ migrate_problems_to_per_state_layout() {
     return 0
   fi
 
-  # JTBD-006 AFK transparency (T8 jtbd-review nitpick c): single stderr
+  # progress-the-backlog-while-i-m-away-user-outcome AFK transparency (T8 jtbd-review nitpick c): single stderr
   # line on first-fire so AFK orchestrator output records the action.
-  echo "migrate-problems-layout: relocated $moved_count tickets to per-state subdirs (ADR-031)" >&2
+  echo "migrate-problems-layout: relocated $moved_count tickets to per-state subdirs (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule)" >&2
 
-  # JTBD-201 audit-trail forward-pointer (T8 jtbd-review nitpick b):
-  # commit body cites ADR-031 so future `git log` readers have the
+  # restore-service-fast-with-an-audit-trail-user-outcome audit-trail forward-pointer (T8 jtbd-review nitpick b):
+  # commit body cites problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule so future `git log` readers have the
   # semantic context without needing to grep the trailer.
   # T10 fix: use sequential `-m` paragraphs instead of `--trailer`; the
   # `--trailer` mechanism in git 2.47.x appended a spurious trailing
@@ -116,9 +116,9 @@ migrate_problems_to_per_state_layout() {
   # parsers downstream. Sequential `-m` paragraphs write a clean
   # `RISK_BYPASS: adr-031-migration` line in the body.
   (cd "$repo_root" && git commit \
-    -m "docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)" \
+    -m "docs(problems): auto-migrate to per-state subdirectory layout (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule)" \
     -m "See: docs/decisions/031-problem-ticket-directory-layout.accepted.md" \
-    -m "Policy-authorised under ADR-013 Rule 6 + ADR-019 precedent (pure-rename + pure-mkdir; fully reversible via git revert)." \
+    -m "Policy-authorised under structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 + afk-orchestrator-preflight-get-the-repo-into-a-clean-state-before-starting-architecture-rule precedent (pure-rename + pure-mkdir; fully reversible via git revert)." \
     -m "RISK_BYPASS: adr-031-migration") || {
     echo "ERROR: migration commit failed" >&2
     return 1

package/lib/story-oversight.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# story-oversight.sh — ADR-090 lazy-fingerprint ratification helpers.
+# story-oversight.sh — story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule lazy-fingerprint ratification helpers.
 #
 # Shared by detect-unratified-stories-maps.sh, check-rfc-stories-ratified.sh, and
 # mark-story-oversight-confirmed.sh so all three agree on ONE hash definition
@@ -8,8 +8,8 @@
 # A story MAP is RATIFIED when it carries a `confirmed` human-oversight marker
 # AND a stored oversight-hash that matches a fresh hash of its content-minus-
 # marker. Any content edit changes the hash → the artefact reads as drifted /
-# unratified until re-ratified. This is ADR-090's drift-invalidation (ADR-009
-# drift lineage, NOT ADR-066 write-once) — the same hash-the-artefact pattern
+# unratified until re-ratified. This is story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule's drift-invalidation (gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule
+# drift lineage, NOT human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule write-once) — the same hash-the-artefact pattern
 # the external-comms gate uses.
 #
 # Sourced, not executed. Requires `shasum` (BSD + coreutils both ship it).
@@ -19,17 +19,17 @@
 # encodings in one filter:
 #   - markdown: `human-oversight:` / `oversight-hash:` frontmatter lines
 #   - HTML:     <meta name="human-oversight" ...> / <meta name="oversight-hash" ...>
-#   - ADR-102 data island: the same fields as JSON keys, `"humanOversight":` /
-#     `"oversightHash":` / `"oversightDate":` / `"oversightNote":`. Since ADR-102
+#   - story-maps-render-from-json-through-a-canonical-template-architecture-rule data island: the same fields as JSON keys, `"humanOversight":` /
+#     `"oversightHash":` / `"oversightDate":` / `"oversightNote":`. Since story-maps-render-from-json-through-a-canonical-template-architecture-rule
 #     scopes a map's hash to the island, the marker now lives INSIDE the hashed
 #     region — so without this third spelling, ratifying a map mutated the very
 #     bytes it was fingerprinting and the stored hash could never match. Every
 #     map would have read as drifted the instant it was ratified.
 # THE single definition of what the fingerprint ignores. Reads stdin, writes the
 # normalised stream. Both hash functions route through this and neither carries
-# its own copy — that duplication is why the P474 `**Status**:` mirror had to be
+# its own copy — that duplication is why the oversight-hash-treats-the-status-body-mirror-as-substance-so-an-accept-transition-self-invalidates-its-own-ratification-problem `**Status**:` mirror had to be
 # removed from two places and why a third copy could have been missed entirely
-# (RFC-059 / STORY-055).
+# (lifecycle-state-is-not-duplicated-inside-hashed-story-content-release-design / one-definition-of-what-the-oversight-fingerprint-ignores-delivery-story).
 #
 # Excludes the marker lines plus the lifecycle `status` key in both encodings, and
 # normalises lifecycle PROGRESS — acceptance-criterion ticks and slice
@@ -37,9 +37,9 @@
 # criterion or advancing status is progress, not a revision of what the human
 # ratified; the value statement, criterion TEXT and structure all still drift.
 #
-# Editing this filter changes ADR-090's Decision Outcome, not merely a mechanism.
+# Editing this filter changes story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule's Decision Outcome, not merely a mechanism.
 # It is the surface the 2026-07-03 narrowing changed while going unrecorded for
-# three weeks; a change here needs an ADR-090 amendment. The pattern is a
+# three weeks; a change here needs an story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule amendment. The pattern is a
 # LITERAL on purpose: built from a variable, an expansion that ever yielded empty
 # would make `grep -vE ''` suppress every line and hash the empty stream to a
 # constant, after which one artefact's stored hash would validate against ANY
@@ -59,20 +59,20 @@ oversight_excluded_keys() {
 
 # The MAP-SUBSTANCE key set: the island keys a story map's ratification hangs on.
 #
-# Editing this set — here or in the SUBSTANCE tuple below — changes ADR-090's
-# Decision Outcome as amended by ADR-103, not merely a mechanism. It IS the drift
-# trigger. A change here needs an ADR-090 amendment, and the bidirectional test
+# Editing this set — here or in the SUBSTANCE tuple below — changes story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule's
+# Decision Outcome as amended by a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule, not merely a mechanism. It IS the drift
+# trigger. A change here needs an story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule amendment, and the bidirectional test
 # will NOT catch that: it asserts the accessor and the tuple agree, so it passes
 # whenever both move together, which is the shape of exactly that edit. The
 # sibling notice on _oversight_filter says the same thing for the same reason.
 #
 # SCOPE: island keys only. Unlike oversight_excluded_keys, which strips keys from
 # every artefact in three encodings, this set is meaningless for anything with no
-# island — stories and pre-ADR-102 maps fall through to whole-file bytes. The two
+# island — stories and pre-story-maps-render-from-json-through-a-canonical-template-architecture-rule maps fall through to whole-file bytes. The two
 # are not complements; `excluded ∪ substance` is not the key space.
 #
-# THIS IS THE ONLY ENUMERATION. Six documents used to restate it (ADR-090,
-# ADR-103, ADR-105, capture-story-map, and manage-story-map twice) and by
+# THIS IS THE ONLY ENUMERATION. Six documents used to restate it (story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule,
+# a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule, the-grid-ships-in-the-file-a-map-is-readable-with-no-script-engine-architecture-rule, capture-story-map, and manage-story-map twice) and by
 # 2026-08-08 it had drifted in both directions at once: the ADRs still named
 # `lead` and `traceProse`, dead the day before, while manage-story-map had lost
 # `storyMapId` and `secondaryPersona`, both live. The prose now states the rule
@@ -88,25 +88,25 @@ oversight_map_substance_keys() {
 
 # Emit the bytes a fingerprint should cover.
 #
-# For a story map under ADR-102 that is the DATA ISLAND alone, not the whole
+# For a story map under story-maps-render-from-json-through-a-canonical-template-architecture-rule that is the DATA ISLAND alone, not the whole
 # file: the grid, the <style> block and the <meta> block are all generated from
 # the island, so hashing the whole file would let a template change regenerate
 # every map, drift every stored fingerprint, and silently revoke ratification
-# across the corpus (ADR-090's marker is drift-invalidated). A presentation
+# across the corpus (story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule's marker is drift-invalidated). A presentation
 # change must never revoke a substance approval.
 #
-# Anything with no island — stories (.md), and maps predating ADR-102 — falls
+# Anything with no island — stories (.md), and maps predating story-maps-render-from-json-through-a-canonical-template-architecture-rule — falls
 # through to whole-file bytes, so the story leg and the legacy corpus are
 # untouched.
 _oversight_hashable() {
   local f="$1"
   if grep -qF '<script id="story-map-data"' "$f" 2>/dev/null; then
-    # ADR-103: the fingerprint covers SUBSTANCE only — the map's identity and
+    # a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: the fingerprint covers SUBSTANCE only — the map's identity and
     # prose, its traces, and its backbone (the activity columns). Releases and
     # the cards in them are SCHEDULING: drawing a row, or putting a story in
     # one, is not a revision of what a human approved.
     #
-    # This is what retires the ADR-101 carve-out. That existed because
+    # This is what retires the an-afk-loop-may-accept-and-implement-a-story-that-only-decomposes-already-ratified-substance-architecture-rule carve-out. That existed because
     # capturing a story onto its map drifted the map's hash, which broke the
     # very condition the story had to satisfy. With cards outside the basis,
     # the drift never happens and the carve-out has nothing to carve.
@@ -144,17 +144,17 @@ oversight_content_hash() {
   _oversight_hashable "$1" | _oversight_filter | shasum -a 256 | awk '{print $1}'
 }
 
-# ADR-103 retired the ADR-101 AFK pure-decomposition carve-out and its map leg.
-# The carve-out existed because ADR-095 compels a card onto the map at capture,
-# which under ADR-090 drift-invalidation re-opened the map's ratification by
+# a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule retired the an-afk-loop-may-accept-and-implement-a-story-that-only-decomposes-already-ratified-substance-architecture-rule AFK pure-decomposition carve-out and its map leg.
+# The carve-out existed because story-map-membership-and-story-content-completeness-are-enforced-at-capture-architecture-rule compels a card onto the map at capture,
+# which under story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule drift-invalidation re-opened the map's ratification by
 # construction — the condition a story had to satisfy was broken by authoring the
-# story. ADR-103 took cards out of the fingerprint basis entirely, so that no
+# story. a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule took cards out of the fingerprint basis entirely, so that no
 # longer happens and there is nothing left to exclude. Removed with it:
 # oversight_content_hash_excluding_stories, oversight_map_leg_ok,
 # oversight_is_pure_decomposition, oversight_declares_pure_decomposition.
 
 # Echo the stored oversight-hash, empty if none. Three spellings carry the same
-# fact: md frontmatter, an HTML <meta>, and — for an ADR-102 map — the data
+# fact: md frontmatter, an HTML <meta>, and — for an story-maps-render-from-json-through-a-canonical-template-architecture-rule map — the data
 # island, which is where mark-story-oversight-confirmed actually writes. The
 # island MUST be read here: the <meta> is a projection the renderer regenerates
 # from it, so a map marked but not yet re-rendered would otherwise read as
@@ -171,7 +171,7 @@ oversight_stored_hash() {
 oversight_is_confirmed() {
   grep -qiE '^human-oversight:[[:space:]]*confirmed([[:space:]]|$)' "$1" && return 0
   grep -qiE '<meta[^>]*name="human-oversight"[^>]*content="confirmed"' "$1" && return 0
-  # ADR-102 island spelling — see oversight_stored_hash for why this is load-bearing.
+  # story-maps-render-from-json-through-a-canonical-template-architecture-rule island spelling — see oversight_stored_hash for why this is load-bearing.
   grep -qiE '"humanOversight"[[:space:]]*:[[:space:]]*"confirmed"' "$1" && return 0
   return 1
 }
@@ -187,7 +187,7 @@ is_story_map_ratified() {
   [ "$stored" = "$(oversight_content_hash "$f")" ]
 }
 
-# Is this STORY approved? ADR-103 made the story map the approval surface, and a
+# Is this STORY approved? a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule made the story map the approval surface, and a
 # story carries no oversight marker of its own — not even one saying it inherits.
 # A story is approved exactly when every map it names is ratified.
 #

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@windyroad/itil",
-  "version": "1.2.0",
-  "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
+  "version": "2.0.0-preview.1111",
+  "description": "ITIL-aligned IT service management for Claude Code and Codex",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"
   },
   "type": "module",
+  "scripts": {
+    "build:codex": "node scripts/sync-codex-skills.mjs --build",
+    "prepack": "node scripts/sync-codex-skills.mjs --pack",
+    "postpack": "node scripts/sync-codex-skills.mjs --restore-pack"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,22 +22,30 @@
     "claude-code-plugin",
     "ai-agent",
     "ai-coding",
-    "itil"
+    "itil",
+    "codex"
   ],
   "files": [
     "bin/",
     "agents/",
     "hooks/",
     "skills/",
+    "skills-codex/",
     "scripts/",
     "templates/",
+    ".agents/",
     ".claude-plugin/",
+    ".codex-plugin/",
+    "hooks-codex/",
     "lib/",
     "!skills/*/eval/",
     "!agents/test/",
     "!hooks/test/",
     "!lib/test/",
     "!scripts/test/",
+    "!scripts/check-published-internal-ids.sh",
+    "!scripts/codex-work-problems.md",
+    "!scripts/sync-codex-skills.mjs",
     "!skills/*/test/"
   ]
 }

package/scripts/catchup-scan.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # packages/itil/scripts/catchup-scan.sh
 #
-# Phase 2 of P080 — `--catchup` migration-mode worklist scanner for
+# Phase 2 of problem-080-no-bidirectional-update-of-upstream-reported-problems-local-lifecycle-transitions-never-propagate-back-to-the-reporter-problem — `--catchup` migration-mode worklist scanner for
 # `/wr-itil:update-upstream`. Walks the EXISTING `.verifying.md` +
 # `.closed.md` ticket corpus, filters to tickets carrying a `## Reported
 # Upstream` back-link section (written by `/wr-itil:report-upstream`
@@ -10,16 +10,16 @@
 #
 # Read-only / local-only: this script makes NO `gh` calls and NO writes.
 # It only reads local ticket files and prints a worklist to stdout. The
-# actual `gh issue comment` / `gh issue close` posts — and the ADR-028
+# actual `gh issue comment` / `gh issue close` posts — and the external-comms-gate-voice-tone-risk-leak-evaluators-on-shared-pretooluse-surface-architecture-rule
 # external-comms + voice-tone gate composition that guards them — stay in
 # the `/wr-itil:update-upstream` SKILL's per-ticket Step 4-6 loop, which
 # consumes this worklist. Keeping the writes out of the scanner keeps it
 # AFK-safe and behaviourally testable without a live upstream.
 #
-# Idempotency (P080 Phase 2 acceptance criterion 3): a ticket whose
+# Idempotency (problem-080-no-bidirectional-update-of-upstream-reported-problems-local-lifecycle-transitions-never-propagate-back-to-the-reporter-problem Phase 2 acceptance criterion 3): a ticket whose
 # `## Upstream Lifecycle Updates` log already records an entry for the
 # current target-state transition is reported as SKIP/already-logged, NOT
-# re-posted. The marker-on-body log (append-only per the ADR-024 P080
+# re-posted. The marker-on-body log (append-only per the cross-project-problem-reporting-contract-report-upstream-skill-in-windyroad-itil-architecture-rule problem-080-no-bidirectional-update-of-upstream-reported-problems-local-lifecycle-transitions-never-propagate-back-to-the-reporter-problem
 # amendment) is the source of truth — re-running catchup is safe.
 #
 # Usage:
@@ -31,19 +31,19 @@
 #   0 = success (zero or more worklist lines on stdout)
 #   1 = error (problems-dir missing, malformed CLI args)
 #
-# Two surfaces are walked (P376 — cross-direction parity):
+# Two surfaces are walked (catchup-scanner-misses-the-inbound-direction-outbound-templates-carry-the-same-structural-defect-the-rework-fixed-on-the-inbound-side-cross-direction-parity-gap-problem — cross-direction parity):
 #   OUTBOUND — tickets with a `## Reported Upstream` section (issues WE filed
 #     against an upstream we depend on).
 #   INBOUND  — tickets with an `**Origin**: inbound-reported (#NN)` field
-#     (ADR-076 — issues someone else filed *against us* on our own repo, which
-#     the P363 rework made dispatchable). Without this leg the inbound catchup
+#     (inbound-reported-problems-rank-ahead-of-internally-discovered-problems-via-a-sort-tier-architecture-rule — issues someone else filed *against us* on our own repo, which
+#     the inbound-reported-tickets-never-receive-fix-released-verdict-on-originating-issue-problem rework made dispatchable). Without this leg the inbound catchup
 #     candidates were a manual `grep -lE '^\*\*Origin\*\*:\s*inbound-reported'`
 #     surface the maintainer had to remember after every `--catchup` run.
 # A ticket carrying BOTH surfaces emits BOTH an outbound and an inbound line
 # (the two legs are independent, mirroring the update-upstream SKILL).
 #
 # Structured stdout (one per actionable upstream entry; <= 150 bytes per
-# line per ADR-038). ASCII `->` for the transition arrow per the P334
+# line per progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule). ASCII `->` for the transition arrow per the generate-decisions-compendium-sh-uses-awk-substr-with-unicode-ellipsis-not-portable-between-macos-bsd-awk-and-linux-gnu-awk-ci-drift-gate-fires-on-cross-platform-regenerations-problem
 # awk/script portability lesson (no Unicode in machine-read output):
 #   CATCHUP P<NNN> <url> state=<state> transition=<KE->Verifying|Verifying->Closed> disclosure=<issue|pull-request>
 #   CATCHUP P<NNN> inbound-<ref> state=<state> transition=<…> direction=inbound
@@ -57,24 +57,24 @@
 # Trailing summary line (stderr) for the SKILL / human reader:
 #   SUMMARY scanned=<N> catchup=<N> skip-logged=<N> skip-out-of-band=<N>
 #
-# @problem P080 — no bidirectional update of upstream-reported problems (Phase 2 --catchup)
-# @adr ADR-024 (amended P080 Phase 2 — --catchup migration mode + idempotency contract)
-# @adr ADR-014 (governance skills commit their own work)
-# @adr ADR-038 (progressive disclosure — per-row byte budget)
-# @adr ADR-049 (invoked via wr-itil-catchup-scan bin shim, never repo-relative path)
-# @adr ADR-032 (foreground synchronous skill)
-# @adr ADR-076 (reads the `**Origin**: inbound-reported (#NN)` field for the inbound leg)
-# @adr ADR-117 (prefer an upstream pull request over an issue — the CATCHUP
+# @problem problem-080-no-bidirectional-update-of-upstream-reported-problems-local-lifecycle-transitions-never-propagate-back-to-the-reporter-problem — no bidirectional update of upstream-reported problems (Phase 2 --catchup)
+# @adr cross-project-problem-reporting-contract-report-upstream-skill-in-windyroad-itil-architecture-rule (amended problem-080-no-bidirectional-update-of-upstream-reported-problems-local-lifecycle-transitions-never-propagate-back-to-the-reporter-problem Phase 2 — --catchup migration mode + idempotency contract)
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (governance skills commit their own work)
+# @adr progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule (progressive disclosure — per-row byte budget)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (invoked via wr-itil-catchup-scan bin shim, never repo-relative path)
+# @adr governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule (foreground synchronous skill)
+# @adr inbound-reported-problems-rank-ahead-of-internally-discovered-problems-via-a-sort-tier-architecture-rule (reads the `**Origin**: inbound-reported (#NN)` field for the inbound leg)
+# @adr prefer-an-upstream-pull-request-over-an-issue-when-the-upstream-accepts-pull-requests-architecture-rule (prefer an upstream pull request over an issue — the CATCHUP
 #   row carries a `disclosure=` discriminator so the consuming skill knows
 #   whether to comment on a pull request or an issue. A `pull request` path
 #   is actionable, so it is NOT skipped alongside out-of-band / mailbox.)
-# @problem P376 — catchup scanner misses the inbound direction (cross-direction parity)
-# @rfc RFC-028 (consume the Origin field for inbound-reported verdict — extended to the catchup surface)
-# @jtbd JTBD-301 (reporter feedback loop — the catchup's primary job)
-# @jtbd JTBD-006 (AFK-safe worklist scanner)
-# @jtbd JTBD-004 (cross-repo coordination — reconcile local corpus vs upstream trackers)
-# @jtbd JTBD-001 (governance without slowing down — derive the worklist, no manual policing)
-# @jtbd JTBD-201 (symmetric local/upstream audit trail)
+# @problem catchup-scanner-misses-the-inbound-direction-outbound-templates-carry-the-same-structural-defect-the-rework-fixed-on-the-inbound-side-cross-direction-parity-gap-problem — catchup scanner misses the inbound direction (cross-direction parity)
+# @rfc consume-the-origin-field-for-inbound-reported-fix-released-verdict-release-design (consume the Origin field for inbound-reported verdict — extended to the catchup surface)
+# @jtbd report-a-problem-without-pre-classifying-it-user-outcome (reporter feedback loop — the catchup's primary job)
+# @jtbd progress-the-backlog-while-i-m-away-user-outcome (AFK-safe worklist scanner)
+# @jtbd connect-agents-across-repos-to-collaborate-user-outcome (cross-repo coordination — reconcile local corpus vs upstream trackers)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (governance without slowing down — derive the worklist, no manual policing)
+# @jtbd restore-service-fast-with-an-audit-trail-user-outcome (symmetric local/upstream audit trail)
 
 set -uo pipefail
 
@@ -108,7 +108,7 @@ fi
 # reporter most wants (fix released / closed) are the ones the pre-Phase-1
 # corpus is missing. Open / Known-Error / Parked tickets are out of scope
 # for the migration (their transitions, if linked, fire the per-ticket
-# path going forward). Dual-tolerant per RFC-002: flat layout
+# path going forward). Dual-tolerant per docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design: flat layout
 # `<NNN>-*.<status>.md` AND per-state subdir `<status>/<NNN>-*.md`.
 
 shopt -s nullglob
@@ -170,7 +170,7 @@ extract_ticket_id() {
 }
 
 # Extract the actionable inbound issue ref from the `**Origin**:
-# inbound-reported (<ref>)` field (ADR-076). Returns the `#NN` /
+# inbound-reported (<ref>)` field (inbound-reported-problems-rank-ahead-of-internally-discovered-problems-via-a-sort-tier-architecture-rule). Returns the `#NN` /
 # `<repo>#NN` token, or empty when the Origin is not inbound-reported OR
 # carries no actionable issue number (e.g. "relayed from other projects").
 extract_inbound_ref() {

package/scripts/check-fail-soft-skip-discipline.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# check-fail-soft-skip-discipline.sh — advisory lint for P351 (skills
+# check-fail-soft-skip-discipline.sh — advisory lint for skills-fail-soft-skip-when-their-precondition-config-is-missing-should-auto-bootstrap-with-user-input-as-needed-rather-than-silently-skipping-problem (skills
 # fail-soft-skip when their precondition config is missing — should
 # auto-bootstrap with user input as needed rather than silently
 # skipping).
@@ -7,7 +7,7 @@
 # Detects SKILL.md prose that names the fail-soft-skip pattern without
 # a paired auto-bootstrap routine. The default behaviour of skills with
 # config-file preconditions has been "fail-soft skip" when the config is
-# missing; the right behaviour (per P351) is to recognise the gap and
+# missing; the right behaviour (per skills-fail-soft-skip-when-their-precondition-config-is-missing-should-auto-bootstrap-with-user-input-as-needed-rather-than-silently-skipping-problem) is to recognise the gap and
 # auto-bootstrap the missing config — invoking AskUserQuestion for any
 # required user input, then proceeding with the original pass. In AFK
 # mode where AskUserQuestion is unavailable, queue a config-direction
@@ -43,13 +43,13 @@
 #   Promote `WR_FAIL_SOFT_SKIP_WARN_ONLY=0` once every affected SKILL.md
 #   has been migrated to the auto-bootstrap pattern.
 #
-# @adr ADR-040 (advisory-then-load-bearing reusable pattern)
-# @adr ADR-049 (plugin-bundled scripts; PATH shim)
-# @adr ADR-052 (behavioural-tests-default)
-# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory exit 0)
-# @jtbd JTBD-001 (Enforce Governance Without Slowing Down)
-# @jtbd JTBD-101 (Extend the Suite with New Plugins)
-# @problem P351 (skills fail-soft-skip when precondition config missing
+# @adr session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule (advisory-then-load-bearing reusable pattern)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin-bundled scripts; PATH shim)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural-tests-default)
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (non-interactive fail-safe — advisory exit 0)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (Enforce Governance Without Slowing Down)
+# @jtbd extend-the-suite-with-new-plugins-user-outcome (Extend the Suite with New Plugins)
+# @problem skills-fail-soft-skip-when-their-precondition-config-is-missing-should-auto-bootstrap-with-user-input-as-needed-rather-than-silently-skipping-problem (skills fail-soft-skip when precondition config missing
 #                — should auto-bootstrap with user input)
 
 set -uo pipefail
@@ -132,7 +132,7 @@ done
 if [ "$violations" -gt 0 ]; then
   echo "" >&2
   echo "check-fail-soft-skip-discipline: $violations potential fail-soft-skip site(s) across $scanned SKILL.md file(s)" >&2
-  echo "Phase 1 advisory (WR_FAIL_SOFT_SKIP_WARN_ONLY=$WARN_ONLY). Authors should pair each site with an auto-bootstrap routine per P351." >&2
+  echo "Phase 1 advisory (WR_FAIL_SOFT_SKIP_WARN_ONLY=$WARN_ONLY). Authors should pair each site with an auto-bootstrap routine per skills-fail-soft-skip-when-their-precondition-config-is-missing-should-auto-bootstrap-with-user-input-as-needed-rather-than-silently-skipping-problem." >&2
   if [ "$WARN_ONLY" = "0" ]; then
     exit 1
   fi

package/scripts/check-fix-rfc-trace.sh

@@ -60,18 +60,18 @@
 # Exit 3 is a refusal the caller can act on without reading prose, and is
 # distinct from caller-misuse 2.
 #
-# @adr ADR-119 (a fix proposal draws a release row, never a document; the reader
+# @adr a-fix-proposal-draws-a-release-row-never-a-document-architecture-rule (a fix proposal draws a release row, never a document; the reader
 #   is repointed ahead of the writer and fails closed during the window)
-# @adr ADR-103 (a release row is the RFC; the map is the approval surface, and
+# @adr a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule (a release row is the RFC; the map is the approval surface, and
 #   a proposal needing a new map queues for a person)
-# @adr ADR-071 (every fix goes through an RFC — unconditional, no carve-out)
-# @adr ADR-060 (I1 load-bearing-from-the-start; I13 fix-proposal invariant)
-# @adr ADR-049 (invoked via the wr-itil-check-fix-rfc-trace bin shim on
+# @adr every-fix-goes-through-an-rfc-architecture-rule (every fix goes through an RFC — unconditional, no carve-out)
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (I1 load-bearing-from-the-start; I13 fix-proposal invariant)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (invoked via the wr-itil-check-fix-rfc-trace bin shim on
 #   $PATH; never repo-relative from a SKILL)
-# @adr ADR-052 (behavioural bats coverage in
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural bats coverage in
 #   packages/itil/scripts/test/check-fix-rfc-trace.bats)
-# @problem P314
-# @problem P508
+# @problem rework-the-fix-time-rfc-trace-gate-wrong-lifecycle-placement-hard-block-should-be-auto-create-per-corrected-known-error-semantics-problem
+# @problem the-fix-proposal-still-instantiates-a-standalone-rfc-document-after-made-it-a-release-row-problem
 
 set -uo pipefail
 

package/scripts/check-locale-discipline.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# check-locale-discipline.sh — advisory lint for P328 (BSD locale UTF-8
+# check-locale-discipline.sh — advisory lint for bsd-grep-sed-awk-on-macos-silently-fail-or-error-on-utf-8-without-lc-all-en-us-utf-8-problem (BSD locale UTF-8
 # friction on macOS).
 #
 # BSD `grep` / `sed` / `awk` on macOS silently fail (or emit
@@ -8,8 +8,8 @@
 # `LC_ALL=en_US.UTF-8` set. Our prose surfaces (ADRs, problem-ticket bodies,
 # briefing entries, SKILL.md files) are pervasively em-dash / smart-quote
 # rich, so any script that grep / sed / awks those surfaces is exposed.
-# P328 captures three distinct incident classes from the 2026-05-30
-# ADR-077 compendium session.
+# bsd-grep-sed-awk-on-macos-silently-fail-or-error-on-utf-8-without-lc-all-en-us-utf-8-problem captures three distinct incident classes from the 2026-05-30
+# generated-docs-decisions-readme-md-compendium-as-token-cheap-load-surface-for-routine-architect-agent-compliance-architecture-rule compendium session.
 #
 # This lint walks `packages/*/scripts/*.sh`, `packages/*/hooks/*.sh`, and
 # `packages/*/lib/*.sh` (including `packages/*/hooks/lib/*.sh`) and reports
@@ -40,15 +40,15 @@
 #   been migrated. Until then, the warnings are signal-only — they identify
 #   scripts that may silently mis-process UTF-8 input on macOS.
 #
-# @adr ADR-040 (advisory-then-load-bearing reusable pattern)
-# @adr ADR-049 (plugin-bundled scripts; PATH shim)
-# @adr ADR-052 (behavioural-tests-default)
-# @adr ADR-080 (highest-version-wins shim wrapper)
-# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory exit 0)
-# @adr ADR-005 (Plugin testing strategy)
-# @jtbd JTBD-001 (Enforce Governance Without Slowing Down)
-# @jtbd JTBD-101 (Extend the Suite with New Plugins)
-# @problem P328 (BSD grep/sed/awk on macOS friction with UTF-8)
+# @adr session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule (advisory-then-load-bearing reusable pattern)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin-bundled scripts; PATH shim)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural-tests-default)
+# @adr highest-version-wins-shim-wrapper-for-plugin-scaffold-template-shims-architecture-rule (highest-version-wins shim wrapper)
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (non-interactive fail-safe — advisory exit 0)
+# @adr plugin-testing-strategy-architecture-rule (Plugin testing strategy)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (Enforce Governance Without Slowing Down)
+# @jtbd extend-the-suite-with-new-plugins-user-outcome (Extend the Suite with New Plugins)
+# @problem bsd-grep-sed-awk-on-macos-silently-fail-or-error-on-utf-8-without-lc-all-en-us-utf-8-problem (BSD grep/sed/awk on macOS friction with UTF-8)
 
 set -uo pipefail
 
@@ -172,7 +172,7 @@ for f in "${TARGETS[@]}"; do
 done
 
 if [ "$violations" -gt 0 ]; then
-  printf 'check-locale-discipline: %d violation(s) across %d script(s) — add `export LC_ALL=en_US.UTF-8` at the top of each script that calls grep/sed/awk on UTF-8 content, or use an inline `LC_ALL=...` prefix per invocation (P328).\n' \
+  printf 'check-locale-discipline: %d violation(s) across %d script(s) — add `export LC_ALL=en_US.UTF-8` at the top of each script that calls grep/sed/awk on UTF-8 content, or use an inline `LC_ALL=...` prefix per invocation (bsd-grep-sed-awk-on-macos-silently-fail-or-error-on-utf-8-without-lc-all-en-us-utf-8-problem).\n' \
     "$violations" "$scanned" >&2
   if [ "$WARN_ONLY" = "1" ]; then
     exit 0

package/scripts/check-problems-readme-budget.sh

@@ -2,9 +2,9 @@
 # packages/itil/scripts/check-problems-readme-budget.sh
 #
 # Diagnose-only advisory script for the docs/problems/README.md "Last
-# reviewed" line (line 3). Sibling to P099's
+# reviewed" line (line 3). Sibling to problem-099-docs-briefing-md-grows-unbounded-via-run-retro-appends-violates-progressive-disclosure-problem's
 # packages/retrospective/scripts/check-briefing-budgets.sh on a
-# different surface — both apply ADR-040 line 92's reusable triplet
+# different surface — both apply session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule line 92's reusable triplet
 # (read-only diagnostic + behavioural bats + ADR-tier-budget
 # enforcement clause) to an accumulator-doc surface.
 #
@@ -13,7 +13,7 @@
 #
 # Default <readme-path> is ./docs/problems/README.md.
 # Threshold is read from PROBLEMS_README_LINE3_MAX_BYTES (default 5120
-# — matches ADR-040 Tier 3 Tier 3 envelope; the soft per-fragment cap
+# — matches session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule Tier 3 Tier 3 envelope; the soft per-fragment cap
 # is 1024 bytes, enforced by the SKILL.md authoring contracts in
 # manage-problem / transition-problem / transition-problems /
 # review-problems / reconcile-readme).
@@ -23,23 +23,23 @@
 #   2 = parse error (README path missing or unreadable)
 #
 # Output format on overflow (one line, terse machine-readable per
-# ADR-038 progressive-disclosure budget):
+# progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule progressive-disclosure budget):
 #   OVER <readme-path> line=3 bytes=<N> threshold=<N>
 #
 # Output is empty (no lines) when line 3 is under the threshold.
 #
 # Read-only — does NOT mutate the README. Truncation is owned by the
-# per-operation refresh contracts in manage-problem Step 5 P094 +
-# Step 7 P062 (and the sibling skills).
+# per-operation refresh contracts in manage-problem Step 5 problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem +
+# Step 7 problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem (and the sibling skills).
 #
-# @problem P134
-# @adr ADR-040 (Session-start briefing surface — Tier 3 budget; line 92's
+# @problem docs-problems-readme-md-line-3-narrative-blob-accumulator-bloat-sibling-to-briefing-tier-3-on-a-different-surface-problem
+# @adr session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule (Session-start briefing surface — Tier 3 budget; line 92's
 #   reusable-pattern note explicitly names "problems index" as a
 #   candidate surface for this triplet)
-# @adr ADR-038 (Progressive disclosure — per-row terse budget)
-# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory exit 0)
-# @adr ADR-005 (Plugin testing strategy)
-# @jtbd JTBD-001 / JTBD-006 / JTBD-101
+# @adr progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule (Progressive disclosure — per-row terse budget)
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (non-interactive fail-safe — advisory exit 0)
+# @adr plugin-testing-strategy-architecture-rule (Plugin testing strategy)
+# @jtbd enforce-governance-without-slowing-down-user-outcome / progress-the-backlog-while-i-m-away-user-outcome / extend-the-suite-with-new-plugins-user-outcome
 
 set -uo pipefail
 

package/scripts/check-rfc-has-stories.sh

@@ -1,19 +1,19 @@
 #!/usr/bin/env bash
-# check-rfc-has-stories.sh — ADR-089 (every RFC has at least one story).
+# check-rfc-has-stories.sh — every-rfc-has-at-least-one-story-architecture-rule (every RFC has at least one story).
 #
 # The load-bearing detection half of the manage-rfc `proposed -> accepted` gate:
 # an RFC must list >=1 story before it can be accepted. Exits non-zero (with a
 # stderr directive) when the RFC's `stories:` frontmatter is empty (`stories: []`)
 # or missing; exits 0 when >=1 `STORY-NNN` is listed (inline or block-list).
 #
-# This removes the pre-ADR-089 empty-stories fallback (the "atomic RFC ships with
-# stories: [] / JTBD-101 friction guard" shape). An atomic fix is now an RFC with
+# This removes the pre-every-rfc-has-at-least-one-story-architecture-rule empty-stories fallback (the "atomic RFC ships with
+# stories: [] / extend-the-suite-with-new-plugins-user-outcome friction guard" shape). An atomic fix is now an RFC with
 # exactly one full story, never an empty list.
 #
 # Usage: check-rfc-has-stories.sh <rfc-file>
 # Exit:  0 = >=1 story; 1 = empty/missing stories; 2 = usage / file error.
 #
-# Authority: ADR-089. Driver: P404. Behavioural test: check-rfc-has-stories.bats.
+# Authority: every-rfc-has-at-least-one-story-architecture-rule. Driver: implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem. Behavioural test: check-rfc-has-stories.bats.
 set -euo pipefail
 
 rfc="${1:-}"
@@ -30,13 +30,13 @@ fi
 stories_line="$(awk '/^stories:/{print; exit}' "$rfc")"
 
 if [ -z "$stories_line" ]; then
-  echo "check-rfc-has-stories: $rfc has no 'stories:' field — an RFC must list >=1 story (ADR-089). Decompose the fix into >=1 story before accepting." >&2
+  echo "check-rfc-has-stories: $rfc has no 'stories:' field — an RFC must list >=1 story (every-rfc-has-at-least-one-story-architecture-rule). Decompose the fix into >=1 story before accepting." >&2
   exit 1
 fi
 
 # Reject an explicit empty inline list: `stories: []`.
 if printf '%s' "$stories_line" | grep -qE '^stories:[[:space:]]*\[[[:space:]]*\][[:space:]]*$'; then
-  echo "check-rfc-has-stories: $rfc has empty 'stories: []' — an RFC must list >=1 story (ADR-089; the empty-stories fallback is removed). An atomic fix is an RFC with exactly one full story." >&2
+  echo "check-rfc-has-stories: $rfc has empty 'stories: []' — an RFC must list >=1 story (every-rfc-has-at-least-one-story-architecture-rule; the empty-stories fallback is removed). An atomic fix is an RFC with exactly one full story." >&2
   exit 1
 fi
 
@@ -55,5 +55,5 @@ if awk '
   exit 0
 fi
 
-echo "check-rfc-has-stories: $rfc 'stories:' lists no STORY- ids — an RFC must list >=1 story (ADR-089)." >&2
+echo "check-rfc-has-stories: $rfc 'stories:' lists no STORY- ids — an RFC must list >=1 story (every-rfc-has-at-least-one-story-architecture-rule)." >&2
 exit 1