@windyroad/retrospective 0.16.0 → 0.17.0-preview.279

package/scripts/check-briefing-budgets.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-briefing-budgets.sh
+#
+# Diagnose-only advisory script for the docs/briefing/ tree (Tier 3 of
+# ADR-040). Walks <briefing-dir>/<topic>.md files, measures byte size
+# per file, and reports each topic file at or above the configured
+# threshold so run-retro Step 3 can route them through the rotation
+# AskUserQuestion (interactive) or defer to the retro summary (AFK).
+#
+# Usage:
+#   check-briefing-budgets.sh [<briefing-dir>]
+#
+# Default <briefing-dir> is ./docs/briefing.
+# Threshold is read from BRIEFING_TIER3_MAX_BYTES (default 5120 — the
+# upper bound of ADR-040's stated "2-5 KB / topic" Tier 3 envelope).
+#
+# Exit codes:
+#   0 = always (advisory only — overflow is signal, not failure)
+#   2 = parse error (briefing dir missing or unreadable)
+#
+# Output format on overflow (one line per file, terse machine-readable
+# per ADR-038 progressive-disclosure budget):
+#   OVER <basename> bytes=<N> threshold=<N>
+#
+# Files at >= 2.0x the threshold also emit a second line that promotes
+# ADR-040's reassessment trigger ("≥ 3 topic files exceed 2× the
+# configured ceiling for ≥ 2 consecutive retro cycles") from
+# policy-revisit-time to per-cycle enforcement on the same threshold:
+#   MUST_SPLIT <basename> reason=<code>
+#
+# The MUST_SPLIT line is the "no defer" signal: run-retro Step 3 Tier 3
+# silent-agent rotation is forced to pick split-by-subtopic /
+# split-by-date for these files (the trim-noise / leave-as-is fall-
+# throughs are not eligible). See P145.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   1. All OVER lines, sorted by basename.
+#   2. Then all MUST_SPLIT lines, sorted by basename.
+#
+# Output is empty (no lines) when no topic files exceed the threshold.
+# README.md is excluded from the scan — it is Tier 2, not Tier 3.
+#
+# Read-only — does NOT mutate any briefing file. Rotation is surfaced
+# to the user via run-retro Step 3.
+#
+# @problem P099 (initial OVER advisory)
+# @problem P145 (MUST_SPLIT escalation — closes the defer-recurrence gap)
+# @adr ADR-040 (Session-start briefing surface — Tier 3 budget; this
+#   script promotes Tier 3 from informational to advisory enforcement;
+#   MUST_SPLIT promotes the 2× reassessment trigger to per-cycle)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-013 (Rule 1 / Rule 6 — interactive vs AFK)
+# @adr ADR-044 (Decision-delegation contract — MUST_SPLIT is framework-
+#   resolved removal of the do-nothing options when ratio is decisive)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-101
+
+set -uo pipefail
+
+BRIEFING_DIR="${1:-docs/briefing}"
+THRESHOLD="${BRIEFING_TIER3_MAX_BYTES:-5120}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$BRIEFING_DIR" ]; then
+  echo "check-briefing-budgets: briefing dir not found: $BRIEFING_DIR" >&2
+  exit 2
+fi
+
+# ── Scan ────────────────────────────────────────────────────────────────────
+# Iterate markdown files at the top level of BRIEFING_DIR (not recursive).
+# Sort by basename for stable diff output (per bats fixture contract).
+
+shopt -s nullglob
+files=("$BRIEFING_DIR"/*.md)
+shopt -u nullglob
+
+if [ "${#files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Build (basename, bytes) pairs sorted by basename.
+declare -a entries=()
+for path in "${files[@]}"; do
+  base="$(basename "$path")"
+  # README.md is the Tier 2 index, not a Tier 3 topic file.
+  if [ "$base" = "README.md" ]; then
+    continue
+  fi
+  bytes=$(wc -c < "$path" | tr -d ' ')
+  entries+=("$base $bytes")
+done
+
+# Sort entries by basename
+IFS=$'\n' sorted=($(printf '%s\n' "${entries[@]}" | sort))
+unset IFS
+
+# Pass 1: emit OVER lines for every file at or above threshold.
+# Track MUST_SPLIT candidates (ratio >= 2.0x) for pass 2.
+declare -a must_split=()
+for entry in "${sorted[@]}"; do
+  base="${entry% *}"
+  bytes="${entry##* }"
+  if [ "$bytes" -ge "$THRESHOLD" ]; then
+    echo "OVER $base bytes=$bytes threshold=$THRESHOLD"
+    # Integer-arithmetic ratio test: bytes >= 2 * threshold.
+    # Avoids float math; exact at the 2.0x boundary per ADR-040
+    # reassessment trigger.
+    if [ "$bytes" -ge "$(( THRESHOLD * 2 ))" ]; then
+      must_split+=("$base")
+    fi
+  fi
+done
+
+# Pass 2: emit MUST_SPLIT lines (already sorted by pass-1 traversal order
+# which is basename-sorted).
+for base in "${must_split[@]}"; do
+  echo "MUST_SPLIT $base reason=ratio-exceeds-2x"
+done
+
+exit 0

package/scripts/check-internal-id-leaks.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-internal-id-leaks.sh
+#
+# Diagnose-only advisory script for plugin-published internal-ID leaks per
+# ADR-055 (Plugin-published artefacts use namespace-prefixed permalinks).
+#
+# Walks shipped-artefact surfaces under `<root-dir>/packages/<plugin>/`:
+#   - skills/<skill>/SKILL.md
+#   - agents/*.md
+#   - hooks/*.sh
+#   - CHANGELOG.md
+#
+# Reports each artefact carrying bare internal-ID tokens that lack the
+# `WR-` namespace prefix. Bare tokens are tokens that resolve correctly
+# only inside the windyroad-claude-plugin source repo's docs/decisions/,
+# docs/jtbd/, and docs/problems/ trees — adopter projects either find
+# nothing (failure mode 1, benign) or resolve to UNRELATED IDs in the
+# adopter's own tree (failure mode 3, dangerous).
+#
+# Usage:
+#   check-internal-id-leaks.sh [<root-dir>]
+#
+# Default <root-dir> is `.`.
+#
+# Token forms detected (case-sensitive, word-boundary):
+#   ADR-NNN   (3+ digits)
+#   JTBD-NNN  (3+ digits)
+#   PNNN      (exactly 3 digits — problem ticket form)
+#
+# Tokens that DO NOT trigger:
+#   WR-ADR-NNN, WR-JTBD-NNN, WR-PNNN  (namespace-prefixed; the strategy)
+#   docstring annotation lines beginning with `# @adr` / `# @jtbd` /
+#     `# @problem` (maintainer-facing source annotations, never expanded
+#     into adopter agent context per ADR-055 §Scope)
+#
+# Files NOT scanned:
+#   REFERENCE.md sibling files (lazy-loaded maintainer surface per ADR-054)
+#
+# Exit codes:
+#   0 = always (advisory only — drift is signal, not failure)
+#   2 = parse error (root dir missing or unreadable)
+#
+# Output format on drift (one line per file with leaks, terse machine-
+# readable per ADR-038 progressive-disclosure budget):
+#   OVER <plugin>/<relative-path> bare_count=<N>
+#
+# Followed by a final aggregate summary line:
+#   TOTAL packages=<N> with_leaks=<M> drift_instances=<K>
+#
+# Output is empty (no lines) when no shipped artefact carries bare
+# tokens — silent-on-pass per ADR-045 hook injection budget discipline.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   OVER lines sorted by `<plugin>/<relative-path>` identifier.
+#   TOTAL line last.
+#
+# Read-only — does NOT mutate any artefact. Per ADR-052, the bats fixture
+# at scripts/test/check-internal-id-leaks.bats is BEHAVIOURAL — asserts
+# script output on temp-fixture trees, NOT script source content.
+#
+# @problem P137 (Plugin-published artefacts reference internal IDs that
+#   adopter projects can't resolve)
+# @adr ADR-055 (Plugin-published artefacts use namespace-prefixed
+#   permalinks — strategy + advisory detector)
+# @adr ADR-038 (Progressive disclosure — terse machine-readable signal)
+# @adr ADR-045 (Hook injection budget — silent-on-pass discipline)
+# @adr ADR-052 (Behavioural-tests-default — fixture pattern)
+# @adr ADR-054 (SKILL.md runtime budget — REFERENCE.md exclusion source)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just
+#   Installed — semantic correctness axis of adopter-facing content)
+
+set -uo pipefail
+
+ROOT_DIR="${1:-.}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$ROOT_DIR" ]; then
+  echo "check-internal-id-leaks: root dir not found: $ROOT_DIR" >&2
+  exit 2
+fi
+
+# ── Collect artefact paths ──────────────────────────────────────────────────
+
+shopt -s nullglob
+declare -a artefacts=()
+for path in "$ROOT_DIR"/packages/*/skills/*/SKILL.md; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/agents/*.md; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/hooks/*.sh; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/CHANGELOG.md; do
+  artefacts+=("$path")
+done
+shopt -u nullglob
+
+if [ "${#artefacts[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Count bare tokens per file ──────────────────────────────────────────────
+# Algorithm (perl one-liner per file):
+#   1. Skip lines matching `^\s*#\s*@(adr|jtbd|problem)\b` (docstring annotations).
+#   2. On surviving lines, find all `(?<!WR-)\b(ADR-\d{3,}|JTBD-\d{3,}|P\d{3})\b`
+#      matches and increment a counter.
+#   3. Print the counter as a single integer.
+#
+# Negative lookbehind `(?<!WR-)` is safe in perl. Word-boundary `\b` keeps
+# `WR-ADR-014` matched only at position 3 (after `WR-`), which the
+# lookbehind then rejects. Bare `ADR-014` has start-of-string or non-WR-
+# char before, lookbehind passes, match counts.
+#
+# Word-boundary on the `P\d{3}` form requires \b on both ends so that
+# `Phase` (no digit follows) and `P3` (only 1 digit) don't match.
+
+declare -a leaks=()
+declare -A package_set=()
+declare -i total_drift=0
+
+# Strip ROOT_DIR + trailing slash for relative-path display.
+strip_root() {
+  local full="$1"
+  local prefix="$ROOT_DIR/packages/"
+  echo "${full#"$prefix"}"
+}
+
+for path in "${artefacts[@]}"; do
+  count=$(perl -ne '
+    next if /^\s*#\s*\@(adr|jtbd|problem)\b/i;
+    while (/(?<!WR-)\b(ADR-\d{3,}|JTBD-\d{3,}|P\d{3})\b/g) {
+      $n++;
+    }
+    END { print $n // 0 }
+  ' "$path")
+
+  if [ "$count" -gt 0 ]; then
+    rel="$(strip_root "$path")"
+    leaks+=("$rel $count")
+    plugin="${rel%%/*}"
+    package_set["$plugin"]=1
+    total_drift=$((total_drift + count))
+  fi
+done
+
+if [ "${#leaks[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Emit OVER lines (sorted) ────────────────────────────────────────────────
+
+IFS=$'\n' sorted=($(printf '%s\n' "${leaks[@]}" | sort))
+unset IFS
+
+for entry in "${sorted[@]}"; do
+  identifier="${entry% *}"
+  bare="${entry##* }"
+  echo "OVER $identifier bare_count=$bare"
+done
+
+# ── Emit TOTAL summary ──────────────────────────────────────────────────────
+
+echo "TOTAL packages=${#package_set[@]} with_leaks=${#leaks[@]} drift_instances=$total_drift"
+
+exit 0

package/scripts/check-readme-jtbd-currency.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-readme-jtbd-currency.sh
+#
+# Diagnose-only advisory script for ADR-051 (JTBD-anchored README rule).
+# Walks packages/*/README.md and emits a drift signal per package:
+#
+#   - has_jtbd_anchor=<yes|no>     — at least one JTBD-\d{3} match in the README
+#   - cited_jobs=<count>           — count of distinct JTBD IDs cited
+#   - known_jobs=<count>           — count of cited IDs that resolve to a current
+#                                    docs/jtbd/<persona>/JTBD-NNN-*.md (any status)
+#   - drift_hints=<comma-list>     — signal vocabulary:
+#         missing-jtbd-section     (no JTBD-\d{3} at all)
+#         stale-jtbd-citation      (cited ID has no resolving file)
+#         deprecated-jtbd-citation (cited ID resolves only to .deprecated.md / .superseded.md)
+#         skill-inventory-drift    (a directory under packages/<plugin>/skills/ is not named in README)
+#
+# Plus a trailing TOTAL line summarising the window:
+#   TOTAL packages=<N> with_jtbd=<M> drift_instances=<K>
+#
+# Exit code is always 0 — the script is advisory per ADR-013 Rule 6
+# fail-safe / ADR-040 declarative-first / ADR-051 Phase 1.
+# Drift count is emitted as data on stdout; downstream consumers
+# (run-retro Step 2b future wiring, release-pre-flight habit, Phase 2
+# escalation per ADR-051 Phase 2 criterion) decide whether to act.
+#
+# Usage:
+#   check-readme-jtbd-currency.sh [<packages-dir>] [<jtbd-dir>]
+#
+# Defaults:
+#   <packages-dir> = ./packages
+#   <jtbd-dir>     = ./docs/jtbd
+#
+# Exit codes:
+#   0 = always (advisory only — count is signal, not failure)
+#   2 = parse error (packages-dir or jtbd-dir missing or unreadable)
+#
+# Output format (one line per package, alphabetical):
+#   README package=<name> has_jtbd_anchor=<yes|no> cited_jobs=<N> known_jobs=<M> drift_hints=<csv>
+#
+# @problem P152 (No pressure or nudge for documentation currency — the driver problem)
+# @adr ADR-051 (JTBD-anchored README with declarative drift advisory — this script's normative source)
+# @adr ADR-008 (JTBD directory structure — the resolution target layout)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory script never blocks AFK)
+# @adr ADR-040 (declarative-first / advisory-then-escalate precedent)
+# @adr ADR-049 (bin/-on-PATH script resolution — paired wr-retrospective-check-readme-jtbd-currency shim)
+# @adr ADR-005 / ADR-037 (Plugin testing strategy — behavioural tests via bats)
+# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just Installed — primary served job)
+# @jtbd JTBD-007 (Keep Plugins Current Across Projects — currency expansion)
+# @jtbd JTBD-101 (Extend the Suite with New Plugins — clear patterns the detector documents)
+
+set -uo pipefail
+
+PACKAGES_DIR="${1:-packages}"
+JTBD_DIR="${2:-docs/jtbd}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PACKAGES_DIR" ]; then
+  echo "check-readme-jtbd-currency: packages dir not found: $PACKAGES_DIR" >&2
+  exit 2
+fi
+
+if [ ! -d "$JTBD_DIR" ]; then
+  echo "check-readme-jtbd-currency: jtbd dir not found: $JTBD_DIR" >&2
+  exit 2
+fi
+
+# ── Build the JTBD index ────────────────────────────────────────────────────
+# Map JTBD-NNN -> comma-separated status suffixes (proposed|validated|deprecated|superseded)
+# A JTBD ID may resolve to multiple files (e.g. during a status transition);
+# we record ALL status suffixes per ID for downstream use.
+
+declare -A JTBD_STATUS_BY_ID
+declare -A JTBD_RESOLVED
+
+for jpath in "$JTBD_DIR"/*/JTBD-*.md; do
+  [ -e "$jpath" ] || continue
+  base="$(basename "$jpath")"
+  if [[ "$base" =~ ^(JTBD-[0-9]{3})-.*\.([a-z]+)\.md$ ]]; then
+    id="${BASH_REMATCH[1]}"
+    status="${BASH_REMATCH[2]}"
+    JTBD_RESOLVED["$id"]=1
+    if [ -z "${JTBD_STATUS_BY_ID[$id]:-}" ]; then
+      JTBD_STATUS_BY_ID["$id"]="$status"
+    else
+      JTBD_STATUS_BY_ID["$id"]="${JTBD_STATUS_BY_ID[$id]},$status"
+    fi
+  fi
+done
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+append_hint() {
+  local current="$1"
+  local hint="$2"
+  if [ -z "$current" ]; then
+    echo "$hint"
+  elif [[ ",$current," == *",$hint,"* ]]; then
+    echo "$current"
+  else
+    echo "$current,$hint"
+  fi
+}
+
+is_deprecated_only() {
+  local statuses="$1"
+  IFS=',' read -ra arr <<< "$statuses"
+  for s in "${arr[@]}"; do
+    case "$s" in
+      deprecated|superseded) ;;
+      *) return 1 ;;
+    esac
+  done
+  return 0
+}
+
+# ── Scan packages ───────────────────────────────────────────────────────────
+
+total_packages=0
+total_with_jtbd=0
+total_drift_instances=0
+
+package_dirs=()
+for pdir in "$PACKAGES_DIR"/*/; do
+  [ -d "$pdir" ] || continue
+  package_dirs+=("$pdir")
+done
+
+if [ "${#package_dirs[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+IFS=$'\n' sorted_dirs=($(printf '%s\n' "${package_dirs[@]}" | sort))
+unset IFS
+
+for pdir in "${sorted_dirs[@]}"; do
+  package="$(basename "$pdir")"
+  readme="$pdir/README.md"
+
+  # Skip packages without a README — out of scope
+  [ -f "$readme" ] || continue
+
+  total_packages=$(( total_packages + 1 ))
+
+  # Extract distinct JTBD-NNN matches from the README
+  cited_ids=()
+  while IFS= read -r id; do
+    [ -z "$id" ] && continue
+    cited_ids+=("$id")
+  done < <(grep -oE 'JTBD-[0-9]{3}' "$readme" 2>/dev/null | sort -u)
+
+  cited_count="${#cited_ids[@]}"
+
+  has_anchor="no"
+  if [ "$cited_count" -gt 0 ]; then
+    has_anchor="yes"
+    total_with_jtbd=$(( total_with_jtbd + 1 ))
+  fi
+
+  hints=""
+  known_count=0
+
+  if [ "$cited_count" -eq 0 ]; then
+    hints=$(append_hint "$hints" "missing-jtbd-section")
+  else
+    has_stale=0
+    has_deprecated_only=0
+    for id in "${cited_ids[@]}"; do
+      if [ -n "${JTBD_RESOLVED[$id]:-}" ]; then
+        known_count=$(( known_count + 1 ))
+        if is_deprecated_only "${JTBD_STATUS_BY_ID[$id]}"; then
+          has_deprecated_only=1
+        fi
+      else
+        has_stale=1
+      fi
+    done
+    [ "$has_stale" -eq 1 ] && hints=$(append_hint "$hints" "stale-jtbd-citation")
+    [ "$has_deprecated_only" -eq 1 ] && hints=$(append_hint "$hints" "deprecated-jtbd-citation")
+  fi
+
+  # Soft heuristic: skill inventory drift — every directory under
+  # packages/<plugin>/skills/ should be named in the README.
+  if [ -d "$pdir/skills" ]; then
+    for sdir in "$pdir/skills"/*/; do
+      [ -d "$sdir" ] || continue
+      skill="$(basename "$sdir")"
+      if ! grep -q -F "$skill" "$readme" 2>/dev/null; then
+        hints=$(append_hint "$hints" "skill-inventory-drift")
+        break
+      fi
+    done
+  fi
+
+  # Drift instance: any non-empty hint set
+  if [ -n "$hints" ]; then
+    total_drift_instances=$(( total_drift_instances + 1 ))
+  fi
+
+  echo "README package=$package has_jtbd_anchor=$has_anchor cited_jobs=$cited_count known_jobs=$known_count drift_hints=$hints"
+done
+
+if [ "$total_packages" -gt 0 ]; then
+  echo "TOTAL packages=$total_packages with_jtbd=$total_with_jtbd drift_instances=$total_drift_instances"
+fi
+
+exit 0

package/scripts/check-skill-md-budgets.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-skill-md-budgets.sh
+#
+# Diagnose-only advisory script for SKILL.md byte budgets per ADR-054.
+# Walks `<root-dir>/packages/*/skills/*/SKILL.md` and
+# `<root-dir>/.claude/skills/*/SKILL.md`, measures byte size per file, and
+# reports each SKILL.md exceeding the WARN threshold so retro Step 2b can
+# surface the rotation candidate (interactive) or defer to retro summary
+# (AFK).
+#
+# Usage:
+#   check-skill-md-budgets.sh [<root-dir>]
+#
+# Default <root-dir> is `.`.
+# Thresholds:
+#   WARN ≥ SKILL_MD_WARN_BYTES (default 8192)
+#   MUST_SPLIT ≥ SKILL_MD_MUST_SPLIT_BYTES (default 16384)
+#
+# Exit codes:
+#   0 = always (advisory only — overflow is signal, not failure)
+#   2 = parse error (root dir missing or unreadable)
+#
+# Output format on overflow (one line per file, terse machine-readable
+# per ADR-038 progressive-disclosure budget):
+#   OVER <plugin>/<skill> bytes=<N> threshold=<N>
+#
+# Files at >= MUST_SPLIT also emit a second line:
+#   MUST_SPLIT <plugin>/<skill> reason=<code>
+#
+# This mirrors the OVER / MUST_SPLIT pair shape from `check-briefing-budgets.sh`
+# (P099 / P145 / ADR-040) deliberately so adopters learn one concept across
+# two surfaces.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   1. All OVER lines, sorted by `<plugin>/<skill>` identifier.
+#   2. Then all MUST_SPLIT lines, sorted by identifier.
+#
+# Output is empty (no lines) when no SKILL.md exceeds the WARN threshold.
+# REFERENCE.md sibling files (per ADR-054) are excluded from the scan —
+# they are intentionally lazy-loaded and not subject to the runtime budget.
+#
+# Read-only — does NOT mutate any SKILL.md file.
+#
+# @problem P097 (initial advisory — SKILL.md runtime budget surface)
+# @adr ADR-054 (SKILL.md runtime budget policy — taxonomy + sibling pattern + budget)
+# @adr ADR-040 (Session-start briefing surface — Tier 3 OVER / MUST_SPLIT vocabulary precedent)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-052 (Behavioural-tests-default — fixture is behavioural)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-101
+
+set -uo pipefail
+
+ROOT_DIR="${1:-.}"
+WARN_BYTES="${SKILL_MD_WARN_BYTES:-8192}"
+MUST_SPLIT_BYTES="${SKILL_MD_MUST_SPLIT_BYTES:-16384}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$ROOT_DIR" ]; then
+  echo "check-skill-md-budgets: root dir not found: $ROOT_DIR" >&2
+  exit 2
+fi
+
+# ── Scan ────────────────────────────────────────────────────────────────────
+# Collect SKILL.md paths from two surfaces:
+#   1. <root>/packages/*/skills/*/SKILL.md
+#   2. <root>/.claude/skills/*/SKILL.md
+# REFERENCE.md siblings are NOT scanned (per ADR-054).
+
+shopt -s nullglob
+plugin_skills=("$ROOT_DIR"/packages/*/skills/*/SKILL.md)
+local_skills=("$ROOT_DIR"/.claude/skills/*/SKILL.md)
+shopt -u nullglob
+
+if [ "${#plugin_skills[@]}" -eq 0 ] && [ "${#local_skills[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Build (identifier, bytes) pairs.
+# Identifier shape:
+#   plugin-skill: <plugin>/<skill> (e.g. "itil/manage-problem")
+#   project-local: .claude/<skill> (e.g. ".claude/install-updates")
+declare -a entries=()
+for path in "${plugin_skills[@]}"; do
+  # Path shape: <root>/packages/<plugin>/skills/<skill>/SKILL.md
+  skill_dir="$(dirname "$path")"
+  skill="$(basename "$skill_dir")"
+  plugin="$(basename "$(dirname "$(dirname "$skill_dir")")")"
+  identifier="$plugin/$skill"
+  bytes=$(wc -c < "$path" | tr -d ' ')
+  entries+=("$identifier $bytes")
+done
+for path in "${local_skills[@]}"; do
+  # Path shape: <root>/.claude/skills/<skill>/SKILL.md
+  skill_dir="$(dirname "$path")"
+  skill="$(basename "$skill_dir")"
+  identifier=".claude/$skill"
+  bytes=$(wc -c < "$path" | tr -d ' ')
+  entries+=("$identifier $bytes")
+done
+
+if [ "${#entries[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Sort entries by identifier for deterministic output
+IFS=$'\n' sorted=($(printf '%s\n' "${entries[@]}" | sort))
+unset IFS
+
+# Pass 1: emit OVER lines for every file at or above WARN threshold.
+# Track MUST_SPLIT candidates (>= MUST_SPLIT_BYTES) for pass 2.
+declare -a must_split=()
+for entry in "${sorted[@]}"; do
+  identifier="${entry% *}"
+  bytes="${entry##* }"
+  if [ "$bytes" -ge "$WARN_BYTES" ]; then
+    echo "OVER $identifier bytes=$bytes threshold=$WARN_BYTES"
+    if [ "$bytes" -ge "$MUST_SPLIT_BYTES" ]; then
+      must_split+=("$identifier")
+    fi
+  fi
+done
+
+# Pass 2: emit MUST_SPLIT lines (already in basename-sorted order from pass 1).
+for identifier in "${must_split[@]}"; do
+  echo "MUST_SPLIT $identifier reason=ratio-exceeds-must-split"
+done
+
+exit 0