@hunyed15/codecgc 0.1.0

package/codecgc/reference/artifact-class-policy.md

@@ -0,0 +1,81 @@
+# CodeCGC 产物类别策略
+
+## 1. 目的
+
+这份文档说明 CodeCGC 如何区分真实产品产物与本地验证 fixture。
+
+## 2. 允许值
+
+当前支持的 `artifact_class` 只有两种：
+
+- `product`
+- `fixture`
+
+## 3. 默认规则
+
+通过 `init` 或 `plan` 创建的新工作流产物，默认都属于：
+
+- `artifact_class: product`
+
+这代表正常的仓库交付意图。
+
+## 4. Fixture 规则
+
+只有当一个工作流的主要目的，是验证运行时行为而不是交付真实项目工作时，才应使用：
+
+- `artifact_class: fixture`
+
+## 5. 当前存储规则
+
+`product` 产物当前放在：
+
+- `codecgc/features/`
+- `codecgc/issues/`
+
+`fixture` 产物当前放在：
+
+- `codecgc/fixtures/features/`
+- `codecgc/fixtures/issues/`
+
+因此 `artifact_class` 仍然是机器可读的意图标记，而 fixture 现在也有自己独立的目录根。
+
+## 6. 审计传播规则
+
+当 checklist 或 fix 产物里声明了 `artifact_class` 时，运行时会把它继续传播到 audit 的：
+
+- `source.artifact_class`
+
+当前规则是：
+
+- `product` audit 默认写入 `codecgc/execution/`
+- `fixture` audit 默认写入 `codecgc/fixtures/execution/`
+
+这样后续工具就能区分：
+
+- 真实产品执行证据
+- fixture 验证执行证据
+
+## 7. 操作规则
+
+如果一个工作流只是为了验证：
+
+- 路由
+- 审核回写
+- 状态推进
+- 结构化规划
+
+那么就应使用：
+
+- `--artifact-class fixture`
+
+否则保持默认的 `product`。
+
+## 8. 历史修复规则
+
+如果旧 audit 仍然保留在错误目录或仍含旧路径信息，可以使用：
+
+- `python scripts/normalize_codecgc_audits.py`
+
+如果旧 demo 工作流还停留在产品目录下，可以使用：
+
+- `python scripts/migrate_demo_workflows_to_fixtures.py`

package/codecgc/reference/build-flow.md

