@birdie_moblie/open_spec 2.1.7

package/dist/core/sources.js

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import { sha256File } from '../shared/hash.js';
+import { statSync } from 'node:fs';
+import { copyPath, ensureDir, exists, listFilesRecursive, readJson, removePath, writeJson } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { collectSources } from '../hooks/engine.js';
+import { artifactPath, requireChange } from './change.js';
+import { appendEvent, saveState } from './state.js';
+import { ChangeStateSchema, NODES, SourcesLedgerSchema, } from './types.js';
+import { normalizeRel, resolveInside } from '../shared/paths.js';
+const CAPABILITIES = ['requirements', 'interfaces', 'design'];
+const BACKUP_REL = '.opsx/source-update-backup';
+const MUTABLE_ARTIFACTS = ['spec.md', 'tech.md', 'plan', 'parsed', 'reports'];
+export function addSources(projectRoot, changeName, input) {
+    const state = requireChange(projectRoot, changeName);
+    if (state.activeWorker)
+        throw new AppError('worker_active', 'active Worker 存在时不能更新 source');
+    // Validate the entire request before writing a revision or creating an update
+    // backup. An invalid append-only locator cannot be repaired by appending again.
+    for (const source of input.sources ?? []) {
+        if (!isCapability(source.capability))
+            throw new AppError('invalid_capability', `不支持的 source capability: ${source.capability}`);
+        if (source.kind !== 'file')
+            continue;
+        let file;
+        try {
+            file = resolveInside(projectRoot, source.locator, 'source_file_outside_project');
+        }
+        catch (error) {
+            if (!(error instanceof AppError))
+                throw error;
+            throw new AppError(error.code, `${error.message}；请先将获授权的文件复制到项目内，再用相对路径登记。此次未写入来源账本。`);
+        }
+        if (!exists(file) || !statSync(file).isFile())
+            throw new AppError('source_file_missing', `来源文件不存在或不是普通文件: ${source.locator}；请先创建文件，再登记。此次未写入来源账本。`);
+    }
+    const current = loadLedger(projectRoot, changeName, state.sourceRevision);
+    const pastGateA = ['code', 'gate_b', 'verify', 'gate_c', 'completed'].includes(state.node)
+        || state.gates['gate-A'].status === 'approved';
+    const updatingApprovedChange = pastGateA || Boolean(state.sourceUpdate);
+    if (pastGateA && !state.sourceUpdate) {
+        createSourceUpdateBackup(projectRoot, changeName, state);
+        const completedTaskIds = state.tasks.filter((task) => task.status === 'completed').map((task) => task.id);
+        state.sourceUpdate = {
+            fromRevision: state.sourceRevision,
+            startedAt: new Date().toISOString(),
+            previousNode: state.node,
+            hadCompletedTasks: state.tasks.some((task) => task.status === 'completed'),
+            backupPath: BACKUP_REL,
+            completedTaskIds,
+            changedSourceIds: [],
+        };
+    }
+    const items = [...current.items];
+    const addedIds = [];
+    for (const source of input.sources ?? []) {
+        // Narrowed again for the public TypeScript input type; validation above is
+        // intentionally before any source-update side effect.
+        if (!isCapability(source.capability))
+            throw new AppError('invalid_capability', `不支持的 source capability: ${source.capability}`);
+        let nextIndex = items.length + 1;
+        while (items.some((item) => item.id === `src-${nextIndex}`))
+            nextIndex += 1;
+        const id = `src-${nextIndex}`;
+        items.push({
+            id,
+            capability: source.capability,
+            kind: source.kind,
+            locator: source.locator,
+        });
+        addedIds.push(id);
+    }
+    if (items.length === 0 && !(input.notes ?? current.notes)) {
+        throw new AppError('empty_sources', '至少需要 notes 或一条 source');
+    }
+    const ledger = {
+        revision: state.sourceRevision + 1,
+        notes: input.notes ?? current.notes,
+        items,
+    };
+    writeJson(artifactPath(projectRoot, changeName, `sources/sources-r${ledger.revision}.json`), ledger);
+    state.sourceRevision = ledger.revision;
+    if (state.sourceUpdate) {
+        state.sourceUpdate.changedSourceIds = [...new Set([...state.sourceUpdate.changedSourceIds, ...addedIds])];
+    }
+    state.node = NODES.COLLECT;
+    state.tasks = updatingApprovedChange ? state.tasks.map((task) => ({ ...task, status: 'pending' })) : [];
+    state.lastIssue = null;
+    state.verifyRunId = null;
+    state.repair = null;
+    state.gates['gate-A'] = { status: 'pending' };
+    if (updatingApprovedChange) {
+        state.gates['gate-B'] = { status: 'pending' };
+        state.gates['gate-C'] = { status: 'pending' };
+    }
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'sources.updated', { revision: ledger.revision });
+    return ledger;
+}
+export function collect(projectRoot, changeName, config, options = {}) {
+    const state = requireChange(projectRoot, changeName);
+    if (state.activeWorker)
+        throw new AppError('worker_active', 'active Worker 存在时不能重新采集');
+    if (state.node !== NODES.COLLECT)
+        throw new AppError('collect_not_pending', '采集已完成；更新来源后再采集，不能回退当前阶段');
+    if (state.sourceRevision === 0)
+        throw new AppError('no_sources', '请先运行 openspec sources add');
+    const ledger = loadLedger(projectRoot, changeName, state.sourceRevision);
+    const ledgerPath = artifactPath(projectRoot, changeName, `sources/sources-r${ledger.revision}.json`);
+    const outcome = collectSources(projectRoot, changeName, config, ledger.items, {
+        refresh: options.refresh,
+        checkpoint: (sourceId, artifact, collection) => {
+            const item = ledger.items.find((source) => source.id === sourceId);
+            item.artifact = artifact;
+            item.collection = collection;
+            writeJson(ledgerPath, ledger);
+        },
+    });
+    if (outcome.deferred.length > 0) {
+        throw new AppError('sources_incomplete', `source 尚未完成采集: ${outcome.deferred.join(', ')}`, outcome);
+    }
+    const bySource = new Map(outcome.sourceArtifacts.map((item) => [item.sourceId, item.path]));
+    ledger.items = ledger.items.map(({ collection: _checkpoint, ...item }) => {
+        const artifact = bySource.get(item.id) ?? item.artifact;
+        return { ...item, artifact, ...(artifact ? { artifactSha256: sha256File(artifactPath(projectRoot, changeName, artifact)) } : {}) };
+    });
+    writeJson(artifactPath(projectRoot, changeName, `sources/sources-r${ledger.revision}.json`), ledger);
+    state.collectedRevision = state.sourceRevision;
+    state.node = NODES.PARSE;
+    state.activeWorker = null;
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'sources.collected', {
+        revision: ledger.revision,
+        artifacts: outcome.artifacts,
+        covered: outcome.covered,
+    });
+    return { ledger, ...outcome };
+}
+export function abortUpdate(projectRoot, changeName, reason) {
+    const state = requireChange(projectRoot, changeName);
+    if (!state.sourceUpdate)
+        throw new AppError('no_source_update', '当前没有可中止的 source update');
+    if (state.gates['gate-A'].status === 'approved' && state.node !== NODES.GATE_A) {
+        throw new AppError('source_update_committed', '新版 Gate-A 已通过，不能中止');
+    }
+    const from = state.sourceUpdate.fromRevision;
+    const ledger = loadLedger(projectRoot, changeName, from);
+    const backupRoot = artifactPath(projectRoot, changeName, state.sourceUpdate.backupPath);
+    const parsed = ChangeStateSchema.safeParse(readJson(resolveInside(backupRoot, 'state.json', 'source_backup_outside_change')));
+    if (!parsed.success)
+        throw new AppError('source_update_backup_invalid', 'source update backup 状态不合法', parsed.error.issues);
+    if (parsed.data.changeName !== changeName)
+        throw new AppError('source_update_backup_mismatch', 'source update backup 不属于当前 change');
+    restoreMutableArtifacts(projectRoot, changeName, backupRoot);
+    removeNewSourceRevisions(projectRoot, changeName, from);
+    removePath(backupRoot);
+    const restored = parsed.data;
+    restored.sourceUpdate = null;
+    saveState(projectRoot, restored);
+    appendEvent(projectRoot, changeName, 'source_update.aborted', { reason, revision: from });
+    return ledger;
+}
+export function commitSourceUpdate(projectRoot, state) {
+    if (!state.sourceUpdate)
+        return;
+    removePath(artifactPath(projectRoot, state.changeName, state.sourceUpdate.backupPath));
+    state.sourceUpdate = null;
+}
+export function loadLedger(projectRoot, changeName, revision) {
+    if (revision <= 0)
+        return { revision: 0, notes: '', items: [] };
+    const file = artifactPath(projectRoot, changeName, `sources/sources-r${revision}.json`);
+    if (!exists(file))
+        throw new AppError('sources_ledger_missing', `缺少 source ledger: r${revision}`);
+    const parsed = SourcesLedgerSchema.safeParse(readJson(file));
+    if (!parsed.success)
+        throw new AppError('invalid_sources_ledger', `source ledger 不合法: r${revision}`, parsed.error.issues);
+    if (parsed.data.revision !== revision)
+        throw new AppError('sources_revision_mismatch', `source ledger revision 不匹配: 期望 r${revision}`);
+    return parsed.data;
+}
+function isCapability(value) {
+    return CAPABILITIES.includes(value);
+}
+export function parseSourceArg(raw) {
+    const separator = raw.indexOf('=');
+    const capabilityRaw = separator >= 0 ? raw.slice(0, separator) : '';
+    const rest = separator >= 0 ? raw.slice(separator + 1) : undefined;
+    if (!capabilityRaw || rest === undefined || !rest) {
+        throw new AppError('invalid_source', '格式应为 capability=locator 或 capability:text=...');
+    }
+    const [capabilityPart, kindPart] = capabilityRaw.split(':');
+    const capability = capabilityPart ?? '';
+    if (!isCapability(capability))
+        throw new AppError('invalid_capability', `不支持的 capability: ${capability}`);
+    if (kindPart === 'text')
+        return { capability, kind: 'text', locator: rest };
+    if (kindPart === 'file')
+        return { capability, kind: 'file', locator: rest };
+    return { capability, kind: 'url', locator: rest };
+}
+function createSourceUpdateBackup(projectRoot, changeName, state) {
+    const backupRoot = artifactPath(projectRoot, changeName, BACKUP_REL);
+    removePath(backupRoot);
+    ensureDir(resolveInside(backupRoot, 'artifacts', 'source_backup_outside_change'));
+    writeJson(resolveInside(backupRoot, 'state.json', 'source_backup_outside_change'), state);
+    for (const relative of MUTABLE_ARTIFACTS) {
+        const source = artifactPath(projectRoot, changeName, relative);
+        if (exists(source))
+            copyPath(source, resolveInside(backupRoot, path.posix.join('artifacts', relative), 'source_backup_outside_change'));
+    }
+}
+function restoreMutableArtifacts(projectRoot, changeName, backupRoot) {
+    for (const relative of MUTABLE_ARTIFACTS) {
+        const target = artifactPath(projectRoot, changeName, relative);
+        removePath(target);
+        const backup = resolveInside(backupRoot, path.posix.join('artifacts', relative), 'source_backup_outside_change');
+        if (exists(backup))
+            copyPath(backup, target);
+    }
+}
+function removeNewSourceRevisions(projectRoot, changeName, fromRevision) {
+    const sourcesDir = artifactPath(projectRoot, changeName, 'sources');
+    for (const file of listFilesRecursive(sourcesDir)) {
+        const match = path.basename(file).match(/^sources-r(\d+)\.json$/);
+        if (match && Number(match[1]) > fromRevision)
+            removePath(file);
+    }
+}
+export function parseSourceFileArg(raw) {
+    const parsed = parseSourceArg(raw);
+    return { capability: parsed.capability, kind: 'file', locator: normalizeRel(parsed.locator) };
+}
+//# sourceMappingURL=sources.js.map

