@hunyed15/codecgc 0.1.6 → 0.1.8

package/codecgc/compound/codecgc-capability-matrix.md

@@ -0,0 +1,37 @@
+# CodeCGC Capability Matrix
+
+This matrix defines which layer owns each product capability.
+
+## Product Layers
+
+| Capability | Claude | CodeCGC MCP | Runtime | Codex | Gemini | CLI |
+| --- | --- | --- | --- | --- | --- | --- |
+| User request intake | Owner | Tool surface | Support | No | No | Fallback |
+| Project install | Initiates | Owner | Executes | No | No | Fallback |
+| Status and doctor | Reads | Owner | Executes | No | No | Fallback |
+| Requirement clarification | Owner | Optional state write | Stores artifacts | No | No | Debug |
+| Planning | Owner | Entry or plan tool | Builds workflow state | No | No | Fallback |
+| Backend implementation | Controller | Routes | Dispatches | Owner | No | Debug |
+| Frontend implementation | Controller | Routes | Dispatches | No | Owner | Debug |
+| Test execution | Controller | Routes | Dispatches | Backend tests | Frontend tests | Debug |
+| Review | Owner | Review tool | Evidence and writeback | Responds to backend fixes | Responds to frontend fixes | Fallback |
+| History | Reads | Owner | Scans artifacts | No | No | Fallback |
+| Route explanation | Reads | Owner | Evaluates state | No | No | Fallback |
+| Release readiness | Reads | Optional tool | Audits repository | No | No | Owner |
+| External capability audit | Reads | Optional tool | Audits registry | No | No | Owner |
+| Documentation updates | Owner | Optional governance tools | Stores artifacts | No by default | No by default | Debug |
+
+## Boundary Rules
+
+- Claude controls the workflow, but does not directly implement routed product source changes.
+- CodeCGC MCP is the preferred product capability surface for Claude.
+- Runtime modules own workflow state, routing, audit, and evidence behavior.
+- Codex owns backend code and backend tests.
+- Gemini owns frontend code and frontend tests.
+- CLI remains a compatibility, CI, and maintainer debugging surface.
+
+## Design Direction
+
+Do not add a new slash command for every runtime action.
+
+When a capability becomes stable, expose it through the orchestrator MCP first. Keep CLI access for fallback and automation.

package/codecgc/reference/README.md

@@ -0,0 +1,69 @@
+# CodeCGC Reference Index
+
+This directory contains the stable user and maintainer references shipped with CodeCGC.
+
+## Recommended Reading Order
+
+1. [Quickstart](quickstart.md)
+2. [Onboarding](onboarding.md)
+3. [Operation Guide](operation-guide.md)
+4. [Real Workflow Loop](real-workflow-loop.md)
+5. [Recovery Loop](recovery-loop.md)
+6. [Troubleshooting](troubleshooting.md)
+7. [Path Contract](path-contract.md)
+8. [MCP Tool Surface](mcp-tool-surface.md)
+9. [Maintainer Guide](maintainer-guide.md)
+
+## Core Product Contract
+
+CodeCGC is a Claude-native development orchestration layer.
+
+- Claude owns orchestration, requirements, design, review, acceptance, docs, and workflow state.
+- Codex owns backend implementation and backend tests.
+- Gemini owns frontend implementation and frontend tests.
+- CodeCGC orchestrator MCP owns the user-facing capability surface.
+- The CLI remains available for local debugging, CI checks, and fallback execution.
+
+The normal user path is:
+
+```text
+Claude /cgc -> CodeCGC MCP tool -> CodeCGC runtime -> Codex or Gemini executor
+```
+
+The normal install path is:
+
+```text
+npm global install -> project-local cgc-install -> cgc-start -> project .mcp.json / .claude / model-routing.yaml
+```
+
+User-level Claude installation is optional and must be explicit.
+
+## Public User Surface
+
+The preferred Claude-facing commands are intentionally small:
+
+- `/cgc`
+- `/cgc-install`
+- `/cgc-status`
+- `/cgc-doctor`
+- `/cgc-review`
+- `/cgc-history`
+
+Other `cgc-*` commands may remain available as CLI commands, but ordinary users should not need to memorize all of them.
+
+## Maintainer Surface
+
+Maintainers may use lower-level commands directly:
+
+- `cgc-plan`
+- `cgc-build`
+- `cgc-fix`
+- `cgc-test`
+- `cgc-route`
+- `cgc-package-audit`
+- `cgc-external-status`
+- `cgc-external-audit`
+- `cgc-release-readiness`
+- `cgc-lifecycle`
+
+These commands are useful for debugging, CI, release checks, and validating runtime behavior.

