@lmzhen/dsh-evolution-commands 0.22.0 → 0.23.0

package/lib/index.js

@@ -2,9 +2,10 @@ import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
 import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_GROUP_LABELS, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, assertSkillsRootAliasRetired, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, composePresetEntry, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, isDeprecatedParamId, isMissingPath, isPresent, isUnknown, liveBool, mergePresetRow, newRunRegistry, newSkillLibrary, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeText, reportsSweepLockTarget, resolveBasePresetPatch, resolveParamId, resolveRootConfig, scopedProbeReport, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_SKILL_LIMITS, MAX_TIMER_DELAY_MS, PARAM_EXPOSURE, PARAM_GROUP_LABELS, absentHostServices, appendEvolutionEvent, applyNamespaceMigration, asRecord, assertSkillsRootAliasRetired, atomicWriteFiles, buildLearnPrompt, canonicalWriteId, clampedNumber, classifyNamespaceMigration, composePresetEntry, elapsedSince, errorText, eventsFile, evolutionHome, evolutionRoot, isDeprecatedParamId, isPresent, isRecord, isUnknown, liveBool, mergePresetRow, newRunRegistry, newSkillLibrary, paramSettingsId, partitionVersions, planNamespaceMigration, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeText, reportsSweepLockTarget, resolveBasePresetPatch, resolveParamId, resolveRootConfig, scopedProbeReport, sweepReports, transactIo } from "@lmzhen/dsh-evolution-core";
 import { buildEnrichment, buildMaintainFacts, enrichmentSnapshotOptions, runMaintain, snapshotFromLibrary } from "@lmzhen/dsh-evolution-maintenance";
