@lmzhen/dsh-evolution-core 0.1.0-rc.14 → 0.1.0-rc.16

package/lib/index.js

@@ -215,6 +215,10 @@ const MAX_SKILL_CONTENT_CHARS = 1e5;
 const MAX_SKILL_FILE_BYTES = 1048576;
 const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
 const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
+/** Skill-review completion channel trigger mode: 'cadence' | 'completion' | 'both'. */
+const DEFAULT_SKILL_REVIEW_TRIGGER = "both";
+/** Cumulative session tool calls before a session counts as "proven long" for the completion channel. */
+const DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS = 20;
 const DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS = 3;
 const DEFAULT_SUBSTANTIVE_MIN_USER_CHARS = 200;
 const DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS = 500;
@@ -245,6 +249,47 @@ function buildCuratorRunReport(input) {
 		...input.snapshotPath === void 0 ? {} : { snapshotPath: input.snapshotPath }
 	};
 }
+const NOMINATION_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+* Parse the curator LLM's YAML nomination block (consolidations + prunings).
+* Line-oriented and lenient by design: the LLM output is advisory, every name
+* is re-validated against the tree before any file move happens downstream.
+*/
+function parseCuratorNominations(text) {
+	const prunings = [];
+	const consolidations = [];
+	let section = null;
+	let currentFrom = "";
+	for (const line of text.split("\n")) {
+		const consolidated = /^\s*-\s*from:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (consolidated) {
+			section = "consolidations";
+			currentFrom = consolidated[1] ?? "";
+			continue;
+		}
+		const into = /^\s*into:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (into) {
+			const intoName = into[1] ?? "";
+			if (section === "consolidations" && currentFrom !== "" && currentFrom !== intoName) consolidations.push({
+				from: currentFrom,
+				into: intoName
+			});
+			currentFrom = "";
+			continue;
+		}
+		const pruned = /^\s*-\s*name:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (pruned) {
+			section = "prunings";
+			const name = pruned[1];
+			if (name) prunings.push(name);
+		}
+	}
+	const valid = (name) => NOMINATION_NAME_RE.test(name);
+	return {
+		prunings: prunings.filter(valid),
+		consolidations: consolidations.filter((item) => valid(item.from) && valid(item.into))
+	};
+}
 function daysSince(iso, created, now) {
 	return (now - new Date(iso ?? created).getTime()) / 864e5;
 }
@@ -259,6 +304,7 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 		if (record.pinned) continue;
 		if (config.excludeSkillNames?.has(name)) continue;
 		if (config.suppressedNames?.has(name)) continue;
+		if (config.referencedSkillNames?.has(name)) continue;
 		const bundled = config.bundledNames?.has(name) === true;
 		if (!(record.created_by === "agent" || config.manageUnmanaged === true) && !(config.pruneBuiltins === true && bundled)) continue;
 		if (PROTECTED_BUILTIN_SKILLS.has(name)) continue;
@@ -882,6 +928,39 @@ var MemoryStore = class {
 	}
 };
 //#endregion
