@windyroad/retrospective 0.16.0 → 0.17.0-preview.277

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

package/scripts/measure-context-budget.sh

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/measure-context-budget.sh
+#
+# Read-only diagnostic script for context-usage measurement (P101 / ADR-043
+# Progressive context-usage measurement and reporting for retrospective sessions).
+# Walks the session's on-disk context contributors and reports per-source
+# bucket byte totals so run-retro Step 2c can render the cheap-layer table
+# (interactive or AFK; same output shape) and the deep-layer skill can
+# consume the same data as its baseline.
+#
+# Usage:
+#   measure-context-budget.sh [<project-root>]
+#
+# Default <project-root> is $CLAUDE_PROJECT_DIR if set, else the current
+# working directory.
+#
+# Threshold for the optional fail-open ceiling is read from
+# CONTEXT_BUDGET_MAX_BYTES (default 10240 — the 5% / 200K cheap-layer
+# envelope per ADR-043). The script does NOT enforce the threshold; it
+# is exposed for the bats fixture and for Step 2c's defensive trip.
+#
+# Exit codes:
+#   0 = always (advisory only — overflow is signal, not failure)
+#   2 = parse error (project root missing or unreadable)
+#
+# Output format (one line per bucket, terse machine-readable per ADR-038
+# progressive-disclosure budget — ≤150 bytes per row):
+#   BUCKET <name> bytes=<N>
+#   BUCKET <name> not-measured reason=<reason>
+#
+# The output is sorted by bucket name for stable diffs (per the
+# check-briefing-budgets.sh precedent + bats fixture contract).
+#
+# Read-only — does NOT mutate any project file. Snapshot persistence
+# (HTML-comment trailer in docs/retros/<date>-context-analysis.md) is the
+# deep-layer skill's responsibility, not this script's.
+#
+# @problem P101
+# @adr ADR-043 (Progressive context-usage measurement and reporting for
+#   retrospective sessions; this script is the measurement primitive)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-026 (Agent output grounding — explicit not-measured sentinels
+#   for surfaces without an on-disk source)
+# @adr ADR-013 (Rule 1 / Rule 6 — interactive vs AFK; this script's
+#   advisory exit-0 contract supports both)
+# @adr ADR-005 (Plugin testing strategy)
+# @adr ADR-037 (Skill testing strategy — bats-contract precedent)
+# @jtbd JTBD-001 / JTBD-005 / JTBD-006
+
+set -uo pipefail
+
+PROJECT_ROOT="${1:-${CLAUDE_PROJECT_DIR:-$(pwd)}}"
+THRESHOLD="${CONTEXT_BUDGET_MAX_BYTES:-10240}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PROJECT_ROOT" ]; then
+  echo "measure-context-budget: project root not found: $PROJECT_ROOT" >&2
+  exit 2
+fi
+
+# Helper — sum byte sizes of files matching a glob. Returns 0 (zero bytes)
+# if the glob matches nothing, distinguishing "scanned, empty" from
+# "surface not present".
+sum_globs() {
+  local total=0
+  local file
+  for pattern in "$@"; do
+    # Use shopt nullglob so an empty match expands to nothing
+    shopt -s nullglob
+    local matches=( $pattern )
+    shopt -u nullglob
+    for file in "${matches[@]}"; do
+      if [ -f "$file" ] && [ -r "$file" ]; then
+        local bytes
+        bytes=$(wc -c < "$file" 2>/dev/null | tr -d ' ')
+        total=$(( total + ${bytes:-0} ))
+      fi
+    done
+  done
+  echo "$total"
+}
+
+# Helper — emit one bucket row. Use a "not-measured" sentinel when the
+# surface is absent (e.g. project has no docs/jtbd/) per ADR-026's
+# ungrounded-field rule.
+emit_bucket() {
+  local name="$1"
+  local bytes="$2"
+  local present="$3"  # 1 if surface present, 0 if absent
+  local reason="${4:-source-absent}"
+  if [ "$present" = "1" ]; then
+    echo "BUCKET $name bytes=$bytes"
+  else
+    echo "BUCKET $name not-measured reason=$reason"
+  fi
+}
+
+# ── Bucket: hooks ───────────────────────────────────────────────────────────
+# Aggregate over packages/*/hooks/**/*.sh + project-local .claude/hooks/**/*.sh
+# Surface present if either exists.
+
+hooks_present=0
+if [ -d "$PROJECT_ROOT/packages" ] || [ -d "$PROJECT_ROOT/.claude/hooks" ]; then
+  hooks_present=1
+fi
+
+if [ "$hooks_present" = "1" ]; then
+  hooks_bytes=$(
+    cd "$PROJECT_ROOT" 2>/dev/null && {
+      shopt -s nullglob globstar
+      pkg_files=( packages/*/hooks/**/*.sh )
+      proj_files=( .claude/hooks/**/*.sh )
+      shopt -u nullglob globstar
+      total=0
+      for f in "${pkg_files[@]}" "${proj_files[@]}"; do
+        if [ -f "$f" ] && [ -r "$f" ]; then
+          b=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+          total=$(( total + ${b:-0} ))
+        fi
+      done
+      echo "$total"
+    }
+  )
+fi
+emit_bucket hooks "${hooks_bytes:-0}" "$hooks_present"
+
+# ── Bucket: skills ──────────────────────────────────────────────────────────
+# Aggregate over packages/*/skills/**/SKILL.md + .claude/skills/**/SKILL.md
+
+skills_present=0
+if [ -d "$PROJECT_ROOT/packages" ] || [ -d "$PROJECT_ROOT/.claude/skills" ]; then
+  skills_present=1
+fi
+
+if [ "$skills_present" = "1" ]; then
+  skills_bytes=$(
+    cd "$PROJECT_ROOT" 2>/dev/null && {
+      shopt -s nullglob globstar
+      pkg_files=( packages/*/skills/**/SKILL.md )
+      proj_files=( .claude/skills/**/SKILL.md )
+      shopt -u nullglob globstar
+      total=0
+      for f in "${pkg_files[@]}" "${proj_files[@]}"; do
+        if [ -f "$f" ] && [ -r "$f" ]; then
+          b=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+          total=$(( total + ${b:-0} ))
+        fi
+      done
+      echo "$total"
+    }
+  )
+fi
+emit_bucket skills "${skills_bytes:-0}" "$skills_present"
+
+# ── Bucket: briefing ────────────────────────────────────────────────────────
+# Aggregate over docs/briefing/*.md (top-level only; nested archives are
+# the deep layer's concern). Single bucket row aggregating per-file detail
+# already exposed via P099's check-briefing-budgets.sh.
+
+briefing_dir="$PROJECT_ROOT/docs/briefing"
+briefing_present=0
+briefing_bytes=0
+if [ -d "$briefing_dir" ]; then
+  briefing_present=1
+  briefing_bytes=$( cd "$PROJECT_ROOT" && sum_globs "docs/briefing/*.md" )
+fi
+emit_bucket briefing "$briefing_bytes" "$briefing_present"
+
+# ── Bucket: decisions ───────────────────────────────────────────────────────
+
+decisions_dir="$PROJECT_ROOT/docs/decisions"
+decisions_present=0
+decisions_bytes=0
+if [ -d "$decisions_dir" ]; then
+  decisions_present=1
+  decisions_bytes=$( cd "$PROJECT_ROOT" && sum_globs "docs/decisions/*.md" )
+fi
+emit_bucket decisions "$decisions_bytes" "$decisions_present"
+
+# ── Bucket: problems ────────────────────────────────────────────────────────
+
+problems_dir="$PROJECT_ROOT/docs/problems"
+problems_present=0
+problems_bytes=0
+if [ -d "$problems_dir" ]; then
+  problems_present=1
+  problems_bytes=$( cd "$PROJECT_ROOT" && sum_globs "docs/problems/*.md" )
+fi
+emit_bucket problems "$problems_bytes" "$problems_present"
+
+# ── Bucket: jtbd ────────────────────────────────────────────────────────────
+
+jtbd_dir="$PROJECT_ROOT/docs/jtbd"
+jtbd_present=0
+jtbd_bytes=0
+if [ -d "$jtbd_dir" ]; then
+  jtbd_present=1
+  jtbd_bytes=$(
+    cd "$PROJECT_ROOT" 2>/dev/null && {
+      shopt -s nullglob globstar
+      files=( docs/jtbd/**/*.md )
+      shopt -u nullglob globstar
+      total=0
+      for f in "${files[@]}"; do
+        if [ -f "$f" ] && [ -r "$f" ]; then
+          b=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+          total=$(( total + ${b:-0} ))
+        fi
+      done
+      echo "$total"
+    }
+  )
+fi
+emit_bucket jtbd "$jtbd_bytes" "$jtbd_present"
+
+# ── Bucket: project-claude-md ───────────────────────────────────────────────
+
+project_claude_md="$PROJECT_ROOT/CLAUDE.md"
+claude_md_present=0
+claude_md_bytes=0
+if [ -f "$project_claude_md" ] && [ -r "$project_claude_md" ]; then
+  claude_md_present=1
+  claude_md_bytes=$( wc -c < "$project_claude_md" 2>/dev/null | tr -d ' ' )
+fi
+emit_bucket project-claude-md "${claude_md_bytes:-0}" "$claude_md_present"
+
+# ── Bucket: memory ──────────────────────────────────────────────────────────
+# User-owned per-project memory files. Read-only attempt; emit not-measured
+# sentinel when the directory is inaccessible (e.g. the running agent is
+# in a different user account or the path doesn't exist for this project).
+
+memory_root="${HOME:-/tmp}/.claude/projects"
+memory_present=0
+memory_bytes=0
+if [ -d "$memory_root" ] && [ -r "$memory_root" ]; then
+  # Best-effort: sum *.md files under any subdirectory of memory_root.
+  # Per-project filtering is the deep layer's concern.
+  memory_present=1
+  shopt -s nullglob globstar
+  mem_files=( "$memory_root"/**/memory/*.md )
+  shopt -u nullglob globstar
+  for f in "${mem_files[@]}"; do
+    if [ -f "$f" ] && [ -r "$f" ]; then
+      b=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+      memory_bytes=$(( memory_bytes + ${b:-0} ))
+    fi
+  done
+fi
+if [ "$memory_present" = "1" ]; then
+  emit_bucket memory "$memory_bytes" 1
+else
+  emit_bucket memory 0 0 user-memory-inaccessible
+fi
+
+# ── Bucket: framework-injected ──────────────────────────────────────────────
+# Available-skills, subagent-types, deferred-tools listings are emitted by
+# the framework on every turn but are NOT byte-countable from the project
+# filesystem. Per ADR-026 ungrounded-field rule, emit explicit sentinel.
+
+emit_bucket framework-injected 0 0 framework-injected-no-on-disk-source
+
+# ── Done ────────────────────────────────────────────────────────────────────
+# Threshold is exposed for callers (Step 2c defensive trip + bats fixture).
+# Echoed as a trailing diagnostic line — callers can grep for `THRESHOLD `
+# to retrieve it without parsing every BUCKET row.
+
+echo "THRESHOLD bytes=$THRESHOLD"
+
+exit 0

package/scripts/test/check-ask-hygiene.bats

@@ -0,0 +1,248 @@
+#!/usr/bin/env bats
+#
+# packages/retrospective/scripts/test/check-ask-hygiene.bats
+#
+# Behavioural tests for `check-ask-hygiene.sh` — the ask-hygiene trail
+# advisory script (P135 Phase 5 / ADR-044). Mirrors the test pattern of
+# `check-briefing-budgets.bats`.
+#
+# Tests are behavioural per ADR-005 / ADR-037 — they exercise the
+# script end-to-end against fixture trail directories and assert on
+# stdout / stderr / exit shape. No structural greps of the script
+# source itself per ADR-044's deviation-default to behavioural-by-
+# default for skill / script testing.
+#
+# @problem P135 (Phase 5 measurement)
+# @adr ADR-044 (Decision-Delegation Contract — lazy-count metric)
+# @adr ADR-040 (Tier 3 advisory-not-fail-closed)
+# @adr ADR-005 / ADR-037 (Plugin testing strategy — behavioural tests)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-201
+
+SCRIPT="${BATS_TEST_DIRNAME}/../check-ask-hygiene.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)" {
+  # Behavioural: script must accept no-arg invocation when invoked from a project root.
+  # We exercise from a fresh tmp dir with no docs/retros to assert the missing-dir
+  # behaviour fires when the default path is used.
+  cd "$TEST_DIR"
+  run bash "$SCRIPT"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"docs/retros"* ]]
+}
+
+# ── Single-entry behaviour ──────────────────────────────────────────────────
+
+@test "single trail entry emits one RETRO line and no TREND" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 5**
+**Direction count: 2**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RETRO 2026-04-27 lazy=5 direction=2"* ]]
+  [[ "$output" != *"TREND"* ]]
+}
+
+@test "trail entry without lazy-count line is skipped silently" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+# Some retro file with no lazy count
+**Direction count: 3**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Multi-entry behaviour ───────────────────────────────────────────────────
+
+@test "multiple trail entries emit RETRO lines sorted oldest-first by date" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 1**
+TRAIL
+  cat > "$TEST_DIR/2026-04-25-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 5**
+TRAIL
+  cat > "$TEST_DIR/2026-04-26-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 3**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  # Assert order: 04-25 (oldest) → 04-26 → 04-27 (newest)
+  line1="${lines[0]}"
+  line2="${lines[1]}"
+  line3="${lines[2]}"
+  [[ "$line1" == *"2026-04-25"* ]]
+  [[ "$line2" == *"2026-04-26"* ]]
+  [[ "$line3" == *"2026-04-27"* ]]
+}
+
+@test "two-or-more entries emit TREND line with first/last/delta" {
+  cat > "$TEST_DIR/2026-04-25-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 5**
+TRAIL
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 1**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"TREND lazy_first=5 lazy_last=1 delta=-4"* ]]
+}
+
+@test "TREND line shows positive delta when lazy count grew" {
+  cat > "$TEST_DIR/2026-04-25-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 1**
+TRAIL
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 4**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"TREND lazy_first=1 lazy_last=4 delta=+3"* ]]
+}
+
+@test "TREND line shows zero delta when lazy count unchanged" {
+  cat > "$TEST_DIR/2026-04-25-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 2**
+TRAIL
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 2**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"TREND lazy_first=2 lazy_last=2 delta=+0"* ]]
+}
+
+# ── Window override ──────────────────────────────────────────────────────────
+
+@test "ASK_HYGIENE_WINDOW=2 keeps only the most-recent 2 entries" {
+  for d in 25 26 27; do
+    cat > "$TEST_DIR/2026-04-$d-ask-hygiene.md" <<TRAIL
+**Lazy count: $d**
+TRAIL
+  done
+  ASK_HYGIENE_WINDOW=2 run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  # Assert: 04-25 not present; 04-26 first; 04-27 last
+  [[ "$output" != *"2026-04-25"* ]]
+  [[ "$output" == *"RETRO 2026-04-26"* ]]
+  [[ "$output" == *"RETRO 2026-04-27"* ]]
+  # TREND should reflect the windowed pair, not the full 3
+  [[ "$output" == *"TREND lazy_first=26 lazy_last=27 delta=+1"* ]]
+}
+
+@test "default window 10 keeps all entries when fewer than 10 exist" {
+  cat > "$TEST_DIR/2026-04-25-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 5**
+TRAIL
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 1**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"2026-04-25"* ]]
+  [[ "$output" == *"2026-04-27"* ]]
+}
+
+# ── Category-coverage shape ──────────────────────────────────────────────────
+
+@test "RETRO line includes all 6 category counts (lazy + 5 non-lazy)" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 0**
+**Direction count: 3**
+**Override count: 1**
+**Silent-framework count: 1**
+**Taste count: 0**
+**Correction-followup count: 0**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"lazy=0"* ]]
+  [[ "$output" == *"direction=3"* ]]
+  [[ "$output" == *"override=1"* ]]
+  [[ "$output" == *"silent=1"* ]]
+  [[ "$output" == *"taste=0"* ]]
+  [[ "$output" == *"correction=0"* ]]
+}
+
+@test "missing non-lazy categories default to 0" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 4**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"lazy=4"* ]]
+  [[ "$output" == *"direction=0"* ]]
+  [[ "$output" == *"override=0"* ]]
+  [[ "$output" == *"silent=0"* ]]
+}
+
+# ── Format tolerance ──────────────────────────────────────────────────────────
+
+@test "lazy-count line works without bold markdown asterisks" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+Lazy count: 7
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"lazy=7"* ]]
+}
+
+@test "lazy-count line is case-insensitive on the LAZY label" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**lazy count: 8**
+TRAIL
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"lazy=8"* ]]
+}
+
+# ── Cross-shell portability (P124 / P133 lessons) ───────────────────────────
+
+@test "script glob iteration uses portable for-loop existence check (no shopt nullglob)" {
+  # Behavioural: invoking an empty retros dir must NOT emit a literal
+  # `*-ask-hygiene.md` because the glob unexpanded to a literal pattern.
+  # The script's portable iteration handles this without zsh `shopt -s nullglob`.
+  run bash "$SCRIPT" "$TEST_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"*-ask-hygiene.md"* ]]
+}
+
+# ── Read-only contract ──────────────────────────────────────────────────────
+
+@test "script is read-only — fixture tree unchanged after run" {
+  cat > "$TEST_DIR/2026-04-27-ask-hygiene.md" <<'TRAIL'
+**Lazy count: 3**
+TRAIL
+  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" ]
+}