@windyroad/retrospective 0.1.2-preview.13 → 0.1.3-preview.26

package/README.md

@@ -0,0 +1,55 @@
+# @windyroad/retrospective
+
+**Session retrospectives for Claude Code.** Captures learnings at the end of each session and creates problem tickets for failures and friction.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+Every coding session produces learnings -- things that went well, things that broke, things that were harder than expected. Without a retrospective, those learnings evaporate.
+
+The retrospective plugin:
+
+- **Reminds** you to run a retro when a session ends
+- **Updates** `docs/BRIEFING.md` with session learnings so future sessions start with context
+- **Creates problem tickets** (via [`@windyroad/problem`](../problem/)) for failures and friction encountered during the session
+
+## Install
+
+```bash
+npx @windyroad/retrospective
+```
+
+Restart Claude Code after installing.
+
+> **Requires:** [`@windyroad/problem`](../problem/) and [`@windyroad/risk-scorer`](../risk-scorer/). The installer warns if they're missing.
+
+## Usage
+
+**Run a session retrospective:**
+
+```
+/wr-retrospective:run-retro
+```
+
+This walks through the session's work, identifies what went well and what didn't, updates `docs/BRIEFING.md`, and creates problem tickets for any failures.
+
+The plugin also triggers a reminder via a `Stop` hook when a session ends naturally.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `check-deps.sh` | Session start | Verifies that `wr-problem` and `wr-risk-scorer` are installed |
+| `retrospective-reminder.sh` | Session end | Reminds you to run a retrospective |
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/retrospective --update
+npx @windyroad/retrospective --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/hooks/hooks.json

@@ -3,9 +3,6 @@
     "SessionStart": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-retrospective wr-problem wr-risk-scorer" }] }
     ],
-    "PreToolUse": [
-      { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/review-plan-enforce.sh" }] }
-    ],
     "Stop": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/retrospective-reminder.sh" }] }
     ]

package/package.json

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

package/skills/{wr:retrospective → run-retro}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:retrospective
+name: wr-retrospective:run-retro
 description: Run a session retrospective. Updates docs/BRIEFING.md with learnings and creates problem tickets for failures and friction.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
 ---

package/hooks/lib/gate-helpers.sh

@@ -1,174 +0,0 @@
-#!/bin/bash
-# Shared portable helpers for gate enforcement hooks.
-# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
-# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
-
-# ---------------------------------------------------------------------------
-# Portable utilities
-# ---------------------------------------------------------------------------
-
-# Portable mtime: tries GNU stat, falls back to macOS stat
-_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
-
-# Portable hash: tries md5sum, falls back to md5 -r, then shasum
-_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
-
-# Paths excluded from pipeline state hashing and docs-only detection.
-_doc_exclusions() {
-    echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'
-}
-
-# ---------------------------------------------------------------------------
-# ERR trap: outputs diagnostic JSON on hook errors (P010)
-# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
-# ---------------------------------------------------------------------------
-
-_enable_err_trap() {
-    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
-}
-
-_err_trap_handler() {
-    local script="$1" line="$2" cmd="$3"
-    local name
-    name=$(basename "$script" 2>/dev/null || echo "$script")
-    # Output diagnostic as systemMessage so it's visible in conversation
-    cat <<EOF
-{
-  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
-}
-EOF
-}
-
-# ---------------------------------------------------------------------------
-# JSON input parsing: standardised helpers replacing inline python3
-# Each reads from _HOOK_INPUT (set by the hook before calling these)
-# ---------------------------------------------------------------------------
-
-# Store hook input for reuse by parsing helpers
-_HOOK_INPUT=""
-
-_parse_input() {
-    _HOOK_INPUT=$(cat)
-}
-
-_get_tool_name() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    print(data.get('tool_name', ''))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-_get_session_id() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    print(data.get('session_id', ''))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-_get_command() {
-    echo "$_HOOK_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 ""
-}
-
-_get_file_path() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    ti = data.get('tool_input', {})
-    print(ti.get('file_path', ti.get('path', '')))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-_get_subagent_type() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    print(data.get('tool_input', {}).get('subagent_type', ''))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-_get_user_prompt() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    print(data.get('user_prompt', ''))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-_get_tool_output() {
-    echo "$_HOOK_INPUT" | python3 -c "
-import sys, json
-try:
-    data = json.load(sys.stdin)
-    # PostToolUse provides tool_response (dict with content array), not tool_output
-    tr = data.get('tool_response', {})
-    if isinstance(tr, dict):
-        content = tr.get('content', [])
-        if isinstance(content, list):
-            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
-            if texts:
-                print('\n'.join(texts))
-                sys.exit(0)
-    # Fallback for older/different hook formats
-    print(data.get('tool_output', ''))
-except:
-    print('')
-" 2>/dev/null || echo ""
-}
-
-# ---------------------------------------------------------------------------
-# Session-scoped tmp directory for risk files
-# ---------------------------------------------------------------------------
-
-# Returns the session-scoped directory for risk temp files.
-# Creates the directory if it doesn't exist.
-# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
-_risk_dir() {
-  local sid="$1"
-  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
-  mkdir -p "$dir"
-  echo "$dir"
-}
-
-# ---------------------------------------------------------------------------
-# Non-doc file detection for WIP gating
-# ---------------------------------------------------------------------------
-
-_is_doc_file() {
-    local file_path="$1"
-    local EXCL
-    EXCL=$(_doc_exclusions)
-    for pattern in $EXCL; do
-        local clean="${pattern#:!}"
-        case "$file_path" in
-            *"$clean"*) return 0 ;;
-        esac
-    done
-    case "$file_path" in
-        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
-    esac
-    return 1
-}

