continuous-improvement 3.9.2 → 3.11.0

package/lib/goal-state.mjs

@@ -0,0 +1,285 @@
+// goal-state.mts — Pure goal-drift scorer for the Clear Goal discipline.
+//
+// No I/O. Turns a task_plan.md body + a list of recent observation rows into a
+// DriftReport that says whether recent tool activity still relates to the
+// stated goal. The MCP tool ci_goal_check (src/bin/mcp-server.mts) wires the
+// file reads around these functions; keeping the logic pure lets the unit
+// tests cover the scoring edges without touching the filesystem.
+//
+// Goal source: a markdown plan with a `## Goal` section (seeded by ci_plan_init).
+// Two optional sections sharpen the signal:
+//   ## Goal Keywords   — comma/newline list; overrides auto-extraction
+//   ## Goal Scope       — `paths:` and `forbidden:` glob lists
+// When ## Goal Keywords is absent, keywords are auto-extracted from the prose.
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "will",
+    "should", "must", "have", "has", "are", "was", "were", "but", "not", "all",
+    "any", "can", "use", "using", "used", "via", "per", "out", "its", "their",
+    "them", "then", "than", "when", "what", "which", "who", "how", "why", "where",
+    "make", "made", "adds", "new", "get", "got", "set", "also", "only", "each",
+    "task", "goal", "plan", "work", "working", "build", "building", "code",
+]);
+// 4 suits Latin/Cyrillic prose, but it silently drops most Korean/Thai words
+// (typically 2 chars) even though the Unicode splitter now keeps them — so the
+// goal-state half of the tokenizer fix is only partial for those scripts. A
+// script-aware floor is a logged follow-up (see CLAUDE.md Deferred).
+const KEYWORD_MIN_LENGTH = 4;
+const KEYWORD_CAP = 20;
+const DEFAULT_WINDOW = 30;
+const DEFAULT_THRESHOLD = 0.3;
+const MAX_MISMATCHES = 5;
+/**
+ * Extract the body of a `## Heading` section. Stops at the next heading of any
+ * level. Heading match is case-insensitive on the trimmed text. Returns "" when
+ * the section is absent or empty.
+ */
+export function getSection(markdown, heading) {
+    const lines = markdown.split(/\r?\n/);
+    const out = [];
+    let inSection = false;
+    const wanted = heading.trim().toLowerCase();
+    for (const line of lines) {
+        if (/^#{1,6}\s/.test(line)) {
+            if (inSection)
+                break;
+            inSection = line.replace(/^#{1,6}\s+/, "").trim().toLowerCase() === wanted;
+            continue;
+        }
+        if (inSection)
+            out.push(line);
+    }
+    return out.join("\n").trim();
+}
+/**
+ * Tokenize prose into goal keywords: lowercase, split on any non-letter /
+ * non-number (Unicode-aware, so accented Latin / Cyrillic / CJK survive), drop
+ * stopwords, pure-digit tokens, and tokens shorter than KEYWORD_MIN_LENGTH.
+ * Deduped, capped at KEYWORD_CAP.
+ */
+export function extractKeywordsFromProse(prose) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of prose.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        const word = raw.trim();
+        if (word.length < KEYWORD_MIN_LENGTH)
+            continue;
+        if (/^\p{N}+$/u.test(word))
+            continue;
+        if (STOPWORDS.has(word))
+            continue;
+        if (seen.has(word))
+            continue;
+        seen.add(word);
+        out.push(word);
+        if (out.length >= KEYWORD_CAP)
+            break;
+    }
+    return out;
+}
+function parseKeywordList(body) {
+    const seen = new Set();
+    const out = [];
+    for (const token of body.split(/[,\n]/)) {
+        const word = token.replace(/^[-*\s]+/, "").trim().toLowerCase();
+        if (!word || seen.has(word))
+            continue;
+        seen.add(word);
+        out.push(word);
+    }
+    return out;
+}
+function parseScopeField(scopeBody, field) {
+    for (const line of scopeBody.split(/\r?\n/)) {
+        const match = line.match(/^\s*[-*]?\s*([A-Za-z_]+)\s*:\s*(.+)$/);
+        if (match && match[1].toLowerCase() === field) {
+            return match[2]
+                .split(",")
+                .map((glob) => glob.trim())
+                .filter((glob) => glob.length > 0);
+        }
+    }
+    return [];
+}
+/**
+ * Parse a plan markdown into a GoalSpec. Returns null when there is no `## Goal`
+ * section (the scorer needs a goal to score against).
+ */
+export function parseGoalFromPlan(planMarkdown) {
+    const prose = getSection(planMarkdown, "Goal");
+    if (!prose)
+        return null;
+    const keywordsSection = getSection(planMarkdown, "Goal Keywords");
+    const scopeSection = getSection(planMarkdown, "Goal Scope");
+    const parsedKeywords = keywordsSection ? parseKeywordList(keywordsSection) : [];
+    // An empty/malformed Goal Keywords section (blank bullets, commas-only) must
+    // degrade to prose extraction, exactly like an absent section — otherwise the
+    // scorer runs with zero keywords and reports all on-goal work as drift.
+    const keywords = parsedKeywords.length > 0 ? parsedKeywords : extractKeywordsFromProse(prose);
+    return {
+        prose,
+        keywords,
+        paths: scopeSection ? parseScopeField(scopeSection, "paths") : [],
+        forbidden: scopeSection ? parseScopeField(scopeSection, "forbidden") : [],
+    };
+}
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i += 1;
+                if (glob[i + 1] === "/")
+                    i += 1;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if ("\\^$.|?+()[]{}".includes(char)) {
+            re += `\\${char}`;
+        }
+        else {
+            re += char;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+/**
+ * Whether a (possibly absolute) path matches a relative glob. Tries the full
+ * normalized path and every `/`-boundary suffix, so `src/auth/**` matches both
+ * `src/auth/x.ts` and `/home/me/repo/src/auth/x.ts`.
+ */
+export function pathMatchesGlob(rawPath, glob) {
+    const path = rawPath.replace(/\\/g, "/");
+    const re = globToRegExp(glob);
+    if (re.test(path))
+        return true;
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i += 1) {
+        if (re.test(parts.slice(i).join("/")))
+            return true;
+    }
+    return false;
+}
+/**
+ * Score the most recent `window` observations against the goal. An observation
+ * "matches" when a goal keyword appears in its tool name / input / output, or
+ * its input path falls under a `## Goal Scope` paths glob. An input under a
+ * `forbidden` glob is a hard drift signal regardless of keywords.
+ */
+export function scoreObservations(observations, goal, opts = {}) {
+    // Reject an explicitly-provided out-of-range window instead of silently
+    // coercing it to the default — an operator typo (window=0, -5, 2.5) must not
+    // read as "unset". An absent window legitimately means "use the default".
+    if (opts.window !== undefined && (!Number.isInteger(opts.window) || opts.window <= 0)) {
+        throw new RangeError(`window must be a positive integer; got ${opts.window}. Omit it to use the default of ${DEFAULT_WINDOW}.`);
+    }
+    const window = opts.window ?? DEFAULT_WINDOW;
+    const threshold = typeof opts.threshold === "number" && Number.isFinite(opts.threshold)
+        ? opts.threshold
+        : DEFAULT_THRESHOLD;
+    const recent = observations.slice(-window);
+    const total = recent.length;
+    if (total === 0) {
+        return {
+            status: "no-data",
+            score: 0,
+            threshold,
+            matching: 0,
+            forbidden: 0,
+            total: 0,
+            goalKeywords: goal.keywords,
+            topMismatches: [],
+            reason: "No observations in the window yet.",
+        };
+    }
+    const keywords = goal.keywords.map((kw) => kw.toLowerCase()).filter((kw) => kw.length > 0);
+    let matching = 0;
+    let forbidden = 0;
+    const mismatches = [];
+    for (const obs of recent) {
+        const input = (obs.input_summary ?? "").toString();
+        const output = (obs.output_summary ?? "").toString();
+        const tool = (obs.tool ?? "").toString();
+        const haystack = `${tool}\n${input}\n${output}`.toLowerCase();
+        const record = { ts: (obs.ts ?? "").toString(), tool, summary: input || output };
+        const isForbidden = goal.forbidden.length > 0 &&
+            input.length > 0 &&
+            goal.forbidden.some((glob) => pathMatchesGlob(input, glob));
+        if (isForbidden) {
+            forbidden += 1;
+            mismatches.push(record);
+            continue;
+        }
+        const keywordHit = keywords.some((kw) => haystack.includes(kw));
+        const pathHit = goal.paths.length > 0 &&
+            input.length > 0 &&
+            goal.paths.some((glob) => pathMatchesGlob(input, glob));
+        if (keywordHit || pathHit) {
+            matching += 1;
+        }
+        else {
+            mismatches.push(record);
+        }
+    }
+    const score = matching / total;
+    let status;
+    let reason;
+    if (forbidden > 0) {
+        status = "drift";
+        reason = `${forbidden} of ${total} recent observations touched forbidden paths.`;
+    }
+    else if (score >= threshold) {
+        status = "on-goal";
+        reason = `${matching}/${total} recent observations relate to the goal (threshold ${threshold}).`;
+    }
+    else {
+        status = "drift";
+        reason = `Only ${matching}/${total} recent observations relate to the goal (threshold ${threshold}).`;
+    }
+    return {
+        status,
+        score,
+        threshold,
+        matching,
+        forbidden,
+        total,
+        goalKeywords: goal.keywords,
+        topMismatches: mismatches.slice(-MAX_MISMATCHES).reverse(),
+        reason,
+    };
+}
+/**
+ * Render a DriftReport as a markdown block for the MCP tool output. Pure
+ * string -> string so the formatting is unit-testable.
+ */
+export function formatDriftReport(report) {
+    const label = report.status === "on-goal"
+        ? "ON GOAL"
+        : report.status === "drift"
+            ? "DRIFT"
+            : "NO DATA";
+    const pct = Math.round(report.score * 100);
+    const lines = [
+        `**Status:** ${label}`,
+        `**Score:** ${pct}% (${report.matching}/${report.total} matched, threshold ${Math.round(report.threshold * 100)}%)`,
+        `**Reason:** ${report.reason}`,
+    ];
+    if (report.goalKeywords.length > 0) {
+        lines.push(`**Goal keywords:** ${report.goalKeywords.join(", ")}`);
+    }
+    if (report.topMismatches.length > 0) {
+        lines.push("", `**Top off-goal activity (most recent ${report.topMismatches.length}):**`);
+        for (const mismatch of report.topMismatches) {
+            const stamp = mismatch.ts ? `[${mismatch.ts}] ` : "";
+            const summary = mismatch.summary.length > 100 ? `${mismatch.summary.slice(0, 100)}…` : mismatch.summary;
+            lines.push(`- ${stamp}${mismatch.tool || "(tool?)"} — ${summary || "(no summary)"}`);
+        }
+    }
+    if (report.status === "drift") {
+        lines.push("", "_Drift detected. Either steer back to the goal, or update the `## Goal` section in your plan if the goal has legitimately changed._");
+    }
+    return lines.join("\n");
+}

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 = "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 25 bundled skills, gating hooks, the Mulahazah auto-leveling instinct engine, and a GitHub Action transcript linter.";
 // 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
@@ -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.",
+        hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit"],
+        hookDescription: "Silently captures every tool call as observations and routes prompts to the matching discipline 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.",
+        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,36 @@ 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,
+    };
     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 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] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand] }],
         },
     };
 }

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 (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}]+/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");
+}