@windyroad/retrospective 0.16.0 → 0.17.0-preview.277

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

package/scripts/check-tarball-shipped-shims.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-tarball-shipped-shims.sh
+#
+# Diagnose-only advisory script for plugin-published tarball-shipped-shim
+# integrity per WR-P154 (P137 detector must run against npm pack output not
+# source tree) and the WR-ADR-049 plugin-script-resolution-via-bin-on-PATH
+# contract.
+#
+# Walks workspace packages under `<root-dir>/packages/<plugin>/`. For each
+# workspace, runs `npm pack --dry-run --json` to enumerate the file set that
+# WOULD ship to npm (per `package.json#files` filtering). For every
+# WR-ADR-049-grammar bin shim (`bin/wr-<plugin>-<name>`) in that file set,
+# parses the shim source to extract the `exec`'d `scripts/<name>.sh` target
+# and asserts the target path is also in the tarball file set.
+#
+# The asymmetry between source-tree state and tarball state is the gap
+# WR-P137 Phase 1 (check-internal-id-leaks.sh, source-tree-walking) does
+# not see — `scripts/` exists on disk but is omitted from `package.json#files`
+# so the shim shipped to adopters exec-fails with `no such file or directory`
+# at invocation time. WR-P154 closes the prevention surface from the
+# publish-manifest side.
+#
+# Usage:
+#   check-tarball-shipped-shims.sh [<root-dir>]
+#
+# Default <root-dir> is `.`.
+#
+# WR-ADR-049-grammar shims that this script considers:
+#   bin/wr-<plugin>-<name>
+# Non-grammar bins (e.g. `bin/install.mjs`, `bin/check-deps.sh`,
+# `bin/windyroad-<plugin>` legacy installers) are skipped — they don't
+# follow the script-resolution-via-bin-on-PATH WR-ADR-049 contract.
+#
+# Exit codes:
+#   0 = always (advisory only — drift is signal, not failure)
+#   2 = parse error (root dir missing or unreadable, npm unavailable)
+#
+# Output format on drift (terse machine-readable per WR-ADR-038):
+#   TARBALL_DRIFT package=<name> shim=<bin/wr-...> target=<scripts/...> tarball-status=missing
+#
+# Followed by a final aggregate summary line:
+#   TOTAL packages=<N> with_drift=<M> missing_targets=<K>
+#
+# Output is empty (no lines) when no shipped artefact carries broken
+# shims — silent-on-pass per WR-ADR-045 hook injection budget discipline.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   TARBALL_DRIFT lines sorted by `<package>/<shim>` identifier.
+#   TOTAL line last.
+#
+# Read-only — does NOT mutate any artefact. Per WR-ADR-052, the bats
+# fixture at scripts/test/check-tarball-shipped-shims.bats is BEHAVIOURAL —
+# asserts script output on temp-fixture trees, NOT script source content.
+#
+# @problem P154 (P137 namespace-prefix detector must run against
+#   npm pack output not source tree)
+# @problem P140 (Step 6.5 fix-and-continue — same prevention surface
+#   from the publisher side)
+# @adr ADR-049 (Plugin script resolution via bin/ on PATH)
+# @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-055 (Plugin-published namespace-prefixed permalinks —
+#   sibling adopter-context decision)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just
+#   Installed — executable correctness axis of adopter-facing content)
+# @jtbd JTBD-101 (Extend the Suite with New Plugins — secondary
+#   plugin-developer feedback surface)
+
+set -uo pipefail
+
+ROOT_DIR="${1:-.}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$ROOT_DIR" ]; then
+  echo "check-tarball-shipped-shims: root dir not found: $ROOT_DIR" >&2
+  exit 2
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "check-tarball-shipped-shims: npm not found on PATH" >&2
+  exit 2
+fi
+
+# ── Walk workspaces ─────────────────────────────────────────────────────────
+
+shopt -s nullglob
+declare -a workspaces=()
+for pkg_json in "$ROOT_DIR"/packages/*/package.json; do
+  workspaces+=("$(dirname "$pkg_json")")
+done
+shopt -u nullglob
+
+if [ "${#workspaces[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Per-workspace pack + drift detection ────────────────────────────────────
+# For each workspace:
+#   1. cd into workspace dir; run `npm pack --dry-run --json` to get the
+#      shipped file list. Independent of monorepo workspaces config — works
+#      in adopter trees too.
+#   2. Parse JSON via python3 (always available on the host) to extract
+#      the file paths AND the package name.
+#   3. For each `bin/wr-<plugin>-<name>` shim in the file list, parse the
+#      shim source on disk (NOT from the tarball — same content) to find
+#      the `exec`'d `../scripts/<name>.sh` target.
+#   4. Check whether the resolved target path is in the tarball file list.
+#   5. Emit `TARBALL_DRIFT` lines for missing targets.
+
+declare -a drifts=()
+declare -A package_set=()
+declare -i missing_total=0
+
+for ws in "${workspaces[@]}"; do
+  # Pack the workspace. Capture stdout; suppress stderr (npm chatter).
+  pack_json=$(cd "$ws" && npm pack --dry-run --json 2>/dev/null) || continue
+  if [ -z "$pack_json" ]; then
+    continue
+  fi
+
+  # Extract package name + file path list via python3.
+  # Output format (one record per line):
+  #   NAME <package-name>
+  #   FILE <relative-path>
+  #   ...
+  parsed=$(printf '%s' "$pack_json" | python3 -c '
+import sys, json
+data = json.load(sys.stdin)
+if not data:
+    sys.exit(0)
+entry = data[0] if isinstance(data, list) else data
+name = entry.get("name", "")
+files = entry.get("files", []) or []
+print("NAME " + name)
+for f in files:
+    p = f.get("path", "")
+    if p:
+        print("FILE " + p)
+') || continue
+
+  pkg_name=""
+  declare -a tarball_files=()
+  while IFS= read -r line; do
+    case "$line" in
+      "NAME "*)
+        pkg_name="${line#NAME }"
+        ;;
+      "FILE "*)
+        tarball_files+=("${line#FILE }")
+        ;;
+    esac
+  done <<< "$parsed"
+
+  if [ -z "$pkg_name" ]; then
+    continue
+  fi
+
+  # Build a lookup set of tarball file paths.
+  declare -A tarball_set=()
+  for f in "${tarball_files[@]}"; do
+    tarball_set["$f"]=1
+  done
+
+  # Find WR-ADR-049-grammar shims in the tarball file list.
+  # Grammar: bin/wr-<plugin>-<name>  (excludes bin/install.mjs, bin/check-deps.sh,
+  # bin/windyroad-<plugin>, bin/anything-without-wr-prefix).
+  workspace_has_drift=0
+  for f in "${tarball_files[@]}"; do
+    case "$f" in
+      bin/wr-*)
+        # Parse the shim source on disk for the exec target.
+        shim_path="$ws/$f"
+        if [ ! -f "$shim_path" ]; then
+          continue
+        fi
+        # Heuristic: extract the relative path after `$(dirname "$0")/../`.
+        # Matches the WR-ADR-049 grammar both for `exec "$(dirname "$0")/../scripts/foo.sh" "$@"`
+        # and the same shape with single quotes / no quotes around dirname.
+        target=$(perl -ne '
+          if (/\$\(dirname\s+["'\'']?\$0["'\'']?\)\/\.\.\/(\S+?)["'\'']?\s/) {
+            print $1; exit;
+          }
+        ' "$shim_path")
+
+        if [ -z "$target" ]; then
+          continue
+        fi
+
+        if [ -z "${tarball_set[$target]:-}" ]; then
+          drifts+=("$pkg_name|$f|$target")
+          missing_total=$((missing_total + 1))
+          workspace_has_drift=1
+        fi
+        ;;
+    esac
+  done
+
+  if [ "$workspace_has_drift" -eq 1 ]; then
+    package_set["$pkg_name"]=1
+  fi
+
+  unset tarball_set
+  unset tarball_files
+done
+
+if [ "${#drifts[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Emit TARBALL_DRIFT lines (sorted) ───────────────────────────────────────
+
+IFS=$'\n' sorted=($(printf '%s\n' "${drifts[@]}" | sort))
+unset IFS
+
+for entry in "${sorted[@]}"; do
+  IFS='|' read -r pkg shim target <<< "$entry"
+  echo "TARBALL_DRIFT package=$pkg shim=$shim target=$target tarball-status=missing"
+done
+
+# ── Emit TOTAL summary ──────────────────────────────────────────────────────
+
+echo "TOTAL packages=${#package_set[@]} with_drift=${#package_set[@]} missing_targets=$missing_total"
+
+exit 0

package/scripts/check-tickets-deferred-cause.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-tickets-deferred-cause.sh
+#
+# Diagnose-only advisory script for Step 4b Stage 1's "Tickets Deferred"
+# fallback (P148). Walks docs/retros/*.md retro summary files, parses the
+# `### Tickets Deferred` table in each, and counts entries whose `Cause`
+# column is not in the allowlist `{skill_unavailable}`. Emits one line
+# per retro file plus a trailing TOTAL summary line.
+#
+# Exit code is always 0 — the script is advisory per ADR-040
+# declarative-first / ADR-013 Rule 6 fail-safe. Violation count is
+# emitted as data on stdout; downstream consumers (retro summary
+# rendering, future enforcement-hook escalation per P135 R6 trajectory)
+# decide whether to act on the count.
+#
+# Usage:
+#   check-tickets-deferred-cause.sh [<retros-dir>]
+#
+# Default <retros-dir> is ./docs/retros.
+#
+# Exit codes:
+#   0 = always (advisory only — count is signal, not failure)
+#   2 = parse error (retros dir missing or unreadable)
+#
+# Output format (one line per retro file with a Tickets Deferred section,
+# oldest first by date prefix):
+#   RETRO <YYYY-MM-DD> file=<basename> deferred=<N> with_valid_cause=<M> violations=<K>
+#
+# Plus a trailing TOTAL line summarising the window:
+#   TOTAL files=<N> deferred=<N> with_valid_cause=<M> violations=<K>
+#
+# Output is empty (no lines) when no retro files contain a Tickets
+# Deferred section — this is the expected steady state when Stage 1
+# ticketing is firing as designed.
+#
+# Tickets Deferred table shape (per run-retro SKILL.md Step 5 template):
+#
+#   ### Tickets Deferred
+#
+#   | Observation | Cause | Citation |
+#   |-------------|-------|----------|
+#   | <text> | `skill_unavailable` | <text> |
+#
+# The script tolerates:
+#   - Cause values wrapped in backticks or bold markers
+#   - Missing Cause column entirely (treated as a violation)
+#   - Out-of-allowlist cause values (treated as a violation)
+#   - Empty Cause cell (treated as a violation)
+#
+# Read-only — does NOT mutate any retro file.
+#
+# @problem P148 (Agent defers ticket creation — broadens Stage 1 fallback gate)
+# @problem P145 (Sibling defer-pattern at Tier 3 rotation — same class of behaviour)
+# @adr ADR-044 (Decision-Delegation Contract — framework-resolution boundary)
+# @adr ADR-040 (Tier 3 advisory-not-fail-closed — declarative-first precedent)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory script never blocks AFK)
+# @adr ADR-005 / ADR-037 (Plugin testing strategy — behavioural tests)
+# @jtbd JTBD-001 (enforce governance without slowing down)
+# @jtbd JTBD-006 (progress backlog while AFK — anti-defer is the load-bearing job)
+# @jtbd JTBD-201 (audit trail for AI-assisted work — Cause field IS the audit trail)
+
+set -uo pipefail
+
+RETROS_DIR="${1:-docs/retros}"
+
+# Allowlist — single source of truth for valid Cause values. The
+# allowlist intentionally has ONE entry. Adding entries requires a
+# matching SKILL.md AFK-branch update (and ideally a sibling ADR).
+ALLOWLIST_CAUSES=("skill_unavailable")
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$RETROS_DIR" ]; then
+  echo "check-tickets-deferred-cause: retros dir not found: $RETROS_DIR" >&2
+  exit 2
+fi
+
+# ── Scan ────────────────────────────────────────────────────────────────────
+# Iterate retro summary files at the top level of RETROS_DIR. Skip
+# ask-hygiene trail files (those are check-ask-hygiene.sh's surface);
+# skip context-analysis files. Glob expansion uses a portable for-loop
+# (P124 lesson — `shopt -s nullglob` is bash-only).
+
+retro_files=()
+for path in "$RETROS_DIR"/*.md; do
+  [ -e "$path" ] || continue
+  # Skip non-summary files
+  basename="$(basename "$path")"
+  case "$basename" in
+    *-ask-hygiene.md) continue ;;
+    *-context-analysis.md) continue ;;
+    *)
+      # Only consider files whose basename starts with a YYYY-MM-DD date prefix
+      if [[ "$basename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
+        retro_files+=("$path")
+      fi
+      ;;
+  esac
+done
+
+if [ "${#retro_files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Sort by basename date prefix, oldest first
+IFS=$'\n' sorted_files=($(printf '%s\n' "${retro_files[@]}" | sort))
+unset IFS
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+extract_date() {
+  local basename
+  basename="$(basename "$1")"
+  # Take the leading YYYY-MM-DD prefix
+  echo "${basename:0:10}"
+}
+
+# Determine if a cause value is in the allowlist
+is_valid_cause() {
+  local raw="$1"
+  # Strip backticks, bold asterisks, and surrounding whitespace
+  local cleaned
+  cleaned=$(echo "$raw" | sed 's/`//g' | sed 's/\*\*//g' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
+  if [ -z "$cleaned" ]; then
+    return 1
+  fi
+  for allowed in "${ALLOWLIST_CAUSES[@]}"; do
+    if [ "$cleaned" = "$allowed" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Parse a single retro file's Tickets Deferred section. Sets the global
+# variables `parsed_deferred`, `parsed_valid`, `parsed_violations` for
+# the caller to read.
+parse_retro_file() {
+  local path="$1"
+  parsed_deferred=0
+  parsed_valid=0
+  parsed_violations=0
+
+  # Extract the lines between `### Tickets Deferred` and the next `###`
+  # heading (or EOF). awk's range pattern handles this idiomatically.
+  local section
+  section=$(awk '
+    /^### Tickets Deferred[[:space:]]*$/ { in_section=1; next }
+    in_section && /^### / { in_section=0 }
+    in_section { print }
+  ' "$path")
+
+  if [ -z "$section" ]; then
+    return 0
+  fi
+
+  # Walk the table rows. A table row starts with `|`, has at least 3
+  # cells, and is not the header or separator row.
+  while IFS= read -r line; do
+    # Skip blank lines, prose, and non-table content
+    [[ "$line" =~ ^\| ]] || continue
+    # Skip the separator row (cells of dashes)
+    [[ "$line" =~ ^\|[[:space:]]*-+[[:space:]]*\| ]] && continue
+    # Skip the header row — detected by literal "Observation" in cell 1
+    if [[ "$line" =~ ^\|[[:space:]]*Observation[[:space:]]*\| ]]; then
+      continue
+    fi
+    # Skip the placeholder example row — detected by `<one-line` template marker
+    if [[ "$line" =~ \<one-line\ observation\ summary\> ]]; then
+      continue
+    fi
+
+    parsed_deferred=$(( parsed_deferred + 1 ))
+
+    # Split the row into cells. The first cell is empty (leading `|`).
+    # Use a perl-free awk split on `|`.
+    local cause_cell
+    cause_cell=$(echo "$line" | awk -F'|' '{print $3}')
+
+    if [ -z "$cause_cell" ]; then
+      # No Cause column at all — violation
+      parsed_violations=$(( parsed_violations + 1 ))
+      continue
+    fi
+
+    if is_valid_cause "$cause_cell"; then
+      parsed_valid=$(( parsed_valid + 1 ))
+    else
+      parsed_violations=$(( parsed_violations + 1 ))
+    fi
+  done <<< "$section"
+}
+
+# ── Emit per-file lines ─────────────────────────────────────────────────────
+
+total_files=0
+total_deferred=0
+total_valid=0
+total_violations=0
+
+for path in "${sorted_files[@]}"; do
+  parse_retro_file "$path"
+  if [ "$parsed_deferred" -eq 0 ]; then
+    continue
+  fi
+  date=$(extract_date "$path")
+  basename="$(basename "$path")"
+  echo "RETRO $date file=$basename deferred=$parsed_deferred with_valid_cause=$parsed_valid violations=$parsed_violations"
+  total_files=$(( total_files + 1 ))
+  total_deferred=$(( total_deferred + parsed_deferred ))
+  total_valid=$(( total_valid + parsed_valid ))
+  total_violations=$(( total_violations + parsed_violations ))
+done
+
+# Emit TOTAL line when at least one file contributed
+if [ "$total_files" -gt 0 ]; then
+  echo "TOTAL files=$total_files deferred=$total_deferred with_valid_cause=$total_valid violations=$total_violations"
+fi
+
+exit 0