@lmzhen/dsh-evolution-review 0.8.0 → 0.10.0

package/README.md

@@ -17,12 +17,13 @@ own, and the delivery mode lives on the `evolution-policy` row, not here.
 - Review subagents are spawned with the plain `skill` tool only (`reviewToolAllow` default and the host/preset config both = `[skill]`: the DSH tool catalog has no `skill_search`/`skill_load` discovery pair, so the Hermes-lineage Anchored Standard `skill_search`/`skill_load` allow-list does not exist here).
 - Review subagents run as `spawn` children on the deployment default preset rather than inheriting the parent agent's composition (`fork`): a fork child is always promoted by the Anchored Standard bootstrap and its narrowed resident catalog would drop the plain `skill` tool from the review allow-list.
 - The review request text is redacted for credential-shaped patterns before it reaches the subagent, but redaction is pattern-based and best-effort, not a security boundary.
-- Read-before-write tracks only reads through the `skill` tool. `skill_manage` has no per-skill read action (`list`/`review` are whole-library, not targeted at one name), so a skill that was only listed via `skill_manage` is not marked as read: a background review may still reject a patch to it until it is actually loaded.
+- Read-before-write (the rule is `evolution-core`'s `skill-reads.ts`, shared with the tool path's admission gate) tracks only reads through the `skill` tool. `skill_manage` has no per-skill read action (`list`/`review` are whole-library, not targeted at one name), so a skill that was only listed via `skill_manage` is not marked as read: a background review may still reject a patch to it until it is actually loaded.
 - The completion-channel counters (`cumulativeToolCalls` / `completionInjected`) are in-memory only. A process restart resets them, which is accepted behavior: the completion review is a one-per-session post-task adaptation and a restart is treated as a fresh conversation boundary. The cadence state (`turnsSinceMemory` / `turnsSinceSkill`) is persisted via `ReviewState` and survives restart: bounded by `REVIEW_STATE_SESSION_CAP` (500, seam constant): the least-recently-active sessions are pruned on save, so a very old session restarting resumes from a fresh cadence baseline rather than an unbounded store.
 - `evolution/review-scheduled` and `evolution/review-error` are emitted for platform/user wiring only: this family has no in-repo production `ctx.on` consumer for them. They are declared externally owned (the platform side wires consumption), which matches the `EXEMPT_ORPHANS` set in `scripts/verify-event-pairing.mjs`.
 - When the `evolution-state` service is not mounted, the memory/skill cadence state is not persisted and every turn restarts from a clean `{ turnsSinceMemory: 0, turnsSinceSkill: 0 }` baseline: the review schedule is stateless and re-decided each turn rather than accumulating across the conversation. The loss is surfaced once per process as a logger warning at the first turn/end.
 - Read-before-write can see the review subagent's own `skill` reads only when the subagent backend exposes `localAgent` (the in-process driver does; out-of-process backends such as ACP and the CLI providers set `localAgent: undefined`). With a remote backend the subagent's reads are invisible, so a plan item patching a skill the subagent itself loaded is dropped as "unread": the review then falls back to the parent session's reads only.
 - **The default `reviewMode: 'inject'` produces no plan ledger.** The review runs in the parent session and emits no `evolution/plan-applied` event, so `evolution-activity`'s `activity.json` and the `evolution-replay` leaderboard never grow in this mode: the only production emit point sits inside the subagent path. Set `reviewMode: 'subagent'` on the `evolution-policy` row when the plan audit trail is required; the plugin states this once at load instead of leaving an empty ledger to be read as "no reviews happened" (v37 S2.2, plan decision (c)).
