@lmzhen/dsh-evolution-core 0.3.15 → 0.3.17

package/lib/index.js

@@ -64,45 +64,81 @@ function nodeEvolutionIo() {
 	};
 	/**
 	* 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
+	* guards the atomic write. A >1s-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
+	* slow writer no longer loses its lock to a peer at the threshold (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.
+	* 0.3.17 (E-8): acquisition and the task are now SEPARATE try blocks — a
+	* task error (win32 rename/EBUSY surfaces as EPERM) used to be mistaken for
+	* lock contention, retried up to 40x and finally reported as
+	* "could not acquire write lock" while the real cause was hidden.
+	* 0.3.17 (E-8a): the takeover threshold (1000ms) now fits INSIDE the ~2s
+	* retry budget (budget >= 2 x threshold), so a dead holder's lock is
+	* actually recoverable within one budget instead of being arithmetically
+	* unreachable.
 	*/
 	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" });
+		for (let attempt = 0; attempt < 40; attempt += 1) {
 			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;
+				await writeFile(lock, String(process.pid), { flag: "wx" });
+			} catch (error) {
+				const code = error?.code;
+				if (code !== "EEXIST" && code !== "EPERM") throw error;
+				try {
+					const st = await stat(lock);
+					if (Date.now() - st.mtimeMs > 1e3) {
+						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;
 				}
-			} catch {
+				await new Promise((resolve) => setTimeout(resolve, 50));
 				continue;
 			}
-			await new Promise((resolve) => setTimeout(resolve, 50));
+			try {
+				return await task();
+			} finally {
+				await rm(lock, { force: true }).catch(() => {});
+			}
 		}
 		throw new Error(`could not acquire write lock for ${path} after 40 attempts`);
 	};
