@hunyed15/codecgc 0.1.7 → 0.1.8

package/codecgc/reference/quickstart.md

@@ -0,0 +1,108 @@
+# CodeCGC Quickstart
+
+This guide shows the shortest path from a clean machine to a working project-local CodeCGC integration.
+
+## 1. Install The CLI
+
+Install the package globally:
+
+```bash
+npm install -g @hunyed15/codecgc --registry=https://registry.npmjs.org/
+```
+
+This only installs the global `cgc*` commands. It does not write user-level Claude files by default.
+
+## 2. Install Into A Project
+
+Run project-local install from the target project root:
+
+```bash
+cd your-project
+cgc-install
+cgc-start
+cgc-status
+cgc-doctor
+```
+
+Inside Claude, use `/cgc-install` and then `/cgc-start` for the same project-local path.
+
+The project install syncs:
+
+```text
+.mcp.json
+model-routing.yaml
+.claude/settings.json
+.claude/hooks/route-edit.ps1
+.claude/commands/cgc*.md
+codecgc/START_HERE.md
+codecgc/
+```
+
+## 3. Read The Project Entry
+
+Run:
+
+```bash
+cgc-start
+```
+
+This is a read-only first-run guide for the current project. If it reports missing onboarding, run `cgc-install` again from the target project root.
+
+## 4. Start Work From The Single Entry
+
+Prefer the Claude entry:
+
+```text
+/cgc 新增一个登录页面，放在 src/components/LoginForm.tsx
+```
+
+If you are outside Claude, use the CLI fallback:
+
+```bash
+cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
+```
+
+CodeCGC should route frontend implementation to Gemini and backend implementation to Codex.
+
+## 5. Continue Or Explain
+
+Use the same entry instead of memorizing internal commands:
+
+```text
+/cgc 继续刚刚的工作
+/cgc 现在下一步该做什么
+```
+
+The orchestrator should decide whether the next action is planning, execution, review, or closure.
+
+## 6. Review An Execution
+
+When an execution audit is ready, use:
+
+```text
+/cgc-review
+```
+
+or the CLI fallback:
+
+```bash
+cgc-review --audit-file codecgc/execution/example-step-1.json --decision accepted
+```
+
+Review is a control point. It may downgrade an `accepted` request to `changes-requested` if local evidence, ownership, or scope checks fail.
+
+For the full state loop, including dry-run downgrade and successful closure, see [Real Workflow Loop](real-workflow-loop.md).
+
+## 7. Use Explicit Commands Only When Needed
+
+Use explicit subcommands only when you already know the workflow phase:
+
+```bash
+cgc-plan ...
+cgc-build ...
+cgc-fix ...
+cgc-test ...
+cgc-route ...
+```
+
+For normal use, `/cgc` and the CodeCGC MCP tools should remain the primary path.

package/codecgc/reference/real-workflow-loop.md

