w workspace-cli

workspace-cli AINative 研发平台实施步骤

本文档用于指导后续代码实现。每一步都应独立提交，保持现有 v1 命令和测试通过。

当前实施和验收同时覆盖 Codex 与 Claude Code。协议、主 Agent 和 Worker 流程测试是固定门槛；真实 smoke 在对应 CLI 已安装时执行。

推荐验证命令：

env GOCACHE=/private/tmp/workspace-cli-gocache \
  GOMODCACHE=/private/tmp/workspace-cli-gomodcache \
  GOSUMDB=off \
  go test -count=1 ./...

env GOCACHE=/private/tmp/workspace-cli-gocache \
  GOMODCACHE=/private/tmp/workspace-cli-gomodcache \
  GOSUMDB=off \
  go vet ./...

git diff --check

Step 1: 文档和范围冻结

目标：把 AINative 需求方案、技术方案和实施步骤作为后续实现的依据。

涉及文件：

实施：

  1. 确认三份 AINative 文档已在 /docs 目录。
  2. README 的设计文档区加入三份文档入口。
  3. GitHub Pages 首页的设计区加入 AINative 规划入口。
  4. 运行 git diff --check。

验收：

Step 2: SQLite migration 和 store 类型

目标：新增 AINative schema，不破坏旧库。

涉及文件：

实施：

  1. 增加 migration 常量 MigrationAINativeWorkflow = "0003_ai_native_workflow"。
  2. 在 Migrate migration 列表中追加 0003。
  3. 对 requirements 增加 AINative 列：description、workflow_status、analysis_agent_id、coding_agent_id、test_agent_id、analysis_final_artifact_id、technical_final_artifact_id。
  4. 对 releases 增加 workflow_status、test_agent_id、active_test_run_id、default_test_command。
  5. 创建新表：agents、worker_pools、worker_instances、review_policies、artifacts、requirement_status_events、release_status_events、agent_jobs、agent_runs、agent_run_events、human_approval_requests、provider_permission_grants、requirement_bugs、release_test_runs、release_test_run_requirements；artifacts 使用 entity_type + entity_id 支持 requirement、release 和 release test run 级产物；human_approval_requests 包含 release_test_run_id；release_test_runs 包含 test_command、test_command_source、working_dir 和 summary_artifact_id。
  6. 插入默认 review policies。
  7. 对旧表新增的 agent/artifact/test_run ID 字段使用 service 层引用校验，并增加查询索引；不要假设 SQLite ALTER TABLE ADD COLUMN 能补外键。
  8. 增加 Go struct 和 CRUD 参数类型。

测试：

验收：

Step 3: Artifact service

目标：实现 artifact 文件写入、版本管理、hash 和 final 标记。

涉及文件：

实施：

  1. 新增 internal/artifact 包。
  2. 实现 artifact path 生成：
    • requirement artifact: work/artifacts/requirements/<req-slug>/<stage>/<artifact-type>-v<n>.md
    • release artifact: work/artifacts/releases/<release-slug>/<stage>/<artifact-type>-v<n>.md
    • release test run artifact: work/artifacts/releases/<release-slug>/test-runs/<test-run-id>/<artifact-type>-v<n>.md
  3. 实现 sha256 计算。
  4. 在 service 层新增通用 artifact 方法：CreateArtifact、ListArtifacts、GetArtifact、FinalizeArtifact；保留需求侧便捷包装 CreateRequirementArtifact、ListRequirementArtifacts、FinalizeRequirementArtifact。
  5. finalize 必须使用 DB 事务，保证同一 entity 同类 artifact 只有一个 final。

测试：

验收：

Step 4: Agent 配置命令

目标：支持配置主 Agent、分析 Agent、Coding Agent、测试 Agent。

涉及文件：

实施：

  1. 新增 workspace agent add <name>。
  2. 支持 flags：--provider、--role、--model、--system-prompt、--system-prompt-file、--sandbox、--approval-policy、--command、--disabled。
  3. 新增 agent list/show/update/remove/health。
  4. Health check：
    • Codex：执行 codex --help。
    • Claude：执行 claude --help。
  5. Health 失败只更新 health_status=unavailable，不删除配置。

测试：

验收：

Step 5: Worker pool 命令

目标：支持配置 Worker 并行度和最大数量。

