@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/scripts/check-rfc-rejected-alternatives.sh

@@ -1,16 +1,16 @@
 #!/usr/bin/env bash
-# check-rfc-rejected-alternatives.sh — ADR-052 behavioural lint enforcing
-# ADR-070 (RFCs hold no independent decisions).
+# check-rfc-rejected-alternatives.sh — behavioural-tests-default-for-skill-testing-architecture-rule behavioural lint enforcing
+# rfcs-hold-no-independent-decisions-architecture-rule (RFCs hold no independent decisions).
 #
-# Invariant (ADR-070 § Confirmation): no RFC body in the RFC directory
+# Invariant (rfcs-hold-no-independent-decisions-architecture-rule § Confirmation): no RFC body in the RFC directory
 # contains a "Considered Options / Alternatives Rejected" block WITHOUT a
-# matching `adrs:` frontmatter reference. ADR-070 line 44 names the
+# matching `adrs:` frontmatter reference. rfcs-hold-no-independent-decisions-architecture-rule line 44 names the
 # machine-detectable tell: "an RFC body containing a rejected-alternatives
 # block with no matching `adrs:` reference is a decision masquerading as
 # scope." Contested choices belong in an ADR (referenced via `adrs:`),
 # never re-argued in the RFC body.
 #
-# This is an ARTEFACT-STATE behavioural check (ADR-052): given an RFC
+# This is an ARTEFACT-STATE behavioural check (behavioural-tests-default-for-skill-testing-architecture-rule): given an RFC
 # corpus directory, it inspects the on-disk RFC bodies + frontmatter and
 # reports violations. It is NOT a structural grep of any SKILL.md / agent
 # prose. Detection targets a markdown HEADING block (`## ... Considered
@@ -24,10 +24,10 @@
 # "Considered Options" headings — they ARE the decision ledger; this lint
 # never scans them.
 #
-# @adr ADR-070 (RFCs hold no independent decisions — the invariant)
-# @adr ADR-052 (behavioural-tests-default — artefact-state assertion)
-# @adr ADR-049 (plugin-bundled scripts; adopters run this over their docs/rfcs)
-# @problem P310 (RFC decisions invisible to the ADR-066 oversight net)
+# @adr rfcs-hold-no-independent-decisions-architecture-rule (RFCs hold no independent decisions — the invariant)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (behavioural-tests-default — artefact-state assertion)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin-bundled scripts; adopters run this over their docs/rfcs)
+# @problem rfcs-carry-independent-decisions-invisible-to-the-human-oversight-net-problem (RFC decisions invisible to the human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule oversight net)
 
 set -euo pipefail
 
@@ -58,7 +58,7 @@ for f in "$rfcs_dir"/RFC-*.md; do
   if grep -qE "$heading_re" "$f"; then
     if ! grep -qE "$adrs_re" "$f"; then
       line=$(grep -nE "$heading_re" "$f" | head -1 | cut -d: -f1)
-      echo "VIOLATION  $f:${line}  rejected-alternatives block with empty/absent adrs: frontmatter (ADR-070)"
+      echo "VIOLATION  $f:${line}  rejected-alternatives block with empty/absent adrs: frontmatter (rfcs-hold-no-independent-decisions-architecture-rule)"
       violations=$((violations + 1))
     fi
   fi
@@ -66,7 +66,7 @@ done
 shopt -u nullglob
 
 if [ "$violations" -gt 0 ]; then
-  echo "check-rfc-rejected-alternatives: $violations violation(s) across $scanned RFC(s) — an RFC carrying a rejected-alternatives block must reference its governing ADR(s) in adrs: (ADR-070)." >&2
+  echo "check-rfc-rejected-alternatives: $violations violation(s) across $scanned RFC(s) — an RFC carrying a rejected-alternatives block must reference its governing ADR(s) in adrs: (rfcs-hold-no-independent-decisions-architecture-rule)." >&2
   exit 1
 fi
 

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

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
-# check-rfc-stories-ratified.sh — ADR-103 (an RFC may reference only APPROVED stories).
+# check-rfc-stories-ratified.sh — a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule (an RFC may reference only APPROVED stories).
 #
 # For each STORY-NNN in the RFC's `stories:` frontmatter, resolve the story file
 # under <stories-root>/*/STORY-NNN-*.md and ask `story_is_approved`: is every map
 # in that story's `story-maps:` field ratified? A story carries no oversight
-# marker of its own (ADR-103), so the remedy for a failure is always to ratify
+# marker of its own (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule), so the remedy for a failure is always to ratify
 # the MAP. Exit non-zero, with a stderr directive naming the offending stories,
 # if any listed story is unapproved or missing.
 #
-# Composes with check-rfc-has-stories.sh (ADR-089): has-stories checks >=1 story
+# Composes with check-rfc-has-stories.sh (every-rfc-has-at-least-one-story-architecture-rule): has-stories checks >=1 story
 # exists; this checks each listed story is ratified. An empty `stories:` passes
 # vacuously here (the has-stories gate owns the emptiness rejection).
 #
