add-coder 0.2.7 → 0.2.10

package/README.en.md

@@ -27,7 +27,26 @@ Traditional AI development: Chat → Generate code → Dig through chat history
 | Auditing relies on developer discipline | The **MCP audit toolchain** automatically records every operation; system gateways enforce checks |
 | No traceability | Audit events are naturally linked: Plan → Spec → Task → Step → Tool Call, forming a complete evidence chain |
 
-### ② Gateway-Driven, Not Free-Form Conversation
+### ② Prompt Cache Native — ¥218/mo, 98% Savings
+
+The ADD paradigm isn't just methodology — its structured Step workflow naturally aligns with DeepSeek's Prompt Cache prefix-matching mechanism, delivering extreme token cost efficiency. **Real-world billing validation**:
+
+| Metric | Value |
+|--------|-------|
+| July actual DeepSeek bill | **¥218.35** |
+| Theoretical cost without cache | ¥11,100 |
+| Cache hit rate | **99.31%** |
+| Cache hit vs miss price gap | **120x** (¥0.025/M vs ¥3/M) |
+| Total cost savings | **98.1%** |
+
+```
+Traditional IDE free chat:  cache hit rate 85–91%, ~5,000 MISS tokens/req
+ADD paradigm + Qoder:       cache hit rate 99.31%, only 2,426 MISS tokens/req
+```
+
+> 📊 [Full analysis report](./docs/ADD范式缓存命中分析报告.md) — 4 Mermaid diagrams, 17-day daily data, cross-IDE comparison, and cost modeling.
+
+### ③ Gateway-Driven, Not Free-Form Conversation
 
 Traditional AI coding is "you say, I do" — quality depends entirely on the LLM's state that day. add-coder embeds **dual quality gateways** into the architecture:
 
@@ -38,7 +57,7 @@ RAHS (Runtime Architecture Health Score) — Runtime architecture health, < 90%
 
 These are not "suggestions" — they are **architectural blocks**. A Step cannot advance without passing its gateway.
 
-### ③ Cross-Session Memory, Not Per-Session Amnesia
+### ④ Cross-Session Memory, Not Per-Session Amnesia
 
 The fatal flaw of AI conversations: architectural decisions from last session, bugs fixed, agreements reached — all forgotten in the next conversation. add-coder solves this at the architecture level:
 
@@ -46,7 +65,7 @@ The fatal flaw of AI conversations: architectural decisions from last session, b
 - **Plan Index** — All Plans are centrally indexed via `index.md`, supporting fuzzy-match quick lookup
 - **DevLog Timeline** — Every operation is written to the `{YYYY-MM}/{DD}/` timeline, enabling full historical state traceability
 
-### ④ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
+### ⑤ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
 
 Not a static template, but a **closed-loop adaptive system**:
 
@@ -56,7 +75,7 @@ Execute → Audit → Boundary Report → Rule Adjustment → Next Execution
 
 Runtime-generated Reports feed back into governance rules, enabling continuous evolution of governance strategies.
 
-### ⑤ Multi-IDE Hooks as the Governance Layer
+### ⑥ Multi-IDE Hooks as the Governance Layer
 
 Hooks are not "notification push" — they are the **IDE runtime interception layer**:
 

package/README.md

@@ -1,5 +1,7 @@
 # add-coder
 