@@ -0,0 +1,123 @@
+# CodeCGC Real Workflow Loop
+
+This page describes the repeatable CodeCGC loop after a project has already run `cgc-install`.
+
+The goal is not to make users memorize every command. The goal is to keep one stable control loop where Claude orchestrates state, Codex or Gemini executes scoped code work, and review closes the loop only when there is enough evidence.
+
+## Ownership Model
+
+Claude owns orchestration work:
+
+- Requirements and clarification.
+- Feature or issue planning.
+- Workflow state explanation.
+- Documentation and acceptance notes.
+- Review decision writeback.
+- Routing recovery when scope or evidence is wrong.
+
+Codex owns backend execution:
+
+- Backend implementation under paths classified as backend.
+- Backend tests when the step is explicitly a backend test step.
+- Returning execution evidence through the backend executor.
+
+Gemini owns frontend execution:
+
+- Frontend implementation under paths classified as frontend.
+- Frontend tests when the step is explicitly a frontend test step.
+- Returning execution evidence through the frontend executor.
+
+CodeCGC owns the contract between them:
+
+- Project-local paths and generated artifacts.
+- `model-routing.yaml` path classification.
+- Step selection from checklist or fix YAML.
+- Execution audit files under `codecgc/execution/`.
+- Review policy and checklist status writeback.
+
+## Normal Loop
+
+The preferred Claude entry is:
+
+```text
+/cgc <your request>
+```
+
+For CLI debugging or CI, the same loop maps to:
+
+```bash
+cgc "add a backend endpoint under src/server/demo.py"
+cgc-route --flow feature --slug 2026-05-10-demo
+cgc-build --slug 2026-05-10-demo
+cgc-review --audit-file codecgc/execution/demo-step-1.json --decision accepted
+cgc-route --flow feature --slug 2026-05-10-demo
+```
+
+The stable states are:
+
+- `needs-planning`: Claude must refine or repair the plan before execution.
+- `awaiting-build`: a feature step is ready for Codex or Gemini execution.
+- `awaiting-fix`: an issue step is ready for Codex or Gemini execution.
+- `awaiting-review`: an execution audit is ready for Claude review.
+- `closed`: the current workflow has no remaining executable step.
+
+## Dry-Run Behavior
+
+Use dry-run to check routing and payload shape:
+
+```bash
+cgc-build --slug 2026-05-10-demo --dry-run
+```
+
+A dry-run writes an audit, but it is not execution evidence. If review is requested as `accepted`, the review policy must downgrade it to `changes-requested` and keep the step `pending`.
+
+Expected recovery:
+
+```text
+dry-run audit -> cgc-review accepted -> final_decision changes-requested -> route recommends cgc-build again
+```
+
+This is intentional. It prevents a workflow from closing when no real executor changed the workspace.
+
+## Successful Execution Behavior
+
+After a real executor run, CodeCGC expects an audit with:
+
+- `mode: execute`
+- matching `task_id`
+- matching `source.step_number`
+- executor success
+- `result.outcome: done`
+- no `dry_run_only` policy check
+- no `execution_not_performed` risk
+
+If those conditions hold, route must recommend `cgc-review` even if the previous review for the same step was `changes-requested`. The newest valid execution evidence should be reviewed instead of being blocked by an older failed review.
+
+Expected recovery:
+
+```text
+changes-requested review -> real execute audit -> route recommends cgc-review -> accepted review -> checklist step done -> route closed
+```
+
+## Review Writeback
+
+Review writes back to the workflow artifact:
+
+- Feature workflows write to `*-acceptance.md`.
+- Issue workflows write to `*-fix-note.md`.
+- Accepted review sets the matching checklist step to `done`.
+- Changes-requested review keeps the matching checklist step `pending`.
+
+Review is a control point, not a text append helper. It can reject or downgrade a requested acceptance when evidence is missing, out of scope, owned by the wrong executor, or only dry-run.
+
+For detailed recovery behavior after executor failure, review rejection, mixed paths, test steps, or session continue, see [Recovery Loop](recovery-loop.md).
+
+## Machine-Independent Paths
+
+Generated and persisted project paths must stay project-relative:
+
+- Good: `codecgc/execution/demo-step-1.json`
+- Good: `src/server/demo.py`
+- Bad: `D:\Users\someone\project\codecgc\execution\demo-step-1.json`
+
+Runtime code may resolve absolute paths internally, but package output, audit JSON, and docs should not depend on the install directory of a specific computer.

package/codecgc/reference/recovery-loop.md

