@windyroad/retrospective 0.19.0 → 0.20.0

package/.claude-plugin/plugin.json

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

package/bin/wr-retrospective-check-plugin-maturity-drift

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# packages/retrospective/bin/wr-retrospective-check-plugin-maturity-drift
+#
+# ADR-049 shim — resolves the canonical body in this package's scripts/
+# dir. Phase 3b drift detector entrypoint; sibling to ADR-051's
+# `wr-retrospective-check-readme-jtbd-currency`.
+
+exec "$(dirname "$0")/../scripts/check-plugin-maturity-drift.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/retrospective",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Session retrospectives that update briefings and create problem tickets",
   "bin": {
     "windyroad-retrospective": "./bin/install.mjs"

package/scripts/check-plugin-maturity-drift.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# packages/retrospective/scripts/check-plugin-maturity-drift.sh
+#
+# Phase 3b (P087 / P238) plugin-maturity drift advisory.
+#
+# Compares each plugin's rendered README.md maturity badge against the
+# canonical `plugin.json` `maturity:` field and emits an NDJSON-shaped
+# drift signal per plugin to stdout. Sibling to ADR-051's
+# `check-readme-jtbd-currency.sh` — same detector pattern, different
+# anchor (maturity rollup vs JTBD citation), different failure mode
+# (render-vs-canonical drift vs citation drift).
+#
+# Drift hint vocabulary:
+#
+#   missing-badge        — plugin.json carries `maturity:` but the README
+#                          has no `*Maturity: ...*` prose-woven badge
+#   stale-band           — README badge band mismatches canonical record
+#   orphan-badge         — README has badge but plugin.json has no
+#                          `maturity:` field (renderer ran ahead of
+#                          populate; or populate was reverted)
+#   anti-pattern-section — README has a standalone `## Maturity` heading
+#                          (ADR-063 §"README badge rendering format"
+#                          rejects the section shape)
+#   anti-pattern-url     — README has a shields.io URL or inline SVG
+#                          (ADR-063 §F5 rejects external-dependency
+#                          rendering)
+#
+# Output format (one line per package, alphabetical):
+#   README package=<name> badge_band=<band|none> record_band=<band|none>
+#     drift_hints=<csv>
+# Plus a trailing TOTAL line:
+#   TOTAL packages=<N> drift_instances=<K>
+#
+# Exit code is always 0 — advisory only per ADR-013 Rule 6 / ADR-040
+# declarative-first / ADR-051 Phase 1 precedent. Drift count is emitted
+# as data on stdout; downstream consumers (run-retro Step 2b wiring,
+# release-pre-flight habit, Phase 4 escalation per ADR-051 Phase 2
+# criterion) decide whether to act.
+#
+# Usage:
+#   check-plugin-maturity-drift.sh [<packages-dir>]
+#
+# Default:
+#   <packages-dir> = ./packages
+#
+# Exit codes:
+#   0 = always (advisory only — count is signal, not failure)
+#   2 = parse error (packages-dir missing or unreadable)
+#
+# @problem P238 (Phase 3b — drift detector)
+# @problem P087 (parent — no maturity signal on plugin features)
+# @problem P152 (sibling drift-detector pattern — JTBD-currency)
+# @adr ADR-063 (Plugin maturity presentation layer — Phase 3b contract)
+# @adr ADR-051 (Sibling drift-detector pattern)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory exit 0)
+# @adr ADR-040 (Declarative-first / advisory-then-escalate)
+# @adr ADR-049 (Shim grammar — `wr-retrospective-check-plugin-maturity-drift`)
+# @adr ADR-052 (Behavioural tests default)
+# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just Installed)
+# @jtbd JTBD-007 (Keep Plugins Current Across Projects — maturity-band-currency
+#   as third currency dimension alongside code + JTBD-content)
+# @jtbd JTBD-101 (Extend the Suite — clear patterns include stability signal)
+
+set -uo pipefail
+
+PACKAGES_DIR="${1:-packages}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PACKAGES_DIR" ]; then
+  echo "check-plugin-maturity-drift: packages dir not found: $PACKAGES_DIR" >&2
+  exit 2
+fi
+
+# ── Python body ─────────────────────────────────────────────────────────────
+
+export CPMD_PACKAGES_DIR="$PACKAGES_DIR"
+
+python3 - <<'PYEOF'
+import json, os, re, sys
+from pathlib import Path
+
+packages_dir = Path(os.environ["CPMD_PACKAGES_DIR"]).resolve()
+
+if not packages_dir.is_dir():
+    print(f"check-plugin-maturity-drift: packages dir not found: {packages_dir}", file=sys.stderr)
+    sys.exit(2)
+
+# Badge prose-woven pattern: `*Maturity: <Band>...*` per ADR-063
+# §"README badge rendering format". Captures the band token as the
+# first word after `Maturity:`.
+BADGE_RE = re.compile(r"\*Maturity:\s+([A-Za-z]+)[^*]*\*")
+ANTI_SECTION_RE = re.compile(r"(?m)^#{1,3}\s+Maturity\s*$")
+ANTI_URL_RE = re.compile(r"shields\.io|img\.shields", re.IGNORECASE)
+
+
+def extract_badge_band(readme_text):
+    """Returns the band token from a `*Maturity: <Band>...*` span, or
+    None when no such span is present.
+    """
+    m = BADGE_RE.search(readme_text)
+    if m:
+        return m.group(1)
+    return None
+
+
+def append_hint(current, hint):
+    if not current:
+        return hint
+    parts = current.split(",")
+    if hint in parts:
+        return current
+    return current + "," + hint
+
+
+def evaluate_plugin(pkg_dir):
+    """Returns (line_dict, hint_count) for one plugin, or None when the
+    plugin should be silently skipped (no README).
+    """
+    plugin_json_path = pkg_dir / ".claude-plugin" / "plugin.json"
+    readme_path = pkg_dir / "README.md"
+    if not readme_path.is_file():
+        return None
+    try:
+        plugin_doc = json.loads(plugin_json_path.read_text(encoding="utf-8"))
+    except Exception:
+        plugin_doc = {}
+    if not isinstance(plugin_doc, dict):
+        plugin_doc = {}
+
+    record_band = None
+    maturity = plugin_doc.get("maturity")
+    if isinstance(maturity, dict):
+        record_band = maturity.get("band")
+
+    readme_text = readme_path.read_text(encoding="utf-8")
+    badge_band = extract_badge_band(readme_text)
+
+    hints = ""
+
+    if record_band and not badge_band:
+        hints = append_hint(hints, "missing-badge")
+    elif badge_band and not record_band:
+        hints = append_hint(hints, "orphan-badge")
+    elif record_band and badge_band and record_band != badge_band:
+        hints = append_hint(hints, "stale-band")
+
+    if ANTI_SECTION_RE.search(readme_text):
+        hints = append_hint(hints, "anti-pattern-section")
+    if ANTI_URL_RE.search(readme_text):
+        hints = append_hint(hints, "anti-pattern-url")
+
+    line = {
+        "package": pkg_dir.name,
+        "badge_band": badge_band or "none",
+        "record_band": record_band or "none",
+        "drift_hints": hints,
+    }
+    return (line, 1 if hints else 0)
+
+
+# ── Walk packages/ ─────────────────────────────────────────────────────────
+
+plugin_dirs = sorted(
+    [d for d in packages_dir.iterdir()
+     if d.is_dir() and (d / ".claude-plugin" / "plugin.json").is_file()
+     or (d.is_dir() and (d / "README.md").is_file())]
+)
+
+total_packages = 0
+total_drift_instances = 0
+
+for pkg_dir in plugin_dirs:
+    result = evaluate_plugin(pkg_dir)
+    if result is None:
+        continue
+    line, drift = result
+    total_packages += 1
+    total_drift_instances += drift
+    print(
+        f"README package={line['package']} "
+        f"badge_band={line['badge_band']} "
+        f"record_band={line['record_band']} "
+        f"drift_hints={line['drift_hints']}"
+    )
+
+if total_packages > 0:
+    print(f"TOTAL packages={total_packages} drift_instances={total_drift_instances}")
+
+PYEOF
+
+exit 0