@@ -16,10 +16,10 @@
 # Exit:  0 = all listed stories ratified (or none listed); 1 = >=1 unratified/missing;
 #        2 = usage / file error.
 #
-# Authority: ADR-090, ADR-103. Driver: P404 Phase 2. Test: check-rfc-stories-ratified.bats.
+# Authority: 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. Driver: implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem Phase 2. Test: check-rfc-stories-ratified.bats.
 set -euo pipefail
 
-# Adopter-safe: source the shared lazy-fingerprint lib RELATIVE TO THIS SCRIPT (P317).
+# Adopter-safe: source the shared lazy-fingerprint lib RELATIVE TO THIS SCRIPT (capture-problem-capture-rfc-manage-problem-step-2-create-gate-marker-step-sources-repo-relative-packages-itil-hooks-lib-sh-fails-in-adopter-installs-recurring-published-path-class-problem).
 LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
   echo "check-rfc-stories-ratified: cannot locate lib dir" >&2; exit 2; }
 # shellcheck source=/dev/null
@@ -54,16 +54,16 @@ for id in $ids; do
     unratified="$unratified $id(missing)"
     continue
   fi
-  # ADR-103: approval reaches a story through its map. Judging it by the story
-  # predicate alone would re-create the P456 deadlock one tier up — the RFC tier
-  # would block on a story ADR-103 approves.
+  # a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: approval reaches a story through its map. Judging it by the story
+  # predicate alone would re-create the afk-iter-cannot-progress-a-ratified-known-error-when-the-fix-vehicle-rfc-has-empty-stories-problem deadlock one tier up — the RFC tier
+  # would block on a story a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule approves.
   if ! story_is_approved "$f" "$maps_root"; then
     unratified="$unratified $id(unapproved)"
   fi
 done
 
 if [ -n "$unratified" ]; then
-  echo "check-rfc-stories-ratified: $rfc references unapproved stories:$unratified — ADR-103: an RFC may reference only approved stories, and a story is approved by its story MAP. Ratify the map named in the story's story-maps: field via /wr-itil:manage-story-map <MAP-ID> ratify — a story carries no oversight marker of its own." >&2
+  echo "check-rfc-stories-ratified: $rfc references unapproved stories:$unratified — a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: an RFC may reference only approved stories, and a story is approved by its story MAP. Ratify the map named in the story's story-maps: field via /wr-itil:manage-story-map <MAP-ID> ratify — a story carries no oversight marker of its own." >&2
   exit 1
 fi
 exit 0

package/scripts/check-ticket-jtbd-ratification.sh

@@ -1,15 +1,15 @@
 #!/usr/bin/env bash
 # wr-itil — predicate: are the JTBDs cited by a problem ticket all ratified?
-# (RFC-016 / P344 — orchestrator-layer mirror of ADR-068 surface 3)
+# (wr-itil-work-problems-step-3-5-jtbd-ratification-predicate-check-orchestrator-layer-mirror-of-surface-3-release-design / wr-itil-work-problems-orchestrator-should-predicate-check-the-cited-jtbds-of-the-selected-ticket-before-dispatching-the-iter-worker-wasted-iter-dispatch-class-when-jtbds-are-unratified-problem — orchestrator-layer mirror of jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule surface 3)
 #
 # `/wr-itil:work-problems` Step 3.5 invokes this script on the selected
 # ticket BEFORE dispatching the iter-subprocess. The per-iter JTBD review
 # subagent already catches the same class via the [Unratified Dependency]
-# verdict (ADR-068 surface 3), but only AFTER spending iter-dispatch cost.
+# verdict (jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule surface 3), but only AFTER spending iter-dispatch cost.
 # This script shifts the predicate left to the orchestrator layer for the
 # cost of one grep + one shim call per cited JTBD.
 #
-# Polarity (RFC-016 § Scope — outer-script polarity INVERTED vs the inner
+# Polarity (wr-itil-work-problems-step-3-5-jtbd-ratification-predicate-check-orchestrator-layer-mirror-of-surface-3-release-design § Scope — outer-script polarity INVERTED vs the inner
 # per-JTBD predicate it dispatches):
 #   exit 0 = all cited JTBDs ratified OR ticket cites none → orchestrator
 #            proceeds with the dispatch. No stdout.
@@ -20,7 +20,7 @@
 #   exit 2 = ticket file missing / unreadable. No stdout; reason on stderr.
 #
 # Silent-pass on missing per-JTBD shim: when `wr-jtbd-is-job-or-persona-
-# unconfirmed` is not on PATH (degenerate adopter case per ADR-031 —
+# unconfirmed` is not on PATH (degenerate adopter case per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule —
 # adopter installed @windyroad/itil without @windyroad/jtbd), the script
 # silent-passes (exit 0). The iter-subprocess JTBD subagent is the
 # authoritative second-source; orchestrator-layer pre-check is optimisation.
