add-coder 0.3.27 → 0.3.29

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

@@ -0,0 +1,88 @@
+// session-end.ts — SessionEnd 治理卡位（bash 版 session-end.sh 的 TS 同语义实现）
+// 路径: templates/core/hooks/lib/session-end.ts
+//
+// 治理职能（卡位 #2）:
+//   ① 清理 tpl-injected 标记文件
+//   ② 会话审计结算（汇总 tool 调用统计）
+//   ③ Stop 未触发兜底: 若 Stop 未执行验收检查，补执行 checklist 快照（best-effort）
+//
+// 设计范式: OOP 服务类（会话收尾三职责聚合）+ common.ts 纯函数复用（标记/状态/验收）。
+
+import { unlinkSync } from "node:fs"
+import {
+  checkAddCompleteness,
+  clearDevAction,
+  detectActiveAdd,
+  hasDevAction,
+  localIsoSeconds,
+  projectHash,
+} from "./common.js"
+
+/** 纯函数：解析 state 字段（对齐 bash awk -F'::' 切分） */
+function stateField(state: string, index: 0 | 1 | 2 | 3 | 4): string {
+  return state.split("::")[index] ?? ""
+}
+
+/**
+ * SessionEnd 治理服务:
+ *   - cleanupFlags: ① 清理标记（tpl-injected + dev action）
+ *   - settle: ② 审计结算（stderr 输出）
+ *   - stopFallback: ③ Stop 未触发兜底（best-effort，不阻断）
+ */
+export class SessionEndGuard {
+  private readonly projectDir: string
+  private readonly tplFlag: string
+
+  constructor(projectDir?: string) {
+    this.projectDir = projectDir ?? process.env.PROJECT_DIR ?? process.cwd()
+    // 标记路径唯一算法 = common.ts projectHash（对齐 bash echo 含换行 md5）
+    this.tplFlag = `/tmp/add_tpl_${projectHash()}`
+  }
+
+  /** ① 清理 tpl-injected 标记 + dev action 标记（对齐 cleanup_tpl_flag/cleanup_dev_flag） */
+  cleanupFlags(): void {
+    try {
+      unlinkSync(this.tplFlag)
+    } catch {
+      /* ignore（对齐 rm -f || true） */
+    }
+    clearDevAction()
+  }
+
+  /** ② 审计结算（core 默认: stderr 文本；qoder 子类 override: stdout JSON additionalContext） */
+  protected emitSettle(): void {
+    process.stderr.write(`[ADD SessionEnd] 会话结束 — ${localIsoSeconds()}\n`)
+  }
+
+  /** ② 审计结算（输出到 stderr 供日志记录，对齐 bash date -Iseconds） */
+  settle(): void {
+    this.emitSettle()
+  }
+
+  /** ③ Stop 未触发兜底（对齐 stop_fallback：dev action 标记还在 → 补 checklist 快照） */
+  stopFallback(): void {
+    if (!hasDevAction()) return
+    process.stderr.write("[ADD SessionEnd] ⚠️ 检测到 dev action 标记未清除——Stop 可能未触发验收检查\n")
+
+    const state = detectActiveAdd()
+    if (state === null) return
+
+    const handoff = stateField(state, 3)
+    const addRoute = stateField(state, 4)
+    if (handoff && handoff !== "none") {
+      process.stderr.write("[ADD SessionEnd] 补执行 checklist 快照（best-effort，不阻断）\n")
+      const issues = checkAddCompleteness(handoff, addRoute !== "none" ? addRoute : "")
+      for (const issue of issues) {
+        process.stderr.write(issue + "\n")
+      }
+    }
+  }
+
+  /** 主入口：①清理 → ②结算 → ③兜底（对齐 bash main） */
+  run(): number {
+    this.cleanupFlags()
+    this.settle()
+    this.stopFallback()
+    return 0
+  }
+}

package/templates/core/governance/session-start-guard.ts

