@lmzhen/dsh-evolution-commands 0.3.82 → 0.3.83

package/README.md

@@ -1,14 +1,26 @@
-# @deepseek-ai/dsh-evolution-commands
+# @lmzhen/dsh-evolution-commands
 
 Human commands for the evolution family
 
+## Command reference
+
+The full `/evolution` subcommand table is single-sourced in the family
+README's **Command reference** section (`packages/README.md` in the source
+repository; it is named here instead of linked because a repo-relative
+markdown link out of this package would be dead inside the npm published
+tree). It is rendered from the subcommand registry (`src/registry.ts`, the same
+single source as the `/evolution` input-declaration hint and the
+bare-command help output), and `tests/registry.spec.ts` (T-WD2) pins that
+rendered table byte-for-byte. This package README cites that home instead
+of restating the table (doc-facts rule N19: never copy a fact across docs).
+
 ## Model Experience
 
 ### Indirect model surface
 
 #### What the model sees
 
-`@deepseek-ai/dsh-evolution-commands` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+`@lmzhen/dsh-evolution-commands` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
 
 #### Token effect
 

package/lib/index.js

@@ -321,8 +321,8 @@ async function diagnose(ctx, options = {}) {
 	if (full && host) conflicts.push("evolution-all and evolution-host are installed together — the infra rows double-mount and startup fails loud. Keep ONE: remove the other bundle.");
 	if (full && preset) conflicts.push("evolution-all and evolution-preset are installed together — the infra rows double-mount. Keep ONE.");
 	if (host && preset) conflicts.push("evolution-host and evolution-preset are installed together — the infra rows double-mount. Keep ONE.");
-	if (full && presetDirInstalled) conflicts.push(`evolution-all and the layered Evolution preset (${layeredArtifactLabel}) are both present — the model rows double-mount. Keep ONE (use layered without all, or drop the preset).`);
-	if (preset && presetDirInstalled) conflicts.push(`evolution-preset and the layered Evolution preset (${layeredArtifactLabel}) are both present — the model rows double-mount (the preset bundle carries the same model rows as all). Keep ONE (drop the preset bundle, or remove the layered preset).`);
+	if (full && presetDirInstalled) conflicts.push(`evolution-all and the layered Evolution preset (${layeredArtifactLabel}) are both present — the four model rows AND the systemPrompt sections double-instance across the profile and preset layers; the preset loader does not fail on it, shadowing semantics take the nearest layer, so an Evolution-preset session silently runs the preset's copies of everything. Keep ONE (use layered without all, or drop the preset).`);
+	if (preset && presetDirInstalled) conflicts.push(`evolution-preset and the layered Evolution preset (${layeredArtifactLabel}) are both present — the preset bundle carries the same model rows as all, so the four model rows AND the systemPrompt sections double-instance and shadowing semantics take the nearest layer (the preset loader does not fail on it). Keep ONE (drop the preset bundle, or remove the layered preset).`);
 	const reviewMounted = full || host || preset;
 	const services = {
 		review: reviewMounted,
@@ -850,13 +850,22 @@ function apply(ctx, rawConfig = {}) {
 						io: ioRegistry.provider()
 					});
 					const enrichment = await buildEnrichment(ctx, library);
-					const { facts } = buildMaintainFacts(await snapshotFromLibrary(library, {
+					const readFailures = [];
+					const snapshots = await snapshotFromLibrary(library, {
 						descriptions: enrichment.descriptions,
 						supportFiles: enrichment.supportFiles,
 						quality: enrichment.quality,
 						protected: enrichment.protected,
-						catalogInvalid: enrichment.catalogInvalid
-					}), enrichment.usageObservedValue, void 0);
+						catalogInvalid: enrichment.catalogInvalid,
+						onReadError: (name, error) => {
+							readFailures.push(name);
+							ctx.logger.warn(`evolution-maintenance: skipping unreadable skill "${name}": ${error instanceof Error ? error.message : String(error)}`);
+						}
+					});
+					if (snapshots.length === 0 && readFailures.length > 0) return err(`maintenance scan could not read ${readFailures.length} listed skill(s) (${readFailures.slice(0, 10).join(", ")}${readFailures.length > 10 ? ", …" : ""}) and read no skill at all — the library was NOT audited; fix the unreadable skills (or their directory names) and run the scan again`);
+					if (snapshots.length === 0 && skillsRootValue !== "" && !await ioRegistry.provider().exists(skillsRootValue)) return err(`maintenance scan found an empty skill library, but the configured skill root does not exist (${skillsRootValue}) — point the skillsRoot config at a real directory (a literal \`~\` is not expanded) and run the scan again`);
+					if (snapshots.length === 0) return ok("Maintenance scan: empty skill library. Nothing to do.");
+					const { facts } = buildMaintainFacts(snapshots, enrichment.usageObservedValue, void 0);
 					return ok(`Maintenance facts (0-token preview):\n${facts}`);
 				}
 				const maintainArgs = /^maintain(?:\s+--timeout[ =](\d+))?\s*$/.exec(input);
@@ -994,7 +1003,9 @@ function apply(ctx, rawConfig = {}) {
 					if (approval) {
 						const session = invocationAgent?.session;
 						const sessionPolicy = effectiveSessionPolicy(ctx, session);
-						if (session !== void 0 && approval.isEnabled !== false && sessionPolicy !== "never" && approval.stageForeground !== false && !approval.hasRunner("skill")) return err("Restructure cannot be staged: no skill replay runner is registered — mount the tool-skill-manage row (evolution-agent preset, or evolution-all) or disable evolution-approval.");
+						const stagesForeground = approval.isEnabled !== false && sessionPolicy !== "never" && approval.stageForeground !== false;
+						if (stagesForeground && session === void 0) return err("E-306: this deployment stages foreground writes, but this invocation carries no agent session — `/evolution restructure` would stage a record with no session attribution. Run it from a session in the GUI or the CLI, or set `stageForeground: false` on the evolution-approval row, then repeat the command.");
+						if (stagesForeground && !approval.hasRunner("skill")) return err("Restructure cannot be staged: no skill replay runner is registered — mount the tool-skill-manage row (evolution-agent preset, or evolution-all) or disable evolution-approval.");
 						const decision = await approval.request({
 							kind: "skill",
 							summary: `/evolution restructure ${name}${planRunId ? ` (plan ${planRunId})` : ""}`,

package/lib/types/registry.d.ts

@@ -4,6 +4,9 @@
  * 0.3.55 (WD1): the input-declaration hint, the bare `/evolution` help output
  * and the README command table all render FROM this table; a hand-written
  * copy anywhere is drift waiting to happen (v10 R-13 proved it once).
+ * PLAN S5.3 (2026-09-16): "the README command table" means the FAMILY README
+ * (`packages/README.md` — the T-WD2 anchor). Package-level READMEs cite that
+ * home instead of restating the table (doc-facts rule N19).
  * Keep `usage` in the exact shape a user can type after `/evolution`.
  */
 export interface CommandEntry {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.3.82",
+  "version": "0.3.83",
   "publishConfig": {
     "access": "public"
   },
@@ -27,12 +27,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.3.82",
-    "@lmzhen/dsh-evolution-core": "^0.3.82",
-    "@lmzhen/dsh-evolution-maintenance": "^0.3.82"
+    "@lmzhen/dsh-evolution-approval": "^0.3.83",
+    "@lmzhen/dsh-evolution-core": "^0.3.83",
+    "@lmzhen/dsh-evolution-maintenance": "^0.3.83"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.3.82"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.3.83"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",