ccgx-workflow 1.0.0

package/templates/commands/commit.md

@@ -0,0 +1,151 @@
+---
+description: '智能 Git 提交：分析改动生成 Conventional Commit 信息，支持拆分建议'
+---
+
+# Commit - 智能 Git 提交
+
+分析当前改动，生成 Conventional Commits 风格的提交信息。
+
+## 使用方法
+
+```bash
+/commit [options]
+```
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--no-verify` | 跳过 Git 钩子 |
+| `--all` | 暂存所有改动 |
+| `--amend` | 修补上次提交 |
+| `--signoff` | 附加签名 |
+| `--emoji` | 包含 emoji 前缀 |
+| `--scope <scope>` | 指定作用域 |
+| `--type <type>` | 指定提交类型 |
+
+---
+
+## 执行工作流
+
+### 🔍 阶段 1：仓库校验
+
+`[模式：检查]`
+
+1. 验证 Git 仓库状态
+2. 检测 rebase/merge 冲突
+3. 读取当前分支/HEAD 状态
+
+### 📋 阶段 2：改动检测
+
+`[模式：分析]`
+
+1. 获取已暂存与未暂存改动
+2. 若暂存区为空：
+   - `--all` → 执行 `git add -A`
+   - 否则提示选择
+
+### ✂️ 阶段 3：拆分建议
+
+`[模式：建议]`
+
+按以下维度聚类：
+- 关注点（源代码 vs 文档/测试）
+- 文件模式（不同目录/包）
+- 改动类型（新增 vs 删除）
+
+若检测到多组独立变更（>300 行 / 跨多个顶级目录），建议拆分。
+
+### ✍️ 阶段 4：生成提交信息
+
+`[模式：生成]`
+
+**格式**：`[emoji] <type>(<scope>): <subject>`
+
+- 首行 ≤ 72 字符
+- 祈使语气
+- 消息体：动机、实现要点、影响范围
+
+**语言**：根据最近 50 次提交判断中文/英文
+
+### 📦 阶段 5：Context 自动归档（若 .context/ 存在）
+
+`[模式：上下文归档]`
+
+**前置判断**：
+- 若 `.context/` 目录不存在 → 在提交成功后输出提示：`💡 建议执行 /ccg:context init 启用决策追踪`，不阻断
+- 若 `.context/` 存在 → 执行以下步骤
+
+**从 git diff 自动生成 ContextEntry**：
+
+1. 获取当前分支名：`git branch --show-current`
+2. 获取暂存区变更：`git diff --cached --stat` + `git diff --cached`（完整 diff）
+3. **分析 diff 生成 ContextEntry**：
+   - `summary`：从阶段 4 生成的 commit message 中取首行
+   - `decisions`：分析 diff 中的关键变更（新增依赖、架构调整、接口变更、配置修改），推断决策理由
+   - `bugs`：若 commit type 为 `fix`，从 diff 中提取 bug 症状、根因、修复方式
+   - `changes.files`：从 `git diff --cached --name-only` 提取
+   - `tests`：若变更包含测试文件，记录测试相关信息
+4. **合并 session.log**（可选）：若 `.context/current/branches/<branch>/session.log` 存在且非空，将其中的手动记录合并到 decisions/bugs 中，然后清空 session.log
+5. **脱敏**：扫描 token/key/password/secret 模式 → 替换为 `[REDACTED]`
+6. **追加**：将 ContextEntry 作为一行追加到 `.context/history/commits.jsonl`
+7. **重生成**：更新 `.context/history/commits.md` 人类视图
+8. **暂存**：`git add .context/history/`
+9. **Trailer**：在 commit message 中添加 `Context-Id: <uuid>` trailer
+
+**ContextEntry 格式**参见 `/ccg:context` 命令中的 Schema 定义。
+
+**失败降级**：若归档过程出错，不阻断提交。写入 minimal ContextEntry（仅 summary + files），继续正常提交。
+
+### ✅ 阶段 6：执行提交
+
+`[模式：执行]`
+
+```bash
+git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG
+```
+
+---
+
+## Type 与 Emoji 映射
+
+| Emoji | Type | 说明 |
+|-------|------|------|
+| ✨ | `feat` | 新增功能 |
+| 🐛 | `fix` | 缺陷修复 |
+| 📝 | `docs` | 文档更新 |
+| 🎨 | `style` | 代码格式 |
+| ♻️ | `refactor` | 重构 |
+| ⚡️ | `perf` | 性能优化 |
+| ✅ | `test` | 测试相关 |
+| 🔧 | `chore` | 构建/工具 |
+| 👷 | `ci` | CI/CD |
+| ⏪️ | `revert` | 回滚 |
+
+---
+
+## 示例
+
+```bash
+# 基本提交
+/commit
+
+# 暂存所有并提交
+/commit --all
+
+# 带 emoji 提交
+/commit --emoji
+
+# 指定类型和作用域
+/commit --scope ui --type feat --emoji
+
+# 修补上次提交
+/commit --amend --signoff
+```
+
+## 关键规则
+
+1. **仅使用 Git** – 不调用包管理器
+2. **尊重钩子** – 默认执行，`--no-verify` 可跳过
+3. **不改源码** – 只读写 `.git/COMMIT_EDITMSG`
+4. **原子提交** – 一次提交只做一件事

package/templates/commands/context.md

@@ -0,0 +1,332 @@
+---
+description: '项目上下文管理：初始化 .context 目录、记录决策日志、压缩归档、查看历史'
+---
+
+# Context - 项目上下文管理
+
+管理 `.context/` 目录结构，为 LLM 工具提供决策审计链。
+
+## 使用方法
+
+```bash
+/context <subcommand> [options]
+```
+
+## 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `init` | 初始化 `.context/` 目录结构 |
+| `log <message>` | （可选）手动追加备注到 session.log，commit 时会合并 |
+| `show` | 查看当前分支的 session.log |
+| `compress` | 压缩 session.log → uncommit.md（手动预览用） |
+| `history` | 查看 history/commits.md |
+| `squash <ids...>` | 合并多条 history 记录（配合 git squash） |
+
+> **核心用法**：`init` 一次，之后只管开发。`/ccg:commit` 提交时自动从 git diff 分析决策并归档到 history/。`log` 仅在你想手动补充备注时使用。
+
+---
+
+## 执行工作流
+
+### 子命令：init
+
+`[模式：初始化]`
+
+在当前项目根目录创建 `.context/` 结构：
+
+1. 检测项目根目录（查找 `.git/`）
+2. 若 `.context/` 已存在，跳过已有文件，仅补全缺失
+3. 创建以下结构：
+
+```
+.context/
+├── .gitignore
+├── .gitattributes
+├── prefs/
+│   ├── coding-style.md
+│   └── workflow.md
+├── current/
+│   └── branches/
+│       └── .gitkeep
+└── history/
+    ├── commits.jsonl
+    ├── commits.md
+    └── archives/
+        └── .gitkeep
+```
+
+4. **创建 `.context/.gitignore`**：
+
+```gitignore
+# Ephemeral workspace — never commit
+current/
+
+# Raw interaction logs — always local only
+**/session.log
+**/session.raw.log
+**/*.session.log
+**/*.raw.log
+
+# Editor / temp
+**/*.tmp
+**/*.bak
+**/*.swp
+```
+
+5. **创建 `.context/.gitattributes`**：
+
+```
+# JSONL append-only: 'union' merge reduces conflicts
+history/commits.jsonl merge=union
+history/archives/*.jsonl merge=union
+```
+
+6. **创建 `.context/prefs/coding-style.md`**（团队编码规范模板）：
+
+```markdown
+# Coding Style Guide
+
+> 此文件定义团队编码规范，所有 LLM 工具在修改代码时必须遵守。
+> 提交到 Git，团队共享。
+
+## General
+- Prefer small, reviewable changes; avoid unrelated refactors.
+- Keep functions short (<50 lines); avoid deep nesting (≤3 levels).
+- Name things explicitly; no single-letter variables except loop counters.
+- Handle errors explicitly; never swallow errors silently.
+
+## Language-Specific
+<!-- 根据项目语言补充，例如：-->
+<!-- ### TypeScript -->
+<!-- - Use strict mode; prefer `interface` over `type` for object shapes. -->
+
+## Git Commits
+- Conventional Commits, imperative mood.
+- Atomic commits: one logical change per commit.
+
+## Testing
+- Every feat/fix MUST include corresponding tests.
+- Coverage must not decrease.
+- Fix flow: write failing test FIRST, then fix code.
+
+## Security
+- Never log secrets (tokens/keys/cookies/JWT).
+- Validate inputs at trust boundaries.
+```
+
+7. **创建 `.context/prefs/workflow.md`**（LLM 工作流规则）：
+
+```markdown
+# Development Workflow Rules
+
+> 此文件定义 LLM 开发工作流的强制规则。
+> 所有 LLM 工具在执行任务时必须遵守，不可跳过任何步骤。
+
+## Full Flow (MUST follow, no exceptions)
+
+### feat (新功能)
+1. 理解需求，分析影响范围
+2. 读取现有代码，理解模式
+3. 编写实现代码
+4. 编写对应测试
+5. 运行测试，修复失败
+6. 更新文档（若 API 变更）
+7. 自查 lint / type-check
+
+### fix (缺陷修复)
+1. 复现问题，确认症状
+2. 定位根因
+3. 编写失败测试（先有红灯）
+4. 修复代码
+5. 验证测试通过（变绿灯）
+6. 回归测试
+
+### refactor (重构)
+1. 确保现有测试通过
+2. 小步重构，每步可验证
+3. 重构后测试必须全部通过
+4. 不改变外部行为
+
+## Context Logging (决策记录)
+
+当你做出以下决策时，MUST 追加到 `.context/current/branches/<当前分支>/session.log`：
+
+1. **方案选择**：选 A 不选 B 时，记录原因
+2. **Bug 发现与修复**：根因 + 修复方法 + 教训
+3. **API/架构决策**：接口设计选择
+4. **放弃的方案**：为什么放弃
+
+追加格式：
+
+## <ISO-8601 时间>
+**Decision**: <你选择了什么>
+**Alternatives**: <被排除的方案>
+**Reason**: <为什么>
+**Risk**: <潜在风险>
+```
+
+8. **创建 `.context/history/commits.jsonl`**（空文件）
+
+9. **创建 `.context/history/commits.md`**（人类视图模板）：
+
+```markdown
+# Commit Decision History
+
+> 此文件是 `commits.jsonl` 的人类可读视图，可由工具重生成。
+> Canonical store: `commits.jsonl` (JSONL, append-only)
+
+| Date | Context-Id | Commit | Summary | Decisions | Bugs | Risk |
+|------|-----------|--------|---------|-----------|------|------|
+```
+
+10. **注入 CLAUDE.md 引用**（若项目存在 CLAUDE.md）：
+
+检测项目根目录是否有 `CLAUDE.md`，若有则在末尾追加：
+
+```markdown
+
+## .context 项目上下文
+
+> 项目使用 `.context/` 管理开发决策上下文。
+
+- 编码规范：`.context/prefs/coding-style.md`
+- 工作流规则：`.context/prefs/workflow.md`
+- 决策历史：`.context/history/commits.md`
+
+**规则**：修改代码前必读 prefs/，做决策时按 workflow.md 规则记录日志。
+```
+
+11. 输出初始化结果摘要
+
+---
+
+### 子命令：log
+
+`[模式：记录]`
+
+1. 获取当前 Git 分支名：`git branch --show-current`
+2. 确保 `.context/current/branches/<branch>/` 目录存在
+3. 将 `<message>` 以结构化格式追加到 `session.log`：
+
+```markdown
+## <ISO-8601 当前时间>
+<message>
+```
+
+---
+
+### 子命令：show
+
+`[模式：查看]`
+
+1. 获取当前分支名
+2. 读取 `.context/current/branches/<branch>/session.log`
+3. 若不存在，提示 "当前分支暂无决策日志"
+4. 输出内容
+
+---
+
+### 子命令：compress
+
+`[模式：压缩]`
+
+将 `session.log` 压缩为结构化 `uncommit.md`，供提交前审查。
+
+1. 读取 `.context/current/branches/<branch>/session.log`
+2. 若为空，提示无内容可压缩
+3. **脱敏**：扫描并替换潜在敏感信息（token/key/password → `[REDACTED]`）
+4. **结构化提取**：从日志中提取 decisions / bugs / alternatives
+5. **生成 uncommit.md**：
+
+```markdown
+# Pre-commit Summary: <branch-name>
+
+| Time | Summary | Decision | Method | Result & Bug |
+|------|---------|----------|--------|--------------|
+| ... | ... | ... | ... | ... |
+```
+
+6. 输出压缩结果供用户审查
+7. 提示用户：确认后可执行 `/ccg:commit` 提交
+
+---
+
+### 子命令：history
+
+`[模式：查看]`
+
+1. 读取 `.context/history/commits.md`
+2. 若不存在，提示 "暂无历史记录，请先使用 /ccg:context init"
+3. 输出内容
+4. 若用户指定文件路径，从 `commits.jsonl` 检索 `changes.files` 包含该路径的条目
+
+---
+
+### 子命令：squash
+
+`[模式：合并]`
+
+配合 `git squash` 使用，合并多条 ContextEntry。
+
+1. 接收 Context-Id 列表
+2. 从 `commits.jsonl` 读取对应条目
+3. 生成新的聚合 ContextEntry：
+   - 新 `context_id`（UUIDv7）
+   - `Context-Refs` = 所有被 squash 的 ids
+   - 合并 decisions / bugs / changes
+4. 追加到 `commits.jsonl`
+5. 重生成 `commits.md`
+
+---
+
+## ContextEntry Schema (v1.0.0)
+
+每条 JSONL 记录格式：
+
+```json
+{
+  "schema_version": "1.0.0",
+  "context_id": "<UUIDv7>",
+  "created_at": "<ISO-8601>",
+  "producer": {
+    "tool": "<tool-name>",
+    "llm": { "provider": "<provider>", "model": "<model>" }
+  },
+  "git": {
+    "branch": "<branch>",
+    "commit_sha": "<short-sha>",
+    "trailers": { "Context-Id": "<uuid>" }
+  },
+  "summary": "<one-line summary>",
+  "decisions": [{
+    "title": "<decision title>",
+    "rationale": "<why>",
+    "tradeoffs": ["<tradeoff>"],
+    "assumptions": ["<assumption>"],
+    "rejected_alternatives": [{ "option": "<alt>", "reason": "<why rejected>" }],
+    "side_effects": ["<side effect>"]
+  }],
+  "bugs": [{
+    "symptom": "<what happened>",
+    "root_cause": "<why>",
+    "fix": "<how fixed>",
+    "lesson": "<takeaway>"
+  }],
+  "changes": { "files": ["<path>"] },
+  "tests": [{ "command": "<cmd>", "result": "<pass/fail>", "coverage": "<pct>" }],
+  "privacy": { "classification": "internal", "redactions_applied": true }
+}
+```
+
+---
+
+## 关键规则
+
+1. **prefs/ 提交到 Git** — 团队共享编码规范
+2. **current/ 永不提交** — 原始日志仅本地
+3. **history/ 提交到 Git** — 永久决策归档
+4. **commits.jsonl 是 canonical** — commits.md 可重生成
+5. **UUIDv7 为主键** — 不依赖 commit SHA（rebase-safe）
+6. **merge=union** — JSONL append 冲突自动合并
+7. **脱敏先于一切** — 任何写入 history 前必须脱敏

package/templates/commands/debate.md

@@ -0,0 +1,165 @@
+---
+description: '原生多轮对辩原语：codex propose ↔ gemini challenge ↔ codex respond，主线编排 cap N 轮或 challenger 自报无 critical 即停'
+argument-hint: "<topic> [--max-rounds N] [--layer backend|frontend|fullstack]"
+---
+
+# Debate - 原生多轮对辩原语
+
+`/ccg:debate <topic>` 由**主线**管 A↔B 多轮对辩状态机。不是 spawn 一个 agent 让它管对辩——主线自己每轮 spawn 一次模型 + 接 ≤ 200 token 摘要 + 判收敛 + 决定下一轮。
+
+> **设计来源**：用户 Q3 + `.ccg-research/07-multimodel-collaboration-rethink.md`：多模型协作的硬主修复，避免单模型自我洗稿。
+
+## 使用方法
+
+```bash
+/ccg:debate <topic> [--max-rounds N] [--layer backend|frontend|fullstack]
+```
+
+**Flags**：
+
+| Flag | 默认 | 说明 |
+|------|------|------|
+| `--max-rounds N` | `3` | 最大轮数；硬上限 `10` |
+| `--layer backend\|frontend\|fullstack` | `backend` | 影响 propose / challenge 角色分配（见下表） |
+
+## 轮次协议
+
+主线按 `debateStateMachine(topic, options)` 给出的计划顺序 spawn：
+
+| Round | Kind | backend | frontend | fullstack |
+|-------|------|---------|----------|-----------|
+| 1 | propose   | codex   | gemini   | codex + gemini 并行 |
+| 2 | challenge | gemini  | codex    | codex + gemini 并行（互相反对） |
+| 3 | respond   | codex   | gemini   | codex + gemini 并行 |
+
+> 第 4 轮起循环 propose → challenge → respond，按 `--max-rounds` 截断。
+
+## 提示词文件
+
+| Kind | CCG Prompt（内嵌或参考） |
+|------|------------------------|
+| propose / respond | `~/.claude/.ccg/prompts/{codex\|gemini}/architect.md`（建设性视角） |
+| challenge | `~/.claude/.ccg/prompts/{codex\|gemini}/reviewer.md`（adversarial / 专挑漏洞） |
+
+## 主线编排状态机
+
+**Step 0：解析参数**
+
+1. 读 `$ARGUMENTS`，第一个非 flag token 即 topic（用引号包裹整段任务描述）
+2. 解析 `--max-rounds N` / `--layer X`
+3. **检测 plugin 可用性（纯目录探测，禁止运行时探活）**：
+   - 用 `Bash` 跑 `ls ~/.claude/plugins/ 2>/dev/null` 找 `codex@*` / `gemini@*` 前缀子目录
+   - 子目录内须含 `SKILL.md` / `plugin.json` / `package.json` / `manifest.json` 任一 marker → 标 `installed: true`
+   - ⛔ **严禁**调用 `/gemini:status` / `/codex:status` / 任何 broker / runtime / health 探活——broker 是**懒启动**的，启动后才有；当前 `brokerRunning: false` 不代表 plugin 不可用
+   - 等价 helper：`detectPluginAvailability()`（`src/utils/plugin-detection.ts:156`）
+   - 任一 plugin 真未装 → 该模型走 general-purpose 降级路径
+4. 调用 helper：`debateStateMachine(topic, { maxRounds, layer, pluginsAvailable })` 得到 `DebateRoundPlan[]`
+
+**Step 1：按计划逐轮 spawn**
+
+对每个 round（`for (let i = 0; i < plan.length; i++)`）：
+
+1. 取 `round = plan[i]`
+2. 对 `round.models` 中的每个 model：
+   - **plugin 路径**（`pluginSubagent` = `codex:codex-rescue` 或 `gemini:gemini-rescue`）：spawn `Agent(subagent_type=round.pluginSubagent[idx], prompt=<下面的 prompt 模板>)`
+     - codex 模型 → `Agent(subagent_type="codex:codex-rescue", ...)`
+     - gemini 模型 → `Agent(subagent_type="gemini:gemini-rescue", ...)`
+   - **降级路径**（`models[idx] === 'general-purpose'`）：spawn `Agent(subagent_type="general-purpose", prompt=<内嵌 round.ccgPromptFiles[idx] 文件全文> + <下面的 prompt 模板>)`
+3. ⛔ **plugin spawn 失败必须重试**：若 `Agent(subagent_type="codex:codex-rescue"|"gemini:gemini-rescue")` 调用失败（spawn 抛错 / 返回非结构化错误 / `parseRoundSummary` 返回 `parsed=false`），最多重试 **2 次**（间隔 **5 秒**）。仅当 **3 次全部失败**时才把该模型本轮替换为 general-purpose 降级路径，并在合成的 `RoundSummary.notes` 标 `plugin spawn failed after 3 attempts, degraded: <具体根因>`。⛔ **禁止**单次失败或单次 broker 负信号即降级——broker 懒启动属正常态。
+
+   **v4.4.3 schema 硬约束**：标记格式必须是 `plugin spawn failed after N attempts, degraded: <reason>` 三段式（N 必须 ≥ 3，reason 必须给具体根因如 `broker timeout` / `API quota` / `parse-failed`，禁用占位文本如 `unknown` / `n/a`）。`parseRoundSummary` 自动从 NOTES 抽取 populate `RoundSummary.degraded`，Step 2 综合阶段会调 `validateRetryProtocol(累积 RoundSummary[])` 校验合规——违规会出现在最终输出的 ⚠️ 协议违规区段（用户可见）。这是把"3 次重试 + degraded 标记"从 prompt 软约束硬化为 schema-level 校验。
+4. **等待所有 model 返回**（`run_in_background: true` + 事件驱动等通知（不调 TaskOutput））
+5. 对每个返回的 ≤200 token 摘要调用 `parseRoundSummary(text)` → `RoundSummary`
+6. 把本轮的 `RoundSummary[]`（fullstack 为 2 条；backend/frontend 为 1 条）合成一条主 `RoundSummary`（取最长 length，合并 propose/challenge/respond/notes 字段）追加到累积数组
+7. **判收敛**：`shouldStop(累积 RoundSummary[], maxRounds)` → 返回 true 即跳出循环
+
+**Step 2：综合输出**
+
+主线综合产出：
+- **最终方案**（最近一轮 propose 或 respond）
+- **分歧点列表**（所有 challenge 内容去重 + 简化）
+- **各方观点摘要表**（每轮 model × kind × 一行核心观点）
+- **收敛理由**（哪个信号触发了停止：`no critical` / `max rounds` / `length-converged`）
+- ⚠️ **协议违规区段**（**v4.4.3 强制**）：在输出最终 markdown 前调用 `validateRetryProtocol(累积 RoundSummary[])` → `RetryProtocolReport`：
+  - `report.compliant === false` → 主线 **必须** 在最终输出加一段 `## ⚠️ Retry Protocol Violations`，逐条列 `report.violations[]`（含 `round` / `kind` / `message`）
+  - 4 类违规枚举：`parse-failed-no-degraded` / `insufficient-attempts` / `missing-reason` / `silent-success`
+  - 设计动机：原 prompt 软约束 "3 次重试 + degraded 标记" 实测会被主线 LLM 跳过（v4.4.2 dogfood 真实案例：主线 R1 一次 fallback 就接受未重试也未标 degraded）。schema 硬校验让违规可观测、可枚举，避免 silent fallback 在 debate 综合阶段被吞
+  - **不要**把 violations 摘要塞进对辩主体内容然后跑路——必须独立成段，让用户看见具体哪轮哪种违规
+
+主线输出 markdown 表格，**不写文件**——主线直接展示给用户。
+
+## Round prompt 模板（spawn 时注入）
+
+### propose / respond round
+
+```
+你是<layer>层的 architect。
+任务：propose <topic>（或 respond 上一轮的 challenge：<上一轮 challenge 内容>）
+
+要求：
+1. 给出**可落地**的方案，含关键设计决策与权衡
+2. 主动列出 ≥ 2 个潜在风险或反对意见的预判
+3. 输出 ≤ 200 token，严格格式：
+   STATUS: completed
+   PROPOSE: <方案核心一句话>     # 或 RESPOND:
+   NOTES: <关键发现 / 风险点 / 一行总结>
+```
+
+### challenge round
+
+```
+你是<layer>层的 critic / reviewer，**严格 adversarial 视角**。
+任务：challenge <上一轮 propose 内容>
+
+要求：
+1. 找出 ≥ 2 个 critical / 重大风险（性能、安全、可维护性、边界条件）
+2. 如果**真的没有 critical**，明确说"no critical issue"或"agreement reached"
+3. 输出 ≤ 200 token：
+   STATUS: completed
+   CHALLENGE: <核心反对论点>
+   NOTES: <发现的关键漏洞 / "no critical issue" / 改进建议>
+```
+
+## 降级路径
+
+| 触发条件 | 主线行为 |
+|---------|----------|
+| `detectPlugin(name)` 返回 `{ installed: false }`（目录或 marker 缺失）**或**同一模型连续 3 次 spawn 失败 | `Agent(subagent_type="general-purpose", prompt=<内嵌 ~/.claude/.ccg/prompts/<model>/<file>.md 全文> + Round prompt 模板)` |
+| `parseRoundSummary` 返回 `parsed=false`（subagent 摘要格式损坏） | 本轮主 RoundSummary 标 `parsed=false`，继续下一轮但在最终 NOTES 里标"未达成共识" |
+| 主线无法解析任何字段（连续 2 轮都 parsed=false） | 提前停止，输出"未达成共识 / 子模型摘要解析失败" 给用户 |
+
+## 收敛信号（`shouldStop` 双信号）
+
+主线**不应**自己重新发明收敛逻辑——直接用 helper：
+
+```
+shouldStop(rounds, maxRounds) → boolean
+```
+
+判定规则：
+1. **任一轮**的 `challenge` 或 `notes` 字段含 `no critical` / `agreement reached` / `lgtm` / `无 critical` / `达成共识` → 立即停
+2. 已达 `maxRounds` → 强制停
+3. 相邻两轮 `length` 变化 < 20% → 信息收敛，停
+
+## Helper
+
+实现于 `src/utils/debate-orchestrator.ts`，主线**不需要 import**（已通过 `src/index.ts` 导出供 SDK 用户调用），主线直接用此模板里描述的协议手动执行各步骤。
+
+helper 暴露：
+- `debateStateMachine(topic, options)` → `DebateRoundPlan[]`
+- `parseRoundSummary(text)` → `RoundSummary`（v4.4.3: 含 `degraded?: { attempts, reason }` 字段）
+- `shouldStop(rounds, maxRounds)` → `boolean`
+- `validateRetryProtocol(rounds)` → `RetryProtocolReport`（**v4.4.3**: Step 2 综合阶段必须调；非 compliant 时主线必须在输出加协议违规区段）
+- `REQUIRED_RETRY_ATTEMPTS` = `3`（与 Step 1.3 的 "3 次全部失败" 文档同步）
+
+## 不做
+
+- ❌ **不**改源代码 / 不写文件（debate 是纯讨论原语）
+- ❌ **不**调 codeagent-wrapper（debate 走 plugin spawn 范式）
+- ❌ **不** spawn debate-manager subagent 让它管对辩——主线自己管，逐轮接摘要
+
+## 与其他命令的关系
+
+- `/ccg:plan` / `/ccg:analyze`：单次双模型并行，不轮转。`/ccg:debate` 适合需求**有争议**或**风险高**的设计决策，用多轮"propose → challenge → respond"压力测试。
+- `/ccg:review --fix`：基于已有代码改动的审查闭环。`/ccg:debate` 用于**改动前**的方案讨论。
+- `/ccg:autonomous`：长跑链路，每个 phase 自包含。`/ccg:debate` 是单一主题的对辩原语，不入 roadmap。