@kolisachint/hoocode-agent 0.5.17 → 0.5.19

package/dist/core/learn/cluster.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The naming pass: decide which occurrences are the same point.
+ *
+ * This is the stage the pipeline was missing. Mining is a map over sessions and
+ * counting is a reduce over labels, but nothing sat in between to agree on what
+ * the labels *are*. The miner was asked to produce them from inside a single
+ * session — to hit a shared vocabulary it had never seen — and on a real corpus
+ * it agreed with itself 3 times in 188 candidates. `use-bun-not-npm` and
+ * `prefer-bun-over-npm` are the same rule and never met.
+ *
+ * So naming happens once, with everything visible at the same time. That is a
+ * different question than the miner was being asked: not "what is a good name
+ * for this sentence" but "which of these sentences are the same point", which
+ * is only answerable in the presence of the others.
+ *
+ * Two properties matter more than elegance here:
+ *
+ * - **Stability across runs.** State keys are `directive:<label>`, so a label
+ *   that drifts between runs silently breaks suppression — every proposal you
+ *   already decided on comes back forever. The labels already on record are
+ *   therefore sent as a preferred vocabulary, and reusing one is the first
+ *   instruction the model gets.
+ * - **Degrading in order.** A window too large for one call is processed in
+ *   sequence, with the names assigned so far carried into the next call. That is
+ *   worse than seeing everything at once, but it is worse in a predictable
+ *   direction: later candidates join earlier clusters rather than starting
+ *   rival ones.
+ */
+import { type Model } from "@kolisachint/hoocode-ai";
+import type { MinedCandidate } from "./mine.js";
+/**
+ * Trim the vocabulary to what fits, keeping both ends.
+ *
+ * The list is ordered: labels already on record first, then names invented
+ * earlier in this run. Those are two different anchors — the first keeps the
+ * bookmark matching across runs, the second keeps a split window from starting
+ * rival names for one point — and taking a plain prefix silently drops the
+ * second exactly when batching makes it necessary.
+ */
+export declare function trimVocabulary(labels: string[], max?: number): string[];
+/** One candidate to be named, with the identity the caller needs to put the label back. */
+export interface ClusterInput {
+    /** Caller's handle for this candidate; returned untouched. */
+    id: number;
+    kind: MinedCandidate["kind"];
+    text: string;
+}
+/**
+ * Assign a label to each input. Missing entries are left for the caller to
+ * handle; a clusterer may legitimately decline to name something.
+ */
+export type Clusterer = (inputs: ClusterInput[], knownLabels: string[], signal?: AbortSignal) => Promise<Map<number, string>>;
+/** Render the numbered list the prompt describes. */
+export declare function renderClusterRequest(inputs: ClusterInput[], knownLabels: string[]): string;
+/**
+ * Read the label assignments out of a model response.
+ *
+ * Same forgiving parse as the miner: models fence JSON they were told not to
+ * fence, and one unparseable response should cost the run its grouping, not its
+ * life. An id the caller never asked about is dropped rather than trusted.
+ */
+export declare function parseClusterLabels(response: string, known: Set<number>): Map<number, string>;
+export interface ClustererDeps {
+    model: Model<any>;
+    apiKey?: string;
+    headers?: Record<string, string>;
+}
+export declare function createLlmClusterer(deps: ClustererDeps): Clusterer;
+/**
+ * Fallback naming for a candidate the clusterer did not label.
+ *
+ * A run whose clustering call failed should still propose something, so an
+ * unlabelled candidate falls back to a slug of its own text. That groups
+ * identical wording and nothing else — the behaviour the pipeline had before
+ * clustering existed, which is the right floor to fail to.
+ */
+export declare function fallbackLabel(text: string): string;
+//# sourceMappingURL=cluster.d.ts.map

