continuous-improvement 3.9.2 → 3.12.3

package/llms.txt

@@ -1,10 +1,10 @@
 # continuous-improvement
 
-> 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.
+> Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.
 
 ## What This Is
 
-A discipline framework for AI coding agents. It enforces seven laws — research, plan, execute one thing at a time, verify, reflect, iterate, learn — and builds behavioral instincts over time via the Mulahazah learning system, so the same correction does not have to be given twice.
+An intelligence amplifier for AI coding agents. It makes Claude reason at a higher level on every task, recall the corrections it has already received, and learn from each session so its competence compounds over time — research, plan, execute one thing at a time, verify, reflect, iterate, learn — building behavioral instincts via the Mulahazah learning system, so the same correction never has to be given twice and each run starts smarter than the last.
 
 ## Install
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "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 — 13 enforcement skills, gating hooks, the Mulahazah auto-leveling instinct engine, and a GitHub Action transcript linter. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
+  "version": "3.12.3",
+  "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",
     "claude-code-skill",
@@ -22,7 +22,7 @@
     "type": "git",
     "url": "git+https://github.com/naimkatiman/continuous-improvement.git"
   },
-  "homepage": "https://github.com/naimkatiman/continuous-improvement#readme",
+  "homepage": "https://continuous-improvement.dev",
   "bugs": {
     "url": "https://github.com/naimkatiman/continuous-improvement/issues"
   },
@@ -32,21 +32,26 @@
     "ci": "bin/unified-cli.mjs"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node bin/generate-plugin-manifests.mjs",
+    "build": "tsc -p tsconfig.json && node bin/generate-plugin-manifests.mjs && node -e \"const fs=require('node:fs'); for (const f of fs.readdirSync('bin')) { if (f.endsWith('.mjs')) fs.chmodSync('bin/'+f, 0o755); } for (const f of fs.readdirSync('hooks')) { if (f.endsWith('.mjs')) fs.chmodSync('hooks/'+f, 0o755); } for (const f of fs.readdirSync('lib')) { if (f.endsWith('.mjs')) fs.chmodSync('lib/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/bin')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/bin/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/lib')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/lib/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/hooks')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/hooks/'+f, 0o755); } for (const f of fs.readdirSync('scripts')) { if (f.endsWith('.mjs')) fs.chmodSync('scripts/'+f, 0o755); } for (const f of fs.readdirSync('synthetic-checks')) { if (f.endsWith('.mjs')) fs.chmodSync('synthetic-checks/'+f, 0o755); } \"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "node -e \"const fs=require('node:fs'); for (const dir of ['bin','test','lib']) { if (!fs.existsSync(dir)) continue; for (const file of fs.readdirSync(dir)) { if (file.endsWith('.mjs')) fs.rmSync(dir + '/' + file, { force: true }); } }\"",
+    "clean": "node -e \"const fs=require('node:fs'); for (const dir of ['bin','hooks','test','lib']) { if (!fs.existsSync(dir)) continue; for (const file of fs.readdirSync(dir)) { if (file.endsWith('.mjs')) fs.rmSync(dir+'/'+file, { force: true }); } }\"",
     "hooks:stats": "node bin/hook-stats.mjs",
     "test": "npm run build && node --test test/*.test.mjs",
     "lint": "node bin/lint-transcript.mjs --help",
-    "verify:generated": "npm run build && git diff --exit-code -- .claude-plugin bin test lib plugins",
+    "verify:generated": "npm run build && git diff --exit-code -- .claude-plugin bin hooks test lib plugins",
     "verify:skill-mirror": "node bin/check-skill-mirror.mjs",
     "verify:skill-tiers": "node bin/check-skill-tiers.mjs",
     "verify:skill-law-tag": "node bin/check-skill-law-tag.mjs",
+    "verify:skill-count": "node bin/check-skill-count.mjs",
     "verify:docs-substrings": "node bin/check-docs-substrings.mjs",
     "verify:everything-mirror": "node bin/check-everything-mirror.mjs",
     "verify:routing-targets": "node bin/check-routing-targets.mjs",
     "verify:doc-runtime-claims": "node bin/check-doc-runtime-claims.mjs",
