@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/hooks/itil-codex-dispatch.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Fan out ITIL hooks from one trusted Codex hook per lifecycle event.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EVENT="${1:-}"
+INPUT="$(cat)"
+INPUT="$(printf '%s' "$INPUT" | CODEX_THREAD_ID="${CODEX_THREAD_ID:-}" python3 -c '
+import json, os, sys
+try:
+    value = json.load(sys.stdin)
+except (json.JSONDecodeError, TypeError):
+    value = {}
+value.setdefault("session_id", os.environ.get("CODEX_THREAD_ID", ""))
+value.setdefault("cwd", os.getcwd())
+value.setdefault("tool_input", {})
+print(json.dumps(value))
+')"
+OUTPUTS=()
+
+run_hook() {
+  local output
+  output="$(printf '%s' "$INPUT" | "$SCRIPT_DIR/$1" 2>&1 || true)"
+  if [ -n "$output" ]; then
+    OUTPUTS+=("$(printf '%s\n' "$output" | sed 's/AskUserQuestion/request_user_input/g; s#\.claude/#.codex/#g; s/CLAUDE\.md/AGENTS.md/g')")
+  fi
+}
+
+emit_outputs() {
+  [ "${#OUTPUTS[@]}" -gt 0 ] || return 0
+  printf '%s\0' "${OUTPUTS[@]}" | EVENT="$EVENT" python3 -c '
+import json, os, sys
+
+messages, reasons, stops = [], [], []
+for raw in sys.stdin.buffer.read().decode().split("\0"):
+    if not raw:
+        continue
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError:
+        messages.append(raw)
+        continue
+    if value.get("systemMessage"):
+        messages.append(value["systemMessage"])
+    if value.get("stopReason"):
+        stops.append(value["stopReason"])
+    specific = value.get("hookSpecificOutput") or {}
+    if specific.get("permissionDecision") == "deny":
+        reasons.append(specific.get("permissionDecisionReason") or "Denied by ITIL policy")
+    if specific.get("additionalContext"):
+        messages.append(specific["additionalContext"])
+
+if reasons:
+    names = {"pre-tool": "PreToolUse", "post-tool": "PostToolUse"}
+    print(json.dumps({"hookSpecificOutput": {
+        "hookEventName": names.get(os.environ.get("EVENT"), "PreToolUse"),
+        "permissionDecision": "deny",
+        "permissionDecisionReason": "\n".join(reasons + messages),
+    }}))
+elif stops:
+    print(json.dumps({"stopReason": "\n".join(stops + messages)}))
+elif messages:
+    print(json.dumps({"systemMessage": "\n".join(messages)}))
+'
+}
+
+tool_name() {
+  printf '%s' "$INPUT" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_name") or "")' 2>/dev/null || true
+}
+
+input_field() {
+  printf '%s' "$INPUT" | python3 -c 'import json,sys; print(json.load(sys.stdin).get(sys.argv[1]) or "")' "$1" 2>/dev/null || true
+}
+
+work_problems_marker() {
+  local session_id digest
+  session_id="$(input_field session_id)"
+  [ -n "$session_id" ] || session_id="${CODEX_THREAD_ID:-unknown}"
+  digest="$(printf '%s' "$session_id" | shasum -a 256 | awk '{print $1}')"
+  printf '%s/wr-itil-codex-work-problems-%s' "${TMPDIR:-/tmp}" "$digest"
+}
+
+check_codex_dependencies() {
+  local installed
+  command -v codex >/dev/null 2>&1 || return 0
+  installed="$(codex plugin list 2>/dev/null)" || return 0
+  [[ "$installed" == *"wr-risk-scorer@"* ]] || OUTPUTS+=("$(jq -n '{systemMessage:"WR ITIL requires wr-risk-scorer for governed commit, push, and release assessment. Install @windyroad/risk-scorer for Codex."}')")
+}
+
+case "$EVENT" in
+  session-start)
+    AGENT_OUTPUT="$(printf '%s' "$INPUT" | node "$SCRIPT_DIR/../scripts/codex-agent.mjs" --session-start 2>/dev/null || true)"
+    [ -z "$AGENT_OUTPUT" ] || OUTPUTS+=("$AGENT_OUTPUT")
+    check_codex_dependencies
+    run_hook itil-pending-questions-surface.sh
+    run_hook itil-rfc-oversight-nudge.sh
+    run_hook itil-story-mirror-migration-nudge.sh
+    ;;
+  user-prompt)
+    PROMPT="$(input_field prompt)"
+    [[ "$PROMPT" == *"wr-itil:work-problems"* ]] && : > "$(work_problems_marker)"
+    run_hook itil-assistant-output-gate.sh
+    run_hook itil-correction-detect.sh
+    run_hook staleness-check.sh
+    ;;
+  pre-tool)
+    run_hook itil-runtime-sid-marker.sh
+    case "$(tool_name)" in
+      Write)
+        run_hook manage-problem-enforce-create.sh
+        run_hook itil-claude-space-protection.sh
+        ;;
+      Edit)
+        run_hook itil-claude-space-protection.sh
+        ;;
+      Bash)
+        run_hook p057-staging-trap-detect.sh
+        run_hook itil-no-implement-draft-gate.sh
+        run_hook itil-bash-polling-antipattern-detect.sh
+        run_hook pre-publish-intake-gate.sh
+        run_hook itil-changeset-discipline.sh
+        run_hook itil-readme-refresh-discipline.sh
+        ;;
+      request_user_input|AskUserQuestion)
+        if [ -f "$(work_problems_marker)" ]; then
+          OUTPUTS+=("$(jq -n '{systemMessage:"MID-LOOP ASK DETECTED: request_user_input fired during wr-itil:work-problems. Use it only at a documented halt point; otherwise queue the question and continue with other actionable work."}')")
+        fi
+        ;;
+    esac
+    ;;
+  post-tool)
+    case "$(tool_name)" in
+      Bash)
+        run_hook itil-rfc-trailer-advisory.sh
+        run_hook itil-commit-trailer-transition-advisory.sh
+        run_hook itil-fix-title-lifecycle-advisory.sh
+        ;;
+      Write|Edit)
+        run_hook itil-fictional-defer-detect.sh
+        run_hook itil-deferral-cadence-gate.sh
+        ;;
+    esac
+    ;;
+  stop)
+    ASSISTANT_TEXT="$(printf '%s' "$INPUT" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("last_assistant_message") or "")' 2>/dev/null || true)"
+    [ -n "$ASSISTANT_TEXT" ] || exit 0
+    # shellcheck source=lib/detectors.sh
+    source "$SCRIPT_DIR/lib/detectors.sh"
+    MATCH="$(printf '%s' "$ASSISTANT_TEXT" | detect_prose_ask 2>/dev/null || true)"
+    [ -z "$MATCH" ] || OUTPUTS+=("$(jq -n --arg match "$MATCH" '{stopReason:("PROSE-ASK DETECTED (pattern: \""+$match+"\"). Act when direction is clear; otherwise use request_user_input in Plan Mode. Never prose-ask.")}')")
+    MATCH="$(printf '%s' "$ASSISTANT_TEXT" | detect_mechanical_optional 2>/dev/null || true)"
+    [ -z "$MATCH" ] || OUTPUTS+=("$(jq -n --arg match "$MATCH" '{stopReason:("MECHANICAL STEP PRESENTED AS OPTIONAL (closer: \""+$match+"\"). Run the contract-mandated step instead of asking or skipping it.")}')")
+    if [[ "$ASSISTANT_TEXT" == *"ALL_DONE"* || "$ASSISTANT_TEXT" == *"## Work Problems Summary"* ]]; then
+      rm -f "$(work_problems_marker)"
+    fi
+    ;;
+  *)
+    echo "itil-codex-dispatch: unknown event '$EVENT'" >&2
+    exit 2
+    ;;
+esac
+
+emit_outputs