package/dist/core/learn/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../../src/core/learn/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAkB,KAAK,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAehD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,SAAmB,GAAG,MAAM,EAAE,CAIjF;AAOD,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CACvB,MAAM,EAAE,YAAY,EAAE,EACtB,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,CAAC,EAAE,WAAW,KAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAqBlC,qDAAqD;AACrD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAgB1F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiC5F;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CA2CjE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD","sourcesContent":["/**\n * The naming pass: decide which occurrences are the same point.\n *\n * This is the stage the pipeline was missing. Mining is a map over sessions and\n * counting is a reduce over labels, but nothing sat in between to agree on what\n * the labels *are*. The miner was asked to produce them from inside a single\n * session — to hit a shared vocabulary it had never seen — and on a real corpus\n * it agreed with itself 3 times in 188 candidates. `use-bun-not-npm` and\n * `prefer-bun-over-npm` are the same rule and never met.\n *\n * So naming happens once, with everything visible at the same time. That is a\n * different question than the miner was being asked: not \"what is a good name\n * for this sentence\" but \"which of these sentences are the same point\", which\n * is only answerable in the presence of the others.\n *\n * Two properties matter more than elegance here:\n *\n * - **Stability across runs.** State keys are `directive:<label>`, so a label\n *   that drifts between runs silently breaks suppression — every proposal you\n *   already decided on comes back forever. The labels already on record are\n *   therefore sent as a preferred vocabulary, and reusing one is the first\n *   instruction the model gets.\n * - **Degrading in order.** A window too large for one call is processed in\n *   sequence, with the names assigned so far carried into the next call. That is\n *   worse than seeing everything at once, but it is worse in a predictable\n *   direction: later candidates join earlier clusters rather than starting\n *   rival ones.\n */\n\nimport { completeSimple, type Model } from \"@kolisachint/hoocode-ai\";\nimport type { MinedCandidate } from \"./mine.js\";\n\n/**\n * Candidates named per call.\n *\n * Sized so a typical window is one call: 200 quotes at ~120 characters is well\n * inside a small model's window with room for the reply. Past that, clustering\n * quality would degrade anyway — a list nobody can hold in mind is one nobody\n * names consistently.\n */\nconst MAX_CANDIDATES_PER_CALL = 200;\n\n/** Known labels offered as vocabulary. Enough to cover a real state file, short of flooding the prompt. */\nconst MAX_KNOWN_LABELS = 150;\n\n/**\n * Trim the vocabulary to what fits, keeping both ends.\n *\n * The list is ordered: labels already on record first, then names invented\n * earlier in this run. Those are two different anchors — the first keeps the\n * bookmark matching across runs, the second keeps a split window from starting\n * rival names for one point — and taking a plain prefix silently drops the\n * second exactly when batching makes it necessary.\n */\nexport function trimVocabulary(labels: string[], max = MAX_KNOWN_LABELS): string[] {\n\tif (labels.length <= max) return labels;\n\tconst head = Math.ceil(max / 2);\n\treturn [...labels.slice(0, head), ...labels.slice(-(max - head))];\n}\n\n/** Quote characters sent per candidate. A directive is identifiable long before this. */\nconst QUOTE_CHARS = 240;\n\nconst MAX_RESPONSE_TOKENS = 4_000;\n\n/** One candidate to be named, with the identity the caller needs to put the label back. */\nexport interface ClusterInput {\n\t/** Caller's handle for this candidate; returned untouched. */\n\tid: number;\n\tkind: MinedCandidate[\"kind\"];\n\ttext: string;\n}\n\n/**\n * Assign a label to each input. Missing entries are left for the caller to\n * handle; a clusterer may legitimately decline to name something.\n */\nexport type Clusterer = (\n\tinputs: ClusterInput[],\n\tknownLabels: string[],\n\tsignal?: AbortSignal,\n) => Promise<Map<number, string>>;\n\nconst CLUSTER_SYSTEM_PROMPT = `You group occurrences from coding sessions by what they MEAN, and give each group a name.\n\nYou are given numbered ITEMS. Each is something a user said, or something that happened, across many sessions. Different sessions phrase the same point differently — your job is to recognise that and name the point once.\n\nRules, in order of importance:\n\n1. If a label in KNOWN LABELS already names the point, reuse it EXACTLY. These are names already on record; reusing one is how a proposal the reader already decided on stays decided. Do not invent a synonym for a label that exists.\n2. Items meaning the same thing MUST get the same label, even when the wording shares no words.\n   - \"we're on bun now\" / \"stop using npm install\" / \"pnpm isn't what we use here\" → use-bun-not-npm\n   - \"never force push\" / \"don't rewrite shared history\" → never-force-push\n3. Items meaning different things MUST NOT share a label, even when the wording is similar. \"doc tools off by default\" and \"network tools off by default\" are the same shape and different rules.\n4. A label is a short kebab-case slug naming the point, 2-5 words. Name the point, not the session it came from.\n5. Never group across kinds. A directive (\"how work should be done\") and a request (\"do this piece of work\") are never the same item, even when they are about the same subject.\n\nOutput STRICT JSON, no markdown fence, no prose. One entry per item, using the item's number:\n{\"labels\":[{\"id\":1,\"label\":\"use-bun-not-npm\"},{\"id\":2,\"label\":\"use-bun-not-npm\"}]}\n\nEvery item gets exactly one label. An item that means something no other item means still gets its own label — a group of one is a normal answer.`;\n\n/** Render the numbered list the prompt describes. */\nexport function renderClusterRequest(inputs: ClusterInput[], knownLabels: string[]): string {\n\tconst lines: string[] = [];\n\n\tif (knownLabels.length > 0) {\n\t\tlines.push(\"KNOWN LABELS (reuse exactly when one fits):\");\n\t\tfor (const label of trimVocabulary(knownLabels)) lines.push(`- ${label}`);\n\t\tlines.push(\"\");\n\t}\n\n\tlines.push(\"ITEMS:\");\n\tfor (const input of inputs) {\n\t\tconst quote = input.text.length > QUOTE_CHARS ? `${input.text.slice(0, QUOTE_CHARS)}…` : input.text;\n\t\tlines.push(`${input.id}. [${input.kind}] ${quote.replace(/\\s+/g, \" \")}`);\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Read the label assignments out of a model response.\n *\n * Same forgiving parse as the miner: models fence JSON they were told not to\n * fence, and one unparseable response should cost the run its grouping, not its\n * life. An id the caller never asked about is dropped rather than trusted.\n */\nexport function parseClusterLabels(response: string, known: Set<number>): Map<number, string> {\n\tconst out = new Map<number, string>();\n\tconst start = response.indexOf(\"{\");\n\tconst end = response.lastIndexOf(\"}\");\n\tif (start < 0 || end <= start) return out;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(response.slice(start, end + 1));\n\t} catch {\n\t\treturn out;\n\t}\n\n\tconst raw = (parsed as { labels?: unknown })?.labels;\n\tif (!Array.isArray(raw)) return out;\n\n\tfor (const item of raw) {\n\t\tif (!item || typeof item !== \"object\") continue;\n\t\tconst entry = item as Record<string, unknown>;\n\t\tconst id = typeof entry.id === \"number\" ? entry.id : Number.NaN;\n\t\tconst label = typeof entry.label === \"string\" ? entry.label.trim().toLowerCase() : \"\";\n\t\tif (!Number.isInteger(id) || !known.has(id) || !label) continue;\n\t\t// Normalized to the slug shape the state file keys on, so a model that\n\t\t// answers \"Use Bun Not Npm\" does not fork the vocabulary on punctuation.\n\t\tout.set(\n\t\t\tid,\n\t\t\tlabel\n\t\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t\t.replace(/^-|-$/g, \"\")\n\t\t\t\t.slice(0, 60),\n\t\t);\n\t}\n\treturn out;\n}\n\nexport interface ClustererDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n}\n\nexport function createLlmClusterer(deps: ClustererDeps): Clusterer {\n\treturn async (inputs, knownLabels, signal) => {\n\t\tconst assigned = new Map<number, string>();\n\t\t// Labels invented in an earlier batch join the vocabulary for the next, so\n\t\t// a split window still converges on one name per point.\n\t\tconst vocabulary = [...knownLabels];\n\n\t\tfor (let offset = 0; offset < inputs.length; offset += MAX_CANDIDATES_PER_CALL) {\n\t\t\tif (signal?.aborted) break;\n\t\t\tconst batch = inputs.slice(offset, offset + MAX_CANDIDATES_PER_CALL);\n\n\t\t\tconst response = await completeSimple(\n\t\t\t\tdeps.model,\n\t\t\t\t{\n\t\t\t\t\tsystemPrompt: CLUSTER_SYSTEM_PROMPT,\n\t\t\t\t\tmessages: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: renderClusterRequest(batch, vocabulary) }],\n\t\t\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\t{ maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers },\n\t\t\t);\n\n\t\t\tif (response.stopReason === \"error\") {\n\t\t\t\tthrow new Error(response.errorMessage || \"clustering call failed\");\n\t\t\t}\n\n\t\t\tconst text = response.content\n\t\t\t\t.filter((block): block is { type: \"text\"; text: string } => block.type === \"text\")\n\t\t\t\t.map((block) => block.text)\n\t\t\t\t.join(\"\");\n\n\t\t\tfor (const [id, label] of parseClusterLabels(text, new Set(batch.map((item) => item.id)))) {\n\t\t\t\tassigned.set(id, label);\n\t\t\t\tif (!vocabulary.includes(label)) vocabulary.push(label);\n\t\t\t}\n\t\t}\n\n\t\treturn assigned;\n\t};\n}\n\n/**\n * Fallback naming for a candidate the clusterer did not label.\n *\n * A run whose clustering call failed should still propose something, so an\n * unlabelled candidate falls back to a slug of its own text. That groups\n * identical wording and nothing else — the behaviour the pipeline had before\n * clustering existed, which is the right floor to fail to.\n */\nexport function fallbackLabel(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t.replace(/^-|-$/g, \"\")\n\t\t\t.slice(0, 60) || \"unlabelled\"\n\t);\n}\n"]}

package/dist/core/learn/cluster.js

