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

package/lib/index.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 import z from "@deepseek-ai/schemastery";
-import { CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, SkillLibrary, buildCuratorRunReport, computeLifecycleTransitions, emptyRecord, evolutionHome, evolutionIoAdapter, loadSuppressedNames, loadUsage, saveSuppressedNames, saveUsage } from "@lmzhen/dsh-evolution-core";
+import { CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MIN_IDLE_HOURS, DEFAULT_STALE_AFTER_DAYS, SkillLibrary, buildCuratorRunReport, computeLifecycleTransitions, computeQualityScores, emptyRecord, evolutionHome, evolutionIoAdapter, loadSuppressedNames, loadUsage, parseCuratorNominations, saveSuppressedNames, saveUsage } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
@@ -23,6 +23,8 @@ var EvolutionCurator = class extends Service {
 		excludeSkillNames: z.array(z.string()).default([]),
 		manageUnmanaged: z.boolean().default(false),
 		pruneBuiltins: z.boolean().default(false),
+		referencedSkillNames: z.array(z.string()).default([]),
+		autoStart: z.boolean().default(true),
 		curatorReviewMaxTokens: z.number().default(2048)
 	});
 	skills;
@@ -38,6 +40,7 @@ var EvolutionCurator = class extends Service {
 	excludeSkillNames;
 	manageUnmanaged;
 	pruneBuiltins;
+	referencedSkillNames;
 	curatorReviewMaxTokens;
 	lastRun = 0;
 	timer;
@@ -56,6 +59,7 @@ var EvolutionCurator = class extends Service {
 		this.excludeSkillNames = new Set(config.excludeSkillNames ?? []);
 		this.manageUnmanaged = config.manageUnmanaged ?? false;
 		this.pruneBuiltins = config.pruneBuiltins ?? false;
+		this.referencedSkillNames = new Set(config.referencedSkillNames ?? []);
 		this.curatorReviewMaxTokens = config.curatorReviewMaxTokens ?? 2048;
 		this.lastRun = Date.now();
 		this.ctx.effect(() => {
@@ -63,6 +67,7 @@ var EvolutionCurator = class extends Service {
 				this.stop();
 			};
 		}, "evolution-curator.stop");
+		if (config.autoStart ?? true) this.start();
 	}
 	lifecycle() {
 		const snapshot = this.ctx.get("evolutionPolicy")?.get();
@@ -84,23 +89,28 @@ var EvolutionCurator = class extends Service {
 		this.timer = void 0;
 	}
 	/**
-	* Optional Hermes-curator LLM pass. The model may only NOMINATE pruning
-	* candidates; archive/restore remains a control-plane operation and every
-	* nominated name is still checked against lifecycle thresholds and
-	* protected markers before any file move.
+	* Optional Hermes-curator LLM pass. The model may only NOMINATE pruning and
+	* consolidation; every move stays a control-plane operation and each
+	* nomination is re-validated against the tree and protected markers before
+	* any file move. `dryRun` prepends the report-only banner.
 	*/
-	async recommend(candidates) {
-		if (candidates.length === 0) return [];
+	async recommend(candidates, options = {}) {
+		const empty = {
+			prunings: [],
+			consolidations: []
+		};
+		if (candidates.length === 0) return empty;
 		const llm = this.ctx.get("llm");
-		if (!llm) return [];
+		if (!llm) return empty;
 		const model = this.ctx.get("evolutionPolicy")?.get().curatorModel ?? "deepseek-v4-pro";
 		const prompt = [
+			options.dryRun ? CURATOR_DRY_RUN_BANNER : "",
 			CURATOR_PROMPT,
 			"",
-			"Stale candidates observed by the deterministic lifecycle scanner:",
+			`Stale candidates observed by the deterministic lifecycle scanner:${candidates.length === 0 ? " (none)" : ""}`,
 			...candidates.map((name) => `- ${name}`),
 			"",
-			"Return a YAML summary with a prunings list. Nominate only candidates whose archival is clearly safe."
+			"Return a YAML summary with consolidations and prunings lists. Nominate only actions whose archival/merge is clearly safe."
 		].join("\n");
 		try {
 			const assembler = new BlockAssembler();
@@ -122,13 +132,13 @@ var EvolutionCurator = class extends Service {
 				maxTokens: this.curatorReviewMaxTokens,
 				purpose: "evolution-curator"
 			})) assembler.push(chunk);
-			const text = assembler.blocks().filter((block) => block.type === "text").map((block) => block.text).join("\n");
-			const names = /* @__PURE__ */ new Set();
-			const section = text.slice(text.indexOf("prunings:"));
-			for (const [, name] of section.matchAll(/^\s*-\s*name:\s*([a-z0-9][a-z0-9-]*)\s*$/gm)) if (name) names.add(name);
-			return [...names].filter((name) => candidates.includes(name));
+			const parsed = parseCuratorNominations(assembler.blocks().filter((block) => block.type === "text").map((block) => block.text).join("\n"));
+			return {
+				prunings: parsed.prunings.filter((name) => candidates.includes(name)),
+				consolidations: parsed.consolidations
+			};
 		} catch {
-			return [];
+			return empty;
 		}
 	}
 	skippedReport(runId, startedAt) {
@@ -145,22 +155,25 @@ var EvolutionCurator = class extends Service {
 	}
 	/**
 	* Run one curator pass. `ignoreGates` skips the interval and idle gates so an
-	* explicit `/evolution curator run` always executes (manual-run semantics).
+	* explicit `/evolution curator run` always executes (manual-run semantics):
+	* `dryRun` computes the lifecycle and the LLM nominations but performs no
+	* mutation, reports what WOULD happen, and does not push out the next run.
 	*/
 	async run(options = {}) {
+		const { ignoreGates = false, dryRun = false } = options;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const runId = randomUUID();
 		const stateService = this.ctx.get("evolutionState");
 		const lifecycle = this.lifecycle();
 		const persisted = await stateService?.loadCuratorState();
-		if (!options.ignoreGates && persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
+		if (!ignoreGates && persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
 			stale: [],
 			archived: [],
 			errors: [],
 			report: this.skippedReport(runId, startedAt),
 			skipped: "interval"
 		};
-		if (!options.ignoreGates && this.minIdleHours > 0 && this.recentSessionActive()) return {
+		if (!ignoreGates && this.minIdleHours > 0 && this.recentSessionActive()) return {
 			stale: [],
 			archived: [],
 			errors: [],
@@ -168,10 +181,11 @@ var EvolutionCurator = class extends Service {
 			skipped: "active-session"
 		};
 		const root = this.skills.root;
-		const snapshotPath = await this.skills.snapshotAll("pre-curator-run");
-		const usage = await loadUsage(root, this.io);
+		const rawUsage = await loadUsage(root, this.io);
+		const usage = dryRun ? new Map([...rawUsage].map(([name, record]) => [name, { ...record }])) : rawUsage;
+		const snapshotPath = dryRun ? void 0 : await this.skills.snapshotAll("pre-curator-run");
 		const suppressedNames = new Set(await loadSuppressedNames(root, this.io));
-		const bundledNames = await this.seedBaseline(usage);
+		const { bundledNames, treeNames } = await this.seedBaseline(usage);
 		const result = computeLifecycleTransitions(usage, {
 			staleAfterDays: lifecycle.staleAfterDays,
 			archiveAfterDays: lifecycle.archiveAfterDays,
@@ -180,41 +194,85 @@ var EvolutionCurator = class extends Service {
 			manageUnmanaged: this.manageUnmanaged,
 			pruneBuiltins: this.pruneBuiltins,
 			bundledNames,
-			suppressedNames
+			suppressedNames,
+			referencedSkillNames: this.referencedSkillNames
+		});
+		const supportDirs = /* @__PURE__ */ new Map();
+		for (const name of treeNames) supportDirs.set(name, await this.skills.countSupportDirs(name));
+		const quality = computeQualityScores({
+			usage,
+			supportDirs
 		});
+		for (const [name, score] of quality) {
+			const record = usage.get(name);
+			if (record) {
+				record.quality_score = score.score;
+				record.quality_warn = score.warn;
+			}
+		}
 		const errors = [];
 		const archivedSkills = [];
-		const llmNominations = this.llmReview ? await this.recommend(result.markStale) : [];
+		const nominations = this.llmReview ? await this.recommend(result.markStale, { dryRun }) : {
+			prunings: [],
+			consolidations: []
+		};
+		const llmNominations = nominations.prunings;
 		const archiveCandidates = [...new Set([...result.archive, ...llmNominations])];
 		let suppressedChanged = false;
-		for (const name of archiveCandidates) {
-			const archived = await this.skills.archive(name, {
-				reason: "Lifecycle: reached archive threshold",
-				allowBundled: this.pruneBuiltins
-			});
-			if (!archived.ok) {
-				const record = usage.get(name);
-				if (record) record.state = "active";
-				errors.push(`${name}: ${archived.message}`);
-			} else {
-				archivedSkills.push({
-					name,
-					path: archived.path ?? "",
-					reason: "Lifecycle: reached archive threshold"
+		if (!dryRun) {
+			for (const name of archiveCandidates) {
+				const archived = await this.skills.archive(name, {
+					reason: "Lifecycle: reached archive threshold",
+					allowBundled: this.pruneBuiltins
 				});
-				if (bundledNames.has(name)) {
-					suppressedNames.add(name);
-					suppressedChanged = true;
+				if (!archived.ok) {
+					const record = usage.get(name);
+					if (record) record.state = "active";
+					errors.push(`${name}: ${archived.message}`);
+				} else {
+					archivedSkills.push({
+						name,
+						path: archived.path ?? "",
+						reason: "Lifecycle: reached archive threshold"
+					});
+					if (bundledNames.has(name)) {
+						suppressedNames.add(name);
+						suppressedChanged = true;
+					}
 				}
 			}
+			const alreadyArchived = new Set(archiveCandidates);
+			for (const nomination of nominations.consolidations) {
+				if (alreadyArchived.has(nomination.from)) continue;
+				if (!treeNames.has(nomination.from) || !treeNames.has(nomination.into)) {
+					errors.push(`${nomination.from}: consolidation target or source missing from the skill tree`);
+					continue;
+				}
+				const consolidated = await this.skills.consolidate(nomination.into, [nomination.from], "background_review");
+				if (!consolidated.ok) {
+					errors.push(`${nomination.from}: ${consolidated.message}`);
+					continue;
+				}
+				const record = usage.get(nomination.from);
+				if (record) {
+					record.state = "archived";
+					record.archived_at = (/* @__PURE__ */ new Date()).toISOString();
+				}
+				alreadyArchived.add(nomination.from);
+				archivedSkills.push({
+					name: nomination.from,
+					path: consolidated.path ?? "",
+					reason: `Consolidated into ${nomination.into}`
+				});
+			}
+			if (suppressedChanged) try {
+				await saveSuppressedNames(root, suppressedNames, this.io);
+			} catch {
+				this.ctx.logger.warn("evolution-curator: failed to persist suppressed names; archived built-ins may re-enter the lifecycle");
+			}
+			await saveUsage(root, usage, this.io);
 		}
-		if (suppressedChanged) try {
-			await saveSuppressedNames(root, suppressedNames, this.io);
-		} catch {
-			this.ctx.logger.warn("evolution-curator: failed to persist suppressed names; archived built-ins may re-enter the lifecycle");
-		}
-		await saveUsage(root, usage, this.io);
-		this.lastRun = Date.now();
+		if (!dryRun) this.lastRun = Date.now();
 		const report = buildCuratorRunReport({
 			runId,
 			startedAt,
@@ -229,7 +287,7 @@ var EvolutionCurator = class extends Service {
 					reason: errors.find((item) => item.startsWith(`${name}:`))?.slice(name.length + 2) ?? "unknown"
 				};
 			}),
-			snapshotPath
+			...snapshotPath === void 0 ? {} : { snapshotPath }
 		});
 		const reportsRoot = join(evolutionHome(), "reports");
 		try {
@@ -238,31 +296,39 @@ var EvolutionCurator = class extends Service {
 			this.ctx.logger.warn(`evolution-curator: failed to persist report ${runId}`);
 			this.ctx.logger.warn(error);
 		}
+		const summary = `${dryRun ? "dry-run" : "auto"}: stale:${result.markStale.length} archived:${archivedSkills.length} consolidated:${nominations.consolidations.length}`;
 		await stateService?.saveCuratorState({
-			lastRunAt: this.lastRun,
-			runCount: (persisted?.runCount ?? 0) + 1,
-			lastSummary: `stale:${result.markStale.length} archived:${archivedSkills.length}`,
+			lastRunAt: dryRun ? persisted?.lastRunAt ?? this.lastRun : this.lastRun,
+			runCount: dryRun ? persisted?.runCount ?? 0 : (persisted?.runCount ?? 0) + 1,
+			lastSummary: summary,
 			paused: false
 		});
 		return {
 			stale: result.markStale,
 			archived: archivedSkills.map((item) => item.name),
 			errors,
-			report
+			report,
+			...this.llmReview ? { nominations } : {}
 		};
 	}
 	/**
 	* Seed baseline records for tree skills the sidecar has not seen yet, so
 	* their inactivity clock starts now (first-sight defer) and bundled skills
-	* become known candidates only when prune-builtins opts them in.
+	* become known candidates only when prune-builtins opts them in. Also
+	* returns the full active tree names for nomination validation.
 	*/
 	async seedBaseline(usage) {
 		const bundledNames = /* @__PURE__ */ new Set();
+		const treeNames = /* @__PURE__ */ new Set();
 		for (const summary of await this.skills.list()) {
+			treeNames.add(summary.name);
 			if (!usage.has(summary.name)) usage.set(summary.name, emptyRecord());
 			if (await this.skills.isBundled(summary.name)) bundledNames.add(summary.name);
 		}
-		return bundledNames;
+		return {
+			bundledNames,
+			treeNames
+		};
 	}
 	recentSessionActive() {
 		const agents = this.ctx.get("agents");

package/lib/types/index.d.ts

@@ -5,7 +5,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import type Schema from '@deepseek-ai/schemastery';
 import { SkillLibrary } from '@deepseek-ai/dsh-evolution-core';
-import { type CuratorRunReport, type SkillActionResult } from '@deepseek-ai/dsh-evolution-core';
+import { type CuratorNominations, type CuratorRunReport, type SkillActionResult } from '@deepseek-ai/dsh-evolution-core';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         evolutionCurator: EvolutionCurator;
@@ -29,6 +29,10 @@ export interface Config {
     manageUnmanaged?: boolean;
     /** Archive long-unused bundled skills too (with suppression against re-seeds). */
     pruneBuiltins?: boolean;
+    /** Static scheduled-task skill references; such skills never auto-transition. */
+    referencedSkillNames?: string[];
+    /** Start the interval timer on context ready (auto-curation). Default true. */
+    autoStart?: boolean;
     /** Max tokens for the optional LLM nomination pass. */
     curatorReviewMaxTokens?: number;
 }
@@ -39,6 +43,8 @@ export interface CuratorRunOutcome {
     errors: string[];
     report: CuratorRunReport;
     skipped?: string;
+    /** LLM nominations when the optional review pass is enabled (audit visibility). */
+    nominations?: CuratorNominations;
 }
 export declare class EvolutionCurator extends Service {
     static inject: string[];
@@ -56,6 +62,7 @@ export declare class EvolutionCurator extends Service {
     private readonly excludeSkillNames;
     private readonly manageUnmanaged;
     private readonly pruneBuiltins;
+    private readonly referencedSkillNames;
     private readonly curatorReviewMaxTokens;
     private lastRun;
     private timer;
@@ -64,24 +71,30 @@ export declare class EvolutionCurator extends Service {
     start(): void;
     stop(): void;
     /**
-     * Optional Hermes-curator LLM pass. The model may only NOMINATE pruning
-     * candidates; archive/restore remains a control-plane operation and every
-     * nominated name is still checked against lifecycle thresholds and
-     * protected markers before any file move.
+     * Optional Hermes-curator LLM pass. The model may only NOMINATE pruning and
+     * consolidation; every move stays a control-plane operation and each
+     * nomination is re-validated against the tree and protected markers before
+     * any file move. `dryRun` prepends the report-only banner.
      */
-    recommend(candidates: string[]): Promise<string[]>;
+    recommend(candidates: string[], options?: {
+        dryRun?: boolean;
+    }): Promise<CuratorNominations>;
     private skippedReport;
     /**
      * Run one curator pass. `ignoreGates` skips the interval and idle gates so an
-     * explicit `/evolution curator run` always executes (manual-run semantics).
+     * explicit `/evolution curator run` always executes (manual-run semantics):
+     * `dryRun` computes the lifecycle and the LLM nominations but performs no
+     * mutation, reports what WOULD happen, and does not push out the next run.
      */
     run(options?: {
         ignoreGates?: boolean;
+        dryRun?: boolean;
     }): Promise<CuratorRunOutcome>;
     /**
      * Seed baseline records for tree skills the sidecar has not seen yet, so
      * their inactivity clock starts now (first-sight defer) and bundled skills
-     * become known candidates only when prune-builtins opts them in.
+     * become known candidates only when prune-builtins opts them in. Also
+     * returns the full active tree names for nomination validation.
      */
     private seedBaseline;
     private recentSessionActive;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-curator",
   "description": "Deterministic skill lifecycle and recovery (community build)",
-  "version": "0.1.0-rc.14",
+  "version": "0.1.0-rc.16",
   "publishConfig": {
     "access": "public"
   },
@@ -33,20 +33,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.14"
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.16"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.14",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.14"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.16",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.16"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.14",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.14",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.14"
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.16",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.16",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.16"
   }
 }