package/dist/core/state.d.ts

@@ -0,0 +1,15 @@
+import { type ChangeState, type GateId } from './types.js';
+export declare function opsxDir(projectRoot: string, changeName: string): string;
+export declare function statePath(projectRoot: string, changeName: string): string;
+export declare function eventsPath(projectRoot: string, changeName: string): string;
+export declare function workersDir(projectRoot: string, changeName: string): string;
+export declare function emptyGates(): Record<GateId, {
+    status: 'pending';
+}>;
+export declare function createState(changeName: string, now?: string): ChangeState;
+export declare function loadState(projectRoot: string, changeName: string): ChangeState;
+export declare function saveState(projectRoot: string, state: ChangeState): void;
+export declare function hasState(projectRoot: string, changeName: string): boolean;
+export declare function appendEvent(projectRoot: string, changeName: string, type: string, payload?: Record<string, unknown>): void;
+export declare function isKnownGate(value: string): value is GateId;
+//# sourceMappingURL=state.d.ts.map

package/dist/core/state.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import { appendText, exists, readJson, writeJson } from '../shared/fs.js';
+import { changeDir, OPSX_DIR, resolveInside } from '../shared/paths.js';
+import { ChangeStateSchema, GATE_IDS, NODES, STATE_VERSION } from './types.js';
+import { AppError } from '../shared/errors.js';
+export function opsxDir(projectRoot, changeName) {
+    return resolveInside(projectRoot, path.posix.join(changeDir(changeName), OPSX_DIR), 'opsx_path_outside_project');
+}
+export function statePath(projectRoot, changeName) {
+    return resolveInside(opsxDir(projectRoot, changeName), 'state.json', 'state_path_outside_change');
+}
+export function eventsPath(projectRoot, changeName) {
+    return resolveInside(opsxDir(projectRoot, changeName), 'events.jsonl', 'events_path_outside_change');
+}
+export function workersDir(projectRoot, changeName) {
+    return resolveInside(opsxDir(projectRoot, changeName), 'workers', 'workers_path_outside_change');
+}
+export function emptyGates() {
+    return {
+        'gate-A': { status: 'pending' },
+        'gate-B': { status: 'pending' },
+        'gate-C': { status: 'pending' },
+    };
+}
+export function createState(changeName, now = new Date().toISOString()) {
+    return {
+        version: STATE_VERSION,
+        changeName,
+        node: NODES.COLLECT,
+        sourceRevision: 0,
+        collectedRevision: 0,
+        gates: emptyGates(),
+        tasks: [],
+        engineChangedFiles: [],
+        activeWorker: null,
+        techSkipped: false,
+        lastIssue: null,
+        sourceUpdate: null,
+        verifyRunId: null,
+        repair: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+export function loadState(projectRoot, changeName) {
+    const result = ChangeStateSchema.safeParse(readJson(statePath(projectRoot, changeName)));
+    if (!result.success) {
+        throw new AppError('invalid_state', `change 状态不合法: ${changeName}`, result.error.issues);
+    }
+    return result.data;
+}
+export function saveState(projectRoot, state) {
+    state.updatedAt = new Date().toISOString();
+    const result = ChangeStateSchema.safeParse(state);
+    if (!result.success) {
+        throw new AppError('invalid_state', `拒绝写入不合法的 change 状态: ${state.changeName}`, result.error.issues);
+    }
+    writeJson(statePath(projectRoot, state.changeName), result.data);
+}
+export function hasState(projectRoot, changeName) {
+    return exists(statePath(projectRoot, changeName));
+}
+export function appendEvent(projectRoot, changeName, type, payload = {}) {
+    const line = JSON.stringify({
+        type,
+        at: new Date().toISOString(),
+        changeName,
+        payload,
+    });
+    appendText(eventsPath(projectRoot, changeName), `${line}\n`);
+}
+export function isKnownGate(value) {
+    return GATE_IDS.includes(value);
+}
+//# sourceMappingURL=state.js.map

package/dist/core/status.d.ts

@@ -0,0 +1,31 @@
+import type { ProjectConfig } from '../config/schema.js';
+export declare function changeStatus(projectRoot: string, changeName: string, config: ProjectConfig): {
+    next: import("./types.js").NextAction;
+    progress: {
+        total: number;
+        completed: number;
+    };
+    uiTasksWithoutDesignRefs: string[];
+    version: number;
+    changeName: string;
+    node: import("./types.js").Node;
+    sourceRevision: number;
+    collectedRevision: number;
+    gates: Record<import("./types.js").GateId, import("./types.js").GateState>;
+    tasks: import("./types.js").TaskState[];
+    engineChangedFiles: string[];
+    codeChanges?: {
+        baseline: string;
+        filesByStep: Record<string, string[]>;
+        pendingSteps?: string[];
+    };
+    activeWorker: import("./types.js").ActiveWorker | null;
+    techSkipped: boolean;
+    lastIssue: import("./types.js").LastIssue | null;
+    sourceUpdate: import("./types.js").SourceUpdate | null;
+    verifyRunId: string | null;
+    repair: import("./types.js").VerifyRepair | null;
+    createdAt: string;
+    updatedAt: string;
+};
+//# sourceMappingURL=status.d.ts.map

package/dist/core/status.js

@@ -0,0 +1,22 @@
+import { effectiveTaskCategories } from '../config/schema.js';
+import { readJson } from '../shared/fs.js';
+import { artifactPath, requireChange } from './change.js';
+import { nextAction } from './flow.js';
+import { loadLedger } from './sources.js';
+import { requireValidTaskPlan, taskProgress } from './tasks.js';
+export function changeStatus(projectRoot, changeName, config) {
+    const state = requireChange(projectRoot, changeName);
+    const hasDesign = loadLedger(projectRoot, changeName, state.sourceRevision).items.some((source) => source.capability === 'design');
+    const missing = [];
+    if (hasDesign && state.tasks.some((task) => task.category === 'ui')) {
+        // 用已确认任务分类校验计划，status 不因项目刚移除某分类而失去可读性。
+        const categories = [...new Set([...Object.keys(effectiveTaskCategories(config)), ...state.tasks.map((task) => task.category)])];
+        const tasks = requireValidTaskPlan(readJson(artifactPath(projectRoot, changeName, 'plan/task-plan.json')), categories);
+        for (const task of state.tasks.filter((item) => item.category === 'ui')) {
+            if (!tasks.find((entry) => entry.id === task.id)?.designRefs?.length)
+                missing.push(task.id);
+        }
+    }
+    return { ...state, next: nextAction(state), progress: taskProgress(state), uiTasksWithoutDesignRefs: missing };
+}
+//# sourceMappingURL=status.js.map

package/dist/core/tasks.d.ts

@@ -0,0 +1,15 @@
+import type { ChangeState, TaskState, TaskPlanTask } from './types.js';
+export declare function nextPendingTask(state: Pick<ChangeState, 'tasks'>): TaskState | undefined;
+export declare function taskProgress(state: Pick<ChangeState, 'tasks'>): {
+    total: number;
+    completed: number;
+};
+export declare function validateTaskPlan(plan: unknown, allowedCategories: string[], knownSourceRefs?: string[]): {
+    tasks: TaskPlanTask[];
+    failure: {
+        code: string;
+        failures: string[];
+    } | null;
+};
+export declare function requireValidTaskPlan(plan: unknown, allowedCategories: string[], knownSourceRefs?: string[]): TaskPlanTask[];
+//# sourceMappingURL=tasks.d.ts.map

package/dist/core/tasks.js

@@ -0,0 +1,143 @@
+import { AppError } from '../shared/errors.js';
+import { assertPathToken, normalizeRel, resolveInside } from '../shared/paths.js';
+export function nextPendingTask(state) {
+    return state.tasks.find((task) => task.status !== 'completed');
+}
+export function taskProgress(state) {
+    return {
+        total: state.tasks.length,
+        completed: state.tasks.filter((task) => task.status === 'completed').length,
+    };
+}
+export function validateTaskPlan(plan, allowedCategories, knownSourceRefs) {
+    const failures = [];
+    if (!isRecord(plan) || !Array.isArray(plan.tasks)) {
+        return { tasks: [], failure: { code: 'invalid_task_plan', failures: ['task-plan.json 必须包含 tasks[]'] } };
+    }
+    if (plan.tasks.length === 0) {
+        return { tasks: [], failure: { code: 'invalid_task_plan', failures: ['task-plan.json 至少需要一个 task'] } };
+    }
+    const categories = new Set(allowedCategories);
+    const seen = new Set();
+    const tasks = [];
+    for (const [index, raw] of plan.tasks.entries()) {
+        if (!isRecord(raw)) {
+            failures.push(`tasks[${index}] 必须是对象`);
+            continue;
+        }
+        const id = typeof raw.id === 'string' ? raw.id.trim() : '';
+        const label = id ? `Task ${id}` : `tasks[${index}]`;
+        if (!id)
+            failures.push(`${label} 需要 id`);
+        else {
+            try {
+                assertPathToken(id, `${label}.id`);
+            }
+            catch (error) {
+                failures.push(error instanceof Error ? error.message : String(error));
+            }
+            if (/^gate-/i.test(id))
+                failures.push(`Gate 不能写成 task: ${id}`);
+            else if (seen.has(id))
+                failures.push(`重复的 task id: ${id}`);
+        }
+        const title = typeof raw.title === 'string' ? raw.title.trim() : typeof raw.subject === 'string' ? raw.subject.trim() : '';
+        if (!title)
+            failures.push(`${label} 需要 title`);
+        const category = typeof raw.category === 'string' ? raw.category.trim() : '';
+        if (!category)
+            failures.push(`${label} 需要 category`);
+        else if (!categories.has(category))
+            failures.push(`${label} 的 category 不在允许集合中: ${category}`);
+        if (raw.type !== undefined && raw.type !== 'code' && raw.type !== 'interface-codegen') {
+            failures.push(`${label}.type 必须是 code 或 interface-codegen`);
+        }
+        const type = raw.type === 'interface-codegen' || category === 'api-codegen' ? 'interface-codegen' : 'code';
+        if ('contextRefs' in raw)
+            failures.push(`${label}.contextRefs 已移除，请按基线契约重新生成计划`);
+        if ('files' in raw)
+            failures.push(`${label}.files 已移除，请使用 refScope`);
+        if ('allowedDirs' in raw)
+            failures.push(`${label}.allowedDirs 已移除，请使用 refScope`);
+        const declared = asStringArray(raw.refScope, `${label}.refScope`, failures);
+        const refScope = [...new Set((declared ?? []).map(normalizeRel))];
+        for (const entry of refScope) {
+            try {
+                resolveInside('/__openspec_ref_scope__', entry, 'invalid_ref_scope');
+            }
+            catch (error) {
+                failures.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+        const dependsOn = asStringArray(raw.dependsOn, `${label}.dependsOn`, failures) ?? [];
+        for (const dep of dependsOn) {
+            if (dep === id)
+                failures.push(`${label} 不能依赖自己`);
+            else if (!seen.has(dep))
+                failures.push(`${label} dependsOn 必须指向更早的 task: ${dep}`);
+        }
+        if (type === 'interface-codegen') {
+            for (const key of ['capability', 'operation', 'provider']) {
+                if (typeof raw[key] !== 'string' || !String(raw[key]).trim()) {
+                    failures.push(`${label}.${key} 在 api-codegen 任务中必填`);
+                }
+            }
+        }
+        if (id)
+            seen.add(id);
+        let designRefs;
+        if (raw.designRefs !== undefined) {
+            if (!Array.isArray(raw.designRefs) || raw.designRefs.some((ref) => typeof ref !== 'string' || !ref.trim())) {
+                failures.push(`${label}.designRefs 必须是非空字符串组成的数组（可为空数组）`);
+            }
+            else
+                designRefs = [...new Set(raw.designRefs.map((ref) => ref.trim()))];
+        }
+        const sourceRefs = asStringArray(raw.sourceRefs, `${label}.sourceRefs`, failures);
+        if (knownSourceRefs) {
+            const known = new Set(knownSourceRefs);
+            for (const sourceRef of sourceRefs ?? []) {
+                if (!known.has(sourceRef))
+                    failures.push(`${label} 引用了未知 sourceRef: ${sourceRef}`);
+            }
+        }
+        tasks.push({
+            id,
+            designRefs,
+            title,
+            category,
+            type,
+            refScope: refScope.length > 0 ? refScope : undefined,
+            dependsOn,
+            notes: typeof raw.notes === 'string' ? raw.notes : undefined,
+            status: 'pending',
+            capability: typeof raw.capability === 'string' ? raw.capability : undefined,
+            operation: typeof raw.operation === 'string' ? raw.operation : undefined,
+            provider: typeof raw.provider === 'string' ? raw.provider : undefined,
+            sourceRefs: sourceRefs && sourceRefs.length > 0 ? sourceRefs : undefined,
+        });
+    }
+    return failures.length > 0
+        ? { tasks: [], failure: { code: 'invalid_task_plan', failures } }
+        : { tasks, failure: null };
+}
+export function requireValidTaskPlan(plan, allowedCategories, knownSourceRefs) {
+    const result = validateTaskPlan(plan, allowedCategories, knownSourceRefs);
+    if (result.failure) {
+        throw new AppError('invalid_task_plan', result.failure.failures.join('; '), result.failure);
+    }
+    return result.tasks;
+}
+function asStringArray(value, field, failures) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        failures.push(`${field} 必须是字符串数组`);
+        return null;
+    }
+    return value.map((item) => item.trim()).filter(Boolean);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=tasks.js.map

package/dist/core/todo.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { ProjectConfig } from '../config/schema.js';
+export declare const PendingWorkSchema: z.ZodObject<{
+    changeName: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        category: z.ZodString;
+        source: z.ZodEnum<{
+            code: "code";
+            worker: "worker";
+        }>;
+        file: z.ZodString;
+        line: z.ZodNumber;
+        text: z.ZodString;
+        marker: z.ZodOptional<z.ZodEnum<{
+            TODO: "TODO";
+            FIXME: "FIXME";
+        }>>;
+        workerId: z.ZodOptional<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    skippedFiles: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PendingWork = z.infer<typeof PendingWorkSchema>;
+export declare function reviewScopedFiles(config: ProjectConfig, files: string[]): string[];
+/** 只读当前 changed-set；历史 Worker 声明单独展示，不推断其已解决。 */
+export declare function collectPendingWork(projectRoot: string, changeName: string, config: ProjectConfig): PendingWork;
+export declare function renderPendingWork(pending: PendingWork): string;
+//# sourceMappingURL=todo.d.ts.map