@lmzhen/dsh-evolution-maintenance 0.0.0 → 0.3.0

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-evolution-maintenance
+
+Skill-library drift-scanning determinism surface for the maintenance subagent
+(design `docs/design-review/011-maintenance-subagent-v2.md`).
+
+- `snapshotFromLibrary` — assemble a plain skill snapshot from a SkillLibrary-like reader.
+- `renderFacts` — canonical `MECHANICAL_FACTS` block (version + joint signature + redaction).
+
+Signal computation lives in `@deepseek-ai/dsh-evolution-core` (`drift-signals`); this
+package owns assembly and rendering only.
+
+## Known Limitations and Deferred Work
+
+- Phase 1-2 expose no service beyond the command surface: the chain
+  (commands → scan → render → subagent → validate) is wired through
+  `/evolution maintain`; orchestration lives in this package.
+- `maintenance_probe` (read-only deep-dive tool, host-mounted via
+  `evolution-maintenance-tools`) is available to maintenance subagents only
+  through the orchestrate `toolFilter` allow-list; it is globally visible to
+  every session as a read-only query (same exposure tier as the `skill`
+  tool — never a write path).
+- The model-visible template (`MAINTAIN_PROMPT`) ships in `evolution-core`
+  `PROMPT_BUNDLE`; the joint-signature mismatch protocol is honored by
+  `renderFacts` callers, not by this package alone.

package/lib/index.js

