@hunyed15/codecgc 0.1.0

package/codecgc/reference/executor-contract.md

@@ -0,0 +1,87 @@
+# CodeCGC 执行器契约
+
+## 1. 目的
+
+这份文档定义 CodeCGC 工作流运行时与执行器 MCP 适配层之间的标准执行契约。
+
+## 2. 当前执行器
+
+前端执行器工具：
+
+- `implement_frontend_task`
+
+后端执行器工具：
+
+- `implement_backend_task`
+
+## 3. 成功返回的必要字段
+
+当执行成功时，两类执行器都必须返回：
+
+- `success`
+- `task_id`
+- `SESSION_ID`
+- `summary`
+- `agent_messages`
+- `changed_files`
+- `policy_checks`
+- `risks`
+
+可选字段：
+
+- `all_messages`
+
+## 4. 失败返回的必要字段
+
+当执行失败时，两类执行器至少必须返回：
+
+- `success`
+- `task_id`
+- `policy_checks`
+- `error`
+
+## 5. 运行时归一化规则
+
+工作流运行时允许在写入 audit 之前，对执行器输出做标准化整理。
+
+当前归一化入口：
+
+- `scripts/run_codecgc_task.py`
+
+audit 层最终会稳定写入：
+
+- `result.success`
+- `result.outcome`
+- `result.task_id`
+- `result.session_id`
+- `result.summary`
+- `result.changed_files`
+- `result.policy_checks`
+- `result.risks`
+- `result.error`
+
+## 6. 当前语义规则
+
+两个执行器目前在工作流层被视为共享同一套语义：
+
+- `success` 表示执行器返回了结构化结果
+- `changed_files` 是审核会消费的范围内文件证据
+- `policy_checks` 是机器可读的策略轨迹
+- `SESSION_ID` 是后续续跑所需的会话句柄
+
+## 7. 可审核规则
+
+执行器返回成功，并不等于已经可以直接通过审核。
+
+要进入可通过审核状态，还必须额外满足：
+
+- 不是 `dry-run`
+- 执行归属正确
+- 变更文件没有超出路由范围
+- audit 最终结果为 `done`
+
+## 8. 当前限制
+
+执行器成功时返回的 `changed_files`，本质上仍然首先来自执行器自身报告，而不是完整独立的版本历史证明。
+
+CodeCGC 已经在 audit 层补充了工作区快照证据，但它还不是完整的 git 级差异证明系统。

package/codecgc/reference/external-capability-registry.json

