@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/hooks/lib/readme-refresh-detect.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# P165: shared README-refresh-discipline detection helper.
+# 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: shared README-refresh-discipline detection helper.
 #
 # `detect_readme_refresh_required` returns 0 (no change required —
 # allow) / 1 (ticket change staged but README refresh not staged —
@@ -7,14 +7,14 @@
 # on stdout so callers can name it in deny messages without re-parsing
 # diff output.
 #
-# Trap shape (P165):
-#   `manage-problem` SKILL.md Step 5 (P094) and Step 7 (P062) say every
+# Trap shape (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):
+#   `manage-problem` SKILL.md Step 5 (problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem) and Step 7 (problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem) say every
 #   ticket creation, ranking-bearing update, and status transition MUST
 #   stage the refreshed `docs/problems/README.md` in the same commit as
-#   the ticket change (ADR-014 single-commit grain). The contract is
+#   the ticket change (governance-skills-commit-their-own-completed-work-architecture-rule single-commit grain). The contract is
 #   declarative; iter subprocess commits have shipped `.verifying.md`
 #   renames or Status edits without the README refresh (observed iter
-#   3 commit d28bd51 — P156 row missing from VQ until iter 4 backfill).
+#   3 commit d28bd51 — ship-wr-architect-capture-adr-skill-lightweight-aside-invocation-surface-for-adr-capture-during-foreground-work-problem row missing from VQ until iter 4 backfill).
 #   Hook-level detection at `git commit` time replaces the declarative-
 #   only enforcement.
 #
@@ -22,14 +22,14 @@
 #   - `git diff --staged --name-only` enumerates staged paths.
 #   - Categorise each path:
 #       * `docs/problems/(open|verifying|closed|known-error|parked)/NNN-*.md`
-#         (new state-directory layout per ADR-031) — counts as a
+#         (new state-directory layout per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule) — counts as a
 #         ticket-state-transition surface; records the path.
 #       * `docs/problems/NNN-*.(open|verifying|closed|known-error|parked).md`
 #         (legacy flat layout) — also counts; supports adopter repos
 #         and any residual flat-layout tickets.
 #       * `docs/problems/README.md` — counts as a README refresh.
 #       * `docs/problems/README-history.md` — ignored (rotated history
-#         per P134; not a ticket file, not the load-bearing README).
+#         per docs-problems-readme-md-line-3-narrative-blob-accumulator-bloat-sibling-to-briefing-tier-3-on-a-different-surface-problem; not a ticket file, not the load-bearing README).
 #       * Anything else — ignored (non-ticket surface; the gate has no
 #         opinion on retros, ADRs, source, etc.).
 #   - If any ticket path is recorded AND README is NOT staged, return
@@ -41,22 +41,22 @@
 #     history). Audit-traceable via shell history. Set in
 #     `.claude/settings.json` env field or shell `export` before
 #     launching `claude` — inline-prefix syntax (`VAR=1 git commit ...`)
-#     does NOT propagate from a Bash subshell to PreToolUse hooks (P173).
-#   - Registered `RISK_BYPASS: <token>` commit-message trailer (P265) →
+#     does NOT propagate from a Bash subshell to PreToolUse hooks (bypass-gate-env-vars-do-not-propagate-from-bash-subshell-to-pretooluse-hook-context-problem).
+#   - Registered `RISK_BYPASS: <token>` commit-message trailer (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem) →
 #     return 0 (allow). Narrow allow-list: `adr-031-migration` (the
-#     standalone ADR-031 layout-migration commit — a rename-only change
+#     standalone problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule layout-migration commit — a rename-only change
 #     that legitimately stages no README refresh; also clears
 #     risk-score-commit-gate.sh) and `capture-deferred-readme` (the
 #     /wr-itil:capture-problem Step 6 commit, whose README refresh is
-#     deferred to /wr-itil:review-problems per ADR-032 — P262; this
+#     deferred to /wr-itil:review-problems per governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule — readme-refresh-hook-conflicts-with-capture-problem-skill-s-deferred-readme-refresh-contract-hook-wins-skill-needs-update-or-hook-needs-carve-out-problem; this
 #     token clears THIS gate only, not the risk-score gate). The trailer
 #     is read from the live `git commit` command string at PreToolUse
 #     time (the commit message is not yet written), matching the sibling
