@lmzhen/dsh-evolution-merge 0.28.0 → 0.30.0

package/lib/types/adapters/channel.js

@@ -0,0 +1,29 @@
+function convert(outcome) {
+    if (outcome.kind !== 'ok')
+        return outcome;
+    return {
+        kind: 'ok',
+        childId: String(outcome.childId),
+        turn: { text: outcome.turn.text, stopReason: outcome.turn.stopReason },
+    };
+}
+export function subagentChannelAdapter(channel) {
+    return {
+        async open(spec) {
+            if (channel.open === undefined)
+                return { kind: 'unavailable', code: 'E-323', reason: 'subagent channel has no open()' };
+            return convert(await channel.open(spec));
+        },
+        async continueTurn(childId, promptText, options) {
+            if (channel.continueTurn === undefined)
+                return { kind: 'unavailable', code: 'E-323', reason: 'subagent channel has no continueTurn()' };
+            return convert(await channel.continueTurn(childId, promptText, options));
+        },
+        async dispose(childId) {
+            if (channel.dispose === undefined)
+                return;
+            await channel.dispose(childId);
+        },
+    };
+}
+//# sourceMappingURL=channel.js.map

package/lib/types/adapters/engine-screen.d.ts

@@ -0,0 +1,55 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { MergeCandidate } from '../contracts.ts';
+import type { SkillCard } from '../skill-card.ts';
+export type EngineScreenResult = {
+    readonly ok: true;
+    readonly report: Record<string, unknown>;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly stage?: string;
+        readonly detail?: string;
+    };
+};
+export interface EngineScreenPort {
+    screen(input: {
+        readonly corpusDir: string;
+        readonly outDir: string;
+        readonly cfg?: Record<string, unknown>;
+        readonly signal?: AbortSignal;
+        readonly onProgress?: (p: {
+            stage: string;
+            done?: number;
+            total?: number;
+        }) => void;
+        readonly runner?: (prompt: string, cfg?: Record<string, unknown>) => Promise<string>;
+    }): Promise<EngineScreenResult>;
+}
+export interface CandidateSelection {
+    readonly candidates: readonly MergeCandidate[];
+    readonly skipped: readonly {
+        readonly pairKey: string;
+        readonly a: string;
+        readonly b: string;
+        readonly reason?: string;
+    }[];
+    readonly reportOnly: readonly unknown[];
+    readonly candidatePairs?: number;
+}
+export type ScreeningCandidates = readonly MergeCandidate[] & {
+    readonly candidatePairs?: number;
+};
+export interface EngineScreeningDeps {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly engine: EngineScreenPort;
+    readonly select: (report: Record<string, unknown>) => CandidateSelection;
+    readonly cfg?: Record<string, unknown>;
+    readonly runner?: (prompt: string, cfg?: Record<string, unknown>) => Promise<string>;
+    readonly onSelection?: (selection: CandidateSelection, runId: string) => Promise<void>;
+}
+/** Write the exact card bodies as a support-free corpus snapshot and return its root. */
+export declare function snapshotCards(io: EvolutionIoLike, home: string, runId: string, cards: readonly SkillCard[]): Promise<string>;
+export declare function createEngineScreening(deps: EngineScreeningDeps): (cards: readonly SkillCard[], runId: string, signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
+//# sourceMappingURL=engine-screen.d.ts.map

package/lib/types/adapters/engine-screen.js

@@ -0,0 +1,45 @@
+/**
+ * G3 screen adapter: cards -> corpus snapshot -> EnginePort.screen.
+ *
+ * The vendor engine reads a corpus from disk; host cards are content. This module
+ * writes only SKILL.md support-free snapshots under the run directory. It does not
+ * decide candidates: the Q02 selector is injected so engine/report-map stays the
+ * single source of that policy.
+ */
+import { join } from 'node:path';
+function safeName(name, index) {
+    const cleaned = name.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return (cleaned === '' ? 'skill-' + String(index) : cleaned) + '__' + String(index);
+}
+/** Write the exact card bodies as a support-free corpus snapshot and return its root. */
+export async function snapshotCards(io, home, runId, cards) {
+    const root = join(home, 'merge', 'runs', runId, 'corpus');
+    for (let index = 0; index < cards.length; index += 1) {
+        const card = cards[index];
+        if (card === undefined)
+            continue;
+        await io.writeText(join(root, safeName(card.name, index), 'SKILL.md'), card.body);
+    }
+    return root;
+}
+export function createEngineScreening(deps) {
+    return async (cards, runId, signal) => {
+        const corpusDir = await snapshotCards(deps.io, deps.home, runId, cards);
+        const outDir = join(deps.home, 'merge', 'runs', runId, 'engine');
+        const result = await deps.engine.screen({
+            corpusDir,
+            outDir,
+            ...(deps.cfg === undefined ? {} : { cfg: deps.cfg }),
+            ...(deps.runner === undefined ? {} : { runner: deps.runner }),
+            signal,
+        });
+        if (!result.ok) {
+            throw new Error('engine screen failed: ' + result.error.code + (result.error.stage === undefined ? '' : ' @' + result.error.stage) + (result.error.detail === undefined ? '' : ': ' + result.error.detail));
+        }
+        const selection = deps.select(result.report);
+        if (deps.onSelection !== undefined)
+            await deps.onSelection(selection, runId);
+        return Object.assign(selection.candidates.slice(), selection.candidatePairs === undefined ? {} : { candidatePairs: selection.candidatePairs });
+    };
+}
+//# sourceMappingURL=engine-screen.js.map

package/lib/types/adapters/library.js

@@ -0,0 +1,14 @@
+export function skillLibraryPort(skills) {
+    const archivedNames = skills.archivedNames;
+    return {
+        readSkill: name => skills.read(name),
+        isArchived: async (name) => {
+            if (typeof archivedNames !== 'function')
+                return false;
+            const names = await archivedNames.call(skills);
+            return names === null ? true : names.includes(name);
+        },
+        commitMerge: plan => skills.commitMerge(plan),
+    };
+}
+//# sourceMappingURL=library.js.map

package/lib/types/adapters/model-runner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DeepSeek judge runner over the platform llm service. The engine calls
+ * runner(prompt, cfg) and expects raw model text; the platform owns provider
+ * selection, usage accounting and transport.
+ */
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+export interface LlmChunkLike {
+    readonly type: string;
+    readonly text?: string;
+    readonly reason?: {
+        readonly kind?: string;
+        readonly failure?: {
+            readonly message?: string;
+        };
+    };
+}
+export interface LlmServiceLike {
+    stream?(options: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+    prepareCall?(config: Record<string, unknown>, signal?: AbortSignal): Promise<{
+        readonly config: Record<string, unknown>;
+        stream(input: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+    }>;
+}
+export declare function createEngineRunner(llm: LlmServiceLike, route: () => ModelRoute): (prompt: string) => Promise<string>;
+//# sourceMappingURL=model-runner.d.ts.map

package/lib/types/adapters/model-runner.js

@@ -0,0 +1,34 @@
+function append(chunk, text) {
+    if (chunk.type === 'text-delta' || chunk.type === 'text')
+        return text + (chunk.text ?? '');
+    if (chunk.type === 'finish' && chunk.reason?.kind === 'error') {
+        throw new Error('model call failed: ' + (chunk.reason.failure?.message ?? 'unknown'));
+    }
+    return text;
+}
+export function createEngineRunner(llm, route) {
+    return async (prompt) => {
+        const selection = route();
+        let text = '';
+        if (llm.stream !== undefined) {
+            for await (const chunk of llm.stream({
+                provider: selection.provider,
+                model: selection.model,
+                messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+                temperature: 0,
+            }))
+                text = append(chunk, text);
+            return text;
+        }
+        if (llm.prepareCall === undefined)
+            throw new Error('llm service has neither stream nor prepareCall');
+        const call = await llm.prepareCall({ provider: selection.provider, model: selection.model, temperature: 0 });
+        for await (const chunk of call.stream({
+            ...call.config,
+            messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+        }))
+            text = append(chunk, text);
+        return text;
+    };
+}
+//# sourceMappingURL=model-runner.js.map

package/lib/types/adapters/select.d.ts

@@ -0,0 +1,3 @@
+import type { CandidateSelection } from './engine-screen.ts';
+export declare function selectWithErrors(report: Record<string, unknown>): CandidateSelection;
+//# sourceMappingURL=select.d.ts.map

package/lib/types/adapters/select.js

@@ -0,0 +1,35 @@
+/** Host selector correction: engine selector does not route judge errors to candidates. */
+import { pairKeyOf, selectCandidates, toEngineCandidate } from '@lmzhen/dsh-evolution-merge-engine';
+export function selectWithErrors(report) {
+    const base = selectCandidates(report);
+    const doc = (report.reportDoc ?? report);
+    const rows = Array.isArray(doc.pairs_final) ? doc.pairs_final : [];
+    const errors = new Set();
+    for (const row of rows) {
+        if (row.error !== true)
+            continue;
+        const a = typeof row.a === 'string' ? row.a : '';
+        const b = typeof row.b === 'string' ? row.b : '';
+        if (a !== '' && b !== '')
+            errors.add(pairKeyOf(a, b));
+    }
+    const candidates = base.candidates.filter(candidate => !errors.has(pairKeyOf(candidate.a, candidate.b)));
+    const skipped = base.skipped.filter(item => !errors.has(item.pairKey));
+    const reportOnly = base.reportOnly.filter((row) => {
+        const value = row;
+        if (typeof value.a !== 'string' || typeof value.b !== 'string')
+            return true;
+        return !errors.has(pairKeyOf(value.a, value.b));
+    });
+    for (const row of rows) {
+        if (row.error !== true)
+            continue;
+        const a = typeof row.a === 'string' ? row.a : '';
+        const b = typeof row.b === 'string' ? row.b : '';
+        if (a === '' || b === '')
+            continue;
+        candidates.push(toEngineCandidate(row, typeof row.reason === 'string' ? row.reason : 'judge-error'));
+    }
+    return { ...base, candidates, skipped, reportOnly };
+}
+//# sourceMappingURL=select.js.map

package/lib/types/adapters/undo.js

@@ -0,0 +1,35 @@
+/**
+ * SkillLibrary-backed undo sink. Blobs are content-addressed but the library exposes them by
+ * version, so the first readBlob call indexes all version bodies once; an undo is rare enough
+ * that this is preferable to adding a second hash index.
+ */
+import { contentHash } from '@lmzhen/dsh-evolution-core';
+export function skillLibraryUndoPort(skills) {
+    let blobs;
+    const readBlob = async (hash) => {
+        if (blobs === undefined) {
+            blobs = new Map();
+            for (const summary of await skills.list()) {
+                for (const version of await skills.listVersions(summary.name)) {
+                    const body = await skills.readVersion(summary.name, version.v);
+                    if (body !== null)
+                        blobs.set(contentHash(body), body);
+                }
+            }
+        }
+        return blobs.get(hash) ?? null;
+    };
+    const sink = {
+        readSkill: name => skills.read(name),
+        readSupport: (name, path) => skills.readSupportFile(name, path),
+        readBlob,
+        async hasArchived(name) { return (await skills.read(name)) === null; },
+        restoreFromArchive: name => skills.restoreFromArchive(name),
+        archive: (name, reason) => skills.archive(name, { reason }),
+        updateSkill: (name, body, anchor) => skills.update(name, body, undefined, anchor),
+        writeSupportFile: (name, path, content, anchor) => skills.writeSupportFile(name, path, content, undefined, anchor),
+        removeSupportFile: (name, path, anchor) => skills.removeSupportFile(name, path, undefined, anchor),
+    };
+    return { ...sink, listVersions: name => skills.listVersions(name) };
+}
+//# sourceMappingURL=undo.js.map

package/lib/types/approve-command.js

@@ -0,0 +1,42 @@
+import { approvePending } from "./pending-actions.js";
+import { withMergeRun } from "./run-shell.js";
+import { recordRound2Outcome } from "./round2-outcome.js";
+export async function runApproveCommand(options) {
+    const taken = await approvePending(options.io, options.home, options.now, options.rowId);
+    if (!taken.ok)
+        return { ok: false, message: taken.message };
+    const row = taken.row;
+    const decision = row.decision;
+    if (decision === undefined)
+        return { ok: false, message: 'pending row has no decision' };
+    return await withMergeRun({
+        io: options.io,
+        home: options.home,
+        registry: options.registry,
+        command: 'approve',
+        approval: { platformWrite: options.platformWrite, mergeApproval: true },
+        now: options.now,
+        async body(ctx) {
+            const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
+            await stage('author');
+            let outcome;
+            try {
+                outcome = await options.ports.round2(row, decision, ctx.signal, ctx.runId);
+            }
+            catch (error) {
+                outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
+            }
+            const base = { scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } }, notes: [] };
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome);
+            return {
+                ...base,
+                stopReason: record.merged ? 'completed' : 'failed',
+                pairs: [record.pair],
+                totals: record.merged
+                    ? { merged: 1, kept: 0, pending: 0, failed: 0 }
+                    : { merged: 0, kept: 0, pending: 0, failed: 1 },
+            };
+        },
+    });
+}
+//# sourceMappingURL=approve-command.js.map