涉及文件：

实施：

  1. 新增 workspace worker add <name> --role analysis|coding|testing --agent <agent>。
  2. 支持 --parallelism、--max-workers、--poll-interval-ms、--lease-seconds。
  3. 新增 worker list/show/update/enable/disable。
  4. 校验 parallelism 和 max_workers 都必须大于 0，且 parallelism 不大于 max_workers；文档和帮助说明 parallelism 限制 active job 数，max_workers 限制存活 worker instance 数。

测试：

验收：

Step 6: Job queue 和 run 记录

目标：实现可重试、可租约恢复的 SQLite job queue。

涉及文件：

实施：

  1. 新增 CreateAgentJob、ClaimAgentJob、StartAgentJob、CompleteAgentJob、FailAgentJob、RetryAgentJob、CancelAgentJob。
  2. ClaimAgentJob 使用事务原子选择 queued job 并写 lease。
  3. 新增 CreateAgentRun、CompleteAgentRun。
  4. 新增 AppendAgentRunEvent、ListRunEventsAfter、ListJobEventsAfter；AppendAgentRunEvent 使用 BEGIN IMMEDIATE 或等价写锁事务为同一 run 生成 event_seq=max+1，调用方不传序号。
  5. 新增 CreateHumanApprovalRequest、ListHumanApprovals、RespondHumanApproval。
  6. 新增 CreateProviderPermissionGrant、GetActiveProviderPermissionGrant、MarkProviderPermissionGrantUsed、ExpireProviderPermissionGrants。
  7. 支持 job status waiting_user_input，该状态不被 worker claim，用户响应后由 service 恢复为 queued、取消或保持 blocked。
  8. 实现 lease 过期恢复：RecoverExpiredJobs(now)。
  9. job_key 采用 <type>-<requirement-or-release>-<timestamp-or-counter>。

测试：

验收：

Step 7: Provider runner

目标：统一 Codex 和 Claude Code 非交互执行。

涉及文件：

实施：

  1. 定义 ProviderRunner、RunRequest、RunResult。
  2. 实现 CodexRunner.BuildCommand：
    • 默认 codex exec --json --cd <cwd> --skip-git-repo-check --sandbox workspace-write -c approval_policy="never" --output-last-message <output.json> <prompt>。
  3. Codex runner 启动前创建 work/runtime/mcp/<job-key>/codex/config.toml，配置 [mcp_servers.workspace_cli] 指向 workspace mcp serve --home <home> --capability-token <job-token>；启动时通过 -c mcp_servers.workspace_cli.command=... 和 -c mcp_servers.workspace_cli.args=[...] 注入该 MCP server，保留用户默认 CODEX_HOME 以复用真实 Codex 登录态。
  4. 实现 ClaudeRunner.BuildCommand：
    • 默认 claude -p --output-format stream-json --mcp-config <path> --permission-mode acceptEdits <prompt>。
  5. Claude runner 使用 job-scoped --mcp-config JSON；不要把 Codex 当成支持 --mcp-config。
  6. runner 输出写到 work/runtime/jobs/<job-key>/<attempt>/。
  7. runner 启动前读取同一 job 的 active provider_permission_grants；grant 未过期、scope 匹配且包含 sandbox/approval policy 时才覆盖 provider 参数，并在使用后标记 used。
  8. runner 边读取 provider stdout/stderr 边调用 AppendAgentRunEvent，至少写 run_started、provider_output、tool_call、artifact_created、approval_requested、blocked、run_completed；写入 DB event 前必须做 secret redaction。单条 provider 输出超过摘要上限时，DB event 只写摘要、原始字节数和 stdout/stderr 文件路径，完整输出只保留在 runtime raw 文件中。
  9. provider 实际启动参数保留 job token，但写入 agent_runs.command 和 provider event 前必须对 exact job token 做 [REDACTED] 替换，包含 Codex -c 内嵌 token、JSON argv 和 standalone signed capability；MCP raw tail 使用同一通用 redactor。
  10. runner 发现 provider 请求澄清或人工确认时，创建 human_approval_requests，写 approval_requested event，并把 job 标记为 waiting_user_input。
  11. 支持 fake runner，用于 daemon、watch 和 workflow 测试。
  12. daemon 把 worker Agent 的 model 传给 Codex/Claude --model，并按 inline system prompt、system prompt file、job input 顺序构造最终 prompt；文件不可读时不启动 provider。
  13. provider 启动前校验 artifact 目录和 job input 指定的 requirement/release workspace；无 workspace_path job 使用 job-attempt scoped runtime CWD，避免把包含 workspace.db 的 home 作为 workspace-write 根目录。

