@lmzhen/dsh-evolution-core 0.8.0 → 0.9.0

package/lib/index.js

@@ -374,7 +374,7 @@ function describeReferenceRewrite(plan) {
 */
 /**
 * Required argument names per `skill_manage` action — the SINGLE SOURCE read
-* by the tool's argument gate (tool-skill-manage executeCore) and the plan
+* by the tool's argument gate (tool-skill-manage write-gates.ts) and the plan
 * validator (evolution-plan-validator), so the two can never drift.
 * OPT-05 (2026-09): the plan validator used to accept a `write_file`/
 * `remove_file` op without `file_path` while the executor required it — the
@@ -512,6 +512,16 @@ const EVOLUTION_WRITE_TOOLS = ["memory", "skill_manage"];
 * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
 * can reference it without importing the skill-store module. */
 const AUTHORING_DESCRIPTION_BAR = 60;
+/** The PLATFORM's default cap on the description a skill catalog shows —
+* `catalogDescriptionMaxLength` on the platform's `tool-skill` row (default 500).
+*
+* Recorded here because it is the third number in the description-length relationship, and the one
+* that is easiest to misread as a family rule: the family's own host/all rows SET that field to
+* `AUTHORING_DESCRIPTION_BAR` (60), so what a family deployment truncates at is the ROW's value —
+* this default only governs compositions that do not override it. It is NOT a refusal threshold:
+* the only refusal is `MAX_DESCRIPTION_LENGTH` / the row's `maxDescriptionLength`, and the catalog
+* cut is a view, not a validation. See tool-skill-manage/README.md for the three-number table. */
+const PLATFORM_CATALOG_DESCRIPTION_DEFAULT = 500;
 /** The split hint both size refusals share (0.5.0 V1). The same sentence used to
 * be copied into validateFrontmatter AND the patch path, and neither copy named
 * where the content should go — the upstream cap message names the destination
@@ -2967,7 +2977,8 @@ function allowRowCollisions(env = process.env) {
 //#endregion
 //#region lib/types/errors.js
 /**
-* THE error-code table: E-301…E-316 with the exact text each one emits.
+* THE error-code table: E-301…E-318 with the exact text each one emits (E-317 and E-318 are the
+* write-admission gates' own refusals).
 *
 * The codes used to be spelled out at 33 call sites across two packages, so one
 * code's wording could drift between the branches that answer it and nothing could
@@ -3000,7 +3011,9 @@ const EVOLUTION_ERRORS = Object.freeze({
 	"e-309-revision-conflict-you-sent": "E-309: revision conflict — you sent %a1%, the document stands at %a2%. Re-read with /evolution params --json and retry.",
 	"e-309-revision-conflict-message-Re": "E-309: revision conflict — %a1%. Re-read with /evolution params --json and retry.",
 	"e-310-the-settings-service-refused": "E-310: the settings service refused the write: %a1% — the owning plugin's rule stands (a cross-field pair, or a cap that may only be tightened). /evolution params shows the current value.",
-	"e-305-this-invocation-carries-no-2": "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI)."
+	"e-305-this-invocation-carries-no-2": "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI).",
+	"e-317-skill-write-not-confirmed": "E-317: skill \"%a1%\" was not %a2% — the confirmation prompt was declined or dismissed, so nothing was written. The prompt appears on every create and bare delete; repeat the call only if the operator asks for it.",
+	"e-318-skill-write-without-a-read": "E-318: skill \"%a1%\" was not read in this session, so this write is refused. Read it with the `skill` tool first (a read that failed does not count), then repeat the write."
 });
 /**
 * Render one table entry, substituting its interpolation slots.
@@ -5899,6 +5912,89 @@ function foldTurn(session, fromSeq) {
 	return signal;
 }
 //#endregion
+//#region lib/types/skill-reads.js
+/**
+* The read-before-write RULE: which writes need a prior read, and which targets count as read.
+*
+* ONE rule for TWO enforcement points (design `dsh-evolution-write-gate-design.md` §4.2): the
+* tool path refuses an unread mutating write (E-318), and the plan path drops such an op from a
+* background review's plan. Before this module the rule lived in `evolution-review` only, so the
+* tool path could not see it at all.
+*
+* The READER is not here either: `tool-dispatch.collectReadSkillNames(events)` folds a session log
+* into the names read through a non-failed dispatch — the review's old session-shaped copy was a
+* line-for-line duplicate of it. What this module adds over it is the session-shaped ADAPTER
+* (`sessionReadSkillNames`), for the ONE caller that holds a session only STRUCTURALLY (the tool
+* path's gate, whose exec view may be a bare stub): it answers "which accessor, and what does an
+* unreadable session mean" — `undefined`, so the gate keeps its previous behavior instead of
+* refusing every write. The review path reads a real platform `Session` and calls the reader
+* directly; a fallback there would be dead code for an impossible case.
+*
+* v32 REV-06(a) is preserved by the dispatch normalizer: a skill counts as READ only when its read
+* did not fail, so a failed/timeout read cannot pass the gate and let a writer blind-overwrite
+* content the model never saw. Matching `tool/call` directly (the pre-v37 form) meant every PTC
+* session (`tool/ptc-dispatch*`) collected an EMPTY set, so every mutating op the model HAD read
+* was dropped — and nothing reported the loss.
+* @module @lmzhen/dsh-evolution-core
+*/
+/**
+* The skill names ONE session read, or `undefined` when its log is not readable.
+*
+* `undefined` is NOT an empty set: a caller that must decide (the tool path's read-before-write
+* gate) can then keep its previous behavior instead of refusing every write in a composition whose
+* session objects expose no log at all.
+* @param session - the session whose reads are wanted; `undefined` when the call carries none.
+* @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
+*/
+function sessionReadSkillNames(session) {
+	const events = session?.snapshotEvents?.();
+	return events === void 0 ? void 0 : collectReadSkillNames(events);
+}
+/** Actions whose target must have been read first (create is authorship, so it is exempt). */
+const READ_REQUIRED_ACTIONS = Object.freeze([
+	"edit",
+	"update",
+	"patch",
+	"delete",
+	"write_file",
+	"remove_file",
+	"restructure"
+]);
+/**
+* Does this one op write a skill the caller never read?
+*
+* V6-26 (0.3.37): the validator normalizes a missing action to `patch`, so a missing action is a
+* read-required write, never silently exempt.
+* @param op - one skill operation (from a tool call or a review plan).
+* @param readNames - names read this session, from {@link collectReadSkillNames}.
+* @returns true when the op is a read-required write to an unread target.
+*/
+function isUnreadWrite(op, readNames) {
+	if (!op.name) return false;
+	return READ_REQUIRED_ACTIONS.includes(op.action ?? "patch") && !readNames.has(op.name);
+}
+/**
+* Drop mutating ops whose target was not read this session, in place.
+*
+* Covers the same mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
+* background review cannot blind-touch support files or edits of skills it never loaded.
+* @param ops - the plan's ops; dropped entries are removed in place.
+* @param readNames - names read this session.
+* @returns the count of dropped ops, so the plan event can report them as rejected.
+*/
+function filterUnreadSkillOps(ops, readNames) {
+	let dropped = 0;
+	for (let index = ops.length - 1; index >= 0; index -= 1) {
+		const op = ops[index];
+		if (!op) continue;
+		if (isUnreadWrite(op, readNames)) {
+			ops.splice(index, 1);
+			dropped += 1;
+		}
+	}
+	return dropped;
+}
+//#endregion
 //#region lib/types/drift-signals.js
 /**
 * Library-level drift signals for the maintenance subagent (design 011).
@@ -8957,6 +9053,20 @@ function readParam(carrier, id) {
 	for (const alias of ALIASES_BY_CANONICAL[canonical] ?? []) if (record[alias] !== void 0) return record[alias];
 }
 /**
+* Chinese display name per group, one entry per line (the scripts read this block
+* by text, the same way they read PARAM_NAMESPACES). The raw group id is what
+* `--group` accepts and what the JSON face reports; this only names it on screen.
+*/
+const PARAM_GROUP_LABELS = Object.freeze({
+	library: "技能库",
+	"write-caps": "写入上限",
+	review: "会话回顾",
+	memory: "记忆",
+	curator: "技能整理",
+	deployment: "安装配置",
+	internal: "内部"
+});
+/**
 * The parameter registry. G1/S1.1 seeds it with the review group (G-C); the
 * remaining groups land in S2.1. E3 = behaviour preference the user may change
 * (live); E2 = resource or identity knob that stays with the deployment.
@@ -8970,9 +9080,9 @@ const PARAM_EXPOSURE = Object.freeze([
 		owner: "evolution-review",
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
-		summary: "Activity units between skill-review injections.",
-		label: "技能审查间隔",
-		hint: "每多少活动单位触发一次技能审查注入。",
+		summary: "Tool calls between skill-review injections: a turn advances by its tool-call count (a turn with none counts as one), or by 1 when the turn itself used a skill.",
+		label: "技能检查间隔",
+		hint: "每累计多少次工具调用检查一次技能：一轮按该轮工具调用数累加（一轮没有工具调用也算 1 次），本轮本身用到技能则只算 1 次。",
 		control: "number",
 		unit: "次",
 		values: ""
@@ -8985,9 +9095,9 @@ const PARAM_EXPOSURE = Object.freeze([
 		owner: "evolution-review",
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
-		summary: "Activity units between memory-review injections.",
-		label: "记忆审查间隔",
-		hint: "每多少活动单位触发一次记忆审查注入。",
+		summary: "Tool calls between memory-review injections: a turn advances by its tool-call count (a turn with none counts as one), or by 1 when the turn itself touched memory.",
+		label: "记忆检查间隔",
+		hint: "每累计多少次工具调用检查一次记忆：一轮按该轮工具调用数累加（一轮没有工具调用也算 1 次），本轮本身用到记忆则只算 1 次。",
 		control: "number",
 		unit: "次",
 		values: ""
@@ -9001,11 +9111,12 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
 		summary: "Which channel may inject a skill review (cadence, completion, both).",
-		label: "审查触发通道",
-		hint: "哪个通道可以注入技能审查：cadence＝按间隔、completion＝按完成、both＝两者。",
+		label: "技能检查时机",
+		hint: "什么时候检查技能：按间隔／按任务完成／两者。",
 		control: "select",
 		unit: "",
-		values: "cadence|completion|both"
+		values: "cadence|completion|both",
+		valueLabels: "按间隔|按任务完成|两者"
 	},
 	{
 		id: "skillReviewCompletionMinToolCalls",
@@ -9016,8 +9127,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
 		summary: "Tool calls a task needs before the completion channel injects.",
-		label: "完成通道最少工具调用",
-		hint: "走完成通道时，任务至少经过多少次工具调用才注入。",
+		label: "完成时的最少工具调用",
+		hint: "选「按任务完成」时，任务至少用了几次工具才检查。",
 		control: "number",
 		unit: "次",
 		values: ""
@@ -9031,8 +9142,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
 		summary: "Master switch for the review plugin.",
-		label: "启用审查插件",
-		hint: "审查插件的总开关。",
+		label: "启用自动检查",
+		hint: "关闭后不再自动回顾会话。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9046,11 +9157,12 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
 		summary: "Run the review in the parent session (inject) or on a subagent.",
-		label: "审查运行方式",
-		hint: "inject＝在父会话内注入，subagent＝交给子代理运行。",
+		label: "运行位置",
+		hint: "在哪里运行检查：在当前会话里／交给子代理。",
 		control: "select",
 		unit: "",
-		values: "subagent|inject"
+		values: "subagent|inject",
+		valueLabels: "交给子代理|在当前会话里"
 	},
 	{
 		id: "reviewWakeInject",
@@ -9061,8 +9173,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#review",
 		summary: "Deliver the deferred review as a waking follow-up message.",
-		label: "审查后续唤醒注入",
-		hint: "把延后的审查作为唤醒消息投递。",
+		label: "延后结果发提醒",
+		hint: "会话空闲时，把延后的检查结果作为一条提醒发给你。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9136,8 +9248,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Character cap on a SKILL.md body (tighten-only).",
-		label: "SKILL.md 正文字符上限",
-		hint: "SKILL.md 正文的字符上限（只许收紧）。",
+		label: "技能文件正文上限",
+		hint: "技能 Markdown 正文最多多少字符（只能调小）。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9151,8 +9263,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Byte cap on one support file (tighten-only).",
-		label: "支持文件字节上限",
-		hint: "单个支持文件的字节上限（只许收紧）。",
+		label: "附带文件大小上限",
+		hint: "技能附带文件单个最大多少字节（只能调小）。",
 		control: "number",
 		unit: "字节",
 		values: ""
@@ -9166,8 +9278,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Character cap on a skill name (tighten-only).",
-		label: "技能名字符上限",
-		hint: "技能名的字符上限（只许收紧）。",
+		label: "技能名长度上限",
+		hint: "技能名最多多少字符（只能调小）。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9181,8 +9293,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Character cap on a skill description (tighten-only).",
-		label: "技能描述字符上限",
-		hint: "技能描述的字符上限（只许收紧）。",
+		label: "技能描述长度上限",
+		hint: "技能描述最多多少字符（只能调小）。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9196,8 +9308,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Refuse a description over the authoring bar instead of advising.",
-		label: "描述严格档",
-		hint: "描述超过写作门槛时拒绝写入，而不是只提示。",
+		label: "描述不合规即拒绝",
+		hint: "描述不符合要求时直接拒绝写入（默认只提醒）。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9211,8 +9323,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Refuse writes whose catalog entry resolves outside the family.",
-		label: "跨源严格档",
-		hint: "目录项解析到家族之外时拒绝写入。",
+		label: "引用外部内容即拒绝",
+		hint: "技能引用了本插件之外的文件时拒绝写入。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9226,11 +9338,12 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Refuse a move that would leave a dangling reference, or verify it.",
-		label: "引用校验档",
-		hint: "移动或合并时对引用的处置：verify＝校验、refuse＝直接拒绝。",
+		label: "引用检查方式",
+		hint: "移动或合并技能时怎么处理引用：先检查／直接拒绝。",
 		control: "select",
 		unit: "",
-		values: "verify|refuse"
+		values: "verify|refuse",
+		valueLabels: "先检查|直接拒绝"
 	},
 	{
 		id: "referenceRewrite",
@@ -9261,11 +9374,12 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Warn about an oversize support file, or refuse the write.",
-		label: "支持文件超限档",
-		hint: "支持文件超出字符上限时：report＝只报告、enforce＝拒写。",
+		label: "附带文件超限时",
+		hint: "附带文件超出上限时：只提醒／拒绝写入。",
 		control: "select",
 		unit: "",
-		values: "report|enforce"
+		values: "report|enforce",
+		valueLabels: "只提醒|拒绝写入"
 	},
 	{
 		id: "memoryChars",
@@ -9276,8 +9390,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#memory",
 		summary: "Character budget the memory store enforces for MEMORY.md.",
-		label: "MEMORY.md 字符预算",
-		hint: "memory 存储对 MEMORY.md 的字符上限。",
+		label: "记忆库上限",
+		hint: "长期记忆文件（MEMORY.md）最多多少字符。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9291,8 +9405,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#memory",
 		summary: "Character budget the memory store enforces for USER.md.",
-		label: "USER.md 字符预算",
-		hint: "memory 存储对 USER.md 的字符上限。",
+		label: "用户画像上限",
+		hint: "用户画像文件（USER.md）最多多少字符。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9316,8 +9430,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#memory",
 		summary: "Characters of one memory entry shown in a tool result preview.",
-		label: "条目预览字符数",
-		hint: "单条记忆预览保留多少字符。",
+		label: "记忆预览长度",
+		hint: "列表里每条记忆最多显示多少字符。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9331,8 +9445,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#memory",
 		summary: "Prefix stored memory entries with their date heading.",
-		label: "记忆条目加日期前缀",
-		hint: "写入记忆时为条目加上日期标题。",
+		label: "记忆条目加日期",
+		hint: "写入时在条目开头加上日期。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9346,8 +9460,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#memory",
 		summary: "Consolidation failures one turn tolerates before the tool gives up.",
-		label: "合并失败容忍次数",
-		hint: "一轮内合并失败多少次后工具放弃。",
+		label: "合并失败重试",
+		hint: "合并记忆连续失败多少次后停止。",
 		control: "number",
 		unit: "次",
 		values: ""
@@ -9361,8 +9475,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Minimum hours between deterministic curation passes.",
-		label: "策展间隔",
-		hint: "两次确定性策展之间至少间隔多少小时。",
+		label: "自动整理间隔",
+		hint: "两次自动整理之间至少间隔多少小时。",
 		control: "number",
 		unit: "小时",
 		values: ""
@@ -9376,8 +9490,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Inactive days before a skill counts as stale.",
-		label: "判为陈旧的天数",
-		hint: "技能多少天没被使用即算陈旧。",
+		label: "多久没用算过时",
+		hint: "技能连续多少天没被用到就算过时。",
 		control: "number",
 		unit: "天",
 		values: ""
@@ -9391,8 +9505,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Inactive days before a stale skill is archived (must be >= staleAfterDays).",
-		label: "归档天数",
-		hint: "陈旧技能再过多少天归档（须 ≥ 判为陈旧的天数）。",
+		label: "过时后归档",
+		hint: "过时技能再过多少天移入归档（不能小于上一项）。",
 		control: "number",
 		unit: "天",
 		values: ""
@@ -9406,8 +9520,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Age at which a low quality score starts warning.",
-		label: "低质量告警天数",
-		hint: "质量分偏低时从多少天开始告警。",
+		label: "质量偏低提醒",
+		hint: "质量评分偏低时，从多少天开始提醒。",
 		control: "number",
 		unit: "天",
 		values: ""
@@ -9421,8 +9535,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Idle hours required before an automatic curation pass runs.",
-		label: "空闲门槛",
-		hint: "至少空闲多少小时才跑自动策展。",
+		label: "最少空闲时长",
+		hint: "你至少多少小时没用，才运行自动整理。",
 		control: "number",
 		unit: "小时",
 		values: ""
@@ -9436,8 +9550,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Let the idle gate open when the activity probe is unavailable.",
-		label: "空闲探针失败时放行",
-		hint: "活动探针不可用时，是否让空闲门槛直接放行。",
+		label: "检测不到活动也运行",
+		hint: "无法判断你是否空闲时，仍然运行自动整理。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9451,8 +9565,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Enable the LLM nomination pass on top of the deterministic lifecycle.",
-		label: "启用 LLM 提名",
-		hint: "在确定性生命周期之上再跑一遍 LLM 提名。",
+		label: "用模型挑选",
+		hint: "在固定规则之外，再用模型挑一遍候选项。",
 		control: "switch",
 		unit: "",
 		values: ""
@@ -9466,8 +9580,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Token budget of the curator LLM review.",
-		label: "策展 LLM token 预算",
-		hint: "策展 LLM 审查可用的 token 预算。",
+		label: "模型处理上限",
+		hint: "每次用模型挑选时最多消耗多少 token。",
 		control: "number",
 		unit: "token",
 		values: ""
@@ -9481,8 +9595,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Wall-clock bound of the curator LLM review.",
-		label: "策展 LLM 超时",
-		hint: "策展 LLM 审查的墙钟上限。",
+		label: "模型处理超时",
+		hint: "一次模型挑选最长允许运行多久。",
 		control: "number",
 		unit: "毫秒",
 		values: ""
@@ -9496,8 +9610,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Body character line the health view judges against.",
-		label: "正文软带",
-		hint: "健康视图判定正文长度的软带。",
+		label: "正文长度参考值",
+		hint: "技能正文超过多少字符算偏长（只用于健康提示）。",
 		control: "number",
 		unit: "字符",
 		values: ""
@@ -9511,8 +9625,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Stamp density per KB that flags log-like content in a body.",
-		label: "标记密度阈值",
-		hint: "每 KB 出现多少个时间标记就算「像日志」。",
+		label: "日志化判定阈值",
+		hint: "每 KB 出现多少个时间标记，就判为「像日志」。",
 		control: "number",
 		unit: "处/KB",
 		values: ""
@@ -9526,8 +9640,8 @@ const PARAM_EXPOSURE = Object.freeze([
 		applies: "live",
 		docAnchor: "PARAMETERS.md#curator",
 		summary: "Patches without a read that flag a write-ghost skill.",
-		label: "空写判定补丁数",
-		hint: "多少次改动都没有任何读取，即判为「写幽灵」。",
+		label: "只写不读判定次数",
+		hint: "连续多少次改动都没有被读取，就判为「只写不读」。",
 		control: "number",
 		unit: "处",
 		values: ""
@@ -10300,4 +10414,4 @@ function sessionAudited(ctx, sessionId, sessionScoped) {
 	return false;
 }
 //#endregion
-export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, 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, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, 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_REFERENCE_REWRITE_POLICY, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_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_LOCK_TAKEOVER_MS, 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, HEALTH_STAMP_RE, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, emptyRecord, errorText, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readNumberParam, readParam, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, 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, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, 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_REFERENCE_REWRITE_POLICY, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_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_LOCK_TAKEOVER_MS, 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, HEALTH_STAMP_RE, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, 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, 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, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, emptyRecord, errorText, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readNumberParam, readParam, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionReadSkillNames, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -21,7 +21,7 @@
  */
 /**
  * Required argument names per `skill_manage` action — the SINGLE SOURCE read
- * by the tool's argument gate (tool-skill-manage executeCore) and the plan
+ * by the tool's argument gate (tool-skill-manage write-gates.ts) and the plan
  * validator (evolution-plan-validator), so the two can never drift.
  * OPT-05 (2026-09): the plan validator used to accept a `write_file`/
  * `remove_file` op without `file_path` while the executor required it — the
@@ -128,6 +128,16 @@ export declare const EVOLUTION_WRITE_TOOLS: readonly ["memory", "skill_manage"];
  * 0.3.16 (T-4): moved here from skill-store.ts so drift-signals (pure, no IO)
  * can reference it without importing the skill-store module. */
 export declare const AUTHORING_DESCRIPTION_BAR = 60;
+/** The PLATFORM's default cap on the description a skill catalog shows —
+ * `catalogDescriptionMaxLength` on the platform's `tool-skill` row (default 500).
+ *
+ * Recorded here because it is the third number in the description-length relationship, and the one
+ * that is easiest to misread as a family rule: the family's own host/all rows SET that field to
+ * `AUTHORING_DESCRIPTION_BAR` (60), so what a family deployment truncates at is the ROW's value —
+ * this default only governs compositions that do not override it. It is NOT a refusal threshold:
+ * the only refusal is `MAX_DESCRIPTION_LENGTH` / the row's `maxDescriptionLength`, and the catalog
+ * cut is a view, not a validation. See tool-skill-manage/README.md for the three-number table. */
+export declare const PLATFORM_CATALOG_DESCRIPTION_DEFAULT = 500;
 /** The split hint both size refusals share (0.5.0 V1). The same sentence used to
  * be copied into validateFrontmatter AND the patch path, and neither copy named
  * where the content should go — the upstream cap message names the destination

package/lib/types/errors.d.ts

@@ -1,5 +1,6 @@
 /**
- * THE error-code table: E-301…E-316 with the exact text each one emits.
+ * THE error-code table: E-301…E-318 with the exact text each one emits (E-317 and E-318 are the
+ * write-admission gates' own refusals).
  *
  * The codes used to be spelled out at 33 call sites across two packages, so one
  * code's wording could drift between the branches that answer it and nothing could
@@ -33,6 +34,8 @@ export declare const EVOLUTION_ERRORS: Readonly<{
     readonly 'e-309-revision-conflict-message-Re': "E-309: revision conflict — %a1%. Re-read with /evolution params --json and retry.";
     readonly 'e-310-the-settings-service-refused': "E-310: the settings service refused the write: %a1% — the owning plugin's rule stands (a cross-field pair, or a cap that may only be tightened). /evolution params shows the current value.";
     readonly 'e-305-this-invocation-carries-no-2': "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI).";
+    readonly 'e-317-skill-write-not-confirmed': "E-317: skill \"%a1%\" was not %a2% — the confirmation prompt was declined or dismissed, so nothing was written. The prompt appears on every create and bare delete; repeat the call only if the operator asks for it.";
+    readonly 'e-318-skill-write-without-a-read': "E-318: skill \"%a1%\" was not read in this session, so this write is refused. Read it with the `skill` tool first (a read that failed does not count), then repeat the write.";
 }>;
 /** One table key. */
 export type EvolutionErrorId = keyof typeof EVOLUTION_ERRORS;

package/lib/types/index.d.ts

@@ -20,7 +20,8 @@
  *   evolution-policy/threat, both stores, review, maintenance.
  * - **Core domain stores/logic** — `skill-store.ts` (skill tree engine +
  *   IO-seam consumer), `memory-store.ts`, `usage.ts`, `curator.ts`,
- *   `quality.ts`, `signals.ts`, `drift-signals.ts`, `skill-health.ts`,
+ *   `quality.ts`, `signals.ts`, `skill-reads.ts` (the read-before-write rule, shared by the
+ *   tool path and the review's plan path), `drift-signals.ts`, `skill-health.ts`,
  *   `preset-composition.ts`, `prompts.ts`, `learn-prompt.ts`,
  *   `evolution-events.ts`, `io.ts` (the ctx.evolutionIo seam itself).
  * @module @lmzhen/dsh-evolution-core
@@ -50,6 +51,7 @@ export * from './write-inventory.ts';
 export * from './scope.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
+export * from './skill-reads.ts';
 export * from './drift-signals.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';

package/lib/types/params.d.ts

@@ -43,6 +43,12 @@ export declare function canonicalWriteId(id: string): string;
 export declare function readParam(carrier: object | undefined, id: string): unknown;
 /** Exposure group (design §7.2): the unit a developer changes together. */
 export type ParamGroup = 'library' | 'write-caps' | 'review' | 'memory' | 'curator' | 'deployment' | 'internal';
+/**
+ * Chinese display name per group, one entry per line (the scripts read this block
+ * by text, the same way they read PARAM_NAMESPACES). The raw group id is what
+ * `--group` accepts and what the JSON face reports; this only names it on screen.
+ */
+export declare const PARAM_GROUP_LABELS: Readonly<Record<ParamGroup, string>>;
 /** Exposure tier (design §7.1): the interface combination a parameter gets. */
 export type ParamTier = 'E0' | 'E1' | 'E2' | 'E3' | 'E4';
 /** Where the authoritative value lives. */
@@ -61,14 +67,17 @@ export type ParamAuthority = 'code' | 'cordis' | 'install';
  * writable through the user layer (a cordis.yml change still follows the
  * deployment's patch-reload policy).
  *
- * UI METADATA (0.7.0): every E3 row carries the optional tail
+ * UI METADATA (0.7.0): every E3 row carries the tail
  * `label, hint, control, unit, values` — in that order, directly after
- * `summary`, still one entry per line. E3 is the only tier the settings cards
- * render, so the card's Chinese name, help text, control kind, unit suffix and
- * value domain come from THIS registry and nowhere else; the browser half is
- * generated from this text (`gen-param-client-view.mjs`). Non-E3 rows must NOT
- * carry the tail (there is no UI surface for them), and `control: 'select'`
- * requires a non-empty pipe-joined `values`.
+ * `summary`, still one entry per line — plus an OPTIONAL trailing
+ * `valueLabels` (0.9.0). E3 is the only tier the settings cards render, so the
+ * card's Chinese name, help text, control kind, unit suffix and value domain
+ * come from THIS registry and nowhere else; the browser half is generated from
+ * this text (`gen-param-client-view.mjs`). Non-E3 rows must NOT carry the tail
+ * (there is no UI surface for them); `control: 'select'` requires a non-empty
+ * pipe-joined `values`, and `valueLabels` — allowed on select rows only — names
+ * those values for display, one label per value, in the same order. The stored
+ * value is never translated: only what the control shows.
  */
 export interface ParamExposure {
     id: string;
@@ -89,6 +98,11 @@ export interface ParamExposure {
     unit?: string;
     /** Pipe-joined allowed values; non-empty exactly when control is 'select'. */
     values?: string;
+    /**
+     * Pipe-joined display names for `values`, same order and count (optional).
+     * The stored value stays the raw one; this only names it on the card.
+     */
+    valueLabels?: string;
 }
 /**
  * The parameter registry. G1/S1.1 seeds it with the review group (G-C); the

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

@@ -0,0 +1,47 @@
+/** The session-log accessor the platform exposes (0.1.5 on; `session.events` before it). */
+export interface EvolutionSessionLogView {
+    /** @returns the session's events, oldest first. */
+    snapshotEvents?: () => Iterable<{
+        type: string;
+        data?: unknown;
+    }>;
+}
+/**
+ * The skill names ONE session read, or `undefined` when its log is not readable.
+ *
+ * `undefined` is NOT an empty set: a caller that must decide (the tool path's read-before-write
+ * gate) can then keep its previous behavior instead of refusing every write in a composition whose
+ * session objects expose no log at all.
+ * @param session - the session whose reads are wanted; `undefined` when the call carries none.
+ * @returns the names read through a non-failed `skill` dispatch, or `undefined` when unreadable.
+ */
+export declare function sessionReadSkillNames(session: EvolutionSessionLogView | undefined): ReadonlySet<string> | undefined;
+/** Actions whose target must have been read first (create is authorship, so it is exempt). */
+export declare const READ_REQUIRED_ACTIONS: readonly string[];
+/**
+ * Does this one op write a skill the caller never read?
+ *
+ * V6-26 (0.3.37): the validator normalizes a missing action to `patch`, so a missing action is a
+ * read-required write, never silently exempt.
+ * @param op - one skill operation (from a tool call or a review plan).
+ * @param readNames - names read this session, from {@link collectReadSkillNames}.
+ * @returns true when the op is a read-required write to an unread target.
+ */
+export declare function isUnreadWrite(op: {
+    action?: string;
+    name?: string;
+}, readNames: ReadonlySet<string>): boolean;
+/**
+ * Drop mutating ops whose target was not read this session, in place.
+ *
+ * Covers the same mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
+ * background review cannot blind-touch support files or edits of skills it never loaded.
+ * @param ops - the plan's ops; dropped entries are removed in place.
+ * @param readNames - names read this session.
+ * @returns the count of dropped ops, so the plan event can report them as rejected.
+ */
+export declare function filterUnreadSkillOps(ops: Array<{
+    action?: string;
+    name?: string;
+}>, readNames: ReadonlySet<string>): number;
+//# sourceMappingURL=skill-reads.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.8.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },