@lmzhen/dsh-evolution-core 0.30.36 → 0.30.38

package/lib/types/mutation-unit.js

@@ -0,0 +1,509 @@
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isCommittedWarning, isProcessAlive } from "./io.js";
+function underRoot(rootDir, target) {
+    if (rootDir === undefined || rootDir === '')
+        return false;
+    const rel = relative(rootDir, target);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * Pure preflight for one mutation request. It deliberately does no IO: the
+ * caller must resolve roots and read bodies before this point; the unit kernel
+ * performs CAS/protection/journal after validation.
+ */
+export function validateMutationRequest(request, limits) {
+    const errors = [];
+    const roots = [];
+    for (const root of request.roots) {
+        const name = root.name.trim();
+        if (name === '') {
+            errors.push({ code: 'root-empty', message: 'mutation root name is empty' });
+            continue;
+        }
+        if (roots.some(entry => entry.name === name)) {
+            errors.push({ code: 'root-duplicate', message: 'duplicate mutation root ' + name });
+            continue;
+        }
+        roots.push({ name, protection: root.protection });
+    }
+    const primary = request.name.trim();
+    if (request.rootDirs !== undefined) {
+        for (const root of roots) {
+            if (request.rootDirs[root.name] === undefined) {
+                errors.push({ code: 'root-dir-missing', message: 'no directory for mutation root ' + root.name });
+            }
+        }
+    }
+    if (!roots.some(root => root.name === primary)) {
+        errors.push({ code: 'root-primary-missing', message: 'primary skill ' + primary + ' is not in roots' });
+    }
+    if (request.ops.length === 0) {
+        errors.push({ code: 'ops-empty', message: 'mutation has no operations' });
+    }
+    const seen = new Set();
+    const ops = [];
+    for (const op of request.ops) {
+        const target = op.target.trim();
+        if (target === '') {
+            errors.push({ code: 'target-empty', message: 'operation target is empty' });
+            continue;
+        }
+        if (seen.has(target)) {
+            errors.push({ code: 'target-duplicate', message: 'duplicate operation target ' + target, target });
+            continue;
+        }
+        seen.add(target);
+        const skill = op.skill?.trim();
+        if (skill !== undefined && !roots.some(root => root.name === skill)) {
+            errors.push({ code: 'op-skill-unknown', message: 'operation skill ' + skill + ' is not in roots', target });
+            continue;
+        }
+        if (request.rootDirs !== undefined) {
+            const owner = skill === undefined
+                ? roots.find(root => underRoot(request.rootDirs?.[root.name], target))
+                : underRoot(request.rootDirs[skill], target) ? { name: skill } : undefined;
+            if (owner === undefined) {
+                errors.push({ code: 'target-outside-root', message: 'operation target is outside its declared root', target });
+                continue;
+            }
+        }
+        if (op.kind === 'write') {
+            const bytes = Buffer.byteLength(op.content, 'utf8');
+            if (bytes > limits.maxSkillFileBytes) {
+                errors.push({ code: 'file-too-large', message: 'write exceeds ' + limits.maxSkillFileBytes + ' bytes', target });
+                continue;
+            }
+            if (basename(target) === 'SKILL.md' && op.content.length > limits.maxSkillContentChars) {
+                errors.push({ code: 'skill-too-large', message: 'SKILL.md exceeds ' + limits.maxSkillContentChars + ' characters', target });
+                continue;
+            }
+            ops.push({ ...op, target });
+        }
+        else {
+            ops.push({ ...op, target });
+        }
+    }
+    return { ok: errors.length === 0, roots, ops, errors };
+}
+const noLock = {
+    async acquire() {
+        return { async release() { } };
+    },
+};
+const identitySerial = async (task) => await task();
+export class MutationUnit {
+    io;
+    limits;
+    serial;
+    lock;
+    journal;
+    snapshots;
+    hooks;
+    validateWrite;
+    transact;
+    transactGuard;
+    now;
+    constructor(options) {
+        this.io = options.io;
+        this.limits = options.limits;
+        this.serial = options.serial ?? identitySerial;
+        this.lock = options.lock ?? noLock;
+        this.journal = options.journal;
+        this.snapshots = options.snapshots;
+        this.hooks = options.hooks;
+        this.validateWrite = options.validateWrite;
+        this.transact = options.transact;
+        this.transactGuard = options.transactGuard ?? true;
+        this.now = options.now ?? Date.now;
+    }
+    preview(request) {
+        const validation = validateMutationRequest(request, this.limits);
+        return {
+            ok: validation.ok,
+            unitId: request.unitId ?? 'preview-' + String(this.now()),
+            roots: validation.roots,
+            ops: validation.ops,
+            errors: validation.errors,
+        };
+    }
+    async apply(request) {
+        const primary = request.name.trim();
+        const unitId = request.unitId ?? 'u-' + String(this.now()) + '-' + Math.random().toString(36).slice(2);
+        const validation = validateMutationRequest(request, this.limits);
+        if (!validation.ok)
+            return { ok: false, unitId, dryRun: request.dryRun === true, changed: [], errors: validation.errors };
+        if (request.dryRun === true)
+            return { ok: true, unitId, dryRun: true, changed: [], errors: [] };
+        return await this.serial(async () => {
+            let lease;
+            try {
+                lease = await this.lock.acquire();
+            }
+            catch (error) {
+                return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'lock-failed', message: error instanceof Error ? error.message : String(error) }] };
+            }
+            const changed = [];
+            const warnings = [];
+            const bestEffort = async (task) => {
+                try {
+                    await task();
+                }
+                catch (error) {
+                    if (!isCommittedWarning(error))
+                        throw error;
+                    warnings.push(error instanceof Error ? error.message : String(error));
+                }
+            };
+            const snapshots = [];
+            try {
+                for (const op of validation.ops) {
+                    const current = await this.io.readText(op.target);
+                    const baseline = op.expected === undefined ? current : op.expected;
+                    if (current !== baseline) {
+                        return { ok: false, unitId, dryRun: false, changed, errors: [{ code: 'cas-drift', message: 'target changed after plan', target: op.target }] };
+                    }
+                    snapshots.push({ target: op.target, before: current, baseline });
+                }
+                for (const op of validation.ops) {
+                    const refusal = this.validateWrite?.(op) ?? null;
+                    if (refusal !== null)
+                        return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'write-validation', message: refusal, target: op.target }] };
+                }
+                const eventOps = snapshots.map(snapshot => {
+                    const op = validation.ops.find(entry => entry.target === snapshot.target);
+                    return {
+                        target: snapshot.target,
+                        before: snapshot.before,
+                        after: op?.kind === 'write' ? op.content : null,
+                        ...(op?.skill === undefined ? {} : { skill: op.skill }),
+                    };
+                });
+                const cleanup = request.cleanupPaths === undefined ? {} : { cleanup: request.cleanupPaths };
+                if (this.snapshots !== undefined)
+                    await bestEffort(() => this.snapshots.write({ unitId, state: 'prepared', ops: eventOps, ...cleanup, createdAt: this.now() }));
+                await bestEffort(async () => this.journal?.write({ unitId, phase: 'prepared', changed: [], target: validation.roots.find(root => root.name === primary)?.name ?? primary, roots: validation.roots.map(root => root.name) }));
+                for (const op of validation.ops) {
+                    const snapshot = snapshots.find(entry => entry.target === op.target);
+                    if (snapshot === undefined)
+                        throw new Error('snapshot missing for ' + op.target);
+                    try {
+                        await this.applyOp(op, snapshot.baseline);
+                        changed.push(op.target);
+                    }
+                    catch (error) {
+                        if (error?.noWrite !== true)
+                            changed.push(op.target);
+                        if (!isCommittedWarning(error))
+                            throw error;
+                        warnings.push(error instanceof Error ? error.message : String(error));
+                    }
+                }
+                await bestEffort(async () => this.journal?.write({ unitId, phase: 'unit-written', changed, target: primary, roots: validation.roots.map(root => root.name) }));
+                await bestEffort(async () => this.journal?.write({ unitId, phase: 'committed', changed, target: primary, roots: validation.roots.map(root => root.name) }));
+                if (this.snapshots !== undefined)
+                    await bestEffort(() => this.snapshots.write({ unitId, state: 'committed', ops: eventOps, ...cleanup, createdAt: this.now() }));
+                try {
+                    await this.hooks?.committed?.({ unitId, changed, ops: eventOps, roots: validation.roots.map(root => root.name) });
+                }
+                catch {
+                    // Hooks are audit/history/event side effects; a completed write must not be rolled back by one.
+                }
+                return { ok: true, unitId, dryRun: false, changed, errors: [], ...(warnings.length === 0 ? {} : { warnings }) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                let rollbackFailure = '';
+                try {
+                    await this.rollback(snapshots.filter(snapshot => changed.includes(snapshot.target)));
+                }
+                catch (rollbackError) {
+                    rollbackFailure = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+                }
+                const detail = rollbackFailure === '' ? message : message + '; rollback failed: ' + rollbackFailure;
+                await this.journal?.write({ unitId, phase: 'failed', changed, error: detail });
+                try {
+                    await this.hooks?.rolledBack?.({
+                        unitId,
+                        changed,
+                        ops: snapshots.map(snapshot => {
+                            const op = validation.ops.find(entry => entry.target === snapshot.target);
+                            return {
+                                target: snapshot.target,
+                                before: snapshot.before,
+                                after: op?.kind === 'write' ? op.content : null,
+                                ...(op?.skill === undefined ? {} : { skill: op.skill }),
+                            };
+                        }),
+                        roots: validation.roots.map(root => root.name),
+                    });
+                }
+                catch {
+                    // best-effort hook; the structured write error remains authoritative
+                }
+                return { ok: false, unitId, dryRun: false, changed, errors: [{ code: 'write-failed', message: detail }] };
+            }
+            finally {
+                await lease.release();
+            }
+        });
+    }
+    /** Recover every prepared snapshot known to the port; safe to call at boot. */
+    async recoverPrepared() {
+        const prepared = await this.snapshots?.listPrepared?.() ?? [];
+        const results = [];
+        for (const snapshot of prepared)
+            results.push(await this.recover(snapshot.unitId));
+        return results;
+    }
+    /** Converge a prepared unit left by a crash. Every path must be at its after-bytes; a drift refuses the whole recovery. */
+    async recover(unitId) {
+        const snapshot = await this.snapshots?.read(unitId);
+        if (snapshot === undefined || snapshot === null) {
+            return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'recover-missing-snapshot', message: 'no snapshot for ' + unitId }] };
+        }
+        if (snapshot.state !== 'prepared') {
+            return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'recover-not-needed', message: 'unit is not prepared: ' + unitId }] };
+        }
+        return await this.serial(async () => {
+            let lease;
+            try {
+                lease = await this.lock.acquire();
+            }
+            catch (error) {
+                return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'lock-failed', message: error instanceof Error ? error.message : String(error) }] };
+            }
+            const reverted = [];
+            try {
+                for (const op of [...snapshot.ops].reverse()) {
+                    const current = await this.io.readText(op.target);
+                    if (current === op.before)
+                        continue;
+                    if (current !== op.after) {
+                        return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'recover-drift', message: 'target is neither before nor after: ' + op.target }] };
+                    }
+                    const inverse = op.before === null
+                        ? { kind: 'delete', target: op.target, ...(op.skill === undefined ? {} : { skill: op.skill }) }
+                        : { kind: 'write', target: op.target, content: op.before, ...(op.skill === undefined ? {} : { skill: op.skill }) };
+                    await this.applyOp(inverse, op.after);
+                    reverted.push(op.target);
+                }
+                for (const path of snapshot.cleanup ?? [])
+                    await this.io.remove(path).catch(() => { });
+                await this.snapshots?.write({ ...snapshot, state: 'undone' });
+                await this.journal?.write({ unitId, phase: 'undone', changed: reverted, ...(snapshot.ops[0]?.target === undefined ? {} : { target: snapshot.ops[0].target }), roots: [...new Set(snapshot.ops.map(op => op.skill).filter((skill) => skill !== undefined))] });
+                try {
+                    await this.hooks?.undone?.({ unitId, changed: reverted, ops: snapshot.ops, roots: [...new Set(snapshot.ops.map(op => op.skill).filter((skill) => skill !== undefined))] });
+                }
+                catch {
+                    // best-effort hook
+                }
+                return { ok: true, unitId, dryRun: false, changed: reverted, errors: [] };
+            }
+            catch (error) {
+                return { ok: false, unitId, dryRun: false, changed: reverted, errors: [{ code: 'recover-failed', message: error instanceof Error ? error.message : String(error) }] };
+            }
+            finally {
+                await lease.release();
+            }
+        });
+    }
+    async undo(unitId) {
+        const snapshot = await this.snapshots?.read(unitId);
+        if (snapshot === undefined || snapshot === null) {
+            return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'undo-missing-snapshot', message: 'no committed snapshot for ' + unitId }] };
+        }
+        if (snapshot.state === 'prepared') {
+            return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'undo-needs-recovery', message: 'unit has a prepared snapshot; run recover first: ' + unitId }] };
+        }
+        if (snapshot.state === 'undone') {
+            return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'undo-already', message: 'unit already undone: ' + unitId }] };
+        }
+        return await this.serial(async () => {
+            let lease;
+            try {
+                lease = await this.lock.acquire();
+            }
+            catch (error) {
+                return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'lock-failed', message: error instanceof Error ? error.message : String(error) }] };
+            }
+            const undone = [];
+            try {
+                for (const op of snapshot.ops) {
+                    const current = await this.io.readText(op.target);
+                    if (current !== op.after) {
+                        return { ok: false, unitId, dryRun: false, changed: [], errors: [{ code: 'undo-preflight', message: 'target changed after the unit: ' + op.target }] };
+                    }
+                }
+                for (const op of [...snapshot.ops].reverse()) {
+                    const inverse = op.before === null
+                        ? { kind: 'delete', target: op.target, ...(op.skill === undefined ? {} : { skill: op.skill }) }
+                        : { kind: 'write', target: op.target, content: op.before, ...(op.skill === undefined ? {} : { skill: op.skill }) };
+                    await this.applyOp(inverse, op.after);
+                    undone.push(op.target);
+                }
+                for (const path of snapshot.cleanup ?? [])
+                    await this.io.remove(path).catch(() => { });
+                await this.journal?.write({ unitId, phase: 'undone', changed: undone, ...(snapshot.ops[0]?.target === undefined ? {} : { target: snapshot.ops[0].target }), roots: [...new Set(snapshot.ops.map(op => op.skill).filter((skill) => skill !== undefined))] });
+                await this.snapshots?.write({ ...snapshot, state: 'undone' });
+                try {
+                    await this.hooks?.undone?.({ unitId, changed: undone, ops: snapshot.ops, roots: [...new Set(snapshot.ops.map(op => op.skill).filter((skill) => skill !== undefined))] });
+                }
+                catch {
+                    // best-effort hook; the undo itself already landed
+                }
+                return { ok: true, unitId, dryRun: false, changed: undone, errors: [] };
+            }
+            catch (error) {
+                for (const target of undone.reverse()) {
+                    const op = snapshot.ops.find(entry => entry.target === target);
+                    if (op === undefined)
+                        continue;
+                    try {
+                        if (op.after === null)
+                            await this.io.remove(target);
+                        else
+                            await this.io.writeText(target, op.after);
+                    }
+                    catch {
+                        // best-effort undo compensation; the structured error below remains honest
+                    }
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false, unitId, dryRun: false, changed: undone, errors: [{ code: 'undo-failed', message }] };
+            }
+            finally {
+                await lease.release();
+            }
+        });
+    }
+    async applyOp(op, baseline) {
+        if (this.transact !== undefined && op.kind === 'write') {
+            let ran = false;
+            await this.transact(this.io, op.target, () => {
+                ran = true;
+                return op.content;
+            });
+            if (!ran)
+                throw new Error('internal error: the write transaction did not invoke the task; no write was performed');
+            return;
+        }
+        const next = op.kind === 'delete' ? null : op.content;
+        if (this.io.transact !== undefined) {
+            let conflict = false;
+            let wrote = false;
+            await this.io.transact(op.target, current => {
+                if (current !== baseline) {
+                    if (this.transactGuard)
+                        throw new Error('concurrent modification detected: ' + op.target);
+                    conflict = true;
+                    return current;
+                }
+                wrote = true;
+                return next;
+            });
+            if (conflict && !wrote)
+                throw Object.assign(new Error('concurrent modification detected: ' + op.target), { noWrite: true });
+            return;
+        }
+        const current = await this.io.readText(op.target);
+        if (current !== baseline)
+            throw new Error('concurrent modification detected: ' + op.target);
+        if (next === null)
+            await this.io.remove(op.target);
+        else
+            await this.io.writeText(op.target, next);
+    }
+    async rollback(snapshots) {
+        for (const snapshot of [...snapshots].reverse()) {
+            if (snapshot.before === null)
+                await this.io.remove(snapshot.target);
+            else
+                await this.io.writeText(snapshot.target, snapshot.before);
+        }
+    }
+}
+function parseFileLock(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value.token !== 'string' || typeof value.pid !== 'number' || typeof value.startedAt !== 'number')
+            return undefined;
+        return { token: value.token, pid: value.pid, startedAt: value.startedAt };
+    }
+    catch {
+        return undefined;
+    }
+}
+const defaultSleep = async (ms) => await new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * Cross-process root mutation lock. A live holder is never stolen; a dead pid
+ * or corrupt record can be taken over. This is separate from merge's run-level
+ * tree lock so an ordinary skill write cannot deadlock a merge run.
+ */
+export function fileMutationLock(io, root, options = {}) {
+    const path = join(dirname(root), '.' + basename(root) + '.mutation-lock');
+    const waitMs = options.waitMs ?? 5000;
+    const pollMs = options.pollMs ?? 25;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    const update = async (task) => {
+        if (io.transact !== undefined) {
+            let ran = false;
+            await io.transact(path, current => {
+                ran = true;
+                return task(current);
+            });
+            if (!ran)
+                throw new Error('mutation-lock-transact-not-run: ' + path);
+            return;
+        }
+        const current = await io.readText(path);
+        const next = task(current);
+        try {
+            if (next === null)
+                await io.remove(path);
+            else
+                await io.writeText(path, next);
+        }
+        catch (error) {
+            if (!isCommittedWarning(error))
+                throw error;
+        }
+    };
+    return {
+        async acquire() {
+            const deadline = now() + waitMs;
+            for (;;) {
+                const token = randomUUID();
+                let acquired = false;
+                await update(current => {
+                    const existing = parseFileLock(current);
+                    if (existing !== undefined && isProcessAlive(existing.pid))
+                        return current;
+                    acquired = true;
+                    return JSON.stringify({ token, pid: process.pid, startedAt: now() });
+                });
+                if (acquired) {
+                    let released = false;
+                    return {
+                        async release() {
+                            if (released)
+                                return;
+                            released = true;
+                            await update(current => {
+                                const record = parseFileLock(current);
+                                return record?.token === token ? null : current;
+                            });
+                        },
+                    };
+                }
+                if (now() >= deadline)
+                    throw new Error('mutation-lock-busy: ' + path);
+                await sleep(Math.min(pollMs, Math.max(0, deadline - now())));
+            }
+        },
+    };
+}
+//# sourceMappingURL=mutation-unit.js.map