@@ -0,0 +1,99 @@
+// lib/session-start-guard.ts — SessionStart 上下文恢复守卫（治理逻辑层，Task 2.1 类化收敛）
+// 治理卡位 #1: ADD状态恢复 + 模板索引注入
+//
+// 设计范式: OOP 守卫类（状态恢复/模板索引/代办/HITL 四职责聚合）。
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { detectActiveAdd, tryResolveMagicDir } from "./common.js"
+import { PreloadTemplates } from "./preload-templates.js"
+
+/**
+ * SessionStart 守卫（① 状态恢复 → ② 模板索引 → ③ 代办 → ④ HITL 待审批检测）:
+ *   缺陷修复（Plan §3.2）: PLANS_DIR 由 magicDir 推导（bash 版未绑定崩溃已修）
+ */
+export class SessionStartGuard {
+  protected readonly projectDir: string
+  protected readonly magicDir: string
+
+  constructor(projectDir: string) {
+    this.projectDir = projectDir
+    // MAGIC_DIR 解析（唯一链：注入优先 → 物理推导）
+    const inferred = tryResolveMagicDir()
+    if (inferred && !process.env.MAGIC_DIR) {
+      process.env.MAGIC_DIR = inferred
+    }
+    this.magicDir = process.env.MAGIC_DIR ?? ""
+  }
+
+  /** 主入口：返回 exit code（0） */
+  run(): number {
+    // ── ① ADD 状态恢复（扩展点: core 纯文本 / qoder JSON）──
+    const state = detectActiveAdd()
+    this.emitState(state)
+
+    // ── ② 模板索引注入（扩展点: core 纯文本 / qoder JSON lines 计数）──
+    this.emitIndex()
+
+    // ── ③ §代办刷新（扩展点: adapter 可 override 关闭）──
+    this.emitTodoReminder(state)
+
+    // ── ④ §HITL 待审批检测（扩展点: adapter 可 override 关闭）──
+    this.emitHitlPending()
+
+    return 0
+  }
+
+  // ─────────────────────────── 扩展点 ───────────────────────────
+
+  /** ① ADD 状态恢复输出（core: 纯文本块） */
+  protected emitState(state: string | null): void {
+    if (state === null) return
+    const [plan, step, rounds, handoff] = state.split("::")
+    process.stdout.write(`[ADD SessionStart] 检测到活跃 ADD Plan:
+  Plan: ${plan}
+  轮次: ${rounds}
+  当前 Step: ${step}
+  handoff: ${handoff}
+  恢复命令: query_audit_logs({ planKeyword: '${plan}' })
+`)
+  }
+
+  /** ② 模板索引输出（core: 纯文本 index） */
+  protected emitIndex(): void {
+    try {
+      process.stdout.write(new PreloadTemplates().index())
+    } catch {
+      /* 模板目录缺失等 fail-fast 场景：stderr 已在 validate 抛出，入口不阻断 */
+    }
+  }
+
+  /** ③ 代办刷新（core: 活跃 Plan 时输出提醒；claude: 无此段） */
+  protected emitTodoReminder(state: string | null): void {
+    if (state !== null) {
+      const plan = state.split("::")[0] ?? ""
+      process.stdout.write(`[代办] 检测到活跃 Plan: ${plan}。如有未加载的 IDE 代办清单，请从 tasks.md §IDE JSON 刷新 TodoWrite。
+`)
+    }
+  }
+
+  /** ④ HITL 待审批检测（core: 7 天内 .hitl.md 计数提示；claude: 无此段） */
+  protected emitHitlPending(): void {
+    const PLANS_DIR = this.magicDir ? join(this.projectDir, this.magicDir, "plans") : ""
+    if (PLANS_DIR && existsSync(PLANS_DIR)) {
+      const weekAgo = Date.now() - 7 * 86400000
+      const hitlCount = readdirSync(PLANS_DIR)
+        .filter((f) => f.endsWith(".hitl.md"))
+        .filter((f) => {
+          try {
+            return statSync(join(PLANS_DIR, f)).mtimeMs >= weekAgo
+          } catch {
+            return false
+          }
+        }).length
+      if (hitlCount > 0) {
+        process.stdout.write(`[HITL 待审批] 检测到 ${hitlCount} 个待审批 HITL 提案，请检查并处理\n`)
+      }
+    }
+  }
+}

