@lmzhen/dsh-tool-skill-manage 0.8.0 → 0.10.0

package/README.md

@@ -6,15 +6,44 @@ library nor its lifecycle rules.
 
 ## Model surface
 
-- **Model-visible:** the `skill_manage` tool schema and its success/validation messages; result tokens scale with what is returned.
+- **Model-visible:** the `skill_manage` tool schema and its success/validation messages; result tokens scale with what is returned. The skills-guidance section (`evolution-skills-guidance`) ends with the policy's protected-skill list, carried by the prompt variable `evolution_skill_guard`: the provider runs at EVERY assembly (a policy change needs no reload), and an empty list leaves the section byte-identical to the guidance alone, so the guidance's prefix-cache behaviour is unchanged.
 - **Prompt prefix / KV cache:** the tool schema is prefix-stable, and skill writes do not alter the current request prompt; catalog invalidation affects the next request; family rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
 - **Mount it?** yes — the `tool-skill-manage` row, carried by the `evolution-all` and one-click `evolution-preset` bundles and the Evolution agent preset delta.
 
 ## Safety model
 
+### Write gates
+
+Every mutation THROUGH THIS TOOL passes ONE ordered admission sequence (`src/write-gates.ts`): the
+scalar argument shape, the required arguments per action, the policy's protected list,
+read-before-write, and the operator confirmation. The
+ADMISSION point runs the sequence before the approval seam, so a write that is refused is never
+staged for approval and never spends the operator's attention; the EXECUTION point (`executeCore`)
+re-runs the gates a replay or a direct write can still fail, because a replay's stored arguments
+passed no schema and the protected list can change while a record sits pending. Both points read the
+same table, so they cannot diverge.
+
+The sequence covers the MODEL tool path. The family's other writers reach their own library
+handles: the `/evolution` and `/graph` command face writes what the operator typed (the operator is
+the authority there), the review's plan executor writes a plan its own filter already screened
+(`filterUnreadSkillOps`), and a record staged outside this tool replays into the execution point
+without re-deciding the admission-only gates — there is no writing session to read.
+
+Read-before-write is admission-only (the replayed record has no writing session): a non-foreground
+write whose target the session never read is refused with `E-318`, and only a read that did not fail
+counts. A session log the tool cannot read proceeds with one warning rather than blocking every
+autonomous write.
+
+A foreground `create`, or a bare foreground `delete`, asks the operator once before it writes and is
+refused with `E-317` when the answer is not the confirm label; a `delete` carrying `absorbed_into` is the
+merge protocol and does not ask. This gate is UX, not a security door: it is admission-only (a
+replayed record already carries the human release that staged it), and an unmounted question
+service, a caller that is not the registry's exact live root agent, or a failing ask all PROCEED
+with one warning — the operator's own session stays the authority that asked for the write.
+
 ### Approval seam
 
-Mutations (create/edit/update/patch/delete/write_file/remove_file/restructure) pass through the evolution approval seam when `evolution-approval` is mounted; approved/staged writes are replayed by the registered runner with the library origin preserved. The missing-required-argument pre-check runs BEFORE that boundary — one shared table and one refusal builder with `executeCore`, so the stage boundary and the execution check cannot diverge: a write that cannot execute is refused, never staged for approval.
+Mutations (create/edit/update/patch/delete/write_file/remove_file/restructure) pass through the evolution approval seam when `evolution-approval` is mounted; approved/staged writes are replayed by the registered runner with the library origin preserved. The admission gates run BEFORE that boundary, so a write that cannot execute is refused, never staged for approval.
 
 ### pin/unpin: explicit exception
 
@@ -29,6 +58,42 @@ Mutations (create/edit/update/patch/delete/write_file/remove_file/restructure) p
   per user. Reading the legacy name still works; writing it is refused. Removal was planned for 0.7.0 and is deferred:
   the alias still ships, so no later version is claimed here.
 
