@lmzhen/dsh-evolution-core 0.3.71 → 0.3.73

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
@@ -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
@@ -5644,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,
@@ -5707,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,
@@ -5816,7 +5893,7 @@ var SkillLibrary = class {
 						expected: freshTargetMd
 					});
 				}
-				return await this.applyTreeChange({
+				const result = await this.applyTreeChange({
 					name: targetName,
 					origin,
 					protection: "write",
@@ -5825,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
@@ -6093,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 {
@@ -6345,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);
@@ -6614,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/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';

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