@lmzhen/dsh-evolution-maintenance 0.4.1 → 0.5.0

package/lib/{enrichment-31K43lVa.js → enrichment-CjZmhRI9.js}

@@ -1,4 +1,4 @@
-import { HEALTH_STAMP_RE, MIN_STAMP_BODY_CHARS, computeDedupGroups, computePrefixClusters, duplicateHeadings, frontmatterCatalogInvalid, isPresent, missingSupportPointers, narrowNameMatches, overlongLines, parseFrontmatter, usageObserved } from "@lmzhen/dsh-evolution-core";
+import { HEALTH_STAMP_RE, MIN_STAMP_BODY_CHARS, bodyCost, computeDedupGroups, computePrefixClusters, duplicateHeadings, frontmatterCatalogInvalid, idleDays, isPresent, missingSupportPointers, narrowNameMatches, overlongLines, parseFrontmatter, resolveCitations, retirementReport, usageObserved } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/drift-scan.js
 /**
 * Skill-library snapshot assembly for drift scanning.
@@ -28,15 +28,25 @@ async function snapshotFromLibrary(library, options = {}) {
 			options.onReadError?.(entry.name, /* @__PURE__ */ new Error("no readable SKILL.md (missing file, or the directory name is not a valid skill name)"));
 			continue;
 		}
+		const supportFiles = options.supportFiles?.get(entry.name);
 		snapshots.push({
 			name: entry.name,
 			body,
 			description: options.descriptions?.get(entry.name),
-			supportFiles: options.supportFiles?.get(entry.name),
+			supportFiles,
+			cost: bodyCost(body),
+			...supportFiles === void 0 ? {} : { citations: resolveCitations({
+				content: body,
+				file: "SKILL.md",
+				files: supportFiles
+			}) },
 			quality: options.quality?.get(entry.name),
 			...options.protected?.get(entry.name) !== void 0 ? { protected: options.protected.get(entry.name) } : {},
 			...options.catalogInvalid?.get(entry.name) === true ? { catalogInvalid: true } : {},
-			...options.usageObserved !== void 0 ? { usageObserved: options.usageObserved } : {}
+			...options.usageObserved !== void 0 ? { usageObserved: options.usageObserved } : {},
+			...options.demand?.get(entry.name) === void 0 ? {} : { demand: options.demand.get(entry.name) },
+			...options.liveness?.get(entry.name) === void 0 ? {} : { liveness: options.liveness.get(entry.name) },
+			...options.supportChars?.get(entry.name) === void 0 ? {} : { supportChars: options.supportChars.get(entry.name) }
 		});
 	}
 	return snapshots;