package/templates/core/governance/state-detect.ts

@@ -0,0 +1,6 @@
+// state-detect.ts — 兼容入口（bash 版 state-detect.sh 的 TS 同语义实现）
+// 状态裁决统一委托 common.ts，禁止维护第二套 magicDir 探测。
+// 协议层契约（Review P1 #5）: 仅当前 magicDir scope；禁止跨端扫描与 .add fallback；
+// 禁止 adapter 名称默认值（入口注入 MAGIC_DIR 或物理位置推导）。
+
+export * from "./common.js"

package/templates/core/governance/stop-router.ts

@@ -0,0 +1,140 @@
+// stop-router.ts — Stop 四象限分流路由基类（治理逻辑层，Task 2.1/4.1 继承体系）
+// 治理卡位 #7: 验收检查 + devlog + 阻断
+// DB lifecycle 真相源（协议层）：DB 不可用时 fail-closed，禁止回退 Handoff/add-route 猜测
+//
+// 设计范式: 模板方法基类——Q0-Q4 分流流程固化，输出形态（JSON/纯文本）由 adapter 子类 override。
+
+import {
+  EXIT_BLOCK,
+  checkAddCompleteness,
+  clearDevAction,
+  detectActiveAdd,
+  hasDevAction,
+} from "./common.js"
+import { buildStopContext } from "./context-inject.js"
+
+/**
+ * Stop 四象限分流路由（Q0-Q4，与 bash stop-check.sh 同语义）:
+ *   Q0: DB 不可用 → fail closed（禁止当"无 Plan"）
+ *   Q1: 无 ADD + 无 dev → 正常停
+ *   Q2: 无 ADD + 有 dev → 严重违规，few-shot 注入 + 阻断
+ *   Q3: 有 ADD + 无 dev → 注入状态
+ *   Q4: 有 ADD + 有 dev → 验收检查
+ * 扩展点（protected，adapter 子类 override 输出形态）:
+ *   - emitQ0 / emitQ2 / emitQ3 / emitQ4Unclosed / emitQ4Pass（core: 纯文本；qoder: stdout JSON）
+ *   - unclosedInterpolate(): has_add_dev_unclosed 是否插值（core: true；qoder: false 缺陷照搬）
+ */
+export class StopRouter {
+  /** 主路由：返回 exit code（0 放行 / 2 阻断） */
+  run(): number {
+    const state = detectActiveAdd()
+    const hasDev = hasDevAction()
+
+    // ═══════════ Q0: DB 不可用 → fail closed ═══════════
+    if (state !== null && state.startsWith("__STATUS_UNAVAILABLE__")) {
+      const reason = state.split("::")[1] ?? ""
+      return this.emitQ0(reason)
+    }
+
+    // ═══════════ Q1: 无 ADD + 无 dev → 正常停 ═══════════
+    if (state === null && !hasDev) {
+      return 0
+    }
+
+    // ═══════════ Q2: 无 ADD + 有 dev → 严重违规 ═══════════
+    if (state === null && hasDev) {
+      return this.emitQ2()
+    }
+
+    const fields = (state as string).split("::")
+    const plan = fields[0] ?? ""
+    const step = fields[1] ?? ""
+    const rounds = fields[2] ?? ""
+    const handoff = fields[3] ?? ""
+    const addRoute = fields[4] ?? ""
+
+    // ═══════════ Q3: 有 ADD + 无 dev → 注入状态 ═══════════
+    if (!hasDev) {
+      return this.emitQ3(plan, rounds, step)
+    }
+
+    // ═══════════ Q4: 有 ADD + 有 dev → 验收检查（决策逻辑扩展点: core checklist / codex DB 进度）═══
+    return this.q4Check(plan, rounds, step, handoff, addRoute)
+  }
+
+  // ─────────────────────────── 扩展点 ───────────────────────────
+
+  /**
+   * Q4 验收决策（双维度组合——2026-08-14 Task 9.4.4④ 上提，回流: I2）:
+   *   维度 1（前置）: DB 任务进度（step = done/total，数值且 done<total → 未完成阻断提示）
+   *   维度 2: checklist 质量（checkAddCompleteness 未闭环 → 阻断）
+   *   互补非替代——codex 原 DB 进度分流语义上提 core，core checklist 质量语义保留。
+   */
+  protected q4Check(plan: string, rounds: string, step: string, handoff: string, addRoute: string): number {
+    void plan
+    void rounds
+    // 维度 1: DB 任务进度（step 格式 done/total，如 11/64）
+    const [donePart, totalPart] = step.split("/")
+    if (
+      /^\d+$/.test(donePart) &&
+      /^\d+$/.test(totalPart) &&
+      Number(donePart) < Number(totalPart)
+    ) {
+      return this.emitQ4Unclosed(
+        `DB Plan 任务进度 ${donePart}/${totalPart}，尚有未完成 Task。请继续执行当前 Plan 的未完成 Task，并为本轮改动补齐 record_dev_operation 审计。`
+      )
+    }
+    // 维度 2: checklist 质量
+    const issues = checkAddCompleteness(
+      handoff && handoff !== "none" ? handoff : "",
+      addRoute && addRoute !== "none" ? addRoute : ""
+    )
+    if (issues.length > 0) {
+      return this.emitQ4Unclosed(issues.join("\n"))
+    }
+
+    clearDevAction()
+    return this.emitQ4Pass()
+  }
+
+  /** Q0: DB 不可用（core: stderr + 2） */
+  protected emitQ0(reason: string): number {
+    process.stderr.write(
+      `[ADD Stop] ⛔ Plan status 暂不可用（${reason}）。未回退 Handoff/add-route 猜测，请恢复数据库或 MCP resolver 后重试。\n`
+    )
+    return EXIT_BLOCK
+  }
+
+  /** Q2: 无 ADD + 有 dev（core: stderr few-shot + 2） */
+  protected emitQ2(): number {
+    process.stderr.write(buildStopContext("no_add_has_dev", "") + "\n")
+    return EXIT_BLOCK
+  }
+
+  /** Q3: 有 ADD + 无 dev（core: 纯文本状态注入 + 0） */
+  protected emitQ3(plan: string, rounds: string, step: string): number {
+    process.stdout.write(`[ADD Stop] Plan: ${plan}, 轮次: ${rounds}, Step: ${step}\n`)
+    process.stdout.write("本次无代码改动。下次继续时执行 session-init 恢复上下文。\n")
+    return 0
+  }
+
+  /** Q4 验收未闭环（core: stderr + 2；unclosedInterpolate=true 插值） */
+  protected emitQ4Unclosed(info: string): number {
+    const text = this.unclosedInterpolate()
+      ? buildStopContext("has_add_dev_unclosed", info)
+      : buildStopContext("has_add_dev_unclosed", "")
+    process.stderr.write(text + "\n")
+    return EXIT_BLOCK
+  }
+
+  /** Q4 验收通过（core: 纯文本 + 0） */
+  protected emitQ4Pass(): number {
+    process.stdout.write("[ADD Stop] ✅ 验收通过——checklist 全部勾选，devlog 已记录。\n")
+    return 0
+  }
+
+  /** has_add_dev_unclosed 是否插值（core: true；qoder: false 缺陷照搬） */
+  protected unclosedInterpolate(): boolean {
+    return true
+  }
+}

