spec-agent 1.0.4 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 
 如果你是通过 npm 公网安装并希望从零开始跑通，建议先阅读：
 
-- [`USAGE_FROM_NPM.md`](./USAGE_FROM_NPM.md)
+- `USAGE_FROM_NPM.md`（npm 网页不支持该相对链接，安装后在本地包目录查看）
 
 ## 在 Cursor 中使用
 
@@ -148,6 +148,20 @@ Options:
   --dry-run             预览交接包生成计划
 ```
 
+#### execute - v2 beta 执行状态机
+```bash
+spec-agent execute --workspace <dir> [options]
+
+Options:
+  --max-parallel <count> 最大并行运行任务数 (默认: 4)
+  --retry <count>        单任务失败后重试次数 (默认: 1)
+  --complete <ids>       标记任务完成，如: T001,T002
+  --fail <ids>           标记任务失败，如: T003
+  --error <message>      配合 --fail 写入失败原因
+  --reset                重置 run_state 后重新初始化
+  --dry-run              仅预览状态迁移，不写文件
+```
+
 ### 退出码约定（用于脚本/CI）
 
 - `scan`:
@@ -178,7 +192,7 @@ spec-agent clean --workspace <dir> [--all]
 
 ### 4. 环境变量配置
 
-| 变量 | 说明 | 默认值 |
+![1775094639360](image/README/1775094639360.png)| 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `OPENAI_API_KEY` | OpenAI API Key | - |
 | `LLM_API_KEY` | 通用 LLM API Key | - |

package/USAGE_FROM_NPM.md

@@ -155,6 +155,19 @@ spec-agent clean --workspace ./output
 spec-agent handoff --workspace ./output --target cursor --include-summaries
 ```
 
+执行状态机（v2 beta，先做实验）：
+
+```bash
+# 第一次执行：初始化 run_state 并调度首批任务
+spec-agent execute --workspace ./output --max-parallel 4
+
+# 回填执行结果：将已完成任务标记为 succeeded
+spec-agent execute --workspace ./output --complete T001,T002
+
+# 回填失败并触发重试/最终失败
+spec-agent execute --workspace ./output --fail T003 --error "compile failed"
+```
+
 ---
 
 ## 9. `--help` 使用方式

package/dist/commands/execute.d.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+interface ExecuteOptions {
+    workspace: string;
+    bundle?: string;
+    maxParallel: string;
+    retry: string;
+    complete?: string;
+    fail?: string;
+    error?: string;
+    reset?: boolean;
+    dryRun?: boolean;
+}
+export declare function executeCommand(options: ExecuteOptions, command: Command): Promise<void>;
+export {};
+//# sourceMappingURL=execute.d.ts.map

package/dist/commands/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/commands/execute.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAmDD,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAsF7F"}

package/dist/commands/execute.js

