@lmzhen/dsh-evolution-maintenance 0.3.82 → 0.4.0

package/README.md

@@ -1,30 +1,31 @@
-# @deepseek-ai/dsh-evolution-maintenance
-
-Skill-library drift-scanning determinism surface for the maintenance subagent
-(design 011 — the maintenance-subagent design paper, archived in git history).
-
-- `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). V10 (F-02): orchestrate soft-probes the tools
-  registry before spawning and degrades the filter to `skill`-only (declared
-  in the subagent prompt) when the tool row is not mounted, instead of failing
-  the spawn; an explicit `toolAllow` option bypasses the probe.
-- The model-visible template (`MAINTAIN_PROMPT`) and the subagent output
-  instruction (`MAINTAIN_OUTPUT_INSTRUCTION`, V10 F-16) ship in `evolution-core`
-  `PROMPT_BUNDLE`; the joint-signature mismatch protocol is honored by
-  `renderFacts` callers, not by this package alone.
+# @lmzhen/dsh-evolution-maintenance
+
+Skill-library drift-scanning determinism surface for the maintenance subagent: it assembles the
+skill snapshot, renders the mechanical-facts block and runs the scan → subagent → validate
+chain behind `/evolution maintain` (`evolution-core` `drift-signals`).
+
+- `snapshotFromLibrary`: assemble a plain skill snapshot from a SkillLibrary-like reader.
+- `renderFacts`: canonical `MECHANICAL_FACTS` block (version + joint signature + redaction).
+
+## Model surface
+
+- **Model-visible:** the read-only `maintenance_probe` tool schema (`evolution-maintenance/tools`), mounted for every session.
+- **Prompt prefix / KV cache:** no system-prompt section of its own; family-level rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
+- **Mount it?** yes — the `evolution-maintenance/tools` row (host/all/preset); the orchestration is consumed by `evolution-commands` (`/evolution maintain`).
+
+## Known limitations
+
+- Phase 1-2 expose no service beyond the command surface: the chain (scan → render → subagent → validate) is wired through `/evolution maintain`.
+- **Plan validation is instance-granular (§3 completeness).** Notes stay id-level: one mention explains away every instance of that id.
+- **A budget-capped dedup scan is reported, never silently shortened.**
+- `maintenance_probe` is readable by every session; maintenance subagents reach it through the orchestrate `toolFilter` allow-list.
+- The model-visible template (`MAINTAIN_PROMPT`) and the subagent output instruction (`MAINTAIN_OUTPUT_INSTRUCTION`, V10 F-16) ship in `evolution-core` `PROMPT_BUNDLE`; the joint-signature mismatch protocol is honored by `renderFacts` callers, not by this package alone.
 
 **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
+
+- (design 011: the maintenance-subagent design paper, archived in git history).
+- The facts block renders one line per skill, so ONE signal id can be `over` on several skills: every `over` instance (`skill::id`; a library-level signal renders once and keeps the bare id) must be covered by plan evidence or named in a note, so a plan that advises one skill no longer zero-explains the same signal on its siblings (P2-4, 0.3.83).
+- `maintenance_probe` appends "note: dedup scan truncated at the pair-comparison budget; groups may be incomplete" and the `dedup_group` signal value carries the same qualification (P2-8, 0.3.83).
+- V10 (F-02): orchestrate soft-probes the tools registry before spawning and degrades the filter to `skill`-only (declared in the subagent prompt) when the tool row is not mounted, instead of failing the spawn; an explicit `toolAllow` option bypasses the probe.

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

@@ -84,7 +84,12 @@ function findSnapshot(snapshots, name) {
 */
 function computeProbe(signal, target, snapshots) {
 	if (!PROBE_SIGNALS.includes(signal)) return result(signal, [`unknown-signal '${signal}' (allowed: ${PROBE_SIGNALS.join(", ")})`], target);
-	if (signal === "dedup_group") return result(signal, computeDedupGroups({ contents: new Map(snapshots.map((snapshot) => [snapshot.name, snapshot.body])) }).map((group) => group.join(" ~ ")));
+	if (signal === "dedup_group") {
+		const dedup = computeDedupGroups({ contents: new Map(snapshots.map((snapshot) => [snapshot.name, snapshot.body])) });
+		const details = dedup.groups.map((group) => group.join(" ~ "));
+		if (dedup.truncated) details.push("note: dedup scan truncated at the pair-comparison budget; groups may be incomplete");
+		return result(signal, details);
+	}
 	if (signal === "prefix_cluster") return result(signal, computePrefixClusters(snapshots.map((snapshot) => snapshot.name)).map((cluster) => `${cluster.key}: ${cluster.members.join(", ")}`));
 	if (signal === "usage_observed") {
 		if (!(snapshots.length > 0 && snapshots.every((snapshot) => snapshot.usageObserved !== null && snapshot.usageObserved !== void 0))) return result(signal, ["usage_observed=unknown"]);

package/lib/index.js

@@ -1,4 +1,4 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-0HDS4Bed.js";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-31K43lVa.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
@@ -232,18 +232,22 @@ function validateAndNormalizeMaintainPlan(raw, report, validSignals) {
 		}
 	}
 	const notes = Array.isArray(raw.notes) ? raw.notes.filter((note) => isNonEmptyString(note)) : [];
-	const overSignals = /* @__PURE__ */ new Set();
-	for (const signal of report.library) if (signal.verdict === "over") overSignals.add(signal.id);
-	for (const skill of report.skills) for (const signal of skill.signals) if (signal.verdict === "over") overSignals.add(signal.id);
-	const covered = new Set(plan.flatMap((item) => item.evidence.map((ev) => ev.signal)));
+	const overInstances = /* @__PURE__ */ new Map();
+	for (const signal of report.library) if (signal.verdict === "over") overInstances.set(signal.id, signal.id);
+	for (const skill of report.skills) for (const signal of skill.signals) if (signal.verdict === "over") overInstances.set(`${skill.name.trim()}::${signal.id}`, signal.id);
+	const covered = /* @__PURE__ */ new Set();
+	for (const item of plan) for (const ev of item.evidence) {
+		covered.add(ev.signal);
+		for (const name of item.names) covered.add(`${name}::${ev.signal}`);
+	}
 	const notesText = notes.join("\n");
-	if (verdict === "issues") if (plan.length === 0 && notes.length === 0 && overSignals.size > 0) errors.push("completeness: verdict=issues with an empty plan AND no notes — every over signal must be covered by evidence or named in a note (§3)");
+	if (verdict === "issues") if (plan.length === 0 && notes.length === 0 && overInstances.size > 0) errors.push("completeness: verdict=issues with an empty plan AND no notes — every over signal must be covered by evidence or named in a note (§3)");
 	else {
-		const uncovered = [...overSignals].filter((id) => !covered.has(id) && !notesText.includes(id));
+		const uncovered = [...overInstances].filter(([instance, id]) => !covered.has(instance) && !notesText.includes(id)).map(([instance]) => instance);
 		if (uncovered.length > 0) errors.push(`completeness: over signal(s) not covered by any plan evidence nor named in a note (${uncovered.join(", ")}) — §3 requires each over signal to be addressed or explicitly explained away`);
 	}
-	else if (verdict === "no_issues" && overSignals.size > 0) {
-		const uncovered = [...overSignals].filter((id) => !notesText.includes(id));
+	else if (verdict === "no_issues" && overInstances.size > 0) {
+		const uncovered = [...overInstances].filter(([, id]) => !notesText.includes(id)).map(([instance]) => instance);
 		if (uncovered.length > 0) errors.push(`completeness: verdict=no_issues while the facts block carries over signal(s) not named in any note (${uncovered.join(", ")}) — each signal must be explicitly explained away in notes (§3/§7)`);
 	}
 	if (errors.length > 0) return {

package/lib/tools.js

@@ -1,4 +1,4 @@
-import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-0HDS4Bed.js";
+import { i as snapshotFromLibrary, n as PROBE_SIGNALS, r as computeProbe, t as buildEnrichment } from "./enrichment-31K43lVa.js";
 import { assertSkillsRootAliasRetired, newSkillLibrary, redactSecrets, resolveRootConfig } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";

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