package/templates/core/governance/subagent-guard-router.ts

@@ -0,0 +1,35 @@
+// subagent-guard-router.ts — SubagentStart 上下文注入路由（治理逻辑层，Task 3.1 能力对齐）
+// 治理卡位 #10: ADD上下文注入子agent + 审计初始化
+//
+// 能力对齐（2026-08-14 六端实态核验）:
+//   强版（状态注入）: claude/vscode/qoder——detect_active_add → 注入 Plan/Step/轮次/handoff
+//   弱版（事件提示）: core/trae/codex——仅"子代理启动请确认遵循 ADD 规范"空话
+//   → 本基类统一为状态注入语义（core 对齐强版）；输出形态（JSON/纯文本）为协议差异由子类 override。
+//
+// 设计范式: 模板方法基类——状态获取流程固化，emit() 输出形态由子类 override。
+
+import { detectActiveAdd } from "./common.js"
+
+/**
+ * SubagentStart 上下文注入路由（模板方法）:
+ *   流程固化（不可 override）: run() = detectActiveAdd → emit(state)
+ *   扩展点（protected）: emit()——core/qoder: hookSpecificOutput JSON；claude/vscode/trae/codex: 纯文本块
+ */
+export class SubagentGuardRouter {
+  /** 主路由：返回 exit code（0） */
+  run(): number {
+    const state = detectActiveAdd()
+    if (state === null) return 0
+    this.emit(state)
+    return 0
+  }
+
+  /** 上下文注入输出（core 协议: hookSpecificOutput JSON，qoder 同构） */
+  protected emit(state: string): void {
+    const [plan, step, rounds, handoff] = state.split("::")
+    const ctx = `[ADD SubagentStart] Plan: ${plan}, Step: ${step}, Round: ${rounds}, handoff: ${handoff}。遵循 ADD 规范，完成后检查 checklist。`
+    process.stdout.write(
+      JSON.stringify({ hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext: ctx } }) + "\n"
+    )
+  }
+}

