continuous-improvement 3.9.2 → 3.11.0

package/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/bin/generate-plugin-manifests.mjs

@@ -35,7 +35,7 @@ async function writeBundledSkills() {
     const sourceSkillsDir = join(REPO_ROOT, "skills");
     const targetSkillsDir = join(PLUGIN_BUNDLE_DIR, "skills");
     const companionSkills = (await readdir(sourceSkillsDir))
-        .filter((file) => /^[a-z][a-z0-9-]*\.md$/.test(file))
+        .filter((file) => file.endsWith(".md") && file !== "README.md")
         .sort();
     await mkdir(targetSkillsDir, { recursive: true });
     await copyFileTo(join(REPO_ROOT, "SKILL.md"), join(targetSkillsDir, PACKAGE_NAME, "SKILL.md"));
@@ -145,9 +145,15 @@ async function writePluginBundle() {
         copyFileTo(join(REPO_ROOT, "bin", "mcp-server.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "mcp-server.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "observe.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "observe.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "backfill.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "backfill.mjs")),
+        copyFileTo(join(REPO_ROOT, "bin", "gateguard-clear.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "gateguard-clear.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "gateguard-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "gateguard-state.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "plugin-metadata.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "plugin-metadata.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "resolve-home-dir.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "resolve-home-dir.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "observe-event.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "observe-event.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "goal-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "goal-state.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "goal-drift-gate.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "goal-drift-gate.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "recall-index.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "recall-index.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "skill-distill.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "skill-distill.mjs")),
         copyFileTo(join(REPO_ROOT, "LICENSE"), join(PLUGIN_BUNDLE_DIR, "LICENSE")),
         writePluginBundleReadme(),
     ]);

package/bin/install.mjs

@@ -8,7 +8,7 @@
  *   npx continuous-improvement install --pack react   # load starter instinct pack
  *   npx continuous-improvement install --uninstall    # remove everything
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { execSync } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -32,13 +32,40 @@ const COMMAND_FILES = [
     "seven-laws.md",
     "superpowers.md",
     "swarm.md",
+    "verify-install.md",
     "workspace-surface-audit.md",
 ];
 const HOOK_TYPES = ["PreToolUse", "PostToolUse"];
 const SESSION_HOOK_TYPES = ["SessionStart", "SessionEnd"];
+// Iterated by install cleanup and uninstall cleanup. Deduped via Set so an
+// accidental overlap between HOOK_TYPES and SESSION_HOOK_TYPES never causes
+// a hook bucket to be processed twice.
+const ALL_HOOK_TYPES = Array.from(new Set([...HOOK_TYPES, ...SESSION_HOOK_TYPES]));
+// Our installer writes `bash ".../.claude/instincts/(observe|session).sh"`.
+// Older Windows installs sometimes stored the same command with backslashes in
+// the quoted path; those no-op because bash can't resolve them. We strip only
+// that installer-owned command shape so foreign hooks that merely mention
+// observe.sh/session.sh survive.
+const INSTALLER_OBSERVE_SESSION_COMMAND_RE = /^bash ".*[\\/]\.claude[\\/]instincts[\\/](?:observe|session)\.sh"$/;
+function isBrokenObserveOrSessionCommand(command) {
+    if (typeof command !== "string")
+        return false;
+    return command.includes("\\") && INSTALLER_OBSERVE_SESSION_COMMAND_RE.test(command);
+}
+// Any installer-owned observe.sh / session.sh hook command, broken or clean.
+// Used by uninstall to drop both freshly-installed forward-slash hooks and any
+// stale legacy entries. Pairs with isBrokenObserveOrSessionCommand above.
+function isOurObserveOrSessionCommand(command) {
+    if (typeof command !== "string")
+        return false;
+    return INSTALLER_OBSERVE_SESSION_COMMAND_RE.test(command);
+}
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
+function toBashPath(filePath) {
+    return filePath.replace(/\\/g, "/");
+}
 function isInstallMode(value) {
     return value === "beginner" || value === "expert";
 }
@@ -53,6 +80,62 @@ function readJsonFile(filePath) {
         return null;
     }
 }
+// The observation hooks (hooks/observe.sh, hooks/session.sh) are bash scripts.
+// On Windows without Git Bash / WSL the hook commands written into settings.json
+// silently no-op, so the user finishes install thinking observation capture is
+// live when it never fires. Refuse the install with one actionable line instead.
+function assertBashAvailableOnWindows() {
+    if (process.platform !== "win32")
+        return;
+    try {
+        execSync("bash --version", { stdio: "ignore" });
+    }
+    catch {
+        console.error("  ✗ Install refused: the observation hooks (hooks/observe.sh, hooks/session.sh) " +
+            "are bash scripts, but `bash --version` is not on PATH. Install Git Bash or WSL, " +
+            "reopen your shell, and re-run — see README → Troubleshooting install.");
+        process.exit(1);
+    }
+}
+// The marketplace `/plugin install` path and this npx installer both write into
+// ~/.claude/. Running both duplicates hooks, commands, and skills. We cannot
+// fully resolve Claude Code's marketplace layout from here, so this is a loud
+// best-effort warning, not a hard refuse — a scan failure must never block install.
+function warnOnMarketplaceCollision() {
+    const pluginsDir = join(getHomeDir(), ".claude", "plugins");
+    if (!existsSync(pluginsDir))
+        return;
+    let hit = false;
+    try {
+        for (const entry of readdirSync(pluginsDir)) {
+            if (entry.includes(SKILL_NAME)) {
+                hit = true;
+                break;
+            }
+            const sub = join(pluginsDir, entry);
+            try {
+                if (statSync(sub).isDirectory() &&
+                    readdirSync(sub).some((e) => e.includes(SKILL_NAME))) {
+                    hit = true;
+                    break;
+                }
+            }
+            catch {
+                // unreadable entry — skip it
+            }
+        }
+    }
+    catch {
+        // best-effort — never block install on a scan failure
+        return;
+    }
+    if (hit) {
+        console.warn("\n  ! Possible Beginner+Expert collision: a marketplace install of\n" +
+            "    continuous-improvement looks present under ~/.claude/plugins/. Running the\n" +
+            "    npx installer on top of it duplicates hooks/commands/skills in ~/.claude/.\n" +
+            "    Pick ONE path — marketplace (/plugin install) or npx — not both.\n");
+    }
+}
 const rawArgs = process.argv.slice(2);
 const modeIndex = rawArgs.indexOf("--mode");
 const requestedMode = modeIndex !== -1 ? rawArgs[modeIndex + 1] : undefined;
@@ -169,9 +252,10 @@ function setupMcpServer() {
         console.log("  ✓ Claude Desktop MCP config updated");
     }
 }
-function hookAlreadyPatched(entries, scriptName) {
-    return entries.some((entry) => Array.isArray(entry.hooks) &&
-        entry.hooks.some((hook) => hook.command.includes(scriptName)));
+function hookAlreadyPatched(entries, expectedCommand) {
+    return entries.some((entry) => entry &&
+        Array.isArray(entry.hooks) &&
+        entry.hooks.some((hook) => typeof hook?.command === "string" && hook.command === expectedCommand));
 }
 function patchClaudeSettings(observePath) {
     const settingsPath = join(getHomeDir(), ".claude", "settings.json");
@@ -183,39 +267,75 @@ function patchClaudeSettings(observePath) {
     if (!settings.hooks) {
         settings.hooks = {};
     }
-    const hookEntry = {
-        matcher: "",
-        hooks: [
-            {
-                type: "command",
-                command: `bash "${observePath}"`,
-            },
-        ],
-    };
+    // Strip broken legacy observe/session hooks at the hook level, not the entry
+    // level. A single entry may carry a foreign command alongside a broken hook;
+    // dropping the whole entry to remove the broken hook would also wipe the
+    // foreign one. Malformed rows (missing/non-array .hooks) are preserved verbatim
+    // — we don't know enough to filter them safely, and dropping risks data loss.
     let changed = false;
+    for (const hookType of ALL_HOOK_TYPES) {
+        const hookEntries = settings.hooks[hookType];
+        if (!Array.isArray(hookEntries))
+            continue;
+        let entryListChanged = false;
+        const cleanedEntries = [];
+        for (const entry of hookEntries) {
+            const entryHooks = entry?.hooks;
+            if (!Array.isArray(entryHooks)) {
+                cleanedEntries.push(entry);
+                continue;
+            }
+            const filteredHooks = entryHooks.filter((hook) => !isBrokenObserveOrSessionCommand(hook?.command));
+            if (filteredHooks.length === entryHooks.length) {
+                cleanedEntries.push(entry);
+                continue;
+            }
+            entryListChanged = true;
+            if (filteredHooks.length > 0) {
+                const cleanedEntry = {
+                    ...entry,
+                    hooks: filteredHooks,
+                };
+                cleanedEntries.push(cleanedEntry);
+            }
+        }
+        if (entryListChanged) {
+            settings.hooks[hookType] = cleanedEntries;
+            changed = true;
+        }
+    }
+    const observeCommand = `bash "${toBashPath(observePath)}"`;
     for (const hookType of HOOK_TYPES) {
         if (!Array.isArray(settings.hooks[hookType])) {
             settings.hooks[hookType] = [];
         }
         const hookEntries = settings.hooks[hookType];
-        if (!hookAlreadyPatched(hookEntries, "observe.sh")) {
-            hookEntries.push(hookEntry);
+        if (!hookAlreadyPatched(hookEntries, observeCommand)) {
+            hookEntries.push({
+                matcher: "",
+                hooks: [
+                    {
+                        type: "command",
+                        command: observeCommand,
+                    },
+                ],
+            });
             changed = true;
         }
     }
     if (INSTALL_MODE === "expert") {
         const sessionPath = join(getHomeDir(), ".claude", "instincts", "session.sh");
-        const sessionHook = {
-            matcher: "",
-            hooks: [{ type: "command", command: `bash "${sessionPath}"` }],
-        };
+        const sessionCommand = `bash "${toBashPath(sessionPath)}"`;
         for (const hookType of SESSION_HOOK_TYPES) {
             if (!Array.isArray(settings.hooks[hookType])) {
                 settings.hooks[hookType] = [];
             }
             const hookEntries = settings.hooks[hookType];
-            if (!hookAlreadyPatched(hookEntries, "session.sh")) {
-                hookEntries.push(sessionHook);
+            if (!hookAlreadyPatched(hookEntries, sessionCommand)) {
+                hookEntries.push({
+                    matcher: "",
+                    hooks: [{ type: "command", command: sessionCommand }],
+                });
                 changed = true;
             }
         }
@@ -292,16 +412,43 @@ function uninstallAll() {
         const settings = readJsonFile(settingsPath);
         if (settings) {
             let changed = false;
-            for (const hookType of [...HOOK_TYPES, ...SESSION_HOOK_TYPES]) {
+            // Filter at the hook level, not the entry level. A foreign command may
+            // share an entry with one of ours; entry-level deletion would silently
+            // wipe the foreign hook. Malformed rows (missing/non-array .hooks) are
+            // preserved verbatim — we don't know enough to filter them safely.
+            // ALL_HOOK_TYPES dedupes any future overlap between HOOK_TYPES and
+            // SESSION_HOOK_TYPES so a bucket is never processed twice.
+            for (const hookType of ALL_HOOK_TYPES) {
                 const hookEntries = settings.hooks?.[hookType];
                 if (!Array.isArray(hookEntries)) {
                     continue;
                 }
-                const nextEntries = hookEntries.filter((entry) => !entry.hooks.some((hook) => hook.command.includes("observe.sh") || hook.command.includes("session.sh")));
-                if (nextEntries.length !== hookEntries.length) {
+                let entryListChanged = false;
+                const cleanedEntries = [];
+                for (const entry of hookEntries) {
+                    const entryHooks = entry?.hooks;
+                    if (!Array.isArray(entryHooks)) {
+                        cleanedEntries.push(entry);
+                        continue;
+                    }
+                    const filteredHooks = entryHooks.filter((hook) => !isOurObserveOrSessionCommand(hook?.command));
+                    if (filteredHooks.length === entryHooks.length) {
+                        cleanedEntries.push(entry);
+                        continue;
+                    }
+                    entryListChanged = true;
+                    if (filteredHooks.length > 0) {
+                        const cleanedEntry = {
+                            ...entry,
+                            hooks: filteredHooks,
+                        };
+                        cleanedEntries.push(cleanedEntry);
+                    }
+                }
+                if (entryListChanged) {
+                    settings.hooks[hookType] = cleanedEntries;
                     changed = true;
                 }
-                settings.hooks[hookType] = nextEntries;
             }
             if (settings.mcpServers?.["continuous-improvement"]) {
                 delete settings.mcpServers["continuous-improvement"];
@@ -403,6 +550,8 @@ console.log(`
 continuous-improvement (mode: ${INSTALL_MODE})
 Research → Plan → Execute → Verify → Reflect → Learn → Iterate
 `);
+assertBashAvailableOnWindows();
+warnOnMarketplaceCollision();
 console.log("Installing to Claude Code...\n");
 const installed = installSkill() ? 1 : 0;
 const modeInfo = {
@@ -417,7 +566,14 @@ if (packIndex !== -1 && rawArgs[packIndex + 1]) {
         const project = getProjectHashSync();
         const targetDir = join(getHomeDir(), ".claude", "instincts", project.hash);
         mkdirSync(targetDir, { recursive: true });
-        const instincts = JSON.parse(readFileSync(packPath, "utf8"));
+        let instincts = [];
+        try {
+            instincts = JSON.parse(readFileSync(packPath, "utf8"));
+        }
+        catch (error) {
+            console.error(`  ✗ Pack "${packName}" could not be loaded: ${getErrorMessage(error)}\n` +
+                `    ${packPath} is not valid JSON. No instincts were written — fix or re-fetch the pack file.`);
+        }
         let loaded = 0;
         for (const instinct of instincts) {
             const instinctPath = join(targetDir, `${instinct.id}.yaml`);

package/bin/mcp-server.mjs

@@ -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");