dsh-continual-evolve 0.4.0 → 0.6.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,22 @@ 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;
+/**
+ * First reason the content reads as carrying a live credential, or undefined
+ * when it screens clean. Unlike {@link projectScopedReason} this guard is
+ * NOT policy-configurable — it protects every sink at once (promotion path,
+ * global writes at the engine throat, mount materialization).
+ */
+export declare function secretLeakReason(content: string): string | undefined;
 /**
  * Build a policy from config values (schemastery strings compiled here so
  * the config layer never touches RegExp). Invalid patterns are skipped —
@@ -41,9 +57,13 @@ export declare function resolvePromotionPolicy(options: {
  */
 export declare function projectScopedReason(content: string, policy: PromotionPolicy): string | undefined;
 /**
- * Tokenize for cheap similarity: ASCII words plus CJK character bigrams
- * (single CJK chars are too ambiguous; bigrams survive segmentation-free
- * Chinese text). Lowercased; single-char ASCII tokens dropped as noise.
+ * Token set for cheap similarity, built on the search module's tokenizer —
+ * one home for "how this project splits words" (ASCII words lowercased plus
+ * CJK character bigrams; bigrams survive segmentation-free Chinese text).
+ * The set form feeds Jaccard overlap (review audit 2026-08-28 C: the
+ * previous private tokenizer duplicated the definition; the calibrated
+ * 0.6/0.8 thresholds are judgment values, not data-fitted, so the merge
+ * costs at most a test re-pin).
  */
 export declare function normalizedTokens(text: string): Set<string>;
 /** Jaccard similarity of two texts' normalized token sets (0..1). */
@@ -53,10 +73,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

@@ -1,4 +1,5 @@
 import { isArchived } from "./types.js";
