@lmzhen/dsh-evolution-core 0.1.0-rc.36 → 0.1.0-rc.38

package/lib/index.js

@@ -377,6 +377,7 @@ function lifecycleCandidate(name, record, config, bundled) {
 function computeScopeView(usage, config, protectedNames) {
 	const managed = [];
 	const watched = [];
+	const qualityWarned = [];
 	const exempted = [];
 	const protectedSet = /* @__PURE__ */ new Set();
 	for (const [name, record] of usage) {
@@ -390,11 +391,13 @@ function computeScopeView(usage, config, protectedNames) {
 		if (lifecycleCandidate(name, record, config, bundled)) {
 			managed.push(name);
 			if (record.state === "stale" || record.quality_warn === true) watched.push(name);
+			if (record.quality_warn === true) qualityWarned.push(name);
 		}
 	}
 	return {
 		managed: managed.sort(),
 		watched: watched.sort(),
+		qualityWarned: qualityWarned.sort(),
 		exempted: exempted.sort(),
 		protected: [...protectedSet].sort()
 	};
@@ -1588,6 +1591,8 @@ const DEFAULT_SKILL_LIMITS = {
 	maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
 	maxSkillFileBytes: MAX_SKILL_FILE_BYTES
 };
+/** Extra file name carried inside a snapshot's `extras/` directory. */
+const SNAPSHOT_EXTRA_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
 function skillsRoot(env = process.env) {
 	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "skills");
 }
@@ -2241,7 +2246,13 @@ var SkillLibrary = class {
 			path: target
 		};
 	}
-	async snapshotAll(reason = "pre-mutation") {
+	/**
+	* Snapshot the recoverable skills state: active tree, usage/suppression
+	* sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
+	* side files the Snapshot owner cares about (curator state); they are
+	* listed in the manifest and only those names are ever read back.
+	*/
+	async snapshotAll(reason = "pre-mutation", extras = []) {
 		const dest = join(join(this.root, ".backups"), `skills-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
 		const names = await listNames(this.root, this.io);
 		for (const name of names) await this.io.copy(skillDir(this.root, name), join(dest, name));
@@ -2251,15 +2262,47 @@ var SkillLibrary = class {
 			await this.io.copy(sidecar, join(dest, name));
 			sidecars.push(name);
 		}
+		const archiveRoot = join(this.root, ".archive");
+		let hasArchive = false;
+		if (await this.io.exists(archiveRoot)) {
+			await this.io.copy(archiveRoot, join(dest, ".archive"));
+			hasArchive = true;
+		}
+		const extraNames = [];
+		for (const extra of extras) {
+			if (!SNAPSHOT_EXTRA_NAME_RE.test(extra.name)) continue;
+			await this.io.writeText(join(dest, "extras", extra.name), extra.content);
+			extraNames.push(extra.name);
+		}
 		await this.io.writeText(join(dest, "manifest.json"), JSON.stringify({
 			reason,
 			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 			skills: names,
-			sidecars
+			sidecars,
+			hasArchive,
+			extras: extraNames
 		}, null, 2));
 		await this.retainSnapshots(5);
 		return dest;
 	}
+	/** Read and normalize a snapshot manifest; null when the file is missing or unparsable. */
+	async readSnapshotManifest(path) {
+		const raw = await this.io.readText(join(path, "manifest.json"));
+		if (raw === null) return null;
+		try {
+			const manifest = JSON.parse(raw);
+			return {
+				reason: typeof manifest.reason === "string" ? manifest.reason : "",
+				createdAt: typeof manifest.createdAt === "string" ? manifest.createdAt : "",
+				skills: Array.isArray(manifest.skills) ? manifest.skills : [],
+				sidecars: Array.isArray(manifest.sidecars) ? manifest.sidecars : [],
+				...typeof manifest.hasArchive === "boolean" ? { hasArchive: manifest.hasArchive } : {},
+				extras: Array.isArray(manifest.extras) ? manifest.extras : []
+			};
+		} catch {
+			return null;
+		}
+	}
 	/** Keep only the newest N snapshots (Hermes keep=5 parity); oldest folded into .backups history. */
 	async retainSnapshots(keep) {
 		const snapshots = await this.listSnapshots();
@@ -2278,36 +2321,69 @@ var SkillLibrary = class {
 		const out = [];
 		for (const name of entries.sort().reverse()) {
 			if (!name.startsWith("skills-")) continue;
-			try {
-				const raw = await this.io.readText(join(backupRoot, name, "manifest.json"));
-				if (raw === null) continue;
-				const manifest = JSON.parse(raw);
-				out.push({
-					path: join(backupRoot, name),
-					createdAt: manifest.createdAt ?? "",
-					reason: manifest.reason ?? ""
-				});
-			} catch {}
+			const manifest = await this.readSnapshotManifest(join(backupRoot, name));
+			if (manifest === null) continue;
+			out.push({
+				path: join(backupRoot, name),
+				createdAt: manifest.createdAt,
+				reason: manifest.reason
+			});
 		}
 		return out;
 	}
-	async restoreLatestSnapshot() {
+	/**
+	* Read the extras of a snapshot, restricted to the names declared in the
+	* manifest — an `extras/` directory is never listed directly, so unknown
+	* files cannot leak back as state on the next restore.
+	*/
+	async readSnapshotExtras(path) {
+		const manifest = await this.readSnapshotManifest(path);
+		if (manifest === null) return [];
+		const extras = [];
+		for (const name of manifest.extras) {
+			if (!SNAPSHOT_EXTRA_NAME_RE.test(name)) continue;
+			const content = await this.io.readText(join(path, "extras", name));
+			if (content !== null) extras.push({
+				name,
+				content
+			});
+		}
+		return extras;
+	}
+	/**
+	* Manifest-driven restore of the latest snapshot: active tree, sidecars,
+	* `.archive/` and (for full-state snapshots) the extras read back by the
+	* caller. `extras` are additionally written into the pre-rollback safety
+	* snapshot so the rollback itself is undoable with the same state.
+	*/
+	async restoreLatestSnapshot(extras = []) {
 		const latest = (await this.listSnapshots())[0];
 		if (!latest) return {
 			ok: false,
 			message: "No skill snapshot available."
 		};
-		await this.snapshotAll("pre-rollback");
+		await this.snapshotAll("pre-rollback", extras);
 		for (const name of await listNames(this.root, this.io)) await this.io.remove(skillDir(this.root, name));
-		const entries = await this.io.list(latest.path);
-		for (const entry of entries) {
-			if (entry === "manifest.json") continue;
+		const manifest = await this.readSnapshotManifest(latest.path);
+		if (manifest === null) for (const entry of await this.io.list(latest.path)) {
+			if (entry === "manifest.json" || entry === "extras") continue;
 			await this.io.copy(join(latest.path, entry), join(this.root, entry));
 		}
+		else {
+			for (const name of manifest.skills) await this.io.copy(join(latest.path, name), join(this.root, name));
+			for (const sidecar of manifest.sidecars) await this.io.copy(join(latest.path, sidecar), join(this.root, sidecar));
+			const archiveRoot = join(this.root, ".archive");
+			if (manifest.hasArchive === true) {
+				await this.io.remove(archiveRoot);
+				await this.io.copy(join(latest.path, ".archive"), archiveRoot);
+			} else if (manifest.hasArchive === false) await this.io.remove(archiveRoot);
+		}
+		const snapshotExtras = await this.readSnapshotExtras(latest.path);
 		return {
 			ok: true,
 			message: `Restored skill tree from ${latest.path}`,
-			path: latest.path
+			path: latest.path,
+			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
 		};
 	}
 };
@@ -2377,4 +2453,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_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, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, computeScopeView, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, 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, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, computeScopeView, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, 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/curator.d.ts

@@ -101,6 +101,8 @@ export interface ScopeView {
     managed: string[];
     /** Managed skills already flagged stale or quality-warned — the ones to watch. */
     watched: string[];
+    /** Managed skills flagged low quality (subset of `watched`) — consolidation candidates. */
+    qualityWarned: string[];
     /** Explicitly exempted by excludeSkillNames / referencedSkillNames. */
     exempted: string[];
     /** Carrying a protection marker (pinned / bundled / hub-installed). */

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

@@ -28,6 +28,26 @@ export interface SkillActionResult {
     message: string;
     path?: string;
 }
+/** Extra file name carried inside a snapshot's `extras/` directory. */
+export declare const SNAPSHOT_EXTRA_NAME_RE: RegExp;
+/** An opaque side file stored under a snapshot's `extras/` (curator state etc.). */
+export interface SnapshotExtra {
+    name: string;
+    content: string;
+}
+/** Normalized manifest of a skills snapshot. */
+export interface SnapshotManifest {
+    reason: string;
+    createdAt: string;
+    /** Active skill names at snapshot time. */
+    skills: string[];
+    /** Co-copied sidecar file names (usage/suppression). */
+    sidecars: string[];
+    /** Whether `.archive/` was co-copied; absent on legacy manifests (do not touch archive on restore). */
+    hasArchive?: boolean;
+    /** Extras declared under `extras/`; only these names are ever read back. */
+    extras: string[];
+}
 /** Who is writing: a foreground user-directed tool call, or the autonomous review/curator pipeline. */
 export type WriteOrigin = 'foreground' | 'subagent' | 'background_review';
 /** Options for `SkillLibrary.archive`. The absorbed-into name and the archival reason are distinct fields. */
@@ -99,7 +119,15 @@ export declare class SkillLibrary {
     restoreFromArchive(name: string): Promise<SkillActionResult>;
     writeSupportFile(name: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     removeSupportFile(name: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
-    snapshotAll(reason?: string): Promise<string>;
+    /**
+     * Snapshot the recoverable skills state: active tree, usage/suppression
+     * sidecars, `.archive/` and caller-supplied extras. `extras` are opaque
+     * side files the Snapshot owner cares about (curator state); they are
+     * listed in the manifest and only those names are ever read back.
+     */
+    snapshotAll(reason?: string, extras?: SnapshotExtra[]): Promise<string>;
+    /** Read and normalize a snapshot manifest; null when the file is missing or unparsable. */
+    readSnapshotManifest(path: string): Promise<SnapshotManifest | null>;
     /** Keep only the newest N snapshots (Hermes keep=5 parity); oldest folded into .backups history. */
     private retainSnapshots;
     listSnapshots(): Promise<Array<{
@@ -107,6 +135,20 @@ export declare class SkillLibrary {
         createdAt: string;
         reason: string;
     }>>;
-    restoreLatestSnapshot(): Promise<SkillActionResult>;
+    /**
+     * Read the extras of a snapshot, restricted to the names declared in the
+     * manifest — an `extras/` directory is never listed directly, so unknown
+     * files cannot leak back as state on the next restore.
+     */
+    readSnapshotExtras(path: string): Promise<SnapshotExtra[]>;
+    /**
+     * Manifest-driven restore of the latest snapshot: active tree, sidecars,
+     * `.archive/` and (for full-state snapshots) the extras read back by the
+     * caller. `extras` are additionally written into the pre-rollback safety
+     * snapshot so the rollback itself is undoable with the same state.
+     */
+    restoreLatestSnapshot(extras?: SnapshotExtra[]): Promise<SkillActionResult & {
+        extras?: SnapshotExtra[];
+    }>;
 }
 //# sourceMappingURL=skill-store.d.ts.map

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.36",
+  "version": "0.1.0-rc.38",
   "publishConfig": {
     "access": "public"
   },