@windyroad/retrospective 0.16.0 → 0.17.0-preview.279

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

package/scripts/list-plugin-attribution.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/list-plugin-attribution.sh
+#
+# Read-only diagnostic for per-plugin hooks/skills byte attribution
+# consumed by the deep-layer skill `/wr-retrospective:analyze-context`
+# (Step 2 — Decompose per-plugin attribution).
+#
+# Replaces the inline `for plugin_dir in packages/*/hooks; do ... done`
+# loops that lived in SKILL.md before P153/ADR-049-reassessment.clause-3.
+# Those loops worked in source-repo dev sessions but expanded to nothing
+# in adopter sessions (no `packages/` dir under adopter project root),
+# emitting zero PLUGIN-HOOKS / PLUGIN-SKILLS rows with no error signal.
+#
+# This helper resolves both modes:
+#   1. Source-tree mode  — walk `<project-root>/packages/<plugin>/{hooks,skills}`.
+#   2. Cache-fallback    — sniff `$PATH` for entries shaped like
+#                          `*/cache/<owner>/<plugin>/<version>/bin`
+#                          and back-walk to each plugin's root.
+#   3. Neither resolves  — emit `PLUGIN-ATTRIBUTION not-measured
+#                          reason=no-plugin-source-resolvable` per ADR-026.
+#
+# Usage:
+#   list-plugin-attribution.sh [<project-root>]
+#
+# Default <project-root> is the current working directory.
+#
+# Output (one row per plugin, terse machine-readable per ADR-038 ≤150 bytes):
+#   PLUGIN-HOOKS  <plugin> bytes=<N>
+#   PLUGIN-SKILLS <plugin> bytes=<N>
+#   PLUGIN-ATTRIBUTION not-measured reason=<reason>
+#
+# Sorted by row-type then plugin name for stable diffs.
+#
+# Exit code: 0 always (advisory only — matches measure-context-budget.sh
+# contract; missing data is signal, not failure).
+#
+# @problem P153
+# @adr ADR-049 (Plugin-bundled scripts via `bin/` on `$PATH` —
+#   reassessment-criteria clause 3 explicitly anticipates this surface)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-026 (Agent output grounding — explicit not-measured sentinels
+#   when neither resolution mode resolves)
+# @jtbd JTBD-301 (Plugin-user) / JTBD-101 (Plugin-developer)
+
+set -uo pipefail
+
+PROJECT_ROOT="${1:-$(pwd)}"
+
+sum_dir_bytes() {
+  local dir="$1"
+  local pattern="$2"
+  if [ ! -d "$dir" ] || [ ! -r "$dir" ]; then
+    echo 0
+    return
+  fi
+  local total=0 b
+  while IFS= read -r -d '' f; do
+    b=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+    total=$(( total + ${b:-0} ))
+  done < <(find "$dir" -type f -name "$pattern" -print0 2>/dev/null)
+  echo "$total"
+}
+
+declare -a ROWS=()
+
+emit_plugin_row() {
+  local row_type="$1"
+  local plugin="$2"
+  local bytes="$3"
+  ROWS+=( "$row_type $plugin bytes=$bytes" )
+}
+
+source_resolved=0
+
+if [ -d "$PROJECT_ROOT/packages" ]; then
+  shopt -s nullglob
+  hook_dirs=( "$PROJECT_ROOT"/packages/*/hooks )
+  skill_dirs=( "$PROJECT_ROOT"/packages/*/skills )
+  shopt -u nullglob
+
+  for d in ${hook_dirs[@]+"${hook_dirs[@]}"}; do
+    plugin=$(basename "$(dirname "$d")")
+    bytes=$(sum_dir_bytes "$d" '*.sh')
+    emit_plugin_row PLUGIN-HOOKS "$plugin" "$bytes"
+    source_resolved=1
+  done
+
+  for d in ${skill_dirs[@]+"${skill_dirs[@]}"}; do
+    plugin=$(basename "$(dirname "$d")")
+    bytes=$(sum_dir_bytes "$d" 'SKILL.md')
+    emit_plugin_row PLUGIN-SKILLS "$plugin" "$bytes"
+    source_resolved=1
+  done
+fi
+
+cache_resolved=0
+
+if [ "$source_resolved" -eq 0 ] && [ -n "${PATH:-}" ]; then
+  # bash 3.2 on macOS lacks `declare -A` — track seen plugins in a
+  # delimiter-bounded string. Membership probe: case "$SEEN_PLUGINS" in
+  # *"|$plugin|"*) ;; esac.
+  SEEN_PLUGINS="|"
+  IFS=':' read -r -a path_entries <<< "$PATH"
+
+  for entry in ${path_entries[@]+"${path_entries[@]}"}; do
+    [ -z "$entry" ] && continue
+    entry="${entry%/}"
+    [[ "$entry" == */bin ]] || continue
+    [[ "$entry" == */cache/* ]] || continue
+
+    plugin_root="${entry%/bin}"
+    plugin=$(basename "$(dirname "$plugin_root")")
+    [ -z "$plugin" ] && continue
+    case "$SEEN_PLUGINS" in *"|$plugin|"*) continue ;; esac
+    SEEN_PLUGINS="${SEEN_PLUGINS}${plugin}|"
+
+    hooks_dir="$plugin_root/hooks"
+    skills_dir="$plugin_root/skills"
+
+    if [ -d "$hooks_dir" ]; then
+      bytes=$(sum_dir_bytes "$hooks_dir" '*.sh')
+      emit_plugin_row PLUGIN-HOOKS "$plugin" "$bytes"
+      cache_resolved=1
+    fi
+    if [ -d "$skills_dir" ]; then
+      bytes=$(sum_dir_bytes "$skills_dir" 'SKILL.md')
+      emit_plugin_row PLUGIN-SKILLS "$plugin" "$bytes"
+      cache_resolved=1
+    fi
+  done
+fi
+
+if [ "$source_resolved" -eq 1 ] || [ "$cache_resolved" -eq 1 ]; then
+  printf '%s\n' ${ROWS[@]+"${ROWS[@]}"} | LC_ALL=C sort
+else
+  echo "PLUGIN-ATTRIBUTION not-measured reason=no-plugin-source-resolvable"
+fi
+
+exit 0