add-coder 0.3.27 → 0.3.28

package/templates/core/hooks/notification.ts

@@ -0,0 +1,11 @@
+// notification.ts — Notification 入口薄壳（Task 2.2/3.1 继承体系）
+// 治理逻辑: governance/notification-router.js（NotificationRouter 探测循环 + reviews 提醒）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { NotificationRouter } from "../governance/notification-router.js"
+
+const input = readHookInput()
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new NotificationRouter(PROJECT_DIR, ".add").run(input))

package/templates/core/hooks/permission-gate.ts

@@ -0,0 +1,7 @@
+// permission-gate.ts — PermissionRequest 入口薄壳（Task 5.1 继承体系）
+// 治理逻辑: governance/permission-gate-router.js（PermissionGateRouter——jq 语义解析 + emit 输出）
+// 入口职责: 仅进程语义（<50 行），治理 0 复制。
+
+import { runPermissionGate } from "../governance/permission-gate-router.js"
+
+runPermissionGate()

package/templates/core/hooks/post-tool-failure.ts

@@ -0,0 +1,7 @@
+// post-tool-failure.ts — PostToolUseFailure 入口薄壳（Task 5.1 继承体系）
+// 治理逻辑: governance/post-tool-failure-router.js（PostToolFailureRouter——jq 语义解析 + emit 输出）
+// 入口职责: 仅进程语义（<50 行），治理 0 复制。
+
+import { runPostToolFailure } from "../governance/post-tool-failure-router.js"
+
+runPostToolFailure()

package/templates/core/hooks/post-tool-use.ts

@@ -0,0 +1,23 @@
+// post-tool-use.ts — PostToolUse 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/post-tool-router.ts（PostToolRouter §1 DPS 哨兵 / §2 文档守卫 / §3 Bash 增强）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { jsonGet, readHookInput } from "../governance/common.js"
+import { PostToolRouter } from "../governance/post-tool-router.js"
+
+const input = readHookInput()
+let toolName = jsonGet(input, "tool_name")
+if (toolName === "") {
+  // bash 版此处 grep 兜底失败触发 set -e 崩溃（exit 1）——缺陷行为，
+  // TS 版修复：无 tool_name 的 PostToolUse 事件静默放行（冒烟契约 ∈ {0,2}）。
+  const fallback = input.match(/"tool_name"\s*:\s*"([^"]*)"/)?.[1] ?? ""
+  if (fallback === "") {
+    process.exit(0)
+  }
+  toolName = fallback
+}
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+const MAGIC_DIR = process.env.MAGIC_DIR || ".qoder"
+
+process.exit(new PostToolRouter(PROJECT_DIR, MAGIC_DIR).run(input, toolName))

package/templates/core/hooks/pre-compact.ts

@@ -0,0 +1,9 @@
+// pre-compact.ts — 上下文压缩前 ADD 状态保存（入口薄壳，Task 2.2/3.1 继承体系）
+// 治理逻辑: governance/pre-compact-guard.js（PreCompactGuard 状态保存 + tpl 标记清理）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { PreCompactGuard } from "../governance/pre-compact-guard.js"
+
+process.env.PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new PreCompactGuard().run())

package/templates/core/hooks/pre-tool-use.ts

@@ -0,0 +1,30 @@
+// pre-tool-use.ts — PreToolUse 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/pre-tool-guard.ts（PreToolUseGuard 服务类，规则消费 hook-guard-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { jsonGet, readHookInput, tryResolveMagicDir } from "../governance/common.js"
+import { PreToolUseGuard } from "../governance/pre-tool-guard.js"
+
+const input = readHookInput()
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+// 探测 MAGIC_DIR（唯一解析链：注入优先 → 物理位置推导）
+let MAGIC_DIR = process.env.MAGIC_DIR
+if (!MAGIC_DIR) {
+  MAGIC_DIR = tryResolveMagicDir() || ".qoder"
+}
+
+const guard = new PreToolUseGuard(PROJECT_DIR, MAGIC_DIR)
+
+const toolName = jsonGet(input, "tool_name")
+const command = jsonGet(input, "command")
+
+let exitCode = 0
+if (command !== "") {
+  exitCode = guard.runSectionA(input)
+  if (exitCode !== 0) process.exit(exitCode)
+} else {
+  exitCode = guard.runSectionB(input, toolName)
+  if (exitCode !== 0) process.exit(exitCode)
+}
+process.exit(0)

package/templates/core/hooks/prompt-submit.ts

