@lmzhen/dsh-evolution-core 0.25.8 → 0.25.9

package/README.md

@@ -95,3 +95,10 @@ consumer — so the `@mode` target stays at six (decision 10, provisional: keep)
 | `E-322` | a cross-field parameter constraint would be broken (the field, its floor and the attempted value are included) | raise the value to the named floor, or lower the sibling first |
 | `E-319` | the confirmation before a create or bare delete went unanswered for `skillWriteConfirmTimeoutSeconds` (`skillWriteConfirm: 'timeout'`), so the write was cancelled | set `skillWriteConfirm` to `auto` (write without asking), keep `ask` (wait until answered), or raise the timeout |
 Symptom → next step; the exact text of every code (`E-301`–`E-322`) is stored once in
+
+## 单元与撤销（本包负责的契约）
+
+- 本包持有单元契约的**类型与折叠**：SkillVersion.unitHead 两形态互斥（代表片 { moves, sources }／路标 { skill }），判别式固定为 moves !== undefined；读端折叠必须带上新字段，否则下一次写就丢。
+- 成员解析与孤路标判定在 src/unit-members.ts：candidateSkills（代表片首位、去重保序）、resolveUnitMembersFromIndexes（只按已知 key、三向校验）、landmarkVerdict 与 staleRouteStubs（可跳 ⟺ 目标存在 ∧ 其索引仍持该 unitId；输出按 skill/version/owner 确定性排序）。
+- 写作端的硬规则：kind 判 previous === null（不是 undefined）；path 抄循环里既有的 rel；同一目标写两次时清单保留最后一次写入的 afterRef。
+- 面向读者的完整说明见仓库 docs/units-and-undo.md。

package/lib/index.js

@@ -577,6 +577,34 @@ const MEMORY_GUIDANCE_SECTION_ORDER = 11e3;
 /** Order of the `evolution-skills-guidance` section (last of the two). */
 const SKILLS_GUIDANCE_SECTION_ORDER = 11100;
 //#endregion
+//#region lib/types/guards.js
+/**
+* The family's plain-object predicate, in ONE place (v46 G7.1 / audit A8).
+*
+* The audit found the same guard — "a non-null object that is not an array" — rewritten fifteen
+* times across nine packages, four times inside core itself, and with two byte-identical `asRecord`
+* copies in evolution-policy and evolution-threat. This module is the single definition; callers
+* import it instead of spelling the clause again.
+*
+* @module @lmzhen/dsh-evolution-core
+*/
+/**
+* Is this a non-null, non-array object (what JSON calls an object)?
+* @param value - the value to test.
+* @returns whether it is a plain object.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Read a value as a record, or undefined when it is not one.
+* @param value - the value to read.
+* @returns the value typed as a record, or undefined.
+*/
+function asRecord(value) {
+	return isRecord(value) ? value : void 0;
+}
+//#endregion
 //#region lib/types/limits.js
 /**
 * Skill content limits: the byte/char budgets every write path validates against.
@@ -766,6 +794,7 @@ function strictFrontmatterValues(block) {
 	if (typeof loaded !== "object" || Array.isArray(loaded)) return null;
 	const values = /* @__PURE__ */ new Map();
 	const split = [];