package/codecgc/reference/maintainer-guide.md

@@ -0,0 +1,93 @@
+# CodeCGC Maintainer Guide
+
+This guide is for people changing CodeCGC itself.
+
+## Development Setup
+
+Install Node.js and Python dependencies:
+
+```bash
+npm install
+pip install -r requirements-dev.txt
+```
+
+If `npm install` is not needed for the current change, you can still run the package scripts directly with the checked-in files.
+
+## Focused Verification
+
+Run these checks before publishing or tagging:
+
+```bash
+python scripts\install_codecgc.py --mode status --format json
+python scripts\install_codecgc.py --mode doctor --format json
+python scripts\audit_codecgc_package_runtime.py --format json
+node --check bin\codecgc.js
+python -m pytest tests\test_codecgc_policy.py tests\test_install_codecgc.py --basetemp D:\tmp\codecgc-pytest
+```
+
+Add broader tests when changing workflow routing, step execution, review policy, or installer behavior.
+
+## Release Readiness Chain
+
+Use:
+
+```bash
+cgc-status
+cgc-doctor
+cgc-package-audit
+cgc-external-status
+cgc-external-audit
+cgc-release-readiness
+cgc-lifecycle
+```
+
+This checks installation readiness, package contents, external capability registration, release signals, and lifecycle coverage.
+
+## Command Surface Rule
+
+Do not add a new slash command for every runtime action.
+
+Preferred layering:
+
+- Claude slash commands are a small user entry surface.
+- CodeCGC MCP tools are the product capability surface.
+- CLI commands are fallback, CI, and maintainer debugging surface.
+- Python scripts are internal runtime implementation.
+
+## Runtime Change Rule
+
+When adding runtime behavior, prefer a stable callable function first, then attach CLI and MCP wrappers to it.
+
+Shared runtime logic belongs in `scripts/codecgc_runtime/`. Keep top-level `scripts/*.py` files as command entry points or compatibility shims when an existing import path is already public inside this repository.
+
+Avoid duplicating business logic separately in:
+
+- Claude command markdown
+- Node CLI wrappers
+- Python scripts
+- MCP tool functions
+
+## Review Policy Rule
+
+Review output must be evidence-based. Do not mark an execution accepted only because the executor said it completed.
+
+At minimum, review should consider:
+
+- executor ownership
+- target scope
+- local diff evidence
+- reported files versus observed files
+- test or validation evidence when available
+- review writeback consistency
+
+## Dirty Worktree Rule
+
+The repository may contain local project files such as `.claude/settings.local.json`.
+
+Do not commit user-local settings. Do not delete unrelated user changes while preparing a release.
+
+## Documentation Rule
+
+Published docs should be stable references, not raw progress logs.
+
+Use the parent design documents as source material, then publish only the user-facing or maintainer-facing contract needed for the release.

package/codecgc/reference/mcp-tool-surface.md

