@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/hooks/itil-no-implement-draft-gate.sh

@@ -1,41 +1,41 @@
 #!/bin/bash
-# wr-itil — PreToolUse:Bash gate (ADR-096 / P404). A story in `draft` is NEVER
+# wr-itil — PreToolUse:Bash gate (a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule / implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem). A story in `draft` is NEVER
 # implementable. Blocks a `git commit` whose `Refs: STORY-NNN` trailer names a
 # story still in docs/stories/draft/ — implementation requires `accepted` (where
-# the INVEST + RFC-trace gates + ADR-090 ratification fire). Capture commits are
+# the INVEST + RFC-trace gates + story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule ratification fire). Capture commits are
 # exempt (they CREATE the draft story). Bootstrap-exempt commits bypass
-# (ADR-060 A4). Degrades to a no-op on abnormal paths — characterised, not
+# (problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule A4). Degrades to a no-op on abnormal paths — characterised, not
 # authorised; see the header note below.
 #
 # This is the enforcement locus the architect named as the ONLY one that catches
-# the exact P404 bypass — a direct implementing commit against a draft story,
+# the exact implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem bypass — a direct implementing commit against a draft story,
 # whether from the orchestrator or by hand.
 #
-# It ALSO enforces the ADR-090 ratification ADR-096 names but never implemented
-# (P465): a commit against an `accepted`/`in-progress` story is blocked unless
+# It ALSO enforces the story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule ratification a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule names but never implemented
+# (the-story-accepted-gate-names-ratification-but-no-surface-enforces-it-problem): a commit against an `accepted`/`in-progress` story is blocked unless
 # that story is ratified. This half is UNCONDITIONAL — a pure tightening, no
-# config, no opt-in — because putting an ADR-090-mandated check behind a flag
-# would be the decision conflict. Under ADR-103 the approval surface is the story
+# config, no opt-in — because putting an story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule-mandated check behind a flag
+# would be the decision conflict. Under a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule the approval surface is the story
 # MAP: a story carries no oversight marker of its own, and is approved when every
 # map in its `story-maps:` field is ratified.
 #
 # Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1.
 #
-# @adr ADR-096 (no-implement-while-draft) ADR-060 (lifecycle)
-#      ADR-095 (sibling capture-time gates) ADR-052 (bats)
-#      ADR-090 (drift-invalidated ratification) ADR-103 (map is the approval surface)
-# @problem P404 P465 P456
+# @adr a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule (no-implement-while-draft) problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (lifecycle)
+#      story-map-membership-and-story-content-completeness-are-enforced-at-capture-architecture-rule (sibling capture-time gates) behavioural-tests-default-for-skill-testing-architecture-rule (bats)
+#      story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule (drift-invalidated ratification) a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule (map is the approval surface)
+# @problem implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem the-story-accepted-gate-names-ratification-but-no-surface-enforces-it-problem afk-iter-cannot-progress-a-ratified-known-error-when-the-fix-vehicle-rfc-has-empty-stories-problem
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
 source "$SCRIPT_DIR/lib/command-detect.sh" 2>/dev/null || exit 0
 # Degrades to a no-op on a missing lib. NOT authorised by any in-force decision:
-# ADR-013 (Structured user interaction for governance-skill decisions) Rule 6
+# structured-user-interaction-for-governance-skill-decisions-architecture-rule (Structured user interaction for governance-skill decisions) Rule 6
 # governs a skill that cannot reach AskUserQuestion, and its Continue clause
 # reads "Do NOT silently fail-soft-skip". This posture is CHARACTERISED, not
 # endorsed — see "the gate degrades to a no-op when its predicate lib is
 # missing" in hooks/test/. Both source guards are terminal and both precede
 # every check, so a missing lib — either one — degrades to no gate at all.
-# Open question queued at P369.
+# Open question queued at plugin-removes-hook-file-but-adopter-session-still-invokes-it-via-stale-binding-architect-compendium-refresh-discipline-sh-case-2026-06-17-problem.
 # shellcheck source=../lib/story-oversight.sh
 source "$SCRIPT_DIR/../lib/story-oversight.sh" 2>/dev/null || exit 0
 
