@lmzhen/dsh-evolution-core 0.1.0-rc.21 → 0.1.0-rc.23

package/lib/index.js

@@ -20,7 +20,11 @@ function evolutionIoAdapter(provider) {
 		list: (path) => provider().list(path),
 		exists: (path) => provider().exists(path),
 		rename: (path, destination) => provider().rename(path, destination),
-		copy: (path, destination) => provider().copy(path, destination)
+		copy: (path, destination) => provider().copy(path, destination),
+		size: (path) => {
+			const io = provider();
+			return io.size ? io.size(path) : Promise.resolve(null);
+		}
 	};
 }
 function nodeEvolutionIo() {
@@ -69,6 +73,13 @@ function nodeEvolutionIo() {
 				recursive: true,
 				force: true
 			});
+		},
+		async size(path) {
+			try {
+				return (await stat(path)).size;
+			} catch {
+				return null;
+			}
 		}
 	};
 }
@@ -366,6 +377,221 @@ function computeLifecycleTransitions(usage, config, now = /* @__PURE__ */ new Da
 	return result;
 }
 //#endregion
+//#region lib/types/prompts.js
+/**
+* Review and curation prompts adapted from Hermes Agent
+* `agent/background_review.py`, `agent/curator.py`, and
+* `agent/learn_prompt.py`, with tool names translated to the DSH-native
+* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
+*
+* Every prompt is pinned in a versioned bundle. Review workers verify the
+* bundle digest before spending a model call, so a partially-patched
+* deployment fails closed instead of silently running a truncated prompt.
+*/
+/**
+* Prompt bundle identity. Bump both id and version whenever a prompt's text
+* changes semantically: the bundle digest is the fail-closed signal for
+* review workers, so a stale id across deployments must be distinguishable.
+*/
+const PROMPT_BUNDLE_ID = "dsh-evolution@2";
+const PROMPT_BUNDLE_VERSION = 2;
+const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
+Review the conversation above and consider saving to memory if appropriate.
+
+Focus on:
+1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
+2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
+
+If something stands out, save it using the memory tool.
+If nothing is worth saving, just say "Nothing to save." and stop.`;
+const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
+Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small.
+
+Target shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.
+
+Signals that warrant action:
+- The user corrected your style, tone, format, verbosity, workflow, or approach.
+- A non-trivial technique, fix, workaround, or debugging path emerged.
+- A loaded skill turned out wrong, missing, or outdated — patch it now.
+
+Preference order:
+1. Patch a skill that was loaded or read this session.
+2. Patch an existing umbrella skill.
+3. Add references/, templates/, or scripts/ support under an existing skill.
+4. Create a new class-level umbrella skill only when nothing fits.
+
+Protected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.
+
+Do NOT capture:
+- Environment-dependent failures (missing binaries, unconfigured credentials).
+- Negative claims about tools ("browser tools do not work").
+- Transient errors that resolved during the session.
+- One-off task narratives.
+
+If a tool failed because of setup state, capture the FIX under an existing setup skill — never "this tool does not work" as a standalone constraint.
+
+"Nothing to save." is a real option but should NOT be the default.`;
+const COMBINED_REVIEW_PROMPT = `[Auto-review]
+Review the conversation above and update two things.
+
+**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.
+
+**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.
+
+Act on whichever dimension has real signal. If genuinely nothing stands out on either, say "Nothing to save." and stop — but don't reach for that conclusion as a default.`;
+const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
+
+The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
+
+Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
+
+Hard rules:
+1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
+2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (\`referenced\`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.
+3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet.
+4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
+5. Judge overlap on CONTENT, not on usage counters.
+6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
+
+How to work:
+1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword (expect 10-25 clusters).
+2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
+   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
+   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
+   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.
+3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
+
+Produce a YAML summary with exactly this shape:
+consolidations:
+  - from: <old-skill-name>
+    into: <umbrella-skill-name>
+    reason: <one short sentence>
+prunings:
+  - name: <skill-name>
+    reason: <one short sentence>
+Nominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).`;
+const CURATOR_DRY_RUN_BANNER = `═══════════════════════════════════════════════════════════════
+DRY-RUN — REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.
+═══════════════════════════════════════════════════════════════
+
+This is a PREVIEW pass. Follow every instruction above EXCEPT:
+  • Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.
+  • Do NOT move, copy, or rewrite any file under the skills tree.
+
+Your output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.
+
+If you accidentally take a mutating action, say so explicitly in the summary.`;
+const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
+Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
+
+Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch skills loaded this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
+
+Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
+function reviewPrompt(kind) {
+	if (kind === "memory") return MEMORY_REVIEW_PROMPT;
+	if (kind === "skill") return SKILL_REVIEW_PROMPT;
+	return COMBINED_REVIEW_PROMPT;
+}
+function sha256(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+function createPromptBundle(prompts) {
+	const canonical = JSON.stringify({
+		id: PROMPT_BUNDLE_ID,
+		version: 2,
+		prompts: Object.fromEntries(Object.entries(prompts).sort())
+	});
+	return Object.freeze({
+		id: PROMPT_BUNDLE_ID,
+		version: 2,
+		prompts: Object.freeze({ ...prompts }),
+		sha256: sha256(canonical)
+	});
+}
+const PROMPT_BUNDLE = createPromptBundle({
+	memory: MEMORY_REVIEW_PROMPT,
+	skill: SKILL_REVIEW_PROMPT,
+	combined: COMBINED_REVIEW_PROMPT,
+	curator: CURATOR_PROMPT,
+	completion: COMPLETION_SKILL_REVIEW_PROMPT
+});
+function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
+	const canonical = JSON.stringify({
+		id: bundle.id,
+		version: bundle.version,
+		prompts: Object.fromEntries(Object.entries(bundle.prompts).sort())
+	});
+	return bundle.sha256 === sha256(canonical);
+}
+const DSH_AUTHORING_STANDARDS = `Follow the Hermes skill-authoring standards, translated to DSH tools.
+
+Frontmatter:
+- name: lowercase-hyphenated, <=64 chars, no spaces.
+- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.
+- version: 0.1.0
+- author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe.
+- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.
+- metadata.hermes.tags: a few Capitalized, Relevant, Tags.
+
+Body section order (omit only when empty):
+1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
+2. "## When to Use" — concrete trigger phrases.
+3. "## Prerequisites" — exact env vars, install steps, credentials.
+4. "## How to Run" — canonical invocation framed through DSH tools.
+5. "## Quick Reference" — flat command/endpoint list.
+6. "## Procedure" — numbered steps with copy-paste-exact commands.
+7. "## Pitfalls" — known limits and rate limits.
+8. "## Verification" — one check proving the skill worked.
+
+DSH-tool framing:
+- Reference DSH tools by name in backticks: \`bash\`, \`str_replace_editor\`, \`write\`, \`skill\`, \`skill_manage\`, \`memory\`.
+- Do not name wrapped shell utilities when a DSH tool already covers them.
+- Larger scripts belong under \`scripts/\` (written with \`skill_manage write_file\`) and are referenced from SKILL.md by relative path.
+
+Quality bar:
+- Prefer verbatim flags, paths, and APIs from the source. Never invent them.
+- Keep it tight: ~100 lines simple, ~200 complex.
+- No router/index/hub skills that only point at other skills.
+- References go in \`references/\`, templates in \`templates/\`.`;
+//#endregion
+//#region lib/types/learn-prompt.js
+/**
+* Open-ended `/evolution learn` prompt builder.
+*
+* `learn` is open-ended: the user can name anything they can describe — a
+* directory of code, an API doc URL, a workflow they just walked the agent
+* through, or pasted notes. The prompt instructs the live agent to gather the
+* named sources with its existing tools, then author a single SKILL.md via
+* `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+* distillation engine and no model-tool footprint.
+*/
+/**
+* Build the agent prompt for an open-ended `/evolution learn` request.
+*
+* @param userRequest free-text the user gave after `/evolution learn`; an
+*   empty string falls back to "the workflow we just went through".
+* @returns a complete instruction the agent runs as a normal turn.
+*/
+function buildLearnPrompt(userRequest) {
+	return [
+		"[/learn] The user wants you to learn a reusable skill from the request below, and save it.",
+		"",
+		"THE REQUEST:",
+		userRequest.trim() || "the workflow we just went through in this conversation — review the steps taken and distill them into a reusable skill",
+		"",
+		"The request is open-ended and may mix two kinds of content, in any order: SOURCES to gather (directories, file paths, URLs, \"what we just did\", pasted notes) AND REQUIREMENTS that shape the skill (what to focus on, what to leave out, scope, naming, the angle to take). Treat EVERY part of the request as load-bearing. In particular, prose that comes after a path or link is NOT incidental — it is the user telling you what they want from that source. A request like `<url> focus on the auth flow, skip the deprecated endpoints` means: gather the URL AND honor \"focus on auth, skip deprecated\" as authoring requirements. Never fetch the first source and ignore the rest.",
+		"",
+		"Do this:",
+		"1. Gather every source the user named, using the tools you already have — reads and searches for local files or directories, web access for URLs, this conversation history if they referred to something you just did, and the text they pasted as-is. If the request is ambiguous about scope, make a reasonable choice and note it; do not stall.",
+		"2. Author ONE SKILL.md, applying every requirement, focus, and constraint in the request — these govern what the SKILL.md covers and emphasizes, not just which sources you read.",
+		"3. Save it with the `skill_manage` tool (action=\"create\"). Pick a sensible category. If the procedure needs a non-trivial script, add it under the skill's `scripts/` with `skill_manage` write_file and reference it by relative path.",
+		"",
+		DSH_AUTHORING_STANDARDS,
+		"",
+		"When done, tell the user the skill name, its category, and a one-line summary of what it captured."
+	].join("\n");
+}
+//#endregion
 //#region lib/types/threats.js
 /**
 * Threat scanning for agent-authored memory and skill content.
@@ -599,6 +825,13 @@ function scanContentThreats(text, maxScanChars = 65536, options = NO_SCAN_OPTION
 * File-backed durable memory with Hermes-compatible semantics.
 * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
 */
+/**
+* Read-guard factor: a memory file larger than this multiple of its target's
+* char limit is treated as externally corrupted and skipped instead of being
+* read whole (aligned with claw `tools/memory.ts` size guard, which uses the
+* same 10× bound around a file that should never exceed the store limit).
+*/
+const READ_GUARD_FACTOR = 10;
 function memoryRoot(env = process.env) {
 	return join(env.DSH_HOME ?? join(homedir(), ".dsh"), "memories");
 }
@@ -633,7 +866,24 @@ var MemoryStore = class {
 	limitFor(target) {
 		return target === "memory" ? this.memoryLimit : this.userLimit;
 	}
+	/**
+	* Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+	* `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+	* (backend without a size probe), under the bound, or the target has no
+	* limit configured.
+	*/
+	async oversizedFile(target) {
+		const size = await this.io.size?.(fileFor(this.root, target));
+		if (size === null || size === void 0) return null;
+		const limit = this.limitFor(target);
+		if (limit <= 0) return null;
+		return size > limit * READ_GUARD_FACTOR ? {
+			size,
+			limit
+		} : null;
+	}
 	async read(target) {
+		if (await this.oversizedFile(target)) return [];
 		const raw = await this.io.readText(fileFor(this.root, target));
 		return raw === null ? [] : [...new Set(normalizeEntries(raw))];
 	}
@@ -669,23 +919,45 @@ var MemoryStore = class {
 		return percent >= 80 ? ` ⚠️ Storage at ${percent}% (${chars}/${limit} chars).` : "";
 	}
 	/**
-	* Best-effort copy of the drifted on-disk file to `<file>.bak.<stamp>` before
-	* refusing the write, so an external edit stays recoverable. Failure to back
-	* up does not change the refusal semantics.
+	* Best-effort raw-copy backup of the on-disk file to `<file>.bak.<stamp>`
+	* before a refusal, so an externally modified (or oversized) file stays
+	* recoverable. Copies bytes instead of reading them so a pathologically
+	* large file is never loaded just to back it up. Failure to back up does
+	* not change the refusal semantics.
 	*/
-	async backupDrift(target) {
+	async backupFile(target) {
 		const path = fileFor(this.root, target);
-		const raw = await this.io.readText(path);
-		if (raw === null) return null;
 		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 14);
 		try {
-			await this.io.writeText(`${path}.bak.${stamp}`, raw);
+			await this.io.copy(path, `${path}.bak.${stamp}`);
 			return `${path}.bak.${stamp}`;
 		} catch {
 			return null;
 		}
 	}
+	/**
+	* Read-guard refusal for write paths. Returns the refusal result when the
+	* target file is oversized, `null` otherwise. The file is skipped for
+	* reading (never loaded), backed up by raw copy, and the model is told to
+	* fix it manually — mirroring the drift refusal so corrupted state is never
+	* silently overwritten.
+	*/
+	async oversizedRefusal(target) {
+		const oversized = await this.oversizedFile(target);
+		if (!oversized) return null;
+		const backup = await this.backupFile(target);
+		const suffix = backup ? ` A backup was saved to ${basename(backup)}.` : "";
+		return {
+			ok: false,
+			message: `Memory file is ${oversized.size} bytes (limit ${oversized.limit * READ_GUARD_FACTOR}) — skipping read.${suffix} Fix the file manually, then retry.`,
+			entries: [],
+			chars: 0,
+			limit: this.limitFor(target)
+		};
+	}
 	async add(target, facts) {
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return refusal;
 		const content = facts.trim();
 		if (!content) return {
 			ok: false,
@@ -741,6 +1013,8 @@ var MemoryStore = class {
 			chars: 0,
 			limit: this.limitFor(target)
 		};
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return refusal;
 		const content = action === "replace" ? (facts ?? "").trim() : "";
 		if (action === "replace" && !content) return {
 			ok: false,
@@ -760,7 +1034,7 @@ var MemoryStore = class {
 			};
 		}
 		if (await this.detectDrift(target)) {
-			const backup = await this.backupDrift(target);
+			const backup = await this.backupFile(target);
 			return {
 				ok: false,
 				message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
@@ -806,8 +1080,10 @@ var MemoryStore = class {
 			chars: 0,
 			limit: this.limitFor(target)
 		};
+		const refusal = await this.oversizedRefusal(target);
+		if (refusal) return refusal;
 		if (await this.detectDrift(target)) {
-			const backup = await this.backupDrift(target);
+			const backup = await this.backupFile(target);
 			return {
 				ok: false,
 				message: `External drift detected in memory file.${backup ? ` A backup was saved to ${basename(backup)}.` : ""} Resolve the drift before retrying.`,
@@ -898,12 +1174,27 @@ var MemoryStore = class {
 		const memory = await this.read("memory");
 		const user = await this.read("user");
 		const parts = [];
-		for (const [target, entries] of [["Memory", memory], ["User Profile", user]]) {
+		for (const [target, label, entries] of [[
+			"memory",
+			"Memory",
+			memory
+		], [
+			"user",
+			"User Profile",
+			user
+		]]) {
+			const oversized = entries.length === 0 ? await this.oversizedFile(target) : null;
+			if (oversized) {
+				parts.push(`## ${label} — file skipped: ${oversized.size} bytes (limit ${oversized.limit * READ_GUARD_FACTOR}); not read`);
+				continue;
+			}
 			const safe = entries.filter((entry) => !scanMemoryThreats(entry));
 			if (safe.length > 0) {
 				const body = safe.join(ENTRY_DELIMITER);
+				const limit = this.limitFor(target);
+				const pct = limit > 0 ? Math.min(100, Math.floor(body.length * 100 / limit)) : 0;
 				const note = safe.length === entries.length ? "" : ` (${entries.length - safe.length} threat-matched entries filtered)`;
-				parts.push(`## ${target} (${safe.length} entries)${note}\n${body}`);
+				parts.push(`## ${label} (${safe.length} entries) [${pct}% — ${body.length}/${limit} chars]${note}\n${body}`);
 			}
 		}
 		return parts.join("\n\n");
@@ -928,6 +1219,7 @@ var MemoryStore = class {
 	* same serialization and returns false, so a normal write is never flagged.
 	*/
 	async detectDrift(target) {
+		if (await this.oversizedFile(target)) return true;
 		const raw = await this.io.readText(fileFor(this.root, target));
 		if (raw === null) return false;
 		return render(normalizeEntries(raw)) !== raw;
@@ -971,183 +1263,6 @@ async function recordMutation(root, io, record, cap = 500) {
 	}, null, 2));
 }
 //#endregion
-//#region lib/types/prompts.js
-/**
-* Review and curation prompts adapted from Hermes Agent
-* `agent/background_review.py`, `agent/curator.py`, and
-* `agent/learn_prompt.py`, with tool names translated to the DSH-native
-* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
-*
-* Every prompt is pinned in a versioned bundle. Review workers verify the
-* bundle digest before spending a model call, so a partially-patched
-* deployment fails closed instead of silently running a truncated prompt.
-*/
-/**
-* Prompt bundle identity. Bump both id and version whenever a prompt's text
-* changes semantically: the bundle digest is the fail-closed signal for
-* review workers, so a stale id across deployments must be distinguishable.
-*/
-const PROMPT_BUNDLE_ID = "dsh-evolution@2";
-const PROMPT_BUNDLE_VERSION = 2;
-const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
-Review the conversation above and consider saving to memory if appropriate.
-
-Focus on:
-1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
-2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
-
-If something stands out, save it using the memory tool.
-If nothing is worth saving, just say "Nothing to save." and stop.`;
-const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
-Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small.
-
-Target shape: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a flat list of narrow one-session skills.
-
-Signals that warrant action:
-- The user corrected your style, tone, format, verbosity, workflow, or approach.
-- A non-trivial technique, fix, workaround, or debugging path emerged.
-- A loaded skill turned out wrong, missing, or outdated — patch it now.
-
-Preference order:
-1. Patch a skill that was loaded or read this session.
-2. Patch an existing umbrella skill.
-3. Add references/, templates/, or scripts/ support under an existing skill.
-4. Create a new class-level umbrella skill only when nothing fits.
-
-Protected skills (bundled/hub-installed) must not be edited. Pinned skills may be patched but not archived.
-
-Do NOT capture:
-- Environment-dependent failures (missing binaries, unconfigured credentials).
-- Negative claims about tools ("browser tools do not work").
-- Transient errors that resolved during the session.
-- One-off task narratives.
-
-If a tool failed because of setup state, capture the FIX under an existing setup skill — never "this tool does not work" as a standalone constraint.
-
-"Nothing to save." is a real option but should NOT be the default.`;
-const COMBINED_REVIEW_PROMPT = `[Auto-review]
-Review the conversation above and update two things.
-
-**Memory**: who the user is. Save durable user preferences, personal details, and expectations with the memory tool.
-
-**Skills**: how to do this class of task. Be ACTIVE. Follow the same class-level umbrella policy, preference order, protected-skill rules, and do-not-capture list as a skill review.
-
-Act on whichever dimension has real signal. If genuinely nothing stands out on either, say "Nothing to save." and stop — but don't reach for that conclusion as a default.`;
-const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
-
-The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
-
-Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
-
-Hard rules:
-1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
-2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (\`referenced\`) skills. Referenced skills MAY be consolidated into an umbrella, but never simply pruned.
-3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet.
-4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
-5. Judge overlap on CONTENT, not on usage counters.
-6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
-
-How to work:
-1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword (expect 10-25 clusters).
-2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
-   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
-   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
-   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella.
-3. Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
-
-Produce a YAML summary with exactly this shape:
-consolidations:
-  - from: <old-skill-name>
-    into: <umbrella-skill-name>
-    reason: <one short sentence>
-prunings:
-  - name: <skill-name>
-    reason: <one short sentence>
-Nominate a pruning only when archival is clearly safe (stale AND genuinely obsolete or fully absorbed elsewhere).`;
-const CURATOR_DRY_RUN_BANNER = `═══════════════════════════════════════════════════════════════
-DRY-RUN — REPORT ONLY. DO NOT MUTATE THE SKILL LIBRARY.
-═══════════════════════════════════════════════════════════════
-
-This is a PREVIEW pass. Follow every instruction above EXCEPT:
-  • Do NOT call skill_manage with action=create, update, patch, delete, write_file, or remove_file.
-  • Do NOT move, copy, or rewrite any file under the skills tree.
-
-Your output IS the deliverable: produce the exact same human-readable summary and YAML block you would on a live run, describing the actions you WOULD take. A reviewer will decide whether to approve a live run.
-
-If you accidentally take a mutating action, say so explicitly in the summary.`;
-const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
-Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
-
-Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch skills loaded this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
-
-Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
-function reviewPrompt(kind) {
-	if (kind === "memory") return MEMORY_REVIEW_PROMPT;
-	if (kind === "skill") return SKILL_REVIEW_PROMPT;
-	return COMBINED_REVIEW_PROMPT;
-}
-function sha256(text) {
-	return createHash("sha256").update(text).digest("hex");
-}
-function createPromptBundle(prompts) {
-	const canonical = JSON.stringify({
-		id: PROMPT_BUNDLE_ID,
-		version: 2,
-		prompts: Object.fromEntries(Object.entries(prompts).sort())
-	});
-	return Object.freeze({
-		id: PROMPT_BUNDLE_ID,
-		version: 2,
-		prompts: Object.freeze({ ...prompts }),
-		sha256: sha256(canonical)
-	});
-}
-const PROMPT_BUNDLE = createPromptBundle({
-	memory: MEMORY_REVIEW_PROMPT,
-	skill: SKILL_REVIEW_PROMPT,
-	combined: COMBINED_REVIEW_PROMPT,
-	curator: CURATOR_PROMPT,
-	completion: COMPLETION_SKILL_REVIEW_PROMPT
-});
-function verifyPromptBundle(bundle = PROMPT_BUNDLE) {
-	const canonical = JSON.stringify({
-		id: bundle.id,
-		version: bundle.version,
-		prompts: Object.fromEntries(Object.entries(bundle.prompts).sort())
-	});
-	return bundle.sha256 === sha256(canonical);
-}
-const DSH_AUTHORING_STANDARDS = `Follow the Hermes skill-authoring standards, translated to DSH tools.
-
-Frontmatter:
-- name: lowercase-hyphenated, <=64 chars, no spaces.
-- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving.
-- version: 0.1.0
-- author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe.
-- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound; omit for portable skills.
-- metadata.hermes.tags: a few Capitalized, Relevant, Tags.
-
-Body section order (omit only when empty):
-1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
-2. "## When to Use" — concrete trigger phrases.
-3. "## Prerequisites" — exact env vars, install steps, credentials.
-4. "## How to Run" — canonical invocation framed through DSH tools.
-5. "## Quick Reference" — flat command/endpoint list.
-6. "## Procedure" — numbered steps with copy-paste-exact commands.
-7. "## Pitfalls" — known limits and rate limits.
-8. "## Verification" — one check proving the skill worked.
-
-DSH-tool framing:
-- Reference DSH tools by name in backticks: \`bash\`, \`str_replace_editor\`, \`write\`, \`skill\`, \`skill_manage\`, \`memory\`.
-- Do not name wrapped shell utilities when a DSH tool already covers them.
-- Larger scripts belong under \`scripts/\` (written with \`skill_manage write_file\`) and are referenced from SKILL.md by relative path.
-
-Quality bar:
-- Prefer verbatim flags, paths, and APIs from the source. Never invent them.
-- Keep it tight: ~100 lines simple, ~200 complex.
-- No router/index/hub skills that only point at other skills.
-- References go in \`references/\`, templates in \`templates/\`.`;
-//#endregion
 //#region lib/types/quality.js
 /**
 * Quality scoring and near-duplicate detection for the curated skill library.
@@ -2067,4 +2182,4 @@ var JsonState = class JsonState {
 	}
 };
 //#endregion
-export { COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };
+export { COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, DSH_AUTHORING_STANDARDS, ENTRY_DELIMITER, JsonState, LOW_QUALITY_THRESHOLD, MAX_DESCRIPTION_LENGTH, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MEMORY_REVIEW_PROMPT, MUTATIONS_FILE_VERSION, MemoryStore, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, QUALITY_WEIGHTS, SKILL_NAME_RE, SKILL_REVIEW_PROMPT, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, advanceReview, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpUse, bumpView, computeDedupGroups, computeLifecycleTransitions, computeQualityScores, contentHash, emptyRecord, evaluateThreat, evolutionHome, evolutionIoAdapter, foldTurn, getRecord, latestActivityAt, loadMutations, loadSuppressedNames, loadUsage, markAgentCreated, memoryRoot, mutationsFile, nodeEvolutionIo, observeEvent, parseCuratorNominations, parseFrontmatter, recordMutation, reviewPrompt, saveSuppressedNames, saveUsage, scanContentThreats, scanMemoryThreats, scanThreats, skillsRoot, suppressedFile, usageFile, validateFrontmatter, verifyPromptBundle };

package/lib/types/index.d.ts

@@ -10,6 +10,7 @@
 export * from './curator.ts';
 export * from './events.ts';
 export * from './io.ts';
+export * from './learn-prompt.ts';
 export * from './memory-store.ts';
 export * from './mutations.ts';
 export * from './prompts.ts';

package/lib/types/io.d.ts

@@ -13,6 +13,13 @@ export interface EvolutionIoLike {
     exists(path: string): Promise<boolean>;
     rename(path: string, destination: string): Promise<void>;
     copy(path: string, destination: string): Promise<void>;
+    /**
+     * Optional byte-size probe for the read guard. Return the file's size in
+     * bytes, or `null`/`undefined` when unknown (unsupported backend, missing
+     * file, stat failure). An implementation without this probe gets no guard:
+     * consumers treat an unknown size as "guard not applicable".
+     */
+    size?(path: string): Promise<number | null>;
 }
 /** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
 export declare function evolutionIoAdapter(provider: () => EvolutionIoLike): EvolutionIoLike;

package/lib/types/learn-prompt.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Open-ended `/evolution learn` prompt builder.
+ *
+ * `learn` is open-ended: the user can name anything they can describe — a
+ * directory of code, an API doc URL, a workflow they just walked the agent
+ * through, or pasted notes. The prompt instructs the live agent to gather the
+ * named sources with its existing tools, then author a single SKILL.md via
+ * `skill_manage` following `DSH_AUTHORING_STANDARDS`. There is no separate
+ * distillation engine and no model-tool footprint.
+ */
+/**
+ * Build the agent prompt for an open-ended `/evolution learn` request.
+ *
+ * @param userRequest free-text the user gave after `/evolution learn`; an
+ *   empty string falls back to "the workflow we just went through".
+ * @returns a complete instruction the agent runs as a normal turn.
+ */
+export declare function buildLearnPrompt(userRequest: string): string;
+//# sourceMappingURL=learn-prompt.d.ts.map

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

@@ -37,6 +37,13 @@ export declare class MemoryStore {
     private failureCount;
     constructor(options?: MemoryStoreOptions);
     limitFor(target: MemoryTarget): number;
+    /**
+     * Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+     * `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+     * (backend without a size probe), under the bound, or the target has no
+     * limit configured.
+     */
+    private oversizedFile;
     read(target: MemoryTarget): Promise<string[]>;
     write(target: MemoryTarget, entries: string[]): Promise<void>;
     resetFailures(): void;
@@ -44,11 +51,21 @@ export declare class MemoryStore {
     /** Percent-based storage hint appended to success message once the target is ≥80% full. */
     private storageHint;
     /**
-     * Best-effort copy of the drifted on-disk file to `<file>.bak.<stamp>` before
-     * refusing the write, so an external edit stays recoverable. Failure to back
-     * up does not change the refusal semantics.
+     * Best-effort raw-copy backup of the on-disk file to `<file>.bak.<stamp>`
+     * before a refusal, so an externally modified (or oversized) file stays
+     * recoverable. Copies bytes instead of reading them so a pathologically
+     * large file is never loaded just to back it up. Failure to back up does
+     * not change the refusal semantics.
+     */
+    private backupFile;
+    /**
+     * Read-guard refusal for write paths. Returns the refusal result when the
+     * target file is oversized, `null` otherwise. The file is skipped for
+     * reading (never loaded), backed up by raw copy, and the model is told to
+     * fix it manually — mirroring the drift refusal so corrupted state is never
+     * silently overwritten.
      */
-    private backupDrift;
+    private oversizedRefusal;
     add(target: MemoryTarget, facts: string): Promise<MemoryApplyResult>;
     replace(target: MemoryTarget, oldText: string, facts: string): Promise<MemoryApplyResult>;
     remove(target: MemoryTarget, oldText: string): Promise<MemoryApplyResult>;

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.1.0-rc.21",
+  "version": "0.1.0-rc.23",
   "publishConfig": {
     "access": "public"
   },