continuous-improvement 3.9.2 → 3.11.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.",
-      "version": "3.9.2",
+      "description": "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 25 bundled skills, gating hooks, the Mulahazah auto-leveling instinct engine, and a GitHub Action transcript linter.",
+      "version": "3.11.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -6,6 +6,67 @@ All notable changes to this skill are documented here.
 
 ## [Unreleased]
 
+## [3.11.0] — 2026-06-07
+
+### Added
+
+- **In-harness GateGuard clearance: `ci_gateguard_clear` + `bin/gateguard-clear.mjs`** — after presenting the facts, clear the gate with the `ci_gateguard_clear` MCP tool (available in beginner *and* expert mode, since the gate fires for every install) or the `gateguard-clear.mjs` CLI over the hook-allowed Bash route, instead of hand-writing the session-state JSON. Both take one or more file paths and record clearance through the shared canonical writer; the CLI accepts `--state <gateguard-session.json>` to target the exact file the block reason prints.
+
+### Changed
+
+- **Landing page rebuilt as a Blueprint spec-sheet on the `continuous-improvement.dev` domain** — `docs/landing/index.html` is now a warm-paper editorial spec-sheet (OKLCH palette, one safety-vermilion accent, Space Grotesk + JetBrains Mono, asymmetric hero, the 7 Laws rendered as numbered clauses, enforcement zig-zag), replacing the previous dark/purple/emoji page. The 7-Law copy is pulled verbatim from `commands/discipline.md`. A `docs/landing/CNAME` plus updated `homepage`, canonical URL, and README link point the GitHub Pages site at the `continuous-improvement.dev` custom domain.
+
+### Fixed
+
+- **GateGuard block reason now points at a clearance path that works on Claude Code** — the runtime hook told the agent to retry with `_gateguard_facts_presented: true`, but Claude Code's strict tool schema (`additionalProperties: false`) rejects that extra param with `InputValidationError` before the hook runs, leaving the first Edit/Write per file unclearable through the file tools. The block reason and the skill's "Honor system" note now lead with the portable route — record clearance in the session state file via a non-destructive Bash write — and keep the inline flag as a secondary path for harnesses that forward unknown tool params. No behavior change to the gate itself.
+- **GateGuard clearance now matches regardless of path form** — the hook and every clearance helper canonicalize the project root and per-file keys (lowercase drive letter, `\`→`/`, strip trailing slash), so a clearance recorded by one process (e.g. the MCP server, which resolves the root via git-toplevel `D:/…`) is seen by the hook (which resolves via `CLAUDE_PROJECT_DIR` `d:/…`). This removes the drive-case / separator mismatch that previously forced seeding every path variant across candidate session dirs by hand. `lib/gateguard-state.mjs` is now bundled into `plugins/continuous-improvement/` (the bundled hook and `mcp-server.mjs` both import it).
+
+---
+
+## [3.10.0] — 2026-06-03
+
+### Fixed
+
+- **Installer now persists cleanup-only hook filtering** — `src/bin/install.mts` now writes `settings.json` when it strips broken legacy observe/session hooks even if the clean installer hook was already present, so coexistence cases no longer leave stale legacy commands behind. Regression coverage now seeds a clean observe hook alongside a broken legacy one and verifies the broken entry disappears while the clean one remains once.
+- **Installer now clones hook entries per target bucket** — the observe/session hook entries are now constructed inside each loop iteration instead of reusing one object across `PreToolUse`/`PostToolUse` or `SessionStart`/`SessionEnd`, so a future mutation in one bucket can't silently leak into the paired bucket.
+- **GateGuard MultiEdit docs now match runtime behavior** — the skill docs no longer describe MultiEdit as `edits[0].file_path` V1; they now document the per-file gate that blocks mixed-clearance batches until every edited path is cleared or facts are presented, and the runtime keeps the 50-file cap intact even for multi-file batches while naming the full batch in the block reason.
+
+---
+
+## [3.9.2] — 2026-05-10
+
+Manifest-derivation patch. One fix plus the release cut.
+
+### Fixed
+
+- **Manifests track the package version automatically** (PR #122) — `VERSION` in `src/lib/plugin-metadata.mts` is now derived from `package.json` at build time instead of being a hand-maintained constant. `npm run build` regenerates `marketplace.json` and `plugin.json` with the correct version on every release without a separate manual edit. v3.9.2 was the first release cut with auto-derived manifests (PR #123).
+
+---
+
+## [3.9.1] — 2026-05-10
+
+First release through the tag-triggered `release.yml` pipeline. The `v3.9.0` tag was placed before PR #99 merged, so this release range also carries the feature and CI work that landed on top of the v3.8.0 dispatcher train — the substantive items are listed below; the `[3.9.0]` entry above describes only PRs #97–#99.
+
+### Added
+
+- **`release.yml` tag-triggered npm publish** (PR #119) — pushing a `v*` tag now builds, verifies, and publishes to npm, with the retarget policy and cut procedure documented in `docs/RELEASING.md`. PR #120 cut v3.9.1 as the first exercise of this pipeline.
+- **`gateguard` runtime PreToolUse hook** (PRs #106, #108) — `hooks/gateguard.mjs` ships as the runtime layer that physically blocks Edit/Write/MultiEdit and destructive Bash until fact-list investigation is presented. PR #107 added hotfix-PR mode, a synthetic-checks rung, and the insights CLAUDE.md template.
+- **Native review-agent trio** (PR #112) — `code-reviewer`, `security-auditor`, and `test-engineer` agents in `plugins/continuous-improvement/agents/`, routed by the orchestrator during verify and review phases.
+- **Three verification-ladder skills** (PR #117) — `state-reconciliation`, `recovery-classification`, and `worktree-safety` added as pre-dispatch invariants.
+- **`verify:doc-runtime-claims` lint** (commit `241e8fe`) — codifies the audit-twice rule: any user-facing runtime-hook claim must carry a `hooks/<file>.mjs` anchor within ±5 lines.
+- **Repo-root `.mcp.json`** (PR #113) — dogfoods `bin/mcp-server.mjs` from inside the repo.
+
+### Changed
+
+- **Installer path collapse + dispatcher rewrite** (commit `bc76bfe`) — installer paths collapsed, versions synced, installer surface expanded.
+- **`pm-skills` switched from vendored snapshot to out-of-band marketplace install** (PR #101) — product-management coverage now installs via `phuryn/pm-skills` per `docs/THIRD_PARTY.md` instead of being vendored under `third-party/`.
+- **CI `verify-generated` check widened** (PR #99) — `git diff` path widened to `.claude-plugin bin test lib plugins`.
+
+### Fixed
+
+- **MCP server emits NDJSON over stdio** (PR #114) — corrected the transport framing to the MCP spec (NDJSON, not LSP-style framing).
+- **`gateguard` doc wording reverted** (commit `5eca467`) — the "runtime gate is roadmap" wording was reverted once the hook actually shipped.
+
 ---
 
 ## [3.9.0] — 2026-05-07

package/QUICKSTART.md

@@ -25,6 +25,8 @@ Without it, `/superpowers` still works — it falls back to inline behavior —
 
 ### Verify the install — two checks
 
+**Fastest path:** restart Claude Code, then run `/verify-install` — it walks all three checks (commands loaded, gateguard fires, observation capture recording) and prints a single ✓ wired / ✗ missing line. The manual checks below are the same probes done by hand, kept here so you can see what each one proves.
+
 **Check 1 — slash command loaded.** Quit and reopen Claude Code (slash commands only load on session start), then run:
 
 ```
@@ -97,14 +99,17 @@ This shows what the system has learned — instincts, confidence levels, and the
 
 ## How auto-leveling works
 
-You don't configure anything. The system promotes itself:
-
-| Your usage | What happens |
-|-----------|-------------|
-| First sessions | Hooks capture tool calls silently. No behavior change. |
-| After ~20 sessions | Agent analyzes patterns, creates instincts (silent — you see nothing) |
-| After ~50 sessions | Instincts cross 0.5 → agent starts suggesting: "Consider: [action]" |
-| After ~100 sessions | Instincts cross 0.7 → agent auto-applies learned behaviors |
+You don't configure anything. The system promotes itself. The unit is
+**observations** — one per tool call, not one per session — so a single active
+session can produce dozens. The four levels below mirror the source-of-truth
+table in [SKILL.md](SKILL.md):
+
+| Level | Trigger | What happens |
+|-------|---------|-------------|
+| CAPTURE | < 20 observations | Hooks capture tool calls silently. No behavior change. |
+| ANALYZE | 20+ observations | Agent analyzes patterns, creates instincts (silent — you see nothing) |
+| SUGGEST | Any instinct at 0.5–0.69 confidence | Agent suggests inline: "Consider: [action]" |
+| AUTO-APPLY | Any instinct at 0.7+ confidence | Agent auto-applies the learned behavior |
 
 Corrections drop instinct confidence. Unused instincts decay. The system self-corrects.
 

package/README.md

@@ -1,49 +1,94 @@
+<!-- README landing-page structure rationale: docs/plans/2026-05-14-readme-landing-rewrite.md -->
+
 <p align="center">
   <img src="assets/combined.gif" alt="Before vs After — The 7 Laws of AI Agent Discipline" width="700" />
 </p>
 
-<h1 align="center">The 7 Laws of AI Agent Discipline</h1>
+<h1 align="center">A seatbelt for Claude Code</h1>
 
 <p align="center">
-  <b>Stop your Claude Code agent from skipping steps, guessing, and declaring "done" without verifying.</b>
+  <b>Research first. Edit safely. Verify before done. Remember what worked.</b>
+</p>
+
+<p align="center">
+  <i>The 7 Laws of AI Agent Discipline — runtime hooks, enforcement skills, and project memory.</i>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/continuous-improvement"><img src="https://img.shields.io/npm/v/continuous-improvement" alt="npm"></a>
   <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-skill-blueviolet" alt="Claude Code"></a>
+  <a href="https://github.com/marketplace/actions/ai-agent-discipline-linter"><img src="https://img.shields.io/badge/GitHub%20Action-marketplace-blue" alt="GitHub Action"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
   <a href="test/"><img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="tests"></a>
 </p>
 
 <p align="center">
-  <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes)
+  <b>New here?</b> → <a href="QUICKSTART.md">QUICKSTART.md</a> (2 minutes) · <a href="https://continuous-improvement.dev">continuous-improvement.dev</a>
 </p>
 
