@windyroad/retrospective 0.16.0 → 0.17.0-preview.277

package/scripts/test/check-tarball-shipped-shims.bats

@@ -0,0 +1,284 @@
+#!/usr/bin/env bats
+
+# Behavioural fixture for the tarball-shipped-shims advisory detector — per
+# WR-P154 (P137 namespace-prefix detector must run against npm pack output
+# not source tree) and the WR-ADR-049 / WR-ADR-052 / WR-ADR-055 cluster.
+#
+# Contract: `check-tarball-shipped-shims.sh [<root-dir>]` is a diagnose-only
+# advisory script. It walks workspaces under `<root-dir>/packages/*/`, runs
+# `npm pack --dry-run --json` per workspace to enumerate the file set that
+# ships, then asserts that every WR-ADR-049-grammar bin shim
+# (`bin/wr-<plugin>-<name>`) in the tarball has its `exec`'d
+# `scripts/<name>.sh` target also in the tarball.
+#
+# Surface: shipped publish-manifest integrity for bin/scripts/ shim
+# resolvability — different correctness axis than check-internal-id-leaks.sh
+# (which measures source-tree namespace-prefix drift).
+#
+# 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 ADR-049 contract this
+# script enforces.
+#
+# Exit codes:
+#   0 = always (advisory only — drift is signal, not failure)
+#   2 = parse error (root dir missing/unreadable, or 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 summary line (always emitted when any drift exists):
+#   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.
+#
+# 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, this fixture
+# is BEHAVIOURAL — it asserts script output on temp-fixture trees, NOT
+# script source content. No greps of check-tarball-shipped-shims.sh source.
+#
+# @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)
+# @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)
+# @adr ADR-052 (Behavioural-tests-default — fixture pattern)
+# @adr ADR-055 (Plugin-published namespace-prefixed permalinks —
+#   sibling adopter-context decision)
+# @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)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-tarball-shipped-shims.sh"
+  FIXTURE_ROOT="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_ROOT"
+}
+
+# Helper: write a workspace package.json with a controlled `files` array.
+# Args: <plugin> <files-json-array>
+# Example: write_package_json alpha '["bin/", "scripts/"]'
+write_package_json() {
+  local plugin="$1"
+  local files="$2"
+  local plugin_dir="$FIXTURE_ROOT/packages/$plugin"
+  mkdir -p "$plugin_dir"
+  cat > "$plugin_dir/package.json" <<EOF
+{
+  "name": "@test/$plugin",
+  "version": "0.1.0",
+  "files": $files
+}
+EOF
+}
+
+# Helper: write an WR-ADR-049-grammar bin shim that exec-s a scripts/ target.
+# Args: <plugin> <name>  (shim becomes bin/wr-<plugin>-<name>, exec-s ../scripts/<name>.sh)
+write_adr049_shim() {
+  local plugin="$1"
+  local name="$2"
+  local bin_dir="$FIXTURE_ROOT/packages/$plugin/bin"
+  mkdir -p "$bin_dir"
+  cat > "$bin_dir/wr-$plugin-$name" <<EOF
+#!/usr/bin/env bash
+exec "\$(dirname "\$0")/../scripts/$name.sh" "\$@"
+EOF
+  chmod +x "$bin_dir/wr-$plugin-$name"
+}
+
+# Helper: write a script body matching the shim's exec target.
+write_script() {
+  local plugin="$1"
+  local name="$2"
+  local script_dir="$FIXTURE_ROOT/packages/$plugin/scripts"
+  mkdir -p "$script_dir"
+  cat > "$script_dir/$name.sh" <<'EOF'
+#!/usr/bin/env bash
+echo "fixture script body"
+EOF
+  chmod +x "$script_dir/$name.sh"
+}
+
+# Helper: write a non-WR-ADR-049-grammar bin entry (e.g. legacy installer).
+# These should be silently ignored by the script.
+write_non_grammar_bin() {
+  local plugin="$1"
+  local name="$2"
+  local bin_dir="$FIXTURE_ROOT/packages/$plugin/bin"
+  mkdir -p "$bin_dir"
+  cat > "$bin_dir/$name" <<'EOF'
+#!/usr/bin/env bash
+echo "legacy installer"
+EOF
+  chmod +x "$bin_dir/$name"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "check-tarball-shipped-shims: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Empty / clean trees ─────────────────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: empty tree (no packages dir) produces no output and exits 0" {
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-tarball-shipped-shims: packages dir with no workspaces produces no output and exits 0" {
+  mkdir -p "$FIXTURE_ROOT/packages"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-tarball-shipped-shims: workspace with no WR-ADR-049 shims produces no output" {
+  write_package_json "alpha" '["bin/"]'
+  write_non_grammar_bin "alpha" "windyroad-alpha"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-tarball-shipped-shims: clean workspace (shim + target both ship) produces no output" {
+  write_package_json "alpha" '["bin/", "scripts/"]'
+  write_adr049_shim "alpha" "good"
+  write_script "alpha" "good"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Drift detection — the iter-20 P033 sibling-finding shape ────────────────
+
+@test "check-tarball-shipped-shims: shim present in tarball, target NOT in tarball — flagged" {
+  # The canonical broken shape: scripts/ exists on disk, shim references it,
+  # but package.json#files omits scripts/ so the target isn't shipped.
+  write_package_json "alpha" '["bin/"]'
+  write_adr049_shim "alpha" "broken"
+  write_script "alpha" "broken"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TARBALL_DRIFT package=@test/alpha shim=bin/wr-alpha-broken target=scripts/broken.sh tarball-status=missing$"
+}
+
+@test "check-tarball-shipped-shims: TOTAL summary emitted on any drift" {
+  write_package_json "alpha" '["bin/"]'
+  write_adr049_shim "alpha" "broken"
+  write_script "alpha" "broken"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TOTAL packages=1 with_drift=1 missing_targets=1$"
+}
+
+@test "check-tarball-shipped-shims: multiple shims in one workspace — each missing target flagged" {
+  write_package_json "alpha" '["bin/"]'
+  write_adr049_shim "alpha" "alpha-one"
+  write_script "alpha" "alpha-one"
+  write_adr049_shim "alpha" "alpha-two"
+  write_script "alpha" "alpha-two"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TARBALL_DRIFT package=@test/alpha shim=bin/wr-alpha-alpha-one target=scripts/alpha-one.sh tarball-status=missing$"
+  echo "$output" | grep -E "^TARBALL_DRIFT package=@test/alpha shim=bin/wr-alpha-alpha-two target=scripts/alpha-two.sh tarball-status=missing$"
+  echo "$output" | grep -E "^TOTAL packages=1 with_drift=1 missing_targets=2$"
+}
+
+@test "check-tarball-shipped-shims: drift across multiple packages aggregates correctly" {
+  write_package_json "alpha" '["bin/"]'
+  write_adr049_shim "alpha" "a-broken"
+  write_script "alpha" "a-broken"
+  write_package_json "beta" '["bin/"]'
+  write_adr049_shim "beta" "b-broken"
+  write_script "beta" "b-broken"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TOTAL packages=2 with_drift=2 missing_targets=2$"
+}
+
+# ── Mixed clean + drift workspaces ──────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: clean workspace + broken workspace — only broken flagged, TOTAL counts only with_drift" {
+  write_package_json "alpha" '["bin/", "scripts/"]'
+  write_adr049_shim "alpha" "good"
+  write_script "alpha" "good"
+  write_package_json "beta" '["bin/"]'
+  write_adr049_shim "beta" "broken"
+  write_script "beta" "broken"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q "alpha"
+  echo "$output" | grep -E "^TARBALL_DRIFT package=@test/beta shim=bin/wr-beta-broken target=scripts/broken.sh tarball-status=missing$"
+  echo "$output" | grep -E "^TOTAL packages=1 with_drift=1 missing_targets=1$"
+}
+
+# ── Determinism ─────────────────────────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: TARBALL_DRIFT lines sorted deterministically by package/shim" {
+  write_package_json "zeta" '["bin/"]'
+  write_adr049_shim "zeta" "z-shim"
+  write_script "zeta" "z-shim"
+  write_package_json "alpha" '["bin/"]'
+  write_adr049_shim "alpha" "a-shim"
+  write_script "alpha" "a-shim"
+  write_package_json "mu" '["bin/"]'
+  write_adr049_shim "mu" "m-shim"
+  write_script "mu" "m-shim"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  local first
+  first=$(echo "$output" | grep '^TARBALL_DRIFT' | head -1)
+  echo "$first" | grep -q "package=@test/alpha"
+  local last
+  last=$(echo "$output" | grep '^TARBALL_DRIFT' | tail -1)
+  echo "$last" | grep -q "package=@test/zeta"
+}
+
+# ── Mixed grammar — non-WR-ADR-049 bins ignored ─────────────────────────────
+
+@test "check-tarball-shipped-shims: legacy bin (non-WR-ADR-049 grammar) alongside grammar shim — only grammar shim checked" {
+  write_package_json "alpha" '["bin/"]'
+  write_non_grammar_bin "alpha" "windyroad-alpha"
+  write_adr049_shim "alpha" "broken"
+  write_script "alpha" "broken"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q "windyroad-alpha"
+  echo "$output" | grep -E "^TARBALL_DRIFT package=@test/alpha shim=bin/wr-alpha-broken target=scripts/broken.sh tarball-status=missing$"
+}
+
+# ── Pre-check error path ────────────────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: missing root dir exits 2" {
+  run "$SCRIPT" "/nonexistent/path/$$"
+  [ "$status" -eq 2 ]
+}
+
+# ── Silent-on-pass invariant ────────────────────────────────────────────────
+
+@test "check-tarball-shipped-shims: no TOTAL line emitted when output is empty" {
+  write_package_json "alpha" '["bin/", "scripts/"]'
+  write_adr049_shim "alpha" "good"
+  write_script "alpha" "good"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/scripts/test/check-tickets-deferred-cause.bats

@@ -0,0 +1,330 @@
+#!/usr/bin/env bats
+#
+# packages/retrospective/scripts/test/check-tickets-deferred-cause.bats
+#
+# Behavioural tests for `check-tickets-deferred-cause.sh` — the
+# Tickets Deferred cause-allowlist advisory script (P148). Mirrors
+# the fixture-based test pattern of `check-ask-hygiene.bats`.
+#
+# Tests are behavioural per ADR-005 / ADR-037 / P081 — they exercise
+# the script end-to-end against fixture retro summary directories
+# and assert on stdout / stderr / exit shape. No structural greps of
+# the script source itself.
+#
+# @problem P148 (Agent defers ticket creation — broadens Stage 1 fallback gate)
+# @problem P081 (Structural-content tests are wasteful — behavioural preferred)
+# @adr ADR-044 (Decision-Delegation Contract)
+# @adr ADR-040 (Tier 3 advisory-not-fail-closed)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe)
+# @adr ADR-005 / ADR-037 (Plugin testing strategy — behavioural tests)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-201
+
+SCRIPT="${BATS_TEST_DIRNAME}/../check-tickets-deferred-cause.sh"
+
+setup() {
+  TEST_DIR="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$TEST_DIR"
+}
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+@test "script file exists and is executable" {
+  [ -f "$SCRIPT" ]
+  [ -x "$SCRIPT" ]
+}
+
+@test "missing retros dir exits 2 with error message on stderr" {
+  run bash "$SCRIPT" "$TEST_DIR/does-not-exist"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"retros dir not found"* ]]
+}
+
+@test "empty retros dir exits 0 with empty stdout" {
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "default retros-dir argument is docs/retros (when omitted)" {
+  cd "$TEST_DIR"
+  run bash "$SCRIPT"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"docs/retros"* ]]
+}
+
+# ── No-defer steady state ───────────────────────────────────────────────────
+
+@test "retro file with no Tickets Deferred section emits no output" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+## Session Retrospective
+
+### Briefing Changes
+- Added: foo
+
+### Problems Created/Updated
+- P148: opened
+
+### No Action Needed
+- learning captured
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Good fixture (skill_unavailable cause) ──────────────────────────────────
+
+@test "good fixture: skill_unavailable cause → 0 violations" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+## Session Retrospective
+
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| Polling regex deadlock observation | `skill_unavailable` | Step 2b detection |
+| SIGTERM flush caveat | `skill_unavailable` | Step 4a verification |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred=2"* ]]
+  [[ "$output" == *"with_valid_cause=2"* ]]
+  [[ "$output" == *"violations=0"* ]]
+}
+
+# ── Bad fixture (session_pressure cause — the P148 anti-pattern) ────────────
+
+@test "bad fixture: session_pressure cause → all entries are violations" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+## Session Retrospective
+
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| Polling regex deadlock | `session_pressure` | Step 2b |
+| SIGTERM flush caveat | `context_heavyweight` | Step 4a |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred=2"* ]]
+  [[ "$output" == *"with_valid_cause=0"* ]]
+  [[ "$output" == *"violations=2"* ]]
+}
+
+# ── Legacy fixture (no Cause column — pre-P148 retro shape) ─────────────────
+
+@test "legacy fixture: no Cause column → all entries are violations" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+## Session Retrospective
+
+### Tickets Deferred
+
+| Observation | Citation |
+|-------------|----------|
+| Polling regex deadlock | Step 2b |
+| SIGTERM flush caveat | Step 4a |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred=2"* ]]
+  [[ "$output" == *"violations=2"* ]]
+}
+
+@test "legacy fixture exit code is 0 — advisory contract holds for AFK safety" {
+  # JTBD-006 line 32 (extended AFK safety): legacy retros lacking the Cause
+  # column would break AFK loops if exit code went non-zero. Fail-closed
+  # escalation belongs at a future hook tier per P135 R6 trajectory, not
+  # at the script.
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Citation |
+|-------------|----------|
+| obs1 | step1 |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+}
+
+# ── Mixed fixture ───────────────────────────────────────────────────────────
+
+@test "mixed fixture: one valid + one invalid → violations=1, with_valid_cause=1" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| Valid observation | `skill_unavailable` | Step 2b |
+| Invalid observation | `session_pressure` | Step 4a |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred=2"* ]]
+  [[ "$output" == *"with_valid_cause=1"* ]]
+  [[ "$output" == *"violations=1"* ]]
+}
+
+# ── Empty Cause cell ────────────────────────────────────────────────────────
+
+@test "empty Cause cell counts as a violation (cause-required invariant)" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| Observation with empty cause |   | Step 2b |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"violations=1"* ]]
+}
+
+# ── Format tolerance ────────────────────────────────────────────────────────
+
+@test "Cause cell tolerates surrounding whitespace and bold markers" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| obs1 |    `skill_unavailable`    | Step 2b |
+| obs2 | **skill_unavailable** | Step 4a |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deferred=2"* ]]
+  [[ "$output" == *"with_valid_cause=2"* ]]
+  [[ "$output" == *"violations=0"* ]]
+}
+
+@test "placeholder template row is skipped — not counted as a deferred entry" {
+  # The retro summary template includes a placeholder example row in the
+  # SKILL.md template (with `<one-line observation summary>` literal text).
+  # When a retro is rendered with no real deferred entries, the template
+  # row may persist; the script must NOT count it as a real deferred
+  # observation.
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| <one-line observation summary> | `skill_unavailable` | <retro-step-citation> |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Multi-file behaviour ────────────────────────────────────────────────────
+
+@test "multiple retro files emit per-file lines plus a TOTAL summary line" {
+  cat > "$TEST_DIR/2026-04-25-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| good obs | `skill_unavailable` | Step 2b |
+RETRO
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| bad obs | `session_pressure` | Step 4a |
+RETRO
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RETRO 2026-04-25"* ]]
+  [[ "$output" == *"RETRO 2026-04-29"* ]]
+  [[ "$output" == *"TOTAL files=2 deferred=2 with_valid_cause=1 violations=1"* ]]
+}
+
+@test "files sorted oldest-first by date prefix" {
+  for d in 27 25 26; do
+    cat > "$TEST_DIR/2026-04-$d-retro.md" <<RETRO
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| obs$d | \`skill_unavailable\` | Step$d |
+RETRO
+  done
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  line1="${lines[0]}"
+  line2="${lines[1]}"
+  line3="${lines[2]}"
+  [[ "$line1" == *"2026-04-25"* ]]
+  [[ "$line2" == *"2026-04-26"* ]]
+  [[ "$line3" == *"2026-04-27"* ]]
+}
+
+# ── File-type filtering ─────────────────────────────────────────────────────
+
+@test "ask-hygiene trail files are skipped (not retro summaries)" {
+  cat > "$TEST_DIR/2026-04-29-ask-hygiene.md" <<'TRAIL'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| should be ignored | `session_pressure` | irrelevant |
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "context-analysis files are skipped (not retro summaries)" {
+  cat > "$TEST_DIR/2026-04-29-context-analysis.md" <<'CTX'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| should be ignored | `session_pressure` | irrelevant |
+CTX
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "files without a YYYY-MM-DD date prefix are skipped" {
+  cat > "$TEST_DIR/README.md" <<'RM'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| should be ignored | `session_pressure` | irrelevant |
+RM
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Cross-shell portability (P124 / P133 lessons) ───────────────────────────
+
+@test "script glob iteration uses portable for-loop existence check" {
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"*.md"* ]]
+}
+
+# ── Read-only contract ──────────────────────────────────────────────────────
+
+@test "script is read-only — fixture tree unchanged after run" {
+  cat > "$TEST_DIR/2026-04-29-retro.md" <<'RETRO'
+### Tickets Deferred
+
+| Observation | Cause | Citation |
+|-------------|-------|----------|
+| obs1 | `skill_unavailable` | Step 2b |
+RETRO
+  pre_hash=$(find "$TEST_DIR" -type f -exec cksum {} \; 2>/dev/null | sort | cksum | awk '{print $1}')
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  post_hash=$(find "$TEST_DIR" -type f -exec cksum {} \; 2>/dev/null | sort | cksum | awk '{print $1}')
+  [ "$pre_hash" = "$post_hash" ]
+}