package/templates/core/governance/subagent-stop-router.ts

@@ -0,0 +1,93 @@
+// lib/subagent-stop-router.ts — SubagentStop 入口路由（core 通用协议参考实现，Task 2.2 薄壳化）
+// 治理卡位 #11: 子agent边界校验 + 审计聚合 + 阻断
+// 与 SubagentStopGuard（能力对齐版）的关系: 本类是 core 入口版语义（bash 逐字），
+//   SubagentStopGuard 供 claude/vscode 薄壳消费（additionalContext 文本差异）。
+//   ——两者文本契约不同（IDE 协议差异），行为等价基线各自由 golden 固化。
+//
+// 设计范式: OOP 路由类（边界校验 + 审计聚合单一职责）。
+
+import { existsSync, readFileSync } from "node:fs"
+import { detectActiveAdd, EXIT_BLOCK, localIsoSeconds } from "./common.js"
+
+/**
+ * SubagentStop 入口路由（core 入口版，bash subagent-stop.sh 逐字语义）:
+ *   ① 边界校验: 检查交付物是否超出 spec 边界（无活跃 Plan → 无法校验告警）
+ *   ② 审计聚合: stderr 审计输出（对齐 bash date -Iseconds）
+ */
+export class SubagentStopRouter {
+  /** 对齐 bash jq -r '.agent_type // .subagent_name // "unknown"'：
+   * 空输入/非法 JSON → jq 无输出 → 空串（不是 "unknown"）；字段缺失才回退 "unknown" */
+  private agentNameFrom(input: string): string {
+    if (input.trim() === "") return ""
+    try {
+      const parsed = JSON.parse(input) as { agent_type?: unknown; subagent_name?: unknown }
+      const v = parsed.agent_type ?? parsed.subagent_name
+      return typeof v === "string" && v !== "" ? v : "unknown"
+    } catch {
+      return ""
+    }
+  }
+
+  // ─────────────────────────── 扩展点 ───────────────────────────
+
+  /** ① 无活跃 Plan 告警（core: stderr；qoder 子类 override: stdout JSON） */
+  protected emitNoPlanWarn(agentName: string): void {
+    process.stderr.write(`[ADD SubagentStop] ⚠️ ${agentName} 已完成，但无活跃 ADD Plan 无法校验边界\n`)
+  }
+
+  /** ② 边界通过审计（core: stderr；qoder 子类 override: stdout JSON） */
+  protected emitBoundaryPass(agentName: string, planKw: string, _handoff: string): void {
+    process.stderr.write(`[ADD SubagentStop] ${agentName} 已完成 — 关联 Plan: ${planKw}\n`)
+    process.stderr.write(`[ADD SubagentStop] ${agentName} 边界校验通过 — ${localIsoSeconds()}\n`)
+  }
+
+  /** 交付物越界检查开关（core: true；qoder: false——qoder 轻量提示无阻断） */
+  protected checkDeliverables(): boolean {
+    return true
+  }
+
+  /** 主路由：返回 exit code（0 放行 / 2 阻断） */
+  run(input: string): number {
+    const agentName = this.agentNameFrom(input)
+
+    // ── ① 边界校验：检查子 agent 交付物是否超出 spec 范围 ──
+    const state = detectActiveAdd()
+    if (state === null) {
+      this.emitNoPlanWarn(agentName)
+      return 0
+    }
+
+    const planKw = state.split("::")[0] ?? ""
+    const handoff = state.split("::")[3] ?? ""
+
+    // 如果 handoff 中存在允许的文件清单，检查交付物是否越界（扩展点: qoder 关闭）
+    if (this.checkDeliverables() && handoff && handoff !== "none" && existsSync(handoff)) {
+      /** 对齐 bash jq -r '.deliverables // ""' */
+      const deliverablesRaw = (() => {
+        try {
+          const parsed = JSON.parse(input) as { deliverables?: unknown }
+          return typeof parsed.deliverables === "string" ? parsed.deliverables : ""
+        } catch {
+          return ""
+        }
+      })()
+      if (deliverablesRaw !== "") {
+        const handoffContent = readFileSync(handoff, "utf-8")
+        const violations: string[] = []
+        for (const f of deliverablesRaw.split(/\s+/)) {
+          if (f === "") continue
+          if (!handoffContent.includes(f)) violations.push(f)
+        }
+        if (violations.length > 0) {
+          process.stderr.write(`[ADD SubagentStop] ❌ ${agentName} 交付物超出 spec 边界: ${violations.join(" ")}\n`)
+          process.stderr.write("[ADD SubagentStop] 要求重做——请检查这些文件是否属于本轮 spec 范围\n")
+          return EXIT_BLOCK
+        }
+      }
+    }
+
+    // ── ② 审计聚合（扩展点: core stderr / qoder stdout JSON）──
+    this.emitBoundaryPass(agentName, planKw, handoff)
+    return 0
+  }
+}

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