@@ -0,0 +1,104 @@
+{
+  "version": 1,
+  "last_updated": "2026-05-03",
+  "capabilities": [
+    {
+      "id": "codexmcp",
+      "name": "Codex MCP",
+      "category": "executor",
+      "integration_type": "embedded-mcp",
+      "status": "integrated",
+      "required": true,
+      "owner": "CodeCGC",
+      "probe_kind": "executor",
+      "executor_target": "backend",
+      "mcp_server_names": ["codex"],
+      "description": "后端执行器，负责 backend build/fix 的实际编码。"
+    },
+    {
+      "id": "geminimcp",
+      "name": "Gemini MCP",
+      "category": "executor",
+      "integration_type": "embedded-mcp",
+      "status": "integrated",
+      "required": true,
+      "owner": "CodeCGC",
+      "probe_kind": "executor",
+      "executor_target": "frontend",
+      "mcp_server_names": ["gemini"],
+      "description": "前端执行器，负责 frontend build/fix 的实际编码。"
+    },
+    {
+      "id": "memos",
+      "name": "MemOS",
+      "category": "memory",
+      "integration_type": "external-mcp",
+      "status": "integrated",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["memos", "mem-os", "memos-mcp"],
+      "description": "持久记忆能力，使用官方 MemOS MCP；CodeCGC 只负责正式纳管、状态审计与协作约束，不重做记忆引擎本体。"
+    },
+    {
+      "id": "augment-search",
+      "name": "Augment Search Via Ace Tool",
+      "category": "code-search",
+      "integration_type": "external-mcp",
+      "status": "integrated",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["ace-tool", "augment", "auggie"],
+      "description": "代码检索与语义上下文增强能力，优先复用 ace-tool 这一现成 MCP 接入面；CodeCGC 只负责正式纳管、状态审计与协作约束，不重做检索引擎本体。"
+    },
+    {
+      "id": "github-mcp",
+      "name": "GitHub MCP",
+      "category": "scm",
+      "integration_type": "external-mcp",
+      "status": "integrated",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["github"],
+      "description": "源码托管、PR、issue 与发布协同能力，优先复用 github/github-mcp-server 官方 MCP；CodeCGC 只负责正式纳管、状态审计与协作约束，不重做 GitHub 平台能力本体。"
+    },
+    {
+      "id": "linear-mcp",
+      "name": "Linear MCP",
+      "category": "project-management",
+      "integration_type": "external-mcp",
+      "status": "integrated",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["linear", "linear-server"],
+      "description": "需求、任务、缺陷与项目节奏管理能力，优先复用 Linear 官方 remote MCP；CodeCGC 只负责正式纳管、状态审计与协作约束，不重做 Linear 平台能力本体。"
+    },
+    {
+      "id": "jira-mcp",
+      "name": "Jira Or Atlassian MCP",
+      "category": "project-management",
+      "integration_type": "external-mcp",
+      "status": "planned",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["jira", "atlassian"],
+      "description": "Atlassian / Jira 项目管理能力，当前仍保留为受控预留位，后续单独评估与纳管。"
+    },
+    {
+      "id": "sentry-mcp",
+      "name": "Sentry MCP",
+      "category": "observability",
+      "integration_type": "external-mcp",
+      "status": "planned",
+      "required": false,
+      "owner": "External",
+      "probe_kind": "workspace-mcp",
+      "mcp_server_names": ["sentry"],
+      "description": "线上异常、堆栈、事件追踪与问题回流能力。"
+    }
+  ]
+}

package/codecgc/reference/fix-flow.md

@@ -0,0 +1,94 @@
+# CodeCGC 问题修复流程
+
+## 1. 目的
+
+这份文档定义 `cgc-fix` 的标准行为。
+
+它是 CodeCGC 在问题修复场景下的受控执行流程。
+
+## 2. 适用范围
+
+`cgc-fix` 只处理范围已经足够收敛的问题修复工作。
+
+它必须：
+
+- 使用 `codecgc/issues/` 下的 issue 产物
+- 遵守 CodeCGC 的执行归属规则
+- 不绕过既有步骤契约直接自由执行
+
+## 3. 标准流程阶段
+
+`cgc-fix` 应按以下顺序推进：
+
+1. 定位 issue 上下文
+2. 检查修复范围与执行归属
+3. 选出当前唯一可执行的问题修复步骤
+4. 校验该步骤的 `codecgc` 契约
+5. 通过 `scripts/run_codecgc_task.py` 发起委派执行
+6. 收集结构化结果与 audit 路径
+7. 把结果交给 `cgc-review`
+
+## 4. 执行前检查
+
+在真正执行之前，Claude 必须确认：
+
+- 问题范围已经足够收敛
+- 当前修复只属于一个执行器
+- 当前步骤没有混合前端与后端工作
+- 当前步骤具备本地验证目标
+
+如果这些条件不满足，就必须回到规划或范围澄清，而不是继续执行。
+
+## 5. 步骤契约检查
+
+当前修复步骤必须包含合法的 `codecgc` 区块，至少包括：
+
+- `kind`
+- `task_id`
+- `task_summary`
+- `target_paths`
+- `constraints`
+- `acceptance`
+- `cd`
+
+只要步骤元数据缺失、混合或仍然模糊，就说明当前修复还不可执行。
+
+## 6. 委派规则
+
+执行必须通过：
+
+- `scripts/run_codecgc_flow_step.py`
+- `scripts/run_codecgc_task.py`
+
+这样才能保证执行器选择与项目路由模型保持一致。
+
+## 7. 结果采集规则
+
+`cgc-fix` 必须收集：
+
+- `success`
+- `task_id`
+- `SESSION_ID`
+- `summary`
+- `changed_files`
+- `policy_checks`
+- `risks`
+- `audit.path`
+
+audit 产物属于最小修复证据集的一部分。
+
+如果执行失败，必须先分类，再决定如何继续，例如：
+
+- 范围错误
+- 缺少设计或修复澄清
+- 环境或工具问题
+- 执行器失败
+
+## 8. 结束状态
+
+`cgc-fix` 只能结束在以下几种状态之一：
+
+- 已成功委派，等待 `cgc-review`
+- 已退回范围澄清
+- 被环境或工具问题阻塞
+- 因步骤不可执行而拒绝继续

