@windyroad/itil 0.54.1 → 0.54.2-preview.786

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.54.1"
+  "version": "0.54.2"
 }

package/bin/wr-itil-resolve-governance-plugin-dirs

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/resolve-governance-plugin-dirs.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/resolve-governance-plugin-dirs.sh" "$@"

package/package.json

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

package/scripts/resolve-governance-plugin-dirs.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Resolve --plugin-dir arguments for the governance plugins an AFK iter
+# subprocess needs.
+#
+# P382: headless `claude -p` loads only USER-scoped enabledPlugins, NOT
+# project-scoped ones. When the windyroad plugins are enabled at project scope
+# (the common adopter setup), an iter subprocess dispatched by work-problems
+# Step 5 receives no windyroad agents/hooks — it commits ungated and cannot run
+# retro-on-exit. `--setting-sources user,project` is insufficient (project
+# activation is trust-gated; headless skips trust). Passing `--plugin-dir
+# <plugin-root>` for each governance plugin DOES make it available. This script
+# emits those `--plugin-dir` argument pairs for the Step 5 dispatch to splice
+# into its `claude -p` invocation.
+#
+# Resolution: each plugin's cache parent is located from its bin dir on $PATH
+# (ADR-049 bin-on-PATH precedent — present in adopter marketplace-cache trees
+# and source-dev alike), then the HIGHEST-SEMVER sibling under that cache parent
+# is selected (ADR-080 highest-version-wins). $PATH order is frozen at session
+# init and goes stale mid-session (P343 / ADR-080 / ADR-081), so it MUST NOT be
+# trusted for version selection — only to discover the cache parent.
+#
+# Output: two lines per resolvable plugin — `--plugin-dir` then the plugin root
+# dir — for `mapfile -t` consumption (one token per line tolerates paths with
+# spaces). Unresolvable plugins are skipped silently: graceful degradation when
+# an adopter has not installed the full governance surface. (This is a
+# deliberate divergence from the canonical shim's loud exit-127 — a missing
+# governance plugin must not abort the whole AFK orchestrator dispatch.)
+#
+# Override the plugin set via WR_GOVERNANCE_PLUGINS (space-separated).
+#
+# @adr ADR-032 (governance skill invocation — Step 5 dispatch contract, P382 amendment)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH)
+# @adr ADR-080 (highest-version-wins resolution — $PATH order is not authoritative)
+# @adr ADR-052 (behavioural test — resolve-governance-plugin-dirs.bats)
+# @problem P382
+set -euo pipefail
+
+PLUGINS="${WR_GOVERNANCE_PLUGINS:-wr-architect wr-jtbd wr-risk-scorer wr-voice-tone wr-itil wr-retrospective wr-style-guide}"
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+IFS=':' read -r -a path_entries <<< "$PATH"
+
+for plugin in $PLUGINS; do
+  # Discover this plugin's cache parent from any of its bin dirs on $PATH.
+  # A bin entry has the shape <cache_parent>/<version>/bin.
+  cache_parent=""
+  for entry in "${path_entries[@]}"; do
+    case "$entry" in
+      */"$plugin"/*/bin)
+        cache_parent="$(dirname "$(dirname "$entry")")"
+        break
+        ;;
+    esac
+  done
+  [ -n "$cache_parent" ] || continue
+
+  # Select the highest-semver sibling under <cache_parent> (ADR-080). PATH order
+  # may name a stale version after a mid-session /install-updates, so re-resolve
+  # the version here rather than reading it from the PATH entry.
+  highest=""
+  while IFS= read -r dir; do
+    name="$(basename "$dir")"
+    [[ "$name" =~ $SEMVER_RE ]] || continue
+    if [ -z "$highest" ] || [ "$(printf '%s\n%s\n' "$highest" "$name" | sort -V | tail -1)" = "$name" ]; then
+      highest="$name"
+    fi
+  done < <(find "$cache_parent" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+  [ -n "$highest" ] || continue
+  printf '%s\n%s\n' "--plugin-dir" "$cache_parent/$highest"
+done

package/scripts/test/resolve-governance-plugin-dirs.bats

@@ -0,0 +1,78 @@
+#!/usr/bin/env bats
+
+# @problem P382 — AFK work-problems `claude -p` iter subprocesses load only
+#                 USER-scoped enabledPlugins; project-scoped governance plugins
+#                 must be passed explicitly via --plugin-dir. This helper emits
+#                 the --plugin-dir argument pairs the Step 5 dispatch splices
+#                 into its claude -p invocation.
+#
+# Contract: `resolve-governance-plugin-dirs.sh` reads $PATH + WR_GOVERNANCE_PLUGINS
+# and emits, per resolvable plugin, two stdout lines — `--plugin-dir` then the
+# plugin root dir — for `mapfile -t` consumption.
+#
+# Load-bearing behaviour (ADR-080): the version is selected by HIGHEST-SEMVER
+# walk of the cache parent, NOT by $PATH order (which is frozen-stale
+# mid-session per P343). The fixture deliberately places a LOWER version's bin
+# earlier on $PATH and asserts the HIGHER version's dir is still emitted.
+#
+# @adr ADR-049 (bin/ on PATH shim — adopter-safe script resolution)
+# @adr ADR-080 (highest-version-wins resolution)
+# @adr ADR-052 (behavioural test per P081)
+# @adr ADR-032 (Step 5 dispatch contract — P382 amendment)
+# @jtbd JTBD-001 (Enforce Governance — iter commits ship gated)
+# @jtbd JTBD-006 (Progress Backlog AFK — full governance surface inside iters)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/resolve-governance-plugin-dirs.sh"
+  CACHE="$(mktemp -d)"
+  # Synthetic marketplace-cache layout (ADR-080 SQ-080-5 — no source-repo
+  # cohabitation). wr-architect has two cached versions; wr-itil has one.
+  mkdir -p "$CACHE/windyroad/wr-architect/0.16.0/bin"
+  mkdir -p "$CACHE/windyroad/wr-architect/0.17.3/bin"
+  mkdir -p "$CACHE/windyroad/wr-itil/0.51.0/bin"
+}
+
+teardown() {
+  rm -rf "$CACHE"
+}
+
+@test "resolve-governance-plugin-dirs: script exists and is executable" {
+  [ -f "$SCRIPT" ]
+  [ -x "$SCRIPT" ]
+}
+
+@test "resolve-governance-plugin-dirs: emits --plugin-dir pairs for resolvable plugins" {
+  PATH="$CACHE/windyroad/wr-architect/0.17.3/bin:$CACHE/windyroad/wr-itil/0.51.0/bin:/usr/bin:/bin" \
+    WR_GOVERNANCE_PLUGINS="wr-architect wr-itil" run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ "${lines[0]}" = "--plugin-dir" ]
+  [ "${lines[1]}" = "$CACHE/windyroad/wr-architect/0.17.3" ]
+  [ "${lines[2]}" = "--plugin-dir" ]
+  [ "${lines[3]}" = "$CACHE/windyroad/wr-itil/0.51.0" ]
+}
+
+@test "resolve-governance-plugin-dirs: picks highest semver, NOT \$PATH order (ADR-080)" {
+  # Lower version (0.16.0) earlier on PATH than higher (0.17.3) — the resolver
+  # must still emit 0.17.3 (cache-parent highest-semver walk, not PATH order).
+  PATH="$CACHE/windyroad/wr-architect/0.16.0/bin:$CACHE/windyroad/wr-architect/0.17.3/bin:/usr/bin:/bin" \
+    WR_GOVERNANCE_PLUGINS="wr-architect" run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ "${lines[0]}" = "--plugin-dir" ]
+  [ "${lines[1]}" = "$CACHE/windyroad/wr-architect/0.17.3" ]
+}
+
+@test "resolve-governance-plugin-dirs: skips unresolvable plugins silently" {
+  PATH="$CACHE/windyroad/wr-itil/0.51.0/bin:/usr/bin:/bin" \
+    WR_GOVERNANCE_PLUGINS="wr-architect wr-itil wr-not-installed" run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  # Only wr-itil is on PATH → exactly one pair, no wr-architect / wr-not-installed.
+  [ "${#lines[@]}" -eq 2 ]
+  [ "${lines[1]}" = "$CACHE/windyroad/wr-itil/0.51.0" ]
+}
+
+@test "resolve-governance-plugin-dirs: no governance plugins on PATH → empty output, exit 0" {
+  PATH="/usr/bin:/bin" WR_GOVERNANCE_PLUGINS="wr-architect wr-itil" run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/skills/work-problems/SKILL.md

@@ -538,9 +538,22 @@ export WR_SUPPRESS_PENDING_QUESTIONS=1
 # pending-questions guard above (JTBD-006 friction guard).
 export WR_SUPPRESS_OVERSIGHT_NUDGE=1
 
+# Project-scoped governance plugins are NOT loaded by headless `claude -p`
+# (P382): it activates only USER-scoped enabledPlugins, and project activation
+# is trust-gated (headless skips trust), so `--setting-sources user,project`
+# alone does not attach them. Without this, the iter subprocess has no
+# windyroad architect/jtbd/risk-scorer/voice-tone agents or gate hooks — it
+# commits ungated and cannot run retro-on-exit. Pass each governance plugin
+# explicitly via `--plugin-dir`, resolved portably from the installed
+# marketplace cache (highest-version-wins, ADR-080; adopter-safe via the
+# ADR-049 bin-on-PATH shim, NOT a repo-relative path). Unresolvable plugins are
+# skipped silently. <!-- @jtbd JTBD-001 (iter commits ship gated) @jtbd JTBD-006 (full governance surface inside AFK iters) -->
+mapfile -t PLUGIN_DIR_ARGS < <(wr-itil-resolve-governance-plugin-dirs)
+
 claude -p \
   --permission-mode bypassPermissions \
   --output-format json \
+  "${PLUGIN_DIR_ARGS[@]}" \
   "$ITERATION_PROMPT" \
   < /dev/null \
   > "$ITER_JSON" 2>&1 &
@@ -595,6 +608,7 @@ rm -f "$ITER_JSON"
 
 - `--permission-mode bypassPermissions` — handles non-interactive permission prompts. Without this, Bash/Edit/Write calls inside the subprocess halt on approval prompts (no TTY). Alternative modes (`acceptEdits`, `auto`, `dontAsk`) are acceptable if adopters need narrower permission scopes; `bypassPermissions` is the broadest and the empirically-verified path.
 - `--output-format json` — deterministic structured output. The subprocess's final agent message lands in the JSON response's `.result` field; orchestrator extracts `ITERATION_SUMMARY` from that field. Plain-text output would require fragile scraping.
+- `"${PLUGIN_DIR_ARGS[@]}"` — `--plugin-dir <root>` pairs for each governance plugin, emitted by `wr-itil-resolve-governance-plugin-dirs` (the `mapfile` line above). **Load-bearing (P382).** Headless `claude -p` activates only USER-scoped `enabledPlugins`; project-scoped plugins stay inactive because project-plugin activation is trust-gated and headless skips the trust prompt. Empirically (verified 2026-06-21) `--setting-sources user,project` does NOT fix this — only `--plugin-dir` makes a project-scoped plugin's agents/hooks/skills available. Without these args an iter in a project-scope adopter tree commits ungated (architect/jtbd/risk-scorer/voice-tone agents resolve to "not found") and cannot run retro-on-exit. The resolver derives each plugin's root from its `bin/` dir on `$PATH` (ADR-049 — present in adopter marketplace-cache trees and source-dev alike) and selects the highest-semver cached version (ADR-080 — `$PATH` order is frozen at session init and goes stale mid-session, so it is NOT trusted for version selection). Behavioural second-source: `packages/itil/scripts/test/resolve-governance-plugin-dirs.bats`. The expansion is empty (no-op) when no governance plugins resolve, so source-repo dev sessions and minimal adopters degrade gracefully.
 - `< /dev/null` — explicit stdin-closed redirect (P089 Gap 1). Without this, `claude -p` waits up to 3s for stdin data in non-TTY contexts and then prints `Warning: no stdin data received in 3s, proceeding without it. If piping from a slow command, redirect stdin explicitly: < /dev/null to skip, or wait longer.` to stderr. The warning is on stderr — if the caller separates stderr and stdout streams, the warning is harmless. But the orchestrator captures via `2>&1` (required because the CLI emits progress prose on stderr that must not interleave between JSON responses when multiple invocations chain). Under the `2>&1` merge the stderr warning prefixes the stdout JSON and breaks `jq` / `json.load` / `JSON.parse` extraction at "line 1, column 1: Expecting value". The redirect suppresses the warning at source. First observed AFK-iter-7 iter 1 (2026-04-21); workaround is the Anthropic CLI help's own suggestion.
 
 **No per-iteration budget cap.** The dispatch deliberately omits `--max-budget-usd`. Per user direction 2026-04-21: the natural stop condition for an AFK loop is quota exhaustion, not an arbitrary per-iteration dollar cap. A cap would halt iterations before quota is actually exhausted, wasting remaining budget. Runaway-iteration risk is bounded by quota + the orchestrator's Step 6.75 halt on unexpected dirty state + exit-code handling below.