@lmzhen/dsh-evolution-core 0.1.0-rc.7 → 0.1.0-rc.70

package/lib/index.js

@@ -1,16 +1,28 @@
-import { dirname, join } from "node:path";
-import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { readFileSync } from "node:fs";
 //#region lib/types/io.js
 /**
-* Structural IO seam for the legacy facade stores.
+* Structural IO seam for the evolution plugin family.
 *
-* The facade accepts any object exposing this small async file-tree surface.
-* Native DSH packages pass `ctx.evolutionIo.provider()`; standalone consumers
-* (and the facade's own tests) can use `nodeEvolutionIo`.
+* Every evolution package passes `ctx.evolutionIo.provider()`; standalone
+* consumers (and the core's own tests) can use `nodeEvolutionIo`.
 */
+/**
+* Run `task` inside `io.transact` when the backend provides it; otherwise fall
+* back to a plain read → task → write/remove sequence (no cross-process lock —
+* callers keep their single-process serialize chain as the second layer).
+*/
+async function transactIo(io, path, task) {
+	if (io.transact) {
+		await io.transact(path, task);
+		return;
+	}
+	const next = await task(await io.readText(path));
+	if (next === null) await io.remove(path);
+	else await io.writeText(path, next);
+}
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 function evolutionIoAdapter(provider) {
 	return {
@@ -20,23 +32,112 @@ function evolutionIoAdapter(provider) {
 		list: (path) => provider().list(path),
 		exists: (path) => provider().exists(path),
 		rename: (path, destination) => provider().rename(path, destination),
-		copy: (path, destination) => provider().copy(path, destination)
+		copy: (path, destination) => provider().copy(path, destination),
+		size: (path) => {
+			const io = provider();
+			return io.size ? io.size(path) : Promise.resolve(null);
+		},
+		transact: (path, task) => {
+			const io = provider();
+			return io.transact ? io.transact(path, task) : transactIo(io, path, task);
+		},
+		isSymlink: (path) => {
+			const io = provider();
+			return io.isSymlink ? io.isSymlink(path) : Promise.resolve(null);
+		}
 	};
 }
 function nodeEvolutionIo() {
+	const isMissing = (error) => {
+		const code = error?.code;
+		return code === "ENOENT" || code === "ENOTDIR";
+	};
+	/** True when the pid is alive (EPERM = alive but unowned; ESRCH = gone). */
+	const isAlive = (pid) => {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (error) {
+			return error?.code === "EPERM";
+		}
+	};
+	/**
+	* Cross-process write lock (claw `withFileLock` parity): an O_EXCL lock file
+	* guards the atomic write. A >5s-old lock is taken over ONLY after probing
+	* the holder pid it carries (rc.66): a LIVE holder is never stolen, so a
+	* slow writer no longer loses its lock to a peer at the 5s mark (the
+	* takeover is the only best-effort surface; the retry budget fails loud —
+	* rc.65 — instead of ever proceeding unlocked). Budget = 40 * 50ms (~2s,
+	* rc.69): 8-writer contention bursts on a loaded CI runner exceed 10
+	* attempts (500ms), and a fail-loud throw was observed instead of a clean
+	* serialization.
+	*/
+	const withWriteLock = async (path, task) => {
+		const lock = `${path}.lock`;
+		for (let attempt = 0; attempt < 40; attempt += 1) try {
+			await writeFile(lock, String(process.pid), { flag: "wx" });
+			try {
+				return await task();
+			} finally {
+				await rm(lock, { force: true }).catch(() => {});
+			}
+		} catch (error) {
+			const code = error?.code;
+			if (code !== "EEXIST" && code !== "EPERM") throw error;
+			try {
+				const st = await stat(lock);
+				if (Date.now() - st.mtimeMs > 5e3) {
+					const holder = Number(await readFile(lock, "utf8").catch(() => ""));
+					if (!(Number.isInteger(holder) && holder > 0 && isAlive(holder))) {
+						try {
+							await rm(lock, { force: true });
+						} catch {}
+						continue;
+					}
+				}
+			} catch {
+				continue;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+		throw new Error(`could not acquire write lock for ${path} after 40 attempts`);
+	};
 	return {
 		async readText(path) {
 			try {
 				return await readFile(path, "utf8");
-			} catch {
-				return null;
+			} catch (error) {
+				if (isMissing(error)) return null;
+				throw error;
 			}
 		},
 		async writeText(path, content) {
 			await mkdir(dirname(path), { recursive: true });
-			const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
-			await writeFile(tmp, content, "utf8");
-			await rename(tmp, path);
+			await withWriteLock(path, async () => {
+				const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+				await writeFile(tmp, content, "utf8");
+				await rename(tmp, path);
+			});
+		},
+		async transact(path, task) {
+			await mkdir(dirname(path), { recursive: true });
+			await withWriteLock(path, async () => {
+				let current;
+				try {
+					current = await readFile(path, "utf8");
+				} catch (error) {
+					if (isMissing(error)) current = null;
+					else throw error;
+				}
+				const next = await task(current);
+				if (next === null) {
+					await rm(path, { force: true });
+					return;
+				}
+				const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+				await writeFile(tmp, next, "utf8");
+				await rename(tmp, path);
+			});
 		},
 		async remove(path) {
 			await rm(path, {
@@ -47,16 +148,18 @@ function nodeEvolutionIo() {
 		async list(path) {
 			try {
 				return await readdir(path);
-			} catch {
-				return [];
+			} catch (error) {
+				if (isMissing(error)) return [];
+				throw error;
 			}
 		},
 		async exists(path) {
 			try {
 				await stat(path);
 				return true;
-			} catch {
-				return false;
+			} catch (error) {
+				if (isMissing(error)) return false;
+				throw error;
 			}
 		},
 		async rename(path, destination) {
@@ -69,13 +172,24 @@ function nodeEvolutionIo() {
 				recursive: true,
 				force: true
 			});
+		},
+		async size(path) {
+			try {
+				return (await stat(path)).size;
+			} catch (error) {
+				if (isMissing(error)) return null;
+				throw error;
+			}
+		},
+		async isSymlink(path) {
+			try {
+				return (await lstat(path)).isSymbolicLink();
+			} catch {
+				return null;
+			}
 		}
 	};
 }
-/** Absolute path helper kept separate so stores stay platform-correct. */
-function childPath(parent, ...parts) {
-	return join(parent, ...parts);
-}
 //#endregion
 //#region lib/types/usage.js
 /**
@@ -100,22 +214,106 @@ function emptyRecord() {
 		archived_at: null
 	};
 }
-async function loadUsage(root, io = nodeEvolutionIo()) {
+/** A timestamp passes only when `Date.parse` yields a finite epoch (N-3): a bare
+* string check let garbage like "not-a-date" propagate as Invalid Date → NaN
+* into quality math and lifecycle comparisons. */
+const validTimestamp = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const nullableTimestamp = (value) => value === null || validTimestamp(value);
+/**
+* Field-level normalization for one sidecar record (rc.42 audit P2-3): the
+* spread used to copy any junk through verbatim, so a corrupted file could
+* carry `use_count: "3"` into the quality math and lifecycle comparisons as
+* NaN. Every field falls back to its `emptyRecord()` baseline unless it has
+* exactly the declared type; an invalid `created_at` anchors the age clock at
+* now (first-sight defer semantics for a record whose age is unknowable).
+* Timestamps additionally require a parseable date (N-3): `"not-a-date"`
+* would otherwise survive the type check as Invalid Date.
+* Pure — exported for unit tests; `loadUsage` is the production caller.
+*/
+function normalizeUsageRecord(record) {
+	const base = emptyRecord();
+	if (!record || typeof record !== "object" || Array.isArray(record)) return base;
+	const raw = record;
+	const num = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+	const bool = (value, fallback) => typeof value === "boolean" ? value : fallback;
+	return {
+		created_by: typeof raw.created_by === "string" ? raw.created_by : null,
+		use_count: num(raw.use_count, base.use_count),
+		view_count: num(raw.view_count, base.view_count),
+		patch_count: num(raw.patch_count, base.patch_count),
+		last_used_at: nullableTimestamp(raw.last_used_at) ? raw.last_used_at : base.last_used_at,
+		last_viewed_at: nullableTimestamp(raw.last_viewed_at) ? raw.last_viewed_at : base.last_viewed_at,
+		last_patched_at: nullableTimestamp(raw.last_patched_at) ? raw.last_patched_at : base.last_patched_at,
+		created_at: validTimestamp(raw.created_at) ? raw.created_at : base.created_at,
+		state: raw.state === "stale" || raw.state === "archived" ? raw.state : "active",
+		pinned: bool(raw.pinned, base.pinned),
+		archived_at: nullableTimestamp(raw.archived_at) ? raw.archived_at : base.archived_at,
+		quality_score: typeof raw.quality_score === "number" && Number.isFinite(raw.quality_score) ? raw.quality_score : void 0,
+		quality_warn: typeof raw.quality_warn === "boolean" ? raw.quality_warn : void 0
+	};
+}
+/** Parse a raw usage sidecar; malformed content reads as empty (best-effort telemetry). */
+function parseUsage(raw) {
 	const map = /* @__PURE__ */ new Map();
-	const raw = await io.readText(usageFile(root));
-	if (raw !== null) try {
+	if (raw === null) return map;
+	try {
 		const parsed = JSON.parse(raw);
-		for (const [name, record] of Object.entries(parsed)) {
-			const base = emptyRecord();
-			map.set(name, {
-				...base,
-				...record,
-				state: record.state === "stale" || record.state === "archived" ? record.state : "active"
-			});
-		}
+		for (const [name, record] of Object.entries(parsed)) map.set(name, normalizeUsageRecord(record));
 	} catch {}
 	return map;
 }
+async function loadUsage(root, io = nodeEvolutionIo()) {
+	return parseUsage(await io.readText(usageFile(root)));
+}
+/**
+* Atomic read-modify-write on the usage sidecar (rc.50 P2-2): `task` receives
+* the map parsed from the current on-disk state and may mutate it; the result
+* is persisted inside the same transact so a second process sharing DSH_HOME
+* cannot interleave its RMW and lose a counter update. Callers keep their own
+* single-process serialize chain as the second layer.
+*/
+async function mutateUsage(root, io, task) {
+	await transactIo(io, usageFile(root), async (current) => {
+		if (current !== null) try {
+			JSON.parse(current);
+		} catch {
+			return current;
+		}
+		const map = parseUsage(current);
+		await task(map);
+		return JSON.stringify(Object.fromEntries(map.entries()), null, 2);
+	});
+}
+/**
+* Curator-owned usage fields (rc.67 K-2): the curator writes ONLY this set —
+* lifecycle state, archive stamp, the six-factor quality pair, and the
+* marker-mirrored pin flag. Counter and activity-stamp fields belong to the
+* tool-telemetry side (skill-usage / tool-skill-manage), which bumps them
+* through its own transact-backed RMW. A whole-record overwrite by either
+* side would clobber the other side's concurrent increment, so cross-side
+* folds copy this set only.
+*/
+function applyCuratorFields(disk, curated) {
+	disk.state = curated.state;
+	disk.archived_at = curated.archived_at;
+	disk.quality_score = curated.quality_score;
+	disk.quality_warn = curated.quality_warn;
+	disk.pinned = curated.pinned;
+}
+/**
+* Fold a curator run-start snapshot onto the current on-disk map (rc.67 K-2):
+* each curated record is projected onto its disk peer by copying only the
+* curator-owned fields, so a concurrent tool-side bump between snapshot and
+* save survives. Records absent from the snapshot are left untouched; a
+* curated record with no disk peer is seeded from the snapshot.
+*/
+function foldCuratorFields(disk, curated) {
+	for (const [name, record] of curated) {
+		const diskRecord = disk.get(name);
+		if (diskRecord) applyCuratorFields(diskRecord, record);
+		else disk.set(name, { ...record });
+	}
+}
 async function saveUsage(root, map, io = nodeEvolutionIo()) {
 	const obj = Object.fromEntries(map.entries());
 	await io.writeText(usageFile(root), JSON.stringify(obj, null, 2));
@@ -155,15 +353,174 @@ function latestActivityAt(record) {
 	if (values.length === 0) return null;
 	return values.sort().reverse()[0] ?? null;
 }
+/**
+* Curator suppression sidecar: built-in skills the curator has archived stay
+* suppressed across re-seeds, so the lifecycle never fights a re-created
+* bundled skill. Best-effort load/save, mirroring the usage sidecar posture.
+* Versioned shape ({ version, names }) with legacy plain-array compat.
+*/
+const SUPPRESSED_FILE_VERSION = 1;
+function suppressedFile(root) {
+	return join(root, ".curator-suppressed.json");
+}
+async function loadSuppressedNames(root, io = nodeEvolutionIo()) {
+	return parseSuppressed(await io.readText(suppressedFile(root)));
+}
+function parseSuppressed(raw) {
+	if (raw === null) return /* @__PURE__ */ new Set();
+	try {
+		const parsed = JSON.parse(raw);
+		const names = Array.isArray(parsed) ? parsed : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.names) ? parsed.names : [];
+		return new Set(names.filter((entry) => typeof entry === "string"));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+async function saveSuppressedNames(root, names, io = nodeEvolutionIo()) {
+	await io.writeText(suppressedFile(root), JSON.stringify({
+		version: 1,
+		names: [...names].sort()
+	}, null, 2));
+}
+/**
+* Atomic read-modify-write on the suppression sidecar (rc.50 P2-2): `task`
+* receives the set parsed from the current on-disk state and may mutate it;
+* the result is persisted inside the same transact so a second process
+* sharing DSH_HOME cannot interleave its RMW. Best-effort posture unchanged.
+*/
+async function updateSuppressedNames(root, io, task) {
+	await transactIo(io, suppressedFile(root), async (current) => {
+		if (current !== null) try {
+			JSON.parse(current);
+		} catch {
+			return current;
+		}
+		const names = parseSuppressed(current);
+		await task(names);
+		return JSON.stringify({
+			version: 1,
+			names: [...names].sort()
+		}, null, 2);
+	});
+}
+//#endregion
+//#region lib/types/constants.js
+/**
+* Shared constants for the dsh-evolution plugin family.
+*
+* Two classes of value live here, deliberately separated by section so future
+* edits do not blur the semantic boundary:
+*
+* 1. **Fixed protocol/format/security invariants** — changing these breaks an
+*    on-disk format, a naming/format contract, a path-security boundary, or a
+*    cross-component invariant. They are NOT exposed as deployment config.
+*
+* 2. **Cross-package shared tunable defaults** — the same semantic default is
+*    read (with a config override path) by more than one package (e.g.
+*    `evolution-policy` and `evolution-curator` both default `staleAfterDays`
+*    to 30). Centralizing them here means one authoritative default: a config
+*    override still applies per package, but the fallback is single-sourced.
+*
+* Package-private tunables (used by exactly one package) stay in that package,
+* not here — see evolution-replay's `DEFAULT_WEIGHTS` and evolution-feedback's
+* threshold, which are intentionally left where they are used.
+* @module @lmzhen/dsh-evolution-core
+*/
+/** Skill frontmatter `name` validated for the file name (lowercase + hyphen). */
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/** Allowed skill support-file subdirectories (path-traversal boundary). */
+const SUPPORT_DIRS = [
+	"references",
+	"templates",
+	"scripts",
+	"assets"
+];
+/** Delimiter between durable memory entries (on-disk storage format). */
+const ENTRY_DELIMITER = "\n§\n";
+/** Built-in skill names the curator must never lifecycle-manage. */
+const PROTECTED_BUILTIN_SKILLS = new Set(["plan"]);
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_SKILL_CONTENT_CHARS = 1e5;
+const MAX_SKILL_FILE_BYTES = 1048576;
+const DEFAULT_REVIEW_MEMORY_INTERVAL = 10;
+const DEFAULT_REVIEW_SKILL_INTERVAL = 10;
+/** Skill-review completion channel trigger mode: 'cadence' | 'completion' | 'both'. */
+const DEFAULT_SKILL_REVIEW_TRIGGER = "both";
+/** Cumulative session tool calls before a session counts as "proven long" for the completion channel. */
+const DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS = 20;
+const DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS = 3;
+const DEFAULT_SUBSTANTIVE_MIN_USER_CHARS = 200;
+const DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS = 500;
+const DEFAULT_MAX_OPS_PER_PLAN = 32;
+const DEFAULT_CURATOR_INTERVAL_HOURS = 168;
+const DEFAULT_MIN_IDLE_HOURS = 2;
+const DEFAULT_STALE_AFTER_DAYS = 30;
+const DEFAULT_ARCHIVE_AFTER_DAYS = 90;
+const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
+const DEFAULT_USER_CHAR_LIMIT = 1375;
+/** Consolidation-failure backoff cap, shared by MemoryStore and memory-files' Config default. */
+const DEFAULT_CONSOLIDATION_FAILURES = 3;
+const DEFAULT_SKILL_CONTENT_CHARS = 1e5;
+//#endregion
+//#region lib/types/gates.js
+/**
+* The control-plane protection sets, held once and queried everywhere
+* (decision B, rc.44 plan M2): the lifecycle engine, the scope view, the LLM
+* nomination gate and the control-plane consolidate all answer "is this name
+* off limits — and why" from the same instance, so the gate sets can never
+* drift apart the way the three pre-rc.46 implementations did.
+*
+* Scope boundary: a GateSet covers NAME-SET protections only. Marker-based
+* protections (pinned / bundled / hub-installed) are file markers resolved by
+* `SkillLibrary.writeProtection` / `deleteProtection` — they depend on the
+* filesystem and the write origin, not on a name list.
+* @module @lmzhen/dsh-evolution-core
+*/
+var EvolutionGateSet = class {
+	exclude;
+	referenced;
+	suppressed;
+	constructor(inputs = {}) {
+		this.exclude = inputs.exclude ?? /* @__PURE__ */ new Set();
+		this.referenced = inputs.referenced ?? /* @__PURE__ */ new Set();
+		this.suppressed = inputs.suppressed ?? /* @__PURE__ */ new Set();
+	}
+	/**
+	* The first protection blocking this name, or null. Any hit blocks — the
+	* order is diagnostic only, so a name in two sets reports the first.
+	*/
+	blockReason(name) {
+		if (this.exclude.has(name)) return "excluded";
+		if (this.referenced.has(name)) return "referenced";
+		if (this.suppressed.has(name)) return "suppressed";
+		if (PROTECTED_BUILTIN_SKILLS.has(name)) return "protected-builtin";
+		return null;
+	}
+	isBlocked(name) {
+		return this.blockReason(name) !== null;
+	}
+};
+/** Build a GateSet from the curator-style config field names. */
+function createGateSet(config) {
+	return new EvolutionGateSet({
+		exclude: config.excludeSkillNames,
+		referenced: config.referencedSkillNames,
+		suppressed: config.suppressedNames
+	});
+}
 //#endregion
 //#region lib/types/curator.js
 /**
 * Deterministic skill curator: active → stale → archived transitions.
-* Pure function; file moves are performed by SkillLibrary.
+* Pure function with one deliberate side effect: records in the passed
+* `usage` map are MUTATED (state/archived_at) to carry the transition — the
+* caller owns the map and decides whether to clone first (dry-run) or persist
+* after. File moves are performed by SkillLibrary.
 */
-const PROTECTED_BUILTIN_SKILLS = new Set(["plan"]);
 function buildCuratorRunReport(input) {
 	return {
+		schemaVersion: 1,
 		runId: input.runId,
 		startedAt: input.startedAt,
 		finishedAt: input.finishedAt,
@@ -172,25 +529,145 @@ function buildCuratorRunReport(input) {
 		archiveCandidates: [...input.archiveCandidates],
 		archived: [...input.archived],
 		failed: [...input.failed],
-		...input.snapshotPath === void 0 ? {} : { snapshotPath: input.snapshotPath }
+		...input.consolidated === void 0 ? {} : { consolidated: [...input.consolidated] },
+		...input.snapshotPath === void 0 ? {} : { snapshotPath: input.snapshotPath },
+		...input.llmReviewEnabled === void 0 ? {} : { llmReviewEnabled: input.llmReviewEnabled }
+	};
+}
+/**
+* Render a curator run report as a compact human-readable markdown digest
+* (G6): run metadata first, then the notable sections (archived / failed /
+* stale candidates / LLM nominations).
+*/
+function renderCuratorReportMarkdown(report) {
+	const lines = [
+		`# Curator run ${report.runId}`,
+		"",
+		`- **Started** ${report.startedAt}`,
+		`- **Finished** ${report.finishedAt}`,
+		`- **Stale candidates**: ${report.staleCandidates.length}`,
+		`- **LLM nominations**: ${report.llmNominations.length}`,
+		`- **Archived**: ${report.archived.length}`,
+		`- **Failed**: ${report.failed.length}`,
+		...report.snapshotPath === void 0 ? [] : [`- **Snapshot**: ${report.snapshotPath}`],
+		...report.llmReviewEnabled === void 0 ? [] : [`- **llmReview**: ${report.llmReviewEnabled}`]
+	];
+	const section = (title, items) => items.length === 0 ? [] : [
+		"",
+		`## ${title}`,
+		"",
+		...items.map((item) => `- ${item}`)
+	];
+	return [
+		...lines,
+		...section("Archived", report.archived.map((item) => `${item.name} (${item.reason})`)),
+		...section("Failed", report.failed.map((item) => `${item.name}: ${item.reason}`)),
+		...section("Stale candidates", report.staleCandidates),
+		...section("LLM nominations", report.llmNominations),
+		""
+	].join("\n");
+}
+const NOMINATION_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+* Parse the curator LLM's YAML nomination block (consolidations + prunings).
+* Line-oriented and lenient by design: the LLM output is advisory, every name
+* is re-validated against the tree before any file move happens downstream.
+*/
+function parseCuratorNominations(text) {
+	const prunings = [];
+	const consolidations = [];
+	let section = null;
+	let currentFrom = "";
+	for (const line of text.split("\n")) {
+		const consolidated = /^\s*-\s*from:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (consolidated) {
+			section = "consolidations";
+			currentFrom = consolidated[1] ?? "";
+			continue;
+		}
+		const into = /^\s*into:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (into) {
+			const intoName = into[1] ?? "";
+			if (section === "consolidations" && currentFrom !== "" && currentFrom !== intoName) consolidations.push({
+				from: currentFrom,
+				into: intoName
+			});
+			currentFrom = "";
+			continue;
+		}
+		const pruned = /^\s*-\s*name:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(line);
+		if (pruned) {
+			section = "prunings";
+			const name = pruned[1];
+			if (name) prunings.push(name);
+		}
+	}
+	const valid = (name) => NOMINATION_NAME_RE.test(name);
+	return {
+		prunings: prunings.filter(valid),
+		consolidations: consolidations.filter((item) => valid(item.from) && valid(item.into))
+	};
+}
+/**
+* The lifecycle-candidate gate, shared by the transition engine and the scope
+* view so the two can never disagree: records failing ANY of these gates are
+* outside the managed scope.
+*/
+function lifecycleCandidate(name, record, config, bundled, gates = createGateSet(config)) {
+	if (record.pinned) return false;
+	if (gates.isBlocked(name)) return false;
+	if (!(record.created_by === "agent" || config.manageUnmanaged === true) && !(config.pruneBuiltins === true && bundled)) return false;
+	if (record.state === "archived") return false;
+	return true;
+}
+/**
+* Read-only scope classification, derived from the SAME gate the transition
+* engine uses (`lifecycleCandidate`), so the view always predicts what a
+* curator pass may touch. `protectedNames` carries the marker info the usage
+* records lack (bundled / hub-installed / pinned from `SkillLibrary.list()`).
+*/
+function computeScopeView(usage, config, protectedNames, gates) {
+	const managed = [];
+	const watched = [];
+	const qualityWarned = [];
+	const exempted = [];
+	const protectedSet = /* @__PURE__ */ new Set();
+	const gateSet = gates ?? createGateSet(config);
+	for (const [name, record] of usage) {
+		if (gateSet.exclude.has(name) || gateSet.referenced.has(name)) {
+			exempted.push(name);
+			continue;
+		}
+		const bundled = config.bundledNames?.has(name) === true;
+		const suppressed = gateSet.suppressed.has(name);
+		if (record.pinned || bundled || suppressed || protectedNames?.has(name) === true) protectedSet.add(name);
+		if (lifecycleCandidate(name, record, config, bundled, gateSet)) {
+			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()
 	};
 }
 function daysSince(iso, created, now) {
 	return (now - new Date(iso ?? created).getTime()) / 864e5;
 }
-function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Date()) {
+function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Date(), gates) {
 	const result = {
 		transitions: [],
 		archive: [],
 		reactivate: [],
 		markStale: []
 	};
+	const gateSet = gates ?? createGateSet(config);
 	for (const [name, record] of usage) {
-		if (record.pinned) continue;
-		if (config.excludeSkillNames?.has(name)) continue;
-		if (record.created_by !== "agent" && config.manageUnmanaged !== true) continue;
-		if (PROTECTED_BUILTIN_SKILLS.has(name)) continue;
-		if (record.state === "archived") continue;
+		if (!lifecycleCandidate(name, record, config, config.bundledNames?.has(name) === true, gateSet)) continue;
 		const age = daysSince(null, record.created_at, now.getTime());
 		if (record.use_count === 0 && age < config.staleAfterDays) continue;
 		const idle = daysSince(latestActivityAt(record), record.created_at, now.getTime());
@@ -242,6 +719,426 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 	return result;
 }
 //#endregion
+//#region lib/types/evolution-events.js
+/**
+* Self-evolution event log (rc.68): an append-only sidecar under
+* `$DSH_HOME/evolution/events.json` that is the single source of truth for
+* the self-improvement loop. Feedback increments and learn actions share one
+* ordered timeline (`seq` is the ordering key), so "feedback before/after a
+* learn on target X" is answerable. The aggregate `feedback.json` is a
+* rebuildable boot cache, never the truth.
+*
+* The malformed-refusal posture matches the whole sidecar family (rc.65): an
+* append NEVER rewrites a corrupt log — the bytes stay untouched.
+*/
+const EVENT_LOG_VERSION = 1;
+function eventsFile(home) {
+	return join(home, "evolution", "events.json");
+}
+function isEventRecord(event) {
+	return typeof event === "object" && event !== null && typeof event.seq === "number";
+}
+/**
+* Parse an event log body. A missing file, a whitespace-only file (rc.69:
+* rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
+* is still refused on append, never overwritten.
+*
+* Per-entry normalization (rc.70 F-1): entries without a numeric `seq` are
+* skipped here and dropped at the next append — valid entries survive, the
+* damaged record is the only loss (self-heal semantics, matching the usage
+* sidecar's per-field normalization on read).
+*/
+function parseEvolutionEvents(raw) {
+	if (raw === null || raw.trim() === "") return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return [];
+		return parsed.events.filter(isEventRecord);
+	} catch {
+		return [];
+	}
+}
+/**
+* Append one event under the write lock (rc.68): `seq` = current max + 1
+* computed inside the transact, so two processes appending concurrently never
+* collide. A malformed log is refused (bytes preserved) and the append fails.
+* Returns the assigned seq.
+*/
+async function appendEvolutionEvent(io, path, event) {
+	let assigned = 0;
+	await transactIo(io, path, (current) => {
+		if (current !== null && current.trim() !== "") try {
+			JSON.parse(current);
+		} catch {
+			return Promise.resolve(current);
+		}
+		const events = parseEvolutionEvents(current);
+		const maxSeq = events.reduce((max, entry) => Math.max(max, entry.seq), 0);
+		const record = {
+			...event,
+			seq: maxSeq + 1,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		assigned = record.seq;
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			events: [...events, record]
+		}, null, 2));
+	});
+	if (assigned === 0) throw new Error(`evolution event log is malformed and was not touched: ${path}`);
+	return assigned;
+}
+/** Read the event log; a missing/whitespace-only file reads as empty,
+* corrupt content is flagged (and refused on append). */
+async function readEvolutionEvents(io, path) {
+	const raw = await io.readText(path);
+	if (raw === null || raw.trim() === "") return {
+		events: [],
+		malformed: false
+	};
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return {
+			events: [],
+			malformed: false
+		};
+		return {
+			events: parsed.events.filter(isEventRecord),
+			malformed: false
+		};
+	} catch {
+		return {
+			events: [],
+			malformed: true
+		};
+	}
+}
+//#endregion
+//#region lib/types/prompts.js
+/**
+* Review and curation prompts adapted from Hermes Agent
+* `agent/background_review.py`, `agent/curator.py`, and
+* `agent/learn_prompt.py`, with tool names translated to the DSH-native
+* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
+*
+* Alignment policy (2026-08-29): the OPERATIONAL steps and instructions the
+* model follows mirror the Hermes originals structurally (signal list,
+* preference order, support-file taxonomy, curator package integrity,
+* consolidated/pruned reporting block). Tool and platform differences are
+* DSH-adapted (native tool names, pinned-within-review semantics, this
+* platform's index cap), and DSH-only additions are marked as such.
+*
+* Every prompt is pinned in a versioned bundle. Review workers verify the
+* bundle digest before spending a model call, so a partially-patched
+* deployment fails closed instead of silently running a truncated prompt.
+*/
+/**
+* Prompt bundle identity. Bump both id and version whenever a prompt's text
+* changes semantically: the bundle digest is the fail-closed signal for
+* review workers, so a stale id across deployments must be distinguishable.
+*/
+const PROMPT_BUNDLE_ID = "dsh-evolution@7";
+const PROMPT_BUNDLE_VERSION = 7;
+const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
+Review the conversation above and consider saving to memory if appropriate.
+
+Focus on:
+1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
+2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
+
+If something stands out, save it using the memory tool.
+If nothing is worth saving, just say "Nothing to save." and stop.`;
+const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
+Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small. A pass that does nothing is a missed learning opportunity, not a neutral outcome.
+
+Target shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.
+
+Signals to look for (any one of these warrants action):
+  • User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.
+  • User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.
+  • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.
+  • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.
+
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
+Preference order — prefer the earliest action that fits, but do pick one when a signal above fired:
+  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.
+  2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.
+  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files — use the right directory per kind:
+     • references/<topic>.md — session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.
+     • templates/<name>.<ext> — starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).
+     • scripts/<name>.<ext> — statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).
+     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.
+  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong — fall back to (1), (2), or (3).
+
+User-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.
+
+If you notice two existing skills that overlap, note it in your reply — the background curator handles consolidation at scale.
+
+Two-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:
+  • PATTERN (reusable — symptom → mechanism → fix → verification, still valuable next session) belongs in the SKILL.md body.
+  • LOG (one-off — commit SHAs, npm/profile states, what this release changed, this session's process narrative) belongs in a references/ file, never the body. Body density IS reuse rate. Keep new entries tight: a pattern fits in 2-8 physical lines; prefer changing the current-state pointer over appending history.
+
+Protected skills (DO NOT edit these):
+  • Bundled skills (shipped with the platform).
+  • Hub-installed skills (installed from a hub).
+Pinned skills are read-only to THIS background review pass — the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.
+If the only skills that need updating are protected, say 'Nothing to save.' and stop.
+
+Do NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):
+  • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules.
+  • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.
+  • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.
+  • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.
+
+If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint.
+
+'Nothing to save.' is a real option but should NOT be the default. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.`;
+const COMBINED_REVIEW_PROMPT = `[Auto-review]
+Review the conversation above and update two things:
+
+**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.
+
+**Skills**: how to do this class of task. Be ACTIVE — most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.
+
+Target shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.
+
+Signals that warrant a skill update (any one is enough):
+  • User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' — embed the lesson in the skill that governs that task so the next session starts fixed.
+  • Non-trivial technique, fix, workaround, or debugging path emerged.
+  • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now.
+
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
+Preference order for skills — pick the earliest that fits:
+  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.
+  2. UPDATE AN EXISTING UMBRELLA. Patch it.
+  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: references/<topic>.md for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; templates/<name>.<ext> for starter files meant to be copied and modified; scripts/<name>.<ext> for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.
+  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level — NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).
+
+Two-tier deposition discipline (DSH addition): classify before writing — PATTERN (symptom → mechanism → fix → verification) goes in the SKILL.md body; LOG (commit SHAs, npm/profile states, this release's change list, this session's narrative) goes in a references/ file. Body density IS reuse rate; a pattern fits in 2-8 physical lines.
+
+User-preference embedding: when the user complains about how you handled a task, update the skill that governs that task — memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.
+
+If you notice overlapping existing skills, mention it — the background curator handles consolidation.
+
+Protected skills (DO NOT edit these):
+  • Bundled skills (shipped with the platform).
+  • Hub-installed skills (installed from a hub).
+Pinned skills are read-only to THIS background review pass — the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.
+If the only skills that need updating are protected, say 'Nothing to save.' and stop.
+
+Do NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):
+  • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules.
+  • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.
+  • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.
+  • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.
+
+If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint.
+
+Act on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop — but don't reach for that conclusion as a default.`;
+const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
+
+This is an UMBRELLA-BUILDING consolidation pass, not a passive audit and not a duplicate-finder.
+
+The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
+
+Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
+
+Hard rules:
+1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
+2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (referenced) skills. Referenced skills are fully protected — never consolidated, never pruned (there is no scheduled-task reference-rewriting pass; a referenced skill stays in place by design).
+3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet. Never archive a never-used skill unless it is at least 30 days old AND its content is genuinely obsolete or fully absorbed elsewhere.
+4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
+5. Judge overlap on CONTENT, not on usage counters.
+6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
+
+How to work:
+1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword. Expected cluster count scales with the library: a large collection may show 10-25 prefix clusters, a small one often has none — a clean "nothing to consolidate" summary is the correct small-library outcome, not a shortage of ambition.
+2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
+   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
+   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
+   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella. Use the right directory per kind:
+      • references/<topic>.md — session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes, provider quirks, reproduction recipes) written concise and task-focused.
+      • templates/<name>.<ext> — starter files meant to be copied and modified.
+      • scripts/<name>.<ext> — statically re-runnable actions (verification scripts, fixture generators, probes).
+3. Package integrity — not optional: inspect each skill as a COMPLETE directory package, not just SKILL.md. A skill root may include references/, templates/, scripts/, and assets/. If the source skill has support files OR its SKILL.md contains relative links to them, DO NOT flatten only SKILL.md into <umbrella>/references/<old>.md. Choose one safe path instead: keep it as a standalone skill, OR fully merge by re-homing every needed support file into the umbrella's canonical directories AND rewriting the destination instructions to the new paths, OR archive the entire original skill package unchanged. Never leave demoted instructions pointing at files left behind under the old skill directory.
+4. Flag skills whose NAME is too narrow (contains a PR number, a feature codename, a specific error string, an 'audit'/'diagnosis'/'salvage' session artifact) — they almost always belong as a subsection or support file under a class-level umbrella.
+5. Iterate. After one consolidation round, scan the remaining set and look for the NEXT umbrella opportunity. Don't stop after 3 merges.
+
+You are a NOMINATOR, not an executor: this channel has NO tools. Your single deliverable is the structured YAML block below. Never narrate actions you did not take ("merged", "patched", "archived") — you are proposing, and the deterministic engine executes only names from the candidate pool it gave you. (A future execution view would expose skill_manage; today it does not.)
+
+'keep' is a legitimate decision ONLY when the skill is already a class-level umbrella and none of the proposed merges would improve discoverability. 'This is narrow but distinct from its siblings' is NOT a reason to keep — it's a reason to move it under an umbrella as a subsection or support file.
+
+Expected output: real umbrella-ification. Process every obvious cluster. If you end the pass with obvious clusters still untouched, you stopped too early — go back and look at the clusters you left alone.
+
+Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
+
+When done, write a human summary THEN the structured machine-readable block. The block is the contract: every skill you would move to .archive/ MUST appear in exactly one of the two lists. Return ONLY the YAML block after the summary — no post-block prose. Format EXACTLY:
+
+## Structured summary (required)
+\`\`\`yaml
+consolidations:
+  - from: <old-skill-name>
+    into: <umbrella-skill-name>
+    reason: <one short sentence — why merged, not just 'similar'>
+prunings:
+  - name: <skill-name>
+    reason: <one short sentence — why archived with no merge target>
+\`\`\`
+
+Every skill you would move to .archive/ MUST appear in exactly one of the two lists. If you consolidated X into umbrella Y (patched Y, wrote a references file to Y, or created Y with X's content absorbed), X goes under consolidations with into: Y. If you archived X with no absorption — truly stale, irrelevant, or obsolete — X goes under prunings. Leave a list empty (consolidations: []) if none. Do not omit the block. The block comes AFTER your human-readable summary of clusters processed, patches made, and decisions left alone.`;
+const CURATOR_DRY_RUN_BANNER = `═══════════════════════════════════════════════════════════════
+DRY-RUN — REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.
+═══════════════════════════════════════════════════════════════
+
+This is a PREVIEW pass. Follow every instruction above EXCEPT:
+  • Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.
+  • Do NOT move, copy, or rewrite any file under the skills tree.
+
+Your output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.
+
+If you accidentally take a mutating action, say so explicitly in the summary.`;
+const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
+Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
+
+Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch ONLY skills loaded or read this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
+
+Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
+/**
+* System-prompt guidance section (Hermes `SKILLS_GUIDANCE`, DSH-adapted).
+* Registered as a system-prompt section by tool-skill-manage (it mounts
+* exactly when `skill_manage` is available — the DSH analogue of Hermes'
+* `if "skill_manage" in agent.valid_tool_names` condition). Instructs the
+* model to save/repair skills on its own initiative.
+*/
+const SKILLS_GUIDANCE = `Skills guidance:
+• After completing a complex task (5+ tool calls), fixing a tricky error, or discovering a non-trivial workflow, save the approach as a skill with skill_manage so you can reuse it next time.
+• When using a skill and finding it outdated, incomplete, or wrong, patch it immediately with skill_manage (action='patch') — don't wait to be asked. Skills that aren't maintained become liabilities.`;
+const PLAN_CHANNEL_NOTE = `
+
+CHANNEL (subagent): this review channel mounts only the read-only \`skill\` tool — you have NO \`skill_manage\`, NO \`memory\`. Your deliverable is the structured JSON plan below (outputSchema). Describe the patches/creates you RECOMMEND in the plan; never narrate actions you took.`;
+/** Subagent-channel variant: same review policy, channel-limited deliverable (M-2). */
+const SKILL_REVIEW_PLAN_PROMPT = `${SKILL_REVIEW_PROMPT}${PLAN_CHANNEL_NOTE}`;
+/** Subagent-channel variant of the combined review (M-2). */
+const COMBINED_REVIEW_PLAN_PROMPT = `${COMBINED_REVIEW_PROMPT}${PLAN_CHANNEL_NOTE}`;
+function reviewPrompt(kind, channel = "agent") {
+	if (kind === "memory") return MEMORY_REVIEW_PROMPT;
+	if (channel === "plan") return kind === "skill" ? SKILL_REVIEW_PLAN_PROMPT : COMBINED_REVIEW_PLAN_PROMPT;
+	if (kind === "skill") return SKILL_REVIEW_PROMPT;
+	return COMBINED_REVIEW_PROMPT;
+}
+function sha256(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+function createPromptBundle(prompts) {
+	const canonical = JSON.stringify({
+		id: PROMPT_BUNDLE_ID,
+		version: 7,
+		prompts: Object.fromEntries(Object.entries(prompts).sort())
+	});
+	return Object.freeze({
+		id: PROMPT_BUNDLE_ID,
+		version: 7,
+		prompts: Object.freeze({ ...prompts }),
+		sha256: sha256(canonical)
+	});
+}
+const PROMPT_BUNDLE = createPromptBundle({
+	memory: MEMORY_REVIEW_PROMPT,
+	skill: SKILL_REVIEW_PROMPT,
+	combined: COMBINED_REVIEW_PROMPT,
+	skillPlan: SKILL_REVIEW_PLAN_PROMPT,
+	combinedPlan: COMBINED_REVIEW_PLAN_PROMPT,
+	curator: CURATOR_PROMPT,
+	completion: COMPLETION_SKILL_REVIEW_PROMPT,
+	skillsGuidance: SKILLS_GUIDANCE
+});
+function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
+	if (bundle.id !== "dsh-evolution@7" || bundle.version !== 7) return false;
+	const canonical = JSON.stringify({
+		id: PROMPT_BUNDLE_ID,
+		version: 7,
+		prompts: Object.fromEntries(Object.entries(bundle.prompts).sort())
+	});
+	return bundle.sha256 === sha256(canonical);
+}
+const DSH_AUTHORING_STANDARDS = `Follow the Hermes skill-authoring standards, translated to DSH tools.
+
+Frontmatter:
+- name: lowercase-hyphenated, <=64 chars, no spaces.
+- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.
+- version: 0.1.0
+- author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe — an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.
+- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.
+- metadata.hermes.tags: a few Capitalized, Relevant, Tags.
+- metadata.hermes.related_skills: [a, b] — name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).
+
+Body section order (omit only when empty):
+1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
+2. "## When to Use" — concrete trigger phrases.
+3. "## Prerequisites" — exact env vars, install steps, credentials.
+4. "## How to Run" — canonical invocation framed through DSH tools.
+5. "## Quick Reference" — flat command/endpoint list.
+6. "## Procedure" — numbered steps with copy-paste-exact commands.
+7. "## Pitfalls" — known limits and rate limits.
+8. "## Verification" — one check proving the skill worked.
+
+DSH-tool framing:
+- Reference DSH tools by name in backticks: \`bash\`, \`str_replace_editor\`, \`write\`, \`skill\`, \`skill_manage\`, \`memory\`.
+- Do not name wrapped shell utilities when a DSH tool already covers them.
+- Larger scripts belong under \`scripts/\` (written with \`skill_manage write_file\`) and are referenced from SKILL.md by relative path.
+
+Quality bar:
+- Prefer verbatim flags, paths, and APIs from the source. Never invent them.
+- Keep it tight: ~100 lines simple, ~200 complex.
+- No router/index/hub skills that only point at other skills.
+- References go in \`references/\`, templates in \`templates/\`.
+
+Learn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):
+1. Gather every source named (files, URLs, "what we just did", pasted notes) with the tools you already have — and treat prose after a source as authoring requirements, not noise.
+2. Apply every requirement and constraint from the request to the SKILL.md you author.
+3. Author exactly ONE SKILL.md and save it with \`skill_manage\` (action=create); non-trivial scripts go under \`scripts/\`.
+4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.`;
+//#endregion
+//#region lib/types/learn-prompt.js
+/**
+* Open-ended `/evolution learn` prompt builder.
+*
+* `learn` is open-ended: the user can name anything they can describe — a
+* directory of code, an API doc URL, a workflow they just walked the agent
+* through, or pasted notes. The prompt instructs the live agent to gather the
+* named sources with its existing tools, then author a single SKILL.md via
+* `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+* distillation engine and no model-tool footprint.
+*/
+/**
+* Build the agent prompt for an open-ended `/evolution learn` request.
+*
+* @param userRequest free-text the user gave after `/evolution learn`; an
+*   empty string falls back to "the workflow we just went through".
+* @returns a complete instruction the agent runs as a normal turn.
+*/
+function buildLearnPrompt(userRequest) {
+	return [
+		"[/learn] The user wants you to learn a reusable skill from the request below, and save it.",
+		"",
+		"THE REQUEST:",
+		userRequest.trim() || "the workflow we just went through in this conversation — review the steps taken and distill them into a reusable skill",
+		"",
+		"The request is open-ended and may mix two kinds of content, in any order: SOURCES to gather (directories, file paths, URLs, \"what we just did\", pasted notes) AND REQUIREMENTS that shape the skill (what to focus on, what to leave out, scope, naming, the angle to take). Treat EVERY part of the request as load-bearing. In particular, prose that comes after a path or link is NOT incidental — it is the user telling you what they want from that source. A request like `<url> focus on the auth flow, skip the deprecated endpoints` means: gather the URL AND honor \"focus on auth, skip deprecated\" as authoring requirements. Never fetch the first source and ignore the rest.",
+		"",
+		"Do this:",
+		"1. Gather every source the user named, using the tools you already have — reads and searches for local files or directories, web access for URLs, this conversation history if they referred to something you just did, and the text they pasted as-is. If the request is ambiguous about scope, make a reasonable choice and note it; do not stall.",
+		"2. Author ONE SKILL.md, applying every requirement, focus, and constraint in the request — these govern what the SKILL.md covers and emphasizes, not just which sources you read.",
+		"3. Save it with the `skill_manage` tool (action=\"create\"). Pick a sensible category. If the procedure needs a non-trivial script, add it under the skill's `scripts/` with `skill_manage` write_file and reference it by relative path.",
+		"",
+		DSH_AUTHORING_STANDARDS,
+		"",
+		"When done, tell the user the skill name, its category, and a one-line summary of what it captured."
+	].join("\n");
+}
+//#endregion
 //#region lib/types/threats.js
 /**
 * Threat scanning for agent-authored memory and skill content.
@@ -417,10 +1314,12 @@ const SCOPE_ORDER = {
 	context: 2,
 	strict: 3
 };
+const NO_SCAN_OPTIONS = {};
 /**
 * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
+* `options.excludeLabels` removes matching patterns without changing `scope`.
 */
-function scanThreats(text, scope = "strict", maxScanChars = 65536) {
+function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
 	const findings = [];
 	if (ZERO_WIDTH_CHARS.test(text)) findings.push({
 		label: "unicode_zero_width",
@@ -433,8 +1332,10 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536) {
 		scope
 	});
 	const normalized = text.normalize("NFKC").slice(0, maxScanChars);
+	const excluded = new Set(options.excludeLabels ?? []);
 	for (const pattern of PATTERNS) {
 		if (SCOPE_ORDER[pattern.scope] > SCOPE_ORDER[scope]) continue;
+		if (excluded.has(pattern.label)) continue;
 		if (pattern.regex.test(normalized)) findings.push({
 			label: pattern.label,
 			category: pattern.category,
@@ -444,24 +1345,24 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536) {
 	return findings;
 }
 /** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */
-function evaluateThreat(text, scope = "strict", maxScanChars = 65536) {
-	const findings = scanThreats(text, scope, maxScanChars);
+function evaluateThreat(text, scope = "strict", maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
+	const findings = scanThreats(text, scope, maxScanChars, options);
 	return {
 		blocked: findings.length > 0,
 		findings
 	};
 }
 /** User-facing block message for memory writes. */
-function scanMemoryThreats(text, maxScanChars = 65536) {
-	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars);
+function scanMemoryThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
+	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars, options);
 	if (!blocked) return null;
 	const pattern = findings.find((f) => f.category !== "unicode_obfuscation");
 	if (pattern) return `Blocked by security scan (${pattern.label}). Rephrase without instruction-like language.`;
 	return "Blocked by security scan: invisible or potentially malicious Unicode detected.";
 }
 /** User-facing block message for skill content writes. */
-function scanContentThreats(text, maxScanChars = 65536) {
-	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars);
+function scanContentThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
+	const { blocked, findings } = evaluateThreat(text, "strict", maxScanChars, options);
 	if (!blocked) return null;
 	return `Blocked by security scan (${findings[0]?.label ?? "unknown"}). This content appears to contain potentially malicious instructions.`;
 }
@@ -471,7 +1372,39 @@ function scanContentThreats(text, maxScanChars = 65536) {
 * File-backed durable memory with Hermes-compatible semantics.
 * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
 */
-const ENTRY_DELIMITER = "\n§\n";
+/**
+* Read-guard factor: a memory file larger than this multiple of its target's
+* char limit is treated as externally corrupted and skipped instead of being
+* read whole (aligned with claw `tools/memory.ts` size guard, which uses the
+* same 10× bound around a file that should never exceed the store limit).
+*/
+const READ_GUARD_FACTOR = 10;
+/**
+* Consolidation-failure backoff window (package-private, rc.42 audit P2-1):
+* only failures inside the window count toward `maxConsolidationFailures`.
+* The store cannot observe turn boundaries, so the model-facing "this turn"
+* phrasing is approximated with ten minutes — generous enough to cover one
+* turn's retry loop, short enough that a failure yesterday never makes today's
+* first refusal say "stop retrying".
+*/
+const FAILURE_WINDOW_MS = 10 * 6e4;
+/**
+* Recoverable-error preview bounds (B-line G5, Hermes `_previews` parity):
+* failed replace/remove/batch calls echo the current entries so the model can
+* self-recover without re-reading the store. Bounded to five entries of eighty
+* characters each; package-private because it is an error-message shape, not a
+* behavior switch.
+*/
+const ERROR_PREVIEW_ENTRIES = 5;
+const ERROR_PREVIEW_WIDTH = 80;
+function previewEntries(entries) {
+	if (entries.length === 0) return "";
+	const shown = entries.slice(0, ERROR_PREVIEW_ENTRIES).map((entry) => {
+		return `- ${entry.length > ERROR_PREVIEW_WIDTH ? `${entry.slice(0, ERROR_PREVIEW_WIDTH)}…` : entry}`;
+	});
+	const more = entries.length > ERROR_PREVIEW_ENTRIES ? `\n  (+${entries.length - ERROR_PREVIEW_ENTRIES} more)` : "";
+	return `\n\nCurrent entries (preview):\n${shown.join("\n")}${more}`;
+}
 function memoryRoot(env = process.env) {
 	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "memories");
 }
@@ -495,6 +1428,7 @@ var MemoryStore = class {
 	maxFailures;
 	io;
 	failureCount = 0;
+	lastFailureAt = 0;
 	constructor(options = {}) {
 		this.io = options.io ?? nodeEvolutionIo();
 		this.memoryLimit = options.memoryCharLimit ?? 2200;
@@ -506,7 +1440,24 @@ var MemoryStore = class {
 	limitFor(target) {
 		return target === "memory" ? this.memoryLimit : this.userLimit;
 	}
+	/**
+	* Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+	* `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+	* (backend without a size probe), under the bound, or the target has no
+	* limit configured.
+	*/
+	async oversizedFile(target) {
+		const size = await this.io.size?.(fileFor(this.root, target));
+		if (size === null || size === void 0) return null;
+		const limit = this.limitFor(target);
+		if (limit <= 0) return null;
+		return size > limit * READ_GUARD_FACTOR ? {
+			size,
+			limit
+		} : null;
+	}
 	async read(target) {
+		if (await this.oversizedFile(target)) return [];
 		const raw = await this.io.readText(fileFor(this.root, target));
 		return raw === null ? [] : [...new Set(normalizeEntries(raw))];
 	}
@@ -517,133 +1468,168 @@ var MemoryStore = class {
 		this.failureCount = 0;
 	}
 	failure(target, message, entries) {
+		if (Date.now() - this.lastFailureAt > FAILURE_WINDOW_MS) this.failureCount = 0;
+		this.lastFailureAt = Date.now();
 		this.failureCount += 1;
 		const chars = entries.join(ENTRY_DELIMITER).length;
 		if (this.failureCount > this.maxFailures) return {
 			ok: false,
-			message: `Memory consolidation failed ${this.failureCount} times this turn. Stop retrying memory calls and continue with the user's task.`,
+			message: `Memory consolidation failed ${this.failureCount} times this turn. Stop retrying memory calls and continue with the user's task.${previewEntries(entries)}`,
 			entries,
 			chars,
 			limit: this.limitFor(target)
 		};
 		return {
 			ok: false,
-			message,
+			message: `${message}${previewEntries(entries)}`,
 			entries,
 			chars,
 			limit: this.limitFor(target)
 		};
 	}
-	async add(target, facts) {
-		const content = facts.trim();
-		if (!content) return {
+	/**
+	* StorageHint percentage must clamp at 100 like the render header: a drifted
+	* entry can push chars past the limit, and "Storage at 125%" contradicts the
+	* clamped usage indicator.
+	*/
+	storageHint(target, chars) {
+		const limit = this.limitFor(target);
+		if (limit <= 0) return "";
+		const percent = Math.min(100, Math.floor(chars * 100 / limit));
+		return percent >= 80 ? ` ⚠️ Storage at ${percent}% (${chars}/${limit} chars).` : "";
+	}
+	/**
+	* Best-effort raw-copy backup of the on-disk file to `<file>.bak.<stamp>`
+	* before a refusal, so an externally modified (or oversized) file stays
+	* recoverable. Copies bytes instead of reading them so a pathologically
+	* large file is never loaded just to back it up. Failure to back up does
+	* not change the refusal semantics.
+	*/
+	async backupFile(target) {
+		const path = fileFor(this.root, target);
+		const unique = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+		try {
+			await this.io.copy(path, `${path}.bak.${unique}`);
+			return `${path}.bak.${unique}`;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Read-guard refusal for write paths. Returns the refusal result when the
+	* target file is oversized, `null` otherwise. The file is skipped for
+	* reading (never loaded), backed up by raw copy, and the model is told to
+	* fix it manually — mirroring the drift refusal so corrupted state is never
+	* silently overwritten.
+	*/
+	async oversizedRefusal(target) {
+		const oversized = await this.oversizedFile(target);
+		if (!oversized) return null;
+		const backup = await this.backupFile(target);
+		const suffix = backup ? ` A backup was saved to ${basename(backup)}.` : "";
+		return {
 			ok: false,
-			message: "Content cannot be empty.",
+			message: `Memory file is ${oversized.size} bytes (limit ${oversized.limit * READ_GUARD_FACTOR}) — skipping read.${suffix} Fix the file manually, then retry.`,
 			entries: [],
 			chars: 0,
 			limit: this.limitFor(target)
 		};
-		const threat = scanMemoryThreats(content);
-		if (threat) return {
+	}
+	async add(target, facts) {
+		if (!facts.trim()) return {
 			ok: false,
-			message: threat,
+			message: "Content cannot be empty.",
 			entries: [],
 			chars: 0,
 			limit: this.limitFor(target)
 		};
-		const entries = await this.read(target);
-		if (entries.some((entry) => stripDatePrefix(entry) === content)) {
-			this.resetFailures();
+		const path = fileFor(this.root, target);
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return refusal;
+		let outcome;
+		await transactIo(this.io, path, async (current) => {
+			const core = await this.addCore(target, facts, current ?? "");
+			outcome = core.result;
+			return core.write ?? current ?? null;
+		});
+		return outcome;
+	}
+	/**
+	* Single-entry add inside the transaction: shared checks (oversized,
+	* drift, threat) and the content computation. `raw` is the locked view
+	* (`current`) — never a second IO read. `write: null` means "no change".
+	*/
+	async addCore(target, facts, raw) {
+		const content = facts.trim();
+		if (!content) return {
+			result: this.failure(target, "Content cannot be empty.", []),
+			write: null
+		};
+		if (this.driftFromRaw(target, raw)) {
+			const backup = await this.backupFile(target);
 			return {
-				ok: true,
-				message: "Entry already exists (no duplicate added).",
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
+					entries: [],
+					chars: 0,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 		}
-		const next = [...entries, this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${content}` : content];
-		const total = next.join(ENTRY_DELIMITER).length;
-		if (total > this.limitFor(target)) return this.failure(target, `Adding this entry would exceed the ${this.limitFor(target)} char limit. Consolidate or remove stale entries, then retry.`, entries);
-		await this.write(target, next);
-		this.resetFailures();
-		return {
-			ok: true,
-			message: "Entry added.",
-			entries: next,
-			chars: total,
-			limit: this.limitFor(target)
-		};
-	}
-	async replace(target, oldText, facts) {
-		return this.mutate(target, oldText, "replace", facts);
-	}
-	async remove(target, oldText) {
-		return this.mutate(target, oldText, "remove", void 0);
-	}
-	async mutate(target, oldText, action, facts) {
-		const needle = oldText.trim();
-		if (!needle) return {
-			ok: false,
-			message: "old_text cannot be empty.",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
-		const content = action === "replace" ? (facts ?? "").trim() : "";
-		if (action === "replace" && !content) return {
-			ok: false,
-			message: "facts is required for replace; use remove to delete.",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
-		if (action === "replace") {
-			const threat = scanMemoryThreats(content);
-			if (threat) return {
+		const threat = scanMemoryThreats(content);
+		if (threat) return {
+			result: {
 				ok: false,
 				message: threat,
 				entries: [],
 				chars: 0,
 				limit: this.limitFor(target)
+			},
+			write: null
+		};
+		const entries = [...new Set(normalizeEntries(raw))];
+		if (entries.some((entry) => stripDatePrefix(entry) === content)) {
+			this.resetFailures();
+			return {
+				result: {
+					ok: true,
+					message: `Entry already exists (no duplicate added).${this.storageHint(target, entries.join(ENTRY_DELIMITER).length)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 		}
-		if (await this.detectDrift(target)) return {
-			ok: false,
-			message: "External drift detected in memory file. Resolve the drift before retrying.",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
-		const entries = await this.read(target);
-		const matches = entries.map((entry, index) => ({
-			entry,
-			index
-		})).filter(({ entry }) => entry.includes(needle));
-		if (matches.length === 0) return this.failure(target, `No entry matching "${needle}" found.`, entries);
-		if (new Set(matches.map((m) => m.entry)).size > 1) return {
-			ok: false,
-			message: `Multiple distinct entries matched "${needle}". Be more specific.`,
-			entries,
-			chars: entries.join(ENTRY_DELIMITER).length,
-			limit: this.limitFor(target)
-		};
-		const index = matches[0]?.index ?? -1;
-		const next = [...entries];
-		if (action === "remove") next.splice(index, 1);
-		else next[index] = content;
+		const next = [...entries, this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${content}` : content];
 		const total = next.join(ENTRY_DELIMITER).length;
-		if (total > this.limitFor(target)) return this.failure(target, `Resulting memory would exceed the ${this.limitFor(target)} char limit.`, entries);
-		await this.write(target, next);
+		const addLimit = this.limitFor(target);
+		if (addLimit > 0 && total > addLimit) return {
+			result: this.failure(target, `Adding this entry would exceed the ${addLimit} char limit. Consolidate or remove stale entries, then retry.`, entries),
+			write: null
+		};
 		this.resetFailures();
 		return {
-			ok: true,
-			message: `Entry ${action === "remove" ? "removed" : "replaced"}.`,
-			entries: next,
-			chars: total,
-			limit: this.limitFor(target)
+			result: {
+				ok: true,
+				message: `Entry added.${this.storageHint(target, total)}`,
+				entries: next,
+				chars: total,
+				limit: this.limitFor(target)
+			},
+			write: render(next)
 		};
 	}
+	/** Canonical-form drift check derived from the locked view (same formula as `detectDrift`, no second read). */
+	driftFromRaw(target, raw) {
+		if (raw.trim() === "") return false;
+		const entries = normalizeEntries(raw);
+		const limit = this.limitFor(target);
+		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
+		return render(entries) !== raw;
+	}
 	async applyBatch(target, operations) {
 		if (operations.length === 0) return {
 			ok: false,
@@ -652,261 +1638,402 @@ var MemoryStore = class {
 			chars: 0,
 			limit: this.limitFor(target)
 		};
-		if (await this.detectDrift(target)) return {
-			ok: false,
-			message: "External drift detected in memory file. Resolve the drift before retrying.",
-			entries: [],
-			chars: 0,
-			limit: this.limitFor(target)
-		};
-		const entries = await this.read(target);
+		const path = fileFor(this.root, target);
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return refusal;
+		let outcome;
+		await transactIo(this.io, path, async (current) => {
+			const core = await this.applyBatchCore(target, operations, current ?? "");
+			outcome = core.result;
+			return core.write ?? current ?? null;
+		});
+		return outcome;
+	}
+	/** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
+	async applyBatchCore(target, operations, raw) {
+		if (this.driftFromRaw(target, raw)) {
+			const backup = await this.backupFile(target);
+			return {
+				result: {
+					ok: false,
+					message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
+					entries: [],
+					chars: 0,
+					limit: this.limitFor(target)
+				},
+				write: null
+			};
+		}
+		const entries = [...new Set(normalizeEntries(raw))];
 		const working = [...entries];
 		for (const [index, op] of operations.entries()) {
 			const position = index + 1;
 			if (op.action === "add") {
 				const body = (op.facts ?? "").trim();
 				if (!body) return {
-					ok: false,
-					message: `Operation ${position} (add): facts is required. No operations were applied.`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position} (add): facts is required. No operations were applied.${previewEntries(entries)}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				const threat = scanMemoryThreats(body);
 				if (threat) return {
-					ok: false,
-					message: `Operation ${position}: ${threat}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position}: ${threat}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				if (!working.some((entry) => stripDatePrefix(entry) === body)) working.push(this.addDatePrefix ? `## ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}\n${body}` : body);
 				continue;
 			}
 			const needle = (op.old_text ?? "").trim();
 			if (!needle) return {
-				ok: false,
-				message: `Operation ${position} (${op.action}): old_text is required. No operations were applied.`,
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `Operation ${position} (${op.action}): old_text is required. No operations were applied.${previewEntries(entries)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 			const matches = working.map((entry, matchIndex) => ({
 				entry,
 				matchIndex
 			})).filter(({ entry }) => entry.includes(needle));
-			if (matches.length === 0) return this.failure(target, `Operation ${position}: no entry matching "${needle}" found. No operations were applied.`, entries);
+			if (matches.length === 0) return {
+				result: this.failure(target, `Operation ${position}: no entry matching "${needle}" found. No operations were applied.`, entries),
+				write: null
+			};
 			if (new Set(matches.map((m) => m.entry)).size > 1) return {
-				ok: false,
-				message: `Operation ${position}: "${needle}" matched multiple distinct entries. No operations were applied.`,
-				entries,
-				chars: entries.join(ENTRY_DELIMITER).length,
-				limit: this.limitFor(target)
+				result: {
+					ok: false,
+					message: `Operation ${position}: "${needle}" matched multiple distinct entries. No operations were applied.${previewEntries(entries)}`,
+					entries,
+					chars: entries.join(ENTRY_DELIMITER).length,
+					limit: this.limitFor(target)
+				},
+				write: null
 			};
 			const matchIndex = matches[0]?.matchIndex ?? -1;
 			if (op.action === "remove") working.splice(matchIndex, 1);
 			else {
 				const body = (op.facts ?? "").trim();
 				if (!body) return {
-					ok: false,
-					message: `Operation ${position} (replace): facts is required.`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position} (replace): facts is required.${previewEntries(entries)}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				const threat = scanMemoryThreats(body);
 				if (threat) return {
-					ok: false,
-					message: `Operation ${position}: ${threat}`,
-					entries,
-					chars: entries.join(ENTRY_DELIMITER).length,
-					limit: this.limitFor(target)
+					result: {
+						ok: false,
+						message: `Operation ${position}: ${threat}`,
+						entries,
+						chars: entries.join(ENTRY_DELIMITER).length,
+						limit: this.limitFor(target)
+					},
+					write: null
 				};
 				working[matchIndex] = body;
 			}
 		}
 		const total = working.join(ENTRY_DELIMITER).length;
-		if (total > this.limitFor(target)) return this.failure(target, `Batch result (${total} chars) exceeds the ${this.limitFor(target)} limit. Remove or shorten more entries in the same batch.`, entries);
-		await this.write(target, working);
+		const batchLimit = this.limitFor(target);
+		if (batchLimit > 0 && total > batchLimit) return {
+			result: this.failure(target, `Batch result (${total} chars) exceeds the ${batchLimit} limit. Remove or shorten more entries in the same batch.`, entries),
+			write: null
+		};
 		this.resetFailures();
 		return {
-			ok: true,
-			message: `Applied ${operations.length} operation(s).`,
-			entries: working,
-			chars: total,
-			limit: this.limitFor(target)
+			result: {
+				ok: true,
+				message: `Applied ${operations.length} operation(s).${this.storageHint(target, total)}`,
+				entries: working,
+				chars: total,
+				limit: this.limitFor(target)
+			},
+			write: render(working)
 		};
 	}
 	async renderContext() {
 		const memory = await this.read("memory");
 		const user = await this.read("user");
 		const parts = [];
-		for (const [target, entries] of [["Memory", memory], ["User Profile", user]]) {
+		for (const [target, label, entries] of [[
+			"memory",
+			"Memory",
+			memory
+		], [
+			"user",
+			"User Profile",
+			user
+		]]) {
+			const oversized = entries.length === 0 ? await this.oversizedFile(target) : null;
+			if (oversized) {
+				parts.push(`## ${label} — file skipped: ${oversized.size} bytes (limit ${oversized.limit * READ_GUARD_FACTOR}); not read`);
+				continue;
+			}
 			const safe = entries.filter((entry) => !scanMemoryThreats(entry));
 			if (safe.length > 0) {
 				const body = safe.join(ENTRY_DELIMITER);
+				const limit = this.limitFor(target);
+				const pct = limit > 0 ? Math.min(100, Math.floor(body.length * 100 / limit)) : 0;
 				const note = safe.length === entries.length ? "" : ` (${entries.length - safe.length} threat-matched entries filtered)`;
-				parts.push(`## ${target} (${safe.length} entries)${note}\n${body}`);
+				parts.push(`## ${label} (${safe.length} entries) [${pct}% — ${body.length}/${limit} chars]${note}\n${body}`);
 			}
 		}
 		return parts.join("\n\n");
 	}
-	async snapshot() {
-		const [memory, user] = await Promise.all([this.read("memory"), this.read("user")]);
-		return {
-			memory,
-			user
-		};
-	}
-	async restoreSnapshot(snapshot) {
-		await this.write("memory", snapshot.memory);
-		await this.write("user", snapshot.user);
-	}
+	/**
+	* Detect on-disk drift: true when the file is not in the canonical
+	* `render(normalizeEntries(raw))` form. This catches structural anomalies
+	* the writer would quietly normalize away (empty/`§`-only entries, stray
+	* blank lines, leading/trailing delimiters) that indicate the file was
+	* edited outside MemoryStore. Purely single-canonical content reaches the
+	* same serialization and returns false, so a normal write is never flagged.
+	*
+	* An absent, empty, or whitespace-only file is the "never written" state
+	* (rc.42 audit P1-6): it parses to zero entries, so the canonical form
+	* `'\n'` can never byte-match it and every write path was permanently
+	* refused with "External drift detected" — including the repairs the model
+	* would need to make. Such files are adopted instead of flagged.
+	*/
 	async detectDrift(target) {
+		if (await this.oversizedFile(target)) return true;
 		const raw = await this.io.readText(fileFor(this.root, target));
-		if (raw === null) return false;
-		return normalizeEntries(raw).join(ENTRY_DELIMITER) !== raw.trim();
+		if (raw === null || raw.trim() === "") return false;
+		const entries = normalizeEntries(raw);
+		const limit = this.limitFor(target);
+		if (limit > 0 && entries.some((entry) => entry.length > limit)) return true;
+		return render(entries) !== raw;
 	}
 };
 //#endregion
-//#region lib/types/prompts.js
+//#region lib/types/mutations.js
 /**
-* Review and curation prompts adapted from Hermes Agent
-* `agent/background_review.py`, `agent/curator.py`, and
-* `agent/learn_prompt.py`, with tool names translated to the DSH-native
-* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
-*
-* Every prompt is pinned in a versioned bundle. Review workers verify the
-* bundle digest before spending a model call, so a partially-patched
-* deployment fails closed instead of silently running a truncated prompt.
+* 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 PROMPT_BUNDLE_ID = "dsh-evolution@1";
-const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
-Review the conversation above and consider saving to memory if appropriate.
-
-Focus on:
-1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
-2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
-
-If something stands out, save it using the memory tool.
-If nothing is worth saving, just say "Nothing to save." and stop.`;
-const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
-Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small.
-
-Target shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.
-
-Signals that warrant action:
-- The user corrected your style, tone, format, verbosity, workflow, or approach.
-- A non-trivial technique, fix, workaround, or debugging path emerged.
-- A loaded skill turned out wrong, missing, or outdated — patch it now.
-
-Preference order:
-1. Patch a skill that was loaded or read this session.
-2. Patch an existing umbrella skill.
-3. Add references/, templates/, or scripts/ support under an existing skill.
-4. Create a new class-level umbrella skill only when nothing fits.
-
-Protected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.
-
-Do NOT capture:
-- Environment-dependent failures (missing binaries, unconfigured credentials).
-- Negative claims about tools ("browser tools do not work").
-- Transient errors that resolved during the session.
-- One-off task narratives.
-
-If a tool failed because of setup state, capture the FIX under an existing setup skill — never "this tool does not work" as a standalone constraint.
-
-"Nothing to save." is a real option but should NOT be the default.`;
-const COMBINED_REVIEW_PROMPT = `[Auto-review]
-Review the conversation above and update two things.
-
-**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.
-
-**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.
-
-Act on whichever dimension has real signal. If genuinely nothing stands out on either, say "Nothing to save." and stop — but don't reach for that conclusion as a default.`;
-const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library.
-
-Rules:
-1. NEVER hard-delete a skill. Archive is the maximum destructive action.
-2. Do not touch bundled, hub-installed, or pinned skills.
-3. Do not archive recently-created or never-used skills without strong evidence.
-4. Prefer merging narrow skills into class-level umbrellas.
-5. Before archiving a merged skill, ensure its unique content was preserved.
-
-Produce a YAML summary:
-consolidations:
-  - from: <old-skill-name>
-    into: <umbrella-skill-name>
-    reason: <one short sentence>
-prunings:
-  - name: <skill-name>
-    reason: <one short sentence>`;
-function reviewPrompt(kind) {
-	if (kind === "memory") return MEMORY_REVIEW_PROMPT;
-	if (kind === "skill") return SKILL_REVIEW_PROMPT;
-	return COMBINED_REVIEW_PROMPT;
+const DEFAULT_MUTATION_CAP = 500;
+/** Version of the `.mutations.json` file shape; writers always emit the current one. */
+const MUTATIONS_FILE_VERSION = 1;
+function mutationsFile(root) {
+	return join(root, ".mutations.json");
+}
+function contentHash(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+/**
+* Parse a raw mutations sidecar; malformed content reads as empty (auditing is
+* best-effort). Versioned shape ({ version, records }) with legacy
+* plain-array compat, plus a field-level guard for records without the
+* required identity/timestamp fields (rc.42 audit P2-3).
+*/
+function parseMutationRecords(raw) {
+	if (raw === null) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		return (Array.isArray(parsed) ? parsed : typeof parsed === "object" && parsed !== null && Array.isArray(parsed.records) ? parsed.records : []).filter((entry) => typeof entry === "object" && entry !== null && typeof entry.skillName === "string" && typeof entry.action === "string" && typeof entry.at === "string");
+	} catch {
+		return [];
+	}
+}
+async function loadMutations(root, io = nodeEvolutionIo()) {
+	return parseMutationRecords(await io.readText(mutationsFile(root)));
+}
+/** Append one record, trim to `cap`, and write atomically (versioned shape). */
+async function recordMutation(root, io, record, cap = 500) {
+	await transactIo(io, mutationsFile(root), async (current) => {
+		if (current !== null) try {
+			JSON.parse(current);
+		} catch {
+			return current;
+		}
+		const existing = parseMutationRecords(current);
+		existing.push(record);
+		const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			records: trimmed
+		}, null, 2));
+	});
 }
-function sha256(text) {
-	return createHash("sha256").update(text).digest("hex");
+//#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 createPromptBundle(prompts) {
-	const canonical = JSON.stringify({
-		id: PROMPT_BUNDLE_ID,
-		version: 1,
-		prompts: Object.fromEntries(Object.entries(prompts).sort())
-	});
-	return Object.freeze({
-		id: PROMPT_BUNDLE_ID,
-		version: 1,
-		prompts: Object.freeze({ ...prompts }),
-		sha256: sha256(canonical)
-	});
+function daysBetween(from, now) {
+	return Math.max(0, (now.getTime() - new Date(from).getTime()) / 864e5);
 }
-const PROMPT_BUNDLE = createPromptBundle({
-	memory: MEMORY_REVIEW_PROMPT,
-	skill: SKILL_REVIEW_PROMPT,
-	combined: COMBINED_REVIEW_PROMPT,
-	curator: CURATOR_PROMPT
-});
-function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
-	const canonical = JSON.stringify({
-		id: bundle.id,
-		version: bundle.version,
-		prompts: Object.fromEntries(Object.entries(bundle.prompts).sort())
-	});
-	return bundle.sha256 === sha256(canonical);
+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);
+}
+/**
+* Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
+* the curator prompt asks the model to identify "prefix clusters — skills
+* sharing a first word or domain keyword"; the deterministic index supplies
+* stable ground truth instead of letting the model infer clusters from the
+* raw list. Key = first alphanumeric run of the lowercased name; groups with
+* at least two members, largest first then alphabetical. Orientation-only:
+* nomination authority stays with the LLM and the candidate-pool gates.
+*/
+function computePrefixClusters(names) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const key = name.toLowerCase().split(/[^a-z0-9]+/)[0];
+		if (!key) continue;
+		const bucket = groups.get(key);
+		if (bucket) bucket.push(name);
+		else groups.set(key, [name]);
+	}
+	return [...groups.entries()].filter(([, members]) => members.length >= 2).map(([key, members]) => ({
+		key,
+		members
+	})).sort((a, b) => b.members.length - a.members.length || a.key.localeCompare(b.key));
 }
-const DSH_AUTHORING_STANDARDS = `Follow the Hermes skill-authoring standards, translated to DSH tools.
-
-Frontmatter:
-- name: lowercase-hyphenated, <=64 chars, no spaces.
-- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.
-- version: 0.1.0
-- author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe.
-- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.
-- metadata.hermes.tags: a few Capitalized, Relevant, Tags.
-
-Body section order (omit only when empty):
-1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
-2. "## When to Use" — concrete trigger phrases.
-3. "## Prerequisites" — exact env vars, install steps, credentials.
-4. "## How to Run" — canonical invocation framed through DSH tools.
-5. "## Quick Reference" — flat command/endpoint list.
-6. "## Procedure" — numbered steps with copy-paste-exact commands.
-7. "## Pitfalls" — known limits and rate limits.
-8. "## Verification" — one check proving the skill worked.
-
-DSH-tool framing:
-- Reference DSH tools by name in backticks: \`bash\`, \`str_replace_editor\`, \`write\`, \`skill\`, \`skill_manage\`, \`memory\`.
-- Do not name wrapped shell utilities when a DSH tool already covers them.
-- Larger scripts belong under \`scripts/\` (written with \`skill_manage write_file\`) and are referenced from SKILL.md by relative path.
-
-Quality bar:
-- Prefer verbatim flags, paths, and APIs from the source. Never invent them.
-- Keep it tight: ~100 lines simple, ~200 complex.
-- No router/index/hub skills that only point at other skills.
-- References go in \`references/\`, templates in \`templates/\`.`;
 //#endregion
 //#region lib/types/signals.js
 /**
@@ -994,31 +2121,53 @@ function foldTurn(session, fromSeq) {
 * it created unless a `.hermes-managed` marker opts a skill in. Archival is a
 * move to `.archive/` — never a hard delete.
 */
-const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-const MAX_SKILL_NAME_LENGTH = 64;
-const MAX_DESCRIPTION_LENGTH = 1024;
-const MAX_SKILL_CONTENT_CHARS = 1e5;
-const MAX_SKILL_FILE_BYTES = 1048576;
 const DEFAULT_SKILL_LIMITS = {
 	maxNameLength: 64,
 	maxDescriptionLength: MAX_DESCRIPTION_LENGTH,
 	maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
 	maxSkillFileBytes: MAX_SKILL_FILE_BYTES
 };
-const SUPPORT_DIRS = [
-	"references",
-	"templates",
-	"scripts",
-	"assets"
-];
+/** 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");
 }
+/**
+* Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
+* the APPROVAL surface treats every delegated subagent as the autonomous
+* review channel, while the LIBRARY surface keeps the Hermes distinction -
+* the review fork is 'background_review' (the pinned guard blocks its
+* writes) and any other subagent is 'subagent' (agent-authored, not
+* review-channel). `isReview` marks the caller as the background review
+* pipeline itself. Single source: the two tools and the review executor all
+* read this table instead of re-deriving it.
+*/
+function resolveOrigins(headerOrigin, isReview = false) {
+	if (isReview) return {
+		approval: "background_review",
+		library: "background_review"
+	};
+	if (headerOrigin === "subagent") return {
+		approval: "background_review",
+		library: "subagent"
+	};
+	return {
+		approval: "foreground",
+		library: "foreground"
+	};
+}
 function skillDir(root, name) {
 	return join(root, name);
 }
+/** Dot-prefixed on-disk marker name. SINGLE source: `list()` matches directory
+* entries against this name, and path builders must never hardcode a marker
+* literal (N-1: the rc.49 exists()-probe convergence dropped the dot,
+* poisoning every protectedBy/managed report). */
+function markerEntryName(marker) {
+	return `.${marker}`;
+}
 function markerPath(dir, marker) {
-	return join(dir, `.${marker}`);
+	return join(dir, markerEntryName(marker));
 }
 function parseFrontmatter(content) {
 	if (!content.trimStart().startsWith("---")) return null;
@@ -1040,6 +2189,26 @@ function parseFrontmatter(content) {
 		body
 	};
 }
+/**
+* Skill names referenced by a SKILL.md's `related_skills` frontmatter
+* (B-line G3, rc.44): the single parsing source for the quality references
+* factor and the learning-graph edges. The DSH frontmatter parser keeps the
+* YAML value as a string (`"[a, b]"`), so names are scanned out of it; each
+* must satisfy the skill-name shape and the referencing skill itself is
+* excluded. Pure and deduplicated.
+*/
+function relatedSkillNames(content, exclude) {
+	const parsed = parseFrontmatter(content);
+	if (!parsed) return [];
+	const raw = parsed.frontmatter["related_skills"];
+	if (typeof raw !== "string") return [];
+	const names = /* @__PURE__ */ new Set();
+	for (const match of Array.from(raw.matchAll(/[a-z0-9][a-z0-9-]*/g))) {
+		const target = match[0];
+		if (target && SKILL_NAME_RE.test(target) && target !== exclude) names.add(target);
+	}
+	return [...names];
+}
 function validateFrontmatter(content, expectedName, limits = DEFAULT_SKILL_LIMITS) {
 	const parsed = parseFrontmatter(content);
 	if (!parsed) return "SKILL.md must start and end with YAML frontmatter and include a body.";
@@ -1052,6 +2221,31 @@ function validateFrontmatter(content, expectedName, limits = DEFAULT_SKILL_LIMIT
 	if (content.length > limits.maxSkillContentChars) return `SKILL.md content exceeds ${limits.maxSkillContentChars} characters.`;
 	return null;
 }
+/** Hermes authoring quality bar for descriptions (the 60-char Rule). The
+* platform's own index limit stays in `validateFrontmatter`; this bar is the
+* target the authoring standard names, enforced as ADVISORY feedback. */
+const AUTHORING_DESCRIPTION_BAR = 60;
+/**
+* Advisory authoring feedback (P0): evaluate frontmatter against the
+* authoring bar WITHOUT changing platform validation semantics. The bar is
+* the quality target, `validateFrontmatter`'s limits are the compatibility
+* floor, and this bridge layer tells the model when its text would be
+* truncated or route-poor instead of silently shipping it.
+*/
+function authoringFeedback(frontmatter) {
+	const description = frontmatter.description ?? "";
+	const over60 = description.length > 60;
+	const hasColon = description.includes(":");
+	const lines = [];
+	lines.push(over60 ? `Description is ${description.length}/60 characters — exceeds the 60-char authoring bar (Hermes standard; the catalog truncates at the configured platform cap).` : `Description ${description.length}/60 characters — within the authoring bar.`);
+	if (hasColon) lines.push("Description contains a colon — wrap the whole value in double quotes.");
+	return {
+		descriptionChars: description.length,
+		over60,
+		hasColon,
+		lines
+	};
+}
 async function listNames(root, io) {
 	const entries = await io.list(root);
 	const names = [];
@@ -1069,65 +2263,274 @@ function validateSupportPath(filePath) {
 	if (parts.length < 2) return "Provide a file name, not just a directory.";
 	return null;
 }
+/**
+* Index of `pattern` inside `content`, treating whitespace runs (spaces/tabs)
+* as flexible and literal escape sequences (`\n`, `\t`, `\r`) as their real
+* characters: a PATTERN whitespace run matches any content run of any length
+* (even empty), while extra whitespace that only exists in the content is not
+* skipped — the flexibility is one-sided on the pattern, and a backslash-
+* escaped char in the pattern matches the real char in the content
+* (model-copy drift). Returns the [start, end) range in the ORIGINAL content
+* so a patch can replace exactly the matched span and keep every other byte
+* intact. Returns null when no fuzzy match exists.
+*/
+function fuzzyIndexOf(content, pattern, from = 0) {
+	const isSpace = (char) => char !== void 0 && /[ \t]/.test(char);
+	const escaped = (char) => {
+		if (char === "n") return "\n";
+		if (char === "t") return "	";
+		if (char === "r") return "\r";
+		return null;
+	};
+	for (let start = from; start < content.length; start += 1) {
+		let contentIndex = start;
+		let patternIndex = 0;
+		while (patternIndex < pattern.length && contentIndex < content.length) {
+			const patternChar = pattern[patternIndex];
+			const contentChar = content[contentIndex];
+			if (isSpace(patternChar)) {
+				while (patternIndex < pattern.length && isSpace(pattern[patternIndex])) patternIndex += 1;
+				while (contentIndex < content.length && isSpace(content[contentIndex])) contentIndex += 1;
+				continue;
+			}
+			const escapedChar = patternChar === "\\" ? escaped(pattern[patternIndex + 1]) : null;
+			if (escapedChar !== null && contentChar === escapedChar) {
+				patternIndex += 2;
+				contentIndex += 1;
+				continue;
+			}
+			if (patternChar === contentChar) {
+				contentIndex += 1;
+				patternIndex += 1;
+				continue;
+			}
+			break;
+		}
+		if (patternIndex === pattern.length) return [start, contentIndex];
+	}
+	return null;
+}
+/** Trim leading whitespace of the first line and trailing whitespace of the last line. */
+function trimPatternBoundaries(pattern) {
+	const from = pattern.search(/\S/);
+	const trimmed = from < 0 ? pattern : pattern.slice(from);
+	const trailing = trimmed.search(/\s+$/);
+	return trailing < 0 ? trimmed : trimmed.slice(0, trailing);
+}
+/** Replace only the fuzzy-matched span, preserving all surrounding bytes. */
+function fuzzyReplace(content, oldString, newString, replaceAll) {
+	let current = content;
+	let scanFrom = 0;
+	for (;;) {
+		const match = fuzzyIndexOf(current, oldString, scanFrom);
+		if (match === null) return current;
+		const [start, end] = match;
+		const next = current.slice(0, start) + newString + current.slice(end);
+		if (!replaceAll) return next;
+		current = next;
+		scanFrom = start + newString.length;
+	}
+}
 function fuzzyPatch(content, oldString, newString, replaceAll = false) {
+	if (oldString === "") return null;
 	if (content.includes(oldString)) return replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString);
-	const trimmed = content.replaceAll(/[ 	]+$/gm, "");
-	if (trimmed.includes(oldString)) return trimmed.replace(oldString, newString);
-	const whitespace = content.replaceAll(/[ 	]+/g, " ");
-	if (whitespace.includes(oldString)) return whitespace.replace(oldString, newString);
+	const boundary = trimPatternBoundaries(oldString);
+	if (boundary === "") return null;
+	if (boundary !== oldString) {
+		if (fuzzyIndexOf(content, boundary) !== null) {
+			const patched = fuzzyReplace(content, boundary, newString, replaceAll);
+			return patched === content ? null : patched;
+		}
+	}
+	if (fuzzyIndexOf(content, oldString) !== null) {
+		const patched = fuzzyReplace(content, oldString, newString, replaceAll);
+		return patched === content ? null : patched;
+	}
 	return null;
 }
 var SkillLibrary = class {
 	root;
 	limits;
 	io;
-	constructor(root = skillsRoot(), io = nodeEvolutionIo(), limits = DEFAULT_SKILL_LIMITS) {
+	onMutation;
+	constructor(root = skillsRoot(), io = nodeEvolutionIo(), limits = DEFAULT_SKILL_LIMITS, onMutation) {
 		this.root = root;
 		this.io = io;
 		this.limits = limits;
+		this.onMutation = onMutation;
+	}
+	/** Notify the mutation observer after a successful write; observers must never fail the mutation. */
+	notifyMutation(event) {
+		try {
+			this.onMutation?.(event);
+		} catch {}
 	}
 	async list() {
 		const summaries = [];
 		for (const name of await listNames(this.root, this.io)) {
-			const dir = skillDir(this.root, name);
+			const dir = this.dirOf(name);
 			const md = await this.io.readText(join(dir, "SKILL.md"));
 			if (!md) continue;
 			const parsed = parseFrontmatter(md);
-			const protectedBy = await this.deleteProtection(name);
-			const managed = await this.io.exists(markerPath(dir, "hermes-managed"));
+			let entries = [];
+			try {
+				entries = await this.io.list(dir);
+			} catch {}
+			const has = (marker) => entries.includes(markerEntryName(marker));
+			const protectedBy = has("bundled") ? "bundled" : has("hub-installed") ? "hub-installed" : has("pinned") ? "pinned" : null;
 			summaries.push({
 				name,
 				description: parsed?.frontmatter.description ?? "",
 				path: dir,
 				protectedBy,
-				managed,
+				managed: has("hermes-managed"),
 				archived: false
 			});
 		}
 		return summaries;
 	}
-	async read(name) {
-		return this.io.readText(join(skillDir(this.root, name), "SKILL.md"));
+	async read(rawName) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return null;
+		return this.io.readText(join(this.dirOf(name), "SKILL.md"));
+	}
+	/**
+	
+	* Single path-building choke point (rc.42 audit P2-5): every directory path
+	
+	* is built from the TRIMMED name, so a name that passes `badName` (which
+	
+	* trims before validating) can never mint a second, whitespace-padded
+	
+	* directory next to the real one. Callers keep passing raw user input.
+	
+	*/
+	dirOf(name) {
+		return skillDir(this.root, name.trim());
+	}
+	/** Name-format guard shared by every path-building mutator/reader. */
+	badName(name) {
+		const normalized = name.trim();
+		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return `Invalid skill name "${normalized}". Use lowercase letters, digits, and hyphens (<= ${this.limits.maxNameLength}).`;
+		return null;
 	}
-	async writeProtection(name) {
-		const dir = skillDir(this.root, name);
+	async writeProtection(rawName, origin = "foreground") {
+		const name = rawName.trim();
+		const dir = this.dirOf(name);
 		for (const marker of ["bundled", "hub-installed"]) if (await this.io.exists(markerPath(dir, marker))) return marker;
+		if (origin === "background_review" && await this.io.exists(markerPath(dir, "pinned"))) return "pinned";
 		return null;
 	}
-	async deleteProtection(name) {
-		const dir = skillDir(this.root, name);
-		for (const marker of [
+	async deleteProtection(rawName, options = {}) {
+		const name = rawName.trim();
+		const dir = this.dirOf(name);
+		const markers = options.allowBundled ? ["hub-installed", "pinned"] : [
 			"bundled",
 			"hub-installed",
 			"pinned"
-		]) if (await this.io.exists(markerPath(dir, marker))) return marker;
+		];
+		for (const marker of markers) if (await this.io.exists(markerPath(dir, marker))) return marker;
 		return null;
 	}
-	async isManaged(name) {
-		const dir = skillDir(this.root, name);
+	async isManaged(rawName) {
+		const name = rawName.trim();
+		const dir = this.dirOf(name);
 		return await this.io.exists(markerPath(dir, "hermes-managed"));
 	}
-	async create(name, content, origin) {
+	/** Whether the skill carries the bundled marker (curator prune-builtins eligibility). */
+	async isBundled(rawName) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return false;
+		const dir = this.dirOf(name);
+		return await this.io.exists(markerPath(dir, "bundled"));
+	}
+	/** Whether the skill carries the pinned marker (the marker is the factual source; usage.pinned mirrors it). */
+	async isPinned(rawName) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return false;
+		const dir = this.dirOf(name);
+		return await this.io.exists(markerPath(dir, "pinned"));
+	}
+	/** Count non-empty support subdirectories (richness input for quality scoring). */
+	async countSupportDirs(rawName) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return 0;
+		const dir = this.dirOf(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);
+	}
+	/**
+	* Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
+	* deletion, from background-review writes, and from the lifecycle — a
+	* protective mutation, so the autonomous pipeline may never call it. The
+	* marker write is the only state change; content is untouched.
+	*/
+	async setPinned(name, pinned, origin = "foreground") {
+		const normalized = name.trim();
+		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return {
+			ok: false,
+			message: `Invalid skill name "${normalized}". Use lowercase letters, digits, and hyphens (<= ${this.limits.maxNameLength}).`
+		};
+		if (origin === "background_review") return {
+			ok: false,
+			message: "Only the foreground (user or the main agent) may pin or unpin skills."
+		};
+		const dir = this.dirOf(normalized);
+		const marker = markerPath(dir, "pinned");
+		const existing = await this.io.exists(marker);
+		if (pinned && existing) return {
+			ok: true,
+			message: `Skill "${normalized}" is already pinned.`,
+			path: dir
+		};
+		if (!pinned && !existing) return {
+			ok: true,
+			message: `Skill "${normalized}" is not pinned; nothing to do.`,
+			path: dir
+		};
+		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
+			ok: false,
+			message: `Skill "${normalized}" not found.`
+		};
+		if (pinned) await this.io.writeText(marker, "");
+		else await this.io.remove(marker);
+		await this.audit(normalized, pinned ? "pin" : "unpin", null, null, pinned ? "pinned" : "unpinned");
+		return {
+			ok: true,
+			message: pinned ? `Skill "${normalized}" pinned: protected from deletion, background review, and the lifecycle.` : `Skill "${normalized}" unpinned.`,
+			path: dir
+		};
+	}
+	async create(name, content, origin = "foreground") {
 		const normalized = name.trim();
 		if (!SKILL_NAME_RE.test(normalized) || normalized.length > this.limits.maxNameLength) return {
 			ok: false,
@@ -1143,26 +2546,39 @@ var SkillLibrary = class {
 			ok: false,
 			message: threat
 		};
-		const dir = skillDir(this.root, normalized);
+		const dir = this.dirOf(normalized);
 		if (await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
 			message: `Skill "${normalized}" already exists.`
 		};
 		await this.io.writeText(join(dir, "SKILL.md"), content.trimEnd() + "\n");
-		if (origin === "background_review") await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+		if (origin !== "foreground") await this.io.writeText(markerPath(dir, "hermes-managed"), "");
+		await this.audit(normalized, "create", null, content, "created");
+		this.notifyMutation({
+			action: "create",
+			name: normalized,
+			filePath: dir
+		});
 		return {
 			ok: true,
 			message: `Skill "${normalized}" created.`,
 			path: dir
 		};
 	}
-	async update(name, content) {
-		const dir = skillDir(this.root, name);
-		if (!await this.io.readText(join(dir, "SKILL.md"))) return {
+	async update(rawName, content, origin = "foreground") {
+		const name = rawName.trim();
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
+		const dir = this.dirOf(name);
+		const md = await this.io.readText(join(dir, "SKILL.md"));
+		if (!md) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const protection = await this.writeProtection(name);
+		const protection = await this.writeProtection(name, origin);
 		if (protection) return {
 			ok: false,
 			message: `Skill "${name}" is protected (${protection}).`
@@ -1178,20 +2594,32 @@ var SkillLibrary = class {
 			message: threat
 		};
 		await this.io.writeText(join(dir, "SKILL.md"), content.trimEnd() + "\n");
+		await this.audit(name, "update", md, content, "updated");
+		this.notifyMutation({
+			action: "update",
+			name,
+			filePath: dir
+		});
 		return {
 			ok: true,
 			message: `Skill "${name}" updated.`,
 			path: dir
 		};
 	}
-	async patch(name, oldString, newString, filePath = "", replaceAll = false) {
-		const dir = skillDir(this.root, name);
+	async patch(rawName, oldString, newString, filePath = "", replaceAll = false, origin = "foreground") {
+		const name = rawName.trim();
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
+		const dir = this.dirOf(name);
 		const skillMd = join(dir, "SKILL.md");
 		if (!await this.io.exists(skillMd)) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const protection = await this.writeProtection(name);
+		const protection = await this.writeProtection(name, origin);
 		if (protection) return {
 			ok: false,
 			message: `Skill "${name}" is protected (${protection}).`
@@ -1213,7 +2641,7 @@ var SkillLibrary = class {
 			message: `File not found: ${patchLabel}`
 		};
 		const patched = fuzzyPatch(md, oldString, newString, replaceAll);
-		if (!patched) return {
+		if (patched === null) return {
 			ok: false,
 			message: `Could not find old_string in "${name}/${patchLabel}". Use update for a full rewrite.`
 		};
@@ -1238,40 +2666,69 @@ var SkillLibrary = class {
 			message: threat
 		};
 		await this.io.writeText(target, patched.trimEnd() + "\n");
+		await this.audit(name, "patch", md, patched, `patched ${patchLabel}`);
+		this.notifyMutation({
+			action: "patch",
+			name,
+			filePath: dir
+		});
 		return {
 			ok: true,
 			message: `Skill "${name}" patched (${patchLabel}).`,
 			path: dir
 		};
 	}
-	async archive(name, absorbedInto = "") {
-		const dir = skillDir(this.root, name);
-		if (!await this.io.readText(join(dir, "SKILL.md"))) return {
+	async archive(rawName, options = {}) {
+		const name = rawName.trim();
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
+		const dir = this.dirOf(name);
+		const md = await this.io.readText(join(dir, "SKILL.md"));
+		if (!md) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const protection = await this.deleteProtection(name);
+		const protection = await this.deleteProtection(name, options.allowBundled === void 0 ? {} : { allowBundled: options.allowBundled });
 		if (protection) return {
 			ok: false,
 			message: `Skill "${name}" is protected (${protection}).`
 		};
-		if (absorbedInto) {
-			if (!await this.io.readText(join(skillDir(this.root, absorbedInto), "SKILL.md"))) return {
+		if (options.absorbedInto) {
+			if (!await this.io.readText(join(this.dirOf(options.absorbedInto), "SKILL.md"))) return {
 				ok: false,
-				message: `absorbed_into="${absorbedInto}" does not exist.`
+				message: `absorbed_into="${options.absorbedInto}" does not exist.`
 			};
 		}
 		const archiveRoot = join(this.root, ".archive");
-		let dest = join(archiveRoot, name);
-		if (await this.io.exists(dest)) dest = join(archiveRoot, `${name}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 14)}`);
+		let dest = join(archiveRoot, name.trim());
+		if (await this.io.exists(dest)) {
+			const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 14);
+			dest = join(archiveRoot, `${name.trim()}-${stamp}`);
+			while (await this.io.exists(dest)) dest = join(archiveRoot, `${name.trim()}-${stamp}-${Math.random().toString(36).slice(2, 8)}`);
+		}
+		if (this.io.isSymlink) {
+			if (await this.io.isSymlink(dir) === true) return {
+				ok: false,
+				message: `Skill "${name}" is a symlink; refusing to archive it.`
+			};
+		}
 		try {
 			await this.io.rename(dir, dest);
 		} catch {
 			await this.io.copy(dir, dest);
 			await this.io.remove(dir);
 		}
-		const reason = absorbedInto ? `Consolidated into ${absorbedInto}` : "Archived by self-evolution curator";
+		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);
+		this.notifyMutation({
+			action: "archive",
+			name,
+			archivedPath: dest
+		});
 		return {
 			ok: true,
 			message: `Skill "${name}" archived to .archive.`,
@@ -1283,26 +2740,27 @@ var SkillLibrary = class {
 	* an absorbed-into marker. Hermes-style consolidation: overlapping skills
 	* collapse into one, and the originals stay recoverable under `.archive/`.
 	*/
-	async consolidate(target, sources) {
-		const normalizedSources = [...new Set(sources)].filter((name) => name !== target);
+	async consolidate(target, sources, origin = "foreground") {
+		const targetName = target.trim();
+		const normalizedSources = [...new Set(sources.map((name) => name.trim()))].filter((name) => name !== targetName);
 		if (normalizedSources.length === 0) return {
 			ok: false,
 			message: "Consolidation requires at least one distinct source skill."
 		};
-		for (const name of [target, ...normalizedSources]) if (!SKILL_NAME_RE.test(name)) return {
+		for (const name of [targetName, ...normalizedSources]) if (!SKILL_NAME_RE.test(name)) return {
 			ok: false,
 			message: `Invalid skill name "${name}". Use lowercase letters, digits, and hyphens.`
 		};
-		const targetDir = skillDir(this.root, target);
+		const targetDir = this.dirOf(targetName);
 		const targetMd = await this.io.readText(join(targetDir, "SKILL.md"));
 		if (!targetMd) return {
 			ok: false,
-			message: `Skill "${target}" not found.`
+			message: `Skill "${targetName}" not found.`
 		};
-		const targetProtection = await this.writeProtection(target);
+		const targetProtection = await this.writeProtection(targetName, origin);
 		if (targetProtection) return {
 			ok: false,
-			message: `Skill "${target}" is protected (${targetProtection}).`
+			message: `Skill "${targetName}" is protected (${targetProtection}).`
 		};
 		const parts = [];
 		for (const source of normalizedSources) {
@@ -1311,7 +2769,7 @@ var SkillLibrary = class {
 				ok: false,
 				message: `Skill "${source}" is protected (${protection}).`
 			};
-			const sourceMd = await this.io.readText(join(skillDir(this.root, source), "SKILL.md"));
+			const sourceMd = await this.io.readText(join(this.dirOf(source), "SKILL.md"));
 			if (!sourceMd) return {
 				ok: false,
 				message: `Skill "${source}" not found.`
@@ -1324,7 +2782,7 @@ var SkillLibrary = class {
 			parts.push(`\n<!-- consolidated from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}`);
 		}
 		const merged = targetMd.trimEnd() + parts.join("\n") + "\n";
-		const validation = validateFrontmatter(merged, target, this.limits);
+		const validation = validateFrontmatter(merged, targetName, this.limits);
 		if (validation) return {
 			ok: false,
 			message: `Consolidation rejected: ${validation}`
@@ -1334,14 +2792,30 @@ var SkillLibrary = class {
 			ok: false,
 			message: threat
 		};
-		await this.io.writeText(join(targetDir, "SKILL.md"), merged);
-		for (const source of normalizedSources) {
-			const archived = await this.archive(source, target);
-			if (!archived.ok) return archived;
+		const archived = [];
+		try {
+			for (const source of normalizedSources) {
+				const result = await this.archive(source, { absorbedInto: targetName });
+				if (!result.ok) throw new Error(result.message);
+				archived.push(source);
+			}
+			await this.io.writeText(join(targetDir, "SKILL.md"), merged);
+		} catch (error) {
+			await this.io.writeText(join(targetDir, "SKILL.md"), targetMd).catch(() => {});
+			for (const source of archived.reverse()) await this.restoreFromArchive(source).catch(() => {});
+			return {
+				ok: false,
+				message: `Consolidation failed and was rolled back: ${error instanceof Error ? error.message : String(error)}`
+			};
 		}
+		this.notifyMutation({
+			action: "consolidate",
+			name: targetName,
+			filePath: targetDir
+		});
 		return {
 			ok: true,
-			message: `Consolidated ${normalizedSources.join(", ")} into "${target}".`,
+			message: `Consolidated ${normalizedSources.join(", ")} into "${targetName}".`,
 			path: targetDir
 		};
 	}
@@ -1350,12 +2824,13 @@ var SkillLibrary = class {
 	* recoverability: archival never deletes, and this is the control-plane
 	* path back. The `.archive-reason` marker is dropped on restore.
 	*/
-	async restoreFromArchive(name) {
+	async restoreFromArchive(rawName) {
+		const name = rawName.trim();
 		if (!SKILL_NAME_RE.test(name)) return {
 			ok: false,
 			message: `Invalid skill name "${name}". Use lowercase letters, digits, and hyphens.`
 		};
-		if (await this.io.exists(join(skillDir(this.root, name), "SKILL.md"))) return {
+		if (await this.io.exists(join(this.dirOf(name), "SKILL.md"))) return {
 			ok: false,
 			message: `Skill "${name}" already exists in the active root; refusing to overwrite.`
 		};
@@ -1375,7 +2850,13 @@ var SkillLibrary = class {
 			message: `Skill "${name}" is not in .archive.`
 		};
 		const source = join(archiveRoot, chosen);
-		const dest = skillDir(this.root, name);
+		const dest = this.dirOf(name);
+		if (this.io.isSymlink) {
+			if (await this.io.isSymlink(source) === true) return {
+				ok: false,
+				message: `Archived entry "${chosen}" is a symlink; refusing to restore it.`
+			};
+		}
 		try {
 			await this.io.rename(source, dest);
 		} catch {
@@ -1383,19 +2864,30 @@ var SkillLibrary = class {
 			await this.io.remove(source);
 		}
 		if (await this.io.exists(join(dest, ".archive-reason"))) await this.io.remove(join(dest, ".archive-reason"));
+		this.notifyMutation({
+			action: "restore",
+			name,
+			filePath: dest
+		});
 		return {
 			ok: true,
 			message: `Skill "${name}" restored from .archive.`,
 			path: dest
 		};
 	}
-	async writeSupportFile(name, filePath, content) {
-		const dir = skillDir(this.root, name);
+	async writeSupportFile(rawName, filePath, content, origin = "foreground") {
+		const name = rawName.trim();
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
+		const dir = this.dirOf(name);
 		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const protection = await this.writeProtection(name);
+		const protection = await this.writeProtection(name, origin);
 		if (protection) return {
 			ok: false,
 			message: `Skill "${name}" is protected (${protection}).`
@@ -1415,20 +2907,33 @@ 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}`);
+		this.notifyMutation({
+			action: "write_file",
+			name,
+			filePath: target
+		});
 		return {
 			ok: true,
 			message: `Support file "${filePath}" written to "${name}".`,
 			path: target
 		};
 	}
-	async removeSupportFile(name, filePath) {
-		const dir = skillDir(this.root, name);
+	async removeSupportFile(rawName, filePath, origin = "foreground") {
+		const name = rawName.trim();
+		const badName = this.badName(name);
+		if (badName) return {
+			ok: false,
+			message: badName
+		};
+		const dir = this.dirOf(name);
 		if (!await this.io.exists(join(dir, "SKILL.md"))) return {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const protection = await this.writeProtection(name);
+		const protection = await this.writeProtection(name, origin);
 		if (protection) return {
 			ok: false,
 			message: `Skill "${name}" is protected (${protection}).`
@@ -1443,24 +2948,88 @@ 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}`);
+		this.notifyMutation({
+			action: "remove_file",
+			name,
+			filePath: target
+		});
 		return {
 			ok: true,
 			message: `Support file "${filePath}" removed from "${name}".`,
 			path: target
 		};
 	}
-	async snapshotAll(reason = "pre-mutation") {
-		const dest = join(join(this.root, ".backups"), `skills-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
+	/**
+	* 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 backupRoot = join(this.root, ".backups");
+		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+		let dest = join(backupRoot, `skills-${stamp}`);
+		while (await this.io.exists(dest)) dest = join(backupRoot, `skills-${stamp}-${Math.random().toString(36).slice(2, 8)}`);
 		const names = await listNames(this.root, this.io);
-		for (const name of names) await this.io.copy(skillDir(this.root, name), join(dest, name));
+		await Promise.all(names.map(async (name) => {
+			await this.io.copy(this.dirOf(name), join(dest, name));
+		}));
+		const sidecars = [];
+		for (const sidecar of [usageFile(this.root), suppressedFile(this.root)]) if (await this.io.exists(sidecar)) {
+			const name = basename(sidecar);
+			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 validExtras = extras.filter((extra) => SNAPSHOT_EXTRA_NAME_RE.test(extra.name));
+		const extraNames = validExtras.map((extra) => extra.name);
+		await Promise.all(validExtras.map(async (extra) => {
+			await this.io.writeText(join(dest, "extras", extra.name), extra.content);
+		}));
 		await this.io.writeText(join(dest, "manifest.json"), JSON.stringify({
 			reason,
 			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-			skills: names
+			skills: names,
+			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); older ones are removed outright. */
+	async retainSnapshots(keep) {
+		const snapshots = await this.listSnapshots();
+		for (const snapshot of snapshots.slice(keep)) try {
+			await this.io.remove(snapshot.path);
+		} catch {}
+	}
 	async listSnapshots() {
 		const backupRoot = join(this.root, ".backups");
 		let entries;
@@ -1472,96 +3041,93 @@ 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");
-		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;
+		await this.snapshotAll("pre-rollback", extras);
+		let rootEntries;
+		try {
+			rootEntries = await this.io.list(this.root);
+		} catch {
+			rootEntries = [];
+		}
+		for (const entry of rootEntries) {
+			if (entry.startsWith(".")) continue;
+			await this.io.remove(join(this.root, entry));
+		}
+		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);
+		this.notifyMutation({
+			action: "restore",
+			name: "snapshot"
+		});
 		return {
 			ok: true,
 			message: `Restored skill tree from ${latest.path}`,
-			path: latest.path
+			path: latest.path,
+			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
 		};
 	}
 };
 //#endregion
 //#region lib/types/state-store.js
 /**
-* Small crash-safe JSON state store for plugin-owned sidecar state.
-* Writes are atomic (temp + rename). Reads are synchronous for startup use.
+* Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
+* state (reports, activity store, feedback file, state-domain data).
 */
 function evolutionHome(env = process.env) {
 	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "evolution");
 }
-var JsonState = class {
-	initial;
-	path;
-	value;
-	constructor(name, initial, env = process.env) {
-		this.initial = initial;
-		this.path = join(evolutionHome(env), name);
-		this.value = this.loadSync();
-	}
-	loadSync() {
-		try {
-			const raw = readFileSync(this.path, "utf8");
-			const parsed = JSON.parse(raw);
-			return {
-				...this.initial,
-				...parsed
-			};
-		} catch {
-			return { ...this.initial };
-		}
-	}
-	get() {
-		return this.value;
-	}
-	set(value) {
-		this.value = value;
-	}
-	update(mutator) {
-		mutator(this.value);
-	}
-	async flush() {
-		await mkdir(dirname(this.path), { recursive: true });
-		const tmp = `${this.path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
-		await writeFile(tmp, JSON.stringify(this.value, null, 2), "utf8");
-		await rename(tmp, this.path);
-	}
-	/** Merge-on-load helper for persisted maps/records. */
-	async reload() {
-		try {
-			const raw = await readFile(this.path, "utf8");
-			this.value = {
-				...this.initial,
-				...JSON.parse(raw)
-			};
-		} catch {
-			this.value = { ...this.initial };
-		}
-	}
-};
 //#endregion
-export { COMBINED_REVIEW_PROMPT, CURATOR_PROMPT, DEFAULT_SKILL_LIMITS, 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, childPath, computeLifecycleTransitions, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadUsage, markAgentCreated, memoryRoot, nodeEvolutionIo, observeEvent, parseFrontmatter, reviewPrompt, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, usageFile, validateFrontmatter, verifyPromptBundle };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, 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, EVENT_LOG_VERSION, EvolutionGateSet, 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, SKILLS_GUIDANCE, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, appendEvolutionEvent, applyCuratorFields, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, foldCuratorFields, foldTurn, getRecord, latestActivityAt, lifecycleCandidate, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutateUsage, mutationsFile, nodeEvolutionIo, normalizeUsageRecord, observeEvent, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, recordMutation, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, validateFrontmatter, verifyPromptBundle };