@@ -0,0 +1,109 @@
+# CodeCGC Recovery Loop
+
+This page defines how CodeCGC should recover when a workflow cannot move straight from execution to acceptance.
+
+The recovery loop is part of normal product behavior. It is not an exceptional maintainer-only path.
+
+## Recovery States
+
+CodeCGC uses structured command results to make recovery machine-readable:
+
+- `state`: where the workflow stopped.
+- `failure_type`: why the workflow stopped.
+- `recommended_command`: the next command to run, if there is a safe one.
+- `next`: human-facing recovery instruction.
+- `replan_payload`: structured planning payload when the workflow must return to `cgc-plan`.
+- `reused_session_id`: executor session reused for the same task, when available.
+
+## Executor Failure
+
+If an executor returns invalid output, fails, or cannot complete the task, the workflow must not pretend that the step is ready for review.
+
+Expected behavior:
+
+```text
+executor failure -> state blocked -> failure_type executor-failure -> inspect executor output before retry
+```
+
+The retry command may be empty when CodeCGC cannot safely prove that a simple rerun is enough. In that case the operator must inspect the audit and executor logs first.
+
+## Review Rejection
+
+When review writes `changes-requested`, the matching checklist step remains `pending`.
+
+Expected behavior:
+
+```text
+review changes-requested -> route recommends cgc-build/cgc-fix/cgc-test again
+```
+
+If the previous executor audit contains a reusable `session_id`, the next execution command should include `--session-id <id>` for the same task. This keeps the executor conversation continuous without changing the workflow step.
+
+## Mixed Path Recovery
+
+A single executable step must not mix frontend, backend, shared, docs, or orchestration ownership.
+
+Expected behavior:
+
+```text
+mixed ownership -> route recommends cgc-plan -> split_suggestion/replan_payload describes smaller steps
+```
+
+The structured split payload should include:
+
+- `grouped_paths`
+- `path_classification`
+- `suggested_split_steps`
+- `target_paths`
+- `in_scope`
+
+Claude uses this payload to rewrite the plan into narrower executable steps.
+
+## Test Step Recovery
+
+Test steps are routed through `cgc-test`.
+
+The stable marker is:
+
+```yaml
+codecgc:
+  step_type: test
+```
+
+`task_id` naming may still contain `-test-step-` for readability, but routing must not depend on that naming convention.
+
+Expected behavior:
+
+```text
+step_type test -> route recommends cgc-test
+cgc-test --dry-run -> state executed-dry-run -> retry cgc-test without dry-run
+```
+
+## Session Continue
+
+Session continue is scoped to the current task id and artifact class.
+
+CodeCGC resolves reusable session ids from:
+
+1. `audit.result.session_id`
+2. `audit.requested_session_id`
+
+Expected behavior:
+
+```text
+same task_id + existing audit session_id -> next build/fix/test includes --session-id
+```
+
+Session ids must not be copied across unrelated task ids or unrelated artifact classes.
+
+## Verification
+
+Maintainers should keep recovery behavior covered by tests that do not call real Codex or Gemini. The recovery contract can be validated with synthetic audits and temporary workspaces.
+
+Minimum coverage:
+
+- executor failure classification
+- review rejection and retry
+- mixed path split payload
+- explicit `step_type: test`
+- session continue command arguments

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

@@ -18,6 +18,7 @@
 - `cgc-status`
 - `cgc-doctor`
 - `cgc-package-audit`
+- `cgc-external-status`
 - `cgc-external-audit`
 - `cgc-release-readiness`
 
@@ -26,6 +27,7 @@
 - `cgc-status` 看项目级集成是否已同步
 - `cgc-doctor` 看 Python、MCP、执行器和项目级集成是否可运行
 - `cgc-package-audit` 看发布包是否覆盖运行时依赖与发布元数据
+- `cgc-external-status` 看第三方能力状态面板
 - `cgc-external-audit` 看第三方能力白名单与本地 MCP 观测状态
 - `cgc-release-readiness` 做总检查汇总，并补充仓库内 deploy / release 信号感知
 
@@ -69,7 +71,7 @@
 
 1. 先把接入意图写进 `codecgc/reference/external-capability-registry.json`
 2. 再把项目级或用户级 `.mcp.json` 接入做好；对 `MemOS`，优先直接使用官方 `memos-mcp`
-3. 最后用 `cgc-external-audit` 检查“登记状态”和“本地观测状态”是否一致
+3. 日常用 `cgc-external-status` 快速看面板，必要时再用 `cgc-external-audit` 检查“登记状态”和“本地观测状态”是否一致
 
 如果跳过第 1 步，CodeCGC 不把该接入视为正式产品能力。
 
@@ -116,6 +118,7 @@
 - `cgc-status` 无阻塞
 - `cgc-doctor` 无阻塞
 - `cgc-package-audit` 无阻塞
+- `cgc-external-status` 无阻塞
 - `cgc-external-audit` 无阻塞
 - `cgc-release-readiness` 总结论为通过
 

package/codecgc/reference/troubleshooting.md

