continuous-improvement 3.9.2 → 3.12.3

package/lib/plugin-metadata.mjs

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_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.";
+const SHARED_PLUGIN_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.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -76,7 +76,7 @@ const THIRD_PARTY_COMPANIONS = [
     },
     {
         name: "oh-my-claudecode",
-        description: "Multi-agent orchestration system for Claude Code — 39 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
+        description: "Multi-agent orchestration system for Claude Code — 38 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
         version: "4.13.6",
         source: "./third-party/oh-my-claudecode",
         author: {
@@ -127,6 +127,26 @@ const BEGINNER_TOOL_ENTRIES = [
             required: ["summary"],
         },
     },
+    {
+        name: "ci_gateguard_clear",
+        description: "Clear the GateGuard gate for one or more files after presenting the required facts (importers, affected APIs, data schema, the user's instruction). Records canonical per-file clearance in the session state the hook reads, so the next Edit/Write to those paths is allowed. Clearance matches regardless of drive-letter case or path separator. Available in beginner mode because the gate fires for every install.",
+        manifestWhat: "Clear the GateGuard gate for files after presenting facts",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_paths: {
+                    type: "array",
+                    description: "File paths to clear — the paths named in the GateGuard block reason",
+                    items: { type: "string" },
+                },
+                file_path: {
+                    type: "string",
+                    description: "A single file path to clear (alternative to file_paths)",
+                },
+            },
+            required: [],
+        },
+    },
 ];
 const EXPERT_TOOL_ENTRIES = [
     {
@@ -282,17 +302,88 @@ const EXPERT_TOOL_ENTRIES = [
             required: ["pack"],
         },
     },
+    {
+        name: "ci_goal_check",
+        description: "Check whether recent tool activity still relates to the stated goal. Reads the '## Goal' section of task_plan.md (plus optional '## Goal Keywords' and '## Goal Scope' sections), scores the last N observations, and reports a drift score with the top off-goal tool calls.",
+        manifestWhat: "Detect when a session has drifted from its stated goal",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "How many recent observations to score (default: 30)",
+                    default: 30,
+                },
+                goal_file: {
+                    type: "string",
+                    description: "Path to a goal/plan markdown file. Defaults to task_plan.md in the project root, then ~/.claude/instincts/<hash>/goal.md",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "ci_recall",
+        description: "Search past tool-call observations with BM25 ranking. Answers 'have I seen this before?' against ~/.claude/instincts/<hash>/observations.jsonl and returns the most relevant past activity with redacted snippets. Lexical, not semantic.",
+        manifestWhat: "Search past sessions for relevant prior activity (episodic recall)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search terms, e.g. an error message or a past task" },
+                k: {
+                    type: "number",
+                    description: "How many results to return (default: 5)",
+                    default: 5,
+                },
+                since: {
+                    type: "string",
+                    description: "Only search rows newer than this — ISO timestamp or relative window like '7d', '24h', '30m'",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "ci_distill_candidates",
+        description: "List distillation candidates: tool sequences that recurred across multiple successful sessions and could become reusable instincts. Read-only analysis — proposes nothing until you run ci_distill_propose.",
+        manifestWhat: "Find repeated successful tool sequences worth turning into skills",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "ci_distill_propose",
+        description: "Write a DRAFT instinct for a distillation candidate to ~/.claude/instincts/<hash>/drafts/. The draft has a placeholder body for you to edit; it does not affect behavior until promoted.",
+        manifestWhat: "Draft a reusable instinct from a repeated successful pattern",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Candidate id from ci_distill_candidates" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "ci_distill_promote",
+        description: "Promote an edited draft into a live project instinct at 0.5 confidence (SUGGEST tier) and consume the draft. Run after editing the draft body produced by ci_distill_propose.",
+        manifestWhat: "Promote an edited draft into a live instinct",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Draft id to promote" },
+            },
+            required: ["id"],
+        },
+    },
 ];
 const MODE_METADATA = {
     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.",
-        hooks: ["PreToolUse", "PostToolUse"],
-        hookDescription: "Silently captures every tool call as observations. Lightweight and non-blocking.",
+        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.",
+        hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit"],
+        hookDescription: "Silently captures every tool call as observations and routes prompts to the matching skill via the route table. Lightweight and non-blocking.",
     },
     expert: {
-        description: "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay disciplined and learnings survive context resets.",
-        hooks: ["PreToolUse", "PostToolUse", "SessionStart", "SessionEnd"],
-        hookDescription: "Full hook suite: observation capture + session-level instinct loading and auto-reflection.",
+        description: "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
+        hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SessionStart", "SessionEnd"],
+        hookDescription: "Full hook suite: observation capture, lazy prompt routing, session-level instinct loading, and auto-reflection.",
     },
 };
 function getToolCatalog(mode) {
@@ -361,6 +452,11 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gateguard.mjs\"",
         timeout: 5,
     };
