dsh-continual-evolve 0.1.0 → 0.2.0

package/lib/score.js

@@ -1,8 +1,22 @@
-export const DEFAULT_AGGREGATE = { passThreshold: 60, regressionTolerance: 0 };
-/** Aggregate raw cells into code-owned per-case means + overall mean. */
+export const DEFAULT_AGGREGATE = {
+    passThreshold: 60,
+    regressionTolerance: 0,
+    maxFailedCells: 0,
+};
+/**
+ * Aggregate raw cells into code-owned per-case means + overall mean.
+ * Failure-cell protocol (gap A2): failed cells are EXCLUDED from means and
+ * counted separately — a crashed unit can never silently drag the mean down
+ * like a zero. A case whose cells all failed reports null (no mean).
+ */
 export function aggregate(cells) {
     const byCase = new Map();
+    let failed = 0;
     for (const cell of cells) {
+        if (cell.status === "failed") {
+            failed += 1;
+            continue;
+        }
         const list = byCase.get(cell.caseId) ?? [];
         list.push(clampScore(cell.score));
         byCase.set(cell.caseId, list);
@@ -12,7 +26,12 @@ export function aggregate(cells) {
         perCase[caseId] = mean(scores);
     }
     const all = [...byCase.values()].flat();
-    return { ...perCase, overall: all.length > 0 ? mean(all) : null };
+    return {
+        ...perCase,
+        overall: all.length > 0 ? mean(all) : null,
+        failed,
+        total: cells.length,
+    };
 }
 export function entryFromCells(label, cells, refinementId) {
     const aggr = aggregate(cells);
@@ -29,31 +48,53 @@ export function entryFromCells(label, cells, refinementId) {
 export function decisionReport(reference, candidate, decision) {
     const lines = [`overall: ${reference.overall ?? "?"} → ${candidate.overall ?? "?"}`];
     for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
-        if (caseId === "overall" || refScore === null)
+        if (caseId === "overall" || caseId === "failed" || caseId === "total" || refScore === null)
             continue;
         const candScore = candidate.aggregate[caseId];
-        lines.push(`  ${caseId}: ${refScore} → ${candScore ?? "?"}`);
+        const failedMark = isCaseFailed(reference, caseId) || isCaseFailed(candidate, caseId) ? " (failed)" : "";
+        lines.push(`  ${caseId}: ${refScore} → ${candScore ?? "?"}${failedMark}`);
+    }
+    const refFailed = reference.aggregate.failed ?? 0;
+    const candFailed = candidate.aggregate.failed ?? 0;
+    if (refFailed > 0 || candFailed > 0) {
+        lines.push(`failed cells: reference ${refFailed}/${reference.aggregate.total ?? 0} · candidate ${candFailed}/${candidate.aggregate.total ?? 0}`);
     }
     lines.push(decision.accepted
         ? "DECISION: ACCEPTED — overall improved, no regression"
         : `DECISION: REJECTED — ${decision.reasons.join("; ")}`);
     return lines;
 }
+function isCaseFailed(entry, caseId) {
+    return entry.cells.some((cell) => cell.caseId === caseId && cell.status === "failed");
+}
 /**
  * Non-regressive acceptance rule (Self-Harness style):
  * the candidate is accepted iff its overall mean is STRICTLY higher than the
- * reference AND no case regresses by more than `regressionTolerance` points.
+ * reference, no case regresses by more than `regressionTolerance` points,
+ * and neither side has more failed cells than `maxFailedCells` (failure-cell
+ * protocol, gap A2 — a partial/invalid round is never accepted).
  */
 export function decide(reference, candidate, opts) {
     const reasons = [];
     if (reference.overall === null || candidate.overall === null) {
         return { accepted: false, reasons: ["reference or candidate evaluation is incomplete"] };
     }
+    const refFailed = reference.aggregate.failed ?? 0;
+    const candFailed = candidate.aggregate.failed ?? 0;
+    if (refFailed > opts.maxFailedCells) {
+        reasons.push(`reference has ${refFailed} failed cells (max ${opts.maxFailedCells})`);
+    }
+    if (candFailed > opts.maxFailedCells) {
+        reasons.push(`candidate has ${candFailed} failed cells (max ${opts.maxFailedCells})`);
+    }
+    if (reasons.length > 0) {
+        return { accepted: false, reasons };
+    }
     if (candidate.overall <= reference.overall) {
         reasons.push(`overall not improved: ${candidate.overall} <= ${reference.overall}`);
     }
     for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
-        if (caseId === "overall" || refScore === null)
+        if (caseId === "overall" || caseId === "failed" || caseId === "total" || refScore === null)
             continue;
         const candScore = candidate.aggregate[caseId];
         if (candScore === null || candScore === undefined) {

package/lib/skill.d.ts

@@ -5,6 +5,14 @@ export declare function skillNameOf(id: string): string;
 export declare function skillDir(skillsRoot: string, id: string): string;
 /** Render a harness skill entry as a discoverable SKILL.md document. */
 export declare function renderSkillMarkdown(entry: HarnessEntry): string;
-/** Apply the skill-kind edits of an applied refinement to the skills root. */
-export declare function syncSkillsFromResult(skillsRoot: string, result: RefinementResult): void;
+/**
+ * Apply the skill-kind edits of an applied refinement to the skills root.
+ * Returns materialization warnings (rendered-SKILL.md mechanical problems
+ * and dangling resource references) — the file is still written, but the
+ * caller should surface them: a rendered file that fails the platform's
+ * frontmatter rules would be IGNORED by the skill loader, and a body
+ * referencing resources the entry does not ship would load with broken
+ * links.
+ */
+export declare function syncSkillsFromResult(skillsRoot: string, result: RefinementResult): string[];
 //# sourceMappingURL=skill.d.ts.map

package/lib/skill.js

@@ -9,6 +9,7 @@
  */
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+import { skillResourceRefs, validateRenderedSkill } from "./skillquality.js";
 /** Convert a harness entry id (underscore slug) to a kebab-case skill name. */
 export function skillNameOf(id) {
     return id.toLowerCase().replace(/_/g, "-");
@@ -44,8 +45,17 @@ export function renderSkillMarkdown(entry) {
     }
     return `${lines.join("\n").trimEnd()}\n`;
 }
-/** Apply the skill-kind edits of an applied refinement to the skills root. */
+/**
+ * Apply the skill-kind edits of an applied refinement to the skills root.
+ * Returns materialization warnings (rendered-SKILL.md mechanical problems
+ * and dangling resource references) — the file is still written, but the
+ * caller should surface them: a rendered file that fails the platform's
+ * frontmatter rules would be IGNORED by the skill loader, and a body
+ * referencing resources the entry does not ship would load with broken
+ * links.
+ */
 export function syncSkillsFromResult(skillsRoot, result) {
+    const warnings = [];
     for (const edit of result.appliedEdits) {
         if (edit.kind !== "skill" || !edit.applied)
             continue;
@@ -53,15 +63,37 @@ export function syncSkillsFromResult(skillsRoot, result) {
             removeSkill(skillsRoot, edit.id);
             continue;
         }
-        writeSkill(skillsRoot, edit.after);
+        warnings.push(...writeSkill(skillsRoot, edit.after));
     }
+    return warnings;
 }
+/** Write one skill entry as a SKILL.md; returns materialization warnings. */
 function writeSkill(skillsRoot, entry) {
     const dir = skillDir(skillsRoot, entry.id);
     mkdirSync(dir, { recursive: true });
     const temp = join(dir, `SKILL.md.${process.pid}.tmp`);
     writeFileSync(temp, renderSkillMarkdown(entry), "utf8");
     renameSync(temp, join(dir, "SKILL.md"));
+    return materializationWarnings(dir, entry);
+}
+/** Post-write checks on the exact file that landed on disk. */
+function materializationWarnings(dir, entry) {
+    const warnings = [];
+    for (const problem of validateRenderedSkill(entry)) {
+        warnings.push(`skill ${entry.id}: rendered SKILL.md would be ignored by the platform: ${problem}`);
+    }
+    const root = resolve(dir);
+    for (const ref of skillResourceRefs(entry.content)) {
+        const target = resolve(root, ref);
+        if (target !== root && !target.startsWith(`${root}${sep}`)) {
+            warnings.push(`skill ${entry.id}: body resource reference escapes the skill directory: ${ref}`);
+            continue;
+        }
+        if (!existsSync(target)) {
+            warnings.push(`skill ${entry.id}: body references missing resource ${ref} (expected at ${target})`);
+        }
+    }
+    return warnings;
 }
 function removeSkill(skillsRoot, id) {
     const dir = skillDir(skillsRoot, id);

package/lib/skillquality.d.ts

@@ -0,0 +1,81 @@
+import type { HarnessEntry } from "./types.js";
+import { skillNameOf } from "./skill.js";
+/** Relative location of the skill-creator template facts. */
+export declare const SKILL_CREATOR_TEMPLATE_REL: string;
+/**
+ * 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 declare function readSkillCreatorTemplate(skillsRoot: string): string | 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 declare 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):\n\nFrontmatter schema (platform-enforced; violations make the platform IGNORE the whole file):\n- name: required, kebab-case only (^[a-z0-9]+(?:-[a-z0-9]+)*$)\n- description: required, non-empty; write \"use when / do not use when\" routing so the model can select it correctly\n- invocation booleans accept true/false/yes/no/on/off/1/0; legacy camelCase keys (disableModelInvocation / modelInvocable / userInvocable) are rejected\n- whenToUse (optional): non-empty string; metadata (optional): object\n\nThe 7 structural features of the official deepseek-harness skills:\n1. Frontmatter is routing metadata, not a summary (description = when to use / when not to use)\n2. Opens with a boundary declaration (guidance, not a script; mechanical flow skills may omit the disclaimer)\n3. Prerequisites + exclusions: explicit required input, stop when missing (report the required input and stop), excluded scenarios\n4. Layered information: Sources of truth (link only, do not re-summarize) -> numbered blocking requirements -> manual checks -> verification commands -> report format; all executable, no slogans\n5. Skill interlinks: reference a single source of truth instead of duplicating it\n6. Verifiable completion criteria: explicit verification commands and report format\n7. Real use + iteration: a real trigger scenario must exist; calibration conclusions distill into references/\n\nParagraph skeleton (writing order): frontmatter -> H1 + boundary declaration -> Sources of truth -> numbered requirements / workflow (full commands) -> exclusions / stop conditions -> verification and report.\n\nCreation rules: only create a skill for a REAL trigger scenario (who, in what real task, what signal) grounded in the trajectory \u2014 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).";
+export interface SkillQualityGuide {
+    /** Where the guide text came from: the on-disk template or the builtin guide. */
+    source: "template" | "builtin";
+    text: string;
+}
+/**
+ * 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 declare function skillQualityGuide(skillsRoot: string | undefined): SkillQualityGuide;
+/** Split frontmatter out of a raw SKILL.md. Returns { yaml, body } or null when delimiters are missing. */
+export declare function splitFrontmatter(raw: string): {
+    yaml: string;
+    body: string;
+} | null;
+/**
+ * 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 declare function validateRenderedSkillMarkdown(markdown: string): string[];
+/**
+ * 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 declare function validateSkillEntryContent(content: string): string[];
+/**
+ * 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 declare function validateRenderedSkill(entry: HarnessEntry): string[];
+/**
+ * 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 declare function skillResourceRefs(content: string): string[];
+/** Kebab-case name under which the entry materializes (exported for diagnostics). */
+export { skillNameOf };
+//# sourceMappingURL=skillquality.d.ts.map

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, skillNameOf } from "./skill.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 };
+//# sourceMappingURL=skillquality.js.map

package/lib/tool.js

@@ -37,14 +37,15 @@ export function registerEvolveTools(ctx, engine, opts) {
     }));
     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 +65,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)

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,6 +120,8 @@ 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;
 }