dsh-continual-evolve 0.4.0 → 0.5.0

package/README.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-527%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-543%20passing-brightgreen)]()
 
 Continual self-evolution for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a versioned, auditable, rollback-safe harness state layer — prompt notes, memories, skills, subagent specs — refined from session trajectories.
 
@@ -20,11 +20,12 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 - **Local scope** per session; **global scope** across sessions with merge semantics — plus mechanical promotion guards so only portable, substantial, non-duplicate knowledge reaches global
 - **Deterministic rollback**: inverse edits generated from applied results — no LLM re-guessing
 - **Benchmark loop**: candidate refinements are evaluated against frozen cases by a separate scorer before acceptance (rubric encrypted at rest)
+- **Store hygiene**: `/evolve consolidate` turns write-time conflict hints and zero-use staleness into one approved, fully reversible batch of archives
 
 ## How it works
 
 1. **Sediment** — the model creates entries via `evolve_add`, or the automatic review gate proposes them from the session trajectory (turn-interval + compaction checkpoints).
-2. **Guard** — code-enforced validation: edit schema, blast-radius/scope coherence, and the promotion policy (project-scoped markers, thin content, near-duplicate detection keep the global store clean).
+2. **Guard** — code-enforced validation: edit schema, blast-radius/scope coherence, and the promotion policy (project-scoped markers, thin content, near-duplicate detection keep the global store clean). Global creates that near-duplicate an existing entry are rejected at write time (≥0.8 similarity); moderate overlaps carry a `conflictHint` for later consolidation.
 3. **Approve** — global writes require explicit human approval; local-fate proposals are consulted before they land.
 4. **Apply & inject** — atomic apply with snapshot + audit event. Prompt notes and delegation specs inject into the system prompt (capped, relevance-ranked, zero tokens when empty); memories/skills appear as a capped directory index.
 5. **Validate & roll back** — benchmarks score candidates against frozen cases; rejected candidates roll back deterministically.
@@ -52,6 +53,7 @@ Commands (in-session):
 | `/evolve plan [msg]` | run the LLM planner against the store |
 | `/evolve wrapup` | assess this session's local entries: promote / archive / keep |
 | `/evolve archive · unarchive · demote <id>` | hide from injection (data kept, restorable) — `demote` targets global noise |
+| `/evolve consolidate [apply]` | report (or apply) one batch archive of conflict-hinted + stale zero-use global entries |
 | `/evolve failures` | aggregated failure classes (gate + benchmark) |
 | `/evolve log [tail N] [session <id>]` | plugin log |
 | `/evolve export · import <path>` | backup / restore a store |
@@ -100,7 +102,7 @@ Example profile patch:
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (527 tests)
+pnpm test                    # vitest (543 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm lint                    # oxlint src test
 ```

package/README.zh.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-527%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-543%20passing-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
 
@@ -20,11 +20,12 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 - **local 会话级 / global 跨会话** 双作用域与合并语义——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
 - **确定性回滚**：逆操作编辑由已应用结果生成——不靠 LLM 重新猜测
 - **benchmark 闭环**：候选沉淀先经冻结用例 + 独立评分者评估再接受（rubric 加密落盘）
+- **store 卫生**：`/evolve consolidate` 把写入时冲突提示与零使用陈旧条目变成一次批准、完全可逆的批量归档
 
 ## 工作原理
 
 1. **沉淀**——模型经 `evolve_add` 创建条目，或自动 review 门禁从会话轨迹提议（回合间隔 + 压缩检查点）。
-2. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测保持全局库干净）。
+2. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测保持全局库干净）。全局 create 与既有条目高度相似（≥0.8）时写入即拒；中等重叠带 `conflictHint` 供后续合并。
 3. **审批**——全局写入需明确人工批准；local 归宿提议先征询后落地。
 4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、空 store 零 token）；memory/skill 以目录索引出现。
 5. **验证与回滚**——benchmark 用冻结用例为候选打分；被拒候选确定性回滚。
@@ -52,6 +53,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `/evolve plan [msg]` | 对 store 运行 LLM 规划器 |
 | `/evolve wrapup` | 收尾本会话 local 条目：晋升 / 归档 / 保留 |
 | `/evolve archive · unarchive · demote <id>` | 从注入中隐藏（数据保留可恢复）——`demote` 针对全局噪声 |
+| `/evolve consolidate [apply]` | 报告（或应用）冲突提示 + 零使用陈旧全局条目的批量归档 |
 | `/evolve failures` | 失败类聚合（门禁 + benchmark） |
 | `/evolve log [tail N] [session <id>]` | 插件日志 |
 | `/evolve export · import <path>` | 备份 / 恢复 store |
@@ -100,7 +102,7 @@ profile patch 示例：
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（527 例）
+pnpm test                    # vitest（543 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm lint                    # oxlint src test
 ```

package/lib/command.js

@@ -13,6 +13,8 @@ import { executeGoalCommand } from "./goal-command.js";
 import { executeMountCommand, executeUnmountCommand } from "./mount-command.js";
 import { executeBenchmarkCommand } from "./benchmark-command.js";
 import { executeWrapupCommand } from "./wrapup-command.js";
+import { loadUsage } from "./usage.js";
+import { planConsolidation } from "./consolidate.js";
 const USAGE = `Usage:
   /evolve                  show this help and the current local store
   /evolve list [global]    list entries (add "global" for the cross-session store)
@@ -24,6 +26,8 @@ const USAGE = `Usage:
   /evolve archive <id> [global]   hide an entry from injection (data kept, restorable)
   /evolve unarchive <id> [global] restore an archived entry
   /evolve demote <id>             hide a (global) entry from injection, keep data
