@hunyed15/codecgc 0.2.1 → 0.2.3

package/README.md

@@ -64,7 +64,7 @@ model-routing.yaml
 .claude/
   settings.local.json
   hooks/
-    route-edit.ps1
+    edit-guard.js
   commands/
     cgc*.md
 .codex/
@@ -88,7 +88,7 @@ codecgc/
 
 在 CodeCGC 源码仓库中，`.mcp.json`、`.claude/settings.local.json`、`.claude/commands/`、`.codex/`、`.gemini/`、`codecgc/START_HERE.md` 以及实时 workflow 输出目录会被忽略，因为它们是机器相关或项目安装生成的内容。
 
-源码仓库会保留可发布运行时、参考文档、命令模板、测试 fixtures，以及 `.claude/hooks/route-edit.ps1` 这个 hook 模板。
+源码仓库会保留可发布运行时、参考文档、命令模板、测试 fixtures，以及 `.claude/hooks/edit-guard.js` 这个 hook 模板。
 
 ## 角色与路由策略
 

package/bin/codecgc.js

@@ -201,7 +201,7 @@ const installHelpText = `CodeCGC 安装与自检
 
 模式:
   local
-    把项目级 .mcp.json、.claude/settings.json 与 route-edit.ps1 hook 同步到目标工作区。
+    把项目级 .mcp.json、.claude/settings.json 与 edit-guard.js hook 同步到目标工作区。
   status
     检查项目级集成是否就绪。
   doctor

package/codecgc/cgc-onboard/SKILL.md

@@ -28,7 +28,7 @@ Also inspect:
 
 - `.mcp.json`
 - `.claude/settings.json`
-- `.claude/hooks/route-edit.ps1`
+- `.claude/hooks/edit-guard.js`
 - `model-routing.yaml`
 
 ## Rules

package/codecgc/reference/execution-model.md

@@ -47,7 +47,7 @@ CodeCGC 把“工作流控制”和“代码执行”明确分层。
 - `.claude/settings.local.json`
 - `.codex/codecgcrc.json`
 - `.gemini/policies/codecgc-policy.toml`
-- `.claude/hooks/route-edit.ps1`
+- `.claude/hooks/edit-guard.js`
 
 这些文件一起负责“不能越界”。
 

package/codecgc/reference/policy-routing.md

@@ -43,8 +43,7 @@ This creates project-local `.mcp.json`, `.claude/`, `model-routing.yaml`, and th
 
 `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`
-- Claude shell guardrail via the same hook for `Bash` and `PowerShell`
+- Claude hook guardrail via `.claude/hooks/edit-guard.js` 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

package/codecgc/reference/project-structure.md

@@ -16,7 +16,7 @@ mcp/
   geminimcp/
 codecgc/reference/
 codecgc/cgc*/
-.claude/hooks/route-edit.ps1
+.claude/hooks/edit-guard.js
 model-routing.yaml
 ```
 
@@ -43,7 +43,7 @@ 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 `.claude/hooks/edit-guard.js` 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.
 
@@ -57,7 +57,7 @@ model-routing.yaml
 .claude/
   settings.local.json
   hooks/
-    route-edit.ps1
+    edit-guard.js
   commands/
     cgc*.md
 .codex/

package/codecgc/reference/quickstart.md

@@ -32,7 +32,7 @@ The project install syncs:
 .mcp.json
 model-routing.yaml
 .claude/settings.local.json
-.claude/hooks/route-edit.ps1
+.claude/hooks/edit-guard.js
 .claude/commands/cgc*.md
 .codex/codecgcrc.json
 .gemini/policies/codecgc-policy.toml

package/codecgc/reference/shared-conventions.md

@@ -38,7 +38,7 @@
 这套规则通过两层落地：
 
 1. 工作流层：`cgc-build` 与 `cgc-fix`
-2. guardrail 层：`.claude/hooks/route-edit.ps1`
+2. guardrail 层：`.claude/hooks/edit-guard.js`
 
 ## 4. 当前公开命令面
 

package/codecgc/templates/project/CLAUDE.md

