@hunyed15/codecgc 0.1.0

package/codecgc/reference/long-lived-artifacts.md

@@ -0,0 +1,98 @@
+# CodeCGC 长期产物说明
+
+## 1. 目的
+
+这份文档说明 `codecgc/` 里哪些目录属于“长期项目记忆”，哪些只是交付过程产物。
+
+简单说：
+
+- `feature / issue / execution` 更像交付过程状态
+- `requirements / architecture / roadmap / compound` 更像长期产品记忆
+
+## 2. 四类长期产物
+
+### Requirements
+
+路径：
+
+- `codecgc/requirements/`
+
+用途：
+
+- 保存当前已经生效的稳定需求
+- 记录产品或模块当前边界
+
+### Architecture
+
+路径：
+
+- `codecgc/architecture/`
+
+用途：
+
+- 保存系统地图
+- 记录当前真实架构状态
+
+### Roadmap
+
+路径：
+
+- `codecgc/roadmap/`
+
+用途：
+
+- 保存超出单个 feature 范围的阶段性规划
+- 记录后续要继续拆分的 initiative 级设计
+
+### Compound
+
+路径：
+
+- `codecgc/compound/`
+
+用途：
+
+- 保存跨多个视角的组合型长期产物
+- 例如 operating model、capability matrix、productization gap
+
+## 3. 写文档前先问一个问题
+
+先判断这份内容到底是在描述什么：
+
+- 如果描述的是“某一步怎么交付”，它应该留在交付流里
+- 如果描述的是“这个项目当前长期成立的事实”，它应该进入长期产物目录
+
+交付流目录包括：
+
+- `codecgc/features/`
+- `codecgc/issues/`
+- `codecgc/execution/`
+
+fixture 目录包括：
+
+- `codecgc/fixtures/features/`
+- `codecgc/fixtures/issues/`
+- `codecgc/fixtures/execution/`
+
+参见：
+
+- `codecgc/reference/fixture-governance.md`
+
+## 4. 回写原则
+
+正常顺序应当是：
+
+1. 先在 feature / issue 中完成规划、执行、审核
+2. 再从交付结果里提炼稳定知识
+3. 最后把稳定知识回写到长期产物目录
+
+不要在交付范围还不清楚时，先写一堆长期文档抢占真相。
+
+## 5. 当前使用规则
+
+如果同一份信息同时满足下面两个条件，就应该优先考虑写入长期目录：
+
+- 它会在后续多个会话中被反复引用
+- 它已经不再依赖某个单独步骤是否完成
+
+这类文档的价值不是“记录一次过程”，而是“降低未来恢复上下文的成本”。

package/codecgc/reference/operation-guide.md

