ccgx-workflow 2.4.1 → 2.5.0

package/templates/commands/autonomous.md

@@ -1,7 +1,7 @@
 ---
 name: ccg:autonomous
-description: 跨 phase 自治长跑：roadmap → wave 并行（默认）spawn phase-runner，仅 blocker 暂停
-argument-hint: "[--from N] [--to N] [--only N] [--quality=fast|triple|debate] [--interactive] [--offload] [--sequential] [--max-concurrent N]"
+description: 跨 phase 自治长跑：roadmap → 原生 Workflow 串行编排（默认，后台运行 + 断点恢复），--legacy 降级 wave 并行 prompt 轮转
+argument-hint: "[--from N] [--to N] [--only N] [--legacy] [--resume [job-id]] [--quality=fast|triple|debate] [--interactive] [--offload] [--sequential] [--max-concurrent N] [--nested=on|off]"
 context_budget: orchestrator-15
 subagent_freshness: required
 allowed-tools:
@@ -15,6 +15,7 @@ allowed-tools:
   - Task
   - Agent
   - TodoWrite
+  - Workflow
 ---
 <!-- CCG:AUTONOMOUS:START -->
 
@@ -22,20 +23,26 @@ allowed-tools:
 
 ## 职能定位
 
-`/ccg:autonomous` 是**编排层之上的编排层**：读 `.ccg/roadmap.md` 一次性跑完整个 milestone 的所有 phase，每个 phase 内部委托给 `/ccg:team`（或 `/ccg:spec-impl`）完成 8 阶段流程，仅在 blocker / 灰区接受 / 用户决策点暂停。
+`/ccg:autonomous` 是**编排层之上的编排层**：读 `.ccg/roadmap.md` 一次性跑完整个 milestone 的所有 phase，仅在 blocker / 灰区接受 / 用户决策点暂停。
 
-> **调度模型**：默认采用 **wave 并行**。
-> autonomous 用 Kahn 拓扑排序把 EXEC_QUEUE 划分成 wave，wave 内 phase 一次性并行
-> spawn `Agent(phase-runner)`（max-concurrent 默认 4），wave 之间顺序执行——这与
-> `team-exec` wave 调度心智模型对齐，墙钟时间通常压缩 30-40%。
-> 顺序串行行为通过 `--sequential` flag 保留作为调试 / API 限额场景的降级路径。
+> **调度模型**：默认采用**原生 Workflow 串行编排**。
+> 主线把 roadmap 解析成依赖正确的串行 phase 序，烘焙成一个 Workflow JS 脚本
+> （`for` 循环逐 phase `await agent(...)` 调 phase-runner），交给 `Workflow` 工具
+> **后台运行**——transcript 由引擎托管、不占主线内存；主线 turn end 等
+> task-notification，醒来只消费 ≤200 token 结构化摘要。中断 / 失败后
+> `/ccg:autonomous --resume [job-id]` 以 `resumeFromRunId` 断点恢复：已完成
+> phase 的 `agent()` 调用命中缓存直接重放，不重跑。
+>
+> 旧 **wave 并行 prompt 轮转协议**整体保留为降级路径（见文末附录 A）：
+> `--legacy` 显式启用；`Workflow` 工具不可用时自动降级并明示原因。
+> workflow 模式适合无人值守长跑；强交互场景用 `--legacy --interactive`。
 
 **与 `/ccg:team` 的边界**：
 
 | 维度 | `/ccg:team` | `/ccg:autonomous` |
 |------|-------------|-------------------|
 | 范围 | 单个任务的 8 阶段全流程 | 多个 phase 顺序串联 |
-| 调用对象 | 直接 spawn Architect / Dev / QA / Reviewer | 调用 `/ccg:team` 或 `/ccg:spec-impl` |
+| 调用对象 | 直接 spawn Architect / Dev / QA / Reviewer | Workflow 串行调 phase-runner（legacy：`/ccg:team` 或 `/ccg:spec-impl`） |
 | 状态文件 | `.ccg/state.md`（任务 wave 维度） | `.ccg/roadmap.md`（phase 维度） |
 | 暂停条件 | Critical 未修、Phase 6 之后用户确认 | blocker / 灰区 / 跨 phase 依赖断裂 |
 | 适合 | 一次性完整开发任务 | 长程 milestone（重构、迁移、多阶段功能） |
@@ -64,7 +71,7 @@ allowed-tools:
 ## 前置条件
 
 1. **`.ccg/roadmap.md` 必须存在**。若不存在，autonomous 第一步引导用户创建（见 Step 1）。