@@ -60,6 +70,8 @@ const PROBE_SIGNALS = [
 	"dup_heading",
 	"overlong_line",
 	"pointer_missing",
+	"citation_resolution",
+	"demand",
 	"narrow_name",
 	"description_chars",
 	"quality_low"
@@ -110,6 +122,25 @@ function computeProbe(signal, target, snapshots) {
 		case "dup_heading": return result(signal, duplicateHeadings(body).map((d) => `${d.heading} x${d.count}`), target);
 		case "overlong_line": return result(signal, overlongLines(body).map((line) => `line ${line.lineNo}: ${line.chars} chars`), target);
 		case "pointer_missing": return result(signal, missingSupportPointers(body, snapshot.supportFiles ?? []).map((path) => `no body reference: ${path}`), target);
+		case "citation_resolution": {
+			const citations = snapshot.citations;
+			if (citations === void 0) return result(signal, ["not-scanned (support files not enumerated)"], target);
+			if (citations.truncated) return result(signal, [`scan truncated at ${citations.refs.length} refs`], target);
+			const cited = citations.refs.filter((ref) => ref.kind === "citation");
+			const dangling = citations.dangling.map((ref) => `${ref.target ?? ref.raw}:${ref.line}`);
+			const unverified = citations.unverified.map((ref) => `${ref.target ?? ref.raw}:${ref.line}`);
+			return result(signal, dangling.length > 0 ? dangling.map((entry) => `dangling ${entry}`) : [`dangling=0 of ${cited.length} (foreign=${citations.foreign.length}${unverified.length === 0 ? "" : `, unverified=${unverified.length}: ${unverified.slice(0, 3).join(", ")}`})`], target);
+		}
+		case "demand": {
+			if (!snapshot.supportFiles || snapshot.supportFiles.length === 0) return result(signal, ["not-enumerated (support files unknown)"], target);
+			if (snapshot.usageObserved !== true) return result(signal, ["window-closed (no observed reads yet)"], target);
+			const demand = snapshot.demand ?? {};
+			const cold = snapshot.supportFiles.filter((path) => (demand[path] ?? 0) === 0);
+			const retire = retirementReport(snapshot, snapshot.supportFiles);
+			const coldLines = cold.length === 0 ? [`cold=0 of ${snapshot.supportFiles.length}`] : cold.map((path) => `never read: ${path}`);
+			const retireLines = retire.candidates.length === 0 ? [`retire: ${retire.status}`] : retire.candidates.map((candidate) => `retire candidate: ${candidate.path} (idle ${candidate.idleDays}d)`);
+			return result(signal, [...coldLines, ...retireLines], target);
+		}
 		case "narrow_name": return result(signal, narrowNameMatches(snapshot.name).map((shape) => `narrow shape: ${shape}`), target);
 		case "description_chars": {
 			const desc = snapshot.description;
@@ -143,6 +174,10 @@ async function buildEnrichment(ctx, library) {
 	const quality = /* @__PURE__ */ new Map();
 	const protectedMap = /* @__PURE__ */ new Map();
 	const catalogInvalid = /* @__PURE__ */ new Map();
+	const demand = /* @__PURE__ */ new Map();
+	const liveness = /* @__PURE__ */ new Map();
+	const supportChars = /* @__PURE__ */ new Map();
+	const now = /* @__PURE__ */ new Date();
 	for (const entry of await library.list()) {
 		if (entry.protectionUnknown) protectedMap.set(entry.name, "unknown");
 		else if (entry.protectedBy) protectedMap.set(entry.name, entry.protectedBy);
@@ -162,6 +197,11 @@ async function buildEnrichment(ctx, library) {
 		if (isPresent(files) && files.value.length > 0) supportFiles.set(entry.name, files.value);
 		const record = usageMap?.get(entry.name);
 		if (typeof record?.quality_score === "number") quality.set(entry.name, record.quality_score);
+		const reads = record?.support_reads;
+		if (reads !== void 0 && Object.keys(reads).length > 0) demand.set(entry.name, reads);
+		if (record !== void 0) liveness.set(entry.name, { idleDays: idleDays(record, now) });
+		const big = await library.supportFileChars(entry.name);
+		if (big !== null && Object.keys(big).length > 0) supportChars.set(entry.name, big);
 	}
 	return {
 		descriptions,
@@ -169,7 +209,10 @@ async function buildEnrichment(ctx, library) {
 		quality,
 		usageObservedValue,
 		protected: protectedMap,
-		catalogInvalid
+		catalogInvalid,
+		demand,
+		liveness,
+		supportChars
 	};
 }
 //#endregion

package/lib/index.js

@@ -1,4 +1,4 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-31K43lVa.js";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-CjZmhRI9.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
@@ -414,6 +414,9 @@ async function runMaintain(runtime, options = {}) {
 			protected: options.protected ? options.protected() : void 0,
 			catalogInvalid: options.catalogInvalid ? options.catalogInvalid() : void 0,
 			usageObserved,
+			...options.demand === void 0 ? {} : { demand: options.demand() },
+			...options.liveness === void 0 ? {} : { liveness: options.liveness() },
+			...options.supportChars === void 0 ? {} : { supportChars: options.supportChars() },
 			onReadError: (name, error) => {
 				readFailures.push(name);
 				runtime.logger?.warn(`evolution-maintenance: skipping unreadable skill "${name}": ${error instanceof Error ? error.message : String(error)}`);

package/lib/tools.js

@@ -1,4 +1,4 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-31K43lVa.js";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-CjZmhRI9.js";
 import { assertSkillsRootAliasRetired, newSkillLibrary, redactSecrets, resolveRootConfig } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -34,7 +34,7 @@ function apply(ctx, rawConfig = {}) {
 				},
 				target: {
 					type: "string",
-					description: "Skill name for skill-level signals (required for stamp_density/body_size/dup_heading/overlong_line/pointer_missing/narrow_name/description_chars/quality_low)."
+					description: "Skill name for skill-level signals (required for stamp_density/body_size/dup_heading/overlong_line/pointer_missing/citation_resolution/demand/narrow_name/description_chars/quality_low)."
 				}
 			},
 			output: {
@@ -76,7 +76,8 @@ function apply(ctx, rawConfig = {}) {
 					quality: enrichment.quality,
 					protected: enrichment.protected,
 					catalogInvalid: enrichment.catalogInvalid,
-					usageObserved: enrichment.usageObservedValue
+					usageObserved: enrichment.usageObservedValue,
+					demand: enrichment.demand
 				}));
 				const redacted = redactSecrets(probe.detail.join("\n"));
 				return {

package/lib/types/drift-scan.d.ts

@@ -7,7 +7,7 @@
  * when absent they stay `undefined`, which the signal layer reports as
  * `unknown` (never a fabricated verdict).
  */
-import type { DriftSkillSnapshot } from '@lmzhen/dsh-evolution-core';
+import { type DriftSkillSnapshot, type SkillLiveness } from '@lmzhen/dsh-evolution-core';
 /** Minimal SkillLibrary surface needed for snapshot assembly. */
 export interface SkillLibraryLike {
     list(): Promise<ReadonlyArray<{
@@ -34,6 +34,12 @@ export interface SnapshotOptions {
      * the snapshot (E-36): without it the probe always answered 'unknown' while
      * the facts block reported the enrichment value. */
     usageObserved?: boolean | undefined;
+    /** Per-support-file read counts per skill (design §5.5). */
+    demand?: ReadonlyMap<string, Readonly<Record<string, number>>> | undefined;
+    /** Idle age per skill (design §5.6). */
+    liveness?: ReadonlyMap<string, SkillLiveness> | undefined;
+    /** Support-file char counts for files that can exceed the cap (design §16.6). */
+    supportChars?: ReadonlyMap<string, Readonly<Record<string, number>>> | undefined;
 }
 /**
  * Assemble drift snapshots from a library reader and optional enrichment.

package/lib/types/enrichment.d.ts

@@ -7,7 +7,7 @@
  * enrichment at all).
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type SkillLibrary } from '@lmzhen/dsh-evolution-core';
+import { type SkillLibrary, type SkillLiveness } from '@lmzhen/dsh-evolution-core';
 export interface Enrichment {
     descriptions: ReadonlyMap<string, string>;
     supportFiles: ReadonlyMap<string, readonly string[]>;
@@ -17,6 +17,16 @@ export interface Enrichment {
     protected: ReadonlyMap<string, string>;
     /** Skills whose frontmatter the strict-YAML platform catalog cannot load. */
     catalogInvalid: ReadonlyMap<string, boolean>;
+    /** Per-support-file read counts (design §5.5) — present only where the usage
+     * sidecar recorded at least one read, so absence stays "no evidence". */
+    demand: ReadonlyMap<string, Readonly<Record<string, number>>>;
+    /** Idle age per skill (design §5.6) — present only for skills with a usage
+     * record, so a skill the sidecar never saw stays "no age evidence". */
+    liveness: ReadonlyMap<string, SkillLiveness>;
+    /** Support-file char counts for files big enough to possibly exceed the cap
+     * (design §16.6) — present only where at least one such file exists, so the
+     * common measured-and-clean case adds no field. */
+    supportChars: ReadonlyMap<string, Readonly<Record<string, number>>>;
 }
 export declare function buildEnrichment(ctx: Context, library: SkillLibrary): Promise<Enrichment>;
 //# sourceMappingURL=enrichment.d.ts.map

package/lib/types/orchestrate.d.ts

@@ -4,7 +4,7 @@
  * text. Deterministic parts stay pure; the subagent call is the only
  * external dependency (injected, fake-able in tests).
  */
-import { type DriftReport, type DriftSkillSnapshot } from '@lmzhen/dsh-evolution-core';
+import { type DriftReport, type DriftSkillSnapshot, type SkillLiveness } from '@lmzhen/dsh-evolution-core';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { type SkillLibraryLike } from './drift-scan.ts';
 /** I-5 (v37): the platform's `SubagentStartRequest` fields this orchestrator sends.
@@ -98,6 +98,12 @@ export interface MaintainOptions {
     protected?: () => ReadonlyMap<string, string>;
     catalogInvalid?: () => ReadonlyMap<string, boolean>;
     usageObserved?: () => boolean | undefined;
+    /** Per-support-file read counts per skill (design §5.5). */
+    demand?: () => ReadonlyMap<string, Readonly<Record<string, number>>>;
+    /** Idle age per skill (design §5.6). */
+    liveness?: () => ReadonlyMap<string, SkillLiveness>;
+    /** Support-file char counts for files that can exceed the cap (design §16.6). */
+    supportChars?: () => ReadonlyMap<string, Readonly<Record<string, number>>>;
 }
 export interface MaintainOutcome {
     ok: boolean;

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.4.1",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.4.1"
+    "@lmzhen/dsh-evolution-core": "^0.5.0"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",