@@ -0,0 +1,298 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCommand = executeCommand;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
+const logger_1 = require("../utils/logger");
+const file_1 = require("../utils/file");
+async function executeCommand(options, command) {
+    const logger = new logger_1.Logger();
+    try {
+        const workspacePath = path.resolve(options.workspace);
+        const bundlePath = options.bundle
+            ? path.resolve(options.bundle)
+            : path.join(workspacePath, 'handoff', 'handoff_bundle.json');
+        const executionDir = path.join(workspacePath, 'execution');
+        const statePath = path.join(executionDir, 'run_state.json');
+        const reportPath = path.join(executionDir, 'execution_report.json');
+        const inboxDir = path.join(executionDir, 'inbox');
+        const handoffTasksDir = path.join(workspacePath, 'handoff', 'tasks');
+        const maxParallel = Math.max(1, parseInt(options.maxParallel || '4', 10) || 4);
+        const maxRetries = Math.max(0, parseInt(options.retry || '1', 10) || 1);
+        if (!(await (0, file_1.fileExists)(bundlePath))) {
+            logger.error(`handoff bundle not found: ${bundlePath}`);
+            logger.info('Run spec-agent handoff first.');
+            process.exit(1);
+        }
+        const bundle = await (0, file_1.readJson)(bundlePath);
+        await (0, file_1.ensureDir)(executionDir);
+        await (0, file_1.ensureDir)(inboxDir);
+        if (options.reset && await (0, file_1.fileExists)(statePath)) {
+            await fs.remove(statePath);
+            logger.warn('Existing run_state.json removed due to --reset');
+        }
+        const state = await loadOrInitState(statePath, bundlePath, workspacePath, maxParallel, maxRetries, bundle, logger);
+        applyManualTransitions(state, options, logger);
+        applyBlockedStatus(state);
+        const scheduled = scheduleRunningTasks(state, maxParallel);
+        for (const taskId of scheduled) {
+            await createInboxFile(taskId, handoffTasksDir, inboxDir);
+            state.history.push({
+                at: new Date().toISOString(),
+                action: 'scheduled',
+                taskId,
+                detail: 'Moved to running and generated inbox task file',
+            });
+        }
+        state.maxParallel = maxParallel;
+        state.updatedAt = new Date().toISOString();
+        if (!options.dryRun) {
+            await (0, file_1.writeJson)(statePath, state);
+            await (0, file_1.writeJson)(reportPath, buildExecutionReport(state));
+        }
+        const summary = summarizeState(state);
+        logger.info(`Execution workspace: ${workspacePath}`);
+        logger.info(`Bundle: ${bundlePath}`);
+        logger.info(`State: ${statePath}`);
+        logger.info(`Report: ${reportPath}`);
+        logger.info(`Status => pending:${summary.pending} running:${summary.running} succeeded:${summary.succeeded} failed:${summary.failed} blocked:${summary.blocked}`);
+        if (scheduled.length > 0) {
+            logger.success(`Scheduled ${scheduled.length} tasks: ${scheduled.join(', ')}`);
+        }
+        else {
+            logger.info('No new tasks scheduled in this round.');
+        }
+        if (options.dryRun) {
+            logger.warn('Dry run mode - state/report files were not written.');
+        }
+        logger.json({
+            status: 'success',
+            scheduled,
+            summary,
+            statePath,
+            reportPath,
+            inboxDir,
+        });
+    }
+    catch (error) {
+        const logger = new logger_1.Logger();
+        logger.error(`Execute failed: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+async function loadOrInitState(statePath, bundlePath, workspacePath, maxParallel, maxRetries, bundle, logger) {
+    if (await (0, file_1.fileExists)(statePath)) {
+        const state = await (0, file_1.readJson)(statePath);
+        reconcileStateWithBundle(state, bundle, maxRetries, logger);
+        return state;
+    }
+    const now = new Date().toISOString();
+    const tasks = {};
+    for (const task of bundle.tasks || []) {
+        tasks[task.id] = {
+            taskId: task.id,
+            name: task.name,
+            assignedAgent: task.assignedAgent || 'UNKNOWN',
+            dependencies: task.dependencies || [],
+            status: 'pending',
+            attempts: 0,
+            maxAttempts: maxRetries + 1,
+            updatedAt: now,
+        };
+    }
+    return {
+        version: '2.0.0-beta',
+        createdAt: now,
+        updatedAt: now,
+        workspace: workspacePath,
+        bundlePath,
+        maxParallel,
+        tasks,
+        history: [{ at: now, action: 'init', detail: `Initialized from ${bundlePath}` }],
+    };
+}
+function reconcileStateWithBundle(state, bundle, maxRetries, logger) {
+    const now = new Date().toISOString();
+    const existingIds = new Set(Object.keys(state.tasks));
+    let added = 0;
+    for (const task of bundle.tasks || []) {
+        if (existingIds.has(task.id)) {
+            continue;
+        }
+        state.tasks[task.id] = {
+            taskId: task.id,
+            name: task.name,
+            assignedAgent: task.assignedAgent || 'UNKNOWN',
+            dependencies: task.dependencies || [],
+            status: 'pending',
+            attempts: 0,
+            maxAttempts: maxRetries + 1,
+            updatedAt: now,
+        };
+        added++;
+    }
+    if (added > 0) {
+        logger.warn(`Detected ${added} new tasks from bundle, appended to run state`);
+        state.history.push({ at: now, action: 'reconcile', detail: `Added ${added} new tasks from bundle` });
+    }
+}
+function parseTaskIds(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map(item => item.trim())
+        .filter(Boolean);
+}
+function applyManualTransitions(state, options, logger) {
+    const now = new Date().toISOString();
+    const completeIds = parseTaskIds(options.complete);
+    const failIds = parseTaskIds(options.fail);
+    for (const taskId of completeIds) {
+        const task = state.tasks[taskId];
+        if (!task) {
+            logger.warn(`Complete ignored (task not found): ${taskId}`);
+            continue;
+        }
+        task.status = 'succeeded';
+        task.lastError = undefined;
+        task.updatedAt = now;
+        state.history.push({ at: now, action: 'complete', taskId });
+    }
+    for (const taskId of failIds) {
+        const task = state.tasks[taskId];
+        if (!task) {
+            logger.warn(`Fail ignored (task not found): ${taskId}`);
+            continue;
+        }
+        task.attempts += 1;
+        task.updatedAt = now;
+        task.lastError = options.error || 'manual failure';
+        if (task.attempts < task.maxAttempts) {
+            task.status = 'pending';
+            state.history.push({
+                at: now,
+                action: 'retry',
+                taskId,
+                detail: `attempt ${task.attempts}/${task.maxAttempts - 1}`,
+            });
+        }
+        else {
+            task.status = 'failed';
+            state.history.push({
+                at: now,
+                action: 'failed',
+                taskId,
+                detail: `attempt ${task.attempts}/${task.maxAttempts - 1}`,
+            });
+        }
+    }
+}
+function applyBlockedStatus(state) {
+    const now = new Date().toISOString();
+    for (const task of Object.values(state.tasks)) {
+        if (task.status !== 'pending')
+            continue;
+        const hasHardFailedDependency = task.dependencies.some(depId => state.tasks[depId]?.status === 'failed');
+        if (hasHardFailedDependency) {
+            task.status = 'blocked';
+            task.updatedAt = now;
+            task.lastError = 'blocked by failed dependency';
+            state.history.push({ at: now, action: 'blocked', taskId: task.taskId, detail: task.lastError });
+        }
+    }
+}
+function scheduleRunningTasks(state, maxParallel) {
+    const now = new Date().toISOString();
+    const currentRunning = Object.values(state.tasks).filter(task => task.status === 'running').length;
+    const availableSlots = Math.max(0, maxParallel - currentRunning);
+    if (availableSlots <= 0)
+        return [];
+    const ready = Object.values(state.tasks).filter(task => {
+        if (task.status !== 'pending')
+            return false;
+        if (task.dependencies.length === 0)
+            return true;
+        return task.dependencies.every(depId => state.tasks[depId]?.status === 'succeeded');
+    });
+    ready.sort((a, b) => a.taskId.localeCompare(b.taskId));
+    const picked = ready.slice(0, availableSlots);
+    for (const task of picked) {
+        task.status = 'running';
+        task.updatedAt = now;
+    }
+    return picked.map(task => task.taskId);
+}
+async function createInboxFile(taskId, handoffTasksDir, inboxDir) {
+    const source = path.join(handoffTasksDir, `${taskId}.md`);
+    const target = path.join(inboxDir, `${taskId}.md`);
+    if (await (0, file_1.fileExists)(source)) {
+        await fs.copyFile(source, target);
+        return;
+    }
+    await fs.writeFile(target, `# ${taskId}\n\nTask prompt file not found in handoff/tasks.\n`, 'utf-8');
+}
+function summarizeState(state) {
+    const summary = {
+        pending: 0,
+        running: 0,
+        succeeded: 0,
+        failed: 0,
+        blocked: 0,
+    };
+    for (const task of Object.values(state.tasks)) {
+        summary[task.status] += 1;
+    }
+    return summary;
+}
+function buildExecutionReport(state) {
+    const summary = summarizeState(state);
+    const done = summary.succeeded + summary.failed + summary.blocked;
+    const total = Object.keys(state.tasks).length;
+    const completionRate = total === 0 ? 0 : Number(((done / total) * 100).toFixed(2));
+    return {
+        version: '2.0.0-beta',
+        generatedAt: new Date().toISOString(),
+        workspace: state.workspace,
+        bundlePath: state.bundlePath,
+        maxParallel: state.maxParallel,
+        totalTasks: total,
+        summary,
+        completionRate,
+        lastEvents: state.history.slice(-30),
+    };
+}
+//# sourceMappingURL=execute.js.map

package/dist/commands/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/commands/execute.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -47,6 +47,7 @@ const status_1 = require("./commands/status");
 const clean_1 = require("./commands/clean");
 const doctor_1 = require("./commands/doctor");
 const handoff_1 = require("./commands/handoff");
+const execute_1 = require("./commands/execute");
 const program = new commander_1.Command();
 const pkgVersion = (() => {
     try {
@@ -179,5 +180,18 @@ program
     .option('--include-summaries', 'Include summary directory as required evidence')
     .option('--dry-run', 'Preview handoff generation plan')
     .action(handoff_1.handoffCommand);
+program
+    .command('execute')
+    .description('Run v2 beta execution state machine from handoff bundle')
+    .option('-w, --workspace <dir>', 'Workspace directory', '.')
+    .option('-b, --bundle <path>', 'Path to handoff_bundle.json (optional)')
+    .option('-p, --max-parallel <count>', 'Max parallel running tasks', '4')
+    .option('-r, --retry <count>', 'Retry times per task after failure', '1')
+    .option('--complete <ids>', 'Mark task IDs as completed, comma-separated')
+    .option('--fail <ids>', 'Mark task IDs as failed, comma-separated')
+    .option('--error <message>', 'Failure reason when using --fail')
+    .option('--reset', 'Reset existing run state and reinitialize from bundle')
+    .option('--dry-run', 'Preview execution transitions without writing state')
+    .action(execute_1.executeCommand);
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-agent",
-  "version": "1.0.4",
+  "version": "2.0.0",
   "description": "CLI for requirement decomposition and agent-ready planning",
   "main": "dist/index.js",
   "bin": {

package/spec-agent-implementation.md

@@ -50,6 +50,7 @@ spec-agent/
 │   │   ├── dispatch.ts        # Phase 5: 任务分配
 │   │   ├── learn.ts           # 学习积累模式
 │   │   ├── handoff.ts         # 生成多 Agent 执行交接包（v2 beta）
+│   │   ├── execute.ts         # v2 beta 执行状态机（run_state/report）
 │   │   ├── pipeline.ts        # 一键执行全流程
 │   │   ├── status.ts          # 查看工作状态
 │   │   └── clean.ts           # 清理中间文件
@@ -449,6 +450,28 @@ spec-agent handoff --workspace ./workspace --target cursor --include-summaries
 
 ---
 
+### 3.13 execute — 执行状态机（v2 beta）
+
+```bash
+# 初始化并调度首批任务
+spec-agent execute --workspace ./workspace --max-parallel 4
+
+# 回填成功
+spec-agent execute --workspace ./workspace --complete T001,T002
+
+# 回填失败（按 retry 策略进入 pending 或 failed）
+spec-agent execute --workspace ./workspace --fail T003 --error "build failed"
+```
+
+**功能**：
+
+- 从 `handoff_bundle.json` 初始化 `execution/run_state.json`
+- 按依赖与并行度调度任务进入 `running`
+- 支持手动回填任务 `succeeded/failed`
+- 产出 `execution/execution_report.json` 供实验评估
+
+---
+
 ## 四、核心类型定义
 
 ```typescript

package/src/commands/execute.ts

@@ -0,0 +1,358 @@
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { Command } from 'commander';
+import { Logger } from '../utils/logger';
+import { ensureDir, fileExists, readJson, writeJson } from '../utils/file';
+
+interface ExecuteOptions {
+  workspace: string;
+  bundle?: string;
+  maxParallel: string;
+  retry: string;
+  complete?: string;
+  fail?: string;
+  error?: string;
+  reset?: boolean;
+  dryRun?: boolean;
+}
+
+type ExecutionStatus =
+  | 'pending'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'blocked';
+
+interface BundleTask {
+  id: string;
+  name: string;
+  dependencies?: string[];
+  assignedAgent?: string;
+}
+
+interface HandoffBundle {
+  version: string;
+  createdAt: string;
+  workspace: string;
+  tasks: BundleTask[];
+}
+
+interface RunTaskState {
+  taskId: string;
+  name: string;
+  assignedAgent: string;
+  dependencies: string[];
+  status: ExecutionStatus;
+  attempts: number;
+  maxAttempts: number;
+  lastError?: string;
+  updatedAt: string;
+}
+
+interface RunState {
+  version: string;
+  createdAt: string;
+  updatedAt: string;
+  workspace: string;
+  bundlePath: string;
+  maxParallel: number;
+  tasks: Record<string, RunTaskState>;
+  history: Array<{
+    at: string;
+    action: string;
+    taskId?: string;
+    detail?: string;
+  }>;
+}
+
+export async function executeCommand(options: ExecuteOptions, command: Command): Promise<void> {
+  const logger = new Logger();
+
+  try {
+    const workspacePath = path.resolve(options.workspace);
+    const bundlePath = options.bundle
+      ? path.resolve(options.bundle)
+      : path.join(workspacePath, 'handoff', 'handoff_bundle.json');
+    const executionDir = path.join(workspacePath, 'execution');
+    const statePath = path.join(executionDir, 'run_state.json');
+    const reportPath = path.join(executionDir, 'execution_report.json');
+    const inboxDir = path.join(executionDir, 'inbox');
+    const handoffTasksDir = path.join(workspacePath, 'handoff', 'tasks');
+    const maxParallel = Math.max(1, parseInt(options.maxParallel || '4', 10) || 4);
+    const maxRetries = Math.max(0, parseInt(options.retry || '1', 10) || 1);
+
+    if (!(await fileExists(bundlePath))) {
+      logger.error(`handoff bundle not found: ${bundlePath}`);
+      logger.info('Run spec-agent handoff first.');
+      process.exit(1);
+    }
+
+    const bundle = await readJson<HandoffBundle>(bundlePath);
+    await ensureDir(executionDir);
+    await ensureDir(inboxDir);
+
+    if (options.reset && await fileExists(statePath)) {
+      await fs.remove(statePath);
+      logger.warn('Existing run_state.json removed due to --reset');
+    }
+
+    const state = await loadOrInitState(statePath, bundlePath, workspacePath, maxParallel, maxRetries, bundle, logger);
+
+    applyManualTransitions(state, options, logger);
+    applyBlockedStatus(state);
+
+    const scheduled = scheduleRunningTasks(state, maxParallel);
+    for (const taskId of scheduled) {
+      await createInboxFile(taskId, handoffTasksDir, inboxDir);
+      state.history.push({
+        at: new Date().toISOString(),
+        action: 'scheduled',
+        taskId,
+        detail: 'Moved to running and generated inbox task file',
+      });
+    }
+
+    state.maxParallel = maxParallel;
+    state.updatedAt = new Date().toISOString();
+
+    if (!options.dryRun) {
+      await writeJson(statePath, state);
+      await writeJson(reportPath, buildExecutionReport(state));
+    }
+
+    const summary = summarizeState(state);
+    logger.info(`Execution workspace: ${workspacePath}`);
+    logger.info(`Bundle: ${bundlePath}`);
+    logger.info(`State: ${statePath}`);
+    logger.info(`Report: ${reportPath}`);
+    logger.info(
+      `Status => pending:${summary.pending} running:${summary.running} succeeded:${summary.succeeded} failed:${summary.failed} blocked:${summary.blocked}`
+    );
+    if (scheduled.length > 0) {
+      logger.success(`Scheduled ${scheduled.length} tasks: ${scheduled.join(', ')}`);
+    } else {
+      logger.info('No new tasks scheduled in this round.');
+    }
+
+    if (options.dryRun) {
+      logger.warn('Dry run mode - state/report files were not written.');
+    }
+
+    logger.json({
+      status: 'success',
+      scheduled,
+      summary,
+      statePath,
+      reportPath,
+      inboxDir,
+    });
+  } catch (error) {
+    const logger = new Logger();
+    logger.error(`Execute failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+async function loadOrInitState(
+  statePath: string,
+  bundlePath: string,
+  workspacePath: string,
+  maxParallel: number,
+  maxRetries: number,
+  bundle: HandoffBundle,
+  logger: Logger
+): Promise<RunState> {
+  if (await fileExists(statePath)) {
+    const state = await readJson<RunState>(statePath);
+    reconcileStateWithBundle(state, bundle, maxRetries, logger);
+    return state;
+  }
+
+  const now = new Date().toISOString();
+  const tasks: Record<string, RunTaskState> = {};
+  for (const task of bundle.tasks || []) {
+    tasks[task.id] = {
+      taskId: task.id,
+      name: task.name,
+      assignedAgent: task.assignedAgent || 'UNKNOWN',
+      dependencies: task.dependencies || [],
+      status: 'pending',
+      attempts: 0,
+      maxAttempts: maxRetries + 1,
+      updatedAt: now,
+    };
+  }
+
+  return {
+    version: '2.0.0-beta',
+    createdAt: now,
+    updatedAt: now,
+    workspace: workspacePath,
+    bundlePath,
+    maxParallel,
+    tasks,
+    history: [{ at: now, action: 'init', detail: `Initialized from ${bundlePath}` }],
+  };
+}
+
+function reconcileStateWithBundle(
+  state: RunState,
+  bundle: HandoffBundle,
+  maxRetries: number,
+  logger: Logger
+): void {
+  const now = new Date().toISOString();
+  const existingIds = new Set(Object.keys(state.tasks));
+  let added = 0;
+  for (const task of bundle.tasks || []) {
+    if (existingIds.has(task.id)) {
+      continue;
+    }
+    state.tasks[task.id] = {
+      taskId: task.id,
+      name: task.name,
+      assignedAgent: task.assignedAgent || 'UNKNOWN',
+      dependencies: task.dependencies || [],
+      status: 'pending',
+      attempts: 0,
+      maxAttempts: maxRetries + 1,
+      updatedAt: now,
+    };
+    added++;
+  }
+  if (added > 0) {
+    logger.warn(`Detected ${added} new tasks from bundle, appended to run state`);
+    state.history.push({ at: now, action: 'reconcile', detail: `Added ${added} new tasks from bundle` });
+  }
+}
+
+function parseTaskIds(raw?: string): string[] {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function applyManualTransitions(state: RunState, options: ExecuteOptions, logger: Logger): void {
+  const now = new Date().toISOString();
+  const completeIds = parseTaskIds(options.complete);
+  const failIds = parseTaskIds(options.fail);
+
+  for (const taskId of completeIds) {
+    const task = state.tasks[taskId];
+    if (!task) {
+      logger.warn(`Complete ignored (task not found): ${taskId}`);
+      continue;
+    }
+    task.status = 'succeeded';
+    task.lastError = undefined;
+    task.updatedAt = now;
+    state.history.push({ at: now, action: 'complete', taskId });
+  }
+
+  for (const taskId of failIds) {
+    const task = state.tasks[taskId];
+    if (!task) {
+      logger.warn(`Fail ignored (task not found): ${taskId}`);
+      continue;
+    }
+    task.attempts += 1;
+    task.updatedAt = now;
+    task.lastError = options.error || 'manual failure';
+    if (task.attempts < task.maxAttempts) {
+      task.status = 'pending';
+      state.history.push({
+        at: now,
+        action: 'retry',
+        taskId,
+        detail: `attempt ${task.attempts}/${task.maxAttempts - 1}`,
+      });
+    } else {
+      task.status = 'failed';
+      state.history.push({
+        at: now,
+        action: 'failed',
+        taskId,
+        detail: `attempt ${task.attempts}/${task.maxAttempts - 1}`,
+      });
+    }
+  }
+}
+
+function applyBlockedStatus(state: RunState): void {
+  const now = new Date().toISOString();
+  for (const task of Object.values(state.tasks)) {
+    if (task.status !== 'pending') continue;
+    const hasHardFailedDependency = task.dependencies.some(depId => state.tasks[depId]?.status === 'failed');
+    if (hasHardFailedDependency) {
+      task.status = 'blocked';
+      task.updatedAt = now;
+      task.lastError = 'blocked by failed dependency';
+      state.history.push({ at: now, action: 'blocked', taskId: task.taskId, detail: task.lastError });
+    }
+  }
+}
+
+function scheduleRunningTasks(state: RunState, maxParallel: number): string[] {
+  const now = new Date().toISOString();
+  const currentRunning = Object.values(state.tasks).filter(task => task.status === 'running').length;
+  const availableSlots = Math.max(0, maxParallel - currentRunning);
+  if (availableSlots <= 0) return [];
+
+  const ready = Object.values(state.tasks).filter(task => {
+    if (task.status !== 'pending') return false;
+    if (task.dependencies.length === 0) return true;
+    return task.dependencies.every(depId => state.tasks[depId]?.status === 'succeeded');
+  });
+
+  ready.sort((a, b) => a.taskId.localeCompare(b.taskId));
+  const picked = ready.slice(0, availableSlots);
+  for (const task of picked) {
+    task.status = 'running';
+    task.updatedAt = now;
+  }
+  return picked.map(task => task.taskId);
+}
+
+async function createInboxFile(taskId: string, handoffTasksDir: string, inboxDir: string): Promise<void> {
+  const source = path.join(handoffTasksDir, `${taskId}.md`);
+  const target = path.join(inboxDir, `${taskId}.md`);
+  if (await fileExists(source)) {
+    await fs.copyFile(source, target);
+    return;
+  }
+  await fs.writeFile(target, `# ${taskId}\n\nTask prompt file not found in handoff/tasks.\n`, 'utf-8');
+}
+
+function summarizeState(state: RunState): Record<ExecutionStatus, number> {
+  const summary: Record<ExecutionStatus, number> = {
+    pending: 0,
+    running: 0,
+    succeeded: 0,
+    failed: 0,
+    blocked: 0,
+  };
+  for (const task of Object.values(state.tasks)) {
+    summary[task.status] += 1;
+  }
+  return summary;
+}
+
+function buildExecutionReport(state: RunState): Record<string, unknown> {
+  const summary = summarizeState(state);
+  const done = summary.succeeded + summary.failed + summary.blocked;
+  const total = Object.keys(state.tasks).length;
+  const completionRate = total === 0 ? 0 : Number(((done / total) * 100).toFixed(2));
+  return {
+    version: '2.0.0-beta',
+    generatedAt: new Date().toISOString(),
+    workspace: state.workspace,
+    bundlePath: state.bundlePath,
+    maxParallel: state.maxParallel,
+    totalTasks: total,
+    summary,
+    completionRate,
+    lastEvents: state.history.slice(-30),
+  };
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import { statusCommand } from './commands/status';
 import { cleanCommand } from './commands/clean';
 import { doctorCommand } from './commands/doctor';
 import { handoffCommand } from './commands/handoff';
+import { executeCommand } from './commands/execute';
 
 const program = new Command();
 const pkgVersion = (() => {
@@ -158,4 +159,18 @@ program
   .option('--dry-run', 'Preview handoff generation plan')
   .action(handoffCommand);
 
+program
+  .command('execute')
+  .description('Run v2 beta execution state machine from handoff bundle')
+  .option('-w, --workspace <dir>', 'Workspace directory', '.')
+  .option('-b, --bundle <path>', 'Path to handoff_bundle.json (optional)')
+  .option('-p, --max-parallel <count>', 'Max parallel running tasks', '4')
+  .option('-r, --retry <count>', 'Retry times per task after failure', '1')
+  .option('--complete <ids>', 'Mark task IDs as completed, comma-separated')
+  .option('--fail <ids>', 'Mark task IDs as failed, comma-separated')
+  .option('--error <message>', 'Failure reason when using --fail')
+  .option('--reset', 'Reset existing run state and reinitialize from bundle')
+  .option('--dry-run', 'Preview execution transitions without writing state')
+  .action(executeCommand);
+
 program.parse();