@@ -0,0 +1,184 @@
+/**
+ * The naming pass: decide which occurrences are the same point.
+ *
+ * This is the stage the pipeline was missing. Mining is a map over sessions and
+ * counting is a reduce over labels, but nothing sat in between to agree on what
+ * the labels *are*. The miner was asked to produce them from inside a single
+ * session — to hit a shared vocabulary it had never seen — and on a real corpus
+ * it agreed with itself 3 times in 188 candidates. `use-bun-not-npm` and
+ * `prefer-bun-over-npm` are the same rule and never met.
+ *
+ * So naming happens once, with everything visible at the same time. That is a
+ * different question than the miner was being asked: not "what is a good name
+ * for this sentence" but "which of these sentences are the same point", which
+ * is only answerable in the presence of the others.
+ *
+ * Two properties matter more than elegance here:
+ *
+ * - **Stability across runs.** State keys are `directive:<label>`, so a label
+ *   that drifts between runs silently breaks suppression — every proposal you
+ *   already decided on comes back forever. The labels already on record are
+ *   therefore sent as a preferred vocabulary, and reusing one is the first
+ *   instruction the model gets.
+ * - **Degrading in order.** A window too large for one call is processed in
+ *   sequence, with the names assigned so far carried into the next call. That is
+ *   worse than seeing everything at once, but it is worse in a predictable
+ *   direction: later candidates join earlier clusters rather than starting
+ *   rival ones.
+ */
+import { completeSimple } from "@kolisachint/hoocode-ai";
+/**
+ * Candidates named per call.
+ *
+ * Sized so a typical window is one call: 200 quotes at ~120 characters is well
+ * inside a small model's window with room for the reply. Past that, clustering
+ * quality would degrade anyway — a list nobody can hold in mind is one nobody
+ * names consistently.
+ */
+const MAX_CANDIDATES_PER_CALL = 200;
+/** Known labels offered as vocabulary. Enough to cover a real state file, short of flooding the prompt. */
+const MAX_KNOWN_LABELS = 150;
+/**
+ * Trim the vocabulary to what fits, keeping both ends.
+ *
+ * The list is ordered: labels already on record first, then names invented
+ * earlier in this run. Those are two different anchors — the first keeps the
+ * bookmark matching across runs, the second keeps a split window from starting
+ * rival names for one point — and taking a plain prefix silently drops the
+ * second exactly when batching makes it necessary.
+ */
+export function trimVocabulary(labels, max = MAX_KNOWN_LABELS) {
+    if (labels.length <= max)
+        return labels;
+    const head = Math.ceil(max / 2);
+    return [...labels.slice(0, head), ...labels.slice(-(max - head))];
+}
+/** Quote characters sent per candidate. A directive is identifiable long before this. */
+const QUOTE_CHARS = 240;
+const MAX_RESPONSE_TOKENS = 4_000;
+const CLUSTER_SYSTEM_PROMPT = `You group occurrences from coding sessions by what they MEAN, and give each group a name.
+
+You are given numbered ITEMS. Each is something a user said, or something that happened, across many sessions. Different sessions phrase the same point differently — your job is to recognise that and name the point once.
+
+Rules, in order of importance:
+
+1. If a label in KNOWN LABELS already names the point, reuse it EXACTLY. These are names already on record; reusing one is how a proposal the reader already decided on stays decided. Do not invent a synonym for a label that exists.
+2. Items meaning the same thing MUST get the same label, even when the wording shares no words.
+   - "we're on bun now" / "stop using npm install" / "pnpm isn't what we use here" → use-bun-not-npm
+   - "never force push" / "don't rewrite shared history" → never-force-push
+3. Items meaning different things MUST NOT share a label, even when the wording is similar. "doc tools off by default" and "network tools off by default" are the same shape and different rules.
+4. A label is a short kebab-case slug naming the point, 2-5 words. Name the point, not the session it came from.
+5. Never group across kinds. A directive ("how work should be done") and a request ("do this piece of work") are never the same item, even when they are about the same subject.
+
+Output STRICT JSON, no markdown fence, no prose. One entry per item, using the item's number:
+{"labels":[{"id":1,"label":"use-bun-not-npm"},{"id":2,"label":"use-bun-not-npm"}]}
+
+Every item gets exactly one label. An item that means something no other item means still gets its own label — a group of one is a normal answer.`;
+/** Render the numbered list the prompt describes. */
+export function renderClusterRequest(inputs, knownLabels) {
+    const lines = [];
+    if (knownLabels.length > 0) {
+        lines.push("KNOWN LABELS (reuse exactly when one fits):");
+        for (const label of trimVocabulary(knownLabels))
+            lines.push(`- ${label}`);
+        lines.push("");
+    }
+    lines.push("ITEMS:");
+    for (const input of inputs) {
+        const quote = input.text.length > QUOTE_CHARS ? `${input.text.slice(0, QUOTE_CHARS)}…` : input.text;
+        lines.push(`${input.id}. [${input.kind}] ${quote.replace(/\s+/g, " ")}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Read the label assignments out of a model response.
+ *
+ * Same forgiving parse as the miner: models fence JSON they were told not to
+ * fence, and one unparseable response should cost the run its grouping, not its
+ * life. An id the caller never asked about is dropped rather than trusted.
+ */
+export function parseClusterLabels(response, known) {
+    const out = new Map();
+    const start = response.indexOf("{");
+    const end = response.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return out;
+    let parsed;
+    try {
+        parsed = JSON.parse(response.slice(start, end + 1));
+    }
+    catch {
+        return out;
+    }
+    const raw = parsed?.labels;
+    if (!Array.isArray(raw))
+        return out;
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const entry = item;
+        const id = typeof entry.id === "number" ? entry.id : Number.NaN;
+        const label = typeof entry.label === "string" ? entry.label.trim().toLowerCase() : "";
+        if (!Number.isInteger(id) || !known.has(id) || !label)
+            continue;
+        // Normalized to the slug shape the state file keys on, so a model that
+        // answers "Use Bun Not Npm" does not fork the vocabulary on punctuation.
+        out.set(id, label
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, "")
+            .slice(0, 60));
+    }
+    return out;
+}
+export function createLlmClusterer(deps) {
+    return async (inputs, knownLabels, signal) => {
+        const assigned = new Map();
+        // Labels invented in an earlier batch join the vocabulary for the next, so
+        // a split window still converges on one name per point.
+        const vocabulary = [...knownLabels];
+        for (let offset = 0; offset < inputs.length; offset += MAX_CANDIDATES_PER_CALL) {
+            if (signal?.aborted)
+                break;
+            const batch = inputs.slice(offset, offset + MAX_CANDIDATES_PER_CALL);
+            const response = await completeSimple(deps.model, {
+                systemPrompt: CLUSTER_SYSTEM_PROMPT,
+                messages: [
+                    {
+                        role: "user",
+                        content: [{ type: "text", text: renderClusterRequest(batch, vocabulary) }],
+                        timestamp: Date.now(),
+                    },
+                ],
+            }, { maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers });
+            if (response.stopReason === "error") {
+                throw new Error(response.errorMessage || "clustering call failed");
+            }
+            const text = response.content
+                .filter((block) => block.type === "text")
+                .map((block) => block.text)
+                .join("");
+            for (const [id, label] of parseClusterLabels(text, new Set(batch.map((item) => item.id)))) {
+                assigned.set(id, label);
+                if (!vocabulary.includes(label))
+                    vocabulary.push(label);
+            }
+        }
+        return assigned;
+    };
+}
+/**
+ * Fallback naming for a candidate the clusterer did not label.
+ *
+ * A run whose clustering call failed should still propose something, so an
+ * unlabelled candidate falls back to a slug of its own text. That groups
+ * identical wording and nothing else — the behaviour the pipeline had before
+ * clustering existed, which is the right floor to fail to.
+ */
+export function fallbackLabel(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60) || "unlabelled");
+}
+//# sourceMappingURL=cluster.js.map

package/dist/core/learn/cluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../../../src/core/learn/cluster.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The naming pass: decide which occurrences are the same point.\n *\n * This is the stage the pipeline was missing. Mining is a map over sessions and\n * counting is a reduce over labels, but nothing sat in between to agree on what\n * the labels *are*. The miner was asked to produce them from inside a single\n * session — to hit a shared vocabulary it had never seen — and on a real corpus\n * it agreed with itself 3 times in 188 candidates. `use-bun-not-npm` and\n * `prefer-bun-over-npm` are the same rule and never met.\n *\n * So naming happens once, with everything visible at the same time. That is a\n * different question than the miner was being asked: not \"what is a good name\n * for this sentence\" but \"which of these sentences are the same point\", which\n * is only answerable in the presence of the others.\n *\n * Two properties matter more than elegance here:\n *\n * - **Stability across runs.** State keys are `directive:<label>`, so a label\n *   that drifts between runs silently breaks suppression — every proposal you\n *   already decided on comes back forever. The labels already on record are\n *   therefore sent as a preferred vocabulary, and reusing one is the first\n *   instruction the model gets.\n * - **Degrading in order.** A window too large for one call is processed in\n *   sequence, with the names assigned so far carried into the next call. That is\n *   worse than seeing everything at once, but it is worse in a predictable\n *   direction: later candidates join earlier clusters rather than starting\n *   rival ones.\n */\n\nimport { completeSimple, type Model } from \"@kolisachint/hoocode-ai\";\nimport type { MinedCandidate } from \"./mine.js\";\n\n/**\n * Candidates named per call.\n *\n * Sized so a typical window is one call: 200 quotes at ~120 characters is well\n * inside a small model's window with room for the reply. Past that, clustering\n * quality would degrade anyway — a list nobody can hold in mind is one nobody\n * names consistently.\n */\nconst MAX_CANDIDATES_PER_CALL = 200;\n\n/** Known labels offered as vocabulary. Enough to cover a real state file, short of flooding the prompt. */\nconst MAX_KNOWN_LABELS = 150;\n\n/**\n * Trim the vocabulary to what fits, keeping both ends.\n *\n * The list is ordered: labels already on record first, then names invented\n * earlier in this run. Those are two different anchors — the first keeps the\n * bookmark matching across runs, the second keeps a split window from starting\n * rival names for one point — and taking a plain prefix silently drops the\n * second exactly when batching makes it necessary.\n */\nexport function trimVocabulary(labels: string[], max = MAX_KNOWN_LABELS): string[] {\n\tif (labels.length <= max) return labels;\n\tconst head = Math.ceil(max / 2);\n\treturn [...labels.slice(0, head), ...labels.slice(-(max - head))];\n}\n\n/** Quote characters sent per candidate. A directive is identifiable long before this. */\nconst QUOTE_CHARS = 240;\n\nconst MAX_RESPONSE_TOKENS = 4_000;\n\n/** One candidate to be named, with the identity the caller needs to put the label back. */\nexport interface ClusterInput {\n\t/** Caller's handle for this candidate; returned untouched. */\n\tid: number;\n\tkind: MinedCandidate[\"kind\"];\n\ttext: string;\n}\n\n/**\n * Assign a label to each input. Missing entries are left for the caller to\n * handle; a clusterer may legitimately decline to name something.\n */\nexport type Clusterer = (\n\tinputs: ClusterInput[],\n\tknownLabels: string[],\n\tsignal?: AbortSignal,\n) => Promise<Map<number, string>>;\n\nconst CLUSTER_SYSTEM_PROMPT = `You group occurrences from coding sessions by what they MEAN, and give each group a name.\n\nYou are given numbered ITEMS. Each is something a user said, or something that happened, across many sessions. Different sessions phrase the same point differently — your job is to recognise that and name the point once.\n\nRules, in order of importance:\n\n1. If a label in KNOWN LABELS already names the point, reuse it EXACTLY. These are names already on record; reusing one is how a proposal the reader already decided on stays decided. Do not invent a synonym for a label that exists.\n2. Items meaning the same thing MUST get the same label, even when the wording shares no words.\n   - \"we're on bun now\" / \"stop using npm install\" / \"pnpm isn't what we use here\" → use-bun-not-npm\n   - \"never force push\" / \"don't rewrite shared history\" → never-force-push\n3. Items meaning different things MUST NOT share a label, even when the wording is similar. \"doc tools off by default\" and \"network tools off by default\" are the same shape and different rules.\n4. A label is a short kebab-case slug naming the point, 2-5 words. Name the point, not the session it came from.\n5. Never group across kinds. A directive (\"how work should be done\") and a request (\"do this piece of work\") are never the same item, even when they are about the same subject.\n\nOutput STRICT JSON, no markdown fence, no prose. One entry per item, using the item's number:\n{\"labels\":[{\"id\":1,\"label\":\"use-bun-not-npm\"},{\"id\":2,\"label\":\"use-bun-not-npm\"}]}\n\nEvery item gets exactly one label. An item that means something no other item means still gets its own label — a group of one is a normal answer.`;\n\n/** Render the numbered list the prompt describes. */\nexport function renderClusterRequest(inputs: ClusterInput[], knownLabels: string[]): string {\n\tconst lines: string[] = [];\n\n\tif (knownLabels.length > 0) {\n\t\tlines.push(\"KNOWN LABELS (reuse exactly when one fits):\");\n\t\tfor (const label of trimVocabulary(knownLabels)) lines.push(`- ${label}`);\n\t\tlines.push(\"\");\n\t}\n\n\tlines.push(\"ITEMS:\");\n\tfor (const input of inputs) {\n\t\tconst quote = input.text.length > QUOTE_CHARS ? `${input.text.slice(0, QUOTE_CHARS)}…` : input.text;\n\t\tlines.push(`${input.id}. [${input.kind}] ${quote.replace(/\\s+/g, \" \")}`);\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Read the label assignments out of a model response.\n *\n * Same forgiving parse as the miner: models fence JSON they were told not to\n * fence, and one unparseable response should cost the run its grouping, not its\n * life. An id the caller never asked about is dropped rather than trusted.\n */\nexport function parseClusterLabels(response: string, known: Set<number>): Map<number, string> {\n\tconst out = new Map<number, string>();\n\tconst start = response.indexOf(\"{\");\n\tconst end = response.lastIndexOf(\"}\");\n\tif (start < 0 || end <= start) return out;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(response.slice(start, end + 1));\n\t} catch {\n\t\treturn out;\n\t}\n\n\tconst raw = (parsed as { labels?: unknown })?.labels;\n\tif (!Array.isArray(raw)) return out;\n\n\tfor (const item of raw) {\n\t\tif (!item || typeof item !== \"object\") continue;\n\t\tconst entry = item as Record<string, unknown>;\n\t\tconst id = typeof entry.id === \"number\" ? entry.id : Number.NaN;\n\t\tconst label = typeof entry.label === \"string\" ? entry.label.trim().toLowerCase() : \"\";\n\t\tif (!Number.isInteger(id) || !known.has(id) || !label) continue;\n\t\t// Normalized to the slug shape the state file keys on, so a model that\n\t\t// answers \"Use Bun Not Npm\" does not fork the vocabulary on punctuation.\n\t\tout.set(\n\t\t\tid,\n\t\t\tlabel\n\t\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t\t.replace(/^-|-$/g, \"\")\n\t\t\t\t.slice(0, 60),\n\t\t);\n\t}\n\treturn out;\n}\n\nexport interface ClustererDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n}\n\nexport function createLlmClusterer(deps: ClustererDeps): Clusterer {\n\treturn async (inputs, knownLabels, signal) => {\n\t\tconst assigned = new Map<number, string>();\n\t\t// Labels invented in an earlier batch join the vocabulary for the next, so\n\t\t// a split window still converges on one name per point.\n\t\tconst vocabulary = [...knownLabels];\n\n\t\tfor (let offset = 0; offset < inputs.length; offset += MAX_CANDIDATES_PER_CALL) {\n\t\t\tif (signal?.aborted) break;\n\t\t\tconst batch = inputs.slice(offset, offset + MAX_CANDIDATES_PER_CALL);\n\n\t\t\tconst response = await completeSimple(\n\t\t\t\tdeps.model,\n\t\t\t\t{\n\t\t\t\t\tsystemPrompt: CLUSTER_SYSTEM_PROMPT,\n\t\t\t\t\tmessages: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: renderClusterRequest(batch, vocabulary) }],\n\t\t\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\t{ maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers },\n\t\t\t);\n\n\t\t\tif (response.stopReason === \"error\") {\n\t\t\t\tthrow new Error(response.errorMessage || \"clustering call failed\");\n\t\t\t}\n\n\t\t\tconst text = response.content\n\t\t\t\t.filter((block): block is { type: \"text\"; text: string } => block.type === \"text\")\n\t\t\t\t.map((block) => block.text)\n\t\t\t\t.join(\"\");\n\n\t\t\tfor (const [id, label] of parseClusterLabels(text, new Set(batch.map((item) => item.id)))) {\n\t\t\t\tassigned.set(id, label);\n\t\t\t\tif (!vocabulary.includes(label)) vocabulary.push(label);\n\t\t\t}\n\t\t}\n\n\t\treturn assigned;\n\t};\n}\n\n/**\n * Fallback naming for a candidate the clusterer did not label.\n *\n * A run whose clustering call failed should still propose something, so an\n * unlabelled candidate falls back to a slug of its own text. That groups\n * identical wording and nothing else — the behaviour the pipeline had before\n * clustering existed, which is the right floor to fail to.\n */\nexport function fallbackLabel(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-z0-9]+/g, \"-\")\n\t\t\t.replace(/^-|-$/g, \"\")\n\t\t\t.slice(0, 60) || \"unlabelled\"\n\t);\n}\n"]}

package/dist/core/learn/coverage.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Is this already written down?
+ *
+ * The answer decides the most useful distinction the digest makes — `new` vs
+ * `restated` vs `has-skill` — and it used to be decided by bag-of-words
+ * overlap: count how many content words of the proposal appear anywhere in a
+ * rule line, call it covered above 0.6. That is wrong in both directions and
+ * for the same reason, namely that it does not read. It calls "always run tests
+ * before pushing" covered by a line about "running the test suite in CI", and
+ * it misses a real paraphrase that happens to pick different vocabulary.
+ *
+ * Both mistakes are expensive. A false `restated` accuses a rule that is
+ * working of not working, and tells the reader to rewrite something fine. A
+ * false `new` proposes a rule they already have, which is how a context file
+ * grows duplicates.
+ *
+ * So a model reads the rules and the proposals together and matches them. One
+ * call for the whole batch, because the question is small and the corpus is the
+ * same for every item — the context file is a few thousand tokens and does not
+ * want re-sending once per proposal.
+ */
+import type { Model } from "@kolisachint/hoocode-ai";
+export interface CoverageIndex {
+    /** Candidate rule lines from the repo context file and both user scopes. */
+    ruleLines: string[];
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface CoverageMatch {
+    /** The context-file line that covers this, if any. */
+    rule?: string;
+    /** The skill that covers this, if any. Only set when no rule matched. */
+    skill?: string;
+}
+/** One thing to look up, identified by the label the reduce step grouped on. */
+export interface CoverageQuery {
+    label: string;
+    text: string;
+}
+/**
+ * Decide coverage for a batch. Injectable so the pipeline can be tested without
+ * a model, and so a run with no model configured can degrade to "everything is
+ * new" rather than failing.
+ */
+export type CoverageJudge = (queries: CoverageQuery[], index: CoverageIndex, signal?: AbortSignal) => Promise<Map<string, CoverageMatch>>;
+/** Read the verdict list back, ignoring anything malformed rather than failing the run. */
+export declare function parseVerdicts(response: string, queries: CoverageQuery[], index: CoverageIndex): Map<string, CoverageMatch>;
+export interface CoverageDeps {
+    model: Model<any>;
+    apiKey?: string;
+    headers?: Record<string, string>;
+}
+export declare function createLlmCoverageJudge(deps: CoverageDeps): CoverageJudge;
+/** Everything is new. Used when no model is available, so the run still produces a digest. */
+export declare const noCoverageJudge: CoverageJudge;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/core/learn/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../../src/core/learn/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAGrD,MAAM,WAAW,aAAa;IAC7B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,aAAa;IAC7B,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC3B,OAAO,EAAE,aAAa,EAAE,EACxB,KAAK,EAAE,aAAa,EACpB,MAAM,CAAC,EAAE,WAAW,KAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AA0DzC,2FAA2F;AAC3F,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EAAE,EACxB,KAAK,EAAE,aAAa,GAClB,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAwC5B;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,aAAa,CA6BxE;AAED,8FAA8F;AAC9F,eAAO,MAAM,eAAe,EAAE,aAAqC,CAAC","sourcesContent":["/**\n * Is this already written down?\n *\n * The answer decides the most useful distinction the digest makes — `new` vs\n * `restated` vs `has-skill` — and it used to be decided by bag-of-words\n * overlap: count how many content words of the proposal appear anywhere in a\n * rule line, call it covered above 0.6. That is wrong in both directions and\n * for the same reason, namely that it does not read. It calls \"always run tests\n * before pushing\" covered by a line about \"running the test suite in CI\", and\n * it misses a real paraphrase that happens to pick different vocabulary.\n *\n * Both mistakes are expensive. A false `restated` accuses a rule that is\n * working of not working, and tells the reader to rewrite something fine. A\n * false `new` proposes a rule they already have, which is how a context file\n * grows duplicates.\n *\n * So a model reads the rules and the proposals together and matches them. One\n * call for the whole batch, because the question is small and the corpus is the\n * same for every item — the context file is a few thousand tokens and does not\n * want re-sending once per proposal.\n */\n\nimport type { Model } from \"@kolisachint/hoocode-ai\";\nimport { completeSimple } from \"@kolisachint/hoocode-ai\";\n\nexport interface CoverageIndex {\n\t/** Candidate rule lines from the repo context file and both user scopes. */\n\truleLines: string[];\n\tskills: Array<{ name: string; description: string }>;\n}\n\nexport interface CoverageMatch {\n\t/** The context-file line that covers this, if any. */\n\trule?: string;\n\t/** The skill that covers this, if any. Only set when no rule matched. */\n\tskill?: string;\n}\n\n/** One thing to look up, identified by the label the reduce step grouped on. */\nexport interface CoverageQuery {\n\tlabel: string;\n\ttext: string;\n}\n\n/**\n * Decide coverage for a batch. Injectable so the pipeline can be tested without\n * a model, and so a run with no model configured can degrade to \"everything is\n * new\" rather than failing.\n */\nexport type CoverageJudge = (\n\tqueries: CoverageQuery[],\n\tindex: CoverageIndex,\n\tsignal?: AbortSignal,\n) => Promise<Map<string, CoverageMatch>>;\n\n/** Rule lines sent per call. A context file longer than this is already the problem. */\nconst MAX_RULE_LINES = 400;\n/** Skills sent per call. */\nconst MAX_SKILLS = 120;\n/** Description characters per skill — the opening says what it does; the rest is trigger bait. */\nconst SKILL_DESCRIPTION_CHARS = 300;\nconst MAX_RESPONSE_TOKENS = 2_000;\n\nconst COVERAGE_SYSTEM_PROMPT = `You decide whether each proposed rule is ALREADY covered by existing project rules or skills.\n\nYou are given numbered RULES (lines from context files), numbered SKILLS (name and description), and numbered PROPOSALS.\n\nEach rule reads \\`[scope] Heading > Subheading > line\\`. The scope is \\`repo\\` (binds work in this project) or \\`user\\` (binds everywhere). The heading path is the section the line lives under, and it is what tells you the line's subject when the line alone is ambiguous.\n\nFor each proposal, decide:\n- \"rule\" — an existing rule already says this. The reader repeating it means that rule is not working, so it should be rewritten rather than duplicated.\n- \"skill\" — an existing skill already does this, and the reader asked by hand anyway. Usually the skill's description does not describe the situation they were in.\n- \"new\" — nothing covers it.\n\nJudge by MEANING, not by shared words. Different vocabulary for the same instruction is covered. Shared vocabulary about different things is NOT covered:\n- proposal \"always use bun, never npm\" vs rule \"install dependencies with bun\" → covered (rule)\n- proposal \"run tests before pushing\" vs rule \"CI runs the test suite on every PR\" → NOT covered, these are different instructions to different actors\n- proposal \"prefer table output\" vs rule \"use tables in documentation\" → NOT covered unless the scope matches\n\nPrefer \"new\" when genuinely unsure. A false \"covered\" tells the reader to rewrite a rule that is fine; a false \"new\" merely proposes something they can reject.\n\nRules win over skills when both match: rewriting a line is more actionable than sharpening a description.\n\nOutput STRICT JSON, no markdown fence, no prose. Use the proposal's exact label:\n{\"verdicts\":[{\"label\":\"use-bun-not-npm\",\"verdict\":\"rule\",\"ruleIndex\":3},{\"label\":\"scaffold-route\",\"verdict\":\"skill\",\"skillIndex\":1},{\"label\":\"prefer-tables\",\"verdict\":\"new\"}]}`;\n\nfunction buildPrompt(queries: CoverageQuery[], index: CoverageIndex): string {\n\tconst lines: string[] = [];\n\n\tlines.push(\"RULES:\");\n\tconst rules = index.ruleLines.slice(0, MAX_RULE_LINES);\n\tif (rules.length === 0) lines.push(\"(none)\");\n\tfor (const [i, rule] of rules.entries()) {\n\t\tlines.push(`${i}. ${rule}`);\n\t}\n\n\tlines.push(\"\", \"SKILLS:\");\n\tconst skills = index.skills.slice(0, MAX_SKILLS);\n\tif (skills.length === 0) lines.push(\"(none)\");\n\tfor (const [i, skill] of skills.entries()) {\n\t\tlines.push(`${i}. ${skill.name} — ${skill.description.slice(0, SKILL_DESCRIPTION_CHARS)}`);\n\t}\n\n\tlines.push(\"\", \"PROPOSALS:\");\n\tfor (const query of queries) {\n\t\tlines.push(`- label: ${query.label}\\n  text: ${query.text}`);\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/** Read the verdict list back, ignoring anything malformed rather than failing the run. */\nexport function parseVerdicts(\n\tresponse: string,\n\tqueries: CoverageQuery[],\n\tindex: CoverageIndex,\n): Map<string, CoverageMatch> {\n\tconst out = new Map<string, CoverageMatch>();\n\tconst start = response.indexOf(\"{\");\n\tconst end = response.lastIndexOf(\"}\");\n\tif (start < 0 || end <= start) return out;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(response.slice(start, end + 1));\n\t} catch {\n\t\treturn out;\n\t}\n\n\tconst raw = (parsed as { verdicts?: unknown })?.verdicts;\n\tif (!Array.isArray(raw)) return out;\n\n\tconst known = new Set(queries.map((q) => q.label));\n\tfor (const item of raw) {\n\t\tif (!item || typeof item !== \"object\") continue;\n\t\tconst verdict = item as Record<string, unknown>;\n\t\tconst label = typeof verdict.label === \"string\" ? verdict.label.trim().toLowerCase() : \"\";\n\t\t// A label the batch did not ask about is a hallucinated row; dropping it is\n\t\t// safer than letting it mark some other proposal covered.\n\t\tif (!label || !known.has(label)) continue;\n\n\t\tif (verdict.verdict === \"rule\") {\n\t\t\tconst at = typeof verdict.ruleIndex === \"number\" ? index.ruleLines[verdict.ruleIndex] : undefined;\n\t\t\t// An out-of-range index means the model decided \"covered\" but cannot show\n\t\t\t// which line. Treat that as `new`: the reader cannot act on an unnamed rule.\n\t\t\tif (at) out.set(label, { rule: at });\n\t\t\tcontinue;\n\t\t}\n\t\tif (verdict.verdict === \"skill\") {\n\t\t\tconst at = typeof verdict.skillIndex === \"number\" ? index.skills[verdict.skillIndex] : undefined;\n\t\t\tif (at) out.set(label, { skill: at.name });\n\t\t\tcontinue;\n\t\t}\n\t\tout.set(label, {});\n\t}\n\treturn out;\n}\n\nexport interface CoverageDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n}\n\nexport function createLlmCoverageJudge(deps: CoverageDeps): CoverageJudge {\n\treturn async (queries, index, signal) => {\n\t\t// Nothing to match against means nothing can be covered, and the call would\n\t\t// be pure cost.\n\t\tif (queries.length === 0 || (index.ruleLines.length === 0 && index.skills.length === 0)) {\n\t\t\treturn new Map();\n\t\t}\n\n\t\tconst response = await completeSimple(\n\t\t\tdeps.model,\n\t\t\t{\n\t\t\t\tsystemPrompt: COVERAGE_SYSTEM_PROMPT,\n\t\t\t\tmessages: [\n\t\t\t\t\t{ role: \"user\", content: [{ type: \"text\", text: buildPrompt(queries, index) }], timestamp: Date.now() },\n\t\t\t\t],\n\t\t\t},\n\t\t\t{ maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers },\n\t\t);\n\n\t\tif (response.stopReason === \"error\") {\n\t\t\tthrow new Error(response.errorMessage || \"coverage call failed\");\n\t\t}\n\n\t\tconst text = response.content\n\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t.map((c) => c.text)\n\t\t\t.join(\"\\n\");\n\t\treturn parseVerdicts(text, queries, index);\n\t};\n}\n\n/** Everything is new. Used when no model is available, so the run still produces a digest. */\nexport const noCoverageJudge: CoverageJudge = async () => new Map();\n"]}