-2. **Agent Teams 已启用**（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`），因为内部要调 `/ccg:team`。
+2. **phase-runner agent 已安装**（`~/.claude/agents/ccg/phase-runner.md`，CCG 标准安装自带）。legacy 路径另需 Agent Teams 已启用（`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`），因为内部要调 `/ccg:team`。
 3. **WORKDIR**：通过 Bash `pwd`（Unix）或 `cd`（Windows）获取当前工作目录绝对路径，禁止从 `$HOME` 推断。
 
 ---
@@ -103,17 +110,20 @@ allowed-tools:
 | `--to N` 提供 | 跑到 Phase N 结束，含 N，不推进 N+1 |
 | 都未提供 | 从第一个非 `completed` phase 开始，跑到末尾 |
 | 同时给 `--only` 和 `--from`/`--to` | `--only` 优先，其余忽略并提示 |
-| `--interactive` | 每个 phase 内的 plan 阶段保留与用户问答（不自动判定灰区） |
-| `--offload` | **重型 phase 自动外包给 codex plugin**（fresh context + 后台 + 主线只 poll status），默认开启自动判定，flag 显式时强制开启 |
-| `--sequential` | **降级为顺序串行**：禁用 wave 并行，单 phase 一波顺序串跑。调试 / API 限额场景使用 |
-| `--max-concurrent N` | 单 wave 内最大并发 phase 数，默认 4。`--max-concurrent 1` 等价 `--sequential` |
-| `--quality=fast\|triple\|debate` | 单 phase 内的质量档分级。`fast`=单波 + 1 路 verify；`triple`=Plan-Critic-Verify 4 wave（**默认**）；`debate`=triple + codex↔gemini 多轮对辩。详见 Step 4.0 |
-| `--nested=on\|off` | phase-runner 是否启用 nested rescue 委派（CLI 子进程内 spawn `codex:codex-rescue` / `gemini:gemini-rescue` 委派代码改动）。默认 `off` 保守。phase frontmatter `nested_rescue: true\|false` 优先级更高。详见 Step 4.0c |
+| `--legacy` | **强制走附录 A** 旧 wave 并行 prompt 轮转协议。`--quality` / `--offload` / `--sequential` / `--max-concurrent` / `--nested` / `--interactive` 仅 legacy 路径生效——workflow 模式下给出任一即提示并默认转 `--legacy` |
+| `--resume [job-id]` | 断点恢复 workflow 模式 job（缺省取最近未完成的 workflow job），详见 Step 4.7 |
+| `--interactive` | 每个 phase 内的 plan 阶段保留与用户问答（不自动判定灰区）。**仅 legacy 路径**（后台 workflow 无法问答） |
+| `--offload` | **重型 phase 自动外包给 codex plugin**（fresh context + 后台 + 主线只 poll status），默认开启自动判定，flag 显式时强制开启。**仅 legacy 路径** |
+| `--sequential` | **降级为顺序串行**：禁用 wave 并行，单 phase 一波顺序串跑。调试 / API 限额场景使用。**仅 legacy 路径**（workflow 模式本身就是串行） |
+| `--max-concurrent N` | 单 wave 内最大并发 phase 数，默认 4。`--max-concurrent 1` 等价 `--sequential`。**仅 legacy 路径** |
+| `--quality=fast\|triple\|debate` | 单 phase 内的质量档分级。`fast`=单波 + 1 路 verify；`triple`=Plan-Critic-Verify 4 wave（**默认**）；`debate`=triple + codex↔gemini 多轮对辩。**仅 legacy 路径**，详见附录 A Step 4.0a |
+| `--nested=on\|off` | phase-runner 是否启用 nested rescue 委派（CLI 子进程内 spawn `codex:codex-rescue` / `gemini:gemini-rescue` 委派代码改动）。默认 `off` 保守。phase frontmatter `nested_rescue: true\|false` 优先级更高。**仅 legacy 路径**，详见附录 A Step 4.0c |
 
 附加规则：
 - 状态已是 `completed` 的 phase 默认跳过（除非 `--only N` 强制重跑）
 - 状态为 `failed` 的 phase 进入队列时询问用户：重跑 / 跳过 / 终止
 - `EXEC_QUEUE` 为空 → 输出"所有 phase 已完成 ✅"并退出
+- `--resume` 提供时跳过 Step 2/3 的队列重建与确认，直接进 Step 4.7（队列以已落盘的 workflow.mjs 为准）
 
 ### Step 3: 用户确认
 
@@ -127,18 +137,398 @@ allowed-tools:
 - Phase 3: 前端登录页（依赖 Phase 2）
 - Phase 4: SSO 集成（依赖 Phase 3）
 
-预计调用：
-- /ccg:team × 3（每个 phase 一次完整 8 阶段）
-- 暂停条件：Critical 未修 / 用户决策点 / 跨 phase 依赖断裂
+调度引擎：workflow（原生 Workflow 串行编排，后台运行） | legacy（附录 A prompt 轮转）
+预计调用：phase-runner × N（workflow 串行）/ /ccg:team × N（legacy）
+暂停条件：Critical 未修 / 用户决策点 / 跨 phase 依赖断裂
 
-模式：<auto | interactive>
+模式：<auto | interactive (legacy)>
 
 确认开始？
 ```
 
-`--interactive` 模式下，每个 phase 的 plan 阶段保留与用户问答（不自动判定灰区），其余阶段照常自治。
+`--legacy --interactive` 模式下，每个 phase 的 plan 阶段保留与用户问答（不自动判定灰区），其余阶段照常自治。
 
