@lmzhen/dsh-tool-skill-manage 0.7.0 → 0.9.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,20 @@ 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.
+
 ## 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, PARAM_NAMESPACES, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, authoringFeedback, callingScope, clampedNumber, computeDedupGroups, contentHash, evolutionIoAdapter, installParamSection, isPresent, isUnknown, newSkillLibrary, 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_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, 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),
@@ -41,8 +215,6 @@ const Config = z.object({
 	threatExemptLabels: z.array(z.string()).default([]),
 	strictCrossSource: z.boolean().default(false)
 });
-/** Namespace the write caps and the four stage policies live in (core's PARAM_NAMESPACES). */
-const SKILLS_SETTINGS_NAMESPACE = "evolution-skills";
 /** 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. */
 const SKILLS_SETTINGS_SCHEMA = z.object({
@@ -72,31 +244,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) => {
@@ -160,7 +427,7 @@ function apply(ctx, rawConfig = {}) {
 			supportFileCharPolicy: resolved.supportFileCharPolicy
 		});
 	};
-	section.overrides = installParamSection(ctx, PARAM_NAMESPACES["tool-skill-manage"] ?? "evolution-skills", SKILLS_SETTINGS_SCHEMA, settingsBase, {
+	section.overrides = installParamSection(ctx, paramNamespace("tool-skill-manage"), SKILLS_SETTINGS_SCHEMA, settingsBase, {
 		warn: (message) => {
 			ctx.logger.warn("dsh-evolution-skills: " + message);
 		},
@@ -240,32 +507,20 @@ 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;
 		if ((action === "create" || action === "edit" || action === "update") && args.content) {
@@ -447,8 +702,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 !== "") {
@@ -507,4 +774,4 @@ function apply(ctx, rawConfig = {}) {
 	});
 }
 //#endregion
-export { Config, SKILLS_SETTINGS_NAMESPACE, SKILLS_SETTINGS_SCHEMA, SKILL_SETTINGS_CAPS, apply, inject, name, validateSkillSettings };
+export { Config, SKILLS_SETTINGS_SCHEMA, SKILL_SETTINGS_CAPS, apply, inject, name, validateSkillSettings };

package/lib/types/index.d.ts

@@ -48,8 +48,6 @@ export interface Config {
     strictCrossSource?: boolean;
 }
 export declare const Config: z<Config>;
-/** Namespace the write caps and the four stage policies live in (core's PARAM_NAMESPACES). */
-export declare const SKILLS_SETTINGS_NAMESPACE = "evolution-skills";
 /** Write behaviour a user may change (G3/S3.4). Field names are the CANONICAL
  * parameter ids from the registry. The four caps are TIGHTEN-ONLY: the settings
  * `validate` hook refuses a value above what the deployment allocated, because

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.7.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,24 +27,24 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.7.0",
-    "@lmzhen/dsh-evolution-core": "^0.7.0"
+    "@lmzhen/dsh-evolution-approval": "^0.9.0",
+    "@lmzhen/dsh-evolution-core": "^0.9.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.7.0",
-    "@lmzhen/dsh-skill-usage": "^0.7.0"
+    "@lmzhen/dsh-evolution-io": "^0.9.0",
+    "@lmzhen/dsh-skill-usage": "^0.9.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.7.0",
-    "@lmzhen/dsh-evolution-io": "^0.7.0",
-    "@lmzhen/dsh-skill-usage": "^0.7.0"
+    "@lmzhen/dsh-evolution-core": "^0.9.0",
+    "@lmzhen/dsh-evolution-io": "^0.9.0",
+    "@lmzhen/dsh-skill-usage": "^0.9.0"
   }
 }