package/lib/types/prompts.d.ts

@@ -3,8 +3,8 @@
  * changes semantically: the bundle digest is the fail-closed signal for
  * review workers, so a stale id across deployments must be distinguishable.
  */
-export declare const PROMPT_BUNDLE_VERSION = 22;
-export declare const PROMPT_BUNDLE_ID = "dsh-evolution@22";
+export declare const PROMPT_BUNDLE_VERSION = 23;
+export declare const PROMPT_BUNDLE_ID = "dsh-evolution@23";
 export declare const MEMORY_REVIEW_PROMPT = "[Auto-review \u2014 Memory]\nReview the conversation above and consider saving to memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate?\n\nIf something stands out, save it using the memory tool.\nIf nothing is worth saving, just say \"Nothing to save.\" and stop.";
 export declare const SKILL_REVIEW_PROMPT = "[Auto-review \u2014 Skills]\nReview the conversation above and update the skill library. Be ACTIVE \u2014 inspect the session and the existing library thoroughly, and prefer a small, precise update when the session teaches something durable. Activity is not a quota: a precise no-op after checking is better than a vague or forced entry.\n\nTarget 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.\n\nA skill body is a reusable decision rule (when / do / check); dates, versions, incident narratives, and one-off evidence belong in references when they would otherwise dominate the body.\n\nSignals to look for (any one of these warrants action):\n  \u2022 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.\n  \u2022 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.\n  \u2022 Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.\n  \u2022 A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.\n\nRead-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.\n\nPreference order \u2014 prefer the earliest action that fits, but do pick one when a signal above fired:\n  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.\n  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.\n  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files \u2014 use the right directory per kind:\n     \u2022 references/<topic>.md \u2014 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.\n     \u2022 templates/<name>.<ext> \u2014 starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can reproduce with modifications).\n     \u2022 scripts/<name>.<ext> \u2014 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).\n     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.\n  4. RESTRUCTURE a loaded skill whose body grew log-like \u2014 rc/sha/date-dense sections, session-detail spirals, or a fat body with no support files. Use skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section (from that heading to the next heading) moves into the support file and its position becomes a pointer line. The skill's name and directory never change. Only propose headings that exist verbatim in the body; never invent one, and never restructure a healthy small skill.\n  5. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL only when no existing class-level skill covers the class and no existing umbrella can absorb the learning. 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 \u2014 fall back to (1), (2), or (3).\n\nUser-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.\n\nIf you notice two existing skills that overlap, note it in your reply \u2014 the background curator handles consolidation at scale.\n\nTwo-tier deposition discipline (DSH addition, same spirit as the umbrella rule): before writing, classify the knowledge:\n  \u2022 PATTERN (reusable \u2014 symptom \u2192 mechanism \u2192 fix \u2192 verification, still valuable next session) belongs in the SKILL.md body.\n  \u2022 LOG (one-off \u2014 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.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so this pass may not update them. They also cannot be archived by any writer (the foreground included): remove the .pinned marker first. Foreground and delegated-subagent update/patch writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 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.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 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.\n\nIf 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 \u2014 never 'this tool does not work' as a standalone constraint.\n\n'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, state what you checked and stop. Otherwise, act.";
 export declare const COMBINED_REVIEW_PROMPT = "[Auto-review]\nReview the conversation above and update two things:\n\n**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.\n\n**Skills**: how to do this class of task. Be ACTIVE \u2014 inspect the session and the existing library thoroughly, and prefer a small, precise update when the session teaches something durable. Activity is not a quota: a precise no-op after checking is better than a vague or forced entry.\n\nTarget 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.\n\nA skill body is a reusable decision rule (when / do / check); dates, versions, incident narratives, and one-off evidence belong in references when they would otherwise dominate the body.\n\nSignals that warrant a skill update (any one is enough):\n  \u2022 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' \u2014 embed the lesson in the skill that governs that task so the next session starts fixed.\n  \u2022 Non-trivial technique, fix, workaround, or debugging path emerged.\n  \u2022 A skill that was loaded or consulted turned out wrong, missing, or outdated \u2014 patch it now.\n\nRead-before-write: update, patch, delete, or write support files ONLY into skills you loaded or read in THIS session. On the plan channel ops on unread skills are rejected; direct writes have no such guard, so treat the rule as binding. CREATE of a brand-new umbrella is the only exception.\n\nPreference order for skills \u2014 pick the earliest that fits:\n  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.\n  2. UPDATE AN EXISTING UMBRELLA. Patch it.\n  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.\n  4. RESTRUCTURE a loaded skill whose body grew log-like (rc/sha/date-dense sections, session-detail spirals, fat body with no support files) via skill_manage action=restructure with restructure: [{\"heading\": \"<the exact ## heading text>\", \"to_file\": \"references/<topic>.md\"}] \u2014 the ENTIRE ## section moves into the support file and its position becomes a pointer line; the skill's name and directory never change. Only propose headings that exist verbatim in the body.\n  5. CREATE A NEW CLASS-LEVEL UMBRELLA only when no existing class-level skill covers the class and no existing umbrella can absorb the learning. Name at the class level \u2014 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).\n\nTwo-tier deposition discipline (DSH addition): classify before writing \u2014 PATTERN (symptom \u2192 mechanism \u2192 fix \u2192 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.\n\nUser-preference embedding: when the user complains about how you handled a task, update the skill that governs that task \u2014 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.\n\nIf you notice overlapping existing skills, mention it \u2014 the background curator handles consolidation.\n\nProtected skills (DO NOT edit these):\n  \u2022 Bundled skills (shipped with the platform).\n  \u2022 Hub-installed skills (installed from a hub).\nPinned skills are read-only to THIS background review pass \u2014 the pinned write guard refuses background changes, so this pass may not update them. They also cannot be archived by any writer (the foreground included): remove the .pinned marker first. Foreground and delegated-subagent update/patch writes to pinned skills remain allowed.\nIf the only skills that need updating are protected, say 'Nothing to save.' and stop.\n\nDo NOT capture as skills (these become persistent self-imposed constraints that bite you later when the environment changes):\n  \u2022 Environment-dependent failures: missing binaries, fresh-install errors, post-migration path mismatches, 'command not found', unconfigured credentials, uninstalled packages. The user can fix these \u2014 they are not durable rules.\n  \u2022 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.\n  \u2022 Session-specific transient errors that resolved before the conversation ended. If retrying worked, the lesson is the retry pattern, not the original failure.\n  \u2022 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.\n\nIf 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 \u2014 never 'this tool does not work' as a standalone constraint.\n\nAct on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop \u2014 but don't reach for that conclusion as a default.";