-### Step 4: Phase 主循环（wave 并行 + 质量档分级）
+### Step 4: Workflow 原生编排（默认路径）
+
+> **Workflow 工具调用面防御原则**：Workflow 工具的参数名 / 脚本传入方式
+> （script 内容 vs scriptPath）/ runId 返回字段 / 结果读取方式，一律**以运行时
+> 工具 schema 实际字段为准，禁猜参数名**。沿用 phase-runner 的 ground-truth
+> 先验协议：不确定的接口面先看工具 schema，再下手。
+
+#### 4.1 可用性判定
+
+1. 检查当前会话**工具清单**是否含 `Workflow` 工具：
+   - 含且未给 `--legacy` → 走本 Step 4
+   - 不含 → 输出 `⚠ Workflow 工具不可用，降级 prompt 轮转协议（附录 A）` → 走附录 A
+   - 给了 `--legacy` → 直接走附录 A（不输出降级警告）
+2. EXEC_QUEUE 含任何 `opsx://` phase → **workflow 模式不支持**（`/ccg:spec-impl` 是命令不是 agent，无法经 `agent()` 调用）。提示用户二选一，不静默吞掉：
+   - 整体 `--legacy` 走附录 A
+   - 用 `--only` / `--from/--to` 把 opsx phase 拆出来单独跑
+3. 给了 `--quality` / `--offload` / `--sequential` / `--max-concurrent` / `--nested` / `--interactive` 任一 → 这些 flag 仅 legacy 路径生效，提示用户并**默认转 `--legacy`**。
+
+#### 4.2 串行序
+
+主线按 `wave-scheduler` + `workflow-autonomous` 的算法语义**手算**串行序（权威路径）。`~/.claude/.ccg/dist/index.mjs` 通常不存在——installer 当前不安装 dist，不要依赖 `node -e` 调它；仓库 `src/utils/wave-scheduler.ts` / `src/utils/workflow-autonomous.ts` 的 `parseRoadmap / schedule / flattenWaves` 是下列伪码的设计真相源：
+
+```
+phases       = parseRoadmap(<roadmap.md 内容>)
+sched        = schedule(phases, { skipCompleted: true })
+serial       = flattenWaves(sched)      # waves 按序展平 = 依赖正确的串行 phase id 序
+SERIAL_QUEUE = serial ∩ EXEC_QUEUE      # 与 Step 2 flag 过滤结果取交集（保持 serial 顺序）
+```
+
+- `sched.skipped`（cascade-skip）的 phase 照旧在 roadmap.md 写 `skipped (cascade from Phase X)` 备注后从队列排除
+- `SERIAL_QUEUE` 为空 → 输出"无可执行 phase"并退出
+
+#### 4.3 phase prompt 烘焙
+
+对 SERIAL_QUEUE 每个 phase 生成 phase-runner YAML 契约 prompt（字段语义见 `~/.claude/agents/ccg/phase-runner.md` 输入契约）。**只放 immutable 字段**——roadmap status / 进度时间戳等可变内容一律排除，保证 `--resume` 时脚本字面量不漂移、`agent()` 缓存可命中：
+
+```yaml
+phase_id: phase-<N>-<slug>
+phase_n: <N>
+phase_name: <从 roadmap.md 标题提取>
+phase_type: <读 `- **Type**:` 行；缺省 generic>
+phase_goal: |
+  <Goal 段全文>
+phase_acceptance: |
+  <Acceptance 段全文>
+phase_depends_on: <依赖 phase 列表 + 它们的产物路径>
+workdir: <WORKDIR>
+baseline_sha: <启动时最近 baseline commit sha7>
+report_path: .claude/team-plan/phase-<N>-<slug>-report.md
+commit_prefix: feat(<milestone>-p<N>):
+job_id: <job-id>
+summary_format: json
+checkpoint_path: .context/jobs/<job-id>/checkpoints/phase-<id>.json
+cancel_flag_path: .context/jobs/<job-id>/cancel.flag
+progress_log: .context/jobs/<job-id>/progress.jsonl
+```
+
+prompt 尾部追加三条运行时指令（phase-runner 侧契约见其 "Workflow 编排模式" 段）：
+
+1. 开工前 Read `cancel_flag_path`：存在 → 按 PHASE_SUMMARY_SCHEMA 返回**全 7 字段**，`status='failed'`、`notes='cancel-flag-detected'`（完整样本见 phase-runner.md "Workflow 编排模式" 段的 cancel 示例），不做任何改动
+2. 开工前 Read `checkpoint_path`：存在且 `status=completed` → **原样返回其内容**（幂等重入，防缓存未命中重做）
+3. 收尾 Write checkpoint（内容 = 摘要 JSON 本体）+ 向 `progress_log` append 一行 `{"type":"phase-result","phase_id":"<id>","status":"<status>"}`（复用 `/ccg:status` 既有观测面）
+
+#### 4.4 脚本生成与持久化
+
+按下方权威骨架**手写**生成 Workflow JS 脚本，Write 到 `.context/jobs/<job-id>/workflow.mjs`。`~/.claude/.ccg/dist/index.mjs` 通常不存在（installer 当前不安装 dist），不要依赖 `node -e` 调 `buildWorkflowScript`；仓库 `src/utils/workflow-autonomous.ts` 的 `buildWorkflowScript` 是本骨架的设计真相源：
+
+```js
+export const meta = {
+  name: 'ccg-autonomous-<milestone-slug>',
+  description: 'CCG autonomous: <project> (<N> phases, serial)',
+  phases: [
+    { title: 'Phase 2: 实现 user API' },
+    // ... 按串行序逐个字面量，与 PHASES 同序同量
+  ],
+}
+
+const PHASES = [
+  {
+    id: '2',
+    title: 'Phase 2: 实现 user API',
+    prompt: 'phase_id: ...\n...', // 4.3 烘焙好的 YAML 全文，经 JSON.stringify 烘焙防转义事故
+  },
+  // ...
+]
+
+const SUMMARY_SCHEMA = { /* PHASE_SUMMARY_SCHEMA 字面量（workflow-autonomous.ts 为真相源） */ }
+
+export default async function run(args) {
+  const runAttempt = (args && args.runAttempt) || 1
+  const results = []
+  for (const p of PHASES) {
+    const upstream = results
+      .map(r => 'Phase ' + r.id + ': ' + r.status + ' — ' + r.notes)
+      .join('\n')
+    const basePrompt = p.prompt + '\n\nupstream_summaries: |\n' + (upstream || '(none)')
+    const opts = { label: 'phase-' + p.id, phase: p.title, schema: SUMMARY_SCHEMA, agentType: 'phase-runner' }
+    const canceled = x => x !== null && typeof x === 'object' && typeof x.notes === 'string' && x.notes.includes('cancel-flag-detected')
+    let s = await agent(basePrompt, opts)
+    if ((s === null || s.status === 'failed') && !canceled(s)) {
+      // 失败处理：1 次重试。label 掺 runAttempt → resume 后旧失败结果即使被缓存也强制重执行
+      s = await agent(
+        basePrompt + '\n\nretry_reason: 首次失败或返回 null，仅修复失败点',
+        { ...opts, label: 'phase-' + p.id + '-retry-r' + runAttempt },
+      )
+    }
+    if (s === null || s.status === 'failed' || s.status === 'partial') {
+      results.push({
+        id: p.id,
+        status: s === null ? 'failed' : s.status,
+        notes: s === null ? 'agent returned null after retry' : s.notes,
+        escalated: true,
+      })
+      break // 升级暂停：不推进下游，主线收尾走 blocker 路径
+    }
+    results.push({ id: p.id, ...s }) // completed / degraded 均推进
+  }
+  return { runAttempt, results }
+}
+```
+
+确定性铁律：
+
+- 脚本内**零** `Date.now()` / `Math.random()` / 无参 `new Date()`（Workflow 可重放约束）——时间戳全在主线生成（job-id）或 phase-runner 运行时 Bash 取（写 checkpoint 内容，不影响脚本重放）
+- `meta` 是纯字面量；`meta.phases` 与 `PHASES` 同序同量；所有字符串经 `JSON.stringify` 烘焙
+- **⛔ resume 永不重新生成此文件**——字面量漂移会击穿 `agent()` 调用缓存
+- phase-runner 已列入 `ccg-subagent-context.cjs` 的 SUBAGENT_DENYLIST（prompt 由本命令烘焙、自带全量 phase 上下文），hook 不会再注入动态上下文——`--resume` 时 `agent()` 缓存确定性不受 hook 注入漂移影响
+
+#### 4.5 启动
+
+1. job-id = `auto-<milestone-slug>-<yyyymmdd-hhmm>`（主线 Bash 取当前时间生成，时间戳不进脚本）
+2. 写 `.context/jobs/<job-id>/state.json`：
+   ```json
+   { "task_id": "<job-id>", "kind": "autonomous", "run_mode": "workflow",
+     "status": "running", "started_at": "<ISO>", "last_update": "<ISO>",
+     "run_attempt": 1,
+     "summary": "workflow serial: <N> phases" }
+   ```
+3. roadmap.md 一次性批注：milestone 头部加 `Mode: workflow` + `Job: <job-id>`，串行序首 phase 标 `in_progress`
+4. 调 `Workflow` 工具**后台运行**该脚本，传 `args: { runAttempt: 1 }`——脚本传入方式 / 参数名**以运行时工具 schema 为准，禁猜**
+5. 拿到返回的 runId 后立即 atomic 写回 state.json `workflow_run_id` 字段
+6. 主线 **turn end**，等 task-notification（沿用全仓事件驱动等待协议）。运行期用户可用 `/ccg:status <job-id>`（progress.jsonl 的 phase-result 行）或 `/workflows` 面板看进度
+
+#### 4.6 收尾（task-notification 唤醒）
+
+1. 读 workflow 最终结果 `{ runAttempt, results }`
+2. 逐项 `summaryFromWorkflowResult(result)` 校验转换（status 非法 / 缺 required 字段 → 该项按 failed 处理并记入 NOTES）
+3. 批量更新 roadmap.md：completed / failed / partial 状态 + `Completed:` / `Outcome:` 字段；未触达 phase 保持 pending
+4. 末项 notes 含 `cancel-flag-detected` → 协作取消生效：state.json `status:'canceled'`，输出取消摘要，**不走 blocker**
+5. 否则 `decideMilestoneOutcome(results)` 裁决：
+   - `completed` → 写 `.context/jobs/<job-id>/result.md`（milestone 摘要 ≤200 token）+ state.json `status:'done'` + 输出 Milestone Summary（沿用"退出报告格式"节）
+   - `escalated` / `partial` → state.json `status:'failed'` + 走 Step 5 blocker AskUserQuestion，选项加一条"修复后 `/ccg:autonomous --resume <job-id>`"
+
+#### 4.7 断点恢复（`--resume [job-id]`）
+
+1. 缺省 job-id → 取最近一个 `run_mode='workflow'` 且 `status≠done` 的 autonomous job（`listJobs` 按 started_at DESC）
+2. 校验 `.context/jobs/<job-id>/workflow.mjs` 与 state.json `workflow_run_id` 都存在；任一缺失 → 报错并建议重跑（无法断点恢复）
+3. 读 state.json 的 `run_attempt`（缺省按 `1`）→ **+1** → 以**同一脚本文件**（绝不重新生成）+ `resumeFromRunId: <workflow_run_id>` + `args: { runAttempt: <新值> }` 重启后台 run，并把新值 **atomic 写回** state.json `run_attempt` 字段（context 内旧值不可信——`/clear` 后只剩 disk 真相）：
+   - 已完成 phase 的 `agent()` 调用（前缀未变更）命中缓存直接重放——不重跑、git log 无新 commit
+   - 失败 phase 双保险强制重执行：retry label 掺 `runAttempt`（缓存键已变）+ checkpoint 幂等重入（误重跑代价趋零）
+4. 新 runId atomic 写回 state.json `workflow_run_id`，`status` 回 `'running'`，后续同 4.5 步骤 6 / 4.6
+
+#### 失败语义表（脚本内已固化，此处为主线心智模型）
+
+| phase 结果 | 脚本行为 | 主线收尾 |
+|-----------|---------|---------|
+| `null` / `failed` | 脚本内 1 次重试（retry label 掺 runAttempt）→ 仍失败 break 升级暂停 | Step 5 blocker |
+| `partial` | **不重试**直接 break 升级暂停（后台无法 AskUserQuestion，灰区一律暂停） | Step 5 blocker |
+| `degraded` | 继续推进（与 `decideNextAction` 语义一致：fallback 已成功） | roadmap 标 completed + Note |
+| notes 含 `cancel-flag-detected` | break，不重试 | state.json `status:'canceled'` |
+
+### Step 5: Blocker 路径
+
+任何 blocker 都通过 `AskUserQuestion` 暂停，向用户报告：
+
+```markdown
+⚠️ Autonomous 暂停于 Phase 2
+
+原因: <Critical 未修 / 依赖 Phase 1 失败 / API 配额耗尽 / 用户决策点>
+
+详情:
+<具体内容，含 phase 摘要、错误日志、灰区描述>
+
+下一步:
+1. 重试本 phase（workflow 模式：修复后 /ccg:autonomous --resume <job-id>；legacy：重新调 /ccg:team）
+2. 跳过本 phase（标记 skipped，下游依赖 phase 自动 skipped）
+3. 终止 autonomous（保留 roadmap.md 当前进度，下次可续跑）
+4. 我来手动处理（暂停 autonomous，用户处理后回复"继续"）
+```
+
+用户选择决定后续行为；选 4 时 autonomous 进入挂起态，等用户回到主对话发"继续"信号后从断点恢复（workflow 模式恢复 = `--resume <job-id>`）。
+
+---
+
+## 暂停条件 / Blocker 定义
+
+必须暂停的场景：
+
+| 触发 | 描述 |
+|------|------|
+| Critical 未修 | team 完成 Phase 7 后仍有 Critical，且用户在 team 内选了"接受失败"或修复 2 轮仍失败 |
+| 依赖断裂 | 当前 phase 的 `Depends on` 中有 phase 状态为 failed/skipped |
+| 灰区接受 | phase 产出灰区决策（多个合理选项无单一最优解）；workflow 模式下 partial 一律暂停 |
+| 测试不可恢复地失败 | Phase 5 测试报告显示核心断言失败且 Phase 7 修复无效 |
+| API 配额耗尽 | codeagent-wrapper 多次返回 quota/rate limit 错误 |
+| 跨 phase 依赖文件被覆写 | Phase N 修改了 Phase N-1 的产出文件（罕见，靠 team-exec 的文件隔离基本可避免） |
+| 用户显式中断 | 用户在主对话发 stop / pause / 取消（workflow 模式走 `/ccg:cancel <job-id>` 协作取消） |
+
+---
+
+## 状态文件 `.ccg/roadmap.md` 格式
+
+autonomous 是 **roadmap.md 的唯一写者**。team-exec 不动它。
+
+```markdown
+# CCG Project Roadmap
+
+**Project**: user-auth-system
+**Started**: 2026-05-01
+**Last Updated**: 2026-05-03 14:30
+
+## Phase 1: 数据库 schema 设计 (completed)
+- **Goal**: 为 users / sessions / oauth_accounts 设计 schema 与迁移脚本
+- **Depends on**: (none)
+- **Started**: 2026-05-01 09:00 | **Completed**: 2026-05-01 11:20
+- **Plan**: .claude/team-plan/db-schema-20260501-0900/
+- **Outcome**: prisma schema 完成，3 张表 + 7 个索引，迁移脚本通过 dry-run
+
+## Phase 2: 实现 user API (in_progress)
+- **Goal**: 实现 register / login / refresh token / logout 四个 endpoint
+- **Depends on**: Phase 1
+- **Started**: 2026-05-03 10:00
+- **Plan**: .claude/team-plan/user-api-20260503-1000/
+
+## Phase 3: 前端登录页 (pending)
+- **Goal**: 登录页 + 注册页 + 表单校验 + 错误态
+- **Depends on**: Phase 2
+
+## Phase 4: SSO 集成 (opsx://add-google-sso)
+- **Goal**: 接入 Google OAuth 2.0
+- **Depends on**: Phase 3
+- **Note**: 走 OpenSpec 路径，autonomous 调 /ccg:spec-impl
+```
+
+**字段约定**：
+- 状态括号在标题尾部：`(pending|in_progress|completed|failed|skipped)`
+- `Depends on` 缺省值为 `(none)`
+- `Plan` 字段指向该 phase 内 team 产出的 plan 目录
+- `Outcome` 一句话总结，便于下次回顾
+- `opsx://<change-id>` 标记走 OpenSpec 路径
+- `Mode: workflow` + `Job: <job-id>`（milestone 头部）：workflow 模式启动时主线批注，`--resume` 恢复时核对
+- `Type: backend|frontend|fullstack|docs|generic`（可选）：phase-runner 工作风格路由，缺省 `generic`
+- `Quality: fast|triple|debate`（可选，**仅 legacy 路径生效**）：单 phase 覆盖全局 `--quality` flag。例：
+  ```markdown
+  ## Phase 22: schema migration (pending)
+  - **Goal**: 数据库 schema 破坏性变更
+  - **Quality**: debate    ← 这步用最高档（多轮对辩）
+  - **Depends on**: Phase 21
+  ```
+  缺省时遵循全局 flag，全局也无时默认 `triple`。详见附录 A Step 4.0a。
+
+---
+
+## 状态文件 `.ccg/state.md` 跨 phase 扩展
+
+`.ccg/state.md` 由 team-exec 写、记录 wave 任务进度。autonomous 不重写它，但**容许它带 phase 维度**：每个 phase 启动 team 时，team-exec 在 state.md 顶部加一节：
+
+```markdown
+# CCG Team Execution State
+
+**Plan**: .claude/team-plan/user-api-20260503-1000.md
+**Phase**: 2 / 4 (user-auth-system roadmap)
+**Team**: user-api-team
+**Started**: 2026-05-03 10:00
+...
+
+## Wave 1 (completed)
+- [x] T1: ...
+```
+
+新增的 `**Phase**:` 行让用户从 state.md 一眼看出当前在 milestone 的哪一步；这是约定，不强制——老 team-exec 不写 Phase 行也兼容。
+
+**写入时机分工**：
+
+| 文件 | 写入者 | 写入时机 |
+|------|--------|---------|
+| `.ccg/roadmap.md` | autonomous | 每个 phase 进入 in_progress / completed / failed / skipped 时 |
+| `.ccg/state.md` | team-exec | 每个 wave 结束时（与 W2c 行为完全一致） |
+| `.claude/team-plan/<task>-*.md` | team 各阶段 teammate | PRD / 蓝图 / 计划 / 报告产出时 |
+| `.context/jobs/<job-id>/*` | autonomous 主线 + phase-runner | workflow 模式：state.json / workflow.mjs / checkpoints / progress.jsonl / result.md |
+
+---
+
+## 退出报告格式
+
+EXEC_QUEUE 全部跑完后（无论全成功还是含失败/跳过），输出 milestone 收尾报告到主对话，**并将精简版追加到 `.ccg/roadmap.md` 末尾的 `## Milestone Summary` 节**。
+
+```markdown
+# 🏁 Milestone Summary: <project name>
+
+**Started**: 2026-05-01 09:00
+**Ended**: 2026-05-03 18:42
+**Total Phases**: 4
+**Mode**: workflow
+
+## 执行结果
+| Phase | 名称 | 状态 | 耗时 | 产物 |
+|-------|------|------|------|------|
+| 1 | 数据库 schema | ✅ completed | 2h20 | prisma/schema.prisma + 3 迁移 |
+| 2 | user API | ✅ completed | 3h15 | src/api/auth/* (8 文件) |
+| 3 | 前端登录页 | ⚠️ completed (1 Critical 接受) | 4h10 | src/pages/Login.tsx + Signup.tsx |
+| 4 | SSO 集成 | ❌ failed | 1h30 | (无完整产出) |
+
+## 经验提炼
+- Phase 2 的 token 刷新机制设计值得复用到 Phase 4（被忽略）
+- Phase 3 灰区：表单校验位置（前端/后端/双端），用户选了双端
+- Phase 4 失败原因：Google OAuth callback URL 配置缺失，需 IT 协助
+
+## 未解决项
+- [Critical-3.2] Login 表单未做 rate limit（接受到下一 milestone）
+- [Failure-4] Google SSO 集成阻塞，等 IT 提供 client_id
+
+## 推荐下一步
+1. 处理 Phase 4 阻塞后重跑：`/ccg:autonomous --resume <job-id>`（或 `--only 4`）
+2. 创建新 milestone 处理 rate limit 项
+3. 提交 Phase 1-3 产出：`/ccg:commit`
+
+## 产出物索引
+- PRD: .claude/team-plan/*-prd.md (4 份)
+- 蓝图: .claude/team-plan/*-blueprint.md (4 份)
+- 计划: .claude/team-plan/*-plan.md (4 份)
+- 报告: .claude/team-plan/*-report.md (4 份)
+- 代码变更: 见各 report 的"变更摘要"节
+```
+
+---
+
+## 与 OpenSpec 协同
+
+如果项目使用 OpenSpec，roadmap.md 的 phase 可以引用 OPSX proposal id：
+
+```markdown
+## Phase 4: SSO 集成 (opsx://add-google-sso)
+- **Goal**: 接入 Google OAuth 2.0
+- **Depends on**: Phase 3
+```
+
+autonomous 检测到 `opsx://` 前缀时：
+- 不调 `/ccg:team`，改调 `/ccg:spec-impl <change-id>`
+- 由 spec-impl 负责完整的 Plan → Impl → Review → Archive 流程
+- spec-impl 完成后写入 OpenSpec 的归档目录，autonomous 仍在 roadmap.md 写 `completed` + `Plan: openspec/archive/<change-id>/`
+- Critical 处理与失败暂停逻辑与普通 phase 一致
+
+混合 milestone（有 phase 走 team、有 phase 走 spec-impl）受支持，autonomous 按 phase 标题里有无 `opsx://` 自动路由。
+
+**⚠ workflow 模式限制**：`opsx://` phase 只能走 legacy 路径（`/ccg:spec-impl` 是命令不是 agent）。含 opsx phase 的队列在 Step 4.1 会提示改 `--legacy` 或拆跑，不会静默跳过。
+
+---
+
+## Exit Criteria
+
+- [ ] `.ccg/roadmap.md` 已存在且解析无误
+- [ ] EXEC_QUEUE 中所有 phase 已尝试执行（completed / failed / skipped 状态明确）
+- [ ] 每个 phase 都经 phase-runner（workflow 模式）或 `/ccg:team` / `/ccg:spec-impl`（legacy）间接执行，autonomous 自身未直接 spawn Architect/Dev/QA/Reviewer
+- [ ] roadmap.md 反映最终各 phase 状态
+- [ ] 发生 blocker 时已通过 `AskUserQuestion` 暂停并记录用户决策
+- [ ] Milestone Summary 已输出到主对话并追加到 roadmap.md
+- [ ] 所有 team / state.md 由各 phase 内的 team-exec 自行清理，autonomous 不越权
+- [ ] workflow 模式：`.context/jobs/<job-id>/workflow.mjs` 已落盘且 state.json 含 `workflow_run_id` + `run_mode: 'workflow'`
+- [ ] 发生降级（Workflow 工具不可用 / legacy-only flag / opsx 拆跑）时已向用户明示原因
+
+---
+
+## 附录 A：降级路径——prompt 轮转协议（--legacy / 无 Workflow 工具）
+
+触发条件（满足任一即走本附录，其余场景一律走正文 Step 4 workflow 编排）：
+1. 用户显式给 `--legacy`，或给了仅 legacy 生效的 flag（`--quality` / `--offload` / `--sequential` / `--max-concurrent` / `--nested` / `--interactive`）并确认转 legacy
+2. 当前会话工具清单不含 `Workflow` 工具（主线已输出降级警告 + 原因）
+3. EXEC_QUEUE 含 `opsx://` phase 且用户选择整体走 legacy
+
+### Step 4（legacy）: Phase 主循环（wave 并行 + 质量档分级）
 
 #### 4.0 Ground-Truth 采样
 