@@ -0,0 +1,112 @@
+# CodeCGC MCP Tool Surface
+
+This document defines the stable response contract for CodeCGC orchestrator MCP tools.
+
+## Role
+
+CodeCGC MCP is the preferred Claude-facing capability layer.
+
+The CLI is still available for:
+
+- local debugging
+- CI checks
+- release checks
+- fallback execution when MCP is unavailable
+
+## Response Envelope
+
+Every CodeCGC MCP tool returns a JSON object with this shape:
+
+```json
+{
+  "success": true,
+  "tool": "codecgc.status",
+  "payload": {},
+  "error": null,
+  "meta": {
+    "contract_version": "1.0",
+    "payload_success": true,
+    "response_shape": "codecgc.mcp.tool_result"
+  }
+}
+```
+
+## Fields
+
+- `success`: Overall MCP tool success. This is false if the runtime payload failed or if the MCP wrapper failed before getting a runtime payload.
+- `tool`: Fully qualified CodeCGC tool name.
+- `payload`: Raw runtime payload returned by the underlying CodeCGC runtime script.
+- `error`: Normalized error object, or null.
+- `meta.contract_version`: MCP response contract version.
+- `meta.payload_success`: Raw runtime payload success flag.
+- `meta.response_shape`: Constant response shape identifier.
+
+## Error Object
+
+When `success` is false, `error` uses this shape:
+
+```json
+{
+  "type": "RuntimeScriptError",
+  "category": "runtime-script-failed",
+  "message": "Runtime script reported failure.",
+  "tool": "codecgc.status",
+  "script": "install_codecgc.py",
+  "args": ["--mode", "status", "--format", "json"],
+  "returncode": 1
+}
+```
+
+If the runtime script raises or produces invalid JSON before returning a payload, `type` is the exception class name and `payload` contains a minimal failure summary.
+
+## Error Categories
+
+Stable categories currently include:
+
+- `runtime-script-failed`: the runtime script returned a non-zero exit code.
+- `runtime-payload-failed`: the runtime script returned JSON with `success: false` but no process return code.
+- `runtime-json-invalid`: the MCP wrapper could not parse runtime JSON, or runtime parsing raised a `ValueError`.
+- `runtime-timeout`: the runtime process timed out.
+- `runtime-script-missing`: the expected runtime script or file was not found.
+- `runtime-permission-denied`: the runtime wrapper hit a filesystem permission error.
+- `mcp-wrapper-exception`: the MCP wrapper failed for another reason before producing a normal payload.
+
+Runtime payloads may provide a more specific `error_category` or `failure_category`; when present, the MCP wrapper preserves that category.
+
+## Current Tools
+
+- `codecgc.install`
+- `codecgc.start`
+- `codecgc.status`
+- `codecgc.doctor`
+- `codecgc.entry`
+- `codecgc.continue`
+- `codecgc.explain`
+- `codecgc.review`
+- `codecgc.history`
+- `codecgc.route`
+- `codecgc.plan`
+- `codecgc.build`
+- `codecgc.fix`
+- `codecgc.test`
+- `codecgc.package_audit`
+- `codecgc.external_audit`
+- `codecgc.release_readiness`
+- `codecgc.lifecycle`
+
+## Compatibility Rule
+
+The raw runtime result remains available under `payload`.
+
+Claude-facing behavior should consume the envelope first, then inspect `payload` for domain-specific details.
+
+## Argument Mapping Rule
+
+MCP tools must keep argument mapping deterministic.
+
+- User-facing `format` hints do not change the envelope shape.
+- `codecgc.install` always calls `install_codecgc.py` with `--format json` internally and records the requested format in `payload.requested_format`.
+- `codecgc.start` calls `install_codecgc.py --mode start --format json` and is read-only.
+- `workspace` values are normalized before being passed to runtime scripts.
+- Repeated list values are emitted as repeated flags, not comma-joined strings.
+- Boolean switches are omitted when false and emitted as bare flags when true.

package/codecgc/reference/onboarding.md