@@ -0,0 +1,448 @@
+import { n as computeProbe, t as PROBE_SIGNALS } from "./probe-CrVeRJ6b.js";
+import { AUTHORING_DESCRIPTION_BAR, DEFAULT_HEALTH_THRESHOLDS, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, LOW_QUALITY_THRESHOLD, MAINTAIN_PROMPT, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, computeDriftSignals, findDriftSignal, redactSecrets, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { createHash, randomUUID } from "node:crypto";
+//#region lib/types/drift-scan.js
+/**
+* Skill-library snapshot assembly for drift scanning.
+*
+* `computeDriftSignals` (evolution-core) is a pure function over a plain
+* snapshot; this module converts a SkillLibrary-like reader into that
+* snapshot. Quality score and usage-window status are caller-provided —
+* when absent they stay `undefined`, which the signal layer reports as
+* `unknown` (never a fabricated verdict).
+*/
+/**
+* Assemble drift snapshots from a library reader and optional enrichment.
+* Missing enrichment stays `undefined` → signal layer reports `unknown`.
+*/
+async function snapshotFromLibrary(library, options = {}) {
+	const entries = await library.list();
+	const snapshots = [];
+	for (const entry of entries) {
+		const body = await library.read(entry.name);
+		if (body === void 0 || body === null) continue;
+		snapshots.push({
+			name: entry.name,
+			body,
+			description: options.descriptions?.get(entry.name),
+			supportFiles: options.supportFiles?.get(entry.name),
+			quality: options.quality?.get(entry.name)
+		});
+	}
+	return snapshots;
+}
+//#endregion
+//#region lib/types/render-facts.js
+/**
+* Mechanical-facts rendering for the maintenance subagent (011 §6).
+*
+* One canonical block: opening tag with version + joint signature, one
+* `[FACT]`/`[UNKNOWN]` line per signal, closing tag. The template side
+* renders its own `<MAINTAIN_PROMPT>` header with the same signature, so
+* the model can compare the two heads (011 mismatch protocol). All rendered
+* value/detail text passes through the optional redactor before it leaves
+* the session.
+*/
+function renderFacts(report, options) {
+	const redact = options.redact ?? redactSecrets;
+	const lines = [];
+	lines.push(`<<<MECHANICAL_FACTS v=${options.signalsVersion} sig=${options.signature}>>>`);
+	for (const signal of report.library) lines.push(...renderSignal(signal, redact));
+	for (const skill of report.skills) {
+		lines.push(`# skill=${skill.name}`);
+		for (const signal of skill.signals) lines.push(...renderSignal(signal, redact));
+	}
+	lines.push("<<<END FACTS>>>");
+	return lines.join("\n");
+}
+function renderSignal(signal, redact) {
+	const prefix = signal.verdict === "unknown" ? "[UNKNOWN]" : "[FACT]";
+	const value = redact(signal.value);
+	const parts = [
+		`${prefix} signal=${signal.id}`,
+		`value=${value}`,
+		`verdict=${signal.verdict}`
+	];
+	if (signal.threshold !== void 0) parts.push(`threshold=${signal.threshold}`);
+	if (signal.detail !== void 0) parts.push(`detail=${redact(signal.detail)}`);
+	return [parts.join(" ")];
+}
+/** Convenience for tests and replays: summarize a skill assessment. */
+function summarizeAssessment(assessment) {
+	const over = assessment.signals.filter((signal) => signal.verdict === "over").map((signal) => signal.id);
+	return over.length === 0 ? `${assessment.name}: clean` : `${assessment.name}: ${over.join(",")}`;
+}
+//#endregion
+//#region lib/types/validate-plan.js
+/**
+* Maintain-plan validation and normalization (011 §7).
+*
+* Contract checks (mechanical, no semantics): enum membership, required
+* fields, evidence closed over the facts block's signal set, needs_human
+* consistency with the confidence/reversibility/is_override/unknown rules,
+* and the quality_low=unknown global imposition. Never judges whether a
+* recommendation is right — only whether it is well-formed and traceable.
+*/
+const KINDS = new Set([
+	"skill-level",
+	"relationship-level",
+	"library-level"
+]);
+const REVERSIBILITIES = new Set([
+	"archive",
+	"restructure",
+	"patch",
+	"rename",
+	"none"
+]);
+const IMPACTS = new Set([
+	"better",
+	"worse",
+	"neutral"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value, fallback) {
+	return isNonEmptyString(value) ? value : fallback;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function validateEvidence(value, validSignals, errors, path) {
+	if (!Array.isArray(value) || value.length === 0) {
+		errors.push(`${path}.evidence: must be a non-empty array`);
+		return [];
+	}
+	const out = [];
+	const arr = value;
+	for (const index of arr.keys()) {
+		const entry = arr[index];
+		if (!isRecord(entry) || !isNonEmptyString(entry.signal) || !isNonEmptyString(entry.value)) {
+			errors.push(`${path}.evidence[${index}]: must be {signal, value} strings`);
+			continue;
+		}
+		if (!validSignals.has(entry.signal)) errors.push(`${path}.evidence[${index}].signal="${entry.signal}": not in the facts block`);
+		out.push({
+			signal: entry.signal,
+			value: entry.value
+		});
+	}
+	return out;
+}
+/**
+* Validate and normalize a maintain plan against the facts report.
+* @param raw - subagent output (already JSON-parsed by the subagent channel).
+* @param report - the DriftReport rendered into the facts block (quality_low gate source).
+* @param validSignals - ids present in the rendered facts block.
+*/
+function validateAndNormalizeMaintainPlan(raw, report, validSignals) {
+	const errors = [];
+	const forcedHuman = [];
+	if (!isRecord(raw)) return {
+		ok: false,
+		errors: ["plan root: must be an object"],
+		plan: {
+			verdict: "no_issues",
+			plan: [],
+			notes: []
+		},
+		forcedHuman
+	};
+	const verdict = raw.verdict;
+	if (verdict !== "issues" && verdict !== "no_issues") errors.push(`verdict: must be "issues" or "no_issues", got ${String(verdict)}`);
+	const plan = [];
+	if (!Array.isArray(raw.plan)) errors.push("plan: must be an array");
+	else {
+		const rawPlan = raw.plan;
+		if (verdict === "no_issues" && rawPlan.length > 0) errors.push("verdict=no_issues with a non-empty plan");
+		for (const index of rawPlan.keys()) {
+			const item = rawPlan[index];
+			const path = `plan[${index}]`;
+			if (!isRecord(item)) {
+				errors.push(`${path}: must be an object`);
+				continue;
+			}
+			if (typeof item.kind !== "string" || !KINDS.has(item.kind)) errors.push(`${path}.kind: invalid`);
+			if (!Array.isArray(item.names) || item.names.length === 0 || !item.names.every(isNonEmptyString)) errors.push(`${path}.names: non-empty string array required`);
+			if (!isNonEmptyString(item.rule)) errors.push(`${path}.rule: required`);
+			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`);
+			if (typeof item.impact !== "string" || !IMPACTS.has(item.impact)) errors.push(`${path}.impact: invalid`);
+			if (!isNonEmptyString(item.impact_reason)) errors.push(`${path}.impact_reason: required`);
+			if (typeof item.reversibility !== "string" || !REVERSIBILITIES.has(item.reversibility)) errors.push(`${path}.reversibility: invalid`);
+			if (!isNonEmptyString(item.undo_path)) errors.push(`${path}.undo_path: required`);
+			if (typeof item.confidence !== "number" || !Number.isFinite(item.confidence) || item.confidence < 0 || item.confidence > 1) errors.push(`${path}.confidence: finite number in [0,1] required`);
+			if (typeof item.needs_human !== "boolean") errors.push(`${path}.needs_human: boolean required`);
+			if (typeof item.is_override !== "boolean") errors.push(`${path}.is_override: boolean required`);
+			if (item.is_override === true && !isNonEmptyString(item.override_reason)) errors.push(`${path}.override_reason: required when is_override`);
+			const evidence = validateEvidence(item.evidence, validSignals, errors, path);
+			plan.push({
+				kind: isNonEmptyString(item.kind) ? item.kind : "skill-level",
+				names: Array.isArray(item.names) ? item.names : [],
+				rule: str(item.rule, ""),
+				evidence,
+				finding: str(item.finding, ""),
+				recommendation: str(item.recommendation, ""),
+				semantic_reasoning: str(item.semantic_reasoning, ""),
+				impact: isNonEmptyString(item.impact) ? item.impact : "neutral",
+				impact_reason: str(item.impact_reason, ""),
+				reversibility: isNonEmptyString(item.reversibility) ? item.reversibility : "none",
+				undo_path: str(item.undo_path, ""),
+				confidence: typeof item.confidence === "number" ? item.confidence : 0,
+				needs_human: item.needs_human === true,
+				is_override: item.is_override === true,
+				override_reason: isNonEmptyString(item.override_reason) ? item.override_reason : void 0
+			});
+		}
+	}
+	const notes = Array.isArray(raw.notes) ? raw.notes.filter((note) => isNonEmptyString(note)) : [];
+	if (errors.length > 0) return {
+		ok: false,
+		errors,
+		plan: {
+			verdict: verdict === "no_issues" ? "no_issues" : "issues",
+			plan,
+			notes
+		},
+		forcedHuman
+	};
+	const unknownQualitySkills = new Set(report.skills.filter((skill) => findDriftSignal(skill.signals, "quality_low")?.verdict === "unknown").map((skill) => skill.name));
+	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)));
+	}
+	for (const item of plan) {
+		const referencesUnknown = item.evidence.some((ev) => {
+			return findSignalInReport(report, ev.signal)?.verdict === "unknown";
+		});
+		const lowConfidence = item.confidence < .6;
+		const irreversible = item.reversibility === "rename" || item.reversibility === "none";
+		if (!item.needs_human && (lowConfidence || irreversible || item.is_override || referencesUnknown)) item.needs_human = true;
+	}
+	return {
+		ok: true,
+		errors: [],
+		plan: {
+			verdict,
+			plan,
+			notes
+		},
+		forcedHuman
+	};
+}
+function findSignalInReport(report, id) {
+	return report.library.find((signal) => signal.id === id) ?? report.skills.flatMap((skill) => skill.signals).find((signal) => signal.id === id);
+}
+//#endregion
+//#region lib/types/orchestrate.js
+/**
+* Maintain orchestration (011 §3/§7): snapshot → drift signals → facts
+* render → subagent (template M + facts) → validate/normalize → display
+* text. Deterministic parts stay pure; the subagent call is the only
+* external dependency (injected, fake-able in tests).
+*/
+function existingSignalIds(report) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const signal of report.library) ids.add(signal.id);
+	for (const skill of report.skills) for (const signal of skill.signals) ids.add(signal.id);
+	return ids;
+}
+/** Render template-M placeholders from the signal vocabulary (011 single-source rule). */
+function renderMaintainTemplate(template, bundleVersion, signalsVersion, signature) {
+	let out = template;
+	out = out.replace(/{\s*signal:([a-z_]+)\.threshold\s*}/g, (_, id) => thresholdNoun(id));
+	out = out.replace(/{\s*signal:([a-z_]+)\s*}/g, (_, id) => DRIFT_SIGNAL_NOUNS[id] ?? id);
+	out = out.replaceAll("{bundle_version}", bundleVersion);
+	out = out.replaceAll("{signals_version}", signalsVersion);
+	out = out.replaceAll("{joint_signature}", signature);
+	return out;
+}
+function thresholdNoun(id) {
+	if (id === "stamp_density") return `${DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb}/KB`;
+	if (id === "description_chars") return `${AUTHORING_DESCRIPTION_BAR}`;
+	if (id === "body_size") return `${DEFAULT_HEALTH_THRESHOLDS.softBodyChars}`;
+	if (id === "overlong_line") return `${DRIFT_MAX_LINE_CHARS}`;
+	return `(阈 ${id})`;
+}
+function jointSignature(template, signalsVersion) {
+	const canonical = JSON.stringify({
+		signalsVersion,
+		template,
+		nouns: DRIFT_SIGNAL_NOUNS,
+		thresholds: {
+			stampDensityPerKb: DEFAULT_HEALTH_THRESHOLDS.stampDensityPerKb,
+			minStampBodyChars: 2e3,
+			softBodyChars: DEFAULT_HEALTH_THRESHOLDS.softBodyChars,
+			descriptionChars: AUTHORING_DESCRIPTION_BAR,
+			qualityLow: LOW_QUALITY_THRESHOLD,
+			maxLineChars: DRIFT_MAX_LINE_CHARS
+		}
+	});
+	return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+/**
+* Deterministic half of a maintenance scan: snapshots → drift report →
+* rendered facts block (joint signature + redaction). Shared by `runMaintain`
+* and the `--facts` preview so the preview can never disagree with the scan.
+*/
+function buildMaintainFacts(snapshots, usageObserved, redact) {
+	const report = computeDriftSignals(snapshots.map((snapshot) => ({
+		...snapshot,
+		usageObserved
+	})));
+	const signalsVersion = DRIFT_SIGNALS_VERSION;
+	const signature = jointSignature(MAINTAIN_PROMPT, signalsVersion);
+	return {
+		report,
+		facts: renderFacts(report, {
+			signalsVersion,
+			signature,
+			redact
+		}),
+		signalsVersion,
+		signature
+	};
+}
+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)`);
+	if (plan.verdict === "no_issues") {
+		lines.push("No drift issues detected. Nothing to do.");
+		return lines.join("\n");
+	}
+	for (const item of plan.plan) {
+		const flags = [
+			item.impact,
+			`rev=${item.reversibility}`,
+			`conf=${item.confidence.toFixed(2)}`,
+			item.needs_human ? "HUMAN" : ""
+		].filter(Boolean);
+		lines.push(`- [${item.kind}] ${item.names.join(", ")} · rule=${item.rule} · ${flags.join(" ")}`);
+		lines.push(`  finding: ${item.finding}`);
+		lines.push(`  action: ${item.recommendation}`);
+		if (item.undo_path && item.undo_path !== "n/a") lines.push(`  undo: ${item.undo_path}`);
+		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}`);
+	}
+	return lines.join("\n");
+}
+/** Run one maintenance scan and return display text plus validation metadata. */
+async function runMaintain(runtime, options = {}) {
+	try {
+		if (!verifyPromptBundle(PROMPT_BUNDLE)) return {
+			ok: false,
+			error: "dsh-evolution prompt bundle integrity check failed; refusing to run maintain"
+		};
+		const snapshots = await snapshotFromLibrary(runtime.library, {
+			supportFiles: options.supportFiles ? options.supportFiles() : void 0,
+			descriptions: options.descriptions ? options.descriptions() : void 0,
+			quality: options.quality ? options.quality() : void 0
+		});
+		if (snapshots.length === 0) return {
+			ok: true,
+			runId: randomUUID(),
+			verdict: "no_issues",
+			text: "Maintenance scan: empty skill library. Nothing to do."
+		};
+		const { facts, report, signalsVersion, signature } = buildMaintainFacts(snapshots, options.usageObserved ? options.usageObserved() : void 0, options.redact);
+		const template = renderMaintainTemplate(MAINTAIN_PROMPT, PROMPT_BUNDLE_ID, signalsVersion, signature);
+		const prompt = `${facts}
+
+按模板契约输出 JSON 维护计划（verdict/plan/notes）；除 skill 工具与维护模板外你无其他工具。`;
+		const timeoutMs = options.timeoutMs ?? 12e4;
+		const agentOptions = { model: options.model ?? "deepseek-v4-pro" };
+		if (options.provider) agentOptions.provider = options.provider;
+		const raw = (await (await runtime.subagents.start("spawn", {
+			label: "dsh-evolution-maintain",
+			prompt: [{
+				type: "text",
+				text: prompt
+			}],
+			parent: runtime.parent,
+			signal: AbortSignal.timeout(timeoutMs),
+			maxDepth: options.maxDepth ?? 0,
+			agentOptions,
+			persona: template,
+			toolFilter: { allow: [...options.toolAllow ?? ["skill", "maintenance_probe"]] },
+			outputSchema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					verdict: { type: "string" },
+					plan: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: { type: "string" },
+								names: {
+									type: "array",
+									items: { type: "string" }
+								},
+								rule: { type: "string" },
+								evidence: {
+									type: "array",
+									items: {
+										type: "object",
+										additionalProperties: false,
+										properties: {
+											signal: { type: "string" },
+											value: { type: "string" }
+										}
+									}
+								},
+								finding: { type: "string" },
+								recommendation: { type: "string" },
+								semantic_reasoning: { type: "string" },
+								impact: { type: "string" },
+								impact_reason: { type: "string" },
+								reversibility: { type: "string" },
+								undo_path: { type: "string" },
+								confidence: { type: "number" },
+								needs_human: { type: "boolean" },
+								is_override: { type: "boolean" },
+								override_reason: { type: "string" }
+							}
+						}
+					},
+					notes: {
+						type: "array",
+						items: { type: "string" }
+					}
+				}
+			}
+		})).result)?.structured;
+		if (raw === void 0) return {
+			ok: false,
+			error: "Maintain subagent returned no structured plan."
+		};
+		const validated = validateAndNormalizeMaintainPlan(raw, report, existingSignalIds(report));
+		if (!validated.ok) return {
+			ok: false,
+			error: `Maintain plan rejected by validator: ${validated.errors.slice(0, 5).join("; ")}`
+		};
+		const runId = randomUUID();
+		return {
+			ok: true,
+			runId,
+			verdict: validated.plan.verdict,
+			forcedHuman: validated.forcedHuman,
+			text: formatPlan(validated, runId)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: String(error)
+		};
+	}
+}
+//#endregion
+export { PROBE_SIGNALS, buildMaintainFacts, computeProbe, renderFacts, renderMaintainTemplate, runMaintain, snapshotFromLibrary, summarizeAssessment, validateAndNormalizeMaintainPlan };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-maintenance";
+const name = "evolution-maintenance-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/tools.js

@@ -0,0 +1,83 @@
+import { n as computeProbe, t as PROBE_SIGNALS } from "./probe-CrVeRJ6b.js";
+import { SkillLibrary, redactSecrets } from "@deepseek-ai/dsh-evolution-core";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/tools.js
+/**
+* `maintenance_probe` tool (011 Phase 3).
+*
+* Read-only deep-dive: returns single-source machine detail for one signal
+* (library-level group/cluster membership, or per-skill line/pointer/shape
+* evidence). The subagent may use it to sharpen confidence and
+* semantic_reasoning; it must never introduce evidence ids outside the facts
+* block (validated plan-side). No write path exists in this tool.
+* @module @deepseek-ai/dsh-evolution-maintenance-tools
+*/
+const name = "evolution-maintenance-tools";
+function apply(ctx, rawConfig = {}) {
+	const config = rawConfig;
+	ctx.inject(["tools"], (toolCtx) => {
+		toolCtx.tools.register(defineTool({
+			name: "maintenance_probe",
+			description: "Read-only deep-dive into maintenance scan signals: library-level group/cluster membership or per-skill detail (line numbers, pointer gaps, narrow shapes, stamp samples). Machine-derived from the same calculators as the facts block — never introduces new evidence ids. Output is JSON detail.",
+			parameters: {
+				signal: {
+					type: "string",
+					required: true,
+					enum: PROBE_SIGNALS
+				},
+				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)."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						signal: { type: "string" },
+						target: { type: "string" },
+						detail: {
+							type: "array",
+							items: { type: "string" }
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: (value.detail ?? []).join("\n")
+				}]
+			},
+			isConcurrencySafe: () => true,
+			async execute(args) {
+				const signal = args.signal ?? "";
+				const target = args.target;
+				const ioRegistry = ctx.get("evolutionIo");
+				if (!ioRegistry) return {
+					signal,
+					detail: ["evolution-io registry not mounted"],
+					...target ? { target } : {}
+				};
+				const library = new SkillLibrary(config.skillsRoot, ioRegistry.provider());
+				const entries = await library.list();
+				const snapshots = [];
+				for (const entry of entries) {
+					const body = await library.read(entry.name);
+					if (body === null) continue;
+					snapshots.push({
+						name: entry.name,
+						body
+					});
+				}
+				const probe = computeProbe(signal, target, snapshots);
+				const redacted = redactSecrets(probe.detail.join("\n"));
+				return {
+					...probe,
+					detail: redacted.split("\n")
+				};
+			}
+		}));
+	});
+}
+//#endregion
+export { apply, name };

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

@@ -0,0 +1,31 @@
+/**
+ * Skill-library snapshot assembly for drift scanning.
+ *
+ * `computeDriftSignals` (evolution-core) is a pure function over a plain
+ * snapshot; this module converts a SkillLibrary-like reader into that
+ * snapshot. Quality score and usage-window status are caller-provided —
+ * when absent they stay `undefined`, which the signal layer reports as
+ * `unknown` (never a fabricated verdict).
+ */
+import type { DriftSkillSnapshot } from '@deepseek-ai/dsh-evolution-core';
+/** Minimal SkillLibrary surface needed for snapshot assembly. */
+export interface SkillLibraryLike {
+    list(): Promise<ReadonlyArray<{
+        name: string;
+    }>>;
+    read(name: string): Promise<string | null | undefined>;
+}
+export interface SnapshotOptions {
+    /** Support-file relative paths per skill name, when the caller has them. */
+    supportFiles?: ReadonlyMap<string, readonly string[]> | undefined;
+    /** Parsed frontmatter description per skill name, when available. */
+    descriptions?: ReadonlyMap<string, string> | undefined;
+    /** Quality score per skill name, when the caller computed it. */
+    quality?: ReadonlyMap<string, number> | undefined;
+}
+/**
+ * Assemble drift snapshots from a library reader and optional enrichment.
+ * Missing enrichment stays `undefined` → signal layer reports `unknown`.
+ */
+export declare function snapshotFromLibrary(library: SkillLibraryLike, options?: SnapshotOptions): Promise<DriftSkillSnapshot[]>;
+//# sourceMappingURL=drift-scan.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Maintenance-scan determinism surface (design 011, Phase 1).
+ *
+ * Snapshot assembly (library → drift snapshot) and mechanical-facts
+ * rendering. Pure functions: no IO inside signal computation; the assembled
+ * snapshot is handed to `computeDriftSignals` (evolution-core) untouched.
+ * The full service chain (commands → scan → render → subagent → validate)
+ * is Phase 2; this module is the deterministic half, unit-testable without
+ * a live library.
+ * @module @deepseek-ai/dsh-evolution-maintenance
+ */
+export * from './drift-scan.ts';
+export * from './render-facts.ts';
+export * from './validate-plan.ts';
+export * from './orchestrate.ts';
+export * from './probe.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-maintenance-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/orchestrate.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Maintain orchestration (011 §3/§7): snapshot → drift signals → facts
+ * render → subagent (template M + facts) → validate/normalize → display
+ * text. Deterministic parts stay pure; the subagent call is the only
+ * external dependency (injected, fake-able in tests).
+ */
+import { type DriftReport, type DriftSkillSnapshot } from '@deepseek-ai/dsh-evolution-core';
+import { type SkillLibraryLike } from './drift-scan.ts';
+export interface MaintainRuntime {
+    /** SkillLibrary-like reader for snapshot assembly. */
+    library: SkillLibraryLike;
+    /** Subagent spawner (platform `subagents` service — minimal shape for injection). */
+    subagents: {
+        start(kind: string, options: unknown): Promise<{
+            result: Promise<unknown>;
+        }>;
+    };
+    /** Parent agent/session handle passed through to the subagent, when available. */
+    parent?: unknown;
+}
+export interface MaintainOptions {
+    timeoutMs?: number;
+    maxDepth?: number;
+    model?: string;
+    provider?: string;
+    toolAllow?: readonly string[];
+    redact?: ((text: string) => string) | undefined;
+    supportFiles?: () => ReadonlyMap<string, readonly string[]>;
+    descriptions?: () => ReadonlyMap<string, string>;
+    quality?: () => ReadonlyMap<string, number>;
+    usageObserved?: () => boolean | undefined;
+}
+export interface MaintainOutcome {
+    ok: boolean;
+    error?: string | undefined;
+    runId?: string | undefined;
+    verdict?: 'issues' | 'no_issues' | undefined;
+    text?: string | undefined;
+    forcedHuman?: string[] | undefined;
+}
+/** Render template-M placeholders from the signal vocabulary (011 single-source rule). */
+export declare function renderMaintainTemplate(template: string, bundleVersion: string, signalsVersion: string, signature: string): string;
+/** Facts bundle shared by the full scan and the `--facts` 0-token preview. */
+export interface FactsBundle {
+    report: DriftReport;
+    facts: string;
+    signalsVersion: string;
+    signature: string;
+}
+/**
+ * Deterministic half of a maintenance scan: snapshots → drift report →
+ * rendered facts block (joint signature + redaction). Shared by `runMaintain`
+ * and the `--facts` preview so the preview can never disagree with the scan.
+ */
+export declare function buildMaintainFacts(snapshots: ReadonlyArray<DriftSkillSnapshot>, usageObserved: boolean | undefined, redact: ((text: string) => string) | undefined): FactsBundle;
+/** Run one maintenance scan and return display text plus validation metadata. */
+export declare function runMaintain(runtime: MaintainRuntime, options?: MaintainOptions): Promise<MaintainOutcome>;
+//# sourceMappingURL=orchestrate.d.ts.map

package/lib/types/probe.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Probe detail computation (011 Phase 3).
+ *
+ * Pure functions over a skill snapshot — the SAME calculators the scan uses
+ * (`duplicateHeadings` / `overlongLines` / `missingSupportPointers` /
+ * `narrowNameMatches` / `computeDedupGroups` / `computePrefixClusters`), so a
+ * probe result can never disagree with the facts block. No IO, no writes.
+ */
+import { type DriftSkillSnapshot } from '@deepseek-ai/dsh-evolution-core';
+export declare const PROBE_SIGNALS: ReadonlyArray<string>;
+export interface ProbeResult {
+    signal: string;
+    /** Present only when the query carried a target. */
+    target?: string;
+    detail: string[];
+}
+/**
+ * Compute probe details for a query. Skill-level signals require `target`;
+ * library-level signals ignore it. Unknown signals yield an explicit
+ * `unknown-signal` detail (never a fabricated verdict).
+ */
+export declare function computeProbe(signal: string, target: string | undefined, snapshots: ReadonlyArray<DriftSkillSnapshot>): ProbeResult;
+//# sourceMappingURL=probe.d.ts.map

package/lib/types/render-facts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Mechanical-facts rendering for the maintenance subagent (011 §6).
+ *
+ * One canonical block: opening tag with version + joint signature, one
+ * `[FACT]`/`[UNKNOWN]` line per signal, closing tag. The template side
+ * renders its own `<MAINTAIN_PROMPT>` header with the same signature, so
+ * the model can compare the two heads (011 mismatch protocol). All rendered
+ * value/detail text passes through the optional redactor before it leaves
+ * the session.
+ */
+import { type DriftReport, type DriftSkillAssessment } from '@deepseek-ai/dsh-evolution-core';
+export interface RenderFactsOptions {
+    /** signals_version — changes whenever the signal set/thresholds change. */
+    signalsVersion: string;
+    /** Joint signature: sha256(template-text + signal-definitions) — shared with MAINTAIN_PROMPT head. */
+    signature: string;
+    /** Optional redactor; defaults to core `redactSecrets`. */
+    redact?: ((text: string) => string) | undefined;
+}
+export declare function renderFacts(report: DriftReport, options: RenderFactsOptions): string;
+/** Convenience for tests and replays: summarize a skill assessment. */
+export declare function summarizeAssessment(assessment: DriftSkillAssessment): string;
+//# sourceMappingURL=render-facts.d.ts.map

package/lib/types/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `maintenance_probe` tool (011 Phase 3).
+ *
+ * Read-only deep-dive: returns single-source machine detail for one signal
+ * (library-level group/cluster membership, or per-skill line/pointer/shape
+ * evidence). The subagent may use it to sharpen confidence and
+ * semantic_reasoning; it must never introduce evidence ids outside the facts
+ * block (validated plan-side). No write path exists in this tool.
+ * @module @deepseek-ai/dsh-evolution-maintenance-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-maintenance-tools";
+export interface Config {
+    /** Skill-tree root for probe reads; empty uses skillsRoot(). Align with
+     * tool-skill-manage/skill-usage/evolution-skill-catalog/commands rows (A7). */
+    skillsRoot?: string | undefined;
+}
+export declare function apply(ctx: Context, rawConfig?: Config): void;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Maintain-plan validation and normalization (011 §7).
+ *
+ * Contract checks (mechanical, no semantics): enum membership, required
+ * fields, evidence closed over the facts block's signal set, needs_human
+ * consistency with the confidence/reversibility/is_override/unknown rules,
+ * and the quality_low=unknown global imposition. Never judges whether a
+ * recommendation is right — only whether it is well-formed and traceable.
+ */
+import { type DriftReport } from '@deepseek-ai/dsh-evolution-core';
+export type MaintainVerdict = 'issues' | 'no_issues';
+export type MaintainPlanItemKind = 'skill-level' | 'relationship-level' | 'library-level';
+export type MaintainReversibility = 'archive' | 'restructure' | 'patch' | 'rename' | 'none';
+export type MaintainImpact = 'better' | 'worse' | 'neutral';
+export interface MaintainEvidence {
+    signal: string;
+    value: string;
+}
+export interface MaintainPlanItem {
+    kind: MaintainPlanItemKind;
+    names: string[];
+    rule: string;
+    evidence: MaintainEvidence[];
+    finding: string;
+    recommendation: string;
+    semantic_reasoning: string;
+    impact: MaintainImpact;
+    impact_reason: string;
+    reversibility: MaintainReversibility;
+    undo_path: string;
+    confidence: number;
+    needs_human: boolean;
+    is_override: boolean;
+    override_reason?: string | undefined;
+}
+export interface MaintainPlan {
+    verdict: MaintainVerdict;
+    plan: MaintainPlanItem[];
+    notes: string[];
+}
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    /** Normalized plan (needs_human impositions applied). */
+    plan: MaintainPlan;
+    /** Skill names whose items were force-marked needs_human by the quality_low gate. */
+    forcedHuman: string[];
+}
+/**
+ * Validate and normalize a maintain plan against the facts report.
+ * @param raw - subagent output (already JSON-parsed by the subagent channel).
+ * @param report - the DriftReport rendered into the facts block (quality_low gate source).
+ * @param validSignals - ids present in the rendered facts block.
+ */
+export declare function validateAndNormalizeMaintainPlan(raw: unknown, report: DriftReport, validSignals: ReadonlySet<string>): ValidationResult;
+//# sourceMappingURL=validate-plan.d.ts.map

package/package.json

@@ -1 +1,52 @@
-{"name":"@lmzhen/dsh-evolution-maintenance","version":"0.0.0","description":"placeholder bootstrap for OIDC publisher setup","license":"MIT"}
+{
+  "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.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-evolution-maintenance"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./tools": {
+      "types": "./lib/types/tools.d.ts",
+      "default": "./lib/tools.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/tools.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts",
+    "lib/types/tools.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@lmzhen/dsh-evolution-core": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}