-#     `risk-score-commit-gate.sh` recognition (P170 T11) for the shared
-#     `adr-031-migration` token. Registry of record: ADR-014
+#     `risk-score-commit-gate.sh` recognition (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 T11) for the shared
+#     `adr-031-migration` token. Registry of record: governance-skills-commit-their-own-completed-work-architecture-rule
 #     commit-message bypass-token table.
 #
-# Narrative-only short-circuit (P230):
+# Narrative-only short-circuit (readme-refresh-discipline-hook-misfires-on-narrative-only-ticket-edits-when-no-ranking-bearing-field-changed-and-reconcile-readme-sh-exit-0-problem):
 #   - When all staged ticket edits are purely narrative — no
 #     ranking-bearing field change (Priority / Effort / Status / WSJF /
 #     Type field-lines), no title change, no rename between state
@@ -65,7 +65,7 @@
 #     the current README, return 0 (allow). Reconcile-readme is the
 #     authoritative drift oracle for narrative-only edits.
 #   - Ranking-bearing edits still fall through to existing detection
-#     regardless of reconcile state, preserving ADR-014 single-commit
+#     regardless of reconcile state, preserving governance-skills-commit-their-own-completed-work-architecture-rule single-commit
 #     grain for the change-set surface (architect verdict: reconcile is
 #     a robustness layer on top of per-operation refresh, not a
 #     supersession of either).
@@ -80,44 +80,44 @@
 # Cost: one `git diff` invocation per check (~10ms on this repo's
 # working tree). Per-invocation deterministic — runs on every
 # `git commit` invocation rather than relying on per-tool-call session
-# state tracking. Mirrors P125 `staging-detect.sh` + P141
+# state tracking. Mirrors staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem `staging-detect.sh` + afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem
 # `changeset-detect.sh` precedent (architect-approved no-marker design
-# per ADR-009 carve-out).
+# per gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule carve-out).
 #
 # References:
-#   ADR-005  — plugin testing strategy (hook bats live under
-#              `hooks/test/` per P081 behavioural-test discipline).
-#   ADR-009  — gate marker lifecycle (this helper deliberately does
+#   plugin-testing-strategy-architecture-rule  — plugin testing strategy (hook bats live under
+#              `hooks/test/` per problem-081-structural-source-content-tests-are-wasteful-tdd-agent-should-reject-them-and-require-behavioural-tests-framework-stub-enhancements-problem behavioural-test discipline).
+#   gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule  — gate marker lifecycle (this helper deliberately does
 #              NOT use markers; detection is per-invocation
 #              deterministic, not per-session trust window — same
-#              precedent as P125 / P141).
-#   ADR-013 Rule 1 — deny redirects with mechanical recovery (the deny
+#              precedent as staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem / afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem).
+#   structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 1 — deny redirects with mechanical recovery (the deny
 #              text names the offending ticket path + the literal
 #              `git add docs/problems/README.md` recovery command +
 #              the BYPASS env var override).
-#   ADR-014  — single-commit grain (this hook enforces it for the
+#   governance-skills-commit-their-own-completed-work-architecture-rule  — single-commit grain (this hook enforces it for the
 #              ticket-state-transition surface).
-#   ADR-022  — `.verifying.md` lifecycle status (one of the surface
+#   problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule  — `.verifying.md` lifecycle status (one of the surface
 #              shapes the hook detects).
-#   ADR-031  — per-state-subdir problem ticket layout (the new layout
+#   problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule  — per-state-subdir problem ticket layout (the new layout
 #              the hook detects).