@@ -30,11 +30,11 @@
 #     <ticket-file> = path to a problem-ticket .md file (relative or absolute)
 #     JTBD_DIR defaults to docs/jtbd
 #
-# @rfc RFC-016 (P344 — work-problems Step 3.5 JTBD ratification predicate)
-# @adr ADR-068 (JTBD + persona human-oversight marker — surface 3 mirrored)
-# @adr ADR-074 (substance-confirm-before-build — JTBD-as-driver symmetric)
-# @adr ADR-049 (PATH shim grammar)
-# @problem P344
+# @rfc wr-itil-work-problems-step-3-5-jtbd-ratification-predicate-check-orchestrator-layer-mirror-of-surface-3-release-design (wr-itil-work-problems-orchestrator-should-predicate-check-the-cited-jtbds-of-the-selected-ticket-before-dispatching-the-iter-worker-wasted-iter-dispatch-class-when-jtbds-are-unratified-problem — work-problems Step 3.5 JTBD ratification predicate)
+# @adr jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule (JTBD + persona human-oversight marker — surface 3 mirrored)
+# @adr confirm-a-decision-s-substance-before-building-dependent-work-on-it-architecture-rule (substance-confirm-before-build — JTBD-as-driver symmetric)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (PATH shim grammar)
+# @problem wr-itil-work-problems-orchestrator-should-predicate-check-the-cited-jtbds-of-the-selected-ticket-before-dispatching-the-iter-worker-wasted-iter-dispatch-class-when-jtbds-are-unratified-problem
 
 set -uo pipefail
 
@@ -51,7 +51,7 @@ JTBD_DIR="${2:-docs/jtbd}"
   exit 2
 }
 
-# ADR-031 silent-pass: if the per-JTBD predicate shim is absent, the
+# problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule silent-pass: if the per-JTBD predicate shim is absent, the
 # orchestrator-layer pre-check cannot run. The iter-subprocess JTBD
 # subagent will catch any unratified-dep at the inner layer; this script
 # is the optimisation surface, not the authoritative gate.

package/scripts/check-upstream-responses.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # packages/itil/scripts/check-upstream-responses.sh
 #
-# Phase 1 of P249 — outbound symmetric counterpart to ADR-062's inbound
+# Phase 1 of no-process-for-issue-reporters-to-check-for-responses-symmetric-gap-to-inbound-discovery-problem — outbound symmetric counterpart to inbound-upstream-report-discovery-assessment-pipeline-peer-of-architecture-rule's inbound
 # discovery pipeline. Scans local problem tickets for `## Reported
 # Upstream` back-link sections (written by `/wr-itil:report-upstream`
 # Step 7), polls each upstream issue via `gh issue view`, diffs against
@@ -10,7 +10,7 @@
 #
 # Read-only externally: `gh issue view`, or `gh pr view` plus the pull
 # request's inline review comments via `gh api` — no
-# `gh issue comment` / `gh issue create`. Does NOT trip ADR-028
+# `gh issue comment` / `gh issue create`. Does NOT trip external-comms-gate-voice-tone-risk-leak-evaluators-on-shared-pretooluse-surface-architecture-rule
 # external-comms gate. AFK-safe.
 #
 # Usage:
@@ -28,7 +28,7 @@
 #   2 = partial — some upstream polls failed; successful ones are still
 #       written to cache + audit-log
 #
-# Structured stdout (one per ticket; ≤ 150 bytes per line per ADR-038):
+# Structured stdout (one per ticket; ≤ 150 bytes per line per progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule):
 #   NEW     P<NNN> <url> state=<state> new-responses=<N>
 #   STATE   P<NNN> <url> state=<old>→<new>
 #   LABEL   P<NNN> <url> labels-added=<csv> labels-removed=<csv>
@@ -37,26 +37,26 @@
 #
 # Precedence when multiple change classes apply: STATE > NEW (responses) > LABEL > NONE.
 #
-# @problem P249 — no process for issue reporters to check for responses (Phase 1)
-# @adr ADR-014 (governance skills commit their own work)
-# @adr ADR-024 (back-link source of truth — Reported Upstream URL)
-# @adr ADR-031 (cache file placement under docs/problems/)
-# @adr ADR-032 (foreground synchronous skill)
-# @adr ADR-038 (progressive disclosure — per-row byte budget)
-# @adr ADR-049 (invoked via wr-itil-check-upstream-responses bin shim)
-# @adr ADR-062 (inbound discovery — symmetric counterpart)
-# @adr ADR-117 (prefer an upstream pull request over an issue — the
+# @problem no-process-for-issue-reporters-to-check-for-responses-symmetric-gap-to-inbound-discovery-problem — no process for issue reporters to check for responses (Phase 1)
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (governance skills commit their own work)
+# @adr cross-project-problem-reporting-contract-report-upstream-skill-in-windyroad-itil-architecture-rule (back-link source of truth — Reported Upstream URL)
+# @adr problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule (cache file placement under docs/problems/)
+# @adr governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule (foreground synchronous skill)
+# @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-check-upstream-responses bin shim)
+# @adr inbound-upstream-report-discovery-assessment-pipeline-peer-of-architecture-rule (inbound discovery — symmetric counterpart)
+# @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
 #   `## Reported Upstream` disclosure path selects `gh pr view` over
 #   `gh issue view`. An ABSENT path means a ticket written before that