@@ -539,28 +929,34 @@ nested rescue 委派由此路径解锁。
   路由（由 `src/utils/challenger-orchestrator.ts` 的 `planChallengerSpawns` 决定，
   本模板只描述 LLM 该做什么）：
 
+  > **vendor 挑战走 Bash 直调 helper**：占位符 `{{CODEX_BASH_TASK}}` / `{{GEMINI_BASH_TASK}}`
+  > 由 install 渲染为 `node <ccgx-call-plugin.mjs 绝对路径> <vendor> --json`，绕开
+  > `Agent→gemini-companion→ACP` 慢路径与 sonnet wrapper silent-fallback；CCG 自家
+  > specialist（assumptions-analyzer / nyquist-auditor）仍走 `Agent(...)`（它们是真 subagent）。
+
   | phase Type | spawn 计划（adversarial=true）|
   |-----------|------------------------------|
-  | `backend`  | `Agent(codex:codex-rescue)` + `Agent(assumptions-analyzer)` |
-  | `frontend` | `Agent(gemini:gemini-rescue)` + `Agent(nyquist-auditor)` |
-  | `fullstack`| `Agent(codex:codex-rescue)` + `Agent(gemini:gemini-rescue)` + `Agent(assumptions-analyzer)` + `Agent(nyquist-auditor)` |
+  | `backend`  | `{{CODEX_BASH_TASK}}`（Bash 直调）+ `Agent(assumptions-analyzer)` |
+  | `frontend` | `{{GEMINI_BASH_TASK}}`（Bash 直调）+ `Agent(nyquist-auditor)` |
+  | `fullstack`| `{{CODEX_BASH_TASK}}` + `{{GEMINI_BASH_TASK}}`（均 Bash 直调）+ `Agent(assumptions-analyzer)` + `Agent(nyquist-auditor)` |
   | `docs`/`generic` | `Agent(assumptions-analyzer)` 单兵 |
 