package/lib/types/authoring-flow.d.ts

@@ -7,12 +7,15 @@ import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type RuleFinding } from './rules.ts';
 import { type CommitPort, type CommitStagedResult } from './commit-execute.ts';
 import type { StagedTree } from './rules.ts';
-import type { SkillCard } from './screening.ts';
+import type { SkillCard } from './skill-card.ts';
 export interface RunAuthoringOptions {
     readonly io: EvolutionIoLike;
     readonly home: string;
     readonly runId: string;
+    readonly stageKey?: string;
+    readonly reuseStaging?: boolean;
     readonly target: string;
+    readonly mode?: 'merge-into-existing' | 'create-umbrella' | 'keep';
     readonly cards: readonly SkillCard[];
     readonly author: (staging: {
         readonly home: string;
@@ -25,7 +28,9 @@ export interface RunAuthoringOptions {
 export type AuthoringResult = {
     readonly ok: true;
     readonly tree: StagedTree;
-    readonly commit: CommitStagedResult;
+    readonly commit: Extract<CommitStagedResult, {
+        readonly ok: true;
+    }>;
 } | {
     readonly ok: false;
     readonly message: string;

package/lib/types/authoring-flow.js

@@ -0,0 +1,48 @@
+import { createStaging, setStagingTarget } from "./staging.js";
+import { readStagedTree } from "./staged-tree.js";
+import { validateStagedTree, hasBlockingFinding } from "./rules.js";
+import { commitStagedRun } from "./commit-execute.js";
+export async function runAuthoring(options) {
+    const targetCard = options.cards.find(card => card.name === options.target);
+    if (targetCard?.protectionUnknown === true || targetCard?.protectedBy === 'pinned')
+        return { ok: false, message: 'target is pinned: ' + options.target };
+    const stageKey = options.stageKey ?? options.runId;
+    if (options.reuseStaging === true) {
+        if (!await setStagingTarget(options.io, options.home, stageKey, options.target, options.mode))
+            return { ok: false, message: 'staging missing or unreadable: ' + stageKey };
+    }
+    else {
+        const created = await createStaging(options.io, options.home, {
+            runId: stageKey,
+            target: options.target,
+            ...(options.mode === undefined ? {} : { mode: options.mode }),
+            sources: options.cards.map(card => ({ name: card.name, body: card.body, files: card.files ?? [] })),
+            promptVersion: 'merge-b/v1',
+            ttlDays: 7,
+            now: options.now,
+        });
+        if (!created.ok)
+            return { ok: false, message: created.message };
+    }
+    try {
+        await options.author({ home: options.home, runId: stageKey });
+    }
+    catch (error) {
+        return { ok: false, message: 'author failed: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+    const tree = await readStagedTree(options.io, options.home, stageKey);
+    if (tree.kind !== 'present')
+        return { ok: false, message: 'staged tree is not readable: ' + (tree.kind === 'unknown' ? tree.reason : 'absent') };
+    const findings = validateStagedTree(tree.value);
+    if (hasBlockingFinding(findings))
+        return { ok: false, message: 'staged tree failed the rule gate', findings };
+    const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
+        origin: 'subagent',
+        summary: options.summary,
+        now: options.now,
+    });
+    if (!commit.ok)
+        return { ok: false, message: commit.message };
+    return { ok: true, tree: tree.value, commit };
+}
+//# sourceMappingURL=authoring-flow.js.map

package/lib/types/channel-port.d.ts

@@ -4,7 +4,7 @@
  * outside this adapter: the caller owns staging -> commitStagedRun.
  */
 import type { MergeDecision, MergeRow } from './contracts.ts';
-import type { SkillCard } from './screening.ts';
+import type { SkillCard } from './skill-card.ts';
 import type { ScanRound1Outcome } from './scan-run.ts';
 export interface ChannelTurnLike {
     readonly text: string;
@@ -45,6 +45,7 @@ export interface ChannelRound1Options {
     readonly allow: readonly string[];
     readonly cwd?: string;
     readonly timeoutMs: number;
+    readonly onChildOpened?: (childId: string) => void;
 }
 export interface ChannelRound1Result {
     readonly outcome: ScanRound1Outcome;

package/lib/types/channel-port.js

@@ -0,0 +1,74 @@
+import { parseDecision } from "./decision.js";
+import { buildRound1Prompt, buildRound2Prompt, STANDBY_PROMPT } from "./prompts.js";
+export async function runRound1OverChannel(options, candidate, signal) {
+    let childId;
+    const dispose = async () => {
+        if (childId !== undefined) {
+            const id = childId;
+            childId = undefined;
+            try {
+                await options.channel.dispose(id);
+            }
+            catch { /* teardown must not replace the outcome */ }
+        }
+    };
+    const opened = await options.channel.open({
+        parent: options.parent,
+        label: 'merge-round1',
+        promptText: STANDBY_PROMPT,
+        kind: 'reviewer',
+        allow: options.allow,
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        timeoutMs: options.timeoutMs,
+        signal,
+    });
+    if (opened.kind === 'unavailable')
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: opened.code, message: opened.reason, retryable: true, retryFrom: 'agent1' } }, dispose };
+    if (opened.kind === 'aborted')
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: 'aborted', message: 'round1 aborted', retryable: false, retryFrom: 'none' } }, dispose };
+    childId = opened.childId;
+    if (opened.turn.stopReason !== 'completed') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: opened.turn.stopReason, message: 'standby did not complete', retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    try {
+        options.onChildOpened?.(opened.childId);
+    }
+    catch (error) {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: 'child-bind', message: String(error), retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    const round1 = await options.channel.continueTurn(opened.childId, buildRound1Prompt(candidate, options.cards), { timeoutMs: options.timeoutMs, signal });
+    if (round1.kind !== 'ok') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: round1.kind, message: round1.kind === 'unavailable' ? round1.reason : 'round1 aborted', retryable: round1.kind !== 'aborted', retryFrom: round1.kind === 'aborted' ? 'none' : 'agent1' } }, dispose };
+    }
+    if (round1.turn.stopReason !== 'completed') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: round1.turn.stopReason, message: 'round1 did not complete', retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    const parsed = parseDecision(round1.turn.text, candidate);
+    if (!parsed.ok) {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: parsed.code, message: parsed.message, retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    if (!parsed.decision.shouldMerge || parsed.decision.mode === 'keep') {
+        await dispose();
+        return { outcome: { kind: 'keep', decision: parsed.decision }, dispose };
+    }
+    const child = opened.childId;
+    return {
+        outcome: { kind: 'merge', decision: parsed.decision },
+        childId: child,
+        dispose,
+        async author(row, decision, turnSignal) {
+            const turn = await options.channel.continueTurn(child, buildRound2Prompt(row, decision), { timeoutMs: options.timeoutMs, signal: turnSignal });
+            if (turn.kind !== 'ok')
+                throw new Error(turn.kind === 'unavailable' ? turn.reason : 'round2 aborted');
+            if (turn.turn.stopReason !== 'completed')
+                throw new Error('round2 did not complete: ' + turn.turn.stopReason);
+            return turn.turn.text;
+        },
+    };
+}
+//# sourceMappingURL=channel-port.js.map

