@lmzhen/dsh-evolution-feedback 0.1.0-rc.7 → 0.1.0-rc.71

package/lib/index.js

@@ -1,6 +1,430 @@
 import z from "@deepseek-ai/schemastery";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
+//#region ../evolution-core/src/io.ts
+/**
+* Run `task` inside `io.transact` when the backend provides it; otherwise fall
+* back to a plain read → task → write/remove sequence (no cross-process lock —
+* callers keep their single-process serialize chain as the second layer).
+*/
+async function transactIo(io, path, task) {
+	if (io.transact) {
+		await io.transact(path, task);
+		return;
+	}
+	const next = await task(await io.readText(path));
+	if (next === null) await io.remove(path);
+	else await io.writeText(path, next);
+}
+/** Lazy adapter over an IO provider registry, shared by every evolution consumer. */
+function evolutionIoAdapter(provider) {
+	return {
+		readText: (path) => provider().readText(path),
+		writeText: (path, content) => provider().writeText(path, content),
+		remove: (path) => provider().remove(path),
+		list: (path) => provider().list(path),
+		exists: (path) => provider().exists(path),
+		rename: (path, destination) => provider().rename(path, destination),
+		copy: (path, destination) => provider().copy(path, destination),
+		size: (path) => {
+			const io = provider();
+			return io.size ? io.size(path) : Promise.resolve(null);
+		},
+		transact: (path, task) => {
+			const io = provider();
+			return io.transact ? io.transact(path, task) : transactIo(io, path, task);
+		},
+		isSymlink: (path) => {
+			const io = provider();
+			return io.isSymlink ? io.isSymlink(path) : Promise.resolve(null);
+		}
+	};
+}
+/** Active-log split point (rc.71): when the active log reaches this many events
+* the older half is rotated into an archive; the active stays bounded so a
+* single append stays O(active) instead of O(total-history). Tunable default —
+* callers may override per append (the tests use small values). */
+const EVENT_LOG_ROTATE_AT = 4e3;
+/** Archive file prefix: `events-<lastArchivedSeq>.json`. The active file is
+* `events.json` and never matches this glob. */
+const EVENT_ARCHIVE_PREFIX = "events-";
+function eventsFile(home) {
+	return join(home, "evolution", "events.json");
+}
+function isEventRecord(event) {
+	return typeof event === "object" && event !== null && typeof event.seq === "number";
+}
+/**
+* Parse an event log body. A missing file, a whitespace-only file (rc.69:
+* rebuildable, NOT malformed) or a corrupt one reads as empty; corrupt content
+* is still refused on append, never overwritten.
+*
+* Per-entry normalization (rc.70 F-1): entries without a numeric `seq` are
+* skipped here and dropped at the next append — valid entries survive, the
+* damaged record is the only loss (self-heal semantics, matching the usage
+* sidecar's per-field normalization on read).
+*/
+function parseEvolutionEvents(raw) {
+	if (raw === null || raw.trim() === "") return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return [];
+		return parsed.events.filter(isEventRecord);
+	} catch {
+		return [];
+	}
+}
+/**
+* Append one event under the write lock (rc.68): `seq` = current max + 1
+* computed inside the transact, so two processes appending concurrently never
+* collide. A malformed log is refused (bytes preserved) and the append fails.
+* Returns the assigned seq.
+*
+* Rotation (rc.71, 007 design): when the active log reaches `rotateAt`, the
+* older half is copied into an archive inside the SAME transact (the archive
+* path has its own lock, so no recursion) and the active is replaced with the
+* newer half + the new event. seqs stay globally monotonic; a crash between
+* archive write and active write leaves both copies, which the timeline merge
+* dedupes by seq. An archive-write failure aborts the append (active keeps the
+* full old content — no loss) and the caller's best-effort handling applies.
+*/
+async function appendEvolutionEvent(io, path, event, rotateAt = EVENT_LOG_ROTATE_AT) {
+	let assigned = 0;
+	await transactIo(io, path, async (current) => {
+		if (current !== null && current.trim() !== "") try {
+			JSON.parse(current);
+		} catch {
+			return current;
+		}
+		const nextEvents = await rotateIfDue(io, path, parseEvolutionEvents(current), rotateAt);
+		const maxSeq = nextEvents.reduce((max, entry) => Math.max(max, entry.seq), 0);
+		const record = {
+			...event,
+			seq: maxSeq + 1,
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		assigned = record.seq;
+		return JSON.stringify({
+			version: 1,
+			events: [...nextEvents, record]
+		}, null, 2);
+	});
+	if (assigned === 0) throw new Error(`evolution event log is malformed and was not touched: ${path}`);
+	return assigned;
+}
+/**
+* Split the active log at its midpoint when due: the older half is written to
+* `events-<lastArchivedSeq>.json` (await — a failed archive write aborts the
+* append so the active is never truncated without its copy), old archives are
+* pruned, and the newer half is returned as the next active body. No-op when
+* under the threshold.
+*/
+async function rotateIfDue(io, path, events, rotateAt) {
+	if (events.length < rotateAt) return events;
+	const mid = Math.ceil(events.length / 2);
+	const head = events.slice(0, mid);
+	const tail = events.slice(mid);
+	const anchor = tail[0]?.seq ?? events[events.length - 1]?.seq ?? 0;
+	const archivePath = join(dirname(path), `${EVENT_ARCHIVE_PREFIX}${anchor - 1}.json`);
+	await io.writeText(archivePath, JSON.stringify({
+		version: 1,
+		events: head
+	}, null, 2));
+	await retainEventArchives(io, path);
+	return tail;
+}
+/**
+* Prune old event archives (rc.71): keep the newest `EVENT_LOG_RETAIN_ARCHIVES`.
+* The name's numeric part is the last archived seq, so ordering is NUMERIC —
+* lexicographic would rank `events-10` before `events-2`. Best-effort per
+* removal; exported for the retention test.
+*/
+async function retainEventArchives(io, path) {
+	const dir = dirname(path);
+	const names = (await io.list(dir)).filter((name) => name.startsWith("events-") && name.endsWith(".json"));
+	const archiveSeq = (name) => Number.parseInt(name.slice(7, name.length - 5), 10) || 0;
+	names.sort((a, b) => archiveSeq(a) - archiveSeq(b));
+	const excess = names.slice(0, Math.max(0, names.length - 10));
+	for (const name of excess) await io.remove(join(dir, name)).catch(() => {});
+}
+/** Read the event log; a missing/whitespace-only file reads as empty,
+* corrupt content is flagged (and refused on append). */
+async function readEvolutionEvents(io, path) {
+	const raw = await io.readText(path);
+	if (raw === null || raw.trim() === "") return {
+		events: [],
+		malformed: false
+	};
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.events)) return {
+			events: [],
+			malformed: false
+		};
+		return {
+			events: parsed.events.filter(isEventRecord),
+			malformed: false
+		};
+	} catch {
+		return {
+			events: [],
+			malformed: true
+		};
+	}
+}
+/**
+* Read the full timeline (rc.71): active log + all archives, merged by seq
+* (active copy wins, duplicates only arise from the rotation crash window),
+* sorted ascending. Per-file malformed flag as in `readEvolutionEvents`; a
+* malformed ARCHIVE is skipped (never bricks the boot) and still flagged.
+*/
+async function readEvolutionTimeline(io, path) {
+	const dir = dirname(path);
+	const names = (await io.list(dir)).filter((name) => name.startsWith("events-") && name.endsWith(".json")).sort();
+	let malformed = false;
+	const bySeq = /* @__PURE__ */ new Map();
+	for (const name of names) {
+		const read = await readEvolutionEvents(io, join(dir, name));
+		if (read.malformed) malformed = true;
+		for (const event of read.events) bySeq.set(event.seq, event);
+	}
+	const active = await readEvolutionEvents(io, path);
+	if (active.malformed) malformed = true;
+	for (const event of active.events) bySeq.set(event.seq, event);
+	return {
+		events: [...bySeq.values()].sort((a, b) => a.seq - b.seq),
+		malformed
+	};
+}
+//#endregion
+//#region ../evolution-core/src/prompts.ts
+/**
+* Review and curation prompts adapted from Hermes Agent
+* `agent/background_review.py`, `agent/curator.py`, and
+* `agent/learn_prompt.py`, with tool names translated to the DSH-native
+* catalog (`memory`, `skill_manage`, `skill`, `bash`, `str_replace_editor`).
+*
+* Alignment policy (2026-08-29): the OPERATIONAL steps and instructions the
+* model follows mirror the Hermes originals structurally (signal list,
+* preference order, support-file taxonomy, curator package integrity,
+* consolidated/pruned reporting block). Tool and platform differences are
+* DSH-adapted (native tool names, pinned-within-review semantics, this
+* platform's index cap), and DSH-only additions are marked as such.
+*
+* Every prompt is pinned in a versioned bundle. Review workers verify the
+* bundle digest before spending a model call, so a partially-patched
+* deployment fails closed instead of silently running a truncated prompt.
+*/
+/**
+* Prompt bundle identity. Bump both id and version whenever a prompt's text
+* changes semantically: the bundle digest is the fail-closed signal for
+* review workers, so a stale id across deployments must be distinguishable.
+*/
+const PROMPT_BUNDLE_ID = "dsh-evolution@7";
+const MEMORY_REVIEW_PROMPT = `[Auto-review — Memory]
+Review the conversation above and consider saving to memory if appropriate.
+
+Focus on:
+1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
+2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?
+
+If something stands out, save it using the memory tool.
+If nothing is worth saving, just say "Nothing to save." and stop.`;
+const SKILL_REVIEW_PROMPT = `[Auto-review — Skills]
+Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small. A pass that does nothing is a missed learning opportunity, not a neutral outcome.
+
+Target shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.
+
+Signals to look for (any one of these warrants action):
+  • User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.
+  • User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.
+  • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.
+  • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.
+
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
+Preference order — prefer the earliest action that fits, but do pick one when a signal above fired:
+  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded or you read. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.
+  2. UPDATE AN EXISTING UMBRELLA. If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.
+  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files — use the right directory per kind:
+     • references/<topic>.md — session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.
+     • templates/<name>.<ext> — starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).
+     • scripts/<name>.<ext> — statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).
+     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.
+  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong — fall back to (1), (2), or (3).
+
+User-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.
+
+If you notice two existing skills that overlap, note it in your reply — the background curator handles consolidation at scale.
+
+Two-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:
+  • PATTERN (reusable — symptom → mechanism → fix → verification, still valuable next session) belongs in the SKILL.md body.
+  • LOG (one-off — commit SHAs, npm/profile states, what this release changed, this session's process narrative) belongs in a references/ file, never the body. Body density IS reuse rate. Keep new entries tight: a pattern fits in 2-8 physical lines; prefer changing the current-state pointer over appending history.
+
+Protected skills (DO NOT edit these):
+  • Bundled skills (shipped with the platform).
+  • Hub-installed skills (installed from a hub).
+Pinned skills are read-only to THIS background review pass — the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.
+If the only skills that need updating are protected, say 'Nothing to save.' and stop.
+
+Do NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):
+  • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules.
+  • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.
+  • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.
+  • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.
+
+If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint.
+
+'Nothing to save.' is a real option but should NOT be the default. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.`;
+const COMBINED_REVIEW_PROMPT = `[Auto-review]
+Review the conversation above and update two things:
+
+**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.
+
+**Skills**: how to do this class of task. Be ACTIVE — most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.
+
+Target shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a references/ directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.
+
+Signals that warrant a skill update (any one is enough):
+  • User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' — embed the lesson in the skill that governs that task so the next session starts fixed.
+  • Non-trivial technique, fix, workaround, or debugging path emerged.
+  • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now.
+
+Read-before-write (enforced by this channel): update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session — ops on unread skills are dropped; CREATE of a brand-new umbrella is the only exception.
+
+Preference order for skills — pick the earliest that fits:
+  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded or read in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.
+  2. UPDATE AN EXISTING UMBRELLA. Patch it.
+  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: references/<topic>.md for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; templates/<name>.<ext> for starter files meant to be copied and modified; scripts/<name>.<ext> for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.
+  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level — NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).
+
+Two-tier deposition discipline (DSH addition): classify before writing — PATTERN (symptom → mechanism → fix → verification) goes in the SKILL.md body; LOG (commit SHAs, npm/profile states, this release's change list, this session's narrative) goes in a references/ file. Body density IS reuse rate; a pattern fits in 2-8 physical lines.
+
+User-preference embedding: when the user complains about how you handled a task, update the skill that governs that task — memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.
+
+If you notice overlapping existing skills, mention it — the background curator handles consolidation.
+
+Protected skills (DO NOT edit these):
+  • Bundled skills (shipped with the platform).
+  • Hub-installed skills (installed from a hub).
+Pinned skills are read-only to THIS background review pass — the pinned write guard refuses background changes, so only the foreground may update or archive them. Foreground and delegated-subagent writes to pinned skills remain allowed.
+If the only skills that need updating are protected, say 'Nothing to save.' and stop.
+
+Do NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):
+  • Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these — they are not durable rules.
+  • Negative claims about tools or features ('browser tools do not work', 'X tool is broken', 'cannot use Y'). These harden into refusals the agent cites against itself for months after the actual problem was fixed.
+  • Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.
+  • One-off task narratives. A user asking 'summarize today's market' or 'analyze this PR' is not a class of work that warrants a skill.
+
+If a tool failed because of setup state, capture the FIX (install command, config step, env var to set) under an existing setup or troubleshooting skill — never 'this tool does not work' as a standalone constraint.
+
+Act on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop — but don't reach for that conclusion as a default.`;
+const CURATOR_PROMPT = `You are the skill curator. Maintain a healthy, class-level skill library, not a flat pile of narrow one-session skills.
+
+This is an UMBRELLA-BUILDING consolidation pass, not a passive audit and not a duplicate-finder.
+
+The goal is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS. A skill collection of many narrow skills where each captures one session's specific bug is a FAILURE of the library. An agent searching skills matches on descriptions, not exact names; one broad umbrella with labeled subsections beats five narrow siblings for discoverability.
+
+Right target shape: class-level skills with rich SKILL.md + references/, templates/, scripts/ support files for session-specific detail.
+
+Hard rules:
+1. NEVER hard-delete a skill. Archive (moving to .archive/) is the maximum destructive action; archives are recoverable, deletion is not.
+2. Do not touch bundled, hub-installed, pinned, or scheduled-task-referenced (referenced) skills. Referenced skills are fully protected — never consolidated, never pruned (there is no scheduled-task reference-rewriting pass; a referenced skill stays in place by design).
+3. Do not archive recently-created or never-used skills without strong evidence. "use=0" is NOT evidence either way — it only means the trigger has not come up yet. Never archive a never-used skill unless it is at least 30 days old AND its content is genuinely obsolete or fully absorbed elsewhere.
+4. Do NOT reject consolidation on the grounds that "each skill has a distinct trigger". The right bar is: would a human maintainer write this as N separate skills, or one skill with N labeled subsections? When the answer is the latter, merge.
+5. Judge overlap on CONTENT, not on usage counters.
+6. Before archiving a merged skill, ensure its unique content was preserved in the umbrella.
+
+How to work:
+1. Scan the candidate list. Identify PREFIX CLUSTERS — skills sharing a first word or domain keyword. Expected cluster count scales with the library: a large collection may show 10-25 prefix clusters, a small one often has none — a clean "nothing to consolidate" summary is the correct small-library outcome, not a shortage of ambition.
+2. For each cluster with 2+ members, ask "what is the UMBRELLA CLASS these skills serve?" and consolidate:
+   a. MERGE INTO AN EXISTING UMBRELLA (patch a labeled section for each sibling's unique insight, then archive the siblings).
+   b. CREATE A NEW UMBRELLA SKILL.md covering the shared workflow with short labeled subsections, then archive the absorbed siblings.
+   c. DEMOTE session-specific detail to references/, templates/, or scripts/ under the umbrella. Use the right directory per kind:
+      • references/<topic>.md — session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes, provider quirks, reproduction recipes) written concise and task-focused.
+      • templates/<name>.<ext> — starter files meant to be copied and modified.
+      • scripts/<name>.<ext> — statically re-runnable actions (verification scripts, fixture generators, probes).
+3. Package integrity — not optional: inspect each skill as a COMPLETE directory package, not just SKILL.md. A skill root may include references/, templates/, scripts/, and assets/. If the source skill has support files OR its SKILL.md contains relative links to them, DO NOT flatten only SKILL.md into <umbrella>/references/<old>.md. Choose one safe path instead: keep it as a standalone skill, OR fully merge by re-homing every needed support file into the umbrella's canonical directories AND rewriting the destination instructions to the new paths, OR archive the entire original skill package unchanged. Never leave demoted instructions pointing at files left behind under the old skill directory.
+4. Flag skills whose NAME is too narrow (contains a PR number, a feature codename, a specific error string, an 'audit'/'diagnosis'/'salvage' session artifact) — they almost always belong as a subsection or support file under a class-level umbrella.
+5. Iterate. After one consolidation round, scan the remaining set and look for the NEXT umbrella opportunity. Don't stop after 3 merges.
+
+You are a NOMINATOR, not an executor: this channel has NO tools. Your single deliverable is the structured YAML block below. Never narrate actions you did not take ("merged", "patched", "archived") — you are proposing, and the deterministic engine executes only names from the candidate pool it gave you. (A future execution view would expose skill_manage; today it does not.)
+
+'keep' is a legitimate decision ONLY when the skill is already a class-level umbrella and none of the proposed merges would improve discoverability. 'This is narrow but distinct from its siblings' is NOT a reason to keep — it's a reason to move it under an umbrella as a subsection or support file.
+
+Expected output: real umbrella-ification. Process every obvious cluster. If you end the pass with obvious clusters still untouched, you stopped too early — go back and look at the clusters you left alone.
+
+Keep the umbrella body tight and scannable: exact commands, verbatim paths, ~100-200 lines; never invent flags or APIs.
+
+When done, write a human summary THEN the structured machine-readable block. The block is the contract: every skill you would move to .archive/ MUST appear in exactly one of the two lists. Return ONLY the YAML block after the summary — no post-block prose. Format EXACTLY:
+
+## Structured summary (required)
+\`\`\`yaml
+consolidations:
+  - from: <old-skill-name>
+    into: <umbrella-skill-name>
+    reason: <one short sentence — why merged, not just 'similar'>
+prunings:
+  - name: <skill-name>
+    reason: <one short sentence — why archived with no merge target>
+\`\`\`
+
+Every skill you would move to .archive/ MUST appear in exactly one of the two lists. If you consolidated X into umbrella Y (patched Y, wrote a references file to Y, or created Y with X's content absorbed), X goes under consolidations with into: Y. If you archived X with no absorption — truly stale, irrelevant, or obsolete — X goes under prunings. Leave a list empty (consolidations: []) if none. Do not omit the block. The block comes AFTER your human-readable summary of clusters processed, patches made, and decisions left alone.`;
+const COMPLETION_SKILL_REVIEW_PROMPT = `[Auto-review — Skills · task complete]
+Your current task now appears complete. Before wrapping up, review the approach and update the skill library via skill_manage.
+
+Follow the skills review policy: be ACTIVE, prefer class-level umbrellas, patch ONLY skills loaded or read this session, and capture non-trivial techniques and user corrections. Do NOT capture environment-dependent failures, negative claims about tools, or one-off task narratives.
+
+Do NOT modify output files or re-run the task. If you are still mid-task, ignore this.`;
+/**
+* System-prompt guidance section (Hermes `SKILLS_GUIDANCE`, DSH-adapted).
+* Registered as a system-prompt section by tool-skill-manage (it mounts
+* exactly when `skill_manage` is available — the DSH analogue of Hermes'
+* `if "skill_manage" in agent.valid_tool_names` condition). Instructs the
+* model to save/repair skills on its own initiative.
+*/
+const SKILLS_GUIDANCE = `Skills guidance:
+• After completing a complex task (5+ tool calls), fixing a tricky error, or discovering a non-trivial workflow, save the approach as a skill with skill_manage so you can reuse it next time.
+• When using a skill and finding it outdated, incomplete, or wrong, patch it immediately with skill_manage (action='patch') — don't wait to be asked. Skills that aren't maintained become liabilities.`;
+const PLAN_CHANNEL_NOTE = `
+
+CHANNEL (subagent): this review channel mounts only the read-only \`skill\` tool — you have NO \`skill_manage\`, NO \`memory\`. Your deliverable is the structured JSON plan below (outputSchema). Describe the patches/creates you RECOMMEND in the plan; never narrate actions you took.`;
+/** Subagent-channel variant: same review policy, channel-limited deliverable (M-2). */
+const SKILL_REVIEW_PLAN_PROMPT = `${SKILL_REVIEW_PROMPT}${PLAN_CHANNEL_NOTE}`;
+/** Subagent-channel variant of the combined review (M-2). */
+const COMBINED_REVIEW_PLAN_PROMPT = `${COMBINED_REVIEW_PROMPT}${PLAN_CHANNEL_NOTE}`;
+function sha256(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+function createPromptBundle(prompts) {
+	const canonical = JSON.stringify({
+		id: PROMPT_BUNDLE_ID,
+		version: 7,
+		prompts: Object.fromEntries(Object.entries(prompts).sort())
+	});
+	return Object.freeze({
+		id: PROMPT_BUNDLE_ID,
+		version: 7,
+		prompts: Object.freeze({ ...prompts }),
+		sha256: sha256(canonical)
+	});
+}
+createPromptBundle({
+	memory: MEMORY_REVIEW_PROMPT,
+	skill: SKILL_REVIEW_PROMPT,
+	combined: COMBINED_REVIEW_PROMPT,
+	skillPlan: SKILL_REVIEW_PLAN_PROMPT,
+	combinedPlan: COMBINED_REVIEW_PLAN_PROMPT,
+	curator: CURATOR_PROMPT,
+	completion: COMPLETION_SKILL_REVIEW_PROMPT,
+	skillsGuidance: SKILLS_GUIDANCE
+});
+//#endregion
+//#region ../evolution-core/src/threats.ts
+const FILLER = String.raw`(?:\w+\s+){0,8}`;
+new RegExp(String.raw`ignore\s+${FILLER}(?:previous|above|prior|all)\s+${FILLER}instructions`, "i"), new RegExp(String.raw`new\s+${FILLER}system\s+${FILLER}prompt`, "i"), new RegExp(String.raw`forget\s+${FILLER}(?:everything|all)\s+${FILLER}(?:discussed|you\s+know)`, "i"), new RegExp(String.raw`you\s+have\s+been\s+${FILLER}(?:updated|upgraded|patched)\s+to`, "i"), new RegExp(String.raw`do\s+not\s+${FILLER}tell\s+${FILLER}the\s+user`, "i"), new RegExp(String.raw`output\s+${FILLER}(?:system|initial)\s+prompt`, "i");
+//#endregion
 //#region lib/types/index.js
 /**
 * Feedback-to-quality scoring for self-evolution.
@@ -8,8 +432,15 @@ import { join } from "node:path";
 * Feedback is durable through `ctx.evolutionIo` (when mounted) and skill
 * feedback feeds `quality_score` / `quality_warn` on the usage record, so
 * curator decisions can consume it deterministically.
+*
+* Persistence (rc.68): the EVENTS LOG (`evolution/events.json`, via
+* `evolution-core/evolution-events.ts`) is the single source of truth —
+* every increment appends one event under the write lock. `feedback.json` is
+* a rebuildable BOOT CACHE (`{ version: 2, lastSeq, skills, sessions }`),
+* never the truth; the in-memory state is the optimistic aggregate.
 * @module @lmzhen/dsh-evolution-feedback
 */
+const CACHE_VERSION = 2;
 var EvolutionFeedback = class {
 	state = {
 		skills: {},
@@ -17,8 +448,14 @@ var EvolutionFeedback = class {
 	};
 	chain = Promise.resolve();
 	path;
+	eventsPath;
+	io;
 	constructor(io, home = process.env.DSH_HOME ?? join(homedir(), ".dsh"), pathOverride) {
-		if (io) this.path = pathOverride ?? join(home, "evolution", "feedback.json");
+		if (io) {
+			this.path = pathOverride ?? join(home, "evolution", "feedback.json");
+			this.eventsPath = eventsFile(home);
+		}
+		this.io = io;
 	}
 	mutate(task) {
 		const run = this.chain.then(task, task);
@@ -27,21 +464,43 @@ var EvolutionFeedback = class {
 	}
 	async restore(io) {
 		const path = this.path;
-		if (!path) return;
+		const eventsPath = this.eventsPath;
+		if (!path || !eventsPath) return;
 		await this.mutate(async () => {
-			const raw = await io.readText(path);
-			if (raw === null) return;
-			try {
-				const parsed = JSON.parse(raw);
-				this.state = {
-					skills: { ...parsed.skills },
-					sessions: { ...parsed.sessions }
-				};
+			const rawEvents = await io.readText(eventsPath);
+			const archiveNames = (await io.list(dirname(eventsPath))).filter((name) => name.startsWith("events-") && name.endsWith(".json"));
+			if ((rawEvents === null || rawEvents.trim() === "") && archiveNames.length === 0) {
+				const aggregate = parseAggregate(await io.readText(path));
+				if (aggregate) try {
+					await migrateFeedbackEvents(io, eventsPath, aggregate);
+				} catch {}
+			}
+			const { events } = await readEvolutionTimeline(io, eventsPath);
+			const cache = parseCache(await io.readText(path));
+			const maxSeq = events.reduce((max, event) => Math.max(max, event.seq), 0);
+			const truth = cache ? foldWithDelta(cache, events) : foldFeedbackState(events);
+			this.state = {
+				skills: {
+					...truth.skills,
+					...this.state.skills
+				},
+				sessions: {
+					...truth.sessions,
+					...this.state.sessions
+				}
+			};
+			if (maxSeq > 0 && (!cache || cache.lastSeq < maxSeq)) try {
+				await io.writeText(path, JSON.stringify({
+					version: CACHE_VERSION,
+					lastSeq: maxSeq,
+					...truth
+				}, null, 2));
 			} catch {}
 		});
 	}
-	record(target, rating, note, kind = "session", io) {
-		const table = kind === "skill" ? this.state.skills : this.state.sessions;
+	record(target, rating, note, kind = "session") {
+		const mode = kind === "skill" ? "skills" : "sessions";
+		const table = this.state[mode];
 		const current = table[target] ?? {
 			positive: 0,
 			negative: 0
@@ -49,7 +508,20 @@ var EvolutionFeedback = class {
 		current[rating] += 1;
 		if (note !== void 0) current.lastNote = note;
 		table[target] = current;
-		if (io && this.path) this.flush(io);
+		const recordIo = this.io;
+		const eventsPath = this.eventsPath;
+		if (!recordIo || !eventsPath) return;
+		this.mutate(async () => {
+			try {
+				await appendEvolutionEvent(recordIo, eventsPath, {
+					type: "feedback",
+					target,
+					kind,
+					rating,
+					note
+				});
+			} catch (error) {}
+		});
 	}
 	score(target, kind = "session") {
 		const record = (kind === "skill" ? this.state.skills : this.state.sessions)[target];
@@ -64,14 +536,179 @@ var EvolutionFeedback = class {
 			sessions: { ...this.state.sessions }
 		};
 	}
-	async flush(io) {
+	/** Await the pending record-task chain (unload safety; rc.66). */
+	waitIdle() {
+		return this.chain;
+	}
+	/** Rebuild the boot cache from the log truth (rc.68); best-effort. */
+	persistCache() {
 		const path = this.path;
-		if (!path || !io) return;
-		await this.mutate(async () => {
-			await io.writeText(path, JSON.stringify(this.state, null, 2));
+		const eventsPath = this.eventsPath;
+		const recordIo = this.io;
+		if (!path || !eventsPath || !recordIo) return Promise.resolve();
+		return this.mutate(async () => {
+			try {
+				const { events } = await readEvolutionTimeline(recordIo, eventsPath);
+				const maxSeq = events.reduce((max, event) => Math.max(max, event.seq), 0);
+				if (maxSeq === 0) return;
+				await recordIo.writeText(path, JSON.stringify({
+					version: CACHE_VERSION,
+					lastSeq: maxSeq,
+					...foldFeedbackState(events)
+				}, null, 2));
+			} catch {}
 		});
 	}
 };
+/** True when `existing` contains the legacy sequence as a contiguous run on
+* its semantic fields (skip case). `seq` and `at` are excluded: after a merge
+* the legacy events carry shifted seqs, and a re-synthesis stamps a different
+* `at` — the semantic identity is type/kind/target/rating/note. A coincidental
+* semantic match of an already-appended user sequence yields the identical
+* aggregation, so the skip is harmless for counts and notes. */
+function containsLegacySequence(existing, expected) {
+	if (expected.length === 0) return true;
+	for (let start = 0; start <= existing.length - expected.length; start += 1) {
+		let match = true;
+		for (let offset = 0; offset < expected.length; offset += 1) {
+			const a = expected[offset];
+			const b = existing[start + offset];
+			if (!a || !b || a.type !== b.type || a.kind !== b.kind || a.target !== b.target || a.rating !== b.rating || a.note !== b.note) {
+				match = false;
+				break;
+			}
+		}
+		if (match) return true;
+	}
+	return false;
+}
+/**
+* Merge a legacy aggregate into the event log (rc.69): the expected synthetic
+* sequence is APPENDED (seq-shifted) when the log does not already contain it
+* — so a concurrent first writer's events AND the legacy history both
+* survive; when the sequence is already present the migration was completed
+* (by a first writer or by this path) and nothing is re-appended. Idempotent
+* and race-safe (the search runs inside the same transact). Exported for the
+* migration-race regression test.
+*/
+async function migrateFeedbackEvents(io, eventsPath, aggregate) {
+	const expected = synthesizeFeedbackEvents(aggregate);
+	await transactIo(io, eventsPath, (current) => {
+		const existing = parseEvolutionEvents(current);
+		if (containsLegacySequence(existing, expected)) return Promise.resolve(current);
+		const maxSeq = existing.reduce((max, event) => Math.max(max, event.seq), 0);
+		const merged = [...existing, ...expected.map((event, index) => ({
+			...event,
+			seq: maxSeq + index + 1
+		}))];
+		return Promise.resolve(JSON.stringify({
+			version: 1,
+			events: merged
+		}, null, 2));
+	});
+}
+/** Parse a legacy aggregate (v1) or a v2 cache into a plain aggregate state. */
+function parseAggregate(raw) {
+	if (raw === null) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		const skills = isRecord(parsed.skills) ? parsed.skills : void 0;
+		const sessions = isRecord(parsed.sessions) ? parsed.sessions : void 0;
+		if (!skills && !sessions) return null;
+		return {
+			skills: skills ?? {},
+			sessions: sessions ?? {}
+		};
+	} catch {
+		return null;
+	}
+}
+function parseCache(raw) {
+	if (raw === null) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed.version !== CACHE_VERSION || typeof parsed.lastSeq !== "number") return null;
+		if (!isRecord(parsed.skills) || !isRecord(parsed.sessions)) return null;
+		return {
+			lastSeq: parsed.lastSeq,
+			state: {
+				skills: parsed.skills,
+				sessions: parsed.sessions
+			}
+		};
+	} catch {
+		return null;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Fold all feedback events from zero (the truth view). */
+function foldFeedbackState(events) {
+	const state = {
+		skills: {},
+		sessions: {}
+	};
+	for (const event of events) applyFeedbackEvent(state, event);
+	return state;
+}
+/** Fold events after the cache's lastSeq onto the cached aggregates. */
+function foldWithDelta(cache, events) {
+	const state = {
+		skills: { ...cache.state.skills },
+		sessions: { ...cache.state.sessions }
+	};
+	for (const event of events) if (event.seq > cache.lastSeq) applyFeedbackEvent(state, event);
+	return state;
+}
+function applyFeedbackEvent(state, event) {
+	if (event.type !== "feedback") return;
+	const target = event.target;
+	if (target === void 0 || event.rating === void 0) return;
+	const table = event.kind === "skill" ? state.skills : state.sessions;
+	const record = table[target] ?? {
+		positive: 0,
+		negative: 0
+	};
+	record[event.rating] += 1;
+	if (event.note !== void 0) record.lastNote = event.note;
+	table[target] = record;
+}
+/** Synthesize one event per aggregate count unit, lastNote on the final event (migration). */
+function synthesizeFeedbackEvents(aggregate) {
+	const events = [];
+	const at = (/* @__PURE__ */ new Date()).toISOString();
+	const emitTarget = (kind, target, record) => {
+		const first = events.length + 1;
+		for (let index = 0; index < record.positive; index += 1) events.push({
+			seq: events.length + 1,
+			at,
+			type: "feedback",
+			kind,
+			target,
+			rating: "positive"
+		});
+		for (let index = 0; index < record.negative; index += 1) events.push({
+			seq: events.length + 1,
+			at,
+			type: "feedback",
+			kind,
+			target,
+			rating: "negative"
+		});
+		if (record.lastNote !== void 0 && events.length >= first) {
+			const last = events.length - 1;
+			const final = events[last];
+			if (final) events[last] = {
+				...final,
+				note: record.lastNote
+			};
+		}
+	};
+	for (const [target, record] of Object.entries(aggregate.skills)) emitTarget("skill", target, record);
+	for (const [target, record] of Object.entries(aggregate.sessions)) emitTarget("session", target, record);
+	return events;
+}
 const name = "evolution-feedback";
 const Config = z.object({
 	qualityWarnThreshold: z.number().default(-.25),
@@ -79,10 +716,7 @@ const Config = z.object({
 });
 function apply(ctx, rawConfig = {}) {
 	const ioRegistry = ctx.get("evolutionIo");
-	const io = ioRegistry ? {
-		readText: (path) => ioRegistry.provider().readText(path),
-		writeText: (path, content) => ioRegistry.provider().writeText(path, content)
-	} : void 0;
+	const io = ioRegistry ? evolutionIoAdapter(() => ioRegistry.provider()) : void 0;
 	const feedback = new EvolutionFeedback(io, process.env.DSH_HOME ?? join(homedir(), ".dsh"), rawConfig.path || void 0);
 	if (io) feedback.restore(io).catch((error) => {
 		ctx.logger.warn(error);
@@ -91,8 +725,8 @@ function apply(ctx, rawConfig = {}) {
 	const skillUsage = ctx.get("skillUsage");
 	if (skillUsage) {
 		const original = feedback.record.bind(feedback);
-		feedback.record = (target, rating, note, kind, recordIo) => {
-			original(target, rating, note, kind ?? "session", recordIo ?? io);
+		feedback.record = (target, rating, note, kind) => {
+			original(target, rating, note, kind ?? "session");
 			if (kind === "skill") {
 				const score = feedback.score(target, "skill");
 				const warn = score < (rawConfig.qualityWarnThreshold ?? -.25);
@@ -103,8 +737,8 @@ function apply(ctx, rawConfig = {}) {
 		};
 	}
 	ctx.effect(() => () => {
-		if (io) feedback.flush(io);
-	}, "evolution-feedback.flush");
+		return Promise.all([feedback.persistCache(), feedback.waitIdle()]);
+	}, "evolution-feedback.records");
 }
 //#endregion
-export { Config, EvolutionFeedback, apply, name };
+export { Config, EvolutionFeedback, apply, migrateFeedbackEvents, name };

package/lib/types/index.d.ts

@@ -4,10 +4,17 @@
  * Feedback is durable through `ctx.evolutionIo` (when mounted) and skill
  * feedback feeds `quality_score` / `quality_warn` on the usage record, so
  * curator decisions can consume it deterministically.
+ *
+ * Persistence (rc.68): the EVENTS LOG (`evolution/events.json`, via
+ * `evolution-core/evolution-events.ts`) is the single source of truth —
+ * every increment appends one event under the write lock. `feedback.json` is
+ * a rebuildable BOOT CACHE (`{ version: 2, lastSeq, skills, sessions }`),
+ * never the truth; the in-memory state is the optimistic aggregate.
  * @module @deepseek-ai/dsh-evolution-feedback
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type EvolutionIoLike } from '@deepseek-ai/dsh-evolution-core';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         evolutionFeedback: EvolutionFeedback;
@@ -22,27 +29,41 @@ export interface FeedbackState {
     skills: Record<string, FeedbackRecord>;
     sessions: Record<string, FeedbackRecord>;
 }
-interface IoLike {
-    readText(path: string): Promise<string | null>;
-    writeText(path: string, content: string): Promise<void>;
-}
+type IoLike = EvolutionIoLike;
 export declare class EvolutionFeedback {
     private state;
     private chain;
     private readonly path?;
+    private readonly eventsPath?;
+    private readonly io;
     constructor(io?: IoLike, home?: string, pathOverride?: string);
     private mutate;
     restore(io: IoLike): Promise<void>;
-    record(target: string, rating: 'positive' | 'negative', note?: string, kind?: 'skill' | 'session', io?: IoLike): void;
+    record(target: string, rating: 'positive' | 'negative', note?: string, kind?: 'skill' | 'session'): void;
     score(target: string, kind?: 'skill' | 'session'): number;
     snapshot(): FeedbackState;
-    flush(io?: IoLike): Promise<void>;
+    /** Await the pending record-task chain (unload safety; rc.66). */
+    waitIdle(): Promise<unknown>;
+    /** Rebuild the boot cache from the log truth (rc.68); best-effort. */
+    persistCache(): Promise<void>;
 }
+/**
+ * Merge a legacy aggregate into the event log (rc.69): the expected synthetic
+ * sequence is APPENDED (seq-shifted) when the log does not already contain it
+ * — so a concurrent first writer's events AND the legacy history both
+ * survive; when the sequence is already present the migration was completed
+ * (by a first writer or by this path) and nothing is re-appended. Idempotent
+ * and race-safe (the search runs inside the same transact). Exported for the
+ * migration-race regression test.
+ */
+export declare function migrateFeedbackEvents(io: IoLike, eventsPath: string, aggregate: FeedbackState): Promise<void>;
 export declare const name = "evolution-feedback";
 export interface Config {
     /** Score below which curator receives quality_warn for a skill. */
     qualityWarnThreshold?: number;
-    /** Explicit feedback file path; empty derives $DSH_HOME/evolution/feedback.json. */
+    /** Explicit boot-cache file path; empty derives $DSH_HOME/evolution/feedback.json.
+     * The event log always stays at $DSH_HOME/evolution/events.json (derived from
+     * home, never from this override). */
     path?: string;
 }
 export declare const Config: z<Config>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-feedback",
   "description": "Feedback-to-quality scoring for self-evolution (community build)",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.71",
   "publishConfig": {
     "access": "public"
   },
@@ -35,15 +35,15 @@
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.7",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.7"
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.71",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.71"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.7",
-    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.7",
-    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.7"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.71",
+    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.71",
+    "@lmzhen/dsh-skill-usage": "^0.1.0-rc.71"
   }
 }