-    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run verify:doc-runtime-claims && npm run typecheck"
+    "verify:test-imports-only": "node bin/check-test-imports-only.mjs",
+    "verify:scripts-citation-drift": "node bin/check-scripts-citation-drift.mjs",
+    "verify:third-party-shape": "node bin/check-third-party-shape.mjs",
+    "verify:tool-count": "node bin/check-tool-count.mjs",
+    "verify:all": "npm run verify:skill-mirror && npm run verify:skill-tiers && npm run verify:skill-law-tag && npm run verify:skill-count && npm run verify:docs-substrings && npm run verify:everything-mirror && npm run verify:routing-targets && npm run verify:doc-runtime-claims && npm run verify:test-imports-only && npm run verify:scripts-citation-drift && npm run verify:third-party-shape && npm run verify:tool-count && npm run typecheck"
   },
   "files": [
     ".claude-plugin/",

package/plugins/beginner.json

@@ -1,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.9.2",
+  "version": "3.12.3",
   "mode": "beginner",
-  "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four discipline skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default.",
+  "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four grounding skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
   "tools": [
     {
       "name": "ci_status",
@@ -15,6 +15,10 @@
     {
       "name": "ci_reflect",
       "what": "Reflect on what you did this session"
+    },
+    {
+      "name": "ci_gateguard_clear",
+      "what": "Clear the GateGuard gate for files after presenting facts"
     }
   ],
   "setup": {
@@ -46,8 +50,9 @@
   "hooks": {
     "included": [
       "PreToolUse",
-      "PostToolUse"
+      "PostToolUse",
+      "UserPromptSubmit"
     ],
-    "description": "Silently captures every tool call as observations. Lightweight and non-blocking."
+    "description": "Silently captures every tool call as observations and routes prompts to the matching skill via the route table. Lightweight and non-blocking."
   }
 }

package/plugins/continuous-improvement/.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": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.12.3",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "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 — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.",
+  "version": "3.12.3",
+  "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
   "author": {
     "name": "naimkatiman",
     "url": "https://github.com/naimkatiman"

package/plugins/continuous-improvement/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Naim Katiman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Naim Katiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/continuous-improvement/agents/README.md

@@ -40,7 +40,7 @@ Pick this only when **independent** investigations can run in parallel and produ
 
 - `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
 
-This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns.
+This is the only orchestration pattern this repo endorses. See the **Decision matrix** below for when to fan out versus invoke a single persona.
 
 ## Decision matrix
 
@@ -107,7 +107,7 @@ The personas in this repo are designed to work as Claude Code subagents and as A
 - **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example.
 - **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
 
-Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping.
+Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging).
 
 Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
 
@@ -117,4 +117,4 @@ Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmat
 2. Define the role, scope, output format, and rules.
 3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
 4. Add the persona to the table at the top of this file.
-5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself.
+5. If the persona enables a new orchestration pattern, document it in the **Decision matrix** above rather than inventing the pattern in the persona file itself.

package/plugins/continuous-improvement/bin/backfill.mjs

@@ -27,25 +27,25 @@ const args = process.argv.slice(2);
 const DRY_RUN = args.includes("--dry-run");
 const HELP = args.includes("--help") || args.includes("-h");
 if (HELP) {
-    console.log(`
-backfill — Tag legacy thin-schema observation rows.
-
-Usage:
-  npx continuous-improvement backfill            Tag rows in place
-  npx continuous-improvement backfill --dry-run  Report counts, write nothing
-
-What it does:
-  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
-  schema field ("thin" or "rich") to every row that lacks one. Thin rows
-  came from the legacy bash fallback (jq missing) and have no input_summary;
-  rich rows came from the Node observer and have full tool_input.command /
-  Edit.file_path / etc.
-
-Output:
-  - observations.jsonl rewritten in place (original kept as .bak)
-  - backfill-summary.json with per-project counts
-
-Idempotent. Always exits 0 — failures go to stderr only.
+    console.log(`
+backfill — Tag legacy thin-schema observation rows.
+
+Usage:
+  npx continuous-improvement backfill            Tag rows in place
+  npx continuous-improvement backfill --dry-run  Report counts, write nothing
+
+What it does:
+  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
+  schema field ("thin" or "rich") to every row that lacks one. Thin rows
+  came from the legacy bash fallback (jq missing) and have no input_summary;
+  rich rows came from the Node observer and have full tool_input.command /
+  Edit.file_path / etc.
+
+Output:
+  - observations.jsonl rewritten in place (original kept as .bak)
+  - backfill-summary.json with per-project counts
+
+Idempotent. Always exits 0 — failures go to stderr only.
 `);
     process.exit(0);
 }

package/plugins/continuous-improvement/bin/gateguard-clear.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * gateguard-clear — record GateGuard clearance for files from the Bash route.
+ *
+ * The GateGuard PreToolUse hook blocks the first Edit/Write per file and prints
+ * the session-state path in its block reason. After presenting the required
+ * facts, run this to clear the gate so the retry is allowed. Bash is not gated
+ * (unless the command is destructive), so this surface always works — including
+ * where the ci_gateguard_clear MCP tool is not connected.
+ *
+ * Usage:
+ *   node bin/gateguard-clear.mjs <file_path> [<file_path>...] [--state <path>]
+ *
+ * Default resolves the session dir canonically, the same way the hook does.
+ * --state <path> writes that exact gateguard-session.json — the path the block
+ * reason prints — bypassing resolution for any residual env mismatch.
+ */
+import { dirname, join } from "node:path";
+import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+function main() {
+    const argv = process.argv.slice(2);
+    const files = [];
+    let stateFile = "";
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--state") {
+            stateFile = argv[i + 1] ?? "";
+            i += 1;
+        }
+        else {
+            files.push(arg);
+        }
+    }
+    if (argv.includes("--state") && stateFile === "") {
+        process.stderr.write("--state requires a <gateguard-session.json> path argument\n");
+        process.exit(2);
+    }
+    if (files.length === 0) {
+        process.stderr.write("usage: gateguard-clear <file_path> [<file_path>...] [--state <gateguard-session.json>]\n");
+        process.exit(2);
+    }
+    // clearFiles writes <sessionDir>/gateguard-session.json. With --state the
+    // caller hands us the full state-file path the block reason printed, so the
+    // session dir is its parent.
+    const sessionDir = stateFile ? dirname(stateFile) : resolveSessionDir();
+    const { cleared, skippedForCap } = clearFiles(sessionDir, files);
+    process.stdout.write(`Cleared ${cleared.length}: ${cleared.length > 0 ? cleared.join(", ") : "(none — already cleared)"}\n`);
+    if (skippedForCap.length > 0) {
+        process.stdout.write(`Skipped — session cap of ${MAX_CLEARED_FILES} reached: ${skippedForCap.join(", ")}\n`);
+    }
+    process.stdout.write(`State: ${join(sessionDir, "gateguard-session.json")}\n`);
+}
+main();