测试：

验收：

Step 8: Coordinator daemon

目标：启动本地 Worker pool，调度 job，并处理 heartbeat/retry。

涉及文件：

实施：

  1. 新增 workspace agent daemon start/status/stop 命令。
  2. V1 的 start 为前台运行；后台 supervisor 不在 V1 范围内。
  3. daemon 周期性读取 enabled worker pools。
  4. 按 pool parallelism claim job，且 active job 数不得超过 parallelism。
  5. 按 pool max_workers 创建或复用 worker instance，live worker 数不得超过 max_workers。
  6. 启动 provider runner，并写 worker instance heartbeat。
  7. 增加 coordinator lane：使用 agent_default_main_agent 串行 claim role=coordinator job，复用 job lease、run 记录和 retry 逻辑，但不要求用户创建 coordinator worker pool。
  8. 增加 workflow watch loop：扫描 pending_acceptance、pending_analysis、pending_development、release test bug、release stale 和 publish-in-progress，幂等创建 coordinator/analysis/development/bugfix/test rerun job。
  9. coordinator watch 覆盖 analysis_completed、development_completed、open test bug、release stale、release publish_in_progress 和非 coordinator blocked job；需求/release 按最新 status event ID、bug 按 bug ID、blocked job 按 source job ID + attempt 隔离观察代次，legacy 无事件数据使用实体+状态 fallback key。
  10. publish_in_progress 先写幂等 manual-recovery diagnostic 再生成 coordinator job；coordinator input 写入触发类型、状态事件/错误原因和不可绕过的 workflow gate，并排除 coordinator 自身 blocked job。
  11. 捕获 context cancel，优雅停止。
  12. 一轮调度串行 claim worker slot 后并发运行 provider；SQLite 状态短事务使用单一共享连接，requirement-workspace job 按 requirement 串行，release-only job 按 release 串行。

测试：

验收：

Step 9: MCP server

目标：提供 Agent 可用的结构化 workspace-cli 控制面。

涉及文件：

实施：

  1. 新增 workspace mcp serve --capability-token <token>。
  2. 实现 stdio JSON-RPC 基础协议和 tools/list、tools/call。
  3. 注册工具：req_submit、req_list、req_show、req_watch、req_assign_agents、req_update_workflow_status、req_prepare_workspace、artifact_create、artifact_list、artifact_show、artifact_finalize、job_create、job_list、job_show、job_update、job_watch、run_tail、approval_list、approval_show、approval_respond、bug_create、bug_list、bug_update、release_create、release_test_start、release_test_status、release_status、release_watch、release_integrate、release_publish。
  4. 实现 capability token 校验，token 可先采用 HMAC JSON payload。
  5. 所有工具只调用 service 层。
  6. 新增 workspace mcp health：生成短期 coordinator capability，通过同一 stdio Serve 边界调用 tools/list，校验非空结果并展示 transport/tool count/tool names；mcp serve 使用 cmd.InOrStdin()，保证 CLI 和测试共享输入边界。

测试：

验收：

Step 10: AI 主 Agent 启动

目标：让用户通过主 Agent 聊天操作 workspace-cli。

涉及文件：

实施：

  1. 新增 workspace ai start [--agent <name>]。
  2. 默认读取 agent_default_main_agent。
  3. 生成 coordinator capability token。
  4. 生成 provider 工具配置文件。
  5. 启动 Codex 或 Claude 交互会话：
    • Codex 先生成 session-scoped config.toml 审计文件，其中 [mcp_servers.workspace_cli] 指向 workspace mcp serve --home <home> --capability-token <coordinator-token>；再执行 codex --cd <session-runtime>/workspace --sandbox workspace-write --ask-for-approval on-request -c mcp_servers.workspace_cli.command=... -c mcp_servers.workspace_cli.args=[...]，不覆盖用户 CODEX_HOME，也不把包含 workspace.db 的 home 作为可写 CWD。
    • Claude 推荐 claude --mcp-config <path> --append-system-prompt-file <prompt-file>。
  6. 主 Agent system prompt 明确：用户询问进展时优先调用 req_show、req_watch、release_watch、job_watch、run_tail、approval_list；出现 pending approval 时必须向用户展示问题和可选项。
  7. 注入 WORKSPACE_CLI_HOME 和 workspace 二进制路径。