+    const companionPreferenceCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/companion-preference.mjs\"",
+        timeout: 5,
+    };
     const observeCommand = {
         type: "command",
         command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
@@ -376,18 +472,41 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/three-section-close.mjs\"",
         timeout: 5,
     };
+    const goalDriftStopCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/goal-drift-stop.mjs\"",
+        timeout: 5,
+    };
+    const routePromptCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
+        timeout: 5,
+    };
+    const recallBriefingCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/recall-briefing.mjs\"",
+        timeout: 5,
+    };
     return {
-        description: "Gateguard fact-forcing PreToolUse, observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
         hooks: {
-            // gateguard runs FIRST so its block decision short-circuits before
-            // observe.sh records the tool call. observe.sh stays in PreToolUse for
-            // the observation feed; the Claude Code host runs both regardless of
-            // gateguard's decision.
-            PreToolUse: [{ hooks: [gateguardCommand, observeCommand] }],
+            // gateguard runs FIRST on PreToolUse so its block decision short-circuits
+            // before companion-preference sees the call. companion-preference runs
+            // second on Skill tool calls; it is a no-op under ci-first (the default)
+            // and never blocks under companions-first. observe.sh only runs on
+            // PostToolUse: gateguard-blocked calls are intentionally not observed so
+            // PreToolUse stays at two subprocesses on the hot path. route-prompt
+            // fires on UserPromptSubmit and emits a system-reminder when a prompt
+            // pattern in hooks/route-table.json matches; non-matching prompts pass
+            // through with no output.
+            PreToolUse: [
+                { hooks: [gateguardCommand, companionPreferenceCommand] },
+            ],
             PostToolUse: [{ hooks: [observeCommand] }],
+            UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand] }],
         },
     };
 }

package/lib/recall-briefing.mjs