+  /evolve consolidate [apply]     report (or apply) a batch archive of conflict-hinted
+                                  and stale zero-use global entries
   /evolve log [tail N]            show the recent plugin log (default 50 lines)
   /evolve failures               aggregated failure counts (gate + benchmark, by class)
   /evolve export [global] <path>  backup a store to a JSON file
@@ -172,6 +176,28 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 }, { scope });
                 return success(renderResult(result));
             }
+            case "consolidate": {
+                // R3: deterministic global-store hygiene. Report by default;
+                // `apply` re-scans fresh state and lands the whole batch as ONE
+                // refinement (single snapshot + audit record, fully rollback-able).
+                const apply = rest[0] === "apply";
+                const state = engine.load("global", undefined);
+                const { candidates, edits } = planConsolidation(state, loadUsage(engine.baseDir));
+                if (candidates.length === 0) {
+                    return success("global store is already consolidated — no conflict-hinted or stale zero-use entries.");
+                }
+                const report = candidates.map((candidate, index) => `${index + 1}. [${candidate.kind}:${candidate.id}] ${candidate.title}\n   ${candidate.reason}`).join("\n");
+                if (!apply) {
+                    return success(`consolidation plan — ${candidates.length} archive candidate(s):\n${report}\n(run "/evolve consolidate apply" to archive all of them in one refinement)`);
+                }
+                const result = engine.apply("global", undefined, {
+                    summary: `Consolidate global store: archive ${candidates.length} entries`,
+                    rationale: "Human-invoked batch consolidation via /evolve consolidate apply.",
+                    expectedOutcome: "Candidate entries are hidden from injection (data kept; restorable via /evolve unarchive).",
+                    edits,
+                }, { scope: "global" });
+                return success(`${report}\n\napplied:\n${renderResult(result)}`);
+            }
             case "failures": {
                 // /evolve failures — failure-signature aggregation (D1 observation):
                 // failed review-gate records + failed benchmark cells, counted by class.

package/lib/consolidate.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Global-store consolidation (R3): turn the two hygiene signals — R2's
+ * `conflictHint` stamps and usage v2's zero-injection staleness — into one
+ * deterministic, human-approved batch of archive edits (`/evolve consolidate`).
+ *
+ * Design (ADR implemented/feature/2026-08-24-consolidation-command.md):
+ * - pure functions only; the command layer owns loading, reporting, and the
+ *   apply phase, and ALWAYS re-scans fresh state before applying (the report
+ *   and the apply are two separate invocations — prefer under-archiving over
+ *   mis-archiving when state moved in between);
+ * - archiving keeps data (ARCHIVED_AT_KEY stamp, restorable via
+ *   `/evolve unarchive`) and preserves every existing metadata key including
+ *   the conflictHint itself, so unarchived entries keep their trail;
+ * - no LLM call anywhere: code proposes, the human disposes.
+ */
+import type { HarnessState, RefinementEdit, RefinementKind } from "./types.js";
+import { type UsageStore } from "./usage.js";
+/** Zero-use entries at least this old are stale candidates (30d, matching the injection recency half-life scale). */
+export declare const STALE_MIN_AGE_MS: number;
+/** Parsed `<kind>:<id>:<score>` value of a {@link CONFLICT_HINT_KEY} stamp. */
+export interface ConflictHint {
+    kind: RefinementKind;
+    id: string;
+    score: number;
+}
+/**
+ * Parse one conflictHint metadata value. Returns undefined for anything that
+ * is not exactly `<kind>:<id>:<score>` with a known kind and a score in
+ * [0, 1] — foreign or legacy junk must never crash the scan.
+ */
+export declare function parseConflictHint(value: unknown): ConflictHint | undefined;
+/** One planned archive with its human-readable justification. */
+export interface ConsolidationCandidate {
+    kind: RefinementKind;
+    id: string;
+    title: string;
+    reason: string;
+}
+/**
+ * Entries stamped by the write-time conflict guard whose target still exists
+ * and is still active. The hinted (newer) entry is the archive candidate —
+ * the pointed-to original stays as the live copy.
+ */
+export declare function findConflictPairs(state: HarnessState): ConsolidationCandidate[];
+/**
+ * Active global entries never injected in any session and untouched for at
+ * least `minAgeMs`: prime staleness candidates. Operates on whatever state
+ * it is handed (callers pass the global store).
+ */
+export declare function findStaleEntries(state: HarnessState, store: UsageStore, now: number, minAgeMs?: number): ConsolidationCandidate[];
+/**
+ * Merge both scans (conflict reason wins on overlap), deduped by kind:id,
+ * and build the batch archive edits. Each edit preserves the entry's full
+ * content and existing metadata — only ARCHIVED_AT_KEY is added — so
+ * `/evolve unarchive` restores everything intact.
+ *
+ * @param now Epoch ms used for the archivedAt stamp (injected for tests).
+ */
+export declare function planConsolidation(state: HarnessState, store: UsageStore, now?: number, opts?: {
+    minAgeMs?: number;
+}): {
+    candidates: ConsolidationCandidate[];
+    edits: RefinementEdit[];
+};
+//# sourceMappingURL=consolidate.d.ts.map

package/lib/consolidate.js

@@ -0,0 +1,113 @@
+import { ARCHIVED_AT_KEY, CONFLICT_HINT_KEY, isArchived } from "./types.js";
+import { getUsageCount } from "./usage.js";
+/** Zero-use entries at least this old are stale candidates (30d, matching the injection recency half-life scale). */
+export const STALE_MIN_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const KINDS = ["prompt", "memory", "skill", "subagent"];
+/**
+ * Parse one conflictHint metadata value. Returns undefined for anything that
+ * is not exactly `<kind>:<id>:<score>` with a known kind and a score in
+ * [0, 1] — foreign or legacy junk must never crash the scan.
+ */
+export function parseConflictHint(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const parts = value.split(":");
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const [kind, id, rawScore] = parts;
+    if (!kind || !id || !rawScore || !KINDS.includes(kind)) {
+        return undefined;
+    }
+    const score = Number(rawScore);
+    if (!Number.isFinite(score) || score < 0 || score > 1) {
+        return undefined;
+    }
+    return { kind: kind, id, score };
+}
+/**
+ * Entries stamped by the write-time conflict guard whose target still exists
+ * and is still active. The hinted (newer) entry is the archive candidate —
+ * the pointed-to original stays as the live copy.
+ */
+export function findConflictPairs(state) {
+    const candidates = [];
+    for (const kind of KINDS) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (isArchived(entry))
+                continue;
+            const hint = parseConflictHint(entry.metadata[CONFLICT_HINT_KEY]);
+            if (!hint || hint.kind !== kind)
+                continue;
+            const target = state.entries[hint.kind]?.[hint.id];
+            if (!target || isArchived(target))
+                continue;
+            candidates.push({
+                kind,
+                id: entry.id,
+                title: entry.title,
+                reason: `near-duplicate of ${hint.id} 「${target.title}」 (${Math.round(hint.score * 100)}%) — keep the original`,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Active global entries never injected in any session and untouched for at
+ * least `minAgeMs`: prime staleness candidates. Operates on whatever state
+ * it is handed (callers pass the global store).
+ */
+export function findStaleEntries(state, store, now, minAgeMs = STALE_MIN_AGE_MS) {
+    const candidates = [];
+    for (const kind of KINDS) {
+        for (const entry of Object.values(state.entries[kind])) {
+            if (isArchived(entry))
+                continue;
+            if (getUsageCount(store, kind, entry.id) !== 0)
+                continue;
+            const updatedAt = Date.parse(entry.updated_at);
+            if (Number.isNaN(updatedAt) || now - updatedAt < minAgeMs)
+                continue;
+            candidates.push({
+                kind,
+                id: entry.id,
+                title: entry.title,
+                reason: `0 injections since ${entry.updated_at.slice(0, 10)} (stale)`,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Merge both scans (conflict reason wins on overlap), deduped by kind:id,
+ * and build the batch archive edits. Each edit preserves the entry's full
+ * content and existing metadata — only ARCHIVED_AT_KEY is added — so
+ * `/evolve unarchive` restores everything intact.
+ *
+ * @param now Epoch ms used for the archivedAt stamp (injected for tests).
+ */
+export function planConsolidation(state, store, now = Date.now(), opts) {
+    const byKey = new Map();
+    for (const candidate of [...findConflictPairs(state), ...findStaleEntries(state, store, now, opts?.minAgeMs)]) {
+        const key = `${candidate.kind}:${candidate.id}`;
+        if (!byKey.has(key)) {
+            byKey.set(key, candidate);
+        }
+    }
+    const candidates = [...byKey.values()];
+    const edits = candidates.map((candidate) => {
+        const entry = state.entries[candidate.kind][candidate.id];
+        const metadata = { ...entry?.metadata, [ARCHIVED_AT_KEY]: new Date(now).toISOString() };
+        return {
+            action: "update",
+            kind: candidate.kind,
+            id: candidate.id,
+            title: candidate.title,
+            content: entry?.content ?? "",
+            metadata,
+        };
+    });
+    return { candidates, edits };
+}
+//# sourceMappingURL=consolidate.js.map

package/lib/inject.d.ts

@@ -19,6 +19,9 @@
  */
 import type { HarnessEntry, HarnessState } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
+import { tokenize } from "./search.js";
+/** CJK-bigram tokenizer re-exported for ranking consumers (see search.ts). */
+export { tokenize };
 /** Prompt sections render at most this many entries per kind. */
 export declare const MAX_INJECTED_ENTRIES_PER_KIND = 6;
 /** Per-entry content budget inside the injected block (matches render.ts). */
@@ -60,17 +63,6 @@ export interface AgentLike {
 export interface InjectContext {
     agent?: AgentLike;
 }
-/**
- * Lowercase tokenization for the keyword relevance scorer: runs of ASCII
- * alphanumerics and CJK characters become tokens (CJK is not split so whole
- * Chinese words/characters stay comparable), everything else is a separator.
- */
-export declare function tokenize(text: string): string[];
-/**
- * Keyword hit count of `query` tokens inside an entry: title hits weigh 2×,
- * content/path hits 1×. BM25-level relevance without any external service.
- */
-export declare function relevanceHits(entry: HarnessEntry, query: string): number;
 /**
  * Normalized recency in [0, 1]: 1 when the entry was just updated, decaying
  * linearly to 0 after {@link RECENCY_HALF_LIFE_MS}. Unparseable timestamps
@@ -79,11 +71,13 @@ export declare function relevanceHits(entry: HarnessEntry, query: string): numbe
 export declare function recencyScore(entry: HarnessEntry, now: number): number;
 /**
  * Rank entries for injection, best first. With no query the ranking is pure
- * recency (newest first). With a query, any entry with at least one keyword
- * hit outranks every hit-less entry (`hits * 2 + recency <= 1` for the
- * latter), and hits decide the order among relevant entries; recency then
- * breaks remaining ties, and the stable dictionary order is the final
- * tiebreak, so the result is deterministic.
+ * recency (newest first). With a query, entries are scored once against a
+ * per-call BM25 index (CJK bigrams; field-weighted title ×2 — see
+ * search.ts): any entry with a positive score (≥1 matched token) outranks
+ * every hit-less entry (score exactly 0), scores decide the order among
+ * relevant entries, recency breaks remaining ties, and the stable dictionary
+ * order is the final tiebreak, so the result is deterministic. The input is
+ * never mutated.
  */
 export declare function rankEntries(entries: readonly HarnessEntry[], query?: string, now?: number): HarnessEntry[];
 /**

package/lib/inject.js

@@ -2,6 +2,9 @@ import { isArchived } from "./types.js";
 import { mergeHarnessStates } from "./state.js";
 import { entryLine } from "./render.js";
 import { recordInjection } from "./usage.js";
+import { buildRelevanceIndex, relevanceScore, tokenize } from "./search.js";
+/** CJK-bigram tokenizer re-exported for ranking consumers (see search.ts). */
+export { tokenize };
 /** Prompt sections render at most this many entries per kind. */
 export const MAX_INJECTED_ENTRIES_PER_KIND = 6;
 /** Per-entry content budget inside the injected block (matches render.ts). */
@@ -18,31 +21,6 @@ export const MAX_QUERY_CHARS = 400;
 function stableCompare(a, b) {
     return [a.path, a.title, a.id].join("\0").localeCompare([b.path, b.title, b.id].join("\0"));
 }
-/**
- * Lowercase tokenization for the keyword relevance scorer: runs of ASCII
- * alphanumerics and CJK characters become tokens (CJK is not split so whole
- * Chinese words/characters stay comparable), everything else is a separator.
- */
-export function tokenize(text) {
-    return text
-        .toLowerCase()
-        .split(/[^a-z0-9\u4e00-\u9fff]+/)
-        .filter((token) => token.length > 0);
-}
-/**
- * Keyword hit count of `query` tokens inside an entry: title hits weigh 2×,
- * content/path hits 1×. BM25-level relevance without any external service.
- */
-export function relevanceHits(entry, query) {
-    const titleTokens = tokenize(entry.title);
-    const bodyTokens = tokenize(`${entry.content} ${entry.path}`);
-    let hits = 0;
-    for (const token of tokenize(query)) {
-        hits += titleTokens.filter((t) => t === token).length * 2;
-        hits += bodyTokens.filter((t) => t === token).length;
-    }
-    return hits;
-}
 /**
  * Normalized recency in [0, 1]: 1 when the entry was just updated, decaying
  * linearly to 0 after {@link RECENCY_HALF_LIFE_MS}. Unparseable timestamps
@@ -61,20 +39,34 @@ export function recencyScore(entry, now) {
 }
 /**
  * Rank entries for injection, best first. With no query the ranking is pure
- * recency (newest first). With a query, any entry with at least one keyword
- * hit outranks every hit-less entry (`hits * 2 + recency <= 1` for the
- * latter), and hits decide the order among relevant entries; recency then
- * breaks remaining ties, and the stable dictionary order is the final
- * tiebreak, so the result is deterministic.
+ * recency (newest first). With a query, entries are scored once against a
+ * per-call BM25 index (CJK bigrams; field-weighted title ×2 — see
+ * search.ts): any entry with a positive score (≥1 matched token) outranks
+ * every hit-less entry (score exactly 0), scores decide the order among
+ * relevant entries, recency breaks remaining ties, and the stable dictionary
+ * order is the final tiebreak, so the result is deterministic. The input is
+ * never mutated.
  */
 export function rankEntries(entries, query, now = Date.now()) {
     const q = (query ?? "").trim();
-    return [...entries].sort((a, b) => {
-        if (q.length > 0) {
-            const relevanceDelta = relevanceHits(b, q) * 2 - relevanceHits(a, q) * 2;
-            if (relevanceDelta !== 0) {
-                return relevanceDelta;
+    if (q.length === 0) {
+        return [...entries].sort((a, b) => {
+            const recencyDelta = recencyScore(b, now) - recencyScore(a, now);
+            if (recencyDelta !== 0) {
+                return recencyDelta;
             }
+            return stableCompare(a, b);
+        });
+    }
+    // Precompute scores once: the old comparator re-tokenized both sides on
+    // every comparison (O(n log n) tokenizations); one index + one score per
+    // entry turns the pass into table lookups.
+    const index = buildRelevanceIndex(entries);
+    const scores = new Map(entries.map((entry) => [entry, relevanceScore(index, entry, q)]));
+    return [...entries].sort((a, b) => {
+        const relevanceDelta = (scores.get(b) ?? 0) - (scores.get(a) ?? 0);
+        if (relevanceDelta !== 0) {
+            return relevanceDelta;
         }
         const recencyDelta = recencyScore(b, now) - recencyScore(a, now);
         if (recencyDelta !== 0) {

package/lib/promotion.d.ts

@@ -14,7 +14,7 @@
  * Pure functions only — the callers (wrapup command, gate local-fate phase)
  * supply the resolved {@link PromotionPolicy}.
  */
-import type { HarnessState, RefinementKind } from "./types.js";
+import type { HarnessEntry, HarnessState, RefinementKind } from "./types.js";
 export interface PromotionPolicy {
     /** Content matching any pattern is project-scoped and stays local. */
     blockPatterns: RegExp[];
@@ -24,6 +24,15 @@ export interface PromotionPolicy {
     maxContentOverlap: number;
 }
 export declare const DEFAULT_PROMOTION_POLICY: PromotionPolicy;
+/**
+ * Write-time conflict guard (R2): a global create whose similarity against an
+ * existing same-kind entry reaches this score is rejected outright — a
+ * near-duplicate adds zero information and the model should evolve_update
+ * the existing entry instead.
+ */
+export declare const CONFLICT_BLOCK_SCORE = 0.8;
+/** Similarity at/above this stamps {@link CONFLICT_HINT_KEY} but lets the write proceed. */
+export declare const CONFLICT_WARN_SCORE = 0.5;
 /**
  * Build a policy from config values (schemastery strings compiled here so
  * the config layer never touches RegExp). Invalid patterns are skipped —
@@ -53,10 +62,22 @@ export interface SimilarEntryHit {
     title: string;
     score: number;
 }
+/**
+ * Human/LLM-readable description of a similarity hit, shared by the block
+ * error and the approval-question suffix so both surfaces explain the same
+ * way.
+ */
+export declare function buildConflictNotice(hit: SimilarEntryHit): string;
+/**
+ * The most similar entry of the list, above `minScore`. Title and content
+ * both feed the comparison (titles are short; content carries the real
+ * signal). Generic form of {@link mostSimilarGlobalEntry} — callers decide
+ * which corpus (global store, merged view) the candidates come from.
+ */
+export declare function mostSimilarEntry(entries: readonly HarnessEntry[], title: string, content: string, minScore: number): SimilarEntryHit | undefined;
 /**
  * The most similar non-archived global entry of the same kind, above the
- * policy threshold. Title and content both feed the comparison (titles are
- * short; content carries the real signal).
+ * policy threshold.
  */
 export declare function mostSimilarGlobalEntry(globalState: HarnessState, kind: RefinementKind, title: string, content: string, policy: PromotionPolicy): SimilarEntryHit | undefined;
 //# sourceMappingURL=promotion.d.ts.map

package/lib/promotion.js

@@ -10,6 +10,15 @@ export const DEFAULT_PROMOTION_POLICY = {
     minPromoteChars: 100,
     maxContentOverlap: 0.6,
 };
+/**
+ * Write-time conflict guard (R2): a global create whose similarity against an
+ * existing same-kind entry reaches this score is rejected outright — a
+ * near-duplicate adds zero information and the model should evolve_update
+ * the existing entry instead.
+ */
+export const CONFLICT_BLOCK_SCORE = 0.8;
+/** Similarity at/above this stamps {@link CONFLICT_HINT_KEY} but lets the write proceed. */
+export const CONFLICT_WARN_SCORE = 0.5;
 /**
  * Build a policy from config values (schemastery strings compiled here so
  * the config layer never touches RegExp). Invalid patterns are skipped —
@@ -83,20 +92,36 @@ export function contentOverlap(a, b) {
     return intersection / (left.size + right.size - intersection);
 }
 /**
- * The most similar non-archived global entry of the same kind, above the
- * policy threshold. Title and content both feed the comparison (titles are
- * short; content carries the real signal).
+ * Human/LLM-readable description of a similarity hit, shared by the block
+ * error and the approval-question suffix so both surfaces explain the same
+ * way.
  */
-export function mostSimilarGlobalEntry(globalState, kind, title, content, policy) {
+export function buildConflictNotice(hit) {
+    return `near-duplicate of ${hit.id} 「${hit.title}」 (similarity ${Math.round(hit.score * 100)}%)`;
+}
+/**
+ * The most similar entry of the list, above `minScore`. Title and content
+ * both feed the comparison (titles are short; content carries the real
+ * signal). Generic form of {@link mostSimilarGlobalEntry} — callers decide
+ * which corpus (global store, merged view) the candidates come from.
+ */
+export function mostSimilarEntry(entries, title, content, minScore) {
     let best;
-    for (const other of Object.values(globalState.entries[kind])) {
+    for (const other of entries) {
         if (isArchived(other))
             continue;
         const score = Math.max(contentOverlap(title, other.title), contentOverlap(content, other.content));
-        if (score >= policy.maxContentOverlap && (best === undefined || score > best.score)) {
+        if (score >= minScore && (best === undefined || score > best.score)) {
             best = { id: other.id, title: other.title, score };
         }
     }
     return best;
 }
+/**
+ * The most similar non-archived global entry of the same kind, above the
+ * policy threshold.
+ */
+export function mostSimilarGlobalEntry(globalState, kind, title, content, policy) {
+    return mostSimilarEntry(Object.values(globalState.entries[kind]), title, content, policy.maxContentOverlap);
+}
 //# sourceMappingURL=promotion.js.map

package/lib/search.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Retrieval primitives for injection ranking: CJK-aware tokenization plus a
+ * dependency-free, field-weighted BM25 scorer (ADR
+ * `implemented/feature/2026-08-24-cjk-bigram-bm25-retrieval.md`).
+ *
+ * Why this shape:
+ * - the old scorer tokenized whole CJK runs as single tokens compared for
+ *   exact equality, so any rewording of a Chinese query missed every entry
+ *   (「检索升级」 never matched 「全文检索方案」); overlapping character
+ *   bigrams — the standard cjk_bigram analyzer shape (Elasticsearch/
+ *   OpenSearch) — fix recall while keeping English behavior identical;
+ * - raw hit counts weighted common words and distinctive terms alike; BM25's
+ *   IDF separates them. We use Lucene's non-negative variant
+ *   `ln(1 + (N - df + 0.5) / (df + 0.5))` so EVERY matched token scores > 0
+ *   and unmatched documents score exactly 0, preserving rankEntries'
+ *   "relevant outranks recent-but-irrelevant" ordering invariant;
+ * - the index lifetime is one ranking call. Stores hold tens~hundreds of
+ *   entries (measured full rebuild + score: single-digit milliseconds), the
+ *   JSON state files stay the single source of truth, and npm installers
+ *   carry zero native/WASM baggage — better-sqlite3 FTS5, sql.js, MiniSearch,
+ *   FlexSearch were all evaluated and rejected (see the ADR's alternatives).
+ */
+import type { HarnessEntry } from "./types.js";
+/** BM25 term-saturation constant (Okapi k1). */
+export declare const BM25_K1 = 1.5;
+/** BM25 document-length normalization constant (Okapi b). */
+export declare const BM25_B = 0.75;
+/** Multiplier for title-field matches (title hits outweigh body hits 2:1). */
+export declare const TITLE_FIELD_WEIGHT = 2;
+/**
+ * Tokenize text for relevance scoring: lowercase ASCII runs become word
+ * tokens; CJK runs become overlapping character bigrams (a single-character
+ * run stays a unigram). Deterministic and allocation-light — safe to call per
+ * injection build.
+ *
+ * @param text Arbitrary entry or query text.
+ * @returns Tokens in occurrence order (duplicates kept; consumers dedupe when
+ *          order-independent weighting is wanted).
+ */
+export declare function tokenize(text: string): string[];
+/** Per-field corpus statistics for one ranking pass. */
+interface FieldStats {
+    /** Term-frequency map per document, positioned like {@link RelevanceIndex.positions}. */
+    readonly tfs: ReadonlyArray<ReadonlyMap<string, number>>;
+    /** Token count per document (this field's dl for BM25 length normalization). */
+    readonly lengths: ReadonlyArray<number>;
+    /** Document frequency per distinct term across the corpus. */
+    readonly df: ReadonlyMap<string, number>;
+    /** Average token count across the corpus (0 when empty). */
+    readonly averageLength: number;
+}
+/** Precomputed corpus statistics backing {@link relevanceScore}. */
+export interface RelevanceIndex {
+    /** Number of documents in the corpus. */
+    readonly size: number;
+    /** Identity positions: the exact entry objects the index was built from. */
+    readonly positions: ReadonlyMap<object, number>;
+    readonly titles: FieldStats;
+    readonly bodies: FieldStats;
+}
+/**
+ * Build the corpus statistics (per-field tf, df, average length) for one
+ * ranking call. Pure: the index reads its input snapshot and never mutates
+ * the entries.
+ *
+ * @param entries The candidate entries being ranked this call.
+ * @returns An index that answers {@link relevanceScore} for exactly these
+ *          entries (identity-keyed).
+ */
+export declare function buildRelevanceIndex(entries: readonly HarnessEntry[]): RelevanceIndex;
+/**
+ * Field-weighted BM25 score of `entry` against `query` within `index`:
+ * `TITLE_FIELD_WEIGHT × bm25(title) + bm25(body)`. Query tokens are deduped,
+ * so repeating a word adds no weight.
+ *
+ * @returns A score > 0 when at least one query token occurs in the entry
+ *          (either field), and exactly 0 otherwise — the property rankEntries'
+ *          relevance-first ordering relies on. Never throws; an entry outside
+ *          the index simply scores 0.
+ */
+export declare function relevanceScore(index: RelevanceIndex, entry: HarnessEntry, query: string): number;
+export {};
+//# sourceMappingURL=search.d.ts.map

package/lib/search.js

@@ -0,0 +1,136 @@
+/** BM25 term-saturation constant (Okapi k1). */
+export const BM25_K1 = 1.5;
+/** BM25 document-length normalization constant (Okapi b). */
+export const BM25_B = 0.75;
+/** Multiplier for title-field matches (title hits outweigh body hits 2:1). */
+export const TITLE_FIELD_WEIGHT = 2;
+/**
+ * One pass, two run shapes: ASCII alphanumeric words, or maximal CJK runs.
+ * Runs never mix scripts because the alternation splits at the boundary, so
+ * 「深色主题dark主题」 tokenizes as 深色/色主/主题, "dark", 主题.
+ */
+const TOKEN_RUN_PATTERN = /[a-z0-9]+|[\u4e00-\u9fff]+/g;
+const ASCII_RUN_PATTERN = /^[a-z0-9]+$/;
+/**
+ * Tokenize text for relevance scoring: lowercase ASCII runs become word
+ * tokens; CJK runs become overlapping character bigrams (a single-character
+ * run stays a unigram). Deterministic and allocation-light — safe to call per
+ * injection build.
+ *
+ * @param text Arbitrary entry or query text.
+ * @returns Tokens in occurrence order (duplicates kept; consumers dedupe when
+ *          order-independent weighting is wanted).
+ */
+export function tokenize(text) {
+    const tokens = [];
+    for (const match of text.toLowerCase().matchAll(TOKEN_RUN_PATTERN)) {
+        const run = match[0];
+        if (ASCII_RUN_PATTERN.test(run)) {
+            tokens.push(run);
+        }
+        else if (run.length === 1) {
+            tokens.push(run);
+        }
+        else {
+            for (let i = 0; i < run.length - 1; i += 1) {
+                tokens.push(run.slice(i, i + 2));
+            }
+        }
+    }
+    return tokens;
+}
+function buildFieldStats(fieldTokens) {
+    const tfs = fieldTokens.map((tokens) => {
+        const tf = new Map();
+        for (const token of tokens) {
+            tf.set(token, (tf.get(token) ?? 0) + 1);
+        }
+        return tf;
+    });
+    const df = new Map();
+    let totalLength = 0;
+    for (let position = 0; position < tfs.length; position += 1) {
+        const tf = tfs[position];
+        let length = 0;
+        for (const count of tf.values()) {
+            length += count;
+        }
+        totalLength += length;
+        for (const token of tf.keys()) {
+            df.set(token, (df.get(token) ?? 0) + 1);
+        }
+    }
+    return {
+        tfs,
+        lengths: fieldTokens.map((tokens) => tokens.length),
+        df,
+        averageLength: tfs.length === 0 ? 0 : totalLength / tfs.length,
+    };
+}
+/**
+ * Build the corpus statistics (per-field tf, df, average length) for one
+ * ranking call. Pure: the index reads its input snapshot and never mutates
+ * the entries.
+ *
+ * @param entries The candidate entries being ranked this call.
+ * @returns An index that answers {@link relevanceScore} for exactly these
+ *          entries (identity-keyed).
+ */
+export function buildRelevanceIndex(entries) {
+    const titles = [];
+    const bodies = [];
+    for (const entry of entries) {
+        titles.push(tokenize(entry.title));
+        bodies.push(tokenize(`${entry.content} ${entry.path}`));
+    }
+    return {
+        size: entries.length,
+        positions: new Map(entries.map((entry, position) => [entry, position])),
+        titles: buildFieldStats(titles),
+        bodies: buildFieldStats(bodies),
+    };
+}
+/** One field's BM25 contribution for a single term (0 when the term is absent). */
+function bm25Term(termFrequency, documentFrequency, corpusSize, docLength, averageLength) {
+    if (termFrequency <= 0 || documentFrequency <= 0) {
+        return 0;
+    }
+    const inverseDocumentFrequency = Math.log(1 + (corpusSize - documentFrequency + 0.5) / (documentFrequency + 0.5));
+    const normalization = averageLength > 0 ? 1 - BM25_B + BM25_B * (docLength / averageLength) : 1;
+    return inverseDocumentFrequency * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + BM25_K1 * normalization));
+}
+/**
+ * Field-weighted BM25 score of `entry` against `query` within `index`:
+ * `TITLE_FIELD_WEIGHT × bm25(title) + bm25(body)`. Query tokens are deduped,
+ * so repeating a word adds no weight.
+ *
+ * @returns A score > 0 when at least one query token occurs in the entry
+ *          (either field), and exactly 0 otherwise — the property rankEntries'
+ *          relevance-first ordering relies on. Never throws; an entry outside
+ *          the index simply scores 0.
+ */
+export function relevanceScore(index, entry, query) {
+    const position = index.positions.get(entry);
+    if (position === undefined || index.size === 0) {
+        return 0;
+    }
+    const seen = new Set();
+    let titleScore = 0;
+    let bodyScore = 0;
+    for (const token of tokenize(query)) {
+        if (seen.has(token)) {
+            continue;
+        }
+        seen.add(token);
+        const titleDf = index.titles.df.get(token) ?? 0;
+        if (titleDf > 0) {
+            titleScore += bm25Term(index.titles.tfs[position]?.get(token) ?? 0, titleDf, index.size, index.titles.lengths[position] ?? 0, index.titles.averageLength);
+        }
+        const bodyDf = index.bodies.df.get(token) ?? 0;
+        if (bodyDf > 0) {
+            bodyScore += bm25Term(index.bodies.tfs[position]?.get(token) ?? 0, bodyDf, index.size, index.bodies.lengths[position] ?? 0, index.bodies.averageLength);
+        }
+    }
+    return TITLE_FIELD_WEIGHT * titleScore + bodyScore;
+}
+//# sourceMappingURL=search.js.map

package/lib/service.js

@@ -1,8 +1,10 @@
+import { CONFLICT_HINT_KEY } from "./types.js";
 import { applyRefinementProposal } from "./apply.js";
 import { randomUUID } from "node:crypto";
 import { rollbackProposal } from "./rollback.js";
 import { loadHarnessState, saveHarnessState } from "./state.js";
 import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
+import { CONFLICT_BLOCK_SCORE, CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./promotion.js";
 export function createEvolutionEngine(baseDir, hooks = {}) {
     function load(scope, sessionId) {
         return loadHarnessState(storePaths(baseDir, scope, sessionId).stateDir, scope);
@@ -10,6 +12,28 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
     function apply(scope, sessionId, proposal, context) {
         const paths = storePaths(baseDir, scope, sessionId);
         const state = context?.baselineState ?? load(scope, sessionId);
+        // Write-time conflict guard (R2): global creates are checked against
+        // the existing same-kind entries BEFORE any side effect — a
+        // near-duplicate is rejected with an actionable error (evolve_update
+        // instead), a moderate overlap proceeds stamped with
+        // CONFLICT_HINT_KEY. Rollbacks bypass the guard: re-creating an entry
+        // that resembles its successor is the point of rollback. Local scope
+        // is never blocked (scratch space); the wrapup/fate promotion path
+        // already enforces its own overlap policy there.
+        const warnHits = new Map();
+        if (scope === "global" && !context?.rollbackOf) {
+            for (const [index, edit] of proposal.edits.entries()) {
+                if (edit.action !== "create")
+                    continue;
+                const hit = mostSimilarEntry(Object.values(state.entries[edit.kind]), edit.title ?? "", edit.content ?? "", CONFLICT_WARN_SCORE);
+                if (!hit)
+                    continue;
+                if (hit.score >= CONFLICT_BLOCK_SCORE) {
+                    throw new Error(`create blocked: ${buildConflictNotice(hit)} already lives in the global ${edit.kind} store — use evolve_update on it instead of adding a duplicate`);
+                }
+                warnHits.set(index, hit);
+            }
+        }
         const id = `evolve_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
         // Code-enforced snapshot: runs before any mutation, cannot be skipped by the model.
         snapshotBefore(paths, id);
@@ -20,6 +44,21 @@ export function createEvolutionEngine(baseDir, hooks = {}) {
             ...(context?.baselineState ? { baselineState: context.baselineState } : {}),
             ...(context?.rollbackOf ? { rollbackOf: context.rollbackOf } : {}),
         });
+        // Stamp warn-tier conflicts onto the freshly created entries (both the
+        // live state and the result's after-snapshot stay coherent).
+        for (const [index, hit] of warnHits) {
+            const applied = result.appliedEdits[index];
+            if (!applied?.applied || applied.action !== "create" || !applied.id)
+                continue;
+            const hint = `${applied.kind}:${hit.id}:${hit.score.toFixed(2)}`;
+            const live = state.entries[applied.kind][applied.id];
+            if (live) {
+                live.metadata[CONFLICT_HINT_KEY] = hint;
+                if (applied.after) {
+                    applied.after.metadata[CONFLICT_HINT_KEY] = hint;
+                }
+            }
+        }
         saveHarnessState(paths.stateDir, state);
         appendResult(paths, result);
         hooks.onApplied?.(result);

package/lib/tool.js

@@ -1,6 +1,7 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { formatHarnessStateForPrompt } from "./render.js";
 import { requireGlobalApproval } from "./approval.js";
+import { CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./promotion.js";
 import { entrySourceOf } from "./source.js";
 import { getUsageCount, loadUsage } from "./usage.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
@@ -72,7 +73,13 @@ export function registerEvolveTools(ctx, engine, opts) {
         execute: async (args, exec) => {
             const scope = scopeOf(args.global, "local");
             if (scope === "global" && opts.requireGlobalApproval) {
-                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_add ${args.kind} "${args.title}" → 跨会话全局 store`);
+                // Informed approval: surface a similarity hit against the
+                // existing global store BEFORE the human decides — the
+                // engine's write-time guard still has the final say.
+                const globalState = engine.load("global", undefined);
+                const hit = mostSimilarEntry(Object.values(globalState.entries[args.kind]), args.title ?? "", args.content ?? "", CONFLICT_WARN_SCORE);
+                const conflictNote = hit ? ` ⚠️ ${buildConflictNotice(hit)}——建议改用 evolve_update` : "";
+                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_add ${args.kind} "${args.title}" → 跨会话全局 store${conflictNote}`);
             }
             const edit = {
                 action: "create",

package/lib/types.d.ts

@@ -57,6 +57,14 @@ export declare const PROMOTED_AT_KEY = "promotedAt";
  * cross-session copy back to the session it was distilled from.
  */
 export declare const SOURCED_FROM_KEY = "sourcedFromLocal";
+/**
+ * Metadata key stamped on a GLOBAL entry that was created despite a
+ * moderate-similarity overlap with an existing entry (write-time conflict
+ * guard, warn tier): `<kind>:<id>:<score>` — points at the entry it may
+ * duplicate so wrapup/fate can consolidate later. Creates at/above the block
+ * threshold never reach this stamp; they are rejected outright.
+ */
+export declare const CONFLICT_HINT_KEY = "conflictHint";
 /**
  * True when the entry is archived (hidden from injection, restorable).
  * Absent or empty archivedAt means the entry is active.

package/lib/types.js

@@ -43,6 +43,14 @@ export const PROMOTED_AT_KEY = "promotedAt";
  * cross-session copy back to the session it was distilled from.
  */
 export const SOURCED_FROM_KEY = "sourcedFromLocal";
+/**
+ * Metadata key stamped on a GLOBAL entry that was created despite a
+ * moderate-similarity overlap with an existing entry (write-time conflict
+ * guard, warn tier): `<kind>:<id>:<score>` — points at the entry it may
+ * duplicate so wrapup/fate can consolidate later. Creates at/above the block
+ * threshold never reach this stamp; they are rejected outright.
+ */
+export const CONFLICT_HINT_KEY = "conflictHint";
 /**
  * True when the entry is archived (hidden from injection, restorable).
  * Absent or empty archivedAt means the entry is active.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-continual-evolve",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Continual self-evolution plugin for DeepSeek Harness: versioned, auditable, rollback-safe harness state (prompt notes, memories, skills, subagent specs) refined from session trajectories.",
   "license": "MIT",
   "repository": {