@@ -52,5 +52,5 @@ export interface PromptBundle {
 }
 export declare const PROMPT_BUNDLE: PromptBundle;
 export declare function verifyPromptBundle(bundle?: PromptBundle): boolean;
-export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe \u2014 an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n- metadata.hermes.related_skills: [a, b] \u2014 name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## When to Use\" \u2014 concrete trigger phrases.\n3. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n4. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n5. \"## Quick Reference\" \u2014 flat command/endpoint list.\n6. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n7. \"## Pitfalls\" \u2014 known limits and rate limits.\n8. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.\n\nLearn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):\n1. Gather every source named (files, URLs, \"what we just did\", pasted notes) with the tools you already have \u2014 and treat prose after a source as authoring requirements, not noise.\n2. Apply every requirement and constraint from the request to the SKILL.md you author.\n3. Author exactly ONE SKILL.md and save it with `skill_manage` (action=create); non-trivial scripts go under `scripts/`.\n4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.";
+export declare const DSH_AUTHORING_STANDARDS = "Follow the Hermes skill-authoring standards, translated to DSH tools.\n\nFrontmatter:\n- name: lowercase-hyphenated, <=64 chars, no spaces.\n- description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.\n- whenToUse: ONE abstract sentence describing the task situation that should trigger this skill. This is the platform's machine-routing field: do not enumerate a scenario list and do not repeat the description. One line only; quote it if it contains a colon.\n- version: 0.1.0\n- author: always the literal value \"Hermes\". NEVER fill it from the environment, git config, or any identity you can probe \u2014 an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.\n- platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.\n- metadata.hermes.tags: a few Capitalized, Relevant, Tags.\n- metadata.hermes.related_skills: [a, b] \u2014 name sibling skills this one builds on or is referenced by (optional; feeds the quality references factor).\n\nBody section order (omit only when empty):\n1. \"# <Human Title>\" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.\n2. \"## Prerequisites\" \u2014 exact env vars, install steps, credentials.\n3. \"## How to Run\" \u2014 canonical invocation framed through DSH tools.\n4. \"## Quick Reference\" \u2014 flat command/endpoint list.\n5. \"## Procedure\" \u2014 numbered steps with copy-paste-exact commands.\n6. \"## Pitfalls\" \u2014 known limits and rate limits.\n7. \"## Verification\" \u2014 one check proving the skill worked.\n\nDSH-tool framing:\n- Reference DSH tools by name in backticks: `bash`, `str_replace_editor`, `write`, `skill`, `skill_manage`, `memory`.\n- Do not name wrapped shell utilities when a DSH tool already covers them.\n- Larger scripts belong under `scripts/` (written with `skill_manage write_file`) and are referenced from SKILL.md by relative path.\n\nQuality bar:\n- Prefer verbatim flags, paths, and APIs from the source. Never invent them.\n- Keep it tight: ~100 lines simple, ~200 complex.\n- No router/index/hub skills that only point at other skills.\n- References go in `references/`, templates in `templates/`.\n\nLearn workflow (when the user asks you to learn a reusable skill, or you decide to turn a source/request into one):\n1. Gather every source named (files, URLs, \"what we just did\", pasted notes) with the tools you already have \u2014 and treat prose after a source as authoring requirements, not noise.\n2. Apply every requirement and constraint from the request to the SKILL.md you author.\n3. Author exactly ONE SKILL.md and save it with `skill_manage` (action=create); non-trivial scripts go under `scripts/`.\n4. When done, tell the user the skill name, its category, and a one-line summary of what it captured.";
 //# sourceMappingURL=prompts.d.ts.map