测试：

验收：

Step 11: AINative 需求提交和 Agent 分配

目标：实现新需求进入 pending_acceptance，并支持主 Agent 分配三类 Agent。

涉及文件：

实施：

  1. 新增 workspace req submit <title>。
  2. 支持 --description、--description-file、--repo、--key。
  3. 新增 SubmitRequirement service 方法：创建 requirement row、保存 description/repo scope、设置 workflow_status=pending_acceptance，但不创建 worktree。
  4. 新增 req assign-agents。
  5. 新增 PrepareRequirementWorkspace(ctx, req) service 方法：对已存在 requirement 读取绑定 repo，fetch base branch，按 feature/<req-slug> 创建缺失 worktree 和 requirement repo relation；该方法不得调用会再次 insert requirement row 的 CreateRequirement。
  6. PrepareRequirementWorkspace 幂等处理：已存在干净 worktree 时复用；缺失时创建；脏 worktree、路径冲突、feature 分支被其他 worktree 占用时返回 blocked/error，并保持 workflow_status 不变。
  7. 新增 req prepare-workspace，供主 Agent/MCP/调试使用。
  8. 分配后可推进到 pending_analysis。
  9. 每次状态变化写 requirement_status_events。

测试：

验收：

Step 12: 分析阶段 Loop

目标：生成需求设计方案、技术方案和 Review，支持终稿标记。

涉及文件：

实施：

  1. 当需求进入 pending_analysis，workflow watch loop 创建 analysis_generate job。
  2. analysis job prompt 包含需求描述、repo 范围、输出 artifact 要求。
  3. Review job prompt 包含最新方案和 review policy。
  4. Review 通过时需求进入 analysis_completed；该状态不要求用户已 finalize 终稿。
  5. Review 通过并把需求推进到 analysis_completed 后，coordinator 必须创建 artifact_finalization approval；用户选择两类终稿 artifact 后，service 在同一事务中 finalize。
  6. 新增 CLI：
    • req artifact create/list/show/finalize
    • req advance <req> pending_development
  7. 用户可以通过 approval respond 完成终稿选择，也可以先编辑 artifact 生成新版本，再用 CLI finalize 两类 artifact。
  8. 用户 finalize requirement_design 和 technical_design 后才能进入 pending_development。

测试：

验收：

Step 13: 开发阶段 Loop

目标：Coding Agent 按终稿技术方案逐步开发、逐步 Review，并复用 req finish。

涉及文件：

实施：

  1. pending_development 且两类终稿齐全时，coordinator 先调用 PrepareRequirementWorkspace。
  2. workspace 准备成功后，把需求推进到 developing 并创建 implementation_plan job。
  3. plan artifact 生成后拆分 step job。
  4. 每个 step job 在 requirement workspace 执行。
  5. 每步完成后创建 implementation_step_review job。
  6. Review 失败时创建 step fix job。
  7. 所有步骤完成后创建 implementation_report 和 implementation_review。
  8. 调用现有 FinishRequirement。
  9. stage ready 后设置 workflow_status=development_completed。
  10. implementation_blocker replan 定稿后，以新 technical design 创建独立 plan job，并让 step、Review、fix、report 全部按新 plan artifact 隔离；报告只聚合当前周期。
  11. step 或 fix result 返回 implementation_blocker.reason 时，自动创建 blocker artifact，并原子创建 continue/replan/block approval、阻塞 source job；同一次 run 重试保持幂等。

测试：

验收：

Step 14: Release 测试和 bugfix Loop

目标：测试 Agent 对 release 整体 Review 和单测，发现 bug 后回 feature 分支修复。

涉及文件：

