@windyroad/retrospective 0.16.0-preview.273 → 0.17.0-preview.277

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-retrospective",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Session retrospective reminders and plan review for Claude Code"
 }

package/bin/wr-retrospective-check-tarball-shipped-shims

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/check-tarball-shipped-shims.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/retrospective",
-  "version": "0.16.0-preview.273",
+  "version": "0.17.0-preview.277",
   "description": "Session retrospectives that update briefings and create problem tickets",
   "bin": {
     "windyroad-retrospective": "./bin/install.mjs"
@@ -23,6 +23,7 @@
     "agents/",
     "hooks/",
     "skills/",
+    "scripts/",
     ".claude-plugin/",
     "lib/"
   ]

package/scripts/check-ask-hygiene.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-ask-hygiene.sh
+#
+# Diagnose-only advisory script for the ask-hygiene trail (per Step 2d
+# in run-retro, ADR-044 / P135 Phase 5). Walks docs/retros/*-ask-hygiene.md
+# trail files, extracts the lazy AskUserQuestion count from each, and
+# emits a tabular trend over the last N retros so the user can see
+# whether ADR-044's framework-resolution boundary is taking hold.
+#
+# Usage:
+#   check-ask-hygiene.sh [<retros-dir>]
+#
+# Default <retros-dir> is ./docs/retros.
+# Window is read from ASK_HYGIENE_WINDOW (default 10 — last N retros).
+#
+# Exit codes:
+#   0 = always (advisory only — count is signal, not failure)
+#   2 = parse error (retros dir missing or unreadable)
+#
+# Output format on populated trail (one line per retro, oldest first):
+#   RETRO <YYYY-MM-DD> lazy=<N> direction=<N> override=<N> silent=<N> taste=<N> correction=<N>
+#
+# Plus a trailing TREND line summarising first vs last lazy count
+# (when 2+ entries are in the window):
+#   TREND lazy_first=<N> lazy_last=<N> delta=<+|-N>
+#
+# Output is empty (no lines) when no retro trail entries are found —
+# this is the expected first-run state, not an error.
+#
+# Trail file shape (per Step 2d contract — written by run-retro):
+#   docs/retros/<YYYY-MM-DD>-ask-hygiene.md
+#
+# Each trail file MUST contain a single line of the shape:
+#   `Lazy count: <N>` (case-insensitive; allows a leading `**` for bold)
+#
+# And SHOULD contain matching counts for each non-lazy category:
+#   `Direction count: <N>`
+#   `Override count: <N>`
+#   `Silent-framework count: <N>`
+#   `Taste count: <N>`
+#   `Correction-followup count: <N>`
+#
+# The script tolerates missing non-lazy categories (defaults to 0).
+# The lazy-count line is the only required field; without it the file
+# is skipped silently.
+#
+# Read-only — does NOT mutate any retro file.
+#
+# @problem P135 (Phase 5 measurement)
+# @adr ADR-044 (Decision-Delegation Contract — framework-resolution boundary; lazy-count metric is the regression signal)
+# @adr ADR-040 (Tier 3 advisory-not-fail-closed — declarative-first precedent)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-026 (Cost-source grounding — trail entries cite specific tool invocations per retro)
+# @adr ADR-013 Rule 5 (Policy-authorised silent proceed — script proceeds silently per ADR-040 advisory pattern)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-201
+
+set -uo pipefail
+
+RETROS_DIR="${1:-docs/retros}"
+WINDOW="${ASK_HYGIENE_WINDOW:-10}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$RETROS_DIR" ]; then
+  echo "check-ask-hygiene: retros dir not found: $RETROS_DIR" >&2
+  exit 2
+fi
+
+# ── Scan ────────────────────────────────────────────────────────────────────
+# Iterate ask-hygiene trail files at the top level of RETROS_DIR.
+# Glob expansion uses an existence-check loop for cross-shell portability
+# (P124 lesson — bash's `shopt -s nullglob` fails on zsh).
+
+trail_files=()
+for path in "$RETROS_DIR"/*-ask-hygiene.md; do
+  [ -e "$path" ] || continue
+  trail_files+=("$path")
+done
+
+if [ "${#trail_files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Sort by basename (which starts with the YYYY-MM-DD date prefix), oldest first
+IFS=$'\n' sorted_files=($(printf '%s\n' "${trail_files[@]}" | sort))
+unset IFS
+
+# Apply the window — keep only the last N entries (most-recent N)
+total="${#sorted_files[@]}"
+if [ "$total" -gt "$WINDOW" ]; then
+  start=$(( total - WINDOW ))
+  windowed=("${sorted_files[@]:$start}")
+else
+  windowed=("${sorted_files[@]}")
+fi
+
+# Extract counts per file
+extract_count() {
+  local path="$1"
+  local label="$2"
+  local default="${3:-0}"
+  # Match lines like "Lazy count: 5" or "**Lazy count: 5**" (case-insensitive).
+  # Markdown bold is an enclosing pair, so leading **<text>: <N>** has the
+  # trailing ** AFTER the number, not after the label.
+  local match
+  match=$(grep -iE "^\*{0,2}$label count:[[:space:]]+[0-9]+" "$path" 2>/dev/null \
+    | head -1 \
+    | grep -oE '[0-9]+' \
+    | head -1)
+  if [ -z "$match" ]; then
+    echo "$default"
+  else
+    echo "$match"
+  fi
+}
+
+extract_date() {
+  local basename
+  basename="$(basename "$1")"
+  # Strip the -ask-hygiene.md suffix; what remains is the YYYY-MM-DD prefix
+  echo "${basename%-ask-hygiene.md}"
+}
+
+# Emit per-retro lines
+declare -a lazy_counts=()
+for path in "${windowed[@]}"; do
+  date=$(extract_date "$path")
+  # Lazy count is required (no default); if missing, skip the file silently.
+  # Inline rather than calling extract_count() because its `local default=...`
+  # falls back to "0" on empty (bash `${3:-0}` semantics), which would
+  # mask the "no lazy line" case.
+  lazy=$(grep -iE "^\*{0,2}Lazy count:[[:space:]]+[0-9]+" "$path" 2>/dev/null \
+    | head -1 \
+    | grep -oE '[0-9]+' \
+    | head -1)
+  if [ -z "$lazy" ]; then
+    continue
+  fi
+  # Other categories default to 0 if the trail entry omits them
+  direction=$(extract_count "$path" "Direction" "0")
+  override=$(extract_count "$path" "Override" "0")
+  silent=$(extract_count "$path" "Silent-framework" "0")
+  taste=$(extract_count "$path" "Taste" "0")
+  correction=$(extract_count "$path" "Correction-followup" "0")
+  echo "RETRO $date lazy=$lazy direction=$direction override=$override silent=$silent taste=$taste correction=$correction"
+  lazy_counts+=("$lazy")
+done
+
+# Emit trend line when 2+ entries are in the window
+if [ "${#lazy_counts[@]}" -ge 2 ]; then
+  first="${lazy_counts[0]}"
+  last="${lazy_counts[${#lazy_counts[@]}-1]}"
+  delta=$(( last - first ))
+  if [ "$delta" -ge 0 ]; then
+    delta_s="+$delta"
+  else
+    delta_s="$delta"
+  fi
+  echo "TREND lazy_first=$first lazy_last=$last delta=$delta_s"
+fi
+
+exit 0

package/scripts/check-briefing-budgets.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-briefing-budgets.sh
+#
+# Diagnose-only advisory script for the docs/briefing/ tree (Tier 3 of
+# ADR-040). Walks <briefing-dir>/<topic>.md files, measures byte size
+# per file, and reports each topic file at or above the configured
+# threshold so run-retro Step 3 can route them through the rotation
+# AskUserQuestion (interactive) or defer to the retro summary (AFK).
+#
+# Usage:
+#   check-briefing-budgets.sh [<briefing-dir>]
+#
+# Default <briefing-dir> is ./docs/briefing.
+# Threshold is read from BRIEFING_TIER3_MAX_BYTES (default 5120 — the
+# upper bound of ADR-040's stated "2-5 KB / topic" Tier 3 envelope).
+#
+# 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>
+#
+# Files at >= 2.0x the threshold also emit a second line that promotes
+# ADR-040's 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:
+#   MUST_SPLIT <basename> reason=<code>
+#
+# 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 (the trim-noise / leave-as-is fall-
+# throughs are not eligible). See P145.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   1. All OVER lines, sorted by basename.
+#   2. Then all MUST_SPLIT lines, sorted by basename.
+#
+# 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.
+#
+# Read-only — does NOT mutate any briefing file. Rotation is surfaced
+# to the user via run-retro Step 3.
+#
+# @problem P099 (initial OVER advisory)
+# @problem P145 (MUST_SPLIT escalation — closes the defer-recurrence gap)
+# @adr ADR-040 (Session-start briefing surface — Tier 3 budget; this
+#   script promotes Tier 3 from informational to advisory enforcement;
+#   MUST_SPLIT promotes the 2× reassessment trigger to per-cycle)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+# @adr ADR-013 (Rule 1 / Rule 6 — interactive vs AFK)
+# @adr ADR-044 (Decision-delegation contract — MUST_SPLIT is framework-
+#   resolved removal of the do-nothing options when ratio is decisive)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-101
+
+set -uo pipefail
+
+BRIEFING_DIR="${1:-docs/briefing}"
+THRESHOLD="${BRIEFING_TIER3_MAX_BYTES:-5120}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$BRIEFING_DIR" ]; then
+  echo "check-briefing-budgets: briefing dir not found: $BRIEFING_DIR" >&2
+  exit 2
+fi
+
+# ── Scan ────────────────────────────────────────────────────────────────────
+# Iterate markdown files at the top level of BRIEFING_DIR (not recursive).
+# Sort by basename for stable diff output (per bats fixture contract).
+
+shopt -s nullglob
+files=("$BRIEFING_DIR"/*.md)
+shopt -u nullglob
+
+if [ "${#files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# Build (basename, bytes) pairs sorted by basename.
+declare -a entries=()
+for path in "${files[@]}"; do
+  base="$(basename "$path")"
+  # README.md is the Tier 2 index, not a Tier 3 topic file.
+  if [ "$base" = "README.md" ]; then
+    continue
+  fi
+  bytes=$(wc -c < "$path" | tr -d ' ')
+  entries+=("$base $bytes")
+done
+
+# Sort entries by basename
+IFS=$'\n' sorted=($(printf '%s\n' "${entries[@]}" | sort))
+unset IFS
+
+# Pass 1: emit OVER lines for every file at or above threshold.
+# Track MUST_SPLIT candidates (ratio >= 2.0x) for pass 2.
+declare -a must_split=()
+for entry in "${sorted[@]}"; do
+  base="${entry% *}"
+  bytes="${entry##* }"
+  if [ "$bytes" -ge "$THRESHOLD" ]; then
+    echo "OVER $base bytes=$bytes threshold=$THRESHOLD"
+    # Integer-arithmetic ratio test: bytes >= 2 * threshold.
+    # Avoids float math; exact at the 2.0x boundary per ADR-040
+    # reassessment trigger.
+    if [ "$bytes" -ge "$(( THRESHOLD * 2 ))" ]; then
+      must_split+=("$base")
+    fi
+  fi
+done
+
+# Pass 2: emit MUST_SPLIT lines (already sorted by pass-1 traversal order
+# which is basename-sorted).
+for base in "${must_split[@]}"; do
+  echo "MUST_SPLIT $base reason=ratio-exceeds-2x"
+done
+
+exit 0

package/scripts/check-internal-id-leaks.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-internal-id-leaks.sh
+#
+# Diagnose-only advisory script for plugin-published internal-ID leaks per
+# ADR-055 (Plugin-published artefacts use namespace-prefixed permalinks).
+#
+# Walks shipped-artefact surfaces under `<root-dir>/packages/<plugin>/`:
+#   - skills/<skill>/SKILL.md
+#   - agents/*.md
+#   - hooks/*.sh
+#   - CHANGELOG.md
+#
+# Reports each artefact carrying bare internal-ID tokens that lack the
+# `WR-` namespace prefix. Bare tokens are tokens that resolve correctly
+# only inside the windyroad-claude-plugin source repo's docs/decisions/,
+# docs/jtbd/, and docs/problems/ trees — adopter projects either find
+# nothing (failure mode 1, benign) or resolve to UNRELATED IDs in the
+# adopter's own tree (failure mode 3, dangerous).
+#
+# Usage:
+#   check-internal-id-leaks.sh [<root-dir>]
+#
+# Default <root-dir> is `.`.
+#
+# Token forms detected (case-sensitive, word-boundary):
+#   ADR-NNN   (3+ digits)
+#   JTBD-NNN  (3+ digits)
+#   PNNN      (exactly 3 digits — problem ticket form)
+#
+# Tokens that DO NOT trigger:
+#   WR-ADR-NNN, WR-JTBD-NNN, WR-PNNN  (namespace-prefixed; the strategy)
+#   docstring annotation lines beginning with `# @adr` / `# @jtbd` /
+#     `# @problem` (maintainer-facing source annotations, never expanded
+#     into adopter agent context per ADR-055 §Scope)
+#
+# Files NOT scanned:
+#   REFERENCE.md sibling files (lazy-loaded maintainer surface 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 (one line per file with leaks, terse machine-
+# readable per ADR-038 progressive-disclosure budget):
+#   OVER <plugin>/<relative-path> bare_count=<N>
+#
+# Followed by a final aggregate 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.
+#
+# Output ordering (deterministic for stable retro-summary diffs):
+#   OVER lines sorted by `<plugin>/<relative-path>` identifier.
+#   TOTAL line last.
+#
+# Read-only — does NOT mutate any artefact. Per ADR-052, the bats fixture
+# at scripts/test/check-internal-id-leaks.bats is BEHAVIOURAL — asserts
+# script output on temp-fixture trees, NOT script source content.
+#
+# @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 discipline)
+# @adr ADR-052 (Behavioural-tests-default — fixture pattern)
+# @adr ADR-054 (SKILL.md runtime budget — REFERENCE.md exclusion source)
+# @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)
+
+set -uo pipefail
+
+ROOT_DIR="${1:-.}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$ROOT_DIR" ]; then
+  echo "check-internal-id-leaks: root dir not found: $ROOT_DIR" >&2
+  exit 2
+fi
+
+# ── Collect artefact paths ──────────────────────────────────────────────────
+
+shopt -s nullglob
+declare -a artefacts=()
+for path in "$ROOT_DIR"/packages/*/skills/*/SKILL.md; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/agents/*.md; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/hooks/*.sh; do
+  artefacts+=("$path")
+done
+for path in "$ROOT_DIR"/packages/*/CHANGELOG.md; do
+  artefacts+=("$path")
+done
+shopt -u nullglob
+
+if [ "${#artefacts[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Count bare tokens per file ──────────────────────────────────────────────
+# Algorithm (perl one-liner per file):
+#   1. Skip lines matching `^\s*#\s*@(adr|jtbd|problem)\b` (docstring annotations).
+#   2. On surviving lines, find all `(?<!WR-)\b(ADR-\d{3,}|JTBD-\d{3,}|P\d{3})\b`
+#      matches and increment a counter.
+#   3. Print the counter as a single integer.
+#
+# Negative lookbehind `(?<!WR-)` is safe in perl. Word-boundary `\b` keeps
+# `WR-ADR-014` matched only at position 3 (after `WR-`), which the
+# lookbehind then rejects. Bare `ADR-014` has start-of-string or non-WR-
+# char before, lookbehind passes, match counts.
+#
+# Word-boundary on the `P\d{3}` form requires \b on both ends so that
+# `Phase` (no digit follows) and `P3` (only 1 digit) don't match.
+
+declare -a leaks=()
+declare -A package_set=()
+declare -i total_drift=0
+
+# Strip ROOT_DIR + trailing slash for relative-path display.
+strip_root() {
+  local full="$1"
+  local prefix="$ROOT_DIR/packages/"
+  echo "${full#"$prefix"}"
+}
+
+for path in "${artefacts[@]}"; do
+  count=$(perl -ne '
+    next if /^\s*#\s*\@(adr|jtbd|problem)\b/i;
+    while (/(?<!WR-)\b(ADR-\d{3,}|JTBD-\d{3,}|P\d{3})\b/g) {
+      $n++;
+    }
+    END { print $n // 0 }
+  ' "$path")
+
+  if [ "$count" -gt 0 ]; then
+    rel="$(strip_root "$path")"
+    leaks+=("$rel $count")
+    plugin="${rel%%/*}"
+    package_set["$plugin"]=1
+    total_drift=$((total_drift + count))
+  fi
+done
+
+if [ "${#leaks[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+# ── Emit OVER lines (sorted) ────────────────────────────────────────────────
+
+IFS=$'\n' sorted=($(printf '%s\n' "${leaks[@]}" | sort))
+unset IFS
+
+for entry in "${sorted[@]}"; do
+  identifier="${entry% *}"
+  bare="${entry##* }"
+  echo "OVER $identifier bare_count=$bare"
+done
+
+# ── Emit TOTAL summary ──────────────────────────────────────────────────────
+
+echo "TOTAL packages=${#package_set[@]} with_leaks=${#leaks[@]} drift_instances=$total_drift"
+
+exit 0

package/scripts/check-readme-jtbd-currency.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-readme-jtbd-currency.sh
+#
+# Diagnose-only advisory script for ADR-051 (JTBD-anchored README rule).
+# Walks packages/*/README.md and emits a drift signal per package:
+#
+#   - has_jtbd_anchor=<yes|no>     — at least one JTBD-\d{3} match in the README
+#   - cited_jobs=<count>           — count of distinct JTBD IDs cited
+#   - known_jobs=<count>           — count of cited IDs that resolve to a current
+#                                    docs/jtbd/<persona>/JTBD-NNN-*.md (any status)
+#   - drift_hints=<comma-list>     — signal vocabulary:
+#         missing-jtbd-section     (no JTBD-\d{3} at all)
+#         stale-jtbd-citation      (cited ID has no resolving file)
+#         deprecated-jtbd-citation (cited ID resolves only to .deprecated.md / .superseded.md)
+#         skill-inventory-drift    (a directory under packages/<plugin>/skills/ is not named in README)
+#
+# Plus a trailing TOTAL line summarising the window:
+#   TOTAL packages=<N> with_jtbd=<M> drift_instances=<K>
+#
+# Exit code is always 0 — the script is advisory per ADR-013 Rule 6
+# fail-safe / ADR-040 declarative-first / ADR-051 Phase 1.
+# Drift count is emitted as data on stdout; downstream consumers
+# (run-retro Step 2b future wiring, release-pre-flight habit, Phase 2
+# escalation per ADR-051 Phase 2 criterion) decide whether to act.
+#
+# Usage:
+#   check-readme-jtbd-currency.sh [<packages-dir>] [<jtbd-dir>]
+#
+# Defaults:
+#   <packages-dir> = ./packages
+#   <jtbd-dir>     = ./docs/jtbd
+#
+# Exit codes:
+#   0 = always (advisory only — count is signal, not failure)
+#   2 = parse error (packages-dir or jtbd-dir missing or unreadable)
+#
+# Output format (one line per package, alphabetical):
+#   README package=<name> has_jtbd_anchor=<yes|no> cited_jobs=<N> known_jobs=<M> drift_hints=<csv>
+#
+# @problem P152 (No pressure or nudge for documentation currency — the driver problem)
+# @adr ADR-051 (JTBD-anchored README with declarative drift advisory — this script's normative source)
+# @adr ADR-008 (JTBD directory structure — the resolution target layout)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory script never blocks AFK)
+# @adr ADR-040 (declarative-first / advisory-then-escalate precedent)
+# @adr ADR-049 (bin/-on-PATH script resolution — paired wr-retrospective-check-readme-jtbd-currency shim)
+# @adr ADR-005 / ADR-037 (Plugin testing strategy — behavioural tests via bats)
+# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just Installed — primary served job)
+# @jtbd JTBD-007 (Keep Plugins Current Across Projects — currency expansion)
+# @jtbd JTBD-101 (Extend the Suite with New Plugins — clear patterns the detector documents)
+
+set -uo pipefail
+
+PACKAGES_DIR="${1:-packages}"
+JTBD_DIR="${2:-docs/jtbd}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PACKAGES_DIR" ]; then
+  echo "check-readme-jtbd-currency: packages dir not found: $PACKAGES_DIR" >&2
+  exit 2
+fi
+
+if [ ! -d "$JTBD_DIR" ]; then
+  echo "check-readme-jtbd-currency: jtbd dir not found: $JTBD_DIR" >&2
+  exit 2
+fi
+
+# ── Build the JTBD index ────────────────────────────────────────────────────
+# Map JTBD-NNN -> comma-separated status suffixes (proposed|validated|deprecated|superseded)
+# A JTBD ID may resolve to multiple files (e.g. during a status transition);
+# we record ALL status suffixes per ID for downstream use.
+
+declare -A JTBD_STATUS_BY_ID
+declare -A JTBD_RESOLVED
+
+for jpath in "$JTBD_DIR"/*/JTBD-*.md; do
+  [ -e "$jpath" ] || continue
+  base="$(basename "$jpath")"
+  if [[ "$base" =~ ^(JTBD-[0-9]{3})-.*\.([a-z]+)\.md$ ]]; then
+    id="${BASH_REMATCH[1]}"
+    status="${BASH_REMATCH[2]}"
+    JTBD_RESOLVED["$id"]=1
+    if [ -z "${JTBD_STATUS_BY_ID[$id]:-}" ]; then
+      JTBD_STATUS_BY_ID["$id"]="$status"
+    else
+      JTBD_STATUS_BY_ID["$id"]="${JTBD_STATUS_BY_ID[$id]},$status"
+    fi
+  fi
+done
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+append_hint() {
+  local current="$1"
+  local hint="$2"
+  if [ -z "$current" ]; then
+    echo "$hint"
+  elif [[ ",$current," == *",$hint,"* ]]; then
+    echo "$current"
+  else
+    echo "$current,$hint"
+  fi
+}
+
+is_deprecated_only() {
+  local statuses="$1"
+  IFS=',' read -ra arr <<< "$statuses"
+  for s in "${arr[@]}"; do
+    case "$s" in
+      deprecated|superseded) ;;
+      *) return 1 ;;
+    esac
+  done
+  return 0
+}
+
+# ── Scan packages ───────────────────────────────────────────────────────────
+
+total_packages=0
+total_with_jtbd=0
+total_drift_instances=0
+
+package_dirs=()
+for pdir in "$PACKAGES_DIR"/*/; do
+  [ -d "$pdir" ] || continue
+  package_dirs+=("$pdir")
+done
+
+if [ "${#package_dirs[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+IFS=$'\n' sorted_dirs=($(printf '%s\n' "${package_dirs[@]}" | sort))
+unset IFS
+
+for pdir in "${sorted_dirs[@]}"; do
+  package="$(basename "$pdir")"
+  readme="$pdir/README.md"
+
+  # Skip packages without a README — out of scope
+  [ -f "$readme" ] || continue
+
+  total_packages=$(( total_packages + 1 ))
+
+  # Extract distinct JTBD-NNN matches from the README
+  cited_ids=()
+  while IFS= read -r id; do
+    [ -z "$id" ] && continue
+    cited_ids+=("$id")
+  done < <(grep -oE 'JTBD-[0-9]{3}' "$readme" 2>/dev/null | sort -u)
+
+  cited_count="${#cited_ids[@]}"
+
+  has_anchor="no"
+  if [ "$cited_count" -gt 0 ]; then
+    has_anchor="yes"
+    total_with_jtbd=$(( total_with_jtbd + 1 ))
+  fi
+
+  hints=""
+  known_count=0
+
+  if [ "$cited_count" -eq 0 ]; then
+    hints=$(append_hint "$hints" "missing-jtbd-section")
+  else
+    has_stale=0
+    has_deprecated_only=0
+    for id in "${cited_ids[@]}"; do
+      if [ -n "${JTBD_RESOLVED[$id]:-}" ]; then
+        known_count=$(( known_count + 1 ))
+        if is_deprecated_only "${JTBD_STATUS_BY_ID[$id]}"; then
+          has_deprecated_only=1
+        fi
+      else
+        has_stale=1
+      fi
+    done
+    [ "$has_stale" -eq 1 ] && hints=$(append_hint "$hints" "stale-jtbd-citation")
+    [ "$has_deprecated_only" -eq 1 ] && hints=$(append_hint "$hints" "deprecated-jtbd-citation")
+  fi
+
+  # Soft heuristic: skill inventory drift — every directory under
+  # packages/<plugin>/skills/ should be named in the README.
+  if [ -d "$pdir/skills" ]; then
+    for sdir in "$pdir/skills"/*/; do
+      [ -d "$sdir" ] || continue
+      skill="$(basename "$sdir")"
+      if ! grep -q -F "$skill" "$readme" 2>/dev/null; then
+        hints=$(append_hint "$hints" "skill-inventory-drift")
+        break
+      fi
+    done
+  fi
+
+  # Drift instance: any non-empty hint set
+  if [ -n "$hints" ]; then
+    total_drift_instances=$(( total_drift_instances + 1 ))
+  fi
+
+  echo "README package=$package has_jtbd_anchor=$has_anchor cited_jobs=$cited_count known_jobs=$known_count drift_hints=$hints"
+done
+
+if [ "$total_packages" -gt 0 ]; then
+  echo "TOTAL packages=$total_packages with_jtbd=$total_with_jtbd drift_instances=$total_drift_instances"
+fi
+
+exit 0