@windyroad/itil 0.23.1 → 0.23.2

package/.claude-plugin/plugin.json

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

package/bin/wr-itil-check-problems-readme-budget

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/check-problems-readme-budget.sh" "$@"

package/bin/wr-itil-reconcile-readme

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

package/hooks/hooks.json

@@ -23,6 +23,10 @@
       {
         "matcher": "Bash",
         "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-publish-intake-gate.sh" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/itil-changeset-discipline.sh" }]
       }
     ],
     "Stop": [

package/hooks/itil-changeset-discipline.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# P141: PreToolUse:Bash hook — denies `git commit` invocations whose
+# staged set includes `packages/<plugin>/` source files but no
+# `.changeset/*.md` is staged. Hook-level enforcement replaces the
+# unreliable iter-prompt-time changeset reminder (40% miss rate
+# observed in 2026-04-28 AFK loop session — see ticket).
+#
+# Detection delegates to `lib/changeset-detect.sh::detect_changeset_required`.
+# When the helper returns 1, this hook emits PreToolUse deny JSON
+# with the offending plugin slug inline and the literal `bun run
+# changeset` recovery command, satisfying ADR-013 Rule 1's "deny
+# redirects to a recovery path" contract via the mechanical-recovery
+# shape (no skill wrapper required — authoring a changeset 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 changeset-clean  (helper returns 0)
+#   - BYPASS_CHANGESET_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 `p057-staging-trap-detect.sh`).
+#   ADR-013 Rule 1 — deny redirects with mechanical recovery.
+#   ADR-014 — governance skills commit their own work (the hook keeps
+#             iter commits self-contained — no orchestrator-main-turn
+#             back-fill needed).
+#   ADR-018 — inter-iteration release cadence (the hook strengthens
+#             release-cadence integrity by ensuring every publishable
+#             iter has a changeset to drain).
+#   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).
+#   P073    — sibling changeset author-time gate (Write/Edit on
+#             `.changeset/*.md`); composes-with as defence-in-depth.
+#   P125    — sibling staging-trap hook (same enforcement-layer shape).
+#   P141    — this hook.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/changeset-detect.sh
+source "$SCRIPT_DIR/lib/changeset-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 plugin slug 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_SLUG=$(detect_changeset_required 2>/dev/null) && exit 0
+
+# Trap detected — emit deny with terse recovery.
+# Voice-tone budget per ADR-045 deny-band ≤300 bytes total. Names the
+# plugin slug, the literal recovery command (`bun run changeset`), the
+# BYPASS env var escape, and the P141 cite.
+REASON="BLOCKED: P141 changeset discipline. packages/${TRAPPED_SLUG}/ source needs .changeset/*.md. Recovery: bun run changeset. Bypass: BYPASS_CHANGESET_GATE=1."
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "${REASON}"
+  }
+}
+EOF
+exit 0

