@windyroad/retrospective 0.17.0 → 0.18.0

package/.claude-plugin/plugin.json

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

package/hooks/hooks.json

@@ -19,6 +19,17 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/retrospective-readme-jtbd-currency.sh"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

package/hooks/retrospective-readme-jtbd-currency.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# P159: PreToolUse:Bash hook — denies `git commit` invocations whose
+# post-commit working tree exhibits JTBD-currency drift in any
+# packages/<plugin>/README.md (no JTBD-NNN anchor, stale or
+# deprecated-only citation, or skill directory missing from README).
+#
+# Hook-level enforcement at commit time replaces ADR-051 Phase 1's
+# retro-time advisory surface (shipped under P158, df47ad1). The user
+# correction (P159) and the architect verdict identified the retro
+# surface as too late: the most-common drift class (contributor adds
+# skill/hook/agent and forgets the README) ships in a commit that
+# does not touch README.md, so a retro-time consumer sees the drift
+# only after the contributor has already committed.
+#
+# Detection delegates to the existing detector script
+# (`packages/retrospective/scripts/check-readme-jtbd-currency.sh`),
+# invoked against the project's working tree (`./packages/` +
+# `./docs/jtbd/`). The hook reads the detector's
+# `TOTAL packages=<N> with_jtbd=<M> drift_instances=<K>` summary and
+# denies when `drift_instances > 0`.
+#
+# Allow paths (exit 0 silently per ADR-045 Pattern 1):
+#   - tool_name != "Bash"            (only Bash invocations are gated)
+#   - command does not contain      `git commit` substring (non-commit
+#                                   Bash bypasses entirely — `git
+#                                   status`, `git log`, etc.)
+#   - BYPASS_JTBD_CURRENCY=1         (single-most-common legitimate
+#                                   escape — bypass-traceable via
+#                                   shell history)
+#   - outside a git work tree        (adopter sessions outside the
+#                                   plugin monorepo)
+#   - no `./packages/` directory     (project does not have ADR-051's
+#                                   structural anchor — adopter
+#                                   project shape; gate is a no-op)
+#   - no `./docs/jtbd/` directory    (project has not run
+#                                   /wr-jtbd:update-guide; gate is a
+#                                   no-op)
+#   - detector exits non-zero        (parse error / hostile env;
+#                                   fail-open per ADR-013 Rule 6)
+#   - detector emits no TOTAL line   (no packages found; nothing to
+#                                   gate)
+#   - drift_instances == 0           (clean tree)
+#
+# Deny shape (per ADR-013 Rule 1 — deny redirects with mechanical
+# recovery; ADR-045 deny-band ≤300 bytes):
+#   - Names the first offending plugin slug + drift hint vocabulary.
+#   - Names the wr-jtbd:agent recovery path AND the hand-edit fallback
+#     (graceful degradation when @windyroad/jtbd is not installed).
+#   - Names BYPASS_JTBD_CURRENCY=1 as the env-var escape.
+#   - Cites P159 for traceability.
+#   - Truncates the drift_hints CSV to the first hint to keep the
+#     deny-band ≤300 bytes for worst-case slug + hint combinations.
+#
+# Cost: one invocation of `check-readme-jtbd-currency.sh` per `git
+# commit` (~80–150ms in the worst case across 12 plugin READMEs +
+# ~30 JTBD job files; per the architect's ADR-023 perf review at
+# Phase 1 design time). Per-invocation deterministic; no marker
+# (mirrors P125 `staging-detect.sh` and P141
+# `itil-changeset-discipline.sh` precedent — architect-approved
+# no-marker design when detection cost stays under ~150ms).
+#
+# References:
+#   ADR-005 — plugin testing strategy (hook bats live under
+#             `packages/<plugin>/hooks/test/`).
+#   ADR-013 Rule 1 — deny redirects with mechanical recovery (the
+#             deny names the wr-jtbd:agent recovery, the hand-edit
+#             fallback, and the BYPASS env override).
+#   ADR-013 Rule 6 — non-interactive fail-safe (fail-open outside a
+#             git work tree, on parse error, in projects lacking
+#             ADR-051 anchors, and on detector failure).
+#   ADR-014 — governance skills commit their own work (this hook
+#             keeps iter commits self-contained).
+#   ADR-018 — inter-iteration release cadence (the hook strengthens
+#             release-cadence integrity by ensuring every publishable
+#             iter has a current README before commit).
+#   ADR-038 — progressive disclosure / deny-message terseness budget.
+#   ADR-045 — hook injection budget (Pattern 1 silent-on-pass; deny
+#             band ≤300 bytes for this hook).
+#   ADR-051 — JTBD-anchored README rule (this hook is the load-
+#             bearing-from-the-start commit-gate surface; supersedes
+#             retro-time advisory consumption as primary).
+#   ADR-052 — behavioural-tests default (bats fixture asserts on
+#             emitted JSON, not source content).
+#   P081 — behavioural tests preferred over structural greps.
+#   P125 — sibling staging-trap helper (per-invocation no-marker).
+#   P141 — sibling changeset-discipline gate on `git commit` (same
+#             hook shape).
+#   P158 — retro Step 2b wiring (backup advisory; survives this
+#             hook's primary-surface migration).
+#   P159 — this hook.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DETECTOR="$SCRIPT_DIR/../scripts/check-readme-jtbd-currency.sh"
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only gate Bash. Non-Bash tools bypass entirely.
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+COMMAND=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only fire on `git commit` invocations. Substring match catches common
+# shapes (`git commit -m`, `git commit --amend`, leading `cd && git
+# commit`, `chore: version packages` release commits routed via
+# `git commit -m 'chore: version packages'`, etc.) without
+# over-matching unrelated bash.
+case "$COMMAND" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+
+# Bypass via env var — single most-common legitimate escape.
+if [ "${BYPASS_JTBD_CURRENCY:-}" = "1" ]; then
+  exit 0
+fi
+
+# Fail-open if not inside a git working tree.
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Fail-open if the project lacks ADR-051's structural anchors.
+# Adopter projects without `./packages/` or `./docs/jtbd/` are not
+# subject to the rule; the hook is a no-op for them.
+[ -d "./packages" ] || exit 0
+[ -d "./docs/jtbd" ] || exit 0
+
+# Fail-open if the detector script itself is missing (defensive —
+# hook + detector ship together, but install-time corruption or
+# adopter-side patching should not block legitimate commits).
+[ -x "$DETECTOR" ] || exit 0
+
+# Run the detector. Capture exit code + output. Fail-open on detector
+# error (exit != 0).
+DETECTOR_OUTPUT=$(bash "$DETECTOR" "./packages" "./docs/jtbd" 2>/dev/null) || exit 0
+
+# Parse the TOTAL summary line. If absent, no packages were
+# enumerated — fail-open (no drift to report).
+TOTAL_LINE=$(echo "$DETECTOR_OUTPUT" | grep -E '^TOTAL packages=' | tail -n1)
+[ -n "$TOTAL_LINE" ] || exit 0
+
+# Extract drift_instances=<K>.
+DRIFT_INSTANCES=$(echo "$TOTAL_LINE" | grep -oE 'drift_instances=[0-9]+' | head -n1 | cut -d'=' -f2)
+[ -n "$DRIFT_INSTANCES" ] || exit 0
+
+# Allow path: clean tree.
+if [ "$DRIFT_INSTANCES" -eq 0 ]; then
+  exit 0
+fi
+
+# Drift detected — extract first offending package + its drift hints
+# for the deny message. The detector emits one "README package=<name>
+# ... drift_hints=<csv>" line per package; we name the first one with
+# a non-empty drift_hints.
+OFFENDING_LINE=$(echo "$DETECTOR_OUTPUT" | grep -E '^README package=' | grep -vE 'drift_hints=$' | head -n1)
+OFFENDING_SLUG=$(echo "$OFFENDING_LINE" | grep -oE 'package=[A-Za-z0-9_-]+' | head -n1 | cut -d'=' -f2)
+OFFENDING_HINTS=$(echo "$OFFENDING_LINE" | grep -oE 'drift_hints=[A-Za-z0-9,_-]+' | head -n1 | cut -d'=' -f2)
+
+# Fall back to a generic name if parsing failed (shouldn't happen but
+# defensive).
+[ -n "$OFFENDING_SLUG" ] || OFFENDING_SLUG="(unknown)"
+[ -n "$OFFENDING_HINTS" ] || OFFENDING_HINTS="drift"
+
+# Truncate the hints CSV to the first hint. Multi-hint cases (e.g.
+# both `missing-jtbd-section` and `skill-inventory-drift` on one
+# package) are bounded so the deny-band stays under 300 bytes for
+# worst-case slug + hint combinations.
+PRIMARY_HINT="${OFFENDING_HINTS%%,*}"
+
+# Deny — voice/tone budget per ADR-045 deny-band ≤300 bytes total
+# (envelope ~137 bytes; REASON ~163 bytes for worst-case slug +
+# hint). Names the offending plugin slug, the primary drift hint,
+# the wr-jtbd:agent recovery path with hand-edit fallback (graceful
+# degradation per architect F advisory), the BYPASS env, and the
+# P159 cite.
+REASON="BLOCKED: P159 JTBD drift in ${OFFENDING_SLUG} (${PRIMARY_HINT}). Recovery: wr-jtbd:agent OR cite a JTBD-NNN in README. Bypass: BYPASS_JTBD_CURRENCY=1."
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "${REASON}"
+  }
+}
+EOF
+exit 0

