@lmzhen/dsh-evolution-core 0.3.70 → 0.3.72

package/lib/index.js

@@ -1,4 +1,4 @@
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
@@ -956,6 +956,41 @@ async function updateSuppressedNames(root, io, task) {
 * threshold, which are intentionally left where they are used.
 * @module @lmzhen/dsh-evolution-core
 */
+/**
+* Required argument names per `skill_manage` action — the SINGLE SOURCE read
+* by the tool's argument gate (tool-skill-manage executeCore) and the plan
+* validator (evolution-plan-validator), so the two can never drift.
+* OPT-05 (2026-09): the plan validator used to accept a `write_file`/
+* `remove_file` op without `file_path` while the executor required it — the
+* staged write then failed at EVERY approve until rejected.
+* Rows here are the op-level requirements only: `delete` additionally
+* requires `absorbed_into` at the PLAN layer (review passes may only delete
+* into an umbrella) and `pin`/`unpin` are tool-only actions — each consumer
+* adds its own extras on top of this table. An empty-string argument is NOT
+* caught here (the tool's gate deliberately lets it reach the library for a
+* more specific remedy message); the validator adds its own `.trim()`
+* emptiness checks for payload fields.
+*/
+const SKILL_ACTION_REQUIRED_FIELDS = {
+	create: ["name", "content"],
+	edit: ["name", "content"],
+	update: ["name", "content"],
+	patch: [
+		"name",
+		"old_string",
+		"new_string"
+	],
+	delete: ["name"],
+	write_file: [
+		"name",
+		"file_path",
+		"file_content"
+	],
+	remove_file: ["name", "file_path"],
+	restructure: ["name"],
+	pin: ["name"],
+	unpin: ["name"]
+};
 /** Skill frontmatter `name` validated for the file name (lowercase + hyphen).
 * 计划 B-4 (v18): tightened to the UPSTREAM `SKILL_NAME` shape
 * (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:20). The
@@ -1647,11 +1682,11 @@ async function readEvolutionEvents(io, path) {
 * malformed (or unreadable) ARCHIVE is skipped — it never bricks the boot and
 * it is still flagged.
 */
-async function readEvolutionTimeline(io, path) {
+async function readEvolutionTimeline(io, path, archives) {
 	const dir = dirname(path);
 	let malformed = false;
 	const bySeq = /* @__PURE__ */ new Map();
-	for (const name of await listEventArchives(io, path)) {
+	for (const name of archives ?? await listEventArchives(io, path)) {
 		const read = await readEvolutionEvents(io, join(dir, name));
 		if (read.malformed) malformed = true;
 		for (const event of read.events) bySeq.set(event.seq, event);
@@ -2137,13 +2172,22 @@ function buildLearnPrompt(userRequest) {
 * C-11: the adoption test and the RETURNED value now come from the
 * SAME trimmed source — the old form tested `trim()` but returned the raw
 * value, so `DSH_HOME=" /x "` was accepted AND persisted with literal spaces.
-* Known tradeoff vs upstream `resolveDshHome`: `~` is NOT expanded here —
-* documented as a deliberate difference in the v10 audit; revisit only if a
-* real deployment needs it.
+* OPT-27 (2026-09, plan D5 — accepted): the v10-era "no `~` expansion, no
+* resolve" divergence from upstream `resolveDshHome` is RETIRED. It became
+* load-bearing when the skill-catalog shadow made "same tree as the upstream
+* `USER_DSH_RANK` provider" a hard contract: upstream watches the EXPANDED
+* absolute `<home>/skills` while this value fed a literal `~/x` (a directory
+* named `~` under the host CWD) or a CWD-relative path — split-brain skill
+* trees, preset installs the platform never reads, doctor probes of a
+* directory nothing serves. Behavior now matches upstream:
+* `resolve(expandHomePath(selected))`. Only `~`-prefixed and RELATIVE
+* DSH_HOME values change landing spot; absolute homes are byte-identical.
 */
 function evolutionRoot(env = process.env) {
 	const home = env.DSH_HOME?.trim();
-	return home ? home : join(homedir(), ".dsh");
+	const selected = home ? home : join(homedir(), ".dsh");
+	const expanded = selected === "~" ? homedir() : selected.startsWith("~/") || selected.startsWith("~\\") ? join(homedir(), selected.slice(2)) : selected;
+	return isAbsolute(expanded) ? expanded : resolve(expanded);
 }
 /** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar
 * state (reports, activity store, feedback file, state-domain data). */
@@ -2516,7 +2560,9 @@ function scanMemoryThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTIONS
 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.${THREAT_EXEMPTION_HINT}`;
+	const pattern = findings.find((f) => f.category !== "unicode_obfuscation");
+	if (pattern) return `Blocked by security scan (${pattern.label}). This content appears to contain potentially malicious instructions.${THREAT_EXEMPTION_HINT}`;
+	return `Blocked by security scan: invisible or potentially malicious Unicode detected. This content appears to contain potentially malicious instructions.${THREAT_EXEMPTION_HINT}`;
 }
 /**
 * WD2 (0.3.56): the shared tail of every user-facing threat block — names the
@@ -3508,7 +3554,7 @@ const SECRET_PATTERNS = [
 const INLINE_ASSIGNMENT_PATTERN = /* @__PURE__ */ new RegExp("(^|[^\\w-])([\\w-]{0,64}[_\\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\\-][\\w-]{0,64})?)\\b([\"\\']?[\\t ]*[:=][\\t ]*)([^\\r\\n]+)", "gi");
 const URL_CREDENTIALS_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)([^\s/@]+)@/gi;
 const PEM_PRIVATE_KEY_PATTERN = new RegExp(`-----BEGIN\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----[\\s\\S]*?-----END\\s+(?:(?:RSA|EC|DSA|OPENSSH|ENCRYPTED|PGP)\\s+)?PRIVATE\\s+KEY(?:\\s+BLOCK)?-----`, "g");
-const BLOCK_KEY_ONLY_LINE = /(?:^|\s)([\w-]{0,64}[_\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\-][\w-]{0,64})?)\s*:\s*$/i;
+const BLOCK_KEY_ONLY_LINE = /(?:^|\s)([\w-]{0,64}[_\-])?((?:token|api[_-]?key|secret|password|passwd)(?:[_\-][\w-]{0,64})?)\s*:(?:\r)?$/i;
 /**
 * Mask credential-shaped text before it crosses a session boundary.
 * @param text - the text about to be sent to a model outside this session.
@@ -3525,7 +3571,7 @@ function redactSecrets(text) {
 		const line = lines[i];
 		if (line === void 0 || !BLOCK_KEY_ONLY_LINE.test(line)) continue;
 		const next = lines[i + 1] ?? "";
-		const [, indent, value, tail] = /^([ \t]+)(\S.*?)([ \t]*)$/.exec(next) ?? [];
+		const [, indent, value, tail] = /^([ \t]+)(\S.*?)([ \t]*)(?:\r)?$/.exec(next) ?? [];
 		if (indent === void 0 || value === void 0) continue;
 		if (value.includes("<redacted>")) continue;
 		lines[i + 1] = `${indent}<redacted>${tail ?? ""}`;
@@ -3877,6 +3923,32 @@ function findDriftSignal(signals, id) {
 * the default dsh skill-filesystem user root. The plugin only manages skills
 * it created unless a `.hermes-managed` marker opts a skill in. Archival is a
 * move to `.archive/` — never a hard delete.
+*
+* ## Concurrency discipline (OPT-09, 2026-09) — read before adding a mutator
+*
+* Three primitives, three distinct jobs (they compose, they do not replace
+* each other):
+*
+* 1. **In-process serial queue** (`this.serial`, makeSerialQueue) — orders the
+*    read→plan→commit phases of one skill's mutation against OTHER mutators
+*    in this process. Used by: create/update/patch/setPinned/restructure/
+*    writeSupportFile/removeSupportFile and (whole-mutation) consolidate.
+*    NON-reentrant: a callback must never call a public method that wraps
+*    itself in `this.serial` (archive/restoreFromArchive deliberately do not).
+* 2. **Per-directory write lock** (io.ts LOCK_*) — cross-process mutual
+*    exclusion plus in-process crash ownership (tickets, takeover). Checked
+*    with `hasWriteLock` before any destructive move (archive/restore/
+*    snapshot); held inside transactIo by byte writers.
+* 3. **CAS baseline (`expected:`)** — any read whose bytes feed a later write
+*    must either live inside the serial section that commits the write, or
+*    carry its plan-time bytes as `expected` so the commit fails closed on
+*    drift (V8-11 / V24-01). A read outside the serial section WITHOUT a
+*    baseline is a lost-update bug; this file's history is the test suite.
+*
+* Known residuals (deliberate, documented at their sites): the archive commit
+* re-check narrows but does not close the pin race (OPT-06); snapshotAll
+* re-probes after its copies so a mid-copy writer demotes to `skipped`
+* (OPT-07); the movers' probe→rename window is owned by the io.ts protocol.
 */
 /** 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
@@ -3888,6 +3960,65 @@ const DEFAULT_SKILL_LIMITS = {
 	maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
 	maxSkillFileBytes: MAX_SKILL_FILE_BYTES
 };
+/**
+* Evaluate a stage-time anchor against the bytes a locked read observed.
+* @param anchor - the caller's anchor, or `undefined` for an unanchored write.
+* @param current - the bytes the write lock read (`null` = the target is absent).
+* @returns `match` when the write may proceed, otherwise the refusal verdict.
+*/
+function anchorVerdict(anchor, current) {
+	if (anchor === void 0) return "match";
+	if ("absent" in anchor) return current === null ? "match" : "drift";
+	if (current === null) return "missing";
+	return contentHash(current) === anchor.sha256 ? "match" : "drift";
+}
+/**
+* Build the refusal for a skill write whose anchor did not hold. The wording is
+* the library's own; a caller with staged-replay wording (the skill tool, the
+* review plan) re-words it from {@link SkillActionResult.anchor}.
+* @param name - the skill name the refusal names.
+* @param verdict - the non-matching verdict.
+* @returns the refusal result (nothing was written).
+*/
+function anchorRefusal(name, verdict) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: verdict,
+		message: verdict === "missing" ? `Skill "${name}" not found.` : `Skill "${name}" changed since it was read; the write was refused to avoid overwriting newer content.`
+	};
+}
+/**
+* Build the refusal for a support-file write/remove whose anchor did not hold.
+* @param name - the owning skill name.
+* @param filePath - the support-file path inside the skill.
+* @param verdict - the non-matching verdict.
+* @returns the refusal result (nothing was written or removed).
+*/
+/**
+* Refusal for a target the locked read could not verify at all (EISDIR, an
+* unreadable file). A staged replay reports "could not be verified" instead of
+* propagating an exception: nothing was read, so nothing can have been written.
+* @param name - the owning skill name.
+* @param filePath - the support-file path, or `null` for the skill body.
+* @returns the refusal result.
+*/
+function anchorUnverifiable(name, filePath) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: "drift",
+		message: filePath === null ? `Skill "${name}" could not be read to verify the staged content.` : `Support file "${filePath}" of "${name}" could not be read to verify the staged content.`
+	};
+}
+function anchorRefusalFile(name, filePath, verdict) {
+	return {
+		ok: false,
+		stale: true,
+		anchor: verdict,
+		message: verdict === "missing" ? `File "${filePath}" not found in skill "${name}".` : `Support file "${filePath}" of "${name}" changed since it was read; the write was refused to avoid overwriting newer content.`
+	};
+}
 /** Upper bound of moves per restructure proposal (validator and core agree). */
 const MAX_RESTRUCTURE_MOVES = 5;
 /** Restructure targets are plain markdown files under references/ — no
@@ -4647,9 +4778,11 @@ var SkillLibrary = class {
 	* mutation event are issued ONLY when a write actually lands, so a no-op
 	* never inflates the mutation-maturity counter.
 	*/
-	async runSingleWrite(path, task) {
+	async runSingleWrite(path, task, readFailure) {
 		let outcome;
+		const progress = { entered: false };
 		const run = async (current) => {
+			progress.entered = true;
 			const o = await task(current ?? null);
 			outcome = {
 				...o,
@@ -4662,11 +4795,18 @@ var SkillLibrary = class {
 		if (this.transact) try {
 			await this.transact(this.io, path, run);
 		} catch (error) {
+			if (!progress.entered && readFailure !== void 0) return readFailure;
 			if (!committedOnly(error)) throw error;
 			durabilityWarning = error instanceof Error ? error.message : String(error);
 		}
 		else {
-			const current = await this.io.readText(path);
+			let current;
+			try {
+				current = await this.io.readText(path);
+			} catch (error) {
+				if (readFailure !== void 0) return readFailure;
+				throw error;
+			}
 			const next = await run(current);
 			if (next !== null && next !== current) try {
 				await this.io.writeText(path, next);
@@ -4745,7 +4885,14 @@ var SkillLibrary = class {
 			throw error;
 		}
 	}
-	async list() {
+	/**
+	* Summarize the skill tree.
+	* @param options - `withContent` attaches each skill's whole SKILL.md body to
+	* its summary (v35 C11): the read this listing already performs is the one the
+	* body would cost again, so a content-consuming caller pays no second pass.
+	* @returns one summary per readable skill directory.
+	*/
+	async list(options = {}) {
 		const summaries = [];
 		for (const name of await listNames(this.root, this.io)) {
 			const dir = this.dirOf(name);
@@ -4793,7 +4940,8 @@ var SkillLibrary = class {
 					hermesManaged
 				].some((value) => value === null),
 				managed: hermesManaged === true,
-				...typeof parsedWhenToUse === "string" && parsedWhenToUse.trim() !== "" ? { whenToUse: parsedWhenToUse } : {}
+				...typeof parsedWhenToUse === "string" && parsedWhenToUse.trim() !== "" ? { whenToUse: parsedWhenToUse } : {},
+				...options.withContent === true ? { content: md } : {}
 			});
 		}
 		return summaries;
@@ -5145,11 +5293,11 @@ var SkillLibrary = class {
 			...norm.changed ? { normalizedFrontmatterFields: norm.fields } : {}
 		};
 	}
-	async update(rawName, content, origin = "foreground") {
+	async update(rawName, content, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.updateCore(name, content, origin));
+		return await this.serial(() => this.updateCore(name, content, origin, anchor));
 	}
-	async updateCore(name, content, origin) {
+	async updateCore(name, content, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -5186,6 +5334,11 @@ var SkillLibrary = class {
 			message: threat
 		};
 		return await this.runSingleWrite(path, (current) => {
+			const verdict = anchorVerdict(anchor, current);
+			if (verdict !== "match") return {
+				result: anchorRefusal(name, verdict),
+				write: null
+			};
 			if (current === null) return {
 				result: {
 					ok: false,
@@ -5224,7 +5377,7 @@ var SkillLibrary = class {
 					skillDir: dir
 				}
 			};
-		});
+		}, anchor !== void 0 ? anchorRefusal(name, "missing") : void 0);
 	}
 	async patch(rawName, oldString, newString, filePath = "", replaceAll = false, origin = "foreground") {
 		const name = rawName.trim();
@@ -5563,6 +5716,11 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${name}" is being written (write lock present); retry archiving once the write completes.`
 		};
+		const commitProtection = await this.deleteProtection(name, options);
+		if (commitProtection) return {
+			ok: false,
+			message: commitProtection === "pinned" ? `Skill "${name}" is pinned and cannot be archived. Remove the \`.pinned\` marker in its directory, then retry.` : `Skill "${name}" is protected (${commitProtection}).`
+		};
 		const moveFailure = await this.moveDir(dir, dest);
 		if (moveFailure !== void 0) return {
 			ok: false,
@@ -5626,74 +5784,74 @@ var SkillLibrary = class {
 			ok: false,
 			message: `Skill "${targetName}" is protected (${targetProtection}).`
 		};
-		const referenceWrites = [];
-		const parts = [];
-		if (mode === "append") for (const source of normalizedSources) {
-			const protection = await this.deleteProtection(source);
-			if (protection) return {
-				ok: false,
-				message: `Skill "${source}" is protected (${protection}).`
-			};
-			const sourceMd = await this.io.readText(join(this.dirOf(source), "SKILL.md"));
-			if (!sourceMd) return {
-				ok: false,
-				message: `Skill "${source}" not found.`
-			};
-			const parsed = parseFrontmatter(sourceMd);
-			if (!parsed) return {
-				ok: false,
-				message: `Skill "${source}" has no valid frontmatter; refusing to merge.`
-			};
-			if (await this.countSupportDirs(source) > 0) return {
-				ok: false,
-				message: `Consolidation rejected: source "${source}" carries support files — use mode:'reference' or archive the whole package instead.`
-			};
-			const refs = supportRefs(parsed.body);
-			if (refs.length > 0) return {
-				ok: false,
-				message: `Consolidation rejected: source "${source}" body references support files (${refs.join(", ")}) that would be left behind — use mode:'reference' or archive the whole package instead.`
-			};
-			parts.push(`\n<!-- consolidated from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}`);
-		}
-		else for (const source of normalizedSources) {
-			const protection = await this.deleteProtection(source);
-			if (protection) return {
-				ok: false,
-				message: `Skill "${source}" is protected (${protection}).`
-			};
-			const sourceMd = await this.io.readText(join(this.dirOf(source), "SKILL.md"));
-			if (!sourceMd) return {
-				ok: false,
-				message: `Skill "${source}" not found.`
-			};
-			const parsed = parseFrontmatter(sourceMd);
-			if (!parsed) return {
-				ok: false,
-				message: `Skill "${source}" has no valid frontmatter; refusing to demote.`
-			};
-			const refs = supportRefs(parsed.body);
-			if (refs.length > 0) return {
-				ok: false,
-				message: `Consolidation rejected: source "${source}" body references support files (${refs.join(", ")}) that would be left behind — archive the whole package instead.`
-			};
-			const target = join(targetDir, "references", `${source}.md`);
-			referenceWrites.push({
-				target,
-				content: `<!-- demoted from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}\n`
-			});
-		}
-		const archived = [];
-		try {
-			if (!await this.io.readText(join(targetDir, "SKILL.md"))) return {
-				ok: false,
-				message: `Skill "${targetName}" not found.`
-			};
-			for (const source of normalizedSources) {
-				const result = await this.archive(source, { absorbedInto: targetName });
-				if (!result.ok) throw new Error(result.message);
-				archived.push(source);
+		return await this.serial(async () => {
+			const referenceWrites = [];
+			const parts = [];
+			if (mode === "append") for (const source of normalizedSources) {
+				const protection = await this.deleteProtection(source);
+				if (protection) return {
+					ok: false,
+					message: `Skill "${source}" is protected (${protection}).`
+				};
+				const sourceMd = await this.io.readText(join(this.dirOf(source), "SKILL.md"));
+				if (!sourceMd) return {
+					ok: false,
+					message: `Skill "${source}" not found.`
+				};
+				const parsed = parseFrontmatter(sourceMd);
+				if (!parsed) return {
+					ok: false,
+					message: `Skill "${source}" has no valid frontmatter; refusing to merge.`
+				};
+				if (await this.countSupportDirs(source) > 0) return {
+					ok: false,
+					message: `Consolidation rejected: source "${source}" carries support files — use mode:'reference' or archive the whole package instead.`
+				};
+				const refs = supportRefs(parsed.body);
+				if (refs.length > 0) return {
+					ok: false,
+					message: `Consolidation rejected: source "${source}" body references support files (${refs.join(", ")}) that would be left behind — use mode:'reference' or archive the whole package instead.`
+				};
+				parts.push(`\n<!-- consolidated from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}`);
+			}
+			else for (const source of normalizedSources) {
+				const protection = await this.deleteProtection(source);
+				if (protection) return {
+					ok: false,
+					message: `Skill "${source}" is protected (${protection}).`
+				};
+				const sourceMd = await this.io.readText(join(this.dirOf(source), "SKILL.md"));
+				if (!sourceMd) return {
+					ok: false,
+					message: `Skill "${source}" not found.`
+				};
+				const parsed = parseFrontmatter(sourceMd);
+				if (!parsed) return {
+					ok: false,
+					message: `Skill "${source}" has no valid frontmatter; refusing to demote.`
+				};
+				const refs = supportRefs(parsed.body);
+				if (refs.length > 0) return {
+					ok: false,
+					message: `Consolidation rejected: source "${source}" body references support files (${refs.join(", ")}) that would be left behind — archive the whole package instead.`
+				};
+				const target = join(targetDir, "references", `${source}.md`);
+				referenceWrites.push({
+					target,
+					content: `<!-- demoted from ${source} at ${(/* @__PURE__ */ new Date()).toISOString()} -->\n${parsed.body.trim()}\n`
+				});
 			}
-			const result = await this.serial(async () => {
+			const archived = [];
+			try {
+				if (!await this.io.readText(join(targetDir, "SKILL.md"))) return {
+					ok: false,
+					message: `Skill "${targetName}" not found.`
+				};
+				for (const source of normalizedSources) {
+					const result = await this.archive(source, { absorbedInto: targetName });
+					if (!result.ok) throw new Error(result.message);
+					archived.push(source);
+				}
 				const freshTargetMd = await this.io.readText(join(targetDir, "SKILL.md"));
 				if (!freshTargetMd) return {
 					ok: false,
@@ -5735,7 +5893,7 @@ var SkillLibrary = class {
 						expected: freshTargetMd
 					});
 				}
-				return await this.applyTreeChange({
+				const result = await this.applyTreeChange({
 					name: targetName,
 					origin,
 					protection: "write",
@@ -5744,30 +5902,30 @@ var SkillLibrary = class {
 					auditSummary: `consolidated ${normalizedSources.join(", ")} (${mode}) into ${targetName}`,
 					eventAction: "consolidate"
 				});
-			});
-			if (!result.ok) throw new Error(result.message);
-			return {
-				ok: true,
-				message: `Consolidated ${normalizedSources.join(", ")} into "${targetName}".`,
-				path: targetDir
-			};
-		} catch (error) {
-			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 (!result.ok) throw new Error(result.message);
+				return {
+					ok: true,
+					message: `Consolidated ${normalizedSources.join(", ")} into "${targetName}".`,
+					path: targetDir
+				};
+			} catch (error) {
+				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: ${reason}`
+				};
 			}
-			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: ${reason}`
-			};
-		}
+		});
 	}
 	/**
 	* Content-distribution repair (008 batch B, 009-R kernel): move body
@@ -6012,6 +6170,14 @@ var SkillLibrary = class {
 			ok: false,
 			message: await this.io.exists(join(dest, "SKILL.md")) ? `Skill "${name}" already exists in the active root; refusing to overwrite.` : `Skill directory "${name}" already exists in the active root but carries no SKILL.md; remove or repair it before restoring.`
 		};
+		let caseVariant;
+		try {
+			caseVariant = (await this.io.list(this.root)).find((entry) => entry !== name && entry.toLowerCase() === name.toLowerCase());
+		} catch {}
+		if (caseVariant !== void 0) return {
+			ok: false,
+			message: `Skill "${caseVariant}" (same name, different letter case) already exists in the active root; restoring "${name}" beside it would create ambiguous duplicates — restore as "${caseVariant}" or remove the variant first.`
+		};
 		const archiveRoot = join(this.root, ".archive");
 		let entries;
 		try {
@@ -6081,11 +6247,11 @@ var SkillLibrary = class {
 			path: dest
 		};
 	}
-	async writeSupportFile(rawName, filePath, content, origin = "foreground") {
+	async writeSupportFile(rawName, filePath, content, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.writeSupportFileCore(name, filePath, content, origin));
+		return await this.serial(() => this.writeSupportFileCore(name, filePath, content, origin, anchor));
 	}
-	async writeSupportFileCore(name, filePath, content, origin) {
+	async writeSupportFileCore(name, filePath, content, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -6117,6 +6283,11 @@ var SkillLibrary = class {
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
 		return await this.runSingleWrite(target, (current) => {
+			const verdict = anchorVerdict(anchor, current);
+			if (verdict !== "match") return {
+				result: anchorRefusalFile(name, filePath, verdict),
+				write: null
+			};
 			if (current !== null && content.trimEnd() === current.trimEnd()) return {
 				result: {
 					ok: true,
@@ -6147,13 +6318,13 @@ var SkillLibrary = class {
 					file: target
 				}
 			};
-		});
+		}, anchor !== void 0 ? anchorUnverifiable(name, filePath) : void 0);
 	}
-	async removeSupportFile(rawName, filePath, origin = "foreground") {
+	async removeSupportFile(rawName, filePath, origin = "foreground", anchor) {
 		const name = rawName.trim();
-		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin));
+		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin, anchor));
 	}
-	async removeSupportFileCore(name, filePath, origin) {
+	async removeSupportFileCore(name, filePath, origin, anchor) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -6175,17 +6346,25 @@ var SkillLibrary = class {
 			message: validation
 		};
 		const target = join(dir, ...filePath.replace(/\\/g, "/").split("/").filter(Boolean));
-		if (!await this.io.exists(target)) return {
-			ok: false,
-			message: `File "${filePath}" not found in skill "${name}".`
-		};
+		if (!await this.io.exists(target)) {
+			if (anchor !== void 0) return anchorRefusalFile(name, filePath, "missing");
+			return {
+				ok: false,
+				message: `File "${filePath}" not found in skill "${name}".`
+			};
+		}
 		const before = await this.io.readText(target).catch(() => null);
 		if (before === null) return {
 			ok: false,
 			message: `"${filePath}" is not a readable regular file — remove the files inside it one by one.`
 		};
-		if (this.transact) await this.transact(this.io, target, () => null);
-		else await this.io.remove(target);
+		let verdict = anchorVerdict(anchor, before);
+		if (verdict === "match" && this.transact) await this.transact(this.io, target, (current) => {
+			verdict = anchorVerdict(anchor, current);
+			return verdict === "match" ? null : current;
+		});
+		else if (verdict === "match") await this.io.remove(target);
+		if (verdict !== "match") return anchorRefusalFile(name, filePath, verdict);
 		await this.audit(name, "remove_file", before, null, `removed ${filePath}`);
 		this.notifyMutation({
 			action: "remove_file",
@@ -6251,6 +6430,13 @@ var SkillLibrary = class {
 				await this.io.copy(this.dirOf(name), join(dest, name));
 			}))).find((result) => result.status === "rejected");
 			if (copyFailure) throw copyFailure.reason;
+			const suspect = [];
+			for (const name of copyable) if (await this.hasWriteLock(this.dirOf(name))) suspect.push(name);
+			if (suspect.length > 0) {
+				for (const name of suspect) console.warn(`skill-store: snapshot demoted "${name}" to skipped — a write lock appeared while its copy ran; the copied bytes are suspect`);
+				for (const name of suspect) copyable.splice(copyable.indexOf(name), 1);
+				skipped.push(...suspect);
+			}
 			const sidecars = [];
 			for (const sidecar of [usageFile(this.root), suppressedFile(this.root)]) if (await this.io.exists(sidecar)) {
 				const name = basename(sidecar);
@@ -6520,4 +6706,4 @@ var SkillLibrary = class {
 	}
 };
 //#endregion
-export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, 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, EMPTY_LOCK_TAKEOVER_MS, 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, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, decideTakeover, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, isCommittedWarning, isProcessAlive, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { AUTHORING_DESCRIPTION_BAR, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, 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, EMPTY_LOCK_TAKEOVER_MS, 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, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, PATTERN_OVERLAP, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorFields, applyCuratorLifecycleFields, applyCuratorMetaFields, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, clampedNumber, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, createGateSet, decideTakeover, duplicateHeadings, emptyRecord, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, isCommittedWarning, isProcessAlive, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadSuppressedNames, loadUsage, makeSerialQueue, markAgentCreated, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, readEvolutionEvents, readEvolutionTimeline, recordMutation, redactSecrets, relatedSkillNames, renameWithRetry, renderCuratorReportMarkdown, resolveOrigins, resolveRootConfig, resolveSkillsRoot, retainEventArchives, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, transactIo, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -19,6 +19,22 @@
  * threshold, which are intentionally left where they are used.
  * @module @lmzhen/dsh-evolution-core
  */
+/**
+ * Required argument names per `skill_manage` action — the SINGLE SOURCE read
+ * by the tool's argument gate (tool-skill-manage executeCore) and the plan
+ * validator (evolution-plan-validator), so the two can never drift.
+ * OPT-05 (2026-09): the plan validator used to accept a `write_file`/
+ * `remove_file` op without `file_path` while the executor required it — the
+ * staged write then failed at EVERY approve until rejected.
+ * Rows here are the op-level requirements only: `delete` additionally
+ * requires `absorbed_into` at the PLAN layer (review passes may only delete
+ * into an umbrella) and `pin`/`unpin` are tool-only actions — each consumer
+ * adds its own extras on top of this table. An empty-string argument is NOT
+ * caught here (the tool's gate deliberately lets it reach the library for a
+ * more specific remedy message); the validator adds its own `.trim()`
+ * emptiness checks for payload fields.
+ */
+export declare const SKILL_ACTION_REQUIRED_FIELDS: Readonly<Record<string, readonly string[]>>;
 /** Skill frontmatter `name` validated for the file name (lowercase + hyphen).
  * 计划 B-4 (v18): tightened to the UPSTREAM `SKILL_NAME` shape
  * (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, packages/skill/skill/src/index.ts:20). The

package/lib/types/evolution-events.d.ts

@@ -140,5 +140,5 @@ export declare function readEvolutionEvents(io: EvolutionIoLike, path: string):
  * malformed (or unreadable) ARCHIVE is skipped — it never bricks the boot and
  * it is still flagged.
  */
-export declare function readEvolutionTimeline(io: EvolutionIoLike, path: string): Promise<EventLogRead>;
+export declare function readEvolutionTimeline(io: EvolutionIoLike, path: string, archives?: readonly string[]): Promise<EventLogRead>;
 //# sourceMappingURL=evolution-events.d.ts.map

package/lib/types/index.d.ts

@@ -7,6 +7,23 @@
  * the host auto-assembles to register this package's no-op invariant);
  * consumers import named exports from the package root so published npm
  * bundles never depend on source subpaths.
+ *
+ * ## Layer map (OPT-28, 2026-09) — locate code by LAYER, not by directory
+ *
+ * This one physical package carries THREE architecture layers of the family;
+ * when adding or looking for something, go by the export's layer:
+ *
+ * - **Cross-cutting basics** — `state-store.ts` (env roots — the single
+ *   source of DSH-home semantics), `serial.ts`, `numeric.ts`, `constants.ts`,
+ *   `mutations.ts`, `events.ts`, `gates.ts`.
+ * - **Security primitives** — `threats.ts` (content threat scanner),
+ *   `redact.ts` (credential masking at model boundaries). Consumers:
+ *   evolution-policy/threat, both stores, review, maintenance.
+ * - **Core domain stores/logic** — `skill-store.ts` (skill tree engine +
+ *   IO-seam consumer), `memory-store.ts`, `usage.ts`, `curator.ts`,
+ *   `quality.ts`, `signals.ts`, `drift-signals.ts`, `skill-health.ts`,
+ *   `preset-composition.ts`, `prompts.ts`, `learn-prompt.ts`,
+ *   `evolution-events.ts`, `io.ts` (the ctx.evolutionIo seam itself).
  * @module @lmzhen/dsh-evolution-core
  */
 export * from './curator.ts';

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

@@ -5,6 +5,32 @@
  * the default dsh skill-filesystem user root. The plugin only manages skills
  * it created unless a `.hermes-managed` marker opts a skill in. Archival is a
  * move to `.archive/` — never a hard delete.
+ *
+ * ## Concurrency discipline (OPT-09, 2026-09) — read before adding a mutator
+ *
+ * Three primitives, three distinct jobs (they compose, they do not replace
+ * each other):
+ *
+ * 1. **In-process serial queue** (`this.serial`, makeSerialQueue) — orders the
+ *    read→plan→commit phases of one skill's mutation against OTHER mutators
+ *    in this process. Used by: create/update/patch/setPinned/restructure/
+ *    writeSupportFile/removeSupportFile and (whole-mutation) consolidate.
+ *    NON-reentrant: a callback must never call a public method that wraps
+ *    itself in `this.serial` (archive/restoreFromArchive deliberately do not).
+ * 2. **Per-directory write lock** (io.ts LOCK_*) — cross-process mutual
+ *    exclusion plus in-process crash ownership (tickets, takeover). Checked
+ *    with `hasWriteLock` before any destructive move (archive/restore/
+ *    snapshot); held inside transactIo by byte writers.
+ * 3. **CAS baseline (`expected:`)** — any read whose bytes feed a later write
+ *    must either live inside the serial section that commits the write, or
+ *    carry its plan-time bytes as `expected` so the commit fails closed on
+ *    drift (V8-11 / V24-01). A read outside the serial section WITHOUT a
+ *    baseline is a lost-update bug; this file's history is the test suite.
+ *
+ * Known residuals (deliberate, documented at their sites): the archive commit
+ * re-check narrows but does not close the pin race (OPT-06); snapshotAll
+ * re-probes after its copies so a mid-copy writer demotes to `skipped`
+ * (OPT-07); the movers' probe→rename window is owned by the io.ts protocol.
  */
 import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type MutationRecord } from './mutations.ts';
@@ -31,7 +57,32 @@ export interface SkillSummary {
      * platform catalog keeps it while this provider shadows the upstream
      * filesystem provider. Absent when the frontmatter has none. */
     whenToUse?: string;
+    /** v35 C11: the whole SKILL.md body, present only for
+     * {@link SkillLibrary.list} calls that pass `{ withContent: true }`. A consumer
+     * that needs both the summary fields and the body (tree hashing, enrichment,
+     * drift scans) saves the second per-skill read; the default stays body-free so
+     * the common listing does not hold a whole tree in memory. */
+    content?: string;
 }
+/**
+ * Stage-time anchor for a full-content write (v35 C9): the sha256 the caller read
+ * when it staged the plan, or `absent` when the target did not exist then. The
+ * library compares it against the bytes it reads INSIDE the write's own lock — the
+ * same read the write commits — so a concurrent writer landing between staging and
+ * commit is refused instead of silently overwritten.
+ */
+export type WriteAnchor = {
+    readonly sha256: string;
+} | {
+    readonly absent: true;
+};
+/**
+ * What the write lock observed about an anchor target.
+ * - `match`: the anchor holds; the write proceeds.
+ * - `drift`: the target exists with different bytes.
+ * - `missing`: the target does not exist (an `absent` anchor `match`es this).
+ */
+export type AnchorVerdict = 'match' | 'drift' | 'missing';
 export interface SkillActionResult {
     ok: boolean;
     message: string;
@@ -42,6 +93,12 @@ export interface SkillActionResult {
     /** 0.3.18 (E-68): patch produced byte-identical content (old===new) — no
      * write, no audit, no mutation event; callers must not count a patch. */
     noop?: boolean;
+    /** Set when the caller passed a {@link WriteAnchor} that the locked read did
+     * not satisfy: nothing was written. Carries {@link SkillActionResult.anchor}
+     * so a caller with staged-replay wording can translate it (v35 C9). */
+    stale?: true;
+    /** The locked read's verdict for the caller's anchor. */
+    anchor?: AnchorVerdict;
 }
 /**
  * One section move of a restructure proposal (008 batch B): a body section
@@ -369,7 +426,16 @@ export declare class SkillLibrary {
      * last-writer-wins.
      */
     readSupportFile(name: string, filePath: string): Promise<string | null>;
-    list(): Promise<SkillSummary[]>;
+    /**
+     * Summarize the skill tree.
+     * @param options - `withContent` attaches each skill's whole SKILL.md body to
+     * its summary (v35 C11): the read this listing already performs is the one the
+     * body would cost again, so a content-consuming caller pays no second pass.
+     * @returns one summary per readable skill directory.
+     */
+    list(options?: {
+        withContent?: boolean;
+    }): Promise<SkillSummary[]>;
     read(rawName: string): Promise<string | null>;
     /**
   
@@ -439,7 +505,7 @@ export declare class SkillLibrary {
     private setPinnedCore;
     create(name: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
     private createCore;
-    update(rawName: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    update(rawName: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private updateCore;
     patch(rawName: string, oldString: string, newString: string, filePath?: string, replaceAll?: boolean, origin?: WriteOrigin): Promise<SkillActionResult>;
     private patchCore;
@@ -546,9 +612,9 @@ export declare class SkillLibrary {
      * path back. The `.archive-reason` marker is dropped on restore.
      */
     restoreFromArchive(rawName: string): Promise<SkillActionResult>;
-    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private writeSupportFileCore;
-    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin): Promise<SkillActionResult>;
+    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private removeSupportFileCore;
     /**
      * v23 (ML-1): `.archive` retention. Archived skills are recoverable history,

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

@@ -20,9 +20,16 @@
  * C-11: the adoption test and the RETURNED value now come from the
  * SAME trimmed source — the old form tested `trim()` but returned the raw
  * value, so `DSH_HOME=" /x "` was accepted AND persisted with literal spaces.
- * Known tradeoff vs upstream `resolveDshHome`: `~` is NOT expanded here —
- * documented as a deliberate difference in the v10 audit; revisit only if a
- * real deployment needs it.
+ * OPT-27 (2026-09, plan D5 — accepted): the v10-era "no `~` expansion, no
+ * resolve" divergence from upstream `resolveDshHome` is RETIRED. It became
+ * load-bearing when the skill-catalog shadow made "same tree as the upstream
+ * `USER_DSH_RANK` provider" a hard contract: upstream watches the EXPANDED
+ * absolute `<home>/skills` while this value fed a literal `~/x` (a directory
+ * named `~` under the host CWD) or a CWD-relative path — split-brain skill
+ * trees, preset installs the platform never reads, doctor probes of a
+ * directory nothing serves. Behavior now matches upstream:
+ * `resolve(expandHomePath(selected))`. Only `~`-prefixed and RELATIVE
+ * DSH_HOME values change landing spot; absolute homes are byte-identical.
  */
 export declare function evolutionRoot(env?: NodeJS.ProcessEnv): string;
 /** Evolution home path helper: `$DSH_HOME/evolution` for plugin-owned sidecar

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.70",
+  "version": "0.3.72",
   "publishConfig": {
     "access": "public"
   },