dsh-continual-evolve 0.2.0 → 0.4.0

package/lib/review.js

@@ -1,6 +1,6 @@
-import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
 import { extractJsonObject } from "./plan.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+import { streamText } from "./llm-text.js";
 export const AUTO_REVIEW_SYSTEM_PROMPT = `You are the automatic /evolve review gate.
 
 Decide whether this checkpoint should run /evolve. Auto /evolve writes local
@@ -88,7 +88,9 @@ export function serializeSurface(events, maxChars) {
 }
 export async function reviewAutoRefine(ctx, options) {
     const { agent, state, history } = options;
-    if (!agent.options.provider || !agent.options.model) {
+    const provider = options.overrideProvider ?? agent.options.provider;
+    const model = options.overrideModel ?? agent.options.model;
+    if (!provider || !model) {
         throw new Error("evolve: no provider/model route for the review gate");
     }
     if (!options.trajectory || options.trajectory.length === 0) {
@@ -101,44 +103,14 @@ export async function reviewAutoRefine(ctx, options) {
         `<conversation>\n${options.trajectory}\n</conversation>`,
         "Return shouldRefine=true when the trajectory contains evidence useful to this session's future turns. Prefer local edits; do not ask for global refinement here.",
     ].join("\n\n");
-    const assembler = new BlockAssembler();
-    for await (const chunk of ctx.llm.stream({
-        provider: agent.options.provider,
-        model: agent.options.model,
+    const text = await streamText(ctx, {
+        provider,
+        model,
         system: AUTO_REVIEW_SYSTEM_PROMPT,
-        messages: [
-            createUserMessage({
-                content: [{ type: "text", text: userPrompt }],
-                source: { kind: "plugin", plugin: "dsh-continual-evolve" },
-            }),
-        ],
-        // Force non-reasoning output so the model spends its budget on the JSON
-        // answer, not on visible thinking (reasoning models otherwise produce
-        // zero text blocks — the exact failure recorded in reviews.jsonl).
-        reasoningEffort: ReasoningEffortId("off"),
+        prompt: userPrompt,
         maxTokens: options.budgetTokens ?? 8000,
-        ...(options.signal ? { signal: options.signal } : {}),
-    })) {
-        assembler.push(chunk);
-    }
-    const finish = assembler.finish;
-    if (finish.kind === "error") {
-        throw new Error(`evolve: review gate call failed: ${finish.failure?.message ?? "unknown"}`);
-    }
-    if (finish.kind === "aborted") {
-        throw new Error("evolve: review gate call aborted");
-    }
-    if (finish.kind === "max-tokens") {
-        throw new Error("evolve: review gate output budget exhausted (max-tokens)");
-    }
-    const text = assembler
-        .blocks()
-        .filter((block) => block.type === "text")
-        .map((block) => block.text)
-        .join("\n");
-    if (text.length === 0) {
-        throw new Error("evolve: review gate produced no text");
-    }
+        signal: options.signal,
+    });
     return parseAutoRefineReview(text);
 }
 //# sourceMappingURL=review.js.map

package/lib/rollback.d.ts

@@ -3,9 +3,7 @@
  * result, in reverse order. Rollback is pure data transformation — no LLM
  * is asked to "guess" the previous state.
  */
-import type { HarnessEntry, RefinementProposal, RefinementResult } from "./types.js";
+import type { RefinementProposal, RefinementResult } from "./types.js";
 /** Build the inverse proposal for an applied refinement. */
 export declare function rollbackProposal(target: RefinementResult): RefinementProposal;
-/** Recreate an entry from a prior snapshot (used when an inverse edit is an update). */
-export declare function restoreEntry(prior: HarnessEntry): HarnessEntry;
 //# sourceMappingURL=rollback.d.ts.map

package/lib/rollback.js

@@ -58,12 +58,4 @@ function inverseEdit(edit, refinementId) {
     }
     return undefined;
 }
-/** Recreate an entry from a prior snapshot (used when an inverse edit is an update). */
-export function restoreEntry(prior) {
-    return {
-        ...prior,
-        updated_at: new Date().toISOString(),
-        version: prior.version + 1,
-    };
-}
 //# sourceMappingURL=rollback.js.map

package/lib/score.d.ts

@@ -23,6 +23,8 @@ export interface AggregateResult extends Record<string, number | null> {
     failed: number;
     /** Total cells considered (ok + failed). */
     total: number;
+    /** Gap C3: total wall-clock duration of all cells in milliseconds. */
+    totalDurationMs: number;
 }
 /**
  * Aggregate raw cells into code-owned per-case means + overall mean.
@@ -38,6 +40,19 @@ export interface Decision {
 }
 /** Human-readable decision report with per-case before → after deltas. */
 export declare function decisionReport(reference: EvaluationEntry, candidate: EvaluationEntry, decision: Decision): string[];
+/**
+ * Gap A3 (version_changed semantics): detect cells whose case material
+ * changed between the reference and candidate evaluation runs. A candidate
+ * cell whose `caseHash` differs from the reference cell of the SAME case
+ * means the statement/rubric was edited between the two runs — its score is
+ * not comparable to the baseline and must not count toward the decision.
+ *
+ * The check is conservative: cells without a hash on either side (pre-A3
+ * data) and cells already failed are left untouched. Mismatched cells are
+ * returned re-marked as `failed` with a reason in notes, so aggregation
+ * excludes them and the acceptance rule can reject the round.
+ */
+export declare function flagMaterialDrift(reference: EvaluationEntry, candidateCells: readonly CellScore[]): CellScore[];
 /**
  * Non-regressive acceptance rule (Self-Harness style):
  * the candidate is accepted iff its overall mean is STRICTLY higher than the

package/lib/score.js

@@ -26,11 +26,18 @@ export function aggregate(cells) {
         perCase[caseId] = mean(scores);
     }
     const all = [...byCase.values()].flat();
+    let totalDurationMs = 0;
+    for (const cell of cells) {
+        if (cell.durationMs !== undefined && cell.durationMs >= 0) {
+            totalDurationMs += cell.durationMs;
+        }
+    }
     return {
         ...perCase,
         overall: all.length > 0 ? mean(all) : null,
         failed,
         total: cells.length,
+        totalDurationMs,
     };
 }
 export function entryFromCells(label, cells, refinementId) {
@@ -47,8 +54,12 @@ export function entryFromCells(label, cells, refinementId) {
 /** Human-readable decision report with per-case before → after deltas. */
 export function decisionReport(reference, candidate, decision) {
     const lines = [`overall: ${reference.overall ?? "?"} → ${candidate.overall ?? "?"}`];
-    for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
-        if (caseId === "overall" || caseId === "failed" || caseId === "total" || refScore === null)
+    // Per-case deltas over the actual evaluated cases only (aggregate() mixes
+    // case means with metadata keys like totalDurationMs — never render those
+    // as cases).
+    for (const caseId of new Set(reference.cells.map((cell) => cell.caseId))) {
+        const refScore = reference.aggregate[caseId];
+        if (refScore === null || refScore === undefined)
             continue;
         const candScore = candidate.aggregate[caseId];
         const failedMark = isCaseFailed(reference, caseId) || isCaseFailed(candidate, caseId) ? " (failed)" : "";
@@ -59,11 +70,55 @@ export function decisionReport(reference, candidate, decision) {
     if (refFailed > 0 || candFailed > 0) {
         lines.push(`failed cells: reference ${refFailed}/${reference.aggregate.total ?? 0} · candidate ${candFailed}/${candidate.aggregate.total ?? 0}`);
     }
+    // Gap C3: show duration summary when available.
+    const refDuration = reference.aggregate.totalDurationMs ?? 0;
+    const candDuration = candidate.aggregate.totalDurationMs ?? 0;
+    if (refDuration > 0 || candDuration > 0) {
+        lines.push(`duration: ${formatDuration(refDuration)} → ${formatDuration(candDuration)}`);
+    }
     lines.push(decision.accepted
         ? "DECISION: ACCEPTED — overall improved, no regression"
         : `DECISION: REJECTED — ${decision.reasons.join("; ")}`);
     return lines;
 }
+/**
+ * Gap A3 (version_changed semantics): detect cells whose case material
+ * changed between the reference and candidate evaluation runs. A candidate
+ * cell whose `caseHash` differs from the reference cell of the SAME case
+ * means the statement/rubric was edited between the two runs — its score is
+ * not comparable to the baseline and must not count toward the decision.
+ *
+ * The check is conservative: cells without a hash on either side (pre-A3
+ * data) and cells already failed are left untouched. Mismatched cells are
+ * returned re-marked as `failed` with a reason in notes, so aggregation
+ * excludes them and the acceptance rule can reject the round.
+ */
+export function flagMaterialDrift(reference, candidateCells) {
+    const referenceHashes = new Map();
+    for (const cell of reference.cells) {
+        if (cell.status !== "failed" && cell.caseHash !== undefined && !referenceHashes.has(cell.caseId)) {
+            referenceHashes.set(cell.caseId, cell.caseHash);
+        }
+    }
+    if (referenceHashes.size === 0) {
+        return [...candidateCells];
+    }
+    return candidateCells.map((cell) => {
+        if (cell.status === "failed" || cell.caseHash === undefined) {
+            return cell;
+        }
+        const refHash = referenceHashes.get(cell.caseId);
+        if (refHash !== undefined && refHash !== cell.caseHash) {
+            return {
+                ...cell,
+                status: "failed",
+                passed: false,
+                notes: `materials changed: case ${cell.caseId} hash ${cell.caseHash} ≠ reference ${refHash} (re-run the reference or fix the material)`,
+            };
+        }
+        return cell;
+    });
+}
 function isCaseFailed(entry, caseId) {
     return entry.cells.some((cell) => cell.caseId === caseId && cell.status === "failed");
 }
@@ -93,9 +148,17 @@ export function decide(reference, candidate, opts) {
     if (candidate.overall <= reference.overall) {
         reasons.push(`overall not improved: ${candidate.overall} <= ${reference.overall}`);
     }
-    for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
-        if (caseId === "overall" || caseId === "failed" || caseId === "total" || refScore === null)
-            continue;
+    // Per-case regression is judged ONLY over the cases that actually exist in
+    // the evaluation — aggregate() mixes per-case means with metadata keys
+    // (failed/total/totalDurationMs), and iterating raw keys would (and did)
+    // treat totalDurationMs as a case score, rejecting a candidate whose run
+    // merely took longer. Derived from reference.cells, never from the
+    // aggregate key set.
+    for (const caseId of new Set(reference.cells.map((cell) => cell.caseId))) {
+        const refScore = reference.aggregate[caseId];
+        if (refScore === null || refScore === undefined) {
+            continue; // case had no comparable mean (all cells failed) — nothing to regress
+        }
         const candScore = candidate.aggregate[caseId];
         if (candScore === null || candScore === undefined) {
             reasons.push(`candidate missing case ${caseId}`);
@@ -119,4 +182,10 @@ function clampScore(score) {
 function round2(value) {
     return Math.round(value * 100) / 100;
 }
+/** Gap C3: human-readable duration (ms → "1.2s" or "340ms"). */
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
 //# sourceMappingURL=score.js.map

package/lib/service.d.ts

@@ -5,7 +5,6 @@
  */
 import type { EntrySource, HarnessScope, RefinementProposal, RefinementResult } from "./types.js";
 import { applyRefinementProposal } from "./apply.js";
-import { storePaths } from "./store.js";
 export interface ApplyContext {
     scope: HarnessScope;
     sessionId?: string;
@@ -13,6 +12,8 @@ export interface ApplyContext {
     baselineState?: Parameters<typeof applyRefinementProposal>[0];
     /** Trajectory citation stamped into newly created entries (see apply.ts). */
     source?: EntrySource | undefined;
+    /** Marks the resulting refinement as the deterministic rollback of another (audit chain). */
+    rollbackOf?: string | undefined;
 }
 export interface EvolutionHooks {
     /** Called after every applied refinement (side-effect boundary: skills sync, etc.). */
@@ -26,5 +27,4 @@ export declare function createEvolutionEngine(baseDir: string, hooks?: Evolution
     baseDir: string;
 };
 export type EvolutionEngine = ReturnType<typeof createEvolutionEngine>;
-export { storePaths };
 //# sourceMappingURL=service.d.ts.map

package/lib/service.js

@@ -1,4 +1,5 @@
 import { applyRefinementProposal } from "./apply.js";
+import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
@@ -9,7 +10,7 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
     function apply(scope, sessionId, proposal, context) {
         const paths = storePaths(baseDir, scope, sessionId);
         const state = context?.baselineState ?? load(scope, sessionId);
-        const id = `evolve_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const id = `evolve_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
         // Code-enforced snapshot: runs before any mutation, cannot be skipped by the model.
         snapshotBefore(paths, id);
         const result = applyRefinementProposal(state, proposal, {
@@ -17,6 +18,7 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
             scope,
             ...(context?.source ? { source: context.source } : {}),
             ...(context?.baselineState ? { baselineState: context.baselineState } : {}),
+            ...(context?.rollbackOf ? { rollbackOf: context.rollbackOf } : {}),
         });
         saveHarnessState(paths.stateDir, state);
         appendResult(paths, result);
@@ -31,12 +33,14 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
             throw new Error(`Refinement ${refinementId} not found in ${scope} history`);
         }
         const proposal = rollbackProposal(target);
-        return apply(scope, sessionId, proposal);
+        // The rollback refinement carries rollbackOf so the audit chain links
+        // the inverse operation back to its origin (previously the rollback
+        // record only echoed "Rollback refinement <id>" in its summary text).
+        return apply(scope, sessionId, proposal, { scope, rollbackOf: refinementId });
     }
     function history(scope, sessionId) {
         return loadResults(storePaths(baseDir, scope, sessionId));
     }
     return { load, apply, rollback, history, baseDir };
 }
-export { storePaths };
 //# sourceMappingURL=service.js.map

package/lib/skill-render.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Skill rendering: pure functions that convert harness entries into
+ * SKILL.md documents. Extracted from skill.ts to break the circular
+ * dependency between skill.ts ↔ skillquality.ts.
+ *
+ * Both skill.ts (materializer) and skillquality.ts (validator) need
+ * these rendering functions; importing from this shared leaf module
+ * keeps the dependency graph acyclic.
+ */
+import type { HarnessEntry } from "./types.js";
+/** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
+export declare function skillNameOf(id: string): string;
+/**
+ * Render a harness skill entry as a discoverable SKILL.md document.
+ *
+ * 2026-08-22: the frontmatter description now carries a ROUTING HINT —
+ * title plus the first meaningful content line — instead of the bare title.
+ * The skill catalog matches on description; a title-only description gave
+ * loaders nothing to route on (observed: materialized skills were 7-line
+ * stubs with a one-line description and no use-when signal).
+ */
+export declare function renderSkillMarkdown(entry: HarnessEntry): string;
+//# sourceMappingURL=skill-render.d.ts.map

package/lib/skill-render.js

@@ -0,0 +1,68 @@
+/** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
+export function skillNameOf(id) {
+    return id.toLowerCase().replace(/_/g, "-");
+}
+/**
+ * First content line usable as a routing hint: non-empty, not a Markdown
+ * heading, not a list marker, not frontmatter. Undefined when the body is
+ * effectively empty.
+ */
+function routingHint(content) {
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith("#") || line.startsWith("---") || line.startsWith("-") || line.startsWith("*"))
+            continue;
+        return oneLine(line);
+    }
+    return undefined;
+}
+/** Max rendered frontmatter description length (loaders truncate anyway). */
+const MAX_DESCRIPTION_LENGTH = 240;
+/**
+ * Render a harness skill entry as a discoverable SKILL.md document.
+ *
+ * 2026-08-22: the frontmatter description now carries a ROUTING HINT —
+ * title plus the first meaningful content line — instead of the bare title.
+ * The skill catalog matches on description; a title-only description gave
+ * loaders nothing to route on (observed: materialized skills were 7-line
+ * stubs with a one-line description and no use-when signal).
+ */
+export function renderSkillMarkdown(entry) {
+    const hint = routingHint(entry.content);
+    const base = oneLine(entry.title);
+    let description;
+    if (base.length === 0) {
+        description = (hint ?? "").slice(0, MAX_DESCRIPTION_LENGTH);
+    }
+    else if (hint !== undefined && !base.toLowerCase().includes(hint.toLowerCase())) {
+        description = `${base} — use when: ${hint}`.slice(0, MAX_DESCRIPTION_LENGTH);
+    }
+    else {
+        description = base.slice(0, MAX_DESCRIPTION_LENGTH);
+    }
+    const lines = [
+        "---",
+        `name: ${skillNameOf(entry.id)}`,
+        `description: ${description}`,
+        "---",
+        "",
+        entry.content.trim(),
+    ];
+    const reference = entry.reference;
+    if (reference && typeof reference === "object" && Object.keys(reference).length > 0) {
+        lines.push("", "## Invocation");
+        for (const [key, value] of Object.entries(reference)) {
+            lines.push(`- ${key}: ${JSON.stringify(value)}`);
+        }
+    }
+    if (Object.keys(entry.arguments).length > 0) {
+        lines.push("", "## Arguments", "```json", JSON.stringify(entry.arguments, null, 2), "```");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+//# sourceMappingURL=skill-render.js.map

package/lib/skill.d.ts

@@ -1,10 +1,7 @@
-import type { HarnessEntry, RefinementResult } from "./types.js";
-/** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
-export declare function skillNameOf(id: string): string;
+import type { RefinementResult } from "./types.js";
+export { renderSkillMarkdown, skillNameOf } from "./skill-render.js";
 /** Resolve and defend the skill directory for an entry id. */
 export declare function skillDir(skillsRoot: string, id: string): string;
-/** Render a harness skill entry as a discoverable SKILL.md document. */
-export declare function renderSkillMarkdown(entry: HarnessEntry): string;
 /**
  * Apply the skill-kind edits of an applied refinement to the skills root.
  * Returns materialization warnings (rendered-SKILL.md mechanical problems

package/lib/skill.js

@@ -9,11 +9,9 @@
  */
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+import { renderSkillMarkdown, skillNameOf } from "./skill-render.js";
 import { skillResourceRefs, validateRenderedSkill } from "./skillquality.js";
-/** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
-export function skillNameOf(id) {
-    return id.toLowerCase().replace(/_/g, "-");
-}
+export { renderSkillMarkdown, skillNameOf } from "./skill-render.js";
 /** Resolve and defend the skill directory for an entry id. */
 export function skillDir(skillsRoot, id) {
     const root = resolve(skillsRoot);
@@ -23,28 +21,6 @@ export function skillDir(skillsRoot, id) {
     }
     return dir;
 }
-/** Render a harness skill entry as a discoverable SKILL.md document. */
-export function renderSkillMarkdown(entry) {
-    const lines = [
-        "---",
-        `name: ${skillNameOf(entry.id)}`,
-        `description: ${oneLine(entry.title)}`,
-        "---",
-        "",
-        entry.content.trim(),
-    ];
-    const reference = entry.reference;
-    if (reference && typeof reference === "object" && Object.keys(reference).length > 0) {
-        lines.push("", "## Invocation");
-        for (const [key, value] of Object.entries(reference)) {
-            lines.push(`- ${key}: ${JSON.stringify(value)}`);
-        }
-    }
-    if (Object.keys(entry.arguments).length > 0) {
-        lines.push("", "## Arguments", "```json", JSON.stringify(entry.arguments, null, 2), "```");
-    }
-    return `${lines.join("\n").trimEnd()}\n`;
-}
 /**
  * Apply the skill-kind edits of an applied refinement to the skills root.
  * Returns materialization warnings (rendered-SKILL.md mechanical problems
@@ -101,7 +77,4 @@ function removeSkill(skillsRoot, id) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-function oneLine(text) {
-    return text.replace(/\s+/g, " ").trim();
-}
 //# sourceMappingURL=skill.js.map

package/lib/skillquality.d.ts

@@ -1,5 +1,4 @@
 import type { HarnessEntry } from "./types.js";
-import { skillNameOf } from "./skill.js";
 /** Relative location of the skill-creator template facts. */
 export declare const SKILL_CREATOR_TEMPLATE_REL: string;
 /**
@@ -77,5 +76,5 @@ export declare function validateRenderedSkill(entry: HarnessEntry): string[];
  */
 export declare function skillResourceRefs(content: string): string[];
 /** Kebab-case name under which the entry materializes (exported for diagnostics). */
-export { skillNameOf };
+export { skillNameOf } from "./skill-render.js";
 //# sourceMappingURL=skillquality.d.ts.map

package/lib/skillquality.js

@@ -21,7 +21,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { renderSkillMarkdown, skillNameOf } from "./skill.js";
+import { renderSkillMarkdown } from "./skill-render.js";
 /** Skill-name regex the platform enforces (skill-filesystem). */
 const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const TRUE_WORDS = new Set(["true", "yes", "on", "1"]);
@@ -307,5 +307,5 @@ export function skillResourceRefs(content) {
     return [...refs];
 }
 /** Kebab-case name under which the entry materializes (exported for diagnostics). */
-export { skillNameOf };
+export { skillNameOf } from "./skill-render.js";
 //# sourceMappingURL=skillquality.js.map

package/lib/state.js

@@ -80,8 +80,13 @@ export function loadHarnessState(stateDir, scope = "global") {
                     scope: normalizeScope(entry["scope"], scope),
                     reference: objectRecord(entry["reference"]) ?? {},
                     arguments: objectRecord(entry["arguments"]) ?? {},
+                    // skill_kind must survive persistence: /evolve mount and the
+                    // listing render branch on it (guidance vs executable).
+                    ...(entry["skill_kind"] === "guidance" || entry["skill_kind"] === "executable"
+                        ? { skill_kind: entry["skill_kind"] }
+                        : {}),
                     metadata: objectRecord(entry["metadata"]) ?? {},
-                    source: entry["source"] === "evolve" ? "evolve" : "evolve",
+                    source: "evolve",
                     created_at: typeof entry["created_at"] === "string" ? entry["created_at"] : new Date(0).toISOString(),
                     updated_at: typeof entry["updated_at"] === "string" ? entry["updated_at"] : new Date(0).toISOString(),
                     version: typeof entry["version"] === "number" ? entry["version"] : 1,

package/lib/store.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessScope, HarnessState, RefinementResult } from "./types.js";
+import type { HarnessScope, RefinementResult } from "./types.js";
 export declare const EVOLVE_DIR = "evolve";
 export interface StorePaths {
     /** Directory holding harness_state.json. */
@@ -15,6 +15,4 @@ export declare function snapshotBefore(paths: StorePaths, refinementId: string):
 export declare function appendResult(paths: StorePaths, result: RefinementResult): void;
 /** Read the applied results history; malformed lines are skipped, never fatal. */
 export declare function loadResults(paths: StorePaths): RefinementResult[];
-/** Load a state file into memory, returning empty state when absent. */
-export declare function loadStateFile(paths: StorePaths): HarnessState;
 //# sourceMappingURL=store.d.ts.map

package/lib/store.js

@@ -14,7 +14,6 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { emptyHarnessState } from "./types.js";
 import { stateFilePath } from "./state.js";
 export const EVOLVE_DIR = "evolve";
 export function storePaths(baseDir, scope, sessionId) {
@@ -65,10 +64,4 @@ export function loadResults(paths) {
 function isResult(data) {
     return typeof data === "object" && data !== null && "id" in data && "appliedEdits" in data;
 }
-/** Load a state file into memory, returning empty state when absent. */
-export function loadStateFile(paths) {
-    return existsSync(stateFilePath(paths.stateDir))
-        ? JSON.parse(readFileSync(stateFilePath(paths.stateDir), "utf8"))
-        : emptyHarnessState();
-}
 //# sourceMappingURL=store.js.map

package/lib/tool.js

@@ -2,6 +2,8 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 import { formatHarnessStateForPrompt } from "./render.js";
 import { requireGlobalApproval } from "./approval.js";
 import { entrySourceOf } from "./source.js";
+import { getUsageCount, loadUsage } from "./usage.js";
+import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
 const SCOPES = ["local", "global"];
 /** Accept both the boolean tool parameter (`global: true`) and the string form. */
 export function scopeOf(value, fallback) {
@@ -32,7 +34,22 @@ export function registerEvolveTools(ctx, engine, opts) {
         execute: async (args, exec) => {
             const scope = scopeOf(args.scope, "local");
             const state = engine.load(scope, sessionIdOf(exec));
-            return textResult(formatHarnessStateForPrompt(state));
+            const text = formatHarnessStateForPrompt(state);
+            // Append injection usage counts (gap B1).
+            const usage = loadUsage(engine.baseDir);
+            const usageLines = [];
+            for (const kind of Object.keys(state.entries)) {
+                for (const entry of Object.values(state.entries[kind])) {
+                    const count = getUsageCount(usage, kind, entry.id);
+                    if (count > 0) {
+                        usageLines.push(`${kind}:${entry.id} — injected ${count}×`);
+                    }
+                }
+            }
+            if (usageLines.length > 0) {
+                return textResult(`${text}\n\n# Injection Usage\n${usageLines.join("\n")}`);
+            }
+            return textResult(text);
         },
     }));
     ctx.tools.register(defineTool({
@@ -154,6 +171,10 @@ function applyEditsText(engine, scope, sessionId, edits, agent) {
         : { scope });
     const applied = result.appliedEdits.filter((e) => e.applied);
     const failed = result.appliedEdits.filter((e) => !e.applied);
+    // Gap C4: emit structured evolve_complete event for third-party consumers.
+    if (applied.length > 0 && sessionId) {
+        emitEvolveComplete(engine.baseDir, buildEvolveCompleteEvent(result, "manual_tool", sessionId));
+    }
     const lines = [`refinement ${result.id}: ${applied.length} applied, ${failed.length} failed`];
     for (const e of applied) {
         lines.push(`- ${e.action} ${e.kind}:${e.id} (v${(e.after?.version ?? e.before?.version) ?? "?"})`);

package/lib/types.d.ts

@@ -124,6 +124,14 @@ export interface RefinementEdit {
     skill_kind?: SkillKind;
     metadata?: Record<string, unknown>;
     reason?: string;
+    /**
+     * Gap C2: blast-radius annotation — how broadly this edit applies.
+     * Values: "general" (cross-project tactical), "project" (single project),
+     * "session" (one-off session-specific). The review gate checks that
+     * local-scope edits are "session" or "project" and global-scope edits
+     * are "general" or "project".
+     */
+    blastRadius?: "general" | "project" | "session";
 }
 /** The structured output of a planning pass. */
 export interface RefinementProposal {

package/lib/usage.d.ts

@@ -0,0 +1,45 @@
+import type { HarnessState, RefinementKind } from "./types.js";
+export interface UsageStore {
+    /** Injection count per entry key (`kind:id`). */
+    counts: Record<string, number>;
+    /** Session dedup marker: the last session id each key was counted in (v2). */
+    lastSession?: Record<string, string>;
+}
+/**
+ * Load the usage store from disk; returns an empty store when absent or
+ * corrupt. Accepts BOTH on-disk shapes:
+ * - legacy (≤0.3.x): a flat `{ "kind:id": count }` map,
+ * - v2: `{ version: 2, counts, lastSession }` with per-session dedup.
+ */
+export declare function loadUsage(baseDir: string): UsageStore;
+/** Persist the usage store atomically (always the v2 shape). */
+export declare function saveUsage(baseDir: string, store: UsageStore): void;
+/** Build the usage key for an entry. */
+export declare function usageKey(kind: RefinementKind, id: string): string;
+/**
+ * Increment injection counts for the entries that were actually injected.
+ * Called after `entriesSectionText` renders the injected block. Keys not
+ * present in the store are initialized to 1.
+ *
+ * Session dedup (2026-08-22): with a sessionId, each key counts AT MOST
+ * ONCE per session — the old per-build counting produced meaningless
+ * numbers (one entry hit 2311× in a week) and hid the real "how many
+ * sessions found this useful" signal that staleness decay needs. Without
+ * a sessionId the call degrades to legacy always-increment behavior.
+ */
+export declare function recordInjection(baseDir: string, injectedKeys: readonly string[], sessionId?: string): void;
+/**
+ * Get the injection count for a specific entry. Returns 0 when the entry
+ * has never been injected (absent from the store).
+ */
+export declare function getUsageCount(store: UsageStore, kind: RefinementKind, id: string): number;
+/**
+ * Find entries with zero injection usage. Returns `{kind, id, title}` for
+ * each entry that has never been injected — prime candidates for archival.
+ */
+export declare function zeroUsageEntries(state: HarnessState, store: UsageStore): {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+}[];
+//# sourceMappingURL=usage.d.ts.map