@@ -0,0 +1,75 @@
+// subagent-stop.ts — SubagentStop 治理卡位（bash 版 subagent-stop.sh 的 TS 同语义实现）
+// 路径: templates/core/hooks/lib/subagent-stop.ts
+//
+// 治理职能（卡位 #11）:
+//   ① 子 agent 结果边界校验: 检查交付物是否在 spec 边界内（不越界、不遗漏）
+//   ② 审计聚合: 将子 agent 的 sub-traceId 审计记录合并回主 traceId
+//   ③ 阻断能力: 子 agent 结果不符合 spec → exit 2 要求重做
+//
+// 设计范式: OOP 服务类（边界校验单一职责聚合）+ 纯函数解析（state 字段切分）。
+
+import { existsSync, readFileSync } from "node:fs"
+import { detectActiveAdd, EXIT_BLOCK, jsonGet, localIsoSeconds, readHookInput } from "./common.js"
+
+/** 纯函数：解析 state 字段（对齐 bash awk -F'::' 切分） */
+function stateField(state: string, index: 0 | 1 | 2 | 3 | 4): string {
+  return state.split("::")[index] ?? ""
+}
+
+/**
+ * SubagentStop 治理服务:
+ *   - checkBoundary: 交付物边界校验（无活跃 Plan → 仅告警不阻断）
+ *   - main: stdin 解析 → agent_type 提取 → 边界校验 → 审计聚合
+ */
+export class SubagentStopGuard {
+  /**
+   * 边界校验: 检查子 agent 交付物是否超出 spec 定义的文件范围。
+   * 返回 0=通过，1=越界（要求重做）。
+   */
+  checkBoundary(subagentName: string, deliverables: readonly string[]): number {
+    const state = detectActiveAdd()
+
+    if (state === null) {
+      // 无活跃 Plan —— 无 spec 可参考，仅告警不阻断
+      process.stderr.write(`[ADD SubagentStop] ⚠️ 无活跃 ADD Plan，无法校验 ${subagentName} 的交付物边界\n`)
+      return 0
+    }
+
+    const planKw = stateField(state, 0)
+    const handoff = stateField(state, 3)
+
+    process.stderr.write(`[ADD SubagentStop] ${subagentName} 已完成，交付物: ${deliverables.join(" ")}\n`)
+    process.stderr.write(`[ADD SubagentStop] 关联 Plan: ${planKw} | handoff: ${handoff}\n`)
+
+    // best-effort: 如果 handoff 中列出了允许的文件范围，检查交付物是否在其中
+    if (handoff && existsSync(handoff) && deliverables.length > 0) {
+      const handoffContent = readFileSync(handoff, "utf-8")
+      const violations = deliverables.filter((f) => !handoffContent.includes(f))
+      if (violations.length > 0) {
+        process.stderr.write(`[ADD SubagentStop] ❌ ${subagentName} 交付物超出 spec 边界: ${violations.join(" ")}\n`)
+        process.stderr.write("[ADD SubagentStop] 请检查这些文件是否属于本轮 spec 范围，或更新 handoff 文件清单\n")
+        return 1
+      }
+    }
+    return 0
+  }
+
+  /** 主入口（对齐 bash main） */
+  run(subagentName: string, stdin: string): number {
+    // 尝试从 stdin JSON 提取交付物信息（对齐 bash grep/sed 提取 agent_type）
+    const agentType = jsonGet(stdin, "agent_type")
+    const effectiveName = agentType ? `${subagentName}(${agentType})` : subagentName
+    const deliverables: string[] = []
+
+    // ① 边界校验
+    if (this.checkBoundary(effectiveName, deliverables) !== 0) {
+      process.stderr.write("[ADD SubagentStop] 要求重做——交付物超出 spec 边界\n")
+      return EXIT_BLOCK
+    }
+
+    // ② 审计聚合（输出到 stderr 供日志记录，对齐 bash date -Iseconds）
+    process.stderr.write(`[ADD SubagentStop] ${effectiveName} 边界校验通过 — ${localIsoSeconds()}\n`)
+
+    return 0
+  }
+}

