@windyroad/retrospective 0.2.0 → 0.3.0-preview.116

package/.claude-plugin/plugin.json

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

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/itil`](../itil/)) for failures and friction encountered during the session
+
+## Install
+
+```bash
+npx @windyroad/retrospective
+```
+
+Restart Claude Code after installing.
+
+> **Requires:** [`@windyroad/itil`](../itil/) 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-itil` 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/bin/install.mjs

@@ -4,10 +4,10 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
 
 const PLUGIN = "wr-retrospective";
-const DEPS = ["wr-problem", "wr-risk-scorer"];
+const DEPS = ["wr-itil", "wr-risk-scorer"];
 
 const flags = utils.parseStandardArgs(process.argv);
 
@@ -20,6 +20,7 @@ Session retrospectives that update briefings and create problem tickets
 Options:
   --update     Update this plugin and its skills
   --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
   --dry-run    Show what would be done without executing
   --help, -h   Show this help
 `);
@@ -36,7 +37,7 @@ utils.checkPrerequisites();
 if (flags.uninstall) {
   utils.uninstallPackage(PLUGIN);
 } else if (flags.update) {
-  utils.updatePackage(PLUGIN);
+  utils.updatePackage(PLUGIN, { scope: flags.scope });
 } else {
-  utils.installPackage(PLUGIN, { deps: DEPS });
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

package/hooks/hooks.json

@@ -1,10 +1,7 @@
 {
   "hooks": {
     "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" }] }
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/check-deps.sh wr-retrospective wr-itil wr-risk-scorer" }] }
     ],
     "Stop": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/retrospective-reminder.sh" }] }

package/lib/install-utils.mjs

@@ -0,0 +1,146 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin update "${pluginName}@${MARKETPLACE_NAME}" --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName, { scope = "project" } = {}) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName, { scope });
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

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

package/skills/run-retro/SKILL.md

@@ -0,0 +1,174 @@
+---
+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
+---
+
+# Session Retrospective
+
+Reflect on the current session, update the project briefing, and create problem tickets for failures and friction.
+
+## Steps
+
+### 1. Read the current briefing
+
+Read `docs/BRIEFING.md` to understand what previous sessions already captured.
+
+### 2. Reflect on this session
+
+Consider the work done in this session and identify:
+
+**What you wish you'd been told up front** — things that were non-obvious and caused wasted effort or wrong assumptions. These should be added to BRIEFING.md "What You Need to Know" if they aren't already there.
+
+**What surprised you** — things that contradicted reasonable expectations. These should be added to BRIEFING.md "What Will Surprise You" if they aren't already there.
+
+**What was harder than it should have been** — friction points, tool limitations, process overhead, confusing code. These should become problem tickets via the `/problem` skill.
+
+**What failed** — things that broke, bugs encountered, hooks that errored, tests that failed unexpectedly. These should become problem tickets via the `/problem` skill.
+
+**What should we make easier or automate** — repetitive manual steps, missing tooling, things that could be scripted. These should become problem tickets via the `/problem` skill.
+
+**What recurring pattern did I (or the assistant) observe that would be better codified?** — a pattern that (a) was invoked multiple times in one session or across sessions, (b) has a deterministic action order or a clear invariant, and (c) is reusable beyond one project. These are **codification candidates** and route through Step 4b below. Do not treat them as problem tickets unless the user explicitly picks that routing option.
+
+**What existing skill, agent, hook, ADR, guide, or other codifiable showed a flaw, gap, or friction this session that a targeted edit would fix?** — the **improvement axis** of the codification surface. Criteria: (a) the flaw is reproducible and specific, (b) the fix is a bounded edit to an existing file, (c) no new concept is being invented. Improvement observations flow through the same Step 4b `AskUserQuestion` call as creation candidates, but their options name the improvement shape (e.g. `Skill — improvement stub`, `ADR — supersede or amend`) and the resulting Step 5 row records `Kind: improve` rather than `Kind: create`. An improvement that touches multiple unrelated concerns must be split using the P016 / P017 concern-boundary pattern before routing. If a single output accumulates ≥ 3 improvements in one session, prefer a single coordinating problem ticket over N separate tickets.
+
+For each codification candidate, also identify the **Kind** (`create` for a new output, `improve` for a targeted edit to an existing output) and the **best shape** for the codification. The Windy Road suite supports many shapes — pick the one that fits the pattern, not the one you happened to learn first:
+
+- **Skill** — deterministic multi-step sequence the user invokes by name (e.g. `wr-itil:ship-fix`). Worked example: `fetch origin → check changesets → score risk → commit → push → release → sync manifest → mark Fix Released`.
+- **Agent** — bounded investigation or review the main agent should delegate to (e.g. a performance-specialist the architect calls in for runtime-path changes). Place under `packages/<plugin>/agents/`.
+- **Hook** — event-driven enforcement or prompt injection (PreToolUse, PostToolUse, UserPromptSubmit). Use when "I keep forgetting to X before Y" — hooks make X unmissable without adding memory load.
+- **Settings entry** — `.claude/settings.json` changes: allowlisted commands, env vars, hook wiring. Best fit when a session repeatedly hits permission prompts for the same benign tool.
+- **Shell or Node script** — reusable repo-level tooling in `scripts/` (e.g. `sync-install-utils.sh`, `sync-plugin-manifests.mjs`). Best fit for multi-step shell sequences worth scripting.
+- **CI step** — `.github/workflows/*.yml` insertion. Best fit for "we'd have caught that earlier with a CI check".
+- **ADR** — architectural decision worth recording. Route to `/wr-architect:create-adr`.
+- **JTBD** — job-to-be-done record for a persona. Route to `/wr-jtbd:update-guide`.
+- **Guide** — voice, style, or risk policy edit. Route to `/wr-voice-tone:update-guide`, `/wr-style-guide:update-guide`, or `/wr-risk-scorer:update-policy`.
+- **Problem ticket** — diagnostic, project-specific friction (the default for flaws). Route to `/wr-itil:manage-problem`.
+- **Test fixture** — regression test for a recurring failure pattern (bats fixture, unit test). Best fit when the observation is "this kept breaking the same way".
+- **Memory** — per-user or per-project memory note in `~/.claude/.../memory/`. Best fit for short, user-habit observations that aren't a codifiable sequence (e.g. "I always forget to run `npm run verify` before pushing").
+
+If no shape fits — the observation is a one-off learning, not a repeating pattern — it belongs in BRIEFING.md (Step 3), not Step 4b.
+
+Counter-examples (what does **not** become a codification candidate):
+- "The commit gate rejected my work twice because X was misconfigured" — diagnostic, project-specific → **problem ticket** shape (route via Step 4b).
+- "I always forget to run `npm run verify` before pushing" — short, user-habit rather than codifiable sequence → **memory** shape or **BRIEFING.md** note.
+
+### 3. Update BRIEFING.md
+
+Edit `docs/BRIEFING.md`:
+
+- **Add** new learnings to the appropriate section ("What You Need to Know" or "What Will Surprise You")
+- **Remove** stale items that are no longer true. A learning is stale when:
+  - The issue has been fixed (e.g., "CI doesn't test v2" after v2 tests are added)
+  - It's now documented elsewhere (e.g., in an ADR, CLAUDE.md, or README)
+  - The codebase has changed enough that it's no longer relevant
+- **Update** items where the details have changed
+- Keep the file concise — under 2000 tokens. Each item should be 1-2 lines.
+
+Use the AskUserQuestion tool to confirm any removals: "I'd like to remove [item] from BRIEFING.md because [reason]. Is this correct?"
+
+### 4. Create or update problem tickets
+
+For each item identified in "What was harder than it should have been", "What failed", and "What should we make easier or automate", use the `/problem` skill to:
+
+- Check if a problem ticket already exists in `docs/problems/`
+- If yes: update it with new evidence from this session
+- If no: create a new problem ticket
+
+### 4b. Recommend new codifications
+
+For each **codification candidate** identified in Step 2, route the decision through a single `AskUserQuestion` call. This is the ADR-013 Rule 1 structured-interaction pattern — do not present the choices as prose enumeration in the skill output. The shape and Kind identified in Step 2 determine which option rows the user picks from; every shape and Kind routes through the same `AskUserQuestion` so the decision stays one structured interaction (architect decision: flat shape-prefixed options, not a two-step type-then-action or Kind-then-shape flow).
+
+For each candidate, invoke `AskUserQuestion` with:
+- `header: "Codification candidate"`
+- `multiSelect: false`
+- Options (a flat list; each option names the shape and Kind up front so the decision is auditable):
+
+  **Creation axis (Kind: create)** — new outputs:
+  1. `Skill — create stub` — description: "Record a stub candidate (suggested name, scope, triggers, prior uses) for a future scaffolding flow. Skill scaffolding itself is out of scope for this retrospective."
+  2. `Agent — create stub` — description: "Record a stub candidate for a new agent (suggested name, scope, trigger conditions, delegating skill). Place under `packages/<plugin>/agents/` when scaffolded."
+  3. `Hook — create stub` — description: "Record a stub candidate for a new hook (event: PreToolUse / PostToolUse / UserPromptSubmit; trigger; action summary)."
+  4. `Settings — propose entry` — description: "Record a proposed `.claude/settings.json` entry (allowlist / env / hook wiring) for later review."
+  5. `Script — create stub` — description: "Record a stub `scripts/*.sh` or `scripts/*.mjs` candidate (shebang + TODO + scope)."
+  6. `CI — propose step` — description: "Record a proposed `.github/workflows/ci.yml` insertion."
+  7. `ADR — invoke create-adr` — description: "Delegate to `/wr-architect:create-adr` so the decision is captured with proper MADR structure. Routing skill, not a stub."
+  8. `JTBD — invoke update-guide` — description: "Delegate to `/wr-jtbd:update-guide` to add or amend a job-to-be-done record. Routing skill, not a stub."
+  9. `Guide — invoke update-guide / update-policy` — description: "Delegate to `/wr-voice-tone:update-guide`, `/wr-style-guide:update-guide`, or `/wr-risk-scorer:update-policy` depending on the guide touched."
+  10. `Problem — invoke manage-problem` — description: "Delegate to `/wr-itil:manage-problem` so the candidate is WSJF-ranked against other backlog items. Routing skill, not a stub."
+  11. `Test fixture — create stub` — description: "Record a candidate bats / unit-test fixture for the recurring failure pattern."
+  12. `Memory — propose note` — description: "Record a proposed memory note (per-user or per-project) for a short user-habit observation that isn't a codifiable sequence."
+
+  **Improvement axis (Kind: improve)** — targeted edits to existing outputs (P051):
+  13. `Skill — improvement stub` — description: "Record a proposed targeted edit to an existing skill's SKILL.md (file path, observed flaw, evidence, edit summary). Use when an existing skill has a bounded, reproducible gap."
+  14. `Agent — improvement stub` — description: "Record a proposed targeted edit to an existing agent file (path, observed flaw, edit summary)."
+  15. `Hook — improvement stub` — description: "Record a proposed targeted edit to an existing hook script or `.claude/settings.json` wiring."
+  16. `ADR — supersede or amend` — description: "Delegate to `/wr-architect:create-adr` with a `supersedes ADR-N` hint so the new ADR explicitly replaces or amends the outdated one. Routing skill, not a stub."
+  17. `Guide — improvement edit` — description: "Delegate to `/wr-voice-tone:update-guide`, `/wr-style-guide:update-guide`, `/wr-jtbd:update-guide`, or `/wr-risk-scorer:update-policy` for a targeted edit to an existing guide (voice / style / JTBD / risk policy)."
+  18. `Problem — edit existing ticket` — description: "Delegate to `/wr-itil:manage-problem <NNN>` update flow to amend an existing open or known-error ticket with new observations from this session."
+
+  **Default:**
+  19. `Skip — not codify-worthy` — description: "Neither stub nor route. The observation is too small, too ambiguous, or a one-off learning that belongs in BRIEFING.md."
+
+If a single output has accumulated ≥ 3 improvement candidates in one session, prefer offering a single coordinating ticket (`Problem — invoke manage-problem` with an "apply N improvements to X" scope) over recording N separate improvement stubs — this reduces ticket churn and keeps the affected output's improvement queue coherent.
+
+If an improvement candidate touches multiple unrelated concerns, apply the P016 / P017 concern-boundary split before routing: re-run the `AskUserQuestion` once per concern, each with its own shape + Kind selection. This mirrors the concern-boundary analysis used when creating new problem tickets.
+
+If the option count is impractical for a single `AskUserQuestion` payload in a given Claude Code version, fall back to a two-question flow: (1) `"Which shape fits?"` with the shape list, (2) `"Create, improve, or skip?"` with `Create stub / Improvement stub / Invoke dedicated skill / Skip` — but prefer the single call when the surface allows it.
+
+When the user chooses any of the **Create stub** shapes (skill / agent / hook / settings / script / CI / test / memory), record a candidate entry in the Step 5 summary under "Codification Candidates" with:
+- **Kind** — `create`
+- **Shape** — which codification type (skill, agent, hook, etc.)
+- **Suggested name** — for skills: `wr-<plugin>:<action>`; for agents: `<plugin>:<name>`; for hooks: `<event>:<trigger>`; for scripts: `scripts/<name>.<ext>`; etc.
+- **Scope** — one sentence on what the codification does and when it should fire
+- **Triggers** — example user prompts or events that should invoke it
+- **Prior uses** — 2-3 observed invocations from this session
+
+When the user chooses any of the **Improvement stub** shapes (skill / agent / hook), record a candidate entry in the Step 5 summary under "Codification Candidates" with:
+- **Kind** — `improve`
+- **Shape** — which existing codifiable is being edited (skill, agent, hook)
+- **Target file** — the existing file path (e.g. `packages/itil/skills/manage-problem/SKILL.md`)
+- **Observed flaw** — one-sentence description of the gap, friction, or defect
+- **Edit summary** — one-sentence description of the proposed targeted edit
+- **Evidence** — 1-3 observations from this session showing the flaw
+
+When the user chooses any of the **Invoke <dedicated skill>** routes (ADR create / JTBD / Guide / Problem) OR the improvement routing options (ADR supersede or amend / Guide improvement edit / Problem edit existing ticket), delegate to the named skill with a context hand-off describing the candidate. Record the routing decision in the Step 5 summary under "Codification Candidates" with Kind (`create` or `improve`), Shape = the routing target, and a `routed to <skill>` marker. For `ADR — supersede or amend`, include the `supersedes ADR-N` hint in the hand-off so create-adr produces the correct MADR header.
+
+When the user chooses **Skip**, record the candidate in the Step 5 summary under "Codification Candidates" with a `skipped` marker so the pattern is still visible in the session audit trail.
+
+**Non-interactive fallback (per ADR-013 Rule 6):** if `AskUserQuestion` is unavailable, record each candidate in the Step 5 summary under "Codification Candidates" with a `flagged — not actioned (non-interactive)` marker, noting the identified Kind alongside Shape (e.g. `Kind: improve, Shape: skill, flagged — not actioned (non-interactive)`). Do not create stubs, route to dedicated skills, or scaffold. The user can review the flags and decide when they return. Improvement candidates flagged this way retain the Target file and Observed flaw fields so the user has enough to act on without re-deriving the context.
+
+**Backward compatibility**: "Skill" is retained as one shape among many so existing P044 muscle memory and `run-retro-skill-candidates.bats` continue to hold. Use the singular shape name in the summary (e.g. `Shape: skill`) so legacy greps still match. Improvement-axis rows use the same singular shape names (`Shape: skill, Kind: improve`) so the Shape column stays consistent across both axes.
+
+### 5. Summary
+
+Present a summary to the user:
+
+```
+## Session Retrospective
+
+### BRIEFING.md Changes
+- Added: [items added]
+- Removed: [items removed with reasons]
+- Updated: [items modified]
+
+### Problems Created/Updated
+- [problem ticket]: [summary]
+
+### Codification Candidates
+
+| Kind | Shape | Suggested name / Target file | Scope / Flaw | Triggers / Evidence | Decision |
+|------|-------|-----------------------------|--------------|----------------------|----------|
+| create  | skill | [suggested name] | [scope] | [examples] | created stub / routed to <skill> / skipped / flagged (non-interactive) |
+| create  | agent | ... | ... | ... | ... |
+| improve | skill | [target file path] | [observed flaw] | [1-3 session observations] | improvement stub / routed to <skill> / skipped / flagged (non-interactive) |
+| improve | hook  | ... | ... | ... | ... |
+
+### No Action Needed
+- [learnings that were already captured]
+```
+
+The `Kind` column takes values `create` or `improve` — the create / improve axis defined in Step 2 and Step 4b. Creation rows use the `Suggested name` / `Scope` / `Triggers` field semantics; improvement rows reuse the same columns with `Target file` / `Observed flaw` / `Evidence` semantics (per the stub-recording guidance in Step 4b). The decision column carries the same vocabulary for both Kinds, with `improvement stub` replacing `created stub` for Kind=improve rows.
+
+If the "Codification Candidates" table has no rows, omit it rather than rendering an empty header. The legacy "Skill Candidates" heading is preserved as a worked-example row in the Shape column so downstream tooling that grepped for "Skill Candidates" continues to find skill-shaped entries within the unified table.
+
+$ARGUMENTS

package/skills/run-retro/test/run-retro-codification-candidates.bats

@@ -0,0 +1,168 @@
+#!/usr/bin/env bats
+# Doc-lint guard: run-retro SKILL.md must include a generalised codification
+# branch that recommends agents, hooks, and other codifiable outputs — not
+# only skills. This is the P050 generalisation of P044's single-output-type
+# recommendation surface, extended by P051 with an improvement axis for
+# existing codifiables.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document includes the
+# multi-shape codification branch introduced by P050 and the improvement-axis
+# extension introduced by P051.
+#
+# Cross-reference:
+#   P051: docs/problems/051-run-retro-does-not-recommend-improvements-to-existing-codifiables.open.md
+#   P050: docs/problems/050-run-retro-does-not-recommend-other-codifiable-outputs.known-error.md
+#   P044: docs/problems/044-run-retro-does-not-recommend-new-skills.known-error.md (predecessor)
+#   ADR-013 Rule 1 / Rule 6 (docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md)
+#   @jtbd JTBD-101 (extend the suite with clear patterns)
+#   @jtbd JTBD-006 (progress the backlog while I'm away — AFK-safe Rule 6 fallback)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md Step 2 includes a generalised codification reflection category (P050)" {
+  # P050 fix: Step 2 must prompt for recurring patterns that would be better
+  # codified — not only as skills. The generalised wording names "codif"
+  # (codification / codifiable / codified) so reviewers and agents can tell
+  # P050 shipped.
+  run grep -in "codification candidate\|codifiable\|codify\|codified" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 2 names at least three codification shapes beyond skills (P050)" {
+  # The shape question is the point of P050. Names at minimum: agent, hook,
+  # and one of: settings, script, CI step, ADR, JTBD, guide, test. "skill"
+  # stays in the list as a worked example so P044 muscle memory survives.
+  run grep -ic "agent" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+  run grep -ic "hook" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+  run grep -icE "settings|script|ci step|ADR|JTBD|guide|test fixture" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+}
+
+@test "SKILL.md Step 4b recommendation branch covers multiple shapes (P050)" {
+  # Step 4b must route per-shape. The recommendation branch names more than
+  # just "skill" as an output type.
+  run grep -inE "(agent|hook).*stub|stub.*(agent|hook)|create.*(agent|hook)|(agent|hook).*candidate" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b uses a single AskUserQuestion with shape-prefixed options (ADR-013 Rule 1)" {
+  # Architect decision: flat AskUserQuestion with type-prefixed labels, not a
+  # two-step chained flow. At least three shape-prefixed option lines must
+  # appear in the Step 4b block. Match both plain and backticked forms:
+  #   "Skill — ..." / "`Skill — ...`" / "**Skill** — ..."
+  run grep -cE "(\`|\*\*)?(Skill|Agent|Hook|Settings|Script|CI|ADR|JTBD|Guide|Problem|Test fixture|Memory)(\`|\*\*)? +(—|-) " "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 3 ]
+}
+
+@test "SKILL.md Step 4b routes ADR candidates to wr-architect:create-adr (P050)" {
+  # Dedicated codification skills already exist — Step 4b must route to them,
+  # not duplicate intake.
+  run grep -in "wr-architect:create-adr\|/wr-architect:create-adr" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b routes JTBD candidates to wr-jtbd:update-guide (P050)" {
+  run grep -in "wr-jtbd:update-guide\|/wr-jtbd:update-guide" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b preserves non-interactive fallback for generalised shapes (ADR-013 Rule 6)" {
+  # The Rule 6 fallback that P044 introduced must cover the generalised surface.
+  # When AskUserQuestion is unavailable, all shape candidates are flagged rather
+  # than silently chosen.
+  run grep -in "non-interactive\|Rule 6" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 summary has a Codification Candidates section with Shape column (P050)" {
+  # P050 candidate fix (3): unified table. Either:
+  #   - a "### Codification Candidates" heading AND a "Shape" column, OR
+  #   - a "### Codification Candidates" heading with per-shape rows.
+  # Accept either shape but require the heading.
+  run grep -n "### Codification Candidates\|## Codification Candidates" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -in "shape" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md retains 'skill' as a worked example within the generalised category (backward compat with P044)" {
+  # Architect advisory: keep 'skill' in the shape list as one worked example so
+  # the existing P044 muscle memory and the run-retro-skill-candidates.bats
+  # line-30 grep still pass. This is the compatibility test.
+  run grep -in "would be better as a skill\|better as a skill\|as a skill\|skill candidate" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# P051 improvement-axis assertions
+#
+# P051 extends the P050 codification surface with an improvement axis so
+# existing skills, agents, hooks, ADRs, and guides can be recommended for
+# targeted edits (not only new creation). The architect decision requires:
+#   - flat shape-prefixed option list (no two-step create-vs-improve question)
+#   - parallel naming (e.g. `Skill — improvement stub` mirrors
+#     `Skill — create stub`)
+#   - Kind column in the Step 5 summary table (create / improve)
+#   - non-interactive fallback records the improvement Kind alongside Shape
+# ---------------------------------------------------------------------------
+
+@test "SKILL.md Step 2 includes an improvement reflection category for existing codifiables (P051)" {
+  # P051 fix: Step 2 must prompt for flaws observed in existing skills /
+  # agents / hooks / ADRs / guides — the improvement axis. The generalised
+  # phrasing names "improvement" or "improve" alongside "codification" so
+  # reviewers and agents can tell P051 shipped.
+  run grep -inE "existing (skill|agent|hook|codifiable).*(flaw|friction|gap|improve|improvement)|improvement(-| )shaped|improvement reflection|improvement candidate|improve an existing" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b names improvement-shaped options for multiple shapes (P051)" {
+  # P051 fix: the flat option list must carry `Skill — improvement ...`,
+  # `Agent — improvement ...`, and `Hook — improvement ...` rows in addition
+  # to the create-stub rows introduced by P050. Match at least three
+  # shape-prefixed improvement options.
+  run grep -cE "(\`|\*\*)?(Skill|Agent|Hook|ADR|Guide|Problem)(\`|\*\*)? +(—|-) +(improvement|supersede|amend|edit)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 3 ]
+}
+
+@test "SKILL.md Step 4b routes improvement-axis ADR candidates to create-adr with supersede hint (P051)" {
+  # ADR improvement shape is "supersede or amend an existing ADR". The
+  # routing target stays `/wr-architect:create-adr` (it writes the new ADR
+  # with a supersedes reference) — P051 adds the supersede/amend wording as
+  # a shape-prefixed option so the improvement axis is recognisable.
+  # Require both: an `ADR — supersede` (or equivalent) shape-prefixed option
+  # AND a route through `wr-architect:create-adr` near that option.
+  run grep -inE "(\`|\*\*)?ADR(\`|\*\*)? +(—|-) +(supersede|amend)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 summary distinguishes create from improve via a Kind column (P051)" {
+  # P051 candidate fix (3): the Codification Candidates table gains a `Kind`
+  # column carrying `create` / `improve`. Accept either a literal "Kind"
+  # column header or explicit `create / improve` values cited in the summary
+  # template. Both forms signal that the summary separates the two axes.
+  run grep -inE "\| *Kind *\||Kind column|Kind.*create.*improve|create / improve|create/improve" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b non-interactive fallback covers improvement candidates (P051 + ADR-013 Rule 6)" {
+  # Rule 6 fallback must mention the improvement axis explicitly so an AFK
+  # loop that flags an improvement candidate records Kind=improve alongside
+  # Shape (per architect advisory — the audit trail needs both axes for
+  # improvements). Accept either explicit Kind=improve language in the
+  # fallback block, OR a statement that the fallback records the Kind
+  # alongside Shape.
+  run grep -inE "flagged.*improve|improvement.*flagged|Kind.*(Shape|alongside)|(Shape|alongside).*Kind" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/run-retro/test/run-retro-skill-candidates.bats

@@ -0,0 +1,104 @@
+#!/usr/bin/env bats
+# Doc-lint guard: run-retro SKILL.md must include the skill-recommendation branch.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests do not assert hook behaviour; they assert that the skill specification
+# document includes the skill-candidate branch added in P044.
+#
+# Cross-reference:
+#   P044 (docs/problems/044-run-retro-does-not-recommend-new-skills.known-error.md)
+#   ADR-013 Rule 1 / Rule 6 (docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+#   @jtbd JTBD-101 (extend the suite with clear patterns)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md exists and has frontmatter" {
+  [ -f "$SKILL_FILE" ]
+  run head -1 "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "---" ]
+}
+
+@test "SKILL.md Step 2 includes the skill-candidate reflection category (P044, updated by P050)" {
+  # P044 fix: Step 2 must prompt for recurring workflows that would be better
+  # as skills. P050 generalises this to a codification category, with "skill"
+  # retained as one worked example within the shape list. This test accepts
+  # either the original P044 phrasing OR the P050 generalised phrasing that
+  # still names "skill" as a shape.
+  run grep -in "recurring workflow.*better as a skill\|would be better as a skill\|recurring pattern.*better codified\|\*\*Skill\*\* — " "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md includes a Step 4b Recommend new skills branch (P044)" {
+  # P044 fix: a dedicated output branch for skill candidates, distinct from Step 4
+  # (problem tickets) and Step 5 (summary).
+  run grep -n "Recommend new skills\|Step 4b" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b uses AskUserQuestion (ADR-013 Rule 1)" {
+  # ADR-013 Rule 1: the skill-candidate decision branch must use AskUserQuestion,
+  # not prose '(a)/(b)/(c)' enumeration. Architect review flagged this as the
+  # gotcha to avoid when implementing P044.
+  run grep -n "AskUserQuestion" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b header matches ADR-013 structured-interaction pattern (P044, updated by P050)" {
+  # P044 used "Skill candidate" as the AskUserQuestion header. P050 generalises
+  # to "Codification candidate" with "Skill" as one shape option. Accept either —
+  # both preserve the ADR-013 Rule 1 structured-interaction shape.
+  run grep -in "Skill candidate\|Codification candidate" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b names the structured options for skill-shaped candidates (P044, updated by P050)" {
+  # P044 required three specific option labels (Create a new skill / Track as a
+  # problem / Skip — not skill-worthy). P050 generalises: the skill shape now
+  # appears as a row in the flat shape-prefixed option list ("Skill — create
+  # stub"). The "track as problem" path becomes the explicit "Problem" row.
+  # Skip path becomes "Skip — not codify-worthy". This test accepts either
+  # pattern so the P044 regression guard survives P050's generalisation.
+  run grep -in "Create a new skill\|Skill — create stub\|Skill - create stub" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -in "Track as a problem ticket\|Problem — invoke manage-problem\|Problem - invoke manage-problem" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -in "Skip — not skill-worthy\|Skip - not skill-worthy\|Skip — not codify-worthy\|Skip - not codify-worthy" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 4b has non-interactive fallback per ADR-013 Rule 6" {
+  # ADR-013 Rule 6: if AskUserQuestion is unavailable, flag candidates instead of
+  # silently choosing. P044 implementation uses "flagged — not actioned" wording.
+  run grep -n "non-interactive\|Rule 6" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 summary template has a Skill / Codification Candidates slot (P044, updated by P050)" {
+  # P044 fix: the summary template must include a Skill Candidates section so
+  # recommendations are visible in the session audit alongside BRIEFING changes
+  # and problem tickets. P050 generalises this to a unified "Codification
+  # Candidates" table with a Shape column; skill-shaped candidates still appear
+  # (as Shape: skill rows). Accept either heading.
+  run grep -n "### Skill Candidates\|### Codification Candidates" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md does not contain 'Options: (a)' prose option list (ADR-013)" {
+  # ADR-013 Rule 1: user-facing decisions must use AskUserQuestion, not prose
+  # "Options: (a)/(b)/(c)". This matches the narrow pattern used by
+  # manage-problem-no-prose-options.bats so criteria lists using (a)/(b)/(c)
+  # as internal enumeration (which are fine) don't trip the test.
+  run grep -n "Options: (a)" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "SKILL.md does not contain 'Your call:' prose option prompt (ADR-013)" {
+  # ADR-013 Rule 1: mirrors the manage-problem regression guard.
+  run grep -n "Your call:" "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}

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

package/skills/wr:retrospective/SKILL.md

@@ -1,72 +0,0 @@
----
-name: wr:retrospective
-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
----
-
-# Session Retrospective
-
-Reflect on the current session, update the project briefing, and create problem tickets for failures and friction.
-
-## Steps
-
-### 1. Read the current briefing
-
-Read `docs/BRIEFING.md` to understand what previous sessions already captured.
-
-### 2. Reflect on this session
-
-Consider the work done in this session and identify:
-
-**What you wish you'd been told up front** — things that were non-obvious and caused wasted effort or wrong assumptions. These should be added to BRIEFING.md "What You Need to Know" if they aren't already there.
-
-**What surprised you** — things that contradicted reasonable expectations. These should be added to BRIEFING.md "What Will Surprise You" if they aren't already there.
-
-**What was harder than it should have been** — friction points, tool limitations, process overhead, confusing code. These should become problem tickets via the `/problem` skill.
-
-**What failed** — things that broke, bugs encountered, hooks that errored, tests that failed unexpectedly. These should become problem tickets via the `/problem` skill.
-
-**What should we make easier or automate** — repetitive manual steps, missing tooling, things that could be scripted. These should become problem tickets via the `/problem` skill.
-
-### 3. Update BRIEFING.md
-
-Edit `docs/BRIEFING.md`:
-
-- **Add** new learnings to the appropriate section ("What You Need to Know" or "What Will Surprise You")
-- **Remove** stale items that are no longer true. A learning is stale when:
-  - The issue has been fixed (e.g., "CI doesn't test v2" after v2 tests are added)
-  - It's now documented elsewhere (e.g., in an ADR, CLAUDE.md, or README)
-  - The codebase has changed enough that it's no longer relevant
-- **Update** items where the details have changed
-- Keep the file concise — under 2000 tokens. Each item should be 1-2 lines.
-
-Use the AskUserQuestion tool to confirm any removals: "I'd like to remove [item] from BRIEFING.md because [reason]. Is this correct?"
-
-### 4. Create or update problem tickets
-
-For each item identified in "What was harder than it should have been", "What failed", and "What should we make easier or automate", use the `/problem` skill to:
-
-- Check if a problem ticket already exists in `docs/problems/`
-- If yes: update it with new evidence from this session
-- If no: create a new problem ticket
-
-### 5. Summary
-
-Present a summary to the user:
-
-```
-## Session Retrospective
-
-### BRIEFING.md Changes
-- Added: [items added]
-- Removed: [items removed with reasons]
-- Updated: [items modified]
-
-### Problems Created/Updated
-- [problem ticket]: [summary]
-
-### No Action Needed
-- [learnings that were already captured]
-```
-
-$ARGUMENTS