+import { tokenize } from "./search.js";
 /** Regex sources that mark content as project-scoped (never global). */
 const DEFAULT_BLOCK_PATTERNS = [
     String.raw `\/(?:mnt|home|Users)\/`, // absolute POSIX paths: "/home/…", "/mnt/…", "/Users/…"
@@ -10,6 +11,68 @@ 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;
+/**
+ * Fixed secret-detection patterns — a security invariant, deliberately NOT
+ * part of the configurable {@link PromotionPolicy}: a user pattern typo must
+ * never be able to disable secret screening. Each entry pairs a human label
+ * with a regex tuned for low false positives (placeholders like
+ * "YOUR_API_KEY_HERE" don't match; realistic mixed literals do).
+ */
+const SECRET_PATTERNS = [
+    { label: "AnySearch API key", regex: /\bas_sk_[A-Za-z0-9]{8,}\b/ },
+    { label: "Anthropic API key", regex: /\bsk-ant-[A-Za-z0-9_-]{16,}\b/ },
+    { label: "OpenAI-style API key", regex: /\bsk-(?:proj-)?[A-Za-z0-9_-]{16,}\b/ },
+    { label: "GitHub token", regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/ },
+    { label: "GitHub fine-grained PAT", regex: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ },
+    { label: "AWS access key", regex: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { label: "Google API key", regex: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { label: "Slack token", regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    { label: "npm grant token", regex: /\bnpm_[A-Za-z0-9]{36}\b/ },
+    { label: "private key block", regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----/ },
+    {
+        label: "credential assignment",
+        // The credential-name group is manually case-insensitive ("apiKey" in
+        // JSON, "API_KEY" in env examples) so the placeholder lookahead stays
+        // case-sensitive: it excludes only ALL-CAPS placeholders
+        // ("YOUR_KEY_HERE"), not real mixed/lowercase literals.
+        regex: /\b(?:[Aa][Pp][Ii][_-]?[Kk][Ee][Yy]|[Ss][Ee][Cc][Rr][Ee][Tt]|[Tt][Oo][Kk][Ee][Nn]|[Pp][Aa][Ss][Ss][Ww][Oo][Rr][Dd]|[Pp][Aa][Ss][Ss][Ww][Dd]|[Pp][Ww][Dd])\b["']?\s*[:=]\s*["'](?!["']*[A-Z0-9_]+["'])[A-Za-z0-9+/_-]{16,}["']/,
+    },
+];
+/**
+ * Redact a matched secret for error/audit surfaces: enough to identify the
+ * credential family, never the full value (reasons land in reviews.jsonl,
+ * question texts, and logs).
+ */
+function redactSecret(matched) {
+    if (matched.length <= 10) {
+        return `${matched.slice(0, 3)}…`;
+    }
+    return `${matched.slice(0, 6)}…${matched.slice(-3)}`;
+}
+/**
+ * First reason the content reads as carrying a live credential, or undefined
+ * when it screens clean. Unlike {@link projectScopedReason} this guard is
+ * NOT policy-configurable — it protects every sink at once (promotion path,
+ * global writes at the engine throat, mount materialization).
+ */
+export function secretLeakReason(content) {
+    for (const { label, regex } of SECRET_PATTERNS) {
+        const match = regex.exec(content);
+        if (match?.[0]) {
+            return `possible ${label} ("${redactSecret(match[0])}") — secrets must never be sedimented into harness state; rotate the credential and keep it out of the store`;
+        }
+    }
+    return undefined;
+}
 /**
  * Build a policy from config values (schemastery strings compiled here so
  * the config layer never touches RegExp). Invalid patterns are skipped —
@@ -46,26 +109,16 @@ export function projectScopedReason(content, policy) {
     return undefined;
 }
 /**
- * Tokenize for cheap similarity: ASCII words plus CJK character bigrams
- * (single CJK chars are too ambiguous; bigrams survive segmentation-free
- * Chinese text). Lowercased; single-char ASCII tokens dropped as noise.
+ * Token set for cheap similarity, built on the search module's tokenizer —
+ * one home for "how this project splits words" (ASCII words lowercased plus
+ * CJK character bigrams; bigrams survive segmentation-free Chinese text).
+ * The set form feeds Jaccard overlap (review audit 2026-08-28 C: the
+ * previous private tokenizer duplicated the definition; the calibrated
+ * 0.6/0.8 thresholds are judgment values, not data-fitted, so the merge
+ * costs at most a test re-pin).
  */
 export function normalizedTokens(text) {
-    const lowered = text.toLowerCase();
-    const tokens = new Set();
-    for (const match of lowered.matchAll(/[a-z0-9_]{2,}/g)) {
-        tokens.add(match[0] ?? "");
-    }
-    let previous;
-    for (const match of lowered.matchAll(/[\u3400-\u9fff]/g)) {
-        const char = match[0] ?? "";
-        if (previous !== undefined) {
-            tokens.add(`${previous}${char}`);
-        }
-        previous = char;
-    }
-    tokens.delete("");
-    return tokens;
+    return new Set(tokenize(text));
 }
 /** Jaccard similarity of two texts' normalized token sets (0..1). */
 export function contentOverlap(a, b) {
@@ -83,20 +136,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/rollback.js

@@ -19,6 +19,8 @@ export function rollbackProposal(target) {
 function inverseEdit(edit, refinementId) {
     if (edit.before && edit.after) {
         // Forward action was an update: restore the before snapshot.
+        // skill_kind rides along (review audit 2026-08-28 B4): without it a
+        // rollback could flip the skill form or fail validation on re-apply.
         return {
             action: "update",
             kind: edit.kind,
@@ -28,12 +30,16 @@ function inverseEdit(edit, refinementId) {
             path: edit.before.path,
             reference: edit.before.reference,
             arguments: edit.before.arguments,
+            ...(edit.before.skill_kind !== undefined ? { skill_kind: edit.before.skill_kind } : {}),
             metadata: edit.before.metadata,
             reason: `Rollback ${refinementId}`,
         };
     }
     if (edit.before) {
         // Forward action was a delete: re-create the entry from the snapshot.
+        // skill_kind is required for the re-created skill to pass the same
+        // contract validation as the original create (B4: a deleted guidance
+        // skill was previously unrecoverable via rollback).
         return {
             action: "create",
             kind: edit.kind,
@@ -43,6 +49,7 @@ function inverseEdit(edit, refinementId) {
             path: edit.before.path,
             reference: edit.before.reference,
             arguments: edit.before.arguments,
+            ...(edit.before.skill_kind !== undefined ? { skill_kind: edit.before.skill_kind } : {}),
             metadata: edit.before.metadata,
             reason: `Rollback ${refinementId}`,
         };

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,15 +1,73 @@
+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, secretLeakReason } from "./promotion.js";
 export function createEvolutionEngine(baseDir, hooks = {}) {
     function load(scope, sessionId) {
         return loadHarnessState(storePaths(baseDir, scope, sessionId).stateDir, scope);
     }
     function apply(scope, sessionId, proposal, context) {
         const paths = storePaths(baseDir, scope, sessionId);
-        const state = context?.baselineState ?? load(scope, sessionId);
+        // Working state is ALWAYS the freshest on-disk snapshot: apply mutates
+        // and persists the state whole-file, so building on the caller's
+        // planning-time copy would silently overwrite concurrent writers
+        // (another gate run, another session writing global). The caller's
+        // baselineState is ONLY the optimistic-concurrency comparison baseline
+        // — "reject edits whose target changed since planning" (review audit
+        // 2026-08-28 B1: the two roles were previously folded into one object,
+        // which made the advertised guard unreachable).
+        const state = 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.
+        //
+        // Secret-leak guard (P0, same throat): global creates AND updates are
+        // screened for credential-shaped literals before any side effect — a
+        // secret reaching the cross-session store is a leak even when the
+        // entry itself is legitimate. The screen covers every field the edit
+        // can plant: title, content, and the JSON forms of reference,
+        // arguments, and metadata (mount embeds reference verbatim into the
+        // generated plugin file). Fixed patterns, not policy-configurable.
+        const warnHits = new Map();
+        if (scope === "global" && !context?.rollbackOf) {
+            for (const [index, edit] of proposal.edits.entries()) {
+                if (edit.action === "create" || edit.action === "update") {
+                    const screenable = [
+                        typeof edit.title === "string" ? edit.title : "",
+                        typeof edit.content === "string" ? edit.content : "",
+                        edit.reference !== undefined ? JSON.stringify(edit.reference) : "",
+                        edit.arguments !== undefined ? JSON.stringify(edit.arguments) : "",
+                        edit.metadata !== undefined ? JSON.stringify(edit.metadata) : "",
+                    ];
+                    const secret = secretLeakReason(screenable.join("\n"));
+                    if (secret) {
+                        throw new Error(`${edit.action} blocked: ${secret}`);
+                    }
+                }
+                if (edit.action !== "create")
+                    continue;
+                // An unknown kind must fail per-edit in validateEdit, never
+                // crash the whole proposal here (review audit 2026-08-28 S1).
+                const corpus = state.entries[edit.kind];
+                if (!corpus)
+                    continue;
+                const hit = mostSimilarEntry(Object.values(corpus), 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 +78,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/state.d.ts

@@ -1,8 +1,4 @@
 import type { HarnessScope, HarnessState } from "./types.js";
-/** Directory holding the cross-session (global) store. */
-export declare function globalStateDir(baseDir: string): string;
-/** Directory holding a session-scoped (local) store, if the session has one. */
-export declare function localStateDir(sessionDir: string | undefined): string | undefined;
 export declare function stateFilePath(stateDir: string): string;
 /**
  * Load state from disk, degrading to empty on any unreadable or malformed
@@ -21,14 +17,6 @@ export declare function mergeHarnessStates(globalState: HarnessState, localState
  * preserving the mode of an existing file (defaults to 0o600 for new files).
  */
 export declare function saveHarnessState(stateDir: string, state: HarnessState): string;
-/**
- * Capture the state snapshot a plan was based on. At apply time the caller
- * re-reads the file and compares; an entry that changed since planning is
- * rejected per-edit, never silently overwritten.
- */
-export declare function baselineOf(state: HarnessState): HarnessState;
 /** True when an entry in `current` differs from the same entry in `baseline`. */
 export declare function entryChangedSince(baseline: HarnessState, current: HarnessState, kind: keyof HarnessState["entries"], id: string): boolean;
-/** The set of keys an entry must not expose beyond the persisted shape. */
-export declare const ENTRY_KEYS: readonly ["id", "kind", "title", "content", "path", "scope", "reference", "arguments", "metadata", "source", "created_at", "updated_at", "version"];
 //# sourceMappingURL=state.d.ts.map

package/lib/state.js

@@ -16,14 +16,6 @@ import { readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { emptyHarnessState } from "./types.js";
-/** Directory holding the cross-session (global) store. */
-export function globalStateDir(baseDir) {
-    return join(baseDir, "evolve");
-}
-/** Directory holding a session-scoped (local) store, if the session has one. */
-export function localStateDir(sessionDir) {
-    return sessionDir ? join(sessionDir, "evolve") : undefined;
-}
 export function stateFilePath(stateDir) {
     return join(stateDir, "harness_state.json");
 }
@@ -95,7 +87,10 @@ export function loadHarnessState(stateDir, scope = "global") {
         }
     }
     if (Array.isArray(root["refinements"])) {
-        state.refinements = root["refinements"];
+        // Shape-check members like entries do: a hand-edited file must never
+        // reach render/planner paths and crash them (review audit 2026-08-28
+        // S6 — loadHarnessState promises "never throws on a bad file").
+        state.refinements = root["refinements"].filter((item) => typeof item === "object" && item !== null && typeof item["id"] === "string");
     }
     return state;
 }
@@ -140,20 +135,10 @@ export function saveHarnessState(stateDir, state) {
     }
     return path;
 }
-/**
- * Capture the state snapshot a plan was based on. At apply time the caller
- * re-reads the file and compares; an entry that changed since planning is
- * rejected per-edit, never silently overwritten.
- */
-export function baselineOf(state) {
-    return JSON.parse(JSON.stringify(state));
-}
 /** True when an entry in `current` differs from the same entry in `baseline`. */
 export function entryChangedSince(baseline, current, kind, id) {
     const before = baseline.entries[kind][id];
     const after = current.entries[kind][id];
     return JSON.stringify(before ?? null) !== JSON.stringify(after ?? null);
 }
-/** The set of keys an entry must not expose beyond the persisted shape. */
-export const ENTRY_KEYS = ["id", "kind", "title", "content", "path", "scope", "reference", "arguments", "metadata", "source", "created_at", "updated_at", "version"];
 //# sourceMappingURL=state.js.map

package/lib/store.js

@@ -32,7 +32,9 @@ export function snapshotBefore(paths, refinementId) {
         return;
     }
     mkdirSync(paths.snapshotsDir, { recursive: true });
-    writeFileSync(join(paths.snapshotsDir, `${refinementId}.json`), readFileSync(statePath, "utf8"), "utf8");
+    // 0600: the snapshot is a full copy of harness_state.json — same
+    // permission discipline as the store itself (review audit 2026-08-28 S5).
+    writeFileSync(join(paths.snapshotsDir, `${refinementId}.json`), readFileSync(statePath, "utf8"), { encoding: "utf8", mode: 0o600 });
 }
 /** Append an applied result to the store's JSONL history. */
 export function appendResult(paths, result) {