@@ -0,0 +1,11 @@
+// prompt-submit.ts — UserPromptSubmit 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/prompt-router.ts（PromptRouter L1/L2/L3 分流，日报阈值消费 hook-event-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { PromptRouter } from "../governance/prompt-router.js"
+
+const input = readHookInput()
+const MAGIC_DIR = process.env.MAGIC_DIR || ".qoder"
+
+process.exit(new PromptRouter(MAGIC_DIR).run(input))

package/templates/core/hooks/review-checklist.ts

@@ -0,0 +1,4 @@
+// review-checklist.ts — Review 检查清单校验（bash 版 review-checklist.sh 的 TS 同语义实现）
+
+process.stdout.write("[ADD ReviewChecklist] 请在提交前确认 checklist.md 全部项已勾选。\n")
+process.exit(0)

package/templates/core/hooks/session-end.ts

@@ -0,0 +1,10 @@
+// session-end.ts — SessionEnd 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/session-end.ts（SessionEndGuard 清理 + 结算 + 兜底）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SessionEndGuard } from "../governance/session-end.js"
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+process.env.PROJECT_DIR = PROJECT_DIR
+
+process.exit(new SessionEndGuard(PROJECT_DIR).run())

package/templates/core/hooks/session-start.ts

@@ -0,0 +1,9 @@
+// session-start.ts — SessionStart 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/session-start-guard.ts（SessionStartGuard 状态恢复 + 模板索引 + 代办 + HITL）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SessionStartGuard } from "../governance/session-start-guard.js"
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new SessionStartGuard(PROJECT_DIR).run())

package/templates/core/hooks/stop-check.ts

@@ -0,0 +1,14 @@
+// stop-check.ts — Stop 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/stop-router.ts（StopRouter 四象限分流，象限文本消费 hook-context-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { tryResolveMagicDir } from "../governance/common.js"
+import { StopRouter } from "../governance/stop-router.js"
+
+// 对齐 bash: MAGIC_DIR 从物理位置推导并 export（入口注入优先）
+const inferredMagicDir = tryResolveMagicDir()
+if (inferredMagicDir && !process.env.MAGIC_DIR) {
+  process.env.MAGIC_DIR = inferredMagicDir
+}
+
+process.exit(new StopRouter().run())

package/templates/core/hooks/subagent-guard.ts

@@ -0,0 +1,8 @@
+// subagent-guard.ts — SubagentStart 入口薄壳（Task 3.1 能力对齐）
+// 治理逻辑: governance/subagent-guard-router.js（SubagentGuardRouter 状态注入——对齐强版语义）
+// 能力对齐注: 原 core 为弱版（事件提示空话），已对齐 claude/vscode/qoder 强版（状态注入）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SubagentGuardRouter } from "../governance/subagent-guard-router.js"
+
+process.exit(new SubagentGuardRouter().run())

package/templates/core/hooks/subagent-stop.ts

@@ -0,0 +1,9 @@
+// subagent-stop.ts — SubagentStop 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/subagent-stop-router.ts（SubagentStopRouter 边界校验 + 审计聚合）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { SubagentStopRouter } from "../governance/subagent-stop-router.js"
+
+const input = readHookInput()
+process.exit(new SubagentStopRouter().run(input))

package/templates/core/scripts/mcp-server/tools/gateway/check_rahs.ts