package/hooks/lib/review-gate.sh

@@ -1,102 +0,0 @@
-#!/bin/bash
-# Shared gate logic for review enforcement hooks (a11y, voice-tone, style-guide).
-# Sourced by *-enforce-edit.sh hooks and review-plan-enforce.sh.
-# Provides: check_review_gate, review_gate_deny, review_gate_parse_error
-
-# Source shared portable helpers (_mtime, _hashcmd)
-_REVIEW_GATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$_REVIEW_GATE_DIR/gate-helpers.sh"
-
-# Check review gate marker. Returns 0 if marker is valid (allow), 1 if invalid (deny).
-# Sets REVIEW_GATE_REASON on failure.
-# Usage: check_review_gate "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
-check_review_gate() {
-  local SESSION_ID="$1"
-  local SYSTEM="$2"        # e.g., "a11y", "voice-tone", "style-guide"
-  local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
-  local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
-  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-  local TTL_SECONDS="${REVIEW_TTL:-600}"
-
-  # 1. Marker must exist
-  if [ ! -f "$MARKER" ]; then
-    REVIEW_GATE_REASON="No ${SYSTEM} review marker found. The ${SYSTEM} agent must review first."
-    return 1
-  fi
-
-  # 2. TTL check — marker mtime must be within TTL
-  local NOW=$(date +%s)
-  local MARKER_TIME=$(_mtime "$MARKER")
-  local AGE=$(( NOW - MARKER_TIME ))
-  if [ "$AGE" -ge "$TTL_SECONDS" ]; then
-    rm -f "$MARKER" "$HASH_FILE"
-    REVIEW_GATE_REASON="${SYSTEM} review expired (${AGE}s old, TTL ${TTL_SECONDS}s). Re-run the ${SYSTEM} agent."
-    return 1
-  fi
-
-  # 3. Drift detection — policy file hash must match
-  if [ -f "$HASH_FILE" ] && [ -n "$POLICY_FILE" ]; then
-    local STORED_HASH=$(cat "$HASH_FILE")
-    local CURRENT_HASH=""
-    if [ -f "$POLICY_FILE" ]; then
-      CURRENT_HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
-    elif [ -d "$POLICY_FILE" ]; then
-      # Directory (e.g., docs/decisions/) — hash all .md files
-      CURRENT_HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
-    else
-      CURRENT_HASH="missing"
-    fi
-    if [ "$STORED_HASH" != "$CURRENT_HASH" ]; then
-      rm -f "$MARKER" "$HASH_FILE"
-      REVIEW_GATE_REASON="${SYSTEM} policy file changed since last review. Re-run the ${SYSTEM} agent."
-      return 1
-    fi
-  fi
-
-  # Slide TTL window forward
-  touch "$MARKER"
-  return 0
-}
-
-# Store policy file hash after a successful review.
-# Usage: store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
-store_review_hash() {
-  local SESSION_ID="$1"
-  local SYSTEM="$2"
-  local POLICY_FILE="$3"
-  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-
-  if [ -n "$POLICY_FILE" ]; then
-    local HASH=""
-    if [ -f "$POLICY_FILE" ]; then
-      HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
-    elif [ -d "$POLICY_FILE" ]; then
-      HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
-    else
-      HASH="missing"
-    fi
-    echo "$HASH" > "$HASH_FILE"
-  fi
-}
-
-# Emit fail-closed deny JSON for PreToolUse hooks.
-review_gate_deny() {
-  local REASON="$1"
-  cat <<EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "$REASON"
-  }
-}
-EOF
-}
-
-# Emit fail-closed deny JSON for parse failures.
-review_gate_parse_error() {
-  cat <<'EOF'
-{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
-    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
-EOF
-}

package/hooks/review-plan-enforce.sh

@@ -1,73 +0,0 @@
-#!/bin/bash
-# PreToolUse hook: Denies ExitPlanMode until review specialists have
-# reviewed the plan. Skips UI specialists (a11y, voice-tone, style-guide,
-# jtbd) when the plan only touches non-UI files (P008 optimization).
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/lib/review-gate.sh"
-source "$SCRIPT_DIR/lib/gate-helpers.sh"
-
-INPUT=$(cat)
-
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
-
-if [ -z "$SESSION_ID" ]; then
-  review_gate_parse_error
-  exit 0
-fi
-
-# Detect if the plan touches UI files by checking uncommitted changes
-# UI patterns: *.html, *.jsx, *.tsx, *.vue, *.svelte, *.astro, *.css, *.scss
-HAS_UI_FILES=false
-UI_PATTERNS='\.html$|\.jsx$|\.tsx$|\.vue$|\.svelte$|\.astro$|\.css$|\.scss$|\.ejs$|\.hbs$|\.erb$|\.leaf$'
-if git diff --cached --name-only 2>/dev/null | grep -qE "$UI_PATTERNS"; then
-    HAS_UI_FILES=true
-elif git diff --name-only 2>/dev/null | grep -qE "$UI_PATTERNS"; then
-    HAS_UI_FILES=true
-elif git ls-files --others --exclude-standard 2>/dev/null | grep -qE "$UI_PATTERNS"; then
-    HAS_UI_FILES=true
-fi
-
-# Also check the plan file itself for mentions of UI files
-PLAN_DIR="$HOME/.claude/plans"
-if [ -d "$PLAN_DIR" ] && [ "$HAS_UI_FILES" = false ]; then
-    LATEST_PLAN=$(ls -t "$PLAN_DIR"/*.md 2>/dev/null | head -1)
-    if [ -n "$LATEST_PLAN" ] && grep -qiE '\.html|\.jsx|\.tsx|\.vue|\.svelte|\.css|component|page|form|modal|dialog' "$LATEST_PLAN" 2>/dev/null; then
-        HAS_UI_FILES=true
-    fi
-fi
-
-MISSING=""
-
-if [ "$HAS_UI_FILES" = true ]; then
-    # UI files detected — require all specialists
-    for SYSTEM in a11y voice-tone style-guide jtbd; do
-      MARKER="/tmp/${SYSTEM}-plan-reviewed-${SESSION_ID}"
-      if [ ! -f "$MARKER" ]; then
-        case "$SYSTEM" in
-          a11y)       AGENT="accessibility-agents:accessibility-lead" ;;
-          voice-tone) AGENT="voice-and-tone-lead" ;;
-          style-guide) AGENT="style-guide-lead" ;;
-          jtbd)       AGENT="jtbd-lead" ;;
-        esac
-        if [ -z "$MISSING" ]; then
-          MISSING="$AGENT"
-        else
-          MISSING="${MISSING}, ${AGENT}"
-        fi
-      fi
-    done
-else
-    # No UI files — skip a11y, voice-tone, style-guide, jtbd
-    # Auto-create their markers so the gate passes
-    for SYSTEM in a11y voice-tone style-guide jtbd; do
-        touch "/tmp/${SYSTEM}-plan-reviewed-${SESSION_ID}"
-    done
-fi
-
-if [ -n "$MISSING" ]; then
-  review_gate_deny "BLOCKED: Cannot approve plan without specialist review. Missing: ${MISSING}. Delegate to each agent to review the plan."
-  exit 0
-fi
-
-exit 0