+- **Evidence that cites only bookkeeping frames is REPORTED, never refused (phase 1).** `EVIDENCE_CLASS` (`evolution-plan-validator`) counts the ops whose entire `evidence` list points at turn/step boundary frames — a seq the range rule accepts but that carries no content — and this plugin logs one `dsh-evolution-review:` warning per plan; the count rides `evolution/plan-applied` as `evidenceClassReports` and appears in no model-visible text. Nothing is dropped: `EVIDENCE_RANGE` remains the only evidence gate, and a session log whose frames carry no `seq` leaves the report silent (`undefined` is not an empty index) instead of reporting every op.
 - **`.pinned` protection in the `'inject'` channel rides a family-internal session mark.** The review prompt marks the parent session, `tool-skill-manage` reads that mark and resolves both origin surfaces (approval + library) to `background_review`, and the next REAL user message (`source.kind === 'user'`) clears it (plugin notices, including the review prompt itself, do not). Two bounds follow from the platform's inject contract (no driver wake; a prompt is dropped on cancel/dispose and may be missed with an already-claimed batch): with `reviewWakeInject: false`, or on a host without `followup`, (a) a pending prompt may never execute while the session stays idle, and (b) when the user's next message wakes the session, the mark is cleared before that pending prompt reaches the model (its writes are then attributed `foreground` and the pinned guard does not cover them). A prompt delivered while a HUMAN message is already queued is not marked at all: the platform claims that human turn first, so a session-level window would attribute the user's own writes to `background_review` (S2-8, FLOW1-3): the plugin reads the pre-claim queue (`agent.inbox`) because the platform exposes no claim identity, and warns once per mount when it withholds the mark.
 
 ## Configuration