@@ -0,0 +1,242 @@
+# CodeCGC 操作指南
+
+## 1. 目的
+
+这份文档是 CodeCGC 的本地使用实操指南。
+
+统一产品命令面是：
+
+- `cgc`
+- `cgc-install`
+- `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`
+- `cgc-lifecycle`
+
+底层实现入口如 `scripts/codecgc_cli.py`、`scripts/route_codecgc_workflow.py` 只属于维护者调试层。
+
+默认原则：
+
+- 日常使用优先走 `cgc-*`
+- 调试运行时本身时再看 Python 脚本入口
+
+## 2. 首次接入顺序
+
+如果你是第一次把 CodeCGC 接入某个项目，建议顺序是：
+
+1. 在目标项目根目录运行 `cgc-install`
+2. 运行 `cgc-status`，必要时再运行 `cgc-doctor`
+3. 用 `cgc "<自然语言需求>"` 或 `cgc-entry` 开始
+
+最小示例：
+
+```bash
+cgc-install
+cgc-status
+cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
+```
+
+如果当前 shell 目录不是目标项目根目录：
+
+```bash
+cgc-install --workspace D:\Projects\MyApp
+cgc-status --workspace D:\Projects\MyApp
+```
+
+## 3. 什么时候切到明确子命令
+
+只有在阶段已经明确时，才切到工作流子命令：
+
+- `cgc-plan`：还需要规划或澄清
+- `cgc-build` / `cgc-fix`：当前步骤已具备执行条件
+- `cgc-review`：已经存在 audit，等待审核决策
+- `cgc-route`：只想知道下一步推荐命令
+- `cgc-external-audit`：只想看外部能力接入状态
+- `cgc-release-readiness`：发布或长期维护前做总检查
+- `cgc-lifecycle`：快速判断仓库现在处于哪个生命周期阶段
+
+## 4. 主命令用法
+
+### 4.1 单入口
+
+```bash
+cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
+cgc "继续刚刚的工作"
+cgc --request "现在下一步该做什么"
+cgc --latest
+```
+
+`cgc` 是意图优先入口，默认输出更适合人直接阅读的摘要。
+
+如果需要完整结构化结果，使用：
+
+```bash
+cgc-entry --request "新增一个登录页面，放在 src/components/LoginForm.tsx"
+```
+
+### 4.2 规划
+
+```bash
+cgc-plan --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend
+cgc-plan --flow issue --slug demo-sync-bug --summary "Demo sync bug fix" --target-path backend/src/sync.py --kind backend
+```
+
+当结构化信息已知时，优先显式传入目标、范围、验收和风险，而不是只给最短摘要。
+
+## 5. `plan` 的当前行为
+
+`cgc-plan` 当前不仅会建骨架，还会做步骤塑形：
+
+- 前后端混合目标路径会拆成多个可执行步骤
+- 共享或未知路径会转成仅规划步骤
+- 只要仍存在仅规划步骤，`route` 就会继续把流程留在 `cgc-plan`
+- 每个可执行步骤都可以拥有自己的 action、task summary 与 acceptance
+
+`plan` 还会返回 `planning_status`，当前常见值包括：
+
+- `ready-for-build`
+- `ready-for-fix`
+- `needs-clarification`
+- `needs-roadmap`
+
+## 6. 执行步骤
+
+```bash
+cgc-build --slug 2026-05-01-demo-login-ui --step-number 1 --dry-run
+cgc-fix --slug 2026-05-01-demo-sync-bug --step-number 1 --dry-run
+```
+
+`build` 与 `fix` 当前不会只返回简单成功/失败，而会补充：
+
+- `state`
+- `failure_type`
+- `recommended_command`
+- `next`
+- `audit_path`
+
+当未显式传入 `--step-number` 时，运行时会自动选择下一个可执行的 `pending` 步骤。
+
+## 7. 审核回写
+
+```bash
+cgc-review --audit-file codecgc/execution/demo-login-ui-step-1.json --decision accepted
+```
+
+`review` 现在是审核控制点，而不是单纯回写助手。
+
+它会在以下场景把请求的 `accepted` 降级为 `changes-requested`：
+
+- 只有 `dry-run`
+- 执行器归属不匹配
+- 变更文件越界
+- 执行器没有成功返回 `done`
+- 本地证据与执行器自报不一致
+
+审核回写后，匹配步骤的状态也会同步更新：
+
+- `accepted` -> `done`
+- `changes-requested` -> `pending`
+
+## 8. 路由判断
+
+```bash
+cgc-route --flow feature --slug 2026-05-01-demo-login-ui
+```
+
+`route` 当前会综合三层证据：
+
+- 工作流产物完整性
+- 当前步骤最近一次执行 audit
+- acceptance / fix-note 中最近一次审核结论
+
+常见结果包括：
+
+- 推荐 `cgc-build` 或 `cgc-fix`
+- 推荐 `cgc-review`
+- 不再推荐任何命令，表示当前流程已关闭
+
+对于多步骤工作流，`route` 现在会优先跟随“当前 pending 步骤”，而不是简单相信历史上最后一次审核结果。
+
+## 9. 推荐操作闭环
+
+推荐顺序始终是：
+
+1. `cgc-plan`
+2. 必要时补全或细化产物
+3. `cgc-build` 或 `cgc-fix`
+4. 检查 audit
+5. `cgc-review`
+
+## 10. 维护与发布检查
+
+如果你当前不是在推进某个 feature / issue，而是在维护 CodeCGC 本身，建议改用下面这条链路：
+
+1. `cgc-status`
+2. `cgc-doctor`
+3. `cgc-package-audit`
+4. `cgc-external-audit`
+5. `cgc-release-readiness`
+6. `cgc-lifecycle`
+
+其中：
+
+- `cgc-external-audit` 用来判断第三方能力是否处于“正式接入 / 规划中 / 本地漂移”哪一种状态
+- `cgc-release-readiness` 用来把安装、运行时、发布包、外部接入与生命周期资产汇总成一个结论
+- `cgc-lifecycle` 用来把 roadmap、workflow 与 execution 当前分布汇总成生命周期阶段
+
+## 11. Fixture 与历史修复
+
+如果只是创建验证样例工作流，应使用：
+
+```bash
+python scripts/codecgc_cli.py init --flow feature --slug fixture-demo --summary "Fixture demo" --artifact-class fixture
+```
+
+如果历史 audit 仍在错误目录或保留旧路径，可运行：
+
+```bash
+python scripts/normalize_codecgc_audits.py
+```
+
+如果历史 demo 工作流仍在 product 目录，可运行：
+
+```bash
+python scripts/migrate_demo_workflows_to_fixtures.py
+```
+
+如果历史 acceptance / fix-note 缺少或保留旧审核策略字段，可运行：
+
+```bash
+python scripts/refresh_codecgc_review_policy.py --write
+```
+
+这属于维护修复命令，不是普通用户日常主流程。
+
+## 12. 产品规则
+
+`cgc-plan`、`cgc-build`、`cgc-fix`、`cgc-review`、`cgc-route` 必须共同遵守同一套运行时时序。
+
+技能层定义工作流规则。
+CLI 层提供本地执行便利。
+
+## 13. 底层调试入口
+
+以下入口只在维护 CodeCGC 自身、调试产品壳、或直接验证运行时层时使用：
+
+```bash
+python scripts/codecgc_cli.py entry --request "新增一个登录页面，放在 src/components/LoginForm.tsx"
+python scripts/codecgc_cli.py plan --flow feature --slug demo-login-ui --summary "Demo login UI feature" --target-path src/components/LoginForm.tsx --kind frontend
+python scripts/codecgc_cli.py build --slug 2026-05-01-demo-login-ui --step-number 1 --dry-run
+python scripts/codecgc_cli.py fix --slug 2026-05-01-demo-sync-bug --step-number 1 --dry-run
+python scripts/codecgc_cli.py review --audit-file codecgc/execution/demo-login-ui-step-1.json --decision accepted
+python scripts/codecgc_cli.py route --flow feature --slug 2026-05-01-demo-login-ui
+python scripts/route_codecgc_workflow.py --flow feature --slug 2026-05-01-demo-login-ui
+```

