@lmzhen/dsh-evolution-curator 0.1.0-rc.8 → 0.1.0

package/README.md

@@ -28,4 +28,10 @@ Independent of request-prefix construction. This package does not alter the asse
 
 - `archive` never deletes: skills move to `.archive/` with a `.archive-reason` marker.
 - `restore(name)` (service) / `/evolution skill restore <name>` brings one archived skill back to the active root and resets its usage state.
-- `consolidate(target, sources)` (service) / `/evolution consolidate` merges source bodies into the target, archives the sources with an absorbed-into marker, and folds their usage records into `archived` state. Both operations snapshot the skill tree first (`pre-consolidate` / `pre-restore`).
+- `consolidate(target, sources)` (service) / `/evolution consolidate` merges source bodies into the target, archives the sources with an absorbed-into marker, and folds their usage records into `archived` state. Both operations snapshot the full state first (`pre-consolidate` / `pre-restore`).
+- `restoreSnapshot` (service) / `/evolution restore` rolls the FULL state back to the latest snapshot: active tree, usage/suppression sidecars, `.archive/` and the curator state carried in the snapshot (`curator-state.json`), so the interval gate does not immediately re-fire after a rollback. The restore itself is undoable — the pre-rollback safety snapshot preserves the current tree plus its state.
+
+## Automatic scheduling
+
+- `autoStart` (default true) arms an hourly interval check plus a deferred catch-up check `bootGraceSeconds` (default 10) after host boot. Both decide due-ness from the **persisted** `lastRunAt`, so a restart with an overdue schedule runs the first pass within the boot grace instead of waiting a full interval. `bootGraceSeconds: 0` disables the deferral (not recommended: the check may run against a half-mounted host). All scheduling gates — interval, idle, first-run deferral, and the reentrancy guard — remain inside `run()`.
+- `autoStart: false` disables both automatic checks; `/evolution curator run` (manual, gate-skipping) still works.

package/lib/index.js

@@ -3,25 +3,41 @@ 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, SkillLibrary, buildCuratorRunReport, computeLifecycleTransitions, evolutionHome, evolutionIoAdapter, loadUsage, 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, EvolutionGateSet, SkillLibrary, buildCuratorRunReport, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, emptyRecord, evolutionHome, evolutionIoAdapter, foldCuratorFields, loadSuppressedNames, loadUsage, mutateUsage, parseCuratorNominations, relatedSkillNames, renderCuratorReportMarkdown, updateSuppressedNames } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
 * Deterministic skill lifecycle curator with interval gate and archive.
 * @module @lmzhen/dsh-evolution-curator
 */
+/** Quality-warned skills may turn stale after this many idle days (package-private tunable, P2-8). */
+const DEFAULT_QUALITY_WARN_STALE_AFTER_DAYS = 7;
+/**
+* Block LLM-nominated consolidations that would touch a gate-protected name:
+* exclude / referenced / suppressed skills must never merge (neither as the
+* source being archived nor as the umbrella being edited). Mirrors the control
+* plane's `consolidate()` guard; automatic nominations must pass the same gate.
+*/
+function gateConsolidations(consolidations, gates) {
+	const gateSet = gates instanceof EvolutionGateSet ? gates : new EvolutionGateSet(gates);
+	return consolidations.filter((n) => !gateSet.isBlocked(n.from) && !gateSet.isBlocked(n.into));
+}
 var EvolutionCurator = class extends Service {
 	static inject = ["evolutionIo"];
 	static Config = z.object({
 		enabled: z.boolean().default(true),
-		intervalHours: z.number().default(168),
-		staleAfterDays: z.number().default(30),
-		archiveAfterDays: z.number().default(90),
+		intervalHours: z.number().default(DEFAULT_CURATOR_INTERVAL_HOURS),
+		staleAfterDays: z.number().default(DEFAULT_STALE_AFTER_DAYS),
+		archiveAfterDays: z.number().default(DEFAULT_ARCHIVE_AFTER_DAYS),
 		llmReview: z.boolean().default(false),
 		curatorProvider: z.string().default("deepseek-official"),
-		qualityWarnStaleAfterDays: z.number().default(7),
-		minIdleHours: z.number().default(0),
+		qualityWarnStaleAfterDays: z.number().default(DEFAULT_QUALITY_WARN_STALE_AFTER_DAYS),
+		minIdleHours: z.number().default(DEFAULT_MIN_IDLE_HOURS),
 		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),
+		bootGraceSeconds: z.number().default(10),
 		curatorReviewMaxTokens: z.number().default(2048)
 	});
 	skills;