package/hooks/test/retrospective-readme-jtbd-currency.bats

@@ -0,0 +1,263 @@
+#!/usr/bin/env bats
+
+# P159: retrospective-readme-jtbd-currency.sh PreToolUse:Bash hook must
+# deny `git commit` invocations whose post-commit working tree exhibits
+# JTBD-currency drift (no JTBD-NNN anchor in a plugin README, stale or
+# deprecated-only citations, or skills/<dir>/ missing from the README).
+# Hook-level enforcement at commit time replaces ADR-051 Phase 1's
+# retro-time advisory surface, which the user correction (P159) and the
+# architect verdict identify as too late: the most-common drift class
+# (contributor adds skill/hook/agent and forgets the README) ships in a
+# commit that doesn't touch README.md, so a retro-time consumer sees the
+# drift only after the contributor has already committed.
+#
+# Detection delegates to the existing
+# `packages/retrospective/scripts/check-readme-jtbd-currency.sh`
+# detector, which the hook invokes against the project's working tree
+# (`./packages/` + `./docs/jtbd/`). The hook reads the detector's
+# `TOTAL packages=<N> with_jtbd=<M> drift_instances=<K>` summary line
+# and denies when `drift_instances > 0`.
+#
+# Per ADR-005 (plugin testing strategy) — hook bats live under
+# packages/<plugin>/hooks/test/ and assert on emitted JSON, not source
+# content. Per ADR-052 / P081 — behavioural; no source greps. Per
+# ADR-045 Pattern 1 — allow paths emit 0 bytes; deny-band ≤300 bytes.
+# Per ADR-013 Rule 1 — deny redirects to mechanical recovery (here: the
+# wr-jtbd:agent for prose-weaving guidance, with hand-edit fallback).
+# Per ADR-013 Rule 6 — fail-open outside a git work tree, on parse
+# errors, or in projects without ADR-051's structural anchors
+# (./packages/ or ./docs/jtbd/) so adopter projects are not blocked.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/retrospective-readme-jtbd-currency.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  git init --quiet -b main
+  git config user.email "test@example.com"
+  git config user.name "Test"
+  echo "seed" > seed.txt
+  git add seed.txt
+  git -c commit.gpgsign=false commit --quiet -m "initial"
+  unset BYPASS_JTBD_CURRENCY
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  unset BYPASS_JTBD_CURRENCY
+}
+
+run_bash_hook() {
+  local cmd="$1"
+  local json
+  json=$(printf '{"tool_name":"Bash","tool_input":{"command":"%s"}}' "$cmd")
+  echo "$json" | bash "$HOOK"
+}
+
+# Helper: build a stub project layout with a drifted plugin README.
+# README has no JTBD-NNN citation; jtbd dir has one resolving job.
+make_drifted_project() {
+  mkdir -p packages/stub docs/jtbd/plugin-user
+  printf '%s\n' "# @windyroad/stub" "no jtbd anchor here" > packages/stub/README.md
+  cat > docs/jtbd/plugin-user/JTBD-302-trust-readme.proposed.md <<'EOF'
+---
+status: proposed
+job-id: trust-readme
+persona: plugin-user
+date-created: 2026-05-04
+---
+
+# JTBD-302
+EOF
+}
+
+# Helper: build a stub project layout with a clean plugin README.
+# README cites a resolving JTBD-NNN; no skill drift.
+make_clean_project() {
+  mkdir -p packages/stub docs/jtbd/plugin-user
+  printf '%s\n' "# @windyroad/stub" "Serves JTBD-302." > packages/stub/README.md
+  cat > docs/jtbd/plugin-user/JTBD-302-trust-readme.proposed.md <<'EOF'
+---
+status: proposed
+job-id: trust-readme
+persona: plugin-user
+date-created: 2026-05-04
+---
+
+# JTBD-302
+EOF
+}
+
+# Helper: build a stub project with skill-inventory-drift —
+# packages/stub/skills/orphan/ exists but README doesn't name "orphan".
+make_skill_drift_project() {
+  mkdir -p packages/stub/skills/orphan docs/jtbd/plugin-user
+  printf '%s\n' "# @windyroad/stub" "Serves JTBD-302." > packages/stub/README.md
+  cat > docs/jtbd/plugin-user/JTBD-302-trust-readme.proposed.md <<'EOF'
+---
+status: proposed
+job-id: trust-readme
+persona: plugin-user
+date-created: 2026-05-04
+---
+
+# JTBD-302
+EOF
+}
+
+# ── Trap detection: deny when drift detected ───────────────────────────────
+
+@test "deny: drifted README (no JTBD-NNN cite) on git commit triggers deny" {
+  make_drifted_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P159"* ]]
+}
+
+@test "deny: skill-inventory-drift on git commit triggers deny" {
+  make_skill_drift_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny message names the offending plugin slug" {
+  make_drifted_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stub"* ]]
+}
+
+@test "deny message names the wr-jtbd:agent recovery path" {
+  make_drifted_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"wr-jtbd"* ]]
+}
+
+@test "deny message stays under ADR-045 deny-band (<300 bytes)" {
+  make_drifted_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -lt 300 ]
+}
+
+@test "deny: chore release commit (chore: version packages) is subject to the gate" {
+  make_drifted_project
+  run run_bash_hook "chore: version packages"
+  # Not a `git commit` invocation — should NOT trigger deny because the
+  # command field is the message, not the invocation. The actual release
+  # path runs `git commit` which IS gated; verify that shape:
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+
+  # Now the canonical release commit shape:
+  run run_bash_hook "git commit -m 'chore: version packages'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "deny: git commit --amend on drifted tree also triggers deny" {
+  make_drifted_project
+  run run_bash_hook "git commit --amend --no-edit"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# ── Allow paths: each non-trap shape must NOT deny ─────────────────────────
+
+@test "allow: clean README (cites resolving JTBD-NNN) on git commit allows the commit" {
+  make_clean_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: BYPASS_JTBD_CURRENCY=1 env var allows drifted commit" {
+  make_drifted_project
+  BYPASS_JTBD_CURRENCY=1 run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: non-Bash tool exits 0 without deny" {
+  make_drifted_project
+  run bash -c "echo '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"foo.md\"}}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: Bash command that is NOT git commit (e.g., git status) bypasses detection" {
+  make_drifted_project
+  run run_bash_hook "git status"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# ── Fail-open contracts (ADR-013 Rule 6) ───────────────────────────────────
+
+@test "allow: outside a git work tree exits 0 without deny (fail-open)" {
+  cd "$ORIG_DIR"
+  TEMP_NONGIT=$(mktemp -d)
+  cd "$TEMP_NONGIT"
+  run run_bash_hook "git commit -m 'feat'"
+  cd "$TEST_DIR"
+  rm -rf "$TEMP_NONGIT"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: project without packages/ dir exits 0 without deny (fail-open)" {
+  # No packages/, no docs/jtbd/ — adopter project shape.
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: project with packages/ but no docs/jtbd/ exits 0 without deny (fail-open)" {
+  mkdir -p packages/stub
+  echo "# stub" > packages/stub/README.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: empty JSON exits 0 without deny (fail-open on parse-incomplete)" {
+  make_drifted_project
+  run bash -c "echo '{}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "allow: malformed JSON exits 0 without deny (fail-open on parse error)" {
+  make_drifted_project
+  run bash -c "echo 'not-json' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+}
+
+# ── Allow path silence (ADR-045 Pattern 1) ─────────────────────────────────
+
+@test "allow path on clean tree emits 0 bytes (ADR-045 Pattern 1 silent-on-pass)" {
+  make_clean_project
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "allow path on non-Bash tool emits 0 bytes (silent-on-pass)" {
+  make_drifted_project
+  run bash -c "echo '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"foo.md\"}}' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "allow path on non-commit Bash emits 0 bytes (silent-on-pass)" {
+  make_drifted_project
+  run run_bash_hook "git status"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -eq 0 ]
+}

package/package.json

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