package/dist/core/learn/coverage.js

@@ -0,0 +1,144 @@
+/**
+ * Is this already written down?
+ *
+ * The answer decides the most useful distinction the digest makes — `new` vs
+ * `restated` vs `has-skill` — and it used to be decided by bag-of-words
+ * overlap: count how many content words of the proposal appear anywhere in a
+ * rule line, call it covered above 0.6. That is wrong in both directions and
+ * for the same reason, namely that it does not read. It calls "always run tests
+ * before pushing" covered by a line about "running the test suite in CI", and
+ * it misses a real paraphrase that happens to pick different vocabulary.
+ *
+ * Both mistakes are expensive. A false `restated` accuses a rule that is
+ * working of not working, and tells the reader to rewrite something fine. A
+ * false `new` proposes a rule they already have, which is how a context file
+ * grows duplicates.
+ *
+ * So a model reads the rules and the proposals together and matches them. One
+ * call for the whole batch, because the question is small and the corpus is the
+ * same for every item — the context file is a few thousand tokens and does not
+ * want re-sending once per proposal.
+ */
+import { completeSimple } from "@kolisachint/hoocode-ai";
+/** Rule lines sent per call. A context file longer than this is already the problem. */
+const MAX_RULE_LINES = 400;
+/** Skills sent per call. */
+const MAX_SKILLS = 120;
+/** Description characters per skill — the opening says what it does; the rest is trigger bait. */
+const SKILL_DESCRIPTION_CHARS = 300;
+const MAX_RESPONSE_TOKENS = 2_000;
+const COVERAGE_SYSTEM_PROMPT = `You decide whether each proposed rule is ALREADY covered by existing project rules or skills.
+
+You are given numbered RULES (lines from context files), numbered SKILLS (name and description), and numbered PROPOSALS.
+
+Each rule reads \`[scope] Heading > Subheading > line\`. The scope is \`repo\` (binds work in this project) or \`user\` (binds everywhere). The heading path is the section the line lives under, and it is what tells you the line's subject when the line alone is ambiguous.
+
+For each proposal, decide:
+- "rule" — an existing rule already says this. The reader repeating it means that rule is not working, so it should be rewritten rather than duplicated.
+- "skill" — an existing skill already does this, and the reader asked by hand anyway. Usually the skill's description does not describe the situation they were in.
+- "new" — nothing covers it.
+
+Judge by MEANING, not by shared words. Different vocabulary for the same instruction is covered. Shared vocabulary about different things is NOT covered:
+- proposal "always use bun, never npm" vs rule "install dependencies with bun" → covered (rule)
+- proposal "run tests before pushing" vs rule "CI runs the test suite on every PR" → NOT covered, these are different instructions to different actors
+- proposal "prefer table output" vs rule "use tables in documentation" → NOT covered unless the scope matches
+
+Prefer "new" when genuinely unsure. A false "covered" tells the reader to rewrite a rule that is fine; a false "new" merely proposes something they can reject.
+
+Rules win over skills when both match: rewriting a line is more actionable than sharpening a description.
+
+Output STRICT JSON, no markdown fence, no prose. Use the proposal's exact label:
+{"verdicts":[{"label":"use-bun-not-npm","verdict":"rule","ruleIndex":3},{"label":"scaffold-route","verdict":"skill","skillIndex":1},{"label":"prefer-tables","verdict":"new"}]}`;
+function buildPrompt(queries, index) {
+    const lines = [];
+    lines.push("RULES:");
+    const rules = index.ruleLines.slice(0, MAX_RULE_LINES);
+    if (rules.length === 0)
+        lines.push("(none)");
+    for (const [i, rule] of rules.entries()) {
+        lines.push(`${i}. ${rule}`);
+    }
+    lines.push("", "SKILLS:");
+    const skills = index.skills.slice(0, MAX_SKILLS);
+    if (skills.length === 0)
+        lines.push("(none)");
+    for (const [i, skill] of skills.entries()) {
+        lines.push(`${i}. ${skill.name} — ${skill.description.slice(0, SKILL_DESCRIPTION_CHARS)}`);
+    }
+    lines.push("", "PROPOSALS:");
+    for (const query of queries) {
+        lines.push(`- label: ${query.label}\n  text: ${query.text}`);
+    }
+    return lines.join("\n");
+}
+/** Read the verdict list back, ignoring anything malformed rather than failing the run. */
+export function parseVerdicts(response, queries, index) {
+    const out = new Map();
+    const start = response.indexOf("{");
+    const end = response.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return out;
+    let parsed;
+    try {
+        parsed = JSON.parse(response.slice(start, end + 1));
+    }
+    catch {
+        return out;
+    }
+    const raw = parsed?.verdicts;
+    if (!Array.isArray(raw))
+        return out;
+    const known = new Set(queries.map((q) => q.label));
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const verdict = item;
+        const label = typeof verdict.label === "string" ? verdict.label.trim().toLowerCase() : "";
+        // A label the batch did not ask about is a hallucinated row; dropping it is
+        // safer than letting it mark some other proposal covered.
+        if (!label || !known.has(label))
+            continue;
+        if (verdict.verdict === "rule") {
+            const at = typeof verdict.ruleIndex === "number" ? index.ruleLines[verdict.ruleIndex] : undefined;
+            // An out-of-range index means the model decided "covered" but cannot show
+            // which line. Treat that as `new`: the reader cannot act on an unnamed rule.
+            if (at)
+                out.set(label, { rule: at });
+            continue;
+        }
+        if (verdict.verdict === "skill") {
+            const at = typeof verdict.skillIndex === "number" ? index.skills[verdict.skillIndex] : undefined;
+            if (at)
+                out.set(label, { skill: at.name });
+            continue;
+        }
+        out.set(label, {});
+    }
+    return out;
+}
+export function createLlmCoverageJudge(deps) {
+    return async (queries, index, signal) => {
+        // Nothing to match against means nothing can be covered, and the call would
+        // be pure cost.
+        if (queries.length === 0 || (index.ruleLines.length === 0 && index.skills.length === 0)) {
+            return new Map();
+        }
+        const response = await completeSimple(deps.model, {
+            systemPrompt: COVERAGE_SYSTEM_PROMPT,
+            messages: [
+                { role: "user", content: [{ type: "text", text: buildPrompt(queries, index) }], timestamp: Date.now() },
+            ],
+        }, { maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers });
+        if (response.stopReason === "error") {
+            throw new Error(response.errorMessage || "coverage call failed");
+        }
+        const text = response.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+        return parseVerdicts(text, queries, index);
+    };
+}
+/** Everything is new. Used when no model is available, so the run still produces a digest. */
+export const noCoverageJudge = async () => new Map();
+//# sourceMappingURL=coverage.js.map