+	/** 0.3.17 (E-8b): sweep tmp files a crashed writer left behind — same
+	* `<target>.<pid>.<rand>.tmp` shape, older than 1h AND held by a dead pid.
+	* Lazy: only the directory a write is about to touch gets swept, once per
+	* write, inside the write lock. */
+	const sweepStaleTmps = async (path) => {
+		const dir = dirname(path);
+		const base = basename(path);
+		let entries;
+		try {
+			entries = await readdir(dir);
+		} catch {
+			return;
+		}
+		const prefix = `${base}.`;
+		for (const name of entries) {
+			if (!name.startsWith(prefix) || !name.endsWith(".tmp")) continue;
+			const tmpPath = join(dir, name);
+			const holder = Number(name.slice(prefix.length, name.length - 4).split(".")[0] ?? "");
+			try {
+				const st = await stat(tmpPath);
+				const deadHolder = !Number.isInteger(holder) || holder <= 0 || !isAlive(holder);
+				if (Date.now() - st.mtimeMs > 36e5 && deadHolder) await rm(tmpPath, { force: true });
+			} catch {}
+		}
+	};
 	return {
 		async readText(path) {
 			try {
@@ -115,6 +151,7 @@ function nodeEvolutionIo() {
 		async writeText(path, content) {
 			await mkdir(dirname(path), { recursive: true });
 			await withWriteLock(path, async () => {
+				await sweepStaleTmps(path);
 				const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
 				await writeFile(tmp, content, "utf8");
 				await rename(tmp, path);
@@ -123,6 +160,7 @@ function nodeEvolutionIo() {
 		async transact(path, task) {
 			await mkdir(dirname(path), { recursive: true });
 			await withWriteLock(path, async () => {
+				await sweepStaleTmps(path);
 				let current;
 				try {
 					current = await readFile(path, "utf8");
@@ -370,9 +408,9 @@ function latestActivityAt(record) {
 		record.last_used_at,
 		record.last_viewed_at,
 		record.last_patched_at
-	].filter((value) => typeof value === "string");
+	].filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)));
 	if (values.length === 0) return null;
-	return values.sort().reverse()[0] ?? null;
+	return values.reduce((latest, value) => Date.parse(value) > Date.parse(latest) ? value : latest);
 }
 /**
 * Whether the library has ANY observed read evidence (C observation window):
@@ -494,6 +532,25 @@ 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;
+/** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
+* never carry — single source for plan-validator, evolution-policy and the
+* threat scanner (they used to each hardcode the list). */
+const FORBIDDEN_CONTROL_KEYS = [
+	"policy",
+	"threshold",
+	"prompt_hash",
+	"model_route",
+	"evolution_config"
+];
+/** 0.3.17 (S3.10): the model-facing write tools the policy guard and threat
+* scanner cover. */
+const EVOLUTION_WRITE_TOOLS = ["memory", "skill_manage"];
+/** 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.
+* 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
+* can reference it without importing the skill-store module. */
+const AUTHORING_DESCRIPTION_BAR = 60;
 //#endregion
 //#region lib/types/gates.js
 /**
@@ -999,8 +1056,8 @@ async function readEvolutionTimeline(io, path) {
 * 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@13";
 const PROMPT_BUNDLE_VERSION = 13;
+const PROMPT_BUNDLE_ID = `dsh-evolution@13`;
 const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
 Review the conversation above and consider saving to memory if appropriate.
 
@@ -1264,8 +1321,8 @@ 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 === "memory") return MEMORY_REVIEW_PROMPT;
 	if (kind === "skill") return SKILL_REVIEW_PROMPT;
 	return COMBINED_REVIEW_PROMPT;
 }
@@ -1297,7 +1354,7 @@ const PROMPT_BUNDLE = createPromptBundle({
 	skillsGuidance: SKILLS_GUIDANCE
 });
 function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
-	if (bundle.id !== "dsh-evolution@13" || bundle.version !== 13) return false;
+	if (bundle.id !== PROMPT_BUNDLE_ID || bundle.version !== 13) return false;
 	const canonical = JSON.stringify({
 		id: PROMPT_BUNDLE_ID,
 		version: 13,
@@ -1510,7 +1567,7 @@ const PATTERNS = [
 		label: "hermes_env",
 		category: "persistence",
 		scope: "strict",
-		regex: /\$?HOME\/\.hermes|~\/\.hermes|\.hermes\/\.env/i
+		regex: /\$?HOME\/\.hermes|~\/\.hermes|\.hermes\/\.env|%USERPROFILE%[\\/]\.hermes/i
 	},
 	{
 		label: "c2_node_registration",
@@ -1557,9 +1614,16 @@ const SCOPE_ORDER = {
 	strict: 3
 };
 const NO_SCAN_OPTIONS = {};
+/** Window overlap for the full-coverage scan: far larger than the longest
+* pattern span (~530 chars: `curl [^\n]{0,512} ...`), so a match straddling a
+* window boundary is fully inside at least one window (E-12, 0.3.16). */
+const PATTERN_OVERLAP = 4096;
 /**
 * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
 * `options.excludeLabels` removes matching patterns without changing `scope`.
+* `maxScanChars` is the WINDOW SIZE, not a total cap (E-12, 0.3.16): the whole
+* text is always scanned in overlapping windows, so content beyond 65,536
+* characters (skill files may run to 100,000) is no longer a blind zone.
 */
 function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_SCAN_OPTIONS) {
 	const findings = [];
@@ -1573,12 +1637,23 @@ function scanThreats(text, scope = "strict", maxScanChars = 65536, options = NO_
 		category: "unicode_obfuscation",
 		scope
 	});
-	const normalized = text.normalize("NFKC").slice(0, maxScanChars);
+	const normalized = text.normalize("NFKC");
+	const windows = [];
+	if (normalized.length <= maxScanChars) windows.push(normalized);
+	else {
+		const step = Math.max(1, maxScanChars - PATTERN_OVERLAP);
+		for (let start = 0; start < normalized.length; start += step) windows.push(normalized.slice(start, start + maxScanChars));
+	}
 	const excluded = new Set(options.excludeLabels ?? []);
-	for (const pattern of PATTERNS) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const window of windows) 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({
+		if (!pattern.regex.test(window)) continue;
+		const key = `${pattern.label}|${pattern.scope}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		findings.push({
 			label: pattern.label,
 			category: pattern.category,
 			scope: pattern.scope
@@ -1648,7 +1723,7 @@ function previewEntries(entries) {
 	return `\n\nCurrent entries (preview):\n${shown.join("\n")}${more}`;
 }
 function memoryRoot(env = process.env) {
-	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "memories");
+	return join(env.DSH_HOME || join(homedir(), ".dsh"), "memories");
 }
 function fileFor(root, target) {
 	return join(root, target === "memory" ? "MEMORY.md" : "USER.md");
@@ -1703,9 +1778,6 @@ var MemoryStore = class {
 		const raw = await this.io.readText(fileFor(this.root, target));
 		return raw === null ? [] : [...new Set(normalizeEntries(raw))];
 	}
-	async write(target, entries) {
-		await this.io.writeText(fileFor(this.root, target), render(entries));
-	}
 	resetFailures() {
 		this.failureCount = 0;
 	}
@@ -2101,7 +2173,7 @@ async function loadMutations(root, io = nodeEvolutionIo()) {
 }
 /** 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) => {
+	await transactIo(io, mutationsFile(root), (current) => {
 		if (current !== null) try {
 			JSON.parse(current);
 		} catch {
@@ -2110,10 +2182,10 @@ async function recordMutation(root, io, record, cap = 500) {
 		const existing = parseMutationRecords(current);
 		existing.push(record);
 		const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
-		return Promise.resolve(JSON.stringify({
+		return JSON.stringify({
 			version: 1,
 			records: trimmed
-		}, null, 2));
+		}, null, 2);
 	});
 }
 //#endregion
@@ -2248,7 +2320,7 @@ function computeDedupGroups(input) {
 		const [ra, rb] = [find(a), find(b)];
 		if (ra !== rb) parent.set(rb, ra);
 	};
-	for (const [hash, bucketNames] of hashes) {
+	for (const [, bucketNames] of hashes) {
 		const first = bucketNames[0];
 		if (first === void 0 || bucketNames.length === 1) continue;
 		for (let index = 1; index < bucketNames.length; index += 1) {
@@ -2326,9 +2398,9 @@ const SECRET_PATTERNS = [
 	["gitlab token", /glpat-[A-Za-z0-9_-]{16,}/g],
 	["slack token", /xox[baprs]-[A-Za-z0-9-]{10,}/g],
 	["jwt", /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g],
-	["bearer credential", /Bearer [A-Za-z0-9._~+/=\-]{16,}/g],
-	["inline assignment", /(\b(?:token|api[_-]?key|secret|password|passwd)\b[\s]*[:=][\s]*["']?)([A-Z0-9._~+/=\-]{12,})/gi]
+	["bearer credential", /Bearer [A-Za-z0-9._~+/=\-]{16,}/g]
 ];
+const INLINE_ASSIGNMENT_PATTERN = /(\b(?:token|api[_-]?key|secret|password|passwd)\b[\s]*[:=][\s]*["']?)([A-Z0-9._~+/=\-]{12,})/gi;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -2336,10 +2408,29 @@ const SECRET_PATTERNS = [
 */
 function redactSecrets(text) {
 	let out = text;
-	for (const [, pattern] of SECRET_PATTERNS) out = out.replace(pattern, (_match, p1) => p1 === void 0 ? "<redacted>" : `${p1}<redacted>`);
+	for (const [, pattern] of SECRET_PATTERNS) out = out.replace(pattern, "<redacted>");
+	out = out.replace(INLINE_ASSIGNMENT_PATTERN, (_match, p1) => `${p1 ?? ""}<redacted>`);
 	return out;
 }
 //#endregion
+//#region lib/types/serial.js
+/**
+* A process-local serial task queue: each task starts only after the previous
+* one settles (success or failure), so read-modify-write sequences that share
+* one file never interleave inside this process. The durable cross-process
+* serialization layer is the IO backend's transact lock; this chain is the
+* second layer (0.3.17 S2.8, T-1: the shape was duplicated in state-json and
+* memory-files — one factory now).
+*/
+function makeSerialQueue() {
+	let chain = Promise.resolve();
+	return (task) => {
+		const run = chain.then(task, task);
+		chain = run.then(() => void 0, () => void 0);
+		return run;
+	};
+}
+//#endregion
 //#region lib/types/skill-health.js
 /**
 * Skill structure-health domain (rc.73 A1, 008 design): a SECOND assessment
@@ -2414,6 +2505,7 @@ const FIX_PATTERNS = [/worked after|fixed by|the fix was|root cause/i, /retry(?:
 /** Fold one session event into the current turn observation. */
 function observeEvent(signal, event) {
 	if (event.type === "user/message") {
+		if (!Array.isArray(event.data.content)) return;
 		const text = event.data.content.map((block) => block.type === "text" ? block.text : "").join(" ");
 		signal.userChars += text.length;
 		if (CORRECTION_PATTERNS.some((pattern) => pattern.test(text))) signal.memorySignal = true;
@@ -2473,6 +2565,165 @@ function foldTurn(session, fromSeq) {
 	return signal;
 }
 //#endregion
+//#region lib/types/drift-signals.js
+/**
+* Library-level drift signals for the maintenance subagent (design 011).
+*
+* Deterministic fact checks over a skill-library snapshot: domain drift
+* (narrow names, near-duplicate groups, prefix clusters) and layer drift
+* (log-like bodies, duplicate headings, overlong lines, missing support-file
+* pointers, description over the authoring bar). Pure functions only — no IO,
+* no LLM, no services. Thresholds are imported from their owning modules
+* (skill-health / quality / skill-store), never duplicated.
+*
+* Distinct from `signals.ts` — the session-level review signal gate.
+*/
+/** Physical line length at/above which a body line is reported overlong (011 §4). */
+const DRIFT_MAX_LINE_CHARS = 1500;
+/** Signal-set version: bump whenever ids/thresholds change (011 §7 version coupling). */
+const DRIFT_SIGNALS_VERSION = "1";
+/** Render-time nouns for the MAINTAIN_PROMPT placeholders (single vocabulary with the facts block). */
+const DRIFT_SIGNAL_NOUNS = {
+	dedup_group: "近重复组",
+	prefix_cluster: "前缀聚类",
+	stamp_density: "stamp 密度",
+	body_size: "正文体量",
+	dup_heading: "重复标题",
+	overlong_line: "超长行",
+	pointer_missing: "缺失指针",
+	description_chars: "描述长度",
+	narrow_name: "窄名",
+	usage_observed: "使用观察",
+	quality_low: "质量分"
+};
+const NARROW_NAME_PATTERNS = [
+	{
+		label: "error-string",
+		re: /^(?:err|error|exception|traceback|warn|fail)(?:[-_][a-z0-9]+)+$/i
+	},
+	{
+		label: "pr-number",
+		re: /^(?:pr|issue)[-_]?\d{2,}$/i
+	},
+	{
+		label: "dated",
+		re: /\d{4}-\d{2}-\d{2}/
+	},
+	{
+		label: "session-verb",
+		re: /^(?:fix|debug|audit|salvage|diagnose|investigate)[-_][a-z0-9-]+$/i
+	}
+];
+/** Detect support files the body never references (by basename or relative path). */
+function missingSupportPointers(body, supportFiles) {
+	return supportFiles.filter((path) => {
+		const base = path.split("/").pop() ?? path;
+		return base.length > 0 && !body.includes(base) && !body.includes(path);
+	});
+}
+/** Duplicate `## heading` occurrences: singleton results default to head of the file. */
+function duplicateHeadings(body) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const line of body.split("\n")) {
+		const m = /^##\s+(.+)$/.exec(line);
+		if (m?.[1]) {
+			const heading = m[1].trim();
+			if (heading) counts.set(heading, (counts.get(heading) ?? 0) + 1);
+		}
+	}
+	return [...counts.entries()].filter(([, count]) => count > 1).map(([heading, count]) => ({
+		heading,
+		count
+	}));
+}
+/** Physical lines over `max` characters: `{ lineNo, chars }`, 1-based line numbers. */
+function overlongLines(body, max = DRIFT_MAX_LINE_CHARS) {
+	const out = [];
+	const lines = body.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const length = (lines[index] ?? "").length;
+		if (length > max) out.push({
+			lineNo: index + 1,
+			chars: length
+		});
+	}
+	return out;
+}
+/** Narrow-name shapes detected in a skill name (empty = none). */
+function narrowNameMatches(name) {
+	return NARROW_NAME_PATTERNS.filter(({ re }) => re.test(name)).map(({ label }) => label);
+}
+function supportGroupCount(supportFiles) {
+	const groups = /* @__PURE__ */ new Set();
+	for (const path of supportFiles ?? []) {
+		const head = path.split("/")[0];
+		if (head) groups.add(head);
+	}
+	return groups.size;
+}
+function sig(id, verdict, value, threshold, detail) {
+	return {
+		id,
+		verdict,
+		value,
+		threshold,
+		detail
+	};
+}
+/**
+* Compute all drift signals for a snapshot. Missing inputs (quality score,
+* usage window) yield `unknown` — never a fabricated verdict.
+*/
+function computeDriftSignals(snapshots) {
+	const library = [];
+	const names = snapshots.map((s) => s.name);
+	const dedup = computeDedupGroups({ contents: new Map(snapshots.map((s) => [s.name, s.body])) });
+	library.push(dedup.length === 0 ? sig("dedup_group", "pass", "none", "size >= 2") : sig("dedup_group", "over", dedup.map((group) => group.join(", ")).join(" | "), "size >= 2", `members=${dedup.map((group) => group.join("|")).join(";")}`));
+	const clusters = computePrefixClusters(names);
+	library.push(clusters.length === 0 ? sig("prefix_cluster", "pass", "none", "size >= 2") : sig("prefix_cluster", "over", clusters.map((cluster) => cluster.members.join(", ")).join(" | "), "size >= 2", `key=${clusters.map((cluster) => cluster.key).join("|")}`));
+	const allProvided = snapshots.length > 0 && snapshots.every((s) => s.usageObserved !== null && s.usageObserved !== void 0);
+	library.push(!allProvided ? sig("usage_observed", "unknown", "not-observed", void 0, "usage window status missing") : snapshots.every((s) => s.usageObserved === true) ? sig("usage_observed", "pass", "observed") : sig("usage_observed", "pass", "unobserved"));
+	return {
+		library,
+		skills: snapshots.map((snapshot) => {
+			const signals = [];
+			const body = snapshot.body;
+			const supportFiles = snapshot.supportFiles ?? [];
+			const supportEnumerated = snapshot.supportFiles !== void 0;
+			const density = assessStructureHealth({
+				skillName: snapshot.name,
+				bodyChars: body.length,
+				bodyText: body,
+				supportGroups: supportGroupCount(supportFiles)
+			}, DEFAULT_HEALTH_THRESHOLDS).dims.stampDensityPerKb;
+			signals.push(density === null ? sig("stamp_density", "pass", body.length < 2e3 ? "below-min-body" : "not-assessed") : sig("stamp_density", density >= DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb ? "over" : "pass", `${density.toFixed(2)}/KB`, `${DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb}/KB`));
+			signals.push(sig("body_size", body.length >= DEFAULT_HEALTH_THRESHOLDS.softBodyChars ? "over" : "pass", `${body.length}`, `${DEFAULT_HEALTH_THRESHOLDS.softBodyChars}`));
+			const dupes = duplicateHeadings(body);
+			signals.push(dupes.length === 0 ? sig("dup_heading", "pass", "none") : sig("dup_heading", "over", dupes.map((d) => `${d.heading}(${d.count})`).join(", "), "count >= 2"));
+			const long = overlongLines(body);
+			signals.push(long.length === 0 ? sig("overlong_line", "pass", "none") : sig("overlong_line", "over", long.map((l) => `${l.lineNo}:${l.chars}`).join(", "), `${DRIFT_MAX_LINE_CHARS}`));
+			const missing = supportEnumerated ? missingSupportPointers(body, supportFiles) : void 0;
+			signals.push(!supportEnumerated ? sig("pointer_missing", "unknown", "not-enumerated", void 0, "support files not enumerated") : (missing ?? []).length === 0 ? sig("pointer_missing", "pass", "none") : sig("pointer_missing", "over", missing?.join(", ") ?? ""));
+			const narrow = narrowNameMatches(snapshot.name);
+			signals.push(narrow.length === 0 ? sig("narrow_name", "pass", "none") : sig("narrow_name", "over", narrow.join(", "), void 0, `name=${snapshot.name}`));
+			const description = snapshot.description;
+			signals.push(description === void 0 ? sig("description_chars", "unknown", "missing", "60") : sig("description_chars", description.length > 60 ? "over" : "pass", `${description.length}`, `60`));
+			const quality = snapshot.quality;
+			signals.push(quality === null || quality === void 0 ? sig("quality_low", "unknown", "not-assessed") : sig("quality_low", quality < .3 ? "over" : "pass", quality.toFixed(2), `${LOW_QUALITY_THRESHOLD}`));
+			return {
+				name: snapshot.name,
+				signals,
+				...snapshot.protected !== void 0 && snapshot.protected !== null ? { protected: snapshot.protected } : {},
+				...snapshot.catalogInvalid !== void 0 ? { catalogInvalid: snapshot.catalogInvalid } : {}
+			};
+		})
+	};
+}
+/** Convenience: fetch one signal from an assessment or library list. */
+function findDriftSignal(signals, id) {
+	return signals.find((signal) => signal.id === id);
+}
+//#endregion
 //#region lib/types/skill-store.js
 /**
 * Skill library management for the self-evolution plugin.
@@ -2482,6 +2733,10 @@ 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.
 */
+/** 0.3.16 (S1.13, T-6): the pointer-line prefix written into a body when a
+* section is moved to references/ — single literal, both restructure and
+* append-mode consolidation emit the same discoverability line. */
+const POINTER_LINE_PREFIX = "> 详见 references/";
 const DEFAULT_SKILL_LIMITS = {
 	maxNameLength: 64,
 	maxDescriptionLength: MAX_DESCRIPTION_LENGTH,
@@ -2495,7 +2750,7 @@ const RESTRUCTURE_TARGET_RE = /^references\/[a-z0-9][a-z0-9._-]*\.md$/;
 /** 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");
+	return join(env.DSH_HOME || join(homedir(), ".dsh"), "skills");
 }
 /**
 * Map a requesting session onto the two origin surfaces (rc.44 plan M2-2.3):
@@ -2583,21 +2838,26 @@ function parseFrontmatter(content) {
 }
 /** YAML plain-scalar hazards that make an UNQUOTED frontmatter value
 * unloadable to the platform catalog (strict YAML parser): `: ` (mapping
-* separator), ` #` (comment start), or a leading YAML indicator. The
-* evolution `parseFrontmatter` is deliberately lenient, so violations
-* silently split family-visibility from platform-visibility (0.3.11
-* inkos-harness case: the description carried "…: " and the catalog dropped
-* the whole skill). Already-quoted values and well-formed flow collections
-* (`[a, b]` / `{a: b}`) are considered safe. This rule is only the FAST
-* PATH — the write path re-verifies every rewrite with the real YAML parser
-* (see normalizeFrontmatter), so an incomplete approximation can never
-* corrupt a multiline flow value (P3-4). */
+* separator), ` #` (comment start), a trailing `:` (a mapping marker),
+* or a leading YAML indicator. The evolution `parseFrontmatter` is
+* deliberately lenient, so violations silently split family-visibility from
+* platform-visibility (0.3.11 inkos-harness case: the description carried
+* "…: " and the catalog dropped the whole skill). Already-quoted values and
+* well-formed flow collections (`[a, b]` / `{a: b}`) are considered safe.
+* 0.3.16 (E-47): null/bool/number-shaped plain scalars are flagged too — they
+* parse as booleans/numbers on the platform while the family keeps the string
+* (a `description: true` split-brain).
+* This rule is only the FAST PATH — the write path re-verifies every rewrite
+* with the real YAML parser (see normalizeFrontmatter), so an incomplete
+* approximation can never corrupt a multiline flow value (P3-4). */
 function yamlPlainScalarNeedsQuotes(value) {
 	if (value.length === 0) return false;
 	if (value.length >= 2 && (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'"))) return false;
 	if (/^\[.*\]$/.test(value) || /^\{.*\}$/.test(value)) return false;
 	if (value.includes(": ")) return true;
 	if (value.includes(" #")) return true;
+	if (value.endsWith(":")) return true;
+	if (/^(?:null|true|false|~|[-+]?\d+(?:\.\d+)?)$/i.test(value)) return true;
 	if (/^[-?:,[\]{}#&*!|>'\"%@`\s]/.test(value)) return true;
 	return false;
 }
@@ -2723,10 +2983,6 @@ function validateFrontmatter(content, expectedName, limits = DEFAULT_SKILL_LIMIT
 	if (content.length > limits.maxSkillContentChars) return `SKILL.md content exceeds ${limits.maxSkillContentChars} characters. Consider splitting into a smaller SKILL.md with supporting files.`;
 	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
@@ -2835,7 +3091,7 @@ function fuzzyReplace(content, oldString, newString, replaceAll) {
 }
 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);
+	if (content.includes(oldString)) return replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, () => newString);
 	const boundary = trimPatternBoundaries(oldString);
 	if (boundary === "") return null;
 	if (boundary !== oldString) {
@@ -2900,7 +3156,7 @@ function planRestructureSections(body, moves) {
 	for (let i = 0; i < lines.length; i += 1) {
 		const span = byStart.get(i);
 		if (span) {
-			rebuilt.push(`> 详见 references/${span.rel.split("/").at(-1)}`);
+			rebuilt.push(`${POINTER_LINE_PREFIX}${span.rel.split("/").at(-1)}`);
 			i = span.end - 1;
 		} else rebuilt.push(lines[i] ?? "");
 	}
@@ -2957,7 +3213,12 @@ var SkillLibrary = class {
 	async read(rawName) {
 		const name = rawName.trim();
 		if (this.badName(name) !== null) return null;
-		return this.io.readText(join(this.dirOf(name), "SKILL.md"));
+		try {
+			return await this.io.readText(join(this.dirOf(name), "SKILL.md"));
+		} catch (error) {
+			if (error?.code === "EISDIR") return null;
+			throw error;
+		}
 	}
 	/**
 	
@@ -3180,7 +3441,7 @@ var SkillLibrary = class {
 		this.notifyMutation({
 			action: "create",
 			name: normalized,
-			filePath: dir
+			skillDir: dir
 		});
 		return {
 			ok: true,
@@ -3235,7 +3496,7 @@ var SkillLibrary = class {
 		this.notifyMutation({
 			action: "update",
 			name,
-			filePath: dir
+			skillDir: dir
 		});
 		return {
 			ok: true,
@@ -3324,7 +3585,7 @@ var SkillLibrary = class {
 		this.notifyMutation({
 			action: "patch",
 			name,
-			filePath: dir
+			skillDir: dir
 		});
 		return {
 			ok: true,
@@ -3374,7 +3635,23 @@ var SkillLibrary = class {
 			await this.io.rename(dir, dest);
 		} catch {
 			await this.io.copy(dir, dest);
-			await this.io.remove(dir);
+			try {
+				await this.io.remove(dir);
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				try {
+					await this.io.remove(dest);
+					return {
+						ok: false,
+						message: `Archive copy succeeded but the source could not be removed (${reason}); the copied archive was rolled back.`
+					};
+				} catch {
+					return {
+						ok: false,
+						message: `Archive copy succeeded but the source could not be removed (${reason}) and the archive copy could not be rolled back — the skill now exists in BOTH the active root and .archive; clean up manually.`
+					};
+				}
+			}
 		}
 		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`);
@@ -3499,7 +3776,7 @@ var SkillLibrary = class {
 					content: `<!-- demoted from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}\n`
 				});
 			}
-			const pointerLines = normalizedSources.map((source) => `\n> 详见 references/${source}.md`).join("");
+			const pointerLines = normalizedSources.map((source) => `\n${POINTER_LINE_PREFIX}${source}.md`).join("");
 			const extended = targetMd.trimEnd() + pointerLines + "\n";
 			const validation = validateFrontmatter(extended, targetName, this.limits);
 			if (validation) return {
@@ -3529,10 +3806,20 @@ var SkillLibrary = class {
 			});
 			if (!result.ok) throw new Error(result.message);
 		} catch (error) {
-			for (const source of archived.reverse()) await this.restoreFromArchive(source).catch(() => {});
+			const reason = error instanceof Error ? error.message : String(error);
+			const failedRestores = [];
+			for (const source of archived.reverse()) try {
+				if (!(await this.restoreFromArchive(source)).ok) failedRestores.push(source);
+			} catch {
+				failedRestores.push(source);
+			}
+			if (failedRestores.length > 0) return {
+				ok: false,
+				message: `Consolidation failed (${reason}); rolled back EXCEPT ${failedRestores.join(", ")} — still in .archive, restore them with /evolution skill restore.`
+			};
 			return {
 				ok: false,
-				message: `Consolidation failed and was rolled back: ${error instanceof Error ? error.message : String(error)}`
+				message: `Consolidation failed and was rolled back: ${reason}`
 			};
 		}
 		return {
@@ -3584,20 +3871,20 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${name}" not found.`
 		};
-		const normalized = md.replace(/\r\n/g, "\n");
-		const frontmatterEnd = normalized.indexOf("\n---", 3);
-		if (frontmatterEnd < 0) return {
+		const block = frontmatterBlock(md);
+		if (!block) return {
 			ok: false,
 			message: "SKILL.md has no valid frontmatter; refusing to restructure."
 		};
-		const header = normalized.slice(0, frontmatterEnd + 4);
-		const plan = planRestructureSections(normalized.slice(frontmatterEnd + 4), moves);
+		const header = block.lines.slice(0, block.end + 1).join(block.nl);
+		const plan = planRestructureSections(md.slice(header.length).replace(/\r\n/g, "\n"), moves);
 		if ("error" in plan) return {
 			ok: false,
 			message: `Restructure rejected: ${plan.error}`
 		};
-		const newMd = header + plan.body;
-		const newMdCheck = validateFrontmatter(newMd, name, this.limits);
+		const newMd = `${header}${plan.body}`.replace(/\r\n/g, "\n");
+		const finalMd = block.nl === "\r\n" ? newMd.replace(/\n/g, "\r\n") : newMd;
+		const newMdCheck = validateFrontmatter(finalMd, name, this.limits);
 		if (newMdCheck) return {
 			ok: false,
 			message: `Restructure rejected: ${newMdCheck}`
@@ -3629,7 +3916,7 @@ var SkillLibrary = class {
 		}
 		writes.push({
 			target: join(dir, "SKILL.md"),
-			content: newMd
+			content: finalMd
 		});
 		const result = await this.applyTreeChange({
 			name,
@@ -3721,11 +4008,11 @@ var SkillLibrary = class {
 				message: `Tree change failed and was rolled back: ${error instanceof Error ? error.message : String(error)}`
 			};
 		}
-		await this.audit(name, plan.auditAction, md, landing.find((entry) => entry.target.endsWith("SKILL.md"))?.content ?? md, plan.auditSummary);
+		await this.audit(name, plan.auditAction, md, landing.find((entry) => entry.target.split(/[\\/]/).pop() === "SKILL.md")?.content ?? md, plan.auditSummary);
 		this.notifyMutation({
 			action: plan.eventAction,
 			name,
-			filePath: dir
+			skillDir: dir
 		});
 		return {
 			ok: true,
@@ -3758,7 +4045,12 @@ var SkillLibrary = class {
 				message: "No skill archive available."
 			};
 		}
-		const chosen = entries.filter((entry) => entry === name || entry.startsWith(`${name}-`)).sort().reverse()[0];
+		const candidates = entries.filter((entry) => entry === name || entry.startsWith(`${name}-`)).sort().reverse();
+		let chosen;
+		for (const candidate of candidates) if (parseFrontmatter(await this.io.readText(join(archiveRoot, candidate, "SKILL.md")).catch(() => null) ?? "")?.frontmatter.name === name) {
+			chosen = candidate;
+			break;
+		}
 		if (!chosen) return {
 			ok: false,
 			message: `Skill "${name}" is not in .archive.`
@@ -3774,14 +4066,21 @@ var SkillLibrary = class {
 		try {
 			await this.io.rename(source, dest);
 		} catch {
-			await this.io.copy(source, dest);
-			await this.io.remove(source);
+			try {
+				await this.io.copy(source, dest);
+				await this.io.remove(source);
+			} catch (error) {
+				return {
+					ok: false,
+					message: `Restore of "${name}" from .archive failed: ${error instanceof Error ? error.message : String(error)}`
+				};
+			}
 		}
 		if (await this.io.exists(join(dest, ".archive-reason"))) await this.io.remove(join(dest, ".archive-reason"));
 		this.notifyMutation({
 			action: "restore",
 			name,
-			filePath: dest
+			skillDir: dest
 		});
 		return {
 			ok: true,
@@ -3827,7 +4126,8 @@ var SkillLibrary = class {
 		this.notifyMutation({
 			action: "write_file",
 			name,
-			filePath: target
+			skillDir: dir,
+			file: target
 		});
 		return {
 			ok: true,
@@ -3868,7 +4168,8 @@ var SkillLibrary = class {
 		this.notifyMutation({
 			action: "remove_file",
 			name,
-			filePath: target
+			skillDir: dir,
+			file: target
 		});
 		return {
 			ok: true,
@@ -3996,7 +4297,43 @@ var SkillLibrary = class {
 			ok: false,
 			message: "No skill snapshot available."
 		};
-		await this.snapshotAll("pre-rollback", extras);
+		const preRollbackPath = await this.snapshotAll("pre-rollback", extras);
+		try {
+			await this.restoreSnapshotIntoRoot(latest.path);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			try {
+				await this.restoreSnapshotIntoRoot(preRollbackPath);
+				return {
+					ok: false,
+					message: `Snapshot restore failed (${reason}); the active tree was rolled back to the pre-rollback snapshot.`
+				};
+			} catch (rollbackError) {
+				return {
+					ok: false,
+					message: `Snapshot restore failed (${reason}) AND pre-rollback restore failed (${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}). Rescue manually from: ${preRollbackPath} (pre-rollback), ${latest.path} (target).`
+				};
+			}
+		}
+		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,
+			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
+		};
+	}
+	/**
+	* Whole-tree replacement from one snapshot path (rc.50 P2-14): every
+	* NON-system entry in the active root is cleared first, then the manifest
+	* drives the repopulation (skills, sidecars, `.archive`). Extracted from
+	* restoreLatestSnapshot so a failed restore can roll itself back (E-13).
+	*/
+	async restoreSnapshotIntoRoot(snapshotPath) {
 		let rootEntries;
 		try {
 			rootEntries = await this.io.list(this.root);
@@ -4007,200 +4344,30 @@ var SkillLibrary = class {
 			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)) {
+		const manifest = await this.readSnapshotManifest(snapshotPath);
+		if (manifest === null) for (const entry of await this.io.list(snapshotPath)) {
 			if (entry === "manifest.json" || entry === "extras") continue;
-			await this.io.copy(join(latest.path, entry), join(this.root, entry));
+			await this.io.copy(join(snapshotPath, 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));
+			for (const name of manifest.skills) await this.io.copy(join(snapshotPath, name), join(this.root, name));
+			for (const sidecar of manifest.sidecars) await this.io.copy(join(snapshotPath, 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);
+				await this.io.copy(join(snapshotPath, ".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,
-			...snapshotExtras.length === 0 ? {} : { extras: snapshotExtras }
-		};
 	}
 };
 //#endregion
-//#region lib/types/drift-signals.js
-/**
-* Library-level drift signals for the maintenance subagent (design 011).
-*
-* Deterministic fact checks over a skill-library snapshot: domain drift
-* (narrow names, near-duplicate groups, prefix clusters) and layer drift
-* (log-like bodies, duplicate headings, overlong lines, missing support-file
-* pointers, description over the authoring bar). Pure functions only — no IO,
-* no LLM, no services. Thresholds are imported from their owning modules
-* (skill-health / quality / skill-store), never duplicated.
-*
-* Distinct from `signals.ts` — the session-level review signal gate.
-*/
-/** Physical line length at/above which a body line is reported overlong (011 §4). */
-const DRIFT_MAX_LINE_CHARS = 1500;
-/** Signal-set version: bump whenever ids/thresholds change (011 §7 version coupling). */
-const DRIFT_SIGNALS_VERSION = "1";
-/** Render-time nouns for the MAINTAIN_PROMPT placeholders (single vocabulary with the facts block). */
-const DRIFT_SIGNAL_NOUNS = {
-	dedup_group: "近重复组",
-	prefix_cluster: "前缀聚类",
-	stamp_density: "stamp 密度",
-	body_size: "正文体量",
-	dup_heading: "重复标题",
-	overlong_line: "超长行",
-	pointer_missing: "缺失指针",
-	description_chars: "描述长度",
-	narrow_name: "窄名",
-	usage_observed: "使用观察",
-	quality_low: "质量分"
-};
-const NARROW_NAME_PATTERNS = [
-	{
-		label: "error-string",
-		re: /^(?:err|error|exception|traceback|warn|fail)(?:[-_][a-z0-9]+)+$/i
-	},
-	{
-		label: "pr-number",
-		re: /^(?:pr|issue)[-_]?\d{2,}$/i
-	},
-	{
-		label: "dated",
-		re: /\d{4}-\d{2}-\d{2}/
-	},
-	{
-		label: "session-verb",
-		re: /^(?:fix|debug|audit|salvage|diagnose|investigate)[-_][a-z0-9-]+$/i
-	}
-];
-/** Detect support files the body never references (by basename or relative path). */
-function missingSupportPointers(body, supportFiles) {
-	return supportFiles.filter((path) => {
-		const base = path.split("/").pop() ?? path;
-		return base.length > 0 && !body.includes(base) && !body.includes(path);
-	});
-}
-/** Duplicate `## heading` occurrences: singleton results default to head of the file. */
-function duplicateHeadings(body) {
-	const counts = /* @__PURE__ */ new Map();
-	for (const line of body.split("\n")) {
-		const m = /^##\s+(.+)$/.exec(line);
-		if (m?.[1]) {
-			const heading = m[1].trim();
-			if (heading) counts.set(heading, (counts.get(heading) ?? 0) + 1);
-		}
-	}
-	return [...counts.entries()].filter(([, count]) => count > 1).map(([heading, count]) => ({
-		heading,
-		count
-	}));
-}
-/** Physical lines over `max` characters: `{ lineNo, chars }`, 1-based line numbers. */
-function overlongLines(body, max = DRIFT_MAX_LINE_CHARS) {
-	const out = [];
-	const lines = body.split("\n");
-	for (let index = 0; index < lines.length; index += 1) {
-		const length = (lines[index] ?? "").length;
-		if (length > max) out.push({
-			lineNo: index + 1,
-			chars: length
-		});
-	}
-	return out;
-}
-/** Narrow-name shapes detected in a skill name (empty = none). */
-function narrowNameMatches(name) {
-	return NARROW_NAME_PATTERNS.filter(({ re }) => re.test(name)).map(({ label }) => label);
-}
-function supportGroupCount(supportFiles) {
-	const groups = /* @__PURE__ */ new Set();
-	for (const path of supportFiles ?? []) {
-		const head = path.split("/")[0];
-		if (head) groups.add(head);
-	}
-	return groups.size;
-}
-function sig(id, verdict, value, threshold, detail) {
-	return {
-		id,
-		verdict,
-		value,
-		threshold,
-		detail
-	};
-}
-/**
-* Compute all drift signals for a snapshot. Missing inputs (quality score,
-* usage window) yield `unknown` — never a fabricated verdict.
-*/
-function computeDriftSignals(snapshots) {
-	const library = [];
-	const names = snapshots.map((s) => s.name);
-	const dedup = computeDedupGroups({ contents: new Map(snapshots.map((s) => [s.name, s.body])) });
-	library.push(dedup.length === 0 ? sig("dedup_group", "pass", "none", "size >= 2") : sig("dedup_group", "over", dedup.map((group) => group.join(", ")).join(" | "), "size >= 2", `members=${dedup.map((group) => group.join("|")).join(";")}`));
-	const clusters = computePrefixClusters(names);
-	library.push(clusters.length === 0 ? sig("prefix_cluster", "pass", "none", "size >= 2") : sig("prefix_cluster", "over", clusters.map((cluster) => cluster.members.join(", ")).join(" | "), "size >= 2", `key=${clusters.map((cluster) => cluster.key).join("|")}`));
-	const allProvided = snapshots.length > 0 && snapshots.every((s) => s.usageObserved !== null && s.usageObserved !== void 0);
-	library.push(!allProvided ? sig("usage_observed", "unknown", "not-observed", void 0, "usage window status missing") : snapshots.every((s) => s.usageObserved === true) ? sig("usage_observed", "pass", "observed") : sig("usage_observed", "pass", "unobserved"));
-	return {
-		library,
-		skills: snapshots.map((snapshot) => {
-			const signals = [];
-			const body = snapshot.body;
-			const supportFiles = snapshot.supportFiles ?? [];
-			const supportEnumerated = snapshot.supportFiles !== void 0;
-			const density = assessStructureHealth({
-				skillName: snapshot.name,
-				bodyChars: body.length,
-				bodyText: body,
-				supportGroups: supportGroupCount(supportFiles)
-			}, DEFAULT_HEALTH_THRESHOLDS).dims.stampDensityPerKb;
-			signals.push(density === null ? sig("stamp_density", "pass", body.length < 2e3 ? "below-min-body" : "not-assessed") : sig("stamp_density", density >= DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb ? "over" : "pass", `${density.toFixed(2)}/KB`, `${DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb}/KB`));
-			signals.push(sig("body_size", body.length >= DEFAULT_HEALTH_THRESHOLDS.softBodyChars ? "over" : "pass", `${body.length}`, `${DEFAULT_HEALTH_THRESHOLDS.softBodyChars}`));
-			const dupes = duplicateHeadings(body);
-			signals.push(dupes.length === 0 ? sig("dup_heading", "pass", "none") : sig("dup_heading", "over", dupes.map((d) => `${d.heading}(${d.count})`).join(", "), "count >= 2"));
-			const long = overlongLines(body);
-			signals.push(long.length === 0 ? sig("overlong_line", "pass", "none") : sig("overlong_line", "over", long.map((l) => `${l.lineNo}:${l.chars}`).join(", "), `${DRIFT_MAX_LINE_CHARS}`));
-			const missing = supportEnumerated ? missingSupportPointers(body, supportFiles) : void 0;
-			signals.push(!supportEnumerated ? sig("pointer_missing", "unknown", "not-enumerated", void 0, "support files not enumerated") : (missing ?? []).length === 0 ? sig("pointer_missing", "pass", "none") : sig("pointer_missing", "over", missing?.join(", ") ?? ""));
-			const narrow = narrowNameMatches(snapshot.name);
-			signals.push(narrow.length === 0 ? sig("narrow_name", "pass", "none") : sig("narrow_name", "over", narrow.join(", "), void 0, `name=${snapshot.name}`));
-			const description = snapshot.description;
-			signals.push(description === void 0 ? sig("description_chars", "unknown", "missing", "60") : sig("description_chars", description.length > 60 ? "over" : "pass", `${description.length}`, `60`));
-			const quality = snapshot.quality;
-			signals.push(quality === null || quality === void 0 ? sig("quality_low", "unknown", "not-assessed") : sig("quality_low", quality < .3 ? "over" : "pass", quality.toFixed(2), `${LOW_QUALITY_THRESHOLD}`));
-			return {
-				name: snapshot.name,
-				signals,
-				...snapshot.protected !== void 0 && snapshot.protected !== null ? { protected: snapshot.protected } : {},
-				...snapshot.catalogInvalid !== void 0 ? { catalogInvalid: snapshot.catalogInvalid } : {}
-			};
-		})
-	};
-}
-/** Convenience: fetch one signal from an assessment or library list. */
-function findDriftSignal(signals, id) {
-	return signals.find((signal) => signal.id === id);
-}
-//#endregion
 //#region lib/types/state-store.js
 /**
 * 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");
+	return join(env.DSH_HOME || join(homedir(), ".dsh"), "evolution");
 }
 //#endregion
-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_HEALTH_THRESHOLDS, 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, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EvolutionGateSet, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, 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, RESTRUCTURE_TARGET_RE, 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, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };
+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_HEALTH_THRESHOLDS, 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, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, 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, RESTRUCTURE_TARGET_RE, 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, applyCuratorLifecycleFields, applyCuratorMetaFields, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionHome, evolutionIoAdapter, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterYamlUnsafeValues, getRecord, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renderCuratorReportMarkdown, resolveOrigins, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, verifyPromptBundle, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -50,4 +50,17 @@ export declare const DEFAULT_USER_CHAR_LIMIT = 1375;
 /** Consolidation-failure backoff cap, shared by MemoryStore and memory-files' Config default. */
 export declare const DEFAULT_CONSOLIDATION_FAILURES = 3;
 export declare const DEFAULT_SKILL_CONTENT_CHARS = 100000;
+/** 0.3.17 (S3.10, T-1): control-plane fields a model-facing write call may
+ * never carry — single source for plan-validator, evolution-policy and the
+ * threat scanner (they used to each hardcode the list). */
+export declare const FORBIDDEN_CONTROL_KEYS: readonly ["policy", "threshold", "prompt_hash", "model_route", "evolution_config"];
+/** 0.3.17 (S3.10): the model-facing write tools the policy guard and threat
+ * scanner cover. */
+export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];
+/** 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.
+ * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
+ * can reference it without importing the skill-store module. */
+export declare const AUTHORING_DESCRIPTION_BAR = 60;
 //# sourceMappingURL=constants.d.ts.map

package/lib/types/events.d.ts

@@ -35,7 +35,11 @@ export interface EvolutionPlanAppliedEvent {
 export interface EvolutionSkillMutatedEvent {
     action: string;
     name: string;
-    filePath?: string;
+    /** 0.3.16 (E-50): was `filePath` with mixed semantics — skill-directory ops
+     * carried the DIRECTORY while file ops (write_file/remove_file) carried the
+     * FILE path. Split into explicit fields so a subscriber can distinguish. */
+    skillDir?: string;
+    file?: string;
     archivedPath?: string;
 }
 declare module '@deepseek-ai/cordis' {

package/lib/types/index.d.ts

@@ -19,6 +19,7 @@ export * from './preset-composition.ts';
 export * from './prompts.ts';
 export * from './quality.ts';
 export * from './redact.ts';
+export * from './serial.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
 export * from './drift-signals.ts';

package/lib/types/io.d.ts

@@ -26,8 +26,10 @@ export interface EvolutionIoLike {
      * (`null` when missing) and returns the next content; returning `null`
      * deletes the file. A backend without it falls back to plain read+write and
      * the caller keeps its single-process chain as the second layer.
+     * 0.3.16: sync returns are allowed (0.3.16 S1.14 X-1 — mutated callers with
+     * no await in the task need no Promise residue).
      */
-    transact?(this: void, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
+    transact?(this: void, path: string, task: (current: string | null) => string | null | Promise<string | null>): Promise<void>;
     /**
      * Optional symlink probe (G7). `true` = the path is a symlink, `false` = a
      * real entry, `null` = guard not applicable (backend without the probe or
@@ -40,7 +42,7 @@ export interface EvolutionIoLike {
  * back to a plain read → task → write/remove sequence (no cross-process lock —
  * callers keep their single-process serialize chain as the second layer).
  */
-export declare function transactIo(io: EvolutionIoLike, path: string, task: (current: string | null) => Promise<string | null>): Promise<void>;
+export declare function transactIo(io: EvolutionIoLike, path: string, task: (current: string | null) => string | null | Promise<string | null>): Promise<void>;
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;
 export declare function nodeEvolutionIo(): EvolutionIoLike;

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

@@ -46,7 +46,6 @@ export declare class MemoryStore {
      */
     private oversizedFile;
     read(target: MemoryTarget): Promise<string[]>;
-    write(target: MemoryTarget, entries: string[]): Promise<void>;
     resetFailures(): void;
     private failure;
     /**

package/lib/types/prompts.d.ts

@@ -3,8 +3,8 @@
  * changes semantically: the bundle digest is the fail-closed signal for
  * review workers, so a stale id across deployments must be distinguishable.
  */
-export declare const PROMPT_BUNDLE_ID = "dsh-evolution@13";
 export declare const PROMPT_BUNDLE_VERSION = 13;
+export declare const PROMPT_BUNDLE_ID = "dsh-evolution@13";
 export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
 export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 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.\n\nTarget 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.\n\nSignals to look for (any one of these warrants action):\n  \u2022 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.\n  \u2022 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.\n  \u2022 Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.\n  \u2022 A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order \u2014 prefer the earliest action that fits, but do pick one when a signal above fired:\n  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.\n  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.\n  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files \u2014 use the right directory per kind:\n     \u2022 references/<topic>.md \u2014 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.\n     \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).\n     \u2022 scripts/<name>.<ext> \u2014 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).\n     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.\n  4. RESTRUCTURE a loaded skill whose body grew log-like \u2014 rc/sha/date-dense sections, session-detail spirals, or a fat body with no support files. Use skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section (from that heading to the next heading) moves into the support file and its position becomes a pointer line. The skill's name and directory never change. Only propose headings that exist verbatim in the body; never invent one, and never restructure a healthy small skill.\n  5. 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 \u2014 fall back to (1), (2), or (3).\n\nUser-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.\n\nIf you notice two existing skills that overlap, note it in your reply \u2014 the background curator handles consolidation at scale.\n\nTwo-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:\n  \u2022 PATTERN (reusable \u2014 symptom \u2192 mechanism \u2192 fix \u2192 verification, still valuable next session) belongs in the SKILL.md body.\n  \u2022 LOG (one-off \u2014 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.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 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.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 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.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 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.\n\nIf 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 \u2014 never 'this tool does not work' as a standalone constraint.\n\n'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.";
 export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things:\n\n**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.\n\n**Skills**: how to do this class of task. Be ACTIVE \u2014 most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.\n\nTarget 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.\n\nSignals that warrant a skill update (any one is enough):\n  \u2022 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' \u2014 embed the lesson in the skill that governs that task so the next session starts fixed.\n  \u2022 Non-trivial technique, fix, workaround, or debugging path emerged.\n  \u2022 A skill that was loaded or consulted turned out wrong, missing, or outdated \u2014 patch it now.\n\nRead-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session \u2014 ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.\n\nPreference order for skills \u2014 pick the earliest that fits:\n  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.\n  2. UPDATE AN EXISTING UMBRELLA. Patch it.\n  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.\n  4. RESTRUCTURE a loaded skill whose body grew log-like (rc/sha/date-dense sections, session-detail spirals, fat body with no support files) via skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section moves into the support file and its position becomes a pointer line; the skill's name and directory never change. Only propose headings that exist verbatim in the body.\n  5. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level \u2014 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).\n\nTwo-tier deposition discipline (DSH addition): classify before writing \u2014 PATTERN (symptom \u2192 mechanism \u2192 fix \u2192 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.\n\nUser-preference embedding: when the user complains about how you handled a task, update the skill that governs that task \u2014 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.\n\nIf you notice overlapping existing skills, mention it \u2014 the background curator handles consolidation.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 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.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 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.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 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.\n\nIf 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 \u2014 never 'this tool does not work' as a standalone constraint.\n\nAct on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop \u2014 but don't reach for that conclusion as a default.";

package/lib/types/serial.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A process-local serial task queue: each task starts only after the previous
+ * one settles (success or failure), so read-modify-write sequences that share
+ * one file never interleave inside this process. The durable cross-process
+ * serialization layer is the IO backend's transact lock; this chain is the
+ * second layer (0.3.17 S2.8, T-1: the shape was duplicated in state-json and
+ * memory-files — one factory now).
+ */
+export declare function makeSerialQueue(): <T>(task: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=serial.d.ts.map

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

@@ -119,15 +119,18 @@ export declare function parseFrontmatter(content: string): {
 } | null;
 /** YAML plain-scalar hazards that make an UNQUOTED frontmatter value
  * unloadable to the platform catalog (strict YAML parser): `: ` (mapping
- * separator), ` #` (comment start), or a leading YAML indicator. The
- * evolution `parseFrontmatter` is deliberately lenient, so violations
- * silently split family-visibility from platform-visibility (0.3.11
- * inkos-harness case: the description carried "…: " and the catalog dropped
- * the whole skill). Already-quoted values and well-formed flow collections
- * (`[a, b]` / `{a: b}`) are considered safe. This rule is only the FAST
- * PATH — the write path re-verifies every rewrite with the real YAML parser
- * (see normalizeFrontmatter), so an incomplete approximation can never
- * corrupt a multiline flow value (P3-4). */
+ * separator), ` #` (comment start), a trailing `:` (a mapping marker),
+ * or a leading YAML indicator. The evolution `parseFrontmatter` is
+ * deliberately lenient, so violations silently split family-visibility from
+ * platform-visibility (0.3.11 inkos-harness case: the description carried
+ * "…: " and the catalog dropped the whole skill). Already-quoted values and
+ * well-formed flow collections (`[a, b]` / `{a: b}`) are considered safe.
+ * 0.3.16 (E-47): null/bool/number-shaped plain scalars are flagged too — they
+ * parse as booleans/numbers on the platform while the family keeps the string
+ * (a `description: true` split-brain).
+ * This rule is only the FAST PATH — the write path re-verifies every rewrite
+ * with the real YAML parser (see normalizeFrontmatter), so an incomplete
+ * approximation can never corrupt a multiline flow value (P3-4). */
 export declare function yamlPlainScalarNeedsQuotes(value: string): boolean;
 /** Raw-line scan of the frontmatter block: entries whose UNQUOTED value is
  * YAML-unsafe for the strict platform catalog. Operates on the ORIGINAL line
@@ -172,10 +175,9 @@ export declare function normalizeFrontmatter(content: string): FrontmatterNormal
  */
 export declare function relatedSkillNames(content: string, exclude?: string): string[];
 export declare function validateFrontmatter(content: string, expectedName?: string, limits?: SkillLimits): string | 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. */
-export declare const AUTHORING_DESCRIPTION_BAR = 60;
+/** Hermes authoring quality bar for descriptions — see constants.ts
+ * (0.3.16 T-4 moved the single source there; the public re-export sits behind
+ * the package root, which re-exports constants anyway). */
 export interface AuthoringFeedback {
     /** Frontmatter description length in characters (0 when absent). */
     descriptionChars: number;
@@ -341,5 +343,12 @@ export declare class SkillLibrary {
     restoreLatestSnapshot(extras?: SnapshotExtra[]): Promise<SkillActionResult & {
         extras?: SnapshotExtra[];
     }>;
+    /**
+     * Whole-tree replacement from one snapshot path (rc.50 P2-14): every
+     * NON-system entry in the active root is cleared first, then the manifest
+     * drives the repopulation (skills, sidecars, `.archive`). Extracted from
+     * restoreLatestSnapshot so a failed restore can roll itself back (E-13).
+     */
+    private restoreSnapshotIntoRoot;
 }
 //# sourceMappingURL=skill-store.d.ts.map

package/lib/types/threats.d.ts

@@ -26,6 +26,9 @@ export interface ScanOptions {
 /**
  * Scan text at `scope`. Patterns are cumulative: `strict` includes all scopes.
  * `options.excludeLabels` removes matching patterns without changing `scope`.
+ * `maxScanChars` is the WINDOW SIZE, not a total cap (E-12, 0.3.16): the whole
+ * text is always scanned in overlapping windows, so content beyond 65,536
+ * characters (skill files may run to 100,000) is no longer a blind zone.
  */
 export declare function scanThreats(text: string, scope?: ThreatScope, maxScanChars?: number, options?: ScanOptions): ThreatFinding[];
 /** Blocking policy: any hit blocks. `severity` is deliberately not a gate. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "publishConfig": {
     "access": "public"
   },