@lmzhen/dsh-evolution-commands 0.3.82 → 0.4.0

package/README.md

@@ -1,39 +1,28 @@
-# @deepseek-ai/dsh-evolution-commands
+# @lmzhen/dsh-evolution-commands
 
-Human commands for the evolution family
+Human commands for the evolution family: it registers the `/evolution …` command surface
+and its help text, and drives the other rows from a command. It adds no automatic
+background behaviour of its own.
 
-## Model Experience
+## Model surface
 
-### Indirect model surface
+- **Model-visible:** one direct token — the `/evolution learn` injection — the full learning guidance is injected as a user message in this session; everything else adds no tokens.
+- **Prompt prefix / KV cache:** independent of request-prefix construction — it does not alter the assembled prompt or tool list; family rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
+- **Mount it?** yes — the `evolution-commands` row, carried by the `evolution-host`, `evolution-all` and `evolution-preset` bundles.
 
-#### What the model sees
+## Command reference
 
-`@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.
-
-#### Token effect
-
-P2-22 (v11) correction: this package's **only** direct model-visible token is the
-`/evolution learn` injection — the full learning guidance is injected as a user
-message in this session. Everything else adds no tokens; consumers add their own.
-The injection goes through the agent's waking primitive (`followup`, falling back
-to `inject` when the host lacks it), **called on the agent instance**: the
-platform's `Agent.followup` is a prototype method (`this.send(...)`), so a
-detached reference throws and queues nothing (0.3.73 fix; the same shape is
-pinned by rule N13b in `packages/scripts/verify-arch-guards.mjs`, which masks comments and string literals before matching and self-tests its detector at startup).
-
-#### KV Cache effect
-
-Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
-
-## Known Limitations and Deferred Work
+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.
 
+## Known limitations
 
 - No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
-- **① variant form: the `/evolution …` command face is visible in every session**
-  (accepted, not fixed — 0.3.78). Commands are registered in scope layers, and the
-  family registers once on the host plane, so a session on a platform original
-  preset still lists the management-only subcommands even though no automatic
-  family behaviour reaches it. The difference and its reasoning are single-sourced
-  in `INSTALL.md` ("Known difference").
+- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed). Commands are registered in scope layers, and the family registers once on the host plane, so a session on a platform original preset still lists the management-only subcommands even though no automatic family behaviour reaches it. The difference and its reasoning are single-sourced in `INSTALL.md` ("Known difference").
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
+
+## Notes and history
+
+- P2-22 (v11) correction: this package's **only** direct model-visible token is the `/evolution learn` injection — the full learning guidance is injected as a user message in this session.
+- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed: 0.3.78).
+- The injection goes through the agent's waking primitive (`followup`, falling back to `inject` when the host lacks it), **called on the agent instance**: the platform's `Agent.followup` is a prototype method (`this.send(...)`), so a detached reference throws and queues nothing (0.3.73 fix; the same shape is pinned by rule N13b in `packages/scripts/verify-arch-guards.mjs`, which masks comments and string literals before matching and self-tests its detector at startup).

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.4.0",
   "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.4.0",
+    "@lmzhen/dsh-evolution-core": "^0.4.0",
+    "@lmzhen/dsh-evolution-maintenance": "^0.4.0"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.3.82"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.4.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",