@@ -0,0 +1,192 @@
+<!-- codecgc:claude-md:v1 -->
+# CodeCGC Claude 默认提示词
+
+## 核心身份
+
+你是 CodeCGC 工作流中的 Claude 主控层。你的职责是把用户需求组织成可追踪、可审核、可恢复的工作流，而不是默认直接修改所有代码。
+
+默认分工：
+
+- Claude：需求澄清、规划、设计、文档、审核、验收、状态解释、失败恢复。
+- Codex：后端代码、后端测试、后端修复。
+- Gemini：前端代码、前端测试、前端修复。
+- CodeCGC：路由策略、执行审计、review 回写、工作流状态闭环。
+
+## 语言与输出
+
+- 默认用中文回复用户。
+- 回复先给结论，再给下一步。
+- 命令、路径、文件名、工具名使用反引号。
+- 不输出冗长背景；只保留完成任务需要的信息。
+- 涉及日期、版本、路径和命令时使用精确值。
+
+## 首选入口
+
+普通需求优先使用 CodeCGC 单入口：
+
+```text
+/cgc <自然语言需求>
+```
+
+MCP 可用时优先调用 CodeCGC MCP 工具：
+
+- `codecgc.entry`
+- `codecgc.continue`
+- `codecgc.explain`
+- `codecgc.plan`
+- `codecgc.build`
+- `codecgc.fix`
+- `codecgc.test`
+- `codecgc.review`
+- `codecgc.route`
+- `codecgc.history`
+
+CLI 只作为 MCP 不可用、本地调试或 CI 回退：
+
+```bash
+cgc "<自然语言需求>"
+cgc-plan ...
+cgc-build ...
+cgc-fix ...
+cgc-test ...
+cgc-review ...
+cgc-route ...
+```
+
+## 安装边界
+
+CodeCGC 默认使用项目级安装。
+
+```text
+/cgc-init
+/cgc-start
+/cgc-status
+/cgc-doctor
+```
+
+CLI 回退：
+
+```bash
+cgc-init
+cgc-start
+cgc-status
+cgc-doctor
+```
+
+规则：
+
+- `/cgc-init` 和 `cgc-init` 默认写入当前项目。
+- 不要默认写入 `~/.claude`。
+- Windows PowerShell 如拦截 `.ps1` shim，使用 `cgc-init.cmd`、`cgc-status.cmd`、`cgc-doctor.cmd`。
+
+## 写入边界
+
+`model-routing.yaml` 是路径归属的唯一策略来源。
+
+Claude 可以直接处理：
+
+- `codecgc/**`
+- `.claude/**`
+- `.mcp.json`
+- `model-routing.yaml`
+- `README.md`
+- `docs/**`
+- `CHANGELOG.md`
+
+Claude 不应直接修改产品源码：
+
+- 后端源码和后端测试应交给 Codex。
+- 前端源码和前端测试应交给 Gemini。
+- shared 路径必须先拆分再执行。
+- unknown 路径必须先澄清或更新路由策略。
+
+如果 hook 拦截写入，不要绕过。应解释路径归属，并通过 `/cgc` 或 CodeCGC MCP 重新路由。
+
+## 标准闭环
+
+默认流程：
+
+```text
+需求 -> 规划 -> 路由 -> Codex/Gemini 执行 -> audit -> Claude 审核 -> 继续或关闭
+```
+
+稳定状态：
+
+- `needs-planning`：先由 Claude 补充或修复规划。
+- `awaiting-build`：feature 步骤可执行。
+- `awaiting-fix`：issue 修复步骤可执行。
+- `awaiting-review`：已有 audit，等待审核。
+- `closed`：当前 workflow 已结束。
+
+## 审核规则
+
+`/cgc-review` 是控制点，不是简单写“通过”。
+
+接受前必须确认：
+
+- audit 是真实执行，不是 dry-run。
+- executor 归属正确。
+- 变更路径符合 `model-routing.yaml`。
+- 执行结果成功且有证据。
+- 验收标准已满足。
+
+必须驳回或保持 `changes-requested`：
+
+- 只有 dry-run。
+- 执行器失败、超时或输出无效。
+- 路径越界。
+- 前后端执行器归属错误。
+- mixed/shared/unknown 路径未拆分。
+- 证据不足或本地事实与执行器自报不一致。
+
+## 失败恢复
+
+- executor failure：检查 audit 和执行器输出，不要假装完成。
+- review changes-requested：保持同一 workflow，继续执行推荐的 build/fix/test。
+- mixed ownership：回到 plan，拆成 backend/frontend/docs/orchestration 子步骤。
+- test step：使用 `cgc-test`，不要用 build/fix 代替。
+- session continue：只在同一 task id 和 artifact class 内复用 session id。
+
+## 文档放置
+
+普通项目文档：
+
+```text
+docs/
+README.md
+CHANGELOG.md
+```
+
+CodeCGC 工作流和治理产物：
+
+```text
+codecgc/features/
+codecgc/issues/
+codecgc/execution/
+codecgc/requirements/
+codecgc/architecture/
+codecgc/roadmap/
+codecgc/compound/
+codecgc/docs/
+codecgc/reference/
+```
+
+长期文档和 audit 使用项目相对路径，不固化某台机器的安装目录或 npx 临时缓存路径。
+
+## 硬规则
+
+- 不要为了速度绕过 CodeCGC 直接改产品代码。
+- 用户要求实现功能或修复代码时，优先进入 `/cgc` 工作流。
+- 用户要求修改文档、规划、验收或审核说明时，Claude 可直接处理。
+- dry-run 不是完成证据。
+- 没有 audit 不要宣称执行器任务完成。
+- 不要把 Codex/Gemini 当只读分析模型；它们在 CodeCGC 中是代码执行器。
+
+## 记忆口诀
+
+```text
+Claude 负责想清楚、写清楚、审清楚。
+Codex 负责后端代码。
+Gemini 负责前端代码。
+CodeCGC 负责路由、证据、状态和闭环。
+```