package/hooks/itil-commit-trailer-transition-advisory.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
-# wr-itil — PostToolUse:Bash hook (P378/RFC-030 Piece 2). The SHARED
-# commit-trailer auto-transition trigger that ADR-060 (line 292/307) promised
+# wr-itil — PostToolUse:Bash hook (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem/rfc-lifecycle-self-maintenance-release-design Piece 2). The SHARED
+# commit-trailer auto-transition trigger that problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (line 292/307) promised
 # for BOTH the RFC and story tiers and that manage-rfc + manage-story both
 # deferred to "a future commit-trailer-trigger hook" — never built. This is it.
 #
-# Per ADR-014, a hook MUST NOT perform the transition itself (git mv + Status
+# Per governance-skills-commit-their-own-completed-work-architecture-rule, a hook MUST NOT perform the transition itself (git mv + Status
 # edit + commit lands OUTSIDE the triggering commit's grain). So the hook
 # DETECTS eligibility and ADVISES; the skill (/wr-itil:manage-rfc |
 # /wr-itil:manage-story) — or an AFK orchestrator acting on the advisory —
@@ -17,16 +17,16 @@
 #   - is NOT the artefact's capture commit (subject does not start with
 #     `docs(rfcs): capture RFC-` / `feat(itil): capture STORY-`), AND
 #   - the referenced artefact is in a pre-in-progress status
-#     (RFC: .proposed/.accepted ; story: .accepted — per ADR-096 a draft
+#     (RFC: .proposed/.accepted ; story: .accepted — per a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule a draft
 #     story is blocked from implementation, not advised to advance) on disk.
 # → emit a stderr advisory naming the transition command. Silent otherwise.
 #
-# Advisory-only (ADR-013 Rule 6 fail-open; ADR-045 ≤300-byte band; exit 0).
+# Advisory-only (structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-open; hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule ≤300-byte band; exit 0).
 # Bypass: BYPASS_TRANSITION_ADVISORY=1.
 #