+> **What this is *not*:** a prompt template, a `CLAUDE.md`, or a vibes-based reminder. It is a runtime hook (`hooks/gateguard.mjs`) plus a bundled skill set that physically blocks `Edit` / `Write` / destructive `Bash` until the agent has done the work.
+
 ---
 
-## The problem this solves
+## What this does
+
+Claude Code is powerful but skips the boring discipline: it edits before reading, guesses instead of checking, stacks five concerns into one commit, and says "done" without running tests. Continuous Improvement adds three layers that stop that:
+
+1. **Before an edit** — [`gateguard`](skills/gateguard.md) ships as a `PreToolUse` hook (`hooks/gateguard.mjs`) that physically blocks `Edit` / `Write` / `MultiEdit` and destructive `Bash` until the agent presents a fact-list investigation.
+2. **During work** — bundled skills enforce planning, one-thing-at-a-time execution, TDD ([`tdd-workflow`](skills/tdd-workflow.md)), and a six-phase verification ladder ([`verification-loop`](skills/verification-loop.md)) before "done".
+3. **After work** — `/seven-laws` reflection plus the Mulahazah instinct engine capture lessons so the same mistake does not repeat next session.
+
+Beginner install is two slash commands inside Claude Code (no Node, no bash). Expert install adds MCP tools, observation hooks, instinct packs, and a GitHub Action transcript linter for CI.
+
+---
+
+## Before and after
+
+Without Continuous Improvement, "fix the login redirect bug" looks like this:
+
+> Claude edits `Login.tsx`, `LoginForm.tsx`, `useAuth.ts`, `authRouter.ts`, `redirects.ts`, and `useNavigate.ts` — six files, no plan, no investigation. Says "done". The redirect still loops. You roll back six files.
+
+With Continuous Improvement, the same prompt is forced through the gate:
+
+> `gateguard` blocks the first `Edit` until Claude presents a fact list. Claude reads `useAuth.ts`, finds the existing `redirectAfterLogin` helper, traces *why* the redirect loops (a stale `from` query param), and edits one line in one file. `verification-loop` runs the tests. The reply names the file, the line, the cause.
+
+Same agent. Same model. Different discipline.
+
+---
 