实施：

  1. 新增共用 service 方法用于启动和查询 release test；CLI workspace release test start/status 与 MCP release_test_start/release_test_status 必须调用同一 service 方法，start 支持 --test-command <cmd>。
  2. release create 支持 --test-command <cmd> 并保存为 releases.default_test_command。
  3. release integrated 后在一个 transaction 中创建 release_test_runs 与完整 release_test_run_requirements requirement+repo+commit 快照，再创建 release_test job；有命令和缺命令路径都遵守该原子边界。test command 解析顺序为 release test start --test-command、releases.default_test_command、agent_default_test_command，并分别写入 test_command_source=explicit、release_default、agent_default。
  4. 测试 Agent 生成 entity_type=release_test_run 的 test_report artifact，并写入 release_test_runs.summary_artifact_id。
  5. 测试 Agent 必须在 test_report 中记录执行过的测试命令、命令来源、工作目录、退出码和关键输出摘要；Agent 推断并实际执行的命令写入 test_command_source=inferred。没有任何可执行测试命令时，创建关联当前 release_test_run_id 的 test_command_missing approval，test run 进入 waiting_user_input，用户补充命令后更新该 test run 的 test_command/test_command_source=user_supplied 并恢复为 queued，用户选择 block 后才标记 blocked，不能把需求推进到 testing_completed。
  6. 发现问题时先把 Agent 输出的 requirement ID/key 和 repo ID/name 解析到当前 immutable test-run snapshot；daemon 和 service/MCP 写边界都只允许单 repo 推断，多 repo 必须显式指定。MCP 必须把 created-by job 固定为 capability job 并解析它的 active run，service/store 直接路径也必须提供 matching job/run。再原子创建 requirement_bugs、把需求从 testing 退回 pending_development、写 requirement status event 和 bug_created run event；任一 event failure 回滚 bug 和 workflow。任何 provider result 解析/schema 错误都在一个 transaction 中阻塞 job/test run、失败 run 并写实时/release 诊断。
  7. Coding Agent 执行 bugfix job：
    • 调用 ReopenRequirement。
    • 修改 feature worktree。
    • 调用 FinishRequirement。
  8. bug 关闭后 release 重新 integrate，重新 test。
    • req reopen 必须原子写 AINative release stale workflow/event；retest coordinator 以 stale workflow 为权威扫描入口，并兼容旧数据中仅 legacy status stale 的 release。
  9. 无 open bug 且测试通过后，相关需求进入 testing_completed；release 先进入 testing_completed，写入 active_test_run_id=<当前 passed release_test_run> 和 release_status_events。随后发布确认流程再把 release 推进到 pending_release。
  10. release test provider 启动前和结束后逐 repo 检查 release worktree；测试前 dirty 或测试过程产生变更时，通过一个 execution-block transaction 阻塞 job/test run、写可用 run event/run failure 和 release 诊断并拒绝测试结果，不自动清理用户文件。

测试：

验收：

Step 15: 发布状态联动

目标：release publish 成功后，AINative workflow 状态同步为 released。

涉及文件：

实施：

  1. 包装现有 PublishRelease 成功路径。
  2. release 从 testing_completed 进入 pending_release 时，基于 active_test_run_id 指向的当前 passed test run 创建 release/test-run scoped publish_confirmation approval；payload 包含 test run 的 requirement+repo+commit 快照摘要；choice=confirm 自动携带 confirm=true，缺少 true confirmation 的 approve 保持 pending；approve/cancel/reject response 与 release status event、可用 run event必须在同一 transaction 中提交；用户拒绝时 release 和需求保持 pending_release，daemon 不自动重建同一 release/test run 的确认。
  3. release_publish 执行前必须校验同一 release 和当前通过的 release test run 存在 approved 且 confirm=true 的 publish_confirmation，当前 active release 的 requirement 集合、repo 集合和每个 requirement+repo 的提交与 release_test_run_requirements 快照一致，并重新执行现有 dirty guard、external commit 和测试状态 guard。
  4. active release requirements 发布成功并确认 release 代码已合并到目标默认分支 main 或 master 后，将 AINative 需求状态推进：
    • testing_completed -> pending_release
    • pending_release -> releasing
    • releasing -> released
  5. 如果 publish 失败但进入 publish-in-progress，release 进入 publish_in_progress 并写 release_status_events，需求保持 releasing。
  6. 如果 publish 因 stale 或 requirement+repo+commit 快照不一致阻塞，release 进入 stale 或回到 pending_testing 并创建 test rerun 提示。

测试：