-#   decision, which the pre-ADR-117 skill could only ever have filed as
+#   decision, which the pre-prefer-an-upstream-pull-request-over-an-issue-when-the-upstream-accepts-pull-requests-architecture-rule skill could only ever have filed as
 #   a public issue — so absent means issue, and no probe is needed. This
-#   is the explicit legacy-path decision ADR-117 requires; an
+#   is the explicit legacy-path decision prefer-an-upstream-pull-request-over-an-issue-when-the-upstream-accepts-pull-requests-architecture-rule requires; an
 #   issue-then-pr probe would double the call count for every legacy
 #   ticket on every cycle against a `gh` rate budget nothing governs.)
-# @jtbd JTBD-004 (cross-repo coordination — primary anchor)
-# @jtbd JTBD-006 (AFK-safe)
-# @jtbd JTBD-001 (governance without slowing down)
-# @jtbd JTBD-201 (audit trail)
+# @jtbd connect-agents-across-repos-to-collaborate-user-outcome (cross-repo coordination — primary anchor)
+# @jtbd progress-the-backlog-while-i-m-away-user-outcome (AFK-safe)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (governance without slowing down)
+# @jtbd restore-service-fast-with-an-audit-trail-user-outcome (audit trail)
 
 set -uo pipefail
 
@@ -119,7 +119,7 @@ UPDATED_CACHE="$CACHE_JSON"
 
 # ── Discover tickets with `## Reported Upstream` URL ────────────────────────
 #
-# Dual-tolerant per RFC-002: flat layout `<NNN>-*.<status>.md` AND
+# 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 layout `<status>/<NNN>-*.md`.
 
 shopt -s nullglob
