@lmzhen/dsh-evolution-core 0.9.0 → 0.11.1

package/README.md

@@ -1,8 +1,6 @@
 # @lmzhen/dsh-evolution-core
 
-Shared pure library for the family: `SkillLibrary`/`MemoryStore`, the prompts and guidance text,
-the threat/quality/drift signals and the IO primitives (`nodeEvolutionIo`, `transactIo`,
-`evolutionIoAdapter`). It is **not a Cordis row** — it registers no service, tool or prompt
+Shared pure library for the family: `SkillLibrary`/`MemoryStore`, the prompts and guidance text, the threat/quality/drift signals, the skill CONTENT history (`skill-history.ts`: content-addressed versions behind every write) and the frame classification the plan path reports over (`evidence.ts`), plus the IO primitives (`nodeEvolutionIo`, `transactIo`, `evolutionIoAdapter`). It is **not a Cordis row** — it registers no service, tool or prompt
 section, and importing the package root is its only entry.
 
 ## Model surface
@@ -15,12 +13,24 @@ section, and importing the package root is its only entry.
 
 - This package is a library, not a Cordis row; do not mount it as a plugin.
 - 数值配置已在消费方 Config 面钳制（`min 1`/各字段域）；`MemoryStore` 内部对 `limit <= 0` 仍按 unbounded 防御处理——那是库内部防御，不构成"0 = 禁用"的配置语义。
+- **Content-history storage grows with the number of DISTINCT bodies a skill has ever been written
+  with, not with the retained count.** Trimming drops index entries; the blobs they point at stay on
+  disk (they are shared by content, so a reference count would have to span every skill's index, and no
+  sweeper exists yet). Measured on a 3.6 KB skill written 41 times: a 5.7 KB index over 20 entries and
+  41 blob files totalling 150 KB (41x the live body); unchanged writes add nothing. Plan disk accordingly
+  or remove `.history/blobs` entries by hand.
 - Skill-library writes are serialized in-process; cross-process writers to the SAME skill file must go through the single-file paths (`update`, `patch`, `writeSupportFile`). The full concurrency model, its two-phase exceptions and their provenance are in Notes and history.
 
 **Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
 
 ## Notes and history
 