+### Description length: the three numbers
+
+A skill description is measured against three different bounds. They are not interchangeable, and
+only the second one refuses a write:
+
+| Bound | Value | Source | What it does |
+|---|---|---|---|
+| Authoring bar | 60 chars | `AUTHORING_DESCRIPTION_BAR` (the upstream 60-char rule) | advisory feedback on every create/edit/update; `descriptionStrict: true` turns it into a refusal |
+| Family storage ceiling | 1024 chars | `MAX_DESCRIPTION_LENGTH`, lowered per deployment by this row's `maxDescriptionLength` | the hard validation limit — the ONLY refusal threshold of the three |
+| Platform catalog view | 500 chars by default | `catalogDescriptionMaxLength` on the platform's `tool-skill` row (`PLATFORM_CATALOG_DESCRIPTION_DEFAULT`) | truncates the description in the skill catalog the model reads; the family's own rows set that field to 60 (`evolution-host`, `evolution-all` and `evolution-preset` each carry it, and the composer injects it onto a generated preset row too), so 500 governs only a composition that overrides none of them; `packages/README.md` states which of those rows takes effect per install form |
+
+The third row is a view, not a rule: a description the family accepts can still be cut in a catalog
+viewer, which is why the authoring feedback names the bar rather than treating the cut as a limit.
+
+### The create-time duplicate hint
+
+A `create` compares its candidate against the library listing before it writes, over the name +
+description projection (core `nearDuplicateSummaries`, at `SUMMARY_DUPLICATE_HINT_THRESHOLD`), and
+names the closest existing skills in the same "Authoring check" block. Three properties are
+deliberate: it adds no read of its own (`library.list()` already reads every SKILL.md to parse
+its frontmatter — that listing is what publishes `description` — and the hint never calls
+`library.read`, never holds a body and never compares content); it is a HINT (the write proceeds
+— only the model's next decision changes); and a listing failure degrades to a named line instead of
+silence, because "nothing similar was checked" and "nothing similar exists" must not look alike. The
+library-wide BODY scan stays where it was, in the `review` action.
+
+### The retention line
+
+A whole-body replacement that keeps less than half of the previous SKILL.md says so in the same result
+message (`Content kept 26% of the previous body (2104 of 8123 characters); the replaced version is
+preserved in this skill's history.`). It is computed where the write path still holds both bodies — the
+library's own in-lock read, core `contentRetentionFeedback` — because a caller re-reading the file
+would race the writers the library serializes. Like the duplicate hint it is FEEDBACK, not a gate: no ratio
+refuses a write, small skills stay quiet (a 40-character skill cut in half is not news), and patches,
+support-file writes, creates and archives have no ratio to report.
+
 ## Known limitations
 
 - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.

package/lib/index.js

@@ -1,7 +1,171 @@
 import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, authoringFeedback, callingScope, clampedNumber, computeDedupGroups, contentHash, evolutionIoAdapter, installParamSection, isPresent, isUnknown, newSkillLibrary, paramNamespace, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, readNumberParam, resolveExecOrigins } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, authoringFeedback, callingScope, clampedNumber, computeDedupGroups, contentHash, errorText, evolutionIoAdapter, installParamSection, isPresent, isUnknown, isUnreadWrite, nearDuplicateSummaries, newSkillLibrary, paramNamespace, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, readNumberParam, resolveExecOrigins, sessionReadSkillNames } from "@lmzhen/dsh-evolution-core";