package/templates/core/governance/vocabulary.ts

@@ -0,0 +1,109 @@
+// vocabulary.ts — 从 vocabulary markdown 表格加载触发词（bash 版 vocabulary.sh 的 TS 同语义实现）
+// 单一数据源: {MAGIC_DIR}/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
+// 协议层契约（Review P1 #5）: 仅当前 magicDir scope；magicDir 解析统一委托 common.ts
+// （tryResolveMagicDir——唯一解析链的柔和变体，禁止第二套探测，禁止跨端扫描与 .add fallback）
+//
+// 设计范式: 函数式——纯函数流式变换（read → inRange 过滤 → 表格解析 → 结构化条目），
+// 内部结构化类型 TriggerEntry（泛型 parse 收敛字段切分），外部序列化对齐 bash "prio::regex::action" 契约。
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { tryResolveMagicDir } from "./common.js"
+
+/** 结构化触发词条目（内部类型；输出契约由 serializeTrigger 序列化） */
+export interface TriggerEntry {
+  /** P0/P1/P2 优先级 */
+  readonly priority: string
+  /** 触发词正则（已去反引号、' / ' → '|'、trim） */
+  readonly regex: string
+  /** 响应文本（trim） */
+  readonly action: string
+}
+
+/** 输出契约序列化: 优先级::触发词正则::响应文本（:: 避免与触发词内的 | 冲突） */
+export function serializeTrigger(e: TriggerEntry): string {
+  return `${e.priority}::${e.regex}::${e.action}`
+}
+
+/** 纯函数：vocabulary 文件路径（magicDir 未注入且无法推导 → ""，调用方静默返回空） */
+function vocabularyFile(): string {
+  const magicDir = tryResolveMagicDir()
+  if (!magicDir) return ""
+  return join(
+    process.env.PROJECT_DIR || process.cwd(),
+    magicDir,
+    "vocabulary",
+    "add-governance-vocabulary.md"
+  )
+}
+
+/**
+ * 泛型表格行解析器：把 IFS='|' 切分的行映射为结构化结果。
+ * 字段语义（对齐 bash while IFS='|' read -r _ prio raw_trigger action）:
+ *   cells[1]=prio、cells[2]=raw_trigger、cells[3]=action（xargs 等价 trim）
+ */
+function mapTableRow<T>(line: string, map: (prio: string, rawTrigger: string, action: string) => T | null): T | null {
+  const cells = line.split("|")
+  const prio = cells[1]?.trim() ?? ""
+  const rawTrigger = cells[2] ?? ""
+  const action = cells[3]?.trim() ?? ""
+  // trigger 归一化: 去反引号、' * / *' → '|'、trim（对齐 bash sed 链）
+  const trigger = rawTrigger.replace(/`/g, "").replace(/ *\/ */g, "|").trim()
+  if (!trigger) return null
+  return map(prio, trigger, action)
+}
+
+/**
+ * 加载触发词（对齐 bash load_triggers 的 sed 范围/grep 行过滤/while 解析）:
+ *   - 范围: ^## 类别 A: 文档类型 至 ^## 类别 [G-Z]
+ *   - 行过滤: ^| (P0|P1|P2) 
+ * 文件缺失/路径不可判定 → 空数组（与 bash return 1 等价，静默不阻断）
+ */
+export function loadTriggers(): TriggerEntry[] {
+  const file = vocabularyFile()
+  if (!file || !existsSync(file)) return []
+  const lines = readFileSync(file, "utf-8").split("\n")
+  const out: TriggerEntry[] = []
+  let inRange = false
+  for (const line of lines) {
+    if (/^## 类别 A: 文档类型/.test(line)) inRange = true
+    if (/^## 类别 [G-Z]/.test(line)) inRange = false
+    if (!inRange) continue
+    if (!/^\| (P0|P1|P2) /.test(line)) continue
+    const entry = mapTableRow(line, (priority, regex, action) => ({ priority, regex, action }))
+    if (entry) out.push(entry)
+  }
+  return out
+}
+
+/** 开发关键词检测行判定（Layer 2/3 分流特征：超长 regex 含 修.?bug|fix.?bug） */
+function isDevKeywordLine(regex: string): boolean {
+  return /修\.?bug|fix\.?bug/i.test(regex)
+}
+
+/**
+ * 匹配触发词（对齐 bash match_trigger）:
+ *   - 跳过开发关键词检测行
+ *   - 不区分大小写正则匹配 prompt → "[ADD 触发] ${regex} → ${action}"
+ *   - 非法正则静默跳过（与 bash grep -E 行为对齐）
+ */
+export function matchTrigger(prompt: string): string[] {
+  return loadTriggers().flatMap(({ regex, action }) => {
+    if (isDevKeywordLine(regex)) return []
+    try {
+      return new RegExp(regex, "i").test(prompt) ? [`[ADD 触发] ${regex} → ${action}`] : []
+    } catch {
+      return []
+    }
+  })
+}
+
+/**
+ * 加载开发关键词（对齐 bash load_dev_keywords）:
+ *   只取包含"开发|改功能"的开发关键词检测行，输出其 regex
+ */
+export function loadDevKeywords(): string[] {
+  return loadTriggers()
+    .filter((e) => serializeTrigger(e).includes("开发|改功能"))
+    .map((e) => e.regex)
+}

package/templates/core/hooks/doc-format-guard.ts

@@ -0,0 +1,21 @@
+// doc-format-guard.ts — doc-format-guard 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/doc-format-guard.ts（DocFormatGuard 服务类，规则消费 hook-doc-format-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readFileSync } from "node:fs"
+import { DocFormatGuard } from "../governance/doc-format-guard.js"
+
+// ── 主入口（仅产物被 node 直调时执行；被 import 时保持纯库） ──
+if (import.meta.url === new URL(`file://${process.argv[1] ?? ""}`).href) {
+  const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+  const MAGIC_DIR = process.env.MAGIC_DIR || ".qoder"
+
+  const guard = new DocFormatGuard(PROJECT_DIR, MAGIC_DIR)
+  let raw = ""
+  try {
+    raw = readFileSync(0, "utf-8")
+  } catch {
+    raw = ""
+  }
+  process.exitCode = guard.run(raw)
+}