package/codecgc/reference/release-maintenance-playbook.md

@@ -0,0 +1,150 @@
+# CodeCGC Release / Maintenance / Ops Playbook
+
+## 1. 目的
+
+这份文档定义 CodeCGC 在发布、长期维护、以及运维接入前的最小可执行闭环。
+
+它不是 roadmap，也不是一次性 feature 设计稿。
+它回答的是：
+
+- 发布前要检查什么
+- 长期维护时要怎么判断系统是否健康
+- 运维与外部系统接入时，哪些检查必须先通过
+
+## 2. 三条入口命令
+
+维护者优先使用下面这组命令：
+
+- `cgc-status`
+- `cgc-doctor`
+- `cgc-package-audit`
+- `cgc-external-audit`
+- `cgc-release-readiness`
+
+其中：
+
+- `cgc-status` 看项目级集成是否已同步
+- `cgc-doctor` 看 Python、MCP、执行器和项目级集成是否可运行
+- `cgc-package-audit` 看发布包是否覆盖运行时依赖与发布元数据
+- `cgc-external-audit` 看第三方能力白名单与本地 MCP 观测状态
+- `cgc-release-readiness` 做总检查汇总，并补充仓库内 deploy / release 信号感知
+
+## 3. 发布前顺序
+
+建议固定按这个顺序执行：
+
+1. `cgc-status`
+2. `cgc-doctor`
+3. `cgc-package-audit`
+4. `cgc-external-audit`
+5. `cgc-release-readiness`
+
+只有当前一项没有阻塞时，才进入下一项。
+
+## 4. 长期维护顺序
+
+当你不是在发布，而是在维护已有安装面时，优先顺序改成：
+
+1. `cgc-status`
+2. `cgc-doctor`
+3. `cgc-external-audit`
+4. 必要时 `cgc-release-readiness`
+
+原因是长期维护时，最常见的问题不是“包漏文件”，而是：
+
+- 目标项目级集成漂移
+- 本机 Python 或 MCP 运行时变化
+- 新增了第三方 MCP，但没有登记到 CodeCGC 白名单
+
+## 5. 运维接入规则
+
+当需要接入 GitHub、Linear、Jira、Sentry、MemOS 或代码检索能力时，遵守下面规则。
+
+当前项目已经明确：
+
+- `Jira / Atlassian MCP` 不进入现阶段主线
+- `Sentry MCP` 不进入现阶段主线
+
+也就是说，下面规则目前主要作用于已经纳管的 `MemOS / ace-tool / GitHub / Linear`，以及未来如果你主动决定再启用 `Jira` 或 `Sentry` 的情况：
+
+1. 先把接入意图写进 `codecgc/reference/external-capability-registry.json`
+2. 再把项目级或用户级 `.mcp.json` 接入做好；对 `MemOS`，优先直接使用官方 `memos-mcp`
+3. 最后用 `cgc-external-audit` 检查“登记状态”和“本地观测状态”是否一致
+
+如果跳过第 1 步，CodeCGC 不把该接入视为正式产品能力。
+
+`MemOS` 的特殊边界是：
+
+- Claude 本身已经可以直接使用官方 `memos-mcp`
+- CodeCGC 不再额外包一层记忆服务
+- CodeCGC 只负责把它纳入正式白名单、状态审计与长期协作约束
+
+`Augment` 的特殊边界是：
+
+- Claude 本身已经可以直接使用 `ace-tool` 这一现成 MCP 接入面
+- CodeCGC 不再额外包一层代码检索服务
+- CodeCGC 只负责把它纳入正式白名单、状态审计与长期协作约束
+
+`GitHub MCP` 的特殊边界是：
+
+- Claude 本身已经可以直接使用 `github/github-mcp-server` 官方 MCP
+- CodeCGC 不再额外包一层 GitHub 服务
+- CodeCGC 只负责把它纳入正式白名单、状态审计与长期协作约束
+
+`Linear MCP` 的特殊边界是：
+
+- Claude 本身已经可以直接使用 Linear 官方 remote MCP
+- CodeCGC 不再额外包一层 Linear 服务
+- CodeCGC 只负责把它纳入正式白名单、状态审计与长期协作约束
+
+`Jira / Atlassian MCP` 当前边界是：
+
+- 当前不接入
+- 不视为 CodeCGC 当前可用态的缺失
+- 只有未来明确服务 Jira 体系团队时，才重新纳入评估
+
+`Sentry MCP` 当前边界是：
+
+- 当前不接入
+- 它属于 post-release observability 能力
+- 不视为 CodeCGC 当前可用态的缺失
+
+## 6. 退出条件
+
+只有同时满足下面条件，才算进入“可发布 / 可长期维护 / 可继续扩接”的状态：
+
+- `cgc-status` 无阻塞
+- `cgc-doctor` 无阻塞
+- `cgc-package-audit` 无阻塞
+- `cgc-external-audit` 无阻塞
+- `cgc-release-readiness` 总结论为通过
+
+## 7. 边界
+
+CodeCGC 自己只负责：
+
+- 工作流控制
+- 执行器分工
+- 审计与 review
+- 命令与安装壳
+- 外部能力白名单与接入状态治理
+
+CodeCGC 不负责自己重做：
+
+- 记忆引擎
+- 代码检索引擎
+- GitHub / PM / 监控平台本体
+
+这些能力都应优先复用成熟产品，并受 CodeCGC 的白名单与接入审计约束。
+
+## 8. Deploy 信号感知
+
+`cgc-release-readiness` 现在还会额外检查仓库内是否存在下面这类信号：
+
+- GitHub Actions workflow
+- Dockerfile
+- docker compose / compose
+- deploy / release 脚本
+- `.env.example` 等运行时配置样例
+
+这层当前只负责判断仓库有没有“已经开始考虑发布/部署”的迹象，不直接接通具体部署平台。