package/dist/core/learn/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../../src/core/learn/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAgCzD,wFAAwF;AACxF,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,4BAA4B;AAC5B,MAAM,UAAU,GAAG,GAAG,CAAC;AACvB,oGAAkG;AAClG,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;gLAqBiJ,CAAC;AAEjL,SAAS,WAAW,CAAC,OAAwB,EAAE,KAAoB,EAAU;IAC5E,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,QAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,KAAK,aAAa,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACxB;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAC5B,QAAgB,EAChB,OAAwB,EACxB,KAAoB,EACS;IAC7B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC;IAE1C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,GAAG,GAAI,MAAiC,EAAE,QAAQ,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAEpC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QAChD,MAAM,OAAO,GAAG,IAA+B,CAAC;QAChD,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,4EAA4E;QAC5E,0DAA0D;QAC1D,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAE1C,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAClG,0EAA0E;YAC1E,6EAA6E;YAC7E,IAAI,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACrC,SAAS;QACV,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACjG,IAAI,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3C,SAAS;QACV,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACX;AAQD,MAAM,UAAU,sBAAsB,CAAC,IAAkB,EAAiB;IACzE,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;QACxC,4EAA4E;QAC5E,gBAAgB;QAChB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YACzF,OAAO,IAAI,GAAG,EAAE,CAAC;QAClB,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,cAAc,CACpC,IAAI,CAAC,KAAK,EACV;YACC,YAAY,EAAE,sBAAsB;YACpC,QAAQ,EAAE;gBACT,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE;aACvG;SACD,EACD,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CACtF,CAAC;QAEF,IAAI,QAAQ,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,IAAI,sBAAsB,CAAC,CAAC;QAClE,CAAC;QAED,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO;aAC3B,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aACrE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAAA,CAC3C,CAAC;AAAA,CACF;AAED,8FAA8F;AAC9F,MAAM,CAAC,MAAM,eAAe,GAAkB,KAAK,IAAI,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC","sourcesContent":["/**\n * Is this already written down?\n *\n * The answer decides the most useful distinction the digest makes — `new` vs\n * `restated` vs `has-skill` — and it used to be decided by bag-of-words\n * overlap: count how many content words of the proposal appear anywhere in a\n * rule line, call it covered above 0.6. That is wrong in both directions and\n * for the same reason, namely that it does not read. It calls \"always run tests\n * before pushing\" covered by a line about \"running the test suite in CI\", and\n * it misses a real paraphrase that happens to pick different vocabulary.\n *\n * Both mistakes are expensive. A false `restated` accuses a rule that is\n * working of not working, and tells the reader to rewrite something fine. A\n * false `new` proposes a rule they already have, which is how a context file\n * grows duplicates.\n *\n * So a model reads the rules and the proposals together and matches them. One\n * call for the whole batch, because the question is small and the corpus is the\n * same for every item — the context file is a few thousand tokens and does not\n * want re-sending once per proposal.\n */\n\nimport type { Model } from \"@kolisachint/hoocode-ai\";\nimport { completeSimple } from \"@kolisachint/hoocode-ai\";\n\nexport interface CoverageIndex {\n\t/** Candidate rule lines from the repo context file and both user scopes. */\n\truleLines: string[];\n\tskills: Array<{ name: string; description: string }>;\n}\n\nexport interface CoverageMatch {\n\t/** The context-file line that covers this, if any. */\n\trule?: string;\n\t/** The skill that covers this, if any. Only set when no rule matched. */\n\tskill?: string;\n}\n\n/** One thing to look up, identified by the label the reduce step grouped on. */\nexport interface CoverageQuery {\n\tlabel: string;\n\ttext: string;\n}\n\n/**\n * Decide coverage for a batch. Injectable so the pipeline can be tested without\n * a model, and so a run with no model configured can degrade to \"everything is\n * new\" rather than failing.\n */\nexport type CoverageJudge = (\n\tqueries: CoverageQuery[],\n\tindex: CoverageIndex,\n\tsignal?: AbortSignal,\n) => Promise<Map<string, CoverageMatch>>;\n\n/** Rule lines sent per call. A context file longer than this is already the problem. */\nconst MAX_RULE_LINES = 400;\n/** Skills sent per call. */\nconst MAX_SKILLS = 120;\n/** Description characters per skill — the opening says what it does; the rest is trigger bait. */\nconst SKILL_DESCRIPTION_CHARS = 300;\nconst MAX_RESPONSE_TOKENS = 2_000;\n\nconst COVERAGE_SYSTEM_PROMPT = `You decide whether each proposed rule is ALREADY covered by existing project rules or skills.\n\nYou are given numbered RULES (lines from context files), numbered SKILLS (name and description), and numbered PROPOSALS.\n\nEach rule reads \\`[scope] Heading > Subheading > line\\`. The scope is \\`repo\\` (binds work in this project) or \\`user\\` (binds everywhere). The heading path is the section the line lives under, and it is what tells you the line's subject when the line alone is ambiguous.\n\nFor each proposal, decide:\n- \"rule\" — an existing rule already says this. The reader repeating it means that rule is not working, so it should be rewritten rather than duplicated.\n- \"skill\" — an existing skill already does this, and the reader asked by hand anyway. Usually the skill's description does not describe the situation they were in.\n- \"new\" — nothing covers it.\n\nJudge by MEANING, not by shared words. Different vocabulary for the same instruction is covered. Shared vocabulary about different things is NOT covered:\n- proposal \"always use bun, never npm\" vs rule \"install dependencies with bun\" → covered (rule)\n- proposal \"run tests before pushing\" vs rule \"CI runs the test suite on every PR\" → NOT covered, these are different instructions to different actors\n- proposal \"prefer table output\" vs rule \"use tables in documentation\" → NOT covered unless the scope matches\n\nPrefer \"new\" when genuinely unsure. A false \"covered\" tells the reader to rewrite a rule that is fine; a false \"new\" merely proposes something they can reject.\n\nRules win over skills when both match: rewriting a line is more actionable than sharpening a description.\n\nOutput STRICT JSON, no markdown fence, no prose. Use the proposal's exact label:\n{\"verdicts\":[{\"label\":\"use-bun-not-npm\",\"verdict\":\"rule\",\"ruleIndex\":3},{\"label\":\"scaffold-route\",\"verdict\":\"skill\",\"skillIndex\":1},{\"label\":\"prefer-tables\",\"verdict\":\"new\"}]}`;\n\nfunction buildPrompt(queries: CoverageQuery[], index: CoverageIndex): string {\n\tconst lines: string[] = [];\n\n\tlines.push(\"RULES:\");\n\tconst rules = index.ruleLines.slice(0, MAX_RULE_LINES);\n\tif (rules.length === 0) lines.push(\"(none)\");\n\tfor (const [i, rule] of rules.entries()) {\n\t\tlines.push(`${i}. ${rule}`);\n\t}\n\n\tlines.push(\"\", \"SKILLS:\");\n\tconst skills = index.skills.slice(0, MAX_SKILLS);\n\tif (skills.length === 0) lines.push(\"(none)\");\n\tfor (const [i, skill] of skills.entries()) {\n\t\tlines.push(`${i}. ${skill.name} — ${skill.description.slice(0, SKILL_DESCRIPTION_CHARS)}`);\n\t}\n\n\tlines.push(\"\", \"PROPOSALS:\");\n\tfor (const query of queries) {\n\t\tlines.push(`- label: ${query.label}\\n  text: ${query.text}`);\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/** Read the verdict list back, ignoring anything malformed rather than failing the run. */\nexport function parseVerdicts(\n\tresponse: string,\n\tqueries: CoverageQuery[],\n\tindex: CoverageIndex,\n): Map<string, CoverageMatch> {\n\tconst out = new Map<string, CoverageMatch>();\n\tconst start = response.indexOf(\"{\");\n\tconst end = response.lastIndexOf(\"}\");\n\tif (start < 0 || end <= start) return out;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(response.slice(start, end + 1));\n\t} catch {\n\t\treturn out;\n\t}\n\n\tconst raw = (parsed as { verdicts?: unknown })?.verdicts;\n\tif (!Array.isArray(raw)) return out;\n\n\tconst known = new Set(queries.map((q) => q.label));\n\tfor (const item of raw) {\n\t\tif (!item || typeof item !== \"object\") continue;\n\t\tconst verdict = item as Record<string, unknown>;\n\t\tconst label = typeof verdict.label === \"string\" ? verdict.label.trim().toLowerCase() : \"\";\n\t\t// A label the batch did not ask about is a hallucinated row; dropping it is\n\t\t// safer than letting it mark some other proposal covered.\n\t\tif (!label || !known.has(label)) continue;\n\n\t\tif (verdict.verdict === \"rule\") {\n\t\t\tconst at = typeof verdict.ruleIndex === \"number\" ? index.ruleLines[verdict.ruleIndex] : undefined;\n\t\t\t// An out-of-range index means the model decided \"covered\" but cannot show\n\t\t\t// which line. Treat that as `new`: the reader cannot act on an unnamed rule.\n\t\t\tif (at) out.set(label, { rule: at });\n\t\t\tcontinue;\n\t\t}\n\t\tif (verdict.verdict === \"skill\") {\n\t\t\tconst at = typeof verdict.skillIndex === \"number\" ? index.skills[verdict.skillIndex] : undefined;\n\t\t\tif (at) out.set(label, { skill: at.name });\n\t\t\tcontinue;\n\t\t}\n\t\tout.set(label, {});\n\t}\n\treturn out;\n}\n\nexport interface CoverageDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n}\n\nexport function createLlmCoverageJudge(deps: CoverageDeps): CoverageJudge {\n\treturn async (queries, index, signal) => {\n\t\t// Nothing to match against means nothing can be covered, and the call would\n\t\t// be pure cost.\n\t\tif (queries.length === 0 || (index.ruleLines.length === 0 && index.skills.length === 0)) {\n\t\t\treturn new Map();\n\t\t}\n\n\t\tconst response = await completeSimple(\n\t\t\tdeps.model,\n\t\t\t{\n\t\t\t\tsystemPrompt: COVERAGE_SYSTEM_PROMPT,\n\t\t\t\tmessages: [\n\t\t\t\t\t{ role: \"user\", content: [{ type: \"text\", text: buildPrompt(queries, index) }], timestamp: Date.now() },\n\t\t\t\t],\n\t\t\t},\n\t\t\t{ maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers },\n\t\t);\n\n\t\tif (response.stopReason === \"error\") {\n\t\t\tthrow new Error(response.errorMessage || \"coverage call failed\");\n\t\t}\n\n\t\tconst text = response.content\n\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t.map((c) => c.text)\n\t\t\t.join(\"\\n\");\n\t\treturn parseVerdicts(text, queries, index);\n\t};\n}\n\n/** Everything is new. Used when no model is available, so the run still produces a digest. */\nexport const noCoverageJudge: CoverageJudge = async () => new Map();\n"]}

package/dist/core/learn/digest.d.ts

@@ -8,10 +8,23 @@
  * because "said in 5 of your last 12 sessions" is a decision the reader can
  * make in one keystroke, where "extracted from your session" is not.
  */
+import type { AuditReport } from "./audit.js";
 import type { LearnDigest } from "./extract.js";
 /** True when there is nothing worth asking the model to look at. */
 export declare function isEmptyDigest(digest: LearnDigest): boolean;
+/**
+ * Render the audit findings as a message the model can act on.
+ *
+ * Deliberately framed as questions rather than verdicts. The checker is
+ * deterministic and therefore confident, but "this path does not resolve" is
+ * not the same claim as "this line is wrong" — a context file may name a
+ * location the tool reads at runtime, or one that belongs to another checkout.
+ * Roughly a third of findings on a real file are of that kind, so the message
+ * that carries them has to ask for verification, not authorise a sweep.
+ */
+export declare function renderAuditReport(report: AuditReport): string;
 export declare function renderLearnDigest(digest: LearnDigest, options: {
     userScopePath: string;
+    mode?: "incremental" | "all";
 }): string;
 //# sourceMappingURL=digest.d.ts.map