package/hooks/lib/changeset-detect.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# P141: shared changeset-discipline detection helper.
+#
+# `detect_changeset_required` returns 0 (no change required — allow) /
+# 1 (changeset required but not staged — caller should deny). On 1, the
+# offending plugin slug is echoed on stdout so callers can name it in
+# deny messages without re-parsing diff output.
+#
+# Trap shape (P141):
+#   `/wr-itil:work-problems` AFK iter subprocesses receive prompt-time
+#   guidance to author a `.changeset/*.md` whenever they ship a
+#   `packages/<plugin>/` change. Under context pressure (heavy SKILL.md
+#   + ticket body + architect/JTBD prompt content) the reminder is
+#   sometimes dropped — observed at 40% miss rate across 5 publishable
+#   iters in the 2026-04-28 evidence session. Hook-level detection at
+#   `git commit` time replaces the unreliable prompt-time signal.
+#
+# Detection logic:
+#   - `git diff --staged --name-only` enumerates staged paths.
+#   - Categorise each path:
+#       * `.changeset/<name>.md` (excluding `README.md`) — counts as
+#         a valid changeset.
+#       * `packages/<slug>/...` — examined further:
+#           - allow-list: `test/*`, `hooks/test/*`, `scripts/test/*`
+#             (test code; no publishable behaviour change).
+#           - allow-list: `README.md`.
+#           - allow-list: `docs/<anything>.md` (per architect verdict
+#             2026-05-02 — `*.md` under `docs/` only; SKILL.md is the
+#             publishable contract per ADR-037 framing and is NOT in
+#             the allow-list).
+#           - otherwise: publishable source — record the slug.
+#       * any other path: ignored (non-publishable surface — `.github/`,
+#         root config, top-level `docs/`, etc.).
+#   - If any path is publishable source AND no valid changeset is
+#     staged, return 1 + echo the slug.
+#
+# Bypass:
+#   - `BYPASS_CHANGESET_GATE=1` env var → return 0 (allow). For
+#     legitimate non-publishable commits (e.g. CI-only changes
+#     bundled with a small source tweak the agent has decided not
+#     to release). 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`'s exit-0 fallback —
+#     a hook that fails-closed on hostile environments would block
+#     legitimate commits in non-git contexts (e.g. agent-driven
+#     scripts that happen to mention `git commit` in unrelated
+#     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 the P125 `staging-detect.sh`
+# precedent (architect-approved no-marker design).
+#
+# References:
+#   ADR-005  — plugin testing strategy (hook bats live under
+#              `hooks/test/` per P081 behavioural-test discipline).
+#   ADR-013 Rule 1 — deny redirects with mechanical recovery (the deny
+#              text names the plugin slug + the literal `bun run
+#              changeset` command + the BYPASS env var override).
+#   ADR-014  — governance skills commit their own work (this hook
+#              ensures iter commits stay self-contained per
+#              ADR-014 single-commit grain).
+#   ADR-018  — inter-iteration release cadence (this hook strengthens
+#              the cadence by ensuring every publishable iter has a
+#              changeset to drain at release time).
+#   ADR-038  — progressive disclosure / deny-message terseness.
+#   ADR-045  — hook injection budget (Pattern 1 silent-on-pass; deny
+#              band ≤300 bytes for this hook).
+#   P073     — sibling changeset author-time gate (different surface:
+#              Write/Edit on `.changeset/*.md`). Composes-with as
+#              defence-in-depth.
+#   P125     — sibling staging-trap helper (same enforcement-layer
+#              shape — per-invocation deterministic, no markers).
+#   P141     — this helper.
+
+# Detect whether the current staged set requires a changeset that is
+# not staged.
+#
+# Echoes the offending plugin slug on stdout when detected.
+#
+# Returns:
+#   0 — no change required, or BYPASS env set, or fail-open (allow)
+#   1 — change required + no changeset staged (caller should deny)
+detect_changeset_required() {
+  # Bypass via env var — single most-common legitimate escape.
+  if [ "${BYPASS_CHANGESET_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_changeset=0
+  local plugin_source_slug=""
+  local path rest slug subpath
+
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+
+    case "$path" in
+      .changeset/README.md)
+        # README in changeset dir is meta-doc, not a real changeset.
+        ;;
+      .changeset/*.md)
+        has_changeset=1
+        ;;
+      packages/*)
+        rest="${path#packages/}"
+        slug="${rest%%/*}"
+        # When the path has no further segments (e.g. `packages/foo`),
+        # ${rest#*/} returns rest unchanged — defensive subpath fallback.
+        if [ "$rest" = "$slug" ]; then
+          subpath="$rest"
+        else
+          subpath="${rest#*/}"
+        fi
+
+        # Allow-list: test paths.
+        case "$subpath" in
+          test/*|hooks/test/*|scripts/test/*) continue ;;
+        esac
+
+        # Allow-list: package README.
+        case "$subpath" in
+          README.md) continue ;;
+        esac
+
+        # Allow-list: *.md under docs/ (any nesting depth).
+        case "$subpath" in
+          docs/*)
+            case "$subpath" in
+              *.md) continue ;;
+            esac
+            ;;
+        esac
+
+        # Anything else under packages/<slug>/ is publishable source.
+        plugin_source_slug="$slug"
+        ;;
+      *)
+        # Non-packages/ path: always allow.
+        ;;
+    esac
+  done <<EOF
+$staged
+EOF
+
+  if [ -n "$plugin_source_slug" ] && [ "$has_changeset" -eq 0 ]; then
+    printf '%s\n' "$plugin_source_slug"
+    return 1
+  fi
+
+  return 0
+}

package/hooks/test/itil-changeset-discipline.bats

@@ -0,0 +1,247 @@
+#!/usr/bin/env bats
+
+# P141: itil-changeset-discipline.sh PreToolUse:Bash hook must deny
+# `git commit` invocations whose staged set includes packages/<plugin>/
+# source files but no .changeset/*.md is staged. Hook-level enforcement
+# replaces unreliable iter-prompt-time changeset reminders (40% miss
+# rate observed in 2026-04-28 AFK loop session).
+#
+# Detection logic (per ticket Fix Strategy):
+#   On `git commit` invocations, run `git diff --staged --name-only`.
+#   If any path matches packages/<plugin>/<non-allow-listed> AND no
+#   .changeset/*.md (excluding README.md / config.json) is staged,
+#   emit a deny with recovery directive `bun run changeset` and the
+#   P141 cite. Allow when at least one valid changeset is staged, when
+#   staged packages/<plugin>/ files are entirely allow-listed (test
+#   paths or doc paths), or when BYPASS_CHANGESET_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-changeset-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 packages/itil/skills/foo packages/itil/hooks packages/itil/hooks/test \
+           packages/itil/hooks/lib packages/itil/scripts/test packages/itil/docs \
+           packages/itil/.claude-plugin .changeset .github/workflows docs
+  echo "seed" > seed.txt
+  git add seed.txt
+  git -c commit.gpgsign=false commit --quiet -m "initial"
+  unset BYPASS_CHANGESET_GATE
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  unset BYPASS_CHANGESET_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 P141 shape ---
+
+@test "deny: staged packages/<plugin>/ source without changeset triggers deny on git commit" {
+  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\""* ]]
+  [[ "$output" == *"P141"* ]]
+}
+
+@test "deny: staged packages/<plugin>/hooks/ shell source without changeset triggers deny" {
+  echo "#!/bin/bash" > packages/itil/hooks/new-hook.sh
+  git add packages/itil/hooks/new-hook.sh
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P141"* ]]
+}
+
+@test "deny: staged plugin.json without changeset triggers deny" {
+  echo "{}" > packages/itil/.claude-plugin/plugin.json
+  git add packages/itil/.claude-plugin/plugin.json
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny message names plugin slug, recovery command, P141 cite" {
+  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" == *"itil"* ]]
+  [[ "$output" == *"changeset"* ]]
+  [[ "$output" == *"P141"* ]]
+}
+
+@test "deny message stays under ADR-045 deny-band (<300 bytes)" {
+  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}" -lt 300 ]
+}
+
+# --- Allow paths: each non-trap shape must NOT deny ---
+
+@test "allow: staged packages/<plugin>/ source WITH a staged changeset allows the commit" {
+  echo "skill body" > packages/itil/skills/foo/SKILL.md
+  echo "---" > .changeset/wr-itil-p141.md
+  echo '"@windyroad/itil": patch' >> .changeset/wr-itil-p141.md
+  echo "---" >> .changeset/wr-itil-p141.md
+  echo "fix the thing" >> .changeset/wr-itil-p141.md
+  git add packages/itil/skills/foo/SKILL.md .changeset/wr-itil-p141.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged test-only changes under packages/<plugin>/hooks/test/ allow without changeset" {
+  echo "#!/usr/bin/env bats" > packages/itil/hooks/test/new-test.bats
+  git add packages/itil/hooks/test/new-test.bats
+  run run_bash_hook "git commit -m 'test'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged test-only changes under packages/<plugin>/scripts/test/ allow without changeset" {
+  echo "#!/usr/bin/env bats" > packages/itil/scripts/test/new-script-test.bats
+  git add packages/itil/scripts/test/new-script-test.bats
+  run run_bash_hook "git commit -m 'test'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged packages/<plugin>/README.md alone allows without changeset (doc-only)" {
+  echo "# itil" > packages/itil/README.md
+  git add packages/itil/README.md
+  run run_bash_hook "git commit -m 'docs'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged docs under packages/<plugin>/docs/ allow without changeset (doc-only)" {
+  echo "# guide" > packages/itil/docs/guide.md
+  git add packages/itil/docs/guide.md
+  run run_bash_hook "git commit -m 'docs'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny: staged SKILL.md (NOT in allow-list per architect amendment) triggers deny" {
+  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: staged .github/ workflow change without changeset (non-publishable path)" {
+  echo "name: ci" > .github/workflows/ci.yml
+  git add .github/workflows/ci.yml
+  run run_bash_hook "git commit -m 'ci'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: staged top-level docs/ change without changeset (non-publishable path)" {
+  echo "# briefing" > docs/BRIEFING.md
+  git add docs/BRIEFING.md
+  run run_bash_hook "git commit -m 'docs'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: BYPASS_CHANGESET_GATE=1 env var allows packages/<plugin>/ commit without changeset" {
+  echo "skill body" > packages/itil/skills/foo/SKILL.md
+  git add packages/itil/skills/foo/SKILL.md
+  BYPASS_CHANGESET_GATE=1 run run_bash_hook "git commit -m 'feat'"
+  [ "$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 "#!/usr/bin/env bats" > packages/itil/hooks/test/new-test.bats
+  git add packages/itil/hooks/test/new-test.bats
+  run run_bash_hook "git commit -m 'test'"
+  [ "$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 "skill body" > packages/itil/skills/foo/SKILL.md
+  git add packages/itil/skills/foo/SKILL.md
+  run run_bash_hook "git status"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# --- Changeset variants: README.md and config.json don't count as a real changeset ---
+
+@test "deny: staged .changeset/README.md alone does NOT count as a valid changeset" {
+  echo "skill body" > packages/itil/skills/foo/SKILL.md
+  echo "# changesets" > .changeset/README.md
+  git add packages/itil/skills/foo/SKILL.md .changeset/README.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# --- Mixed staged sets ---
+
+@test "deny: staged source + test in same commit still requires changeset (mixed set)" {
+  echo "skill body" > packages/itil/skills/foo/SKILL.md
+  echo "#!/usr/bin/env bats" > packages/itil/hooks/test/new-test.bats
+  git add packages/itil/skills/foo/SKILL.md packages/itil/hooks/test/new-test.bats
+  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\""* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/manage-problem/SKILL.md

@@ -186,9 +186,11 @@ What "work" means depends on the problem's status:
 Before parsing the request, run the diagnose-only reconciliation check. The contract here catches **cross-session drift** that per-operation refresh paths (P094 refresh-on-create + P062 refresh-on-transition) cannot retroactively see — if any past session committed a ticket change without staging the README refresh, the next manage-problem invocation reads a stale README that lies about what is open / verifying / closed.
 
 ```bash
-bash packages/itil/scripts/reconcile-readme.sh docs/problems
+wr-itil-reconcile-readme docs/problems
 ```
 
+The `wr-itil-reconcile-readme` command is a `$PATH`-resolved shim shipped in `packages/itil/bin/` that dispatches the canonical `packages/itil/scripts/reconcile-readme.sh` body. ADR-049 — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
 Exit-code routing:
 - **Exit 0 (clean)**: continue to Step 1.
 - **Exit 1 (drift detected)**: structured diff lines printed to stdout, one per drift entry (≤150 bytes per ADR-038 progressive-disclosure budget). **Halt this invocation** with a directive to invoke `/wr-itil:reconcile-readme` (interactive mode) or auto-route through the same skill in non-interactive mode (per ADR-013 Rule 6, AFK orchestrator). The reconciliation must complete and commit before this manage-problem invocation proceeds — proceeding into ticket creation / update / transition with a stale README would re-encode the drift into the post-operation refresh and propagate the lie.
@@ -462,7 +464,7 @@ The "Last reviewed" line (line 3 of `docs/problems/README.md`) was designed as a
 1. **Single most-recent fragment only on line 3.** The "Last reviewed" parenthetical names ONE event — the operation this refresh covers. Do NOT prepend a `Prior:` segment, do NOT stack multi-paragraph rationale, do NOT carry history forward inline.
 2. **Soft cap: ≤ 1024 bytes per fragment.** Authoring guidance — keep the fragment dense and audit-meaningful (ticket ID + verb + one-line summary + ADR/JTBD anchors when load-bearing). Multi-paragraph rationale belongs in retros, ticket bodies, and ADR amendments — never on line 3.
 3. **Archive sibling: `docs/problems/README-history.md`.** When this refresh would displace prior line-3 content, append the displaced content to `README-history.md` BEFORE writing the new line 3. Forward-chronology — newest fragment goes at the bottom under a date heading (`## YYYY-MM-DD`). The archive is a log; it's grep-and-tail territory, not display-tier (which is why its chronology diverges from the README's reverse-chrono surface convention).
-4. **Hard ceiling: 5120 bytes on line 3.** Matches ADR-040 Tier 3 envelope. Surfaced advisory-only by `packages/itil/scripts/check-problems-readme-budget.sh` — the script emits `OVER docs/problems/README.md line=3 bytes=<N> threshold=<N>` when the ceiling is breached. Always exits 0 (advisory; overflow is signal, not failure).
+4. **Hard ceiling: 5120 bytes on line 3.** Matches ADR-040 Tier 3 envelope. Surfaced advisory-only by `wr-itil-check-problems-readme-budget` (`$PATH`-resolved shim per ADR-049; canonical body at `packages/itil/scripts/check-problems-readme-budget.sh`) — the script emits `OVER docs/problems/README.md line=3 bytes=<N> threshold=<N>` when the ceiling is breached. Always exits 0 (advisory; overflow is signal, not failure).
 
 **Mechanism** (when authoring a refresh):
 
@@ -474,7 +476,7 @@ The "Last reviewed" line (line 3 of `docs/problems/README.md`) was designed as a
 
 **Fast-path interaction**: the Step 9 freshness check uses git-mtime on `docs/problems/README.md`, NOT the prose contents of line 3. Truncating line 3 does NOT degrade the fast-path contract.
 
-**Cross-references**: ADR-040 line 92 (reusable accumulator-doc pattern — explicitly names "problems index"), ADR-038 (progressive disclosure), ADR-014 (single-commit governance), `packages/itil/scripts/check-problems-readme-budget.sh`, `packages/itil/scripts/test/check-problems-readme-budget.bats`.
+**Cross-references**: ADR-040 line 92 (reusable accumulator-doc pattern — explicitly names "problems index"), ADR-038 (progressive disclosure), ADR-014 (single-commit governance), ADR-049 (plugin-bundled scripts via `bin/` on `$PATH`), `wr-itil-check-problems-readme-budget` shim (canonical body at `packages/itil/scripts/check-problems-readme-budget.sh`), `packages/itil/scripts/test/check-problems-readme-budget.bats`.
 
 ### 6. For updates: Edit the existing file
 

package/skills/reconcile-readme/SKILL.md

@@ -41,9 +41,11 @@ Three invocation surfaces, all routed through this skill so the agent-applied-ed
 Invoke the mechanical drift detector:
 
 ```bash
-bash packages/itil/scripts/reconcile-readme.sh docs/problems
+wr-itil-reconcile-readme docs/problems
 ```
 
+The `wr-itil-reconcile-readme` command is a `$PATH`-resolved shim shipped in `packages/itil/bin/` that dispatches the canonical `packages/itil/scripts/reconcile-readme.sh` body. ADR-049 — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
 Exit codes:
 - `0` — clean. No drift; nothing to do. Report "Reconciliation: clean (0 drift entries)" and exit.
 - `1` — drift detected. The script prints one structured row per drift entry to stdout (each ≤ 150 bytes per ADR-038 progressive-disclosure budget). Continue to Step 2.

package/skills/work-problems/SKILL.md

@@ -86,9 +86,11 @@ Step 6.75 treats a Step-0-resolved-with-user-confirmation state as `dirty-for-kn
 After the session-continuity detection pass, Step 0 MUST run the diagnose-only README reconciliation check. The orchestrator reads `docs/problems/README.md`'s WSJF Rankings table to pick the highest-WSJF actionable ticket (Step 3); if that table lies about which tickets are open vs verifying vs closed, the orchestrator burns iterations on no-op tickets — exactly the failure class P118 captures (a prior session committed a ticket transition without staging the README refresh, and no subsequent session systematically reconciled).
 
 ```bash
-bash packages/itil/scripts/reconcile-readme.sh docs/problems
+wr-itil-reconcile-readme docs/problems
 ```
 
+The `wr-itil-reconcile-readme` command is a `$PATH`-resolved shim shipped in `packages/itil/bin/` that dispatches the canonical `packages/itil/scripts/reconcile-readme.sh` body. ADR-049 — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
 Exit-code routing:
 - **Exit 0 (clean)**: continue to Step 1.
 - **Exit 1 (drift detected)**: structured diff lines printed to stdout, one per drift entry (≤150 bytes per ADR-038 progressive-disclosure budget). Per ADR-013 Rule 6 (non-interactive AFK fail-safe), invoke `/wr-itil:reconcile-readme` to apply the corrections + commit a `chore(problems): reconcile README ...` commit, then proceed to Step 1. The reconciled README is the orchestrator's source of truth for Step 3 ranking — a stale read at Step 1 would propagate the lie into the iteration's selection.