@@ -0,0 +1,57 @@
+// recall-briefing.mts — Pure decision core for the proactive recall-briefing hook.
+//
+// No I/O. Given (enabled, already-briefed, prompt, ranked recall hits), decides
+// whether to inject a one-time-per-session "you've touched related work before"
+// system-reminder and renders it. The hook (src/hooks/recall-briefing.mts) does
+// the filesystem work — read the prompt, read observations.jsonl, build the BM25
+// index (recall-index.mts), track per-session state — then calls decideBriefing.
+// Keeping the decision pure lets the unit tests cover every gate and boundary
+// (disabled / already-briefed / empty-or-short prompt / no hits / malformed
+// input) without touching the filesystem, per the repo lesson that green gates
+// do not prove boundary safety.
+//
+// This is an amplifier, not a gate: it never blocks a prompt. It only surfaces
+// prior context so the agent reuses a past fix instead of re-deriving it. It is
+// opt-in (the hook checks an env flag) and fires at most once per session.
+export const DEFAULT_MAX_HITS = 3;
+export const DEFAULT_MIN_PROMPT_LENGTH = 12;
+/** Render ranked hits as a compact UserPromptSubmit system-reminder. Pure string. */
+export function formatBriefing(hits) {
+    const lines = [
+        "<system-reminder>",
+        "Recall briefing: this project has prior sessions that touched related work. Before re-deriving a fix, consider the `ci_recall` MCP tool (or `/recall`) for full context. Most relevant past activity:",
+    ];
+    for (const h of hits) {
+        const stamp = h && h.ts ? `[${h.ts}] ` : "";
+        const tool = (h && h.tool) || "(tool?)";
+        const snippet = ((h && h.snippet) || "").replace(/\s+/g, " ").trim();
+        lines.push(`- ${stamp}${tool}: ${snippet || "(no summary)"}`);
+    }
+    lines.push("</system-reminder>");
+    return lines.join("\n");
+}
+/**
+ * Decide whether to inject a recall briefing. Fails closed: any disabling
+ * condition (opted out, already briefed, prompt below the noise floor, no hits,
+ * malformed input) returns shouldBrief=false and never throws.
+ */
+export function decideBriefing(params) {
+    const none = { shouldBrief: false, reminder: null };
+    if (!params || params.enabled !== true)
+        return none;
+    if (params.alreadyBriefed === true)
+        return none;
+    const prompt = typeof params.prompt === "string" ? params.prompt : "";
+    const minLen = typeof params.minPromptLength === "number" && params.minPromptLength >= 0
+        ? params.minPromptLength
+        : DEFAULT_MIN_PROMPT_LENGTH;
+    if (prompt.trim().length < minLen)
+        return none;
+    const maxHits = typeof params.maxHits === "number" && params.maxHits > 0
+        ? Math.floor(params.maxHits)
+        : DEFAULT_MAX_HITS;
+    const hits = Array.isArray(params.hits) ? params.hits.slice(0, maxHits) : [];
+    if (hits.length === 0)
+        return none;
+    return { shouldBrief: true, reminder: formatBriefing(hits) };
+}

package/lib/recall-index.mjs