@@ -0,0 +1,112 @@
+# CodeCGC Troubleshooting
+
+## Install Mode Confusion
+
+`npm install -g @hunyed15/codecgc` installs the CLI globally.
+
+It does not install CodeCGC into every project. Run this per project:
+
+```bash
+cgc-install
+cgc-start
+cgc-status
+cgc-doctor
+```
+
+Use `--mode user-dry-run` only to preview user-level Claude integration:
+
+```bash
+cgc-install --mode user-dry-run
+```
+
+Do not use `--mode user` unless you intentionally want to write user-level Claude files.
+
+## MCP JSON Parse Errors
+
+If an MCP install tool reports a JSON parse failure, first check whether the files were still written correctly:
+
+```bash
+cgc-status
+cgc-doctor
+```
+
+The MCP tool surface should request JSON internally, even when the user asked for summary output. If the tool returns non-JSON text, treat it as a tool wrapper bug and verify state with `cgc-status`.
+
+## Missing First-Run Guide
+
+If `cgc-start`, `cgc-status`, or `cgc-doctor` reports `onboarding_file` or `onboarding_file_ready`, rerun project-local install:
+
+```bash
+cgc-install
+cgc-start
+```
+
+The generated file is `codecgc/START_HERE.md`. It should use project-relative paths and should not contain a machine-specific package install directory.
+
+## Claude Hook Blocks A Write
+
+The hook is a guardrail. It blocks Claude direct writes to product source paths that should belong to Codex or Gemini.
+
+Expected behavior:
+
+- Claude may update docs and orchestration files.
+- Codex should update backend code and backend tests.
+- Gemini should update frontend code and frontend tests.
+- Mixed ownership must be split before execution.
+
+If a write was blocked incorrectly, inspect `model-routing.yaml` first. It is the project-local policy source.
+
+## Codex Or Gemini Is Unavailable
+
+Run:
+
+```bash
+cgc-doctor
+```
+
+Then verify that the target project's `.mcp.json` contains the expected `codecgc`, `codex`, and `gemini` MCP server entries.
+
+If only CodeCGC works but executor calls fail, the issue is usually in the executor MCP installation, CLI availability, or authentication state.
+
+## Python Or PyYAML Missing
+
+Install runtime dependencies for the Python used by CodeCGC:
+
+```bash
+pip install pyyaml
+```
+
+For repository development:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+## Pytest Temp Directory Errors On Windows
+
+If pytest cannot write to the default temporary directory, use an explicit temp root:
+
+```bash
+python -m pytest tests\test_codecgc_policy.py tests\test_install_codecgc.py --basetemp D:\tmp\codecgc-pytest
+```
+
+## Path Looks Machine-Specific
+
+Runtime configuration may contain install-time absolute paths. Persisted project artifacts should use project-relative paths.
+
+See [Path Contract](path-contract.md).
+
+## When In Doubt
+
+Run the readiness chain:
+
+```bash
+cgc-status
+cgc-doctor
+cgc-package-audit
+cgc-external-status
+cgc-external-audit
+cgc-release-readiness
+```
+
+Use `cgc-lifecycle` when the question is about product phase or workflow coverage rather than installation health.

package/codecgc/roadmap/codecgc-release-maintenance/delivery-plan.md

@@ -0,0 +1,49 @@
+# CodeCGC Release Maintenance Delivery Plan
+
+This delivery plan turns the release maintenance roadmap into concrete work items.
+
+## Immediate Work
+
+1. Keep project-local install as the default product path.
+2. Keep user-level install behind explicit `--mode user` or `--mode user-dry-run`.
+3. Keep `/cgc` and `codecgc.entry` as the primary user path.
+4. Keep the hook as a write guardrail, not as the orchestration engine.
+5. Keep release docs stable and user-facing.
+
+## Near-Term Work
+
+1. Stabilize MCP tool schemas and response payloads.
+2. Normalize MCP errors so Claude can decide the next action without parsing logs.
+3. Extract workflow state access behind a runtime API.
+4. Reduce duplicate logic between CLI wrappers and MCP tools.
+5. Add focused tests for MCP tool argument mapping.
+
+## Review Trust Work
+
+1. Preserve local diff evidence in audit summaries.
+2. Record validation commands and outcomes when available.
+3. Distinguish missing evidence from failed evidence.
+4. Keep ownership mismatch and out-of-scope changes as blocking review risks.
+5. Ensure old fixtures do not silently bypass new review policy fields.
+
+## Documentation Work
+
+1. Keep `codecgc/reference/README.md` as the reference index.
+2. Keep `quickstart.md` focused on first successful use.
+3. Keep `troubleshooting.md` focused on real install/runtime failures.
+4. Keep `path-contract.md` focused on absolute runtime paths versus project-relative artifacts.
+5. Keep `maintainer-guide.md` focused on checks, release, and contribution rules.
+
+## Verification
+
+Before release, run:
+
+```bash
+cgc-status
+cgc-doctor
+cgc-package-audit
+cgc-external-audit
+cgc-release-readiness
+```
+
+For repository changes, also run the focused test suite documented in `codecgc/reference/maintainer-guide.md`.