package/codecgc/templates/project/claude/hooks/edit-guard.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// CodeCGC Edit Guard — PreToolUse hook (Edit|Write|MultiEdit)
+// Routes file edits through model-routing.yaml policy.
+// Zero external dependencies. Never crashes (try/catch -> exit(0)).
+
+'use strict';
+
+try {
+  var fs = require('fs');
+  var path = require('path');
+
+  // ── Read stdin ──
+  var inputData = '';
+  if (!process.stdin.isTTY) {
+    inputData = fs.readFileSync(0, 'utf-8');
+  }
+  if (!inputData.trim()) {
+    process.exit(0);
+  }
+
+  var parsed = JSON.parse(inputData);
+  var toolInput = parsed.tool_input || parsed.input || parsed;
+  var toolName = (parsed.tool_name || '').trim();
+  var filePath = (toolInput.file_path || toolInput.path || '').trim();
+
+  if (!filePath) {
+    process.exit(0);
+  }
+
+  // ── Find routing file ──
+  var cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  var routingPath = path.join(cwd, 'model-routing.yaml');
+
+  if (!fs.existsSync(routingPath)) {
+    process.exit(0);
+  }
+
+  // ── Parse YAML (simple, handles model-routing.yaml structure) ──
+  var routingContent = fs.readFileSync(routingPath, 'utf-8');
+  var sections = parseSimpleYaml(routingContent);
+
+  // ── Classify path ──
+  var normalizedPath = normalizePath(filePath, cwd);
+  var owner = classifyPath(normalizedPath, sections);
+
+  // ── Decide ──
+  if (owner === 'orchestration' || owner === 'docs') {
+    process.exit(0);
+  }
+
+  var ownerLabel = owner || 'unknown';
+  var reason = 'CodeCGC: ' + ownerLabel + ' paths should be routed through /cgc (Codex for backend, Gemini for frontend).';
+  if (ownerLabel === 'unknown') {
+    reason = 'CodeCGC: path is not covered by model-routing.yaml. Add it to the appropriate section or route through /cgc.';
+  }
+  if (ownerLabel === 'shared') {
+    reason = 'CodeCGC: shared paths require split-first routing. Use /cgc to split into backend/frontend steps.';
+  }
+
+  console.log(JSON.stringify({
+    decision: 'deny',
+    reason: reason
+  }));
+} catch {
+  process.exit(0);
+}
+
+// ── Helpers ──
+
+function normalizePath(filePath, cwd) {
+  var p = filePath.replace(/\\/g, '/');
+  if (path.isAbsolute(filePath)) {
+    try {
+      p = path.relative(cwd, filePath).replace(/\\/g, '/');
+    } catch { /* keep original */ }
+  }
+  while (p.startsWith('./')) {
+    p = p.slice(2);
+  }
+  return p;
+}
+
+function parseSimpleYaml(content) {
+  var sections = {};
+  var currentKey = null;
+  var lines = content.split('\n');
+
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    // Skip empty lines and comments
+    if (!line.trim() || line.trim().charAt(0) === '#') continue;
+
+    // Top-level key (no leading whitespace, ends with :)
+    if (line.charAt(0) !== ' ' && line.charAt(0) !== '\t' && line.indexOf(':') > 0) {
+      currentKey = line.split(':')[0].trim();
+      if (!sections[currentKey]) sections[currentKey] = [];
+      continue;
+    }
+
+    if (!currentKey) continue;
+
+    var trimmed = line.trim();
+
+    // Nested key under current section (e.g. "frontend:" under "test_paths:")
+    // Check if line has indentation + is a key (contains : but is not a list item)
+    var indent = line.length - line.replace(/^(\s*)/, '').length;
+    if (indent > 0 && trimmed.indexOf(':') > 0 && trimmed.charAt(0) !== '-') {
+      var subKey = trimmed.split(':')[0].trim();
+      var compoundKey = currentKey + '_' + subKey;
+      if (!sections[compoundKey]) sections[compoundKey] = [];
+      // Point currentKey to compound key so subsequent list items go there
+      currentKey = compoundKey;
+      continue;
+    }
+
+    // List item (indented, starts with -)
+    if (trimmed.charAt(0) === '-') {
+      var value = trimmed.slice(1).trim();
+      // Strip quotes
+      if ((value.charAt(0) === '"' && value.charAt(value.length - 1) === '"')
+        || (value.charAt(0) === "'" && value.charAt(value.length - 1) === "'")) {
+        value = value.slice(1, -1);
+      }
+      if (value) {
+        sections[currentKey].push(value);
+      }
+    }
+  }
+
+  return sections;
+}
+
+function classifyPath(normalizedPath, sections) {
+  // Order matters: shared first, then orchestration, docs, tests, frontend, backend
+  var groups = [
+    ['shared', sections['shared_paths'] || []],
+    ['orchestration', sections['orchestration_paths'] || []],
+    ['docs', sections['docs_paths'] || []],
+    ['frontend-test', sections['test_paths_frontend'] || []],
+    ['backend-test', sections['test_paths_backend'] || []],
+    ['frontend', sections['frontend_paths'] || []],
+    ['backend', sections['backend_paths'] || []]
+  ];
+
+  for (var i = 0; i < groups.length; i++) {
+    var owner = groups[i][0];
+    var patterns = groups[i][1];
+    if (matchesAny(normalizedPath, patterns)) {
+      return owner;
+    }
+  }
+  return 'unknown';
+}
+
+function matchesAny(filePath, patterns) {
+  for (var i = 0; i < patterns.length; i++) {
+    if (globMatch(filePath, patterns[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function globMatch(filePath, pattern) {
+  var regex = globToRegex(pattern);
+  return regex.test(filePath);
+}
+
+function globToRegex(pattern) {
+  var regexStr = '^';
+  var i = 0;
+  while (i < pattern.length) {
+    var ch = pattern.charAt(i);
+    if (ch === '*' && i + 1 < pattern.length && pattern.charAt(i + 1) === '*') {
+      // ** matches everything
+      regexStr += '.*';
+      i += 2;
+      // skip trailing / if present
+      if (i < pattern.length && pattern.charAt(i) === '/') i++;
+    } else if (ch === '*') {
+      // * matches anything except /
+      regexStr += '[^/]*';
+      i++;
+    } else if (ch === '.') {
+      regexStr += '\\.';
+      i++;
+    } else {
+      regexStr += ch;
+      i++;
+    }
+  }
+  regexStr += '$';
+  return new RegExp(regexStr);
+}

package/codecgc/templates/project/claude/settings.local.json

@@ -3,10 +3,23 @@
     "allow": [
       "WebSearch",
       "Read(**)",
-      "Edit(**)",
-      "Update(**)",
-      "Write(**)",
-      "mcp__*",
+      "Edit(codecgc/**)",
+      "Edit(.claude/**)",
+      "Edit(.mcp.json)",
+      "Edit(model-routing.yaml)",
+      "Edit(README.md)",
+      "Edit(docs/**)",
+      "Edit(CHANGELOG.md)",
+      "Write(codecgc/**)",
+      "Write(.claude/**)",
+      "Write(.mcp.json)",
+      "Write(model-routing.yaml)",
+      "Write(README.md)",
+      "Write(docs/**)",
+      "Write(CHANGELOG.md)",
+      "mcp__codecgc__*",
+      "mcp__codex__*",
+      "mcp__gemini__*",
       "Bash(*)",
       "PowerShell(*)"
     ]

package/mcp/codexmcp/src/codexmcp/server.py

@@ -21,7 +21,7 @@ import shutil
 mcp = FastMCP("Codex MCP Server-from guda.studio")
 
 # Mirror of model-routing.yaml frontend_paths — keep these hints in sync with
-# route-edit.ps1 and geminimcp/server.py BACKEND_PATH_HINTS.
+# edit-guard.js and geminimcp/server.py BACKEND_PATH_HINTS.
 FRONTEND_PATH_HINTS = (
     "apps/web/",
     "src/components/",

package/mcp/geminimcp/src/geminimcp/server.py

@@ -25,7 +25,7 @@ PROJECT_GEMINI_POLICY_RELATIVE_PATH = Path(".gemini") / "policies" / "codecgc-po
 mcp = FastMCP("Gemini MCP Server-from guda.studio")
 
 # Mirror of model-routing.yaml backend_paths — keep these hints in sync with
-# route-edit.ps1 and codexmcp/server.py FRONTEND_PATH_HINTS.
+# edit-guard.js and codexmcp/server.py FRONTEND_PATH_HINTS.
 BACKEND_PATH_HINTS = (
     "apps/api/",
     "server/",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunyed15/codecgc",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Claude-hosted multi-model workflow product shell for CodeCGC.",
   "license": "MIT",
   "type": "commonjs",
@@ -47,7 +47,7 @@
     "scripts/codecgc_runtime/*.py",
     "scripts/postinstall_codecgc.js",
     "scripts/README-codecgc-cli.md",
-    ".claude/hooks/route-edit.ps1",
+    ".claude/hooks/edit-guard.js",
     "codecgc/cgc/",
     "codecgc/cgc-arch/",
     "codecgc/cgc-build/",

package/scripts/audit_codecgc_package_runtime.py

@@ -23,7 +23,7 @@ RUNTIME_ENTRYPOINTS = [
 ]
 
 RUNTIME_STATIC_REQUIREMENTS = [
-    ".claude/hooks/route-edit.ps1",
+    ".claude/hooks/edit-guard.js",
     "codecgc/templates/project/claude/settings.local.json",
     "codecgc/templates/project/codex/codecgcrc.json",
     "codecgc/templates/project/gemini/policies/codecgc-policy.toml",

package/scripts/install_codecgc.py

@@ -21,9 +21,10 @@ from sync_codecgc_mcp_config import write_mcp_config
 WORKSPACE = PACKAGE_ROOT
 PROJECT_ROUTING_PATH = WORKSPACE / "model-routing.yaml"
 PROJECT_TEMPLATES_DIR = WORKSPACE / "codecgc" / "templates" / "project"
-PROJECT_HOOK_PATH = PROJECT_TEMPLATES_DIR / "claude" / "hooks" / "route-edit.ps1"
-EDIT_GUARDRAIL_MATCHER = "Edit|Write|MultiEdit|Bash|PowerShell"
-LEGACY_EDIT_GUARDRAIL_MATCHERS = {"Edit|Write", "Edit|Write|MultiEdit"}
+PROJECT_HOOK_PATH = PROJECT_TEMPLATES_DIR / "claude" / "hooks" / "edit-guard.js"
+PROJECT_CLAUDE_MD_TEMPLATE = PROJECT_TEMPLATES_DIR / "CLAUDE.md"
+CLAUDE_MD_MARKER = "<!-- codecgc:claude-md:v1 -->"
+EDIT_GUARDRAIL_MATCHER = "Edit|Write|MultiEdit"
 PROJECT_ONBOARDING_RELATIVE_PATH = "codecgc/START_HERE.md"
 PROJECT_ONBOARDING_MARKER = "<!-- codecgc:onboarding:v1 -->"
 CLAUDE_SETTINGS_TEMPLATE = PROJECT_TEMPLATES_DIR / "claude" / "settings.local.json"
@@ -38,7 +39,7 @@ DEFAULT_HOOKS = {
             "hooks": [
                 {
                     "type": "command",
-                    "command": "powershell -ExecutionPolicy Bypass -File .claude/hooks/route-edit.ps1",
+                    "command": "node .claude/hooks/edit-guard.js",
                 }
             ],
         }
@@ -83,7 +84,8 @@ def get_workspace_paths(override_workspace: str = "") -> dict[str, Path]:
         "settings": claude_dir / "settings.local.json",
         "legacy_settings": claude_dir / "settings.json",
         "mcp": root / ".mcp.json",
-        "hook_script": hooks_dir / "route-edit.ps1",
+        "hook_script": hooks_dir / "edit-guard.js",
+        "claude_md": claude_dir / "CLAUDE.md",
         "commands_dir": claude_dir / "commands",
         "routing_file": root / "model-routing.yaml",
         "onboarding_file": root / PROJECT_ONBOARDING_RELATIVE_PATH,
@@ -165,7 +167,8 @@ cgc "新增一个登录页面，放在 src/components/LoginForm.tsx"
 .mcp.json
 model-routing.yaml
 .claude/settings.local.json
-.claude/hooks/route-edit.ps1
+.claude/hooks/edit-guard.js
+.claude/CLAUDE.md
 .claude/commands/cgc*.md
 .codex/codecgcrc.json
 .gemini/policies/codecgc-policy.toml
@@ -250,10 +253,6 @@ def policy_file_is_valid(path: Path) -> bool:
     return True
 
 
-def _normalize_command_path_for_markdown(path: Path) -> str:
-    return str(path).replace("\\", "\\\\")
-
-
 def build_mcp_first_command_template(
     *,
     filename: str,
@@ -559,7 +558,7 @@ def is_codecgc_route_edit_hook(hook: Any) -> bool:
     if hook.get("type") != "command":
         return False
     command = str(hook.get("command", "")).replace("\\", "/").lower()
-    return "route-edit.ps1" in command
+    return "edit-guard" in command
 
 
 def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dict[str, Any], bool]:
@@ -578,7 +577,7 @@ def merge_hook_settings(current: dict[str, Any], command_text: str) -> tuple[dic
     for item in list(pre_tool_use):
         if not isinstance(item, dict):
             continue
-        if item.get("matcher") not in LEGACY_EDIT_GUARDRAIL_MATCHERS | {EDIT_GUARDRAIL_MATCHER}:
+        if item.get("matcher") != EDIT_GUARDRAIL_MATCHER:
             continue
         hook_list = item.get("hooks")
         if not isinstance(hook_list, list):
@@ -796,32 +795,8 @@ def mcp_server_matches_runtime_shape(server_payload: dict[str, Any], spec: dict[
     return True
 
 
-def mcp_config_matches_runtime_shape(payload: dict[str, Any]) -> bool:
-    servers = payload.get("mcpServers")
-    if not isinstance(servers, dict):
-        return False
-
-    for server_name, spec in RUNTIME_MCP_SERVER_SPECS.items():
-        server_payload = servers.get(server_name)
-        if not isinstance(server_payload, dict):
-            return False
-        if not mcp_server_matches_runtime_shape(server_payload, spec):
-            return False
-    return True
-
-
 def build_workspace_hook_command(workspace_paths: dict[str, Path]) -> str:
-    package_root = str(WORKSPACE).replace("'", "''")
-    workspace_root_path = Path(workspace_paths["root"])
-    hook_script_path = workspace_paths.get("hook_script", workspace_root_path / ".claude" / "hooks" / "route-edit.ps1")
-    workspace_root = str(workspace_root_path).replace("'", "''")
-    hook_script = str(hook_script_path).replace("\\", "/").replace("'", "''")
-    return (
-        "powershell -ExecutionPolicy Bypass -Command "
-        f"\"$env:CODECGC_PACKAGE_ROOT='{package_root}'; "
-        f"$env:CODECGC_WORKSPACE_ROOT='{workspace_root}'; "
-        f"& '{hook_script}'\""
-    )
+    return "node .claude/hooks/edit-guard.js"
 
 
 def build_mode_summary_payload(
@@ -841,6 +816,32 @@ def build_mode_summary_payload(
     return summary
 
 
+def install_project_claude_md(target_path: Path) -> str:
+    """Install or append CodeCGC rules to .claude/CLAUDE.md.
+
+    - Does not exist: create with template content.
+    - Exists without marker: append template content.
+    - Exists with marker: skip (don't overwrite user modifications).
+    """
+    if not PROJECT_CLAUDE_MD_TEMPLATE.exists():
+        return str(target_path)
+
+    template_content = PROJECT_CLAUDE_MD_TEMPLATE.read_text(encoding="utf-8")
+
+    if target_path.exists():
+        existing = target_path.read_text(encoding="utf-8")
+        if CLAUDE_MD_MARKER in existing:
+            return str(target_path)
+        # Append with separator
+        separator = "\n\n---\n\n" if not existing.endswith("\n\n") else ""
+        target_path.write_text(existing + separator + template_content, encoding="utf-8")
+    else:
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(template_content, encoding="utf-8")
+
+    return str(target_path)
+
+
 def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
     workspace_paths = get_workspace_paths(override_workspace)
     mcp_path = write_mcp_config(workspace_paths["mcp"], workspace_paths["root"])
@@ -861,6 +862,7 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
         shutil.copyfile(PROJECT_HOOK_PATH, workspace_paths["hook_script"])
     written_commands = write_custom_command_files(workspace_paths["commands_dir"], WORKSPACE / "bin")
     onboarding_file = write_project_onboarding_file(workspace_paths["root"])
+    claude_md_path = install_project_claude_md(workspace_paths["claude_md"])
 
     summary = build_mode_summary_payload(
         scope="项目级 Claude 与 MCP 集成面",
@@ -878,6 +880,7 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
         "codex_policy": str(codex_policy_path),
         "gemini_policy": str(gemini_policy_path),
         "hook_script": str(workspace_paths["hook_script"]),
+        "claude_md": str(claude_md_path),
         "commands_dir": str(workspace_paths["commands_dir"]),
         "onboarding_file": str(onboarding_file),
         "workflow_dirs": workflow_dirs,
@@ -887,7 +890,8 @@ def install_local_runtime(override_workspace: str = "") -> dict[str, Any]:
             "Project-local model-routing.yaml was synchronized as the policy source of truth.",
             "Project-local codecgc workflow directories were initialized.",
             "Claude pre-edit guardrail hook was synchronized into the target workspace.",
-            "Claude project permissions were rendered from codecgc/templates/project/claude/settings.local.json.",
+            "Claude project permissions were rendered with whitelist (Edit/Write restricted to codecgc, .claude, docs, config).",
+            ".claude/CLAUDE.md was installed with CodeCGC workflow rules and three-layer protection guidance.",
             "Project-local Codex policy contract was synchronized into .codex/codecgcrc.json.",
             "Project-local Gemini policy was synchronized into .gemini/policies/codecgc-policy.toml.",
             "Project-local Claude slash commands were synchronized into .claude/commands.",

package/scripts/run_codecgc_task.py

@@ -106,10 +106,9 @@ def extract_text_content(value: Any) -> str:
 
 
 def normalize_mcp_result(raw: dict[str, Any]) -> dict[str, Any]:
-    structured_content = raw.get("structuredContent")
-    if isinstance(structured_content, dict):
-        return structured_content
-
+    # Prefer text content over structuredContent — the tool's actual JSON
+    # response is in content[0].text, while structuredContent is an MCP SDK
+    # convenience wrapper that may omit top-level fields like "success".
     content = raw.get("content")
     if isinstance(content, list):
         for item in content:
@@ -127,6 +126,10 @@ def normalize_mcp_result(raw: dict[str, Any]) -> dict[str, Any]:
             if isinstance(parsed, dict):
                 return parsed
 
+    structured_content = raw.get("structuredContent")
+    if isinstance(structured_content, dict):
+        return structured_content
+
     return {
         "success": False,
         "error": "Unable to parse structured MCP tool result.",
@@ -280,15 +283,23 @@ def write_audit_file(audit_root: Path, audit_record: dict[str, Any]) -> Path:
 
 async def execute_payload(payload: dict[str, Any], timeout_seconds: int) -> dict[str, Any]:
     params = build_server_params(payload["target"])
+    raw_result = None
 
-    async with stdio_client(params) as (read_stream, write_stream):
-        async with ClientSession(read_stream, write_stream) as session:
-            await session.initialize()
-            raw_result = await session.call_tool(
-                payload["tool_name"],
-                payload["tool_args"],
-                read_timeout_seconds=datetime.timedelta(seconds=timeout_seconds),
-            )
+    try:
+        async with stdio_client(params) as (read_stream, write_stream):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+                raw_result = await session.call_tool(
+                    payload["tool_name"],
+                    payload["tool_args"],
+                    read_timeout_seconds=datetime.timedelta(seconds=timeout_seconds),
+                )
+    except* ExceptionGroup:
+        # MCP SDK 清理阶段的 TaskGroup 异常不影响已获得的结果
+        pass
+
+    if raw_result is None:
+        raise RuntimeError("MCP call failed before producing a result.")
 
     dumped = raw_result.model_dump(mode="json")
     normalized = normalize_mcp_result(dumped)

package/.claude/hooks/route-edit.ps1

@@ -1,87 +0,0 @@
-$ErrorActionPreference = "Stop"
-
-function Write-Approve {
-    $payload = @{
-        decision = "approve"
-    } | ConvertTo-Json -Compress
-    [Console]::Out.Write($payload)
-    exit 0
-}
-
-function Write-Deny($reason) {
-    $payload = @{
-        decision = "deny"
-        reason   = $reason
-    } | ConvertTo-Json -Compress
-    [Console]::Out.Write($payload)
-    exit 0
-}
-
-$inputJson = [Console]::In.ReadToEnd()
-if ([string]::IsNullOrWhiteSpace($inputJson)) {
-    Write-Approve
-}
-
-$configuredPackageRoot = [Environment]::GetEnvironmentVariable("CODECGC_PACKAGE_ROOT")
-if (-not [string]::IsNullOrWhiteSpace($configuredPackageRoot)) {
-    $packageRoot = Resolve-Path $configuredPackageRoot
-} else {
-    $packageRoot = Resolve-Path (Join-Path $PSScriptRoot "..\..")
-}
-
-$configuredWorkspaceRoot = [Environment]::GetEnvironmentVariable("CODECGC_WORKSPACE_ROOT")
-if (-not [string]::IsNullOrWhiteSpace($configuredWorkspaceRoot)) {
-    $workspaceRoot = Resolve-Path $configuredWorkspaceRoot
-} else {
-    $workspaceRoot = Resolve-Path (Get-Location)
-}
-
-$policyScript = Join-Path $packageRoot "scripts\codecgc_policy.py"
-$routingFile = Join-Path $workspaceRoot "model-routing.yaml"
-$mcpConfigFile = Join-Path $workspaceRoot ".mcp.json"
-
-if (-not (Test-Path $policyScript)) {
-    Write-Deny "CodeCGC: policy checker is missing: $policyScript"
-}
-
-$pythonCommand = [Environment]::GetEnvironmentVariable("CODECGC_PYTHON_COMMAND")
-if ([string]::IsNullOrWhiteSpace($pythonCommand) -and (Test-Path $mcpConfigFile)) {
-    try {
-        $mcpConfig = Get-Content -Raw $mcpConfigFile | ConvertFrom-Json
-        $pythonCommand = [string]$mcpConfig.mcpServers.codecgc.command
-    } catch {
-        $pythonCommand = ""
-    }
-}
-if ([string]::IsNullOrWhiteSpace($pythonCommand)) {
-    $pythonCommand = "python"
-}
-
-$psi = New-Object System.Diagnostics.ProcessStartInfo
-$psi.FileName = $pythonCommand
-$escapedPolicyScript = $policyScript.Replace('"', '\"')
-$escapedRoutingFile = $routingFile.Replace('"', '\"')
-$psi.Arguments = "`"$escapedPolicyScript`" --hook-check --actor claude --operation write --routing-file `"$escapedRoutingFile`""
-$psi.RedirectStandardInput = $true
-$psi.RedirectStandardOutput = $true
-$psi.RedirectStandardError = $true
-$psi.UseShellExecute = $false
-$psi.CreateNoWindow = $true
-
-$process = [System.Diagnostics.Process]::Start($psi)
-$process.StandardInput.Write($inputJson)
-$process.StandardInput.Close()
-$stdout = $process.StandardOutput.ReadToEnd()
-$stderr = $process.StandardError.ReadToEnd()
-$process.WaitForExit()
-
-if ($process.ExitCode -ne 0) {
-    $detail = if ([string]::IsNullOrWhiteSpace($stderr)) { $stdout } else { $stderr }
-    Write-Deny "CodeCGC: policy checker failed. $detail"
-}
-
-if ([string]::IsNullOrWhiteSpace($stdout)) {
-    Write-Approve
-}
-
-[Console]::Out.Write($stdout)

package/codecgc/templates/project/claude/hooks/route-edit.ps1

@@ -1,87 +0,0 @@
-$ErrorActionPreference = "Stop"
-
-function Write-Approve {
-    $payload = @{
-        decision = "approve"
-    } | ConvertTo-Json -Compress
-    [Console]::Out.Write($payload)
-    exit 0
-}
-
-function Write-Deny($reason) {
-    $payload = @{
-        decision = "deny"
-        reason   = $reason
-    } | ConvertTo-Json -Compress
-    [Console]::Out.Write($payload)
-    exit 0
-}
-
-$inputJson = [Console]::In.ReadToEnd()
-if ([string]::IsNullOrWhiteSpace($inputJson)) {
-    Write-Approve
-}
-
-$configuredPackageRoot = [Environment]::GetEnvironmentVariable("CODECGC_PACKAGE_ROOT")
-if (-not [string]::IsNullOrWhiteSpace($configuredPackageRoot)) {
-    $packageRoot = Resolve-Path $configuredPackageRoot
-} else {
-    $packageRoot = Resolve-Path (Join-Path $PSScriptRoot "..\..")
-}
-
-$configuredWorkspaceRoot = [Environment]::GetEnvironmentVariable("CODECGC_WORKSPACE_ROOT")
-if (-not [string]::IsNullOrWhiteSpace($configuredWorkspaceRoot)) {
-    $workspaceRoot = Resolve-Path $configuredWorkspaceRoot
-} else {
-    $workspaceRoot = Resolve-Path (Get-Location)
-}
-
-$policyScript = Join-Path $packageRoot "scripts\codecgc_policy.py"
-$routingFile = Join-Path $workspaceRoot "model-routing.yaml"
-$mcpConfigFile = Join-Path $workspaceRoot ".mcp.json"
-
-if (-not (Test-Path $policyScript)) {
-    Write-Deny "CodeCGC: policy checker is missing: $policyScript"
-}
-
-$pythonCommand = [Environment]::GetEnvironmentVariable("CODECGC_PYTHON_COMMAND")
-if ([string]::IsNullOrWhiteSpace($pythonCommand) -and (Test-Path $mcpConfigFile)) {
-    try {
-        $mcpConfig = Get-Content -Raw $mcpConfigFile | ConvertFrom-Json
-        $pythonCommand = [string]$mcpConfig.mcpServers.codecgc.command
-    } catch {
-        $pythonCommand = ""
-    }
-}
-if ([string]::IsNullOrWhiteSpace($pythonCommand)) {
-    $pythonCommand = "python"
-}
-
-$psi = New-Object System.Diagnostics.ProcessStartInfo
-$psi.FileName = $pythonCommand
-$escapedPolicyScript = $policyScript.Replace('"', '\"')
-$escapedRoutingFile = $routingFile.Replace('"', '\"')
-$psi.Arguments = "`"$escapedPolicyScript`" --hook-check --actor claude --operation write --routing-file `"$escapedRoutingFile`""
-$psi.RedirectStandardInput = $true
-$psi.RedirectStandardOutput = $true
-$psi.RedirectStandardError = $true
-$psi.UseShellExecute = $false
-$psi.CreateNoWindow = $true
-
-$process = [System.Diagnostics.Process]::Start($psi)
-$process.StandardInput.Write($inputJson)
-$process.StandardInput.Close()
-$stdout = $process.StandardOutput.ReadToEnd()
-$stderr = $process.StandardError.ReadToEnd()
-$process.WaitForExit()
-
-if ($process.ExitCode -ne 0) {
-    $detail = if ([string]::IsNullOrWhiteSpace($stderr)) { $stdout } else { $stderr }
-    Write-Deny "CodeCGC: policy checker failed. $detail"
-}
-
-if ([string]::IsNullOrWhiteSpace($stdout)) {
-    Write-Approve
-}
-
-[Console]::Out.Write($stdout)