验收：

Step 16: 状态展示、实时 watch 和人工确认

目标：让用户和主 Agent 能实时看到进度、阻塞、执行输出摘要和等待确认项。

涉及文件：

实施：

  1. req list/show 增加 AINative workflow 状态展示。
  2. job list/show 展示 attempts、lease、last_error、run 文件。
  3. 新增 job watch <job-key> [--follow]，展示 run events、heartbeat、pending approval 和最新 artifact。
  4. 新增 run tail <run-id> [--follow] [--raw] [--unsafe-unredacted]，默认展示结构化 event，--raw 读取 stdout/stderr 脱敏尾部，--unsafe-unredacted 只允许本地 CLI 显式读取未脱敏尾部。
  5. 新增 req watch <req> [--follow]，聚合需求 workflow、active jobs、最新 run event、pending approvals。
  6. 新增通用 artifact list --entity-type <requirement|release|release_test_run> --entity-id <id> 和 artifact show <artifact-id>；保留 req artifact create/list/show/finalize 作为 requirement entity 的便捷包装。
  7. 新增 approval list/show/respond，用户可以查看并响应需求澄清、发布确认、测试命令缺失等请求；respond 支持 --response-json，并提供 --final-requirement-design-artifact、--final-technical-design-artifact、--test-command、--confirm、--scope、--expires-at、--sandbox、--approval-policy 等 typed shortcut flags。
  8. 新增 release watch <release> [--follow]，聚合 release workflow、release_status_events、test run、requirement+repo+commit 快照、open bug、关联需求状态、pending approvals、最近 run events 和 test_report artifact id/path。
  9. 新增 release status <release>，展示 release workflow、test run、test_report artifact id/path、open bug 和 pending approval 摘要。
  10. README 增加 AINative 高级模式示例。
  11. docs 首页增加高级模式入口。

测试：

验收：

Step 17: 端到端 fake provider 验证

目标：在不依赖真实 Codex/Claude 的测试中跑完整 AINative 流程。

涉及文件：

实施：

  1. 建立临时 bare repo。
  2. req submit。
  3. assign fake analysis/coding/testing agents。
  4. analysis fake runner 先触发一次需求澄清 approval，job 进入 waiting_user_input。
  5. 用户 respond 澄清后，service 将原 analysis job 恢复为 queued，下一次 fake analysis run 使用补充后的需求上下文继续。
  6. analysis fake runner 生成需求设计、技术方案和 Review。
  7. 创建 artifact_finalization approval，用户选择两份终稿 artifact。
  8. service 关闭 approval 并 finalize 两类 artifact。
  9. PrepareRequirementWorkspace 创建 feature worktree，并把需求推进到 developing。
  10. development fake runner 修改 repo 文件并完成 req finish。
  11. development fake runner 输出多条 run event，job watch 可以读到执行过程。
  12. release integrate。
  13. testing fake runner 先创建 bug。
  14. bugfix fake runner reopen 并修复。
  15. release test 通过。
  16. 创建 publish_confirmation approval。
  17. 用户用 --confirm 响应发布确认。
  18. release publish。

验收：

Step 18: 真实 provider smoke

目标：在本机 Codex 可用时验证真实 provider 最小路径。

实施：

  1. 检查 codex --help。
  2. 创建临时 workspace home 和简单 repo。
  3. 配置 Codex analysis Agent。
  4. 运行一个只读 analysis job，要求只创建 artifact，不改代码。
  5. 验证 run stdout 和 artifact。

注意：

验收：

Step 19: 文档、帮助和兼容性审计

目标：实现完成前确认旧流程和新流程边界清楚。

实施：

  1. README 明确普通本地流程和 AINative 高级模式。
  2. docs/requirements-planning.md 不改写为已实现 AINative，避免误导 v1 用户。
  3. 新增 AINative 文档保持规划或已实现状态同步。
  4. 所有新增 CLI help 不承诺未完成能力。
  5. 核对 release publish dirty guard、external commit guard、publish confirmation、active release test snapshot freshness 和 publish-in-progress 重试优先级。
  6. 全量测试、vet、diff check 通过。

验收：

Step 20: 全面 Review 加固

目标：修复需求元数据、Review 策略、调度、provider 生命周期和本地安全边界的完成度缺口。