@@ -0,0 +1,69 @@
+# CodeCGC Onboarding
+
+This document defines the real-project entry experience after `cgc-install`.
+
+## Contract
+
+`cgc-install` is project-local by default. After a successful install, a target project should contain:
+
+```text
+codecgc/START_HERE.md
+.claude/commands/cgc-start.md
+```
+
+`codecgc/START_HERE.md` is generated for the target project and is safe to keep in the project because it uses project-relative paths only. It must not contain the package installation directory or a developer machine path.
+
+## First User Path
+
+Inside Claude:
+
+```text
+/cgc-install
+/cgc-start
+/cgc-status
+/cgc-doctor
+/cgc 新增一个登录页面，放在 src/components/LoginForm.tsx
+```
+
+Outside Claude:
+
+```bash
+cgc-install
+cgc-start
+cgc-status
+cgc-doctor
+cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
+```
+
+## `/cgc-start`
+
+`/cgc-start` is a read-only entry command. It should call `codecgc.start` and summarize:
+
+- whether `codecgc/START_HERE.md` exists and matches the current onboarding contract
+- the project-local onboarding file path
+- the shortest next actions for Claude and CLI users
+- the fallback action when onboarding is missing, normally `/cgc-install` or `cgc-install`
+
+The CLI equivalent is `cgc-start`.
+
+## Why This Exists
+
+Without an explicit first-run entry, new users can install successfully but still be unsure whether to use `/cgc`, `/cgc-install`, `cgc-plan`, `cgc-build`, or another lower-level command. The onboarding surface keeps ordinary users on the product path:
+
+```text
+install -> start -> status/doctor -> /cgc natural-language request
+```
+
+Maintainer commands remain available, but they should not be required for the first successful workflow.
+
+## Failure Handling
+
+If `cgc-start` reports missing onboarding, run:
+
+```bash
+cgc-install
+```
+
+If `cgc-status` reports `onboarding_file` as missing or outdated, the same repair action applies.
+
+If `cgc-doctor` reports `onboarding_file_ready` as failed, reinstall project-local integration before debugging executor availability.

package/codecgc/reference/operation-guide.md

@@ -4,28 +4,26 @@
 
 这份文档是 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`
+CodeCGC 的推荐用户入口是 Claude 内的 `/cgc`，背后优先调用 CodeCGC orchestrator MCP 工具。
+
+最小公开入口是：
+
+- `/cgc`
+- `/cgc-start`
+- `/cgc-install`
+- `/cgc-status`
+- `/cgc-doctor`
+- `/cgc-review`
+- `/cgc-history`
+
+CLI 命令继续保留，但主要用于本地调试、CI、维护和 MCP 不可用时的回退。
 
 底层实现入口如 `scripts/codecgc_cli.py`、`scripts/route_codecgc_workflow.py` 只属于维护者调试层。
 
 默认原则：
 
-- 日常使用优先走 `cgc-*`
+- 日常使用优先走 `/cgc` 或 `codecgc.entry`
+- 已明确 workflow 阶段时，才显式调用 `cgc-plan` / `cgc-build` / `cgc-fix` / `cgc-test` / `cgc-review`
 - 调试运行时本身时再看 Python 脚本入口
 
 ## 2. 首次接入顺序
@@ -33,13 +31,16 @@
 如果你是第一次把 CodeCGC 接入某个项目，建议顺序是：
 
 1. 在目标项目根目录运行 `cgc-install`
-2. 运行 `cgc-status`，必要时再运行 `cgc-doctor`
-3. 用 `cgc "<自然语言需求>"` 或 `cgc-entry` 开始
+2. 运行 `cgc-start` 查看项目本地首次使用入口
+3. 运行 `cgc-status`，必要时再运行 `cgc-doctor`
+4. 在 Claude 中用 `/cgc <自然语言需求>` 开始
+5. 如果不在 Claude 中，再用 `cgc "<自然语言需求>"` 作为 CLI 回退
 
 最小示例：
 
 ```bash
 cgc-install