-You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern.
+## Who this is for
 
-| You ask the agent to... | What actually happens |
-|---|---|
-| Add a feature | It edits five files, never runs the build, says "done" |
-| Fix a bug | It reinvents a helper that already exists in the repo |
-| Refactor a module | It bundles three unrelated changes into one commit |
-| Pick up where last session ended | It re-explores from zero — the prior session's lessons are gone |
-| Verify the change works | It claims "this should work" without running a single test |
+Use this if you:
 
-Every one of those failures is the agent skipping a step a disciplined engineer would not skip. The 7 Laws of AI Agent Discipline names each step, gives it a hook or a skill that enforces it, and feeds the captured patterns back into the agent so the same mistake gets harder to repeat next session.
+- ship from real repositories with real consequences
+- have been bitten by an agent that edits before understanding
+- want tests, builds, or healthchecks to pass before "done"
+- want lessons from yesterday to survive into today
 
-## What you get
+Skip it if you:
 
-- **A 7-step discipline** the agent must follow every task — research → plan → execute one thing → verify → reflect → learn → iterate. Each Law has at least one skill or hook that enforces it.
-- **14 bundled skills + a runtime PreToolUse hook** that turn the Laws into enforced behavior — `gateguard` runs as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit/Write/destructive Bash until the agent presents fact-list investigation. `tdd-workflow` enforces RED → GREEN → REFACTOR, `verification-loop` runs build/types/tests/security before "done", `deploy-receipt` closes the merge-to-production gap (deployed SHA + healthcheck), `proceed-with-the-recommendation` walks any agent's recommendation list top-to-bottom with per-item verification. The runtime hook catches the "skipped investigation" failure mode at the tool-call layer; the skills run model-side once the gate clears. See [§ How enforcement works](#how-enforcement-works) for the two-layer model.
-- **Mulahazah, the auto-leveling instinct engine** — hooks capture every tool call; after ~20 observations the agent analyzes patterns and creates instincts with confidence scores. Suggestions appear at 0.5+, auto-apply at 0.7+, decay when ignored. Project-scoped, promote to global after 2+ projects. You configure nothing.
-- **A GitHub Action transcript linter** that catches skipped Laws in CI — writes without prior research, edits without verification, too many files at once.
-- **Two install paths** — Beginner is two slash commands inside Claude Code (no Node, no bash, ~90% of users). Expert adds the MCP server, observation hooks, instinct packs, and the linter.
+- only do one-off prompts (no edits, no commits)
+- do not use Claude Code
+- dislike *any* friction before agent edits
+- want a prompt template, not a runtime gate
 
