dsh-continual-evolve 0.1.1 → 0.3.0

package/lib/skillquality.js

@@ -0,0 +1,311 @@
+/**
+ * Skill-quality integration: makes the DSH skill quality standard — carried
+ * by the author-distilled skills skill-creator / skill-audit (distilled
+ * from the official deepseek-harness 11 skills, facts verified against
+ * deepseek-harness 47f9438) — usable INSIDE the self-evolution loop.
+ *
+ * The planner and review gate are raw `ctx.llm` calls — they do not live in
+ * an agent session, so they cannot load skills through the `skill` tool.
+ * The skill-creator / skill-audit skills stay the single source of truth on
+ * disk; this module only:
+ *
+ * 1. reads the template facts at runtime
+ *    (`<skillsRoot>/skill-creator/references/template.md`, 85 lines) and
+ *    hands them to the planner as a `<skill_quality_standard>` block —
+ *    the on-disk template wins, a built-in distilled guide is the fallback
+ *    for installs without these skills;
+ * 2. code-enforces the mechanical frontmatter rules of
+ *    `skill-creator/scripts/validate-frontmatter.mjs` (the platform would
+ *    IGNORE a file that fails them), so a skill entry can never materialize
+ *    a SKILL.md the platform refuses to load.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderSkillMarkdown } from "./skill-render.js";
+/** Skill-name regex the platform enforces (skill-filesystem). */
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TRUE_WORDS = new Set(["true", "yes", "on", "1"]);
+const FALSE_WORDS = new Set(["false", "no", "off", "0"]);
+const LEGACY_KEYS = ["disableModelInvocation", "modelInvocable", "userInvocable"];
+const CANONICAL_KEYS = {
+    disableModelInvocation: "disable-model-invocation",
+    modelInvocable: "disable-model-invocation",
+    userInvocable: "user-invocable",
+};
+/** Relative location of the skill-creator template facts. */
+export const SKILL_CREATOR_TEMPLATE_REL = join("skill-creator", "references", "template.md");
+/**
+ * Read the skill-creator template facts
+ * (`<skillsRoot>/skill-creator/references/template.md`; facts distilled
+ * from the official deepseek-harness skills). Returns null when the skills
+ * are not installed — callers fall back to the builtin distilled guide.
+ * Reading is a runtime reference, never a copy: template updates in the
+ * skill are picked up automatically.
+ */
+export function readSkillCreatorTemplate(skillsRoot) {
+    const path = join(skillsRoot, SKILL_CREATOR_TEMPLATE_REL);
+    try {
+        if (!existsSync(path))
+            return null;
+        const text = readFileSync(path, "utf8");
+        return text.trim().length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Builtin distilled skill-quality guide (fallback when the skill-creator
+ * template is not installed). Condenses the template facts — frontmatter
+ * schema, the 7 structural features, paragraph skeleton, and the
+ * no-duplication / real-trigger rules — so a planner still authors skills
+ * to the standard on installs without the skill-creator / skill-audit
+ * skills.
+ */
+export const BUILTIN_SKILL_QUALITY_GUIDE = `DSH skill quality standard (distilled by the author from the official deepseek-harness 11 skills; the full facts live in <skillsRoot>/skill-creator/references/template.md when installed):
+
+Frontmatter schema (platform-enforced; violations make the platform IGNORE the whole file):
+- name: required, kebab-case only (^[a-z0-9]+(?:-[a-z0-9]+)*$)
+- description: required, non-empty; write "use when / do not use when" routing so the model can select it correctly
+- invocation booleans accept true/false/yes/no/on/off/1/0; legacy camelCase keys (disableModelInvocation / modelInvocable / userInvocable) are rejected
+- whenToUse (optional): non-empty string; metadata (optional): object
+
+The 7 structural features of the official deepseek-harness skills:
+1. Frontmatter is routing metadata, not a summary (description = when to use / when not to use)
+2. Opens with a boundary declaration (guidance, not a script; mechanical flow skills may omit the disclaimer)
+3. Prerequisites + exclusions: explicit required input, stop when missing (report the required input and stop), excluded scenarios
+4. Layered information: Sources of truth (link only, do not re-summarize) -> numbered blocking requirements -> manual checks -> verification commands -> report format; all executable, no slogans
+5. Skill interlinks: reference a single source of truth instead of duplicating it
+6. Verifiable completion criteria: explicit verification commands and report format
+7. Real use + iteration: a real trigger scenario must exist; calibration conclusions distill into references/
+
+Paragraph skeleton (writing order): frontmatter -> H1 + boundary declaration -> Sources of truth -> numbered requirements / workflow (full commands) -> exclusions / stop conditions -> verification and report.
+
+Creation rules: only create a skill for a REAL trigger scenario (who, in what real task, what signal) grounded in the trajectory — never invent one to pad the store; do not duplicate the official 11 skills or existing entries; skill bodies should be a SKILL.md document (this is what materializes under <skillsRoot>/<kebab-name>/SKILL.md).`;
+/**
+ * The quality guide handed to the planner: the skill-creator template facts
+ * when the skills are installed, otherwise the builtin distilled guide.
+ * Never throws — a missing/unreadable template degrades to the builtin.
+ */
+export function skillQualityGuide(skillsRoot) {
+    if (skillsRoot) {
+        const template = readSkillCreatorTemplate(skillsRoot);
+        if (template !== null) {
+            return {
+                source: "template",
+                text: `The skill-creator template facts (distilled from the official deepseek-harness 11 skills, verified against deepseek-harness 47f9438; single source of truth, read from <skillsRoot>/skill-creator/references/template.md):\n\n${template}`,
+            };
+        }
+    }
+    return { source: "builtin", text: BUILTIN_SKILL_QUALITY_GUIDE };
+}
+/** Split frontmatter out of a raw SKILL.md. Returns { yaml, body } or null when delimiters are missing. */
+export function splitFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0] !== "---")
+        return null;
+    const close = lines.indexOf("---", 1);
+    if (close < 0)
+        return null;
+    return { yaml: lines.slice(1, close).join("\n"), body: lines.slice(close + 1).join("\n") };
+}
+/** Parse one scalar in the YAML subset the platform's schema keys use. */
+function parseScalar(raw, lineNo) {
+    const value = raw.trim();
+    if (value === "")
+        return "";
+    if (value.startsWith("'")) {
+        if (!value.endsWith("'"))
+            throw new Error(`unterminated single-quoted scalar at line ${lineNo}`);
+        return value.slice(1, -1).replace(/''/g, "'");
+    }
+    if (value.startsWith('"')) {
+        if (!value.endsWith('"'))
+            throw new Error(`unterminated double-quoted scalar at line ${lineNo}`);
+        return value
+            .slice(1, -1)
+            .replace(/\\n/g, "\n")
+            .replace(/\\t/g, "\t")
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, "\\");
+    }
+    return value;
+}
+/** Minimal YAML-subset parser for the flat schema the platform reads (mirrors validate-frontmatter.mjs). */
+function parseMiniYaml(text) {
+    const data = {};
+    const lines = text.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? "";
+        const lineNo = i + 1;
+        i += 1;
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        if (line.length - line.trimStart().length > 0) {
+            throw new Error(`unsupported indented construct at line ${lineNo}: ${trimmed}`);
+        }
+        const match = /^([A-Za-z0-9_-]+):(?:\s+(.*))?$/.exec(trimmed);
+        if (!match)
+            throw new Error(`unparseable line ${lineNo}: ${trimmed}`);
+        const key = match[1] ?? "";
+        let value = match[2] ?? "";
+        if (value === "|" || value === ">") {
+            const block = [];
+            while (i < lines.length && (lines[i] ?? "").trim() !== "" && (lines[i] ?? "").startsWith(" ")) {
+                block.push(lines[i] ?? "");
+                i += 1;
+            }
+            data[key] = block.join("\n");
+            continue;
+        }
+        if (value === "" && i < lines.length && (lines[i] ?? "").startsWith(" ") && (lines[i] ?? "").trim() !== "") {
+            const nested = {};
+            while (i < lines.length && (lines[i] ?? "").trim() !== "" && (lines[i] ?? "").startsWith(" ")) {
+                const nm = /^([A-Za-z0-9_-]+):(?:\s+(.*))?$/.exec((lines[i] ?? "").trim());
+                if (!nm)
+                    throw new Error(`unparseable nested line ${i + 1}: ${(lines[i] ?? "").trim()}`);
+                nested[nm[1] ?? ""] = parseScalar(nm[2] ?? "", i + 1);
+                i += 1;
+            }
+            data[key] = nested;
+            continue;
+        }
+        data[key] = parseScalar(value, lineNo);
+    }
+    return data;
+}
+/**
+ * Mechanical frontmatter validation of a rendered SKILL.md, mirroring
+ * `skill-creator/scripts/validate-frontmatter.mjs` (and the platform's
+ * skill-filesystem rules): delimiter structure, name kebab-case, non-empty
+ * description, invocation-boolean spellings, legacy camelCase key rejection,
+ * whenToUse/metadata types. Returns human-readable problems; an empty array
+ * means the file would load.
+ */
+export function validateRenderedSkillMarkdown(markdown) {
+    const problems = [];
+    const split = splitFrontmatter(markdown);
+    if (!split) {
+        return [
+            "missing YAML frontmatter (first line `---` with a closing `---`) — platform would IGNORE this file",
+        ];
+    }
+    let data;
+    try {
+        data = parseMiniYaml(split.yaml);
+    }
+    catch (cause) {
+        return [`invalid YAML frontmatter: ${cause instanceof Error ? cause.message : String(cause)} — platform would IGNORE this file`];
+    }
+    const name = typeof data["name"] === "string" && data["name"].length > 0 ? data["name"] : undefined;
+    if (name === undefined) {
+        problems.push("frontmatter requires non-empty `name` — platform would IGNORE this file");
+    }
+    else if (!NAME_RE.test(name)) {
+        problems.push(`invalid skill name "${name}" (must match ${NAME_RE}) — platform would IGNORE this file`);
+    }
+    const description = typeof data["description"] === "string" && data["description"].length > 0 ? data["description"] : undefined;
+    if (description === undefined) {
+        problems.push("frontmatter requires non-empty `description` — platform would IGNORE this file");
+    }
+    for (const legacy of LEGACY_KEYS) {
+        if (Object.hasOwn(data, legacy)) {
+            problems.push(`legacy key "${legacy}" is unsupported; use "${CANONICAL_KEYS[legacy]}" — platform would IGNORE this file`);
+        }
+    }
+    for (const key of ["disable-model-invocation", "user-invocable"]) {
+        if (!Object.hasOwn(data, key))
+            continue;
+        const value = data[key];
+        if (typeof value === "boolean")
+            continue;
+        const word = String(value).toLowerCase();
+        if (TRUE_WORDS.has(word) || FALSE_WORDS.has(word))
+            continue;
+        problems.push(`frontmatter field "${key}" must be a boolean (accepted: true/false/yes/no/on/off/1/0), got ${JSON.stringify(value)} — platform would IGNORE this file`);
+    }
+    if (Object.hasOwn(data, "whenToUse") && !(typeof data["whenToUse"] === "string" && data["whenToUse"].length > 0)) {
+        problems.push("`whenToUse` must be a non-empty string when present");
+    }
+    if (Object.hasOwn(data, "metadata") && (typeof data["metadata"] !== "object" || data["metadata"] === null || Array.isArray(data["metadata"]))) {
+        problems.push("`metadata` must be an object when present");
+    }
+    return problems;
+}
+/**
+ * Mechanical validation of a skill entry's raw `content` (the SKILL.md body
+ * that materializes under the generated frontmatter). Code-enforced at
+ * apply time so a bad entry never reaches the store:
+ * - empty content is rejected;
+ * - content must not open with a `---` block: the materializer generates
+ *   its own frontmatter, and a second frontmatter in the body would be
+ *   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.
+ * Returns human-readable problems; an empty array means the content is
+ * mechanically acceptable.
+ */
+export function validateSkillEntryContent(content) {
+    const problems = [];
+    const trimmed = content.trim();
+    if (trimmed.length === 0) {
+        problems.push("skill content is empty");
+        return problems;
+    }
+    if (trimmed.startsWith("---")) {
+        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)) {
+        const ref = match[0] ?? "";
+        if (ref.startsWith("../") || ref.includes("/../") || ref.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(ref)) {
+            problems.push(`skill content resource reference escapes the skill directory: ${ref}`);
+        }
+    }
+    return problems;
+}
+/**
+ * Validate the FULL rendered SKILL.md of an entry (generated frontmatter +
+ * body) — the exact bytes that materialize on disk. Used as the final
+ * code-enforced line after materialization; problems here mean the platform
+ * would refuse to load the file.
+ */
+export function validateRenderedSkill(entry) {
+    return validateRenderedSkillMarkdown(renderSkillMarkdown(entry));
+}
+/**
+ * Resource references (`references/…`, `scripts/…`) found in a skill body —
+ * the same scanning policy as validate-frontmatter.mjs: markdown link
+ * 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).
+ */
+export function skillResourceRefs(content) {
+    const refs = new Set();
+    for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+        const target = ((match[1] ?? "").trim().split(/\s+/)[0] ?? "").trim();
+        if (/^(references|scripts)\/[\w./-]+$/.test(target) && !target.startsWith("../")) {
+            refs.add(target);
+        }
+    }
+    const stripped = content.replace(/\[[^\]]*\]\([^)]*\)/g, "");
+    for (const match of stripped.matchAll(/(?<![\w])(references|scripts)\/[\w./-]+\.\w+/g)) {
+        const path = match[0] ?? "";
+        // Cross-skill interlinks (`../skill-creator/...`) resolve against the
+        // sibling skill's directory, not this one — skip references whose
+        // prose prefix walks up a directory (mirrors validate-frontmatter.mjs).
+        let cursor = (match.index ?? 0) - 1;
+        while (cursor >= 0 && /[\w./-]/.test(stripped[cursor] ?? ""))
+            cursor -= 1;
+        if (!stripped.slice(cursor + 1, match.index ?? 0).includes("..")) {
+            refs.add(path);
+        }
+    }
+    return [...refs];
+}
+/** Kebab-case name under which the entry materializes (exported for diagnostics). */
+export { skillNameOf } from "./skill-render.js";
+//# sourceMappingURL=skillquality.js.map