实施：

  1. 新增 migration 0005，保存验收标准、优先级及分析/开发 Review policy 绑定。
  2. 增加 Review policy CLI/MCP CRUD，并在需求分配 Agent 时校验和绑定策略。
  3. 将需求澄清中的字段和 repo 更新纳入 approval 原子事务。
  4. 允许独立配置 parallelism/max_workers，按两者最小值调度；生产 daemon 在 provider run 期间继续轮询其他 pool。
  5. heartbeat 原子刷新 worker 和 job lease，daemon 使用当前 workspace 二进制绝对路径启动 MCP。
  6. provider 成功启动后才消费 grant；所有启动后失败路径终止进程并收敛 run/job。
  7. capability 强制到期；敏感目录和文件使用 0700/0600；raw tail 严格限制单次读取字节数。
  8. 为每个批次写 Review 记录，并完成全量 test/race/vet/build、built-binary MCP 和真实 Codex smoke。

验收：

Step 21: 长期运行与双 Provider 完整性

  1. 增加 daemon 单实例持久化 lease、后台 start、真实 status/stop 和实例级 Worker 回收。
  2. 将 provider 启动后失败的 event/run/job 收敛合并为单一 store 事务，Worker 局部错误不终止 daemon。
  3. 主 Agent 改用短期 capability file，定时轮换；会话完成后撤销并删除 token。
  4. requirement priority 参与 job 排序，同时保留阶段内部步骤和 Review 顺序。
  5. 将 Claude Code 主 Agent、MCP 和 stream-json Worker 纳入正式测试与完成度 gate。

Step 22: Sandbox、Lease 与孤儿 Run 收敛

  1. daemon 和 CodexRunner 将 Worker 的所有可写 sandbox 配置规范化为当前登记 worktree 内的 workspace-write，permission grant 只读取 workspace_policy。
  2. heartbeat 同时校验未过期 lease、lease owner、Worker current job 和未过期 run-bound token；所有权丢失后取消 Provider 并由 reconciliation 收敛。
  3. migration 0010 回填历史 workspace policy，并按 job 状态收敛 orphan running run 后建立唯一索引。
  4. Block、Cancel、resume、retry、approval resume 和新 run 创建复用单 job reconciliation，原子写 run 终态事件、撤销 token 并回收 Worker。
  5. Provider workspace 逐级拒绝业务 symlink，只允许 macOS 三个固定系统路径别名，并在 Provider 请求启动前复查。

验收：

Step 23: Lease Capability 与残留所有权收敛

  1. capability 签发必须与数据库中的 active lease 在同一事务校验，expiry 严格等于 lease expiry；过期、owner 不匹配或已有 active token 时拒绝。
  2. Retry、Requeue 和 Resume 在更新前断言不存在有效 lease 或 running run；live Job 返回稳定所有权冲突错误。
  3. heartbeat 必须恰好续期一个当前 run-bound token；Provider 创建 run 前允许唯一 unbound token，其他 token 基数均整体回滚。
  4. migration 0011 与 daemon recovery 清理 queued/terminal Job 的残留 Worker/token，以及引用不存在 Job 的执行记录。
  5. active 状态聚合要求 lease 未过期，succeeded run 不写 error，reconciliation 原因只进入 terminal event。

验收：

Step 24: AI Native 开发流程文档与 GitHub Pages 专章

目标：让用户不需要阅读内部实现日志，也能从公开文档完成 AI Native 平台配置，并理解从需求提交到发布的完整运行和恢复流程。

实施：

  1. 新增 docs/ai-native-development-workflow.md，覆盖角色职责、Agent/Worker/Review policy 配置、完整状态机、分析与开发 Review Loop、release test/bugfix Loop、发布确认、实时观察、artifact、安全边界和故障恢复。
  2. 为流程指南增加 GitHub Pages layout 和文档页样式，确保 Markdown 生成可直接访问的 ai-native-development-workflow.html。
  3. 在 docs/index.html 新增独立 AI Native workflow 章节，展示角色、六阶段研发闭环、状态链、人工门禁、实时命令和安全恢复约束。
  4. README、需求方案、首页设计卡和 footer 增加流程指南入口。
  5. 对 GitHub Pages 首页执行桌面端和移动端响应式检查，修复 sticky header 下的锚点遮挡。

验收：