+//#region lib/types/write-gates.js
+/**
+* The write-admission sequence: ONE ordered table of the reasons a skill write is refused.
+*
+* Two points read this table (design `dsh-evolution-write-gate-design.md` §3). The ADMISSION
+* point (`execute`, BEFORE the approval seam) runs every gate that applies to `'admission'`, so a
+* write that is refused is never staged and never spends the operator's attention twice. The
+* EXECUTION point (the `executeCore` funnel, reached by the direct path and by the approval
+* replay) runs the gates that apply to `'execution'`: the stored plan of a replayed write passed
+* no schema, and the protected list can change while a record sits pending, so those verdicts are
+* re-decided at the bytes.
+*
+* Order is part of the contract: a gate that can only refuse comes before one that needs a round
+* trip with the operator, so a write that is refused anyway never asks anything.
+*
+* A gate decides whether a write may be ATTEMPTED. The library decides whether it can be
+* PERFORMED — its own structured refusals (a restructure element that is not an object, a patch
+* anchor that no longer matches, an `absorbed_into` that does not exist) stay where the bytes are
+* read.
+*
+* Rule bodies live in `evolution-core` (the read-before-write rule in `skill-reads`, the
+* required-argument table in `SKILL_ACTION_REQUIRED_FIELDS`); this module owns the ORDER and the
+* applicability of each gate, which is an execution-point fact of this tool.
+* @module @lmzhen/dsh-tool-skill-manage/write-gates
+*/
+/** The confirm question's stable id — one question per write, so an answer to an earlier prompt
+* can never be read as the answer to a later one. */
+const CONFIRM_QUESTION_ID = "evolution-skill-write";
+/** The cancel label every confirm question offers. */
+const CANCEL_LABEL = "Cancel";
+/** The scalar fields the tool schema types as strings; the replay channel has no schema.
+* `action` is one of them: a non-string action used to fall through to the library as "Unknown
+* action" while the read gate re-defaulted it to `patch` and refused with E-318 (review
+* 2026-09-26, P2), so the shape gate refuses it by name instead. */
+const SCALAR_ARG_FIELDS = [
+	"action",
+	"name",
+	"content",
+	"old_string",
+	"new_string",
+	"file_path",
+	"file_content",
+	"absorbed_into"
+];
+/**
+* Narrow the arguments once for every gate.
+*
+* The admission point reaches the gates AFTER the schema, the replay channel BEFORE any
+* validation, so a gate reads only what it can prove: anything else counts as absent, exactly as
+* the missing-argument check already treated a non-string action.
+* @param args - the arguments as the caller sent them.
+* @returns the narrowed view.
+*/
+function gateArgsOf(args) {
+	const scalars = typeof args === "object" && args !== null ? args : {};
+	const action = scalars.action;
+	const name = scalars.name;
+	const absorbedInto = scalars.absorbed_into;
+	return {
+		action: typeof action === "string" ? action : void 0,
+		name: typeof name === "string" ? name : "",
+		absorbedInto: typeof absorbedInto === "string" && absorbedInto.trim() !== "" ? absorbedInto : void 0,
+		scalars
+	};
+}
+/** The sequence, in order. A gate whose `appliesTo` omits the asking point is skipped. */
+const GATES = [
+	{
+		id: "argument-shape",
+		appliesTo: ["admission", "execution"],
+		run: ({ view }) => {
+			for (const field of SCALAR_ARG_FIELDS) {
+				const value = view.scalars[field];
+				if (value === void 0 || value === null || typeof value === "string") continue;
+				return `skill_manage: "${field}" must be a string (got ${typeof value}); refusing the write.`;
+			}
+			return null;
+		}
+	},
+	{
+		id: "missing-args",
+		appliesTo: ["admission", "execution"],
+		run: ({ view }) => {
+			const action = view.action;
+			const missing = (action === void 0 || !Object.hasOwn(SKILL_ACTION_REQUIRED_FIELDS, action) ? [] : SKILL_ACTION_REQUIRED_FIELDS[action] ?? []).filter((field) => view.scalars[field] === void 0 || view.scalars[field] === null);
+			if (missing.length === 0) return null;
+			return `skill_manage ${action} requires ${missing.join(", ")}; the tool description lists the arguments per action.`;
+		}
+	},
+	{
+		id: "policy-protection",
+		appliesTo: ["admission", "execution"],
+		run: ({ view, origin, protectedNames }) => {
+			if (origin === "foreground") return null;
+			if (view.name === "" || !protectedNames?.includes(view.name)) return null;
+			return `skill_manage: "${view.name}" is protected by the current policy (protectedSkillNames); replayed/autonomous writes are refused.`;
+		}
+	},
+	{
+		id: "read-before-write",
+		appliesTo: ["admission"],
+		run: ({ view, origin, readNames, warn }) => {
+			if (origin === "foreground") return null;
+			if (readNames === void 0) {
+				warn("skill_manage: the read-before-write check could not run for this call — the session log is not readable here, so the write is allowed.");
+				return null;
+			}
+			if (view.action === void 0) return null;
+			if (!isUnreadWrite({
+				action: view.action,
+				name: view.name
+			}, readNames)) return null;
+			return errorText("e-318-skill-write-without-a-read", { a1: view.name });
+		}
+	},
+	{
+		id: "human-confirm",
+		appliesTo: ["admission"],
+		run: async ({ view, origin, confirm, warn }) => {
+			const action = view.action;
+			if (action === void 0 || origin !== "foreground" || view.name === "") return null;
+			if (!(action === "create" || action === "delete" && view.absorbedInto === void 0)) return null;
+			if (confirm === void 0) {
+				warn("skill_manage: no confirmation channel is mounted, so the write proceeds unconfirmed.");
+				return null;
+			}
+			const confirmLabel = action === "create" ? "Create" : "Delete";
+			if (await confirm({
+				action,
+				name: view.name,
+				confirmLabel,
+				question: {
+					id: CONFIRM_QUESTION_ID,
+					header: "Confirm",
+					question: action === "create" ? `Create skill "${view.name}"? A new skill directory is written into the family tree.` : `Delete skill "${view.name}"? It is archived under .archive and leaves the catalog.`,
+					options: [{ label: confirmLabel }, { label: CANCEL_LABEL }]
+				}
+			})) return null;
+			return errorText("e-317-skill-write-not-confirmed", {
+				a1: view.name,
+				a2: action === "create" ? "created" : "deleted"
+			});
+		}
+	}
+];
+/**
+* Run the sequence for one write attempt.
+* @param context - the asking point, the write, and the seams the human-facing gate needs.
+* @returns the FIRST refusal, or null when every applicable gate passed. Both points return the
+*   message as the tool result unchanged, so the two entries refuse with identical wording.
+*/
+async function runWriteGates(context) {
+	const input = {
+		...context,
+		view: gateArgsOf(context.args)
+	};
+	for (const gate of GATES) {
+		if (!gate.appliesTo.includes(context.point)) continue;
+		const refusal = await gate.run(input);
+		if (refusal !== null) return refusal;
+	}
+	return null;
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Model-facing skill_manage tool over ctx.evolutionIo + ctx.skillUsage.
@@ -31,6 +195,16 @@ const inject = [
 /** 0.3.18 (E-70): review output lists at most this many near-duplicate groups
 * (a cap, not a per-group limit) — the one named bound for the slice below. */
 const MAX_DEDUP_GROUPS_IN_REVIEW = 3;
+/** B4 (design §4.3): the prompt variable that carries the protected-skill list into the guidance
+* section. Names must match the platform's `[a-z][a-z0-9_]*` reference syntax. */
+const PROTECTED_SKILLS_VARIABLE = "evolution_skill_guard";
+/** Names shown inline before the line collapses to a count — the guidance is in EVERY request, so
+* the line is bounded even when the policy protects a long list. */
+const PROTECTED_SKILLS_INLINE_MAX = 12;
+/** The guidance section's text: `SKILLS_GUIDANCE` followed by the variable reference. Composed HERE
+* rather than inside the core constant, because the review prompts share that constant and no
+* variable is registered for them. */
+const GUIDANCE_WITH_GUARD = `${SKILLS_GUIDANCE}{{${PROTECTED_SKILLS_VARIABLE}}}`;
 const Config = z.object({
 	root: z.string().default(""),
 	maxSkillNameLength: z.number().min(1).default(DEFAULT_SKILL_LIMITS.maxNameLength),
@@ -39,7 +213,8 @@ const Config = z.object({
 	maxSkillFileBytes: z.number().min(1).default(DEFAULT_SKILL_LIMITS.maxSkillFileBytes),
 	descriptionStrict: z.boolean().default(false),
 	threatExemptLabels: z.array(z.string()).default([]),
-	strictCrossSource: z.boolean().default(false)
+	strictCrossSource: z.boolean().default(false),
+	skillVersionKeep: z.number().min(1).default(DEFAULT_SKILL_LIMITS.versionKeep ?? DEFAULT_SKILL_VERSION_KEEP)
 });
 /** Schema the platform validates the user layer against; defaults mirror the core
 * constants and the row schema, so an empty document resolves to today's behaviour. */
@@ -70,31 +245,126 @@ const SKILL_SETTINGS_CAPS = [
 function validateSkillSettings(value, ceilings) {
 	for (const key of SKILL_SETTINGS_CAPS) if (value[key] > ceilings[key]) throw new Error(`${key} may only be tightened: ${value[key]} exceeds the deployment value ${ceilings[key]}`);
 }
+/** The platform error code a question-service failure carries, when it carries one. */
+function questionErrorCode(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** The message of a caught platform error, for the one warning a degraded gate emits. */
+function reasonOfError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* The registry's live ROOT agent for this call's session, or `undefined`.
+*
+* The registry keys agents by their shared agent/session id (platform `agent/src/index.ts:567`), and
+* the platform's `ask()` accepts only an agent that is BOTH its exact live instance and a root
+* (platform `user-questions/src/index.ts:96-106`). An id that resolves to an agent owned by another
+* agent is not a root: the caller then proceeds unconfirmed rather than blocking a human question on
+* an agent no human is watching.
+* @param probe - the context, read through the optional-service probe.
+* @param exec - this call's execution context.
+* @returns the live root agent, when this session has one.
+*/
+function liveRootAgentOf(probe, exec) {
+	const agents = probe.get("agents");
+	const sessionId = exec.agent?.session?.id;
+	if (agents === void 0 || typeof sessionId !== "string") return void 0;
+	const candidate = agents.get(sessionId);
+	return candidate !== void 0 && agents.roots().includes(candidate) ? candidate : void 0;
+}
+/** The one thing the operator's answer decides: was the confirm label selected? */
+function confirmedBy(answer, questionId, confirmLabel) {
+	return (answer.answers.find((entry) => entry.id === questionId)?.selected ?? []).includes(confirmLabel);
+}
 /** v30 REV-02: read the protected-skill list off the (optional) policy
 * snapshot through an `unknown` boundary — the Context augmentation types the
 * getter non-optionally, but at runtime the row can be absent. */
 function policySnapshotOf(source) {
 	return source?.get?.();
 }
-function missingRequiredArgs(args) {
-	const action = args.action;
-	const scalarArgs = args;
-	return (action === void 0 || typeof action !== "string" || !Object.hasOwn(SKILL_ACTION_REQUIRED_FIELDS, action) ? [] : SKILL_ACTION_REQUIRED_FIELDS[action] ?? []).filter((field) => scalarArgs[field] === void 0 || scalarArgs[field] === null);
-}
-function missingArgsRefusal(action, missing) {
-	return {
-		ok: false,
-		message: `skill_manage ${action} requires ${missing.join(", ")}; the tool description lists the arguments per action.`,
-		skills: []
-	};
-}
 function apply(ctx, rawConfig = {}) {
 	const systemPrompt = ctx.get("systemPrompt");
-	if (systemPrompt) ctx.effect(() => systemPrompt.section({
-		name: "evolution-skills-guidance",
-		order: SKILLS_GUIDANCE_SECTION_ORDER,
-		text: SKILLS_GUIDANCE
-	}), "tool-skill-manage.skills-guidance");
+	if (systemPrompt) ctx.effect(() => {
+		const disposeVariable = systemPrompt.variable(PROTECTED_SKILLS_VARIABLE, () => protectedSkillsLine());
+		const disposeSection = systemPrompt.section({
+			name: "evolution-skills-guidance",
+			order: SKILLS_GUIDANCE_SECTION_ORDER,
+			text: GUIDANCE_WITH_GUARD
+		});
+		return () => {
+			disposeSection();
+			disposeVariable();
+		};
+	}, "tool-skill-manage.skills-guidance");
+	/** The policy snapshot's protected list, or `undefined` when the row is not mounted — read by
+	* the write gates at BOTH points, through the one unknown-boundary helper above. */
+	const protectedSkillNamesOf = () => policySnapshotOf(ctx.get("evolutionPolicy"))?.protectedSkillNames;
+	/**
+	* The protected-skill line appended to the skills guidance (B4, design §4.3).
+	*
+	* The list is otherwise visible only to the REVIEW prompts, so the tool-path model could learn a
+	* name was protected only by having a write refused — this line is what lets it avoid the call.
+	* It returns `''` — never `undefined`, which the platform refuses to render — when no policy
+	* row is mounted or nothing is protected, and the empty value leaves the section byte-identical
+	* to the guidance alone, so the guidance's prefix-cache stability is untouched.
+	* @returns the line including the newline that joins it to the guidance.
+	*/
+	const protectedSkillsLine = () => {
+		try {
+			const names = protectedSkillNamesOf() ?? [];
+			if (names.length === 0) return "";
+			const shown = names.slice(0, PROTECTED_SKILLS_INLINE_MAX);
+			const rest = names.length - shown.length;
+			return `\nProtected skills (do not edit): ${shown.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}`;
+		} catch {
+			return "";
+		}
+	};
+	let writeGateWarned = false;
+	const warnWriteGateOnce = (message) => {
+		if (writeGateWarned) return;
+		writeGateWarned = true;
+		ctx.logger.warn(message);
+	};
+	const probe = ctx;
+	let confirmWarned = false;
+	const confirmUnavailable = (reason) => {
+		if (!confirmWarned) {
+			confirmWarned = true;
+			ctx.logger.warn(`skill_manage: the confirmation prompt could not be shown (${reason}) — the write proceeds unconfirmed.`);
+		}
+		return true;
+	};
+	const isDismissed = (error) => questionErrorCode(error) === "ASK_ABORTED";
+	const confirmSkillWrite = async (request, exec) => {
+		const questions = probe.get("userQuestions");
+		if (questions === void 0) return confirmUnavailable("no user-questions service is mounted");
+		const ask = (agent) => questions.ask({
+			questions: [{
+				id: request.question.id,
+				header: request.question.header,
+				question: request.question.question,
+				options: request.question.options.map((option) => ({ label: option.label }))
+			}],
+			agent,
+			...exec.signal !== void 0 ? { signal: exec.signal } : {}
+		});
+		const declared = exec.agent;
+		if (declared !== void 0) try {
+			return confirmedBy(await ask(declared), request.question.id, request.confirmLabel);
+		} catch (error) {
+			if (isDismissed(error)) return false;
+			if (questionErrorCode(error) !== "CALLER_NOT_LIVE") return confirmUnavailable(reasonOfError(error));
+		}
+		const located = liveRootAgentOf(probe, exec);
+		if (located === void 0) return confirmUnavailable("the calling session has no live root agent");
+		try {
+			return confirmedBy(await ask(located), request.question.id, request.confirmLabel);
+		} catch (error) {
+			return isDismissed(error) ? false : confirmUnavailable(reasonOfError(error));
+		}
+	};
 	const io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
 	const numericClamped = [];
 	const limit = (name, value, fallback) => {
@@ -107,7 +377,8 @@ function apply(ctx, rawConfig = {}) {
 		maxNameLength: limit("maxSkillNameLength", rawConfig.maxSkillNameLength, DEFAULT_SKILL_LIMITS.maxNameLength),
 		maxDescriptionLength: limit("maxDescriptionLength", rawConfig.maxDescriptionLength, DEFAULT_SKILL_LIMITS.maxDescriptionLength),
 		maxSkillContentChars: limit("maxSkillContentChars", readNumberParam(rawConfig, "skillContentChars"), DEFAULT_SKILL_LIMITS.maxSkillContentChars),
-		maxSkillFileBytes: limit("maxSkillFileBytes", rawConfig.maxSkillFileBytes, DEFAULT_SKILL_LIMITS.maxSkillFileBytes)
+		maxSkillFileBytes: limit("maxSkillFileBytes", rawConfig.maxSkillFileBytes, DEFAULT_SKILL_LIMITS.maxSkillFileBytes),
+		versionKeep: limit("skillVersionKeep", rawConfig.skillVersionKeep, DEFAULT_SKILL_LIMITS.versionKeep ?? DEFAULT_SKILL_VERSION_KEEP)
 	};
 	const library = newSkillLibrary({
 		config: rawConfig,
@@ -238,38 +509,28 @@ function apply(ctx, rawConfig = {}) {
 				skills: []
 			};
 		}
-		const scalarArgs = args;
-		for (const field of [
-			"name",
-			"content",
-			"old_string",
-			"new_string",
-			"file_path",
-			"file_content",
-			"absorbed_into"
-		]) {
-			const value = scalarArgs[field];
-			if (value !== void 0 && value !== null && typeof value !== "string") return {
-				ok: false,
-				message: `skill_manage: "${field}" must be a string (got ${typeof value}); refusing the write.`,
-				skills: []
-			};
-		}
-		if (origin !== "foreground") {
-			if ((policySnapshotOf(ctx.get("evolutionPolicy"))?.protectedSkillNames)?.includes(name)) return {
-				ok: false,
-				message: `skill_manage: "${name}" is protected by the current policy (protectedSkillNames); replayed/autonomous writes are refused.`,
-				skills: []
-			};
-		}
-		const missing = missingRequiredArgs(args);
-		if (missing.length > 0) return missingArgsRefusal(action, missing);
+		const refusal = await runWriteGates({
+			point: "execution",
+			args,
+			origin,
+			protectedNames: protectedSkillNamesOf(),
+			readNames: void 0,
+			confirm: void 0,
+			warn: warnWriteGateOnce
+		});
+		if (refusal !== null) return {
+			ok: false,
+			message: refusal,
+			skills: []
+		};
 		let feedbackLines = [];
 		const stagedAnchor = typeof args.staged_from_sha256 === "string" && args.staged_from_sha256 !== "" ? args.staged_from_sha256 === "absent" ? { absent: true } : { sha256: args.staged_from_sha256 } : void 0;
+		let candidateDescription = "";
 		if ((action === "create" || action === "edit" || action === "update") && args.content) {
 			const parsed = parseFrontmatter(args.content);
 			if (parsed) {
 				const feedback = authoringFeedback(parsed.frontmatter);
+				candidateDescription = parsed.frontmatter.description ?? "";
 				feedbackLines = feedback.lines;
 				if (settings().descriptionStrict && feedback.over60) return {
 					ok: false,
@@ -279,8 +540,10 @@ function apply(ctx, rawConfig = {}) {
 			}
 		}
 		let result;
-		if (action === "create") result = await library.create(name, args.content ?? "", origin);
-		else if (action === "edit" || action === "update") result = await library.update(name, args.content ?? "", origin, stagedAnchor);
+		if (action === "create") {
+			feedbackLines.push(...await duplicateHintLines(name, candidateDescription));
+			result = await library.create(name, args.content ?? "", origin);
+		} else if (action === "edit" || action === "update") result = await library.update(name, args.content ?? "", origin, stagedAnchor);
 		else if (action === "patch") result = await library.patch(name, args.old_string ?? "", args.new_string ?? "", args.file_path ?? "", args.replace_all === true, origin);
 		else if (action === "delete") result = await library.archive(name, args.absorbed_into ? { absorbedInto: args.absorbed_into } : {});
 		else if (action === "write_file") result = await library.writeSupportFile(name, args.file_path ?? "", args.file_content ?? "", origin, stagedAnchor);
@@ -322,6 +585,39 @@ function apply(ctx, rawConfig = {}) {
 			skills: []
 		};
 	}
+	/** Batch C (2026-09-27, design §3C-2): the create-time near-duplicate hint — one
+	* line naming the existing skill(s) this candidate is about to near-copy, over
+	* core's `summary` projection (name + description). Three properties are the
+	* design's, not stylistic choices:
+	*
+	*   - It adds NO read of its own. `library.list()` reads each SKILL.md to parse its
+	*     frontmatter — that listing is what publishes `description` — and the hint never
+	*     calls `library.read`, never holds a body and never compares content, so a create
+	*     pays no SECOND whole-tree pass for it.
+	*   - It is a HINT: the write proceeds either way (G4 — create's foreground
+	*     behavior is unchanged). The model gets the news, not a refusal.
+	*   - A failed listing degrades to a NAMED line, never to silence: "nothing
+	*     similar was checked" and "nothing similar exists" must not look alike
+	*     (the PLAN-R2 P2-5 posture the review path already takes).
+	*
+	* The level and the math live in core (`nearDuplicateSummaries`,
+	* `SUMMARY_DUPLICATE_HINT_THRESHOLD`) — this function owns the wording only. */
+	async function duplicateHintLines(name, description) {
+		let matches;
+		try {
+			matches = nearDuplicateSummaries({
+				candidate: {
+					name,
+					description
+				},
+				existing: await library.list()
+			});
+		} catch (error) {
+			return [`Duplicate check skipped: the skill listing failed (${error instanceof Error ? error.message : String(error)}).`];
+		}
+		if (matches.length === 0) return [];
+		return [`Near-duplicate of existing skill(s): ${matches.map((match) => `${match.name} (${match.score.toFixed(2)})`).join(", ")} — prefer patch/update on that skill over adding a near-copy.`];
+	}
 	async function buildSkillReviewText() {
 		const list = await library.list();
 		const report = await ctx.skillUsage.report();
@@ -445,8 +741,20 @@ function apply(ctx, rawConfig = {}) {
 					skills: []
 				};
 			}
-			const missing = missingRequiredArgs(args);
-			if (missing.length > 0) return missingArgsRefusal(args.action, missing);
+			const refusal = await runWriteGates({
+				point: "admission",
+				args,
+				origin: libraryOrigin,
+				protectedNames: protectedSkillNamesOf(),
+				readNames: sessionReadSkillNames(exec.agent?.session),
+				confirm: async (request) => confirmSkillWrite(request, exec),
+				warn: warnWriteGateOnce
+			});
+			if (refusal !== null) return {
+				ok: false,
+				message: refusal,
+				skills: []
+			};
 			const approval = ctx.get("evolutionApproval");
 			if (approval && args.action !== "list" && args.action !== "review" && args.action !== "pin" && args.action !== "unpin") {
 				if ((args.action === "update" || args.action === "edit") && typeof args.name === "string" && args.name !== "") {

package/lib/types/index.d.ts

@@ -46,6 +46,10 @@ export interface Config {
      * the family tree) is REFUSED instead of warned about. Default false —
      * warn only, keeping the family tree an autonomous evolution zone. */
     strictCrossSource?: boolean;
+    /** Content versions retained per skill (skill-history.ts). E2: a deployment value on this row,
+     * like the four caps above — the settings layer deliberately has no card for it (retention is
+     * storage policy, not an authoring knob). */
+    skillVersionKeep?: number;
 }
 export declare const Config: z<Config>;
 /** Write behaviour a user may change (G3/S3.4). Field names are the CANONICAL

package/lib/types/write-gates.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The write-admission sequence: ONE ordered table of the reasons a skill write is refused.
+ *
+ * Two points read this table (design `dsh-evolution-write-gate-design.md` §3). The ADMISSION
+ * point (`execute`, BEFORE the approval seam) runs every gate that applies to `'admission'`, so a
+ * write that is refused is never staged and never spends the operator's attention twice. The
+ * EXECUTION point (the `executeCore` funnel, reached by the direct path and by the approval
+ * replay) runs the gates that apply to `'execution'`: the stored plan of a replayed write passed
+ * no schema, and the protected list can change while a record sits pending, so those verdicts are
+ * re-decided at the bytes.
+ *
+ * Order is part of the contract: a gate that can only refuse comes before one that needs a round
+ * trip with the operator, so a write that is refused anyway never asks anything.
+ *
+ * A gate decides whether a write may be ATTEMPTED. The library decides whether it can be
+ * PERFORMED — its own structured refusals (a restructure element that is not an object, a patch
+ * anchor that no longer matches, an `absorbed_into` that does not exist) stay where the bytes are
+ * read.
+ *
+ * Rule bodies live in `evolution-core` (the read-before-write rule in `skill-reads`, the
+ * required-argument table in `SKILL_ACTION_REQUIRED_FIELDS`); this module owns the ORDER and the
+ * applicability of each gate, which is an execution-point fact of this tool.
+ * @module @lmzhen/dsh-tool-skill-manage/write-gates
+ */
+import { type WriteOrigin } from '@lmzhen/dsh-evolution-core';
+/** The point whose verdict is being taken. */
+export type WriteGatePoint = 'admission' | 'execution';
+/** One confirm question, as the gate writes it and the seam asks it. */
+export interface WriteConfirmRequest {
+    /** The action being confirmed (`create` or `delete`). */
+    readonly action: string;
+    /** The skill the write would create or archive. */
+    readonly name: string;
+    /** The question for the operator: the options are the confirm label, then the cancel label. */
+    readonly question: {
+        readonly id: string;
+        readonly header: string;
+        readonly question: string;
+        readonly options: readonly {
+            readonly label: string;
+        }[];
+    };
+    /** The option label that means "proceed". */
+    readonly confirmLabel: string;
+}
+/**
+ * Ask the human to confirm one irreversible skill write.
+ *
+ * MUST be total: an implementation resolves every unavailability — no question service, no live root
+ * agent, a failing ask — to `true`, because this gate is an operator convenience and no failure of the
+ * question service may block the operator's own write. `false` means the human answered something
+ * other than the confirm label.
+ * @param request - the question to put to the operator and the label that means "proceed".
+ * @returns true to proceed with the write.
+ */
+export type WriteConfirm = (request: WriteConfirmRequest) => Promise<boolean>;
+/** What every gate reads. */
+export interface WriteGateContext {
+    /** The point asking: the tool's admission of a call, or its execution at the bytes. */
+    readonly point: WriteGatePoint;
+    /** The parsed (admission) or stored (replay) arguments — unvalidated, hence the shape gate. */
+    readonly args: unknown;
+    /** The library write origin: `foreground` is the operator's own session. */
+    readonly origin: WriteOrigin;
+    /** The policy snapshot's protected list; `undefined` when no policy row is mounted. */
+    readonly protectedNames: readonly string[] | undefined;
+    /** Names this session read successfully; `undefined` when the session log is not readable. */
+    readonly readNames: ReadonlySet<string> | undefined;
+    /** The human confirm seam — read only by the gates that apply to `'admission'`. */
+    readonly confirm: WriteConfirm | undefined;
+    /** Report a degraded gate; must not throw. The implementation decides how often it speaks — the
+     * shipped seam latches once per PROCESS, because the conditions it reports (no question service,
+     * an unreadable session log) belong to the deployment, not to one write. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Run the sequence for one write attempt.
+ * @param context - the asking point, the write, and the seams the human-facing gate needs.
+ * @returns the FIRST refusal, or null when every applicable gate passed. Both points return the
+ *   message as the tool result unchanged, so the two entries refuse with identical wording.
+ */
+export declare function runWriteGates(context: WriteGateContext): Promise<string | null>;
+//# sourceMappingURL=write-gates.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-tool-skill-manage",
   "description": "Model-facing skill_manage tool (community build)",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,24 +27,24 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.8.0",
-    "@lmzhen/dsh-evolution-core": "^0.8.0"
+    "@lmzhen/dsh-evolution-approval": "^0.10.0",
+    "@lmzhen/dsh-evolution-core": "^0.10.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.8.0",
-    "@lmzhen/dsh-skill-usage": "^0.8.0"
+    "@lmzhen/dsh-evolution-io": "^0.10.0",
+    "@lmzhen/dsh-skill-usage": "^0.10.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.8.0",
-    "@lmzhen/dsh-evolution-io": "^0.8.0",
-    "@lmzhen/dsh-skill-usage": "^0.8.0"
+    "@lmzhen/dsh-evolution-core": "^0.10.0",
+    "@lmzhen/dsh-evolution-io": "^0.10.0",
+    "@lmzhen/dsh-skill-usage": "^0.10.0"
   }
 }