@@ -0,0 +1,175 @@
+// recall-index.mts — Pure BM25 episodic search over observation rows.
+//
+// No I/O. Turns a list of observation rows into a searchable in-memory index
+// and answers ranked queries with redacted snippets. The MCP tool ci_recall
+// (src/bin/mcp-server.mts) reads observations.jsonl and wires these functions;
+// keeping the index pure lets the unit tests cover tokenization, ranking,
+// recency filtering, and secret redaction without touching the filesystem.
+//
+// v1 is dependency-free (preserves the package's zero-runtime-deps property):
+// the index is rebuilt per query from the row list. At current observation
+// volumes (well under 100k rows) the rebuild is sub-50ms; a node:sqlite FTS5
+// migration is a follow-up if volumes grow.
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "are",
+    "was", "were", "but", "not", "all", "any", "can", "its", "out", "has", "had",
+]);
+const TOKEN_MIN_LENGTH = 2;
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+const DEFAULT_K = 5;
+const SNIPPET_RADIUS = 60;
+/** Lowercase, split on any non-letter / non-number / non-mark (Unicode-aware), drop stopwords and tokens shorter than TOKEN_MIN_LENGTH. */
+export function tokenize(text) {
+    const out = [];
+    for (const raw of text.toLowerCase().split(/[^\p{L}\p{N}\p{M}]+/u)) {
+        if (raw.length < TOKEN_MIN_LENGTH)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        out.push(raw);
+    }
+    return out;
+}
+/**
+ * Redact common secret shapes from a snippet before it is surfaced. Conservative
+ * by design: matches AWS access keys, JWT-shaped triplets, bearer tokens,
+ * KEY/SECRET/TOKEN/PASSWORD assignments, and long hex strings. Applied to every
+ * snippet returned by query().
+ */
+export function redactSecrets(text) {
+    return text
+        .replace(/AKIA[0-9A-Z]{16}/g, "AKIA<redacted>")
+        .replace(/Bearer\s+[A-Za-z0-9._~+/-]{20,}=*/gi, "Bearer <redacted>")
+        .replace(/\b([A-Za-z][A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|PWD))(\s*[:=]\s*)(\S+)/gi, "$1$2<redacted>")
+        .replace(/\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "<jwt-redacted>")
+        .replace(/\b[a-f0-9]{32,}\b/gi, "<hex-redacted>");
+}
+function docText(obs) {
+    return [obs.tool ?? "", obs.input_summary ?? "", obs.output_summary ?? ""]
+        .filter((part) => part.length > 0)
+        .join("  ");
+}
+/** Build an in-memory BM25 index from a list of observation rows. */
+export function buildIndex(observations) {
+    const docs = [];
+    const df = new Map();
+    let totalLength = 0;
+    observations.forEach((obs, index) => {
+        const text = docText(obs);
+        const tokens = tokenize(text);
+        const tf = new Map();
+        for (const token of tokens) {
+            tf.set(token, (tf.get(token) ?? 0) + 1);
+        }
+        for (const term of tf.keys()) {
+            df.set(term, (df.get(term) ?? 0) + 1);
+        }
+        docs.push({ obs, index, text, tf, length: tokens.length });
+        totalLength += tokens.length;
+    });
+    return {
+        docs,
+        df,
+        avgdl: docs.length > 0 ? totalLength / docs.length : 0,
+        n: docs.length,
+    };
+}
+function idf(index, term) {
+    const df = index.df.get(term) ?? 0;
+    return Math.log(1 + (index.n - df + 0.5) / (df + 0.5));
+}
+function scoreDoc(index, doc, queryTerms) {
+    let score = 0;
+    for (const term of queryTerms) {
+        const freq = doc.tf.get(term);
+        if (!freq)
+            continue;
+        const denom = freq + BM25_K1 * (1 - BM25_B + (BM25_B * doc.length) / (index.avgdl || 1));
+        score += idf(index, term) * ((freq * (BM25_K1 + 1)) / denom);
+    }
+    return score;
+}
+/** Parse an ISO timestamp or a relative window ("7d", "24h", "30m") into a cutoff epoch-ms. */
+export function parseSince(since, now) {
+    const relative = since.trim().match(/^(\d+)\s*([dhm])$/i);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const unit = relative[2].toLowerCase();
+        const ms = unit === "d" ? 86_400_000 : unit === "h" ? 3_600_000 : 60_000;
+        return now - amount * ms;
+    }
+    const parsed = Date.parse(since);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function obsSession(obs) {
+    return (obs.session ?? obs.session_id ?? "").toString();
+}
+function makeSnippet(text, queryTerms) {
+    const lower = text.toLowerCase();
+    let pos = -1;
+    for (const term of queryTerms) {
+        const found = lower.indexOf(term);
+        if (found !== -1 && (pos === -1 || found < pos))
+            pos = found;
+    }
+    if (pos === -1)
+        pos = 0;
+    const start = Math.max(0, pos - SNIPPET_RADIUS);
+    const end = Math.min(text.length, pos + SNIPPET_RADIUS);
+    let snippet = text.slice(start, end);
+    if (start > 0)
+        snippet = `…${snippet}`;
+    if (end < text.length)
+        snippet = `${snippet}…`;
+    return redactSecrets(snippet);
+}
+/**
+ * Rank observations against a query with BM25. Results are sorted by score
+ * descending, ties broken by recency (ts descending). `since` filters out rows
+ * older than an ISO timestamp or relative window. Snippets are redacted.
+ */
+export function query(index, queryString, opts = {}) {
+    const queryTerms = [...new Set(tokenize(queryString))];
+    if (queryTerms.length === 0)
+        return [];
+    const k = opts.k && opts.k > 0 ? opts.k : DEFAULT_K;
+    const cutoff = opts.since ? parseSince(opts.since, opts.now ?? Date.now()) : null;
+    const hits = [];
+    for (const doc of index.docs) {
+        const ts = (doc.obs.ts ?? "").toString();
+        if (cutoff !== null) {
+            // Fail closed: a row with no ts or an unparseable ts has unknown age, so
+            // it must not leak through a time-bounded query.
+            const tsMs = ts ? Date.parse(ts) : Number.NaN;
+            if (Number.isNaN(tsMs) || tsMs < cutoff)
+                continue;
+        }
+        const score = scoreDoc(index, doc, queryTerms);
+        if (score <= 0)
+            continue;
+        hits.push({
+            ts,
+            session: obsSession(doc.obs),
+            tool: (doc.obs.tool ?? "").toString(),
+            snippet: makeSnippet(doc.text, queryTerms),
+            score,
+            index: doc.index,
+        });
+    }
+    hits.sort((a, b) => (b.score !== a.score ? b.score - a.score : b.ts.localeCompare(a.ts)));
+    return hits.slice(0, k);
+}
+/** Render ranked hits as a markdown block for the MCP tool output. Pure string -> string. */
+export function formatRecallHits(hits, queryString) {
+    if (hits.length === 0) {
+        return `No past observations matched "${queryString}". Try broader or different terms — recall is lexical, not semantic.`;
+    }
+    const lines = [`## Recall: "${queryString}"`, "", `${hits.length} match(es), most relevant first:`, ""];
+    for (const hit of hits) {
+        const stamp = hit.ts ? `[${hit.ts}] ` : "";
+        lines.push(`- ${stamp}**${hit.tool || "(tool?)"}** (score ${hit.score.toFixed(2)})`);
+        lines.push(`  ${hit.snippet || "(no summary)"}`);
+    }
+    return lines.join("\n");
+}

