@windyroad/itil 0.27.1 → 0.28.0-preview.304

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/README.md

@@ -88,6 +88,14 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:report-upstream` | Report a local problem as a structured issue against an upstream repository (ADR-024) |
 | `/wr-itil:capture-rfc` | Lightweight RFC-capture skill — mandatory problem-trace per ADR-060 I1 invariant; opens a coordinated multi-commit change traceable to ≥ 1 driving problem (Phase 1 of the Problem-RFC-Story framework, P170 / ADR-060) |
 | `/wr-itil:manage-rfc` | Heavyweight RFC intake + lifecycle management — proposed → accepted → in-progress → verifying → closed; sibling to `manage-problem` at the RFC tier (ADR-060) |
+| `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) |
+| `/wr-itil:list-stories` | Read-only display of stories grouped by lifecycle state, with optional `--rfc RFC-<NNN>` filter rendering the RFC's ordered story list per ADR-060 line 259 (Phase 2 / P170) |
+| `/wr-itil:reconcile-stories` | Detect and correct drift between `docs/stories/README.md` and on-disk story inventory + reverse-trace `## Stories` sections on driving problems / RFCs / JTBDs (Phase 2 / P170) |
+| `/wr-itil:manage-story` | Heavyweight story lifecycle management — draft → accepted → in-progress → done → archived; I7+I8+I10 hard-block at accepted transition; INVEST 4-axis check; auto-transitions on `Refs: STORY-NNN` commit trailer + linked RFC closure (Phase 2 / P170) |
+| `/wr-itil:capture-story-map` | Lightweight story-map-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I3 + I4 invariants; HTML skeleton at `docs/story-maps/draft/STORY-MAP-NNN-<slug>.html` per ADR-060 § Phase 2 encoding amendment 2026-05-12 (Phase 2 / P170) |
+| `/wr-itil:manage-story-map` | Heavyweight story-map lifecycle management — draft → accepted → in-progress → completed → archived; backbone/ribs/slices authoring guidance; reverse-trace `## Story Maps` refresh on driving problems + JTBDs (Phase 2 / P170) |
+| `/wr-itil:reconcile-story-maps` | Detect and correct drift between `docs/story-maps/README.md` and on-disk story-map HTML inventory (Phase 2 / P170) |
+| `/wr-itil:list-story-maps` | Read-only display of story-maps grouped by lifecycle state; no WSJF (I5 invariant — maps are planning artefacts, not work items) (Phase 2 / P170) |
 | `/wr-itil:manage-incident` | Declare, triage, mitigate, and close an incident with evidence-first discipline |
 | `/wr-itil:list-incidents` | Read-only display of active incidents by severity |
 | `/wr-itil:mitigate-incident` / `/wr-itil:restore-incident` / `/wr-itil:close-incident` / `/wr-itil:link-incident` | Incident lifecycle transitions (ADR-011) |
