@birdie_moblie/open_spec 2.1.7

package/dist/core/worker.js

@@ -0,0 +1,478 @@
+import path from 'node:path';
+import { codeChangeScope, retainCodeChanges } from './code-changes.js';
+import { prepareWorkerEvidence, validateWorkerEvidence } from './worker-evidence.js';
+import { pluginBindingCurrent } from '../hooks/plugin-runtime.js';
+import { randomUUID } from 'node:crypto';
+import { exists, readJson, writeJson } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { captureDiffBaseline, changedFilesSince, parseDiffBaseline } from '../shared/git.js';
+import { effectiveTaskCategories } from '../config/schema.js';
+import { buildRepairInitContext, buildStageInitContext, buildTaskInitContext, buildVerifyHookDescriptors, fileHookState } from '../hooks/engine.js';
+import { artifactRel, requireChange } from './change.js';
+import { assertStepAllowed } from './flow.js';
+import { nextPendingTask, requireValidTaskPlan, taskProgress } from './tasks.js';
+import { appendEvent, saveState, workersDir } from './state.js';
+import { loadLedger } from './sources.js';
+import { loadVerifiedReport } from './verify.js';
+import { isOpsxInternal, resolveInside } from '../shared/paths.js';
+import { NODES, PACKET_VERSION, WorkerPacketSchema, TaskStateSchema, WorkerResultSchema, } from './types.js';
+const baselines = new Map();
+export function createWorker(projectRoot, changeName, stepId, config, options = {}) {
+    const state = requireChange(projectRoot, changeName);
+    let previous;
+    let retainedBaseline;
+    if (options.refresh && !state.activeWorker)
+        throw new AppError('no_active_worker', '刷新需要同一步骤的活动 Worker');
+    if (state.activeWorker && state.activeWorker.stepId === stepId) {
+        const existing = WorkerPacketSchema.safeParse(readJson(resolveInside(projectRoot, state.activeWorker.packet)));
+        if (!existing.success)
+            throw new AppError('invalid_worker_packet', '现有 worker packet 不合法', existing.error.issues);
+        assertPacketMatchesState(state, existing.data);
+        if (!options.refresh) {
+            prepareWorkerEvidence(projectRoot, changeName, existing.data);
+            // scout 可能在首次 create 之后才写出摘要；重派时把它暴露给 build/repair。
+            if (attachTaskContext(projectRoot, existing.data))
+                writeJson(resolveInside(projectRoot, state.activeWorker.packet), existing.data);
+            return { packet: existing.data, path: state.activeWorker.packet };
+        }
+        previous = existing.data;
+        if (isCodeChangingStep(stepId)) {
+            retainedBaseline = readBaseline(projectRoot, state, previous.workerId);
+            // Refreshing a binding must never reset the task's original diff boundary.
+            changedFilesSince(projectRoot, retainedBaseline);
+        }
+    }
+    if (state.activeWorker && !previous) {
+        throw new AppError('worker_active', `已有进行中的 worker: ${state.activeWorker.workerId}`);
+    }
+    if (state.node === NODES.COLLECT && stepId === 'parse' && state.collectedRevision >= state.sourceRevision && state.sourceRevision > 0) {
+        state.node = NODES.PARSE;
+    }
+    assertStepAllowed(state, stepId);
+    const workerId = `${stepId}-${randomUUID()}`;
+    const dir = workersDir(projectRoot, changeName);
+    const packetRel = `${artifactRel(changeName, '.opsx/workers')}/${workerId}.packet.json`;
+    const resultRel = `${artifactRel(changeName, '.opsx/workers')}/${workerId}.result.json`;
+    const packet = buildPacket(projectRoot, state, stepId, workerId, resultRel, config);
+    if (previous?.decisions)
+        packet.decisions = previous.decisions;
+    const baseline = retainedBaseline ?? (isCodeChangingStep(stepId) ? captureDiffBaseline(projectRoot) : null);
+    prepareWorkerEvidence(projectRoot, changeName, packet);
+    attachTaskContext(projectRoot, packet);
+    if (Object.keys(state.codeChanges?.filesByStep ?? {}).length)
+        packet.refs.codeChanges = artifactRel(changeName, '.opsx/code-changes.json');
+    writeJson(path.join(projectRoot, packetRel), packet);
+    if (baseline) {
+        baselines.set(baselineKey(projectRoot, workerId), baseline);
+        writeJson(path.join(dir, `${workerId}.baseline.json`), baseline);
+        state.codeChanges ??= { baseline: `${artifactRel(changeName, '.opsx/workers')}/${workerId}.baseline.json`, filesByStep: {} };
+    }
+    state.activeWorker = {
+        workerId,
+        stepId,
+        packet: packetRel,
+        expectedResult: resultRel,
+        createdAt: new Date().toISOString(),
+    };
+    if (stepId === 'parse')
+        state.node = NODES.PARSE;
+    if (stepId === 'verify')
+        state.verifyRunId = workerId;
+    saveState(projectRoot, state);
+    if (previous) {
+        baselines.delete(baselineKey(projectRoot, previous.workerId));
+        appendEvent(projectRoot, changeName, 'worker.cancelled', {
+            workerId: previous.workerId, reason: 'explicit refresh', replacementWorkerId: workerId,
+            preservedBaseline: Boolean(retainedBaseline),
+        });
+    }
+    appendEvent(projectRoot, changeName, 'worker.created', { workerId, stepId });
+    return { packet, path: packetRel };
+}
+export function acceptWorker(projectRoot, changeName, resultPath, config) {
+    const state = requireChange(projectRoot, changeName);
+    if (!state.activeWorker)
+        throw new AppError('no_active_worker', '当前没有待验收的 worker');
+    const expectedAbs = resolveInside(projectRoot, state.activeWorker.expectedResult, 'worker_result_outside_project');
+    const actualAbs = path.isAbsolute(resultPath) ? resultPath : path.join(projectRoot, resultPath);
+    if (path.resolve(expectedAbs) !== path.resolve(actualAbs)) {
+        throw new AppError('result_path_mismatch', `result 路径必须是 ${state.activeWorker.expectedResult}`);
+    }
+    if (!exists(actualAbs))
+        throw new AppError('result_missing', '找不到 worker result 文件');
+    const parsed = WorkerResultSchema.safeParse(readJson(actualAbs));
+    if (!parsed.success)
+        throw new AppError('invalid_worker_result', 'worker result 不合法', parsed.error.issues);
+    const result = parsed.data;
+    if (result.workerId !== state.activeWorker.workerId || result.stepId !== state.activeWorker.stepId) {
+        throw new AppError('result_mismatch', 'result 的 workerId/stepId 与 packet 不一致');
+    }
+    if (!['completed', 'failed', 'blocked'].includes(result.status)) {
+        throw new AppError('invalid_result_status', 'status 只能是 completed / failed / blocked');
+    }
+    const packetParsed = WorkerPacketSchema.safeParse(readJson(resolveInside(projectRoot, state.activeWorker.packet, 'worker_packet_outside_project')));
+    if (!packetParsed.success)
+        throw new AppError('invalid_worker_packet', 'worker packet 不合法', packetParsed.error.issues);
+    assertPacketMatchesState(state, packetParsed.data);
+    validateExecuteHookResults(projectRoot, packetParsed.data, result);
+    if (result.executeHookResults?.length) {
+        appendEvent(projectRoot, changeName, 'worker.execute_hooks', {
+            workerId: result.workerId,
+            results: result.executeHookResults,
+        });
+    }
+    const now = new Date().toISOString();
+    if (result.status === 'blocked') {
+        state.lastIssue = { type: 'worker_blocked', stepId: result.stepId, questions: result.questions, updatedAt: now, reason: result.notes };
+        appendEvent(projectRoot, changeName, 'worker.blocked', { workerId: result.workerId });
+        saveState(projectRoot, state);
+        return state;
+    }
+    if (result.status === 'failed') {
+        state.lastIssue = {
+            type: 'worker_failed',
+            stepId: result.stepId,
+            fixable: false,
+            reason: result.notes,
+            updatedAt: now,
+        };
+        appendEvent(projectRoot, changeName, 'worker.failed', { workerId: result.workerId });
+        saveState(projectRoot, state);
+        return state;
+    }
+    validateWorkerEvidence(projectRoot, changeName, packetParsed.data);
+    if (result.skipTech && packetParsed.data.skipTechAllowed === false)
+        throw new AppError('required_tech_command', 'required tech command 存在，不能跳过 tech');
+    const changedFiles = applyCompleted(projectRoot, state, result, config);
+    state.activeWorker = null;
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'worker.accepted', { workerId: result.workerId, stepId: result.stepId, node: state.node, changedFiles, notes: result.notes });
+    return state;
+}
+/**
+ * 记录用户对 blocked Worker 的答复：写入 packet.decisions 并清除 blocked issue。
+ * 之后 `worker create` 同一 step 会复用该 packet，Worker 按 decisions 完成产物后重新 accept。
+ */
+export function answerWorker(projectRoot, changeName, answers) {
+    const state = requireChange(projectRoot, changeName);
+    if (!state.activeWorker)
+        throw new AppError('no_active_worker', '当前没有等待答复的 worker');
+    if (state.lastIssue?.type !== 'worker_blocked') {
+        throw new AppError('worker_not_blocked', '当前 worker 不处于 blocked 状态，无需答复');
+    }
+    const cleaned = answers.map((answer) => answer.trim()).filter(Boolean);
+    if (cleaned.length === 0)
+        throw new AppError('empty_answers', '至少需要一条答复');
+    const packetAbs = resolveInside(projectRoot, state.activeWorker.packet, 'worker_packet_outside_project');
+    const parsed = WorkerPacketSchema.safeParse(readJson(packetAbs));
+    if (!parsed.success)
+        throw new AppError('invalid_worker_packet', 'worker packet 不合法', parsed.error.issues);
+    assertPacketMatchesState(state, parsed.data);
+    const decision = { questions: state.lastIssue.questions ?? [], answers: cleaned, answeredAt: new Date().toISOString() };
+    const packet = { ...parsed.data, decisions: [...(parsed.data.decisions ?? []), decision] };
+    writeJson(packetAbs, packet);
+    state.lastIssue = null;
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'worker.answered', { workerId: state.activeWorker.workerId, ...decision });
+    return { state, packet, path: state.activeWorker.packet };
+}
+export function cancelWorker(projectRoot, changeName, reason) {
+    const state = requireChange(projectRoot, changeName);
+    if (!state.activeWorker)
+        throw new AppError('no_active_worker', '当前没有可取消的 worker');
+    if (isCodeChangingStep(state.activeWorker.stepId)) {
+        const scope = codeChangeScope(projectRoot, state, state.activeWorker);
+        retainCodeChanges(projectRoot, state, state.activeWorker, scope.changedFiles, true);
+    }
+    appendEvent(projectRoot, changeName, 'worker.cancelled', { workerId: state.activeWorker.workerId, reason, retainedFiles: state.codeChanges?.filesByStep[state.activeWorker.stepId] ?? [] });
+    baselines.delete(baselineKey(projectRoot, state.activeWorker.workerId));
+    state.activeWorker = null;
+    saveState(projectRoot, state);
+    return state;
+}
+function applyCompleted(projectRoot, state, result, config) {
+    state.lastIssue = null;
+    const stepId = result.stepId;
+    if (stepId === 'parse') {
+        assertArtifact(projectRoot, state.changeName, 'spec.md');
+        if (result.skipTech) {
+            const reason = result.notes?.trim();
+            if (!reason)
+                throw new AppError('skip_tech_reason_required', 'skipTech 需要在 notes 说明满足跳过判据的理由');
+            appendEvent(projectRoot, state.changeName, 'worker.tech_skipped', { workerId: result.workerId, reason });
+        }
+        state.node = result.skipTech ? NODES.PLAN : NODES.TECH;
+        state.techSkipped = Boolean(result.skipTech);
+        return;
+    }
+    if (stepId === 'tech') {
+        assertArtifact(projectRoot, state.changeName, 'tech.md');
+        state.node = NODES.PLAN;
+        return;
+    }
+    if (stepId === 'plan') {
+        const plan = readJson(path.join(projectRoot, artifactRel(state.changeName, 'plan/task-plan.json')));
+        const categories = Object.keys(effectiveTaskCategories(config));
+        const sourceRefs = loadLedger(projectRoot, state.changeName, state.sourceRevision).items.map((item) => item.id);
+        const tasks = requireValidTaskPlan(plan, categories, sourceRefs).map((task) => TaskStateSchema.parse(task));
+        const unmapped = Object.entries(state.codeChanges?.filesByStep ?? {})
+            .filter(([step, files]) => files.length && state.codeChanges?.pendingSteps?.includes(step) && step.startsWith('code-') && !tasks.some((task) => `code-${task.id}` === step));
+        if (unmapped.length)
+            throw new AppError('retained_task_unmapped', '新计划必须保留尚需复核的任务 ID 与文件归属', { retained: Object.fromEntries(unmapped) });
+        state.tasks = tasks;
+        state.node = NODES.GATE_A;
+        if (state.sourceUpdate?.hadCompletedTasks) {
+            writeJson(path.join(projectRoot, artifactRel(state.changeName, `plan/source-reconciliation-r${state.sourceRevision}.json`)), {
+                revision: state.sourceRevision,
+                sourceIds: state.sourceUpdate.changedSourceIds,
+                completedTaskIds: state.sourceUpdate.completedTaskIds,
+            });
+        }
+        return;
+    }
+    if (stepId.startsWith('code-')) {
+        const taskId = stepId.slice('code-'.length);
+        const expectedTask = nextPendingTask(state);
+        if (!expectedTask || expectedTask.id !== taskId) {
+            throw new AppError('task_not_ready', `当前只允许执行下一个 pending task: ${expectedTask?.id ?? 'none'}`);
+        }
+        const task = state.tasks.find((item) => item.id === taskId);
+        if (!task)
+            throw new AppError('unknown_task', `找不到 task: ${taskId}`);
+        const actual = codeChangeScope(projectRoot, state, result).changedFiles;
+        const declared = [...new Set(result.changedFiles ?? [])].filter((file) => !isOpsxInternal(file)).sort();
+        if (JSON.stringify(declared) !== JSON.stringify(actual)) {
+            appendEvent(projectRoot, state.changeName, 'worker.changed_files_mismatch', {
+                workerId: result.workerId,
+                declared,
+                actual,
+            });
+            // Omitted declarations retain legacy engine-computed semantics; explicit claims must match.
+            if (result.changedFiles !== undefined)
+                throw new AppError('worker_changed_files_mismatch', '声明文件与任务累计待验收范围不一致；核对原始基线和保留文件后重新声明', { declared, actual });
+        }
+        task.status = 'completed';
+        task.completedAt = new Date().toISOString();
+        retainCodeChanges(projectRoot, state, result, actual);
+        baselines.delete(baselineKey(projectRoot, result.workerId));
+        const progress = taskProgress(state);
+        state.node = progress.completed === progress.total ? NODES.GATE_B : NODES.CODE;
+        state.verifyRunId = null;
+        return actual;
+    }
+    if (stepId === 'repair-verify') {
+        const actual = codeChangeScope(projectRoot, state, result).changedFiles;
+        const declared = [...new Set(result.changedFiles ?? [])].filter((file) => !isOpsxInternal(file)).sort();
+        if (JSON.stringify(declared) !== JSON.stringify(actual)) {
+            appendEvent(projectRoot, state.changeName, 'worker.changed_files_mismatch', {
+                workerId: result.workerId,
+                declared,
+                actual,
+            });
+            // Omitted declarations retain legacy engine-computed semantics; explicit claims must match.
+            if (result.changedFiles !== undefined)
+                throw new AppError('worker_changed_files_mismatch', '声明文件与任务累计待验收范围不一致；核对原始基线和保留文件后重新声明', { declared, actual });
+        }
+        retainCodeChanges(projectRoot, state, result, actual);
+        baselines.delete(baselineKey(projectRoot, result.workerId));
+        state.node = NODES.VERIFY;
+        state.repair = null;
+        state.verifyRunId = null;
+        return actual;
+    }
+    if (stepId === 'verify') {
+        if (!state.verifyRunId || state.verifyRunId !== result.workerId) {
+            throw new AppError('verify_run_mismatch', 'verify Worker 与当前 verify run 不一致');
+        }
+        const report = loadVerifiedReport(projectRoot, state.changeName, state.verifyRunId);
+        if (report.status === 'failed') {
+            state.lastIssue = {
+                type: 'worker_failed',
+                stepId: 'verify',
+                fixable: true,
+                reason: 'QA 未通过',
+                updatedAt: new Date().toISOString(),
+            };
+            state.node = NODES.VERIFY;
+            return;
+        }
+        state.node = NODES.GATE_C;
+        state.repair = null;
+    }
+}
+function buildPacket(projectRoot, state, stepId, workerId, expectedResult, config) {
+    const refs = {
+        spec: artifactRel(state.changeName, 'spec.md'),
+        taskPlan: artifactRel(state.changeName, 'plan/task-plan.json'),
+        sources: artifactRel(state.changeName, `sources/sources-r${state.sourceRevision}.json`),
+    };
+    if (!state.techSkipped)
+        refs.tech = artifactRel(state.changeName, 'tech.md');
+    const packet = {
+        version: PACKET_VERSION,
+        workerId,
+        stepId,
+        changeName: state.changeName,
+        node: state.node,
+        refs,
+        expectedResult,
+    };
+    const sourceCapabilities = loadLedger(projectRoot, state.changeName, state.sourceRevision).items.map((item) => item.capability);
+    if (['parse', 'tech', 'plan'].includes(stepId))
+        packet.executionEvidence = true;
+    if (stepId === 'parse') {
+        packet.skipTechAllowed = !(config.hooks ?? []).some((hook) => hook.stage === 'tech' && hook.type === 'command' && hook.required !== false && (!hook.capability || sourceCapabilities.includes(hook.capability)));
+        packet.initContext = buildStageInitContext(projectRoot, config, 'parse', sourceCapabilities);
+    }
+    if (stepId === 'tech')
+        packet.initContext = buildStageInitContext(projectRoot, config, 'tech', sourceCapabilities);
+    if (stepId === 'plan') {
+        const categories = effectiveTaskCategories(config);
+        packet.allowedCategories = Object.keys(categories);
+        packet.planNotes = planNotes(config);
+        packet.initContext = buildStageInitContext(projectRoot, config, 'plan', sourceCapabilities);
+    }
+    if (stepId.startsWith('code-')) {
+        packet.executionEvidence = true;
+        const taskId = stepId.slice('code-'.length);
+        const scheduled = state.tasks.find((item) => item.id === taskId);
+        if (!scheduled)
+            throw new AppError('unknown_task', `找不到 task: ${taskId}`);
+        packet.initContext = buildTaskInitContext(projectRoot, config, scheduled.category);
+        const plan = readJson(resolveInside(projectRoot, refs.taskPlan));
+        const tasks = requireValidTaskPlan(plan, Object.keys(effectiveTaskCategories(config)));
+        const task = tasks.find((item) => item.id === taskId);
+        if (!task)
+            throw new AppError('unknown_task', `找不到 task: ${taskId}`);
+        if (task.title !== scheduled.title || task.category !== scheduled.category || task.type !== scheduled.type
+            || JSON.stringify(task.dependsOn) !== JSON.stringify(scheduled.dependsOn)) {
+            throw new AppError('task_plan_state_mismatch', `task-plan 与已确认调度状态不一致: ${taskId}`);
+        }
+        packet.task = {
+            id: task.id,
+            title: task.title,
+            category: task.category,
+            type: task.type,
+            refScope: task.refScope,
+            dependsOn: task.dependsOn,
+            notes: task.notes,
+            designRefs: task.designRefs,
+            sourceRefs: task.sourceRefs,
+            capability: task.capability,
+            operation: task.operation,
+            provider: task.provider,
+        };
+    }
+    const designSources = loadLedger(projectRoot, state.changeName, state.sourceRevision).items
+        .filter((source) => source.capability === 'design');
+    if (designSources.length)
+        packet.refs.design = designSources.map((source) => ({
+            sourceId: source.id, kind: source.kind,
+            locator: source.kind === 'text' ? undefined : source.locator,
+            artifact: source.artifact ? artifactRel(state.changeName, source.artifact) : undefined,
+        }));
+    if (stepId === 'verify')
+        packet.verifyHooks = buildVerifyHookDescriptors(projectRoot, config);
+    if (stepId === 'repair-verify') {
+        packet.executionEvidence = true;
+        if (!state.repair)
+            throw new AppError('repair_not_requested', '当前没有 verify repair 请求');
+        packet.refs.qaReport = artifactRel(state.changeName, `.opsx/verify/${state.repair.sourceVerifyRunId}/qa-report.json`);
+        packet.initContext = buildRepairInitContext(projectRoot, config, state.tasks.filter((task) => task.status === 'completed').map((task) => task.category));
+    }
+    if (packet.executionEvidence)
+        packet.executionEvidenceVersion = 2;
+    const parsed = WorkerPacketSchema.safeParse(packet);
+    if (!parsed.success)
+        throw new AppError('invalid_worker_packet', '生成的 worker packet 不合法', parsed.error.issues);
+    return parsed.data;
+}
+/** scout 子代理写出的 task 摘要路径；按 taskId 固定，与 workerId 无关，返修与重派都能复用。 */
+export function taskContextRel(changeName, taskId) {
+    return `${artifactRel(changeName, '.opsx/workers')}/${taskId}.context.md`;
+}
+/**
+ * 摘要存在时通过 `refs.taskContext` 暴露给 build/repair；不存在则不加字段，也不做任何校验。
+ * 摘要是普通 markdown，不进 schema，避免重蹈引擎级上下文投影的复杂度。
+ */
+function attachTaskContext(projectRoot, packet) {
+    if (!packet.stepId.startsWith('code-'))
+        return false;
+    const relative = taskContextRel(packet.changeName, packet.stepId.slice('code-'.length));
+    if (packet.refs.taskContext === relative || !exists(path.join(projectRoot, relative)))
+        return false;
+    packet.refs.taskContext = relative;
+    return true;
+}
+/** 只列各分类说明；plan stage 的 hook 走 initContext descriptor 并要求回执。 */
+function planNotes(config) {
+    return Object.entries(effectiveTaskCategories(config))
+        .map(([id, value]) => `${id}: ${value.notes}`)
+        .join('\n');
+}
+function assertArtifact(projectRoot, changeName, relative) {
+    if (!exists(path.join(projectRoot, artifactRel(changeName, relative)))) {
+        throw new AppError('artifact_missing', `缺少产物: ${relative}`);
+    }
+}
+function readBaseline(projectRoot, state, workerId) {
+    const cached = baselines.get(baselineKey(projectRoot, workerId));
+    if (cached)
+        return cached;
+    const file = path.join(projectRoot, artifactRel(state.changeName, `.opsx/workers/${workerId}.baseline.json`));
+    if (!exists(file))
+        throw new AppError('worker_baseline_missing', `缺少 worker baseline: ${workerId}`);
+    return parseDiffBaseline(readJson(file));
+}
+function baselineKey(projectRoot, workerId) {
+    return `${path.resolve(projectRoot)}\0${workerId}`;
+}
+function isCodeChangingStep(stepId) {
+    return stepId.startsWith('code-') || stepId === 'repair-verify';
+}
+function assertPacketMatchesState(state, packet) {
+    if (!state.activeWorker
+        || packet.workerId !== state.activeWorker.workerId
+        || packet.stepId !== state.activeWorker.stepId
+        || packet.changeName !== state.changeName
+        || packet.expectedResult !== state.activeWorker.expectedResult) {
+        throw new AppError('worker_packet_mismatch', 'worker packet 与当前权威状态不一致');
+    }
+}
+function validateExecuteHookResults(projectRoot, packet, result) {
+    const hooks = packet.initContext?.hooks ?? [];
+    const known = new Map(hooks.map((hook) => [hook.id, hook]));
+    const seen = new Set();
+    const results = result.executeHookResults ?? [];
+    for (const hookResult of results) {
+        if (!known.has(hookResult.id))
+            throw new AppError('unknown_execute_hook_result', `result 包含未知 execute hook: ${hookResult.id}`);
+        if (seen.has(hookResult.id))
+            throw new AppError('duplicate_execute_hook_result', `result 重复 execute hook: ${hookResult.id}`);
+        seen.add(hookResult.id);
+    }
+    if (result.status !== 'completed')
+        return;
+    const byId = new Map(results.map((item) => [item.id, item]));
+    for (const hook of hooks) {
+        if (hook.plugin && byId.get(hook.id)?.status === 'passed' && !pluginBindingCurrent(projectRoot, hook.plugin)) {
+            throw new AppError('plugin_identity_changed', `插件身份已变化，重新创建 Worker: ${hook.id}`);
+        }
+        if (hook.type !== 'file' || byId.get(hook.id)?.status !== 'passed')
+            continue;
+        const state = fileHookState(projectRoot, hook.path);
+        if (state === 'missing') {
+            throw new AppError('execute_hook_file_missing', `file Hook 不存在，不能回执 passed: ${hook.id}`);
+        }
+        if (state === 'unfilled') {
+            throw new AppError('execute_hook_file_unfilled', `file Hook 仍是未填写的模板（含 openspec:fill-me 标记），不能回执 passed: ${hook.id} → ${hook.path}`);
+        }
+    }
+    const failures = hooks
+        .filter((hook) => hook.required && byId.get(hook.id)?.status !== 'passed')
+        .map((hook) => hook.id);
+    if (failures.length > 0) {
+        throw new AppError('required_execute_hooks_incomplete', `必需 execute Hook 未通过: ${failures.join(', ')}`, { hooks: failures });
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/delivery/claude-install.d.ts

@@ -0,0 +1,4 @@
+import { type ExecResult } from '../shared/exec.js';
+/** Native install is a no-op for existing registrations; upgrade and verify its actual files. */
+export declare function installClaudePlugin(projectRoot: string, selector: string, expectedRoot: string): ExecResult;
+//# sourceMappingURL=claude-install.d.ts.map

package/dist/delivery/claude-install.js

@@ -0,0 +1,44 @@
+import { realpathSync } from 'node:fs';
+import { z } from 'zod';
+import { execFile } from '../shared/exec.js';
+import { digestDirectory } from '../shared/hash.js';
+const InstalledPlugin = z.object({
+    id: z.string(), scope: z.string(), projectPath: z.string().optional(),
+    enabled: z.boolean(), installPath: z.string(),
+});
+/** Native install is a no-op for existing registrations; upgrade and verify its actual files. */
+export function installClaudePlugin(projectRoot, selector, expectedRoot) {
+    const run = (args) => execFile('claude', ['plugin', ...args], { cwd: projectRoot });
+    const installed = run(['install', selector, '--scope', 'local', '--yes']);
+    if (!installed.ok)
+        return installed;
+    const updated = run(['update', selector, '--scope', 'local', '--yes']);
+    if (!updated.ok)
+        return updated;
+    const listed = run(['list', '--json']);
+    if (!listed.ok)
+        return listed;
+    try {
+        const root = realpathSync(projectRoot);
+        const sameProject = (candidate) => {
+            try {
+                return realpathSync(candidate) === root;
+            }
+            catch {
+                return false;
+            } // Native history may retain deleted worktrees from other tasks.
+        };
+        const matches = z.array(InstalledPlugin).parse(JSON.parse(listed.stdout)).filter(item => item.id === selector && item.scope === 'local' && item.projectPath
+            && sameProject(item.projectPath));
+        if (matches.length !== 1 || !matches[0].enabled)
+            throw new Error('未找到唯一启用的 local 安装记录');
+        if (digestDirectory(matches[0].installPath) !== digestDirectory(expectedRoot)) {
+            throw new Error('原生缓存内容与固定制品不一致；确认发布版本已更新，重新升级后再验证');
+        }
+        return { ok: true, code: 0, stdout: updated.stdout, stderr: '' };
+    }
+    catch (error) {
+        return { ok: false, code: 1, stdout: '', stderr: `Claude 插件实装校验失败 (${selector}): ${String(error)}` };
+    }
+}
+//# sourceMappingURL=claude-install.js.map

package/dist/delivery/distribution.d.ts

@@ -0,0 +1,3 @@
+/** Native plugin clients receive the same runtime allowlist as npm consumers. */
+export declare function preparePluginDistribution(root: string): string;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/delivery/distribution.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { renameSync, statSync } from 'node:fs';
+import { copyPath, ensureDir, exists, listFilesRecursive, readJson, removePath } from '../shared/fs.js';
+import { digestDirectory, sha256, sha256File } from '../shared/hash.js';
+import { openspecHome } from '../marketplace/adapters.js';
+import { AppError } from '../shared/errors.js';
+import { matchPattern, resolveInside } from '../shared/paths.js';
+/** Native plugin clients receive the same runtime allowlist as npm consumers. */
+export function preparePluginDistribution(root) {
+    const manifest = readJson(path.join(root, 'package.json'));
+    const files = manifest.files.filter((file) => !file.startsWith('!'));
+    // Patterns cannot describe a reviewable native artifact; the package uses explicit paths.
+    if (files.some((file) => /[*?]/.test(file) || path.isAbsolute(file) || file.split('/').includes('..'))) {
+        throw new AppError('invalid_distribution_files', '插件分发需要明确的 package.files 路径');
+    }
+    for (const required of ['package.json', 'LICENSE'])
+        if (!files.includes(required))
+            files.push(required);
+    const contents = files.filter((file) => exists(resolveInside(root, file)));
+    const digest = sha256(contents.map((file) => {
+        const absolute = path.join(root, file);
+        return `${file}:${statSync(absolute).isDirectory() ? digestDirectory(absolute) : sha256File(absolute)}`;
+    }).join('\n'));
+    const base = path.join(openspecHome(), 'distributions');
+    const target = path.join(base, digest);
+    const temp = path.join(base, `.prepare-${randomUUID()}`);
+    ensureDir(temp);
+    try {
+        for (const file of contents)
+            copyPath(path.join(root, file), path.join(temp, file));
+        const excluded = manifest.files.filter((file) => file.startsWith('!')).map((file) => file.slice(1));
+        for (const file of listFilesRecursive(temp)) {
+            const relative = path.relative(temp, file).replaceAll('\\', '/');
+            if (excluded.some((pattern) => matchPattern(relative, pattern) || matchPattern(relative, pattern.replaceAll('/**/', '/'))))
+                removePath(file);
+        }
+        const expected = digestDirectory(temp);
+        if (exists(target)) {
+            if (digestDirectory(target) !== expected)
+                throw new AppError('distribution_changed', '已准备的插件制品被修改');
+            removePath(temp);
+        }
+        else
+            renameSync(temp, target);
+        return target;
+    }
+    catch (error) {
+        removePath(temp);
+        throw error;
+    }
+}
+//# sourceMappingURL=distribution.js.map

package/dist/delivery/skills.d.ts

@@ -0,0 +1,36 @@
+import { type WorkflowName } from '../core/types.js';
+export type HostId = 'claude' | 'codex' | 'cursor';
+export type DeliveryStatus = 'installed' | 'pending_user_action' | 'skipped_by_user' | 'failed';
+export interface DeliveryResult {
+    host: HostId;
+    status: DeliveryStatus;
+    digest: string;
+    skills: string[];
+    target: string;
+    error?: string;
+}
+export declare function deliverSkills(projectRoot: string, hosts: HostId[], mode: 'install' | 'pending' | 'skip'): DeliveryResult[];
+export declare function verifyDelivery(projectRoot: string, host: HostId): {
+    ok: boolean;
+    status: DeliveryStatus | 'missing';
+    expected: string;
+    actual: string;
+};
+export declare function digestDelivery(root: string, host: HostId): string;
+/** Entire executable artifact, excluding installation dependencies and local state. */
+export declare function digestPackage(root: string): string;
+export declare function generateInstallCli(version: string, packageName: string): string;
+export declare function writeInstallCli(projectRoot: string, version: string, packageName: string): void;
+export declare function verifyInstallCli(projectRoot: string, version: string, packageName: string): {
+    ok: boolean;
+    expected: {
+        packageName: string;
+        packageVersion: string;
+    };
+    actual: {
+        packageName?: string;
+        packageVersion?: string;
+    } | null;
+};
+export declare function isWorkflow(value: string): value is WorkflowName;
+//# sourceMappingURL=skills.d.ts.map