-The whole thing is MIT, free, and lives in this one repo. No service, no account, no telemetry leaves your machine.
+(The runtime gate is `hooks/gateguard.mjs`; full mechanics in [How enforcement works](#how-enforcement-works) below.)
+
+---
+
+## The problem this solves
+
+You have used Claude Code (or any agentic coding tool) long enough to recognize the failure pattern. Matt Pocock's [Skills For Real Engineers](https://github.com/mattpocock/skills) names four root failure modes that account for nearly every "the agent didn't help" complaint; the 7 Laws of AI Agent Discipline catch those four at the tool-call boundary plus a fifth that only shows up across sessions.
+
+| # | Failure mode | What you see | Which Law fires | What enforces it |
+|---|---|---|---|---|
+| 1 | **Misalignment** | The agent doesn't do what you want — invents requirements, reinvents helpers that already exist | Law 1 (Research) | [`grill-me`](skills/grill-me.md), [`grill-with-docs`](skills/grill-with-docs.md), [`gateguard`](skills/gateguard.md), [`workspace-surface-audit`](skills/workspace-surface-audit.md) |
+| 2 | **No shared language** | The agent uses 20 words where 1 would do; jargon decoded fresh every session; variable names drift from domain terms | Law 2 (Plan), Law 7 (Learn) | [`grill-with-docs`](skills/grill-with-docs.md) (writes & maintains `CONTEXT.md`), [`token-budget-advisor`](skills/token-budget-advisor.md), [`strategic-compact`](skills/strategic-compact.md) |
+| 3 | **No feedback loop** | The code doesn't work — agent claims "done" without running build, tests, or healthcheck | Law 4 (Verify) | [`tdd-workflow`](skills/tdd-workflow.md), [`verification-loop`](skills/verification-loop.md), [`deploy-receipt`](skills/deploy-receipt.md) |
+| 4 | **Design rot** | Ball-of-mud accelerates — agent bundles three concerns into one PR, stacks untested changes, ignores prior architectural decisions | Law 2 (Plan), Law 3 (One Thing) | [`superpowers:writing-plans`](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md), [`safety-guard`](skills/safety-guard.md), [`worktree-safety`](skills/worktree-safety.md), [`wild-risa-balance`](skills/wild-risa-balance.md) |
+| 5 | **Forgotten lessons** | Next session starts from zero — prior corrections, decisions, instincts are lost; the same mistake repeats next week | Law 5 (Reflect), Law 7 (Learn) | [`handoff`](skills/handoff.md), [`para-memory-files`](skills/para-memory-files.md), Mulahazah instinct engine |
+
+Three of those alignment + reflection skills (`grill-me`, `grill-with-docs`, `handoff`) are MIT-licensed ports from mattpocock/skills; the rest are continuous-improvement-native. Every failure mode has at least one runtime hook or model-side skill that catches it before it lands in the diff.
 
 ---
 
@@ -86,7 +131,7 @@ You should see Claude **blocked** by the bundled `gateguard` PreToolUse hook (`h
 
 The 7 Laws are enforced at **two layers**:
 
-- **Runtime layer (hooks).** `gateguard` ships as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit / Write / MultiEdit / destructive Bash on the first mutation per file until the agent presents the facts named in [skills/gateguard.md § Gate Types](skills/gateguard.md). Destructive Bash (`rm -rf`, `git push --force`, `--force-with-lease`, `DROP DATABASE`, Windows `Remove-Item -Recurse`, etc.) is gated on every call, not just first. Read-only and exploratory tools (Read, Grep, Glob, routine Bash like `git status`) bypass the gate. Per-session state at `~/.claude/instincts/<project-hash>/gateguard-session.json` caps cumulative clearances at 50 distinct files to bound stuck-loop damage.
+- **Runtime layer (hooks).** `gateguard` ships as a PreToolUse hook (`hooks/gateguard.mjs`) that physically blocks Edit / Write / MultiEdit / destructive Bash on the first mutation per file until the agent presents the facts named in [skills/gateguard.md § Gate Types](skills/gateguard.md). Destructive Bash (`rm -rf`, `git push --force`, `--force-with-lease`, `DROP DATABASE`, Windows `Remove-Item -Recurse`, etc.) is gated on every call, not just first. Read-only and exploratory tools (Read, Grep, Glob, routine Bash like `git status`) bypass the gate. Per-session state at `~/.claude/instincts/<project-hash>/gateguard-session.json` caps cumulative clearances at 50 distinct files to bound stuck-loop damage. A second runtime hook, `goal-drift-stop` (`hooks/goal-drift-stop.mjs`), fires on `Stop`: it scores each turn against the stated `## Goal` and, on a substantive wrap-up that has drifted off-goal, warns by default (or re-prompts under `CLAUDE_GOAL_DRIFT_GATE=block`) — so a drifted session can't quietly declare "done". Fail-open.
 - **Model layer (skills).** Once the runtime gate clears for a file, the rest of the discipline (`tdd-workflow`, `verification-loop`, `proceed-with-the-recommendation`, etc.) runs model-side — the agent reads each skill and applies it. `observe.sh` / `observe.mjs` records every tool call into the Mulahazah feed for instinct extraction; that surface is observational, not enforcement.
 
 V1 honest limitations: the runtime gate is honor-system once the agent flips `_gateguard_facts_presented: true` (the hook can't verify the investigation actually happened); the state file is deletable and parallel hook invocations can race. Documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
@@ -125,6 +170,7 @@ The framework has documented operator-level modes that change hook behavior with
 | Env var | Effect | How to set |
 |---|---|---|
 | `CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` | `three-section-close.mjs` short-circuits before any enforcement or telemetry. Use when end-of-turn reflection should run as internal thinking rather than visible "What has been done / What is next / Recommendation" sections. Public default unchanged — the rule still fires for everyone else. | bash/zsh: `export CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_THREE_SECTION_CLOSE_DISABLED','1','User')` (persistent). |
+| `CLAUDE_GOAL_DRIFT_GATE` | `goal-drift-stop.mjs` (a `Stop` hook) scores each turn's activity against the `## Goal` in `task_plan.md` and acts on drift. `warn` (default) prints a one-line stderr notice and never blocks; `block` re-prompts a substantive wrap-up that has drifted off-goal so the goal gates the close; `off` disables it. Reads the same observation feed as Mulahazah; fails open on any error. | bash/zsh: `export CLAUDE_GOAL_DRIFT_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_GOAL_DRIFT_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_GOAL_DRIFT_GATE','block','User')` (persistent). |
 
 ---
 
@@ -148,19 +194,13 @@ Research -> Plan -> Execute (one thing) -> Verify -> Reflect -> Learn -> Iterate
   <img src="assets/diagram-7-laws-loop.jpg" alt="The 7 Laws of AI Agent Discipline — circular workflow loop" width="820" />
 </p>
 
-Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md).
+Full spec, reflection-block format, and anti-examples: [SKILL.md](SKILL.md). Full Law-to-tool alignment matrix: [CONTRIBUTING.md § Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix).
 
 ---
 
-## Mulahazah: Auto-Leveling Learning
-
-Hooks capture every tool call. After ~20 observations, Claude analyzes patterns and creates **instincts** with confidence scores:
+## Mulahazah: auto-leveling learning
 
-- **< 0.5** silent (stored, not surfaced)
-- **0.5–0.69** suggested inline when relevant
-- **0.7+** auto-applied
-- User corrections drop confidence by 0.1; unused instincts decay
-- Project-scoped, promoted to global after seen across 2+ projects
+Hooks capture every tool call. After ~20 observations Claude analyzes patterns and creates **instincts** with confidence scores: silent below 0.5, suggested at 0.5–0.69, auto-applied at 0.7+. Corrections drop confidence by 0.1; unused instincts decay. Project-scoped; promoted to global after seen across 2+ projects. You configure nothing.
 
 <p align="center">
   <img src="assets/diagram-mulahazah-learning.jpg" alt="Mulahazah pipeline" width="820" />
@@ -179,135 +219,27 @@ Hooks capture every tool call. After ~20 observations, Claude analyzes patterns
 /superpowers                      Law activator — route the task to the right specialist
 /workspace-surface-audit          Audit repo + MCP + env, recommend high-value skills
 /planning-with-files              Create task_plan.md, findings.md, progress.md
+/grill-me                         Interview-mode alignment (one question at a time)
+/grill-with-docs                  Grill-me with persistent outcomes — updates CONTEXT.md + ADRs inline
+/handoff                          End-of-session compaction into mktemp brief for the next agent
 /discipline                       Quick reference card of the 7 Laws
+/verify-install                   One-shot post-install check — commands, gateguard, observe
 /dashboard                        Visual instinct health dashboard
+/companion-preference             Inspect companion-preference hook telemetry
 /ralph                            Autonomous PRD story-by-story loop
-/learn-eval                       Capture session patterns into new skills (expert)
-/harvest                          Extract reusable patterns from session friction
+/learn-eval                       Capture session patterns into new skills (needs observation history)
+/harvest                          Extract reusable patterns from session friction (needs observation history)
 /release-train                    Coordinate a multi-PR release sequence
 /swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-All 13 ship in the marketplace bundle. The Beginner install gets all of them. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
+All 18 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval` and `/harvest` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
 
 ---
 
-## Law Coverage
+## Skills
 
-Every bundled skill, command, and hook enforces at least one of the 7 Laws. The full Law-to-tool alignment matrix lives in [CONTRIBUTING.md → Law Coverage Matrix](CONTRIBUTING.md#law-coverage-matrix); each skill's `description:` also leads with `Enforces Law N (...)` so the tag shows up every time the skill is loaded. Operator-level mode toggles live in the **Operator modes** section above the 7 Laws, alongside install.
-
----
-
-## All 14 Skills
-
-The plugin ships **1 core + 1 featured + 5 tier-1 + 4 tier-2 + 3 always-bundled = 14 skills**. Source-of-truth lives in [`skills/`](skills/) (one `.md` per skill); the plugin bundle at [`plugins/continuous-improvement/skills/`](plugins/continuous-improvement/skills/) is regenerated by `npm run build`.
-
-<details>
-<summary>Show the full skill table (14 rows)</summary>
-
-| # | Skill | Tier | Law | What it does |
-|---|-------|------|-----|--------------|
-| 1 | [`continuous-improvement`](SKILL.md) | core | — | The 7 Laws spec itself (research → plan → execute → verify → reflect → learn → iterate) |
-| 2 | [`proceed-with-the-recommendation`](skills/proceed-with-the-recommendation.md) ⭐ | featured | all 7 | Walks any agent's recommendation list top-to-bottom, routes each item, verifies per item, halts on `needs-approval` |
-| 3 | [`gateguard`](skills/gateguard.md) | 1 | 1 | Runtime PreToolUse hook (`hooks/gateguard.mjs`) + skill: physically blocks Edit/Write/MultiEdit and every destructive Bash until fact-list investigation is presented. Read-only and routine Bash bypass. |
-| 4 | [`para-memory-files`](skills/para-memory-files.md) | 1 | 5 + 7 | Durable file-based memory using PARA (Projects/Areas/Resources/Archives) for cross-session context |
-| 5 | [`tdd-workflow`](skills/tdd-workflow.md) | 1 | 3 + 4 | RED → GREEN → REFACTOR enforcement with 80%+ coverage across unit/integration/E2E |
-| 6 | [`verification-loop`](skills/verification-loop.md) | 1 | 4 | Six-phase verification (build, types, lint, tests, security, diff) with PASS/FAIL report |
-| 7 | [`deploy-receipt`](skills/deploy-receipt.md) | 1 | 4 | Closes the merge-to-production gap on auto-deploy targets (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io). "Done" requires the deployed SHA matching merged HEAD + a healthcheck returning 200 — runs after the vendored `finishing-a-development-branch`. |
-| 8 | [`safety-guard`](skills/safety-guard.md) | 2 | 3 | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory |
-| 9 | [`strategic-compact`](skills/strategic-compact.md) | 2 | 5 | Suggests `/compact` at logical phase boundaries instead of arbitrary auto-compaction |
-| 10 | [`token-budget-advisor`](skills/token-budget-advisor.md) | 2 | 2 | Token estimator that offers 25/50/75/100% depth choices before answering |
-| 11 | [`wild-risa-balance`](skills/wild-risa-balance.md) | 2 | 2 | Pairs WILD (bold) generation with RISA (safe) execution; splits recommendation lists into pilots above a baseline |
-| 12 | [`ralph`](skills/ralph.md) | companion | 6 | Autonomous loop that executes a PRD story-by-story with quality checks between iterations |
-| 13 | [`superpowers`](skills/superpowers.md) | companion | activator | Law activator — routes tasks to the correct Law-aligned specialist so the right discipline fires automatically |
-| 14 | [`workspace-surface-audit`](skills/workspace-surface-audit.md) | companion | 1 | Audits the active repo, MCP servers, plugins, env, then recommends high-value skills/workflows |
-
-</details>
-
-The orchestrator skill `proceed-with-the-recommendation` also routes to optional companion skills from external plugins (e.g. `obra/superpowers`, `code-review`, `frontend-design`, `commit-commands`). Each routing target has an inline fallback in the orchestrator, so the plugin works on a clean install with nothing else present — install the dedicated companion only when you want a specialist over the fallback. Full target list with source-plugin and risk-if-absent: [`plugins/continuous-improvement/README.md` § Required vs Optional companions](plugins/continuous-improvement/README.md#required-vs-optional-companions).
-
-### Beginner gets — by default
-
-Tier 1 + featured + companion. Auto-installed when you run the plugin install commands above. No flags, no choices.
-
-### Expert gets — additionally
-
-Tier 2 (`safety-guard`, `strategic-compact`, `token-budget-advisor`, `wild-risa-balance`), the MCP server (12 tools incl. `ci_plan_init`/`ci_plan_status`), session-observation hooks for Mulahazah, and `/learn-eval` for capturing session patterns into new skills.
-
-### Drop-in single-file install
-
-Want one skill without the whole plugin? Copy the `.md` file straight into `~/.claude/skills/<name>/SKILL.md`:
-
-```bash
-SKILL=proceed-with-the-recommendation
-mkdir -p ~/.claude/skills/$SKILL
-curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
-  -o ~/.claude/skills/$SKILL/SKILL.md
-```
-
----
-
-## Evolution — adding a new skill
-
-Drop one `.md` file into [`skills/`](skills/), run `npm run build`, and the plugin bundle, manifests, and bundled-skills README regenerate from that source. Seven lints (`verify:all` + `verify:generated`) block the merge if anything drifts.
-
-### The 5-step recipe
-
-```bash
-# 1. Create the source file
-touch skills/<your-skill>.md
-```
-
-```yaml
-# 2. Frontmatter must declare name + tier + Law-tagged description
----
-name: <your-skill>
-tier: "1"                # core | featured | "1" | "2" | companion
-description: "Enforces Law N (<law name>) of the 7 Laws of AI Agent Discipline. <what it does>."
----
-```
-
-```bash
-# 3. Regenerate the bundle (also writes plugins/.../skills/<your-skill>/SKILL.md
-#    + the bundled-skills README, which is itself generator-output)
-npm run build
-
-# 4. Run all 6 verify lints — must all pass
-npm run verify:all
-
-# 5. Commit one concern at a time (per CLAUDE.md): the source skill alone first,
-#    then any wiring (hooks, commands, Law-coverage table updates) as separate commits
-git add skills/<your-skill>.md plugins/continuous-improvement/skills/<your-skill>/
-git commit -m "feat(skills): add <your-skill> for Law N enforcement"
-```
-
-### What the build does for you automatically
-
-- **Mirrors source → bundle** (`bin/generate-plugin-manifests.mjs`): copies `skills/<name>.md` to `plugins/continuous-improvement/skills/<name>/SKILL.md`
-- **Regenerates plugin manifests** with the new skill listed in tier order
-- **Re-renders** [`plugins/continuous-improvement/skills/README.md`](plugins/continuous-improvement/skills/README.md) (do not edit by hand — generator output)
-
-### What the lints enforce so you cannot ship a half-wired skill
-
-| Lint | Blocks |
-|------|--------|
-| `verify:skill-mirror` | source `skills/<name>.md` and `plugins/.../<name>/SKILL.md` are out of sync |
-| `verify:skill-tiers` | skill has missing or unrecognized `tier:` value |
-| `verify:skill-law-tag` | skill description does not start with `Enforces Law N` (or `Law activator`, or `all 7 Laws`) |
-| `verify:docs-substrings` | README/QUICKSTART references a removed/renamed skill |
-| `verify:everything-mirror` | non-skill files in `plugins/continuous-improvement/` drift from their root-level source |
-| `verify:routing-targets` | `proceed-with-the-recommendation` names a routing target that is neither bundled nor declared in `optional-companions.json` |
-| `verify:generated` | `npm run build` was not re-run after a source change |
-
-### When to fold a new external skill into the 7 Laws
-
-A new skill is a fit if it provably enforces (or is a routed activator for) at least one of the 7 Laws. The Law-tag lint will refuse it otherwise. If it sits outside the laws (a domain skill — e.g. SQL optimization), keep it as an external plugin. The 7 Laws plugin stays disciplined about scope; that is the point.
-
-### What is *not* automated (the honest limits)
-
-- The Law-coverage matrix above (`## Law Coverage`) is hand-maintained — add your new skill to the right Law row when you ship it.
-- The "All 14 Skills" count in the section header is a literal — bump it when N changes.
-- Promotion between tiers (e.g. `2` → `1` after it proves itself) is a manual edit to the frontmatter `tier:` field, by design — the maintainer should make that call deliberately.
+The plugin ships **25 skills** — 1 core + 1 featured + 6 tier-1 + 14 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 26th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 
@@ -322,9 +254,7 @@ Lint agent behavior in CI. Detects skipped laws.
     strict: true
 ```
 
-`@v3` is a floating major-version tag that retargets on every `v3.x.y` release. Pin to a specific tag (`@v3.7.0`) if you need byte-reproducible CI; use `@v3` to ride patch and minor bumps automatically. See [CONTRIBUTING.md § Release](CONTRIBUTING.md#release) for the retarget policy.
-
-Catches: writes without prior research (Law 1), too many edits without verification (Law 3), code changes without tests/builds (Law 4), too many files at once (Law 6). Run locally with `node bin/lint-transcript.mjs <file>`.
+Catches writes without prior research (Law 1), too many edits without verification (Law 3), code changes without tests/builds (Law 4), too many files at once (Law 6). Run locally with `node bin/lint-transcript.mjs <file>`. The `@v3` floating-tag retarget policy lives in [CONTRIBUTING.md § Release](CONTRIBUTING.md#release).
 
 ---
 
@@ -356,7 +286,7 @@ Every skill description leads with `Enforces Law N (...)` so the discipline tag
 
 Workflows from this repo, applied to real open-source contributions:
 
-### pm-skills (product-on-purpose, 189 stars, Apache 2.0)
+### pm-skills (product-on-purpose, Apache 2.0)
 
 [F-07 discover-market-sizing](https://github.com/product-on-purpose/pm-skills/pull/141) - new domain skill in the Discover phase covering TAM/SAM/SOM market sizing for the [pm-skills](https://github.com/product-on-purpose/pm-skills) library.
 
@@ -368,9 +298,10 @@ Authored end-to-end with `/superpowers` and `/proceed-with-the-recommendation`:
 
 - [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
 - [SKILL.md](SKILL.md) — full 7 Laws spec
+- [docs/skills.md](docs/skills.md) — full 25-skill catalog
 - [examples/](examples/) — bug fix, feature build, refactor walkthroughs
 - [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
-- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals
+- [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill
 - [SECURITY.md](SECURITY.md)
 
 MIT.

package/bin/check-docs-substrings.mjs

@@ -177,6 +177,48 @@ export const DOCS_ASSERTIONS = [
     { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "## Stacked-PR Plan Precondition (≥3 files)", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
     { file: "skills/superpowers.md", pattern: "Per-PR table", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
     { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "Per-PR table", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
+    // superpowers Companion-Preference Override — locked 2026-05-13 (PR 1 of dispatcher-bias train).
+    // The dispatcher gained an opt-in settings key (~/.claude/settings.json →
+    // continuous_improvement.companion_preference: "ci-first" | "companions-first" | "strict-companions")
+    // that lets an operator who installed a companion plugin promote it over the CI-bundled default.
+    // Each assertion below catches a specific class of regression:
+    //   - "## Companion-Preference Override" → removing the whole override section
+    //   - "companion_preference"              → renaming or moving the settings key
+    //   - "strict-companions"                 → losing the hard-halt variant
+    { file: "skills/superpowers.md", pattern: "## Companion-Preference Override", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "## Companion-Preference Override", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    { file: "skills/superpowers.md", pattern: "companion_preference", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "companion_preference", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    { file: "skills/superpowers.md", pattern: "strict-companions", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "strict-companions", source: "docs-substrings-manifest:superpowers-companion-preference-override" },
+    // superpowers Runtime Enforcement subsection — locked 2026-05-13 (PR 3 of dispatcher-bias train).
+    // The Companion-Preference Override moved from documented-only to runtime-enforced via
+    // hooks/companion-preference.mjs (PreToolUse). The "### Runtime enforcement" subsection
+    // names the hook file as the verify:doc-runtime-claims anchor and describes the per-mode
+    // decision contract. Each assertion catches a specific class of regression:
+    //   - "### Runtime enforcement"           → removing the whole subsection
+    //   - "hooks/companion-preference.mjs"    → losing the hook anchor (also satisfies doc-runtime-claims)
+    //   - "fails open"                        → losing the no-block-on-bug invariant
+    { file: "skills/superpowers.md", pattern: "### Runtime enforcement", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "### Runtime enforcement", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    { file: "skills/superpowers.md", pattern: "hooks/companion-preference.mjs", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "hooks/companion-preference.mjs", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    { file: "skills/superpowers.md", pattern: "fails open", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "fails open", source: "docs-substrings-manifest:superpowers-runtime-enforcement" },
+    // superpowers Telemetry subsection — locked 2026-05-14 (PR 4 of dispatcher-bias train).
+    // The hook gained a JSONL telemetry writer at ~/.claude/instincts/<hash>/companion-preference.jsonl
+    // that fires under every mode including ci-first (which writes `observation` shadow rows). The
+    // "### Telemetry" subsection documents the JSONL path and the four-value action enum. Each
+    // assertion catches a specific class of regression:
+    //   - "### Telemetry"                     → removing the whole subsection
+    //   - "companion-preference.jsonl"        → renaming the JSONL file
+    //   - "observation"                       → losing the ci-first shadow row that makes default-flip decisions evidence-driven
+    { file: "skills/superpowers.md", pattern: "### Telemetry", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "### Telemetry", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
+    { file: "skills/superpowers.md", pattern: "companion-preference.jsonl", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "companion-preference.jsonl", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
+    { file: "skills/superpowers.md", pattern: "`observation`", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "`observation`", source: "docs-substrings-manifest:superpowers-telemetry-jsonl" },
     // verification-loop per-project ladder — locked 2026-05-07 (PR C of second-release train).
     // Phase 0 (Ladder Resolution) was added so Phases 1–6 read the project's actual build/typecheck/
     // lint/test/security/deploy_receipt invocations from .claude/verify-ladder.json (or sniff /
@@ -253,6 +295,37 @@ export const DOCS_ASSERTIONS = [
     { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: `The "no" escape valve (both tiers)`, source: "wild-risa-tiers.test.mts" },
     { file: "skills/proceed-with-the-recommendation.md", pattern: "explicit handoff signal", source: "wild-risa-tiers.test.mts" },
     { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "explicit handoff signal", source: "wild-risa-tiers.test.mts" },
+    // proceed-with-the-recommendation --once fast-path mode — locked 2026-05-13 (PR 2 of dispatcher-bias train).
+    // The orchestrator gained an opt-in mode that runs Phase 1 + Phase 3 + Phase 4 only on single-item
+    // safe-tagged confirmations, skipping P-MAG, Plan, Reflect, and the three-section close. Hard
+    // preconditions refuse --once and fall back to the full flow if list size != 1, item is not safe,
+    // it touches > 3 files / > 150 LOC, hits restricted dirs, or is destructive. Each assertion below
+    // catches a specific class of regression:
+    //   - "## Fast-Path: `--once` Mode"        → removing the whole section
+    //   - "Refuse --once if any fail"-shaped   → losing the precondition gate (matched via "--once refused:")
+    //   - "Phase 0 — P-MAG" + "**Skipped.**"   → losing the explicit phase-status table (matched via "Skipped.** Reason: single-item")
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "## Fast-Path: `--once` Mode", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "## Fast-Path: `--once` Mode", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "--once refused:", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "--once refused:", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Skipped.** Reason: single-item", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Skipped.** Reason: single-item", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "commands/proceed-with-the-recommendation.md", pattern: "Fast-path: `--once` mode", source: "docs-substrings-manifest:proceed-once-mode" },
+    { file: "plugins/continuous-improvement/commands/proceed-with-the-recommendation.md", pattern: "Fast-path: `--once` mode", source: "docs-substrings-manifest:proceed-once-mode" },
+    // /companion-preference status reader — locked 2026-05-14 (PR 5 of dispatcher-bias train).
+    // The reader CLI (bin/companion-preference-status.mjs) and slash command (commands/companion-preference.md)
+    // turn the JSONL telemetry from PR #138 into a per-skill aggregation report. The slash command must
+    // expose the frontmatter name, the canonical CLI invocation, and the documented --json subcommand.
+    // Each assertion catches a specific class of regression:
+    //   - "name: companion-preference"                → renaming the slash command
+    //   - "companion-preference-status.mjs"            → renaming the CLI entry point
+    //   - "## Subcommands"                             → losing the documented surface (--json, --days, --all)
+    { file: "commands/companion-preference.md", pattern: "name: companion-preference", source: "docs-substrings-manifest:companion-preference-status-reader" },
+    { file: "plugins/continuous-improvement/commands/companion-preference.md", pattern: "name: companion-preference", source: "docs-substrings-manifest:companion-preference-status-reader" },
+    { file: "commands/companion-preference.md", pattern: "companion-preference-status.mjs", source: "docs-substrings-manifest:companion-preference-status-reader" },
+    { file: "plugins/continuous-improvement/commands/companion-preference.md", pattern: "companion-preference-status.mjs", source: "docs-substrings-manifest:companion-preference-status-reader" },
+    { file: "commands/companion-preference.md", pattern: "## Subcommands", source: "docs-substrings-manifest:companion-preference-status-reader" },
+    { file: "plugins/continuous-improvement/commands/companion-preference.md", pattern: "## Subcommands", source: "docs-substrings-manifest:companion-preference-status-reader" },
 ];
 export function checkAssertions(repoRoot, assertions = DOCS_ASSERTIONS) {
     const fileCache = new Map();