@lmzhen/dsh-evolution-core 0.1.0-rc.15 → 0.1.0-rc.17

package/lib/index.js

@@ -928,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
@@ -1099,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.
@@ -1314,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 {
@@ -1337,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.`,
@@ -1345,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.`
 		};
@@ -1365,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.`,
@@ -1425,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}).`,
@@ -1433,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.`
 		};
@@ -1459,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.`,
@@ -1613,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}".`,
@@ -1641,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}".`,
@@ -1769,4 +1984,4 @@ var JsonState = class JsonState {
 	}
 };
 //#endregion
-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_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, 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, parseCuratorNominations, 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/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/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.15",
+  "version": "0.1.0-rc.17",
   "publishConfig": {
     "access": "public"
   },