dsh-continual-evolve 0.7.6 → 0.9.0

package/lib/recall.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Targeted memory recall (P1): the precise-reading counterpart of the cheap
+ * directory index.
+ *
+ * The injected directory view (`inject.ts`) shows one line per entry and the
+ * full `evolve_list` dumps whole stores; neither answers "give me everything
+ * about X". Recall fills that gap: filter by query/kind/scope/memory-type,
+ * rank with the same CJK BM25 machinery as injection, and return full
+ * content plus source, version, and staleness signals. Read-only — it never
+ * mutates a store.
+ */
+import type { EvolutionEngine } from "./service.js";
+import type { HarnessScope, RefinementKind } from "./types.js";
+/** Memory recall types (the `memoryType` taxonomy, not entry kinds). */
+export declare const RECALL_MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type RecallMemoryType = (typeof RECALL_MEMORY_TYPES)[number];
+/** Default and maximum hits returned per recall call. */
+export declare const DEFAULT_RECALL_LIMIT = 10;
+export declare const MAX_RECALL_LIMIT = 50;
+export interface RecallFilters {
+    /** Free-text relevance query; empty means "most recently updated first". */
+    query?: string;
+    /** Entry kinds to search; default is memory only. */
+    kinds?: RefinementKind[];
+    /** Stores to search; default is local + project + global. */
+    scopes?: HarnessScope[];
+    /** Memory-type filter (applies to memory entries only). */
+    memoryTypes?: RecallMemoryType[];
+    /** Maximum hits; clamped to 1..50, defaults to 10. */
+    limit?: number;
+    /** Include archived entries; default false. */
+    includeArchived?: boolean;
+}
+/** One recalled entry with full content and provenance. */
+export interface RecallHit {
+    scope: HarnessScope;
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    content: string;
+    path: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    archived: boolean;
+    /** Memory-type hook for memory entries; undefined for other kinds. */
+    memoryType?: string;
+    /** Conflict-hint stamp left by the promotion guard, when present. */
+    staleHint?: string;
+    /** Session the entry was distilled from, when recorded. */
+    sourceSession?: string;
+    /** Source user-message seqs, when recorded. */
+    sourceSeqs?: number[];
+}
+export interface RecallResult {
+    hits: RecallHit[];
+    /** Skipped scopes with reasons (read-path honesty: never silently drop a store). */
+    notes: string[];
+    /** Candidates seen before ranking/truncation. */
+    totalCandidates: number;
+}
+export interface RecallContext {
+    /** Live session id for the local store; absent → local is skipped with a note. */
+    sessionId?: string | undefined;
+    /** Resolved project key; absent → project is skipped with a note. */
+    projectKey?: string | undefined;
+}
+/**
+ * Search the harness stores with mechanical filters and BM25 ranking.
+ *
+ * @param engine The evolution engine (read-only use).
+ * @param context Store identities for the session-scoped stores.
+ * @param filters Query/kind/scope/type/limit/archive filters.
+ * @returns Ranked hits plus a note for every scope that could not be read.
+ * @throws On an unknown kind, scope, or memory type — fail loud instead of
+ *         silently narrowing the search.
+ */
+export declare function recallMemories(engine: EvolutionEngine, context: RecallContext, filters?: RecallFilters): RecallResult;
+/**
+ * Render recall hits for a model or human reader: full content, version,
+ * source, and staleness on every hit; skipped scopes are always shown so
+ * "no results" can never hide an unread store.
+ */
+export declare function formatRecallResult(result: RecallResult, query?: string): string;
+//# sourceMappingURL=recall.d.ts.map

package/lib/recall.js