+Make 0.75 into one.
+
 > 🀄中文 | 🔤[English](#-english-readme)
 
 **AI 代码治理的落地方案** — [codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。 [NPM](https://www.npmjs.com/package/add-coder) · [GitHub](https://github.com/xiaomingming92/add-coder)
@@ -27,7 +29,26 @@ npx add-coder init
 | 审计靠开发者自觉记录 | **MCP 审计工具链** 自动记录每次操作，系统闸门强制检查 |
 | 无关联性 | 审计事件天然关联 Plan → Spec → Task → Step → Tool Call，形成完整证据链 |
 
-### ② 门禁驱动，而非自由对话
+### ② Prompt Cache 原生友好 — 月费 ¥218，节省 98%
+
+ADD 范式不仅是方法论——它的结构化 Step 流程天然适配 DeepSeek Prompt Cache 的前缀匹配机制，带来极致的 Token 成本效率。**实测数据验证**：
+
+| 指标 | 数值 |
+|------|------|
+| DeepSeek 7月实际账单 | **¥218.35** |
+| 若无 Prompt Cache 理论费用 | ¥11,100 |
+| Cache 命中率 | **99.31%** |
+| 缓存命中 vs 未命中价差 | **120 倍**（¥0.025/M vs ¥3/M） |
+| 总费用节省 | **98.1%** |
+
+```
+传统 IDE 自由对话:  cache 命中率 85-91%, 每次请求 MISS 5,000 tokens
+ADD 范式 + Qoder:     cache 命中率 99.31%, 每次请求 MISS 仅 2,426 tokens
+```
+
+> 📊 [完整分析报告](./docs/ADD范式缓存命中分析报告.md) — 含 4 张 Mermaid 图表、17 天逐日数据、跨 IDE 对比与成本建模。
+
+### ③ 门禁驱动，而非自由对话
 
 传统 AI coding 是「你说我做」，质量完全依赖 LLM 当天状态。add-coder 在架构中嵌入了 **双质量闸门**：
 
@@ -38,7 +59,7 @@ RAHS (Runtime Architecture Health Score) — 运行时架构健康度，< 90% BL
 
 这不是「建议」，是**架构阻断** — 不通过闸门的 Step 无法推进到下一步。
 
-### ③ 跨轮记忆，而非每轮失忆
+### ④ 跨轮记忆，而非每轮失忆
 
 AI 对话的致命缺陷：上次讨论的架构决策、已修复的 Bug、达成的约定，下轮对话全部遗忘。add-coder 在架构层面解决：
 
@@ -46,7 +67,7 @@ AI 对话的致命缺陷：上次讨论的架构决策、已修复的 Bug、达
 - **Plan 索引** — 所有 Plan 通过 `index.md` 集中索引，支持模糊匹配快速定位
 - **DevLog 时序记录** — 每一步操作写入 `{YYYY-MM}/{DD}/` 时间轴，可回溯任意历史状态
 
-### ④ Policy-Update-Loop：治理自我进化(脚手架不包含此架构能力,接下来会给到DEMO仓库让大家更好理解Policy-Update-Loop和Report体系)
+### ⑤ Policy-Update-Loop：治理自我进化(脚手架不包含此架构能力,接下来会给到DEMO仓库让大家更好理解Policy-Update-Loop和Report体系)
 
 不是静态模板，而是**闭环自适应系统**：
 
@@ -56,7 +77,7 @@ AI 对话的致命缺陷：上次讨论的架构决策、已修复的 Bug、达
 
 运行时产生的 Report 会反过来更新 governance rules，实现治理策略的持续进化。
 
-### ⑤ 多 IDE 的 Hook 即治理层
+### ⑥ 多 IDE 的 Hook 即治理层
 
 hook 不是「通知推送」，而是 **ADD 范式在 IDE agent 生命周期中的 17 个确定性治理卡位**。每个 IDE（Claude Code / Qoder CN / VS Code Copilot / Trae / Codex）有各自的 hook 机制，但治理逻辑统一——架构一致，适配层不同。
 
@@ -134,7 +155,21 @@ npx add-coder init
 
 ## MCP 审计工具链
 
-`init` 自动部署 MCP 服务器 (`mcp-server.ts`) 到项目中，IDE 通过 `mcp.json` 加载。提供以下审计与治理工具：
+`init` 自动部署 MCP 服务器 (`mcp-server.ts`) 到项目中，IDE 通过 `mcp.json` 加载。基于 **MCP 协议六大能力**（四大原语 + 两个横切）：
+
+```
+MCP 能力            方向              当前状态     说明
+─────────────────────────────────────────────────────────────
+Tools              Client→Server     ✅ 已实现     18 个审计与治理工具（pull 模式）
+Resources+Sub      Client←Server     ✅ 已实现      8 个端点 Plan/Review/Route/Task/Hook 状态推送
+Notifications      Server→Client     ✅ 已实现      HITL 就绪 + Hook 拦截事件推送
+Sampling           Server→Client     ✅ 已实现      服务端回调 AI 生成 Review (HITL 两步法)
+── 横切 ──
+Elicitation        Server→Client     ✅ 已实现      向用户请求 HITL 确认/风险输入
+Tasks (实验性)     双向              ✅ 已实现      长任务持久化 + 状态追踪
+```
+
+**当前已实现的 18 个 Tools**：
 
 | 工具 | 用途 | 触发场景 |
 |------|------|---------|
@@ -147,8 +182,9 @@ npx add-coder init
 | `check_add_route_status` | add-route 文件存在性校验 | Step 3 前 |
 | `check_spec_sync` | Spec 文档勾选状态与代码一致性 | Spec 执行后 |
 | `find_related_docs` | 检索相关架构/规范文档 | 语境理解 |
+| `get_hook_events` | 查询 Hook 拦截事件（planKeyword/hook/时间过滤+分组） | 治理审计、阈值告警 |
 
-> 完整工具列表见 [MCP 工具链规范](https://github.com/xiaomingming92/codein2027/blob/main/docs/大田精准耕播智能决策系统/knowledge/02-规范/%E3%80%8A%E5%BC%80%E5%8F%91%E6%93%8D%E4%BD%9C%E5%AE%A1%E8%AE%A1%E5%AD%98%E6%A1%A3%E8%A7%84%E8%8C%83%E3%80%8B.md)。
+> 完整六能力架构设计见 [MCP 重构 Plan](.qoder/plans/2026-07/23/add-coder-mcp-restructure-plan-v1.md)。
 
 ## 架构全景
 
@@ -213,11 +249,12 @@ npx add-coder init
 
 ## 🎬 预告
 
-| 计划 | 说明 |
-|------|------|
-| Demo 仓库演示 | 提供完整示例仓库，展示 Policy-Update-Loop 与 Report 体系的端到端闭环实践 |
-| MCP 能力重构 | MCP 工具链架构升级，提升审计与门禁工具的可扩展性和独立部署能力 |
-| 对话记忆增强 | 长期项目知识记忆和plan级别的稀疏记忆 |
+| 计划 | 说明 |备注|
+|------|------|------|
+| Demo 仓库演示 | 提供完整示例仓库，展示 Policy-Update-Loop 与 Report 体系的端到端闭环实践 |--|
+| MCP 能力重构 | ✅ v0.2.9 MCP 工具链架构升级，提升审计与门禁工具的可扩展性和独立部署能力 | 2026-07/23/add-coder-mcp-restructure-plan-v1.md |
+| Hook 通知升级 | ✅ v0.2.9 Hook 拦截事件 jsonl → fs.watch → record_dev_operation 落库 + Notification + 治理信号 | 2026-07/24/add-coder-hook-notify-upgrade-plan-v1.md |
+| 对话记忆增强 | 长期项目知识记忆和plan级别的稀疏记忆 |--|
 
 
 
@@ -249,7 +286,26 @@ Traditional AI development: Chat → Generate code → Dig through chat history
 | Auditing relies on developer discipline | The **MCP audit toolchain** automatically records every operation; system gateways enforce checks |
 | No traceability | Audit events are naturally linked: Plan → Spec → Task → Step → Tool Call, forming a complete evidence chain |
 
-### ② Gateway-Driven, Not Free-Form Conversation
+### ② Prompt Cache Native — ¥218/mo, 98% Savings
+
+The ADD paradigm isn't just methodology — its structured Step workflow naturally aligns with DeepSeek's Prompt Cache prefix-matching mechanism, delivering extreme token cost efficiency. **Real-world billing validation**:
+
+| Metric | Value |
+|--------|-------|
+| July actual DeepSeek bill | **¥218.35** |
+| Theoretical cost without cache | ¥11,100 |
+| Cache hit rate | **99.31%** |
+| Cache hit vs miss price gap | **120x** (¥0.025/M vs ¥3/M) |
+| Total cost savings | **98.1%** |
+
+```
+Traditional IDE free chat:  cache hit rate 85–91%, ~5,000 MISS tokens/req
+ADD paradigm + Qoder:       cache hit rate 99.31%, only 2,426 MISS tokens/req
+```
+
+> 📊 [Full analysis report](./docs/ADD范式缓存命中分析报告.md) — 4 Mermaid diagrams, 17-day daily data, cross-IDE comparison, and cost modeling.
+
+### ③ Gateway-Driven, Not Free-Form Conversation
 
 Traditional AI coding is "you say, I do" — quality depends entirely on the LLM's state that day. add-coder embeds **dual quality gateways** into the architecture:
 
@@ -260,7 +316,7 @@ RAHS (Runtime Architecture Health Score) — Runtime architecture health, < 90%
 
 These are not "suggestions" — they are **architectural blocks**. A Step cannot advance without passing its gateway.
 
-### ③ Cross-Session Memory, Not Per-Session Amnesia
+### ④ Cross-Session Memory, Not Per-Session Amnesia
 
 The fatal flaw of AI conversations: architectural decisions from last session, bugs fixed, agreements reached — all forgotten in the next conversation. add-coder solves this at the architecture level:
 
@@ -268,7 +324,7 @@ The fatal flaw of AI conversations: architectural decisions from last session, b
 - **Plan Index** — All Plans are centrally indexed via `index.md`, supporting fuzzy-match quick lookup
 - **DevLog Timeline** — Every operation is written to the `{YYYY-MM}/{DD}/` timeline, enabling full historical state traceability
 
-### ④ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
+### ⑤ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
 
 Not a static template, but a **closed-loop adaptive system**:
 
@@ -278,7 +334,7 @@ Execute → Audit → Boundary Report → Rule Adjustment → Next Execution
 
 Runtime-generated Reports feed back into governance rules, enabling continuous evolution of governance strategies.
 
-### ⑤ Multi-IDE Hooks as the Governance Layer
+### ⑥ Multi-IDE Hooks as the Governance Layer
 
 Hooks are not "notification push" — they are the **IDE runtime interception layer**:
 
@@ -445,10 +501,11 @@ npx add-coder init
 
 ## 🎬 Coming Soon
 
-| Plan | Description |
-|------|-------------|
-| Demo Repo | A full example repository showcasing end-to-end closed-loop practice of Policy-Update-Loop and the Report system |
-| MCP Restructure | MCP toolchain architecture upgrade, improving audit and gateway tool extensibility and standalone deployment capability |
-| Memory Enhancement | Long-term project knowledge memory and plan-level sparse memory |
+| Plan | Description | remark |
+|------|-------------|:---:|
+| Demo Repo | Full example repository showcasing Policy-Update-Loop with Report system end-to-end | 📋 |
+| ~~MCP Restructure~~ | ✅ v0.2.9 3,467-line monolith → 27 modules covering all six MCP primitives | 2026-07/23/... |
+| ~~Hook Notification Upgrade~~ | ✅ v0.2.9 ~36 files: hook intercept → jsonl → fs.watch → record_dev_operation | 2026-07/24/... |
+| Memory Enhancement | Long-term project knowledge memory and plan-level sparse memory | 📋 |
 
 ---

package/dist/index.js

@@ -893,6 +893,16 @@ async function renderAndWrite(ctx) {
     for (const [p, c] of claudeFiles) allFiles.set(p, c);
     console.log(`claude adapter (via Agent Host): ${claudeFiles.size} \u6587\u4EF6`);
   }
+  for (const d of [".add", magicDir]) {
+    const reviewsDir = resolve5(projectRoot, d, "reviews");
+    if (!existsSync6(reviewsDir)) {
+      if (dry) {
+        console.log(`[dry-run] \u5C06\u521B\u5EFA ${reviewsDir}/`);
+      } else {
+        mkdirSync3(reviewsDir, { recursive: true });
+      }
+    }
+  }
   return await writeFiles2(projectRoot, allFiles, { force: options.force, dryRun: options.dryRun });
 }
 async function deployDatabase(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.2.7",
+  "version": "0.2.10",
   "private": false,
   "description": "[codein2027](https://github.com/xiaomingming92/codein2027) - A complete scaffolding for building the ADD programming paradigm, the implementation layer for AI code governance. Core principle: Audit as Infrastructure. Breaks the black-box programming process and cross-session amnesia, evolving programming paradigms into an auditable, traceable, and convergent new era. npx-ready.\n\n[codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架——AI 代码治理的落地方案。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。npx 即用，人人可体验。",
   "repository": {
@@ -38,19 +38,18 @@
   "email": "wujixmm@gmail.com",
   "license": "AGPL-3.0-only",
   "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0-beta.5",
     "commander": "^13.1.0",
     "smol-toml": "^1.7.0",
-    "zod": "^3.24.0"
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "@prisma/adapter-libsql": "^7.0.0",
     "@prisma/adapter-pg": "^7.0.0",
     "@prisma/client": "^7.0.0",
     "dotenv": "*",
     "prisma": "^7.0.0",
-    "tsx": "*",
-    "zod": "^3.24.0"
+    "tsx": ">=4"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {
@@ -59,12 +58,6 @@
     "prisma": {
       "optional": false
     },
-    "@modelcontextprotocol/sdk": {
-      "optional": false
-    },
-    "zod": {
-      "optional": false
-    },
     "dotenv": {
       "optional": false
     },

package/templates/adapters/claude/hooks/doc-format-guard.sh

@@ -8,6 +8,18 @@ input=$(cat)
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 PARENT_DIR="$(dirname "$HOOK_DIR")"
 MAGIC_DIR="$(basename "$PARENT_DIR")"
+PROJECT_DIR="$PWD"
+
+# ── Hook 通知: 拦截事件写入 jsonl（旁路，失败不阻断 exit 2）──
+source "${HOOK_DIR}/lib/notify.sh" 2>/dev/null || true
+ACTIVE_PLAN=$(detect_active_add 2>/dev/null || true)
+if [ -n "$ACTIVE_PLAN" ]; then
+  PLAN_KEYWORD="${ACTIVE_PLAN%%::*}"
+  PLAN_STATUS="active"
+else
+  PLAN_KEYWORD="no-active-plan"
+  PLAN_STATUS="none"
+fi
 
 # DEBUG: dump stdin for investigation
 mkdir -p "$MAGIC_DIR/debug-dump"
@@ -44,6 +56,7 @@ CONTENT=$(echo "$input" | jq -r '
 if [ -z "$CONTENT" ]; then
   echo "⛔ 拒绝：Write 工具未传 file_content，无法校验手写文档格式" >&2
   echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Write 工具未传 file_content，无法校验手写文档。请用 SearchReplace 改写已有文件，或用 Write 工具重试。"}}'
+  write_hook_event "doc-format-guard" "deny" "Write" "Write 工具未传 file_content" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 
@@ -91,6 +104,7 @@ if [ -z "$TEMPLATE_NAME" ]; then
         else
           echo "⛔ handoff 文件内容无法识别模板类型（缺 '## 全局元信息' 或 '## 1. 交接前状态'），拒绝写入" >&2
           echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"handoff 内容不符合 single/multi 模板规范"}}'
+          write_hook_event "doc-format-guard" "deny" "$file_path" "handoff 模板类型无法识别" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
           exit 2
         fi
         ;;
@@ -111,6 +125,7 @@ if [ -z "$TEMPLATE_NAME" ]; then
         fi
         echo "⛔ 拒绝：无法识别文档类型 (file_path: $file_path)，缺少模板匹配规则" >&2
         echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"无法识别 ADD 文档类型，请联系管理员更新 doc-format-guard.sh"}}'
+        write_hook_event "doc-format-guard" "deny" "$file_path" "无法识别文档类型" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
         exit 2
         ;;
     esac
@@ -122,6 +137,7 @@ SCHEMA_FILE="$TEMPLATES_DIR/${TEMPLATE_NAME%.md}.schema.json"
 if [ ! -f "$SCHEMA_FILE" ]; then
   echo "⛔ 阻断：模板 ${TEMPLATE_NAME} 缺少对应的 .schema.json 校验规则" >&2
   echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"缺少 .schema.json 校验规则文件，禁止无规则放行"}}'
+  write_hook_event "doc-format-guard" "deny" "$file_path" "缺少 .schema.json 校验规则" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 
@@ -172,6 +188,7 @@ if [ -n "$ISSUES" ]; then
   echo "⛔ $TEMPLATE_NAME 校验不通过:
 $ISSUES" >&2
   echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"文档格式校验不通过，请对照模板修正\"}}"
+  write_hook_event "doc-format-guard" "deny" "$file_path" "文档格式校验不通过" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 

package/templates/adapters/claude/hooks/lib/notify.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# notify.sh — Hook 拦截事件写入 jsonl（零外部依赖，bash 原生）
+# 用法: source 后在 exit 2 前调用 write_hook_event
+#
+# 写入格式（7 字段 jsonl）:
+#   {"ts":"ISO8601","hook":"...","decision":"deny","cmd":"...","reason":"...","planKeyword":"...","planStatus":"..."}
+#
+# 磁盘管理:
+#   - 单文件 ≤256KB，超限轮转为 .old（覆盖，不累积多份）
+#   - 总量 ≤512KB（当前 + 一个 .old）
+#   - MCP Server 宕机不丢事件，重启后从文件恢复消费
+
+write_hook_event() {
+  local hook="$1" decision="$2" cmd="$3" reason="$4" plan="${5:-unknown}" status="${6:-none}"
+  local dir="${MAGIC_DIR:-.qoder}/reports"
+  mkdir -p "$dir" 2>/dev/null || true
+  local file="$dir/hook-events.jsonl"
+
+  # 超过 256KB 自动轮转（262144 bytes）
+  if [ -f "$file" ]; then
+    local sz
+    sz=$(stat -c%s "$file" 2>/dev/null || echo 0)
+    [ "$sz" -gt 262144 ] && mv "$file" "${file}.old" 2>/dev/null || true
+  fi
+
+  printf '{"ts":"%s","hook":"%s","decision":"%s","cmd":"%s","reason":"%s","planKeyword":"%s","planStatus":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$hook" \
+    "$decision" \
+    "$cmd" \
+    "$reason" \
+    "$plan" \
+    "$status" >> "$file"
+}

package/templates/adapters/claude/hooks/pre-tool-use.sh

@@ -7,6 +7,17 @@ HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
 COMMON_LIB="$HOOK_DIR/lib/common.sh"
 [ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
+[ -f "$HOOK_DIR/lib/notify.sh" ] && source "$HOOK_DIR/lib/notify.sh" 2>/dev/null || true
+
+# ── Hook 通知: 提前计算 Plan 关联信息 ──
+ACTIVE_PLAN=$(detect_active_add 2>/dev/null || true)
+if [ -n "$ACTIVE_PLAN" ]; then
+  PLAN_KEYWORD="${ACTIVE_PLAN%%::*}"
+  PLAN_STATUS="active"
+else
+  PLAN_KEYWORD="no-active-plan"
+  PLAN_STATUS="none"
+fi
 
 input=$(parse_input)
 tool_name=$(json_get "$input" "tool_name")
@@ -20,21 +31,25 @@ if [ "$tool_name" = "Bash" ]; then
   # 危险命令
   if echo "$cmd" | grep -qiE 'rm[[:space:]]+-rf[[:space:]]+/|DROP[[:space:]]+TABLE|git[[:space:]]+push[[:space:]]+--force|mkfs\.|dd[[:space:]]+if='; then
     echo "⛔ 危险命令已被阻止: $cmd" >&2
+    write_hook_event "pre-tool-use" "deny" "$cmd" "危险命令已被阻止" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
     exit $EXIT_BLOCK
   fi
   # 终端写文件拦截（含 > / >> / << heredoc / mv / touch / python -c > file）
   if echo "$cmd" | grep -qE '(cat|echo|tee|sed[[:space:]]+-i|awk|printf|cp|mv|dd|touch)[[:space:]]*.*([>]{1,2}|[|][[:space:]]*tee|<<)'; then
     echo "⛔ 禁止通过终端命令直接写文件: $cmd。请使用 Write/Edit/SearchReplace 工具。" >&2
+    write_hook_event "pre-tool-use" "deny" "$cmd" "禁止通过终端直接写文件" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
     exit $EXIT_BLOCK
   fi
-  # mv 无重定向但仍操作文件
-  if echo "$cmd" | grep -qE '^[[:space:]]*mv[[:space:]]+/tmp/'; then
-    echo "⛔ 禁止通过 mv /tmp/ 绕过 IDE 工具: $cmd" >&2
+  # cp / mv / touch — 可创建或覆盖文件，无重定向也拦（对齐 core §A 检测5）
+  if echo "$cmd" | grep -qE '(^|;|\|\||&&|\|)\s*(cp|mv|touch)\b'; then
+    echo "⛔ 禁止通过 cp/mv/touch 操作文件: $cmd。请使用 Write 或 SearchReplace 工具。" >&2
+    write_hook_event "pre-tool-use" "deny" "$cmd" "禁止通过 cp/mv/touch 操作文件" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
     exit $EXIT_BLOCK
   fi
-  # python/node 脚本写文件
-  if echo "$cmd" | grep -qE '(python3|python|node)[[:space:]].*[>]{1,2}'; then
-    echo "⛔ 禁止通过脚本语言直接写文件: $cmd。请使用 Write/Edit/SearchReplace 工具。" >&2
+  # python/node/ruby/perl/php 脚本解释器 — 可写任意文件
+  if echo "$cmd" | grep -qE '(^|;|\|\||&&|\|)\s*(python3?|node|ruby|perl|php)(\s|$)'; then
+    echo "⛔ 禁止通过脚本解释器直接写文件: $cmd。请使用 Write 或 SearchReplace 工具。" >&2
+    write_hook_event "pre-tool-use" "deny" "$cmd" "禁止通过脚本解释器直接修改文件" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
     exit $EXIT_BLOCK
   fi
   mark_dev_action
@@ -51,7 +66,10 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ]; then
     if type detect_active_add >/dev/null 2>&1; then
       state=$(detect_active_add 2>/dev/null || true)
       if [ -z "$state" ]; then
-        echo "[ADD PreToolUse] ⚠️ 正在写入 Plan/Spec/Review 文档但无活跃 ADD Plan——请先执行 add-paradigm" >&2
+        echo "⛔ 正在写入 Plan/Spec/Review 文档但无活跃 ADD Plan——请先执行 add-paradigm" >&2
+        echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Plan/Spec/Review 写入需要活跃 ADD Plan，请先执行 add-paradigm\"}}"
+        write_hook_event "pre-tool-use" "deny" "$file_path" "Plan/Spec/Review 写入需活跃 ADD Plan" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
+        exit $EXIT_BLOCK
       fi
     fi
   fi
@@ -59,6 +77,7 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ]; then
   # 敏感文件保护
   if echo "$file_path" | grep -qE '\.env$|\.env\.production$|\.env\.local$|credentials|secrets'; then
     echo "⛔ 敏感文件受保护，禁止写入: $file_path" >&2