package/lib/types/commands.d.ts

@@ -8,6 +8,7 @@ export type MergeCliCommand = {
     readonly verb: 'pair';
     readonly a: string;
     readonly b: string;
+    readonly force?: true;
 } | {
     readonly verb: 'status';
     readonly id?: string;
@@ -23,6 +24,10 @@ export type MergeCliCommand = {
     readonly verb: 'doctor';
 } | {
     readonly verb: 'pending';
+    readonly expired?: true;
+} | {
+    readonly verb: 'candidates';
+    readonly retry?: true;
 } | {
     readonly verb: 'approve';
     readonly id: string;
@@ -33,9 +38,13 @@ export type MergeCliCommand = {
     readonly verb: 'resume';
     readonly id?: string;
     readonly clear?: string;
+    readonly retry?: true;
 } | {
     readonly verb: 'skipped';
     readonly restore?: string;
+} | {
+    readonly verb: 'discard';
+    readonly id: string;
 } | {
     readonly verb: 'undo';
     readonly target: string;

package/lib/types/commands.js

@@ -0,0 +1,79 @@
+const USAGE = 'usage: /evolution merge scan | pair [--force] <a> <b> | status [id] | report [id] | cancel [id] | runs | doctor | pending [--expired] | candidates [--retry] | approve <id> | reject <id> | resume [id] [--retry] [--clear <id>] | skipped [--restore <id>] | discard <id> | undo <target> --run <id>';
+function flags(args, allowed) {
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith('--') || token === '--force' || token === '--expired' || token === '--retry')
+            continue;
+        const name = token.slice(2);
+        if (!allowed.includes(name))
+            return { values, error: 'unknown flag: --' + name };
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith('--'))
+            return { values, error: 'missing value for --' + name };
+        values.set(name, value);
+        index += 1;
+    }
+    return { values };
+}
+function switches(args) {
+    return new Set(args.filter(token => token === '--force' || token === '--expired' || token === '--retry').map(token => token.slice(2)));
+}
+function positional(args) {
+    const filtered = args.filter(token => token !== '--force' && token !== '--expired' && token !== '--retry');
+    return filtered.filter((token, index) => !token.startsWith('--') && !(index > 0 && filtered[index - 1].startsWith('--')));
+}
+export function parseMergeCommand(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === undefined || verb === 'help' || verb === '--help' || verb === '-h')
+        return { ok: true, command: { verb: 'scan' }, help: true };
+    const pos = positional(rest);
+    const marked = switches(rest);
+    switch (verb) {
+        case 'scan': return pos.length === 0 ? { ok: true, command: { verb: 'scan' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'pair': return pos.length === 2 ? { ok: true, command: { verb: 'pair', a: pos[0], b: pos[1], ...(marked.has('force') ? { force: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'status': return pos.length <= 1 ? { ok: true, command: { verb: 'status', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'report': return pos.length <= 1 ? { ok: true, command: { verb: 'report', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'cancel': return pos.length <= 1 ? { ok: true, command: { verb: 'cancel', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'runs': return pos.length === 0 ? { ok: true, command: { verb: 'runs' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'doctor': return pos.length === 0 ? { ok: true, command: { verb: 'doctor' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'pending': return pos.length === 0 ? { ok: true, command: { verb: 'pending', ...(marked.has('expired') ? { expired: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'candidates': return pos.length === 0 ? { ok: true, command: { verb: 'candidates', ...(marked.has('retry') ? { retry: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'approve': return pos.length === 1 ? { ok: true, command: { verb: 'approve', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'reject': return pos.length === 1 ? { ok: true, command: { verb: 'reject', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'resume': {
+            const parsed = flags(rest, ['clear']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            const clear = parsed.values.get('clear');
+            if (pos.length > 1)
+                return { ok: false, code: 'usage', message: USAGE };
+            return { ok: true, command: { verb: 'resume', ...(pos[0] === undefined ? {} : { id: pos[0] }), ...(clear === undefined ? {} : { clear }), ...(marked.has('retry') ? { retry: true } : {}) } };
+        }
+        case 'skipped': {
+            const parsed = flags(rest, ['restore']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            if (pos.length > 0)
+                return { ok: false, code: 'usage', message: USAGE };
+            const restore = parsed.values.get('restore');
+            return { ok: true, command: { verb: 'skipped', ...(restore === undefined ? {} : { restore }) } };
+        }
+        case 'discard': return pos.length === 1 ? { ok: true, command: { verb: 'discard', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'undo': {
+            const parsed = flags(rest, ['run']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            const target = pos[0];
+            const run = parsed.values.get('run');
+            if (target === undefined || run === undefined || pos.length !== 1)
+                return { ok: false, code: 'usage', message: USAGE };
+            return { ok: true, command: { verb: 'undo', target, run } };
+        }
+        default: return { ok: false, code: 'usage', message: 'unknown merge command: ' + verb + '\n' + USAGE };
+    }
+}
+export function mergeUsage() {
+    return USAGE;
+}
+//# sourceMappingURL=commands.js.map

package/lib/types/commit-assembly.d.ts

@@ -9,6 +9,8 @@ import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 export interface CommitAssemblyPort {
     /** Current SKILL.md body, or null when the skill is not live. */
     readSkill(name: string): Promise<string | null>;
+    /** Whether the name is already occupied by an archived (tombstoned) skill. */
+    isArchived?(name: string): Promise<boolean>;
 }
 export interface CommitAssemblyOptions {
     readonly origin: WriteOrigin;