package/lib/index.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
-import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, advanceReview, assertSkillsRootAliasRetired, clampedNumber, clearReviewChannel, contentHash, evolutionIoAdapter, foldToolDispatches, foldTurn, installParamSection, markReviewChannel, newSkillLibrary, paramNamespace, policyStageLimits, readDispatchSignal, readNumberParam, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, skillReadNameOf, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { COMPLETION_SKILL_REVIEW_PROMPT, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_REVIEW_CONTEXT_MESSAGES, DEFAULT_REVIEW_MEMORY_INTERVAL, DEFAULT_REVIEW_MESSAGE_CHARS, DEFAULT_REVIEW_SKILL_INTERVAL, DEFAULT_REVIEW_TIMEOUT_MS, DEFAULT_SKILL_CONTENT_CHARS, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_REVIEW_COMPLETION_MIN_TOOL_CALLS, DEFAULT_SKILL_REVIEW_MODEL, DEFAULT_SKILL_REVIEW_TRIGGER, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_USER_CHAR_LIMIT, MAX_TIMER_DELAY_MS, PROMPT_BUNDLE, advanceReview, assertSkillsRootAliasRetired, clampedNumber, clearReviewChannel, collectReadSkillNames, contentHash, evidenceKindIndex, evolutionIoAdapter, filterUnreadSkillOps, filterUnreadSkillOps as filterUnreadSkillOps$1, foldTurn, installParamSection, markReviewChannel, newSkillLibrary, paramNamespace, policyStageLimits, readDispatchSignal, readNumberParam, redactSecrets, resolveOrigins, resolveRootConfig, reviewPrompt, sessionAudited, sweepReviewChannelSessions, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
 import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
 //#region lib/types/session-state.js
 /**
@@ -634,6 +634,7 @@ function apply(ctx, rawConfig = {}) {
 			}
 			const preRunHashes = await treeSkillHashes();
 			const sessionSeqAtPlanTime = session.seq - 1;
+			const substantiveEvidenceSeqs = evidenceKindIndex(session.snapshotEvents());
 			const run = await subagents.start("spawn", {
 				label: "dsh-evolution-review",
 				prompt: [{
@@ -661,19 +662,21 @@ function apply(ctx, rawConfig = {}) {
 					ctx.logger.warn(`dsh-evolution-review: review subagent returned no structured plan${stopDetail !== void 0 ? ` (stopReason=${stopDetail}${diagDetail !== void 0 ? `; diagnostic=${diagDetail}` : ""})` : ""}`);
 					return false;
 				}
-				const childReads = run.localAgent ? collectReadSkillNames(run.localAgent.session) : /* @__PURE__ */ new Set();
+				const childReads = run.localAgent ? collectReadSkillNames(run.localAgent.session.snapshotEvents()) : /* @__PURE__ */ new Set();
 				const plan = result.structured;
 				const policyFingerprint = fingerprintPolicy(snapshot);
 				const validation = validateEvolutionPlan(plan, {
 					sessionSeq: sessionSeqAtPlanTime,
+					substantiveEvidenceSeqs,
 					maxOpsPerPlan: snapshot?.maxOpsPerPlan ?? DEFAULT_MAX_OPS_PER_PLAN,
 					protectedSkillNames: new Set(snapshot?.protectedSkillNames ?? []),
 					maxMemoryChars: snapshot?.memoryChars ?? DEFAULT_MEMORY_CHAR_LIMIT,
 					maxUserChars: snapshot?.userChars ?? DEFAULT_USER_CHAR_LIMIT,
 					maxSkillContentChars: snapshot?.skillContentChars ?? DEFAULT_SKILL_CONTENT_CHARS
 				});
+				if (validation.reports.length > 0) ctx.logger.warn(`dsh-evolution-review: ${validation.reports.length} op(s) cite only bookkeeping frames as evidence: ${validation.reports.map((report) => report.reason).join("; ")}`);
 				const acceptedSkillOps = validation.accepted.skillOps ?? [];
-				const skippedUnread = filterUnreadSkillOps(acceptedSkillOps, new Set([...collectReadSkillNames(session), ...childReads]));
+				const skippedUnread = filterUnreadSkillOps$1(acceptedSkillOps, new Set([...collectReadSkillNames(session.snapshotEvents()), ...childReads]));
 				const evidenceQuotes = [...validation.accepted.memoryOps ?? [], ...acceptedSkillOps].reduce((total, op) => total + (Array.isArray(op.evidence) ? op.evidence.length : 0), 0);
 				const emitApplied = (report) => {
 					try {
@@ -685,6 +688,7 @@ function apply(ctx, rawConfig = {}) {
 							skillApplied: report.actions.filter((action) => action.startsWith("Skill ")).length,
 							rejectedOps: validation.rejected.length,
 							...skippedUnread > 0 ? { skippedUnread } : {},
+							...validation.reports.length > 0 ? { evidenceClassReports: validation.reports.length } : {},
 							executionFailures: report.failedOps?.length ?? 0,
 							...report.executionError !== void 0 ? { executionError: report.executionError } : {},
 							evidenceQuotes,
@@ -1054,29 +1058,6 @@ function staleRefusal(result, name, filePath) {
 		message: filePath === void 0 ? `Skill "${name}" changed since this plan was produced — the full-content update was refused as stale. Re-read the skill and produce a fresh plan.` : `Support file "${filePath}" of "${name}" changed since this plan was produced — the staged file operation was refused as stale. Re-read the skill tree and produce a fresh plan.`
 	};
 }
-/**
-* v37 P7a: the read-before-write credit now comes from evolution-core's
-* `tool-dispatch` module — the ONE reader of the platform's dispatch event
-* types, and the ONE authority on which tool reads a skill.
-*
-* v32 REV-06(a) is preserved by the normalizer: a skill counts as READ only
-* when it did not fail, so a failed/timeout read still cannot pass the
-* read-before-write gate and let the review blind-overwrite content the model
-* never saw. What changed is the vocabulary the gate listens to: matching
-* `tool/call` here meant every PTC session (`tool/ptc-dispatch*`) collected an
-* EMPTY set, so `filterUnreadSkillOps` dropped every mutating op the model had
-* legitimately read first — and nothing reported the loss.
-* @param session - the session whose log is folded.
-* @returns the skill names this session read through a non-failed dispatch.
-*/
-function collectReadSkillNames(session) {
-	const names = /* @__PURE__ */ new Set();
-	for (const dispatch of foldToolDispatches(session.snapshotEvents())) {
-		const name = skillReadNameOf(dispatch);
-		if (name !== void 0) names.add(name);
-	}
-	return names;
-}
 /** Map/set size that triggers a dead-session counter sweep (bounded, not a hard cap). */
 const COUNTER_SWEEP_THRESHOLD = 128;
 /**
@@ -1094,35 +1075,6 @@ function sweepDeadSessionEntries(entries, isAlive) {
 	}
 	return removed;
 }
-/**
-* Drop mutating ops whose target was not read this session, in place.
-* Create is exempt (no read required to author a new skill). Covers the same
-* mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
-* background review cannot blind-touch support files or edits of skills it
-* never loaded. Returns the count of dropped ops so the plan event can report
-* them as rejected.
-*/
-function filterUnreadSkillOps(ops, readNames) {
-	const READ_REQUIRED = [
-		"edit",
-		"update",
-		"patch",
-		"delete",
-		"write_file",
-		"remove_file",
-		"restructure"
-	];
-	let dropped = 0;
-	for (let index = ops.length - 1; index >= 0; index -= 1) {
-		const op = ops[index];
-		if (!op) continue;
-		if (op.name && READ_REQUIRED.includes(op.action ?? "patch") && !readNames.has(op.name)) {
-			ops.splice(index, 1);
-			dropped += 1;
-		}
-	}
-	return dropped;
-}
 function fingerprintPolicy(snapshot) {
 	try {
 		return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex").slice(0, 12);

package/lib/types/index.d.ts

@@ -6,6 +6,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { Session } from '@deepseek-ai/dsh-session';
 import { type ReviewKind } from '@lmzhen/dsh-evolution-core';
+export { filterUnreadSkillOps } from '@lmzhen/dsh-evolution-core';
 export declare const name = "evolution-review";
 export declare const inject: string[];
 export interface Config {
@@ -26,6 +27,8 @@ export interface Config {
     /** Shadowed by the policy snapshot in every shipped composition — configure
      * `reviewMemoryInterval` on the `evolution-policy` row instead (v37 P2-24).
      * Deprecated alias (G0/S0.3): still readable, refused by writes; removed 0.7.0. */
+    /** Review cadence in TOOL CALLS (signals.ts: a turn advances by its tool-call count, minimum 1,
+     * or by 1 when the turn itself carried the memory signal). */
     memoryInterval?: number;
     /** Shadowed by the policy snapshot in every shipped composition — configure
      * `reviewSkillInterval` on the `evolution-policy` row instead. Deprecated
@@ -133,9 +136,11 @@ export declare function clampReviewConfig(rawConfig: Config, ctx: Context): Clam
  * parameter ids from the registry, so the settings document, the params output,
  * the doctor report and the cards all spell one name. */
 export interface ReviewSettings {
-    /** Activity units between skill-review injections. */
+    /** Tool calls between skill-review injections (a turn with no tool call counts as one; a turn
+     * that itself used a skill advances the counter by 1). */
     reviewSkillInterval: number;
-    /** Activity units between memory-review injections. */
+    /** Tool calls between memory-review injections (a turn with no tool call counts as one; a turn
+     * that itself touched memory advances the counter by 1). */
     reviewMemoryInterval: number;
     /** Which channel may inject a skill review. */
     skillReviewTrigger: 'cadence' | 'completion' | 'both';
@@ -164,18 +169,6 @@ export declare function shouldCompletionReview(reason: {
  * number of removed entries.
  */
 export declare function sweepDeadSessionEntries<K>(entries: Map<K, unknown> | Set<K>, isAlive: (id: K) => boolean): number;
-/**
- * Drop mutating ops whose target was not read this session, in place.
- * Create is exempt (no read required to author a new skill). Covers the same
- * mutating surface Hermes guards (edit/patch/write_file/remove_file), so a
- * background review cannot blind-touch support files or edits of skills it
- * never loaded. Returns the count of dropped ops so the plan event can report
- * them as rejected.
- */
-export declare function filterUnreadSkillOps(ops: Array<{
-    action?: string;
-    name?: string;
-}>, readNames: ReadonlySet<string>): number;
 /**
  * V10-10 (P2-11) / A1 (audit P1-1): render one `[result]` evidence line from
  * a tool-result event payload. The former read (`data.output`) targeted a
@@ -204,5 +197,4 @@ export declare function buildReviewRequest(session: Session, kind: ReviewKind, s
     userChars: number;
     assistantChars: number;
 }, maxMessages: number, maxMessageChars: number): string;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-review",
   "description": "Background review orchestration (community build)",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.8.0",
-    "@lmzhen/dsh-evolution-core": "^0.8.0",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.8.0"
+    "@lmzhen/dsh-evolution-approval": "^0.10.0",
+    "@lmzhen/dsh-evolution-core": "^0.10.0",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.10.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -37,8 +37,8 @@
     "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-state": "^0.8.0",
-    "@lmzhen/dsh-evolution-policy": "^0.8.0"
+    "@lmzhen/dsh-evolution-state": "^0.10.0",
+    "@lmzhen/dsh-evolution-policy": "^0.10.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
@@ -48,10 +48,10 @@
     "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-approval": "^0.8.0",
-    "@lmzhen/dsh-evolution-core": "^0.8.0",
-    "@lmzhen/dsh-evolution-curator": "^0.8.0",
-    "@lmzhen/dsh-evolution-plan-validator": "^0.8.0",
-    "@lmzhen/dsh-evolution-state": "^0.8.0"
+    "@lmzhen/dsh-evolution-approval": "^0.10.0",
+    "@lmzhen/dsh-evolution-core": "^0.10.0",
+    "@lmzhen/dsh-evolution-curator": "^0.10.0",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.10.0",
+    "@lmzhen/dsh-evolution-state": "^0.10.0"
   }
 }