dsh-continual-evolve 0.6.1 → 0.7.0

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";
@@ -214,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 —
@@ -245,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 "";
-    }
-    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 [];
     }
-    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
@@ -281,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".
@@ -298,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();
@@ -318,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/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/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).

package/lib/state.js

@@ -20,7 +20,7 @@ export function stateFilePath(stateDir) {
     return join(stateDir, "harness_state.json");
 }
 function normalizeScope(value, fallback) {
-    return value === "global" || value === "local" ? value : fallback;
+    return value === "global" || value === "project" || value === "local" ? value : fallback;
 }
 function objectRecord(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -95,24 +95,31 @@ export function loadHarnessState(stateDir, scope = "global") {
     return state;
 }
 /**
- * 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 function mergeHarnessStates(globalState, localState) {
+export function mergeHarnessStates(globalState, localState, opts) {
     const merged = emptyHarnessState();
-    merged.schema = Math.max(globalState.schema, localState?.schema ?? 1);
+    merged.schema = Math.max(globalState.schema, opts?.projectState?.schema ?? 1, localState?.schema ?? 1);
     for (const kind of Object.keys(merged.entries)) {
         for (const [id, entry] of Object.entries(globalState.entries[kind])) {
             merged.entries[kind][id] = { ...entry, scope: "global" };
         }
+        for (const [id, entry] of Object.entries(opts?.projectState?.entries[kind] ?? {})) {
+            const scoped = { ...entry, scope: "project" };
+            const mergedId = merged.entries[kind][id] ? `project:${id}` : id;
+            merged.entries[kind][mergedId] = scoped;
+        }
         for (const [id, entry] of Object.entries(localState?.entries[kind] ?? {})) {
             const scoped = { ...entry, scope: "local" };
             const mergedId = merged.entries[kind][id] ? `local:${id}` : id;
             merged.entries[kind][mergedId] = scoped;
         }
     }
-    merged.refinements = [...globalState.refinements, ...(localState?.refinements ?? [])];
+    merged.refinements = [...globalState.refinements, ...(opts?.projectState?.refinements ?? []), ...(localState?.refinements ?? [])];
     return merged;
 }
 /**

package/lib/store.d.ts

@@ -8,6 +8,12 @@ export interface StorePaths {
     /** JSONL path for applied refinement results. */
     resultsPath: string;
 }
+/**
+ * Resolve store paths for a scope. For `project` the `sessionId` parameter
+ * carries the project key (see {@link resolveProjectKey} in project.ts) —
+ * it is sanitized to a single path segment so an externally supplied key
+ * can never traverse out of `evolve/projects/`.
+ */
 export declare function storePaths(baseDir: string, scope: HarnessScope, sessionId?: string): StorePaths;
 /** Snapshot the current state file before a mutation, if one exists. */
 export declare function snapshotBefore(paths: StorePaths, refinementId: string): void;

package/lib/store.js

@@ -4,9 +4,10 @@
  * Layout (self-contained under the DSH home; no dependency on session
  * persistence internals):
  *
- *   <dshHome>/evolve/global/harness_state.json    cross-session store
+ *   <dshHome>/evolve/global/harness_state.json    cross-project store
  *   <dshHome>/evolve/global/refinements.jsonl     applied results (rollback source)
- *   <dshHome>/evolve/local/<sessionId>/...        per-session store
+ *   <dshHome>/evolve/projects/<slug-hash>/...     per-project store
+ *   <dshHome>/evolve/local/<sessionId>/...        per-session staging store
  *
  * Snapshot discipline is code-enforced: before any mutating apply, the
  * pre-apply state is copied to `snapshots/<refinementId>.json`. The model has
@@ -14,10 +15,17 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { sanitizeProjectKey } from "./project.js";
 import { stateFilePath } from "./state.js";
 export const EVOLVE_DIR = "evolve";
+/**
+ * Resolve store paths for a scope. For `project` the `sessionId` parameter
+ * carries the project key (see {@link resolveProjectKey} in project.ts) —
+ * it is sanitized to a single path segment so an externally supplied key
+ * can never traverse out of `evolve/projects/`.
+ */
 export function storePaths(baseDir, scope, sessionId) {
-    const scopeDir = scope === "global" ? "global" : join("local", sessionId ?? "anonymous");
+    const scopeDir = scope === "global" ? "global" : scope === "project" ? join("projects", sanitizeProjectKey(sessionId ?? "project")) : join("local", sessionId ?? "anonymous");
     const stateDir = join(baseDir, EVOLVE_DIR, scopeDir);
     return {
         stateDir,

package/lib/tool.d.ts

@@ -6,7 +6,10 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { HarnessScope } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
-/** Accept both the boolean tool parameter (`global: true`) and the string form. */
+/**
+ * Accept the string form (`scope: "project"`) with the legacy boolean tool
+ * parameter (`global: true`) as fallback. `scope` wins when both are given.
+ */
 export declare function scopeOf(value: unknown, fallback: HarnessScope): HarnessScope;
 export interface ToolGateOptions {
     requireGlobalApproval: boolean;