@windyroad/itil 0.35.15 → 0.35.16-preview.426

package/.claude-plugin/plugin.json

@@ -484,5 +484,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.35.15"
+  "version": "0.35.16"
 }

package/bin/wr-itil-check-upstream-cache-staleness

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical run-check-upstream-cache-staleness script.
+exec "$(dirname "$0")/../scripts/run-check-upstream-cache-staleness.sh" "$@"

package/bin/wr-itil-mark-create-gate

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical mark-create-gate script.
+exec "$(dirname "$0")/../scripts/mark-create-gate.sh" "$@"

package/bin/wr-itil-mark-rfc-capture-gate

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical mark-rfc-capture-gate script.
+exec "$(dirname "$0")/../scripts/mark-rfc-capture-gate.sh" "$@"

package/bin/wr-itil-migrate-problems-layout

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical run-migrate-problems-layout script.
+exec "$(dirname "$0")/../scripts/run-migrate-problems-layout.sh" "$@"

package/bin/wr-itil-update-jtbd-references-section

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical update-jtbd-references-section script.
+exec "$(dirname "$0")/../scripts/update-jtbd-references-section.sh" "$@"

package/bin/wr-itil-update-problem-references-section

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical update-problem-references-section script.
+exec "$(dirname "$0")/../scripts/update-problem-references-section.sh" "$@"

package/bin/wr-itil-update-problem-rfcs-section

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical update-problem-rfcs-section script.
+exec "$(dirname "$0")/../scripts/update-problem-rfcs-section.sh" "$@"

package/bin/wr-itil-update-rfc-references-section

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# ADR-049 $PATH shim — dispatches to the canonical update-rfc-references-section script.
+exec "$(dirname "$0")/../scripts/update-rfc-references-section.sh" "$@"

package/hooks/lib/runtime-sid.sh

@@ -44,8 +44,9 @@
 
 # Echoes the runtime-SID marker path on stdout. Always exits 0.
 #