+//#region lib/types/mutations.js
+/**
+* Curator/author audit trail: `.mutations.json` records every skill mutation
+* with before/after content hashes so any automated edit is reviewable and
+* replayable. Best-effort persistence, mirroring the usage sidecar posture.
+* @module @lmzhen/dsh-evolution-core
+*/
+const DEFAULT_MUTATION_CAP = 500;
+function mutationsFile(root) {
+	return join(root, ".mutations.json");
+}
+function contentHash(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+async function loadMutations(root, io = nodeEvolutionIo()) {
+	const raw = await io.readText(mutationsFile(root));
+	if (raw === null) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.skillName === "string" && typeof entry.action === "string");
+	} catch {
+		return [];
+	}
+}
+/** Append one record, trim to `cap`, and write atomically. */
+async function recordMutation(root, io, record, cap = 500) {
+	const existing = await loadMutations(root, io);
+	existing.push(record);
+	const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
+	await io.writeText(mutationsFile(root), JSON.stringify(trimmed, null, 2));
+}
+//#endregion
 //#region lib/types/prompts.js
 /**
 * Review and curation prompts adapted from Hermes Agent
@@ -938,23 +1017,54 @@ Review the conversation above and update two things.
 **Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.
 
 Act on whichever dimension has real signal. If genuinely nothing stands out on either, say "Nothing to save." and stop — but don't reach for that conclusion as a default.`;
-const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library.
+const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
+
+The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
+
+Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
 
-Rules:
-1. NEVER hard-delete a skill. Archive is the maximum destructive action.
-2. Do not touch bundled, hub-installed, or pinned skills.
-3. Do not archive recently-created or never-used skills without strong evidence.
-4. Prefer merging narrow skills into class-level umbrellas.
-5. Before archiving a merged skill, ensure its unique content was preserved.
+Hard rules:
+1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
+2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (\`referenced\`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.
+3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet.
+4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
+5. Judge overlap on CONTENT, not on usage counters.
+6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
 
-Produce a YAML summary:
+How to work:
+1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword (expect 10-25 clusters).
+2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
+   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
+   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
+   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.
+3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
+
+Produce a YAML summary with exactly this shape:
 consolidations:
   - from: <old-skill-name>
     into: <umbrella-skill-name>
     reason: <one short sentence>
 prunings:
   - name: <skill-name>
-    reason: <one short sentence>`;
+    reason: <one short sentence>
+Nominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).`;
+const CURATOR_DRY_RUN_BANNER = `═══════════════════════════════════════════════════════════════
+DRY-RUN — REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.
+═══════════════════════════════════════════════════════════════
+
+This is a PREVIEW pass. Follow every instruction above EXCEPT:
+  • Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.
+  • Do NOT move, copy, or rewrite any file under the skills tree.
+
+Your output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.
+
+If you accidentally take a mutating action, say so explicitly in the summary.`;
+const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
+Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
+
+Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch skills loaded this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
+
+Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
 function reviewPrompt(kind) {
 	if (kind === "memory") return MEMORY_REVIEW_PROMPT;
 	if (kind === "skill") return SKILL_REVIEW_PROMPT;
@@ -980,7 +1090,8 @@ const PROMPT_BUNDLE = createPromptBundle({
 	memory: MEMORY_REVIEW_PROMPT,
 	skill: SKILL_REVIEW_PROMPT,
 	combined: COMBINED_REVIEW_PROMPT,
-	curator: CURATOR_PROMPT
+	curator: CURATOR_PROMPT,
+	completion: COMPLETION_SKILL_REVIEW_PROMPT
 });
 function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
 	const canonical = JSON.stringify({
@@ -1021,6 +1132,143 @@ Quality bar:
 - No router/index/hub skills that only point at other skills.
 - References go in \`references/\`, templates in \`templates/\`.`;
 //#endregion
+//#region lib/types/quality.js
+/**
+* Quality scoring and near-duplicate detection for the curated skill library.
+*
+* Pure functions over data inputs so the scoring policy is unit-testable and
+* the same math feeds the usage sidecar, the `skill_manage review` surface and
+* the learning graph. Weights follow the Hermes/hermes-claw six-factor model;
+* mutation maturity is a documented DSH approximation (single per-month patch
+* trend ratio replaces the claw timestamp-trend formula, since DSH usage
+* records only carry the last patched timestamp).
+* @module @lmzhen/dsh-evolution-core
+*/
+const QUALITY_WEIGHTS = {
+	usageFrequency: .25,
+	stability: .2,
+	recency: .2,
+	references: .1,
+	mutationMaturity: .2,
+	richness: .05
+};
+/** Score below which a skill is flagged for review. */
+const LOW_QUALITY_THRESHOLD = .3;
+function clamp01(value) {
+	return Math.max(0, Math.min(1, value));
+}
+function daysBetween(from, now) {
+	return Math.max(0, (now.getTime() - new Date(from).getTime()) / 864e5);
+}
+function computeQualityScores(input) {
+	const now = input.now ?? /* @__PURE__ */ new Date();
+	const scores = /* @__PURE__ */ new Map();
+	for (const [name, record] of input.usage) {
+		const ageDays = Math.max(1, daysBetween(record.created_at, now));
+		const idleDays = daysBetween(latestActivityAt(record) ?? record.created_at, now);
+		const patchCount = record.patch_count;
+		const useCount = record.use_count;
+		const usageFrequency = clamp01(useCount / ageDays);
+		const stability = useCount === 0 ? 1 : clamp01(1 - patchCount / useCount);
+		const recency = idleDays < 30 ? 1 : clamp01(1 - (idleDays - 30) / 150);
+		const references = clamp01((input.referenceCounts?.get(name) ?? 0) / 3);
+		const mutationMaturity = patchCount === 0 ? .3 : patchCount === 1 ? .4 : clamp01((patchCount - 1) / Math.max(1, ageDays / 30));
+		const richness = clamp01((input.supportDirs?.get(name) ?? 0) * .175);
+		const factors = {
+			usageFrequency,
+			stability,
+			recency,
+			references,
+			mutationMaturity,
+			richness
+		};
+		const score = usageFrequency * QUALITY_WEIGHTS.usageFrequency + stability * QUALITY_WEIGHTS.stability + recency * QUALITY_WEIGHTS.recency + references * QUALITY_WEIGHTS.references + mutationMaturity * QUALITY_WEIGHTS.mutationMaturity + richness * QUALITY_WEIGHTS.richness;
+		scores.set(name, {
+			score,
+			factors,
+			warn: score < LOW_QUALITY_THRESHOLD
+		});
+	}
+	return scores;
+}
+function normalize(content) {
+	return content.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function contentHash$1(content) {
+	return createHash("sha256").update(normalize(content)).digest("hex");
+}
+function tokenize(content) {
+	return new Set(normalize(content).split(/[^a-z0-9\u4e00-\u9fff]+/).filter(Boolean));
+}
+function jaccard(a, b) {
+	if (a.size === 0 || b.size === 0) return 0;
+	let intersection = 0;
+	for (const token of a) if (b.has(token)) intersection += 1;
+	return intersection / (a.size + b.size - intersection);
+}
+/**
+* Two-phase near-duplicate clustering: exact normalized-hash groups first,
+* then token-Jaccard edges at {@link DEDUP_SIMILARITY_THRESHOLD} with a token
+* ratio guard, union-find across the whole set.
+*/
+function computeDedupGroups(input) {
+	const threshold = input.threshold ?? .95;
+	const names = [...input.contents.keys()];
+	const hashes = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const hash = contentHash$1(input.contents.get(name) ?? "");
+		const bucket = hashes.get(hash);
+		if (bucket) bucket.push(name);
+		else hashes.set(hash, [name]);
+	}
+	const parent = /* @__PURE__ */ new Map();
+	const find = (x) => {
+		const root = parent.get(x) ?? x;
+		if (root !== x) parent.set(x, find(root));
+		return parent.get(x) ?? x;
+	};
+	const union = (a, b) => {
+		const [ra, rb] = [find(a), find(b)];
+		if (ra !== rb) parent.set(rb, ra);
+	};
+	for (const [hash, bucketNames] of hashes) {
+		const first = bucketNames[0];
+		if (first === void 0 || bucketNames.length === 1) continue;
+		for (let index = 1; index < bucketNames.length; index += 1) {
+			const peer = bucketNames[index];
+			if (peer) union(first, peer);
+		}
+	}
+	const tokens = /* @__PURE__ */ new Map();
+	const tokenSet = (name) => {
+		let set = tokens.get(name);
+		if (!set) {
+			set = tokenize(input.contents.get(name) ?? "");
+			tokens.set(name, set);
+		}
+		return set;
+	};
+	for (let index = 0; index < names.length; index += 1) {
+		const a = names[index];
+		if (a === void 0) continue;
+		for (let other = index + 1; other < names.length; other += 1) {
+			const b = names[other];
+			if (b === void 0) continue;
+			const [ta, tb] = [tokenSet(a), tokenSet(b)];
+			if (Math.max(ta.size, tb.size) / Math.max(1, Math.min(ta.size, tb.size)) > 5) continue;
+			if (jaccard(ta, tb) >= threshold) union(a, b);
+		}
+	}
+	const groups = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const root = find(name);
+		const group = groups.get(root);
+		if (group) group.push(name);
+		else groups.set(root, [name]);
+	}
+	return [...groups.values()].filter((group) => group.length > 1);
+}
+//#endregion
 //#region lib/types/signals.js
 /**
 * Deterministic review signal gate.
@@ -1236,6 +1484,41 @@ var SkillLibrary = class {
 		const dir = skillDir(this.root, name);
 		return await this.io.exists(markerPath(dir, "bundled"));
 	}
+	/** Count non-empty support subdirectories (richness input for quality scoring). */
+	async countSupportDirs(name) {
+		const dir = skillDir(this.root, name);
+		let entries;
+		try {
+			entries = await this.io.list(dir);
+		} catch {
+			return 0;
+		}
+		let count = 0;
+		for (const subdir of SUPPORT_DIRS) {
+			if (!entries.includes(subdir)) continue;
+			try {
+				if ((await this.io.list(join(dir, subdir))).some((file) => file !== ".gitkeep")) count += 1;
+			} catch {}
+		}
+		return count;
+	}
+	/** Best-effort audit trail entry; never blocks the mutation. */
+	async audit(skillName, action, before, after, summary) {
+		try {
+			await recordMutation(this.root, this.io, {
+				skillName,
+				action,
+				...before === null ? {} : { beforeHash: contentHash(before) },
+				...after === null ? {} : { afterHash: contentHash(after) },
+				summary,
+				at: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		} catch {}
+	}
+	/** Recent mutation audit records (read-only inspection surface). */
+	async listMutations() {
+		return await loadMutations(this.root, this.io);
+	}
 	async create(name, content, origin) {
 		const normalized = name.trim();
 		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return {
@@ -1259,6 +1542,7 @@ var SkillLibrary = class {
 		};
 		await this.io.writeText(join(dir, "SKILL.md"), content.trimEnd() + "\n");
 		if (origin === "background_review") await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+		await this.audit(normalized, "create", null, content, "created");
 		return {
 			ok: true,
 			message: `Skill "${normalized}" created.`,
@@ -1267,7 +1551,8 @@ var SkillLibrary = class {
 	}
 	async update(name, content, origin = "foreground") {
 		const dir = skillDir(this.root, name);
-		if (!await this.io.readText(join(dir, "SKILL.md"))) return {
+		const md = await this.io.readText(join(dir, "SKILL.md"));
+		if (!md) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
@@ -1287,6 +1572,7 @@ var SkillLibrary = class {
 			message: threat
 		};
 		await this.io.writeText(join(dir, "SKILL.md"), content.trimEnd() + "\n");
+		await this.audit(name, "update", md, content, "updated");
 		return {
 			ok: true,
 			message: `Skill "${name}" updated.`,
@@ -1347,6 +1633,7 @@ var SkillLibrary = class {
 			message: threat
 		};
 		await this.io.writeText(target, patched.trimEnd() + "\n");
+		await this.audit(name, "patch", md, patched, `patched ${patchLabel}`);
 		return {
 			ok: true,
 			message: `Skill "${name}" patched (${patchLabel}).`,
@@ -1355,7 +1642,8 @@ var SkillLibrary = class {
 	}
 	async archive(name, options = {}) {
 		const dir = skillDir(this.root, name);
-		if (!await this.io.readText(join(dir, "SKILL.md"))) return {
+		const md = await this.io.readText(join(dir, "SKILL.md"));
+		if (!md) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
@@ -1381,6 +1669,7 @@ var SkillLibrary = class {
 		}
 		const reason = options.reason ?? (options.absorbedInto ? `Consolidated into ${options.absorbedInto}` : "Archived by self-evolution curator");
 		await this.io.writeText(join(dest, ".archive-reason"), `${(/* @__PURE__ */ new Date()).toISOString()}: ${reason}\n`);
+		await this.audit(name, "archive", md, null, reason);
 		return {
 			ok: true,
 			message: `Skill "${name}" archived to .archive.`,
@@ -1535,7 +1824,9 @@ var SkillLibrary = class {
 			message: threat
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
+		const existing = await this.io.readText(target).catch(() => null);
 		await this.io.writeText(target, content);
+		await this.audit(name, "write_file", existing, content, `wrote ${filePath}`);
 		return {
 			ok: true,
 			message: `Support file "${filePath}" written to "${name}".`,
@@ -1563,7 +1854,9 @@ var SkillLibrary = class {
 			ok: false,
 			message: `File "${filePath}" not found in skill "${name}".`
 		};
+		const before = await this.io.readText(target).catch(() => null);
 		await this.io.remove(target);
+		await this.audit(name, "remove_file", before, null, `removed ${filePath}`);
 		return {
 			ok: true,
 			message: `Support file "${filePath}" removed from "${name}".`,
@@ -1691,4 +1984,4 @@ var JsonState = class JsonState {
 	}
 };
 //#endregion
-export { COMBINED_REVIEW_PROMPT, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROTECTED_BUILTIN_SKILLS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SkillLibrary, advanceReview, buildCuratorRunReport, bumpPatch, bumpUse, bumpView, computeLifecycleTransitions, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, nodeEvolutionIo, observeEvent, parseFrontmatter, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };
+export { COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SkillLibrary, advanceReview, buildCuratorRunReport, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };

package/lib/types/constants.d.ts

@@ -33,6 +33,10 @@ export declare const MAX_SKILL_CONTENT_CHARS = 100000;
 export declare const MAX_SKILL_FILE_BYTES = 1048576;
 export declare const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
 export declare const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
+/** Skill-review completion channel trigger mode: 'cadence' | 'completion' | 'both'. */
+export declare const DEFAULT_SKILL_REVIEW_TRIGGER: "both";
+/** Cumulative session tool calls before a session counts as "proven long" for the completion channel. */
+export declare const DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS = 20;
 export declare const DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS = 3;
 export declare const DEFAULT_SUBSTANTIVE_MIN_USER_CHARS = 200;
 export declare const DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS = 500;

package/lib/types/curator.d.ts

@@ -19,6 +19,8 @@ export interface CuratorConfig {
     bundledNames?: ReadonlySet<string>;
     /** Skill names the curator archived once and must not fight across re-seeds. */
     suppressedNames?: ReadonlySet<string>;
+    /** Skills referenced by scheduled/automated jobs: never auto-transitioned (idle clocks mislead for rarely-firing tasks). */
+    referencedSkillNames?: ReadonlySet<string>;
 }
 export interface CuratorTransition {
     name: string;
@@ -64,5 +66,21 @@ export interface CuratorReportInput {
     snapshotPath?: string;
 }
 export declare function buildCuratorRunReport(input: CuratorReportInput): CuratorRunReport;
+/** One LLM-nominated consolidation: `from` merges into the umbrella `into`. */
+export interface CuratorConsolidation {
+    from: string;
+    into: string;
+}
+/** Structured result of the optional curator LLM nomination pass. */
+export interface CuratorNominations {
+    prunings: string[];
+    consolidations: CuratorConsolidation[];
+}
+/**
+ * Parse the curator LLM's YAML nomination block (consolidations + prunings).
+ * Line-oriented and lenient by design: the LLM output is advisory, every name
+ * is re-validated against the tree before any file move happens downstream.
+ */
+export declare function parseCuratorNominations(text: string): CuratorNominations;
 export declare function computeLifecycleTransitions(usage: UsageMap, config: CuratorConfig, now?: Date): CuratorResult;
 //# sourceMappingURL=curator.d.ts.map

package/lib/types/index.d.ts

@@ -11,7 +11,9 @@ export * from './curator.ts';
 export * from './events.ts';
 export * from './io.ts';
 export * from './memory-store.ts';
+export * from './mutations.ts';
 export * from './prompts.ts';
+export * from './quality.ts';
 export * from './signals.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';

package/lib/types/mutations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Curator/author audit trail: `.mutations.json` records every skill mutation
+ * with before/after content hashes so any automated edit is reviewable and
+ * replayable. Best-effort persistence, mirroring the usage sidecar posture.
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+import { type EvolutionIoLike } from './io.ts';
+export interface MutationRecord {
+    skillName: string;
+    action: string;
+    beforeHash?: string;
+    afterHash?: string;
+    summary: string;
+    at: string;
+}
+export declare const DEFAULT_MUTATION_CAP = 500;
+export declare function mutationsFile(root: string): string;
+export declare function contentHash(content: string): string;
+export declare function loadMutations(root: string, io?: EvolutionIoLike): Promise<MutationRecord[]>;
+/** Append one record, trim to `cap`, and write atomically. */
+export declare function recordMutation(root: string, io: EvolutionIoLike, record: MutationRecord, cap?: number): Promise<void>;
+//# sourceMappingURL=mutations.d.ts.map

package/lib/types/prompts.d.ts

@@ -2,7 +2,9 @@ export declare const PROMPT_BUNDLE_ID = "dsh-evolution@1";
 export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
 export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 most sessions produce at least one skill update, even if small.\n\nTarget shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.\n\nSignals that warrant action:\n- The user corrected your style, tone, format, verbosity, workflow, or approach.\n- A non-trivial technique, fix, workaround, or debugging path emerged.\n- A loaded skill turned out wrong, missing, or outdated \u2014 patch it now.\n\nPreference order:\n1. Patch a skill that was loaded or read this session.\n2. Patch an existing umbrella skill.\n3. Add references/, templates/, or scripts/ support under an existing skill.\n4. Create a new class-level umbrella skill only when nothing fits.\n\nProtected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.\n\nDo NOT capture:\n- Environment-dependent failures (missing binaries, unconfigured credentials).\n- Negative claims about tools (\"browser tools do not work\").\n- Transient errors that resolved during the session.\n- One-off task narratives.\n\nIf a tool failed because of setup state, capture the FIX under an existing setup skill \u2014 never \"this tool does not work\" as a standalone constraint.\n\n\"Nothing to save.\" is a real option but should NOT be the default.";
 export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things.\n\n**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.\n\n**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.\n\nAct on whichever dimension has real signal. If genuinely nothing stands out on either, say \"Nothing to save.\" and stop \u2014 but don't reach for that conclusion as a default.";
-export declare const CURATOR_PROMPT = "You are the skill curator. Maintain a healthy, class-level skill library.\n\nRules:\n1. NEVER hard-delete a skill. Archive is the maximum destructive action.\n2. Do not touch bundled, hub-installed, or pinned skills.\n3. Do not archive recently-created or never-used skills without strong evidence.\n4. Prefer merging narrow skills into class-level umbrellas.\n5. Before archiving a merged skill, ensure its unique content was preserved.\n\nProduce a YAML summary:\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence>";
+export declare const CURATOR_PROMPT = "You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.\n\nThe goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.\n\nRight target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.\n\nHard rules:\n1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.\n2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (`referenced`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.\n3. Do not archive recently-created or never-used skills without strong evidence. \"use=0\" is NOT evidence either way \u2014 it only means the trigger has not come up yet.\n4. Do NOT reject consolidation on the grounds that \"each skill has a distinct trigger\". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.\n5. Judge overlap on CONTENT, not on usage counters.\n6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.\n\nHow to work:\n1. Scan the candidate list. Identify PREFIX CLUSTERS \u2014 skills sharing a first word or domain keyword (expect 10-25 clusters).\n2. For each cluster with 2+ members, ask \"what is the UMBRELLA CLASS these skills serve?\" and consolidate:\n   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).\n   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.\n   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.\n3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.\n\nProduce a YAML summary with exactly this shape:\nconsolidations:\n  - from: <old-skill-name>\n    into: <umbrella-skill-name>\n    reason: <one short sentence>\nprunings:\n  - name: <skill-name>\n    reason: <one short sentence>\nNominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).";
+export declare const CURATOR_DRY_RUN_BANNER = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\nDRY-RUN \u2014 REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\nThis is a PREVIEW pass. Follow every instruction above EXCEPT:\n  \u2022 Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.\n  \u2022 Do NOT move, copy, or rewrite any file under the skills tree.\n\nYour output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.\n\nIf you accidentally take a mutating action, say so explicitly in the summary.";
+export declare const COMPLETION_SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills \u00B7 task complete]\nYour current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.\n\nFollow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch skills loaded this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.\n\nDo NOT modify output files or re-run the task. If you are still mid-task, ignore this.";
 export declare function reviewPrompt(kind: 'memory' | 'skill' | 'combined'): string;
 export interface PromptBundle {
     id: string;

package/lib/types/quality.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Quality scoring and near-duplicate detection for the curated skill library.
+ *
+ * Pure functions over data inputs so the scoring policy is unit-testable and
+ * the same math feeds the usage sidecar, the `skill_manage review` surface and
+ * the learning graph. Weights follow the Hermes/hermes-claw six-factor model;
+ * mutation maturity is a documented DSH approximation (single per-month patch
+ * trend ratio replaces the claw timestamp-trend formula, since DSH usage
+ * records only carry the last patched timestamp).
+ * @module @deepseek-ai/dsh-evolution-core
+ */
+import type { UsageMap } from './usage.ts';
+export interface QualityFactors {
+    /** 0.25 — use_count per day of age, capped at 1. */
+    usageFrequency: number;
+    /** 0.20 — 1 − patch/use (zero use = stable). */
+    stability: number;
+    /** 0.20 — 1 under 30 idle days, linear decay to 0 at 180. */
+    recency: number;
+    /** 0.10 — in-degree / 3 (graph references), capped at 1. */
+    references: number;
+    /** 0.20 — patch cadence maturity (DSH approximation of the trend formula). */
+    mutationMaturity: number;
+    /** 0.05 — non-empty support subdirectories × 0.175, capped at 1. */
+    richness: number;
+}
+export interface QualityScore {
+    score: number;
+    factors: QualityFactors;
+    warn: boolean;
+}
+export declare const QUALITY_WEIGHTS: {
+    readonly usageFrequency: 0.25;
+    readonly stability: 0.2;
+    readonly recency: 0.2;
+    readonly references: 0.1;
+    readonly mutationMaturity: 0.2;
+    readonly richness: 0.05;
+};
+/** Score below which a skill is flagged for review. */
+export declare const LOW_QUALITY_THRESHOLD = 0.3;
+export declare function computeQualityScores(input: {
+    usage: UsageMap;
+    referenceCounts?: ReadonlyMap<string, number>;
+    supportDirs?: ReadonlyMap<string, number>;
+    now?: Date;
+}): Map<string, QualityScore>;
+/**
+ * Two-phase near-duplicate clustering: exact normalized-hash groups first,
+ * then token-Jaccard edges at {@link DEDUP_SIMILARITY_THRESHOLD} with a token
+ * ratio guard, union-find across the whole set.
+ */
+export declare function computeDedupGroups(input: {
+    contents: ReadonlyMap<string, string>;
+    threshold?: number;
+}): string[][];
+//# sourceMappingURL=quality.d.ts.map

package/lib/types/skill-store.d.ts

@@ -7,6 +7,7 @@
  * move to `.archive/` — never a hard delete.
  */
 import { type EvolutionIoLike } from './io.ts';
+import { type MutationRecord } from './mutations.ts';
 export interface SkillLimits {
     maxNameLength: number;
     maxDescriptionLength: number;
@@ -63,6 +64,12 @@ export declare class SkillLibrary {
     isManaged(name: string): Promise<boolean>;
     /** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
     isBundled(name: string): Promise<boolean>;
+    /** Count non-empty support subdirectories (richness input for quality scoring). */
+    countSupportDirs(name: string): Promise<number>;
+    /** Best-effort audit trail entry; never blocks the mutation. */
+    private audit;
+    /** Recent mutation audit records (read-only inspection surface). */
+    listMutations(): Promise<MutationRecord[]>;
     create(name: string, content: string, origin: 'foreground' | 'background_review'): Promise<SkillActionResult>;
     update(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     patch(name: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.1.0-rc.14",
+  "version": "0.1.0-rc.16",
   "publishConfig": {
     "access": "public"
   },