@@ -171,7 +171,7 @@ extract_disclosure_path() {
 
 # Which `gh` read subcommand polls this ticket's upstream artefact?
 # `pull request` (or `pull-request`) → `gh pr view`; anything else,
-# INCLUDING an absent disclosure path, → `gh issue view` (ADR-117).
+# INCLUDING an absent disclosure path, → `gh issue view` (prefer-an-upstream-pull-request-over-an-issue-when-the-upstream-accepts-pull-requests-architecture-rule).
 upstream_view_noun() {
   case "$1" in
     *pull*request*) echo "pr" ;;
@@ -349,9 +349,9 @@ if [ ! -f "$AUDIT_LOG" ]; then
   cat > "$AUDIT_LOG" <<'EOF'
 # Outbound upstream-response check — audit log
 
-> Forward-chronology audit trail of `/wr-itil:check-upstream-responses` passes (P249 Phase 1). Each pass appends a `## YYYY-MM-DDTHH:MM:SSZ` heading with tickets polled, response classes observed, and cache refresh confirmation. Mirrors `docs/audits/inbound-discovery-log.md` shape per ADR-062's audit-log surface contract.
+> Forward-chronology audit trail of `/wr-itil:check-upstream-responses` passes (no-process-for-issue-reporters-to-check-for-responses-symmetric-gap-to-inbound-discovery-problem Phase 1). Each pass appends a `## YYYY-MM-DDTHH:MM:SSZ` heading with tickets polled, response classes observed, and cache refresh confirmation. Mirrors `docs/audits/inbound-discovery-log.md` shape per inbound-upstream-report-discovery-assessment-pipeline-peer-of-architecture-rule's audit-log surface contract.
 >
-> Path is intentional per CLAUDE.md P131 — project-generated artefacts go under `docs/`, never `.claude/`.
+> Path is intentional per CLAUDE.md agents-write-project-generated-artefacts-under-claude-user-controlled-config-space-gate-exclusions-are-read-tolerance-not-write-permission-problem — project-generated artefacts go under `docs/`, never `.claude/`.
 
 EOF
 fi

package/scripts/classify-readme-drift.sh

@@ -3,8 +3,8 @@
 #
 # Classify reconcile-readme.sh exit-1 drift output as either
 # inline-refresh-deferrable (covered by uncommitted ticket renames in the
-# working tree — in-flow P094/P062 refresh will land the README correction
-# in the upcoming commit per ADR-014) or halt-route-reconcile (committed
+# working tree — in-flow problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem/problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem refresh will land the README correction
+# in the upcoming commit per governance-skills-commit-their-own-completed-work-architecture-rule) or halt-route-reconcile (committed
 # cross-session drift — must route to /wr-itil:reconcile-readme).
 #
 # Usage:
@@ -20,8 +20,8 @@
 # Output (stdout, single classification line):
 #   INLINE_REFRESH covered=<N>            — every drift ID is the destination
 #                                            of a staged rename in the working
-#                                            tree; defer to in-flow P094/P062
-#                                            refresh per ADR-014.
+#                                            tree; defer to in-flow problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem/problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem
+#                                            refresh per governance-skills-commit-their-own-completed-work-architecture-rule.
 #   HALT_ROUTE_RECONCILE uncovered=<N>    — at least one drift ID is NOT
 #                                            covered by a working-tree rename;
 #                                            committed cross-session drift OR
@@ -33,18 +33,18 @@
 #   1 = HALT_ROUTE_RECONCILE
 #   2 = parse error (drift-stdout-file missing or empty)
 #
-# @problem P149 — manage-problem Step 0 reconcile halt-on-drift directive
+# @problem wr-itil-manage-problem-step-0-reconcile-halt-on-drift-directive-doesn-t-distinguish-uncommitted-rename-rooted-drift-same-session-pending-from-committed-cross-session-drift-should-refresh-inline-rather-than-halt-for-the-former-case-problem — manage-problem Step 0 reconcile halt-on-drift directive
 #                 doesn't distinguish uncommitted-rename-rooted drift from
 #                 committed cross-session drift; this script is the
 #                 detection mechanism that makes the carve-out behavioural.
-# @adr ADR-014 (single-commit grain — the carve-out preserves it for the
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (single-commit grain — the carve-out preserves it for the
 #               in-flow path while keeping cross-session drift safety)
-# @adr ADR-013 Rule 6 (AFK fail-safe — committed drift still routes to
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (AFK fail-safe — committed drift still routes to
 #                       /wr-itil:reconcile-readme; only the inline path
 #                       is added)
-# @adr ADR-038 (progressive disclosure — output is a single terse line)
-# @jtbd JTBD-006 (Progress the Backlog While I'm Away — AFK loop continuity)
-# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — single-commit grain)
+# @adr progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule (progressive disclosure — output is a single terse line)
+# @jtbd progress-the-backlog-while-i-m-away-user-outcome (Progress the Backlog While I'm Away — AFK loop continuity)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (Enforce Governance Without Slowing Down — single-commit grain)
 
 set -uo pipefail
 
@@ -84,9 +84,9 @@ fi
 #
 #   2. Same-ID D + (A or ??) pair (substantial-body edit defeated rename-
 #      detection so the move renders as delete + add for the same ticket ID
-#      — P306). We treat such a pair as equivalent to an R entry for drift-
-#      coverage purposes: the in-flow P094/P062 refresh will reconcile the
-#      README in the upcoming commit per ADR-014.
+#      — classify-readme-drift-sh-only-covers-staged-rename-r-entries-a-same-id-delete-add-d-a-pair-is-uncovered-and-false-halts-problem). We treat such a pair as equivalent to an R entry for drift-
+#      coverage purposes: the in-flow problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem/problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem refresh will reconcile the
+#      README in the upcoming commit per governance-skills-commit-their-own-completed-work-architecture-rule.
 #
 # We match the destination path's ticket ID — the post-rename status is what
 # the in-flow refresh will reconcile.

package/scripts/codex-agent.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const source = join(root, "agents", "hang-off-check.md");
+const filename = "wr-itil-hang-off-check.toml";
+const owner = "# Generated by @windyroad/itil from agents/hang-off-check.md.";
+const sourceId = /\b(?:ADR-\d{3,}|P-?\d{3}|RFC-\d{3,}|JTBD-\d{3,}|STORY(?:-MAP)?-\d{3,}|R-?\d{3})\b/g;
+
+function split(markdown) {
+  const end = markdown.indexOf("\n---\n", 4);
+  return markdown.startsWith("---\n") && end !== -1
+    ? { frontmatter: markdown.slice(4, end), body: markdown.slice(end + 5) }
+    : { frontmatter: "", body: markdown };
+}
+
+function description(frontmatter) {
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith("description:"));
+  if (start === -1) return "Decide whether a problem belongs under an existing ticket.";
+  const value = [lines[start].slice("description:".length).trim()];
+  for (let index = start + 1; index < lines.length && /^\s+/.test(lines[index]); index += 1) value.push(lines[index].trim());
+  return value.filter(Boolean).join(" ").replace(sourceId, "a source governance record");
+}
+
+function instructions(body) {
+  return body
+    .replaceAll("AskUserQuestion", "request_user_input")
+    .replaceAll("Agent tool", "native Codex subagent tool")
+    .replaceAll("packages/itil/", "the installed ITIL plugin/")
+    .replace(sourceId, "the referenced source governance record");
+}
+
+function payload() {
+  const { frontmatter, body } = split(readFileSync(source, "utf8"));
+  return [
+    "# Do not edit by hand; update agents/hang-off-check.md and reinstall.",
+    'name = "wr-itil:hang-off-check"',
+    `description = ${JSON.stringify(description(frontmatter))}`,
+    'sandbox_mode = "read-only"',
+    'developer_instructions = """',
+    instructions(body).replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"').trimEnd(),
+    '"""',
+    "",
+  ].join("\n");
+}
+
+export function renderAgent() {
+  const content = payload();
+  const hash = createHash("sha256").update(content).digest("hex");
+  return `${owner}\n# Generated content SHA-256: ${hash}\n${content}`;
+}
+
+function owned(content) {
+  if (!content.startsWith(`${owner}\n`)) return false;
+  const lines = content.split("\n");
+  const match = lines[1]?.match(/^# Generated content SHA-256: ([0-9a-f]{64})$/);
+  return Boolean(match && createHash("sha256").update(lines.slice(2).join("\n")).digest("hex") === match[1]);
+}
+
+export function agentDir(scope, cwd = process.cwd(), env = process.env) {
+  return scope === "user" ? join(env.CODEX_HOME || join(homedir(), ".codex"), "agents") : join(cwd, ".codex", "agents");
+}
+
+export function installAgent(targetDir, { quiet = false } = {}) {
+  mkdirSync(targetDir, { recursive: true });
+  const target = join(targetDir, filename);
+  const expected = renderAgent();
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf8");
+    if (current === expected) return false;
+    if (!owned(current)) {
+      if (!quiet) console.log(`Preserved user-managed Codex agent at ${target}.`);
+      return false;
+    }
+  }
+  writeFileSync(target, expected, "utf8");
+  if (!quiet) console.log(`Codex ITIL agent installed at ${target}.`);
+  return true;
+}
+
+export function uninstallAgent(targetDir) {
+  const target = join(targetDir, filename);
+  if (existsSync(target) && owned(readFileSync(target, "utf8"))) rmSync(target);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes("--session-start") && !process.env.CODEX_THREAD_ID) process.exit(0);
+  const scopeIndex = process.argv.indexOf("--scope");
+  const scope = scopeIndex === -1 ? (process.argv.includes("--session-start") ? "user" : "project") : process.argv[scopeIndex + 1];
+  const target = agentDir(scope);
+  if (process.argv.includes("--uninstall")) uninstallAgent(target);
+  else {
+    const changed = installAgent(target, { quiet: process.argv.includes("--session-start") });
+    if (changed && process.argv.includes("--session-start")) {
+      console.log(JSON.stringify({ systemMessage: "wr-itil: Codex hang-off-check agent installed; restart Codex to activate it." }));
+    }
+  }
+}

package/scripts/derive-release-vehicle.sh

@@ -2,7 +2,7 @@
 # packages/itil/scripts/derive-release-vehicle.sh
 #
 # Derive the release-vehicle citation for a problem ticket by walking git
-# history. Input: ticket ID (e.g. `P267` or `267`). The script reads the
+# history. Input: ticket ID (e.g. `codify-derive-release-vehicle-sh-helper-for-k-v-release-cycle-citation-problem` or `267`). The script reads the
 # ticket body for a `.changeset/<name>.md` filename reference, finds the
 # `chore: version packages` deletion commit via `git log --diff-filter=D`,
 # resolves the merge PR via the ancestry-path merge commit (or `gh pr list`
@@ -14,7 +14,7 @@
 # <ticket-id>:     `P<NNN>` or bare `<NNN>`. Case-insensitive.
 # <problems-dir>:  defaults to ./docs/problems. Dual-tolerant lookup spans
 #                  flat layout (`<problems-dir>/<NNN>-*.md`) AND per-state
-#                  subdir layout (`<problems-dir>/*/<NNN>-*.md`) per ADR-031.
+#                  subdir layout (`<problems-dir>/*/<NNN>-*.md`) per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule.
 #
 # Output (stdout, multi-line key:value block):
 #   RELEASE_VEHICLE:
@@ -28,40 +28,40 @@
 #   0 = OK (full citation emitted)
 #   1 = ticket file not found
 #   2 = no changeset reference in ticket body AND no co-committed changeset
-#       derivable from the ticket's git history (P389 fallback)
+#       derivable from the ticket's git history (work-iters-omit-the-release-vehicle-seed-on-open-known-error-so-the-post-release-k-v-auto-enumerator-silently-skips-them-problem fallback)
 #   3 = changeset present in working tree (unreleased)
 #   4 = deletion commit found but no merge PR / merge commit resolvable
 #
-# @problem P267 — Codify derive-release-vehicle.sh helper for K→V release-
+# @problem codify-derive-release-vehicle-sh-helper-for-k-v-release-cycle-citation-problem — Codify derive-release-vehicle.sh helper for K→V release-
 #                 cycle citation. K→V transitions composed by hand are
 #                 fragile to wrong-release-cited errors when sessions
 #                 pre-apply transitions across sibling tickets (observed
-#                 2026-05-18 P250 K→V cited P247's release refs).
-# @adr ADR-049 (bin/ on PATH shim — adopter-safe script resolution; helper
+#                 2026-05-18 work-problems-step-6-5-3-within-appetite-no-drain-clause-defers-low-risk-releases-encoding-accumulation-problem K→V cited run-retro-step-3-tier-3-branch-b-leave-as-is-encodes-fictional-defer-sibling-to-evidence-based-criterion-problem's release refs).
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (bin/ on PATH shim — adopter-safe script resolution; helper
 #               is invoked as `wr-itil-derive-release-vehicle`)
-# @adr ADR-022 (Verifying lifecycle — citation supports the K→V transition's
+# @adr problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule (Verifying lifecycle — citation supports the K→V transition's
 #               `## Fix Released` section)
-# @adr ADR-014 (single-commit grain — helper is read-only, no commit impact)
-# @adr ADR-038 (progressive disclosure — short structured stdout block)
-# @adr ADR-005 (Plugin testing strategy — behavioural bats per P081)
-# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — deterministic
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (single-commit grain — helper is read-only, no commit impact)
+# @adr progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule (progressive disclosure — short structured stdout block)
+# @adr plugin-testing-strategy-architecture-rule (Plugin testing strategy — behavioural bats per problem-081-structural-source-content-tests-are-wasteful-tdd-agent-should-reject-them-and-require-behavioural-tests-framework-stub-enhancements-problem)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (Enforce Governance Without Slowing Down — deterministic
 #                 citation prevents cross-cite errors)
-# @jtbd JTBD-006 (Progress the Backlog While I'm Away — orchestrator per-iter
+# @jtbd progress-the-backlog-while-i-m-away-user-outcome (Progress the Backlog While I'm Away — orchestrator per-iter
 #                 K→V audit trail is trustworthy)
-# @jtbd JTBD-101 (Extend the Plugin Suite — sibling shim naming grammar)
+# @jtbd extend-the-suite-with-new-plugins-user-outcome (Extend the Plugin Suite — sibling shim naming grammar)
 
 set -uo pipefail
 
 usage() {
   cat >&2 <<'EOF'
 USAGE: derive-release-vehicle.sh <ticket-id> [<problems-dir>]
-  <ticket-id>    — P<NNN> or bare <NNN> (e.g. P267 or 267)
+  <ticket-id>    — P<NNN> or bare <NNN> (e.g. codify-derive-release-vehicle-sh-helper-for-k-v-release-cycle-citation-problem or 267)
   <problems-dir> — defaults to ./docs/problems
 
 Exit codes:
   0  ok (full citation)
   1  ticket file not found
-  2  no changeset reference in body AND no co-committed changeset in ticket history (P389)
+  2  no changeset reference in body AND no co-committed changeset in ticket history (work-iters-omit-the-release-vehicle-seed-on-open-known-error-so-the-post-release-k-v-auto-enumerator-silently-skips-them-problem)
   3  changeset present in working tree (unreleased)
   4  deletion commit found but no merge PR / merge commit resolvable
 EOF
@@ -83,7 +83,7 @@ if [ -z "$NNN" ]; then
 fi
 NNN="$(printf '%03d' "$((10#$NNN))")"
 
-# ── Locate ticket file (dual-tolerant per ADR-031) ──────────────────────────
+# ── Locate ticket file (dual-tolerant per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule) ──────────────────────────
 TICKET_FILE=""
 for candidate in \
   "$PROBLEMS_DIR/$NNN-"*.md \
@@ -106,17 +106,17 @@ CHANGESET_PATH="$(
     | head -1
 )"
 
-# ── Fallback (P389): body has no changeset reference — recover via co-commit ─
+# ── Fallback (work-iters-omit-the-release-vehicle-seed-on-open-known-error-so-the-post-release-k-v-auto-enumerator-silently-skips-them-problem): body has no changeset reference — recover via co-commit ─
 # An iter that fixes a Known Error sometimes ships the fix + changeset but omits
-# the P330 `**Release vehicle**` seed, leaving the ticket body with no
+# the derive-release-vehicle-helper-requires-pre-edit-of-ticket-changeset-reference-three-touch-when-one-touch-would-suffice-problem `**Release vehicle**` seed, leaving the ticket body with no
 # `.changeset/` reference. derive would exit 2 and the post-release K→V
-# enumerator (P228) silently skips the ticket even though its fix shipped. Under
-# ADR-014's one-commit grain the fix commit that authored the changeset also
+# enumerator (known-error-md-verifying-md-transition-not-happening-consistently-at-release-time-problem) silently skips the ticket even though its fix shipped. Under
+# governance-skills-commit-their-own-completed-work-architecture-rule's one-commit grain the fix commit that authored the changeset also
 # edited this ticket, so a `.changeset/*.md` ADDED by a commit that also touched
 # the ticket file is this ticket's release vehicle. Walk the ticket's commits
 # (newest first, across state renames) and take the first co-committed changeset.
-# ponytail: co-commit join. False negative — the P141 multi-slice case (changeset
-# on an earlier commit that did NOT touch the ticket) still needs the manual P330
+# ponytail: co-commit join. False negative — the afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem multi-slice case (changeset
+# on an earlier commit that did NOT touch the ticket) still needs the manual derive-release-vehicle-helper-requires-pre-edit-of-ticket-changeset-reference-three-touch-when-one-touch-would-suffice-problem
 # seed. False positive — a later commit touching the ticket AND adding an
 # unrelated changeset would be picked first; acceptable for a mechanical fallback.
 if [ -z "$CHANGESET_PATH" ]; then
@@ -133,7 +133,7 @@ if [ -z "$CHANGESET_PATH" ]; then
 fi
 
 if [ -z "$CHANGESET_PATH" ]; then
-  echo "ERROR: no .changeset/<name>.md reference in $TICKET_FILE (and no co-committed changeset in ticket history — P389)" >&2
+  echo "ERROR: no .changeset/<name>.md reference in $TICKET_FILE (and no co-committed changeset in ticket history — work-iters-omit-the-release-vehicle-seed-on-open-known-error-so-the-post-release-k-v-auto-enumerator-silently-skips-them-problem)" >&2
   exit 2
 fi
 

package/scripts/detect-unoversighted-rfcs.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# wr-itil — detect RFCs lacking the human-oversight marker (P378/RFC-030).
+# wr-itil — detect RFCs lacking the human-oversight marker (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem/rfc-lifecycle-self-maintenance-release-design).
 #
-# Clone of the architect/jtbd detect-unoversighted shape (ADR-066/068): greps
+# Clone of the architect/jtbd detect-unoversighted shape (human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule/068): greps
 # each RFC's YAML frontmatter for `human-oversight: confirmed`. No body reads,
 # no per-RFC LLM call. An RFC is "unoversighted" when its frontmatter does not
 # carry that marker line (RFCs are born `human-oversight: unconfirmed` at
@@ -14,7 +14,7 @@
 # confirmed. Always exits 0 (detector, not a gate).
 #
 # Consumed by: itil-rfc-oversight-nudge.sh (SessionStart count). Marker
-# contract: ADR-066 (human-oversight marker), as extended to RFCs by ADR-070/071.
+# contract: human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule (human-oversight marker), as extended to RFCs by rfcs-hold-no-independent-decisions-architecture-rule/071.
 
 set -euo pipefail
 

package/scripts/detect-unratified-stories-maps.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# detect-unratified-stories-maps.sh — ADR-090 detector.
+# detect-unratified-stories-maps.sh — story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule detector.
 #
 # Token-cheap detection of story maps that are NOT ratified, plus the stories
 # those maps leave unapproved. Mirrors wr-architect detect-unoversighted.sh.
@@ -11,7 +11,7 @@
 #   - drift-reopened   (marker says confirmed, but substance changed → mismatch)
 #   - legacy confirmed  (confirmed but no fingerprint yet — needs one re-ratify)
 #
-# A STORY carries no marker at all (ADR-103). It is listed when any map in its
+# A STORY carries no marker at all (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule). It is listed when any map in its
 # `story-maps:` field is unratified, or when it names no map — and the remedy is
 # always to ratify the map, never the story.
 #
@@ -21,7 +21,7 @@
 # oversight-unconfirmed drain.
 set -euo pipefail
 
-# Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (P317).
+# Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (capture-problem-capture-rfc-manage-problem-step-2-create-gate-marker-step-sources-repo-relative-packages-itil-hooks-lib-sh-fails-in-adopter-installs-recurring-published-path-class-problem).
 LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
   echo "detect-unratified-stories-maps: cannot locate lib dir" >&2; exit 0; }
 # shellcheck source=/dev/null
@@ -36,9 +36,9 @@ shopt -s nullglob
   if [ -d "$STORIES_DIR" ]; then
     for f in "$STORIES_DIR"/*.md "$STORIES_DIR"/*/*.md; do
       [ "$(basename "$f")" = "README.md" ] && continue
-      # ADR-103: a story's approval may be its MAP's. Using the map predicate
+      # a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: a story's approval may be its MAP's. Using the map predicate
       # here would report every story as unratified — stories carry no marker at
-      # all — and send the drain to ratify a surface ADR-103 removed.
+      # all — and send the drain to ratify a surface a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule removed.
       story_is_approved "$f" "$MAPS_DIR" || echo "$f"
     done
   fi