+cgc-start
 cgc-status
 cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
 ```
@@ -58,8 +59,9 @@ cgc-status --workspace D:\Projects\MyApp
 - `cgc-plan`：还需要规划或澄清
 - `cgc-build` / `cgc-fix`：当前步骤已具备执行条件
 - `cgc-review`：已经存在 audit，等待审核决策
-- `cgc-route`：只想知道下一步推荐命令
-- `cgc-external-audit`：只想看外部能力接入状态
+- `cgc-route`：维护者只想知道下一步推荐命令
+- `cgc-external-status`：只想看外部能力状态面板
+- `cgc-external-audit`：只想看外部能力登记一致性与声明
 - `cgc-release-readiness`：发布或长期维护前做总检查
 - `cgc-lifecycle`：快速判断仓库现在处于哪个生命周期阶段
 
@@ -74,7 +76,9 @@ cgc --request "现在下一步该做什么"
 cgc --latest
 ```
 
-`cgc` 是意图优先入口，默认输出更适合人直接阅读的摘要。
+`cgc` 是 CLI 意图优先入口，默认输出更适合人直接阅读的摘要。
+
+在 Claude 中，优先使用 `/cgc`，让命令模板调用 `codecgc.entry` MCP 工具。
 
 如果需要完整结构化结果，使用：
 
@@ -182,12 +186,14 @@ cgc-route --flow feature --slug 2026-05-01-demo-login-ui
 1. `cgc-status`
 2. `cgc-doctor`
 3. `cgc-package-audit`
-4. `cgc-external-audit`
+4. `cgc-external-status`
+5. `cgc-external-audit`
 5. `cgc-release-readiness`
 6. `cgc-lifecycle`
 
 其中：
 
+- `cgc-external-status` 用来快速查看第三方能力状态面板
 - `cgc-external-audit` 用来判断第三方能力是否处于“正式接入 / 规划中 / 本地漂移”哪一种状态
 - `cgc-release-readiness` 用来把安装、运行时、发布包、外部接入与生命周期资产汇总成一个结论
 - `cgc-lifecycle` 用来把 roadmap、workflow 与 execution 当前分布汇总成生命周期阶段

package/codecgc/reference/path-contract.md

@@ -0,0 +1,53 @@
+# CodeCGC Path Contract
+
+CodeCGC uses two different path classes. They must not be mixed.
+
+## Install-Time Runtime Paths
+
+Runtime configuration may use absolute paths because every machine installs packages in a different location.
+
+Examples:
+
+- MCP server command paths
+- package script paths
+- hook script command targets
+- local Python script entry points
+
+These paths are generated during install and are allowed to be machine-specific.
+
+## Persisted Project Artifact Paths
+
+Workflow artifacts should use project-relative paths whenever they describe project files or execution evidence.
+
+Examples:
+
+- `codecgc/features/...`
+- `codecgc/issues/...`
+- `codecgc/execution/...`
+- `src/components/LoginForm.tsx`
+- `backend/src/sync.py`
+
+These files should remain portable across machines and repositories.
+
+## Rule
+
+Use absolute paths for runtime launch configuration.
+
+Use project-relative paths for persisted product state, audits, fixtures, review evidence, and workflow documents.
+
+## Installer Responsibility
+
+`cgc-install` is responsible for writing machine-specific runtime paths into the target project integration files.
+
+It should not hard-code paths from the development machine into reusable templates or persisted workflow artifacts.
+
+## Maintainer Check
+
+Before release, run:
+
+```bash
+cgc-package-audit
+cgc-release-readiness
+```
+
+If a fixture or product artifact contains a stale local path, normalize it before publishing.

package/codecgc/reference/policy-routing.md