-# @adr ADR-060 (line 292/307 auto-transition triggers) ADR-014 (hook detects,
-#      skill commits) ADR-045 (budget) ADR-013 (Rule 6 fail-open) ADR-052 (bats)
-# @problem P378  @rfc RFC-030
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (line 292/307 auto-transition triggers) governance-skills-commit-their-own-completed-work-architecture-rule (hook detects,
+#      skill commits) hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule (budget) structured-user-interaction-for-governance-skill-decisions-architecture-rule (Rule 6 fail-open) behavioural-tests-default-for-skill-testing-architecture-rule (bats)
+# @problem rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem  @rfc rfc-lifecycle-self-maintenance-release-design
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
@@ -57,7 +57,7 @@ TRAILERS=$(printf '%s\n' "$BODY" | git interpret-trailers --parse 2>/dev/null \
   | grep -oE 'RFC-[0-9]{3}|STORY-[0-9]{3}' | sort -u || true)
 [ -n "$TRAILERS" ] || exit 0
 
-advise() { echo "P378 ADVISORY: $1" >&2; }
+advise() { echo "rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem ADVISORY: $1" >&2; }
 
 while IFS= read -r id; do
   [ -n "$id" ] || continue
@@ -66,11 +66,11 @@ while IFS= read -r id; do
       [ -d "./docs/rfcs" ] || continue
       shopt -s nullglob; files=(./docs/rfcs/${id}-*.proposed.md ./docs/rfcs/${id}-*.accepted.md); shopt -u nullglob
       [ ${#files[@]} -gt 0 ] || continue
-      advise "${id} carries a non-capture commit but is still $(basename "${files[0]}" | grep -oE 'proposed|accepted'). It should advance to in-progress — run /wr-itil:manage-rfc ${id} in-progress (the skill performs the transition; a hook cannot, per ADR-014). Bypass: BYPASS_TRANSITION_ADVISORY=1."
+      advise "${id} carries a non-capture commit but is still $(basename "${files[0]}" | grep -oE 'proposed|accepted'). It should advance to in-progress — run /wr-itil:manage-rfc ${id} in-progress (the skill performs the transition; a hook cannot, per governance-skills-commit-their-own-completed-work-architecture-rule). Bypass: BYPASS_TRANSITION_ADVISORY=1."
       ;;
     STORY-*)
       [ -d "./docs/stories" ] || continue
-      # ADR-096: a draft story is NEVER implementable — the PreToolUse
+      # a-story-cannot-be-implemented-while-in-draft-implementation-requires-accepted-architecture-rule: a draft story is NEVER implementable — the PreToolUse
       # itil-no-implement-draft-gate blocks a commit referencing a draft story.
       # So this advisory now fires for an ACCEPTED story carrying its first
       # implementing commit: advise accepted -> in-progress (draft -> in-progress

package/hooks/itil-correction-detect.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# P078 / ADR-013 / ADR-038: itil correction-signal UserPromptSubmit gate.
+# problem-078-assistant-does-not-offer-to-capture-a-problem-ticket-when-the-user-delivers-strong-signal-correction-problem / structured-user-interaction-for-governance-skill-decisions-architecture-rule / progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule: itil correction-signal UserPromptSubmit gate.
 #
 # When the incoming user prompt carries a strong-affect correction
 # signal (FFS / all-caps imperatives like DO NOT / direct contradiction
@@ -10,20 +10,20 @@
 # and a ticket preserves the signal as durable WSJF-ranked backlog.
 #
 # Once-per-session full block; terse reminder on subsequent corrections
-# (per ADR-038 progressive disclosure). The full block names the
+# (per progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule progressive disclosure). The full block names the
 # matched pattern so the assistant has the why-this-fired context.
 #
-# Forward-compat: advertises /wr-itil:capture-problem (ADR-032 — not
+# Forward-compat: advertises /wr-itil:capture-problem (governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule — not
 # yet shipped) with /wr-itil:manage-problem as the today-target
 # fallback. When capture-problem ships the wording stays valid.
 #
-# P430 / STORY-047 — WR_SUPPRESS_CORRECTION_DETECT is a DISTINCT guard
+# itil-correction-detect-userpromptsubmit-hook-false-positives-on-orchestrator-afk-prompt-text-problem / gate-the-correction-nudge-on-prompt-authorship-delivery-story — WR_SUPPRESS_CORRECTION_DETECT is a DISTINCT guard
 # class, not a split of WR_SUPPRESS_OVERSIGHT_NUDGE. That guard means
 # "an absent user cannot ratify"; this one means "nobody authored a
 # correction". A machine-authored iter prompt carrying an ordinary
 # imperative ("DO NOT skip the gate") is not a correction signal, and
 # conflating the two would couple this gate's suppression to the
-# ADR-068 / ADR-047 oversight-nudge contract. Provenance is a property
+# jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule / install-updates-scaffolds-governance-artefacts-when-policy-file-is-present-but-artefact-is-missing-architecture-rule oversight-nudge contract. Provenance is a property
 # of the spawning process, so the dispatcher asserts it — the hook does
 # not sniff content for it.
 
@@ -59,7 +59,7 @@ fi
 
 if has_announced "itil-correction-detect" "$SESSION_ID"; then
   cat <<HOOK_OUTPUT
-MANDATORY: correction signal ($MATCHED). OFFER /wr-itil:capture-problem (fallback /wr-itil:manage-problem) BEFORE addressing the request. See P078.
+MANDATORY: correction signal ($MATCHED). OFFER /wr-itil:capture-problem (fallback /wr-itil:manage-problem) BEFORE addressing the request. See problem-078-assistant-does-not-offer-to-capture-a-problem-ticket-when-the-user-delivers-strong-signal-correction-problem.
 HOOK_OUTPUT
 else
   cat <<HOOK_OUTPUT
@@ -71,7 +71,7 @@ NON-OPTIONAL RULES:
 
 1. BEFORE addressing the operational request in the prompt, OFFER
    to capture a problem ticket for the underlying behavioural pattern.
-   Use /wr-itil:capture-problem when shipped (ADR-032 background
+   Use /wr-itil:capture-problem when shipped (governance-skill-invocation-patterns-foreground-background-with-deferred-question-resumption-architecture-rule background
    capture pattern). Until then, fall back to /wr-itil:manage-problem
    for synchronous capture.
 
@@ -84,7 +84,7 @@ NON-OPTIONAL RULES:
 3. The offer is non-blocking — the user can decline — but the offer
    MUST appear before the operational response. Do NOT wait for the
    user to request the ticket themselves; that's exactly the manual-
-   policing-AI-output friction P078 closes.
+   policing-AI-output friction problem-078-assistant-does-not-offer-to-capture-a-problem-ticket-when-the-user-delivers-strong-signal-correction-problem closes.
 
 4. Suggested phrasing: "Before I address that — want me to capture a
    problem ticket for this pattern?" Then proceed with the operational

package/hooks/itil-deferral-cadence-gate.sh

@@ -1,15 +1,15 @@
 #!/bin/bash
-# P375 — wr-itil PostToolUse:Write|Edit|MultiEdit hook.
+# repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem — wr-itil PostToolUse:Write|Edit|MultiEdit hook.
 #
 # The ratified Option-C "authoring-time enforcement gate" (CORE SLICE,
-# advisory rollout). P375's root cause: the repo conflates a "named
+# advisory rollout). repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem's root cause: the repo conflates a "named
 # re-entry point" (a /skill, a lifecycle transition, "next review") with
 # a SELF-FIRING cadence. A deferral that names `/wr-itil:manage-rfc`
 # rots because nothing self-fires manage-rfc on that artefact ("BUT
 # NOTHING TRIGGERS THAT WORK!!!", 2026-06-23). The correct rot test: a
 # deferral is legal only if its trigger chain is reachable from a
 # SELF-FIRING event (a hook, SessionStart, PreToolUse/PostToolUse, a CI
-# workflow, cron, or a work-problems pre-flight). ADR-084's SessionStart
+# workflow, cron, or a work-problems pre-flight). self-firing-deferral-census-a-sessionstart-surfacer-so-deferred-governance-work-cannot-silently-rot-architecture-rule's SessionStart
 # census (Option A) only SURFACES accumulated rot; this gate attacks the
 # root cause — it fires at AUTHORING time, the moment a new uncadenced
 # deferral is written.
@@ -20,7 +20,7 @@
 #      authoring surface — SKILL.md, docs/decisions/*.md (ADRs),
 #      docs/rfcs/*.md (RFCs), or a hook *.sh — and is NOT under
 #      docs/problems/ (tickets descriptively narrate deferrals; highest
-#      false-positive surface; already covered by the ADR-084 census).
+#      false-positive surface; already covered by the self-firing-deferral-census-a-sessionstart-surfacer-so-deferred-governance-work-cannot-silently-rot-architecture-rule census).
 #   2. The new text (Edit new_string / Write content / MultiEdit joined
 #      new_strings) introduces a deferral phrasing (DEFER_RE).
 #   3. Within the +/-5 line window of the match there is NO cadence
@@ -28,12 +28,12 @@
 #      `<!-- cadence: <trigger> -->` comment is the recommended carrier,
 #      but a bare prose mention of a self-firing surface also satisfies.
 #
-# THE LOAD-BEARING P375 REFINEMENT vs the P234 sibling
+# THE LOAD-BEARING repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem REFINEMENT vs the agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem sibling
 # (itil-fictional-defer-detect.sh): a bare named on-demand skill
 # (/wr-foo:bar) or a bare ticket ID (Pnnn / RFC-nnn / ADR-nnn) does NOT
 # satisfy the cadence requirement — that bare-naming IS the conflation
-# P375 names illegal. So CADENCE_RE deliberately OMITS skill-invocation
-# and ticket-ID forms (which the P234 hook WRONGLY accepts).
+# repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem names illegal. So CADENCE_RE deliberately OMITS skill-invocation
+# and ticket-ID forms (which the agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem hook WRONGLY accepts).
 #
 # CORE-SLICE BOUNDARY (named loudly per the architect review): the gate
 # checks the cadence names a self-firing CLASS — it does NOT validate
@@ -42,9 +42,9 @@
 # retrospective-deferral-census.sh -->). Citing a plausible-but-fictional
 # hook name passes this slice; the graph check closes that gap later.
 #
-# Advisory only — NEVER blocks (exit 0 always). Per ADR-040/045
-# declarative-first + ADR-013 Rule 6 fail-open + the P375 architect
-# review (advisory-first per ADR-057 staged rollout; escalation to a
+# Advisory only — NEVER blocks (exit 0 always). Per session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule/045
+# declarative-first + structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-open + the repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem architect
+# review (advisory-first per three-phase-declarative-first-rollout-for-cluster-shaped-governance-rules-architecture-rule staged rollout; escalation to a
 # PreToolUse block is a queued user-owned rollout-mode decision once the
 # advisory's false-positive rate is measured). AFK self-suppress:
 # WR_SUPPRESS_DEFERRAL_CADENCE_GATE=1 (mirrors the census's
@@ -52,27 +52,27 @@
 # authoring governance prose should be able to mute it).
 #
 # References:
-#   P375     — driver (this gate is the Option-C root-cause fix).
-#   P234     — the PostToolUse sibling (retro-only, accepts skills/IDs);
+#   repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem     — driver (this gate is the Option-C root-cause fix).
+#   agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem     — the PostToolUse sibling (retro-only, accepts skills/IDs);
 #              converging the two onto a shared vocabulary is a tracked
-#              P375 follow-on, NOT done here (ADR-002/003 self-containment
+#              repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem follow-on, NOT done here (monorepo-with-independently-installable-per-plugin-packages-architecture-rule/003 self-containment
 #              — itil keeps its own copy of the deferral vocabulary).
-#   ADR-084  — the surfacing-only census (Option A) this gate complements.
-#   ADR-040  — declarative-first; advisory over hard block.
-#   ADR-045  — hook injection budget; advisory ~600 bytes, ceiling 1000.
-#   ADR-013  — Rule 6 fail-open on empty/malformed stdin.
-#   ADR-052  — behavioural bats live alongside.
-#   ADR-057  — staged advisory-first rollout for cluster-shaped rules.
+#   self-firing-deferral-census-a-sessionstart-surfacer-so-deferred-governance-work-cannot-silently-rot-architecture-rule  — the surfacing-only census (Option A) this gate complements.
+#   session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule  — declarative-first; advisory over hard block.
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule  — hook injection budget; advisory ~600 bytes, ceiling 1000.
+#   structured-user-interaction-for-governance-skill-decisions-architecture-rule  — Rule 6 fail-open on empty/malformed stdin.
+#   behavioural-tests-default-for-skill-testing-architecture-rule  — behavioural bats live alongside.
+#   three-phase-declarative-first-rollout-for-cluster-shaped-governance-rules-architecture-rule  — staged advisory-first rollout for cluster-shaped rules.
 
 # Self-suppress (AFK). Only the literal "1" suppresses.
 [ "${WR_SUPPRESS_DEFERRAL_CADENCE_GATE:-}" = "1" ] && exit 0
 
 # Per-surface configuration (copy-and-retarget extensible, like the
-# P234 sibling: adjust the regex vars below).
+# agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem sibling: adjust the regex vars below).
 DEFER_RE='deferred to|deferred pending|defer pending|pending review|re-rate at next|\(deferred|: deferred|deferred[ ]*[—.,;:-]|lands in [Ss]lice|future slice|flesh(ed)? out later|next review|when ready'
 # Cadence-satisfying SELF-FIRING citations. NOTE the deliberate absence
 # of skill-invocation (/wr-foo:bar) and ticket-ID (Pnnn/RFC-nnn/ADR-nnn)
-# — those are the P375 conflation and do NOT satisfy the cadence.
+# — those are the repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem conflation and do NOT satisfy the cadence.
 HOOK_PATH_RE='[A-Za-z0-9_./-]+\.sh\b'
 SESSIONSTART_RE='SessionStart'
 TOOLUSE_RE='PreToolUse|PostToolUse'
@@ -175,7 +175,7 @@ rm -f "$SCAN"
 
 [ -n "$FICTIONAL_LINE" ] || exit 0
 
-# Advisory to stderr. ADR-045 budget (~600 bytes target). exit 0 always.
-echo "P375 ADVISORY: uncadenced deferral authored in ${FILE_PATH} — \"${FICTIONAL_PHRASE}\". A named on-demand re-entry point (/wr-foo:bar, a lifecycle transition, \"next review\") is NOT a cadence — nothing self-fires it, so the work rots. Add a cadence annotation naming a SELF-FIRING trigger within +/-5 lines: <!-- cadence: <hook *.sh | SessionStart | PreToolUse/PostToolUse | .github/workflows/ | cron | work-problems pre-flight> --> OR do the work now. (Core slice checks the trigger CLASS, not that it exists.) See P375." >&2
+# Advisory to stderr. hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule budget (~600 bytes target). exit 0 always.
+echo "repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem ADVISORY: uncadenced deferral authored in ${FILE_PATH} — \"${FICTIONAL_PHRASE}\". A named on-demand re-entry point (/wr-foo:bar, a lifecycle transition, \"next review\") is NOT a cadence — nothing self-fires it, so the work rots. Add a cadence annotation naming a SELF-FIRING trigger within +/-5 lines: <!-- cadence: <hook *.sh | SessionStart | PreToolUse/PostToolUse | .github/workflows/ | cron | work-problems pre-flight> --> OR do the work now. (Core slice checks the trigger CLASS, not that it exists.) See repo-conflates-a-named-re-entry-point-with-a-self-firing-cadence-deferrals-not-transitively-reachable-from-an-automatic-trigger-rot-problem." >&2
 
 exit 0

package/hooks/itil-fictional-defer-detect.sh

@@ -1,11 +1,11 @@
 #!/bin/bash
-# P234 Phase 1 — wr-itil PostToolUse:Write|Edit hook.
+# agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem Phase 1 — wr-itil PostToolUse:Write|Edit hook.
 #
 # Detects "fictional defer" rationales in `docs/retros/*.md` writes —
 # defer-rationale phrases (`next retro`, `next session`, `defer
 # pending`, `defer with cause:`, `deferred per`) that lack a
 # SCHEDULED-FUTURE-SURFACE citation in the surrounding +/-5-line
-# window. The regression class P234 captures (2026-05-17 session 3
+# window. The regression class agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem captures (2026-05-17 session 3
 # retro: 3 MUST_SPLIT files deferred with "cascade case: archive-of-
 # archive tier design needed" rationale; user correction "Don't defer"
 # revealed the cascade was mechanical, not a design barrier).
@@ -25,13 +25,13 @@
 #      (e.g. `deferred per Branch B` — Branch B's next-retro
 #      check-briefing-budgets.sh trigger IS the scheduled surface).
 #
-# When all four hold, the hook emits a stderr advisory citing P234 +
+# When all four hold, the hook emits a stderr advisory citing agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem +
 # the SCHEDULED-FUTURE-SURFACE definition + remediation pattern
 # (cite a surface OR execute the deferred work now). The advisory
 # names the file path, line number, and detected phrase so the next
 # assistant turn has enough context to self-correct.
 #
-# Advisory only — NEVER blocks. Per ADR-013 Rule 6 fail-safe + ADR-045
+# Advisory only — NEVER blocks. Per structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-safe + hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule
 # honour-system budget (target ~600 bytes; hard ceiling 1000). Mirrors
 # the itil-rfc-trailer-advisory.sh PostToolUse precedent (stderr +
 # exit 0) and the itil-mid-loop-ask-detect.sh per-surface configuration
@@ -39,19 +39,19 @@
 # EXEMPT_PHRASES at the top so the hook is copy-and-retarget extensible).
 #
 # References:
-#   P234     — this hook (Phase 1 structural enforcement).
-#   P148     — Tickets Deferred section misuse; same class, different
+#   agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem     — this hook (Phase 1 structural enforcement).
+#   agent-defers-ticket-creation-to-retro-summary-tickets-deferred-section-instead-of-immediately-invoking-wr-itil-manage-problem-observations-could-be-lost-if-user-is-in-a-rush-problem     — Tickets Deferred section misuse; same class, different
 #              surface (advisory script not hook).
-#   P132     — over-ask class (inverse-correctness axis of P234 under-do);
+#   agents-over-ask-in-interactive-sessions-conflating-mechanical-stages-with-user-interactive-stages-of-multi-stage-skill-contracts-inverse-problem     — over-ask class (inverse-correctness axis of agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem under-do);
 #              Phase 2b hook itil-mid-loop-ask-detect.sh is the canonical
 #              advisory-shape template.
-#   ADR-013  — Rule 6 fail-open on missing inputs / parse errors.
-#   ADR-014  — single-commit grain (this hook never auto-fixes).
-#   ADR-040  — declarative-first; advisory-only over hard block.
-#   ADR-044  — framework-resolution boundary; named in advisory.
-#   ADR-045  — hook injection budget; honour-system <1000 hard ceiling.
-#   ADR-052  — behavioural-tests default; bats live alongside.
-#   ADR-057  — three-phase declarative-first cluster rollout
+#   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).
+#   session-start-briefing-surface-sessionstart-hook-over-tiered-directory-indexed-readme-architecture-rule  — declarative-first; advisory-only over hard block.
+#   decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule  — framework-resolution boundary; named in advisory.
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule  — hook injection budget; honour-system <1000 hard ceiling.
+#   behavioural-tests-default-for-skill-testing-architecture-rule  — behavioural-tests default; bats live alongside.
+#   three-phase-declarative-first-rollout-for-cluster-shaped-governance-rules-architecture-rule  — three-phase declarative-first cluster rollout
 #              (Phase 2 advisory-second slot).
 
 # Per-surface configuration. Extending coverage to other accumulator-
@@ -169,7 +169,7 @@ done <<< "$MATCHES"
 
 # Emit advisory to stderr (PostToolUse precedent matches
 # itil-rfc-trailer-advisory.sh). Always exit 0 — advisory, never block.
-# Voice-tone target ~600 bytes; ADR-045 honour-system ceiling <1000.
-echo "P234 ADVISORY: fictional defer detected in ${FILE_PATH}:${FICTIONAL_LINE} — phrase: \"${FICTIONAL_PHRASE}\". No SCHEDULED-FUTURE-SURFACE cited within +/-5 lines. Per ADR-044 framework-resolution boundary, cite a concrete surface (ticket ID Pnnn, named skill /wr-foo:bar, hook path *.sh, CI workflow .github/workflows/, or dated ADR-nnn YYYY-MM-DD) OR execute the deferred work in this session. See P234." >&2
+# Voice-tone target ~600 bytes; hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule honour-system ceiling <1000.
+echo "agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem ADVISORY: fictional defer detected in ${FILE_PATH}:${FICTIONAL_LINE} — phrase: \"${FICTIONAL_PHRASE}\". No SCHEDULED-FUTURE-SURFACE cited within +/-5 lines. Per decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule framework-resolution boundary, cite a concrete surface (ticket ID Pnnn, named skill /wr-foo:bar, hook path *.sh, CI workflow .github/workflows/, or dated ADR-nnn YYYY-MM-DD) OR execute the deferred work in this session. See agent-defers-framework-required-mechanical-work-to-next-retro-next-session-with-rationalization-defer-is-fictional-work-never-scheduled-problem." >&2
 
 exit 0

package/hooks/itil-fix-title-lifecycle-advisory.sh

@@ -1,28 +1,28 @@
 #!/bin/bash
-# wr-itil — PostToolUse:Bash hook (P345/RFC-044/STORY-038). Detects the
+# wr-itil — PostToolUse:Bash hook (fix-titled-commits-do-not-transition-the-ticket-lifecycle-in-the-same-commit-grain-ticket-stays-open-across-release-ci-verify-multiple-intervening-commits-problem/fix-title-lifecycle-drift-advisory-hook-release-design/fix-titled-commits-surface-a-lifecycle-drift-advisory-delivery-story). Detects the
 # fix-without-paired-lifecycle-transition drift: a just-landed commit whose
 # subject is fix-typed (`fix: ...` / `fix(<pkg>): ...`) and names P<NNN>
 # ticket(s) that are still in `docs/problems/open/` — i.e. the commit claims
 # to fix a ticket but carried no Open -> Known Error (or -> Verifying)
 # transition in the same grain. The ticket then ages across release + CI
-# verification until a catch-up cadence notices (P345; P334 witness chain).
+# verification until a catch-up cadence notices (fix-titled-commits-do-not-transition-the-ticket-lifecycle-in-the-same-commit-grain-ticket-stays-open-across-release-ci-verify-multiple-intervening-commits-problem; generate-decisions-compendium-sh-uses-awk-substr-with-unicode-ellipsis-not-portable-between-macos-bsd-awk-and-linux-gnu-awk-ci-drift-gate-fires-on-cross-platform-regenerations-problem witness chain).
 #
-# ADVISORY-ONLY per ADR-092: Open -> Known Error asserts a knowledge claim
+# ADVISORY-ONLY per fix-titled-commit-lifecycle-drift-surfaces-as-an-advisory-never-an-auto-fire-or-hard-gate-architecture-rule: Open -> Known Error asserts a knowledge claim
 # (root cause known + workaround documented) that a fix-titled commit does
 # NOT establish, so this hook must never auto-fire the transition and never
 # block the commit. The hook DETECTS and ADVISES; a skill
 # (/wr-itil:transition-problem) — or the human — PERFORMS the transition
-# (ADR-014 hook-detects-skill-commits grain). Sibling (copy-and-retarget) of
-# itil-commit-trailer-transition-advisory.sh (P378): different signal —
+# (governance-skills-commit-their-own-completed-work-architecture-rule hook-detects-skill-commits grain). Sibling (copy-and-retarget) of
+# itil-commit-trailer-transition-advisory.sh (rfc-lifecycle-is-not-self-maintaining-it-leans-on-human-memory-problem): different signal —
 # commit-title P<NNN> tokens vs Refs: trailers.
 #
-# Advisory-only (ADR-013 Rule 6 fail-open; ADR-045 ≤300-byte TOTAL emission
+# Advisory-only (structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-open; hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule ≤300-byte TOTAL emission
 # even with multiple named tickets; exit 0 on every path).
 # Bypass: BYPASS_FIX_TITLE_LIFECYCLE_ADVISORY=1.
 #
-# @adr ADR-092 (advisory-only posture + binding rule) ADR-014 (hook detects,
-#      skill commits) ADR-045 (budget) ADR-013 (Rule 6 fail-open) ADR-052 (bats)
-# @problem P345  @rfc RFC-044  @story STORY-038
+# @adr fix-titled-commit-lifecycle-drift-surfaces-as-an-advisory-never-an-auto-fire-or-hard-gate-architecture-rule (advisory-only posture + binding rule) governance-skills-commit-their-own-completed-work-architecture-rule (hook detects,
+#      skill commits) hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule (budget) structured-user-interaction-for-governance-skill-decisions-architecture-rule (Rule 6 fail-open) behavioural-tests-default-for-skill-testing-architecture-rule (bats)
+# @problem fix-titled-commits-do-not-transition-the-ticket-lifecycle-in-the-same-commit-grain-ticket-stays-open-across-release-ci-verify-multiple-intervening-commits-problem  @rfc fix-title-lifecycle-drift-advisory-hook-release-design  @story fix-titled-commits-surface-a-lifecycle-drift-advisory-delivery-story
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
@@ -59,7 +59,7 @@ while IFS= read -r pid; do
   shopt -s nullglob; files=(./docs/problems/open/${num}-*.md); shopt -u nullglob
   if [ ${#files[@]} -gt 0 ]; then
     OPEN_COUNT=$((OPEN_COUNT + 1))
-    # Cap the named IDs at 3 so TOTAL emission stays ≤300 bytes (ADR-045).
+    # Cap the named IDs at 3 so TOTAL emission stays ≤300 bytes (hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule).
     if [ "$OPEN_COUNT" -le 3 ]; then
       OPEN_IDS="${OPEN_IDS:+$OPEN_IDS,}$pid"
     fi
@@ -68,5 +68,5 @@ done <<< "$PIDS"
 [ "$OPEN_COUNT" -gt 0 ] || exit 0
 [ "$OPEN_COUNT" -gt 3 ] && OPEN_IDS="${OPEN_IDS}+$((OPEN_COUNT - 3))"
 
-echo "P345 ADVISORY: fix-titled commit names ${OPEN_IDS} still Open — no paired lifecycle transition landed. Transition it (/wr-itil:transition-problem <NNN> known-error) or document why not. Bypass: BYPASS_FIX_TITLE_LIFECYCLE_ADVISORY=1." >&2
+echo "fix-titled-commits-do-not-transition-the-ticket-lifecycle-in-the-same-commit-grain-ticket-stays-open-across-release-ci-verify-multiple-intervening-commits-problem ADVISORY: fix-titled commit names ${OPEN_IDS} still Open — no paired lifecycle transition landed. Transition it (/wr-itil:transition-problem <NNN> known-error) or document why not. Bypass: BYPASS_FIX_TITLE_LIFECYCLE_ADVISORY=1." >&2
 exit 0

package/hooks/itil-mid-loop-ask-detect.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
-# P132 Phase 2b — wr-itil Stop hook.
+# agents-over-ask-in-interactive-sessions-conflating-mechanical-stages-with-user-interactive-stages-of-multi-stage-skill-contracts-inverse-problem Phase 2b — wr-itil Stop hook.
 #
 # Detects orchestrator main-turn `AskUserQuestion` calls fired mid-loop
-# inside `/wr-itil:work-problems` — the regression class P132 captures
+# inside `/wr-itil:work-problems` — the regression class agents-over-ask-in-interactive-sessions-conflating-mechanical-stages-with-user-interactive-stages-of-multi-stage-skill-contracts-inverse-problem captures
 # (2026-05-17 reopen evidence: orchestrator asked iter-target selection
 # between iters 3 and 4; halted the AFK loop for hours of user time).
 #
@@ -16,24 +16,24 @@
 #      is still mid-loop, not in its post-loop wrap-up).
 #
 # When all three match the hook emits a structured `stopReason`
-# advisory citing P130 + the Mid-loop ask discipline subsection of
+# advisory citing wr-itil-work-problems-orchestrator-defaults-to-subprocess-dispatch-even-when-the-user-is-observably-interactive-loses-real-time-presence-advantage-problem + the Mid-loop ask discipline subsection of
 # `packages/itil/skills/work-problems/SKILL.md`. Advisory ONLY — the
 # hook NEVER blocks. The next assistant turn reads the stopReason in
 # its context and self-corrects (queue the question to
 # outstanding_questions and continue iterating).
 #
 # Mirrors the sibling `itil-assistant-output-review.sh` Stop hook
-# precedent (P085 prose-ask detection) on transcript-extraction shape
+# precedent (problem-085-assistant-asks-for-input-when-the-next-step-is-obvious-and-uses-prose-asks-instead-of-askuserquestion-when-input-is-actually-needed-problem prose-ask detection) on transcript-extraction shape
 # and stopReason emit format.
 #
 # References:
-#   P132     — this hook (Phase 2b structural enforcement).
-#   P130     — orchestrator presence-aware dispatch; named in advisory.
-#   ADR-013  — Rule 1 (interactive default) + Rule 6 (AFK fail-safe).
-#   ADR-044  — framework-resolution boundary; named in advisory.
-#   ADR-045  — hook injection budget; advisory honour-system band.
-#   ADR-052  — behavioural tests default.
-#   ADR-005  — plugin testing strategy.
+#   agents-over-ask-in-interactive-sessions-conflating-mechanical-stages-with-user-interactive-stages-of-multi-stage-skill-contracts-inverse-problem     — this hook (Phase 2b structural enforcement).
+#   wr-itil-work-problems-orchestrator-defaults-to-subprocess-dispatch-even-when-the-user-is-observably-interactive-loses-real-time-presence-advantage-problem     — orchestrator presence-aware dispatch; named in advisory.
+#   structured-user-interaction-for-governance-skill-decisions-architecture-rule  — Rule 1 (interactive default) + Rule 6 (AFK fail-safe).
+#   decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule  — framework-resolution boundary; named in advisory.
+#   hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule  — hook injection budget; advisory honour-system band.
+#   behavioural-tests-default-for-skill-testing-architecture-rule  — behavioural tests default.
+#   plugin-testing-strategy-architecture-rule  — plugin testing strategy.
 
 # Per-surface configuration. Extending coverage to other orchestrators
 # (run-retro Step 4b Stage 1, /install-updates Step 6a) is a future
@@ -126,16 +126,16 @@ fi
 
 # All three signals present → emit advisory stopReason. The next
 # assistant turn reads this in its context and self-corrects.
-# Voice-tone target ~600 bytes; ADR-045 honour-system slack < 1000.
+# Voice-tone target ~600 bytes; hook-injection-budget-policy-for-pretooluse-and-posttooluse-hooks-architecture-rule honour-system slack < 1000.
 jq -n '{
   stopReason: (
     "MID-LOOP ASK DETECTED: AskUserQuestion fired inside /wr-itil:work-problems orchestrator main turn. " +
-    "Per P130 + Mid-loop ask discipline subsection of work-problems SKILL.md, mid-loop AskUserQuestion is " +
+    "Per wr-itil-work-problems-orchestrator-defaults-to-subprocess-dispatch-even-when-the-user-is-observably-interactive-loses-real-time-presence-advantage-problem + Mid-loop ask discipline subsection of work-problems SKILL.md, mid-loop AskUserQuestion is " +
     "forbidden except at framework-prescribed halt points (Step 0 session-continuity, Step 2.5/2.5b loop-end emit, " +
     "Step 6.5 above-appetite Rule 5 / CI failure, Step 6.75 dirty halt). " +
     "If at a halt point, this advisory is inapplicable. " +
     "If mid-loop, queue the question to outstanding_questions and continue iterating. " +
-    "See ADR-044 framework-resolution boundary."
+    "See decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule framework-resolution boundary."
   )
 }'