package/codecgc/reference/fixture-governance.md

@@ -0,0 +1,60 @@
+# CodeCGC Fixture 治理
+
+## 1. 目的
+
+这份文档说明 CodeCGC 如何管理历史 demo、验证样例和行为检查工作流。
+
+## 2. 治理规则
+
+如果一个工作流存在的主要目的，是验证以下能力，而不是交付真实项目工作：
+
+- 路由
+- 状态推进
+- 审核回写
+- 结构化规划
+- 会话续跑
+- mixed-scope 阻断
+
+那么它就应归入 fixture 根目录，而不是 product 根目录。
+
+## 3. 目录规则
+
+验证样例及其 audit 应放在：
+
+- `codecgc/fixtures/features/`
+- `codecgc/fixtures/issues/`
+- `codecgc/fixtures/execution/`
+
+真实交付工作流应保留在：
+
+- `codecgc/features/`
+- `codecgc/issues/`
+- `codecgc/execution/`
+
+## 4. 历史迁移
+
+仓库当前已经提供历史 demo 迁移脚本：
+
+- `python scripts/migrate_demo_workflows_to_fixtures.py`
+
+这个脚本会把已知 demo 与验证工作流从 product 根目录迁入 fixture 根目录，并把它们的 `artifact_class` 改成 `fixture`。
+
+## 5. 当前仓库状态
+
+主要历史 demo 工作流已经迁入 fixture 根目录。
+
+这意味着：
+
+- fixture 根目录是当前运行时验证样例的规范位置
+
+## 6. 操作规则
+
+在创建新的样例工作流前，先判断：
+
+- 这是实际产品工作，还是运行时验证样例
+
+如果只是样例，应从一开始就使用：
+
+- `--artifact-class fixture`
+
+并直接把产物放进 fixture 根目录。

package/codecgc/reference/flow-execution.md

@@ -0,0 +1,65 @@
+# CodeCGC 流程执行入口
+
+## 1. 目的
+
+这份文档定义 `cgc-build` 与 `cgc-fix` 共享的步骤执行入口。
+
+两条流程都会通过：
+
+- `scripts/run_codecgc_flow_step.py`
+
+把当前可执行步骤交给运行时执行。
+
+## 2. 输入
+
+这个共享执行入口至少需要：
+
+- `flow`
+- `slug`
+- `step-number`
+
+可选输入：
+
+- `checklist-file`
+- `audit-root`
+- `timeout-seconds`
+- `dry-run`
+
+## 3. 解析规则
+
+如果没有显式传入 `checklist-file`，执行入口会自动从以下目录解析工作流文件：
+
+- `codecgc/features/{slug}/`
+- `codecgc/issues/{slug}/`
+
+当前查找顺序包括：
+
+- `{slug}-checklist.yaml`
+- `checklist.yaml`
+- `{slug}-fix.yaml`
+- `fix-checklist.yaml`
+
+## 4. 共享契约
+
+被解析出来的 YAML 文件，必须包含带有合法 `codecgc` 区块的步骤条目。
+
+这意味着 feature 与 issue 当前共享同一套机器可执行契约：
+
+- 面向人的步骤元信息
+- 面向运行时的 `codecgc` 执行元信息
+
+## 5. 产品规则
+
+当步骤契约已经存在时，`cgc-build` 与 `cgc-fix` 不应再手工重构执行器 prompt。
+
+它们应统一调用这个共享入口，然后读取：
+
+- 结构化执行结果
+- audit 产物
+
+## 6. 当前限制
+
+这个共享执行入口不负责创建 feature 或 issue 产物。
+
+它只负责执行一个已经准备好的步骤契约。
+产物创建、规划补全、审核回写仍然属于更上层工作流逻辑。