-# Usage:
-#   source packages/itil/hooks/lib/runtime-sid.sh
+# Usage (resolve relative to the caller's own location — NEVER repo-relative
+# `packages/...`, which only exists in the source monorepo; P317/RFC-009):
+#   source "$(dirname "${BASH_SOURCE[0]}")/runtime-sid.sh"
 #   path=$(runtime_sid_path)
 runtime_sid_path() {
   if [ -n "${SESSION_MARKER_DIR:-}" ]; then

package/hooks/lib/session-id.sh

@@ -57,8 +57,9 @@
 # Returns the canonical session UUID for the current invocation.
 # Echoes the UUID on stdout. Exit 0 if discovered, 1 if not.
 #
-# Usage:
-#   source packages/itil/hooks/lib/session-id.sh
+# Usage (resolve relative to the caller's own location — NEVER repo-relative
+# `packages/...`, which only exists in the source monorepo; P317/RFC-009):
+#   source "$(dirname "${BASH_SOURCE[0]}")/session-id.sh"   # or ../hooks/lib/ from a scripts/ wrapper
 #   sid=$(get_current_session_id) || { echo "no SID available" >&2; exit 1; }
 get_current_session_id() {
   # Env-var fast path. CLAUDE_SESSION_ID is not exported in agent
@@ -203,9 +204,10 @@ get_current_session_id() {
 # Test overrides: SESSION_MARKER_DIR (marker dir, default /tmp) +
 # SESSION_CANDIDATE_WINDOW_MINS (window minutes, default 1440).
 #
-# Usage:
-#   source packages/itil/hooks/lib/session-id.sh
-#   source packages/itil/hooks/lib/create-gate.sh
+# Usage — SKILLs call the `wr-itil-mark-create-gate` command (it does the
+# source+pipe internally, adopter-safe); direct callers resolve the libs relative
+# to their OWN location, NEVER repo-relative `packages/...` (P317/RFC-009):
+#   LIB="$(dirname "${BASH_SOURCE[0]}")"; source "$LIB/session-id.sh"; source "$LIB/create-gate.sh"
 #   get_candidate_session_ids | mark_step2_complete_candidates
 get_candidate_session_ids() {
   local marker_dir="${SESSION_MARKER_DIR:-/tmp}"

package/package.json

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

package/scripts/mark-create-gate.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# wr-itil — write the problem-tier create-gate marker (P119) under every
+# candidate session SID (P260 / ADR-050 Option C).
+#
+# Internalises the source+pipe that capture-problem / manage-problem Step 2
+# previously ran INLINE with repo-relative `source packages/itil/hooks/lib/*.sh`
+# — which only resolved in the source monorepo and broke in adopter installs
+# (P317 / RFC-009). This script resolves its sibling libs RELATIVE TO ITS OWN
+# LOCATION (`$(dirname)/../hooks/lib`), so it works wherever the plugin is
+# installed. SKILLs invoke it by name via the `wr-itil-mark-create-gate` PATH
+# shim (ADR-049) instead of sourcing repo-relative lib files.
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../hooks/lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-mark-create-gate: cannot locate hooks/lib next to the script" >&2
+  exit 2
+}
+
+# shellcheck source=/dev/null
+source "$LIB/session-id.sh"
+# shellcheck source=/dev/null
+source "$LIB/create-gate.sh"
+
+# Writes /tmp/manage-problem-grep-<SID> under each recent candidate SID; returns
+# non-zero only if no candidate SID was discoverable (fail-closed parity).
+get_candidate_session_ids | mark_step2_complete_candidates

package/scripts/mark-rfc-capture-gate.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# wr-itil — write the RFC-tier create-gate marker (P119) under every candidate
+# session SID (P260 / ADR-050 Option C). Adopter-safe sibling of
+# wr-itil-mark-create-gate (P317 / RFC-009): resolves its libs relative to the
+# script location, not cwd. SKILLs (capture-rfc / manage-rfc) invoke it by name
+# via the `wr-itil-mark-rfc-capture-gate` PATH shim (ADR-049) before writing a
+# docs/rfcs/RFC-*.proposed.md file.
+#
+# The RFC tier has no `_candidates` helper in create-gate.sh (only the single
+# `mark_rfc_capture_complete`), so this script loops the candidate set itself —
+# the RFC-tier analogue of `mark_step2_complete_candidates`.
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../hooks/lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-mark-rfc-capture-gate: cannot locate hooks/lib next to the script" >&2
+  exit 2
+}
+
+# shellcheck source=/dev/null
+source "$LIB/session-id.sh"
+# shellcheck source=/dev/null
+source "$LIB/create-gate.sh"
+
+count=0
+while IFS= read -r sid; do
+  [ -n "$sid" ] || continue
+  mark_rfc_capture_complete "$sid"
+  count=$((count + 1))
+done < <(get_candidate_session_ids)
+
+# Fail-closed parity with mark_step2_complete_candidates: non-zero if no SID.
+[ "$count" -gt 0 ]

package/scripts/run-check-upstream-cache-staleness.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# wr-itil — echo the inbound-discovery-preflight promotion reason, or empty if
+# promotion is not warranted (P317/RFC-009).
+#
+# Adopter-safe wrapper: sources the canonical lib RELATIVE TO THIS SCRIPT
+# (`$(dirname)/../lib`), then echoes the function's result on stdout (the SKILL
+# captures it via `$(...)`). Replaces the SKILL-inline
+# `source packages/itil/lib/check-upstream-cache-staleness.sh;
+#  preflight_reason="$(should_promote_inbound_discovery_preflight "$PWD")"`,
+# which only resolved in the source monorepo (P317). SKILLs invoke this by name
+# via the `wr-itil-check-upstream-cache-staleness` PATH shim (ADR-049).
+# Operates on the directory given as $1 (defaults to $PWD).
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-check-upstream-cache-staleness: cannot locate lib next to the script" >&2
+  exit 2
+}
+# shellcheck source=/dev/null
+source "$LIB/check-upstream-cache-staleness.sh"
+should_promote_inbound_discovery_preflight "${1:-$PWD}"

package/scripts/run-migrate-problems-layout.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# wr-itil — run the problems-layout flat→per-state migration (P317/RFC-009).
+#
+# Adopter-safe wrapper: sources the canonical lib RELATIVE TO THIS SCRIPT
+# (`$(dirname)/../lib`), then invokes the function. Replaces the SKILL-inline
+# `source packages/itil/lib/migrate-problems-layout.sh; migrate_... "$PWD"`,
+# which only resolved in the source monorepo (P317). SKILLs invoke this by name
+# via the `wr-itil-migrate-problems-layout` PATH shim (ADR-049). The migration
+# routine is idempotent + partial-migration-safe (no-op when no flat-layout
+# files exist). Operates on the directory given as $1 (defaults to $PWD).
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-migrate-problems-layout: cannot locate lib next to the script" >&2
+  exit 2
+}
+# shellcheck source=/dev/null
+source "$LIB/migrate-problems-layout.sh"
+migrate_problems_to_per_state_layout "${1:-$PWD}"

package/scripts/test/kind-a-commands.bats