-  **plugin 缺失降级**（acceptance d）：installer 检测不到 `codex:codex-rescue` 或
-  `gemini:gemini-rescue` 命令时，主线只 spawn specialist（CCG 自家 agent，必装），
-  **不 fallback** 到 codeagent-wrapper（已退役依赖）。
+  **plugin 缺失降级**（acceptance d）：installer 检测不到 codex / gemini plugin 时，
+  主线只 spawn specialist（CCG 自家 agent，必装），**不 fallback** 到 codeagent-wrapper（已退役依赖）。
   roadmap.md 备注 `Note: challenger degraded — plugin <name> missing`。
 
-  spawn 范式（一个 message 内并行）：
+  spawn 范式（一个 message 内并行；vendor 用 Bash 直调，specialist 用 Agent）：
 
   ```
-  Agent({ subagent_type: "codex:codex-rescue",
-          description: "Phase <N> challenger (codex)",
-          prompt: <挑战 phase 改动 + 引用 phase-runner 的 commit sha7> })
+  # vendor 挑战：Write tmpfile（含"必须前台执行，禁止 --background / --wait"硬约束 +
+  #   "角色定义见 ~/.claude/.ccg/prompts/<vendor>/reviewer.md，先 Read 再开始" + 引用 phase-runner commit sha7）
+  Bash({ command: `{{CODEX_BASH_TASK}} --prompt-file .context/tmp/ccg-auto-challenge-codex-$JOB.txt`,
+         description: "Phase <N> challenger (codex direct)", run_in_background: true })
   Agent({ subagent_type: "assumptions-analyzer",
           description: "Phase <N> assumption critic",
           prompt: <审视 plan 假设、隐藏依赖、未验证前提> })
   ```