@@ -0,0 +1,142 @@
+import { buildRelevanceIndex, relevanceScore } from "./search.js";
+import { CONFLICT_HINT_KEY } from "./types.js";
+import { isArchived, isMemoryType, ARCHIVED_AT_KEY, MEMORY_TYPE_KEY, SOURCE_SEQS_KEY, SOURCE_SESSION_KEY } from "./types.js";
+/** Memory recall types (the `memoryType` taxonomy, not entry kinds). */
+export const RECALL_MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+/** Entry kinds recall can filter on; memory is the default. */
+const RECALL_KINDS = ["prompt", "memory", "skill", "subagent"];
+/** Default and maximum hits returned per recall call. */
+export const DEFAULT_RECALL_LIMIT = 10;
+export const MAX_RECALL_LIMIT = 50;
+/**
+ * Search the harness stores with mechanical filters and BM25 ranking.
+ *
+ * @param engine The evolution engine (read-only use).
+ * @param context Store identities for the session-scoped stores.
+ * @param filters Query/kind/scope/type/limit/archive filters.
+ * @returns Ranked hits plus a note for every scope that could not be read.
+ * @throws On an unknown kind, scope, or memory type — fail loud instead of
+ *         silently narrowing the search.
+ */
+export function recallMemories(engine, context, filters = {}) {
+    const kinds = filters.kinds ?? ["memory"];
+    for (const kind of kinds) {
+        if (!RECALL_KINDS.includes(kind)) {
+            throw new Error(`evolve_recall: unknown kind "${kind}" (expected one of ${RECALL_KINDS.join(", ")})`);
+        }
+    }
+    const scopes = filters.scopes ?? ["local", "project", "global"];
+    for (const scope of scopes) {
+        if (scope !== "local" && scope !== "project" && scope !== "global") {
+            throw new Error(`evolve_recall: unknown scope "${scope}" (expected local, project, or global)`);
+        }
+    }
+    const memoryTypes = filters.memoryTypes ?? [];
+    for (const memoryType of memoryTypes) {
+        if (!RECALL_MEMORY_TYPES.includes(memoryType)) {
+            throw new Error(`evolve_recall: unknown memoryType "${memoryType}" (expected one of ${RECALL_MEMORY_TYPES.join(", ")})`);
+        }
+    }
+    const limit = typeof filters.limit === "number" && Number.isFinite(filters.limit) && filters.limit > 0
+        ? Math.min(Math.floor(filters.limit), MAX_RECALL_LIMIT)
+        : DEFAULT_RECALL_LIMIT;
+    const query = filters.query?.trim() ?? "";
+    const candidates = [];
+    const notes = [];
+    for (const scope of scopes) {
+        const storeId = scope === "local" ? context.sessionId : scope === "project" ? context.projectKey : undefined;
+        if (scope !== "global" && storeId === undefined) {
+            notes.push(`${scope} store skipped: ${scope === "local" ? "no live session id" : "no project key for this session"}`);
+            continue;
+        }
+        let state;
+        try {
+            state = engine.load(scope, storeId);
+        }
+        catch (cause) {
+            notes.push(`${scope} store unreadable: ${cause instanceof Error ? cause.message : String(cause)}`);
+            continue;
+        }
+        for (const kind of kinds) {
+            for (const entry of Object.values(state.entries[kind])) {
+                if (!filters.includeArchived && isArchived(entry))
+                    continue;
+                if (kind === "memory" && memoryTypes.length > 0) {
+                    const type = entry.metadata[MEMORY_TYPE_KEY];
+                    if (typeof type !== "string" || !memoryTypes.includes(type))
+                        continue;
+                }
+                candidates.push(entry);
+            }
+        }
+    }
+    const ranked = query.length > 0 ? rankByRelevance(candidates, query) : [...candidates].sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+    return { hits: ranked.slice(0, limit).map(toRecallHit), notes, totalCandidates: candidates.length };
+}
+function rankByRelevance(candidates, query) {
+    const index = buildRelevanceIndex(candidates);
+    const normalized = query.trim().toLowerCase();
+    return candidates
+        .map((entry) => {
+        let score = relevanceScore(index, entry, query);
+        // Exact scope:id addressing wins over fuzzy relevance (the
+        // memory-agent manifest search precedent).
+        if (`${entry.scope}:${entry.id}`.toLowerCase() === normalized)
+            score += 1000;
+        return { entry, score };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => b.score - a.score || (a.entry.updated_at < b.entry.updated_at ? 1 : -1))
+        .map((hit) => hit.entry);
+}
+function toRecallHit(entry) {
+    const memoryType = entry.kind === "memory" && isMemoryType(entry.metadata[MEMORY_TYPE_KEY])
+        ? String(entry.metadata[MEMORY_TYPE_KEY])
+        : undefined;
+    const staleHint = typeof entry.metadata[CONFLICT_HINT_KEY] === "string" && entry.metadata[CONFLICT_HINT_KEY].length > 0
+        ? String(entry.metadata[CONFLICT_HINT_KEY])
+        : undefined;
+    const sourceSession = typeof entry.metadata[SOURCE_SESSION_KEY] === "string" ? String(entry.metadata[SOURCE_SESSION_KEY]) : undefined;
+    const rawSeqs = entry.metadata[SOURCE_SEQS_KEY];
+    const sourceSeqs = Array.isArray(rawSeqs) && rawSeqs.every((seq) => typeof seq === "number") ? rawSeqs : undefined;
+    return {
+        scope: entry.scope,
+        kind: entry.kind,
+        id: entry.id,
+        title: entry.title,
+        content: entry.content,
+        path: entry.path,
+        version: entry.version,
+        createdAt: entry.created_at,
+        updatedAt: entry.updated_at,
+        archived: isArchived(entry),
+        ...(memoryType !== undefined ? { memoryType } : {}),
+        ...(staleHint !== undefined ? { staleHint } : {}),
+        ...(sourceSession !== undefined ? { sourceSession } : {}),
+        ...(sourceSeqs !== undefined ? { sourceSeqs } : {}),
+    };
+}
+/**
+ * Render recall hits for a model or human reader: full content, version,
+ * source, and staleness on every hit; skipped scopes are always shown so
+ * "no results" can never hide an unread store.
+ */
+export function formatRecallResult(result, query) {
+    const lines = [`recall: ${result.hits.length} hit(s)${query?.trim() ? ` for "${query.trim()}"` : ""} (${result.totalCandidates} candidate(s))`];
+    for (const hit of result.hits) {
+        const type = hit.memoryType !== undefined ? ` · type=${hit.memoryType}` : "";
+        const archived = hit.archived ? " · archived" : "";
+        const stale = hit.staleHint !== undefined ? ` · conflict-hint=${hit.staleHint}` : "";
+        const source = hit.sourceSession !== undefined ? ` · src=${hit.sourceSession}${hit.sourceSeqs ? `:${hit.sourceSeqs.join(",")}` : ""}` : "";
+        lines.push(`- [${hit.scope}:${hit.kind}:${hit.id}] ${hit.title} (v${hit.version}${type}${archived}${stale}${source})`);
+        lines.push(`  ${hit.content}`);
+    }
+    for (const note of result.notes) {
+        lines.push(`note: ${note}`);
+    }
+    if (result.hits.length === 0) {
+        lines.push(`(${ARCHIVED_AT_KEY} entries are hidden unless includeArchived is set)`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=recall.js.map

package/lib/review-scheduler.js

@@ -68,10 +68,9 @@ export function createReviewScheduler(execute, cursorOf) {
                         bestCursor = candidate;
                     }
                 }
-                if (bestIndex < 0) {
-                    pending.length = 0;
-                    return undefined;
-                }
+                // bestIndex is always set here: the error purge above leaves only
+                // acquired snapshots in `settled` (SnapshotAcquisition has exactly
+                // two variants), so the first settled entry takes the slot.
                 const chosen = pending[bestIndex];
                 pending.splice(bestIndex, 1);
                 for (let index = pending.length - 1; index >= 0; index -= 1) {

package/lib/review.d.ts

@@ -44,7 +44,7 @@ export interface ReviewOptions {
     /** Direct-call token ledger destination; the review phase is fixed by this module. */
     tokenUsage?: TokenUsageTarget;
 }
-export declare const AUTO_REVIEW_SYSTEM_PROMPT = "You are the automatic /evolve review gate.\n\nDecide whether this checkpoint should continue the non-memory /evolve path.\nA dedicated memory extraction agent has already processed the same snapshot\nwith a frozen memory manifest, so do NOT approve solely to create, update,\narchive, or delete a memory entry. Decline with a rationale that the memory\nphase owns that evidence. For the remaining kinds, approve repeated failures,\nreusable tactics, repeated delegation roles, or narrow behavioral policies.\n\nThe current harness state below includes GLOBAL entries (scope=global) plus\nthis session's local entries (scope=local). When a topic is already covered\nby a global entry, do NOT approve a local duplicate of it \u2014 decline and say\nin the rationale that the topic is already covered globally.\n\nReject one-off noise, unsupported hypotheses, transient tool outputs, and\nrequests that carry no reusable content.\n\nStale local entries (superseded, long-unused, obsolete facts) are a valid\nrefine target: approve with instructions naming the entry ids, and tell the\nplanner to archive them (archive hides from injection, data stays restorable)\nrather than delete.\n\nSkill-related trajectories (the evidence concerns creating or improving a\nskill entry) are judged against the DSH skill quality standard (skill-audit\ndimensions: frontmatter routing, the 7 structural features, paragraph\nskeleton, no duplication of the official 11 skills or covered skills).\nApprove only when the trajectory shows a REAL trigger scenario and the\nresulting skill would meet the standard; otherwise decline and say in the\nrationale what must improve \u2014 drafting follows skill-creator, and the\nplanner receives the standard as its <skill_quality_standard> block.\n\nRepeated multi-step workflows (session start/end routines, recurring\nwrap-up or handoff procedures) are a valid refine target: approve with\ninstructions telling the planner to propose a guidance skill (kind=skill,\nskill_kind=guidance \u2014 a SKILL.md document, no python reference). Only\npropose when the same workflow recurs in the trajectory \u2014 never for\none-off flows. Auto-created skills are always offered to the user for a\ndecision before they land; the gate never writes a skill silently.\n\nReturn JSON only:\n{\n  \"shouldRefine\": true|false,\n  \"rationale\": \"short reason\",\n  \"instructions\": \"optional concise instructions for /evolve if shouldRefine is true\"\n}";
+export declare const AUTO_REVIEW_SYSTEM_PROMPT = "You are the automatic /evolve review gate.\n\nDecide whether this checkpoint should continue the non-memory /evolve path.\nA dedicated memory extraction agent has already processed the same snapshot\nwith a frozen memory manifest, so do NOT approve solely to create, update,\narchive, or delete a memory entry. Decline with a rationale that the memory\nphase owns that evidence. For the remaining kinds, approve ONLY when the\ntrajectory shows repeated evidence: the same failure, tactic, delegation\nrole, or behavioral policy recurs at least twice across turns. A single\none-off interaction defaults to decline no matter how useful it looks for\nfuture turns \u2014 one data point is never enough to generalize. When approving,\ncite the repeated spans in the instructions so the planner can ground its\nedits.\n\nThe current harness state below includes GLOBAL entries (scope=global) plus\nthis session's local entries (scope=local). When a topic is already covered\nby a global entry, do NOT approve a local duplicate of it \u2014 decline and say\nin the rationale that the topic is already covered globally.\n\nReject one-off noise, unsupported hypotheses, transient tool outputs, and\nrequests that carry no reusable content.\n\nStale local entries (superseded, long-unused, obsolete facts) are a valid\nrefine target: approve with instructions naming the entry ids, and tell the\nplanner to archive them (archive hides from injection, data stays restorable)\nrather than delete.\n\nSkill-related trajectories (the evidence concerns creating or improving a\nskill entry) are judged against the DSH skill quality standard (skill-audit\ndimensions: frontmatter routing, the 7 structural features, paragraph\nskeleton, no duplication of the official 11 skills or covered skills).\nApprove only when the trajectory shows a REAL trigger scenario and the\nresulting skill would meet the standard; otherwise decline and say in the\nrationale what must improve \u2014 drafting follows skill-creator, and the\nplanner receives the standard as its <skill_quality_standard> block.\n\nRepeated multi-step workflows (session start/end routines, recurring\nwrap-up or handoff procedures) are a valid refine target: approve with\ninstructions telling the planner to propose a guidance skill (kind=skill,\nskill_kind=guidance \u2014 a SKILL.md document, no python reference). Only\npropose when the same workflow recurs in the trajectory \u2014 never for\none-off flows. Auto-created skills are always offered to the user for a\ndecision before they land; the gate never writes a skill silently.\n\nReturn JSON only:\n{\n  \"shouldRefine\": true|false,\n  \"rationale\": \"short reason\",\n  \"instructions\": \"optional concise instructions for /evolve if shouldRefine is true\"\n}";
 /** Parse the gate's JSON reply. */
 export declare function parseAutoRefineReview(text: string): AutoRefineReview;
 /** Serialize surface events to bounded role-prefixed text. */

package/lib/review.js

@@ -10,8 +10,13 @@ Decide whether this checkpoint should continue the non-memory /evolve path.
 A dedicated memory extraction agent has already processed the same snapshot
 with a frozen memory manifest, so do NOT approve solely to create, update,
 archive, or delete a memory entry. Decline with a rationale that the memory
-phase owns that evidence. For the remaining kinds, approve repeated failures,
-reusable tactics, repeated delegation roles, or narrow behavioral policies.
+phase owns that evidence. For the remaining kinds, approve ONLY when the
+trajectory shows repeated evidence: the same failure, tactic, delegation
+role, or behavioral policy recurs at least twice across turns. A single
+one-off interaction defaults to decline no matter how useful it looks for
+future turns — one data point is never enough to generalize. When approving,
+cite the repeated spans in the instructions so the planner can ground its
+edits.
 
 The current harness state below includes GLOBAL entries (scope=global) plus
 this session's local entries (scope=local). When a topic is already covered
@@ -119,7 +124,7 @@ export async function reviewAutoRefine(ctx, options) {
         `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
         `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
         conversationBlock,
-        "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.",
+        "Return shouldRefine=true only when the trajectory shows repeated evidence (>=2 occurrences) useful to this session's future turns. A single one-off interaction defaults to shouldRefine=false. Prefer local edits; do not ask for global refinement here.",
     ]
         .filter(Boolean)
         .join("\n\n");

package/lib/service.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, pruneJsonlFile, pruneSnapshots, resolveHistoryRetention, snapshotBefore, storePaths } from "./store.js";
+import { materializeMemoryProjection } from "./projection.js";
 import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry, secretLeakReason } from "./promotion.js";
 /** A post-commit apply failure that still carries the durable applied result. */
 export class EvolutionApplyPostCommitError extends Error {
@@ -137,6 +138,19 @@ export function createEvolutionEngine(baseDir, hooks = {}, opts = {}) {
         catch {
             // ignored — the next apply retries
         }
+        // Readable Markdown projection (P1): rewritten from the post-apply
+        // state whenever a memory edit landed, so rollback and archive stay
+        // in sync through this same apply path. The model has no writer for
+        // these files — only this engine entry point materializes them.
+        if (result.appliedEdits.some((edit) => edit.applied && edit.kind === "memory")) {
+            try {
+                materializeMemoryProjection(paths.stateDir, state);
+            }
+            catch {
+                // ignored — the projection is derived (JSON stays the source
+                // of truth) and the next memory apply retries
+            }
+        }
         try {
             hooks.onApplied?.(result);
         }

package/lib/skill-render.js

@@ -57,7 +57,8 @@ export function renderSkillMarkdown(entry) {
             lines.push(`- ${key}: ${JSON.stringify(value)}`);
         }
     }
-    if (Object.keys(entry.arguments).length > 0) {
+    const args = entry.arguments;
+    if (args && typeof args === "object" && Object.keys(args).length > 0) {
         lines.push("", "## Arguments", "```json", JSON.stringify(entry.arguments, null, 2), "```");
     }
     return `${lines.join("\n").trimEnd()}\n`;

package/lib/skillquality.d.ts

@@ -54,8 +54,11 @@ export declare function validateRenderedSkillMarkdown(markdown: string): string[
  *   parsed instead of the generated one (the platform reads the FIRST
  *   closing `---`), so the file could be ignored or routed wrongly;
  * - resource references (`references/…`, `scripts/…`) must be skill-local
- *   relative paths — parent-relative (`../`) or absolute targets escape the
- *   skill directory and are rejected.
+ *   relative paths — an embedded `/../` after the category escapes the skill
+ *   directory and is rejected. A leading `../` instead addresses a sibling
+ *   skill (cross-skill interlink, e.g. `../skill-creator/…`) and is allowed:
+ *   it is not dangling-checked since cross-skill targets live outside this
+ *   entry's shipped files (see skillResourceRefs).
  * Returns human-readable problems; an empty array means the content is
  * mechanically acceptable.
  */
@@ -73,6 +76,8 @@ export declare function validateRenderedSkill(entry: HarnessEntry): string[];
  * targets starting with the category, plus backticked/prose paths carrying
  * a filename extension. Used after materialization to warn about dangling
  * references (a body referencing a resource the entry never ships).
+ * Leading-`../` cross-skill interlinks are skipped, not warned: they resolve
+ * against sibling skill directories, never against shipped files.
  */
 export declare function skillResourceRefs(content: string): string[];
 /** Kebab-case name under which the entry materializes (exported for diagnostics). */

package/lib/skillquality.js

@@ -244,8 +244,11 @@ export function validateRenderedSkillMarkdown(markdown) {
  *   parsed instead of the generated one (the platform reads the FIRST
  *   closing `---`), so the file could be ignored or routed wrongly;
  * - resource references (`references/…`, `scripts/…`) must be skill-local
- *   relative paths — parent-relative (`../`) or absolute targets escape the
- *   skill directory and are rejected.
+ *   relative paths — an embedded `/../` after the category escapes the skill
+ *   directory and is rejected. A leading `../` instead addresses a sibling
+ *   skill (cross-skill interlink, e.g. `../skill-creator/…`) and is allowed:
+ *   it is not dangling-checked since cross-skill targets live outside this
+ *   entry's shipped files (see skillResourceRefs).
  * Returns human-readable problems; an empty array means the content is
  * mechanically acceptable.
  */
@@ -260,8 +263,12 @@ export function validateSkillEntryContent(content) {
         problems.push("skill content must not start with a `---` frontmatter block (the materializer generates frontmatter from id/title; a body-level `---` would shadow it and the platform could IGNORE the file)");
     }
     for (const match of trimmed.matchAll(/(?<![\w])(references|scripts)\/[^\s)]+/g)) {
+        // match[0] always starts with `references/` or `scripts/` (the regex
+        // anchors it there), so only an embedded `/../` can escape the skill
+        // directory — the ../-prefix, absolute-path, and drive-letter
+        // spellings can never match and are intentionally not checked.
         const ref = match[0] ?? "";
-        if (ref.startsWith("../") || ref.includes("/../") || ref.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(ref)) {
+        if (ref.includes("/../")) {
             problems.push(`skill content resource reference escapes the skill directory: ${ref}`);
         }
     }
@@ -282,6 +289,8 @@ export function validateRenderedSkill(entry) {
  * targets starting with the category, plus backticked/prose paths carrying
  * a filename extension. Used after materialization to warn about dangling
  * references (a body referencing a resource the entry never ships).
+ * Leading-`../` cross-skill interlinks are skipped, not warned: they resolve
+ * against sibling skill directories, never against shipped files.
  */
 export function skillResourceRefs(content) {
     const refs = new Set();

package/lib/tool.js

@@ -5,6 +5,7 @@ import { formatHarnessStateForPrompt } from "./render.js";
 import { requireGlobalApproval } from "./approval.js";
 import { CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./promotion.js";
 import { entrySourceOf } from "./source.js";
+import { formatRecallResult, recallMemories } from "./recall.js";
 import { getUsageCount, loadUsage } from "./usage.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
 import { DEFAULT_REVIEWS_RETAIN } from "./store.js";
@@ -115,6 +116,45 @@ export function registerEvolveTools(ctx, engine, opts) {
             return textResult(text);
         },
     }));
+    ctx.tools.register(defineTool({
+        name: "evolve_recall",
+        description: "Targeted recall over the harness stores: filter memories (or other kinds) by query, kind, scope, and memory type, and read back full content with version, source, and staleness signals. Read-only — it never mutates a store. Prefer this over evolve_list when looking for something specific.",
+        parameters: {
+            query: { type: "string", description: "Free-text relevance query. Empty means most-recently-updated first." },
+            kinds: {
+                type: "array",
+                items: { type: "string" },
+                description: "Entry kinds to search (default memory only).",
+            },
+            scopes: {
+                type: "array",
+                items: { type: "string" },
+                description: "Stores to search (default local, project, and global).",
+            },
+            memoryTypes: {
+                type: "array",
+                items: { type: "string" },
+                description: "Memory-type filter: user, feedback, project, reference (memory entries only).",
+            },
+            limit: { type: "number", description: "Maximum hits (default 10, at most 50)." },
+            includeArchived: { type: "boolean", description: "Include archived entries (default false)." },
+        },
+        output: {
+            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        execute: async (args, exec) => {
+            const result = recallMemories(engine, { sessionId: sessionIdOf(exec), projectKey: projectKeyOf(exec.agent) ?? undefined }, {
+                ...(typeof args.query === "string" ? { query: args.query } : {}),
+                ...(Array.isArray(args.kinds) ? { kinds: args.kinds } : {}),
+                ...(Array.isArray(args.scopes) ? { scopes: args.scopes } : {}),
+                ...(Array.isArray(args.memoryTypes) ? { memoryTypes: args.memoryTypes } : {}),
+                ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+                ...(typeof args.includeArchived === "boolean" ? { includeArchived: args.includeArchived } : {}),
+            });
+            return textResult(formatRecallResult(result, typeof args.query === "string" ? args.query : undefined));
+        },
+    }));
     ctx.tools.register(defineTool({
         name: "evolve_add",
         description: "Create one harness entry (prompt/memory/skill/subagent). Executable skills require reference {type:python, import, callable} and an arguments contract; guidance skills (skill_kind=guidance) are SKILL.md documents — recurring multi-step workflows — and must NOT carry a reference. Snapshot, version, and history are handled automatically.",

package/lib/types.d.ts

@@ -1,13 +1,3 @@
-/**
- * Type model for the continual-evolution harness state.
- *
- * Design provenance: the state model follows the continual-harness design
- * validated in prime-agent's `/refine` subsystem (MIT): versioned entries
- * keyed by kind, an append-only refinement history carrying an evidence
- * trail, atomic persistence, and deterministic inverse-op rollback. The
- * code here is an original implementation, written for the DeepSeek Harness
- * plugin surface.
- */
 /** What a harness entry can be. */
 export type RefinementKind = "prompt" | "memory" | "skill" | "subagent";
 /**
@@ -201,7 +191,15 @@ export interface PythonReference {
     callable?: string;
     call_pattern?: string;
 }
-/** A stable id derived from a title. */
+/**
+ * A stable id derived from a title: ASCII runs become snake_case (unchanged
+ * legacy behavior). Titles with no ASCII content at all (e.g. pure Chinese)
+ * used to collapse onto the bare fallback, so distinct memories shared one
+ * id and every later create failed as "already exists". They now take
+ * `<fallback>_<sha256-8>` instead: distinct titles get distinct ids while
+ * identical titles still dedupe onto the same id. The fallback itself is
+ * assumed id-safe (callers pass entry kinds).
+ */
 export declare function slug(raw: string, fallback: string): string;
 /** Fresh empty state with the current schema version. */
 export declare function emptyHarnessState(): HarnessState;

package/lib/types.js

@@ -8,6 +8,7 @@
  * code here is an original implementation, written for the DeepSeek Harness
  * plugin surface.
  */
+import { createHash } from "node:crypto";
 /**
  * Memory-entry shape discipline (one fact per entry, typed like ZCode's
  * memory frontmatter): every `memory` create must stamp one of these in
@@ -85,7 +86,15 @@ export function isArchived(entry) {
     const value = entry.metadata[ARCHIVED_AT_KEY];
     return typeof value === "string" && value.length > 0;
 }
-/** A stable id derived from a title. */
+/**
+ * A stable id derived from a title: ASCII runs become snake_case (unchanged
+ * legacy behavior). Titles with no ASCII content at all (e.g. pure Chinese)
+ * used to collapse onto the bare fallback, so distinct memories shared one
+ * id and every later create failed as "already exists". They now take
+ * `<fallback>_<sha256-8>` instead: distinct titles get distinct ids while
+ * identical titles still dedupe onto the same id. The fallback itself is
+ * assumed id-safe (callers pass entry kinds).
+ */
 export function slug(raw, fallback) {
     const normalized = raw
         .trim()
@@ -93,7 +102,10 @@ export function slug(raw, fallback) {
         .replace(/[^a-z0-9]+/g, "_")
         .replace(/^_+|_+$/g, "")
         .slice(0, 80);
-    return normalized || fallback;
+    if (normalized)
+        return normalized;
+    const digest = createHash("sha256").update(raw, "utf8").digest("hex").slice(0, 8);
+    return `${fallback}_${digest}`;
 }
 /** Fresh empty state with the current schema version. */
 export function emptyHarnessState() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-continual-evolve",
-  "version": "0.7.6",
+  "version": "0.9.0",
   "description": "Continual self-evolution plugin for DeepSeek Harness: versioned, auditable, rollback-safe harness state (prompt notes, memories, skills, subagent specs) refined from session trajectories.",
   "license": "MIT",
   "repository": {
@@ -48,12 +48,15 @@
     "build": "tsc -p tsconfig.json",
     "prepare": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "coverage:gaps": "tsx scripts/coverage-gaps.ts",
     "test:watch": "vitest",
     "lint": "oxlint src test",
-    "clean": "rm -rf lib"
+    "clean": "rm -rf lib",
+    "check:docs": "tsx scripts/run-gates.ts docs",
+    "check:governance": "tsx scripts/verify-governance.ts"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -73,6 +76,7 @@
     "@types/node": "^22.10.0",
     "@vitest/coverage-v8": "^3.2.0",
     "oxlint": "^0.16.0",
+    "tsx": "^4.23.15",
     "typescript": "^5.9.0",
     "vitest": "^3.2.0"
   }