package/codecgc/reference/review-writeback.md

@@ -0,0 +1,141 @@
+# CodeCGC 审核回写
+
+## 1. 目的
+
+这份文档说明 `cgc-review` 如何在委派执行完成后，把审核结果写回工作流产物。
+
+当前主入口：
+
+- `scripts/write_codecgc_review.py`
+
+## 2. 输入
+
+审核回写至少需要：
+
+- `audit-file`
+- `decision`
+
+可选输入：
+
+- `risk`
+- `next-step`
+- `force`
+
+## 3. 回写目标
+
+脚本会从 audit 的 `source` 区块解析回写目标。
+
+当前映射规则：
+
+- feature audit -> `{slug}-acceptance.md`
+- issue audit -> `{slug}-fix-note.md`
+
+## 4. 审核规则
+
+审核不等于“执行成功”。
+
+回写结果必须覆盖这些事实：
+
+- 当前执行步骤是否通过审核
+- 执行归属是否正确
+- 实际发生了哪些变更
+- 剩余风险是什么
+- 下一步应该回到哪个阶段
+
+当出现以下情况时，即使请求的是 `accepted`，审核也必须降级为 `changes-requested`：
+
+- 本次只有 `dry-run`
+- 执行器归属与路由目标不一致
+- 变更文件超出 `target_paths`
+- 真实执行后没有观察到已验证的范围内变更
+- 执行器没有返回成功的 `done` 结果
+
+## 5. 当前输出契约
+
+高层审核入口当前会返回：
+
+- `requested_decision`
+- `final_decision`
+- `review_state`
+- `recommended_command`
+- `recommended_action_kind`
+- `fallback_stage`
+- `policy_reason`
+- `scope_check`
+- `executor_check`
+- `verification`
+- `remaining_risk`
+- `next_step`
+
+这些字段属于长期稳定的审核结果契约，供：
+
+- `cgc-review`
+- `cgc-route`
+- `cgc-entry`
+- `operator_brief.machine_next_action`
+
+共同消费。
+
+## 6. 回写内容
+
+审核回写除了更新 acceptance / fix-note 正文，还会同步：
+
+- 当前被审核的 `task_id`
+- 当前被审核的 `step_number`
+- 当前步骤的 checklist / fix YAML 状态
+
+状态推进规则：
+
+- `accepted` -> `done`
+- `changes-requested` -> `pending`
+
+这样 `route / explain / continue` 才能在多步骤工作流中，把审核结论匹配回正确步骤。
+
+## 7. 证据策略
+
+只有真实执行结果才能成为“可通过审核”的证据。
+
+`dry-run` audit 仍然可以写回供检查使用，但不能被视为可直接通过审核的证据。
+
+当本地工作区证据存在时，审核优先使用本地证据，而不是只信执行器自报的 `changed_files`。
+
+当前还会补充这些证据字段：
+
+- `evidence_confidence`
+- `risk_classes`
+- `Observed file diffs`
+- `Local evidence available`
+- `Reported vs local evidence alignment`
+
+如果执行器自报与本地证据不一致，审核必须降级。
+
+## 8. 回退阶段
+
+审核策略当前明确区分 4 类回退阶段：
+
+- `closed`
+- `planning`
+- `execution`
+- `review`
+
+这层设计的目的是减少 Claude 在读完审核结果后再做二次自由解释的成本。
+
+上层只要消费：
+
+- `recommended_action_kind`
+- `fallback_stage`
+- `policy_reason`
+
+就可以决定下一步是关闭、回规划、回执行，还是继续停留在审核阶段。
+
+## 9. 当前限制
+
+当前回写仍然属于“基于工作区快照 diff 的审核控制”。
+
+它已经强于单纯依赖执行器自报，但还不是完整的、带历史感知的 git 级差异分析。
+
+因此以下场景仍属于后续加固范围：
+
+- 大量 rename
+- 并发编辑
+- 多轮交叉执行后的证据归属判定