package/lib/store.d.ts

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

package/lib/store.js

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

package/lib/tool.js

@@ -2,6 +2,8 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 import { formatHarnessStateForPrompt } from "./render.js";
 import { requireGlobalApproval } from "./approval.js";
 import { entrySourceOf } from "./source.js";
+import { getUsageCount, loadUsage } from "./usage.js";
+import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
 const SCOPES = ["local", "global"];
 /** Accept both the boolean tool parameter (`global: true`) and the string form. */
 export function scopeOf(value, fallback) {
@@ -32,19 +34,35 @@ export function registerEvolveTools(ctx, engine, opts) {
         execute: async (args, exec) => {
             const scope = scopeOf(args.scope, "local");
             const state = engine.load(scope, sessionIdOf(exec));
-            return textResult(formatHarnessStateForPrompt(state));
+            const text = formatHarnessStateForPrompt(state);
+            // Append injection usage counts (gap B1).
+            const usage = loadUsage(engine.baseDir);
+            const usageLines = [];
+            for (const kind of Object.keys(state.entries)) {
+                for (const entry of Object.values(state.entries[kind])) {
+                    const count = getUsageCount(usage, kind, entry.id);
+                    if (count > 0) {
+                        usageLines.push(`${kind}:${entry.id} — injected ${count}×`);
+                    }
+                }
+            }
+            if (usageLines.length > 0) {
+                return textResult(`${text}\n\n# Injection Usage\n${usageLines.join("\n")}`);
+            }
+            return textResult(text);
         },
     }));
     ctx.tools.register(defineTool({
         name: "evolve_add",
-        description: "Create one harness entry (prompt/memory/skill/subagent). Skills require reference {type:python, import, callable} and an arguments contract. Snapshot, version, and history are handled automatically.",
+        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.",
         parameters: {
             kind: { type: "string", enum: ["prompt", "memory", "skill", "subagent"], required: true, description: "Entry kind." },
             title: { type: "string", required: true, description: "Stable title." },
             content: { type: "string", required: true, description: "Entry body." },
             path: { type: "string", description: "Optional grouping path." },
-            reference: { type: "object", additionalProperties: true, description: "For skills: {type:'python', import, callable}." },
-            arguments: { type: "object", additionalProperties: true, description: "For skills: accepted input contract." },
+            skill_kind: { type: "string", enum: ["executable", "guidance"], description: "For skills: executable (python reference, default) or guidance (SKILL.md document, no reference)." },
+            reference: { type: "object", additionalProperties: true, description: "For executable skills: {type:'python', import, callable}." },
+            arguments: { type: "object", additionalProperties: true, description: "For executable skills: accepted input contract." },
             global: { type: "boolean", description: "Set true to write the cross-session store (requires human approval; only for durable, reusable lessons)." },
         },
         output: {
@@ -64,6 +82,8 @@ export function registerEvolveTools(ctx, engine, opts) {
             };
             if (args.path !== undefined)
                 edit.path = args.path;
+            if (args.skill_kind !== undefined)
+                edit.skill_kind = args.skill_kind;
             if (args.reference !== undefined)
                 edit.reference = args.reference;
             if (args.arguments !== undefined)
@@ -151,6 +171,10 @@ function applyEditsText(engine, scope, sessionId, edits, agent) {
         : { scope });
     const applied = result.appliedEdits.filter((e) => e.applied);
     const failed = result.appliedEdits.filter((e) => !e.applied);
+    // Gap C4: emit structured evolve_complete event for third-party consumers.
+    if (applied.length > 0 && sessionId) {
+        emitEvolveComplete(engine.baseDir, buildEvolveCompleteEvent(result, "manual_tool", sessionId));
+    }
     const lines = [`refinement ${result.id}: ${applied.length} applied, ${failed.length} failed`];
     for (const e of applied) {
         lines.push(`- ${e.action} ${e.kind}:${e.id} (v${(e.after?.version ?? e.before?.version) ?? "?"})`);

package/lib/types.d.ts

@@ -10,6 +10,14 @@
  */
 /** What a harness entry can be. */
 export type RefinementKind = "prompt" | "memory" | "skill" | "subagent";
+/**
+ * Skill-entry form: `executable` skills carry a python reference contract
+ * and can be hot-mounted as tools; `guidance` skills are SKILL.md documents
+ * (no python reference) that materialize as discoverable skills for the
+ * `skill` tool — the form for recurring multi-step workflows. Absent means
+ * `executable` (backwards compatible with pre-guidance stores).
+ */
+export type SkillKind = "executable" | "guidance";
 /** How an entry changes. */
 export type RefinementAction = "create" | "update" | "delete" | "archive";
 /** Where an entry lives: session-scoped or cross-session. */
@@ -30,6 +38,25 @@ export declare const SOURCE_SEQS_KEY = "sourceSeqs";
  * the entry can be restored (unarchive) or rolled back like any other edit.
  */
 export declare const ARCHIVED_AT_KEY = "archivedAt";
+/**
+ * Metadata key stamped on a LOCAL entry that was promoted to the global
+ * store by a session wrap-up: the id of the global entry it became. Present
+ * means the entry's lifecycle is finished — it must not be offered for
+ * promotion again (the global copy is the live one, the local copy is a
+ * restorable trace).
+ */
+export declare const PROMOTED_TO_KEY = "promotedTo";
+/**
+ * Metadata key recording when a local entry was promoted to the global
+ * store (companion of {@link PROMOTED_TO_KEY}).
+ */
+export declare const PROMOTED_AT_KEY = "promotedAt";
+/**
+ * Metadata key stamped on a GLOBAL entry created by a session wrap-up
+ * promotion: `<sessionId>:<localEntryId>` — the反向 provenance link from the
+ * cross-session copy back to the session it was distilled from.
+ */
+export declare const SOURCED_FROM_KEY = "sourcedFromLocal";
 /**
  * True when the entry is archived (hidden from injection, restorable).
  * Absent or empty archivedAt means the entry is active.
@@ -58,6 +85,8 @@ export interface HarnessEntry {
     reference: Record<string, unknown>;
     /** Skill entries declare their accepted inputs here. */
     arguments: Record<string, unknown>;
+    /** Skill form: "executable" (default) or "guidance" (SKILL.md document). */
+    skill_kind?: SkillKind;
     metadata: Record<string, unknown>;
     source: "evolve";
     created_at: string;
@@ -91,8 +120,18 @@ export interface RefinementEdit {
     path?: string;
     reference?: Record<string, unknown>;
     arguments?: Record<string, unknown>;
+    /** Skill form: "guidance" for SKILL.md document skills; absent = executable. */
+    skill_kind?: SkillKind;
     metadata?: Record<string, unknown>;
     reason?: string;
+    /**
+     * Gap C2: blast-radius annotation — how broadly this edit applies.
+     * Values: "general" (cross-project tactical), "project" (single project),
+     * "session" (one-off session-specific). The review gate checks that
+     * local-scope edits are "session" or "project" and global-scope edits
+     * are "general" or "project".
+     */
+    blastRadius?: "general" | "project" | "session";
 }
 /** The structured output of a planning pass. */
 export interface RefinementProposal {

package/lib/types.js

@@ -24,6 +24,25 @@ export const SOURCE_SEQS_KEY = "sourceSeqs";
  * the entry can be restored (unarchive) or rolled back like any other edit.
  */
 export const ARCHIVED_AT_KEY = "archivedAt";
+/**
+ * Metadata key stamped on a LOCAL entry that was promoted to the global
+ * store by a session wrap-up: the id of the global entry it became. Present
+ * means the entry's lifecycle is finished — it must not be offered for
+ * promotion again (the global copy is the live one, the local copy is a
+ * restorable trace).
+ */
+export const PROMOTED_TO_KEY = "promotedTo";
+/**
+ * Metadata key recording when a local entry was promoted to the global
+ * store (companion of {@link PROMOTED_TO_KEY}).
+ */
+export const PROMOTED_AT_KEY = "promotedAt";
+/**
+ * Metadata key stamped on a GLOBAL entry created by a session wrap-up
+ * promotion: `<sessionId>:<localEntryId>` — the反向 provenance link from the
+ * cross-session copy back to the session it was distilled from.
+ */
+export const SOURCED_FROM_KEY = "sourcedFromLocal";
 /**
  * True when the entry is archived (hidden from injection, restorable).
  * Absent or empty archivedAt means the entry is active.

package/lib/usage.d.ts

@@ -0,0 +1,32 @@
+import type { HarnessState, RefinementKind } from "./types.js";
+export interface UsageStore {
+    /** Injection count per entry key (`kind:id`). */
+    counts: Record<string, number>;
+}
+/** Load the usage store from disk; returns an empty store when absent or corrupt. */
+export declare function loadUsage(baseDir: string): UsageStore;
+/** Persist the usage store atomically. */
+export declare function saveUsage(baseDir: string, store: UsageStore): void;
+/** Build the usage key for an entry. */
+export declare function usageKey(kind: RefinementKind, id: string): string;
+/**
+ * Increment injection counts for the entries that were actually injected.
+ * Called after `entriesSectionText` renders the injected block. Keys not
+ * present in the store are initialized to 1; existing keys are incremented.
+ */
+export declare function recordInjection(baseDir: string, injectedKeys: string[]): void;
+/**
+ * Get the injection count for a specific entry. Returns 0 when the entry
+ * has never been injected (absent from the store).
+ */
+export declare function getUsageCount(store: UsageStore, kind: RefinementKind, id: string): number;
+/**
+ * Find entries with zero injection usage. Returns `{kind, id, title}` for
+ * each entry that has never been injected — prime candidates for archival.
+ */
+export declare function zeroUsageEntries(state: HarnessState, store: UsageStore): {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+}[];
+//# sourceMappingURL=usage.d.ts.map

package/lib/usage.js

@@ -0,0 +1,84 @@
+/**
+ * Entry usage tracking (gap B1): records how many times each entry has been
+ * injected into system prompts. The counts are durable (persisted to disk)
+ * and exposed in `evolve_list` and the gate's archive-candidate reporting,
+ * so "zero-usage stale entries" can be surfaced for cleanup.
+ *
+ * Storage: `<baseDir>/evolve/usage.json` — a flat JSON object mapping
+ * `kind:id` to an integer count. Reads are tolerant of missing/corrupt files;
+ * writes are atomic (tmp + rename).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const USAGE_FILE = "usage.json";
+function usagePath(baseDir) {
+    return join(baseDir, "evolve", USAGE_FILE);
+}
+/** Load the usage store from disk; returns an empty store when absent or corrupt. */
+export function loadUsage(baseDir) {
+    const path = usagePath(baseDir);
+    try {
+        if (!existsSync(path))
+            return { counts: {} };
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+            return { counts: raw };
+        }
+        return { counts: {} };
+    }
+    catch {
+        return { counts: {} };
+    }
+}
+/** Persist the usage store atomically. */
+export function saveUsage(baseDir, store) {
+    const dir = join(baseDir, "evolve");
+    mkdirSync(dir, { recursive: true });
+    const path = usagePath(baseDir);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(store.counts, null, 2)}\n`, "utf8");
+    renameSync(tmp, path);
+}
+/** Build the usage key for an entry. */
+export function usageKey(kind, id) {
+    return `${kind}:${id}`;
+}
+/**
+ * Increment injection counts for the entries that were actually injected.
+ * Called after `entriesSectionText` renders the injected block. Keys not
+ * present in the store are initialized to 1; existing keys are incremented.
+ */
+export function recordInjection(baseDir, injectedKeys) {
+    if (injectedKeys.length === 0)
+        return;
+    const store = loadUsage(baseDir);
+    for (const key of injectedKeys) {
+        store.counts[key] = (store.counts[key] ?? 0) + 1;
+    }
+    saveUsage(baseDir, store);
+}
+/**
+ * Get the injection count for a specific entry. Returns 0 when the entry
+ * has never been injected (absent from the store).
+ */
+export function getUsageCount(store, kind, id) {
+    return store.counts[usageKey(kind, id)] ?? 0;
+}
+/**
+ * Find entries with zero injection usage. Returns `{kind, id, title}` for
+ * each entry that has never been injected — prime candidates for archival.
+ */
+export function zeroUsageEntries(state, store) {
+    const results = [];
+    for (const kind of Object.keys(state.entries)) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (entry.scope !== "local")
+                continue;
+            if (getUsageCount(store, kind, entry.id) === 0) {
+                results.push({ kind, id: entry.id, title: entry.title });
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=usage.js.map

package/lib/validate.d.ts

@@ -4,8 +4,18 @@
  * the base system prompt, required fields per action, and the executable
  * contract skill entries must carry.
  */
-import type { RefinementEdit } from "./types.js";
+import type { HarnessScope, RefinementEdit } from "./types.js";
 export declare const BASE_SYSTEM_PROMPT_ID = "base_system_prompt";
+/**
+ * Gap C2: mechanical check that an edit's declared blast radius is coherent
+ * with the scope it targets. A session-scoped edit claiming "general" would
+ * silently read like a cross-project tactical rule; a global edit claiming
+ * "session" would contradict its persistence. Absent blastRadius is NOT
+ * rejected (pre-C2 data and manual edits stay compatible) — the planner is
+ * instructed to always declare it, and this rule catches what it declares
+ * incoherently.
+ */
+export declare function validateBlastRadiusScope(scope: HarnessScope, blastRadius: "general" | "project" | "session"): string | undefined;
 /** Returns a human-readable failure reason, or undefined when the edit passes. */
-export declare function validateEdit(edit: RefinementEdit, computedId: string | undefined): string | undefined;
+export declare function validateEdit(edit: RefinementEdit, computedId: string | undefined, scope?: HarnessScope): string | undefined;
 //# sourceMappingURL=validate.d.ts.map