+    write_hook_event "pre-tool-use" "deny" "$file_path" "敏感文件受保护" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
     exit $EXIT_BLOCK
   fi
 

package/templates/adapters/claude/hooks/prompt-submit.sh

@@ -8,6 +8,7 @@ export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
 
 COMMON_LIB="$HOOK_DIR/lib/common.sh"
 [ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
+[ -f "$HOOK_DIR/lib/notify.sh" ] && source "$HOOK_DIR/lib/notify.sh" 2>/dev/null || true
 
 export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
 
@@ -56,6 +57,7 @@ if [ -z "$state" ]; then
   Step 8: 收敛判断
 如果 add-paradigm SKILL 尚未激活，请先调用它。
 EOF
+  write_hook_event "prompt-submit" "deny" "$prompt" "无活跃 ADD Plan 下检测到开发任务" "no-active-plan" "none" 2>/dev/null || true
   exit 2
 fi
 
@@ -69,6 +71,20 @@ cat <<EOF
   handoff: ${handoff}
 EOF
 
+# ─── Hook 治理日报（注入 AI 上下文）───
+HOOK_JSONL="${MAGIC_DIR:-.qoder}/reports/hook-events.jsonl"
+if [ -f "$HOOK_JSONL" ]; then
+  TODAY="$(date +%Y-%m-%d)"
+  TOTAL=$(grep -c "\"ts\":\"${TODAY}" "$HOOK_JSONL" 2>/dev/null || echo 0)
+  NO_PLAN=$(grep "\"ts\":\"${TODAY}" "$HOOK_JSONL" 2>/dev/null | grep -c '"planKeyword":"no-active-plan"' || echo 0)
+  if [ "$TOTAL" -gt 0 ] 2>/dev/null; then
+    echo "[Hook 治理] 今日拦截: ${TOTAL} 次 | 无 Plan 违规: ${NO_PLAN} 次"
+    if [ "$NO_PLAN" -ge 10 ] 2>/dev/null; then
+      echo "[Hook ⚠️] 无 Plan 违规已达 ${NO_PLAN} 次（≥10），建议创建 Plan"
+    fi
+  fi
+fi
+
 # 模板全文注入（tpl-injected 去重）
 TPL_SCRIPT="$HOOK_DIR/lib/preload-templates.sh"
 if [ -f "$TPL_SCRIPT" ]; then

package/templates/adapters/codex/hooks/doc-format-guard.sh

@@ -5,6 +5,18 @@ set -euo pipefail
 input=$(cat)
 
 MAGIC_DIR=".codex"
+PROJECT_DIR="$PWD"
+
+# ── Hook 通知: 拦截事件写入 jsonl（旁路，失败不阻断 exit 2）──
+source "${HOOK_DIR}/lib/notify.sh" 2>/dev/null || true
+ACTIVE_PLAN=$(detect_active_add 2>/dev/null || true)
+if [ -n "$ACTIVE_PLAN" ]; then
+  PLAN_KEYWORD="${ACTIVE_PLAN%%::*}"
+  PLAN_STATUS="active"
+else
+  PLAN_KEYWORD="no-active-plan"
+  PLAN_STATUS="none"
+fi
 
 # DEBUG: dump stdin for investigation
 mkdir -p "$MAGIC_DIR/debug-dump"
@@ -41,6 +53,7 @@ CONTENT=$(echo "$input" | jq -r '
 if [ -z "$CONTENT" ]; then
   echo "⛔ 拒绝：Write 工具未传 file_content，无法校验手写文档格式" >&2
   echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Write 工具未传 file_content，无法校验手写文档。请用 SearchReplace 改写已有文件，或用 Write 工具重试。"}}'
+  write_hook_event "doc-format-guard" "deny" "Write" "Write 工具未传 file_content" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 
@@ -90,6 +103,7 @@ if [ -z "$TEMPLATE_NAME" ]; then
         else
           echo "⛔ handoff 文件内容无法识别模板类型（缺 '## 全局元信息' 或 '## 1. 交接前状态'），拒绝写入" >&2
           echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"handoff 内容不符合 single/multi 模板规范"}}'