package/scripts/test/check-plugin-maturity-drift.bats

@@ -0,0 +1,269 @@
+#!/usr/bin/env bats
+
+# @problem P238 — Phase 3b drift detector behavioural confirmation.
+# @problem P087 — parent: plugin maturity battle-hardening signal.
+# @problem P152 — sibling drift-detector pattern (JTBD-currency).
+#
+# Contract under test:
+# `packages/retrospective/scripts/check-plugin-maturity-drift.sh` is an
+# advisory drift detector. It compares each plugin's rendered README
+# maturity badge against the canonical `plugin.json` `maturity:` field
+# and emits NDJSON-per-drift signals to stdout. Exit code 0 always per
+# ADR-013 Rule 6 — drift is data, not failure.
+#
+# Drift classes:
+#   missing-badge      — plugin.json has maturity but README has no badge
+#   stale-band         — badge band mismatches canonical record
+#   orphan-badge       — README has badge but plugin.json has no maturity
+#   anti-pattern-section — README has standalone ## Maturity section
+#   anti-pattern-url   — README has shields.io / SVG badge URL
+#
+# @adr ADR-063 (Plugin maturity presentation layer — Phase 3b contract)
+# @adr ADR-051 (Sibling drift-detector pattern — `check-readme-jtbd-currency.sh`)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — exit 0 always)
+# @adr ADR-049 (Shim grammar — `wr-retrospective-check-plugin-maturity-drift` on $PATH)
+# @adr ADR-052 (Behavioural tests default)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-plugin-maturity-drift.sh"
+  FIXTURE_DIR="$(mktemp -d)"
+  PROJECT_ROOT="$FIXTURE_DIR/project"
+  PKG_DIR="$PROJECT_ROOT/packages"
+  mkdir -p "$PKG_DIR"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_DIR"
+}
+
+# Helper: write a synthetic plugin layout with plugin.json + README.md
+make_plugin() {
+  local name="$1"
+  local plugin_json="$2"
+  local readme="$3"
+  local pkg="$PKG_DIR/$name"
+  mkdir -p "$pkg/.claude-plugin"
+  printf '%s\n' "$plugin_json" > "$pkg/.claude-plugin/plugin.json"
+  printf '%s\n' "$readme" > "$pkg/README.md"
+}
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+@test "script file exists and is executable" {
+  [ -f "$SCRIPT" ]
+  [ -x "$SCRIPT" ]
+}
+
+@test "missing packages dir exits 2 with error message on stderr" {
+  run bash "$SCRIPT" "$FIXTURE_DIR/does-not-exist"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"packages dir not found"* ]]
+}
+
+@test "empty packages dir exits 0 with empty stdout" {
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"TOTAL"* ]] || [ -z "$output" ]
+}
+
+# ── Clean fixture: badge matches plugin.json record ─────────────────────────
+
+@test "clean fixture: matching badge + record emits no drift hints" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.*
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"drift_hints="* ]]
+  [[ "$output" != *"stale-band"* ]]
+  [[ "$output" != *"missing-badge"* ]]
+}
+
+# ── Stale-band fixture: badge != canonical record ───────────────────────────
+
+@test "stale-band fixture: README badge band mismatches plugin.json record" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Beta"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.*
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"stale-band"* ]]
+}
+
+# ── Missing-badge fixture: plugin.json has maturity, README has no badge ────
+
+@test "missing-badge fixture: plugin.json has maturity but README has no badge" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.**
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"missing-badge"* ]]
+}
+
+# ── Orphan-badge fixture: README has badge, plugin.json has no maturity ─────
+
+@test "orphan-badge fixture: README badge present but plugin.json lacks maturity field" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub"}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.*
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"orphan-badge"* ]]
+}
+
+# ── Anti-pattern: standalone ## Maturity section ────────────────────────────
+
+@test "anti-pattern: standalone ## Maturity section emits anti-pattern-section hint" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.*
+
+## Maturity
+
+Alpha band.
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"anti-pattern-section"* ]]
+}
+
+# ── Anti-pattern: shields.io URL ────────────────────────────────────────────
+
+@test "anti-pattern: shields.io URL emits anti-pattern-url hint" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.* ![Maturity](https://img.shields.io/badge/maturity-alpha-orange)
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=stub"* ]]
+  [[ "$output" == *"anti-pattern-url"* ]]
+}
+
+# ── TOTAL summary line ──────────────────────────────────────────────────────
+
+@test "multi-plugin aggregation: emits TOTAL summary with drift count" {
+  make_plugin "alpha" '{"name":"wr-alpha","version":"0.1.0","description":"Alpha","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/alpha
+
+**Alpha plugin.** *Maturity: Alpha.*
+
+## Skills
+"
+  make_plugin "bravo" '{"name":"wr-bravo","version":"0.1.0","description":"Bravo","maturity":{"schema_version":"1.0","band":"Beta"}}' \
+"# @windyroad/bravo
+
+**Bravo plugin.**
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"package=alpha"* ]]
+  [[ "$output" == *"package=bravo"* ]]
+  [[ "$output" == *"TOTAL packages=2"* ]]
+  [[ "$output" == *"drift_instances=1"* ]]
+}
+
+# ── Exit-0-always invariant ─────────────────────────────────────────────────
+
+@test "exit-0-always: even with multiple drift entries, exit code is 0" {
+  make_plugin "alpha" '{"name":"wr-alpha","version":"0.1.0","description":"Alpha","maturity":{"schema_version":"1.0","band":"Beta"}}' \
+"# @windyroad/alpha
+
+**Alpha plugin.** *Maturity: Alpha.*
+
+## Skills
+"
+  make_plugin "bravo" '{"name":"wr-bravo","version":"0.1.0","description":"Bravo","maturity":{"schema_version":"1.0","band":"Stable"}}' \
+"# @windyroad/bravo
+
+**Bravo plugin.**
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+}
+
+# ── Package without README is silently skipped ──────────────────────────────
+
+@test "package without README.md is silently skipped" {
+  local pkg="$PKG_DIR/no-readme"
+  mkdir -p "$pkg/.claude-plugin"
+  echo '{"name":"wr-no-readme","version":"0.1.0","description":"No README","maturity":{"schema_version":"1.0","band":"Alpha"}}' > "$pkg/.claude-plugin/plugin.json"
+
+  make_plugin "with-readme" '{"name":"wr-with-readme","version":"0.1.0","description":"With README","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/with-readme
+
+**With README.** *Maturity: Alpha.*
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"package=no-readme"* ]]
+  [[ "$output" == *"package=with-readme"* ]]
+}
+
+# ── No-network primitive: ADR-035 privacy posture ───────────────────────────
+
+@test "ADR-035: script body invokes no network primitive" {
+  run grep -E "(curl|wget|nc -|netcat|ssh |scp |rsync|http\.client|urllib|requests)" "$SCRIPT"
+  [ "$status" -ne 0 ]
+}
+
+# ── NDJSON output: per-line shape parseable as structured signal ────────────
+
+@test "NDJSON output: each README line follows package=<name> <key>=<value> shape" {
+  make_plugin "stub" '{"name":"wr-stub","version":"0.1.0","description":"Stub","maturity":{"schema_version":"1.0","band":"Alpha"}}' \
+"# @windyroad/stub
+
+**Stub plugin description.** *Maturity: Alpha.*
+
+## Skills
+"
+
+  run bash "$SCRIPT" "$PKG_DIR"
+  [ "$status" -eq 0 ]
+  # Per-package README line is space-separated key=value tokens
+  [[ "$output" == *"README package=stub"* ]]
+  [[ "$output" == *"badge_band="* ]]
+  [[ "$output" == *"record_band="* ]]
+}