@@ -108,7 +116,7 @@ This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](
 ### Solo developer
 
 - **[JTBD-006 Progress the Backlog While I'm Away](../../docs/jtbd/solo-developer/JTBD-006-work-backlog-afk.proposed.md)** — `/wr-itil:work-problems` is the AFK orchestrator that loops through the WSJF-ranked backlog, working tickets without interactive input until quota or a stop condition fires.
-- **[JTBD-008 Decompose a Fix Into Coordinated Changes](../../docs/jtbd/solo-developer/JTBD-008-decompose-fix-into-coordinated-changes.proposed.md)** — `/wr-itil:capture-rfc` + `/wr-itil:manage-rfc` are the capture-time decomposition surface for multi-commit coordinated changes traced to a driving problem; the I1 trace-to-problem invariant is gate-enforced at capture-rfc time (P170 / ADR-060).
+- **[JTBD-008 Decompose a Fix Into Coordinated Changes](../../docs/jtbd/solo-developer/JTBD-008-decompose-fix-into-coordinated-changes.proposed.md)** — `/wr-itil:capture-rfc` + `/wr-itil:manage-rfc` are the capture-time decomposition surface for multi-commit coordinated changes traced to a driving problem (Phase 1); `/wr-itil:capture-story` is the INVEST-shaped sub-workstream surface for individual slices under those coordinated changes (Phase 2 — story tier). The I1 trace-to-problem invariant is gate-enforced at capture-rfc time; I6 + I9 problem-and-JTBD-trace invariants are gate-enforced at capture-story time (P170 / ADR-060).
 
 ### Plugin user (currency anchor)
 

package/bin/wr-itil-reconcile-stories

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/reconcile-stories.sh" "$@"

package/bin/wr-itil-reconcile-story-maps

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/reconcile-story-maps.sh" "$@"

package/hooks/hooks.json

@@ -35,6 +35,10 @@
       {
         "matcher": "Bash",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-changeset-discipline.sh" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-readme-refresh-discipline.sh" }]
       }
     ],
     "PostToolUse": [

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

@@ -0,0 +1,118 @@
+#!/bin/bash
+# P165: 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
+# 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
+# the README, leaving README staleness for the next iter or
+# `/wr-itil:reconcile-readme` to recover.
+#
+# 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
+# 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):
+#   - tool_name != "Bash"               (only Bash invocations are gated)
+#   - command does not contain         `git commit` substring (non-commit
+#                                      Bash bypasses entirely)
+#   - staged set is README-discipline-  (helper returns 0)
+#     clean
+#   - BYPASS_README_REFRESH_GATE=1 env  (helper returns 0 first)
+#   - outside a git work tree           (helper fails-open)
+#   - 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
+#             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
+#             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.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/readme-refresh-detect.sh
+source "$SCRIPT_DIR/lib/readme-refresh-detect.sh"
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only gate Bash. Non-Bash tools bypass entirely.
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+COMMAND=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only fire on `git commit` invocations. Substring match catches common
+# shapes (`git commit -m`, `git commit --amend`, leading `cd && git
+# commit`, etc.) without over-matching unrelated bash.
+case "$COMMAND" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+
+# Run detection. Helper echoes offending ticket path on stdout when
+# detected; returns 1 in that case. Returns 0 (allow) on no-trap,
+# bypass env, or fail-open (non-git tree, parse error).
+TRAPPED_TICKET=$(detect_readme_refresh_required 2>/dev/null) && exit 0
+
+# 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
+# staged path for recovery; the deny only needs to name the ticket
+# distinctly.
+BASENAME="${TRAPPED_TICKET##*/}"
+TICKET_NUM="${BASENAME%%-*}"
+case "$TICKET_NUM" in
+  ''|*[!0-9]*) TICKET_ID="(staged ticket)" ;;
+  *) TICKET_ID="P${TICKET_NUM}" ;;
+esac
+
+# Trap detected — emit deny with terse recovery.
+# Voice-tone budget per ADR-045 deny-band ≤300 bytes total. Names the
+# offending ticket ID, the literal recovery command, the BYPASS env
+# var escape, and the P165 cite.
+REASON="BLOCKED: P165. ${TICKET_ID} needs docs/problems/README.md refresh. Run: git add docs/problems/README.md. Bypass: BYPASS_README_REFRESH_GATE=1."
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "${REASON}"
+  }
+}
+EOF
+exit 0

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