@@ -0,0 +1,95 @@
+# CodeCGC 功能开发流程
+
+## 1. 目的
+
+这份文档定义 `cgc-build` 的标准行为。
+
+它是 CodeCGC 在功能开发场景下的受控执行流程。
+
+## 2. 适用范围
+
+`cgc-build` 只处理“需求已经足够清晰、可以进入执行”的新能力开发工作。
+
+它必须：
+
+- 使用 `codecgc/features/` 下的 feature 产物
+- 遵守 CodeCGC 的执行归属规则
+- 不绕过既有步骤契约直接自由执行
+
+## 3. 标准流程阶段
+
+`cgc-build` 应按以下顺序推进：
+
+1. 定位或初始化 feature 上下文
+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`
+
+不要在已有合法步骤契约的情况下，手工重拼执行器 prompt 直接发起执行。
+
+## 7. 结果采集规则
+
+`cgc-build` 必须收集：
+
+- `success`
+- `task_id`
+- `SESSION_ID`
+- `summary`
+- `changed_files`
+- `policy_checks`
+- `risks`
+- `audit.path`
+
+audit 产物属于执行证据的一部分。
+后续审核不能只依赖自由文本聊天结果。
+
+如果执行失败，`cgc-build` 不能静默继续，而必须分类失败原因，例如：
+
+- 范围错误
+- 设计缺口
+- 环境或工具问题
+- 执行器失败
+
+## 8. 结束状态
+
+`cgc-build` 只能结束在以下几种状态之一：
+
+- 已成功委派，等待 `cgc-review`
+- 已退回规划或设计
+- 被环境或工具问题阻塞
+- 因步骤不可执行而拒绝继续

package/codecgc/reference/checklist-contract.md

@@ -0,0 +1,103 @@
+# CodeCGC Checklist Contract
+
+## 1. 目的
+
+design 文档首先是给人看的。
+checklist contract 首先是给执行系统看的。
+
+因此，一个真正会改代码的 CodeCGC 步骤，应该带有一个 `codecgc` 块，明确声明这一步的机器执行边界。
+
+## 2. 必填字段
+
+`codecgc` 块至少要定义：
+
+- `kind`
+- `task_id`
+- `task_summary`
+- `target_paths`
+- `constraints`
+- `acceptance`
+- `cd`
+
+可选字段包括：
+
+- `codex_sandbox`
+- `gemini_sandbox`
+- `model`
+- `profile`
+- `SESSION_ID`
+
+## 3. 字段规则
+
+### `kind`
+
+只能是：
+
+- `frontend`
+- `backend`
+- `auto`
+
+其中 `auto` 只表示“运行时可进一步判定”，不表示可以放弃边界控制。
+
+### `target_paths`
+
+必须是当前步骤允许修改的最小文件范围。
+
+不要写成整个模块、整个应用或宽泛目录，除非该步骤本身确实只允许那样的范围。
+
+### `task_summary`
+
+只能描述当前这一步，不要把后续步骤一起塞进去。
+
+### `constraints`
+
+这里写的是硬约束，不是愿景描述。
+
+好的约束应接近：
+
+- 不能修改哪些文件
+- 不能跨到哪个层
+- 不能顺手做什么额外重构
+
+### `acceptance`
+
+验收条件必须能在当前步骤内被检查，而不是依赖未来步骤。
+
+## 4. 何时拒绝生成 contract
+
+遇到下面这些情况，不应该勉强附一个宽泛 `codecgc` 块：
+
+- 当前步骤混合了前端和后端范围
+- 当前步骤包含 shared 路径
+- 仍然存在未拍板设计选择
+- 无法明确给出 `target_paths`
+
+这种情况下，正确做法不是“先执行再说”，而是先拆分或回到设计。
+
+## 5. 示例
+
+```yaml
+steps:
+  - action: "仅实现登录页 UI"
+    exit_signal: "前端执行器返回结构化摘要"
+    status: pending
+    codecgc:
+      kind: frontend
+      task_id: login-ui-step-1
+      task_summary: "仅实现已确认范围内的登录页 UI。"
+      target_paths:
+        - frontend/login-page.tsx
+      constraints:
+        - 不要修改 target_paths 之外的文件。
+        - 不要改动后端 API。
+      acceptance:
+        - 登录页 UI 满足当前步骤已确认的范围。
+      cd: .
+      gemini_sandbox: false
+```
+
+## 6. 使用原则
+
+可以把 checklist contract 理解成“Claude 发给执行器的最小合法任务包”。
+
+如果这个任务包写不清楚，说明步骤本身还没准备好，不应该把问题转嫁给执行器。

package/codecgc/reference/execution-audit.md

@@ -0,0 +1,121 @@
+# CodeCGC 执行审计
+
+## 1. 目的
+
+这份文档定义委派执行后生成的 audit 产物。
+
+当前写入入口：
+
+- `scripts/run_codecgc_task.py`
+
+每一次委派的 `build` 或 `fix` 执行，都应生成一个 audit 文件。
+
+## 2. 当前存放位置
+
+审计文件默认存放在：
+
+- `codecgc/execution/`
+
+如果工作流属于 fixture，则会写入：
+
+- `codecgc/fixtures/execution/`
+
+## 3. 文件规则
+
+每次执行写入一个 JSON 文件：
+
+- `{task_id}.json`
+
+当同一个 `task_id` 被再次执行时，应覆盖旧文件，而不是无限追加。
+
+## 4. 顶层必要字段
+
+每个 audit 文件至少必须包含：
+
+- `product`
+- `version`
+- `mode`
+- `timestamp`
+- `task_id`
+- `target`
+- `tool_name`
+- `target_paths`
+- `route_notes`
+- `routing_file`
+- `source`
+- `task_summary`
+- `constraints`
+- `acceptance_criteria`
+- `cd`
+- `requested_session_id`
+- `result`
+
+## 5. `result` 区块
+
+`result` 区块至少必须包含：
+
+- `success`
+- `outcome`
+- `task_id`
+- `session_id`
+- `summary`
+- `changed_files`
+- `policy_checks`
+- `risks`
+- `error`
+
+`source` 区块当前也可能携带：
+
+- `artifact_class`
+
+## 6. `file_evidence` 区块
+
+`file_evidence` 当前用于补充本地证据，应尽量包含：
+
+- `evidence_source`
+- `workspace_changed_files`
+- `verified_changed_files`
+- `out_of_scope_changed_files`
+- `file_diffs`
+- `evidence_confidence`
+
+当可用时，`file_diffs` 还会总结本地观察到的文件变化，例如：
+
+- `path`
+- `change_type`
+- `before_hash`
+- `after_hash`
+- `before_size`
+- `after_size`
+- `before_preview`
+- `after_preview`
+- `in_scope`
+
+## 7. 允许的结果值
+
+当前常见 `outcome` 包括：
+
+- `done`
+- `split-required`
+- `design-gap`
+- `blocked`
+- `executor-failure`
+
+## 8. 审核契约
+
+`cgc-review` 在验收前必须读取 audit 文件。
+
+audit 是最小机器可读执行证据，至少回答这些问题：
+
+- 哪个执行器执行了当前步骤
+- 路由到的是哪些路径
+- 执行返回了什么结果
+- 哪些策略检查通过或失败了
+- 当前步骤是否具备进入审核的证据基础
+
+## 9. 非目标
+
+audit 不是最终验收报告。
+
+它只负责执行证据层。
+最终验收、回写和发布判断仍然属于 Claude。

package/codecgc/reference/execution-model.md

@@ -0,0 +1,118 @@
+# CodeCGC 执行模型
+
+## 1. 目的
+
+CodeCGC 把“工作流控制”和“代码执行”明确分层。
+
+工作流层决定：
+
+- 当前在做哪一步
+- 这一步是否已经可执行
+- 这一步应该交给哪个模型
+
+执行层负责：
+
+- 通过 MCP 调用正确执行器
+- 落地代码改动
+- 产出可审核的结构化证据
+
+## 2. 当前运行链路
+
+当前标准链路如下：
+
+1. 用户通过 `cgc` 或 `cgc-entry` 进入工作流
+2. Claude 读取现有工作流产物
+3. Claude 识别当前唯一可推进的执行步骤
+4. Claude 将步骤打包为机器可执行任务
+5. 运行时调用对应的执行入口
+6. 执行入口再桥接到底层任务执行脚本
+7. MCP 将任务委托给 Gemini 或 Codex
+8. 执行结果被写入 audit 产物
+9. Claude 基于 audit、步骤契约和工作流状态继续审核与回写
+
+简化理解：
+
+- Claude 决定“做什么、何时做、交给谁”
+- Gemini / Codex 负责“按边界把代码做出来”
+
+## 3. 路由输入
+
+路由规则主要声明在：
+
+- `model-routing.yaml`
+
+运行时 guardrail 主要声明在：
+
+- `.mcp.json`
+- `.claude/settings.json`
+- `.claude/hooks/route-edit.ps1`
+
+这些文件一起负责“不能越界”。
+
+## 4. 允许的执行结果
+
+一个代码步骤最终只允许落在下面这些状态之一：
+
+- `ready`：单模型范围明确，可以立即执行
+- `split-required`：前后端混合或 shared 范围，必须先拆分
+- `design-gap`：步骤描述不足，仍需补设计
+- `blocked`：环境、权限或工具阻塞
+- `done`：执行器已经返回完整结果
+
+这些状态不是面向用户的产品口语，而是运行时判断的机器语义。
+
+从 `P6-1` 开始，`split-required` 不再只是一个阻断码。
+当运行时能明确看出哪些路径属于前端、后端或 shared 时，还会额外返回结构化拆分建议，供单入口恢复链和 `cgc-plan` 继续复用。
+
+## 5. 什么叫“可执行步骤”
+
+只有同时满足下面条件，步骤才算真正 ready：
+
+- 只属于一个执行器
+- 不包含 shared 或 mixed 范围
+- `target_paths` 足够小且明确
+- 有当前步骤自己的验收标准
+- 没有把未来工作偷偷塞进当前执行
+
+如果做不到这一点，就不该执行，而应该回到拆分或设计。
+
+## 6. 执行器契约
+
+当前前端执行器是：
+
+- `implement_frontend_task`
+
+当前后端执行器是：
+
+- `implement_backend_task`
+
+执行器返回结果时，至少应包含：
+
+- `success`
+- `task_id`
+- `SESSION_ID`
+- `summary`
+- `changed_files`
+- `policy_checks`
+- `risks`
+
+运行时必须把这些字段持久化到 audit 中，供后续审核使用。
+
+参见：
+
+- `codecgc/reference/execution-audit.md`
+- `codecgc/reference/executor-contract.md`
+
+## 7. 产品原则
+
+CodeCGC 不相信“提示词里说了不要越界”就足够。
+
+正确顺序必须是：
+
+1. 先定义流程
+2. 再生成机器可读步骤契约
+3. 再触发 MCP 执行
+4. 再用 hook 和审核控制做兜底
+
+文档负责解释系统。
+流程控制负责真正约束系统。

package/codecgc/reference/execution-routing.md

@@ -0,0 +1,130 @@
+# CodeCGC 执行路由
+
+## 1. 目的
+
+这份文档定义 CodeCGC 如何对“会改代码的工作”做执行路由。
+
+它不是命名建议，而是执行归属规则。
+
+## 2. 主路由规则
+
+### 前端
+
+当变更主要影响以下范围时，路由给 Gemini：
+
+- 页面
+- 组件
+- 样式
+- 前端状态
+- 客户端交互
+- 浏览器可见行为
+- 前端测试
+
+### 后端
+
+当变更主要影响以下范围时，路由给 Codex：
+
+- 服务
+- API
+- 仓储层
+- 定时任务
+- 持久化
+- 后端领域逻辑
+- 脚本与自动化
+- 后端测试
+
+## 3. 共享范围不能直接执行
+
+如果一个步骤同时触达前端和后端，或者触达真正被两侧共同依赖的共享契约，那么这个步骤不能直接执行。
+
+Claude 必须先拆分。
+
+## 4. 三类共享范围
+
+### 前端内部共享
+
+示例：
+
+- 前端 design token
+- UI 原语
+- 仅前端使用的工具库
+
+默认路由：
+
+- Gemini
+
+### 后端内部共享
+
+示例：
+
+- 后端领域类型
+- 服务端共享工具
+- 数据访问共享能力
+
+默认路由：
+
+- Codex
+
+### 跨边界共享
+
+示例：
+
+- 请求或响应契约
+- 前后端共同消费的类型
+- 事件载荷
+- 需要 API 与 UI 同时对齐的行为
+
+默认路由：
+
+- Claude 先拆分，不直接派给执行器
+
+## 5. 标准拆分模式
+
+跨边界工作通常应被拆成：
+
+1. 契约或设计步骤
+2. 后端实现步骤
+3. 前端实现步骤
+4. 审核与验收步骤
+
+不要把一个宽泛的混合任务直接丢给执行器。
+
+## 6. 路径规则
+
+机器可读的路径映射定义在：
+
+- `model-routing.yaml`
+
+这个文件负责机器路由。
+这份文档负责人类可读的归属说明。
+
+## 7. 可执行前检查
+
+在真正 dispatch 之前，Claude 必须能对下面每一项回答“是”：
+
+- 当前步骤是否只有一个执行器
+- 是否有最小且明确的目标路径集合
+- 是否避免了前后端混合范围
+- 是否避免了未拆分的共享范围
+- 是否拥有步骤级验收条件
+
+只要其中一项是否，当前步骤就不能执行。
+
+## 8. 执行后审核归属
+
+执行完成后：
+
+- Gemini 或 Codex 提供实现证据
+- Claude 决定该步骤是否通过审核
+
+执行归属和审核归属不是同一件事。
+
+## 9. 产品原则
+
+路由不是“模型偏好”问题。
+
+路由的本质是稳定的软件所有权：
+
+- Claude 负责控制与审核
+- Gemini 负责前端实现
+- Codex 负责后端实现