package/plugins/continuous-improvement/bin/mcp-server.mjs

@@ -3,7 +3,7 @@
  * continuous-improvement MCP Server
  *
  * Exposes instincts, observations, and reflection as MCP tools + resources.
- * Two modes: beginner (3 tools) and expert (all tools).
+ * Two modes: beginner (4 tools) and expert (all tools).
  *
  * Usage:
  *   node bin/mcp-server.mjs                  # default: beginner mode
@@ -11,13 +11,17 @@
  *   node bin/mcp-server.mjs --mode beginner  # explicit beginner
  */
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
+import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
+import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
+import { draftFromCandidate, extractTrajectories, findCandidates, formatCandidates, serializeDraft, } from "../lib/skill-distill.mjs";
+import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -32,6 +36,12 @@ function getString(value, fallback = "") {
 function getNumber(value, fallback = 0) {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+// Draft ids are derived from slugified tool n-grams (src/lib/skill-distill.mts)
+// and are joined into a filesystem path, so a caller-supplied id must match the
+// safe shape before it is used to read/write/delete a draft file.
+function isSafeDraftId(id) {
+    return /^draft-[a-z0-9-]+$/.test(id);
+}
 function getBoolean(value, fallback = false) {
     return typeof value === "boolean" ? value : fallback;
 }
@@ -174,6 +184,12 @@ function countObservations(projectHash) {
     }
 }
 function getRecentObservations(projectHash, limit = 50) {
+    // Clamp a non-positive or non-integer limit to the default. slice(-0) would
+    // otherwise return the ENTIRE history (the limit:0 boundary), and a negative
+    // limit would drop rows from the front instead of taking the tail. ci_goal_check
+    // pre-rejects bad limits with a clear error(); this guards ci_observations and
+    // any other caller that passes a user-supplied limit straight through.
+    const cappedLimit = Number.isInteger(limit) && limit > 0 ? limit : 50;
     const observationsFile = join(INSTINCTS_DIR, projectHash, "observations.jsonl");
     if (!existsSync(observationsFile)) {
         return [];
@@ -182,7 +198,7 @@ function getRecentObservations(projectHash, limit = 50) {
         const lines = readFileSync(observationsFile, "utf8")
             .split("\n")
             .filter((line) => line.trim().length > 0);
-        return lines.slice(-limit).flatMap((line) => {
+        return lines.slice(-cappedLimit).flatMap((line) => {
             try {
                 return [JSON.parse(line)];
             }
@@ -195,6 +211,16 @@ function getRecentObservations(projectHash, limit = 50) {
         return [];
     }
 }
+function readDistillObservations(projectHash) {
+    return getRecentObservations(projectHash, 100000).map((observation) => ({
+        ts: getString(observation.ts),
+        session: getString(observation.session),
+        session_id: getString(observation.session_id),
+        tool: getString(observation.tool),
+        input_summary: getString(observation.input_summary),
+        output_summary: getString(observation.output_summary),
+    }));
+}
 function detectLevel(projectHash) {
     const observationCount = countObservations(projectHash);
     const instincts = readInstincts(projectHash);
@@ -480,6 +506,33 @@ function handleTool(name, params) {
             ].join("\n");
             return text(reflection);
         }
+        case "ci_gateguard_clear": {
+            // Beginner-available on purpose: the GateGuard hook fires for every
+            // install, so the clearance action must too. Resolves the session dir via
+            // gateguard-state (canonical), the same way the hook does, so the marker
+            // lands where the hook looks regardless of how each process spelled the
+            // project root.
+            const rawList = Array.isArray(params.file_paths) ? params.file_paths : [];
+            const listPaths = rawList.filter((value) => typeof value === "string" && value.length > 0);
+            const single = getString(params.file_path).trim();
+            const paths = single ? [...listPaths, single] : listPaths;
+            if (paths.length === 0) {
+                return error("file_paths is required — pass the file path(s) named in the GateGuard block reason, e.g. { file_paths: [\"src/x.ts\"] }.");
+            }
+            const sessionDir = resolveSessionDir();
+            const { cleared, skippedForCap } = clearFiles(sessionDir, paths);
+            const lines = [
+                "## GateGuard clearance",
+                "",
+                `**State file:** ${join(sessionDir, "gateguard-session.json")}`,
+                `**Cleared (${cleared.length}):** ${cleared.length > 0 ? cleared.join(", ") : "(none — already cleared)"}`,
+            ];
+            if (skippedForCap.length > 0) {
+                lines.push(`**Skipped — session cap of ${MAX_CLEARED_FILES} reached (${skippedForCap.length}):** ${skippedForCap.join(", ")}`, "Start a new session to reset the gate.");
+            }
+            lines.push("", "Retry the Edit/Write now — it will pass.");
+            return text(lines.join("\n"));
+        }
         case "ci_reinforce": {
             if (MODE !== "expert") {
                 return error("ci_reinforce requires expert mode. Start server with --mode expert");
@@ -665,6 +718,166 @@ function handleTool(name, params) {
             }
             return text(lines.join("\n"));
         }
+        case "ci_goal_check": {
+            if (MODE !== "expert") {
+                return error("ci_goal_check requires expert mode");
+            }
+            const limit = getNumber(params.limit, 30);
+            if (!Number.isInteger(limit) || limit <= 0) {
+                return error(`limit must be a positive integer; got ${limit}. Omit it to score the default 30 most recent observations.`);
+            }
+            const explicit = getString(params.goal_file).trim();
+            const workspaceRoot = getWorkspaceRoot();
+            const candidates = explicit
+                ? [explicit]
+                : [
+                    join(workspaceRoot, PLANNING_FILES.taskPlan),
+                    join(INSTINCTS_DIR, project.hash, "goal.md"),
+                ];
+            let goalContent = "";
+            let goalSource = "";
+            for (const candidate of candidates) {
+                if (!existsSync(candidate)) {
+                    continue;
+                }
+                try {
+                    goalContent = readFileSync(candidate, "utf8");
+                    goalSource = candidate;
+                    break;
+                }
+                catch {
+                    // try the next candidate
+                }
+            }
+            if (!goalContent) {
+                return text(`No goal source found. Looked for: ${candidates.join(", ")}.\nRun ci_plan_init (or /planning-with-files) to create ${PLANNING_FILES.taskPlan} with a '## Goal' section.`);
+            }
+            const goal = parseGoalFromPlan(goalContent);
+            if (!goal) {
+                return text(`Found ${goalSource} but it has no '## Goal' section. Add one — ci_plan_init seeds it. Optional '## Goal Keywords' and '## Goal Scope' sections sharpen the drift signal.`);
+            }
+            const goalObservations = getRecentObservations(project.hash, limit).map((observation) => ({
+                ts: getString(observation.ts),
+                tool: getString(observation.tool),
+                input_summary: getString(observation.input_summary),
+                output_summary: getString(observation.output_summary),
+            }));
+            const report = scoreObservations(goalObservations, goal, { window: limit });
+            return text(`## Goal Check\n\n**Goal source:** ${goalSource}\n\n${formatDriftReport(report)}`);
+        }
+        case "ci_recall": {
+            if (MODE !== "expert") {
+                return error("ci_recall requires expert mode");
+            }
+            const queryString = getString(params.query).trim();
+            if (!queryString) {
+                return error("query is required");
+            }
+            const k = getNumber(params.k, 5);
+            const since = getString(params.since).trim();
+            if (since && parseSince(since, Date.now()) === null) {
+                return error(`Could not parse since="${since}". Use an ISO timestamp (e.g. 2026-05-01) or a relative window like 7d, 24h, or 30m.`);
+            }
+            // Recall searches the full history, not just the recent window.
+            const recallObservations = getRecentObservations(project.hash, 100000).map((observation) => ({
+                ts: getString(observation.ts),
+                session: getString(observation.session),
+                session_id: getString(observation.session_id),
+                tool: getString(observation.tool),
+                input_summary: getString(observation.input_summary),
+                output_summary: getString(observation.output_summary),
+            }));
+            if (recallObservations.length === 0) {
+                return text("No observations yet. Hooks capture tool calls automatically; recall searches that history.");
+            }
+            const index = buildIndex(recallObservations);
+            const hits = queryRecall(index, queryString, { k, since: since || undefined });
+            return text(formatRecallHits(hits, queryString));
+        }
+        case "ci_distill_candidates": {
+            if (MODE !== "expert") {
+                return error("ci_distill_candidates requires expert mode");
+            }
+            const distillObservations = readDistillObservations(project.hash);
+            const candidates = findCandidates(extractTrajectories(distillObservations));
+            return text(formatCandidates(candidates));
+        }
+        case "ci_distill_propose": {
+            if (MODE !== "expert") {
+                return error("ci_distill_propose requires expert mode");
+            }
+            const id = getString(params.id).trim();
+            if (!id) {
+                return error("id is required — run ci_distill_candidates to list current candidate ids");
+            }
+            if (!isSafeDraftId(id)) {
+                return error(`Invalid draft id "${id}". Draft ids look like draft-<slug> (lowercase letters, digits, hyphens).`);
+            }
+            const distillObservations = readDistillObservations(project.hash);
+            const candidate = findCandidates(extractTrajectories(distillObservations)).find((entry) => entry.id === id);
+            if (!candidate) {
+                return error(`No candidate "${id}". Run ci_distill_candidates to list current ids.`);
+            }
+            const draft = serializeDraft(draftFromCandidate(candidate));
+            const draftsDir = join(INSTINCTS_DIR, project.hash, "drafts");
+            mkdirSync(draftsDir, { recursive: true });
+            const draftPath = join(draftsDir, `${id}.yaml`);
+            writeFileSync(draftPath, draft);
+            return text([
+                "## Draft written",
+                "",
+                `**Path:** ${draftPath}`,
+                "",
+                "Edit the body to capture the real recipe (preconditions, concrete steps, gotchas), then promote with:",
+                "",
+                `  ci_distill_promote id=${id}`,
+                "",
+                "```yaml",
+                draft.trimEnd(),
+                "```",
+            ].join("\n"));
+        }
+        case "ci_distill_promote": {
+            if (MODE !== "expert") {
+                return error("ci_distill_promote requires expert mode");
+            }
+            const id = getString(params.id).trim();
+            if (!id) {
+                return error("id is required");
+            }
+            if (!isSafeDraftId(id)) {
+                return error(`Invalid draft id "${id}". Draft ids look like draft-<slug> (lowercase letters, digits, hyphens).`);
+            }
+            const draftPath = join(INSTINCTS_DIR, project.hash, "drafts", `${id}.yaml`);
+            if (!existsSync(draftPath)) {
+                return error(`No draft at ${draftPath}. Run ci_distill_propose id=${id} first.`);
+            }
+            let parsed = null;
+            try {
+                parsed = parseYamlInstinct(readFileSync(draftPath, "utf8"));
+            }
+            catch {
+                parsed = null;
+            }
+            if (!parsed) {
+                return error(`Draft ${draftPath} could not be parsed as an instinct. Check the YAML shape.`);
+            }
+            const promoted = {
+                ...parsed,
+                confidence: 0.5,
+                source: "distilled",
+                scope: "project",
+                observation_count: 1,
+            };
+            writeInstinct(project.hash, promoted);
+            try {
+                rmSync(draftPath);
+            }
+            catch {
+                // best-effort cleanup; the live instinct is already written
+            }
+            return text(`Promoted **${promoted.id}** to a project instinct at confidence ${promoted.confidence} (SUGGEST tier). The draft has been consumed.`);
+        }
         case "ci_dashboard": {
             if (MODE !== "expert") {
                 return error("ci_dashboard requires expert mode");

package/plugins/continuous-improvement/commands/audit.md

@@ -0,0 +1,34 @@
+---
+name: audit
+description: Audit a window of recent commits for real defects, confirm each finding before fixing, verify every surface a fix touches, then report confirmed/dismissed/no-op with evidence. Enforces Law 4 (Verify Before Reporting).
+---
+
+# /audit — Confirm Recent Commits Before You Trust Them
+
+Run the audit-driven loop over recent work: a merged commit with green CI is a claim, not a proof.
+
+## What it does
+
+Takes a commit window, hunts for real defects one concern at a time, proves each finding against the actual code (false positives die before any edit), fixes on a branch with the smallest diff, verifies every surface the fix touches, and reports honestly. Backed by the `audit` skill.
+
+## The loop
+
+```
+1. Scope    git log to pick the window (e.g. HEAD~10..HEAD, or main since last release)
+2. Find     one pass per dimension: value/economy drift, concurrency, surface coverage, type/contract
+3. Confirm  read the actual lines; state in one sentence why it is real, or dismiss it
+4. Fix      one concern per commit; prefer a failing test first, then green
+5. Verify   exercise EVERY surface (backend, frontend, admin, cache, migration), not just the edited one
+6. Report   confirmed (with the proof), dismissed (with why), no-op (in scope, nothing to change)
+```
+
+## Default skeptical
+
+Findings are hypotheses. Default each to a false positive until the code proves the bug — defaulting to "real" is how plausible-but-wrong fixes ship. For a thorough audit, fan the find pass out across dimensions with parallel reviewers, then verify each survivor adversarially.
+
+## Pairs with
+
+- **`audit`** skill — the discipline this command runs.
+- **`code-review`** / **`security-review`** — the per-dimension passes.
+- **`reconcile`** — the safe branch→PR path once the audit produces a fix.
+- **`recall`** — check whether a finding was already hit and fixed before.