-#   ADR-038  — progressive disclosure / deny-message terseness.
-#   ADR-045  — hook injection budget (Pattern 1 silent-on-pass; deny
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule  — progressive disclosure / deny-message terseness.
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule  — hook injection budget (Pattern 1 silent-on-pass; deny
 #              band ≤300 bytes for this hook).
-#   P062     — parent (README refresh on transition contract — manage-
+#   problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem     — parent (README refresh on transition contract — manage-
 #              problem Step 7).
-#   P094     — parent (README refresh on creation contract — manage-
+#   problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem     — parent (README refresh on creation contract — manage-
 #              problem Step 5).
-#   P118     — sibling reconcile-readme recovery path (the after-the-
+#   docs-problems-readme-md-drifts-from-filesystem-truth-across-sessions-despite-refresh-on-create-and-refresh-on-transition-both-closed-problem     — sibling reconcile-readme recovery path (the after-the-
 #              fact rescue this hook obviates).
-#   P125     — sibling staging-trap helper (same enforcement-layer
+#   staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem     — sibling staging-trap helper (same enforcement-layer
 #              shape — per-invocation deterministic, no markers).
-#   P141     — sibling changeset-discipline helper (same shape).
-#   P165     — this helper.
-#   P265     — RISK_BYPASS trailer allow-list bypass (this addition).
+#   afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem     — sibling changeset-discipline helper (same shape).
+#   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     — this helper.
+#   hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem     — RISK_BYPASS trailer allow-list bypass (this addition).
 
 # Allow-list of registered RISK_BYPASS commit-message trailer tokens
-# (P265). A policy-authorised commit may carry `RISK_BYPASS: <token>` in
+# (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem). A policy-authorised commit may carry `RISK_BYPASS: <token>` in
 # its message body; when <token> is registered here, the README-refresh
 # gate allows the commit even though no README refresh is staged. The
 # allow-list keeps the bypass narrow and auditable — a generic
@@ -128,30 +128,30 @@
 #     commit written by lib/migrate-problems-layout.sh. It is a pure
 #     rename (no README content change — the table references tickets by
 #     ID, not path), so requiring a README refresh would deadlock the
-#     migration (P265). The same token clears the sibling
-#     risk-score-commit-gate.sh (P170 T11); both gates recognise it via
+#     migration (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem). The same token clears the sibling
+#     risk-score-commit-gate.sh (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 T11); both gates recognise it via
 #     the identical grep below so one logical migration commit clears
-#     both. Registry of record: ADR-014 commit-message bypass-token table.
+#     both. Registry of record: governance-skills-commit-their-own-completed-work-architecture-rule commit-message bypass-token table.
 #   capture-deferred-readme — the lightweight /wr-itil:capture-problem
 #     Step 6 commit (subject `docs(problems): capture P<NNN> ...`). Per
-#     ADR-032 the capture variant DEFERS the README refresh to the next
+#     governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule the capture variant DEFERS the README refresh to the next
 #     /wr-itil:review-problems (capture-time speed is the load-bearing
 #     distinction from manage-problem's full-intake path), so the capture
 #     commit legitimately stages only the new ticket file. Without this
-#     token the P165 gate's new-ticket-is-ranking-bearing rule denied
-#     every capture commit (P262 — observed 4×/session). UNLIKE
-#     adr-031-migration this token clears the P165 README-refresh gate
+#     token 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 gate's new-ticket-is-ranking-bearing rule denied
+#     every capture commit (readme-refresh-hook-conflicts-with-capture-problem-skill-s-deferred-readme-refresh-contract-hook-wins-skill-needs-update-or-hook-needs-carve-out-problem — observed 4×/session). UNLIKE
+#     adr-031-migration this token clears 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 gate
 #     ONLY — it is intentionally NOT registered in
 #     risk-score-commit-gate.sh (a capture commit is real work and must
 #     be risk-scored normally; risk-score-commit-gate.sh hard-greps only
-#     `adr-031-migration`). Registry of record: ADR-014 commit-message
+#     `adr-031-migration`). Registry of record: governance-skills-commit-their-own-completed-work-architecture-rule commit-message
 #     bypass-token table (which documents the README-gate-only asymmetry).
 _README_REFRESH_BYPASS_TRAILERS=("adr-031-migration" "capture-deferred-readme")
 
 # Returns 0 if the given `git commit` command string carries a
 # registered RISK_BYPASS trailer from the allow-list above. The grep
 # pattern is kept byte-identical to risk-score-commit-gate.sh so both
-# commit gates recognise the token the same way (P265 architect verdict).
+# commit gates recognise the token the same way (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem architect verdict).
 _readme_refresh_command_has_bypass_trailer() {
   local command="${1:-}"
   [ -n "$command" ] || return 1
@@ -169,8 +169,8 @@ _readme_refresh_command_has_bypass_trailer() {
 # is not staged.
 #
 # $1 (optional) — the `git commit` command string. Inspected for a
-#   registered RISK_BYPASS trailer (P265). Empty/absent → no trailer
-#   bypass (fail-safe; preserves pre-P265 behaviour for any caller that
+#   registered RISK_BYPASS trailer (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem). Empty/absent → no trailer
+#   bypass (fail-safe; preserves pre-hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem behaviour for any caller that
 #   does not thread the command through).
 #
 # Echoes the offending ticket path on stdout when detected.
@@ -187,11 +187,11 @@ detect_readme_refresh_required() {
     return 0
   fi
 
-  # Bypass via registered RISK_BYPASS commit-message trailer (P265).
-  # The ADR-031 layout-migration commit is a rename-only change that
+  # Bypass via registered RISK_BYPASS commit-message trailer (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem).
+  # The problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule layout-migration commit is a rename-only change that
   # legitimately stages no README refresh; its `RISK_BYPASS:
   # adr-031-migration` trailer carries the policy authorisation
-  # (ADR-031 § Backward Compatibility + ADR-013 Rule 6).
+  # (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule § Backward Compatibility + structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6).
   if _readme_refresh_command_has_bypass_trailer "$command"; then
     return 0
   fi
@@ -226,7 +226,7 @@ detect_readme_refresh_required() {
       | docs/problems/closed/*.md \
       | docs/problems/known-error/*.md \
       | docs/problems/parked/*.md)
-        # New state-directory layout (ADR-031). Filename must start
+        # New state-directory layout (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule). Filename must start
         # with digits to be a ticket file — exclude any future
         # state-directory-local README or similar.
         basename="${path##*/}"
@@ -258,7 +258,7 @@ EOF
   # README staged alongside — clean.
   [ "$has_readme" -eq 1 ] && return 0
 
-  # P230 narrative-only short-circuit. Detect whether the staged ticket
+  # readme-refresh-discipline-hook-misfires-on-narrative-only-ticket-edits-when-no-ranking-bearing-field-changed-and-reconcile-readme-sh-exit-0-problem narrative-only short-circuit. Detect whether the staged ticket
   # set is purely narrative (no ranking-bearing field change, no rename
   # between state subdirs, no creation/deletion). If so, consult
   # reconcile-readme.sh as the authoritative drift oracle; exit=0 means

package/hooks/lib/runtime-sid.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# P142 (P124 Phase 4): runtime-SID marker path helper.
+# phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem (wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem Phase 4): runtime-SID marker path helper.
 #
 # Computes the per-machine, per-user, per-project marker path that the
 # `itil-runtime-sid-marker.sh` PreToolUse hook writes the runtime
@@ -10,14 +10,14 @@
 #
 # Why this exists:
 #   The Phase 3 helper relied on within-system mtime selection across
-#   ADR-038 announce markers. In orchestrator main turns AFTER subprocess
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule announce markers. In orchestrator main turns AFTER subprocess
 #   dispatch, subprocess announce markers had NEWER mtimes than the
 #   orchestrator's, so newest-mtime-wins picked the wrong UUID. No pure-
 #   helper algorithm can disambiguate orchestrator vs subprocess context
-#   from filesystem state alone (P142 ticket Investigation Tasks). The
+#   from filesystem state alone (phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem ticket Investigation Tasks). The
 #   structural fix is to capture the runtime stdin SID — known with
 #   certainty by the hook on every tool call — into a discoverable file
-#   the helper can read. See ADR-050.
+#   the helper can read. See capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule.
 #
 # Path scoping:
 #   When SESSION_MARKER_DIR is set (sandboxed bats per session-id.bats
@@ -30,22 +30,22 @@
 #   "/tmp/itil-runtime-sid-${USER}-${proj_hash}.current" where
 #   proj_hash = cksum of $PWD. Two Claude Code sessions in DIFFERENT
 #   projects do not race (different proj_hash). Two sessions in the
-#   SAME project on the same machine still race; per ADR-050 this is
+#   SAME project on the same machine still race; per capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule this is
 #   accepted as a documented limitation — the failure mode is a hook-
 #   denied Write that the agent can recover from, not silent corruption.
 #
 # References:
-#   ADR-050 — runtime-SID instrumentation via PreToolUse (this surface).
-#   ADR-048 — gate-misfire recovery procedure (superseded by ADR-050 +
-#             P142 + this lib).
-#   ADR-038 — announce-marker contract (cold-path fallback consumer).
-#   ADR-009 — gate marker lifecycle.
-#   P142    — this fix's ticket.
+#   capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule — runtime-SID instrumentation via PreToolUse (this surface).
+#   documented-recovery-from-gate-misfire-is-the-prescribed-surface-not-bypass-architecture-rule — gate-misfire recovery procedure (superseded by capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule +
+#             phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem + this lib).
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — announce-marker contract (cold-path fallback consumer).
+#   gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule — gate marker lifecycle.
+#   phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem    — this fix's ticket.
 
 # Echoes the runtime-SID marker path on stdout. Always exits 0.
 #
 # Usage (resolve relative to the caller's own location — NEVER repo-relative
-# `packages/...`, which only exists in the source monorepo; P317/RFC-009):
+# `packages/...`, which only exists in the source monorepo; 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/adopter-safe-path-resolution-in-shipped-skills-24-repo-relative-references-release-design):
 #   source "$(dirname "${BASH_SOURCE[0]}")/runtime-sid.sh"
 #   path=$(runtime_sid_path)
 runtime_sid_path() {

package/hooks/lib/session-id.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# P124: agent-side session-ID discovery helper.
+# wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem: agent-side session-ID discovery helper.
 #
 # `get_current_session_id` returns the canonical Claude Code session UUID
 # for the current invocation, used by /wr-itil:manage-problem Step 2
@@ -14,27 +14,27 @@
 #   /wr-itil:manage-problem Step 2's prior fallback `${CLAUDE_SESSION_ID:-default}`
 #   wrote the marker under "default" while the hook checked the real UUID.
 #   Marker mismatch -> Write deny -> agent had to scrape an existing
-#   announce marker filename ad-hoc to recover. P124.
+#   announce marker filename ad-hoc to recover. wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem.
 #
 # Discovery strategy (announce markers preferred over reviewed markers):
 #   /tmp/${SYSTEM}-announced-${SESSION_ID} markers are write-once-per-session
-#   per ADR-038 and are emitted on the FIRST UserPromptSubmit of every
+#   per progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule and are emitted on the FIRST UserPromptSubmit of every
 #   session by every active plugin (architect, jtbd, tdd, style-guide,
 #   voice-tone, itil-assistant-gate, itil-correction-detect). They have
 #   no mtime sliding (unlike `-reviewed-` gate markers, which `touch`-refresh
-#   on every gate check per ADR-009 sliding TTL + P111 subprocess refresh),
+#   on every gate check per gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule sliding TTL + agent-task-subprocess-tool-calls-do-not-refresh-parent-session-s-gate-markers-ttl-inflation-is-a-symptom-treatment-not-the-fix-problem subprocess refresh),
 #   so the announce-marker UUID is the most reliable per-session signal
 #   reachable from agent-side code without an env var.
 #
-# Why itil-local instead of packages/shared (cf. ADR-017):
-#   The discovery direction is the OPPOSITE of ADR-038's announce helper —
-#   ADR-038's session-marker.sh WRITES announce markers from hook side;
+# Why itil-local instead of packages/shared (cf. shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule):
+#   The discovery direction is the OPPOSITE of progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule's announce helper —
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule's session-marker.sh WRITES announce markers from hook side;
 #   this helper READS them from agent side. Only manage-problem SKILL.md
 #   needs agent-side discovery today (Step 2 substep 7), so the helper
 #   is itil-local with read-only fallbacks across other plugins' marker
 #   filenames (no write coupling, no sync obligation). If a second skill
 #   adopts agent-side SID discovery, promote to packages/shared/ at that
-#   point per ADR-017 shared-code-sync. Mirrors create-gate.sh's "Why a
+#   point per shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule shared-code-sync. Mirrors create-gate.sh's "Why a
 #   separate helper from lib/review-gate.sh" precedent.
 #
 # Empty SESSION_ID fallback:
@@ -43,12 +43,12 @@
 #   /tmp/manage-problem-grep- which the hook never matches. Fail-closed.
 #
 # References:
-#   ADR-038 — progressive disclosure / session-marker pattern (announce
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — progressive disclosure / session-marker pattern (announce
 #             markers, /tmp/${SYSTEM}-announced-${SESSION_ID} convention).
-#   ADR-009 — gate marker lifecycle (covers /tmp marker conventions).
-#   ADR-017 — shared-code-sync (consulted; itil-local is the right home today).
-#   P119    — create-gate hook this discovery helper feeds.
-#   P124    — this helper.
+#   gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule — gate marker lifecycle (covers /tmp marker conventions).
+#   shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule — shared-code-sync (consulted; itil-local is the right home today).
+#   agent-bypasses-wr-itil-manage-problem-step-2-duplicate-check-by-writing-tickets-directly-to-docs-problems-problem    — create-gate hook this discovery helper feeds.
+#   wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem    — this helper.
 #
 # Test override: SESSION_MARKER_DIR (defaults to /tmp) lets bats run
 # under a sandboxed marker directory without polluting real session
@@ -58,7 +58,7 @@
 # Echoes the UUID on stdout. Exit 0 if discovered, 1 if not.
 #
 # Usage (resolve relative to the caller's own location — NEVER repo-relative
-# `packages/...`, which only exists in the source monorepo; P317/RFC-009):
+# `packages/...`, which only exists in the source monorepo; 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/adopter-safe-path-resolution-in-shipped-skills-24-repo-relative-references-release-design):
 #   source "$(dirname "${BASH_SOURCE[0]}")/session-id.sh"   # or ../hooks/lib/ from a scripts/ wrapper
 #   sid=$(get_current_session_id) || { echo "no SID available" >&2; exit 1; }
 get_current_session_id() {
@@ -70,7 +70,7 @@ get_current_session_id() {
     return 0
   fi
 
-  # P142 / ADR-050: runtime-SID marker. The PreToolUse hook
+  # phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem / capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule: runtime-SID marker. The PreToolUse hook
   # (itil-runtime-sid-marker.sh) writes the runtime stdin session_id
   # to a per-machine marker on EVERY tool call. The helper, running
   # inside a Bash tool call, reads the marker that the same Bash
@@ -123,19 +123,19 @@ get_current_session_id() {
     #     Multi-session developer machines accumulate one
     #     `${system}-announced-${SID}` marker per past session in /tmp;
     #     the live session's marker is by construction the most-recently-
-    #     created one. P124 Phase 2 used first-glob-match (alphabetical),
+    #     created one. wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem Phase 2 used first-glob-match (alphabetical),
     #     which returned the lexically-first stale UUID when /tmp had
     #     accumulated markers from prior sessions — observed regression
     #     2026-04-28 with 103 stale architect markers selecting the
-    #     wrong UUID, denying the create-gate (P119).
+    #     wrong UUID, denying the create-gate (agent-bypasses-wr-itil-manage-problem-step-2-duplicate-check-by-writing-tickets-directly-to-docs-problems-problem).
     #
     # Why mtime is safe here even though Phase 1 architect rejected it:
     #   The Phase 1 rejection applied to `-reviewed-` markers, which
-    #   `touch`-refresh on every gate check (ADR-009 sliding TTL +
-    #   P111 subprocess refresh). Mtime on a `-reviewed-` marker is
+    #   `touch`-refresh on every gate check (gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule sliding TTL +
+    #   agent-task-subprocess-tool-calls-do-not-refresh-parent-session-s-gate-markers-ttl-inflation-is-a-symptom-treatment-not-the-fix-problem subprocess refresh). Mtime on a `-reviewed-` marker is
     #   "last seen", not "first written" — selecting newest-mtime can
     #   surface a stale session whose marker was just touch-refreshed.
-    #   `-announced-` markers are write-once-per-session per ADR-038
+    #   `-announced-` markers are write-once-per-session per progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule
     #   (no `touch`-refresh, no TTL); their mtime IS the announcing
     #   session's first-prompt timestamp. Newest mtime within a single
     #   `-announced-` glob unambiguously identifies the live session.
@@ -155,7 +155,7 @@ get_current_session_id() {
   return 1
 }
 
-# P260 / ADR-050 Option C: bounded multi-UUID candidate enumeration.
+# create-gate-marker-race-between-concurrent-claude-sessions-via-shared-runtime-sid-file-problem / capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule Option C: bounded multi-UUID candidate enumeration.
 #
 # Echoes EVERY candidate session UUID — one per line, deduplicated — that
 # the create-gate hook (manage-problem-enforce-create.sh) might read from
@@ -172,8 +172,8 @@ get_current_session_id() {
 #   proj_hash), last-writer-wins. When the orchestrator captures a ticket
 #   while the subprocess holds the runtime-sid, `get_current_session_id`
 #   returns the SUBPROCESS SID, but the orchestrator's Write carries the
-#   ORCHESTRATOR SID on its stdin — marker mismatch, create-gate deny (P260).
-#   ADR-050 §Context establishes that no agent-side algorithm can PREDICT
+#   ORCHESTRATOR SID on its stdin — marker mismatch, create-gate deny (create-gate-marker-race-between-concurrent-claude-sessions-via-shared-runtime-sid-file-problem).
+#   capture-the-runtime-stdin-session-id-via-a-pretooluse-hook-so-the-create-gate-marker-binds-to-the-same-sid-the-runtime-hook-will-see-architecture-rule §Context establishes that no agent-side algorithm can PREDICT
 #   the right single SID from filesystem state alone. Option C stops
 #   predicting and writes under every recent candidate instead.
 #
@@ -185,16 +185,16 @@ get_current_session_id() {
 #   2. Every announce-marker UUID across ALL systems whose marker mtime is
 #      within the window (the concurrently-active sessions: orchestrator +
 #      its running subprocess(es)). Announce markers are write-once-per-
-#      session (ADR-038, no touch-refresh), so mtime is the announcing
+#      session (progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule, no touch-refresh), so mtime is the announcing
 #      session's first-prompt timestamp — a stable bound.
 #
 # Bounding (NOT a global fail-open):
 #   The mtime window (SESSION_CANDIDATE_WINDOW_MINS, default 1440 = 24h)
-#   bounds the enumeration against the P124 stale-marker pathology (103
+#   bounds the enumeration against the wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem stale-marker pathology (103
 #   accumulated UUIDs selecting the wrong SID). 24h comfortably covers any
 #   realistic single AFK loop while excluding multi-day marker accumulation.
 #   Extra markers under recently-stale UUIDs are HARMLESS — empty files; the
-#   hook only matches the marker equal to the Write's stdin SID. The P119
+#   hook only matches the marker equal to the Write's stdin SID. The agent-bypasses-wr-itil-manage-problem-step-2-duplicate-check-by-writing-tickets-directly-to-docs-problems-problem
 #   audit invariant holds: every marker still records that THIS session ran
 #   the duplicate-check grep (the marker is only written because Step 2's
 #   grep provably ran this turn; widening WHICH SID files receive that proof
@@ -206,7 +206,7 @@ get_current_session_id() {
 #
 # Usage — SKILLs call the `wr-itil-mark-create-gate` command (it does the
 # source+pipe internally, adopter-safe); direct callers resolve the libs relative
-# to their OWN location, NEVER repo-relative `packages/...` (P317/RFC-009):
+# to their OWN location, NEVER repo-relative `packages/...` (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/adopter-safe-path-resolution-in-shipped-skills-24-repo-relative-references-release-design):
 #   LIB="$(dirname "${BASH_SOURCE[0]}")"; source "$LIB/session-id.sh"; source "$LIB/create-gate.sh"
 #   get_candidate_session_ids | mark_step2_complete_candidates
 get_candidate_session_ids() {
@@ -224,7 +224,7 @@ get_candidate_session_ids() {
     # `-mmin -N` are portable across BSD (macOS) and GNU find. `-L` follows the
     # start-point symlink — on macOS marker_dir defaults to /tmp, a symlink to
     # /private/tmp, which `find` would otherwise refuse to descend, silently
-    # enumerating zero candidates (no-op on Linux where /tmp is a real dir). P380.
+    # enumerating zero candidates (no-op on Linux where /tmp is a real dir). wr-architect-mark-oversight-confirmed-shim-s-find-tmp-doesn-t-follow-macos-tmp-private-tmp-symlink-problem.
     # The sed strips the leading path then the `<system>-announced-` prefix,
     # leaving the trailing UUID (UUIDs never contain the literal "-announced-").
     find -L "$marker_dir" -maxdepth 1 -name '*-announced-*' -mmin "-${window_mins}" 2>/dev/null \

package/hooks/lib/session-marker.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Shared session-announcement marker helpers (P095 / ADR-038).
+# Shared session-announcement marker helpers (problem-095-userpromptsubmit-hooks-across-five-windyroad-plugins-re-emit-full-mandatory-prose-on-every-prompt-problem / progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule).
 #
 # Used by UserPromptSubmit hooks to gate verbose MANDATORY instruction
 # prose behind a once-per-session check. First prompt of a session emits

package/hooks/lib/staging-detect.sh

@@ -1,19 +1,19 @@
 #!/bin/bash
-# P125: shared staging-trap detection helper.
+# staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem: shared staging-trap detection helper.
 #
 # `detect_p057_trap` returns 0 (no trap detected — allow) / 1 (trap
 # detected — caller should deny). On 1, the trap'd path is echoed on
 # stdout and a one-line recovery hint is emitted on stderr so callers
 # can surface both in deny messages without re-parsing diff output.
 #
-# Trap shape (P057):
+# Trap shape (problem-057-git-mv-edit-git-add-staging-ordering-trap-drops-content-edits-from-the-commit-problem):
 #   `git mv A B` stages the rename atomically. If the agent then
 #   modifies B via the Edit tool (or any other working-tree edit),
 #   git's index still carries only the rename — the post-rename
 #   content edit is a working-tree modification needing a separate
 #   `git add B`. Without that re-stage, only the rename lands at
 #   commit time and the edit leaks into the next commit (audit-trail
-#   corruption — the original P057 concern).
+#   corruption — the original problem-057-git-mv-edit-git-add-staging-ordering-trap-drops-content-edits-from-the-commit-problem concern).
 #
 # Detection logic:
 #   - `git diff --staged --name-status` enumerates staged changes;
@@ -24,7 +24,7 @@
 #
 # Cost: two `git diff` invocations per check (~10-50ms on this repo's
 # working tree; bounded by repo size, not commit batch size). Per
-# architect verdict on P125: cheaper than a session-marker variant
+# architect verdict on staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem: cheaper than a session-marker variant
 # and deterministic — runs on every `git commit` invocation rather
 # than relying on per-tool-call session state tracking.
 #
@@ -38,20 +38,20 @@
 #     in unrelated contexts).
 #
 # References:
-#   ADR-005 — plugin testing strategy (hook bats live under hooks/test/).
-#   ADR-009 — gate marker lifecycle (this helper deliberately does NOT
+#   plugin-testing-strategy-architecture-rule — plugin testing strategy (hook bats live under hooks/test/).
+#   gate-marker-lifecycle-ttl-drift-not-stop-hook-reset-architecture-rule — gate marker lifecycle (this helper deliberately does NOT
 #             use markers; detection is per-invocation deterministic,
 #             not per-session trust window).
-#   ADR-013 Rule 1 — deny redirects with mechanical recovery (the deny
+#   structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 1 — deny redirects with mechanical recovery (the deny
 #                    text names the file + the literal `git add <new>`
 #                    recovery; no skill round-trip required).
-#   ADR-038 — progressive disclosure / deny-message terseness.
-#   P057    — original staging-trap ticket (closed; documentation fix).
-#   P119    — sibling create-gate hook + lib/create-gate.sh helper
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — progressive disclosure / deny-message terseness.
+#   problem-057-git-mv-edit-git-add-staging-ordering-trap-drops-content-edits-from-the-commit-problem    — original staging-trap ticket (closed; documentation fix).
+#   agent-bypasses-wr-itil-manage-problem-step-2-duplicate-check-by-writing-tickets-directly-to-docs-problems-problem    — sibling create-gate hook + lib/create-gate.sh helper
 #             (precedent for the deny + helper-pair shape).
-#   P125    — this helper.
+#   staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem    — this helper.
 
-# Detect the P057 staging trap in the current git working tree.
+# Detect the problem-057-git-mv-edit-git-add-staging-ordering-trap-drops-content-edits-from-the-commit-problem staging trap in the current git working tree.
 #
 # Echoes the trap'd path on stdout when detected; emits a one-line
 # recovery hint on stderr.
@@ -94,7 +94,7 @@ detect_p057_trap() {
         # Match against working-tree mod list (full-line match).
         if printf '%s\n' "$wt_mods" | grep -Fxq "$new_path"; then
           printf '%s\n' "$new_path"
-          echo "P057 staging-trap: re-stage with: git add $new_path" >&2
+          echo "problem-057-git-mv-edit-git-add-staging-ordering-trap-drops-content-edits-from-the-commit-problem staging-trap: re-stage with: git add $new_path" >&2
           return 1
         fi
         ;;