+	let metadata;
 	for (const [key, value] of Object.entries(loaded)) {
 		if (typeof value !== "string" && PLATFORM_STRING_FIELDS.includes(key)) split.push({
 			key,
@@ -783,10 +812,15 @@ function strictFrontmatterValues(block) {
 			values.set(key, `[${value.map((item) => String(item)).join(", ")}]`);
 			continue;
 		}
+		if (key === "metadata" && isRecord(value)) {
+			metadata = value;
+			continue;
+		}
 	}
 	return {
 		values,
-		split
+		split,
+		metadata
 	};
 }
 /**
@@ -858,7 +892,8 @@ function readFrontmatterBlock(content) {
 		body,
 		unsafeValues: unsafeFrontmatterEntries(found.block),
 		strictFailed: strict === null,
-		platformStringSplit: strict?.split ?? []
+		platformStringSplit: strict?.split ?? [],
+		metadata: strict?.metadata
 	};
 }
 /**
@@ -878,6 +913,7 @@ function parseFrontmatter(content) {
 		frontmatter: read.frontmatter,
 		body: read.body,
 		unsafeValues: read.unsafeValues,
+		metadata: read.metadata,
 		catalogInvalid: read.strictFailed || read.unsafeValues.length > 0 || read.platformStringSplit.length > 0,
 		platformStringSplit: read.platformStringSplit
 	};
@@ -1028,7 +1064,10 @@ function normalizeFrontmatter(content) {
 function relatedSkillNames(content, exclude) {
 	const parsed = parseFrontmatter(content);
 	if (!parsed) return [];
-	const raw = parsed.frontmatter["related_skills"];
+	const nestedHost = parsed.metadata?.["hermes"];
+	const nestedRaw = isRecord(nestedHost) ? nestedHost["related_skills"] : void 0;
+	const flat = parsed.frontmatter["related_skills"];
+	const raw = typeof flat === "string" ? flat : Array.isArray(nestedRaw) ? `[${nestedRaw.map((item) => String(item)).join(", ")}]` : void 0;
 	if (typeof raw !== "string") return [];
 	const names = /* @__PURE__ */ new Set();
 	for (const match of Array.from(raw.matchAll(/(?<![A-Za-z0-9_-])[a-z0-9][a-z0-9-]*(?![A-Za-z0-9_-])/g))) {
@@ -1371,34 +1410,6 @@ function admissionVerdict(baseline, ruleId, thresholds = DEFAULT_ADMISSION) {
 	};
 }
 //#endregion
-//#region lib/types/guards.js
-/**
-* The family's plain-object predicate, in ONE place (v46 G7.1 / audit A8).
-*
-* The audit found the same guard — "a non-null object that is not an array" — rewritten fifteen
-* times across nine packages, four times inside core itself, and with two byte-identical `asRecord`
-* copies in evolution-policy and evolution-threat. This module is the single definition; callers
-* import it instead of spelling the clause again.
-*
-* @module @lmzhen/dsh-evolution-core
-*/
-/**
-* Is this a non-null, non-array object (what JSON calls an object)?
-* @param value - the value to test.
-* @returns whether it is a plain object.
-*/
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/**
-* Read a value as a record, or undefined when it is not one.
-* @param value - the value to read.
-* @returns the value typed as a record, or undefined.
-*/
-function asRecord(value) {
-	return isRecord(value) ? value : void 0;
-}
-//#endregion
 //#region lib/types/probe.js
 function probePresent(value) {
 	return {
@@ -2491,6 +2502,7 @@ function renderCuratorReportMarkdown(report) {
 		...report.aborted === void 0 ? [] : [`- **Aborted**: ${report.aborted}`],
 		...report.unattributed === void 0 || report.unattributed.length === 0 ? [] : [`- **Unattributed errors**: ${report.unattributed.length}`],
 		...report.snapshotPath === void 0 ? [] : [`- **Snapshot**: ${report.snapshotPath}`],
+		...report.routeStubs === void 0 ? [] : [`- **Stale route stubs**: ${report.routeStubs.stubs}`],
 		...report.llmReviewEnabled === void 0 ? [] : [`- **llmReview**: ${report.llmReviewEnabled}`],
 		...report.wouldPrune === void 0 ? [] : [report.wouldPrune === null ? "- **Would prune (archiveRetention=report)**: unknown (archive listing unreadable)" : `- **Would prune (archiveRetention=report)**: ${report.wouldPrune.length}`],
 		...report.nominationsWarnings === void 0 || report.nominationsWarnings.length === 0 ? [] : [`- **Nomination warnings**: ${report.nominationsWarnings.join("; ")}`]
@@ -2506,6 +2518,7 @@ function renderCuratorReportMarkdown(report) {
 		...section("Archived", report.archived.map((item) => `${item.name} (${item.reason})`)),
 		...section("Failed", report.failed.map((item) => `${item.name}: ${item.reason}`)),
 		...section("Unattributed", report.unattributed ?? []),
+		...section("Stale route stubs", (report.routeStubs?.detail ?? []).map((stub) => stub.skill + " v" + String(stub.v) + " -> " + stub.owner + " (" + stub.reason + ")")),
 		...section("Stale candidates", report.staleCandidates),
 		...section("LLM nominations", report.llmNominations),
 		...section("Retention (kept, not deleted)", report.wouldPrune ?? []),
@@ -8717,6 +8730,8 @@ function readVersionEntry(entry) {
 	if (typeof candidate.chars !== "number") return null;
 	const summary = typeof candidate.summary === "string" && candidate.summary !== "" ? candidate.summary : void 0;
 	const path = typeof candidate.path === "string" && candidate.path !== "" ? candidate.path : void 0;
+	const unitId = typeof candidate.unitId === "string" && candidate.unitId !== "" ? candidate.unitId : void 0;
+	const unitHead = candidate.unitHead;
 	const base = {
 		v: candidate.v,
 		at: candidate.at,
@@ -8724,7 +8739,9 @@ function readVersionEntry(entry) {
 		hash: candidate.hash,
 		chars: candidate.chars,
 		...summary === void 0 ? {} : { summary },
-		...path === void 0 ? {} : { path }
+		...path === void 0 ? {} : { path },
+		...unitId === void 0 ? {} : { unitId },
+		...unitHead === void 0 ? {} : { unitHead }
 	};
 	return typeof candidate.beforeHash === "string" && candidate.beforeHash !== "" ? {
 		...base,
@@ -8796,11 +8813,14 @@ function nextHistoryIndex(versions, input, keep) {
 		action: BASELINE_ACTION,
 		hash: beforeHash,
 		chars: input.before?.length ?? 0,
-		...pathField
+		...pathField,
+		...input.unitId === void 0 ? {} : { unitId: input.unitId }
 	});
 	const removalHash = afterHash === null ? beforeHash : null;
 	if (afterHash !== null) {
 		if (grown[grown.length - 1]?.hash !== afterHash) grown.push({
+			...input.unitId === void 0 ? {} : { unitId: input.unitId },
+			...input.unitHead === void 0 ? {} : { unitHead: input.unitHead },
 			v: nextVersion(grown),
 			at: input.at,
 			action: input.action,
@@ -8820,10 +8840,39 @@ function nextHistoryIndex(versions, input, keep) {
 			hash: removalHash,
 			chars: input.before?.length ?? 0,
 			...pathField,
+			...input.unitId === void 0 ? {} : { unitId: input.unitId },
+			...input.unitHead === void 0 ? {} : { unitHead: input.unitHead },
 			...input.summary === void 0 ? {} : { summary: input.summary }
 		});
 	}
-	const trimmed = grown.slice(Math.max(0, grown.length - clampKeep(keep)));
+	const budget = clampKeep(keep);
+	const groups = [];
+	const byUnit = /* @__PURE__ */ new Map();
+	for (const entry of grown) {
+		const unit = entry.unitId;
+		if (unit === void 0) {
+			groups.push([entry]);
+			continue;
+		}
+		const found = byUnit.get(unit);
+		if (found !== void 0) {
+			found.push(entry);
+			continue;
+		}
+		const made = [entry];
+		byUnit.set(unit, made);
+		groups.push(made);
+	}
+	const keptIndexes = /* @__PURE__ */ new Set();
+	let keptCount = 0;
+	for (let i = groups.length - 1; i >= 0; i -= 1) {
+		const group = groups[i];
+		if (group === void 0) continue;
+		if (keptCount > 0 && keptCount + group.length > budget) break;
+		for (const entry of group) keptIndexes.add(grown.indexOf(entry));
+		keptCount += group.length;
+	}
+	const trimmed = grown.filter((_, index) => keptIndexes.has(index));
 	const recorded = {};
 	if (beforeHash !== null) {
 		const v = lastVersionOf(trimmed, beforeHash);
@@ -9133,6 +9182,141 @@ function elapsedSince(at, nowMs) {
 	};
 }
 //#endregion
+//#region lib/types/unit-members.js
+/** Candidate skills: head first, then `sources[]` order, DEDUPLICATED (sources may name the head). */
+function candidateSkills(head) {
+	const out = [head.skill];
+	for (const source of head.sources) if (!out.includes(source.skill)) out.push(source.skill);
+	return out;
+}
+/** @param indexes - skill name -> that skill's index text, or null when the index file is absent. */
+/** The `path` of one manifest move, or the empty string when the record carries no string one.
+*  Kept as a function so the read never stringifies an object (the linter refuses
+*  `String(unknown)` for exactly that reason) and every call site reads the same way. */
+function movePath(move) {
+	const raw = move.path;
+	return typeof raw === "string" ? raw : "";
+}
+function resolveUnitMembersFromIndexes(head, indexes, readEntries) {
+	const members = [];
+	const missing = [];
+	for (const skill of candidateSkills(head)) {
+		const text = indexes.get(skill);
+		if (text === void 0 || text === null) {
+			missing.push({
+				skill,
+				reason: "index-absent"
+			});
+			continue;
+		}
+		const entries = readEntries(text).filter((entry) => entry.unitId === head.unitId);
+		if (entries.length === 0) {
+			missing.push({
+				skill,
+				reason: "unit-absent"
+			});
+			continue;
+		}
+		members.push({
+			skill,
+			entries
+		});
+	}
+	const conflicts = [];
+	const manifest = head.unitHead?.moves ?? void 0;
+	if (manifest !== void 0) {
+		const shardPaths = [];
+		for (const slice of members) for (const entry of slice.entries) for (const move of entry.unitHead?.moves ?? []) {
+			const path = movePath(move);
+			if (path !== "") shardPaths.push(path);
+		}
+		const wanted = manifest.map((move) => movePath(move)).filter((p) => p !== "");
+		for (const path of wanted) if (!shardPaths.includes(path)) conflicts.push({
+			kind: "missing",
+			path
+		});
+		for (const path of shardPaths) if (!wanted.includes(path)) conflicts.push({
+			kind: "foreign",
+			path
+		});
+		for (const path of wanted) if (shardPaths.filter((p) => p === path).length > 1) conflicts.push({
+			kind: "duplicated",
+			path
+		});
+	}
+	return {
+		members,
+		missing,
+		conflicts
+	};
+}
+/** A unit's members are trustworthy only when nothing is missing and nothing conflicts. */
+function unitMembersAreComplete(members) {
+	return members.missing.length === 0 && members.conflicts.length === 0;
+}
+/**
+* The io shell (A19.2): open ONLY the known keys -- never enumerate a directory. A skill whose index
+* file is unreadable becomes `null` (index-absent), which the core then reports by name.
+*/
+async function resolveUnitMembers(root, io, head, indexPath, readEntries) {
+	const indexes = /* @__PURE__ */ new Map();
+	for (const skill of candidateSkills(head)) {
+		let text = null;
+		try {
+			text = await io.readText(indexPath(root, skill));
+		} catch {
+			text = null;
+		}
+		indexes.set(skill, text);
+	}
+	return resolveUnitMembersFromIndexes(head, indexes, (raw) => readEntries(raw));
+}
+/** G3b: a LANDMARK carries the owning skill and no manifest (the two forms never coexist). */
+function isLandmark(entry) {
+	const head = entry.unitHead;
+	return head !== void 0 && head.moves === void 0 && head.skill !== void 0;
+}
+/** @param entry - the entry being judged. @param ownerEntries - the owner skill's index, or null when
+* the owner has no readable index. */
+function landmarkVerdict(entry, ownerEntries) {
+	const head = entry.unitHead;
+	if ((isLandmark(entry) ? head?.skill : void 0) === void 0 || entry.unitId === void 0) return {
+		jumpable: false,
+		reason: "not-a-landmark"
+	};
+	if (ownerEntries === null) return {
+		jumpable: false,
+		reason: "owner-absent"
+	};
+	return ownerEntries.some((candidate) => candidate.unitId === entry.unitId) ? { jumpable: true } : {
+		jumpable: false,
+		reason: "unit-absent"
+	};
+}
+/**
+* Scan a whole corpus (skill name -> index entries, or null when unreadable) for stale route stubs.
+* Sorted by (skill, version, owner): a function of the corpus, not of the caller's map order.
+*/
+function staleRouteStubs(indexes) {
+	const out = [];
+	for (const [skill, entries] of indexes) {
+		if (entries === null) continue;
+		for (const entry of entries) {
+			const head = entry.unitHead;
+			const owner = isLandmark(entry) ? head?.skill : void 0;
+			if (owner === void 0) continue;
+			const verdict = landmarkVerdict(entry, indexes.get(owner) ?? null);
+			if (!verdict.jumpable && verdict.reason !== "not-a-landmark") out.push({
+				skill,
+				v: entry.v,
+				owner,
+				reason: verdict.reason
+			});
+		}
+	}
+	return out.sort((a, b) => a.skill.localeCompare(b.skill) || a.v - b.v || a.owner.localeCompare(b.owner));
+}
+//#endregion
 //#region lib/types/skill-store.js
 /**
 * Skill library management for the self-evolution plugin.
@@ -9206,6 +9390,7 @@ function pointerBlock(rel, sectionText) {
 function collisionsNote(collisions) {
 	return collisions.length === 0 ? "" : ` collisions: ${collisions.slice(0, 5).join(", ")}`;
 }
+let nextUnitSeq = 0;
 /**
 * Evaluate a stage-time anchor against the bytes a locked read observed.
 * @param anchor - the caller's anchor, or `undefined` for an unanchored write.
@@ -10005,7 +10190,7 @@ var SkillLibrary = class {
 	* mutation ledger that points at it. The history failure is not silent — a deployment whose
 	* history stopped growing is a degradation worth seeing once (the ledger keeps hashes either
 	* way). */
-	async audit(skillName, action, before, after, summary, path, origin) {
+	async audit(skillName, action, before, after, summary, path, unitId, unitHead, origin) {
 		const at = (/* @__PURE__ */ new Date()).toISOString();
 		let versions = null;
 		try {
@@ -10016,7 +10201,9 @@ var SkillLibrary = class {
 				before,
 				after,
 				at,
-				...path === void 0 ? {} : { path }
+				...path === void 0 ? {} : { path },
+				...unitId === void 0 ? {} : { unitId },
+				...unitHead === void 0 ? {} : { unitHead }
 			};
 			versions = await recordVersions(this.root, this.io, input, keep);
 		} catch (error) {
@@ -11077,8 +11264,7 @@ var SkillLibrary = class {
 			message: badName
 		};
 		const dir = this.dirOf(name);
-		const md = await this.io.readText(join(dir, "SKILL.md"));
-		if (!md) return {
+		if (!await this.io.readText(join(dir, "SKILL.md"))) return {
 			ok: false,
 			message: `技能「${name}」不存在。`
 		};
@@ -11162,10 +11348,26 @@ var SkillLibrary = class {
 				message: `目录树变更失败：${reason}。回滚无法恢复 ${stuck.join(", ")}：请从 .backups 快照恢复这些目标（或重新应用这次变更）。`
 			};
 		}
-		const skillMdWrite = landing.find((entry) => entry.target.split(/[\\/]/).pop() === "SKILL.md");
-		const auditedBefore = skillMdWrite === void 0 ? md : skillMdWrite.previous;
-		const auditedAfter = skillMdWrite === void 0 ? md : skillMdWrite.content;
-		await this.audit(name, plan.auditAction, auditedBefore, auditedAfter, plan.auditSummary, void 0, plan.origin);
+		const unitId = plan.unitId ?? "u-" + Date.now().toString(36) + "-" + (nextUnitSeq += 1).toString(36);
+		for (const land of landing) {
+			const rel = land.target.split(/[\\/]/).pop() === "SKILL.md" ? void 0 : land.target.slice(dir.length + 1).split("\\").join("/");
+			const unitHead = land === landing[0] ? {
+				moves: landing.filter((l) => l.target.split(/[\\/]/).pop() !== "SKILL.md").map((l) => {
+					const p = l.target.slice(dir.length + 1).split(String.fromCharCode(92)).join(String.fromCharCode(47));
+					return {
+						path: p,
+						kind: l.previous === null ? "created" : "moved",
+						to: p,
+						...l.previous === null ? {} : { beforeRef: contentHash(l.previous) },
+						afterRef: contentHash(l.content)
+					};
+				}).filter((m, idx, all) => all.map((x) => x.path).lastIndexOf(m.path) === idx),
+				sources: [{ skill: name }]
+			} : void 0;
+			const auditedBefore = land.previous;
+			const auditedAfter = land.content;
+			await this.audit(name, plan.auditAction, auditedBefore, auditedAfter, plan.auditSummary, rel, unitId, unitHead, plan.origin);
+		}
 		this.notifyMutation({
 			action: plan.eventAction,
 			name,
@@ -11366,11 +11568,11 @@ var SkillLibrary = class {
 			};
 		}, anchor !== void 0 ? () => anchorUnverifiable(name, filePath) : (error) => unreadableTarget(name + "/" + filePath, error));
 	}
-	async removeSupportFile(rawName, filePath, origin = "foreground", anchor) {
+	async removeSupportFile(rawName, filePath, origin = "foreground", anchor, unitId) {
 		const name = rawName.trim();
-		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin, anchor));
+		return await this.serial(() => this.removeSupportFileCore(name, filePath, origin, anchor, unitId));
 	}
-	async removeSupportFileCore(name, filePath, origin, anchor) {
+	async removeSupportFileCore(name, filePath, origin, anchor, unitId) {
 		const badName = this.badName(name);
 		if (badName) return {
 			ok: false,
@@ -11424,7 +11626,7 @@ var SkillLibrary = class {
 			};
 		} else if (verdict === "match") await this.io.remove(target);
 		if (verdict !== "match") return anchorRefusalFile(name, filePath, verdict);
-		await this.audit(name, "remove_file", lockedBefore, null, `removed ${filePath}`, filePath);
+		await this.audit(name, "remove_file", lockedBefore, null, `removed ${filePath}`, filePath, unitId);
 		this.notifyMutation({
 			action: "remove_file",
 			name,
@@ -13759,4 +13961,4 @@ function foldUntrustedLines(text, limit) {
 	return limit > 0 ? marked.slice(0, limit) : marked;
 }
 //#endregion
-export { AGENT_PRESET_PACKAGE, AGENT_PRESET_ROOT_HINT, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, BASELINE_ACTION, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEDUP_MAX_PAIR_COMPARISONS, DEDUP_SIMILARITY_THRESHOLD, DEFAULT_ADMISSION, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, 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_PROBE_TIMEOUT_MS, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_RUN_RECORDS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_PATCH_SEED, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, FUZZY_MAX_PATTERN_CHARS, FUZZY_MAX_WORK, HEALTH_STAMP_RE, HISTORY_DIR, HISTORY_INDEX_VERSION, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LONG_RUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_REQUEST_BODY_BYTES, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NAMESPACE_MIGRATIONS, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, PLATFORM_SERVICE_PROBES, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, RETENTION_FEEDBACK_KEEP_RATIO, RETENTION_FEEDBACK_MIN_CHARS, RULES, RUNS_SCHEMA_VERSION, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUMMARY_DUPLICATE_HINT_THRESHOLD, SUPPORT_DIRS, SUPPORT_SPRAWL_FILES, SUPPRESSED_FILE_VERSION, SkillLibrary, TEXT_DIFF_MAX_CHARS, TEXT_DIFF_MAX_LINES, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UNTRUSTED_LINE_BREAK, UNTRUSTED_LINE_MARK, UPSTREAM_LIMIT_CHARS_PER_TOKEN, VERSION_SUMMARY_MAX_CHARS, absentHostServices, admissionVerdict, advanceReview, affinity, ageCopyKey, allowRowCollisions, anchorVerdict, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyNamespaceMigration, applyReferenceRewrite, asRecord, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, atomicWriteFiles, authoringFeedback, basePresetPlugins, blobPath, bodyCost, buildCuratorRunReport, buildHealthBaseline, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampOnce, clampedNumber, classifyNamespaceMigration, clearReviewChannel, collectReadSkillNames, composePresetComposition, composePresetEntry, composePresetInsert, composePresetRow, compositionRowIds, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, countReferenceFiles, createGateSet, daysSinceIso, declaredReportStamp, denseBlockSequence, describeReferenceRewrite, diffFindings, dispatchKeyOf, dispatchStepOf, displayBodyOf, duplicateHeadings, elapsedSince, emptyRecord, entryTarget, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionActivityProjection, evolutionEventPayloadIssue, evolutionEvidenceProjection, evolutionHome, evolutionIoAdapter, evolutionReadsProjection, evolutionRoot, evolutionSignalsProjection, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurnEvent, foldTurnEvents, foldUntrustedLines, frontmatterBlock, frontmatterCatalogInvalid, fuzzyPatch, getRecord, h2Sections, historyIndexFile, historyRoot, identity, idleDays, initialTurnFold, installEvolutionProjections, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isBookkeepingFrame, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isLoopbackRequest, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isRecord, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, latestVersionAt, lifecycleCandidate, lintBody, lintSkill, listDirectories, listEventArchives, liveBool, liveEnum, liveNumber, liveString, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, mergePresetRow, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newRunRegistry, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, normalizeVersionSummary, observeEvent, orderVersions, overlongLines, paramNamespace, paramRowId, paramSettingsId, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, partitionVersions, payloadText, persistedWriteSite, persistedWriteSites, pickWithPolicy, planNamespaceMigration, planReferenceRewrite, planRehoming, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeAbsent, probeDesktopScope, probeList, probeMtime, probePresent, probeReason, probeText, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readJsonBody, readJsonObject, readNumberParam, readParam, readingStats, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, removePresetRow, renameWithRetry, renderCuratorReportMarkdown, renderLongRunTable, reportTime, reportsSweepLockTarget, resolveBasePresetPatch, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, restructureCandidates, retainEventArchives, retirementReport, reviewPrompt, rowBlockSpan, rowSiblingEnd, runsFile, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionEvidenceIndex, sessionLastEventTime, sessionReadNames, sessionReadSkillNames, sessionSeesFamilyTools, sessionTurnSignals, skillReadNameOf, skillRowCells, skillStateKey, skillsRoot, supportFileReadOf, suppressedFile, sweepReports, sweepReviewChannelSessions, textDiffFacts, tokenLineFor, transactIo, transactTaskGuard, trimPatternBoundaries, trimTrailingBlankLines, unhookedSupportPointers, unwrapLive, updateSuppressedNames, usageFile, usageObserved, userSetKeys, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionActionKind, versionRowCells, versionSummaryPrompt, versionTarget, vocabulary, writeDurableTmp, writeJson, writePathSymbols, yamlPlainScalarNeedsQuotes };
+export { AGENT_PRESET_PACKAGE, AGENT_PRESET_ROOT_HINT, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, BASELINE_ACTION, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEDUP_MAX_PAIR_COMPARISONS, DEDUP_SIMILARITY_THRESHOLD, DEFAULT_ADMISSION, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, 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_PROBE_TIMEOUT_MS, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_RUN_RECORDS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_PATCH_SEED, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, FUZZY_MAX_PATTERN_CHARS, FUZZY_MAX_WORK, HEALTH_STAMP_RE, HISTORY_DIR, HISTORY_INDEX_VERSION, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LONG_RUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_REQUEST_BODY_BYTES, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NAMESPACE_MIGRATIONS, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, PLATFORM_SERVICE_PROBES, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, RETENTION_FEEDBACK_KEEP_RATIO, RETENTION_FEEDBACK_MIN_CHARS, RULES, RUNS_SCHEMA_VERSION, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUMMARY_DUPLICATE_HINT_THRESHOLD, SUPPORT_DIRS, SUPPORT_SPRAWL_FILES, SUPPRESSED_FILE_VERSION, SkillLibrary, TEXT_DIFF_MAX_CHARS, TEXT_DIFF_MAX_LINES, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UNTRUSTED_LINE_BREAK, UNTRUSTED_LINE_MARK, UPSTREAM_LIMIT_CHARS_PER_TOKEN, VERSION_SUMMARY_MAX_CHARS, absentHostServices, admissionVerdict, advanceReview, affinity, ageCopyKey, allowRowCollisions, anchorVerdict, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyNamespaceMigration, applyReferenceRewrite, asRecord, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, atomicWriteFiles, authoringFeedback, basePresetPlugins, blobPath, bodyCost, buildCuratorRunReport, buildHealthBaseline, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, candidateSkills, canonicalWriteId, claimInstance, clampOnce, clampedNumber, classifyNamespaceMigration, clearReviewChannel, collectReadSkillNames, composePresetComposition, composePresetEntry, composePresetInsert, composePresetRow, compositionRowIds, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, countReferenceFiles, createGateSet, daysSinceIso, declaredReportStamp, denseBlockSequence, describeReferenceRewrite, diffFindings, dispatchKeyOf, dispatchStepOf, displayBodyOf, duplicateHeadings, elapsedSince, emptyRecord, entryTarget, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionActivityProjection, evolutionEventPayloadIssue, evolutionEvidenceProjection, evolutionHome, evolutionIoAdapter, evolutionReadsProjection, evolutionRoot, evolutionSignalsProjection, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurnEvent, foldTurnEvents, foldUntrustedLines, frontmatterBlock, frontmatterCatalogInvalid, fuzzyPatch, getRecord, h2Sections, historyIndexFile, historyRoot, identity, idleDays, initialTurnFold, installEvolutionProjections, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isBookkeepingFrame, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isLandmark, isLoopbackRequest, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isRecord, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, landmarkVerdict, latestActivityAt, latestVersionAt, lifecycleCandidate, lintBody, lintSkill, listDirectories, listEventArchives, liveBool, liveEnum, liveNumber, liveString, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, mergePresetRow, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newRunRegistry, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, normalizeVersionSummary, observeEvent, orderVersions, overlongLines, paramNamespace, paramRowId, paramSettingsId, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, partitionVersions, payloadText, persistedWriteSite, persistedWriteSites, pickWithPolicy, planNamespaceMigration, planReferenceRewrite, planRehoming, policyStageLimits, presetPatchText, presetRowBlock, presetRowBody, presetRowId, probeAbsent, probeDesktopScope, probeList, probeMtime, probePresent, probeReason, probeText, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readJsonBody, readJsonObject, readNumberParam, readParam, readingStats, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, removePresetRow, renameWithRetry, renderCuratorReportMarkdown, renderLongRunTable, reportTime, reportsSweepLockTarget, resolveBasePresetPatch, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, resolveUnitMembers, resolveUnitMembersFromIndexes, restructureCandidates, retainEventArchives, retirementReport, reviewPrompt, rowBlockSpan, rowSiblingEnd, runsFile, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionEvidenceIndex, sessionLastEventTime, sessionReadNames, sessionReadSkillNames, sessionSeesFamilyTools, sessionTurnSignals, skillReadNameOf, skillRowCells, skillStateKey, skillsRoot, staleRouteStubs, supportFileReadOf, suppressedFile, sweepReports, sweepReviewChannelSessions, textDiffFacts, tokenLineFor, transactIo, transactTaskGuard, trimPatternBoundaries, trimTrailingBlankLines, unhookedSupportPointers, unitMembersAreComplete, unwrapLive, updateSuppressedNames, usageFile, usageObserved, userSetKeys, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionActionKind, versionRowCells, versionSummaryPrompt, versionTarget, vocabulary, writeDurableTmp, writeJson, writePathSymbols, yamlPlainScalarNeedsQuotes };

package/lib/types/curator.d.ts

@@ -54,6 +54,18 @@ export interface CuratorFailedSkill {
     reason: string;
 }
 export interface CuratorRunReport {
+    /** G3b: cross-index orphan landmarks -- report-only, never a verdict. */
+    routeStubs?: {
+        readonly skills: number;
+        readonly stubs: number;
+        readonly reason: string;
+        readonly detail: readonly {
+            readonly skill: string;
+            readonly v: number;
+            readonly owner: string;
+            readonly reason: string;
+        }[];
+    };
     /** Report shape version; readers may ignore unknown fields on later versions. */
     schemaVersion: 1;
     runId: string;

package/lib/types/frontmatter.d.ts

@@ -25,6 +25,12 @@ export declare function frontmatterBlock(content: string): {
  */
 export interface FrontmatterRead {
     frontmatter: Frontmatter;
+    /** P0′: the structured `metadata:` mapping, when the strict parser loaded one.
+     * Published as an OBJECT (never stringified): nested mappings used to be dropped
+     * because a lossy string could be picked up by a routing field — keeping it
+     * structured removes that risk while giving the one consumer the nested
+     * `metadata.hermes.related_skills` form the real corpus actually writes. */
+    metadata?: Record<string, unknown> | undefined;
     body: string;
     /** Raw entries whose UNQUOTED value the strict catalog cannot load as
      * written. Quotes are included, so a value already normalized by the write

package/lib/types/index.d.ts

@@ -72,6 +72,7 @@ export * from './evidence.ts';
 export * from './session-projection.ts';
 export * from './drift-signals.ts';
 export * from './skill-history.ts';
+export * from './unit-members.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';

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

@@ -0,0 +1,19 @@
+/** 技能名文法（与平台 `isSkillName` 等价：kebab-case，点前缀与下划线一律不是技能名）。 */
+export declare const SKILL_NAME_RE: RegExp;
+/** 名字是否是技能名 —— `._x`、`Bad_Name`、`.archive` 都返回 false。 */
+export declare function isSkillName(name: string): boolean;
+/** 相对技能根的路径是否落在平台会发现的位置（depth<=2 且最后一段是 SKILL.md 或 `<name>.md`）。 */
+export declare function isPotentialSkillPath(relPath: string): boolean;
+export interface DiscoveredSkill {
+    name: string;
+    path: string;
+}
+/**
+ * 扫描一个技能根，返回平台**真正会发现**的技能（非递归、depth<=2、含 `SKILL.md` 的目录、
+ * 名字过 kebab-case、跳过点前缀目录）。忽略目录里的边不得计入，也不得算悬空。
+ *
+ * @param root - 技能根目录。
+ * @returns 按名字排序的技能列表（根缺失时返回空数组）。
+ */
+export declare function discoverSkillFiles(root: string): DiscoveredSkill[];
+//# sourceMappingURL=skill-discovery.d.ts.map

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

@@ -34,11 +34,30 @@ export declare const HISTORY_INDEX_VERSION = 1;
 /** The action label for a predecessor the index had never seen (content found on disk before this
  * feature existed, or a hand-edited tree): it says "this is what was there", not what wrote it. */
 export declare const BASELINE_ACTION = "baseline";
+/** G3b: one unit's head. Exactly one of the two forms is present (they never coexist). */
+export interface UnitHead {
+    /** Representative shard: the unit's WHOLE manifest of moves (one entry per written path). */
+    moves?: readonly Readonly<Record<string, unknown>>[];
+    /** Representative shard: the skills this unit wrote, so members resolve without a directory scan. */
+    sources?: readonly {
+        readonly skill: string;
+        readonly dest?: string;
+    }[];
+    /** Cross-skill landmark: the skill that owns the unit (route-only; never carries `moves`). */
+    skill?: string;
+}
 /** One recorded version of one skill. */
 export interface SkillVersion {
     /** Monotonic per skill; the identity, unlike {@link SkillVersion.at}. */
     v: number;
     at: string;
+    /** G3a: the unit this entry belongs to (one tree change = one unit); absent on entries recorded before it. */
+    unitId?: string;
+    /** G3b: the unit HEAD. A representative shard carries `{ moves, sources }` (`moves` is the whole
+     * manifest of the unit, `sources` names the skills it wrote); a cross-skill landmark carries
+     * `{ skill }` only, and the two forms are mutually exclusive. Discriminate on `moves !== undefined`
+     * (a landmark also carries `unitId`, so that field can never discriminate). */
+    unitHead?: UnitHead;
     /** The mutation that produced it (`create`/`update`/`patch`/…), or {@link BASELINE_ACTION}. */
     action: string;
     /** sha256 of the stored content. */
@@ -75,6 +94,10 @@ export interface VersionRecordInput {
     summary?: string;
     /** The support file this write touched, relative to the skill directory; undefined for content. */
     path?: string;
+    /** G3a: the unit this write belongs to — one tree change writes N paths under ONE id. */
+    unitId?: string;
+    /** G3b: present only on the unit's representative shard (see {@link SkillVersion.unitHead}). */
+    unitHead?: UnitHead;
 }
 /** The version numbers one write produced; a side with no content contributes nothing. */
 export interface RecordedVersions {

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

@@ -570,7 +570,7 @@ export declare class SkillLibrary {
     restoreFromArchive(rawName: string): Promise<SkillActionResult>;
     writeSupportFile(rawName: string, filePath: string, content: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
     private writeSupportFileCore;
-    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor): Promise<SkillActionResult>;
+    removeSupportFile(rawName: string, filePath: string, origin?: WriteOrigin, anchor?: WriteAnchor, unitId?: string): Promise<SkillActionResult>;
     private removeSupportFileCore;
     /**
      * v23 (ML-1): `.archive` retention. Archived skills are recoverable history,

package/lib/types/unit-members.d.ts

@@ -0,0 +1,73 @@
+/**
+ * G3b: resolve a unit's members from the skills named in its head's `sources[]`.
+ *
+ * Pure core (no io): the caller hands in each candidate skill's index TEXT, so this function can be
+ * tested with synthetic indexes. Membership is decided ONLY by the known keys -- never by scanning a
+ * directory -- and the result order is the `sources[]` order with the head skill first (deterministic:
+ * no Map/Set iteration order leaks into the output).
+ */
+import type { SkillVersion, UnitHead } from './skill-history.ts';
+export interface UnitMemberSlice {
+    readonly skill: string;
+    readonly entries: readonly SkillVersion[];
+}
+export interface UnitMemberIssue {
+    readonly skill: string;
+    readonly reason: 'index-absent' | 'unit-absent';
+}
+export interface UnitConflict {
+    readonly kind: 'missing' | 'foreign' | 'duplicated';
+    readonly path: string;
+}
+export interface UnitMembers {
+    readonly members: readonly UnitMemberSlice[];
+    readonly missing: readonly UnitMemberIssue[];
+    readonly conflicts: readonly UnitConflict[];
+}
+export interface UnitHeadInput {
+    readonly skill: string;
+    readonly unitId: string;
+    readonly sources: readonly {
+        readonly skill: string;
+    }[];
+    readonly unitHead?: UnitHead;
+}
+/** Candidate skills: head first, then `sources[]` order, DEDUPLICATED (sources may name the head). */
+export declare function candidateSkills(head: UnitHeadInput): string[];
+export declare function resolveUnitMembersFromIndexes(head: UnitHeadInput, indexes: ReadonlyMap<string, string | null>, readEntries: (text: string) => readonly SkillVersion[]): UnitMembers;
+/** A unit's members are trustworthy only when nothing is missing and nothing conflicts. */
+export declare function unitMembersAreComplete(members: UnitMembers): boolean;
+/** Minimal io view the shell needs (structural, so this module imports no io type). */
+export interface UnitMemberIo {
+    readText(path: string): Promise<string | null>;
+}
+/**
+ * The io shell (A19.2): open ONLY the known keys -- never enumerate a directory. A skill whose index
+ * file is unreadable becomes `null` (index-absent), which the core then reports by name.
+ */
+export declare function resolveUnitMembers(root: string, io: UnitMemberIo, head: UnitHeadInput, indexPath: (root: string, name: string) => string, readEntries: (raw: string | null) => readonly SkillVersion[]): Promise<UnitMembers>;
+/** G3b: a LANDMARK carries the owning skill and no manifest (the two forms never coexist). */
+export declare function isLandmark(entry: SkillVersion): boolean;
+/** A landmark is jumpable only when its owner exists AND that index still holds the unit. */
+export type LandmarkVerdict = {
+    readonly jumpable: true;
+} | {
+    readonly jumpable: false;
+    readonly reason: 'not-a-landmark' | 'owner-absent' | 'unit-absent';
+};
+/** @param entry - the entry being judged. @param ownerEntries - the owner skill's index, or null when
+ * the owner has no readable index. */
+export declare function landmarkVerdict(entry: SkillVersion, ownerEntries: readonly SkillVersion[] | null): LandmarkVerdict;
+/** One cross-index orphan: a landmark whose owner or unit can no longer be reached. */
+export interface StaleRouteStub {
+    readonly skill: string;
+    readonly v: number;
+    readonly owner: string;
+    readonly reason: 'owner-absent' | 'unit-absent';
+}
+/**
+ * Scan a whole corpus (skill name -> index entries, or null when unreadable) for stale route stubs.
+ * Sorted by (skill, version, owner): a function of the corpus, not of the caller's map order.
+ */
+export declare function staleRouteStubs(indexes: ReadonlyMap<string, readonly SkillVersion[] | null>): StaleRouteStub[];
+//# sourceMappingURL=unit-members.d.ts.map

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