@@ -0,0 +1,161 @@
+#!/bin/bash
+# P165: shared README-refresh-discipline detection helper.
+#
+# `detect_readme_refresh_required` returns 0 (no change required —
+# allow) / 1 (ticket change staged but README refresh not staged —
+# caller should deny). On 1, the offending ticket file path is echoed
+# on stdout so callers can name it in deny messages without re-parsing
+# diff output.
+#
+# Trap shape (P165):
+#   `manage-problem` SKILL.md Step 5 (P094) and Step 7 (P062) say every
+#   ticket creation, ranking-bearing update, and status transition MUST
+#   stage the refreshed `docs/problems/README.md` in the same commit as
+#   the ticket change (ADR-014 single-commit grain). The contract is
+#   declarative; iter subprocess commits have shipped `.verifying.md`
+#   renames or Status edits without the README refresh (observed iter
+#   3 commit d28bd51 — P156 row missing from VQ until iter 4 backfill).
+#   Hook-level detection at `git commit` time replaces the declarative-
+#   only enforcement.
+#
+# Detection logic:
+#   - `git diff --staged --name-only` enumerates staged paths.
+#   - Categorise each path:
+#       * `docs/problems/(open|verifying|closed|known-error|parked)/NNN-*.md`
+#         (new state-directory layout per ADR-031) — counts as a
+#         ticket-state-transition surface; records the path.
+#       * `docs/problems/NNN-*.(open|verifying|closed|known-error|parked).md`
+#         (legacy flat layout) — also counts; supports adopter repos
+#         and any residual flat-layout tickets.
+#       * `docs/problems/README.md` — counts as a README refresh.
+#       * `docs/problems/README-history.md` — ignored (rotated history
+#         per P134; not a ticket file, not the load-bearing README).
+#       * Anything else — ignored (non-ticket surface; the gate has no
+#         opinion on retros, ADRs, source, etc.).
+#   - If any ticket path is recorded AND README is NOT staged, return
+#     1 + echo the first offending ticket path.
+#
+# Bypass:
+#   - `BYPASS_README_REFRESH_GATE=1` env var → return 0 (allow). For
+#     legitimate narrative-only ticket-body edits that don't change
+#     ranking-bearing fields. Audit-traceable via shell history.
+#
+# Fail-open contract:
+#   - Outside a git working tree, or when `git diff` fails for any
+#     reason (parse error, broken index, permissions), return 0
+#     (allow). Mirrors `lib/staging-detect.sh` + `lib/changeset-detect.sh`
+#     fail-open precedent — a hook that fails-closed on hostile
+#     environments would block legitimate commits in non-git contexts.
+#
+# Cost: one `git diff` invocation per check (~10ms on this repo's
+# working tree). Per-invocation deterministic — runs on every
+# `git commit` invocation rather than relying on per-tool-call session
+# state tracking. Mirrors P125 `staging-detect.sh` + P141
+# `changeset-detect.sh` precedent (architect-approved no-marker design
+# per ADR-009 carve-out).
+#
+# References:
+#   ADR-005  — plugin testing strategy (hook bats live under
+#              `hooks/test/` per P081 behavioural-test discipline).
+#   ADR-009  — gate marker lifecycle (this helper deliberately does
+#              NOT use markers; detection is per-invocation
+#              deterministic, not per-session trust window — same
+#              precedent as P125 / P141).
+#   ADR-013 Rule 1 — deny redirects with mechanical recovery (the deny
+#              text names the offending ticket path + the literal
+#              `git add docs/problems/README.md` recovery command +
+#              the BYPASS env var override).
+#   ADR-014  — single-commit grain (this hook enforces it for the
+#              ticket-state-transition surface).
+#   ADR-022  — `.verifying.md` lifecycle status (one of the surface
+#              shapes the hook detects).
+#   ADR-031  — per-state-subdir problem ticket layout (the new layout
+#              the hook detects).
+#   ADR-038  — progressive disclosure / deny-message terseness.
+#   ADR-045  — hook injection budget (Pattern 1 silent-on-pass; deny
+#              band ≤300 bytes for this hook).
+#   P062     — parent (README refresh on transition contract — manage-
+#              problem Step 7).
+#   P094     — parent (README refresh on creation contract — manage-
+#              problem Step 5).
+#   P118     — sibling reconcile-readme recovery path (the after-the-
+#              fact rescue this hook obviates).
+#   P125     — sibling staging-trap helper (same enforcement-layer
+#              shape — per-invocation deterministic, no markers).
+#   P141     — sibling changeset-discipline helper (same shape).
+#   P165     — this helper.
+
+# Detect whether the current staged set requires a README refresh that
+# is not staged.
+#
+# Echoes the offending ticket path on stdout when detected.
+#
+# Returns:
+#   0 — no change required, or BYPASS env set, or fail-open (allow)
+#   1 — ticket change staged + README not staged (caller should deny)
+detect_readme_refresh_required() {
+  # Bypass via env var — single most-common legitimate escape.
+  if [ "${BYPASS_README_REFRESH_GATE:-}" = "1" ]; then
+    return 0
+  fi
+
+  # Fail-open if not inside a git working tree.
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+
+  local staged
+  staged=$(git diff --staged --name-only 2>/dev/null) || return 0
+
+  # No staged paths — nothing to gate.
+  [ -n "$staged" ] || return 0
+
+  local has_readme=0
+  local offending_ticket=""
+  local path basename
+
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+
+    case "$path" in
+      docs/problems/README.md)
+        has_readme=1
+        ;;
+      docs/problems/README-history.md)
+        # Rotated history file — not a ticket, not the load-bearing
+        # README. Ignored.
+        ;;
+      docs/problems/open/*.md \
+      | docs/problems/verifying/*.md \
+      | docs/problems/closed/*.md \
+      | docs/problems/known-error/*.md \
+      | docs/problems/parked/*.md)
+        # New state-directory layout (ADR-031). Filename must start
+        # with digits to be a ticket file — exclude any future
+        # state-directory-local README or similar.
+        basename="${path##*/}"
+        case "$basename" in
+          [0-9]*.md)
+            [ -z "$offending_ticket" ] && offending_ticket="$path"
+            ;;
+        esac
+        ;;
+      docs/problems/[0-9]*.md)
+        # Legacy flat layout: docs/problems/NNN-*.<state>.md.
+        # Excludes README.md and README-history.md (already cased
+        # above; both start with `R`, not a digit).
+        [ -z "$offending_ticket" ] && offending_ticket="$path"
+        ;;
+      *)
+        # Non-ticket surface: ignored.
+        ;;
+    esac
+  done <<EOF
+$staged
+EOF
+
+  if [ -n "$offending_ticket" ] && [ "$has_readme" -eq 0 ]; then
+    printf '%s\n' "$offending_ticket"
+    return 1
+  fi
+
+  return 0
+}

