@lmzhen/dsh-evolution-maintenance 0.3.67 → 0.3.69

package/lib/{enrichment-CYpvRfH_.js → enrichment-2NEuOAZU.js}

@@ -1,4 +1,4 @@
-import { HEALTH_STAMP_RE, MIN_STAMP_BODY_CHARS, computeDedupGroups, computePrefixClusters, duplicateHeadings, frontmatterYamlUnsafeValues, missingSupportPointers, narrowNameMatches, overlongLines, parseFrontmatter, usageObserved } from "@lmzhen/dsh-evolution-core";
+import { HEALTH_STAMP_RE, MIN_STAMP_BODY_CHARS, computeDedupGroups, computePrefixClusters, duplicateHeadings, frontmatterCatalogInvalid, missingSupportPointers, narrowNameMatches, overlongLines, parseFrontmatter, usageObserved } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/drift-scan.js
 /**
 * Skill-library snapshot assembly for drift scanning.
@@ -24,7 +24,10 @@ async function snapshotFromLibrary(library, options = {}) {
 			options.onReadError?.(entry.name, error);
 			continue;
 		}
-		if (body === void 0 || body === null) continue;
+		if (body === void 0 || body === null) {
+			options.onReadError?.(entry.name, /* @__PURE__ */ new Error("no readable SKILL.md (missing file, or the directory name is not a valid skill name)"));
+			continue;
+		}
 		snapshots.push({
 			name: entry.name,
 			body,
@@ -141,7 +144,7 @@ async function buildEnrichment(ctx, library) {
 		const body = await library.read(entry.name);
 		if (body === void 0 || body === null) continue;
 		const parsed = parseFrontmatter(body);
-		if (frontmatterYamlUnsafeValues(body).length > 0) catalogInvalid.set(entry.name, true);
+		if (frontmatterCatalogInvalid(body)) catalogInvalid.set(entry.name, true);
 		const description = parsed?.frontmatter.description;
 		if (typeof description === "string" && description.trim().length > 0) descriptions.set(entry.name, description);
 		const files = await library.listSupportFiles(entry.name);

package/lib/index.js

@@ -1,5 +1,5 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-CYpvRfH_.js";
-import { AUTHORING_DESCRIPTION_BAR, DEFAULT_HEALTH_THRESHOLDS, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MIN_STAMP_BODY_CHARS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, computeDriftSignals, findDriftSignal, redactSecrets, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-2NEuOAZU.js";
+import { AUTHORING_DESCRIPTION_BAR, DEFAULT_CURATOR_MODEL, DEFAULT_HEALTH_THRESHOLDS, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_TIMER_DELAY_MS, MIN_STAMP_BODY_CHARS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, computeDriftSignals, findDriftSignal, redactSecrets, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { createHash, randomUUID } from "node:crypto";
 //#region lib/types/render-facts.js
 /**
@@ -49,6 +49,16 @@ function renderSignal(signal, redact) {
 * and the quality_low=unknown global imposition. Never judges whether a
 * recommendation is right — only whether it is well-formed and traceable.
 */
+/**
+* V27 D-3: the clause ids the maintain template ITSELF enumerates — the `- A1 …`
+* bullets of its §5 rule catalogue. `rule` is checked against this set (parsed
+* from the shipped template at module load, so a template edit that adds or
+* renames a clause moves the set with it) instead of the former bare
+* non-empty-string check, which let a plan cite a clause number that does not
+* exist and still pass mechanical validation. `self-consistency.spec.ts` pins
+* the parsed set so a template rewording cannot silently empty it.
+*/
+const MAINTAIN_RULE_IDS = new Set([...MAINTAIN_PROMPT.matchAll(/^-\s+([A-D]\d)\s/gm)].map((match) => match[1]));
 const KINDS = new Set([
 	"skill-level",
 	"relationship-level",
@@ -176,6 +186,7 @@ function validateAndNormalizeMaintainPlan(raw, report, validSignals) {
 				}
 			}
 			if (!isNonEmptyString(item.rule)) errors.push(`${path}.rule: required`);
+			else if (!MAINTAIN_RULE_IDS.has(item.rule.trim())) errors.push(`${path}.rule: "${item.rule}" is not a clause id the maintain template defines (${[...MAINTAIN_RULE_IDS].sort().join(", ")})`);
 			if (typeof item.finding !== "string" || item.finding.trim().length === 0) errors.push(`${path}.finding: required`);
 			if (!isNonEmptyString(item.recommendation)) errors.push(`${path}.recommendation: required`);
 			if (!isNonEmptyString(item.semantic_reasoning)) errors.push(`${path}.semantic_reasoning: required`);
@@ -238,7 +249,7 @@ function validateAndNormalizeMaintainPlan(raw, report, validSignals) {
 		},
 		forcedHuman
 	};
-	const unknownQualitySkills = new Set(report.skills.filter((skill) => findDriftSignal(skill.signals, "quality_low")?.verdict === "unknown").map((skill) => skill.name));
+	const unknownQualitySkills = new Set(report.skills.filter((skill) => findDriftSignal(skill.signals, "quality_low")?.verdict === "unknown").map((skill) => skill.name.trim()));
 	for (const item of plan) if (item.names.some((name) => unknownQualitySkills.has(name)) && !item.needs_human) {
 		item.needs_human = true;
 		forcedHuman.push(...item.names.filter((name) => unknownQualitySkills.has(name)));
@@ -349,8 +360,10 @@ function formatPlan(validated, runId) {
 	const { plan, forcedHuman } = validated;
 	const lines = [];
 	lines.push(`Maintenance scan ${runId}: verdict=${plan.verdict} (${plan.plan.length} recommendations, ${plan.notes.length} notes)`);
+	const noteLines = plan.notes.length === 0 ? [] : ["Notes:", ...plan.notes.map((note) => `- ${note}`)];
 	if (plan.verdict === "no_issues") {
 		lines.push("No drift issues detected. Nothing to do.");
+		lines.push(...noteLines);
 		return lines.join("\n");
 	}
 	for (const item of plan.plan) {
@@ -367,10 +380,7 @@ function formatPlan(validated, runId) {
 		if (item.is_override && item.override_reason) lines.push(`  override: ${item.override_reason}`);
 	}
 	if (forcedHuman.length > 0) lines.push(`(quality_low gate: forced needs_human for ${[...new Set(forcedHuman)].join(", ")})`);
-	if (plan.notes.length > 0) {
-		lines.push("Notes:");
-		for (const note of plan.notes) lines.push(`- ${note}`);
-	}
+	lines.push(...noteLines);
 	return lines.join("\n");
 }
 /** Run one maintenance scan and return display text plus validation metadata. */
@@ -383,6 +393,7 @@ async function runMaintain(runtime, options = {}) {
 			error: "dsh-evolution prompt bundle integrity check failed; refusing to run maintain"
 		};
 		const usageObserved = options.usageObserved ? options.usageObserved() : void 0;
+		const readFailures = [];
 		const snapshots = await snapshotFromLibrary(runtime.library, {
 			supportFiles: options.supportFiles ? options.supportFiles() : void 0,
 			descriptions: options.descriptions ? options.descriptions() : void 0,
@@ -391,16 +402,29 @@ async function runMaintain(runtime, options = {}) {
 			catalogInvalid: options.catalogInvalid ? options.catalogInvalid() : void 0,
 			usageObserved,
 			onReadError: (name, error) => {
+				readFailures.push(name);
 				runtime.logger?.warn(`evolution-maintenance: skipping unreadable skill "${name}": ${error instanceof Error ? error.message : String(error)}`);
 			}
 		});
-		if (snapshots.length === 0) return {
-			ok: true,
-			recommendationCount: 0,
-			runId: randomUUID(),
-			verdict: "no_issues",
-			text: "Maintenance scan: empty skill library. Nothing to do."
-		};
+		if (snapshots.length === 0) {
+			if (readFailures.length > 0) return {
+				ok: false,
+				recommendationCount: 0,
+				error: `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 (runtime.rootExists && !await runtime.rootExists()) return {
+				ok: false,
+				recommendationCount: 0,
+				error: `maintenance scan found an empty skill library, but the configured skill root does not exist${runtime.skillRoot ? ` (${runtime.skillRoot})` : ""} — point the skillsRoot config at a real directory (a literal \`~\` is not expanded) and run the scan again`
+			};
+			return {
+				ok: true,
+				recommendationCount: 0,
+				runId: randomUUID(),
+				verdict: "no_issues",
+				text: "Maintenance scan: empty skill library. Nothing to do."
+			};
+		}
 		const { facts, report, signalsVersion, signature } = buildMaintainFacts(snapshots, usageObserved, options.redact);
 		const template = renderMaintainTemplate(MAINTAIN_PROMPT, PROMPT_BUNDLE_ID, signalsVersion, signature);
 		const probeRegistered = runtime.tools?.get("maintenance_probe") != null;
@@ -410,14 +434,14 @@ async function runMaintain(runtime, options = {}) {
 
 ${MAINTAIN_OUTPUT_INSTRUCTION}`;
 		const timeoutMs = options.timeoutMs ?? 6e5;
-		if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) return {
+		if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_DELAY_MS) return {
 			ok: false,
 			recommendationCount: 0,
-			error: `maintain: --timeout must be a positive integer in ms, at most 2147483647; got ${String(timeoutMs)}`
+			error: `maintain: --timeout must be a positive integer in ms, at most ${MAX_TIMER_DELAY_MS}; got ${String(timeoutMs)}`
 		};
 		const signal = options.signal !== void 0 ? AbortSignal.any([AbortSignal.timeout(timeoutMs), options.signal]) : AbortSignal.timeout(timeoutMs);
 		abortSignal = signal;
-		const agentOptions = { model: options.model ?? runtime.evolutionPolicy?.get()?.curatorModel ?? "deepseek-v4-pro" };
+		const agentOptions = { model: options.model ?? runtime.evolutionPolicy?.get()?.curatorModel ?? DEFAULT_CURATOR_MODEL };
 		if (options.provider) agentOptions.provider = options.provider;
 		const run = await runtime.subagents.start("spawn", {
 			label: "dsh-evolution-maintain",
@@ -550,4 +574,4 @@ ${MAINTAIN_OUTPUT_INSTRUCTION}`;
 	}
 }
 //#endregion
-export { PROBE_SIGNALS, buildEnrichment, buildMaintainFacts, computeProbe, renderFacts, renderMaintainTemplate, runMaintain, snapshotFromLibrary, validateAndNormalizeMaintainPlan };
+export { MAINTAIN_RULE_IDS, PROBE_SIGNALS, buildEnrichment, buildMaintainFacts, computeProbe, renderFacts, renderMaintainTemplate, runMaintain, snapshotFromLibrary, validateAndNormalizeMaintainPlan };

package/lib/tools.js

@@ -1,5 +1,5 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-CYpvRfH_.js";
-import { SkillLibrary, redactSecrets, resolveRootConfig, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-2NEuOAZU.js";
+import { SkillLibrary, assertSkillsRootAliasRetired, redactSecrets, resolveRootConfig, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region lib/types/tools.js
@@ -19,8 +19,8 @@ const Config = z.object({
 	skillsRoot: z.string().default("")
 });
 function apply(ctx, rawConfig = {}) {
+	assertSkillsRootAliasRetired(rawConfig);
 	const rootConfig = resolveRootConfig(rawConfig);
-	if (rootConfig.usedDeprecatedAlias) ctx.logger.warn("evolution-maintenance-tools: config \"skillsRoot\" is deprecated (E-7); use \"root\" — the alias is honoured until 0.3.65");
 	ctx.inject(["tools"], (toolCtx) => {
 		const tools = toolCtx.get("tools");
 		toolCtx.effect(() => tools.register(defineTool({

package/lib/types/orchestrate.d.ts

@@ -41,6 +41,14 @@ export interface MaintainRuntime {
     tools?: {
         get(name: string): unknown;
     } | undefined;
+    /** V27 M-02: does the configured skill root EXIST? The io seam maps a missing
+     * directory to an empty listing, so "the scan found no skills" could not be
+     * told apart from "the configured root is not there" (an unexpanded `~`, a
+     * typo — INSTALL.md routes users to absolute paths). Optional: without the
+     * probe the scan keeps the previous empty-library answer. */
+    rootExists?: (() => Promise<boolean>) | undefined;
+    /** V27 M-02: the root the probe above refers to, for the error message. */
+    skillRoot?: string | undefined;
 }
 export interface MaintainOptions {
     timeoutMs?: number;

package/lib/types/tools.d.ts

@@ -15,8 +15,8 @@ export interface Config {
     /** Skill-tree root for probe reads; empty uses the default tree. E-7 (v18):
      * canonical key — the same `root` every other family row reads. */
     root?: string | undefined;
-    /** Deprecated alias of `root` (E-7, v18); honoured only while `root` is
-     * empty, with a warning; removed after 0.3.65. */
+    /** V27 G2.4 (M-08): RETIRED alias of `root`. Declared so the loader passes it
+     * to the load-time gate (which rejects it loudly) instead of dropping it. */
     skillsRoot?: string | undefined;
 }
 export declare const Config: z<Schemastery.ObjectS<{

package/lib/types/validate-plan.d.ts

@@ -8,6 +8,16 @@
  * recommendation is right — only whether it is well-formed and traceable.
  */
 import { type DriftReport } from '@lmzhen/dsh-evolution-core';
+/**
+ * V27 D-3: the clause ids the maintain template ITSELF enumerates — the `- A1 …`
+ * bullets of its §5 rule catalogue. `rule` is checked against this set (parsed
+ * from the shipped template at module load, so a template edit that adds or
+ * renames a clause moves the set with it) instead of the former bare
+ * non-empty-string check, which let a plan cite a clause number that does not
+ * exist and still pass mechanical validation. `self-consistency.spec.ts` pins
+ * the parsed set so a template rewording cannot silently empty it.
+ */
+export declare const MAINTAIN_RULE_IDS: ReadonlySet<string>;
 export type MaintainVerdict = 'issues' | 'no_issues';
 export type MaintainPlanItemKind = 'skill-level' | 'relationship-level' | 'library-level';
 export type MaintainReversibility = 'archive' | 'restructure' | 'patch' | 'rename' | 'none';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-maintenance",
   "description": "Deterministic maintenance-scan surface: skill-library snapshot assembly, drift signals and mechanical-facts rendering (design 011) (community build)",
-  "version": "0.3.67",
+  "version": "0.3.69",
   "publishConfig": {
     "access": "public"
   },
@@ -35,7 +35,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.67"
+    "@lmzhen/dsh-evolution-core": "^0.3.69"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
@@ -43,6 +43,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
   }
 }