+  主线 Read vendor 挑战 stdout 后 `JSON.parse(stdout).text` 取 FINDINGS；specialist 走 Agent 返回。
 
   challenger 摘要协议（每路 ≤200 token）：
 
@@ -595,197 +991,4 @@ nested rescue 委派由此路径解锁。
   ```
 - 进入下一 wave。
 
-### Step 5: Blocker 路径
-
-任何 blocker 都通过 `AskUserQuestion` 暂停，向用户报告：
-
-```markdown
-⚠️ Autonomous 暂停于 Phase 2
-
-原因: <Critical 未修 / 依赖 Phase 1 失败 / API 配额耗尽 / 用户决策点>
-
-详情:
-<具体内容，含 team 的 report 摘要、错误日志、灰区描述>
-
-下一步:
-1. 重试本 phase（重新调 /ccg:team）
-2. 跳过本 phase（标记 skipped，下游依赖 phase 自动 skipped）
-3. 终止 autonomous（保留 roadmap.md 当前进度，下次可续跑）
-4. 我来手动处理（暂停 autonomous，用户处理后回复"继续"）
-```
-
-用户选择决定后续行为；选 4 时 autonomous 进入挂起态，等用户回到主对话发"继续"信号后从断点恢复。
-
----
-
-## 暂停条件 / Blocker 定义
-
-必须暂停的场景：
-
-| 触发 | 描述 |
-|------|------|
-| Critical 未修 | team 完成 Phase 7 后仍有 Critical，且用户在 team 内选了"接受失败"或修复 2 轮仍失败 |
-| 依赖断裂 | 当前 phase 的 `Depends on` 中有 phase 状态为 failed/skipped |
-| 灰区接受 | team 在某阶段产出灰区决策（多个合理选项无单一最优解），且未运行 `--interactive` 模式 |
-| 测试不可恢复地失败 | Phase 5 测试报告显示核心断言失败且 Phase 7 修复无效 |
-| API 配额耗尽 | codeagent-wrapper 多次返回 quota/rate limit 错误 |
-| 跨 phase 依赖文件被覆写 | Phase N 修改了 Phase N-1 的产出文件（罕见，靠 team-exec 的文件隔离基本可避免） |
-| 用户显式中断 | 用户在主对话发 stop / pause / 取消 |
-
----
-
-## 状态文件 `.ccg/roadmap.md` 格式
-
-autonomous 是 **roadmap.md 的唯一写者**。team-exec 不动它。
-
-```markdown
-# CCG Project Roadmap
-
-**Project**: user-auth-system
-**Started**: 2026-05-01
-**Last Updated**: 2026-05-03 14:30
-
-## Phase 1: 数据库 schema 设计 (completed)
-- **Goal**: 为 users / sessions / oauth_accounts 设计 schema 与迁移脚本
-- **Depends on**: (none)
-- **Started**: 2026-05-01 09:00 | **Completed**: 2026-05-01 11:20
-- **Plan**: .claude/team-plan/db-schema-20260501-0900/
-- **Outcome**: prisma schema 完成，3 张表 + 7 个索引，迁移脚本通过 dry-run
-
-## Phase 2: 实现 user API (in_progress)
-- **Goal**: 实现 register / login / refresh token / logout 四个 endpoint
-- **Depends on**: Phase 1
-- **Started**: 2026-05-03 10:00
-- **Plan**: .claude/team-plan/user-api-20260503-1000/
-
-## Phase 3: 前端登录页 (pending)
-- **Goal**: 登录页 + 注册页 + 表单校验 + 错误态
-- **Depends on**: Phase 2
-
-## Phase 4: SSO 集成 (opsx://add-google-sso)
-- **Goal**: 接入 Google OAuth 2.0
-- **Depends on**: Phase 3
-- **Note**: 走 OpenSpec 路径，autonomous 调 /ccg:spec-impl
-```
-
-**字段约定**：
-- 状态括号在标题尾部：`(pending|in_progress|completed|failed|skipped)`
-- `Depends on` 缺省值为 `(none)`
-- `Plan` 字段指向该 phase 内 team 产出的 plan 目录
-- `Outcome` 一句话总结，便于下次回顾
-- `opsx://<change-id>` 标记走 OpenSpec 路径
-- `Quality: fast|triple|debate`（可选）：单 phase 覆盖全局 `--quality` flag。例：
-  ```markdown
-  ## Phase 22: schema migration (pending)
-  - **Goal**: 数据库 schema 破坏性变更
-  - **Quality**: debate    ← 这步用最高档（多轮对辩）
-  - **Depends on**: Phase 21
-  ```
-  缺省时遵循全局 flag，全局也无时默认 `triple`。详见 Step 4.0a。
-
----
-
-## 状态文件 `.ccg/state.md` 跨 phase 扩展
-
-`.ccg/state.md` 由 team-exec 写、记录 wave 任务进度。autonomous 不重写它，但**容许它带 phase 维度**：每个 phase 启动 team 时，team-exec 在 state.md 顶部加一节：
-
-```markdown
-# CCG Team Execution State
-
-**Plan**: .claude/team-plan/user-api-20260503-1000.md
-**Phase**: 2 / 4 (user-auth-system roadmap)
-**Team**: user-api-team
-**Started**: 2026-05-03 10:00
-...
-
-## Wave 1 (completed)
-- [x] T1: ...
-```
-
-新增的 `**Phase**:` 行让用户从 state.md 一眼看出当前在 milestone 的哪一步；这是约定，不强制——老 team-exec 不写 Phase 行也兼容。
-
-**写入时机分工**：
-
-| 文件 | 写入者 | 写入时机 |
-|------|--------|---------|
-| `.ccg/roadmap.md` | autonomous | 每个 phase 进入 in_progress / completed / failed / skipped 时 |
-| `.ccg/state.md` | team-exec | 每个 wave 结束时（与 W2c 行为完全一致） |
-| `.claude/team-plan/<task>-*.md` | team 各阶段 teammate | PRD / 蓝图 / 计划 / 报告产出时 |
-
----
-
-## 退出报告格式
-
-EXEC_QUEUE 全部跑完后（无论全成功还是含失败/跳过），输出 milestone 收尾报告到主对话，**并将精简版追加到 `.ccg/roadmap.md` 末尾的 `## Milestone Summary` 节**。
-
-```markdown
-# 🏁 Milestone Summary: <project name>
-
-**Started**: 2026-05-01 09:00
-**Ended**: 2026-05-03 18:42
-**Total Phases**: 4
-**Mode**: auto
-
-## 执行结果
-| Phase | 名称 | 状态 | 耗时 | 产物 |
-|-------|------|------|------|------|
-| 1 | 数据库 schema | ✅ completed | 2h20 | prisma/schema.prisma + 3 迁移 |
-| 2 | user API | ✅ completed | 3h15 | src/api/auth/* (8 文件) |
-| 3 | 前端登录页 | ⚠️ completed (1 Critical 接受) | 4h10 | src/pages/Login.tsx + Signup.tsx |
-| 4 | SSO 集成 | ❌ failed | 1h30 | (无完整产出) |
-
-## 经验提炼
-- Phase 2 的 token 刷新机制设计值得复用到 Phase 4（被忽略）
-- Phase 3 灰区：表单校验位置（前端/后端/双端），用户选了双端
-- Phase 4 失败原因：Google OAuth callback URL 配置缺失，需 IT 协助
-
-## 未解决项
-- [Critical-3.2] Login 表单未做 rate limit（接受到下一 milestone）
-- [Failure-4] Google SSO 集成阻塞，等 IT 提供 client_id
-
-## 推荐下一步
-1. 处理 Phase 4 阻塞后重跑：`/ccg:autonomous --only 4`
-2. 创建新 milestone 处理 rate limit 项
-3. 提交 Phase 1-3 产出：`/ccg:commit`
-
-## 产出物索引
-- PRD: .claude/team-plan/*-prd.md (4 份)
-- 蓝图: .claude/team-plan/*-blueprint.md (4 份)
-- 计划: .claude/team-plan/*-plan.md (4 份)
-- 报告: .claude/team-plan/*-report.md (4 份)
-- 代码变更: 见各 report 的"变更摘要"节
-```
-
----
-
-## 与 OpenSpec 协同
-
-如果项目使用 OpenSpec，roadmap.md 的 phase 可以引用 OPSX proposal id：
-
-```markdown
-## Phase 4: SSO 集成 (opsx://add-google-sso)
-- **Goal**: 接入 Google OAuth 2.0
-- **Depends on**: Phase 3
-```
-
-autonomous 检测到 `opsx://` 前缀时：
-- 不调 `/ccg:team`，改调 `/ccg:spec-impl <change-id>`
-- 由 spec-impl 负责完整的 Plan → Impl → Review → Archive 流程
-- spec-impl 完成后写入 OpenSpec 的归档目录，autonomous 仍在 roadmap.md 写 `completed` + `Plan: openspec/archive/<change-id>/`
-- Critical 处理与失败暂停逻辑与普通 phase 一致
-
-混合 milestone（有 phase 走 team、有 phase 走 spec-impl）受支持，autonomous 按 phase 标题里有无 `opsx://` 自动路由。
-
----
-
-## Exit Criteria
-
-- [ ] `.ccg/roadmap.md` 已存在且解析无误
-- [ ] EXEC_QUEUE 中所有 phase 已尝试执行（completed / failed / skipped 状态明确）
-- [ ] 每个 phase 都通过 `/ccg:team` 或 `/ccg:spec-impl` 间接执行，autonomous 自身未直接 spawn Architect/Dev/QA/Reviewer
-- [ ] roadmap.md 反映最终各 phase 状态
-- [ ] 发生 blocker 时已通过 `AskUserQuestion` 暂停并记录用户决策
-- [ ] Milestone Summary 已输出到主对话并追加到 roadmap.md
-- [ ] 所有 team / state.md 由各 phase 内的 team-exec 自行清理，autonomous 不越权
-
 <!-- CCG:AUTONOMOUS:END -->