package/hooks/test/itil-readme-refresh-discipline.bats

@@ -0,0 +1,261 @@
+#!/usr/bin/env bats
+
+# P165: itil-readme-refresh-discipline.sh PreToolUse:Bash hook must deny
+# `git commit` invocations whose staged set includes any
+# docs/problems/<state>/NNN-*.md (or legacy docs/problems/NNN-*.md) but
+# does NOT also stage docs/problems/README.md. Hook-level enforcement
+# closes the P094/P062 README-refresh enforcement gap — iter subprocess
+# commits could previously ship a `.verifying.md` rename or Status edit
+# without the corresponding Verification Queue / WSJF Rankings row in
+# the README.
+#
+# Detection logic (per ticket Fix Strategy + architect verdict):
+#   On `git commit` invocations, run `git diff --staged --name-only`.
+#   If any path matches docs/problems/(open|verifying|closed|known-error|parked)/NNN-*.md
+#   OR docs/problems/NNN-*.<state>.md (legacy flat layout) AND
+#   docs/problems/README.md is NOT staged, emit a deny with recovery
+#   directive `git add docs/problems/README.md` and the P165 cite.
+#   Allow when README is staged alongside, when no ticket file is
+#   staged at all (README-only / retro-only / ADR-only / source-only
+#   commits), or when BYPASS_README_REFRESH_GATE=1 is set.
+#
+# Per ADR-005 (plugin testing strategy) — hook bats live under
+# packages/<plugin>/hooks/test/ and assert behaviour on emitted JSON,
+# not source content. Per P081 — no source-grep on hook text. Simulate
+# the PreToolUse:Bash payload on stdin and assert on the emitted
+# permissionDecision.
+#
+# Per ADR-045 Pattern 1 (silent-on-pass) — allow paths emit 0 bytes.
+# Per ADR-045 deny-band — deny messages target ~245 bytes; cap at 300.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/itil-readme-refresh-discipline.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  git init --quiet -b main
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  mkdir -p docs/problems/open docs/problems/verifying docs/problems/closed \
+           docs/problems/known-error docs/problems/parked docs/retros \
+           docs/decisions packages/itil/skills/foo .changeset
+  echo "seed" > seed.txt
+  git add seed.txt
+  git -c commit.gpgsign=false commit --quiet -m "initial"
+  # README must exist for the "stage it alongside" tests to work.
+  echo "# Problem Backlog" > docs/problems/README.md
+  git add docs/problems/README.md
+  git -c commit.gpgsign=false commit --quiet -m "seed readme"
+  unset BYPASS_README_REFRESH_GATE
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  unset BYPASS_README_REFRESH_GATE
+}
+
+run_bash_hook() {
+  local cmd="$1"
+  local json
+  json=$(printf '{"tool_name":"Bash","tool_input":{"command":"%s"}}' "$cmd")
+  echo "$json" | bash "$HOOK"
+}
+
+# --- Trap detection: the canonical P165 shape ---
+
+@test "deny: staged docs/problems/open/NNN-*.md without README refresh triggers deny on git commit" {
+  echo "# Problem 999" > docs/problems/open/999-some-new-ticket.md
+  git add docs/problems/open/999-some-new-ticket.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P165"* ]]
+}
+
+@test "deny: staged docs/problems/verifying/NNN-*.md without README refresh triggers deny" {
+  echo "# Problem 999 verifying" > docs/problems/verifying/999-some-ticket.md
+  git add docs/problems/verifying/999-some-ticket.md
+  run run_bash_hook "git commit -m 'fix'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P165"* ]]
+}
+
+@test "deny: staged docs/problems/closed/NNN-*.md without README refresh triggers deny" {
+  echo "# Problem 999 closed" > docs/problems/closed/999-some-ticket.md
+  git add docs/problems/closed/999-some-ticket.md
+  run run_bash_hook "git commit -m 'close'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny: staged docs/problems/known-error/NNN-*.md without README refresh triggers deny" {
+  echo "# Problem 999 known error" > docs/problems/known-error/999-some-ticket.md
+  git add docs/problems/known-error/999-some-ticket.md
+  run run_bash_hook "git commit -m 'transition'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny: staged docs/problems/parked/NNN-*.md without README refresh triggers deny" {
+  echo "# Problem 999 parked" > docs/problems/parked/999-some-ticket.md
+  git add docs/problems/parked/999-some-ticket.md
+  run run_bash_hook "git commit -m 'park'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny: staged legacy flat-layout docs/problems/NNN-*.<state>.md without README triggers deny" {
+  echo "# Problem 999 flat" > docs/problems/999-some-legacy.open.md
+  git add docs/problems/999-some-legacy.open.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny message names offending ticket ID, recovery command, P165 cite" {
+  echo "# Problem 999" > docs/problems/open/999-some-new-ticket.md
+  git add docs/problems/open/999-some-new-ticket.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  # Deny names the ticket as `P<NNN>` (not full path — see hook
+  # comment: full descriptive ticket slugs exceed ADR-045 deny-band).
+  [[ "$output" == *"P999"* ]]
+  [[ "$output" == *"docs/problems/README.md"* ]]
+  [[ "$output" == *"P165"* ]]
+}
+
+@test "deny message stays under ADR-045 deny-band (<300 bytes)" {
+  echo "# Problem 999" > docs/problems/open/999-some-ticket.md
+  git add docs/problems/open/999-some-ticket.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -lt 300 ]
+}
+
+# --- Allow paths: each non-trap shape must NOT deny ---
+
+@test "allow: staged ticket file WITH docs/problems/README.md allows the commit" {
+  echo "# Problem 999" > docs/problems/open/999-new.md
+  echo "# Problem Backlog updated" > docs/problems/README.md
+  git add docs/problems/open/999-new.md docs/problems/README.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: README-only commit (reconcile-readme path) allows without ticket change" {
+  echo "# Problem Backlog reconciled" > docs/problems/README.md
+  git add docs/problems/README.md
+  run run_bash_hook "git commit -m 'docs: reconcile readme'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: retro-only commit allows without ticket change or README refresh" {
+  echo "# Retro 2026-05-11" > docs/retros/2026-05-11-iter.md
+  git add docs/retros/2026-05-11-iter.md
+  run run_bash_hook "git commit -m 'docs(retros): iter'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: ADR-only commit allows without ticket change or README refresh" {
+  echo "# ADR 999" > docs/decisions/999-some-decision.proposed.md
+  git add docs/decisions/999-some-decision.proposed.md
+  run run_bash_hook "git commit -m 'docs(decisions): adr-999'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: source-only commit (packages/) allows without ticket change or README refresh" {
+  echo "skill body" > packages/itil/skills/foo/SKILL.md
+  git add packages/itil/skills/foo/SKILL.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: BYPASS_README_REFRESH_GATE=1 env var allows ticket commit without README refresh" {
+  echo "# Problem 999" > docs/problems/open/999-bypass.md
+  git add docs/problems/open/999-bypass.md
+  BYPASS_README_REFRESH_GATE=1 run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: docs/problems/README-history.md edit alone does NOT trigger deny (not a ticket file)" {
+  echo "# History" > docs/problems/README-history.md
+  git add docs/problems/README-history.md
+  run run_bash_hook "git commit -m 'docs: rotate history'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# --- Allow path silence (ADR-045 Pattern 1) ---
+
+@test "allow path emits 0 bytes (ADR-045 Pattern 1 silent-on-pass)" {
+  echo "# Retro" > docs/retros/2026-05-11-iter.md
+  git add docs/retros/2026-05-11-iter.md
+  run run_bash_hook "git commit -m 'docs'"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -eq 0 ]
+}
+
+# --- Tool-name and command-shape filters ---
+
+@test "allow: non-Bash tool exits 0 without deny" {
+  run bash -c "echo '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"foo.md\"}}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: Bash command that is NOT git commit (e.g., git status) bypasses detection" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git status"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# --- Mixed staged sets ---
+
+@test "deny: staged ticket + ADR (no README) still triggers deny (mixed surface dominance)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  echo "# ADR 999" > docs/decisions/999-x.proposed.md
+  git add docs/problems/open/999-x.md docs/decisions/999-x.proposed.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged ticket + ADR + README allows (mixed set with README)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  echo "# ADR 999" > docs/decisions/999-x.proposed.md
+  echo "# Problem Backlog updated" > docs/problems/README.md
+  git add docs/problems/open/999-x.md docs/decisions/999-x.proposed.md docs/problems/README.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# --- Parse / fail-open contracts ---
+
+@test "allow: empty JSON exits 0 without deny (fail-open on parse-incomplete)" {
+  run bash -c "echo '{}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: outside a git work tree exits 0 without deny (fail-open)" {
+  cd "$ORIG_DIR"
+  TEMP_NONGIT=$(mktemp -d)
+  cd "$TEMP_NONGIT"
+  run run_bash_hook "git commit -m 'feat'"
+  cd "$TEST_DIR"
+  rm -rf "$TEMP_NONGIT"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}