package/codecgc/reference/lifecycle-map.md

@@ -0,0 +1,172 @@
+# CodeCGC 生命周期地图
+
+## 1. 生命周期总览
+
+CodeCGC 当前采用下面这条交付闭环：
+
+1. Define
+2. Plan
+3. Build
+4. Verify
+5. Review
+6. Ship
+
+这不是“谁都能随时写代码”的自由协作模型，而是一条受控的软件交付链路。
+
+## 2. Define
+
+### 目标
+
+先说明到底要解决什么问题，以及边界在哪里。
+
+### 主要负责人
+
+- Claude
+
+### 常见输出
+
+- 问题定义
+- 用户可见范围
+- 非目标
+- 初步分类：feature / issue / refactor / roadmap
+
+### 退出条件
+
+当需求已经清晰到可以进入规划时，Define 阶段结束。
+
+## 3. Plan
+
+### 目标
+
+把诉求拆成可执行步骤，并为每一步确定明确归属。
+
+### 主要负责人
+
+- Claude
+
+### 常见输出
+
+- design 或 fix plan
+- 步骤拆解
+- 契约边界
+- 执行器归属
+- 步骤级验收标准
+
+### 退出条件
+
+每个执行步骤都必须达到：
+
+- 一个 owner
+- 一个 scope
+- 一个 acceptance target
+
+如果做不到，就不能进入 Build。
+
+## 4. Build
+
+### 目标
+
+真正产出代码改动。
+
+### 主要负责人
+
+- Gemini 负责前端
+- Codex 负责后端
+
+### Claude 的职责
+
+- 打包步骤
+- 调用正确执行器
+- 阻止混合范围执行
+
+### 退出条件
+
+执行器返回结构化结果，且结果对应当前步骤边界。
+
+## 5. Verify
+
+### 目标
+
+确认这一步不仅“写了代码”，而且“有证据说明做对了”。
+
+### 责任分工
+
+- Gemini 对前端工作提供前端可见行为证据
+- Codex 对后端工作提供后端测试或运行证据
+- Claude 判断这些证据是否满足步骤验收
+
+### 常见证据
+
+- 测试结果
+- 页面或交互确认
+- 变更文件列表
+- policy checks
+- 执行摘要
+
+### 退出条件
+
+证据已经足以进入 Review。
+
+## 6. Review
+
+### 目标
+
+判断这一步是否正确、是否越界、是否还存在后续风险。
+
+### 主要负责人
+
+- Claude
+
+### 典型审核问题
+
+- 是否调用了正确执行器
+- 是否遵守了路径边界
+- 是否满足当前步骤验收条件
+- 是否夹带了无关改动
+- 是否还需要进一步拆分跟进
+
+### 退出条件
+
+Claude 能明确做出：
+
+- 通过
+- 需修改
+- 回到设计或规划
+
+三者之一。
+
+## 7. Ship
+
+### 目标
+
+完成闭环，让当前工作流状态可以继续推进、合并或进入下一阶段。
+
+### 主要负责人
+
+- Claude
+
+### 常见输出
+
+- 验收结论
+- 工作流产物回写
+- 变更摘要
+- 残余风险
+- 下一步建议
+
+## 8. 角色覆盖总结
+
+| 阶段 | Claude | Gemini | Codex |
+|---|---|---|---|
+| Define | owner | 默认不参与 | 默认不参与 |
+| Plan | owner | 必要时被咨询 | 必要时被咨询 |
+| Build | controller | 前端 owner | 后端 owner |
+| Verify | 验收控制者 | 前端证据 owner | 后端证据 owner |
+| Review | owner | 按需补充 | 按需补充 |
+| Ship | owner | 默认不参与 | 默认不参与 |
+
+## 9. 产品原则
+
+Claude 覆盖全生命周期。
+
+Gemini 和 Codex 不覆盖全生命周期。
+它们只在自己负责的执行边界内拥有代码交付责任。