@@ -0,0 +1,46 @@
+#!/usr/bin/env bats
+# P317 / RFC-009 T2 + ADR-049: the KIND A wrapper commands resolve their
+# canonical lib RELATIVE TO THE SCRIPT (`$(dirname)/../lib`), so they work in an
+# adopter install — not just the source monorepo where `source packages/...`
+# happened to resolve. Behavioural: simulate an install tree, invoke from a
+# FOREIGN cwd, assert clean lib resolution.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  INSTALL="$(mktemp -d)"
+  mkdir -p "$INSTALL/scripts" "$INSTALL/lib" "$INSTALL/bin"
+  cp "$REPO_ROOT/packages/itil/scripts/run-migrate-problems-layout.sh" "$INSTALL/scripts/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/scripts/run-check-upstream-cache-staleness.sh" "$INSTALL/scripts/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/bin/wr-itil-migrate-problems-layout" "$INSTALL/bin/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/bin/wr-itil-check-upstream-cache-staleness" "$INSTALL/bin/" 2>/dev/null || true
+  cp "$REPO_ROOT"/packages/itil/lib/*.sh "$INSTALL/lib/" 2>/dev/null || true
+  FOREIGN="$(mktemp -d)"   # adopter repo cwd — no packages/ tree
+}
+
+teardown() {
+  rm -rf "$INSTALL" "$FOREIGN"
+}
+
+@test "wr-itil-migrate-problems-layout resolves its lib from a foreign cwd, no-ops on empty dir (P317)" {
+  cd "$FOREIGN"
+  run bash "$INSTALL/bin/wr-itil-migrate-problems-layout" "$FOREIGN"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No such file"* ]]
+  [[ "$output" != *"command not found"* ]]
+}
+
+@test "wr-itil-check-upstream-cache-staleness resolves its lib from a foreign cwd (P317)" {
+  cd "$FOREIGN"
+  run bash "$INSTALL/bin/wr-itil-check-upstream-cache-staleness" "$FOREIGN"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No such file"* ]]
+  [[ "$output" != *"command not found"* ]]
+  [[ "$output" != *"migrate_problems_to_per_state_layout: command not found"* ]]
+}
+
+@test "the direct script (not just the shim) also resolves its lib from a foreign cwd (P317)" {
+  cd "$FOREIGN"
+  run bash "$INSTALL/scripts/run-migrate-problems-layout.sh" "$FOREIGN"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No such file"* ]]
+}

package/scripts/test/mark-create-gate.bats

@@ -0,0 +1,59 @@
+#!/usr/bin/env bats
+# P317 / RFC-009 T1 + ADR-049: the create-gate marker commands resolve their
+# sibling libs RELATIVE TO THE SCRIPT (adopter-safe), not relative to cwd. The
+# bug they fix: SKILLs did `source packages/itil/hooks/lib/*.sh`, which only
+# resolves in the source monorepo and breaks in adopter installs.
+#
+# Behavioural — simulates an adopter install by copying the shipped script +
+# lib tree to a temp dir in the SAME relative layout, then invokes from a
+# FOREIGN cwd (an "adopter repo" with no packages/ tree) and asserts success.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  INSTALL="$(mktemp -d)"
+  mkdir -p "$INSTALL/scripts" "$INSTALL/hooks/lib" "$INSTALL/bin"
+  cp "$REPO_ROOT/packages/itil/scripts/mark-create-gate.sh" "$INSTALL/scripts/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/scripts/mark-rfc-capture-gate.sh" "$INSTALL/scripts/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/bin/wr-itil-mark-create-gate" "$INSTALL/bin/" 2>/dev/null || true
+  cp "$REPO_ROOT/packages/itil/bin/wr-itil-mark-rfc-capture-gate" "$INSTALL/bin/" 2>/dev/null || true
+  cp "$REPO_ROOT"/packages/itil/hooks/lib/*.sh "$INSTALL/hooks/lib/" 2>/dev/null || true
+  FOREIGN="$(mktemp -d)"   # an adopter repo cwd — no packages/ tree
+  MARKERS="$(mktemp -d)"   # empty announce-marker dir so candidates = CLAUDE_SESSION_ID only
+  SID="p317-test-$$-${RANDOM}"
+}
+
+teardown() {
+  rm -rf "$INSTALL" "$FOREIGN" "$MARKERS"
+  rm -f "/tmp/manage-problem-grep-$SID" "/tmp/wr-itil-rfc-capture-grep-$SID"
+}
+
+@test "mark-create-gate.sh runs from a foreign cwd, resolving libs from its own location (P317)" {
+  cd "$FOREIGN"
+  run env CLAUDE_SESSION_ID="$SID" SESSION_MARKER_DIR="$MARKERS" bash "$INSTALL/scripts/mark-create-gate.sh"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No such file"* ]]
+  [[ "$output" != *"command not found"* ]]
+  [ -f "/tmp/manage-problem-grep-$SID" ]
+}
+
+@test "wr-itil-mark-create-gate shim dispatches the script from a foreign cwd (P317/ADR-049)" {
+  cd "$FOREIGN"
+  run env CLAUDE_SESSION_ID="$SID" SESSION_MARKER_DIR="$MARKERS" bash "$INSTALL/bin/wr-itil-mark-create-gate"
+  [ "$status" -eq 0 ]
+  [ -f "/tmp/manage-problem-grep-$SID" ]
+}
+
+@test "mark-rfc-capture-gate.sh writes the RFC-tier marker from a foreign cwd (P317)" {
+  cd "$FOREIGN"
+  run env CLAUDE_SESSION_ID="$SID" SESSION_MARKER_DIR="$MARKERS" bash "$INSTALL/scripts/mark-rfc-capture-gate.sh"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"No such file"* ]]
+  [ -f "/tmp/wr-itil-rfc-capture-grep-$SID" ]
+}
+
+@test "wr-itil-mark-rfc-capture-gate shim dispatches from a foreign cwd (P317/ADR-049)" {
+  cd "$FOREIGN"
+  run env CLAUDE_SESSION_ID="$SID" SESSION_MARKER_DIR="$MARKERS" bash "$INSTALL/bin/wr-itil-mark-rfc-capture-gate"
+  [ "$status" -eq 0 ]
+  [ -f "/tmp/wr-itil-rfc-capture-grep-$SID" ]
+}

package/scripts/test/rfc-stories-extension.bats

@@ -168,6 +168,6 @@ EOF
   # in the SKILL body. Behavioural assertion on the presence of the
   # load-bearing call path; without it, manage-rfc transitions would
   # silently leave the body section stale.
-  run grep -E 'update-rfc-references-section\.sh.*Stories' "$MANAGE_RFC"
+  run grep -E 'wr-itil-update-rfc-references-section.*Stories' "$MANAGE_RFC"
   [ "$status" -eq 0 ]
 }

package/skills/capture-problem/SKILL.md

@@ -156,12 +156,12 @@ If matches are found: list them in the final report. **Do NOT halt or branch.**
 **After the grep completes**, write the per-session create-gate marker so the `PreToolUse:Write` hook (P119) permits the subsequent Write of the new `.open.md` file. Per **P260 / ADR-050 Option C**, write it under EVERY recent candidate session SID (not just one) so a concurrent orchestrator+subprocess race cannot land the marker under the wrong UUID:
 
 ```bash
-source packages/itil/hooks/lib/session-id.sh
-source packages/itil/hooks/lib/create-gate.sh
-get_candidate_session_ids | mark_step2_complete_candidates
+wr-itil-mark-create-gate
 ```
 
-The marker is shared between `manage-problem` and `capture-problem` per ADR-032 amendment — same `/tmp/manage-problem-grep-${SESSION_ID}` path, idempotent across cross-skill ordering. `get_candidate_session_ids` enumerates the `get_current_session_id` pick (P124) plus every recent `/tmp/<system>-announced-<UUID>` UUID within a 24h mtime window, and `mark_step2_complete_candidates` writes the marker under each — so whichever SID the hook reads from the Write's stdin, a matching marker exists. This closes the P260 create-gate race that fires when the orchestrator main turn captures a ticket while a backgrounded iter subprocess holds the per-machine runtime-sid marker (last-writer-wins). The candidate set is bounded to recent same-machine markers — not a global fail-open (the P119 audit invariant holds: each marker still records that THIS session ran the duplicate-check grep). See `/wr-itil:manage-problem` Step 2 substep 7 for the full mechanism.
+`wr-itil-mark-create-gate` is the ADR-049 `$PATH` shim that internalises the former inline `source packages/itil/hooks/lib/{session-id,create-gate}.sh` + `get_candidate_session_ids | mark_step2_complete_candidates`. It resolves those `hooks/lib` siblings RELATIVE TO THE SCRIPT, not cwd (P317/RFC-009) — so it works in adopter installs. NEVER `source packages/...` repo-relative from a SKILL; those paths only resolve in the source monorepo, not where the plugin is installed.
+
+The marker is shared between `manage-problem` and `capture-problem` per ADR-032 amendment — same `/tmp/manage-problem-grep-${SESSION_ID}` path, idempotent across cross-skill ordering. Internally the command enumerates the `get_current_session_id` pick (P124) plus every recent `/tmp/<system>-announced-<UUID>` UUID within a 24h mtime window, and writes the marker under each — so whichever SID the hook reads from the Write's stdin, a matching marker exists. This closes the P260 create-gate race that fires when the orchestrator main turn captures a ticket while a backgrounded iter subprocess holds the per-machine runtime-sid marker (last-writer-wins). The candidate set is bounded to recent same-machine markers — not a global fail-open (the P119 audit invariant holds: each marker still records that THIS session ran the duplicate-check grep). See `/wr-itil:manage-problem` Step 2 substep 7 for the full mechanism.
 
 ### 3. Compute the next ID
 

package/skills/capture-rfc/SKILL.md

@@ -135,6 +135,14 @@ For each resolved trace file, classify by suffix:
 
 **Why advisory and not hard-block at capture-time**: the bounded-escape contract in ADR-060 § Confirmation criterion 2 scopes I1 hard-block to `accepted → in-progress` and `→ verifying` lifecycle transitions; advisory-with-escalation only fires at `→ closed` transition. Capture-time tolerance for Closed/Parked traces is **load-bearing for the Phase 1 dogfood pass**: RFC-001 retro on P168 (P168 is `.verifying.md`) is structurally impossible without it. This is NOT a relaxation of I1; it is the bounded-escape window the ADR carved out at the right lifecycle phase. See ADR-060 § Confirmation criterion 5 (no semantic loss) + Phase 1 item 9 (retro migration as dogfood pass).
 
+**After the trace validation passes**, write the RFC-tier create-gate marker so the `PreToolUse:Write` hook (P119, `manage-problem-enforce-create.sh`) permits the Step 5 Write of the new `docs/rfcs/RFC-*.proposed.md` file:
+
+```bash
+wr-itil-mark-rfc-capture-gate
+```
+
+`wr-itil-mark-rfc-capture-gate` is the ADR-049 `$PATH` shim (adopter-safe — resolves its `hooks/lib` siblings relative to the script, NOT cwd; P317/RFC-009) that writes `/tmp/wr-itil-rfc-capture-grep-${SESSION_ID}` under every recent candidate SID (P260 / ADR-050 Option C — same candidate-set discipline as `wr-itil-mark-create-gate`). NEVER `source packages/...` repo-relative from a SKILL — those paths only resolve in the source monorepo, not adopter installs. The marker is per-session and idempotent, so a single write covers multiple RFC creations this session (e.g. a multi-problem-trace split).
+
 ### 3. Compute next RFC ID
 
 Same `max(local, origin) + 1` formula as `capture-problem` Step 3, scanning `docs/rfcs/RFC-*.md` instead:
@@ -218,7 +226,7 @@ for pid_token in $(echo "$problem_trace" | tr ',' ' '); do
   # Dual-tolerant ticket discovery (RFC-002 migration window).
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-rfcs-section.sh" "$problem_file" docs/rfcs
+  wr-itil-update-problem-rfcs-section "$problem_file" docs/rfcs
   git add "$problem_file"
 done
 ```
@@ -229,7 +237,7 @@ The helper (`packages/itil/scripts/update-problem-rfcs-section.sh`) is idempoten
 
 ```bash
 if [ -n "$stories_trace" ]; then
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "docs/rfcs/RFC-${next}-${slug}.proposed.md" "Stories"
+  wr-itil-update-rfc-references-section "docs/rfcs/RFC-${next}-${slug}.proposed.md" "Stories"
 fi
 ```
 

package/skills/capture-story/SKILL.md

@@ -260,7 +260,7 @@ for pid_token in $(echo "$problem_trace" | tr ',' ' '); do
   # Dual-tolerant ticket discovery (RFC-002 migration window).
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Stories"
+  wr-itil-update-problem-references-section "$problem_file" "Stories"
   git add "$problem_file"
 done
 ```
@@ -272,7 +272,7 @@ for jid_token in $(echo "$jtbd_trace" | tr ',' ' '); do
   jid_num="${jid_token#JTBD-}"
   jtbd_file=$(ls docs/jtbd/*/JTBD-${jid_num}-*.md 2>/dev/null | head -1)
   [ -z "$jtbd_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-jtbd-references-section.sh" "$jtbd_file" "Stories"
+  wr-itil-update-jtbd-references-section "$jtbd_file" "Stories"
   git add "$jtbd_file"
 done
 ```
@@ -284,7 +284,7 @@ for rid_token in $(echo "$rfc_trace" | tr ',' ' '); do
   [ -z "$rid_token" ] && continue
   rfc_file=$(ls docs/rfcs/${rid_token}-*.md 2>/dev/null | head -1)
   [ -z "$rfc_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+  wr-itil-update-rfc-references-section "$rfc_file" "Stories"
   git add "$rfc_file"
 done
 ```

package/skills/capture-story-map/SKILL.md

@@ -170,14 +170,14 @@ for pid_token in $(echo "$problem_trace" | tr ',' ' '); do
   pid_num="${pid_token#P}"
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Story Maps"
+  wr-itil-update-problem-references-section "$problem_file" "Story Maps"
   git add "$problem_file"
 done
 
 for jid_token in $(echo "$jtbd_trace" | tr ',' ' '); do
   jtbd_file=$(ls docs/jtbd/*/${jid_token}-*.md 2>/dev/null | head -1)
   [ -z "$jtbd_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-jtbd-references-section.sh" "$jtbd_file" "Story Maps"
+  wr-itil-update-jtbd-references-section "$jtbd_file" "Story Maps"
   git add "$jtbd_file"
 done
 

package/skills/manage-problem/SKILL.md

@@ -212,12 +212,11 @@ The Phase 2 working-the-problem traversal makes "implement the fix" concretely t
 Before the README-reconciliation preflight (Step 0) and any other layout-dependent logic, source the shared shell migration routine and call the idempotent entrypoint:
 
 ```bash
-# Source the synced copy from this package's lib/ (canonical lives at
-# packages/shared/lib/migrate-problems-layout.sh per ADR-017 sync pattern).
-source packages/itil/lib/migrate-problems-layout.sh
-migrate_problems_to_per_state_layout "$PWD"
+wr-itil-migrate-problems-layout "$PWD"
 ```
 
+`wr-itil-migrate-problems-layout` is the ADR-049 `$PATH` shim (adopter-safe — resolves the canonical `lib/migrate-problems-layout.sh` relative to the script, NOT cwd; P317/RFC-009) that internalises the former inline `source packages/itil/lib/migrate-problems-layout.sh; migrate_problems_to_per_state_layout "$PWD"`. NEVER `source packages/...` repo-relative from a SKILL — those paths only resolve in the source monorepo, not adopter installs.
+
 The routine is **idempotent and partial-migration-safe**. It no-ops when no flat-layout files (`docs/problems/*.<state>.md` at the top level of `docs/problems/`) are detected — the common case in this monorepo (post-Slice-5 T5a 2026-05-10) and in freshly-migrated adopter repos.
 
 On a flat-layout adopter repo (first invocation post-update — JTBD-101 plugin-developer auto-migration path), the routine:
@@ -337,12 +336,12 @@ Before creating, search existing problems for similar issues. The user may not k
 7. **After the grep completes** (whether duplicates were found or not), write the per-session create-gate marker so the `PreToolUse:Write` hook (`packages/itil/hooks/manage-problem-enforce-create.sh`, P119) allows the subsequent Write of the new `.open.md` file. The marker is `/tmp/manage-problem-grep-${SESSION_ID}`. Per **P260 / ADR-050 Option C**, the agent writes it under EVERY recent candidate session SID — not just one — by sourcing the discovery helpers (P124) and piping the candidate set into `mark_step2_complete_candidates`:
 
    ```bash
-   source packages/itil/hooks/lib/session-id.sh
-   source packages/itil/hooks/lib/create-gate.sh
-   get_candidate_session_ids | mark_step2_complete_candidates
+   wr-itil-mark-create-gate
    ```
 
-   **Why every candidate, not one (P260 / ADR-050 Option C)**: under `/wr-itil:work-problems` the orchestrator main turn fires PreToolUse hooks concurrently with its backgrounded iter subprocess (Step 5). Both sessions write the same per-machine runtime-sid marker (last-writer-wins), so the single-SID `get_current_session_id` can return the subprocess SID while the orchestrator's Write carries the orchestrator SID on its stdin — marker mismatch, create-gate deny. No agent-side algorithm can predict the right single SID from filesystem state alone (ADR-050 §Context). `get_candidate_session_ids` instead enumerates EVERY candidate SID the hook might read — the `get_current_session_id` pick (env-var > runtime-sid > announce-marker priority, P124) PLUS every recent `/tmp/<system>-announced-<UUID>` UUID within a 24h mtime window (ADR-038 announce markers, set on prompt 1 of every session by architect / jtbd / tdd / style-guide / voice-tone / itil-assistant-gate / itil-correction-detect hooks) — and `mark_step2_complete_candidates` writes the marker under each. Whichever SID the hook reads from the Write's stdin, a matching marker provably exists. The candidate set is **bounded** to recent same-machine announce markers + the runtime-sid value — NOT a global fail-open: the P119 audit invariant holds (every marker still records that THIS session ran the duplicate-check grep). The marker is per-session, so a single write covers all new tickets for the rest of this session, enabling Step 4b multi-concern splits and same-session unrelated-ticket creation without re-running the grep.
+   `wr-itil-mark-create-gate` is the ADR-049 `$PATH` shim (adopter-safe — resolves its `hooks/lib` siblings relative to the script, NOT cwd; P317/RFC-009) that internalises the former inline `source packages/itil/hooks/lib/{session-id,create-gate}.sh` + `get_candidate_session_ids | mark_step2_complete_candidates`. NEVER `source packages/...` repo-relative from a SKILL — those paths only resolve in the source monorepo, not adopter installs.
+
+   **Why every candidate, not one (P260 / ADR-050 Option C)**: under `/wr-itil:work-problems` the orchestrator main turn fires PreToolUse hooks concurrently with its backgrounded iter subprocess (Step 5). Both sessions write the same per-machine runtime-sid marker (last-writer-wins), so the single-SID `get_current_session_id` can return the subprocess SID while the orchestrator's Write carries the orchestrator SID on its stdin — marker mismatch, create-gate deny. No agent-side algorithm can predict the right single SID from filesystem state alone (ADR-050 §Context). The command instead enumerates EVERY candidate SID the hook might read — the `get_current_session_id` pick (env-var > runtime-sid > announce-marker priority, P124) PLUS every recent `/tmp/<system>-announced-<UUID>` UUID within a 24h mtime window (ADR-038 announce markers, set on prompt 1 of every session by architect / jtbd / tdd / style-guide / voice-tone / itil-assistant-gate / itil-correction-detect hooks) — and writes the marker under each. Whichever SID the hook reads from the Write's stdin, a matching marker provably exists. The candidate set is **bounded** to recent same-machine announce markers + the runtime-sid value — NOT a global fail-open: the P119 audit invariant holds (every marker still records that THIS session ran the duplicate-check grep). The marker is per-session, so a single write covers all new tickets for the rest of this session, enabling Step 4b multi-concern splits and same-session unrelated-ticket creation without re-running the grep.
 
    **Why helpers instead of inline `${CLAUDE_SESSION_ID:-default}`**: the agent's process does NOT export `CLAUDE_SESSION_ID` today; the hook side reads `session_id` from its stdin JSON payload (per the Claude Code PreToolUse contract). The prior fallback wrote the marker under `default` while the hook checked the real UUID — mismatch caused the Write deny on every first ticket of a session until the agent ad-hoc scraped a UUID-bearing marker. The helpers canonicalise that scrape so every agent context discovers candidate SIDs the same way. P124.
 

package/skills/manage-rfc/SKILL.md

@@ -147,7 +147,7 @@ for pid_token in $(awk '/^problems:/{gsub(/[][]/,"");gsub(/,/,"\n");for(i=2;i<=N
   # subdir (`docs/problems/<state>/<NNN>-<title>.md`) layouts.
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-rfcs-section.sh" "$problem_file" docs/rfcs
+  wr-itil-update-problem-rfcs-section "$problem_file" docs/rfcs
   git add "$problem_file"
 done
 ```
@@ -164,7 +164,7 @@ The trailer hook (`itil-rfc-trailer-advisory.sh`) sits on top of this skill-side
 Per ADR-060 line 270 + line 296: every transition that touches the RFC body refreshes the RFC's own `## Stories` body section from its frontmatter `stories:` array. The forward-trace surface renders the ordered execution sequence as inline links to the story files, lazy-empty when `stories: []` (an RFC not decomposed into stories). The helper is the Slice 2b sibling `update-rfc-references-section.sh`:
 
 ```bash
-bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+wr-itil-update-rfc-references-section "$rfc_file" "Stories"
 ```
 
 Idempotent + lazy-empty per the Slice 2a/2b contract. Run after the rename + frontmatter edit so the section reflects the post-transition `stories:` shape. Stage the RFC file (already staged for the lifecycle transition; the helper modifies the same file in-place).
@@ -197,7 +197,7 @@ Batch re-rank all RFCs and refresh `docs/rfcs/README.md`.
 ```bash
 # Aggregate the union of P<NNN> across all RFCs touched in this review.
 for problem_file in $(printf '%s\n' "${touched_problem_files[@]}" | sort -u); do
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-rfcs-section.sh" "$problem_file" docs/rfcs
+  wr-itil-update-problem-rfcs-section "$problem_file" docs/rfcs
   git add "$problem_file"
 done
 ```

package/skills/manage-story/SKILL.md

@@ -138,7 +138,7 @@ for pid_token in $(awk '/^problems:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=
   pid_num="${pid_token#P}"
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Stories"
+  wr-itil-update-problem-references-section "$problem_file" "Stories"
   git add "$problem_file"
 done
 
@@ -146,7 +146,7 @@ done
 for jid in $(awk '/^jtbd:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$story_file"); do
   jtbd_file=$(ls docs/jtbd/*/${jid}-*.md 2>/dev/null | head -1)
   [ -z "$jtbd_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-jtbd-references-section.sh" "$jtbd_file" "Stories"
+  wr-itil-update-jtbd-references-section "$jtbd_file" "Stories"
   git add "$jtbd_file"
 done
 
@@ -154,7 +154,7 @@ done
 for rid in $(awk '/^rfcs:/{gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$story_file"); do
   rfc_file=$(ls docs/rfcs/${rid}-*.md 2>/dev/null | head -1)
   [ -z "$rfc_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+  wr-itil-update-rfc-references-section "$rfc_file" "Stories"
   git add "$rfc_file"
 done
 

package/skills/manage-story-map/SKILL.md

@@ -104,11 +104,11 @@ for pid_token in $(grep -oE '<meta name="problems" content="[^"]*"' "$map_file"
   pid_num="${pid_token#P}"
   problem_file=$(ls docs/problems/${pid_num}-*.md docs/problems/*/${pid_num}-*.md 2>/dev/null | head -1)
   [ -z "$problem_file" ] && continue
-  bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Story Maps"
+  wr-itil-update-problem-references-section "$problem_file" "Story Maps"
   git add "$problem_file"
 done
 
-# Same for JTBDs via update-jtbd-references-section.sh "Story Maps"
+# Same for JTBDs via wr-itil-update-jtbd-references-section "Story Maps"
 ```
 
 Per architect amend finding 2 on Slice 7: story-map HTML files do NOT carry an auto-maintained markdown reverse-trace section themselves (the `<a class="slice">` data-attribute traces are authored manually during backbone design). No reverse-trace refresh on the map itself; reverse-trace only flows OUT to problem + JTBD parents.

package/skills/manage-story-map/test/manage-story-map-contract.bats

@@ -43,12 +43,12 @@ setup() {
 }
 
 @test "manage-story-map: SKILL.md names reverse-trace refresh on problem parents via Story Maps section" {
-  run grep -E 'update-problem-references-section\.sh.*Story Maps' "$SKILL_FILE"
+  run grep -E 'wr-itil-update-problem-references-section.*Story Maps' "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
 
 @test "manage-story-map: SKILL.md names reverse-trace refresh on JTBD parents via Story Maps section" {
-  run grep -E 'update-jtbd-references-section\.sh.*Story Maps' "$SKILL_FILE"
+  run grep -E 'wr-itil-update-jtbd-references-section.*Story Maps' "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
 

package/skills/reconcile-stories/SKILL.md

@@ -56,11 +56,11 @@ For reverse-trace drift entries — invoke the appropriate Slice 2a/2b helper fo
 
 ```bash
 # Problem parent
-bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-problem-references-section.sh" "$problem_file" "Stories"
+wr-itil-update-problem-references-section "$problem_file" "Stories"
 # RFC parent
-bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-rfc-references-section.sh" "$rfc_file" "Stories"
+wr-itil-update-rfc-references-section "$rfc_file" "Stories"
 # JTBD parent
-bash "$(wr-itil-script-path 2>/dev/null || echo packages/itil/scripts)/update-jtbd-references-section.sh" "$jtbd_file" "Stories"
+wr-itil-update-jtbd-references-section "$jtbd_file" "Stories"
 ```
 
 ### 4. Verify + commit

package/skills/work-problems/SKILL.md

@@ -127,10 +127,11 @@ This is a robustness layer ON TOP of P094 + P062, not a supersession — both pe
 After Step 0's fetch/divergence preflight and the README reconciliation block but **before** Step 1's backlog scan, source the shared shell migration routine and call the idempotent entrypoint:
 
 ```bash
-source packages/itil/lib/migrate-problems-layout.sh
-migrate_problems_to_per_state_layout "$PWD"
+wr-itil-migrate-problems-layout "$PWD"
 ```
 
+`wr-itil-migrate-problems-layout` is the ADR-049 `$PATH` shim (adopter-safe — resolves `lib/migrate-problems-layout.sh` relative to the script, NOT cwd; P317/RFC-009) that internalises the former inline `source packages/itil/lib/migrate-problems-layout.sh; migrate_problems_to_per_state_layout "$PWD"`. NEVER `source packages/...` repo-relative from a SKILL — those paths only resolve in the source monorepo, not adopter installs.
+
 The routine is **idempotent and partial-migration-safe**. It no-ops when no flat-layout files (`docs/problems/*.<state>.md` at the top level of `docs/problems/`) are detected — the common case post-Slice-5 T5a in this monorepo and in freshly-migrated adopter repos.
 
 **Closes the Step 1 false-zero defect** (per ADR-031 § Backward Compatibility line 126 "Why both skills"): Step 1 enumerates BEFORE delegating to manage-problem. On a flat-layout adopter repo, the post-ADR-031 Step 1 glob would return zero matches at the per-state shape and stop-condition #1 would fire incorrectly — the orchestrator would exit with a false "nothing to do" signal, never reaching manage-problem's Step 0a auto-migrate. Wiring auto-migrate here at Step 0a is structurally required, not an optimisation.
@@ -154,10 +155,11 @@ After Step 0a's auto-migrate and before Step 1's backlog scan, check whether the
 **Mechanism:**
 
 ```bash
-source packages/itil/lib/check-upstream-cache-staleness.sh
-preflight_reason="$(should_promote_inbound_discovery_preflight "$PWD")"
+preflight_reason="$(wr-itil-check-upstream-cache-staleness "$PWD")"
 ```
 
+`wr-itil-check-upstream-cache-staleness` is the ADR-049 `$PATH` shim (adopter-safe — resolves `lib/check-upstream-cache-staleness.sh` relative to the script, NOT cwd; P317/RFC-009) that internalises the former inline `source ...; should_promote_inbound_discovery_preflight "$PWD"` and echoes the result. NEVER `source packages/...` repo-relative from a SKILL — those paths only resolve in the source monorepo, not adopter installs.
+
 The helper returns one of five outcomes (contract documented at `packages/itil/lib/check-upstream-cache-staleness.sh` + asserted by `packages/itil/skills/work-problems/test/work-problems-step-0b-cache-staleness-behavioural.bats`):
 
 | `preflight_reason`                | Action                                                                                                |