@windyroad/retrospective 0.16.0 → 0.17.0-preview.277

package/scripts/test/check-briefing-budgets.bats

@@ -0,0 +1,307 @@
+#!/usr/bin/env bats
+
+# @problem P099 — docs/briefing/<topic>.md (Tier 3 of ADR-040) accumulates
+# without rotation. ADR-040 names a 2-5 KB / topic ceiling but the budget
+# was informational only. P099 promotes Tier 3 to advisory enforcement: a
+# read-only diagnostic script surfaces topic files over the configured
+# ceiling so run-retro Step 3 can route them through the rotation
+# AskUserQuestion (interactive) or defer to the retro summary (AFK).
+#
+# Contract: `check-briefing-budgets.sh [<briefing-dir>]` is a diagnose-only
+# advisory script. It walks `<briefing-dir>/<topic>.md` files (default
+# `docs/briefing`), measures byte size per file, and reports each topic
+# file whose size is at or above the threshold (default 5120 bytes,
+# overridable via BRIEFING_TIER3_MAX_BYTES env var).
+#
+# 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>
+#
+# 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.
+#
+# The script is read-only — it does NOT mutate any briefing file.
+# Rotation candidates are surfaced to the user via run-retro Step 3
+# (AskUserQuestion interactive path or retro-summary AFK fallback).
+#
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — AFK-safe advisory)
+# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — read-only,
+#   no interactive friction on the happy path; cost amortised across
+#   every subsequent topic-file load)
+# @jtbd JTBD-101 (Extend the Suite with Clear Patterns — reusable
+#   advisory-script + bats + ADR-amendment shape for accumulator surfaces)
+#
+# Cross-reference:
+#   P099: docs/problems/099-briefing-md-grows-unbounded-via-run-retro-appends-violating-progressive-disclosure.open.md
+#   ADR-040 — Session-start briefing surface (Tier 3 budget; this script
+#     promotes Tier 3 from informational to advisory enforcement)
+#   ADR-038 — Progressive disclosure (per-row byte budget on diff output)
+#   ADR-013 Rule 1 / Rule 6 — interactive AskUserQuestion path / AFK fallback
+#   ADR-005 — Plugin testing strategy (script-level bats governance)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-briefing-budgets.sh"
+  FIXTURE_DIR="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_DIR"
+}
+
+# Helper: write a markdown file with N bytes of body content. The header
+# adds a small constant overhead; body fills to roughly the requested
+# size so the total file size approximates the requested target.
+write_briefing_entry() {
+  local path="$1"
+  local target_bytes="$2"
+  : > "$path"
+  printf '# Topic\n\n' >> "$path"
+  local header_size=$(wc -c < "$path" | tr -d ' ')
+  local body_target=$(( target_bytes - header_size ))
+  if [ "$body_target" -gt 0 ]; then
+    # Repeated 80-byte line keeps things readable
+    local line="- entry text padded out to a known length for byte-budget testing.   "
+    local line_size=${#line}
+    line+=$'\n'
+    local line_count=$(( (body_target + line_size) / (line_size + 1) ))
+    local i=0
+    while [ "$i" -lt "$line_count" ]; do
+      printf '%s' "$line" >> "$path"
+      i=$(( i + 1 ))
+    done
+  fi
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "check-briefing-budgets: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "check-briefing-budgets: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Default-threshold behaviour (5120 bytes per ADR-040 Tier 3 ceiling) ─────
+
+@test "check-briefing-budgets: empty briefing dir produces no output and exits 0" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-briefing-budgets: all files under threshold produces no output" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/small-topic.md" 1024
+  write_briefing_entry "$FIXTURE_DIR/briefing/medium-topic.md" 3000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-briefing-budgets: file over threshold emits OVER line with bytes + threshold" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/bloated-topic.md" 10000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER bloated-topic.md bytes=[0-9]+ threshold=5120$"
+}
+
+@test "check-briefing-budgets: file exactly at threshold emits OVER (>= boundary)" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # Create a file exactly 5120 bytes
+  printf '%.0s.' $(seq 1 5120) > "$FIXTURE_DIR/briefing/edge.md"
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER edge.md bytes=5120 threshold=5120$"
+}
+
+@test "check-briefing-budgets: only over-threshold files appear in output" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/under.md" 2000
+  write_briefing_entry "$FIXTURE_DIR/briefing/over-one.md" 8000
+  write_briefing_entry "$FIXTURE_DIR/briefing/over-two.md" 12000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  # Both over-files present
+  echo "$output" | grep -E "^OVER over-one.md bytes=[0-9]+ threshold=5120$"
+  echo "$output" | grep -E "^OVER over-two.md bytes=[0-9]+ threshold=5120$"
+  # Under-file absent
+  ! echo "$output" | grep -q "under.md"
+}
+
+@test "check-briefing-budgets: README.md is excluded from the scan (Tier 2 not Tier 3)" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # Bloated README that would otherwise trip the threshold
+  write_briefing_entry "$FIXTURE_DIR/briefing/README.md" 20000
+  write_briefing_entry "$FIXTURE_DIR/briefing/topic.md" 3000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Configurable threshold via env var ──────────────────────────────────────
+
+@test "check-briefing-budgets: BRIEFING_TIER3_MAX_BYTES env var overrides default" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/topic.md" 3000
+  # Default 5120: under threshold, no output. With env var set to 2000:
+  # over threshold, expect OVER line.
+  BRIEFING_TIER3_MAX_BYTES=2000 run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER topic.md bytes=[0-9]+ threshold=2000$"
+}
+
+@test "check-briefing-budgets: env var threshold of 0 emits every file (sanity)" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/a.md" 100
+  write_briefing_entry "$FIXTURE_DIR/briefing/b.md" 200
+  BRIEFING_TIER3_MAX_BYTES=0 run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q "OVER a.md "
+  echo "$output" | grep -q "OVER b.md "
+}
+
+# ── Argument and error handling ─────────────────────────────────────────────
+
+@test "check-briefing-budgets: defaults to docs/briefing when no arg provided" {
+  cd "$FIXTURE_DIR"
+  mkdir -p docs/briefing
+  write_briefing_entry "docs/briefing/big.md" 10000
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER big.md bytes=[0-9]+ threshold=5120$"
+}
+
+@test "check-briefing-budgets: missing briefing dir exits 2 with parse error on stderr" {
+  run "$SCRIPT" "$FIXTURE_DIR/does-not-exist"
+  [ "$status" -eq 2 ]
+  echo "$output" | grep -iE "not found|missing|does not exist"
+}
+
+@test "check-briefing-budgets: ignores non-markdown files in the briefing dir" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # Bloated non-markdown (e.g. a stray log) should not trip the scan
+  printf '%.0s.' $(seq 1 20000) > "$FIXTURE_DIR/briefing/stray.txt"
+  write_briefing_entry "$FIXTURE_DIR/briefing/topic.md" 1000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Output stability ────────────────────────────────────────────────────────
+
+@test "check-briefing-budgets: output is sorted by filename for stable diffs" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/zebra.md" 8000
+  write_briefing_entry "$FIXTURE_DIR/briefing/alpha.md" 8000
+  write_briefing_entry "$FIXTURE_DIR/briefing/middle.md" 8000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  # First line is alpha, last is zebra
+  first_line=$(echo "$output" | head -1)
+  last_line=$(echo "$output" | tail -1)
+  echo "$first_line" | grep -q "alpha.md"
+  echo "$last_line" | grep -q "zebra.md"
+}
+
+# ── MUST_SPLIT signal (P145) ────────────────────────────────────────────────
+#
+# Files at ratio >= 2.0x the threshold also emit a MUST_SPLIT line that
+# names the same basename and a `reason=` code. This promotes ADR-040's
+# Tier 3 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. 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.
+#
+# Output format on >= 2x ratio (one line per file, in addition to the
+# existing OVER line):
+#   MUST_SPLIT <basename> reason=<code>
+#
+# @problem P145
+
+@test "check-briefing-budgets: file at exactly 2x threshold emits MUST_SPLIT" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # Exactly 10240 bytes = 2.0x of 5120 default threshold
+  printf '%.0s.' $(seq 1 10240) > "$FIXTURE_DIR/briefing/exactly-2x.md"
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^MUST_SPLIT exactly-2x.md reason=ratio-exceeds-2x$"
+}
+
+@test "check-briefing-budgets: file just under 2x does NOT emit MUST_SPLIT" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # 10239 bytes = 1.9998x of 5120 — under the 2.0x trigger
+  printf '%.0s.' $(seq 1 10239) > "$FIXTURE_DIR/briefing/just-under-2x.md"
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  # OVER line still fires (>= threshold)
+  echo "$output" | grep -E "^OVER just-under-2x.md bytes=10239 threshold=5120"
+  # MUST_SPLIT does NOT fire (< 2x ratio)
+  ! echo "$output" | grep -q "MUST_SPLIT"
+}
+
+@test "check-briefing-budgets: file well over 2x emits both OVER and MUST_SPLIT" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # 4.0x ceiling — mirrors today's afk-subprocess.md state
+  write_briefing_entry "$FIXTURE_DIR/briefing/very-bloated.md" 20480
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER very-bloated.md bytes=[0-9]+ threshold=5120"
+  echo "$output" | grep -E "^MUST_SPLIT very-bloated.md reason=ratio-exceeds-2x$"
+}
+
+@test "check-briefing-budgets: file under threshold emits NEITHER OVER nor MUST_SPLIT" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  write_briefing_entry "$FIXTURE_DIR/briefing/small.md" 4096
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q "small.md"
+  ! echo "$output" | grep -q "MUST_SPLIT"
+}
+
+@test "check-briefing-budgets: BRIEFING_TIER3_MAX_BYTES env override flows through to MUST_SPLIT" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # 4096 bytes is 2.0x of 2048 — should trigger MUST_SPLIT under the override
+  write_briefing_entry "$FIXTURE_DIR/briefing/topic.md" 4096
+  BRIEFING_TIER3_MAX_BYTES=2048 run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER topic.md bytes=[0-9]+ threshold=2048"
+  echo "$output" | grep -E "^MUST_SPLIT topic.md reason=ratio-exceeds-2x$"
+}
+
+@test "check-briefing-budgets: mixed OVER + MUST_SPLIT output is sorted deterministically" {
+  mkdir -p "$FIXTURE_DIR/briefing"
+  # Three OVER files; two of them also MUST_SPLIT. Output must be
+  # deterministic so retro summary diffs stay stable across cycles.
+  # Contract: OVER block (sorted by basename) followed by MUST_SPLIT
+  # block (sorted by basename).
+  write_briefing_entry "$FIXTURE_DIR/briefing/zebra-over-only.md" 6000
+  write_briefing_entry "$FIXTURE_DIR/briefing/alpha-must-split.md" 12000
+  write_briefing_entry "$FIXTURE_DIR/briefing/middle-must-split.md" 15000
+  run "$SCRIPT" "$FIXTURE_DIR/briefing"
+  [ "$status" -eq 0 ]
+  # Three OVER lines — alpha first, middle next, zebra last
+  over_lines=$(echo "$output" | grep "^OVER ")
+  [ "$(echo "$over_lines" | wc -l | tr -d ' ')" = "3" ]
+  echo "$over_lines" | sed -n '1p' | grep -q "alpha-must-split.md"
+  echo "$over_lines" | sed -n '2p' | grep -q "middle-must-split.md"
+  echo "$over_lines" | sed -n '3p' | grep -q "zebra-over-only.md"
+  # Two MUST_SPLIT lines — alpha first, middle second; zebra-over-only NOT present
+  must_lines=$(echo "$output" | grep "^MUST_SPLIT ")
+  [ "$(echo "$must_lines" | wc -l | tr -d ' ')" = "2" ]
+  echo "$must_lines" | sed -n '1p' | grep -q "alpha-must-split.md"
+  echo "$must_lines" | sed -n '2p' | grep -q "middle-must-split.md"
+  ! echo "$must_lines" | grep -q "zebra-over-only.md"
+  # All OVER lines come before any MUST_SPLIT line (block ordering)
+  first_must_line_no=$(echo "$output" | grep -n "^MUST_SPLIT " | head -1 | cut -d: -f1)
+  last_over_line_no=$(echo "$output" | grep -n "^OVER " | tail -1 | cut -d: -f1)
+  [ "$last_over_line_no" -lt "$first_must_line_no" ]
+}