package/codecgc/reference/lifecycle-playbook.md

@@ -0,0 +1,104 @@
+# CodeCGC Lifecycle Playbook
+
+## 1. 目的
+
+这份文档定义 CodeCGC 在“从 0 到 1、从 1 到 2、长期维护”三种阶段下的统一使用方式。
+
+它补的是 `lifecycle-map.md` 的操作层。
+
+## 2. 三种阶段
+
+### 2.1 从 0 到 1
+
+适用场景：
+
+- 还没有 workflow
+- 还没有明确的 roadmap 或 feature / issue 资产
+
+优先入口：
+
+1. `cgc`
+2. `cgc-entry`
+3. `cgc-plan`
+
+目标：
+
+- 先把需求收敛成 feature / issue / roadmap 之一
+- 再进入可执行步骤
+
+### 2.2 从 1 到 2
+
+适用场景：
+
+- 已有 roadmap
+- 已有多个 feature / issue workflow
+- 已有 execution 审计沉淀
+
+优先入口：
+
+1. `cgc-lifecycle`
+2. `cgc-route`
+3. `cgc-build / cgc-fix / cgc-review`
+
+目标：
+
+- 判断当前是继续规划、继续执行、还是收尾审核
+- 避免在多个 workflow 并行时丢失当前主线
+
+### 2.3 长期维护
+
+适用场景：
+
+- 已经进入安装、发布、运维或生态接入阶段
+
+优先入口：
+
+1. `cgc-status`
+2. `cgc-doctor`
+3. `cgc-external-audit`
+4. `cgc-release-readiness`
+5. `cgc-lifecycle`
+
+目标：
+
+- 判断当前是环境问题、发布问题、外部接入问题，还是正常的交付推进
+
+## 3. 生命周期总览入口
+
+`cgc-lifecycle` 不负责直接执行 workflow。
+
+它只负责回答：
+
+- 当前仓库更像 setup-only、initiative-planning、planned-not-executed，还是 active-delivery
+- 当前 product / fixture 的 roadmap、workflow、execution 分布是什么
+- roadmap 是否已经继续拆成 child workflow，还是还停留在 initiative 层
+- 下一步更适合回到 `cgc`、`cgc-plan`、`cgc-route`，还是进入维护总检查链
+
+## 4. 使用规则
+
+如果你不知道当前仓库处在哪个阶段，优先跑：
+
+```bash
+cgc-lifecycle
+```
+
+如果你已经知道自己要继续某个 workflow，优先回到：
+
+```bash
+cgc-route --flow feature --slug <slug>
+```
+
+或：
+
+```bash
+cgc-route --flow issue --slug <slug>
+```
+
+## 5. 边界
+
+`cgc-lifecycle` 是总览，不是调度器。
+
+真正的执行、审核、发布与维护，仍然分别归：
+
+- `cgc-entry / cgc-plan / cgc-build / cgc-fix / cgc-review / cgc-route`
+- `cgc-status / cgc-doctor / cgc-package-audit / cgc-external-audit / cgc-release-readiness`