+- Similarity is TWO NAMED QUESTIONS plus a projection the caller declares (`quality.ts`): `identity(text)` ("is it the same text?", a normalized-content hash) and `affinity(a, b)` ("how much vocabulary do these two share?", Jaccard over two `vocabulary()` sets), asked over `projectionText(projection, input)` — `body` for the library-wide scan, `summary` (name + description) for the create-time hint. `computePrefixClusters` stays a name-side STRUCTURAL index, not a score. Adding a projection is one entry in that table; a caller that wants a fourth ruler should name the question it is really asking instead.
+- A whole-body replacement that keeps less than half of the previous body appends one line to its own result
+  (`contentRetentionFeedback`, design §4 item 3): the ratio, both character counts, and the fact that the
+  replaced version is still in the history. Computed in the write funnel where both bodies are in hand, feedback
+  only — no ratio refuses a write, and the function owns no configuration.
+- Content history is HISTORY ONLY: the skill tree is the single truth for current content, and no judgement reads the version index (design invariant I1). Recording is best-effort but happens inside the write lock, so the index never describes content that did not land; a failed record warns once per instance instead of failing the write.
 - Skill-library mutations are read-modify-write on one file, so `SkillLibrary` serializes them in-process with a `makeSerialQueue` chain: `update`, `patch`, `restructure`, `writeSupportFile` and (since 0.3.46) `consolidate`'s target read→merge→commit run their whole read→validate→write under one serial task, so two concurrent mutators on one skill never interleave in this process.
 - `create` is INSIDE the serial chain and, when a transact backend is bound, its exists check runs inside the same per-file transact (v18); `archive`/`consolidate` are rename-based two-phase paths and stay outside the single-file serial chain.
 - **v18 residual (updated):** `create`, `removeSupportFile` and `setPinned` now run on the serial chain (`removeSupportFile`'s delete also goes through the per-file transact), so the remaining single-file residual is the protection TOCTOU (a marker check outside the transact) and the multi-file two-phase paths `archive`/`consolidate`/`restructure`.

package/lib/index.js

@@ -429,6 +429,10 @@ const PROTECTED_BUILTIN_SKILLS = new Set(["plan"]);
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_DESCRIPTION_LENGTH = 1024;
 const MAX_SKILL_CONTENT_CHARS = 1e5;
+/** How many content versions to retain per skill (skill-history.ts). 20 mirrors the count
+* KiroCrew settled on for the same job (its `MAX_SKILL_VERSIONS`), and is an E2 deployment
+* parameter — the value is a retention policy, not a protocol constant. */
+const DEFAULT_SKILL_VERSION_KEEP = 20;
 /** The authoring DISCIPLINE band, taken from the upstream standard (archive §5):
 * peer skills sit at 8-14k characters and a body pushing past 20k belongs in
 * `references/*.md`. Deliberately separate from `MAX_SKILL_CONTENT_CHARS`: the
@@ -600,7 +604,8 @@ const DEFAULT_SKILL_LIMITS = {
 	maxNameLength: 64,
 	maxDescriptionLength: MAX_DESCRIPTION_LENGTH,
 	maxSkillContentChars: MAX_SKILL_CONTENT_CHARS,
-	maxSkillFileBytes: MAX_SKILL_FILE_BYTES
+	maxSkillFileBytes: MAX_SKILL_FILE_BYTES,
+	versionKeep: 20
 };
 //#endregion
 //#region lib/types/frontmatter.js
@@ -4766,6 +4771,12 @@ Learn workflow (when the user asks you to learn a reusable skill, or you decide
 * mutation maturity is a documented DSH approximation (single per-month patch
 * trend ratio replaces the claw timestamp-trend formula, since DSH usage
 * records only carry the last patched timestamp).
+*
+* Batch C (2026-09-27): the similarity half of this module is now TWO NAMED
+* QUESTIONS plus a declared projection — {@link identity} ("is it the same
+* text?") and {@link affinity} ("how much vocabulary do these two share?") asked
+* over {@link projectionText}. Callers name the question and the projection
+* instead of growing a fourth unnamed ruler (design §3C / §1 I2).
 * @module @lmzhen/dsh-evolution-core
 */
 const QUALITY_WEIGHTS = {
@@ -4820,21 +4831,55 @@ function computeQualityScores(input) {
 function normalize(content) {
 	return content.toLowerCase().replace(/\s+/g, " ").trim();
 }
-/** C-26 (v10 audit): renamed from `contentHash` — mutations.ts exports a
+/** Named similarity question 1 — "is it the same text?" — as a normalized
+* content hash: case- and whitespace-insensitive, so two texts that differ only
+* in formatting are the SAME text here. Invariant under which projection the
+* caller read the text from.
+*
+* C-26 (v10 audit): NOT named `contentHash` — mutations.ts exports a
 * contentHash of RAW bytes, this one hashes the NORMALIZED text for dedup
-* grouping. Same private helper, unambiguous name. */
-function normalizedHash(content) {
-	return createHash("sha256").update(normalize(content)).digest("hex");
+* grouping. Same helper as that rename, now a named question. */
+function identity(text) {
+	return createHash("sha256").update(normalize(text)).digest("hex");
 }
-function tokenize(content) {
-	return new Set(normalize(content).split(/[^a-z0-9\u4e00-\u9fff]+/).filter(Boolean));
-}
-function jaccard(a, b) {
+/**
+* The declared projection: WHICH text a comparison weighs.
+*
+* `body` is the library-wide scan's projection (whole SKILL.md, read by the
+* caller). `summary` is name + description in one string — the projection a
+* listing already publishes (`SkillSummary` carries both fields, and a body is
+* attached only when the caller asks for it) — so a summary comparison never
+* reads a body OF ITS OWN: the create-time hint is fed by the listing pass the
+* tool already pays for its frontmatter, and calls no read of its own.
+*/
+function projectionText(projection, input) {
+	switch (projection) {
+		case "body": return input.content ?? "";
+		case "summary": return `${input.name ?? ""} ${input.description ?? ""}`;
+	}
+}
+/** The comparable vocabulary of one text: lowercase alphanumeric runs, plus
+* whole CJK runs (a Chinese description tokenizes by punctuation, not by word —
+* deliberately: the ruler is one home, and a real tokenizer is a different
+* question than "do these two share vocabulary?"). */
+function vocabulary(text) {
+	return new Set(normalize(text).split(/[^a-z0-9\u4e00-\u9fff]+/).filter(Boolean));
+}
+/** Named similarity question 2 — "how much vocabulary do these two share?" —
+* Jaccard over two {@link vocabulary} sets, 0 (nothing in common, or either side
+* empty) to 1 (identical vocabulary). Set-based on purpose: the bulk scan
+* memoizes each name's set once and only the comparisons are budgeted. */
+function affinity(a, b) {
 	if (a.size === 0 || b.size === 0) return 0;
 	let intersection = 0;
 	for (const token of a) if (b.has(token)) intersection += 1;
 	return intersection / (a.size + b.size - intersection);
 }
+/** The `affinity` level at which two bodies are treated as the same skill
+* (design §3C: the default is unchanged at 0.95 — it is now a NAME, because the
+* docblock below has linked it since PLAN-R2 while the code carried a bare
+* literal). Callers may still pass their own level. */
+const DEDUP_SIMILARITY_THRESHOLD = .95;
 /** PLAN-R2 P2-8 (2026-09-16): default cap on two-name comparisons in
 * {@link computeDedupGroups}. A 2000-skill library is ~2M pairs; the old
 * unbounded two-two Jaccard ran seconds to tens of seconds per
@@ -4861,7 +4906,7 @@ function computeDedupGroups(input) {
 	const names = [...input.contents.keys()];
 	const hashes = /* @__PURE__ */ new Map();
 	for (const name of names) {
-		const hash = normalizedHash(input.contents.get(name) ?? "");
+		const hash = identity(projectionText("body", { content: input.contents.get(name) ?? "" }));
 		const bucket = hashes.get(hash);
 		if (bucket) bucket.push(name);
 		else hashes.set(hash, [name]);
@@ -4888,7 +4933,7 @@ function computeDedupGroups(input) {
 	const tokenSet = (name) => {
 		let set = tokens.get(name);
 		if (!set) {
-			set = tokenize(input.contents.get(name) ?? "");
+			set = vocabulary(projectionText("body", { content: input.contents.get(name) ?? "" }));
 			tokens.set(name, set);
 		}
 		return set;
@@ -4908,7 +4953,7 @@ function computeDedupGroups(input) {
 			compared += 1;
 			const [ta, tb] = [tokenSet(a), tokenSet(b)];
 			if (Math.max(ta.size, tb.size) / Math.max(1, Math.min(ta.size, tb.size)) > 5) continue;
-			if (jaccard(ta, tb) >= threshold) union(a, b);
+			if (affinity(ta, tb) >= threshold) union(a, b);
 		}
 	}
 	const groups = /* @__PURE__ */ new Map();
@@ -4924,6 +4969,40 @@ function computeDedupGroups(input) {
 	};
 }
 /**
+* The create-time near-duplicate question (batch C, design §3C-2): WHICH
+* existing skills is this authoring candidate about to near-copy?
+*
+* It is the SAME {@link affinity} question as the library-wide scan, asked over
+* the `summary` projection — the one a listing already publishes
+* (`SkillSummary` carries `name` and `description`; nothing here can see a
+* body, which is the point: a create must not pay a SECOND whole-tree pass — the
+* listing's own frontmatter read is what feeds this comparison). Deliberately hint-only: the caller writes regardless, and the
+* matches are news, not a gate (G4 — the create-time foreground behavior is
+* unchanged).
+*
+* The default level is far below the scan's {@link DEDUP_SIMILARITY_THRESHOLD}
+* because the projection is thinner: a name plus one sentence shares far fewer
+* tokens than two bodies, and a hint that fires on every new skill is noise.
+* Exact same-name candidates are skipped — the library's own create refuses
+* those, and this line must not repeat that refusal.
+*/
+const SUMMARY_DUPLICATE_HINT_THRESHOLD = .5;
+function nearDuplicateSummaries(input) {
+	const threshold = input.threshold ?? .5;
+	const limit = input.limit ?? 3;
+	const candidateTokens = vocabulary(projectionText("summary", input.candidate));
+	const matches = [];
+	for (const existing of input.existing) {
+		if (existing.name === input.candidate.name) continue;
+		const score = affinity(candidateTokens, vocabulary(projectionText("summary", existing)));
+		if (score >= threshold) matches.push({
+			name: existing.name,
+			score
+		});
+	}
+	return matches.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+/**
 * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
 * the curator prompt asks the model to identify "prefix clusters — skills
 * sharing a first word or domain keyword"; the deterministic index supplies
@@ -5995,6 +6074,58 @@ function filterUnreadSkillOps(ops, readNames) {
 	return dropped;
 }
 //#endregion
+//#region lib/types/evidence.js
+/**
+* Which session frames are EVIDENCE, and which are bookkeeping.
+*
+* A plan op must cite `evidence` seqs, and the validator's range rule
+* (`evolution-plan-validator`, rule `EVIDENCE_RANGE`) answers only "is this an integer inside
+* the window the plan was authored against". A boundary frame satisfies that while carrying
+* nothing a claim can rest on: the `turn/start` seq is the frame a claim about that turn was
+* most likely read out of, and citing it is indistinguishable from citing a real exchange. This
+* module owns the ONE classification of a session frame by what it CARRIES, so the plan path can
+* report an op whose whole citation list is bookkeeping (design
+* `dsh-evolution-skill-history-design.md` §3D, phase 1: report only — no op is refused here).
+*
+* The classification is a DENY list of the pure bookends, not an allow list of content frames.
+* The platform's own vocabulary (`KNOWN_SESSION_EVENT_TYPES`, 57 members at 0.1.5-rc.2) mixes
+* content frames with state-change frames, and out-of-repo plugins append types the family cannot
+* enumerate; an unknown frame is therefore treated as carrying content, because a report that
+* fires on an unclassifiable frame is a false positive and phase 1 exists to measure how many TRUE
+* ones there are. Tightening — a narrower definition, or an allow list built from the platform's
+* vocabulary — changes this table and nothing else (`evidenceKindIndex` is the only reader).
+* @module @lmzhen/dsh-evolution-core
+*/
+/** The frame types that record a boundary and carry no content: the turn and step bookends. */
+const BOOKKEEPING_FRAME_TYPES = new Set([
+	"turn/start",
+	"turn/end",
+	"step/start",
+	"step/end"
+]);
+/**
+* The seqs of the frames that carry content.
+*
+* @param events - the session's frames, oldest first (any iterable; nothing is retained).
+* @returns the substantive seqs, or `undefined` when NO frame carried a usable seq. The two
+*   answers are different facts: an empty SET says "every sequenced frame is a boundary", while
+*   `undefined` says "this log cannot tell a boundary from a message" (a stub session in a test,
+*   a composition whose events carry no seq). A caller that cannot classify must stay silent
+*   rather than report every op — the same three-state posture as `sessionReadSkillNames`.
+*/
+function evidenceKindIndex(events) {
+	const substantive = /* @__PURE__ */ new Set();
+	let sequenced = 0;
+	for (const event of events) {
+		const seq = event.seq;
+		if (typeof seq !== "number" || !Number.isInteger(seq)) continue;
+		sequenced += 1;
+		if (typeof event.type === "string" && BOOKKEEPING_FRAME_TYPES.has(event.type)) continue;
+		substantive.add(seq);
+	}
+	return sequenced === 0 ? void 0 : substantive;
+}
+//#endregion
 //#region lib/types/drift-signals.js
 /**
 * Library-level drift signals for the maintenance subagent (design 011).
@@ -6260,6 +6391,337 @@ function findDriftSignal(signals, id) {
 	return signals.find((signal) => signal.id === id);
 }
 //#endregion
+//#region lib/types/skill-history.js
+/**
+* Skill content history: content-addressed blobs plus a per-skill version index.
+*
+* Why it exists: `.mutations.json` records before/after HASHES and calls every automated edit
+* "reviewable and replayable" — but a hash cannot be replayed. With no content store, the only way
+* back was a whole-tree snapshot (`.backups`, keep=5) or `.archive` (removed skills only), so
+* reverting one skill cost the collateral of every other change in that window. This module keeps
+* the content, keyed by skill and version.
+*
+* Invariants (design `dsh-evolution-skill-history-design.md` §1):
+*  - HISTORY IS HISTORY: the skill tree stays the single truth for "current content"; nothing here
+*    feeds a judgment — callers read back content and version NUMBERS only.
+*  - BEST-EFFORT, like the mutation audit: a failed history write warns and never fails the write
+*    that already landed.
+*  - Blobs are content-addressed, so identical bodies are stored once (across skills too).
+*  - Versions are numbered by `v` (max+1), NOT by the clock: a moved system clock must not reorder
+*    history (KiroCrew's `v<N>` choice, independently arrived at). Numbering and the index read-modify-write run
+*    under the INDEX's own io lock, so two writers of one skill cannot mint the same number.
+*  - The array's ORDER is append order, and the index is appended after the content lock is released, so two
+*    writers of ONE skill can interleave their appends. Each entry therefore carries `beforeHash` — the content
+*    it replaced, read under that writer's lock — and that link, not the position, is what `undo` follows
+*    ({@link orderVersions} rebuilds the content order for display when the chain is complete).
+*
+* NOT here: blob garbage collection. Trimming drops INDEX entries; orphan blobs stay until a
+* sweeper collects them, because a reference count would have to span every skill's index and that
+* belongs to the curator's whole-library pass, not to the write path.
+* @module @lmzhen/dsh-evolution-core/skill-history
+*/
+/** Root-level history directory. Dot-prefixed so skill discovery skips it. */
+const HISTORY_DIR = ".history";
+/** Versioned index shape, so a future field can migrate without guessing. */
+const HISTORY_INDEX_VERSION = 1;
+/** The action label for a predecessor the index had never seen (content found on disk before this
+* feature existed, or a hand-edited tree): it says "this is what was there", not what wrote it. */
+const BASELINE_ACTION = "baseline";
+/** The root-level history directory. */
+function historyRoot(root) {
+	return join(root, HISTORY_DIR);
+}
+/** Content-addressed blob path: identical bodies share one file, across skills too. */
+function blobPath(root, hash) {
+	return join(historyRoot(root), "blobs", hash);
+}
+/** One skill's index file. */
+function historyIndexFile(root, name) {
+	return join(historyRoot(root), "skills", name, "index.json");
+}
+/**
+* The versions in CONTENT order (oldest first), rebuilt from the chain links, for display.
+*
+* The stored array is append order, which interleaves when two writers of one skill audit out of
+* order; the links say what actually replaced what. The rebuild runs only when it can account for
+* EVERY entry (exactly one start and a forward link for each step) — otherwise the stored order is
+* returned unchanged, because a partial reconstruction would be a worse answer than the honest one.
+* @param versions - the stored index, oldest first as recorded.
+* @returns the same entries, in content order when the chain is complete.
+*/
+function orderVersions(versions) {
+	if (versions.length < 2) return [...versions];
+	const replaced = /* @__PURE__ */ new Set();
+	for (const entry of versions) if (entry.beforeHash !== void 0) replaced.add(entry.beforeHash);
+	const ends = versions.filter((entry) => !replaced.has(entry.hash));
+	if (ends.length !== 1) return [...versions];
+	const used = /* @__PURE__ */ new Set();
+	const backward = [];
+	let cursor = ends[0];
+	while (cursor !== void 0 && !used.has(cursor)) {
+		used.add(cursor);
+		backward.push(cursor);
+		const before = cursor.beforeHash;
+		cursor = before === void 0 ? void 0 : [...versions].reverse().find((entry) => !used.has(entry) && entry.hash === before);
+	}
+	return backward.length === versions.length ? backward.reverse() : [...versions];
+}
+/** The actions that record a SUPPORT FILE's bytes (they share the skill's version index). */
+const SUPPORT_ACTIONS = ["write_file", "remove_file"];
+/** The actions that record the skill's own SKILL.md body. */
+const CONTENT_ACTIONS = [
+	"create",
+	"update",
+	"patch",
+	"consolidate",
+	"restructure",
+	"restore"
+];
+/**
+* Which artifact one recorded version holds, from the action that produced it.
+* @param action - the entry's action label.
+* @returns the artifact class; `other` when the label does not say.
+*/
+function versionTarget(action) {
+	if (SUPPORT_ACTIONS.includes(action)) return "support";
+	if (CONTENT_ACTIONS.includes(action)) return "content";
+	return "other";
+}
+/**
+* Split one index into the skill body's chain and the support files' versions.
+*
+* Both share ONE index, so a skill that ever wrote a support file has two chains and
+* {@link orderVersions} cannot account for every entry (it falls back to the stored order). Splitting
+* first lets each group rebuild its own order, and keeps the body's chain intact by leaving every
+* entry the index cannot classify in it — a `baseline` predecessor is usually the body's first link.
+* @param versions - the stored index, oldest first as recorded.
+* @returns the two groups, each in content order when its chain is complete.
+*/
+function partitionVersions(versions) {
+	const content = [];
+	const support = [];
+	for (const entry of versions) if (versionTarget(entry.action) === "support") support.push(entry);
+	else content.push(entry);
+	return {
+		content: orderVersions(content),
+		support: orderVersions(support)
+	};
+}
+/** Keep nothing less than one version, whatever the deployment asks for. */
+function clampKeep(keep) {
+	return Number.isFinite(keep) ? Math.max(1, Math.floor(keep)) : 1;
+}
+/** The next version number: max+1, never a timestamp. */
+function nextVersion(versions) {
+	let max = 0;
+	for (const entry of versions) if (entry.v > max) max = entry.v;
+	return max + 1;
+}
+/** The last entry carrying this hash, or undefined (a hash may repeat after an undo). */
+function lastVersionOf(versions, hash) {
+	for (let index = versions.length - 1; index >= 0; index -= 1) {
+		const entry = versions[index];
+		if (entry !== void 0 && entry.hash === hash) return entry.v;
+	}
+}
+/** One entry as this reader accepts it, or null when the entry cannot be understood. */
+function readVersionEntry(entry) {
+	if (typeof entry !== "object" || entry === null) return null;
+	const candidate = entry;
+	if (typeof candidate.v !== "number" || !Number.isInteger(candidate.v) || candidate.v <= 0) return null;
+	if (typeof candidate.hash !== "string" || candidate.hash === "") return null;
+	if (typeof candidate.at !== "string") return null;
+	if (typeof candidate.action !== "string") return null;
+	if (typeof candidate.chars !== "number") return null;
+	return typeof candidate.beforeHash === "string" && candidate.beforeHash !== "" ? {
+		...candidate,
+		beforeHash: candidate.beforeHash
+	} : {
+		v: candidate.v,
+		at: candidate.at,
+		action: candidate.action,
+		hash: candidate.hash,
+		chars: candidate.chars
+	};
+}
+/**
+* Read one index body for a RECORDER: "understood", "no file", or "cannot be understood".
+* A file whose shape is right but which carries an entry this reader would have to drop counts as
+* unreadable — dropping it silently would be the overwrite the audit posture forbids.
+* @param raw - the index file's bytes, or null when absent.
+* @returns the three-state answer.
+*/
+function readHistoryIndex(raw) {
+	if (raw === null) return { kind: "absent" };
+	if (raw.trim() === "") return { kind: "unreadable" };
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return { kind: "unreadable" };
+	}
+	if (typeof parsed !== "object" || parsed === null) return { kind: "unreadable" };
+	const holder = parsed;
+	if (typeof holder.version === "number" && holder.version > 1) return { kind: "unreadable" };
+	if (!Array.isArray(holder.versions)) return { kind: "unreadable" };
+	const versions = [];
+	for (const entry of holder.versions) {
+		const version = readVersionEntry(entry);
+		if (version === null) return { kind: "unreadable" };
+		versions.push(version);
+	}
+	return {
+		kind: "ok",
+		versions
+	};
+}
+/**
+* Parse one index body for a READER. Malformed content, a foreign shape, or a version NEWER than this
+* reader all read as empty — the audit posture: never guess. A recorder must use
+* {@link readHistoryIndex} instead, because it has to PRESERVE bytes it cannot understand.
+* @param raw - the index file's bytes, or null when absent.
+* @returns the versions, oldest first.
+*/
+function parseHistoryIndex(raw) {
+	const state = readHistoryIndex(raw);
+	return state.kind === "ok" ? state.versions : [];
+}
+/**
+* The index after this write, and the version numbers it produced. Pure, so the versioning rules
+* are testable without io.
+*
+* Two rules matter here: a predecessor the index has never seen gets a BASELINE entry (so the state
+* before this mutation is recoverable even for a skill that predates the feature), and re-writing
+* identical content mints NO new version (the library's no-op updates must not grow history).
+* @param versions - the current index, oldest first.
+* @param input - the write being recorded.
+* @param keep - how many versions to retain per skill.
+* @returns the trimmed index and the recorded numbers.
+*/
+function nextHistoryIndex(versions, input, keep) {
+	const beforeHash = input.before === null ? null : contentHash(input.before);
+	const afterHash = input.after === null ? null : contentHash(input.after);
+	const grown = [...versions];
+	if (beforeHash !== null && !grown.some((entry) => entry.hash === beforeHash)) grown.push({
+		v: nextVersion(grown),
+		at: input.at,
+		action: BASELINE_ACTION,
+		hash: beforeHash,
+		chars: input.before?.length ?? 0
+	});
+	if (afterHash !== null) {
+		if (grown[grown.length - 1]?.hash !== afterHash) grown.push({
+			v: nextVersion(grown),
+			at: input.at,
+			action: input.action,
+			hash: afterHash,
+			chars: input.after?.length ?? 0,
+			...beforeHash === null ? {} : { beforeHash }
+		});
+	}
+	const trimmed = grown.slice(Math.max(0, grown.length - clampKeep(keep)));
+	const recorded = {};
+	if (beforeHash !== null) {
+		const v = lastVersionOf(trimmed, beforeHash);
+		if (v !== void 0) recorded.beforeVersion = v;
+	}
+	if (afterHash !== null) {
+		const v = lastVersionOf(trimmed, afterHash);
+		if (v !== void 0) recorded.afterVersion = v;
+	}
+	return {
+		versions: trimmed,
+		recorded
+	};
+}
+/** Shrink level at which the retention line speaks: a body that keeps less than this share of the
+* previous one is a rewrite, not an edit. */
+const RETENTION_FEEDBACK_KEEP_RATIO = .5;
+/** Floor on the REPLACED body: below this a ratio is noise (a 40-character skill cut in half is not
+* news), so the line stays off for small skills. */
+const RETENTION_FEEDBACK_MIN_CHARS = 200;
+/**
+* The anti-overwrite feedback line (design §4, item 3): says how much of the previous body a
+* replacement kept, so a destructive rewrite is visible in the same message that reports the write.
+*
+* Computed where the replaced bytes are still in hand — the write path's own in-lock read — instead of
+* re-reading the file from a caller (that second read would race the writers this library serializes).
+* It is FEEDBACK, never a gate: no ratio refuses a write, and the function owns no configuration
+* (a toggle nobody reads would be configuration that does nothing).
+*
+* @param input - the write being described.
+* @returns the line, or null when the write is not a significant whole-body replacement.
+*/
+function contentRetentionFeedback(input) {
+	if (input.action !== "update") return null;
+	const before = input.before;
+	const after = input.after;
+	if (before === null || after === null) return null;
+	if (before.length < 200) return null;
+	if (after.length >= before.length * .5) return null;
+	return `Content kept ${Math.round(after.length / before.length * 100)}% of the previous body (${after.length} of ${before.length} characters); the replaced version is preserved in this skill's history.`;
+}
+/**
+* Read one skill's versions, oldest first.
+* @param root - the skills root.
+* @param io - the io seam.
+* @param name - the skill name.
+* @returns the versions; an absent or unreadable index reads as empty (never a throw).
+*/
+async function loadVersions(root, io, name) {
+	return parseHistoryIndex(await io.readText(historyIndexFile(root, name)).catch(() => null));
+}
+/**
+* One version's content.
+* @param root - the skills root.
+* @param io - the io seam.
+* @param name - the skill name.
+* @param v - the version number.
+* @returns the content, or null when the version or its blob cannot be read (never '').
+*/
+async function loadVersionContent(root, io, name, v) {
+	const entry = (await loadVersions(root, io, name)).find((candidate) => candidate.v === v);
+	if (entry === void 0) return null;
+	return await io.readText(blobPath(root, entry.hash)).catch(() => null);
+}
+/**
+* Record the content one mutation produced, best-effort.
+*
+* Blobs are written FIRST: the index must never reference content that is not on disk, and a failed
+* blob write aborts the whole record (the caller warns; the mutation itself stands).
+* @param root - the skills root.
+* @param io - the io seam.
+* @param input - the write being recorded.
+* @param keep - how many versions to retain per skill.
+* @returns the version numbers, or null when there was no content to record.
+*/
+async function recordVersions(root, io, input, keep) {
+	if (input.before === null && input.after === null) return null;
+	for (const side of [input.before, input.after]) {
+		if (side === null) continue;
+		const path = blobPath(root, contentHash(side));
+		if (!await io.exists(path).catch(() => false)) await io.writeText(path, side);
+	}
+	const file = historyIndexFile(root, input.skillName);
+	if (readHistoryIndex(await io.readText(file).catch(() => null)).kind === "unreadable") {
+		const quarantine = `${file}.corrupt`;
+		await io.copy(file, quarantine);
+		console.warn(`skill-store: ${file} could not be understood (malformed, foreign, or written by a newer reader); its bytes were copied to ${quarantine} and a fresh index starts from this write`);
+	}
+	const recorded = {};
+	await transactIo(io, file, (current) => {
+		const state = readHistoryIndex(current);
+		const { versions, recorded: numbers } = nextHistoryIndex(state.kind === "ok" ? state.versions : [], input, keep);
+		recorded.beforeVersion = numbers.beforeVersion;
+		recorded.afterVersion = numbers.afterVersion;
+		return JSON.stringify({
+			version: 1,
+			versions
+		}, null, 2);
+	});
+	return recorded;
+}
+//#endregion
 //#region lib/types/fuzzy-match.js
 /**
 * Fuzzy string matching and replacement for patch/restructure edits of skill files.
@@ -6780,6 +7242,9 @@ var SkillLibrary = class {
 	/** V10-03 (P2-18): see the constructor's threatExemptLabels. Empty by
 	* default — the strict ANY-hit-blocks policy is unchanged. */
 	threatExemptLabels;
+	/** skill-history.ts: the content history is best-effort, so a failure must not be SILENT —
+	* but it is a deployment condition, not a per-write event, so it warns once per instance. */
+	historyWarned = false;
 	constructor(root = skillsRoot(), io = nodeEvolutionIo(), limits = DEFAULT_SKILL_LIMITS, onMutation, transact, threatExemptLabels) {
 		this.root = root;
 		this.io = io;
@@ -6844,11 +7309,24 @@ var SkillLibrary = class {
 			message: "internal error: the write transaction did not invoke the task; no write was performed"
 		};
 		if (o.ghostDir === true) await this.cleanupGhostDir(path);
-		if (o.write !== null && o.audit) await this.audit(o.audit.skillName, o.audit.action, o.audit.before, o.audit.after, o.audit.summary);
+		let result = o.result;
+		if (o.write !== null && o.audit) {
+			await this.audit(o.audit.skillName, o.audit.action, o.audit.before, o.audit.after, o.audit.summary);
+			const retention = contentRetentionFeedback({
+				name: o.audit.skillName,
+				action: o.audit.action,
+				before: o.audit.before,
+				after: o.audit.after
+			});
+			if (retention !== null && result.ok) result = {
+				...result,
+				message: `${result.message}\n${retention}`
+			};
+		}
 		if (o.write !== null && o.event) this.notifyMutation(o.event);
-		return durabilityWarning === "" || !o.result.ok ? o.result : {
-			...o.result,
-			message: `${o.result.message} (warning: the write landed but the directory fsync failed — durability unconfirmed: ${durabilityWarning})`
+		return durabilityWarning === "" || !result.ok ? result : {
+			...result,
+			message: `${result.message} (warning: the write landed but the directory fsync failed — durability unconfirmed: ${durabilityWarning})`
 		};
 	}
 	/**
@@ -7151,16 +7629,41 @@ var SkillLibrary = class {
 			return null;
 		}
 	}
-	/** Best-effort audit trail entry; never blocks the mutation. */
+	/** Best-effort audit trail entry; never blocks the mutation.
+	*
+	* Two independent best-effort writes run here, because either one failing must not cost the
+	* other: the CONTENT history (skill-history.ts, so a version can be read back at all) and the
+	* mutation ledger that points at it. The history failure is not silent — a deployment whose
+	* history stopped growing is a degradation worth seeing once (the ledger keeps hashes either
+	* way). */
 	async audit(skillName, action, before, after, summary) {
+		const at = (/* @__PURE__ */ new Date()).toISOString();
+		let versions = null;
+		try {
+			const keep = this.limits.versionKeep ?? 20;
+			versions = await recordVersions(this.root, this.io, {
+				skillName,
+				action,
+				before,
+				after,
+				at
+			}, keep);
+		} catch (error) {
+			if (!this.historyWarned) {
+				this.historyWarned = true;
+				console.warn(`skill-store: content history not recorded for "${skillName}" (${error instanceof Error ? error.message : String(error)}); the mutation itself landed and the audit ledger keeps its hashes`);
+			}
+		}
 		try {
 			await recordMutation(this.root, this.io, {
 				skillName,
 				action,
 				...before === null ? {} : { beforeHash: contentHash(before) },
 				...after === null ? {} : { afterHash: contentHash(after) },
+				...versions?.beforeVersion === void 0 ? {} : { beforeVersion: versions.beforeVersion },
+				...versions?.afterVersion === void 0 ? {} : { afterVersion: versions.afterVersion },
 				summary,
-				at: (/* @__PURE__ */ new Date()).toISOString()
+				at
 			});
 		} catch {}
 	}
@@ -7169,6 +7672,32 @@ var SkillLibrary = class {
 		return await loadMutations(this.root, this.io);
 	}
 	/**
+	* Content versions recorded for one skill, oldest first (skill-history.ts, batch A).
+	*
+	* Read-only: the version seam never feeds a judgment — callers use it to LIST and to read content
+	* back. A malformed or unreadable index reads as empty, and a bad name reads as empty too (the
+	* caller is a human command, so "no versions" is the honest answer for a name that cannot exist).
+	* @param rawName - the skill's name.
+	* @returns the versions, oldest first.
+	*/
+	async listVersions(rawName) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return [];
+		return await loadVersions(this.root, this.io, name);
+	}
+	/**
+	* One version's content, read back from the content-addressed blob store.
+	* @param rawName - the skill's name.
+	* @param v - the version number (see {@link SkillLibrary.listVersions}).
+	* @returns the content, or null when the version does not exist, the name is unusable, or the
+	*   blob cannot be read — never an empty string.
+	*/
+	async readVersion(rawName, v) {
+		const name = rawName.trim();
+		if (this.badName(name) !== null) return null;
+		return await loadVersionContent(this.root, this.io, name, v);
+	}
+	/**
 	* Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
 	* deletion, from background-review writes, and from the lifecycle — a
 	* protective mutation, so the autonomous pipeline may never call it. The
@@ -8941,7 +9470,7 @@ var SkillLibrary = class {
 			throw new Error(`snapshot restore refused: the skill root could not be listed (${error instanceof Error ? error.message : String(error)}) — nothing was changed`);
 		}
 		for (const entry of rootEntries) {
-			if (entry === ".archive" || entry === ".backups" || entry === ".mutations.json" || entry === ".curator-suppressed.json") continue;
+			if (entry === ".archive" || entry === ".backups" || entry === ".mutations.json" || entry === ".curator-suppressed.json" || entry === ".history") continue;
 			if (entry.endsWith(".lock") || entry.endsWith(`.lock.next`)) {
 				await this.refuseLiveLockOrSweep(join(this.root, entry), entry);
 				continue;
@@ -8955,6 +9484,7 @@ var SkillLibrary = class {
 		const restoresSuppressed = manifest.sidecars.includes(".curator-suppressed.json");
 		for (const entry of rootEntries) {
 			if (entry === ".archive" || entry === ".backups" || entry === ".mutations.json") continue;
+			if (entry === ".history") continue;
 			if (entry === ".curator-suppressed.json" && restoresSuppressed) continue;
 			if (entry.endsWith(".lock") || entry.endsWith(`.lock.next`)) continue;
 			await this.io.remove(join(this.root, entry));
@@ -9365,6 +9895,16 @@ const PARAM_EXPOSURE = Object.freeze([
 		docAnchor: "PARAMETERS.md#write-caps",
 		summary: "Report expired archives, or prune them."
 	},
+	{
+		id: "skillVersionKeep",
+		group: "write-caps",
+		tier: "E2",
+		authority: "cordis",
+		owner: "tool-skill-manage",
+		applies: "none",
+		docAnchor: "PARAMETERS.md#write-caps",
+		summary: "Content versions retained per skill; older ones leave the index. Their stored blobs stay on disk — no automatic sweep exists yet, so a long-lived library grows by the distinct bodies it has written."
+	},
 	{
 		id: "supportFileCharPolicy",
 		group: "write-caps",
@@ -10414,4 +10954,4 @@ function sessionAudited(ctx, sessionId, sessionScoped) {
 	return false;
 }
 //#endregion
-export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REFERENCE_REWRITE_POLICY, 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_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_LOCK_TAKEOVER_MS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, advanceReview, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, emptyRecord, errorText, evaluateThreat, eventsFile, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, neutralizePromptVariables, newSkillLibrary, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseLockBody, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readNumberParam, readParam, recordMutation, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionReadSkillNames, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, writeDurableTmp, yamlPlainScalarNeedsQuotes };
+export { ALIVE_LOCK_TAKEOVER_MS, AUTHORING_DESCRIPTION_BAR, AUTHORING_SPLIT_LINE_CHARS, BASELINE_ACTION, CITATION_SUPPORT_DIRS, COMBINED_REVIEW_PLAN_PROMPT, COMBINED_REVIEW_PROMPT, COMPLETION_SKILL_REVIEW_PROMPT, CONTENT_SPLIT_HINT, COST_ASCII_TOKEN_HIGH, COST_ASCII_TOKEN_LOW, COST_CJK_TOKEN_HIGH, COST_CJK_TOKEN_LOW, CURATOR_DRY_RUN_BANNER, CURATOR_PROMPT, DEAD_LOCK_TAKEOVER_MS, DEDUP_MAX_PAIR_COMPARISONS, DEDUP_SIMILARITY_THRESHOLD, DEFAULT_ARCHIVE_AFTER_DAYS, DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_CITATION_REF_BUDGET, DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_CURATOR_BOOT_GRACE_SECONDS, DEFAULT_CURATOR_INTERVAL_HOURS, DEFAULT_CURATOR_MODEL, DEFAULT_CURATOR_REVIEW_MAX_TOKENS, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_MAX_OPS_PER_PLAN, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_MEMORY_REVIEW_MODEL, DEFAULT_MIN_IDLE_HOURS, DEFAULT_MUTATION_CAP, DEFAULT_REFERENCE_REWRITE_POLICY, 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_SKILL_VERSION_KEEP, DEFAULT_STALE_AFTER_DAYS, DEFAULT_SUBSTANTIVE_MIN_AGENT_CHARS, DEFAULT_SUBSTANTIVE_MIN_TOOL_CALLS, DEFAULT_SUBSTANTIVE_MIN_USER_CHARS, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DEFAULT_SUPPORT_READ_TOOL_NAMES, DEFAULT_THREAT_MAX_SCAN_CHARS, DEFAULT_USER_CHAR_LIMIT, DISPATCH_EVENT_TYPES, DRIFT_MAX_LINE_CHARS, DRIFT_SIGNALS_VERSION, DRIFT_SIGNAL_NOUNS, DSH_AUTHORING_STANDARDS, EMPTY_LOCK_TAKEOVER_MS, ENTRY_DELIMITER, EVENT_ARCHIVE_PREFIX, EVENT_LOG_RETAIN_ARCHIVES, EVENT_LOG_ROTATE_AT, EVENT_LOG_VERSION, EVOLUTION_ERRORS, EVOLUTION_WRITE_TOOLS, EvolutionGateSet, FAMILY_SESSION_TOOL_NAMES, FORBIDDEN_CONTROL_KEYS, HEALTH_STAMP_RE, HISTORY_DIR, HISTORY_INDEX_VERSION, HOOK_LINE_RE, INSTANCE_KEYS, KEEP_LINE_RE, LOCK_BODY_RE, LOCK_SUFFIX, LOCK_TEAR_TAKEOVER_MS, LOW_QUALITY_THRESHOLD, LostWriteLock, MAINTAIN_OUTPUT_INSTRUCTION, MAINTAIN_PROMPT, MAX_DESCRIPTION_LENGTH, MAX_RESTRUCTURE_MOVES, MAX_SKILL_CONTENT_CHARS, MAX_SKILL_FILE_BYTES, MAX_SKILL_NAME_LENGTH, MAX_SUPPORT_READ_PATHS, MAX_TIMER_DELAY_MS, MEMORY_GUIDANCE_SECTION_ORDER, MEMORY_REVIEW_PROMPT, MIN_STAMP_BODY_CHARS, MUTATIONS_FILE_VERSION, MemoryStore, NATIVE_CALL_EVENT, NATIVE_RESULT_EVENT, PARAM_ALIASES, PARAM_EXPOSURE, PARAM_GROUP_LABELS, PARAM_NAMESPACES, PATTERN_OVERLAP, PLATFORM_CATALOG_DESCRIPTION_DEFAULT, PLATFORM_ESTIMATE_CHARS_PER_TOKEN, POLICY_STAGE_DEFAULTS, PROMPT_BUNDLE, PROMPT_BUNDLE_ID, PROMPT_BUNDLE_VERSION, PROTECTED_BUILTIN_SKILLS, PTC_DISPATCH_EVENT, PTC_DISPATCH_START_EVENT, QUALITY_WEIGHTS, READ_REQUIRED_ACTIONS, RESTRUCTURE_TARGET_RE, RETENTION_FEEDBACK_KEEP_RATIO, RETENTION_FEEDBACK_MIN_CHARS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, SKILL_NAME_RE, SKILL_REVIEW_PLAN_PROMPT, SKILL_REVIEW_PROMPT, SNAPSHOT_EXTRA_NAME_RE, SUMMARY_DUPLICATE_HINT_THRESHOLD, SUPPORT_DIRS, SUPPRESSED_FILE_VERSION, SkillLibrary, THREAT_EXEMPTION_HINT, TOKEN_ASCII_WEIGHT, TOKEN_CJK_WEIGHT, ToolDispatchNormalizer, ToolDispatchPayloadError, UPSTREAM_LIMIT_CHARS_PER_TOKEN, advanceReview, affinity, allowRowCollisions, appendEvolutionEvent, applyCuratorLifecycleFields, applyCuratorMetaFields, applyReferenceRewrite, assertDispatchPayload, assertSkillsRootAliasRetired, assessStructureHealth, authoringFeedback, blobPath, bodyCost, buildCuratorRunReport, buildLearnPrompt, bumpPatch, bumpSupportRead, bumpUse, bumpView, callingScope, canonicalWriteId, claimInstance, clampedNumber, clearReviewChannel, collectReadSkillNames, composePresetComposition, computeDedupGroups, computeDriftSignals, computeLifecycleTransitions, computePrefixClusters, computeQualityScores, computeScopeView, contentHash, contentRetentionFeedback, countDispatches, createGateSet, daysSinceIso, decideTakeover, describeReferenceRewrite, duplicateHeadings, emptyRecord, errorText, evaluateThreat, eventsFile, evidenceKindIndex, evolutionEventPayloadIssue, evolutionHome, evolutionIoAdapter, evolutionRoot, filterUnreadSkillOps, findDriftSignal, foldCuratorFields, foldToolDispatches, foldTurn, frontmatterBlock, frontmatterCatalogInvalid, getRecord, historyIndexFile, historyRoot, identity, idleDays, installParamSection, instanceClaimKey, instanceClaimedWriteSites, instanceHolder, isAbsent, isCommittedWarning, isDeprecatedParamId, isFileShapedPath, isMissingPath, isPresent, isProcessAlive, isProgramToolName, isReviewChannelSession, isSkillReadToolName, isSkillToolName, isUnknown, isUnreadWrite, latestActivityAt, lifecycleCandidate, listEventArchives, loadMutations, loadRowOverrides, loadSuppressedNames, loadUsage, loadVersionContent, loadVersions, makeSerialQueue, mapProbe, markAgentCreated, markReviewChannel, markerEntryName, memoryRoot, missingSupportPointers, mutateUsage, mutationsFile, narrowNameMatches, nearDuplicateSummaries, neutralizePromptVariables, newSkillLibrary, nextHistoryIndex, nodeEvolutionIo, normalizeFrontmatter, normalizeUsageRecord, observeEvent, orderVersions, overlongLines, paramNamespace, paramSectionOverrides, parseCuratorNominations, parseEvolutionEvents, parseFrontmatter, parseHistoryIndex, parseLockBody, partitionVersions, pendingSelfCleanup, persistedWriteSite, persistedWriteSites, planReferenceRewrite, planRehoming, policyStageLimits, probeAbsent, probeList, probeMtime, probePresent, probeReason, probeUnknown, projectionText, readDispatchSignal, readEvolutionEvents, readEvolutionTimeline, readHistoryIndex, readNumberParam, readParam, recordMutation, recordVersions, redactSecrets, relatedSkillNames, releaseInstance, renameWithRetry, renderCuratorReportMarkdown, resolveCitations, resolveExecOrigins, resolveOrigins, resolveParamId, resolveRootConfig, resolveSkillsRoot, retainEventArchives, retirementReport, reviewPrompt, saveSuppressedNames, saveUsage, scanBodyHooks, scanContentThreats, scanMemoryThreats, scanThreats, scopedProbeReport, sessionAudited, sessionReadSkillNames, sessionSeesFamilyTools, skillReadNameOf, skillsRoot, supportFileReadOf, suppressedFile, sweepReviewChannelSessions, tokenLineFor, transactIo, transactTaskGuard, unhookedSupportPointers, updateSuppressedNames, usageFile, usageObserved, validateFrontmatter, validateRestructureTarget, valueOr, verifyPromptBundle, versionTarget, vocabulary, writeDurableTmp, yamlPlainScalarNeedsQuotes };

package/lib/types/constants.d.ts

@@ -52,6 +52,10 @@ export declare const PROTECTED_BUILTIN_SKILLS: ReadonlySet<string>;
 export declare const MAX_SKILL_NAME_LENGTH = 64;
 export declare const MAX_DESCRIPTION_LENGTH = 1024;
 export declare const MAX_SKILL_CONTENT_CHARS = 100000;
+/** How many content versions to retain per skill (skill-history.ts). 20 mirrors the count
+ * KiroCrew settled on for the same job (its `MAX_SKILL_VERSIONS`), and is an E2 deployment
+ * parameter — the value is a retention policy, not a protocol constant. */
+export declare const DEFAULT_SKILL_VERSION_KEEP = 20;
 /** The authoring DISCIPLINE band, taken from the upstream standard (archive §5):
  * peer skills sit at 8-14k characters and a body pushing past 20k belongs in
  * `references/*.md`. Deliberately separate from `MAX_SKILL_CONTENT_CHARS`: the

package/lib/types/events.d.ts

@@ -57,6 +57,13 @@ export interface EvolutionPlanAppliedEvent {
     skippedUnread?: number | undefined;
     /** First execution-layer failure message (abort reason or op failure). */
     executionError?: string | undefined;
+    /** Batch D (2026-09-27): ops whose ENTIRE evidence list cites bookkeeping frames
+     * (a turn/step boundary) — the report-only phase of the plan path's
+     * `EVIDENCE_CLASS` rule. Not a refusal and not a "not done" cause: the ops in
+     * this count executed. It rides the same payload as the other dimensions so the
+     * observation window has a durable record; the model's notice says nothing about
+     * it. */
+    evidenceClassReports?: number | undefined;
     evidenceQuotes?: number | undefined;
     estimatedInputChars?: number | undefined;
 }

package/lib/types/evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which session frames are EVIDENCE, and which are bookkeeping.
+ *
+ * A plan op must cite `evidence` seqs, and the validator's range rule
+ * (`evolution-plan-validator`, rule `EVIDENCE_RANGE`) answers only "is this an integer inside
+ * the window the plan was authored against". A boundary frame satisfies that while carrying
+ * nothing a claim can rest on: the `turn/start` seq is the frame a claim about that turn was
+ * most likely read out of, and citing it is indistinguishable from citing a real exchange. This
+ * module owns the ONE classification of a session frame by what it CARRIES, so the plan path can
+ * report an op whose whole citation list is bookkeeping (design
+ * `dsh-evolution-skill-history-design.md` §3D, phase 1: report only — no op is refused here).
+ *
+ * The classification is a DENY list of the pure bookends, not an allow list of content frames.
+ * The platform's own vocabulary (`KNOWN_SESSION_EVENT_TYPES`, 57 members at 0.1.5-rc.2) mixes
+ * content frames with state-change frames, and out-of-repo plugins append types the family cannot
+ * enumerate; an unknown frame is therefore treated as carrying content, because a report that
+ * fires on an unclassifiable frame is a false positive and phase 1 exists to measure how many TRUE
+ * ones there are. Tightening — a narrower definition, or an allow list built from the platform's
+ * vocabulary — changes this table and nothing else (`evidenceKindIndex` is the only reader).
+ * @module @lmzhen/dsh-evolution-core
+ */
+/** One session frame, as far as the classification reads it. A platform `SessionEvent` is
+ * assignable: both fields are optional here so a stub log can be classified without pretending
+ * to be a full event. */
+export interface EvidenceFrame {
+    /** The platform event type. An unknown value counts as content (see the module docblock). */
+    type?: unknown;
+    /** The durable sequence number a plan op cites. */
+    seq?: unknown;
+}
+/**
+ * The seqs of the frames that carry content.
+ *
+ * @param events - the session's frames, oldest first (any iterable; nothing is retained).
+ * @returns the substantive seqs, or `undefined` when NO frame carried a usable seq. The two
+ *   answers are different facts: an empty SET says "every sequenced frame is a boundary", while
+ *   `undefined` says "this log cannot tell a boundary from a message" (a stub session in a test,
+ *   a composition whose events carry no seq). A caller that cannot classify must stay silent
+ *   rather than report every op — the same three-state posture as `sessionReadSkillNames`.
+ */
+export declare function evidenceKindIndex(events: Iterable<EvidenceFrame>): ReadonlySet<number> | undefined;
+//# sourceMappingURL=evidence.d.ts.map

package/lib/types/index.d.ts

@@ -23,7 +23,8 @@
  *   `quality.ts`, `signals.ts`, `skill-reads.ts` (the read-before-write rule, shared by the
  *   tool path and the review's plan path), `drift-signals.ts`, `skill-health.ts`,
  *   `preset-composition.ts`, `prompts.ts`, `learn-prompt.ts`,
- *   `evolution-events.ts`, `io.ts` (the ctx.evolutionIo seam itself).
+ *   `evolution-events.ts`, `evidence.ts` (which session frames count as content, for the plan
+ *   path's evidence-class report), `io.ts` (the ctx.evolutionIo seam itself).
  * @module @lmzhen/dsh-evolution-core
  */
 export * from './citations.ts';
@@ -52,7 +53,9 @@ export * from './scope.ts';
 export * from './skill-health.ts';
 export * from './signals.ts';
 export * from './skill-reads.ts';
+export * from './evidence.ts';
 export * from './drift-signals.ts';
+export * from './skill-history.ts';
 export * from './skill-store.ts';
 export * from './state-store.ts';
 export * from './threats.ts';

package/lib/types/limits.d.ts

@@ -78,6 +78,9 @@ export interface SkillLimits {
     archiveRetention?: ArchiveRetentionPolicy | undefined;
     /** See SupportFileCharPolicy; absent means the default (`report`). */
     supportFileCharPolicy?: SupportFileCharPolicy | undefined;
+    /** Content versions retained per skill (skill-history.ts); absent means
+     * `DEFAULT_SKILL_VERSION_KEEP`. */
+    versionKeep?: number | undefined;
 }
 export declare const DEFAULT_SKILL_LIMITS: SkillLimits;
 //# sourceMappingURL=limits.d.ts.map

package/lib/types/mutations.d.ts

@@ -10,6 +10,11 @@ export interface MutationRecord {
     action: string;
     beforeHash?: string;
     afterHash?: string;
+    /** The skill-history version the content on each side of this mutation belongs to
+     * (skill-history.ts). Optional: records written before content history existed carry none, and
+     * the hashes above stay the authority for "what changed". */
+    beforeVersion?: number;
+    afterVersion?: number;
     summary: string;
     at: string;
 }

package/lib/types/quality.d.ts

@@ -7,6 +7,12 @@
  * mutation maturity is a documented DSH approximation (single per-month patch
  * trend ratio replaces the claw timestamp-trend formula, since DSH usage
  * records only carry the last patched timestamp).
+ *
+ * Batch C (2026-09-27): the similarity half of this module is now TWO NAMED
+ * QUESTIONS plus a declared projection — {@link identity} ("is it the same
+ * text?") and {@link affinity} ("how much vocabulary do these two share?") asked
+ * over {@link projectionText}. Callers name the question and the projection
+ * instead of growing a fourth unnamed ruler (design §3C / §1 I2).
  * @module @lmzhen/dsh-evolution-core
  */
 import type { UsageMap } from './usage.ts';
@@ -45,6 +51,52 @@ export declare function computeQualityScores(input: {
     supportDirs?: ReadonlyMap<string, number>;
     now?: Date;
 }): Map<string, QualityScore>;
+/** Named similarity question 1 — "is it the same text?" — as a normalized
+ * content hash: case- and whitespace-insensitive, so two texts that differ only
+ * in formatting are the SAME text here. Invariant under which projection the
+ * caller read the text from.
+ *
+ * C-26 (v10 audit): NOT named `contentHash` — mutations.ts exports a
+ * contentHash of RAW bytes, this one hashes the NORMALIZED text for dedup
+ * grouping. Same helper as that rename, now a named question. */
+export declare function identity(text: string): string;
+/** Which text a similarity question is asked about. Declared by the caller. */
+export type SimilarityProjection = 'body' | 'summary';
+/** The one input shape both projections read from: a caller passes what it has. */
+export interface SimilarityInput {
+    /** The whole SKILL.md — the `body` projection. */
+    content?: string;
+    /** The skill name — half of the `summary` projection. */
+    name?: string;
+    /** The frontmatter description — half of the `summary` projection. */
+    description?: string;
+}
+/**
+ * The declared projection: WHICH text a comparison weighs.
+ *
+ * `body` is the library-wide scan's projection (whole SKILL.md, read by the
+ * caller). `summary` is name + description in one string — the projection a
+ * listing already publishes (`SkillSummary` carries both fields, and a body is
+ * attached only when the caller asks for it) — so a summary comparison never
+ * reads a body OF ITS OWN: the create-time hint is fed by the listing pass the
+ * tool already pays for its frontmatter, and calls no read of its own.
+ */
+export declare function projectionText(projection: SimilarityProjection, input: SimilarityInput): string;
+/** The comparable vocabulary of one text: lowercase alphanumeric runs, plus
+ * whole CJK runs (a Chinese description tokenizes by punctuation, not by word —
+ * deliberately: the ruler is one home, and a real tokenizer is a different
+ * question than "do these two share vocabulary?"). */
+export declare function vocabulary(text: string): ReadonlySet<string>;
+/** Named similarity question 2 — "how much vocabulary do these two share?" —
+ * Jaccard over two {@link vocabulary} sets, 0 (nothing in common, or either side
+ * empty) to 1 (identical vocabulary). Set-based on purpose: the bulk scan
+ * memoizes each name's set once and only the comparisons are budgeted. */
+export declare function affinity(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+/** The `affinity` level at which two bodies are treated as the same skill
+ * (design §3C: the default is unchanged at 0.95 — it is now a NAME, because the
+ * docblock below has linked it since PLAN-R2 while the code carried a bare
+ * literal). Callers may still pass their own level. */
+export declare const DEDUP_SIMILARITY_THRESHOLD = 0.95;
 /** PLAN-R2 P2-8 (2026-09-16): default cap on two-name comparisons in
  * {@link computeDedupGroups}. A 2000-skill library is ~2M pairs; the old
  * unbounded two-two Jaccard ran seconds to tens of seconds per
@@ -79,6 +131,45 @@ export declare function computeDedupGroups(input: {
      * {@link DEDUP_MAX_PAIR_COMPARISONS}; a smaller value truncates earlier. */
     maxPairComparisons?: number;
 }): DedupScanResult;
+/**
+ * The create-time near-duplicate question (batch C, design §3C-2): WHICH
+ * existing skills is this authoring candidate about to near-copy?
+ *
+ * It is the SAME {@link affinity} question as the library-wide scan, asked over
+ * the `summary` projection — the one a listing already publishes
+ * (`SkillSummary` carries `name` and `description`; nothing here can see a
+ * body, which is the point: a create must not pay a SECOND whole-tree pass — the
+ * listing's own frontmatter read is what feeds this comparison). Deliberately hint-only: the caller writes regardless, and the
+ * matches are news, not a gate (G4 — the create-time foreground behavior is
+ * unchanged).
+ *
+ * The default level is far below the scan's {@link DEDUP_SIMILARITY_THRESHOLD}
+ * because the projection is thinner: a name plus one sentence shares far fewer
+ * tokens than two bodies, and a hint that fires on every new skill is noise.
+ * Exact same-name candidates are skipped — the library's own create refuses
+ * those, and this line must not repeat that refusal.
+ */
+export declare const SUMMARY_DUPLICATE_HINT_THRESHOLD = 0.5;
+/** The fields {@link nearDuplicateSummaries} weighs — a structural subset of
+ * `SkillSummary`, so a listing feeds it without a conversion. */
+export interface SummaryCandidate {
+    name: string;
+    description?: string;
+}
+export interface SummaryMatch {
+    name: string;
+    /** The `summary`-projection {@link affinity} in 0..1. */
+    score: number;
+}
+export declare function nearDuplicateSummaries(input: {
+    candidate: SummaryCandidate;
+    existing: ReadonlyArray<SummaryCandidate>;
+    /** Level at which a match is reported. Defaults to
+     * {@link SUMMARY_DUPLICATE_HINT_THRESHOLD}. */
+    threshold?: number;
+    /** Cap on returned matches, closest first. Defaults to 3. */
+    limit?: number;
+}): SummaryMatch[];
 /**
  * Prefix-cluster index over a name set (rc.67 merge heuristic, input side):
  * the curator prompt asks the model to identify "prefix clusters — skills

package/lib/types/skill-history.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Skill content history: content-addressed blobs plus a per-skill version index.
+ *
+ * Why it exists: `.mutations.json` records before/after HASHES and calls every automated edit
+ * "reviewable and replayable" — but a hash cannot be replayed. With no content store, the only way
+ * back was a whole-tree snapshot (`.backups`, keep=5) or `.archive` (removed skills only), so
+ * reverting one skill cost the collateral of every other change in that window. This module keeps
+ * the content, keyed by skill and version.
+ *
+ * Invariants (design `dsh-evolution-skill-history-design.md` §1):
+ *  - HISTORY IS HISTORY: the skill tree stays the single truth for "current content"; nothing here
+ *    feeds a judgment — callers read back content and version NUMBERS only.
+ *  - BEST-EFFORT, like the mutation audit: a failed history write warns and never fails the write
+ *    that already landed.
+ *  - Blobs are content-addressed, so identical bodies are stored once (across skills too).
+ *  - Versions are numbered by `v` (max+1), NOT by the clock: a moved system clock must not reorder
+ *    history (KiroCrew's `v<N>` choice, independently arrived at). Numbering and the index read-modify-write run
+ *    under the INDEX's own io lock, so two writers of one skill cannot mint the same number.
+ *  - The array's ORDER is append order, and the index is appended after the content lock is released, so two
+ *    writers of ONE skill can interleave their appends. Each entry therefore carries `beforeHash` — the content
+ *    it replaced, read under that writer's lock — and that link, not the position, is what `undo` follows
+ *    ({@link orderVersions} rebuilds the content order for display when the chain is complete).
+ *
+ * NOT here: blob garbage collection. Trimming drops INDEX entries; orphan blobs stay until a
+ * sweeper collects them, because a reference count would have to span every skill's index and that
+ * belongs to the curator's whole-library pass, not to the write path.
+ * @module @lmzhen/dsh-evolution-core/skill-history
+ */
+import { type EvolutionIoLike } from './io.ts';
+/** Root-level history directory. Dot-prefixed so skill discovery skips it. */
+export declare const HISTORY_DIR = ".history";
+/** Versioned index shape, so a future field can migrate without guessing. */
+export declare const HISTORY_INDEX_VERSION = 1;
+/** The action label for a predecessor the index had never seen (content found on disk before this
+ * feature existed, or a hand-edited tree): it says "this is what was there", not what wrote it. */
+export declare const BASELINE_ACTION = "baseline";
+/** One recorded version of one skill. */
+export interface SkillVersion {
+    /** Monotonic per skill; the identity, unlike {@link SkillVersion.at}. */
+    v: number;
+    at: string;
+    /** The mutation that produced it (`create`/`update`/`patch`/…), or {@link BASELINE_ACTION}. */
+    action: string;
+    /** sha256 of the stored content. */
+    hash: string;
+    /** Content length in characters, so a listing needs no blob read. */
+    chars: number;
+    /** The content this write REPLACED, as its hash — absent on a create, on a baseline, and on any
+     * entry written before 0.10.0. The array's ORDER is append order, which two writers of one skill
+     * can interleave (the index is appended after the content lock is released); this link is computed
+     * from the bytes a write lock actually read, so it is the authoritative predecessor. */
+    beforeHash?: string;
+}
+/** One history write, carrying the content the caller already holds. */
+export interface VersionRecordInput {
+    skillName: string;
+    action: string;
+    /** Content before the mutation, or null when there was none (create/restore). */
+    before: string | null;
+    /** Content after the mutation, or null when there is none (archive/remove_file). */
+    after: string | null;
+    at: string;
+}
+/** The version numbers one write produced; a side with no content contributes nothing. */
+export interface RecordedVersions {
+    beforeVersion?: number | undefined;
+    afterVersion?: number | undefined;
+}
+/** The root-level history directory. */
+export declare function historyRoot(root: string): string;
+/** Content-addressed blob path: identical bodies share one file, across skills too. */
+export declare function blobPath(root: string, hash: string): string;
+/** One skill's index file. */
+export declare function historyIndexFile(root: string, name: string): string;
+/**
+ * The versions in CONTENT order (oldest first), rebuilt from the chain links, for display.
+ *
+ * The stored array is append order, which interleaves when two writers of one skill audit out of
+ * order; the links say what actually replaced what. The rebuild runs only when it can account for
+ * EVERY entry (exactly one start and a forward link for each step) — otherwise the stored order is
+ * returned unchanged, because a partial reconstruction would be a worse answer than the honest one.
+ * @param versions - the stored index, oldest first as recorded.
+ * @returns the same entries, in content order when the chain is complete.
+ */
+export declare function orderVersions(versions: readonly SkillVersion[]): SkillVersion[];
+/** Which artifact one recorded version holds.
+ *
+ * `content` is the skill's own SKILL.md body. `support` is a support file's bytes: a `write_file`
+ * or `remove_file` mutation stores them in the SAME index as the body's versions, so a skill that
+ * ever wrote a support file has two chains in one index. `other` is an entry whose action does not say
+ * which artifact the bytes belong to — a `baseline` predecessor found on disk, or an action that
+ * records no content of its own (`pin`/`unpin`/`archive` record only predecessors).
+ *
+ * The split is FAIL-CLOSED: an action this module does not know reads as `other` rather than being
+ * assumed to be the body, so a caller that offers "restore this version" never advertises bytes the
+ * index cannot vouch for. `tests/skill-history.spec.ts` pins every action the library can write, so a
+ * new one cannot land unclassified. */
+export type VersionTarget = 'content' | 'support' | 'other';
+/**
+ * Which artifact one recorded version holds, from the action that produced it.
+ * @param action - the entry's action label.
+ * @returns the artifact class; `other` when the label does not say.
+ */
+export declare function versionTarget(action: string): VersionTarget;
+/** The versions of one skill, split by the artifact they hold. */
+export interface VersionGroups {
+    /** The body's versions, plus predecessors whose artifact the index cannot name. */
+    readonly content: SkillVersion[];
+    /** Support-file versions: real history, but not restorable over SKILL.md. */
+    readonly support: SkillVersion[];
+}
+/**
+ * Split one index into the skill body's chain and the support files' versions.
+ *
+ * Both share ONE index, so a skill that ever wrote a support file has two chains and
+ * {@link orderVersions} cannot account for every entry (it falls back to the stored order). Splitting
+ * first lets each group rebuild its own order, and keeps the body's chain intact by leaving every
+ * entry the index cannot classify in it — a `baseline` predecessor is usually the body's first link.
+ * @param versions - the stored index, oldest first as recorded.
+ * @returns the two groups, each in content order when its chain is complete.
+ */
+export declare function partitionVersions(versions: readonly SkillVersion[]): VersionGroups;
+/** What one index file's bytes said. `absent` (no file yet) and `unreadable` (bytes that cannot be
+ * understood: malformed JSON, a foreign shape, an entry this reader would have to drop, or a writer
+ * NEWER than this reader) are DIFFERENT facts — the recorder must never replace the second with an
+ * index derived from "nothing", so it preserves those bytes instead. */
+export type HistoryIndexState = {
+    readonly kind: 'ok';
+    readonly versions: SkillVersion[];
+} | {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'unreadable';
+};
+/**
+ * Read one index body for a RECORDER: "understood", "no file", or "cannot be understood".
+ * A file whose shape is right but which carries an entry this reader would have to drop counts as
+ * unreadable — dropping it silently would be the overwrite the audit posture forbids.
+ * @param raw - the index file's bytes, or null when absent.
+ * @returns the three-state answer.
+ */
+export declare function readHistoryIndex(raw: string | null): HistoryIndexState;
+/**
+ * Parse one index body for a READER. Malformed content, a foreign shape, or a version NEWER than this
+ * reader all read as empty — the audit posture: never guess. A recorder must use
+ * {@link readHistoryIndex} instead, because it has to PRESERVE bytes it cannot understand.
+ * @param raw - the index file's bytes, or null when absent.
+ * @returns the versions, oldest first.
+ */
+export declare function parseHistoryIndex(raw: string | null): SkillVersion[];
+/**
+ * The index after this write, and the version numbers it produced. Pure, so the versioning rules
+ * are testable without io.
+ *
+ * Two rules matter here: a predecessor the index has never seen gets a BASELINE entry (so the state
+ * before this mutation is recoverable even for a skill that predates the feature), and re-writing
+ * identical content mints NO new version (the library's no-op updates must not grow history).
+ * @param versions - the current index, oldest first.
+ * @param input - the write being recorded.
+ * @param keep - how many versions to retain per skill.
+ * @returns the trimmed index and the recorded numbers.
+ */
+export declare function nextHistoryIndex(versions: readonly SkillVersion[], input: VersionRecordInput, keep: number): {
+    versions: SkillVersion[];
+    recorded: RecordedVersions;
+};
+/** Shrink level at which the retention line speaks: a body that keeps less than this share of the
+ * previous one is a rewrite, not an edit. */
+export declare const RETENTION_FEEDBACK_KEEP_RATIO = 0.5;
+/** Floor on the REPLACED body: below this a ratio is noise (a 40-character skill cut in half is not
+ * news), so the line stays off for small skills. */
+export declare const RETENTION_FEEDBACK_MIN_CHARS = 200;
+/** What {@link contentRetentionFeedback} reads: the one write it describes. */
+export interface RetentionFeedbackInput {
+    /** The skill's name, for the sentence. */
+    readonly name: string;
+    /** The action that produced the write; only a whole-body replacement is described. */
+    readonly action: string;
+    /** The replaced body, or null when the skill had none (create / restore). */
+    readonly before: string | null;
+    /** The body now on disk, or null when it was removed (archive / remove_file). */
+    readonly after: string | null;
+}
+/**
+ * The anti-overwrite feedback line (design §4, item 3): says how much of the previous body a
+ * replacement kept, so a destructive rewrite is visible in the same message that reports the write.
+ *
+ * Computed where the replaced bytes are still in hand — the write path's own in-lock read — instead of
+ * re-reading the file from a caller (that second read would race the writers this library serializes).
+ * It is FEEDBACK, never a gate: no ratio refuses a write, and the function owns no configuration
+ * (a toggle nobody reads would be configuration that does nothing).
+ *
+ * @param input - the write being described.
+ * @returns the line, or null when the write is not a significant whole-body replacement.
+ */
+export declare function contentRetentionFeedback(input: RetentionFeedbackInput): string | null;
+/**
+ * Read one skill's versions, oldest first.
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param name - the skill name.
+ * @returns the versions; an absent or unreadable index reads as empty (never a throw).
+ */
+export declare function loadVersions(root: string, io: EvolutionIoLike, name: string): Promise<SkillVersion[]>;
+/**
+ * One version's content.
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param name - the skill name.
+ * @param v - the version number.
+ * @returns the content, or null when the version or its blob cannot be read (never '').
+ */
+export declare function loadVersionContent(root: string, io: EvolutionIoLike, name: string, v: number): Promise<string | null>;
+/**
+ * Record the content one mutation produced, best-effort.
+ *
+ * Blobs are written FIRST: the index must never reference content that is not on disk, and a failed
+ * blob write aborts the whole record (the caller warns; the mutation itself stands).
+ * @param root - the skills root.
+ * @param io - the io seam.
+ * @param input - the write being recorded.
+ * @param keep - how many versions to retain per skill.
+ * @returns the version numbers, or null when there was no content to record.
+ */
+export declare function recordVersions(root: string, io: EvolutionIoLike, input: VersionRecordInput, keep: number): Promise<RecordedVersions | null>;
+//# sourceMappingURL=skill-history.d.ts.map

package/lib/types/skill-store.d.ts

@@ -36,6 +36,7 @@ import { transactIo, type EvolutionIoLike } from './io.ts';
 import { type Probe } from './probe.ts';
 import type { SkillLimits } from './limits.ts';
 import { type MutationRecord } from './mutations.ts';
+import { type SkillVersion } from './skill-history.ts';
 import { type SkillHealthAssessment, type SkillHealthThresholds } from './skill-health.ts';
 import type { EvolutionSkillMutatedEvent } from './events.ts';
 export interface SkillSummary {
@@ -272,6 +273,9 @@ export declare class SkillLibrary {
     /** V10-03 (P2-18): see the constructor's threatExemptLabels. Empty by
      * default — the strict ANY-hit-blocks policy is unchanged. */
     private readonly threatExemptLabels;
+    /** skill-history.ts: the content history is best-effort, so a failure must not be SILENT —
+     * but it is a deployment condition, not a per-write event, so it warns once per instance. */
+    private historyWarned;
     constructor(root?: string, io?: EvolutionIoLike, limits?: SkillLimits, onMutation?: (event: EvolutionSkillMutatedEvent) => void, transact?: typeof transactIo, threatExemptLabels?: readonly string[]);
     /**
      * Run one single-file read-modify-write for a mutator. When `transact` was
@@ -394,10 +398,34 @@ export declare class SkillLibrary {
         patchCount?: number;
         readCount?: number;
     }): Promise<SkillHealthAssessment | null>;
-    /** Best-effort audit trail entry; never blocks the mutation. */
+    /** Best-effort audit trail entry; never blocks the mutation.
+     *
+     * Two independent best-effort writes run here, because either one failing must not cost the
+     * other: the CONTENT history (skill-history.ts, so a version can be read back at all) and the
+     * mutation ledger that points at it. The history failure is not silent — a deployment whose
+     * history stopped growing is a degradation worth seeing once (the ledger keeps hashes either
+     * way). */
     private audit;
     /** Recent mutation audit records (read-only inspection surface). */
     listMutations(): Promise<MutationRecord[]>;
+    /**
+     * Content versions recorded for one skill, oldest first (skill-history.ts, batch A).
+     *
+     * Read-only: the version seam never feeds a judgment — callers use it to LIST and to read content
+     * back. A malformed or unreadable index reads as empty, and a bad name reads as empty too (the
+     * caller is a human command, so "no versions" is the honest answer for a name that cannot exist).
+     * @param rawName - the skill's name.
+     * @returns the versions, oldest first.
+     */
+    listVersions(rawName: string): Promise<SkillVersion[]>;
+    /**
+     * One version's content, read back from the content-addressed blob store.
+     * @param rawName - the skill's name.
+     * @param v - the version number (see {@link SkillLibrary.listVersions}).
+     * @returns the content, or null when the version does not exist, the name is unusable, or the
+     *   blob cannot be read — never an empty string.
+     */
+    readVersion(rawName: string, v: number): Promise<string | null>;
     /**
      * Pin or unpin a skill (`.pinned` marker). Pinned skills are protected from
      * deletion, from background-review writes, and from the lifecycle — a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.9.0",
+  "version": "0.11.1",
   "publishConfig": {
     "access": "public"
   },