dsh-continual-evolve 0.6.0 → 0.7.0

package/lib/inject.d.ts

@@ -52,13 +52,26 @@ export interface AgentLike {
             parentSession?: string;
         };
         /**
-         * Live append-only session log. Typed loosely (`unknown[]`) so the real
-         * `SessionEvent[]` union from dsh-session is assignable; rows are
-         * narrowed to {@link UserMessageEventLike} at read time.
+         * Live append-only session log as the public `session.events` getter.
+         * Typed loosely (`unknown[]`) so the real `SessionEvent[]` union from
+         * dsh-session is assignable; rows are narrowed to
+         * {@link UserMessageEventLike} at read time.
          */
         events?: readonly unknown[];
+        /**
+         * Full-log snapshot reader that answers the same rows in the same order
+         * where the `events` getter is absent. Called with no arguments for the
+         * whole log, which is the read {@link sessionEventsOf} needs.
+         */
+        snapshotEvents?: () => readonly unknown[];
     };
 }
+/**
+ * The session's event log through whichever reader the running harness
+ * generation exposes. Returns [] when neither is present, so every caller
+ * degrades to its empty-log path rather than throwing.
+ */
+export declare function sessionEventsOf(agent: AgentLike | undefined): readonly unknown[];
 /** The section-provider context shape we consume (subset of AssembleContext). */
 export interface InjectContext {
     agent?: AgentLike;
@@ -101,20 +114,42 @@ export declare function formatPromptEntriesSection(entries: readonly HarnessEntr
 export declare function formatSubagentSpecsSection(entries: readonly HarnessEntry[], query?: string): string;
 /**
  * Gap B3: a lightweight directory of ALL non-archived entries across all
- * kinds — one line per entry (`- [kind:id] title`), no content. This gives
- * the model a zero-cost overview of what exists so it can ask for full text
- * via `evolve_list` or `/evolve list`. The directory is appended after the
- * curated top-N injection sections and adds minimal tokens.
+ * kinds — one line per entry, no content. Memory lines carry their recall
+ * type (`- [memory:feedback:id] title`) so the model can judge relevance
+ * from the index alone. This gives the model a zero-cost overview of what
+ * exists so it can ask for full text via `evolve_list` or `/evolve list`.
+ * The directory is appended after the curated top-N injection sections and
+ * adds minimal tokens.
  *
  * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
- * lines (oldest-sorted stable order) with the remainder folded into a single
- * counter line — an uncapped directory across a polluted global store was
- * measured at ~2K chars of every build in every project.
+ * lines with the remainder folded into a single counter line — an uncapped
+ * directory across a polluted global store was measured at ~2K chars of
+ * every build in every project.
+ *
+ * 2026-09-23 relevance order: the directory is sorted by
+ * {@link rankEntries} against the assembly's relevance query, so the lines
+ * folded below the cap are the least relevant — not the dictionary tail.
  */
 export declare const DEFAULT_DIRECTORY_LINES = 15;
+/** One directory index line: memory lines carry their recall-type hook. */
+export declare function directoryLine(entry: HarnessEntry): string;
 export declare function formatEntriesDirectory(...kindEntries: readonly HarnessEntry[][]): string;
 /** {@link formatEntriesDirectory} with an explicit cap (configurable). */
 export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * {@link formatEntriesDirectoryCapped} with a relevance query: entries are
+ * ordered by {@link rankEntries} (relevance first, then recency) so the cap
+ * folds the least relevant entries — never the dictionary tail. An empty
+ * query degrades to the valence/recency/stable order, still deterministic.
+ */
+export declare function formatEntriesDirectoryRanked(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * The directory entries actually shown under the cap, in display order —
+ * the single source for both the rendered text and usage accounting (so a
+ * memory's injection IS its directory line even with the `:type` hook).
+ * Returns [] when the directory is suppressed or empty.
+ */
+export declare function rankedDirectoryEntries(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): HarnessEntry[];
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
  * session whose local store is non-empty, if any. Children inherit their
@@ -125,19 +160,23 @@ export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEn
 export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, agent: AgentLike): HarnessState | undefined;
 /**
  * Compose the full injected block for one assembling agent: global entries
- * merged with the nearest carrying local store (local wins on id collision).
+ * merged with this project's store (when the session cwd resolves one) and
+ * the nearest carrying local store (precedence global < project < local).
  * The optional `query` — when absent, derived from the agent's most recent
  * direct user messages — ranks which entries fill the per-kind cap
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
  *
- * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle);
+ * `opts.projectKey` pins the project layer explicitly (tests, tools) —
+ * otherwise it is derived from the agent's session cwd, best-effort.
  * Usage recording covers ALL kinds — memories and skills appear as directory
  * lines, prompts/subagents as content — and is deduped per session so the
  * counts read "how many sessions saw this", not "how many prompt builds".
  */
 export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string, opts?: {
     directoryLines?: number;
+    projectKey?: string;
 }): string;
 //# sourceMappingURL=inject.d.ts.map

package/lib/inject.js

@@ -1,5 +1,6 @@
-import { isArchived, VALENCE_NEGATIVE_KEY } from "./types.js";
+import { MEMORY_TYPE_KEY, isArchived, isMemoryType, VALENCE_NEGATIVE_KEY } from "./types.js";
 import { mergeHarnessStates } from "./state.js";
+import { projectKeyOf } from "./project.js";
 import { entryLine } from "./render.js";
 import { recordInjection } from "./usage.js";
 import { buildRelevanceIndex, relevanceScore, tokenize } from "./search.js";
@@ -17,6 +18,22 @@ export const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
 export const MAX_QUERY_MESSAGES = 3;
 /** Query text handed to the relevance scorer is capped at this many chars. */
 export const MAX_QUERY_CHARS = 400;
+/**
+ * The session's event log through whichever reader the running harness
+ * generation exposes. Returns [] when neither is present, so every caller
+ * degrades to its empty-log path rather than throwing.
+ */
+export function sessionEventsOf(agent) {
+    const session = agent?.session;
+    if (session === undefined) {
+        return [];
+    }
+    if (Array.isArray(session.events)) {
+        return session.events;
+    }
+    const snapshot = session.snapshotEvents?.();
+    return Array.isArray(snapshot) ? snapshot : [];
+}
 /** Stable dictionary-order tiebreak used when two entries score equally. */
 function stableCompare(a, b) {
     return [a.path, a.title, a.id].join("\0").localeCompare([b.path, b.title, b.id].join("\0"));
@@ -131,8 +148,8 @@ function extractBlockText(content) {
  * falls back to pure recency.
  */
 export function recentUserText(agent, opts) {
-    const events = agent?.session?.events;
-    if (!events || events.length === 0) {
+    const events = sessionEventsOf(agent);
+    if (events.length === 0) {
         return "";
     }
     const maxMessages = opts?.maxMessages ?? MAX_QUERY_MESSAGES;
@@ -198,27 +215,81 @@ export function formatSubagentSpecsSection(entries, query) {
 }
 /**
  * Gap B3: a lightweight directory of ALL non-archived entries across all
- * kinds — one line per entry (`- [kind:id] title`), no content. This gives
- * the model a zero-cost overview of what exists so it can ask for full text
- * via `evolve_list` or `/evolve list`. The directory is appended after the
- * curated top-N injection sections and adds minimal tokens.
+ * kinds — one line per entry, no content. Memory lines carry their recall
+ * type (`- [memory:feedback:id] title`) so the model can judge relevance
+ * from the index alone. This gives the model a zero-cost overview of what
+ * exists so it can ask for full text via `evolve_list` or `/evolve list`.
+ * The directory is appended after the curated top-N injection sections and
+ * adds minimal tokens.
  *
  * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
- * lines (oldest-sorted stable order) with the remainder folded into a single
- * counter line — an uncapped directory across a polluted global store was
- * measured at ~2K chars of every build in every project.
+ * lines with the remainder folded into a single counter line — an uncapped
+ * directory across a polluted global store was measured at ~2K chars of
+ * every build in every project.
+ *
+ * 2026-09-23 relevance order: the directory is sorted by
+ * {@link rankEntries} against the assembly's relevance query, so the lines
+ * folded below the cap are the least relevant — not the dictionary tail.
  */
 export const DEFAULT_DIRECTORY_LINES = 15;
-/** How many of the variadic arrays are content-section kinds (prompt, subagent). */
+/** One directory index line: memory lines carry their recall-type hook. */
+export function directoryLine(entry) {
+    if (entry.kind === "memory") {
+        const type = entry.metadata[MEMORY_TYPE_KEY];
+        const hook = isMemoryType(type) ? `:${type}` : "";
+        return `- [memory${hook}:${entry.id}] ${entry.title}`;
+    }
+    return `- [${entry.kind}:${entry.id}] ${entry.title}`;
+}
+/** Positional contract for the directory variadics: the first two arrays
+ * must be the content-section kinds (prompt, subagent) — the redundancy
+ * check counts exactly those as already visible. Callers pass
+ * (prompt, subagent, memory, skill); any other order miscounts. */
 const CONTENT_SECTION_KINDS = 2;
 export function formatEntriesDirectory(...kindEntries) {
     return formatEntriesDirectoryCapped(DEFAULT_DIRECTORY_LINES, ...kindEntries);
 }
 /** {@link formatEntriesDirectory} with an explicit cap (configurable). */
 export function formatEntriesDirectoryCapped(maxLines, ...kindEntries) {
+    return formatEntriesDirectoryRanked(maxLines, undefined, ...kindEntries);
+}
+/**
+ * {@link formatEntriesDirectoryCapped} with a relevance query: entries are
+ * ordered by {@link rankEntries} (relevance first, then recency) so the cap
+ * folds the least relevant entries — never the dictionary tail. An empty
+ * query degrades to the valence/recency/stable order, still deterministic.
+ */
+export function formatEntriesDirectoryRanked(maxLines, query, ...kindEntries) {
+    const total = kindEntries.flat().filter((e) => !isArchived(e)).length;
+    if (total === 0) {
+        return "";
+    }
+    // Suppressed (every entry already content-visible) renders as "" — the
+    // prompt renderer then drops the section entirely.
+    const shown = rankedDirectoryEntries(maxLines, query, ...kindEntries);
+    if (shown.length === 0) {
+        return "";
+    }
+    const lines = ["# Continual Harness — Entry Directory", "All entries (use evolve_list for full text of any entry):"];
+    for (const entry of shown) {
+        lines.push(directoryLine(entry));
+    }
+    const hidden = total - shown.length;
+    if (hidden > 0) {
+        lines.push(`- …and ${hidden} more entries (evolve_list for the full index)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The directory entries actually shown under the cap, in display order —
+ * the single source for both the rendered text and usage accounting (so a
+ * memory's injection IS its directory line even with the `:type` hook).
+ * Returns [] when the directory is suppressed or empty.
+ */
+export function rankedDirectoryEntries(maxLines, query, ...kindEntries) {
     const allEntries = kindEntries.flat().filter((e) => !isArchived(e));
     if (allEntries.length === 0) {
-        return "";
+        return [];
     }
     // Skip the directory only when EVERY entry is already content-visible.
     // Only the first two arrays (prompt, subagent) have curated sections —
@@ -229,19 +300,9 @@ export function formatEntriesDirectoryCapped(maxLines, ...kindEntries) {
         .slice(0, CONTENT_SECTION_KINDS)
         .reduce((sum, entries) => sum + Math.min(entries.filter((e) => !isArchived(e)).length, MAX_INJECTED_ENTRIES_PER_KIND), 0);
     if (allEntries.length <= contentVisible) {
-        return "";
+        return [];
     }
-    const sorted = [...allEntries].sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
-    const lines = ["# Continual Harness — Entry Directory", "All entries (use evolve_list for full text of any entry):"];
-    const shown = sorted.slice(0, Math.max(maxLines, 1));
-    for (const entry of shown) {
-        lines.push(`- [${entry.kind}:${entry.id}] ${entry.title}`);
-    }
-    const hidden = sorted.length - shown.length;
-    if (hidden > 0) {
-        lines.push(`- …and ${hidden} more entries (evolve_list for the full index)`);
-    }
-    return lines.join("\n");
+    return rankEntries(allEntries, query).slice(0, Math.max(maxLines, 1));
 }
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
@@ -265,14 +326,17 @@ export function nearestLocalStateWithEntries(engine, agent) {
 }
 /**
  * Compose the full injected block for one assembling agent: global entries
- * merged with the nearest carrying local store (local wins on id collision).
+ * merged with this project's store (when the session cwd resolves one) and
+ * the nearest carrying local store (precedence global < project < local).
  * The optional `query` — when absent, derived from the agent's most recent
  * direct user messages — ranks which entries fill the per-kind cap
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
  *
- * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle);
+ * `opts.projectKey` pins the project layer explicitly (tests, tools) —
+ * otherwise it is derived from the agent's session cwd, best-effort.
  * Usage recording covers ALL kinds — memories and skills appear as directory
  * lines, prompts/subagents as content — and is deduped per session so the
  * counts read "how many sessions saw this", not "how many prompt builds".
@@ -282,8 +346,10 @@ export function entriesSectionText(engine, agent, query, opts) {
         return "";
     }
     const globalState = engine.load("global", undefined);
+    const projectKey = opts?.projectKey ?? projectKeyOf(agent);
+    const projectState = projectKey ? engine.load("project", projectKey) : undefined;
     const localState = nearestLocalStateWithEntries(engine, agent);
-    const merged = localState ? mergeHarnessStates(globalState, localState) : globalState;
+    const merged = mergeHarnessStates(globalState, localState, projectState ? { projectState } : undefined);
     const promptEntries = Object.values(merged.entries.prompt);
     const subagentEntries = Object.values(merged.entries.subagent);
     const relevanceQuery = (query ?? recentUserText(agent)).trim();
@@ -302,18 +368,18 @@ export function entriesSectionText(engine, agent, query, opts) {
     }
     // Gap B3: lightweight directory of ALL entries (id+title, one line each).
     // Zero-cost index so the model knows what exists and can ask for full text.
-    const directoryText = formatEntriesDirectoryCapped(opts?.directoryLines ?? DEFAULT_DIRECTORY_LINES, Object.values(merged.entries.prompt), Object.values(merged.entries.memory), Object.values(merged.entries.skill), Object.values(merged.entries.subagent));
+    const directoryLines = opts?.directoryLines ?? DEFAULT_DIRECTORY_LINES;
+    const promptKind = Object.values(merged.entries.prompt);
+    const subagentKind = Object.values(merged.entries.subagent);
+    const memoryKind = Object.values(merged.entries.memory);
+    const skillKind = Object.values(merged.entries.skill);
+    const directoryText = formatEntriesDirectoryRanked(directoryLines, relevanceQuery, promptKind, subagentKind, memoryKind, skillKind);
     // Directory-visible keys count too: a memory's injection IS its directory
-    // line. Set semantics keep content-injected entries single-counted.
-    for (const kind of ["prompt", "memory", "skill", "subagent"]) {
-        for (const entry of Object.values(merged.entries[kind])) {
-            if (isArchived(entry))
-                continue;
-            const key = `${kind}:${entry.id}`;
-            if (injectedKeys.has(key) || directoryText.includes(`[${key}]`)) {
-                injectedKeys.add(key);
-            }
-        }
+    // line. Set semantics keep content-injected entries single-counted. Keys
+    // come from the single display-ordered source (type hooks included), not
+    // substring matching on the rendered text.
+    for (const entry of rankedDirectoryEntries(directoryLines, relevanceQuery, promptKind, subagentKind, memoryKind, skillKind)) {
+        injectedKeys.add(`${entry.kind}:${entry.id}`);
     }
     // Record usage durably (best-effort: failure never blocks injection).
     // Deduped per session — see recordInjection.

package/lib/llm-text.js

@@ -1,4 +1,5 @@
 import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
 /**
  * Stream a single-turn text completion through `ctx.llm`. Forces
  * `reasoningEffort: off` so the model spends its budget on the answer,
@@ -17,7 +18,7 @@ export async function streamText(ctx, opts) {
         messages: [
             createUserMessage({
                 content: [{ type: "text", text: opts.prompt }],
-                source: { kind: "plugin", plugin: "dsh-continual-evolve" },
+                source: EVOLVE_MESSAGE_SOURCE,
             }),
         ],
         reasoningEffort: ReasoningEffortId("off"),

package/lib/message-source.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Producer declaration for every message this plugin injects.
+ *
+ * Harness message sources are a merge-extensible sum type: each producer
+ * declares its own `kind` in its own module, and dsh 0.1.7 removed the shared
+ * catch-all `kind: "plugin"`. Declaring our kind once, here, keeps every
+ * injection site checked against the host vocabulary instead of repeating a
+ * local literal that silently drifts when that vocabulary changes.
+ */
+declare module "@deepseek-ai/dsh-llm" {
+    interface MessageSourceMap {
+        "continual-evolve": EvolveMessageSource;
+    }
+}
+/** Source tag identifying dsh-continual-evolve as the message producer. */
+export interface EvolveMessageSource {
+    kind: "continual-evolve";
+}
+/** Source value carried by every message this plugin injects. */
+export declare const EVOLVE_MESSAGE_SOURCE: {
+    readonly kind: "continual-evolve";
+};
+//# sourceMappingURL=message-source.d.ts.map

package/lib/message-source.js

@@ -0,0 +1,12 @@
+/**
+ * Producer declaration for every message this plugin injects.
+ *
+ * Harness message sources are a merge-extensible sum type: each producer
+ * declares its own `kind` in its own module, and dsh 0.1.7 removed the shared
+ * catch-all `kind: "plugin"`. Declaring our kind once, here, keeps every
+ * injection site checked against the host vocabulary instead of repeating a
+ * local literal that silently drifts when that vocabulary changes.
+ */
+/** Source value carried by every message this plugin injects. */
+export const EVOLVE_MESSAGE_SOURCE = { kind: "continual-evolve" };
+//# sourceMappingURL=message-source.js.map

package/lib/notify.d.ts

@@ -4,11 +4,12 @@
  * module queues a short follow-up turn after an approved gate run so the
  * user SEES what was persisted, how to inspect it, and how to roll it back.
  *
- * The notice is a plugin-sourced user message (`agent.followup`), so it is
- * rendered in the session transcript like any other input and the agent
- * answers with a one-line confirmation. It never fakes tool or assistant
+ * The notice is a `continual-evolve`-sourced user message (`agent.followup`),
+ * so it is rendered in the session transcript like any other input and the
+ * agent answers with a one-line confirmation. It never fakes tool or assistant
  * events, so session replay, the ordered surface, and derived history stay
- * untouched: the notice is a plain `user/message` with a plugin source.
+ * untouched: the notice is a plain `user/message` carrying this plugin's own
+ * source kind.
  *
  * Every mechanical property stays in code: the notice text is built from the
  * applied refinement result, never from model text.

package/lib/notify.js

@@ -1,4 +1,5 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
 /**
  * Compose the user-visible gate notice from an applied refinement result.
  * Lists every successfully applied edit (kind + title + id) and the rollback
@@ -30,7 +31,7 @@ export function notifyAutoReview(ctx, agent, result, turnsSinceLastReview) {
     try {
         agent.followup(createUserMessage({
             content: [{ type: "text", text: buildGateNotice(result, turnsSinceLastReview) }],
-            source: { kind: "plugin", plugin: "dsh-continual-evolve" },
+            source: EVOLVE_MESSAGE_SOURCE,
         }));
     }
     catch (cause) {

package/lib/planner.d.ts

@@ -9,7 +9,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessState, RefinementProposal, RefinementResult } from "./types.js";
-export declare const PLANNER_SYSTEM_PROMPT = "You are the /evolve continual harness subsystem.\n\nYour job is to improve the editable continual harness state. Instead of\nsummarizing the conversation you emit precise Create, Update, or Delete edits\nto reusable state: prompt notes, memories, skills, and subagent specs.\n\nRules:\n- The base system prompt is immutable and MUST NOT be rewritten (never edit id \"base_system_prompt\").\n- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.\n- prompt = narrow behavioral policy addendums; memory = durable facts/preferences/failures;\n  skill = repeatable procedures (must carry a python reference {type:\"python\", import, callable}\n  and an arguments object); subagent = reusable delegation roles.\n- Skill entries are authored to the DSH skill quality standard\n  (skill-creator, distilled from the official deepseek-harness 11 skills;\n  the full facts are provided in the <skill_quality_standard> block below):\n  only for a REAL trigger scenario grounded in the trajectory\n  (who, in what real task, what signal) \u2014 never invent one to pad the store;\n  never duplicate the official 11 skills or existing entries; content is a\n  SKILL.md document (frontmatter routing with \"use when / do not use when\"\n  description, boundary declaration, prerequisites and exclusions, layered\n  information, verifiable completion criteria). Self-check every proposed\n  skill against the 7 structural features and state the result in its\n  reason field.\n- Repeated multi-step workflows (session start/end routines, recurring\n  wrap-up or handoff procedures) may be proposed as guidance skills:\n  kind=skill, skill_kind=\"guidance\", content = a SKILL.md document (no\n  python reference \u2014 executable skills keep requiring reference +\n  arguments). Only propose with repeated evidence in the trajectory, never\n  for one-off flows. Guidance skills materialize as discoverable SKILL.md\n  files under <skillsRoot>/<kebab-name>/SKILL.md and are always offered to\n  the user for a decision before they land.\n- Local edits are session-scoped; global edits persist across sessions.\n- Gap C2: EVERY edit MUST include a \"blastRadius\" field indicating how broadly\n  the edit applies: \"general\" (cross-project tactical rule, applies everywhere),\n  \"project\" (valid for the current project/repo), or \"session\" (one-off,\n  specific to this session's context). The review gate validates that\n  local-scope edits use \"session\" or \"project\", and global-scope edits use\n  \"general\" or \"project\". When in doubt, prefer narrower blast radius.\n- Ground every edit in evidence: the session trajectory (recent direct user\n  messages) is provided when available; prefer edits backed by it over\n  speculation, and never invent preferences the user did not express.\n- Stale entries (superseded by newer ones, never referenced in recent\n  trajectories, obsolete facts): propose action \"archive\" instead of\n  \"delete\" \u2014 archive hides the entry from injection while keeping its data\n  restorable; it requires only kind + id.\n- Output JSON only, exactly this shape:\n{\n  \"summary\": \"one sentence\",\n  \"rationale\": \"why these edits are justified by the evidence\",\n  \"expectedOutcome\": \"what should improve and how to validate it\",\n  \"edits\": [\n    {\n      \"action\": \"create|update|delete\",\n      \"kind\": \"prompt|memory|skill|subagent\",\n      \"id\": \"stable id for update/delete, optional for create\",\n      \"title\": \"required for create/update except delete\",\n      \"content\": \"required for create/update except delete\",\n      \"path\": \"optional grouping path\",\n      \"reference\": {\"type\":\"python\",\"import\":\"pkg.mod\",\"callable\":\"fn\"} ,\n      \"arguments\": {\"name\": {\"type\":\"string\",\"required\":true,\"description\":\"...\"}},\n      \"skill_kind\": \"executable|guidance (optional; skill kind only \u2014 guidance = SKILL.md document without reference)\",\n      \"metadata\": {},\n      \"reason\": \"why this edit is useful\",\n      \"blastRadius\": \"general|project|session\"\n    }\n  ]\n}";
+export declare const PLANNER_SYSTEM_PROMPT = "You are the /evolve continual harness subsystem.\n\nYour job is to improve the editable continual harness state. Instead of\nsummarizing the conversation you emit precise Create, Update, or Delete edits\nto reusable state: prompt notes, memories, skills, and subagent specs.\n\nRules:\n- The base system prompt is immutable and MUST NOT be rewritten (never edit id \"base_system_prompt\").\n- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.\n- prompt = narrow behavioral policy addendums; memory = ONE FACT per entry, typed via metadata.memoryType\n-   (user = who the user is; feedback = a pitfall/correction or confirmed approach, MUST carry Why + How to apply;\n-   project = work goal/constraint not derivable from the repo; reference = URL/dashboard/ticket pointer).\n-   Memory rules: one fact per entry (title = one-line retrieval hook, content = the fact alone);\n-   never save what the repo already records (code structure, past fixes, git history, AGENTS.md) or what only\n-   matters to this conversation \u2014 save the non-obvious point instead; before creating, update the existing\n-   entry when one already covers the fact (creates carry metadata {memoryType} or they are rejected);\n-   skill = repeatable procedures (must carry a python reference {type:\"python\", import, callable}\n  and an arguments object); subagent = reusable delegation roles.\n- Skill entries are authored to the DSH skill quality standard\n  (skill-creator, distilled from the official deepseek-harness 11 skills;\n  the full facts are provided in the <skill_quality_standard> block below):\n  only for a REAL trigger scenario grounded in the trajectory\n  (who, in what real task, what signal) \u2014 never invent one to pad the store;\n  never duplicate the official 11 skills or existing entries; content is a\n  SKILL.md document (frontmatter routing with \"use when / do not use when\"\n  description, boundary declaration, prerequisites and exclusions, layered\n  information, verifiable completion criteria). Self-check every proposed\n  skill against the 7 structural features and state the result in its\n  reason field.\n- Repeated multi-step workflows (session start/end routines, recurring\n  wrap-up or handoff procedures) may be proposed as guidance skills:\n  kind=skill, skill_kind=\"guidance\", content = a SKILL.md document (no\n  python reference \u2014 executable skills keep requiring reference +\n  arguments). Only propose with repeated evidence in the trajectory, never\n  for one-off flows. Guidance skills materialize as discoverable SKILL.md\n  files under <skillsRoot>/<kebab-name>/SKILL.md and are always offered to\n  the user for a decision before they land.\n- Local edits are session-scoped; global edits persist across sessions.\n- Gap C2: EVERY edit MUST include a \"blastRadius\" field indicating how broadly\n  the edit applies: \"general\" (cross-project tactical rule, applies everywhere),\n  \"project\" (valid for the current project/repo), or \"session\" (one-off,\n  specific to this session's context). The review gate validates that\n  local-scope edits use \"session\" or \"project\", and global-scope edits use\n  \"general\" or \"project\". When in doubt, prefer narrower blast radius.\n- Ground every edit in evidence: the session trajectory (recent direct user\n  messages) is provided when available; prefer edits backed by it over\n  speculation, and never invent preferences the user did not express.\n- Stale entries (superseded by newer ones, never referenced in recent\n  trajectories, obsolete facts): propose action \"archive\" instead of\n  \"delete\" \u2014 archive hides the entry from injection while keeping its data\n  restorable; it requires only kind + id.\n- Output JSON only, exactly this shape:\n{\n  \"summary\": \"one sentence\",\n  \"rationale\": \"why these edits are justified by the evidence\",\n  \"expectedOutcome\": \"what should improve and how to validate it\",\n  \"edits\": [\n    {\n      \"action\": \"create|update|delete\",\n      \"kind\": \"prompt|memory|skill|subagent\",\n      \"id\": \"stable id for update/delete, optional for create\",\n      \"title\": \"required for create/update except delete\",\n      \"content\": \"required for create/update except delete\",\n      \"path\": \"optional grouping path\",\n      \"reference\": {\"type\":\"python\",\"import\":\"pkg.mod\",\"callable\":\"fn\"} ,\n      \"arguments\": {\"name\": {\"type\":\"string\",\"required\":true,\"description\":\"...\"}},\n      \"skill_kind\": \"executable|guidance (optional; skill kind only \u2014 guidance = SKILL.md document without reference)\",\n      \"metadata\": {},\n      \"reason\": \"why this edit is useful\",\n      \"blastRadius\": \"general|project|session\"\n    }\n  ]\n}";
 export interface PlanOptions {
     agent: Agent;
     state: HarnessState;

package/lib/planner.js

@@ -12,8 +12,14 @@ to reusable state: prompt notes, memories, skills, and subagent specs.
 Rules:
 - The base system prompt is immutable and MUST NOT be rewritten (never edit id "base_system_prompt").
 - Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.
-- prompt = narrow behavioral policy addendums; memory = durable facts/preferences/failures;
-  skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
+- prompt = narrow behavioral policy addendums; memory = ONE FACT per entry, typed via metadata.memoryType
+-   (user = who the user is; feedback = a pitfall/correction or confirmed approach, MUST carry Why + How to apply;
+-   project = work goal/constraint not derivable from the repo; reference = URL/dashboard/ticket pointer).
+-   Memory rules: one fact per entry (title = one-line retrieval hook, content = the fact alone);
+-   never save what the repo already records (code structure, past fixes, git history, AGENTS.md) or what only
+-   matters to this conversation — save the non-obvious point instead; before creating, update the existing
+-   entry when one already covers the fact (creates carry metadata {memoryType} or they are rejected);
+-   skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
   and an arguments object); subagent = reusable delegation roles.
 - Skill entries are authored to the DSH skill quality standard
   (skill-creator, distilled from the official deepseek-harness 11 skills;

package/lib/project.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stable project key for a workspace. `workspaceIdentity` (when set)
+ * replaces the path as the hash source so renamed checkouts of the same
+ * logical project keep one store.
+ */
+export declare function resolveProjectKey(workspacePath: string, workspaceIdentity?: string): string;
+/** Defense for externally supplied keys (explicit opts): single safe segment. */
+export declare function sanitizeProjectKey(key: string): string;
+/** Minimal agent shape the project-key derivation needs (duck-typed). */
+export interface ProjectKeyAgentLike {
+    session?: {
+        header?: {
+            cwd?: unknown;
+            meta?: {
+                cwd?: unknown;
+            };
+        };
+    };
+}
+/**
+ * Derive the project key from an assembling agent's session cwd. Returns
+ * undefined when no validated absolute cwd is present — the caller then
+ * skips the project layer rather than failing the whole assembly.
+ */
+export declare function projectKeyOf(agent: unknown, opts?: {
+    workspaceIdentity?: string;
+}): string | undefined;
+//# sourceMappingURL=project.d.ts.map

package/lib/project.js

@@ -0,0 +1,66 @@
+/**
+ * Project scope identity: the third harness layer between session-local
+ * staging and the cross-project global store.
+ *
+ * A project is identified by the session's validated absolute `cwd`
+ * (stable slug + sha256, mirroring ZCode's `project-root.ts`), so every
+ * session opened in the same workspace shares one project store while
+ * different checkouts never collide. All helpers are pure and never throw —
+ * a missing cwd simply means "no project layer" (the caller degrades to
+ * global+local, the same shape as an empty project store).
+ */
+import { createHash } from "node:crypto";
+import { basename, isAbsolute, resolve } from "node:path";
+/**
+ * Stable project key for a workspace. `workspaceIdentity` (when set)
+ * replaces the path as the hash source so renamed checkouts of the same
+ * logical project keep one store.
+ */
+export function resolveProjectKey(workspacePath, workspaceIdentity) {
+    const identity = workspaceIdentity?.trim();
+    const normalized = resolve(workspacePath);
+    const keySource = identity && identity.length > 0 ? identity : process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    const hash = createHash("sha256").update(keySource).digest("hex").slice(0, 16);
+    const slug = identity && identity.length > 0 ? "project" : sanitizeSlug(basename(normalized) || "project");
+    return `${slug}-${hash}`;
+}
+function sanitizeSlug(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return slug.length > 0 ? slug : "project";
+}
+/** Defense for externally supplied keys (explicit opts): single safe segment. */
+export function sanitizeProjectKey(key) {
+    const cleaned = key
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return cleaned.length > 0 ? cleaned : "project";
+}
+/**
+ * Derive the project key from an assembling agent's session cwd. Returns
+ * undefined when no validated absolute cwd is present — the caller then
+ * skips the project layer rather than failing the whole assembly.
+ */
+export function projectKeyOf(agent, opts) {
+    try {
+        const header = agent?.session?.header;
+        const raw = header?.cwd ?? header?.meta?.cwd;
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            return undefined;
+        }
+        const cwd = raw.trim();
+        if (!isAbsolute(cwd)) {
+            return undefined;
+        }
+        return resolveProjectKey(cwd, opts?.workspaceIdentity);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=project.js.map

package/lib/service.js

@@ -6,6 +6,11 @@ import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
 import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry, secretLeakReason } from "./promotion.js";
 export function createEvolutionEngine(baseDir, hooks = {}) {
+    /**
+     * Load a scope's state. For `project` the `sessionId` parameter carries
+     * the project key (see `resolveProjectKey` in project.ts); callers
+     * derive it with `projectKeyOf(agent)` and pass it through unchanged.
+     */
     function load(scope, sessionId) {
         return loadHarnessState(storePaths(baseDir, scope, sessionId).stateDir, scope);
     }

package/lib/source.d.ts

@@ -4,12 +4,13 @@
  * citation of (sessionId, seqs) expands back to the exact original
  * conversation rows (the durable log under `<dshHome>/sessions/...`).
  *
- * The extraction reads the live `agent.session.events` log (duck-typed, no
- * dsh-session dependency) and only ever selects direct human messages —
- * injected plugin context and tool results never become citations.
+ * The extraction reads the live session log through the reader the running
+ * harness generation exposes (duck-typed, no dsh-session dependency) and only
+ * ever selects direct human messages — injected plugin context and tool
+ * results never become citations.
  */
 import type { EntrySource } from "./types.js";
-import type { AgentLike } from "./inject.js";
+import { type AgentLike } from "./inject.js";
 /** At most this many source user messages are cited per entry. */
 export declare const MAX_SOURCE_MESSAGES = 3;
 /**

package/lib/source.js

@@ -1,3 +1,4 @@
+import { sessionEventsOf } from "./inject.js";
 /** At most this many source user messages are cited per entry. */
 export const MAX_SOURCE_MESSAGES = 3;
 /**
@@ -6,8 +7,8 @@ export const MAX_SOURCE_MESSAGES = 3;
  * callers then simply omit the citation.
  */
 export function recentUserSeqs(agent, opts) {
-    const events = agent?.session?.events;
-    if (!events || events.length === 0) {
+    const events = sessionEventsOf(agent);
+    if (events.length === 0) {
         return [];
     }
     const maxMessages = opts?.maxMessages ?? MAX_SOURCE_MESSAGES;

package/lib/state.d.ts

@@ -7,11 +7,15 @@ export declare function stateFilePath(stateDir: string): string;
  */
 export declare function loadHarnessState(stateDir: string, scope?: HarnessScope): HarnessState;
 /**
- * Merge global and local state into the view the model sees. Local entries
- * win over same-id global entries; a colliding local id is prefixed
- * `local:` so both remain addressable.
+ * Merge global, project, and local state into the view the model sees.
+ * Precedence is global < project < local: a colliding project id is
+ * prefixed `project:` so both remain addressable, and a colliding local id
+ * is prefixed `local:` (local always wins — it is the session's live
+ * staging copy). Called with two args the project layer is simply absent.
  */
-export declare function mergeHarnessStates(globalState: HarnessState, localState: HarnessState | undefined): HarnessState;
+export declare function mergeHarnessStates(globalState: HarnessState, localState?: HarnessState | undefined, opts?: {
+    projectState?: HarnessState | undefined;
+}): HarnessState;
 /**
  * Persist state atomically: write to a temp file, fsync-free but rename-based,
  * preserving the mode of an existing file (defaults to 0o600 for new files).