package/scripts/test/check-internal-id-leaks.bats

@@ -0,0 +1,286 @@
+#!/usr/bin/env bats
+
+# Behavioural fixture for the internal-ID-leak advisory detector — per
+# ADR-055 (Plugin-published artefacts use namespace-prefixed permalinks).
+#
+# Contract: `check-internal-id-leaks.sh [<root-dir>]` is a diagnose-only
+# advisory script. It walks shipped-artefact surfaces under
+# `<root-dir>/packages/*/` (default `<root-dir>` is `.`) and reports
+# bare internal-ID tokens that lack the `WR-` namespace prefix.
+#
+# Surfaces scanned:
+#   - packages/<plugin>/skills/<skill>/SKILL.md
+#   - packages/<plugin>/agents/*.md
+#   - packages/<plugin>/hooks/*.sh
+#   - packages/<plugin>/CHANGELOG.md
+#
+# Bare tokens flagged (regex):
+#   ADR-NNN  (3+ digits)
+#   JTBD-NNN (3+ digits)
+#   P-NNN or PNNN (3 digits — problem ticket form)
+#
+# Tokens that DO NOT trigger:
+#   WR-ADR-NNN, WR-JTBD-NNN, WR-P-NNN, WR-PNNN  (namespace-prefixed)
+#   docstring annotation lines beginning with `# @adr` / `# @jtbd` /
+#     `# @problem` (maintainer-facing, never expanded into adopter context)
+#   REFERENCE.md sibling files (lazy-loaded, maintainer-facing 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 (terse machine-readable per ADR-038):
+#   OVER <plugin>/<file> bare_count=<N>
+#
+# Followed by a final 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.
+#
+# Read-only — does NOT mutate any artefact. Per ADR-052, this fixture is
+# BEHAVIOURAL — it asserts script output on temp-fixture trees, NOT
+# script source content. No greps of check-internal-id-leaks.sh source.
+#
+# @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)
+# @adr ADR-052 (Behavioural-tests-default — fixture pattern)
+# @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)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-internal-id-leaks.sh"
+  FIXTURE_ROOT="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_ROOT"
+}
+
+# Helper: write a SKILL.md with given body content under fixture plugin.
+# Uses %b to interpret \n in the body argument as a real newline so test
+# fixtures can compose multi-line content inline.
+write_skill() {
+  local plugin="$1"
+  local skill="$2"
+  local body="$3"
+  local skill_dir="$FIXTURE_ROOT/packages/$plugin/skills/$skill"
+  mkdir -p "$skill_dir"
+  printf '%b\n' "$body" > "$skill_dir/SKILL.md"
+}
+
+# Helper: write an agent file with given body.
+write_agent() {
+  local plugin="$1"
+  local agent="$2"
+  local body="$3"
+  local agent_dir="$FIXTURE_ROOT/packages/$plugin/agents"
+  mkdir -p "$agent_dir"
+  printf '%b\n' "$body" > "$agent_dir/$agent.md"
+}
+
+# Helper: write a hook script with given body.
+write_hook() {
+  local plugin="$1"
+  local hook="$2"
+  local body="$3"
+  local hook_dir="$FIXTURE_ROOT/packages/$plugin/hooks"
+  mkdir -p "$hook_dir"
+  printf '%b\n' "$body" > "$hook_dir/$hook.sh"
+}
+
+# Helper: write a CHANGELOG.md with given body.
+write_changelog() {
+  local plugin="$1"
+  local body="$2"
+  local plugin_dir="$FIXTURE_ROOT/packages/$plugin"
+  mkdir -p "$plugin_dir"
+  printf '%b\n' "$body" > "$plugin_dir/CHANGELOG.md"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "check-internal-id-leaks: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Empty / clean trees ─────────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: empty tree produces no output and exits 0" {
+  mkdir -p "$FIXTURE_ROOT/packages"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: clean SKILL.md (no IDs at all) produces no output" {
+  write_skill "alpha" "clean" "# Skill\n\nThis skill has no references at all."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: SKILL.md with WR-prefixed refs only produces no output" {
+  write_skill "alpha" "wr-only" "# Skill\n\nPer WR-ADR-014 and WR-JTBD-101 and WR-P137."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Bare-ID detection across surfaces ───────────────────────────────────────
+
+@test "check-internal-id-leaks: bare ADR-NNN in SKILL.md is flagged" {
+  write_skill "alpha" "leaky" "# Skill\n\nPer ADR-014 the workflow is..."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER alpha/skills/leaky/SKILL.md bare_count=[0-9]+"
+}
+
+@test "check-internal-id-leaks: bare JTBD-NNN in SKILL.md is flagged" {
+  write_skill "alpha" "leaky" "# Skill\n\nServes JTBD-101 and JTBD-302."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER alpha/skills/leaky/SKILL.md bare_count=[0-9]+"
+}
+
+@test "check-internal-id-leaks: bare P-NNN in SKILL.md is flagged" {
+  write_skill "alpha" "leaky" "# Skill\n\nCloses P137 and P078."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER alpha/skills/leaky/SKILL.md bare_count=[0-9]+"
+}
+
+@test "check-internal-id-leaks: bare IDs in agent file are flagged" {
+  write_agent "beta" "specialist" "# Agent\n\nPer ADR-013 Rule 6 escalate."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER beta/agents/specialist.md bare_count=[0-9]+"
+}
+
+@test "check-internal-id-leaks: bare IDs in hook script body are flagged" {
+  write_hook "gamma" "guard" "#!/usr/bin/env bash\n# This deny message points at ADR-014 and P137 from prose."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER gamma/hooks/guard.sh bare_count=[0-9]+"
+}
+
+@test "check-internal-id-leaks: bare IDs in CHANGELOG.md are flagged" {
+  write_changelog "delta" "## 0.1.0\n\n- Per ADR-014 + P081 the new behaviour ships."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER delta/CHANGELOG.md bare_count=[0-9]+"
+}
+
+# ── Exclusions ──────────────────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: docstring @adr annotations on hook lines are NOT flagged" {
+  write_hook "alpha" "annotated" "#!/usr/bin/env bash\n# @adr ADR-014 (commit discipline)\n# @jtbd JTBD-101\n# @problem P137"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: REFERENCE.md sibling files are NOT scanned" {
+  local skill_dir="$FIXTURE_ROOT/packages/alpha/skills/with-ref"
+  mkdir -p "$skill_dir"
+  printf '# Skill\nClean body.\n' > "$skill_dir/SKILL.md"
+  printf '# Reference\nADR-014 is fine here.\n' > "$skill_dir/REFERENCE.md"
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Counting + summary ──────────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: bare_count matches number of bare tokens in file" {
+  write_skill "alpha" "trio" "# Skill\n\nADR-014 and JTBD-101 and P137 — three bare tokens."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER alpha/skills/trio/SKILL.md bare_count=3$"
+}
+
+@test "check-internal-id-leaks: TOTAL summary line emitted on any drift" {
+  write_skill "alpha" "leaky" "Per ADR-014 the workflow is."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TOTAL packages=1 with_leaks=1 drift_instances=1$"
+}
+
+@test "check-internal-id-leaks: TOTAL summary aggregates across files + packages" {
+  write_skill "alpha" "leaky" "Per ADR-014."
+  write_skill "alpha" "another" "JTBD-101."
+  write_agent "beta" "specialist" "P137."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^TOTAL packages=2 with_leaks=3 drift_instances=3$"
+}
+
+@test "check-internal-id-leaks: no TOTAL line emitted when output is empty" {
+  write_skill "alpha" "clean" "No bare references here."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Determinism ─────────────────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: OVER lines are sorted by package/file identifier" {
+  write_skill "zeta" "z-skill" "ADR-014."
+  write_skill "alpha" "a-skill" "ADR-014."
+  write_skill "mu" "m-skill" "ADR-014."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  local first
+  first=$(echo "$output" | grep '^OVER' | head -1)
+  echo "$first" | grep -q "alpha/skills/a-skill/SKILL.md"
+  local last
+  last=$(echo "$output" | grep '^OVER' | tail -1)
+  echo "$last" | grep -q "zeta/skills/z-skill/SKILL.md"
+}
+
+# ── Pre-check error path ────────────────────────────────────────────────────
+
+@test "check-internal-id-leaks: missing root dir exits 2" {
+  run "$SCRIPT" "/nonexistent/path/$$"
+  [ "$status" -eq 2 ]
+}
+
+# ── Boundary tokens that must NOT match ─────────────────────────────────────
+
+@test "check-internal-id-leaks: WR-prefixed token mid-sentence does not flag" {
+  write_skill "alpha" "wr-mid" "Per WR-ADR-014 — clean."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: WR-prefixed JTBD does not flag" {
+  write_skill "alpha" "wr-jtbd" "Serves WR-JTBD-302."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: standalone P3 (less than 3 digits) does not flag" {
+  write_skill "alpha" "edge" "Phase P3 of the rollout."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-internal-id-leaks: lowercase adr-014 does not flag (case-sensitive)" {
+  write_skill "alpha" "lower" "in adr-014 prose context."
+  run "$SCRIPT" "$FIXTURE_ROOT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}