package/lib/types/prompts.js

@@ -26,7 +26,7 @@ import { createHash } from 'node:crypto';
  * changes semantically: the bundle digest is the fail-closed signal for
  * review workers, so a stale id across deployments must be distinguishable.
  */
-export const PROMPT_BUNDLE_VERSION = 22;
+export const PROMPT_BUNDLE_VERSION = 23;
 // 0.3.16 (S1.12, T-5): the id is DERIVED from the version — a one-number bump
 // can no longer drift the two apart.
 export const PROMPT_BUNDLE_ID = `dsh-evolution@${PROMPT_BUNDLE_VERSION}`;
@@ -415,6 +415,7 @@ export const DSH_AUTHORING_STANDARDS = `Follow the Hermes skill-authoring standa
 Frontmatter:
 - name: lowercase-hyphenated, <=64 chars, no spaces.
 - description: ONE sentence, <=60 characters, ends with a period. State the capability, not the implementation. No marketing words. Do NOT repeat the skill name. Count the characters before saving. If the description contains a colon, wrap the whole value in double quotes.
+- whenToUse: ONE abstract sentence describing the task situation that should trigger this skill. This is the platform's machine-routing field: do not enumerate a scenario list and do not repeat the description. One line only; quote it if it contains a colon.
 - version: 0.1.0
 - author: always the literal value "Hermes". NEVER fill it from the environment, git config, or any identity you can probe — an environment-derived name is a privacy leak the user never opted into (skills get shared and published), and the skill names itself as Hermes.
 - platforms: declare [macos], [linux], and/or [windows] only when the skill is genuinely OS-bound (osascript/apt/systemctl => the matching OS; /proc, signal.SIGKILL => linux; fcntl/termios => POSIX). Prefer fixing it cross-platform first (tempdir, pathlib, pure-Node); omit the field for portable skills.
@@ -423,13 +424,12 @@ Frontmatter:
 
 Body section order (omit only when empty):
 1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT do, key dependency stance.
-2. "## When to Use" — concrete trigger phrases.
-3. "## Prerequisites" — exact env vars, install steps, credentials.
-4. "## How to Run" — canonical invocation framed through DSH tools.
-5. "## Quick Reference" — flat command/endpoint list.
-6. "## Procedure" — numbered steps with copy-paste-exact commands.
-7. "## Pitfalls" — known limits and rate limits.
-8. "## Verification" — one check proving the skill worked.
+2. "## Prerequisites" — exact env vars, install steps, credentials.
+3. "## How to Run" — canonical invocation framed through DSH tools.
+4. "## Quick Reference" — flat command/endpoint list.
+5. "## Procedure" — numbered steps with copy-paste-exact commands.
+6. "## Pitfalls" — known limits and rate limits.
+7. "## Verification" — one check proving the skill worked.
 
 DSH-tool framing:
 - Reference DSH tools by name in backticks: \`bash\`, \`str_replace_editor\`, \`write\`, \`skill\`, \`skill_manage\`, \`memory\`.

package/lib/types/proposal-view.d.ts

@@ -18,9 +18,13 @@ export interface ProposalView {
     }>;
     owner: OwnerDecision;
     support?: SupportClosure;
+    /** The source body left behind after extraction; the panel can show what is KEPT. */
+    residual?: string;
     warnings: string[];
     provenance: {
         promptVersion: 'v1';
+        promptHash?: string;
+        model?: string;
         runId: string;
         at: number;
     };

package/lib/types/proposal-view.js

@@ -1,3 +1,4 @@
+import { EXTRACT_PROMPT_HASH, EXTRACT_PROMPT_VERSION } from "./extract-prompt.js";
 /**
  * Project a pure ExtractPlan into the proposal record every read-only surface consumes.
  *
@@ -16,8 +17,9 @@ export function proposalFromPlan(plan, provenance) {
         parts: plan.parts.map(part => ({ heading: part.heading, anchor: part.anchor, reason: part.sourceText.slice(0, 160) })),
         owner: plan.owner,
         support: plan.support,
+        residual: plan.residual,
         warnings: plan.warnings,
-        provenance: { promptVersion: 'v1', runId: provenance.runId, at: provenance.at ?? Date.now() },
+        provenance: { promptVersion: EXTRACT_PROMPT_VERSION, promptHash: EXTRACT_PROMPT_HASH, runId: provenance.runId, at: provenance.at ?? Date.now() },
         status: 'proposed',
     };
 }