-import { copyFileSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { preferProvider } from "@lmzhen/dsh-evolution-io";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region lib/types/migration.js
@@ -194,7 +195,7 @@ async function objectOf(read) {
 	if (read === void 0) return void 0;
 	try {
 		const value = await read();
-		return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+		return isRecord(value) ? value : void 0;
 	} catch {
 		return;
 	}
@@ -579,7 +580,7 @@ function liveRowTails(plugins) {
 * @returns the mapping, or undefined for anything else.
 */
 function asMapping(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+	return asRecord(value);
 }
 /** Profile bundle rows for evolution-family packages across all profiles.
 *
@@ -1288,9 +1289,24 @@ const SOURCE_LABELS = Object.freeze({
 });
 /** What the E-tiers mean, so the count line reads without the docs. */
 const TIER_LEGEND = "档位：E0 固定／E1 只读／E2 安装时定／E3 你可改／E4 装完固化。";
+/**
+* The source column's word for one row (F-1).
+*
+* `unregistered` covers TWO different facts: the owner publishes no settings namespace (the value
+* really cannot be written — E-315/E-316) and the settings service itself is missing (then whether
+* the value could be written is UNKNOWN). Without a provider the column must not claim "不可改", or it
+* contradicts the legend and the footer of the very same output.
+* @param row - the row's surface facts.
+* @param providerMounted - whether a settings provider answered.
+* @returns the label for the source column.
+*/
+function sourceLabel(row, providerMounted) {
+	const label = SOURCE_LABELS[row.source] ?? row.source;
+	return providerMounted || row.source !== "unregistered" ? label : "未知";
+}
 function renderParamRows(rows, options) {
 	const header = pad("参数", 36) + pad("分组", 12) + pad("档位", 6) + pad("生效", 8) + pad("来源", 10) + "当前值";
-	const body = rows.map((row) => pad(row.id, 36) + pad(PARAM_GROUP_LABELS[row.group], 12) + pad(row.tier, 6) + pad(APPLIES_LABELS[row.applies] ?? row.applies, 8) + pad(SOURCE_LABELS[row.source] ?? row.source, 10) + renderValue(row.value));
+	const body = rows.map((row) => pad(row.id, 36) + pad(PARAM_GROUP_LABELS[row.group], 12) + pad(row.tier, 6) + pad(APPLIES_LABELS[row.applies] ?? row.applies, 8) + pad(sourceLabel(row, options.providerMounted), 10) + renderValue(row.value));
 	const tiers = [
 		"E0",
 		"E1",
@@ -1347,116 +1363,160 @@ function renderParamJson(rows) {
 }
 //#endregion
 //#region lib/types/registry.js
+/** The flags the TABLE declares for one subcommand (name → `--flag`), DERIVED from its usage. */
+function flagsOf(name) {
+	const entry = COMMAND_ENTRIES.find((candidate) => entryName(candidate) === name);
+	return entry === void 0 ? [] : entryFlags(entry);
+}
+/** C7 shape, DERIVED: the subcommand name is the first token of `usage` (variants use `|`). */
+function entryName(entry) {
+	const [head = ""] = entry.usage.split(" ");
+	return head.split("|")[0] ?? "";
+}
+/** C7 shape, DERIVED: the flags a `usage` declares, in the form `--flag` (value flags keep their name). */
+function entryFlags(entry) {
+	const found = [];
+	for (const match of entry.usage.matchAll(/--[a-z][a-z-]*/g)) if (!found.includes(match[0])) found.push(match[0]);
+	return found;
+}
 const COMMAND_ENTRIES = [
 	{
+		readonly: true,
 		usage: "pending [--detail]",
 		summary: "列出暂存的写入（--detail 显示参数）"
 	},
 	{
+		readonly: false,
 		usage: "approve <id>",
 		summary: "执行一条已批准的写入"
 	},
 	{
+		readonly: false,
 		usage: "reject <id>",
 		summary: "丢弃一条暂存写入，不执行"
 	},
 	{
+		readonly: false,
 		usage: "release <id>",
 		summary: "把卡在执行中的写入放回待批窗口（先确认效果再批准 or reject)"
 	},
 	{
+		readonly: true,
 		usage: "doctor [--json]",
 		summary: "只读自检：安装形态、冲突、环境、服务（--json 供脚本用）"
 	},
 	{
+		readonly: false,
 		usage: "curator run|pause|resume|status|report|scope",
 		summary: "立即运行一次自动整理，或暂停／恢复／查看状态"
 	},
 	{
+		readonly: true,
 		usage: "mutations",
 		summary: "列出技能改动记录"
 	},
 	{
+		readonly: false,
 		usage: "restore",
 		summary: "从最近的快照恢复技能"
 	},
 	{
+		readonly: false,
 		usage: "consolidate <target> <sources...> [--plan <runId>]",
 		summary: "把若干技能合并进一个总括技能"
 	},
 	{
+		readonly: false,
 		usage: "skill restore <name>",
 		summary: "按名字恢复一个已归档的技能"
 	},
 	{
+		readonly: true,
 		usage: "skill history <name>",
 		summary: "列出某个技能的内容版本（含时间、动作、字符数、哈希前缀）"
 	},
 	{
+		readonly: false,
 		usage: "skill undo <name> [--to v<N>]",
 		summary: "把某个技能的内容回退到某一版（默认上一版；只动内容，撤销本身也记为一版）"
 	},
 	{
+		readonly: false,
 		usage: "skill pin <name>",
 		summary: "钉住一个技能：免于删除、后台审查与生命周期整理（立即生效、随时可解钉；与 skill_manage 的 pin 动作同一语义，不走审批）"
 	},
 	{
+		readonly: false,
 		usage: "skill unpin <name>",
 		summary: "解钉一个技能：撤销上面的冻结（立即生效、不走审批）"
 	},
 	{
+		readonly: true,
 		usage: "skills health",
 		summary: "技能库结构体检"
 	},
 	{
+		readonly: false,
 		usage: "skills refresh",
 		summary: "丢弃目录缓存并重新读取技能树"
 	},
 	{
+		readonly: false,
 		usage: "learn [request]",
 		summary: "向本会话发一条学习请求"
 	},
 	{
+		readonly: false,
 		usage: "maintain [--timeout=<ms> | --facts]",
 		summary: "起一次维护扫描并立即回 run id（后台跑；--facts 为 0 token 预览）"
 	},
 	{
+		readonly: true,
 		usage: "maintain status [<id>]",
 		summary: "看维护扫描：在飞的那次（含已跑多久）或某个 run 的终态"
 	},
 	{
+		readonly: true,
 		usage: "maintain report [<id>]",
 		summary: "读某个 run 的结果正文（省略 id 取本 home 最新一条；没有结果就明说，不装成空结果）"
 	},
 	{
+		readonly: false,
 		usage: "maintain handoff [<id>]",
 		summary: "把某次维护报告交给模型：注入指针与汇报协议，模型只汇报、等你确认后再动手"
 	},
 	{
+		readonly: false,
 		usage: "maintain cancel [<id>]",
 		summary: "停掉在飞的那次维护扫描（省略 id 仅当最新一条是本进程在跑的那次）"
 	},
 	{
+		readonly: false,
 		usage: "migrate",
 		summary: "把旧设置文档里家族的旧分区迁进现在的行（幂等；已迁移过就报「已一致」）"
 	},
 	{
+		readonly: false,
 		usage: "policy set <id> <value> [--expect <revision>]",
 		summary: "通过设置服务写入一个你可改的参数 (E3 only; E1/E2 stay in cordis.yml)"
 	},
 	{
+		readonly: true,
 		usage: "params [--group <name>] [--json]",
 		summary: "列出全部参数：分组、档位、生效时机、来源与当前值（--json feeds scripts)"
 	},
 	{
+		readonly: false,
 		usage: "preset install [--base <name>[,<name>...]]",
 		summary: "把自进化 Agent 预设**行**写进当前 profile 的 patch 层（`profiles/<p>/cordis.patch.yml`；bases 来自 agent 包的 bases.json）"
 	},
 	{
+		readonly: false,
 		usage: "restructure <name> \"<heading>\" <to_file> [--plan <runId>]",
 		summary: "把技能正文的一节移到 references 文件"
 	},
 	{
+		readonly: true,
 		usage: "replay",
 		summary: "比较不同会话与重启之间的计划结果（从活动记录回填）"
 	}
@@ -1474,6 +1534,137 @@ function renderHelpText() {
 	].join("\n");
 }
 //#endregion
+//#region lib/types/parse.js
+/**
+* F-4/G7.4 (C7): the ONE parser for the /evolution command surface.
+*
+* The surface used to answer each subcommand with its own regex (`^params(?: --group ([a-z-]+))?(?: --json)?$`
+* and nine siblings), so `params --json --group review` and `params --group=review` were refused as
+* "not a subcommand", while a sibling regex accepted `=` — and a mistyped group name degraded into the
+* generic error instead of the one that lists the known groups.
+*
+* This parser is order- and `=`-tolerant, matches the subcommand name case-insensitively, keeps a flag
+* VALUE's case intact (the domain layer is the one that validates it), and answers a SYNTAX failure when a
+* declared value flag is left without its value (F-3: `policy set a.b --expect 3` must not read
+* `--expect 3` as the value).
+*
+* @module @lmzhen/dsh-evolution-commands/parse
+*/
+/** The flags whose declared form takes a value (`--group <name>`, `--expect <revision>`, …). */
+/**
+* Exported so the command-table gate can tie it to the table's usage lines (P2: two declarations of
+* "which flags take a value" would otherwise be free to drift apart).
+*/
+const VALUE_FLAGS = [
+	"group",
+	"expect",
+	"base",
+	"to",
+	"timeout",
+	"plan"
+];
+/**
+* Narrow a parse result: true when it is the syntax failure rather than a command.
+* @param result - what {@link parseSubcommand} answered.
+* @returns whether the line was refused.
+*/
+function isParseFailure(result) {
+	return result.kind !== void 0;
+}
+/**
+* Split a command line into tokens: whitespace separates, and a double-quoted run is ONE token with its
+* quotes removed (the `restructure <name> "<heading>" <to_file>` form needs that; the old regexes each
+* carried their own quoting rule).
+* @param input - the text after `/evolution`.
+* @returns the tokens, in order.
+*/
+function tokenize(input) {
+	const tokens = [];
+	let current = "";
+	let quoted = false;
+	for (const char of input.trim()) {
+		if (char === String.fromCharCode(34)) {
+			quoted = !quoted;
+			continue;
+		}
+		if (!quoted && /\s/.test(char)) {
+			if (current !== "") {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (current !== "") tokens.push(current);
+	return tokens;
+}
+/**
+* Read one SUB-FORM line: `maintain status`, `maintain report`, … — the shape the regexes used to own.
+*
+* A sub-form matches only when: the line parses, the name matches, the first positional is the sub-form,
+* and every flag the line carries is DECLARED by the table (an undeclared flag keeps the old
+* "unknown arguments" answer instead of silently becoming a bare flag).
+* @param input - the text after `/evolution`.
+* @param name - the subcommand name the table declares (e.g. `maintain`).
+* @param sub - the sub-form word (e.g. `status`).
+* @param declaredFlags - the flags the table declares for `name` (`flagsOf(name)`).
+* @returns the parsed command, or null when this line is not that sub-form.
+*/
+function subcommandOf(input, name, sub, declaredFlags) {
+	const parsed = parseSubcommand(input);
+	if (isParseFailure(parsed) || parsed.name !== name) return null;
+	if (parsed.positionals[0] !== sub) return null;
+	for (const flag of parsed.flags.keys()) if (!declaredFlags.includes("--" + flag)) return null;
+	return parsed;
+}
+/**
+* Parse one command line into its name, flags and positionals.
+* @param input - the text after `/evolution`.
+* @returns the parsed command, or the syntax failure that refused it.
+*/
+function parseSubcommand(input) {
+	const [first, ...rest] = tokenize(input);
+	if (first === void 0) return {
+		kind: "unknown-subcommand",
+		name: ""
+	};
+	const name = first.toLowerCase();
+	const flags = /* @__PURE__ */ new Map();
+	const positionals = [];
+	for (let index = 0; index < rest.length; index += 1) {
+		const token = rest[index];
+		if (token === void 0) continue;
+		if (!token.startsWith("--")) {
+			positionals.push(token);
+			continue;
+		}
+		const equals = token.indexOf("=");
+		const flag = (equals < 0 ? token : token.slice(0, equals)).slice(2);
+		if (equals >= 0) {
+			flags.set(flag, token.slice(equals + 1));
+			continue;
+		}
+		if (!VALUE_FLAGS.includes(flag)) {
+			flags.set(flag, true);
+			continue;
+		}
+		const next = rest[index + 1];
+		if (next === void 0 || next.startsWith("--")) return {
+			kind: "missing-value",
+			name,
+			flag
+		};
+		flags.set(flag, next);
+		index += 1;
+	}
+	return {
+		name,
+		flags,
+		positionals
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Human commands for the evolution family: /evolution learn|pending|curator|restore|consolidate|skills refresh.
@@ -1650,7 +1841,7 @@ function apply(ctx, rawConfig = {}) {
 		const ioRegistry = ioCtx.get("evolutionIo");
 		if (!ioRegistry) return;
 		const registry = newRunRegistry({
-			io: ioRegistry.provider(),
+			io: preferProvider(ioRegistry, ["fs"]),
 			home: evolutionHome(),
 			warn: (message) => {
 				ctx.logger.warn(message);
@@ -1691,15 +1882,15 @@ function apply(ctx, rawConfig = {}) {
 				return err(errorText("e-306-this-deployment-stages-foreground", { a1: what }));
 			};
 			const approval = ctx.get("evolutionApproval");
-			const pendingMatch = /^pending(?: --detail)?$/.exec(input);
-			if (pendingMatch) {
+			const pendingParsed = parseSubcommand(input);
+			if (!isParseFailure(pendingParsed) && pendingParsed.name === "pending") {
 				if (!approval) return err(errorText("e-301-approval-service-not-mounted"));
 				const listed = [...await approval.list("pending"), ...await approval.list("executing")];
 				const pending = [...new Map(listed.map((row) => [row.id, row])).values()];
 				const ttlMs = typeof approval.ttlMs === "number" && Number.isFinite(approval.ttlMs) ? approval.ttlMs : 0;
 				const ttlNote = ttlMs > 0 ? `\n(staged writes expire after ${ttlMs} ms: an expired write is closed as REJECTED and is never executed — stage it again if it is still wanted)` : "\n(staged writes never expire — the window waits for a decision; set the evolution-approval row pendingTtlMs to bound it)";
 				if (pending.length === 0) return ok("No pending evolution writes." + ttlNote);
-				const detailed = pendingMatch[0] === "pending --detail";
+				const detailed = pendingParsed.flags.get("detail") === true;
 				const nowMs = Date.now();
 				const attribution = (p) => {
 					const age = elapsedSince(p.createdAt, nowMs);
@@ -1882,7 +2073,7 @@ function apply(ctx, rawConfig = {}) {
 				if (!ioRegistry) return err("Evolution IO registry not mounted — skill pinning unavailable.");
 				const result = await newSkillLibrary({
 					config: { root: skillsRootValue },
-					io: ioRegistry.provider(),
+					io: preferProvider(ioRegistry, ["fs"]),
 					ctx,
 					limits: {
 						...DEFAULT_SKILL_LIMITS,
@@ -1936,12 +2127,13 @@ function apply(ctx, rawConfig = {}) {
 				});
 				return woke ? ok("Learning request sent to this session. Follow it now.") : ok("Learning request queued for this session — this host exposes no wake-up channel, so it is read on your next message.");
 			}
-			if (input === "maintain --facts") {
+			const factsParsed = parseSubcommand(input);
+			if (!isParseFailure(factsParsed) && factsParsed.name === "maintain" && factsParsed.flags.get("facts") === true && factsParsed.positionals.length === 0) {
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("Evolution IO registry not mounted — maintenance facts unavailable.");
 				const library = newSkillLibrary({
 					config: { root: skillsRootValue },
-					io: ioRegistry.provider()
+					io: preferProvider(ioRegistry, ["fs"])
 				});
 				const enrichment = await buildEnrichment(ctx, library);
 				const readFailures = [];
@@ -1953,15 +2145,17 @@ function apply(ctx, rawConfig = {}) {
 					}
 				});
 				if (snapshots.length === 0 && readFailures.length > 0) return err(`maintenance scan could not read ${readFailures.length} listed skill(s) (${readFailures.slice(0, 10).join(", ")}${readFailures.length > 10 ? ", …" : ""}) and read no skill at all — the library was NOT audited; fix the unreadable skills (or their directory names) and run the scan again`);
-				if (snapshots.length === 0 && skillsRootValue !== "" && !await ioRegistry.provider().exists(skillsRootValue)) return err(`maintenance scan found an empty skill library, but the configured skill root does not exist (${skillsRootValue}) — point the skillsRoot config at a real directory (a literal \`~\` is not expanded) and run the scan again`);
+				if (snapshots.length === 0 && skillsRootValue !== "" && !await preferProvider(ioRegistry, ["fs"]).exists(skillsRootValue)) return err(`maintenance scan found an empty skill library, but the configured skill root does not exist (${skillsRootValue}) — point the skillsRoot config at a real directory (a literal \`~\` is not expanded) and run the scan again`);
 				if (snapshots.length === 0) return ok("Maintenance scan: empty skill library. Nothing to do.");
 				const { facts } = buildMaintainFacts(snapshots, enrichment.usageObservedValue, void 0);
 				return ok(`Maintenance facts (0-token preview):\n${facts}`);
 			}
-			const maintainArgs = /^maintain(?:\s+--timeout[ =](\d+))?\s*$/.exec(input);
-			if (maintainArgs) {
-				const runTimeoutMs = maintainArgs[1] ? Number(maintainArgs[1]) : config.maintainTimeoutMs ?? 6e5;
-				if (!Number.isSafeInteger(runTimeoutMs) || runTimeoutMs <= 0 || runTimeoutMs > MAX_TIMER_DELAY_MS) return err(maintainArgs[1] ? `Invalid --timeout value: expected a positive integer number of milliseconds up to ${MAX_TIMER_DELAY_MS} (e.g. /evolution maintain --timeout 600000).` : `The maintainTimeoutMs config is invalid: expected a positive integer number of milliseconds up to ${MAX_TIMER_DELAY_MS}. Fix the evolution-commands row config (maintainTimeoutMs), then retry.`);
+			const maintainParsed = parseSubcommand(input);
+			const maintainFlagsDeclared = [...isParseFailure(maintainParsed) ? [] : maintainParsed.flags.keys()].every((flag) => flagsOf("maintain").includes("--" + flag));
+			if (!isParseFailure(maintainParsed) && maintainParsed.name === "maintain" && maintainParsed.positionals.length === 0 && maintainFlagsDeclared) {
+				const timeoutFlag = maintainParsed.flags.get("timeout");
+				const runTimeoutMs = typeof timeoutFlag === "string" ? Number(timeoutFlag) : config.maintainTimeoutMs ?? 6e5;
+				if (!Number.isSafeInteger(runTimeoutMs) || runTimeoutMs <= 0 || runTimeoutMs > MAX_TIMER_DELAY_MS) return err(timeoutFlag !== void 0 ? `Invalid --timeout value: expected a positive integer number of milliseconds up to ${MAX_TIMER_DELAY_MS} (e.g. /evolution maintain --timeout 600000).` : `The maintainTimeoutMs config is invalid: expected a positive integer number of milliseconds up to ${MAX_TIMER_DELAY_MS}. Fix the evolution-commands row config (maintainTimeoutMs), then retry.`);
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — maintenance scan unavailable.");
 				const synced = await syncRuns(registry);
@@ -1992,7 +2186,7 @@ function apply(ctx, rawConfig = {}) {
 					try {
 						const library = newSkillLibrary({
 							config: { root: skillsRootValue },
-							io: ioRegistry.provider()
+							io: preferProvider(ioRegistry, ["fs"])
 						});
 						const enrichment = await buildEnrichment(ctx, library);
 						const outcome = await runMaintain({
@@ -2004,7 +2198,7 @@ function apply(ctx, rawConfig = {}) {
 							logger: { warn: (message) => {
 								ctx.logger.warn(message);
 							} },
-							rootExists: skillsRootValue === "" ? void 0 : () => ioRegistry.provider().exists(skillsRootValue),
+							rootExists: skillsRootValue === "" ? void 0 : () => preferProvider(ioRegistry, ["fs"]).exists(skillsRootValue),
 							skillRoot: skillsRootValue
 						}, {
 							timeoutMs: runTimeoutMs,
@@ -2013,7 +2207,7 @@ function apply(ctx, rawConfig = {}) {
 							enrichment: () => enrichment
 						});
 						const endedAt = Date.now();
-						const resultRef = await writeMaintainReport(ioRegistry.provider(), {
+						const resultRef = await writeMaintainReport(preferProvider(ioRegistry, ["fs"]), {
 							runId: handle.id,
 							...outcome.ok ? {
 								verdict: outcome.verdict,
@@ -2037,7 +2231,7 @@ function apply(ctx, rawConfig = {}) {
 							...outcome.ok ? {} : { failure: handle.signal.aborted ? "cancelled: the scan was stopped before it settled" : outcome.error ?? "Maintenance scan failed." }
 						});
 						if (outcome.ok) {
-							appendEvolutionEvent(ioRegistry.provider(), eventsFile(runRoot), {
+							appendEvolutionEvent(preferProvider(ioRegistry, ["fs"]), eventsFile(runRoot), {
 								type: "maintain",
 								source: "manual",
 								runId: handle.id,
@@ -2091,12 +2285,12 @@ function apply(ctx, rawConfig = {}) {
 					`- stop:   /evolution maintain cancel ${handle.id}`
 				].join("\n"));
 			}
-			const maintainStatus = /^maintain\s+status(?:\s+(\S+))?\s*$/.exec(input);
-			if (maintainStatus) {
+			const maintainStatus = subcommandOf(input, "maintain", "status", flagsOf("maintain"));
+			if (maintainStatus !== null) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — run status unavailable.");
 				const synced = await syncRuns(registry);
-				const wanted = maintainStatus[1];
+				const wanted = maintainStatus.positionals[1];
 				if (wanted !== void 0) {
 					const record = registry.find(wanted);
 					if (!record) {
@@ -2112,12 +2306,12 @@ function apply(ctx, rawConfig = {}) {
 				const recent = all.filter((record) => record.state !== "running").slice(0, 5);
 				return ok([live.length === 0 ? "No maintenance run in flight." : `In flight:\n${live.map(renderRunRecord).join("\n")}`, recent.length === 0 ? "" : `Recent:\n${recent.map(renderRunRecord).join("\n")}`].filter((part) => part !== "").join("\n"));
 			}
-			const maintainReport = /^maintain\s+report(?:\s+(\S+))?\s*$/.exec(input);
-			if (maintainReport) {
+			const maintainReport = subcommandOf(input, "maintain", "report", flagsOf("maintain"));
+			if (maintainReport !== null) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — run results unavailable.");
 				const synced = await syncRuns(registry);
-				const wanted = maintainReport[1];
+				const wanted = maintainReport.positionals[1];
 				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
 				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
 				if (!record) {
@@ -2130,17 +2324,17 @@ function apply(ctx, rawConfig = {}) {
 				if (wanted === void 0 && record.state === "running") return err(`The newest run ${record.id} is still running — its report appears when it settles; /evolution maintain status ${record.id} shows where it is.`);
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("Evolution IO registry not mounted — run results unavailable.");
-				const probed = await readRunReport(ioRegistry.provider(), record);
+				const probed = await readRunReport(preferProvider(ioRegistry, ["fs"]), record);
 				if (probed.kind === "missing") return err(`Run ${record.id} (${record.state}) has NO result: no report was written${record.failure === void 0 ? "" : ` (${record.failure})`}.`);
 				if (probed.kind === "unknown") return err(`Run ${record.id} has a report that could not be read (${probed.reason}) — this is not "no result".`);
 				return ok(probed.text);
 			}
-			const maintainCancel = /^maintain\s+cancel(?:\s+(\S+))?\s*$/.exec(input);
-			if (maintainCancel) {
+			const maintainCancel = subcommandOf(input, "maintain", "cancel", flagsOf("maintain"));
+			if (maintainCancel !== null) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — run cancellation unavailable.");
 				const synced = await syncRuns(registry);
-				const wanted = maintainCancel[1];
+				const wanted = maintainCancel.positionals[1];
 				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
 				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
 				if (!record) {
@@ -2157,12 +2351,12 @@ function apply(ctx, rawConfig = {}) {
 				}
 				return ok(`Maintenance run ${record.id} cancelled — the scan stops at its next checkpoint. /evolution maintain status ${record.id} shows the terminal state.`);
 			}
-			const maintainHandoff = /^maintain\s+handoff(?:\s+(\S+))?\s*$/.exec(input);
-			if (maintainHandoff) {
+			const maintainHandoff = subcommandOf(input, "maintain", "handoff", flagsOf("maintain"));
+			if (maintainHandoff !== null) {
 				const registry = runs;
 				if (!registry) return err("Evolution IO registry not mounted — the report cannot be handed over.");
 				const synced = await syncRuns(registry);
-				const wanted = maintainHandoff[1];
+				const wanted = maintainHandoff.positionals[1];
 				if (wanted === void 0 && !synced.ok) return err(unreadableIndex(synced.note));
 				const record = wanted === void 0 ? newestRun(registry) : registry.find(wanted);
 				if (!record) {
@@ -2175,7 +2369,7 @@ function apply(ctx, rawConfig = {}) {
 				if (wanted === void 0 && record.state === "running") return err(`The newest run ${record.id} is still running — its report appears when it settles; /evolution maintain status ${record.id} shows where it is.`);
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("Evolution IO registry not mounted — the report cannot be handed over.");
-				const probed = await readRunReport(ioRegistry.provider(), record);
+				const probed = await readRunReport(preferProvider(ioRegistry, ["fs"]), record);
 				if (probed.kind === "missing") return err(`Run ${record.id} (${record.state}) has NO result: no report was written${record.failure === void 0 ? "" : ` (${record.failure})`}.`);
 				if (probed.kind === "unknown") return err(`Run ${record.id} has a report that could not be read (${probed.reason}) — this is not "no result".`);
 				const missingAgent = agentMissing("handoff");
@@ -2201,9 +2395,9 @@ function apply(ctx, rawConfig = {}) {
 				return ok(woke ? `Handed run ${record.id} to the model — report: ${reportDigestPath(record)}. It will read the file and follow the action lines.` : `Handed run ${record.id} to the model, queued — this host exposes no wake-up channel, so it is read on your next message.`);
 			}
 			if (/^maintain\b/.test(input)) return err("Unknown maintain arguments: expected `maintain`, `maintain --timeout <ms>` / `maintain --timeout=<ms>`, `maintain status [<id>]`, `maintain report [<id>]`, `maintain handoff [<id>]` or `maintain cancel [<id>]`. Got: " + input);
-			const presetInstall = /^preset install(?: --base (\S+))?$/.exec(input);
-			if (presetInstall !== null || /^preset\b/.test(input)) {
-				if (presetInstall === null) return err("Unknown preset arguments: expected `preset install` or `preset install --base <name>[,<name>...]` (the names live in the agent package's bases.json). Got: " + input);
+			const presetParsed = parseSubcommand(input);
+			const presetInstall = isParseFailure(presetParsed) || presetParsed.name !== "preset" ? null : presetParsed.positionals[0] === "install" && presetParsed.positionals.length === 1 && [...presetParsed.flags.keys()].every((flag) => flagsOf("preset").includes("--" + flag)) ? presetParsed : false;
+			if (presetInstall !== null && presetInstall !== false) {
 				{
 					const mounted = presetProfileTarget(ctx);
 					const exclusion = installExclusionTarget(mounted === void 0 ? void 0 : {
@@ -2220,7 +2414,8 @@ function apply(ctx, rawConfig = {}) {
 				try {
 					const source = resolveAgentPresetDir(import.meta.url);
 					const table = readAgentPresetBases(source);
-					const requestedRaw = presetInstall[1] ?? table.defaultBase;
+					const baseFlag = presetInstall.flags.get("base");
+					const requestedRaw = typeof baseFlag === "string" ? baseFlag : table.defaultBase;
 					const requested = [...new Set(requestedRaw.split(",").map((part) => part.trim()).filter((part) => part !== ""))];
 					if (requested.length === 0) return err(`No agent-preset base named — ${join(source, "bases.json")} lists ${table.entries.map((entry) => entry.name).join(", ")}`);
 					const selected = [];
@@ -2234,45 +2429,51 @@ function apply(ctx, rawConfig = {}) {
 					const profile = presetProfileTarget(ctx);
 					if (profile === void 0) return err("No profile is mounted in this process, so there is no profile patch to write the preset row into — run the command in a session started by `dsh --profile <name>`.");
 					const delta = readFileSync(deltaPath, "utf8");
-					const current = existsSync(profile.patchPath) ? readFileSync(profile.patchPath, "utf8") : "";
-					let merged = current;
-					const written = [];
-					for (const base of selected) {
-						const refusal = baseRefusalReason(base, (name) => ctx.get(name) !== void 0);
-						if (refusal !== void 0) return err(refusal);
-						const basePatch = resolvePresetBasePatch(base.name, profile);
-						const rowId = presetRowId(base.id);
-						const entryText = composePresetEntry(readFileSync(basePatch, "utf8"), delta, {
-							rowId,
-							id: base.id,
-							name: base.display.name,
-							description: base.display.description,
-							order: base.display.order
+					const hmr = ctx.get("hmr");
+					const commit = () => {
+						const current = existsSync(profile.patchPath) ? readFileSync(profile.patchPath, "utf8") : "";
+						let merged = current;
+						const written = [];
+						for (const base of selected) {
+							const refusal = baseRefusalReason(base, (name) => ctx.get(name) !== void 0);
+							if (refusal !== void 0) return err(refusal);
+							const basePatch = resolvePresetBasePatch(base.name, profile);
+							const rowId = presetRowId(base.id);
+							const entryText = composePresetEntry(readFileSync(basePatch, "utf8"), delta, {
+								rowId,
+								id: base.id,
+								name: base.display.name,
+								description: base.display.description,
+								order: base.display.order
+							});
+							const next = mergePresetRow(merged, entryText, rowId);
+							written.push(next === merged ? `${base.name} → ${profile.patchPath} (already current)` : `${base.name} → ${rowId} in ${profile.patchPath}`);
+							merged = next;
+						}
+						if (merged !== current) atomicWriteFiles(dirname(profile.patchPath), [{
+							name: PROFILE_PATCH_FILENAME$1,
+							content: presetPatchText(merged)
+						}], void 0, (message) => {
+							ctx.logger.warn(message);
 						});
-						const next = mergePresetRow(merged, entryText, rowId);
-						written.push(next === merged ? `${base.name} → ${profile.patchPath} (already current)` : `${base.name} → ${rowId} in ${profile.patchPath}`);
-						merged = next;
-					}
-					if (merged !== current) atomicWriteFiles(dirname(profile.patchPath), [{
-						name: PROFILE_PATCH_FILENAME$1,
-						content: presetPatchText(merged)
-					}], void 0, (message) => {
-						ctx.logger.warn(message);
-					});
-					return ok(`Evolution agent preset row installed (${written.join("; ")}). Restart the session switcher to select it.`);
+						return ok(`Evolution agent preset row installed (${written.join("; ")}). Restart the session switcher to select it.`);
+					};
+					const runExclusive = hmr?.runExclusive;
+					if (runExclusive === void 0) return commit();
+					return await runExclusive.call(hmr, commit);
 				} catch (error) {
 					return err(`Preset install failed: ${error instanceof Error ? error.message : String(error)}`);
 				}
 			}
 			if (input.startsWith("restructure ")) {
-				const planTail = /\s--plan\s+(\S+)\s*$/.exec(rawInputTrimmed) ?? null;
-				const planRunId = planTail?.[1] ?? void 0;
-				const rest = planTail ? rawInputTrimmed.slice(0, planTail.index) : rawInputTrimmed;
-				const match = /^restructure\s+(\S+)\s+"([^"]+)"\s+(\S+)$/.exec(rest);
-				if (!match) return err("Usage: /evolution restructure <name> \"<## heading>\" <to_file>");
-				const name = match[1] ?? "";
-				const heading = match[2] ?? "";
-				const toFile = match[3] ?? "";
+				const restParsed = parseSubcommand(rawInputTrimmed);
+				if (isParseFailure(restParsed) || restParsed.name !== "restructure") return err("Usage: /evolution restructure <name> \"<## heading>\" <to_file>");
+				const name = restParsed.positionals[0] ?? "";
+				const heading = restParsed.positionals[1] ?? "";
+				const toFile = restParsed.positionals[2] ?? "";
+				if (name === "" || heading === "" || toFile === "") return err("Usage: /evolution restructure <name> \"<## heading>\" <to_file>");
+				const planFlag = restParsed.flags.get("plan");
+				const planRunId = typeof planFlag === "string" ? planFlag : void 0;
 				if (!toFile.startsWith("references/")) return err("to_file must live under references/ (log/detail destination).");
 				const ioRegistry = ctx.get("evolutionIo");
 				if (!ioRegistry) return err("Evolution IO registry not mounted — restructure unavailable.");
@@ -2308,7 +2509,7 @@ function apply(ctx, rawConfig = {}) {
 				}
 				const result = await newSkillLibrary({
 					config: { root: skillsRootValue },
-					io: ioRegistry.provider(),
+					io: preferProvider(ioRegistry, ["fs"]),
 					ctx,
 					threatExemptLabels: config.threatExemptLabels,
 					limits: {
@@ -2328,8 +2529,8 @@ function apply(ctx, rawConfig = {}) {
 				if (!replay) return err(errorText("e-303-replay-service-not-mounted"));
 				return ok(replay.compare().report);
 			}
-			const paramsMatch = /^params(?: --group ([a-z-]+))?(?: --json)?$/.exec(input);
-			if (paramsMatch) {
+			const paramsParsed = parseSubcommand(input);
+			if (!isParseFailure(paramsParsed) && paramsParsed.name === "params") {
 				const provider = ctx.get("settings");
 				const sections = /* @__PURE__ */ new Map();
 				if (provider?.describe !== void 0) try {
@@ -2344,21 +2545,23 @@ function apply(ctx, rawConfig = {}) {
 					return err(errorText("e-307-the-settings-service-could", { a1: error instanceof Error ? error.message : String(error) }));
 				}
 				const rows = paramSurfaceRows(sections, PARAM_EXPOSURE);
-				const group = paramsMatch[1];
+				const groupFlag = paramsParsed.flags.get("group");
+				const group = typeof groupFlag === "string" ? groupFlag : void 0;
 				const selected = group === void 0 ? rows : rows.filter((row) => row.group === group);
 				if (group !== void 0 && selected.length === 0) return err(errorText("e-308-unknown-parameter-group-group", {
 					a1: group,
 					a2: paramGroups(PARAM_EXPOSURE).join(", ")
 				}));
-				if (input.endsWith("--json")) return ok(renderParamJson(selected));
+				if (paramsParsed.flags.get("json") === true) return ok(renderParamJson(selected));
 				return ok(renderParamRows(selected, { providerMounted: provider !== void 0 }));
 			}
-			const policySetMatch = /^policy set ([A-Za-z][A-Za-z0-9.-]*) (.+?)(?: --expect (\d+))?$/.exec(input);
-			if (policySetMatch) {
+			const policyParsed = parseSubcommand(input);
+			if (isParseFailure(policyParsed) && policyParsed.name === "policy" && policyParsed.kind === "missing-value") return err("/evolution policy set needs a value after --" + (policyParsed.flag ?? "") + "; usage: policy set <id> <value> [--expect <revision>]");
+			if (!isParseFailure(policyParsed) && policyParsed.name === "policy" && policyParsed.positionals[0] === "set") {
 				const provider = ctx.get("settings");
 				if (provider?.update === void 0 || provider.describe === void 0) return err(errorText("e-311-no-settings-service-is"));
-				const rawId = policySetMatch[1] ?? "";
-				const rawValue = policySetMatch[2] ?? "";
+				const rawId = policyParsed.positionals[1] ?? "";
+				const rawValue = policyParsed.positionals[2] ?? "";
 				let id;
 				try {
 					id = canonicalWriteId(rawId);
@@ -2389,13 +2592,24 @@ function apply(ctx, rawConfig = {}) {
 				}));
 				const current = descriptor.value;
 				const resolved = typeof current === "object" && current !== null ? current : void 0;
-				const expectedRaw = policySetMatch[3];
+				const expectFlag = policyParsed.flags.get("expect");
+				const expectedRaw = typeof expectFlag === "string" ? expectFlag : void 0;
 				const expected = expectedRaw === void 0 ? descriptor.revision : Number(expectedRaw);
 				if (expectedRaw !== void 0 && descriptor.revision !== void 0 && Number(expectedRaw) !== descriptor.revision) return err(errorText("e-309-revision-conflict-you-sent", {
 					a1: expectedRaw,
 					a2: descriptor.revision
 				}));
 				const value = parseParamValue(rawValue);
+				const floorId = entry.relation?.atLeast;
+				if (floorId !== void 0 && typeof value === "number") {
+					const sibling = resolved?.[floorId];
+					const floor = typeof sibling === "number" ? sibling : NaN;
+					if (Number.isFinite(floor) && value < floor) return err(errorText("e-322-a-parameter-would-break-a", {
+						a1: id,
+						a2: String(floor),
+						a3: String(value)
+					}));
+				}
 				try {
 					await provider.update(namespace, { [id]: value }, expected);
 				} catch (error) {
@@ -2443,7 +2657,6 @@ function apply(ctx, rawConfig = {}) {
 		const evolutionCommand = {
 			name: "evolution",
 			description: "自进化：状态与待批准写入",
-			recordInput: false,
 			input: { hint: renderHint() },
 			handler: (invocation) => commandBody.run(invocation).catch((error) => ({
 				kind: "error",
@@ -2558,121 +2771,6 @@ function resolveAgentPresetDir(importMetaUrl) {
 		return overlayCandidate;
 	}
 }
-const defaultFs = {
-	writeFileSync: (path, data) => {
-		writeFileSync(path, data);
-	},
-	existsSync: (path) => existsSync(path),
-	copyFileSync: (from, to) => {
-		copyFileSync(from, to);
-	},
-	renameSync: (from, to) => {
-		renameSync(from, to);
-	},
-	rmSync: (path, options) => {
-		rmSync(path, options);
-	},
-	mtime: (path) => {
-		try {
-			return statSync(path).mtimeMs;
-		} catch (error) {
-			if (isMissingPath(error)) return null;
-			throw error;
-		}
-	}
-};
-/**
-* S6.3 (E-40): atomically replace a set of files within one directory.
-* Each file is staged to a sibling `<name>.tmp`, then renamed into place
-* (atomic on the same filesystem); a pre-existing file keeps a single
-* `<name>.bak`. A failure at ANY staging step removes the staged temps and
-* leaves the previous files untouched — a half-written target is impossible
-* up to the staging and backup phases.
-*
-* F-211: the rename COMMIT phase does not carry the same guarantee. When a
-* filesystem refuses to overwrite the destination, the code removes it and
-* retries the rename; if the retry ALSO fails the destination is gone. The
-* single `.bak` created above still holds the previous content, so the target
-* is restored from it (best-effort) before the original rename error is
-* rethrown, so a failed commit never leaves the file missing.
-*
-* V4-17: the `.bak` is refreshed to the committed content after every
-* successful commit, so a later failed commit always recovers to the most
-* recent good generation (a once-at-first-install `.bak` could otherwise
-* restore content several installs old). The recovery error names the `.bak`
-* source (and mtime when available) so the caller knows the generation it
-* restored from.
-*/
-function atomicWriteFiles(targetDir, writes, fs = defaultFs, logger = console.warn) {
-	const stage = (name) => join(targetDir, `${name}.tmp`);
-	const dupes = [...new Set(writes.map((write) => write.name).filter((name, index, all) => all.indexOf(name) !== index))];
-	if (dupes.length > 0) throw new Error(`atomicWriteFiles: duplicate input names: ${dupes.join(", ")}`);
-	try {
-		for (const { name, content } of writes) fs.writeFileSync(stage(name), content);
-		for (const { name } of writes) {
-			const finalPath = join(targetDir, name);
-			const bakPath = join(targetDir, `${name}.bak`);
-			if (fs.existsSync(finalPath) && !fs.existsSync(bakPath)) fs.copyFileSync(finalPath, bakPath);
-		}
-		const committed = [];
-		for (const { name } of writes) {
-			const finalPath = join(targetDir, name);
-			const bakPath = join(targetDir, `${name}.bak`);
-			const tmp = stage(name);
-			try {
-				fs.renameSync(tmp, finalPath);
-				committed.push(name);
-			} catch {
-				try {
-					fs.rmSync(finalPath, { force: true });
-				} catch (removeError) {
-					const already = committed.length > 0 ? `; already committed: ${committed.join(", ")}` : "";
-					throw new Error(`atomicWriteFiles: could not remove "${name}" to replace it (${removeError instanceof Error ? removeError.message : String(removeError)})${already}`);
-				}
-				try {
-					fs.renameSync(tmp, finalPath);
-					committed.push(name);
-				} catch (renameError) {
-					const already = committed.length > 0 ? `; already committed: ${committed.join(", ")}` : "";
-					if (fs.existsSync(bakPath)) {
-						try {
-							fs.copyFileSync(bakPath, finalPath);
-						} catch {
-							throw new Error(`atomicWriteFiles: "${name}" was removed but recovery from ${bakPath} failed (${renameError instanceof Error ? renameError.message : String(renameError)}); verify the file manually${already}`);
-						}
-						const bakMtime = fs.mtime?.(bakPath);
-						const when = bakMtime !== null && bakMtime !== void 0 && Number.isFinite(bakMtime) ? ` (bak mtime ${new Date(bakMtime).toISOString()})` : "";
-						throw new Error(`atomicWriteFiles: "${name}" was removed during commit and restored from the last good generation ${bakPath}${when}; original error: ${renameError instanceof Error ? renameError.message : String(renameError)}${already}`);
-					}
-					throw new Error(`${renameError instanceof Error ? renameError.message : String(renameError)}${already}`);
-				}
-			}
-		}
-		for (const { name } of writes) {
-			const finalPath = join(targetDir, name);
-			try {
-				if (fs.existsSync(finalPath)) fs.copyFileSync(finalPath, join(targetDir, `${name}.bak`));
-			} catch (refreshError) {
-				logger(`atomicWriteFiles: committed "${name}" but failed to refresh its .bak (${refreshError instanceof Error ? refreshError.message : String(refreshError)}); a later failed commit will recover to an OLDER generation`);
-			}
-		}
-	} catch (error) {
-		const cleanupFailures = [];
-		for (const { name } of writes) try {
-			fs.rmSync(stage(name), {
-				force: true,
-				recursive: true
-			});
-		} catch (cleanupError) {
-			cleanupFailures.push(`${name}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
-		}
-		if (cleanupFailures.length > 0) {
-			const original = error instanceof Error ? error.message : String(error);
-			throw new Error(`${original} (staged-temp cleanup also failed: ${cleanupFailures.join("; ")})`);
-		}
-		throw error;
-	}
-}
 /** F-328: render staged args for `pending --detail`, truncated to 500 chars.
 * args may be non-JSON (a tool produced garbage), so the render is fail-safe.
 * V4-19: a truncation is marked with `…(truncated N chars)` so the operator is

package/lib/types/index.d.ts

@@ -12,6 +12,8 @@ declare module '@deepseek-ai/dsh-llm' {
         } & ContextFormed;
     }
 }
+import { atomicWriteFiles } from '@lmzhen/dsh-evolution-core';
+export { atomicWriteFiles };
 export declare const name = "evolution-commands";
 export interface Config {
     /** Skill-tree root for maintain/restructure; empty uses the default tree.
@@ -71,46 +73,4 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     threatExemptLabels: z<string[], string[], "defined">;
 }>>, "plain">;
 export declare function apply(ctx: Context, rawConfig?: Config): void;
-/** F-211: the fs surface atomicWriteFiles uses — injectable so the commit-phase
- * rename-failure path is deterministically testable. Defaults to node:fs.
- * `mtime` (optional) probes a path's last-write time so the failed-commit
- * recovery message can name the generation it restored from. */
-interface FsOps {
-    writeFileSync(path: string, data: string | Uint8Array): void;
-    existsSync(path: string): boolean;
-    copyFileSync(from: string, to: string): void;
-    renameSync(from: string, to: string): void;
-    rmSync(path: string, options?: {
-        force?: boolean;
-        recursive?: boolean;
-    }): void;
-    mtime?(path: string): number | null;
-}
-/**
- * S6.3 (E-40): atomically replace a set of files within one directory.
- * Each file is staged to a sibling `<name>.tmp`, then renamed into place
- * (atomic on the same filesystem); a pre-existing file keeps a single
- * `<name>.bak`. A failure at ANY staging step removes the staged temps and
- * leaves the previous files untouched — a half-written target is impossible
- * up to the staging and backup phases.
- *
- * F-211: the rename COMMIT phase does not carry the same guarantee. When a
- * filesystem refuses to overwrite the destination, the code removes it and
- * retries the rename; if the retry ALSO fails the destination is gone. The
- * single `.bak` created above still holds the previous content, so the target
- * is restored from it (best-effort) before the original rename error is
- * rethrown, so a failed commit never leaves the file missing.
- *
- * V4-17: the `.bak` is refreshed to the committed content after every
- * successful commit, so a later failed commit always recovers to the most
- * recent good generation (a once-at-first-install `.bak` could otherwise
- * restore content several installs old). The recovery error names the `.bak`
- * source (and mtime when available) so the caller knows the generation it
- * restored from.
- */
-export declare function atomicWriteFiles(targetDir: string, writes: Array<{
-    name: string;
-    content: string | Uint8Array;
-}>, fs?: FsOps, logger?: (message: string) => void): void;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/types/parse.d.ts

@@ -0,0 +1,65 @@
+/**
+ * F-4/G7.4 (C7): the ONE parser for the /evolution command surface.
+ *
+ * The surface used to answer each subcommand with its own regex (`^params(?: --group ([a-z-]+))?(?: --json)?$`
+ * and nine siblings), so `params --json --group review` and `params --group=review` were refused as
+ * "not a subcommand", while a sibling regex accepted `=` — and a mistyped group name degraded into the
+ * generic error instead of the one that lists the known groups.
+ *
+ * This parser is order- and `=`-tolerant, matches the subcommand name case-insensitively, keeps a flag
+ * VALUE's case intact (the domain layer is the one that validates it), and answers a SYNTAX failure when a
+ * declared value flag is left without its value (F-3: `policy set a.b --expect 3` must not read
+ * `--expect 3` as the value).
+ *
+ * @module @lmzhen/dsh-evolution-commands/parse
+ */
+/** The flags whose declared form takes a value (`--group <name>`, `--expect <revision>`, …). */
+/**
+ * Exported so the command-table gate can tie it to the table's usage lines (P2: two declarations of
+ * "which flags take a value" would otherwise be free to drift apart).
+ */
+export declare const VALUE_FLAGS: readonly string[];
+/** One parsed command line. */
+export interface ParsedCommand {
+    /** The subcommand name, lower-cased (the table stores it lower-case too). */
+    readonly name: string;
+    /** Declared flags: a value when the flag takes one, `true` when it is bare. */
+    readonly flags: ReadonlyMap<string, string | true>;
+    /** Everything that was neither the name nor a flag, in order. */
+    readonly positionals: readonly string[];
+}
+/** A SYNTAX failure — the caller answers it as a usage error, never as a domain error. */
+export interface ParseFailure {
+    /** Which syntax rule was broken. */
+    readonly kind: 'unknown-subcommand' | 'unknown-flag' | 'missing-value';
+    /** The subcommand name the caller saw (empty when the line was empty). */
+    readonly name: string;
+    /** The flag involved, for the two flag failures. */
+    readonly flag?: string;
+}
+/**
+ * Narrow a parse result: true when it is the syntax failure rather than a command.
+ * @param result - what {@link parseSubcommand} answered.
+ * @returns whether the line was refused.
+ */
+export declare function isParseFailure(result: ParsedCommand | ParseFailure): result is ParseFailure;
+/**
+ * Read one SUB-FORM line: `maintain status`, `maintain report`, … — the shape the regexes used to own.
+ *
+ * A sub-form matches only when: the line parses, the name matches, the first positional is the sub-form,
+ * and every flag the line carries is DECLARED by the table (an undeclared flag keeps the old
+ * "unknown arguments" answer instead of silently becoming a bare flag).
+ * @param input - the text after `/evolution`.
+ * @param name - the subcommand name the table declares (e.g. `maintain`).
+ * @param sub - the sub-form word (e.g. `status`).
+ * @param declaredFlags - the flags the table declares for `name` (`flagsOf(name)`).
+ * @returns the parsed command, or null when this line is not that sub-form.
+ */
+export declare function subcommandOf(input: string, name: string, sub: string, declaredFlags: readonly string[]): ParsedCommand | null;
+/**
+ * Parse one command line into its name, flags and positionals.
+ * @param input - the text after `/evolution`.
+ * @returns the parsed command, or the syntax failure that refused it.
+ */
+export declare function parseSubcommand(input: string): ParsedCommand | ParseFailure;
+//# sourceMappingURL=parse.d.ts.map

package/lib/types/registry.d.ts

@@ -12,9 +12,17 @@
 export interface CommandEntry {
     /** The subcommand as typed after `/evolution`. Variants use `|` (curator run|pause). */
     usage: string;
+    /** C7: true when the subcommand only READS (no skill/param write). Stored: not derivable. */
+    readonly: boolean;
     /** One-line purpose rendered in the help output. */
     summary: string;
 }
+/** The flags the TABLE declares for one subcommand (name → `--flag`), DERIVED from its usage. */
+export declare function flagsOf(name: string): string[];
+/** C7 shape, DERIVED: the subcommand name is the first token of `usage` (variants use `|`). */
+export declare function entryName(entry: CommandEntry): string;
+/** C7 shape, DERIVED: the flags a `usage` declares, in the form `--flag` (value flags keep their name). */
+export declare function entryFlags(entry: CommandEntry): string[];
 export declare const COMMAND_ENTRIES: CommandEntry[];
 /** The input-declaration hint (single line, ` | `-separated). */
 export declare function renderHint(): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,17 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@lmzhen/dsh-evolution-approval": "^0.22.0",
-    "@lmzhen/dsh-evolution-core": "^0.22.0",
-    "@lmzhen/dsh-evolution-maintenance": "^0.22.0"
+    "@lmzhen/dsh-evolution-approval": "^0.23.0",
+    "@lmzhen/dsh-evolution-core": "^0.23.0",
+    "@lmzhen/dsh-evolution-maintenance": "^0.23.0"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.22.0"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.23.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-commands": "^0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1"
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.1",
+    "@lmzhen/dsh-evolution-io": "^0.23.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-commands": "^0.2.0-rc.1"