package/lib/skill-distill.mjs

@@ -0,0 +1,222 @@
+// skill-distill.mts — Pure trajectory → draft-skill distillation.
+//
+// No I/O. Scans observation rows for repeated tool sequences that ended in a
+// successful verification, and proposes DRAFT instincts capturing the pattern.
+// The MCP tools ci_distill_candidates / ci_distill_propose / ci_distill_promote
+// (src/bin/mcp-server.mts) wire the file reads and writes around these
+// functions.
+//
+// Closed-loop "Learn From Every Session" (Law 7) on the SUCCESS side: the
+// friction harvester (src/bin/harvest-friction.mts) already turns failures into
+// instincts; this turns repeated wins into reusable drafts. Drafts never enter
+// the suggestion pool — they require explicit promotion — so a coincidental
+// tool sequence cannot cargo-cult itself into enforced behavior.
+const MIN_TRAJECTORY_LENGTH = 4;
+const GAP_MS = 10 * 60 * 1000;
+const NGRAM_SIZES = [3, 4, 5];
+const DEFAULT_MIN_OCCURRENCES = 3;
+const DEFAULT_MIN_SESSIONS = 2;
+const DRAFT_CONFIDENCE = 0.4;
+const VERIFY_CMD = /\b(npm\s+(run\s+)?(test|verify(:[\w-]+)?|build)|pnpm\s+(test|build)|yarn\s+(test|build)|pytest|cargo\s+test|go\s+test|jest|vitest|make\s+test)\b/i;
+const FAILURE_MARKER = /\b(error|errors|fail|failed|failing|not found|denied|cannot|exception|traceback)\b|exit code [1-9]/i;
+const SUCCESS_MARKER = /\b(pass|passed|passing|success|succeeded|green|0 failures|all tests)\b|\bok\b/i;
+const REFLECTION_MARKER = /\b(verified|phase[- ]?4|verify:all green|all tests pass)\b/i;
+const NOISE_TOOL = /^(ci_|mcp__|TodoWrite$)/;
+function session(obs) {
+    return (obs.session ?? obs.session_id ?? "").toString();
+}
+function text(obs) {
+    return `${obs.input_summary ?? ""}\n${obs.output_summary ?? ""}`;
+}
+function classifyTrajectorySuccess(observations) {
+    for (const obs of observations) {
+        if ((obs.tool ?? "") === "Bash") {
+            const input = (obs.input_summary ?? "").toString();
+            const output = (obs.output_summary ?? "").toString();
+            if (VERIFY_CMD.test(input) && !FAILURE_MARKER.test(output) && (output === "" || SUCCESS_MARKER.test(output))) {
+                return "verify-exit-0";
+            }
+        }
+    }
+    for (const obs of observations) {
+        if (REFLECTION_MARKER.test(text(obs))) {
+            return "reflection-pass";
+        }
+    }
+    return null;
+}
+/**
+ * Split a chronological observation list into contiguous trajectories. A
+ * boundary occurs on session change or a time gap longer than GAP_MS. Only
+ * trajectories of at least MIN_TRAJECTORY_LENGTH observations are returned;
+ * each is classified as succeeded or not.
+ */
+export function extractTrajectories(observations) {
+    const out = [];
+    let group = [];
+    const flush = () => {
+        if (group.length < MIN_TRAJECTORY_LENGTH) {
+            group = [];
+            return;
+        }
+        const successReason = classifyTrajectorySuccess(group);
+        out.push({
+            observations: group,
+            session: session(group[0]),
+            startTs: (group[0].ts ?? "").toString(),
+            endTs: (group[group.length - 1].ts ?? "").toString(),
+            succeeded: successReason !== null,
+            successReason,
+        });
+        group = [];
+    };
+    for (const obs of observations) {
+        if (group.length === 0) {
+            group.push(obs);
+            continue;
+        }
+        const prev = group[group.length - 1];
+        const sessionChanged = session(obs) !== session(prev);
+        const prevMs = Date.parse((prev.ts ?? "").toString());
+        const curMs = Date.parse((obs.ts ?? "").toString());
+        const prevValid = !Number.isNaN(prevMs);
+        const curValid = !Number.isNaN(curMs);
+        const gapTooBig = (prevValid && curValid && curMs - prevMs > GAP_MS) || (prevValid !== curValid);
+        if (sessionChanged || gapTooBig) {
+            flush();
+        }
+        group.push(obs);
+    }
+    flush();
+    return out;
+}
+function toolSequence(trajectory) {
+    return trajectory.observations
+        .map((obs) => (obs.tool ?? "").toString())
+        .filter((tool) => tool.length > 0 && !NOISE_TOOL.test(tool));
+}
+// Tool names are external data (observations.jsonl). The candidate id is later
+// joined into a draft file path, so it must be slugified to [a-z0-9-] to keep a
+// hostile tool name (`../`, `/`, `\`) from escaping the drafts directory.
+function slugifyNgram(ngram) {
+    const slug = ngram
+        .join("-")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : "sequence";
+}
+/**
+ * Mine repeated tool-sequence n-grams from SUCCESSFUL trajectories. A candidate
+ * must occur at least `minOccurrences` times across at least `minSessions`
+ * distinct sessions — so a pattern repeated within a single session is rejected.
+ * Sorted by occurrences then n-gram length, both descending.
+ */
+export function findCandidates(trajectories, opts = {}) {
+    const minOccurrences = opts.minOccurrences ?? DEFAULT_MIN_OCCURRENCES;
+    const minSessions = opts.minSessions ?? DEFAULT_MIN_SESSIONS;
+    const aggregates = new Map();
+    for (const trajectory of trajectories) {
+        if (!trajectory.succeeded)
+            continue;
+        const sequence = toolSequence(trajectory);
+        const outcome = trajectory.successReason ?? "unknown";
+        for (const size of NGRAM_SIZES) {
+            for (let i = 0; i + size <= sequence.length; i += 1) {
+                const ngram = sequence.slice(i, i + size);
+                const key = ngram.join(">");
+                let aggregate = aggregates.get(key);
+                if (!aggregate) {
+                    aggregate = { ngram, occurrences: 0, sessions: new Set(), outcomes: new Set() };
+                    aggregates.set(key, aggregate);
+                }
+                aggregate.occurrences += 1;
+                aggregate.sessions.add(trajectory.session);
+                aggregate.outcomes.add(outcome);
+            }
+        }
+    }
+    const candidates = [];
+    for (const aggregate of aggregates.values()) {
+        if (aggregate.occurrences < minOccurrences)
+            continue;
+        if (aggregate.sessions.size < minSessions)
+            continue;
+        candidates.push({
+            id: `draft-${slugifyNgram(aggregate.ngram)}`,
+            ngram: aggregate.ngram,
+            occurrences: aggregate.occurrences,
+            sessions: [...aggregate.sessions],
+            outcomes: [...aggregate.outcomes],
+        });
+    }
+    candidates.sort((a, b) => b.occurrences !== a.occurrences ? b.occurrences - a.occurrences : b.ngram.length - a.ngram.length);
+    return candidates;
+}
+/** Turn a candidate into a DRAFT instinct with a placeholder body for the user to fill in. */
+export function draftFromCandidate(candidate) {
+    const arrow = candidate.ngram.join(" → ");
+    const outcome = candidate.outcomes.join(", ");
+    return {
+        id: candidate.id,
+        trigger: `Auto-detected pattern: ${candidate.ngram.join(" then ")} (seen ${candidate.occurrences}x across ${candidate.sessions.length} sessions)`,
+        body: [
+            "When this situation recurs, follow the proven sequence that worked before:",
+            "",
+            `  ${arrow}`,
+            "",
+            `This pattern succeeded in ${candidate.occurrences} run(s) across ${candidate.sessions.length} session(s) (outcome: ${outcome}).`,
+            "Replace this placeholder with the concrete steps, preconditions, and gotchas before promoting —",
+            "the tool sequence alone is evidence, not a recipe.",
+        ].join("\n"),
+        confidence: DRAFT_CONFIDENCE,
+        domain: "workflow",
+        ngram: candidate.ngram,
+        occurrences: candidate.occurrences,
+        sessions: candidate.sessions.length,
+        outcome,
+    };
+}
+/**
+ * Serialize a draft to the instinct YAML format (key: value lines, `---`, body)
+ * so it round-trips through the same parser that reads live instincts. Stored
+ * under drafts/ so it is not picked up as a live instinct until promoted.
+ */
+export function serializeDraft(draft) {
+    return [
+        `id: ${draft.id}`,
+        `trigger: "${draft.trigger}"`,
+        `confidence: ${draft.confidence}`,
+        `domain: ${draft.domain}`,
+        "source: distilled",
+        "status: draft",
+        `evidence_ngram: "${draft.ngram.join(">")}"`,
+        `evidence_occurrences: ${draft.occurrences}`,
+        `evidence_sessions: ${draft.sessions}`,
+        `evidence_outcome: "${draft.outcome}"`,
+        "---",
+        draft.body,
+        "",
+    ].join("\n");
+}
+/** Render candidates as a markdown block for the MCP tool output. */
+export function formatCandidates(candidates, limit = 10) {
+    if (candidates.length === 0) {
+        return "No distillation candidates found. A candidate needs a tool sequence that recurred across multiple successful sessions. Keep working — patterns accrue as the observation log grows.";
+    }
+    const shown = candidates.slice(0, limit);
+    const lines = [
+        `## Distillation Candidates (${candidates.length})`,
+        "",
+        "Repeated tool sequences from successful sessions. Propose a draft with `ci_distill_propose id=<id>`, edit its body, then `ci_distill_promote id=<id>`.",
+        "",
+    ];
+    for (const candidate of shown) {
+        lines.push(`- **${candidate.id}**`, `  Sequence: ${candidate.ngram.join(" → ")}`, `  Seen ${candidate.occurrences}x across ${candidate.sessions.length} session(s) — outcome: ${candidate.outcomes.join(", ")}`);
+    }
+    if (candidates.length > limit) {
+        lines.push("", `_…and ${candidates.length - limit} more._`);
+    }
+    return lines.join("\n");
+}