ccg-workflow 3.0.0 → 3.0.2

package/README.md

@@ -1,17 +1,31 @@
 # CCG - Claude + Codex + Gemini Multi-Model Collaboration
 
+<div align="center">
+
+<img src="assets/logo/ccg-logo-cropped.png" alt="CCG Workflow" width="400">
+
 [![GitHub stars](https://img.shields.io/github/stars/fengshao1227/ccg-workflow?style=social)](https://github.com/fengshao1227/ccg-workflow)
 [![NPM Downloads](https://img.shields.io/npm/dt/ccg-workflow?style=flat-square&color=blue)](https://www.npmjs.com/package/ccg-workflow)
 [![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code)
+[![Tests](https://img.shields.io/badge/Tests-139%20passed-brightgreen.svg)]()
+[![Follow on X](https://img.shields.io/badge/X-@CCG__Workflow-black?logo=x&logoColor=white)](https://x.com/CCG_Workflow)
+![star](https://atomgit.com/fengshao1227/ccg-workflow/star/badge.svg)
 
 [简体中文](./README.zh-CN.md) | English
 
-## Sponsor
+</div>
+
+## ♥️ Sponsor
 
-[302.AI](https://share.302.ai/oUDqQ6) — Pay-as-you-go enterprise AI resource hub with the latest AI models and APIs.
+[![302.AI](assets/sponsors/302.ai-en.jpg)](https://share.302.ai/oUDqQ6)
 
-[n1n.ai](https://api.n1n.ai/register?channel=c_ivgzug0w) — One API Key to access 500+ AI models.
+[302.AI](https://share.302.ai/oUDqQ6) is a pay-as-you-go enterprise AI resource hub that offers the latest and most comprehensive AI models and APIs on the market, along with a variety of ready-to-use online AI applications.
+
+---
+
+[**n1n.ai**](https://api.n1n.ai/register?channel=c_ivgzug0w) — Global LLM API Gateway. One API Key to access 500+ top AI models (GPT-5, Claude 4.5, Gemini 3 Pro, and more).
 
 ---
 
@@ -224,10 +238,15 @@ npx ccg-workflow            # Select "Uninstall" from menu
 - **Issues**: [GitHub Issues](https://github.com/fengshao1227/ccg-workflow/issues)
 - **Community**: [Linux.do](https://linux.do)
 
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=fengshao1227/ccg-workflow&type=timeline&legend=top-left)](https://www.star-history.com/#fengshao1227/ccg-workflow&type=timeline&legend=top-left)
+
 ## License
 
 MIT
 
 ---
 
-v3.0.0 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)
+v3.0.2 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)

package/README.zh-CN.md

@@ -1,15 +1,32 @@
 # CCG - Claude + Codex + Gemini 多模型协作
+# CCG - Claude + Codex + Gemini Multi-Model Collaboration
 
+<div align="center">
+
+<img src="assets/logo/ccg-logo-cropped.png" alt="CCG Workflow" width="400">
+
+[![GitHub stars](https://img.shields.io/github/stars/fengshao1227/ccg-workflow?style=social)](https://github.com/fengshao1227/ccg-workflow)
+[![NPM Downloads](https://img.shields.io/npm/dt/ccg-workflow?style=flat-square&color=blue)](https://www.npmjs.com/package/ccg-workflow)
 [![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code)
+[![Tests](https://img.shields.io/badge/Tests-139%20passed-brightgreen.svg)]()
+[![Follow on X](https://img.shields.io/badge/X-@CCG__Workflow-black?logo=x&logoColor=white)](https://x.com/CCG_Workflow)
+![star](https://atomgit.com/fengshao1227/ccg-workflow/star/badge.svg)
+
+[简体中文](./README.zh-CN.md) | English
 
-简体中文 | [English](./README.md)
+</div>
 
-## 赞助商
+## ♥️ Sponsor
 
-[302.AI](https://share.302.ai/oUDqQ6) — 按用量付费的企业级 AI 资源平台。
+[![302.AI](assets/sponsors/302.ai-en.jpg)](https://share.302.ai/oUDqQ6)
+
+[302.AI](https://share.302.ai/oUDqQ6) is a pay-as-you-go enterprise AI resource hub that offers the latest and most comprehensive AI models and APIs on the market, along with a variety of ready-to-use online AI applications.
+
+---
 
-[n1n.ai](https://api.n1n.ai/register?channel=c_ivgzug0w) — 一个 API Key 连接 500+ AI 模型。
+[**n1n.ai**](https://api.n1n.ai/register?channel=c_ivgzug0w) — Global LLM API Gateway. One API Key to access 500+ top AI models (GPT-5, Claude 4.5, Gemini 3 Pro, and more).
 
 ---
 
@@ -227,4 +244,4 @@ MIT
 
 ---
 
-v3.0.0 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)
+v3.0.2 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import cac from 'cac';
 import ansis from 'ansis';
-import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.81OoN8XX.mjs';
+import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.CGOOq1xo.mjs';
 import 'inquirer';
 import 'ora';
 import 'node:child_process';

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.81OoN8XX.mjs';
+export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.CGOOq1xo.mjs';
 import 'ansis';
 import 'inquirer';
 import 'ora';

package/dist/shared/{ccg-workflow.81OoN8XX.mjs → ccg-workflow.CGOOq1xo.mjs}

@@ -10,7 +10,7 @@ import fs from 'fs-extra';
 import { parse, stringify } from 'smol-toml';
 import i18next from 'i18next';
 
-const version = "3.0.0";
+const version = "3.0.2";
 
 function cmd(id, order, category, name, nameEn, description, descriptionEn, cmdOverride) {
   return {
@@ -1028,6 +1028,10 @@ async function installSkillFiles(ctx) {
       overwrite: true,
       errorOnExist: false
     });
+    const securityDir = join(skillsDestDir, "domains", "security");
+    if (await fs.pathExists(securityDir)) {
+      await fs.remove(securityDir);
+    }
     const replacePathsInDir = async (dir) => {
       const entries = await fs.readdir(dir, { withFileTypes: true });
       for (const entry of entries) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccg-workflow",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow",
   "type": "module",
   "packageManager": "pnpm@10.17.1",

package/templates/commands/go.md

@@ -127,7 +127,9 @@ $ARGUMENTS
 mkdir -p .ccg/tasks/{task-name}
 ```
 
-**Step 3**: 写入 `.ccg/tasks/{task-name}/task.json`：
+**Step 3**: 获取当前 git 分支名：`git rev-parse --abbrev-ref HEAD`
+
+**Step 4**: 写入 `.ccg/tasks/{task-name}/task.json`：
 
 ```json
 {
@@ -138,11 +140,15 @@ mkdir -p .ccg/tasks/{task-name}
   "currentPhase": "1",
   "nextAction": "{策略第一阶段的描述}",
   "gate": null,
+  "branch": "{当前 git 分支}",
+  "scope": "{task-name}",
   "createdAt": "{当前 ISO 日期时间}"
 }
 ```
 
-**Step 4**: 如果 `.ccg/spec/` 目录存在，创建 `.ccg/tasks/{task-name}/context.jsonl`，列出相关 spec 文件。
+**Step 5**: 创建 `.ccg/tasks/{task-name}/context.jsonl` 种子文件：
+- 第一行写种子示例：`{"_example": "Fill with {\"file\": \"path\", \"reason\": \"why\"}. Seed rows are skipped."}`
+- 如果 `.ccg/spec/` 存在 → 追加 spec 文件条目
 
 **复杂度 S → 跳过任务创建**（保持轻量）。
 

package/templates/engine/phase-guide.md

@@ -93,3 +93,115 @@ TeamCreate 失败（Agent Teams 未启用）→ Claude 自己按计划顺序实
 - 代码块标明语言
 - 变更摘要用 git diff 格式
 - 研究结果用表格对比
+
+## 8. Spec Evolution Protocol — Spec 反馈环
+
+> 让 `.ccg/spec/` 从静态文档变为随项目开发自动进化的活知识库。
+
+### 触发条件
+
+任务归档前（status → "archived"），如果以下任一条件成立，**必须执行 Spec Evolution**：
+- 本次开发中发现了可复用的编码模式或约定
+- 外部模型审查提出了有价值的规范建议
+- 修复了一个非显而易见的坑（未来可能再踩）
+- 引入了新的第三方库/API/架构模式
+
+### 执行步骤
+
+1. **提炼经验**：分析 `git diff` + review.md（如有），提取可复用的经验教训
+2. **分类归属**：判断经验属于哪个 Spec 域：
+   - 后端相关 → `.ccg/spec/backend/index.md`
+   - 前端相关 → `.ccg/spec/frontend/index.md`
+   - 跨模块/通用 → `.ccg/spec/guides/index.md`
+3. **草拟更新**：以追加方式写出建议新增的 Spec 条目（不覆盖现有内容）
+4. **展示给用户**：
+   ```
+   📝 Spec Evolution — 本次开发经验提炼
+   
+   建议新增到 .ccg/spec/backend/index.md:
+     - [规范条目]（来源：{task-name}，{日期}）
+   
+   确认写入？[Y/n]
+   ```
+5. **用户确认后写入**（⛔ 不可静默写入 Spec）
+6. **无值得提炼的经验 → 跳过**（不要强行凑条目）
+
+### 条目质量标准
+
+好的 Spec 条目：
+- ✅ 具体：引用真实文件路径和 API 签名
+- ✅ 说明 Why：不只说"要这样做"，还说"因为…"
+- ✅ 可验证：子 Agent 能根据条目判断对错
+
+坏的 Spec 条目：
+- ❌ 空泛："写好的代码" / "注意安全"
+- ❌ 一次性：只对本次任务有价值，对未来无意义
+
+## 9. Loop Detection & Recovery — 死循环检测
+
+> workflow-state Hook 自动追踪每轮的 phase + nextAction。连续 3 轮无变化触发 Break-Loop Protocol。
+
+### 机制
+
+- Hook 在每轮用户消息时写入 `.ccg/tasks/{name}/.turns.json`（最近 10 轮滚动缓冲）
+- 检测规则：连续 3 轮 `phase` + `nextAction` 完全相同 → 判定为死循环
+- 触发后在 `<ccg-state>` 面包屑中注入 `⚠️ LOOP DETECTED` 警告
+
+### Break-Loop Protocol（Claude 收到警告后必须执行）
+
+1. **立即停止**当前重复动作
+2. **根因分析**（5 Why）：
+   - 是外部依赖阻塞？（网络/API/权限）→ 告知用户
+   - 是策略不适配？→ 建议升级策略
+   - 是信息不足？→ 向用户提问
+   - 是实现路径走死？→ 换方案
+3. **更新 task.json**：`nextAction` 必须变更为新的动作描述（打破循环）
+4. **如果连续 2 次触发 Break-Loop**（即 6 轮无进展）→ 强制暂停，输出完整状态摘要请用户介入
+
+## 10. Ralph Loop — 迭代审查协议
+
+> 审查不是一次性动作。每轮 spawn 新 Agent（干净上下文），读取磁盘最新状态重新验证，循环自修复。
+
+### 适用场景
+
+策略中标注为 `[Ralph Loop]` 的审查阶段，使用迭代审查代替一次性审查。
+
+### 标准流程
+
+```
+Round N (N=1,2,...,MAX_ROUNDS):
+  1. 双模型并行审查（每次 spawn 新 Agent，干净上下文）
+  2. 质量关卡（verify-security / verify-quality / verify-change）
+  3. 综合审查报告，按 Critical / Warning / Info 分级
+  4. 展示给用户，询问：
+     - 有 Critical → "发现 N 个 Critical 问题，是否修复后再审？[Y/n]"
+     - 无 Critical → "审查通过，是否需要再审一轮？[y/N]"
+  5. 用户选择继续 →
+     a. spawn fix-dev（新 Agent，干净上下文）修复 Critical 问题
+     b. 进度追加到 .ccg/tasks/{name}/fix-log.jsonl
+     c. 回到 Round N+1
+  6. 用户选择停止 → 退出循环，进入下一阶段
+```
+
+### 关键规则
+
+- **每轮审查必须是新 Agent** — 不复用上一轮的 Agent 上下文，避免"上下文污染越修越烂"
+- **fix-dev 也是新 Agent** — 从磁盘读取最新代码状态，只修分配的问题
+- **最多 3 轮**（MAX_ROUNDS=3）— 超过 3 轮说明问题根深，应该回退到规划阶段
+- **用户始终有决定权** — 每轮结束后由用户决定是否继续，不自动循环
+- **fix-log.jsonl 追踪进度** — 每轮结果追加一行 JSON，格式：
+  ```jsonl
+  {"round": 1, "critical": 2, "warning": 5, "fixed": ["file1:issue", "file2:issue"], "ts": "ISO"}
+  {"round": 2, "critical": 0, "warning": 3, "fixed": ["file3:issue"], "ts": "ISO"}
+  ```
+
+### context.jsonl 角色标注
+
+策展 context.jsonl 时，按角色标注 `roles` 字段：
+```jsonl
+{"file": ".ccg/spec/backend/index.md", "reason": "后端规范", "roles": ["implement", "review"]}
+{"file": ".ccg/tasks/{name}/plan.md", "reason": "实施计划", "roles": ["implement"]}
+{"file": ".ccg/tasks/{name}/research/lib-comparison.md", "reason": "库选型", "roles": ["research", "implement"]}
+```
+
+SubAgent-context Hook 自动按角色过滤：无 `roles` 字段 = 注入所有角色。

package/templates/engine/strategies/debug-investigate.md

@@ -144,7 +144,20 @@ Gate: 用户已确认修复方向 ✓
      📍 Next: /ccg commit 提交修复
    ```
 
-**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交修复"`
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次调试的根因和修复方案，提炼可复用的调试经验和防御性编码约定
+2. 如有值得记录的经验（特别是非显而易见的坑）→ 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task"
+```
 
 ---
 

package/templates/engine/strategies/full-collaborate.md

@@ -225,21 +225,25 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
 2. 按 plan.md 中的 Layer 顺序逐文件实施
 3. 仍然遵守质量关卡
 
-### Phase 5: 优化审查 + 质量关卡 [required]
+### Phase 5: 迭代审查 [required · Ralph Loop]
 
 `[模式：优化]`
 
 **Gate check**: 实施已完成
 
-**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "双模型审查 + 质量关卡"`
+**Task 更新**：`currentPhase → "5-optimization"`, `nextAction → "Ralph Loop Round 1: 双模型审查 + 质量关卡"`
 
-#### 5a. 双模型交叉审查
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查。最多 3 轮。
 
-**并行调用**：
+#### Round N 流程（N=1,2,3）
+
+**5a. 双模型交叉审查（每轮 spawn 新 Agent，干净上下文）**
+
+**并行调用**（`run_in_background: true`）：
 - **backend 模型**：reviewer 角色 — 关注安全、性能、错误处理
 - **frontend 模型**：reviewer 角色 — 关注可访问性、设计一致性
 
-#### 5b. 质量关卡
+**5b. 质量关卡**
 
 **⛔ 以下 Skill 必须逐个调用执行，不可跳过，不可用自己的判断替代：**
 
@@ -247,17 +251,35 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
 2. 调用 Skill `verify-quality` — 等待报告
 3. 调用 Skill `verify-change` — 等待报告
 
-任何关卡报告 **Critical** → 必须修复后重新运行该关卡，才能进入 Phase 6。
-
-#### 5c. 综合报告
+**5c. 综合报告**
 
 整合审查意见 + 质量关卡结果，按严重度分级：
 - **Critical**：必须修复（阻塞交付）
 - **Warning**：建议修复
 - **Info**：供参考
 
-展示审查结果，用户确认后执行必要的优化。
-**持久化**：写入 `.ccg/tasks/{task-name}/review.md`
+**持久化**：写入 `.ccg/tasks/{task-name}/review.md`（每轮覆盖）
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`：
+```jsonl
+{"round": N, "critical": X, "warning": Y, "info": Z, "ts": "ISO"}
+```
+
+**5d. 用户决定（⛔ 必须等待）**
+
+展示审查结果后询问用户：
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical 但有 Warning → `无 Critical 问题。需要再审一轮处理 Warning？[y/N]`
+- 全部通过 → 直接进入 Phase 6
+
+用户选择继续 →
+1. spawn fix-dev（**新 Agent，干净上下文**）修复 Critical/Warning
+2. fix-dev 完成后回到 5a 开始 Round N+1
+3. 追加修复记录到 fix-log.jsonl
+
+用户选择停止 → 进入 Phase 6
+
+**第 3 轮仍有 Critical** → 强制停止，建议回退到 Phase 3 重新规划。
 
 ### Phase 6: 最终验收
 
@@ -277,7 +299,28 @@ SendMessage({ to: "reviewer", message: { type: "shutdown_request" } })
      📍 Next: /ccg commit 提交，或查看 .ccg/tasks/{task-name}/ 中的完整记录
    ```
 
-**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交"`
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次 `git diff` + `review.md`，提炼可复用的编码约定和经验教训
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过（不强行凑）
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：将 `.ccg/tasks/{task-name}/` 移动到 `.ccg/tasks/archive/YYYY-MM/{task-name}/`
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+```
+
+**自动提交归档**：
+```bash
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task {task-name}"
+```
+
+```
+📍 Next: /ccg:commit 提交产品代码
+```
 
 ---
 

package/templates/engine/strategies/guided-develop.md

@@ -161,34 +161,59 @@ TaskOutput({ task_id: "<id>", block: true, timeout: 600000 })
 
 **Task 更新**：`currentPhase → "5-implement"`, `nextAction → "按计划执行实施"`
 
-### Phase 6: 验证 + 双模型审查 + 质量关卡
+### Phase 6: 迭代审查 [Ralph Loop]
 
 1. `git diff` 展示所有变更
 2. 运行测试（如果有）
 
-**⛔ 双模型交叉审查（变更 >30 行时必须执行）：**
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查（变更 >30 行时，最多 3 轮）。
+
+#### Round N 流程
+
+**⛔ 双模型交叉审查（每轮 spawn 新调用，干净上下文）：**
 3. 并行调用双模型（`run_in_background: true`，使用 model-router.md 模板）：
    - backend 模型 + reviewer 角色 — 安全、性能、错误处理
    - frontend 模型 + reviewer 角色 — 设计一致性（如涉及前端）
 4. 综合审查意见
 
-**⛔ 质量关卡（变更 >30 行时必须逐个调用 Skill，不可跳过）：**
+**⛔ 质量关卡（必须逐个调用 Skill，不可跳过）：**
 5. 调用 Skill `verify-quality` — 等待报告
 6. 调用 Skill `verify-security` — 等待报告（涉及 auth/input/crypto 时）
 7. 调用 Skill `verify-change` — 等待报告
-8. Critical 问题必须修复
-4. 检查是否满足验收标准
-5. 输出结果：
+
+**用户决定（⛔ 必须等待）：**
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical → `审查通过。需要再审一轮？[y/N]`
+- 用户选择继续 → 修复 Critical 后回到 Round N+1
+- 用户选择停止 → 退出审查循环
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`。
+
+8. 检查是否满足验收标准
+9. 输出结果：
    ```
    ✅ 开发完成
      变更: [N] 文件，[M] 行
      实现: [摘要]
      测试: [通过/跳过/失败情况]
-     质量: [Critical: N, Warning: N, Info: N]
+     审查: [N] 轮，[Critical: N, Warning: N, Info: N]
      📍 Next: 可以用 /ccg:commit 提交
    ```
 
-**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交"`
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次 `git diff` + 审查结果，提炼可复用的编码约定
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task"
+```
 
 ---
 

package/templates/engine/strategies/refactor-safely.md

@@ -110,12 +110,16 @@ Gate: 所有步骤已执行 ✓
 Step [N/M]: [描述] — ✅ 测试通过 / ❌ 测试失败
 ```
 
-### Phase 5: 最终验证 + 双模型审查 + 质量关卡
+### Phase 5: 迭代审查 [Ralph Loop]
 
 1. 运行完整测试套件
 2. 对比基线：确保不引入新的失败
 
-**⛔ 双模型交叉审查（必须执行，使用 model-router.md 调用模板）：**
+参考 `phase-guide.md § 10 Ralph Loop` 执行迭代审查（最多 3 轮）。
+
+#### Round N 流程
+
+**⛔ 双模型交叉审查（每轮 spawn 新调用，干净上下文）：**
 
 3. 获取变更：`git diff` 全量输出
 4. 并行调用双模型审查（`run_in_background: true`）：
@@ -129,23 +133,42 @@ Step [N/M]: [描述] — ✅ 测试通过 / ❌ 测试失败
 7. 调用 Skill `verify-security` — 等待报告
 8. 调用 Skill `verify-change` — 等待报告
 
-**综合报告**：双模型审查 + 质量关卡，按严重度分级：
-- Critical → 必须修复后重新验证
-- Warning → 建议修复
-- Info → 供参考
+**综合报告**：双模型审查 + 质量关卡，按严重度分级
+
+**用户决定（⛔ 必须等待）：**
+- 有 Critical → `发现 N 个 Critical 问题。修复后再审一轮？[Y/n]`
+- 无 Critical → `审查通过。需要再审一轮？[y/N]`
+- 用户选择继续 → 修复后回到 Round N+1
+- 用户选择停止 → 退出审查循环
+
+追加进度到 `.ccg/tasks/{task-name}/fix-log.jsonl`。
 
 9. `git diff` 展示全部变更
-5. 输出结果：
+10. 对比基线，确认无回归
+11. 输出结果：
    ```
    ✅ 重构完成
      步骤: [N] 步全部通过
      变更: [文件数] 文件，[行数] 行
      测试: 基线 [N] 通过 → 重构后 [N] 通过
-     质量: [Critical: N, Warning: N, Info: N]
+     审查: [N] 轮，[Critical: N, Warning: N, Info: N]
      📍 Next: /ccg:commit 提交
    ```
 
-**Task 更新**：`status → "completed"`, `nextAction → "可用 /ccg:commit 提交"`
+#### Spec Evolution（归档前必须执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 分析本次重构的 `git diff`，提炼可复用的重构模式和架构约定
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
+**Task 更新**：`status → "archived"`
+
+**归档任务**：
+```bash
+mkdir -p .ccg/tasks/archive/$(date +%Y-%m) && mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date +%Y-%m)/
+git add .ccg/tasks/ && git commit -m "chore: archive ccg task"
+```
 
 ---
 

package/templates/engine/strategies/review-audit.md

@@ -106,6 +106,13 @@ Gate: 双模型审查已返回 ✓
 
 如果有 Critical 发现，询问用户是否立即修复（可切换到 `direct-fix` 策略）。
 
+#### Spec Evolution（审查完成后执行）
+
+参考 `phase-guide.md § 8 Spec Evolution Protocol` 执行：
+1. 从审查发现中提炼可复用的编码规范（特别是 Critical/Warning 级反复出现的模式）
+2. 如有值得记录的经验 → 草拟 Spec 条目，展示给用户确认后追加到 `.ccg/spec/{domain}/index.md`
+3. 无值得提炼的经验 → 跳过
+
 ---
 
 ## 铁律

package/templates/hooks/subagent-context.js

@@ -3,6 +3,8 @@
 // Injects spec + task context when:
 //   1. codeagent-wrapper is about to be called (Bash)
 //   2. Agent Team member is about to be spawned (Agent)
+// Supports role-based filtering: context.jsonl entries with "roles" field
+// are only injected when the agent's detected role matches.
 
 'use strict';
 
@@ -28,12 +30,11 @@ try {
   // Determine trigger type
   const command = toolInput.command || '';
   const teamName = toolInput.team_name || '';
-  const agentPrompt = toolInput.prompt || '';
+  const agentName = toolInput.name || '';
 
   const isCodeagentCall = command.includes('codeagent-wrapper');
   const isTeamSpawn = !!teamName;
 
-  // Only activate for codeagent-wrapper calls or Agent Team spawns
   if (!isCodeagentCall && !isTeamSpawn) {
     process.exit(0);
   }
@@ -45,20 +46,60 @@ try {
   const task = getActiveTask(root);
   if (!task) process.exit(0);
 
+  // --- Role detection ---
+  const ROLE_FILE_MAP = {
+    'reviewer': 'review',
+    'analyzer': 'research',
+    'debugger': 'debug',
+    'tester': 'review',
+    'architect': 'implement',
+    'optimizer': 'implement',
+    'frontend': 'implement'
+  };
+  const AGENT_NAME_PATTERNS = [
+    { pattern: /dev|builder|fix|impl/i, role: 'implement' },
+    { pattern: /review|check|audit/i, role: 'review' },
+    { pattern: /research|scout|explore|analy/i, role: 'research' },
+    { pattern: /debug|diagnos/i, role: 'debug' }
+  ];
+
+  let detectedRole = 'implement'; // default
+
+  if (isCodeagentCall) {
+    const roleMatch = command.match(/ROLE_FILE:.*\/(\w+)\.md/);
+    if (roleMatch) {
+      detectedRole = ROLE_FILE_MAP[roleMatch[1]] || 'implement';
+    }
+  } else if (isTeamSpawn && agentName) {
+    for (const { pattern, role } of AGENT_NAME_PATTERNS) {
+      if (pattern.test(agentName)) {
+        detectedRole = role;
+        break;
+      }
+    }
+  }
+
   const contextParts = [];
 
-  // Inject active task info for team members
   if (isTeamSpawn) {
     contextParts.push(`<ccg-active-task>
 Active task: ${task.dir}
 Task: ${task.title || task.id} (${task.status})
 Strategy: ${task.strategy}
 Phase: ${task.currentPhase}
+Agent role: ${detectedRole}
 </ccg-active-task>`);
   }
 
-  // Read context.jsonl entries (specs + research refs)
-  const entries = readContextJsonl(task.dir);
+  // Read context.jsonl with role-based filtering
+  const allEntries = readContextJsonl(task.dir);
+  const entries = allEntries.filter(entry => {
+    if (!entry.roles || !Array.isArray(entry.roles) || entry.roles.length === 0) {
+      return true; // no roles field = inject to all
+    }
+    return entry.roles.includes(detectedRole) || entry.roles.includes('all');
+  });
+
   if (entries.length > 0) {
     const specContents = [];
     for (const entry of entries) {
@@ -75,7 +116,7 @@ Phase: ${task.currentPhase}
     }
   }
 
-  // Read PRD and plan
+  // Read PRD and plan (always inject, role-independent)
   const prd = readFileSafe(path.join(task.dir, 'requirements.md'));
   const plan = readFileSafe(path.join(task.dir, 'plan.md'));
 
@@ -93,21 +134,23 @@ Phase: ${task.currentPhase}
     contextParts.push(taskContext.join('\n'));
   }
 
-  // Read research files
-  const researchDir = path.join(task.dir, 'research');
-  if (fs.existsSync(researchDir)) {
-    try {
-      const researchFiles = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
-      if (researchFiles.length > 0) {
-        const researchContents = researchFiles.map(f => {
-          const content = readFileSafe(path.join(researchDir, f));
-          return content ? `--- research/${f} ---\n${content.substring(0, 1500)}` : null;
-        }).filter(Boolean);
-        if (researchContents.length > 0) {
-          contextParts.push(`<ccg-research>\n${researchContents.join('\n\n')}\n</ccg-research>`);
+  // Read research files (only for research + implement roles)
+  if (detectedRole === 'research' || detectedRole === 'implement') {
+    const researchDir = path.join(task.dir, 'research');
+    if (fs.existsSync(researchDir)) {
+      try {
+        const researchFiles = fs.readdirSync(researchDir).filter(f => f.endsWith('.md'));
+        if (researchFiles.length > 0) {
+          const researchContents = researchFiles.map(f => {
+            const content = readFileSafe(path.join(researchDir, f));
+            return content ? `--- research/${f} ---\n${content.substring(0, 1500)}` : null;
+          }).filter(Boolean);
+          if (researchContents.length > 0) {
+            contextParts.push(`<ccg-research>\n${researchContents.join('\n\n')}\n</ccg-research>`);
+          }
         }
-      }
-    } catch { /* silent */ }
+      } catch { /* silent */ }
+    }
   }
 
   if (contextParts.length === 0) process.exit(0);

package/templates/hooks/task-utils.js

@@ -25,9 +25,10 @@ function getActiveTask(projectRoot) {
   try {
     const dirs = fs.readdirSync(tasksDir)
       .filter(d => {
+        if (d === 'archive') return false;
         try {
-          return fs.statSync(path.join(tasksDir, d)).isDirectory()
-            && fs.existsSync(path.join(tasksDir, d, 'task.json'));
+          const full = path.join(tasksDir, d);
+          return fs.statSync(full).isDirectory() && fs.existsSync(path.join(full, 'task.json'));
         } catch { return false; }
       })
       .sort()
@@ -35,10 +36,12 @@ function getActiveTask(projectRoot) {
 
     for (const dir of dirs) {
       try {
-        const raw = fs.readFileSync(path.join(tasksDir, dir, 'task.json'), 'utf-8');
+        const taskPath = path.join(tasksDir, dir, 'task.json');
+        if (!fs.existsSync(taskPath)) continue; // stale pointer detection
+        const raw = fs.readFileSync(taskPath, 'utf-8');
         const task = JSON.parse(raw);
         if (task.status !== 'completed' && task.status !== 'archived') {
-          return { dir: path.join(tasksDir, dir), ...task };
+          return { dir: path.join(tasksDir, dir), ...task, _stale: false };
         }
       } catch { /* skip malformed */ }
     }
@@ -101,6 +104,75 @@ function outputHook(eventName, additionalContext) {
   }));
 }
 
+function archiveTask(taskDir, projectRoot) {
+  try {
+    const now = new Date();
+    const month = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+    const archiveDir = path.join(projectRoot, '.ccg', 'tasks', 'archive', month);
+    if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir, { recursive: true });
+    const name = path.basename(taskDir);
+    const dest = path.join(archiveDir, name);
+    fs.renameSync(taskDir, dest);
+    return dest;
+  } catch { return null; }
+}
+
+function autoCommitTask(projectRoot, message) {
+  try {
+    const { execSync } = require('child_process');
+    execSync('git add .ccg/tasks/', { cwd: projectRoot, stdio: 'pipe' });
+    const diff = execSync('git diff --cached --quiet', { cwd: projectRoot, stdio: 'pipe' }).toString();
+    return false; // nothing to commit
+  } catch {
+    try {
+      const { execSync } = require('child_process');
+      execSync(`git commit -m "${message || 'chore: archive ccg task'}"`, { cwd: projectRoot, stdio: 'pipe' });
+      return true;
+    } catch { return false; }
+  }
+}
+
+function seedContextJsonl(taskDir, projectRoot) {
+  const jsonlPath = path.join(taskDir, 'context.jsonl');
+  if (fs.existsSync(jsonlPath)) return;
+  const specDir = path.join(projectRoot, '.ccg', 'spec');
+  const lines = ['{"_example": "Fill with {\\\"file\\\": \\\"path\\\", \\\"reason\\\": \\\"why\\\"}. One entry per line. Seed rows (with _example key) are skipped."}'];
+  if (fs.existsSync(specDir)) {
+    try {
+      const walk = (dir, prefix) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+          const rel = prefix ? `${prefix}/${e.name}` : e.name;
+          if (e.isDirectory()) walk(path.join(dir, e.name), rel);
+          else if (e.name.endsWith('.md')) lines.push(JSON.stringify({ file: `.ccg/spec/${rel}`, reason: 'project spec' }));
+        }
+      };
+      walk(specDir, '');
+    } catch { /* silent */ }
+  }
+  try { fs.writeFileSync(jsonlPath, lines.join('\n') + '\n', 'utf-8'); } catch { /* silent */ }
+}
+
+function trackTurn(taskDir, phase, nextAction) {
+  const turnsPath = path.join(taskDir, '.turns.json');
+  let turns = [];
+  try { turns = JSON.parse(fs.readFileSync(turnsPath, 'utf-8')); } catch { /* fresh */ }
+  turns.push({ phase: phase || '', next: nextAction || '', ts: Date.now() });
+  if (turns.length > 10) turns = turns.slice(-10);
+  try { fs.writeFileSync(turnsPath, JSON.stringify(turns), 'utf-8'); } catch { /* silent */ }
+  return turns;
+}
+
+function detectLoop(turns, threshold) {
+  threshold = threshold || 3;
+  if (turns.length < threshold) return null;
+  const recent = turns.slice(-threshold);
+  const key = `${recent[0].phase}|${recent[0].next}`;
+  const allSame = recent.every(t => `${t.phase}|${t.next}` === key);
+  if (!allSame) return null;
+  const elapsed = (recent[recent.length - 1].ts - recent[0].ts) / 1000;
+  return { phase: recent[0].phase, nextAction: recent[0].next, count: threshold, elapsedSec: Math.round(elapsed) };
+}
+
 module.exports = {
   findProjectRoot,
   getActiveTask,
@@ -109,5 +181,10 @@ module.exports = {
   readContextJsonl,
   detectTechStack,
   getGitInfo,
-  outputHook
+  outputHook,
+  archiveTask,
+  autoCommitTask,
+  seedContextJsonl,
+  trackTurn,
+  detectLoop
 };

package/templates/hooks/workflow-state.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 // CCG Workflow State Hook — UserPromptSubmit
 // Injects per-turn breadcrumb based on active task state.
+// Includes loop detection: warns when same phase+nextAction repeats 3+ turns.
 // Runs on EVERY user message. Must be fast (<1s) and never crash.
 
 'use strict';
 
 try {
-  const { findProjectRoot, getActiveTask, outputHook } = require('./task-utils.js');
+  const { findProjectRoot, getActiveTask, outputHook, trackTurn, detectLoop } = require('./task-utils.js');
 
   const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const root = findProjectRoot(cwd);
@@ -19,6 +20,9 @@ try {
     process.exit(0);
   }
 
+  const turns = trackTurn(task.dir, task.currentPhase, task.nextAction);
+  const loop = detectLoop(turns, 3);
+
   const lines = [
     '<ccg-state>',
     `Task: ${task.title || task.id} (${task.status})`,
@@ -31,6 +35,18 @@ try {
   }
 
   lines.push(`Next: ${task.nextAction || 'Continue current phase'}`);
+
+  if (loop) {
+    lines.push('');
+    lines.push(`⚠️ LOOP DETECTED: Phase "${loop.phase}" with same nextAction repeated ${loop.count} turns (${loop.elapsedSec}s).`);
+    lines.push('🔄 BREAK-LOOP PROTOCOL:');
+    lines.push('  1. STOP current approach immediately');
+    lines.push('  2. Root-cause analysis: why is this phase not progressing?');
+    lines.push('  3. Options: (a) try alternative approach, (b) escalate to user, (c) upgrade strategy');
+    lines.push('  4. If blocked by external dependency → tell user explicitly');
+    lines.push('  5. Do NOT repeat the same action — that is what caused this loop');
+  }
+
   lines.push('</ccg-state>');
 
   outputHook('UserPromptSubmit', lines.join('\n'));

package/templates/rules/ccg-skill-routing.md

@@ -4,7 +4,11 @@ When the user's request matches trigger keywords below, automatically READ the c
 
 **IMPORTANT**: Read the skill file FIRST, then respond. Do NOT fabricate domain knowledge from training data when a skill file exists.
 
-## Security Domain (`domains/security/`)
+## Security Domain (`domains/security/`) — NOT installed by default
+
+> Security domain files contain red team/pentest reference content that may trigger antivirus false positives.
+> They are NOT installed by default. To enable, manually copy from the npm package:
+> `cp -r $(npm root -g)/ccg-workflow/templates/skills/domains/security/ ~/.claude/skills/ccg/domains/security/`
 
 | Trigger Keywords | Skill File | Description |
 |------------------|-----------|-------------|