package/codecgc/roadmap/codecgc-release-maintenance/overview.md

@@ -0,0 +1,41 @@
+# CodeCGC Release Maintenance Overview
+
+This roadmap tracks the productization work required to keep CodeCGC releasable and maintainable.
+
+## Goal
+
+Make CodeCGC reliable as a Claude-native orchestration layer, not just as a collection of CLI wrappers.
+
+The release maintenance track focuses on:
+
+- Project-local installation correctness
+- Orchestrator MCP tool surface stability
+- Runtime and review evidence quality
+- Package completeness
+- External capability governance
+- Documentation clarity for users and maintainers
+
+## Current Baseline
+
+The current baseline is:
+
+- Global npm install provides CLI commands.
+- Project-local install writes `.mcp.json`, `.claude`, `model-routing.yaml`, and `codecgc/`.
+- CodeCGC MCP exposes the primary orchestrator tools.
+- Codex and Gemini remain executor MCPs.
+- Hook enforcement remains a guardrail, not the main orchestration layer.
+- Release readiness is checked through `cgc-release-readiness`.
+
+## Non-Goals
+
+- Do not remove the CLI before the MCP path is stable.
+- Do not wrap Codex or Gemini in a redundant executor layer.
+- Do not make ordinary users memorize every internal `cgc-*` command.
+- Do not publish raw design progress logs as user documentation.
+
+## Success Criteria
+
+- A new user can install and start from `/cgc-install` and `/cgc`.
+- A maintainer can verify release readiness with one documented command chain.
+- Published docs explain install modes, path rules, troubleshooting, and maintainer checks.
+- Package audits catch missing runtime and reference files before publication.

package/codecgc/roadmap/codecgc-release-maintenance/phases.md

@@ -0,0 +1,84 @@
+# CodeCGC Release Maintenance Phases
+
+## Phase 0: Stable User Entry
+
+Objective:
+
+- Keep the user-facing Claude entry small and predictable.
+
+Deliverables:
+
+- `/cgc` as the primary user entry.
+- `/cgc-install`, `/cgc-status`, and `/cgc-doctor` for setup and health checks.
+- `/cgc-review` and `/cgc-history` for common control points.
+- Documentation that explains when to use CLI fallback.
+
+Exit criteria:
+
+- Users can start without reading internal command mappings.
+
+## Phase 1: Orchestrator MCP First
+
+Objective:
+
+- Make CodeCGC MCP the primary capability layer.
+
+Deliverables:
+
+- Stable tool contracts for install, status, doctor, entry, continue, explain, review, history, and route.
+- JSON responses that can be consumed by Claude without text parsing.
+- Runtime errors normalized into actionable payloads.
+
+Exit criteria:
+
+- Claude command templates prefer MCP tools and only fall back to CLI when necessary.
+
+## Phase 2: Runtime Contract Hardening
+
+Objective:
+
+- Keep workflow logic in reusable runtime code rather than scattered wrappers.
+
+Deliverables:
+
+- Shared runtime APIs for workflow state, routing, audit, and review writeback.
+- CLI wrappers reduced to argument parsing and rendering.
+- MCP tools call the same runtime contract.
+
+Exit criteria:
+
+- Behavior does not diverge between MCP and CLI paths.
+
+## Phase 3: Review Trust
+
+Objective:
+
+- Improve confidence in accepted work.
+
+Deliverables:
+
+- Stronger diff and git evidence summaries.
+- Explicit ownership and path-scope proof.
+- Validation command capture where available.
+- Reproducible audit summaries.
+
+Exit criteria:
+
+- Review results can explain why a step was accepted or rejected without relying only on executor claims.
+
+## Phase 4: Release And Maintenance Closure
+
+Objective:
+
+- Keep the package publishable and maintainable.
+
+Deliverables:
+
+- Package runtime audit.
+- External capability audit.
+- Release readiness audit.
+- Reference docs for quickstart, troubleshooting, path contract, and maintainer workflow.
+
+Exit criteria:
+
+- `cgc-release-readiness` passes before release.