@@ -36,23 +52,33 @@ var EvolutionCurator = class extends Service {
 	minIdleHours;
 	excludeSkillNames;
 	manageUnmanaged;
+	pruneBuiltins;
+	referencedSkillNames;
+	bootGraceSeconds;
 	curatorReviewMaxTokens;
 	lastRun = 0;
 	timer;
+	bootCheck;
+	running = false;
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionCurator");
 		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
-		this.skills = new SkillLibrary(void 0, this.io);
+		this.skills = new SkillLibrary(void 0, this.io, void 0, (event) => {
+			this.ctx.emit("evolution/skill-mutated", event);
+		});
 		this.enabled = config.enabled ?? true;
-		this.intervalHours = config.intervalHours ?? 168;
-		this.staleAfterDays = config.staleAfterDays ?? 30;
-		this.archiveAfterDays = config.archiveAfterDays ?? 90;
+		this.intervalHours = config.intervalHours ?? DEFAULT_CURATOR_INTERVAL_HOURS;
+		this.staleAfterDays = config.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+		this.archiveAfterDays = config.archiveAfterDays ?? DEFAULT_ARCHIVE_AFTER_DAYS;
 		this.llmReview = config.llmReview ?? false;
 		this.curatorProvider = config.curatorProvider ?? "deepseek-official";
-		this.qualityWarnStaleAfterDays = config.qualityWarnStaleAfterDays ?? 7;
-		this.minIdleHours = config.minIdleHours ?? 0;
+		this.qualityWarnStaleAfterDays = config.qualityWarnStaleAfterDays ?? DEFAULT_QUALITY_WARN_STALE_AFTER_DAYS;
+		this.minIdleHours = config.minIdleHours ?? DEFAULT_MIN_IDLE_HOURS;
 		this.excludeSkillNames = new Set(config.excludeSkillNames ?? []);
 		this.manageUnmanaged = config.manageUnmanaged ?? false;
+		this.pruneBuiltins = config.pruneBuiltins ?? false;
+		this.referencedSkillNames = new Set(config.referencedSkillNames ?? []);
+		this.bootGraceSeconds = config.bootGraceSeconds ?? 10;
 		this.curatorReviewMaxTokens = config.curatorReviewMaxTokens ?? 2048;
 		this.lastRun = Date.now();
 		this.ctx.effect(() => {
@@ -60,6 +86,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();
@@ -71,33 +98,85 @@ var EvolutionCurator = class extends Service {
 	}
 	start() {
 		if (!this.enabled || this.timer) return;
-		this.timer = setInterval(() => {
-			if (Date.now() - this.lastRun >= this.lifecycle().intervalHours * 36e5) this.run();
-		}, 3600 * 1e3);
+		this.bootCheck = setTimeout(() => {
+			this.bootCheck = void 0;
+			this.autoCheck();
+		}, this.bootGraceSeconds * 1e3);
+		this.bootCheck.unref();
+		this.timer = setInterval(() => void this.autoCheck(), 3600 * 1e3);
 		this.timer.unref();
 	}
 	stop() {
 		if (this.timer) clearInterval(this.timer);
 		this.timer = void 0;
+		if (this.bootCheck) clearTimeout(this.bootCheck);
+		this.bootCheck = void 0;
+	}
+	/**
+	* Pause or resume automatic curation (B-line G2, Hermes `set_paused`
+	* parity): the flag is persisted on the curator state record and the
+	* `run()` paused gate skips automatic passes while it holds. Manual runs
+	* (`ignoreGates`) are unaffected — pause is a soft stop for the scheduler,
+	* not a lock on the operator.
+	*
+	* Pausing on a state-less curator state seeds the record with `lastRunAt:
+	* now`, so a later resume re-enters through the interval gate and defers a
+	* full cycle instead of firing immediately (first-run defer interaction,
+	* kept deliberately: an unattended resume must not auto-run mid-boot).
+	*/
+	async setPaused(paused) {
+		const stateService = this.curatorStateService();
+		const persisted = await stateService?.loadCuratorState() ?? null;
+		await stateService?.saveCuratorState({
+			schemaVersion: 1,
+			lastRunAt: persisted?.lastRunAt ?? Date.now(),
+			runCount: persisted?.runCount ?? 0,
+			lastSummary: persisted?.lastSummary ?? (paused ? "paused" : "resumed"),
+			paused
+		});
+	}
+	/** Current persisted curator state (read-only view for /evolution curator status). */
+	async status() {
+		return await this.curatorStateService()?.loadCuratorState() ?? null;
 	}
 	/**
-	* 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.
+	* One automatic schedule check: run a pass when the persisted curator state
+	* (falling back to the in-memory clock for state-less compositions) is at
+	* least one interval old. All gates — interval, idle, first-run defer,
+	* reentrancy — stay inside `run()`, so this method only decides whether to
+	* wake it, and never duplicates gate logic.
 	*/
-	async recommend(candidates) {
-		if (candidates.length === 0) return [];
+	async autoCheck() {
+		const last = (await this.curatorStateService()?.loadCuratorState())?.lastRunAt ?? this.lastRun;
+		if (Date.now() - last >= this.lifecycle().intervalHours * 36e5) await this.run();
+	}
+	/**
+	* 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, 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 clusters = computePrefixClusters(candidates);
+		const clusterLines = clusters.length === 0 ? ["Prefix clusters observed in the candidate list: (none)"] : ["Prefix clusters observed in the candidate list (orientation only — verify against the names above; you may also flag additional clusters):", ...clusters.map((cluster) => `- '${cluster.key}': ${cluster.members.join(", ")}`)];
 		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."
+			...clusterLines,
+			"",
+			"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();
@@ -116,17 +195,57 @@ var EvolutionCurator = class extends Service {
 						summary: "curator review"
 					}
 				})],
-				maxTokens: this.curatorReviewMaxTokens,
-				purpose: "evolution-curator"
+				maxTokens: this.curatorReviewMaxTokens
 			})) 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.filter((item) => candidates.includes(item.from))
+			};
 		} catch {
-			return [];
+			return empty;
+		}
+	}
+	/** Optional curator-state service (evolution-state-json / storage-domain). */
+	curatorStateService() {
+		return this.ctx.get("evolutionState");
+	}
+	/**
+	* Full-state snapshot: the skills tree plus the current curator state as an
+	* `extras/curator-state.json` side file. Every pre-mutation snapshot in the
+	* curator goes through here so a later `restoreSnapshot()` can rewind both
+	* the tree and the state (Hermes curator_backup backs up `.curator_state`).
+	*/
+	async snapshotFull(reason = "pre-mutation") {
+		const state = await this.curatorStateService()?.loadCuratorState();
+		const extras = state === null || state === void 0 ? [] : [{
+			name: "curator-state.json",
+			content: JSON.stringify(state, null, 2)
+		}];
+		return await this.skills.snapshotAll(reason, extras);
+	}
+	/**
+	* Full-state rollback: restore the latest snapshot's tree/sidecars/archive
+	* AND the curator state it carried. The pre-rollback safety snapshot keeps
+	* the current tree plus current state (as extras), so the rollback itself
+	* is reversible.
+	*/
+	async restoreSnapshot() {
+		const stateService = this.curatorStateService();
+		const currentState = await stateService?.loadCuratorState();
+		const extras = currentState === null || currentState === void 0 ? [] : [{
+			name: "curator-state.json",
+			content: JSON.stringify(currentState, null, 2)
+		}];
+		const result = await this.skills.restoreLatestSnapshot(extras);
+		if (!result.ok) return result;
+		const stateExtra = result.extras?.find((extra) => extra.name === "curator-state.json");
+		if (stateExtra && stateService) try {
+			await stateService.saveCuratorState(JSON.parse(stateExtra.content));
+		} catch (error) {
+			this.ctx.logger.warn(`evolution-curator: failed to restore curator state: ${error instanceof Error ? error.message : String(error)}`);
 		}
+		return result;
 	}
 	skippedReport(runId, startedAt) {
 		return buildCuratorRunReport({
@@ -137,57 +256,132 @@ var EvolutionCurator = class extends Service {
 			llmNominations: [],
 			archiveCandidates: [],
 			archived: [],
-			failed: []
+			failed: [],
+			llmReviewEnabled: this.llmReview
 		});
 	}
-	async run() {
+	/**
+	* Run one curator pass. `ignoreGates` skips the interval and idle gates so an
+	* 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.
+	* Reentrant calls (autoStart timer + manual command at the same instant) are
+	* skipped with an explicit `already-running` outcome.
+	*/
+	async run(options = {}) {
+		if (this.running) return {
+			stale: [],
+			archived: [],
+			errors: [],
+			report: this.skippedReport("already-running", (/* @__PURE__ */ new Date()).toISOString()),
+			skipped: "already-running"
+		};
+		this.running = true;
+		try {
+			return await this.runCore(options);
+		} finally {
+			this.running = false;
+		}
+	}
+	async runCore(options = {}) {
+		const { ignoreGates = false, dryRun = false } = options;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const runId = randomUUID();
-		const stateService = this.ctx.get("evolutionState");
+		const stateService = this.curatorStateService();
 		const lifecycle = this.lifecycle();
-		const persisted = await stateService?.loadCuratorState();
-		if (persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
+		const persisted = await stateService?.loadCuratorState() ?? null;
+		if (!ignoreGates && persisted?.paused === true) return {
+			stale: [],
+			archived: [],
+			errors: [],
+			report: this.skippedReport(runId, startedAt),
+			skipped: "paused"
+		};
+		if (!ignoreGates && persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
 			stale: [],
 			archived: [],
 			errors: [],
 			report: this.skippedReport(runId, startedAt),
 			skipped: "interval"
 		};
-		if (this.minIdleHours > 0 && this.recentSessionActive()) return {
+		if (!ignoreGates && this.minIdleHours > 0 && this.recentSessionActive()) return {
 			stale: [],
 			archived: [],
 			errors: [],
 			report: this.skippedReport(runId, startedAt),
 			skipped: "active-session"
 		};
+		if (!ignoreGates && persisted === null) {
+			await stateService?.saveCuratorState({
+				schemaVersion: 1,
+				lastRunAt: Date.now(),
+				runCount: 0,
+				lastSummary: "first-run-deferred",
+				paused: false
+			});
+			return {
+				stale: [],
+				archived: [],
+				errors: [],
+				report: this.skippedReport(runId, startedAt),
+				skipped: "first-run-deferred"
+			};
+		}
 		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.snapshotFull("pre-curator-run");
+		const suppressedNames = new Set(await loadSuppressedNames(root, this.io));
+		const gates = new EvolutionGateSet({
+			exclude: this.excludeSkillNames,
+			referenced: this.referencedSkillNames,
+			suppressed: suppressedNames
+		});
+		const { bundledNames, treeNames } = await this.seedBaseline(usage);
+		const contents = /* @__PURE__ */ new Map();
+		for (const name of treeNames) {
+			const text = await this.skills.read(name);
+			if (text) contents.set(name, text);
+		}
+		const dedupMembers = [...new Set(computeDedupGroups({ contents }).filter((group) => group.length >= 2).flat())];
+		await this.scoreTree(usage, treeNames);
 		const result = computeLifecycleTransitions(usage, {
 			staleAfterDays: lifecycle.staleAfterDays,
 			archiveAfterDays: lifecycle.archiveAfterDays,
 			qualityWarnStaleAfterDays: this.qualityWarnStaleAfterDays,
 			excludeSkillNames: this.excludeSkillNames,
-			manageUnmanaged: this.manageUnmanaged
-		});
-		const errors = [];
-		const archivedSkills = [];
-		const llmNominations = this.llmReview ? await this.recommend(result.markStale) : [];
+			manageUnmanaged: this.manageUnmanaged,
+			pruneBuiltins: this.pruneBuiltins,
+			bundledNames,
+			suppressedNames,
+			referencedSkillNames: this.referencedSkillNames
+		}, /* @__PURE__ */ new Date(), gates);
+		const recommendPool = [...new Set([...result.markStale, ...dedupMembers])];
+		const nominations = this.llmReview ? await this.recommend(recommendPool, { dryRun }) : {
+			prunings: [],
+			consolidations: []
+		};
+		const gatedNominations = {
+			...nominations,
+			prunings: nominations.prunings.filter((name) => result.markStale.includes(name)),
+			consolidations: gateConsolidations(nominations.consolidations, gates)
+		};
+		const llmNominations = gatedNominations.prunings;
 		const archiveCandidates = [...new Set([...result.archive, ...llmNominations])];
-		for (const name of archiveCandidates) {
-			const archived = await this.skills.archive(name, "Lifecycle: reached archive threshold");
-			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"
-			});
-		}
-		await saveUsage(root, usage, this.io);
-		this.lastRun = Date.now();
+		const { archivedSkills, errors, consolidated } = await this.applyMutations({
+			dryRun,
+			archiveCandidates,
+			nominations: gatedNominations,
+			treeNames,
+			usage,
+			bundledNames,
+			suppressedNames,
+			root,
+			recommendPool: new Set(recommendPool),
+			stateOwned: new Set([...result.transitions.map((t) => t.name), ...archiveCandidates]),
+			failedFrom: new Map(result.transitions.filter((t) => t.to === "archived").map((t) => [t.name, t.from]))
+		});
+		if (!dryRun) this.lastRun = Date.now();
 		const report = buildCuratorRunReport({
 			runId,
 			startedAt,
@@ -196,32 +390,206 @@ var EvolutionCurator = class extends Service {
 			llmNominations,
 			archiveCandidates,
 			archived: archivedSkills,
-			failed: archiveCandidates.filter((name) => errors.some((error) => error.startsWith(`${name}:`))).map((name) => {
+			failed: [...new Set([...archiveCandidates, ...gatedNominations.consolidations.map((item) => item.from)])].filter((name) => errors.some((error) => error.startsWith(`${name}:`))).map((name) => {
 				return {
 					name,
 					reason: errors.find((item) => item.startsWith(`${name}:`))?.slice(name.length + 2) ?? "unknown"
 				};
 			}),
-			snapshotPath
+			consolidated,
+			...snapshotPath === void 0 ? {} : { snapshotPath },
+			llmReviewEnabled: this.llmReview
 		});
 		const reportsRoot = join(evolutionHome(), "reports");
 		try {
 			await this.io.writeText(join(reportsRoot, `curator-${runId}.json`), JSON.stringify(report, null, 2));
+			await this.io.writeText(join(reportsRoot, `curator-${runId}.md`), renderCuratorReportMarkdown(report));
+			await this.retainReports(20);
 		} catch (error) {
 			this.ctx.logger.warn(`evolution-curator: failed to persist report ${runId}`);
 			this.ctx.logger.warn(error);
 		}
+		const llmHint = !this.llmReview && result.markStale.length > 0 ? " (llmReview: off - deterministic archive only; set llmReview: true for the LLM merge channel)" : "";
+		const summary = `${dryRun ? "dry-run" : "auto"}: stale:${result.markStale.length} archived:${archivedSkills.length} consolidated:${gatedNominations.consolidations.length}${llmHint}`;
+		const pausedNow = (await stateService?.loadCuratorState())?.paused ?? false;
 		await stateService?.saveCuratorState({
-			lastRunAt: this.lastRun,
-			runCount: (persisted?.runCount ?? 0) + 1,
-			lastSummary: `stale:${result.markStale.length} archived:${archivedSkills.length}`,
-			paused: false
+			schemaVersion: 1,
+			lastRunAt: dryRun ? persisted?.lastRunAt ?? this.lastRun : this.lastRun,
+			runCount: dryRun ? persisted?.runCount ?? 0 : (persisted?.runCount ?? 0) + 1,
+			lastSummary: summary,
+			paused: pausedNow
 		});
 		return {
 			stale: result.markStale,
 			archived: archivedSkills.map((item) => item.name),
 			errors,
-			report
+			report,
+			...this.llmReview ? { nominations: gatedNominations } : {}
+		};
+	}
+	/**
+	* 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. 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);
+			const record = usage.get(summary.name);
+			if (record) record.pinned = await this.skills.isPinned(summary.name);
+		}
+		return {
+			bundledNames,
+			treeNames
+		};
+	}
+	/**
+	* F13 six-factor quality scoring, persisted onto the usage records.
+	*/
+	async scoreTree(usage, treeNames) {
+		const supportDirs = /* @__PURE__ */ new Map();
+		for (const name of treeNames) supportDirs.set(name, await this.skills.countSupportDirs(name));
+		const quality = computeQualityScores({
+			usage,
+			supportDirs,
+			referenceCounts: await this.referenceCounts(treeNames)
+		});
+		for (const [name, score] of quality) {
+			const record = usage.get(name);
+			if (record) {
+				record.quality_score = score.score;
+				record.quality_warn = score.warn;
+			}
+		}
+	}
+	/**
+	* In-degree over explicit `related_skills` frontmatter references (the DSH
+	* equivalent of the graph-in-degree references factor): a skill listing
+	* other skill names counts as one reference to each of them, so hub skills
+	* that are explicitly named by peers get a non-zero references factor.
+	*/
+	async referenceCounts(treeNames) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const name of treeNames) {
+			const content = await this.skills.read(name);
+			if (!content) continue;
+			for (const target of relatedSkillNames(content, name)) counts.set(target, (counts.get(target) ?? 0) + 1);
+		}
+		return counts;
+	}
+	/**
+	* Execute lifecycle archives and consolidation nominations, then persist the
+	* suppression and usage sidecars best-effort. A dry-run short-circuits: no
+	* file moves and no state persistence — the caller still writes the report.
+	*/
+	async applyMutations(input) {
+		if (input.dryRun) return {
+			archivedSkills: [],
+			errors: [],
+			suppressedChanged: false,
+			consolidated: []
+		};
+		const { archiveCandidates, nominations, treeNames, usage, bundledNames, suppressedNames, root, failedFrom } = input;
+		const errors = [];
+		const archivedSkills = [];
+		const executedConsolidations = [];
+		let suppressedChanged = false;
+		const suppressedAdded = /* @__PURE__ */ new Set();
+		const stateOwned = new Set(input.stateOwned ?? []);
+		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);
+				const from = failedFrom?.get(name);
+				if (record && (from === "stale" || from === "active")) {
+					record.state = from;
+					record.archived_at = null;
+					stateOwned.add(name);
+				}
+				errors.push(`${name}: ${archived.message}`);
+			} else {
+				const record = usage.get(name);
+				if (record) {
+					record.state = "archived";
+					record.archived_at = (/* @__PURE__ */ new Date()).toISOString();
+					stateOwned.add(name);
+				}
+				archivedSkills.push({
+					name,
+					path: archived.path ?? "",
+					reason: "Lifecycle: reached archive threshold"
+				});
+				if (bundledNames.has(name)) {
+					suppressedNames.add(name);
+					suppressedAdded.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;
+			}
+			if (!input.recommendPool.has(nomination.from)) {
+				errors.push(`${nomination.from}: consolidation nomination outside the candidate pool — refused (advisory text has no executability authority)`);
+				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();
+				stateOwned.add(nomination.from);
+			}
+			alreadyArchived.add(nomination.from);
+			executedConsolidations.push({
+				from: nomination.from,
+				into: nomination.into
+			});
+			archivedSkills.push({
+				name: nomination.from,
+				path: join(this.skills.root, ".archive", nomination.from),
+				reason: `Consolidated into ${nomination.into}`
+			});
+		}
+		if (suppressedChanged) try {
+			await updateSuppressedNames(root, this.io, (current) => {
+				for (const name of suppressedAdded) current.add(name);
+			});
+		} catch {
+			this.ctx.logger.warn("evolution-curator: failed to persist suppressed names; archived built-ins may re-enter the lifecycle");
+		}
+		try {
+			await mutateUsage(root, this.io, (disk) => {
+				foldCuratorFields(disk, usage, stateOwned);
+			});
+		} catch {
+			this.ctx.logger.warn("evolution-curator: failed to persist usage sidecar");
+		}
+		const usageRegistry = this.ctx.get("skillUsage");
+		try {
+			await usageRegistry?.invalidate?.();
+		} catch {}
+		return {
+			archivedSkills,
+			errors,
+			suppressedChanged,
+			consolidated: executedConsolidations
 		};
 	}
 	recentSessionActive() {
@@ -235,11 +603,61 @@ var EvolutionCurator = class extends Service {
 		}
 		return latest > 0 && Date.now() - latest < this.minIdleHours * 36e5;
 	}
+	/**
+	* Keep only the newest N curator reports, ordered by the report's own
+	* `startedAt` (the runId is a UUID and cannot order history). Best-effort
+	* like `retainSnapshots`: a failed removal must not fail the run that just
+	* persisted its report. The paired `.md` digest is pruned with its JSON.
+	*/
+	async retainReports(keep) {
+		const reportsRoot = join(evolutionHome(), "reports");
+		let entries;
+		try {
+			entries = await this.io.list(reportsRoot);
+		} catch {
+			return;
+		}
+		const dated = [];
+		for (const name of entries.filter((entry) => entry.startsWith("curator-") && entry.endsWith(".json"))) try {
+			const raw = await this.io.readText(join(reportsRoot, name));
+			if (raw === null) continue;
+			const parsed = JSON.parse(raw);
+			const startedAt = typeof parsed.startedAt === "string" ? Date.parse(parsed.startedAt) : NaN;
+			if (Number.isFinite(startedAt)) dated.push({
+				name,
+				startedAt
+			});
+		} catch {}
+		dated.sort((a, b) => b.startedAt - a.startedAt);
+		for (const oldReport of dated.slice(keep)) {
+			const stem = oldReport.name.replace(/\.json$/, "");
+			try {
+				await this.io.remove(join(reportsRoot, oldReport.name));
+			} catch {}
+			try {
+				await this.io.remove(join(reportsRoot, `${stem}.md`));
+			} catch {}
+		}
+	}
 	async latestReport() {
 		const reportsRoot = join(evolutionHome(), "reports");
-		const latest = (await this.io.list(reportsRoot)).filter((name) => name.startsWith("curator-") && name.endsWith(".json")).sort().reverse()[0];
-		if (!latest) return null;
-		const raw = await this.io.readText(join(reportsRoot, latest));
+		const names = (await this.io.list(reportsRoot)).filter((name) => name.startsWith("curator-") && name.endsWith(".json")).sort();
+		let latest = null;
+		for (const name of names) {
+			const raw = await this.io.readText(join(reportsRoot, name));
+			if (raw === null) continue;
+			try {
+				const parsed = JSON.parse(raw);
+				const startedAt = typeof parsed.startedAt === "string" ? Date.parse(parsed.startedAt) : 0;
+				if (!Number.isFinite(startedAt)) continue;
+				if (latest === null || startedAt > latest.startedAt) latest = {
+					name,
+					startedAt
+				};
+			} catch {}
+		}
+		if (latest === null) return null;
+		const raw = await this.io.readText(join(reportsRoot, latest.name));
 		if (raw === null) return null;
 		try {
 			return JSON.parse(raw);
@@ -248,25 +666,66 @@ var EvolutionCurator = class extends Service {
 		}
 	}
 	/**
+	* Read-only lifecycle scope classification: which skills are in scope,
+	* watched (stale/quality-warned), exempted, or protected. Uses the same
+	* candidate gate as `run()` (`computeScopeView` / `lifecycleCandidate`),
+	* so the view always predicts what a curator pass may touch.
+	*/
+	async scopeView() {
+		const root = this.skills.root;
+		const usage = await loadUsage(root, this.io);
+		const { bundledNames } = await this.seedBaseline(usage);
+		const gates = new EvolutionGateSet({
+			exclude: this.excludeSkillNames,
+			referenced: this.referencedSkillNames,
+			suppressed: new Set(await loadSuppressedNames(root, this.io))
+		});
+		return computeScopeView(usage, {
+			staleAfterDays: this.lifecycle().staleAfterDays,
+			archiveAfterDays: this.lifecycle().archiveAfterDays,
+			excludeSkillNames: this.excludeSkillNames,
+			referencedSkillNames: this.referencedSkillNames,
+			suppressedNames: new Set(gates.suppressed),
+			manageUnmanaged: this.manageUnmanaged,
+			pruneBuiltins: this.pruneBuiltins,
+			bundledNames
+		}, await this.protectedNameMap(), gates);
+	}
+	/** marker info (pinned/bundled/hub-installed) per skill, from the library list. */
+	async protectedNameMap() {
+		const map = /* @__PURE__ */ new Map();
+		for (const summary of await this.skills.list()) if (summary.protectedBy !== null) map.set(summary.name, summary.protectedBy);
+		return map;
+	}
+	/**
 	* Control-plane consolidation: merge source skill bodies into `target`,
 	* archive the sources with an absorbed-into marker, and fold their usage
 	* records into `archived` state. Snapshot-then-mutate, never a hard delete.
 	*/
 	async consolidate(target, sources) {
-		const blocked = [...this.excludeSkillNames].filter((name) => name === target || sources.includes(name));
+		const suppressedNames = new Set(await loadSuppressedNames(this.skills.root, this.io));
+		const gates = new EvolutionGateSet({
+			exclude: this.excludeSkillNames,
+			referenced: this.referencedSkillNames,
+			suppressed: suppressedNames
+		});
+		const blocked = [...new Set([target, ...sources])].filter((name) => gates.isBlocked(name));
 		if (blocked.length > 0) return {
 			ok: false,
-			message: `Skill(s) excluded from lifecycle management: ${blocked.join(", ")}`
+			message: `Skill(s) protected from consolidation (excluded / referenced / suppressed / protected builtin): ${blocked.join(", ")}`
 		};
-		await this.skills.snapshotAll("pre-consolidate");
+		await this.snapshotFull("pre-consolidate");
 		const result = await this.skills.consolidate(target, sources);
 		if (!result.ok) return result;
-		const usage = await loadUsage(this.skills.root, this.io);
-		for (const source of sources) {
-			const record = usage.get(source);
-			if (record) record.state = "archived";
-		}
-		await saveUsage(this.skills.root, usage, this.io);
+		await mutateUsage(this.skills.root, this.io, (disk) => {
+			for (const source of sources) {
+				const record = disk.get(source);
+				if (record) {
+					record.state = "archived";
+					record.archived_at = (/* @__PURE__ */ new Date()).toISOString();
+				}
+			}
+		});
 		return result;
 	}
 	/**
@@ -274,15 +733,25 @@ var EvolutionCurator = class extends Service {
 	* and reset its usage state, keeping the recoverable-archive invariant.
 	*/
 	async restore(name) {
-		await this.skills.snapshotAll("pre-restore");
+		await this.snapshotFull("pre-restore");
 		const result = await this.skills.restoreFromArchive(name);
 		if (!result.ok) return result;
-		const usage = await loadUsage(this.skills.root, this.io);
-		const record = usage.get(name);
-		if (record) record.state = "active";
-		await saveUsage(this.skills.root, usage, this.io);
+		await mutateUsage(this.skills.root, this.io, (disk) => {
+			const record = disk.get(name);
+			if (record) {
+				record.state = "active";
+				record.archived_at = null;
+			}
+		});
+		if (new Set(await loadSuppressedNames(this.skills.root, this.io)).has(name)) try {
+			await updateSuppressedNames(this.skills.root, this.io, (current) => {
+				current.delete(name);
+			});
+		} catch {
+			this.ctx.logger.warn(`evolution-curator: failed to persist suppressed names after restoring ${name}`);
+		}
 		return result;
 	}
 };
 //#endregion
-export { EvolutionCurator, EvolutionCurator as default };
+export { EvolutionCurator, EvolutionCurator as default, gateConsolidations };

package/lib/types/index.d.ts

@@ -4,8 +4,8 @@
  */
 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 { EvolutionGateSet, SkillLibrary } from '@deepseek-ai/dsh-evolution-core';
+import { type CuratorConsolidation, type CuratorNominations, type CuratorRunReport, type ScopeView, type SkillActionResult } from '@deepseek-ai/dsh-evolution-core';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         evolutionCurator: EvolutionCurator;
@@ -27,9 +27,46 @@ export interface Config {
     excludeSkillNames?: string[];
     /** Include usage records whose created_by is not 'agent' in lifecycle decisions. */
     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;
+    /** Seconds between host boot and the first automatic schedule check (restart catch-up). */
+    bootGraceSeconds?: number;
     /** Max tokens for the optional LLM nomination pass. */
     curatorReviewMaxTokens?: number;
 }
+/** Outcome of one curator run pass. */
+export interface CuratorRunOutcome {
+    stale: string[];
+    archived: string[];
+    errors: string[];
+    report: CuratorRunReport;
+    skipped?: string;
+    /** LLM nominations when the optional review pass is enabled (audit visibility). */
+    nominations?: CuratorNominations;
+}
+/** Persisted curator-state record shape (schemaVersion optional for legacy reads). */
+export interface CuratorStateRecordShape {
+    schemaVersion?: number;
+    lastRunAt: number;
+    runCount: number;
+    lastSummary: string;
+    paused: boolean;
+}
+/**
+ * Block LLM-nominated consolidations that would touch a gate-protected name:
+ * exclude / referenced / suppressed skills must never merge (neither as the
+ * source being archived nor as the umbrella being edited). Mirrors the control
+ * plane's `consolidate()` guard; automatic nominations must pass the same gate.
+ */
+export declare function gateConsolidations(consolidations: CuratorConsolidation[], gates: EvolutionGateSet | {
+    exclude?: ReadonlySet<string>;
+    referenced?: ReadonlySet<string>;
+    suppressed?: ReadonlySet<string>;
+}): CuratorConsolidation[];
 export declare class EvolutionCurator extends Service {
     static inject: string[];
     static Config: Schema<Config>;
@@ -45,30 +82,127 @@ export declare class EvolutionCurator extends Service {
     private readonly minIdleHours;
     private readonly excludeSkillNames;
     private readonly manageUnmanaged;
+    private readonly pruneBuiltins;
+    private readonly referencedSkillNames;
+    private readonly bootGraceSeconds;
     private readonly curatorReviewMaxTokens;
     private lastRun;
     private timer;
+    private bootCheck;
+    private running;
     constructor(ctx: Context, config?: Config);
     private lifecycle;
     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.
+     * Pause or resume automatic curation (B-line G2, Hermes `set_paused`
+     * parity): the flag is persisted on the curator state record and the
+     * `run()` paused gate skips automatic passes while it holds. Manual runs
+     * (`ignoreGates`) are unaffected — pause is a soft stop for the scheduler,
+     * not a lock on the operator.
+     *
+     * Pausing on a state-less curator state seeds the record with `lastRunAt:
+     * now`, so a later resume re-enters through the interval gate and defers a
+     * full cycle instead of firing immediately (first-run defer interaction,
+     * kept deliberately: an unattended resume must not auto-run mid-boot).
      */
-    recommend(candidates: string[]): Promise<string[]>;
-    private skippedReport;
-    run(): Promise<{
-        stale: string[];
-        archived: string[];
-        errors: string[];
-        report: CuratorRunReport;
-        skipped?: string;
+    setPaused(paused: boolean): Promise<void>;
+    /** Current persisted curator state (read-only view for /evolution curator status). */
+    status(): Promise<CuratorStateRecordShape | null>;
+    /**
+     * One automatic schedule check: run a pass when the persisted curator state
+     * (falling back to the in-memory clock for state-less compositions) is at
+     * least one interval old. All gates — interval, idle, first-run defer,
+     * reentrancy — stay inside `run()`, so this method only decides whether to
+     * wake it, and never duplicates gate logic.
+     */
+    private autoCheck;
+    /**
+     * 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[], options?: {
+        dryRun?: boolean;
+    }): Promise<CuratorNominations>;
+    /** Optional curator-state service (evolution-state-json / storage-domain). */
+    private curatorStateService;
+    /**
+     * Full-state snapshot: the skills tree plus the current curator state as an
+     * `extras/curator-state.json` side file. Every pre-mutation snapshot in the
+     * curator goes through here so a later `restoreSnapshot()` can rewind both
+     * the tree and the state (Hermes curator_backup backs up `.curator_state`).
+     */
+    snapshotFull(reason?: string): Promise<string>;
+    /**
+     * Full-state rollback: restore the latest snapshot's tree/sidecars/archive
+     * AND the curator state it carried. The pre-rollback safety snapshot keeps
+     * the current tree plus current state (as extras), so the rollback itself
+     * is reversible.
+     */
+    restoreSnapshot(): Promise<SkillActionResult & {
+        extras?: Array<{
+            name: string;
+            content: string;
+        }>;
     }>;
+    private skippedReport;
+    /**
+     * Run one curator pass. `ignoreGates` skips the interval and idle gates so an
+     * 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.
+     * Reentrant calls (autoStart timer + manual command at the same instant) are
+     * skipped with an explicit `already-running` outcome.
+     */
+    run(options?: {
+        ignoreGates?: boolean;
+        dryRun?: boolean;
+    }): Promise<CuratorRunOutcome>;
+    private runCore;
+    /**
+     * 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. Also
+     * returns the full active tree names for nomination validation.
+     */
+    private seedBaseline;
+    /**
+     * F13 six-factor quality scoring, persisted onto the usage records.
+     */
+    private scoreTree;
+    /**
+     * In-degree over explicit `related_skills` frontmatter references (the DSH
+     * equivalent of the graph-in-degree references factor): a skill listing
+     * other skill names counts as one reference to each of them, so hub skills
+     * that are explicitly named by peers get a non-zero references factor.
+     */
+    private referenceCounts;
+    /**
+     * Execute lifecycle archives and consolidation nominations, then persist the
+     * suppression and usage sidecars best-effort. A dry-run short-circuits: no
+     * file moves and no state persistence — the caller still writes the report.
+     */
+    private applyMutations;
     private recentSessionActive;
+    /**
+     * Keep only the newest N curator reports, ordered by the report's own
+     * `startedAt` (the runId is a UUID and cannot order history). Best-effort
+     * like `retainSnapshots`: a failed removal must not fail the run that just
+     * persisted its report. The paired `.md` digest is pruned with its JSON.
+     */
+    private retainReports;
     latestReport(): Promise<CuratorRunReport | null>;
+    /**
+     * Read-only lifecycle scope classification: which skills are in scope,
+     * watched (stale/quality-warned), exempted, or protected. Uses the same
+     * candidate gate as `run()` (`computeScopeView` / `lifecycleCandidate`),
+     * so the view always predicts what a curator pass may touch.
+     */
+    scopeView(): Promise<ScopeView>;
+    /** marker info (pinned/bundled/hub-installed) per skill, from the library list. */
+    private protectedNameMap;
     /**
      * Control-plane consolidation: merge source skill bodies into `target`,
      * archive the sources with an absorbed-into marker, and fold their usage

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.8",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,20 +33,20 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.8"
+    "@lmzhen/dsh-evolution-core": "^0.1.0"
   },
   "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.8",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-io": "^0.1.0",
+    "@lmzhen/dsh-evolution-state": "^0.1.0"
   },
   "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.8",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.8",
-    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-core": "^0.1.0",
+    "@lmzhen/dsh-evolution-io": "^0.1.0",
+    "@lmzhen/dsh-evolution-state": "^0.1.0"
   }
 }