@@ -82,10 +82,10 @@ while IFS= read -r id; do
   [ -n "$id" ] || continue
   shopt -s nullglob; draftfiles=(./docs/stories/draft/${id}-*.md); shopt -u nullglob
   if [ ${#draftfiles[@]} -gt 0 ]; then
-    deny "BLOCKED (ADR-096 / P404): this commit references ${id} via a Refs: trailer, but ${id} is still in draft. A draft story cannot be implemented — accept it first via /wr-itil:manage-story ${id} accepted (it runs the INVEST + RFC-trace gates + ratification), then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
+    deny "BLOCKED (a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule / implement-in-the-skills-and-tests-1-story-per-rfc-story-map-story-ratification-problem): this commit references ${id} via a Refs: trailer, but ${id} is still in draft. A draft story cannot be implemented — accept it first via /wr-itil:manage-story ${id} accepted (it runs the INVEST + RFC-trace gates + ratification), then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
   fi
 
-  # ADR-090 ratification at the implementation locus (P465). ADR-096's Decision
+  # story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule ratification at the implementation locus (the-story-accepted-gate-names-ratification-but-no-surface-enforces-it-problem). a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule's Decision
   # Outcome claims no unratified story can ever be implemented; nothing enforced
   # it until here. Scoped to accepted/in-progress — done/archived stories are
   # past implementation and are not gated.
@@ -95,10 +95,10 @@ while IFS= read -r id; do
   [ ${#livefiles[@]} -gt 0 ] || continue
   story="${livefiles[0]}"
 
-  # ADR-103: a story's approval is its story MAP's. The story itself carries no
+  # a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: a story's approval is its story MAP's. The story itself carries no
   # oversight marker, so there is one question to ask and one place to fix it.
   if ! story_is_approved "$story"; then
-    deny "BLOCKED (ADR-103 / ADR-096 / P465): this commit references ${id}, but ${id} is not approved. A story is approved by its story map: every map in its \`story-maps:\` field must be ratified, and ${id} either names no map or names one that is unratified or has drifted since it was ratified. Ratify the map via /wr-itil:manage-story-map <MAP-ID> ratify, then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
+    deny "BLOCKED (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule / a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule / the-story-accepted-gate-names-ratification-but-no-surface-enforces-it-problem): this commit references ${id}, but ${id} is not approved. A story is approved by its story map: every map in its \`story-maps:\` field must be ratified, and ${id} either names no map or names one that is unratified or has drifted since it was ratified. Ratify the map via /wr-itil:manage-story-map <MAP-ID> ratify, then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
   fi
 done <<< "$STORIES"
 

package/hooks/itil-pending-questions-surface.sh

@@ -1,25 +1,25 @@
 #!/bin/bash
-# wr-itil — SessionStart hook (P157, ADR-032 P157 amendment, ADR-040 precedent)
+# wr-itil — SessionStart hook (ship-pending-questions-surface-hook-auto-surface-accumulated-outstanding-questions-from-afk-run-state-outstanding-questions-jsonl-at-session-start-when-user-returns-interactive-problem, governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule ship-pending-questions-surface-hook-auto-surface-accumulated-outstanding-questions-from-afk-run-state-outstanding-questions-jsonl-at-session-start-when-user-returns-interactive-problem amendment, session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule precedent)
 #
 # Surfaces accumulated `outstanding_questions` entries from the AFK loop's
 # session-level queue file at .afk-run-state/outstanding-questions.jsonl
 # when the user starts a new interactive session. The queue is populated
 # between iters by /wr-itil:work-problems Step 5 / Step 2.5 / Step 2.5b
-# (P135 Phase 3 + ADR-044 6-class taxonomy schema).
+# (decision-delegation-contract-agents-over-apply-rule-1-s-interactive-default-to-framework-resolved-decisions-codify-the-framework-resolution-boundary-afk-loop-s-batched-questions-as-deliverable-lazy-askuserquestion-measurement-problem Phase 3 + decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule 6-class taxonomy schema).
 #
 # Without this hook, accumulated questions persist across session boundaries
 # unread when an AFK loop halts before its Step 2.5 / Step 2.5b emit fires
 # (manual stop, quota exhaustion, network failure). With this hook, the
 # accumulated queue surfaces deterministically on session start; the agent
-# fires AskUserQuestion in batches (<=4 per call per ADR-013 Rule 1) on the
+# fires AskUserQuestion in batches (<=4 per call per structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 1) on the
 # user's first interactive turn and rewrites the queue file to remove
 # resolved entries.
 #
 # Wired from packages/itil/hooks/hooks.json SessionStart array with
-# matcher "startup" (per ADR-040 Option A). Silent exit if queue is missing,
-# empty, or whitespace-only per ADR-040 Mechanism step 1.
+# matcher "startup" (per session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule Option A). Silent exit if queue is missing,
+# empty, or whitespace-only per session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule Mechanism step 1.
 #
-# AFK-iter cross-context-leak prevention (ADR-032 line 127): when invoked
+# AFK-iter cross-context-leak prevention (governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule line 127): when invoked
 # inside a /wr-itil:work-problems iter subprocess (which inherits the
 # orchestrator's queue file), the orchestrator's Step 5 dispatch block sets
 # WR_SUPPRESS_PENDING_QUESTIONS=1 before each `claude -p` spawn. The hook
@@ -38,11 +38,11 @@ fi
 
 QUEUE_FILE="${CLAUDE_PROJECT_DIR:-.}/.afk-run-state/outstanding-questions.jsonl"
 
-# Silent-on-no-content per ADR-040 Mechanism step 1.
+# Silent-on-no-content per session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule Mechanism step 1.
 [ -f "$QUEUE_FILE" ] || exit 0
 [ -s "$QUEUE_FILE" ] || exit 0
 
-# ADR-044 6-class taxonomy precedence — lower rank value = higher priority.
+# decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule 6-class taxonomy precedence — lower rank value = higher priority.
 # Strings match the JSONL schema in work-problems SKILL.md Step 5 verbatim.
 rank_for_category() {
   case "$1" in
@@ -85,7 +85,7 @@ ENTRIES_TSV=$(
 
 ENTRY_COUNT=$(printf '%s\n' "$ENTRIES_TSV" | wc -l | tr -d ' ')
 
-# Emit additionalContext on stdout (ADR-040 plain-stdout shape per
+# Emit additionalContext on stdout (session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule plain-stdout shape per
 # session-start-briefing.sh precedent).
 {
   echo "PENDING QUESTIONS FROM PRIOR AFK LOOP — accumulated outstanding_questions"
@@ -93,7 +93,7 @@ ENTRY_COUNT=$(printf '%s\n' "$ENTRIES_TSV" | wc -l | tr -d ' ')
   echo ""
   echo "These are direction / deviation-approval / one-time-override / silent-framework"
   echo "/ taste / correction-followup observations queued by /wr-itil:work-problems"
-  echo "iters per ADR-044 6-class taxonomy. Surface them via AskUserQuestion batched"
+  echo "iters per decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule 6-class taxonomy. Surface them via AskUserQuestion batched"
   echo "<=4 per call (sequential when >4) on the user's first interactive turn,"
   echo "ranked deviation-approval > direction > one-time-override > silent-framework"
   echo "> taste > correction-followup. After resolving each entry, remove the"
@@ -117,7 +117,7 @@ ENTRY_COUNT=$(printf '%s\n' "$ENTRIES_TSV" | wc -l | tr -d ' ')
   echo ""
   if [ "$ENTRY_COUNT" -gt 4 ]; then
     echo "Note: ${ENTRY_COUNT} entries exceeds the AskUserQuestion <=4 per-call"
-    echo "cap (ADR-013 Rule 1). Fire sequential calls — first 4 highest-ranked"
+    echo "cap (structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 1). Fire sequential calls — first 4 highest-ranked"
     echo "first, then the next batch, until the queue is drained."
   fi
 } 2>/dev/null

package/hooks/itil-readme-refresh-discipline.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
-# P165: PreToolUse:Bash hook — denies `git commit` invocations whose
+# 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: PreToolUse:Bash hook — denies `git commit` invocations whose
 # staged set includes a `docs/problems/<state>/NNN-*.md` ticket change
 # but does NOT also stage a `docs/problems/README.md` refresh. Hook-
-# level enforcement replaces the declarative-only P094 / P062 contract
+# level enforcement replaces the declarative-only 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 contract
 # in manage-problem SKILL.md Step 5 / Step 7 — iter subprocess commits
 # previously could ship a `.verifying.md` rename or Status edit without
 # the corresponding Verification Queue / WSJF Rankings row update in
@@ -12,14 +12,14 @@
 # Detection delegates to `lib/readme-refresh-detect.sh::detect_readme_refresh_required`.
 # When the helper returns 1, this hook emits PreToolUse deny JSON with
 # the offending ticket path inline and the literal `git add
-# docs/problems/README.md` recovery command, satisfying ADR-013
+# docs/problems/README.md` recovery command, satisfying structured-user-interaction-for-governance-skill-decisions-architecture-rule
 # Rule 1's "deny redirects to a recovery path" contract via the
 # mechanical-recovery shape (no skill wrapper required — staging the
 # README is a single command).
 #
-# Allow paths (exit 0 silently per ADR-045 Pattern 1):
+# Allow paths (exit 0 silently per hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule Pattern 1):
 #   - tool_name != "Bash"               (only Bash invocations are gated)
-#   - command does not invoke           (P268: leading-executable check
+#   - command does not invoke           (hook-substring-matches-git-commit-anywhere-in-bash-command-not-just-actual-git-commit-invocations-problem: leading-executable check
 #     `git commit` as its leading-       via `lib/command-detect.sh`
 #     effective command                  — replaces prior substring match
 #                                        that misfired on grep/sed/cat
@@ -32,23 +32,23 @@
 #   - parse failure on stdin            (mirrors create-gate.sh fail-open)
 #
 # References:
-#   ADR-005 — plugin testing strategy (hook bats live under hooks/test/).
-#   ADR-009 — gate marker lifecycle (this hook 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 hook deliberately does NOT
 #             use markers; detection is per-invocation deterministic
-#             — same precedent as P125 + P141).
-#   ADR-013 Rule 1 — deny redirects with mechanical recovery.
-#   ADR-014 — single-commit grain (the contract this hook enforces).
-#   ADR-022 — `.verifying.md` lifecycle status.
-#   ADR-038 — progressive disclosure / deny-message terseness budget.
-#   ADR-045 — hook injection budget (Pattern 1 silent-on-pass; deny
+#             — same 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.
+#   governance-skills-commit-their-own-completed-work-architecture-rule — single-commit grain (the contract this hook enforces).
+#   problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule — `.verifying.md` lifecycle status.
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — progressive disclosure / deny-message terseness budget.
+#   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).
-#   P094    — parent (README refresh on creation contract).
-#   P118    — sibling reconcile-readme recovery path.
-#   P125    — sibling staging-trap hook (same enforcement-layer shape).
-#   P141    — sibling changeset-discipline hook (same shape).
-#   P165    — this hook.
-#   P268    — leading-executable-token command-detect helper.
+#   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).
+#   problem-094-wr-itil-manage-problem-does-not-refresh-docs-problems-readme-md-on-ticket-creation-problem    — parent (README refresh on creation contract).
+#   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.
+#   staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem    — sibling staging-trap hook (same enforcement-layer shape).
+#   afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem    — sibling changeset-discipline hook (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 hook.
+#   hook-substring-matches-git-commit-anywhere-in-bash-command-not-just-actual-git-commit-invocations-problem    — leading-executable-token command-detect helper.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/readme-refresh-detect.sh
@@ -85,14 +85,14 @@ except:
 # `lib/command-detect.sh::command_invokes_git_commit`, which strips
 # common prefix shapes (leading whitespace, env-var assignments,
 # `cd <path> &&`) and checks whether the residual leading token pair
-# is literally `git commit`. P268: replaced the prior substring match
+# is literally `git commit`. hook-substring-matches-git-commit-anywhere-in-bash-command-not-just-actual-git-commit-invocations-problem: replaced the prior substring match
 # `*"git commit"*` that misfired on non-commit Bash whose argument
 # vectors merely mentioned the phrase (grep/sed/cat-heredoc/echo).
 command_invokes_git_commit "$COMMAND" || exit 0
 
 # Run detection. Helper echoes offending ticket path on stdout when
 # detected; returns 1 in that case. Returns 0 (allow) on no-trap,
-# bypass env, a registered RISK_BYPASS commit-message trailer (P265 —
+# bypass env, a registered RISK_BYPASS commit-message trailer (hook-does-not-recognise-risk-bypass-adr-031-migration-trailer-blocks-step-0a-auto-migrate-problem —
 # `$COMMAND` is threaded in so the helper can inspect the trailer), or
 # fail-open (non-git tree, parse error).
 TRAPPED_TICKET=$(detect_readme_refresh_required "$COMMAND" 2>/dev/null) && exit 0
@@ -100,7 +100,7 @@ TRAPPED_TICKET=$(detect_readme_refresh_required "$COMMAND" 2>/dev/null) && exit
 # Extract the leading ticket-ID digits from the basename so the deny
 # names the ticket as `P<NNN>` rather than the full descriptive path
 # (problem tickets carry long slugs; embedding the full path can
-# exceed ADR-045 deny-band 300 bytes). `git status` reveals the exact
+# exceed hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule deny-band 300 bytes). `git status` reveals the exact
 # staged path for recovery; the deny only needs to name the ticket
 # distinctly.
 BASENAME="${TRAPPED_TICKET##*/}"
@@ -111,14 +111,14 @@ case "$TICKET_NUM" in
 esac
 
 # Trap detected — emit deny with terse recovery.
-# Voice-tone budget per ADR-045 deny-band ≤300 bytes total. Names the
+# Voice-tone budget per hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule deny-band ≤300 bytes total. Names the
 # offending ticket ID, the literal recovery command, the BYPASS env
-# var escape with correct propagation syntax (P231 / P173), and the
-# P165 cite. Inline-prefix `VAR=1 git commit ...` does NOT propagate
+# var escape with correct propagation syntax (readme-refresh-discipline-hook-deny-message-advertises-bypass-readme-refresh-gate-1-inline-prefix-that-does-not-propagate-to-the-pretooluse-hook-recurrence-of-at-a-new-surface-problem / bypass-gate-env-vars-do-not-propagate-from-bash-subshell-to-pretooluse-hook-context-problem), and 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 cite. Inline-prefix `VAR=1 git commit ...` does NOT propagate
 # from a Bash subshell to PreToolUse hooks; the env field of
 # `.claude/settings.json` (or shell `export` before `claude` launch)
 # is the working path.
-REASON="BLOCKED: P165. ${TICKET_ID} needs README refresh: git add docs/problems/README.md. Bypass: BYPASS_README_REFRESH_GATE=1 via .claude/settings.json env (P173)."
+REASON="BLOCKED: 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. ${TICKET_ID} needs README refresh: git add docs/problems/README.md. Bypass: BYPASS_README_REFRESH_GATE=1 via .claude/settings.json env (bypass-gate-env-vars-do-not-propagate-from-bash-subshell-to-pretooluse-hook-context-problem)."
 
 cat <<EOF
 {

package/hooks/itil-rfc-oversight-nudge.sh

@@ -1,23 +1,23 @@
 #!/usr/bin/env bash
-# wr-itil — SessionStart hook (P378/RFC-030; ADR-066/068 oversight-nudge clone)
+# wr-itil — SessionStart hook (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem/rfc-lifecycle-self-maintenance-release-design; human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule/068 oversight-nudge clone)
 #
 # Surfaces a one-line nudge when RFCs lack the human-oversight marker, so the
 # user can ratify them via /wr-itil:manage-rfc <RFC-NNN> (the accepted
 # transition ratifies RFC scope). Sibling of architect-oversight-nudge.sh
-# (ADR-066) and jtbd-oversight-nudge.sh (ADR-068); same class-B SessionStart
-# shape as the ADR-040 session-start surface — so ratification is auto-surfaced
-# every session instead of leaning on the user's memory (P378).
+# (human-oversight-marker-wr-architect-review-decisions-drain-for-recorded-decisions-architecture-rule) and jtbd-oversight-nudge.sh (jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule); same class-B SessionStart
+# shape as the session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule session-start surface — so ratification is auto-surfaced
+# every session instead of leaning on the user's memory (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem).
 #
 # Detection is token-cheap: delegates to detect-unoversighted-rfcs.sh (a grep
 # over docs/rfcs/ frontmatter — no body reads, no per-RFC LLM call). Silent
 # when the unoversighted count is zero (steady state once ratified).
 #
 # AFK self-suppress: shares the suite-wide WR_SUPPRESS_OVERSIGHT_NUDGE guard
-# with the architect + jtbd oversight nudges (ADR-068 § shared cross-plugin
+# with the architect + jtbd oversight nudges (jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule § shared cross-plugin
 # contracts). AFK orchestrators export it once and every oversight nudge
 # self-suppresses — so this interactive ratify nudge never fires into an
-# absent-user subprocess (JTBD-006 friction guard). Only the literal "1"
-# suppresses. Silent-on-zero; fail-open; ADR-040 ≤2KB budget (one line).
+# absent-user subprocess (progress-the-backlog-while-i-m-away-user-outcome friction guard). Only the literal "1"
+# suppresses. Silent-on-zero; fail-open; session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule ≤2KB budget (one line).
 
 set -uo pipefail
 

package/hooks/itil-rfc-trailer-advisory.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
-# P170: PostToolUse:Bash hook — detects `git commit` invocations whose
+# 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: PostToolUse:Bash hook — detects `git commit` invocations whose
 # HEAD commit message carries a `Refs: RFC-<NNN>` trailer (the
-# commit-message RFC trailer convention introduced by ADR-060 Phase 1
+# commit-message RFC trailer convention introduced by problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule Phase 1
 # item 12 + finding 8). For each such trailer, the hook checks whether
 # the driving problem ticket(s) `## RFCs` reverse-trace section lists
 # the RFC; emits a stderr advisory when stale.
@@ -14,14 +14,14 @@
 # `Refs: RFC-<NNN>` trailers but were authored OUTSIDE the RFC skills
 # and therefore did not run the inline refresh.
 #
-# Advisory-only per architect Q2 verdict + ADR-014 single-commit grain:
+# Advisory-only per architect Q2 verdict + governance-skills-commit-their-own-completed-work-architecture-rule single-commit grain:
 # the hook NEVER auto-fixes (no follow-up commit; no working-tree edit
 # after the commit lands). It emits a stderr advisory pointing the
 # user at `/wr-itil:manage-rfc <RFC-NNN>` to refresh the reverse-trace
 # in a subsequent commit, OR at `wr-itil-reconcile-rfcs docs/rfcs
 # docs/problems` to verify drift in batch.
 #
-# Allow paths (silent-on-pass per ADR-045 Pattern 1):
+# Allow paths (silent-on-pass per hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule Pattern 1):
 #   - tool_name != "Bash"           (only Bash invocations gated)
 #   - command lacks `git commit`     (non-commit Bash bypasses)
 #   - BYPASS_RFC_TRAILER_ADVISORY=1  (env-var escape)
@@ -34,10 +34,10 @@
 # Multi-`Refs:` malformed-per-finding-8 advisory: when HEAD's commit
 # message carries multiple `Refs: RFC-<NNN>` trailer lines, the hook
 # emits a malformed-per-finding-8 advisory directing the user to split
-# the commit (one commit advances at most one RFC per ADR-060 finding
+# the commit (one commit advances at most one RFC per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule finding
 # 8). The split itself is user-side work; the hook flags only.
 #
-# Failmode (per ADR-013 Rule 6 fail-open): on parse error in the
+# Failmode (per structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-open): on parse error in the
 # trailer, on a Refs: trailer pointing to a non-existent RFC file
 # (could be a capture-rfc invocation in flight), on `git interpret-trailers`
 # failure — exit 0 silently. The reconcile-rfcs.sh batch surface
@@ -45,37 +45,37 @@
 # Confirmation criterion 3.
 #
 # Cost: one git invocation per `git commit` Bash call (~30-60ms). No
-# marker (per-invocation deterministic; mirrors P125 staging-detect.sh
-# and P141 itil-changeset-discipline.sh precedent).
+# marker (per-invocation deterministic; mirrors staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem staging-detect.sh
+# and afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem itil-changeset-discipline.sh precedent).
 #
 # Command-shape detection delegates to
 # `lib/command-detect.sh::command_invokes_git_commit`, which strips
 # common prefix shapes (leading whitespace, env-var assignments,
 # `cd <path> &&`) and checks whether the residual leading token pair
-# is literally `git commit`. P274: replaced the prior substring match
+# is literally `git commit`. itil-rfc-trailer-advisory-sh-hook-substring-matches-git-commit-anywhere-in-bash-command-sibling-problem: replaced the prior substring match
 # `*"git commit"*` that misfired on non-commit Bash whose argument
 # vectors merely mentioned the phrase (grep / sed / cat-heredoc /
 # echo / `git log --grep`).
 #
 # References:
-#   ADR-005 — plugin testing strategy (hook bats live under hooks/test/).
-#   ADR-013 Rule 6 — fail-open on missing inputs / parse errors.
-#   ADR-014 — single-commit grain (this hook never auto-fixes via
+#   plugin-testing-strategy-architecture-rule — plugin testing strategy (hook bats live under hooks/test/).
+#   structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 — fail-open on missing inputs / parse errors.
+#   governance-skills-commit-their-own-completed-work-architecture-rule — single-commit grain (this hook never auto-fixes via
 #             follow-up commit; advisory-only).
-#   ADR-017 — shared-code sync pattern (command-detect.sh canonical at
+#   shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule — shared-code sync pattern (command-detect.sh canonical at
 #             packages/shared/hooks/lib/).
-#   ADR-038 — progressive disclosure / advisory band ≤300 bytes.
-#   ADR-045 — hook injection budget; Pattern 1 silent-on-pass.
-#   ADR-051 — load-bearing-from-the-start (drift detection ships at
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — progressive disclosure / advisory band ≤300 bytes.
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule — hook injection budget; Pattern 1 silent-on-pass.
+#   windyroad-plugin-readmes-anchor-on-jtbd-job-ids-with-load-bearing-commit-hook-prose-woven-framing-architecture-rule — load-bearing-from-the-start (drift detection ships at
 #             the same time as the convention; never deferred).
-#   ADR-052 — behavioural-tests default; bats live alongside.
-#   ADR-060 — Phase 1 item 12 + Confirmation criterion 3.
-#   P170    — driving problem ticket.
-#   P081    — behavioural tests preferred over structural greps.
-#   P125    — sibling per-invocation no-marker hook precedent.
-#   P141    — sibling commit-time gate hook precedent.
-#   P268    — shared `command_invokes_git_commit` helper.
-#   P274    — sibling-hook refactor: substring-match → helper here.
+#   behavioural-tests-default-for-skill-testing-architecture-rule — behavioural-tests default; bats live alongside.
+#   problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule — Phase 1 item 12 + Confirmation criterion 3.
+#   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    — driving problem ticket.
+#   problem-081-structural-source-content-tests-are-wasteful-tdd-agent-should-reject-them-and-require-behavioural-tests-framework-stub-enhancements-problem    — behavioural tests preferred over structural greps.
+#   staging-trap-recurs-despite-documentation-hook-level-enforcement-candidate-problem    — sibling per-invocation no-marker hook precedent.
+#   afk-iter-packages-plugin-commits-without-changesets-orchestrator-main-turn-back-fill-is-fragile-recovery-hook-level-enforcement-preferable-problem    — sibling commit-time gate hook precedent.
+#   hook-substring-matches-git-commit-anywhere-in-bash-command-not-just-actual-git-commit-invocations-problem    — shared `command_invokes_git_commit` helper.
+#   itil-rfc-trailer-advisory-sh-hook-substring-matches-git-commit-anywhere-in-bash-command-sibling-problem    — sibling-hook refactor: substring-match → helper here.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
@@ -106,7 +106,7 @@ except:
     print('')
 " 2>/dev/null || echo "")
 
-# Only fire on actual `git commit` invocations. P274: delegates to the
+# Only fire on actual `git commit` invocations. itil-rfc-trailer-advisory-sh-hook-substring-matches-git-commit-anywhere-in-bash-command-sibling-problem: delegates to the
 # shared `command_invokes_git_commit` helper for leading-executable
 # semantics (was substring match prone to grep/sed/echo false positives).
 command_invokes_git_commit "$COMMAND" || exit 0
@@ -138,7 +138,7 @@ TRAILERS=$(printf '%s\n' "$COMMIT_MSG" | git interpret-trailers --parse 2>/dev/n
 # Multi-Refs: malformed-per-finding-8 advisory.
 TRAILER_COUNT=$(printf '%s\n' "$TRAILERS" | wc -l | tr -d ' ')
 if [ "$TRAILER_COUNT" -gt 1 ]; then
-  echo "P170 ADVISORY: HEAD commit carries ${TRAILER_COUNT} Refs: RFC trailers (malformed-per-finding-8 — one commit advances at most one RFC per ADR-060). Recovery: split the commit; rerun /wr-itil:manage-rfc on each RFC. Bypass: BYPASS_RFC_TRAILER_ADVISORY=1." >&2
+  echo "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 ADVISORY: HEAD commit carries ${TRAILER_COUNT} Refs: RFC trailers (malformed-per-finding-8 — one commit advances at most one RFC per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule). Recovery: split the commit; rerun /wr-itil:manage-rfc on each RFC. Bypass: BYPASS_RFC_TRAILER_ADVISORY=1." >&2
   exit 0
 fi
 
@@ -209,6 +209,6 @@ done
 # No drift → silent.
 [ -n "$STALE_PIDS" ] || exit 0
 
-# Emit advisory (per ADR-045 ≤300 byte band; stderr; exit 0).
-echo "P170 ADVISORY: HEAD commit ${RFC_ID} trailer; problem(s) ${STALE_PIDS} ## RFCs section stale (skill-side refresh missed). Recovery: /wr-itil:manage-rfc ${RFC_ID} OR wr-itil-reconcile-rfcs docs/rfcs docs/problems. Bypass: BYPASS_RFC_TRAILER_ADVISORY=1." >&2
+# Emit advisory (per hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule ≤300 byte band; stderr; exit 0).
+echo "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 ADVISORY: HEAD commit ${RFC_ID} trailer; problem(s) ${STALE_PIDS} ## RFCs section stale (skill-side refresh missed). Recovery: /wr-itil:manage-rfc ${RFC_ID} OR wr-itil-reconcile-rfcs docs/rfcs docs/problems. Bypass: BYPASS_RFC_TRAILER_ADVISORY=1." >&2
 exit 0

package/hooks/itil-runtime-sid-marker.sh

@@ -1,12 +1,12 @@
 #!/bin/bash
-# P142 / ADR-050: runtime-SID instrumentation 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 instrumentation PreToolUse hook.
 #
 # Captures the runtime stdin `session_id` from Claude Code's PreToolUse
 # JSON payload and writes it to a per-machine, per-user, per-project
 # marker file. The `get_current_session_id` helper (lib/session-id.sh)
 # reads this marker as the authoritative current-session UUID, replacing
 # the Phase 3 mtime-based announce-marker selection that misfired in
-# orchestrator main turns AFTER subprocess dispatch (P142 ticket).
+# orchestrator main turns AFTER subprocess dispatch (phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem ticket).
 #
 # Why a NEW PreToolUse hook (not an extension of an existing one):
 #   - manage-problem-enforce-create.sh already runs on PreToolUse:Write,
@@ -15,8 +15,8 @@
 #     ensures the marker is in place by the time enforce-create reads.
 #   - The architect-enforce-edit / jtbd-enforce-edit / tdd-enforce hooks
 #     are owned by sibling plugins; cross-plugin coupling is rejected
-#     per ADR-017 (shared-code-sync).
-#   - A standalone, single-purpose hook is the cleanest fit for ADR-045
+#     per shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule (shared-code-sync).
+#   - A standalone, single-purpose hook is the cleanest fit for hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule
 #     Pattern 1 (silent-on-pass, side-effect-only).
 #
 # Matcher: PreToolUse:Bash|Write|Edit|Read covers the tool calls that
@@ -25,7 +25,7 @@
 # Read is included for completeness — every tool call that fires a
 # PreToolUse hook contributes a fresh marker).
 #
-# ADR-045 Pattern 1 binding: this hook MUST emit 0 bytes on stdout.
+# hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule Pattern 1 binding: this hook MUST emit 0 bytes on stdout.
 # Adding stdout output would burn the per-tool-call context budget.
 # All side effects are filesystem writes; observability is via the
 # marker file itself.
@@ -37,12 +37,12 @@
 # announce-marker priority logic.
 #
 # References:
-#   ADR-050 — runtime-SID instrumentation surface (this hook).
-#   ADR-048 — gate-misfire recovery (superseded by ADR-050).
-#   ADR-045 — hook injection budget; Pattern 1 binding.
-#   ADR-038 — announce-marker contract (cold-path fallback consumer).
-#   P142    — the ticket this hook closes.
-#   P124    — Phase 3 helper this hook complements.
+#   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 surface (this hook).
+#   documented-recovery-from-gate-misfire-is-the-prescribed-surface-not-bypass-architecture-rule — gate-misfire recovery (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).
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule — hook injection budget; Pattern 1 binding.
+#   progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule — announce-marker contract (cold-path fallback consumer).
+#   phase-4-get-current-session-id-helper-system-priority-bug-subprocess-sids-win-mtime-selection-over-orchestrator-sid-problem    — the ticket this hook closes.
+#   wr-itil-manage-problem-step-2-substep-7-session-id-discovery-is-brittle-agent-has-no-env-var-must-scrape-marker-filenames-problem    — Phase 3 helper this hook complements.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/runtime-sid.sh

package/hooks/itil-story-mirror-migration-nudge.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# wr-itil — SessionStart hook (P474 / RFC-059 / STORY-054).
+# wr-itil — SessionStart hook (oversight-hash-treats-the-status-body-mirror-as-substance-so-an-accept-transition-self-invalidates-its-own-ratification-problem / lifecycle-state-is-not-duplicated-inside-hashed-story-content-release-design / lifecycle-transitions-preserve-a-story-s-ratification-delivery-story).
 #
 # Surfaces a one-line nudge when any story still carries the `**Status**:` body
 # line that duplicates its frontmatter `status:`. That duplicate is why an accept
@@ -12,27 +12,27 @@
 # adopter's repo — as a control it depends entirely on someone remembering. A
 # maintenance action with no automatic trigger does not happen, so artefacts
 # predating the fix would keep the defect indefinitely while newly captured
-# stories were immune. JTBD-009 already sanctions this shape: "Idempotency is
+# stories were immune. migrate-adopter-artefacts-when-a-plugin-layout-evolves-user-outcome already sanctions this shape: "Idempotency is
 # what makes the speculative invocation safe — and what makes the skill safe to
 # wire into bootstrap / install flows."
 #
-# NUDGE ONLY — this hook MUST NOT run the migration. JTBD-009's ratified
+# NUDGE ONLY — this hook MUST NOT run the migration. migrate-adopter-artefacts-when-a-plugin-layout-evolves-user-outcome's ratified
 # "Foreground-synchronous + self-committed" outcome is explicit that the
 # developer reviews the rewritten artefacts before they ship, so migrating
 # unattended would breach a ratified outcome rather than serve it.
 #
-# Names the ADR-049 PATH shim, never a repo-relative `packages/...` path — the
+# Names the plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule PATH shim, never a repo-relative `packages/...` path — the
 # latter resolves only in the source monorepo, which is exactly the blind spot
-# source-repo dogfooding hides (P151/P153/P219/P317).
+# source-repo dogfooding hides (published-skills-reference-repo-relative-script-paths-adopter-bash-invocations-hard-fail-at-step-0-problem/published-skills-enumerate-repo-relative-directories-adopter-sessions-get-zero-byte-attribution-rows-from-missing-trees-problem/manage-problem-skill-md-uses-repo-relative-script-path-that-fails-for-plugin-installed-users-problem/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).
 #
 # Detection is token-cheap: one grep over story filenames, no body reads beyond
 # the match, no LLM call. Silent when clean (the steady state after migrating),
-# fail-open, one line, within the ADR-040 ≤2KB budget.
+# fail-open, one line, within the session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule ≤2KB budget.
 #
 # AFK self-suppress: shares the suite-wide WR_SUPPRESS_OVERSIGHT_NUDGE guard
 # with the architect / jtbd / itil-rfc oversight nudges, so an orchestrator
 # exports it once and every nudge self-suppresses rather than firing at an
-# absent user (JTBD-006 friction guard). Only the literal "1" suppresses.
+# absent user (progress-the-backlog-while-i-m-away-user-outcome friction guard). Only the literal "1" suppresses.
 
 set -uo pipefail
 

package/hooks/lib/block-list.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
-# P123: shared block-list helper for the inbound-report block mechanism.
-# Per ADR-046 §v1 implementation contract — audit-log-only.
+# blocked-user-list-mechanism-for-inbound-report-management-refuse-future-tickets-from-clearly-malicious-reporters-problem: shared block-list helper for the inbound-report block mechanism.
+# Per blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule §v1 implementation contract — audit-log-only.
 #
 # Functions:
 #   is_blocked(<reporter-id-hash>)
@@ -17,16 +17,16 @@
 # Helper does NOT compute hashes. Caller supplies an opaque hex string;
 # the helper validates SHA-256-width hex shape (64 chars, [0-9a-f]).
 # Rationale (architect verdict, this iter): keeping the helper GitHub-
-# agnostic means non-GitHub channel adoption (out-of-scope per ADR-046
+# agnostic means non-GitHub channel adoption (out-of-scope per blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule
 # §Reassessment) wouldn't require helper changes — only the hashing
 # step on the caller side would differ.
 #
 # Persistence:
 #   $BLOCK_LIST_FILE — default `docs/blocked-reporters.json`. JSON array
-#                      of hash strings. Tracked in git per ADR-046.
+#                      of hash strings. Tracked in git per blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule.
 #   $AUDIT_LOG_FILE  — default `docs/blocked-reporters.audit.jsonl`.
 #                      One JSON object per line (append-only). Five-field
-#                      shape per ADR-046 Q2: type, reporter_id_hash,
+#                      shape per blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule Q2: type, reporter_id_hash,
 #                      evidence_ticket, timestamp, author.
 #
 # Both file paths are relative to the caller's CWD so test fixtures
@@ -39,20 +39,20 @@
 # cycle for append).
 #
 # References:
-#   ADR-005 — plugin testing strategy (helper bats live alongside).
-#   ADR-014 — governance skills commit their own work (this helper is
-#             called by future P079 / report-upstream consumers; their
+#   plugin-testing-strategy-architecture-rule — plugin testing strategy (helper bats live alongside).
+#   governance-skills-commit-their-own-completed-work-architecture-rule — governance skills commit their own work (this helper is
+#             called by future problem-079-no-inbound-sync-of-upstream-reported-problems-reports-filed-via-the-intake-templates-never-surface-in-the-local-backlog-problem / report-upstream consumers; their
 #             commits include the block-list mutation).
-#   ADR-017 — shared-code-sync pattern (helper ships ahead of consumers).
-#   ADR-022 — verification-pending status (P123 ships audit-log-only,
+#   shared-code-duplicated-into-per-package-lib-kept-in-sync-by-script-ci-drift-check-architecture-rule — shared-code-sync pattern (helper ships ahead of consumers).
+#   problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule — verification-pending status (blocked-user-list-mechanism-for-inbound-report-management-refuse-future-tickets-from-clearly-malicious-reporters-problem ships audit-log-only,
 #             transitions to verifying; full enforcement in future iters).
-#   ADR-029 — diagnose before implement (ADR-046 is the diagnosis).
-#   ADR-030 — repo-local skills / per-repo artefact precedent.
-#   ADR-037 — skill testing strategy (this is hook-shared-helper, not
+#   diagnose-before-implement-structured-hypothesis-evidence-red-for-the-right-reason-gate-architecture-rule — diagnose before implement (blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule is the diagnosis).
+#   repo-local-skills-for-project-specific-workflow-tooling-architecture-rule — repo-local skills / per-repo artefact precedent.
+#   skill-testing-strategy-contract-assertion-bats-companion-to-architecture-rule — skill testing strategy (this is hook-shared-helper, not
 #             skill content; bats partition under hooks/test/).
-#   ADR-046 — blocked-reporters persistence (proposed → accepted with
+#   blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule — blocked-reporters persistence (proposed → accepted with
 #             this iter); §v1 implementation contract names this helper.
-#   P123    — primary ticket.
+#   blocked-user-list-mechanism-for-inbound-report-management-refuse-future-tickets-from-clearly-malicious-reporters-problem    — primary ticket.
 
 # Default paths — caller's CWD relative. Override for tests by exporting
 # BLOCK_LIST_FILE / AUDIT_LOG_FILE before sourcing.
@@ -62,7 +62,7 @@
 # SHA-256 hex width (64 chars). Helper rejects any input that doesn't
 # match this shape — per architect verdict, we don't allow alternate
 # hash widths in v1 (single-shape contract is simpler to reason about
-# and the JTBD-101 "decide once, encode it" pattern wins here).
+# and the extend-the-suite-with-new-plugins-user-outcome "decide once, encode it" pattern wins here).
 _BLOCK_LIST_HASH_RE='^[0-9a-f]{64}$'
 
 # Validate that a string is SHA-256-width hex. Returns 0 on match.
@@ -80,7 +80,7 @@ _block_list_ensure_file() {
   fi
 }
 
-# Append one JSONL audit-log entry. Five-field shape per ADR-046 Q2.
+# Append one JSONL audit-log entry. Five-field shape per blocked-reporters-persistence-per-repo-hashed-id-audit-log-first-architecture-rule Q2.
 # `evidence_ticket` carries the reason string for unblock entries
 # (type-tagged; the unblock reason reuses the same slot).
 _block_list_audit_append() {