+          write_hook_event "doc-format-guard" "deny" "$file_path" "handoff 模板类型无法识别" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
           exit 2
         fi
         ;;
@@ -110,6 +124,7 @@ if [ -z "$TEMPLATE_NAME" ]; then
         fi
         echo "⛔ 拒绝：无法识别文档类型 (file_path: $file_path)，缺少模板匹配规则" >&2
         echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"无法识别 ADD 文档类型，请联系管理员更新 doc-format-guard.sh"}}'
+        write_hook_event "doc-format-guard" "deny" "$file_path" "无法识别文档类型" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
         exit 2
         ;;
     esac
@@ -121,6 +136,7 @@ SCHEMA_FILE="$TEMPLATES_DIR/${TEMPLATE_NAME%.md}.schema.json"
 if [ ! -f "$SCHEMA_FILE" ]; then
   echo "⛔ 阻断：模板 ${TEMPLATE_NAME} 缺少对应的 .schema.json 校验规则" >&2
   echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"缺少 .schema.json 校验规则文件，禁止无规则放行"}}'
+  write_hook_event "doc-format-guard" "deny" "$file_path" "缺少 .schema.json 校验规则" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 
@@ -227,6 +243,7 @@ if [ -n "$ISSUES" ]; then
   echo "⛔ $TEMPLATE_NAME 校验不通过:
 $ISSUES" >&2
   echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"文档格式校验不通过，请对照模板修正\"}}"