@@ -0,0 +1,57 @@
+# CodeCGC Policy Routing
+
+CodeCGC uses a single routing policy file as the source of truth:
+
+- `model-routing.yaml`
+
+The policy separates files by owner:
+
+- `orchestration`: CodeCGC workflow state, command surfaces, audits, plans, and routing config.
+- `docs`: human-facing documentation.
+- `backend`: backend product code owned by Codex.
+- `frontend`: frontend product code owned by Gemini.
+- `backend-test`: backend tests owned by Codex.
+- `frontend-test`: frontend tests owned by Gemini.
+- `shared`: shared contracts that must be split before execution.
+
+## Control Flow
+
+Normal writes should go through CodeCGC:
+
+1. Claude receives the user request.
+2. CodeCGC plans and routes the task.
+3. Codex or Gemini executes the owned implementation step.
+4. CodeCGC writes an execution audit.
+5. Claude reviews the audit and chooses the next action.
+
+Claude may write orchestration and docs files. Claude must not directly write product source paths.
+
+## Install Boundary
+
+Global npm install only provides the `cgc*` CLI commands. It must not write `~/.claude`, user-level hooks, or user-level slash commands.
+
+Project install is the default integration path:
+
+```bash
+cd your-project
+cgc-install
+```
+
+This creates project-local `.mcp.json`, `.claude/`, `model-routing.yaml`, and the `codecgc/` workflow directories. User-level install modes are explicit escape hatches only.
+
+## Policy Checker
+
+`scripts/codecgc_policy.py` evaluates the policy for every entry point that needs write ownership:
+
+- Claude hook guardrail via `.claude/hooks/route-edit.ps1` for `Edit`, `Write`, and `MultiEdit`
+- task payload construction via `scripts/build_codecgc_task.py`
+- build/fix/test wrappers before executor dispatch
+- status and doctor checks through `model-routing.yaml` validation
+
+The hook is intentionally thin. It only forwards Claude edit requests to the shared policy checker.
+
+## Shared Paths
+
+`shared` paths use `split-first`.
+
+Shared changes must be split into backend and frontend owned tasks, or explicitly redesigned as a compound workflow before implementation. A single executor should not directly own a shared change by default.

package/codecgc/reference/project-structure.md

@@ -0,0 +1,80 @@
+# CodeCGC Project Structure
+
+CodeCGC separates package runtime files from target project workflow files.
+
+## Package Runtime
+
+These files are source-controlled and ship with the npm package:
+
+```text
+bin/
+scripts/
+  codecgc_runtime/
+codecgcmcp/
+codexmcp/
+geminimcp/
+codecgc/reference/
+codecgc/cgc*/
+.claude/hooks/route-edit.ps1
+model-routing.yaml
+```
+
+Package runtime files define commands, MCP servers, policy checking, and reference docs.
+
+`scripts/codecgc_runtime/` is the shared Python runtime package for reusable internals such as path resolution, console rendering, executor registry, routing templates, MCP config generation, and runtime script execution. Top-level `scripts/codecgc_*.py` modules remain as compatibility shims or CLI entry files so existing Node wrappers, MCP tools, tests, and user commands keep their stable contract.
+
+## Source Repository Hygiene
+
+The source repository should not commit project-local install output. These files are generated by `cgc-install` and may contain machine-specific paths:
+
+```text
+.mcp.json
+.claude/settings.json
+.claude/commands/
+codecgc/START_HERE.md
+codecgc/features/
+codecgc/issues/
+codecgc/execution/
+codecgc/requirements/
+codecgc/architecture/
+codecgc/docs/
+```
+
+Keep `.claude/hooks/route-edit.ps1` in source control because it is the packaged hook template copied into target projects.
+
+Keep `codecgc/fixtures/`, `codecgc/reference/`, `codecgc/roadmap/`, and `codecgc/compound/` when they are used as packaged examples, release-maintenance assets, or regression fixtures.
+
+## Target Project Surface
+
+`cgc-install` creates or syncs these files in the target project:
+
+```text
+.mcp.json
+model-routing.yaml
+.claude/
+  settings.json
+  hooks/
+    route-edit.ps1
+  commands/
+    cgc*.md
+codecgc/
+  features/
+  issues/
+  execution/
+  requirements/
+  architecture/
+  roadmap/
+  compound/
+  docs/
+  reference/
+  fixtures/
+```
+
+## Ownership
+
+- `.mcp.json`, `.claude/**`, `model-routing.yaml`, and `codecgc/**` are orchestration paths.
+- Documentation paths are docs paths.
+- Product source paths are owned by Codex or Gemini according to `model-routing.yaml`.
+- Shared source paths require split-first routing.
+
+The project hook enforces the same policy checker used by task dispatch.