@@ -109,7 +109,18 @@ export function registerCheckRahs(server: ToolRegistrar) {
         try {
           // Spec 合规：checklist [T] 项勾选率（[R] 运行时项不计入）
           const specDir = join(PROJECT_ROOT, MAGIC_DIR, "specs");
-          const sn = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
+          // spec 目录名可能带 -vN 版本后缀：优先带版本匹配，回退不带版本 [Task 1.8 修复]
+          const rahsPlanBase = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
+          const rahsVersionSuffix = /-plan-(v\d+)$/i.exec(basename(pm, ".md"))?.[1] ?? "";
+          const rahsCandidates = rahsVersionSuffix
+            ? [`${rahsPlanBase}-${rahsVersionSuffix}`, rahsPlanBase]
+            : [rahsPlanBase];
+          const planContent = (await readFileSafe(join(plansDir, pm))) || "";
+          const rahsSpecRef = planContent.match(/specs\/([^/`\s]+)/);
+          if (rahsSpecRef) rahsCandidates.push(rahsSpecRef[1]);
+          const sn =
+            rahsCandidates.find((d) => existsSync(join(specDir, d))) ??
+            rahsCandidates[0];
           const clPath = join(specDir, sn, "checklist.md");
           if (existsSync(clPath)) {
             const cl = (await readFileSafe(clPath)) || "";

package/templates/core/scripts/mcp-server/tools/plan.ts

@@ -75,8 +75,18 @@ export function registerPlanTools(server: ToolRegistrar) {
         // 提取 planKeyword（关键词: xxx）
         const kwMatch = content.match(/关键词[:：]\s*(.+)/) || content.match(/planKeyword[:：]\s*"?([^"\n]+)"?/)
         const keyword = kwMatch?.[1]?.trim() || t.name
-        // 定位 spec dir
-        const specDirName = basename(t.name).replace(/-plan-v\d+$/, "")
+        // 定位 spec dir（目录名可能带 -vN 版本后缀：优先带版本匹配，再回退不带版本，
+        // 最后回退解析 Plan §六 关联文档 Spec 路径真源）[Task 1.8 修复]
+        const planBase = basename(t.name).replace(/-plan-v\d+$/, "")
+        const versionSuffix = /-plan-(v\d+)$/.exec(basename(t.name))?.[1] ?? ""
+        const specCandidates = versionSuffix
+          ? [`${planBase}-${versionSuffix}`, planBase]
+          : [planBase]
+        const specRef = content.match(/specs\/([^/`\s]+)/)
+        if (specRef) specCandidates.push(specRef[1])
+        const specDirName =
+          specCandidates.find((d) => existsSync(join(specsDir, d))) ??
+          specCandidates[0]
         const tasksPath = join(specsDir, specDirName, "tasks.md")
         const checklistPath = join(specsDir, specDirName, "checklist.md")
         const specPath = join(specsDir, specDirName, "spec.md")

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

@@ -1,283 +0,0 @@
-#!/bin/bash
-# doc-format-guard.sh — schema.json 驱动的 ADD 文档格式守卫
-set -euo pipefail
-
-input=$(cat)
-
-# 动态探测 MAGIC_DIR（兼容多 adapter）
-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"
-echo "=== $(date) ===" >> "$MAGIC_DIR/debug-dump/stdin.log"
-echo "file_path: $(echo "$input" | jq -r '.tool_input.file_path // "EMPTY"')" >> "$MAGIC_DIR/debug-dump/stdin.log"
-echo "has_file_content: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("file_content"))')" >> "$MAGIC_DIR/debug-dump/stdin.log"
-echo "has_replacements: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("replacements"))')" >> "$MAGIC_DIR/debug-dump/stdin.log"
-if echo "$input" | jq -e 'has("tool_input") and (.tool_input | has("file_content"))' > /dev/null 2>&1; then
-  echo "[file_content[500]]: $(echo "$input" | jq -r '.tool_input.file_content' | head -c 500)" >> "$MAGIC_DIR/debug-dump/stdin.log"
-fi
-if echo "$input" | jq -e 'has("tool_input") and (.tool_input | has("replacements"))' > /dev/null 2>&1; then
-  echo "[replacement_new_text[500]]: $(echo "$input" | jq -r '.tool_input.replacements[0].new_text' | head -c 500)" >> "$MAGIC_DIR/debug-dump/stdin.log"
-fi
-echo "top_keys: $(echo "$input" | jq -r 'keys | join(", ")')" >> "$MAGIC_DIR/debug-dump/stdin.log"
-echo "tool_input_keys: $(echo "$input" | jq -r '.tool_input | keys | join(", ") // "NO_TOOL_INPUT"')" >> "$MAGIC_DIR/debug-dump/stdin.log"
-echo "=== DONE ===" >> "$MAGIC_DIR/debug-dump/stdin.log"
-file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
-# L17: 非文件工具事件（空 stdin）→ 不拦截（由 matcher 层过滤）
-[ -z "$file_path" ] && exit 0
-
-if ! echo "$file_path" | grep -qE "$MAGIC_DIR/(plans|specs)/"; then
-  exit 0
-fi
-
-CONTENT=$(echo "$input" | jq -r '
-  if .tool_input.file_content then .tool_input.file_content
-  elif .tool_input.content then .tool_input.content
-  elif .tool_input.new_string then .tool_input.new_string
-  elif .tool_input.new_string then .tool_input.new_string
-  elif .tool_input.replacements then .tool_input.replacements[0].new_text
-  else "" end')
-# L24: PostToolUse 不可阻断（仅反馈），PreToolUse exit 2 + ask 可拦截
-# L24: 文件在 .qoder/(plans|specs)/ 下但 Write 工具未传 content → 无法校验，阻断
-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
-
-PROJECT_DIR="$PWD"
-TEMPLATES_DIR="$PROJECT_DIR/$MAGIC_DIR/templates"
-
-# 文件名类型 token 匹配（特异性排序，取代子串 grep；R5/Task 1.4）
-# review/handoff 不在此层绑定（需内容特征细分单多轮/运行时），留给下方探测链
-TEMPLATE_NAME=""
-base=$(basename "$file_path")
-base=${base%-v[0-9]*}
-case "$base" in
-  *add-route*heavy*) TEMPLATE_NAME="add-route-template-heavyweight.md" ;;
-  *add-route*)       TEMPLATE_NAME="add-route-template.md" ;;
-  *hitl*)            TEMPLATE_NAME="hitl-template.md" ;;
-  *handoff*)         : ;;  # R15: 跳过 token 层，交内容探测链；必须在 *report* 前，防含 report 的 handoff 被误吞
-  *checklist*)       TEMPLATE_NAME="checklist-template.md" ;;
-  *fix-verif*)       TEMPLATE_NAME="fix-verification-template.md" ;;
-  *report*runtime*)  TEMPLATE_NAME="runtime-report-template.md" ;;
-  *report*)          TEMPLATE_NAME="report-template.md" ;;
-  *tasks*)           TEMPLATE_NAME="tasks-template.md" ;;
-  *spec*)            TEMPLATE_NAME="spec-template.md" ;;
-  *plan*)            TEMPLATE_NAME="standard-plan-template.md" ;;
-esac
-
-# 退一步：根据文件内容特征猜测模板类型
-if [ -z "$TEMPLATE_NAME" ]; then
-  if grep -q "## 四、Handoff" <<< "$CONTENT"; then
-    TEMPLATE_NAME="simple-standard-plan-template.md"
-  elif grep -q "## PLAN 元信息" <<< "$CONTENT"; then
-    TEMPLATE_NAME="standard-plan-template.md"
-  elif grep -q "## Review 元信息" <<< "$CONTENT"; then
-    if grep -q "运行时验证" <<< "$CONTENT"; then
-      TEMPLATE_NAME="review-runtime-template.md"
-    elif grep -q "跨仓库格式契约" <<< "$CONTENT"; then
-      TEMPLATE_NAME="review-implementation-template.md"
-    else
-      TEMPLATE_NAME="review-template.md"
-    fi
-  elif grep -q "## Why" <<< "$CONTENT"; then
-    TEMPLATE_NAME="spec-template.md"
-  elif grep -q "## Preconditions" <<< "$CONTENT"; then
-    TEMPLATE_NAME="tasks-template.md"
-  elif grep -q "审计链（证据→devlog→checklist）" <<< "$CONTENT"; then
-    TEMPLATE_NAME="checklist-template.md"
-  else
-    case "$file_path" in
-      *handoff*)
-        # ★ 按内容特征区分单/多轮 handoff，不依赖文件名
-        if grep -qF "## 全局元信息" <<< "$CONTENT"; then
-          TEMPLATE_NAME="handoff-multi-round-template.md"
-        elif grep -qF "## 1. 交接前状态" <<< "$CONTENT"; then
-          TEMPLATE_NAME="handoff-single-round-template.md"
-        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
-        ;;
-      *add-route*heavy*) TEMPLATE_NAME="add-route-template-heavyweight.md" ;;
-      *add-route*)       TEMPLATE_NAME="add-route-template.md" ;;
-      *plan*)            TEMPLATE_NAME="standard-plan-template.md" ;;
-      *tasks*)           TEMPLATE_NAME="tasks-template.md" ;;
-      *spec*)            TEMPLATE_NAME="spec-template.md" ;;
-      *checklist*)       TEMPLATE_NAME="checklist-template.md" ;;
-      *report*runtime*)  TEMPLATE_NAME="runtime-report-template.md" ;;
-      *report*)          TEMPLATE_NAME="report-template.md" ;;
-      *fix-verif*)       TEMPLATE_NAME="fix-verification-template.md" ;;
-      *hitl*)           TEMPLATE_NAME="hitl-template.md" ;;
-      *) 
-        # 增量修订识别：包含 ~~删除线~~ / → 新增标记 / [修订日期] 任意一个 → 视为增量更新，放行
-        if grep -qE '~~.+~~|→|\[[0-9]{4}-[0-9]{2}-[0-9]{2}\s+修订' <<< "$CONTENT"; then
-          echo "[doc-format-guard] 检测到增量修订格式，跳过完整章节校验" >&2
-          exit 0
-        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
-  fi
-fi
-
-SCHEMA_FILE="$TEMPLATES_DIR/${TEMPLATE_NAME%.md}.schema.json"
-# L84: schema 文件不存在 → 无校验规则，阻断（不允许无规则放行）
-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
-
-# SearchReplace 只传 patch（replacements[].new_text），不传全文件 → 跳过章节校验
-IS_SEARCH_REPLACE=$(echo "$input" | jq -r '(.tool_input.replacements | length > 0) or (.tool_input.new_string != null) // false')
-
-ISSUES=""
-
-# ── 章节校验 ──
-# 使用项目目录下的临时文件，避免 /tmp 在沙箱中不可写导致静默跳过
-TMPFILE="$PROJECT_DIR/$MAGIC_DIR/.doc-guard-issues.tmp"
-: > "$TMPFILE"
-trap "rm -f $TMPFILE" EXIT
-
-# ── 锚定校验（锚定制：schema 声明 anchor，参照内容从模板现场提取；Task 1.2）──
-# 锚点不在模板 → 跳过该规则 + stderr 告警（不阻塞写入，冒烟巡检兑底）
-# within 前缀匹配；heading 缺失 → 跳过规则 + 告警（不误拦）
-if [ "$IS_SEARCH_REPLACE" != "true" ]; then
-  jq -r '.sections[] | select(.anchor != null) | .id + "|" + .anchor + "|" + (.within // "")' "$SCHEMA_FILE" 2>/dev/null | while IFS='|' read -r aid anchor within; do
-    [ -z "$anchor" ] && continue
-    ref_line=$(grep -m1 -F "$anchor" "$TEMPLATES_DIR/$TEMPLATE_NAME" 2>/dev/null || true)
-    if [ -z "$ref_line" ]; then
-      echo "[doc-format-guard] anchor_miss: schema ${aid} 声明的 anchor '${anchor}' 在 ${TEMPLATE_NAME} 中未定位，跳过该规则（冒烟巡检兑底）" >&2
-      continue
-    fi
-    tokens=$(echo "$ref_line" | tr '#*`|(){' '         ' | tr -s ' ' '\n' | grep -v '^$' | grep -vF '{' | sort -u)
-    [ -z "$tokens" ] && continue
-    scope="$CONTENT"
-    if [ -n "$within" ]; then
-      if grep -q "^${within}" <<< "$CONTENT"; then
-        scope=$(sed -n "/^${within}/,/^## /p" <<< "$CONTENT")
-      else
-        echo "[doc-format-guard] within_miss: schema ${aid} 的 within '${within}' 在文档中未定位，跳过该规则" >&2
-        continue
-      fi
-    fi
-    # 声明级缺失统计：一个锚点声明的必选 token 有任一缺失即记 1 条规则缺失（struct_score 精确语义）
-    miss_tokens=""
-    for tok in $tokens; do
-      if ! grep -qF "$tok" <<< "$scope"; then
-        miss_tokens="${miss_tokens}${tok} "
-      fi
-    done
-    # if 语句（非 && 链）：miss_tokens 为空时返回 0，避免 while 管道退出码非零触发 set -e
-    if [ -n "$miss_tokens" ]; then
-      echo "  缺锚点(${aid}): ${miss_tokens}"
-    fi
-  done >> "$TMPFILE"
-fi
-
-# SearchReplace 只传 patch → 跳过章节/子章节校验（无法从 patch 推断完整文档结构）
-if [ "$IS_SEARCH_REPLACE" != "true" ]; then
-  jq -r '.sections[] | select(.required == true) | select(.heading != null) | .heading' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r heading; do
-    if ! grep -qF "$heading" <<< "$CONTENT"; then
-      echo "  缺章节: $heading"
-    fi
-  done >> "$TMPFILE"
-
-  # 子章节
-  jq -r '.sections[].subsections[]? | select(.heading != null) | .heading' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r sub; do
-    if ! grep -qF "$sub" <<< "$CONTENT"; then
-      echo "  缺子章节: $sub"
-    fi
-  done >> "$TMPFILE"
-fi
-
-# ── 占位符校验 ──
-jq -r '.placeholders[]?' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r ph; do
-  if grep -qF "$ph" <<< "$CONTENT"; then
-    echo "  未替换占位符: $ph"
-  fi
-done >> "$TMPFILE"
-
-# ── 结构位禁词校验（仅标题行 + schema 声明的 groupColumn；正文叙述免疫；Task 1.2）──
-struct_text=$(grep -E '^#{2,}[[:space:]]' <<< "$CONTENT")
-col=$(jq -r '.groupColumn // empty' "$SCHEMA_FILE" 2>/dev/null)
-if [ -n "$col" ]; then
-  struct_text="${struct_text}
-$(awk -F'|' -v c="$col" 'NF>c {gsub(/^[[:space:]]+|[[:space:]]+$/, "", $(c+1)); print $(c+1)}' <<< "$CONTENT")"
-fi
-jq -r '.forbidden_terms[]?' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r term; do
-  # 结构位（标题行/分组列）是原子单元：定串匹配即可命中；正文不参与（豁免由提取范围保证）
-  if grep -qF "$term" <<< "$struct_text"; then
-    echo "  结构位禁词: $term"
-  fi
-done >> "$TMPFILE"
-
-ISSUES=$(cat "$TMPFILE" 2>/dev/null)
-
-# ── 判定回流 extra（Task 1.5 数据契约：anchor_hit/struct_score 精确语义；override 由上层 hook 在人类推翻时追加）──
-# struct_score = (适用规则数 - 缺失规则数) / 适用规则数 × 100，适用规则从 schema 实况计数
-anchor_total=$(jq -r '[.sections[] | select(.anchor != null)] | length' "$SCHEMA_FILE" 2>/dev/null || echo 0)
-heading_total=$(jq -r '[.sections[] | select(.required == true and .heading != null)] | length' "$SCHEMA_FILE" 2>/dev/null || echo 0)
-sub_total=$(jq -r '[.sections[].subsections[]? | select(.heading != null)] | length' "$SCHEMA_FILE" 2>/dev/null || echo 0)
-term_total=$(jq -r '.forbidden_terms | length' "$SCHEMA_FILE" 2>/dev/null || echo 0)
-if [ "$IS_SEARCH_REPLACE" = "true" ]; then
-  applied=$term_total  # patch 路径仅禁词规则适用
-else
-  applied=$(( anchor_total + heading_total + sub_total + term_total ))
-fi
-missed=$(wc -l < "$TMPFILE" 2>/dev/null | tr -d ' ')
-missed=${missed:-0}
-anchor_hit=true
-grep -q "缺锚点" "$TMPFILE" 2>/dev/null && anchor_hit=false
-struct_score=100
-if [ "$applied" -gt 0 ] 2>/dev/null && [ "$missed" -gt 0 ] 2>/dev/null; then
-  struct_score=$(( (applied - missed) * 100 / applied ))
-  [ "$struct_score" -lt 0 ] && struct_score=0
-fi
-BACKFLOW_EXTRA="\"anchor_hit\":${anchor_hit},\"struct_score\":${struct_score}"
-
-# ── 阻断或放行 ──
-if [ -n "$ISSUES" ]; then
-  echo "⛔ $TEMPLATE_NAME 校验不通过:
-$ISSUES" >&2
-  # 明细注入 stdout reason（去引号防 JSON 破坏，截断 180 字），让被拦方第一时间知道改什么
-  ISSUES_BRIEF=$(printf '%s' "$ISSUES" | tr '\n' ' ' | tr -d '"' | tr -s ' ' | cut -c1-180)
-  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"文档格式校验不通过: ${ISSUES_BRIEF}\"}}"
-  write_hook_event "doc-format-guard" "deny" "$file_path" "文档格式校验不通过" "$PLAN_KEYWORD" "$PLAN_STATUS" "$BACKFLOW_EXTRA" 2>/dev/null || true
-  exit 2
-fi
-
-# ── 自动更新 index.md ──
-if echo "$file_path" | grep -q "$MAGIC_DIR/plans/"; then
-  if [ -x "$PROJECT_DIR/scripts/gen-plan-index.sh" ]; then
-    "$PROJECT_DIR/scripts/gen-plan-index.sh" 2>/dev/null || true
-  fi
-fi
-
-# 放行回流（Task 1.5：anchor_hit/struct_score 正样本底座）
-write_hook_event "doc-format-guard" "allow" "$file_path" "校验通过" "$PLAN_KEYWORD" "$PLAN_STATUS" "$BACKFLOW_EXTRA" 2>/dev/null || true
-
-exit 0