+  write_hook_event "doc-format-guard" "deny" "$file_path" "文档格式校验不通过" "$PLAN_KEYWORD" "$PLAN_STATUS" 2>/dev/null || true
   exit 2
 fi
 

package/templates/adapters/codex/hooks/lib/notify.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# notify.sh — Hook 拦截事件写入 jsonl（零外部依赖，bash 原生）
+# 用法: source 后在 exit 2 前调用 write_hook_event
+#
+# 写入格式（7 字段 jsonl）:
+#   {"ts":"ISO8601","hook":"...","decision":"deny","cmd":"...","reason":"...","planKeyword":"...","planStatus":"..."}
+#
+# 磁盘管理:
+#   - 单文件 ≤256KB，超限轮转为 .old（覆盖，不累积多份）
+#   - 总量 ≤512KB（当前 + 一个 .old）
+#   - MCP Server 宕机不丢事件，重启后从文件恢复消费
+
+write_hook_event() {
+  local hook="$1" decision="$2" cmd="$3" reason="$4" plan="${5:-unknown}" status="${6:-none}"
+  local dir="${MAGIC_DIR:-.qoder}/reports"
+  mkdir -p "$dir" 2>/dev/null || true
+  local file="$dir/hook-events.jsonl"
+
+  # 超过 256KB 自动轮转（262144 bytes）
+  if [ -f "$file" ]; then
+    local sz
+    sz=$(stat -c%s "$file" 2>/dev/null || echo 0)
+    [ "$sz" -gt 262144 ] && mv "$file" "${file}.old" 2>/dev/null || true
+  fi
+
+  printf '{"ts":"%s","hook":"%s","decision":"%s","cmd":"%s","reason":"%s","planKeyword":"%s","planStatus":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$hook" \
+    "$decision" \
+    "$cmd" \
+    "$reason" \
+    "$plan" \
+    "$status" >> "$file"
+}