add-coder 0.3.27 → 0.3.29

package/templates/core/docs/ADD-governance-vscode-copilot.md

@@ -19,9 +19,9 @@ VS Code Copilot 支持 10 种 Agent Hook 事件（官方 8 + Cloud Agent 2）：
 | 子 agent | **SubagentStart**、**SubagentStop** |
 | 其他 | **PreCompact**、errorOccurred（Cloud Agent 专属） |
 
-配置位置：`.github/hooks/*.json`（JSON 格式，`command` 字段指向 shell 脚本）
+配置位置：`.vscode/hooks/*.mjs`（TS 源码 esbuild 烘焙零依赖产物，node 直调——2026-08-14 node 化实态，bash 待退役）
 
-**关键差异 vs Claude Code**：不支持 PostToolUseFailure / StopFailure / Notification / PermissionRequest。但 **VS Code 1.129+ Agent Host 同时读取 `.claude/settings.json`**，`npx add-coder init --adapter=vscode` 会同步产出 `.claude/` 目录，`.github/hooks/*.json` 的 `command` 统一指向 `.claude/hooks/xxx.sh`——双通道共享同一套完整脚本。
+**关键差异 vs Claude Code**：不支持 PostToolUseFailure / StopFailure / Notification / PermissionRequest。但 **VS Code 1.129+ Agent Host 同时读取 `.claude/settings.json`**，`npx add-coder init --adapter=vscode` 会同步产出 `.claude/` 目录，双通道共享同一套 `.mjs` 产物（node 直调）。
 
 ---
 
@@ -48,36 +48,35 @@ errorOccurred ────────────────→ ⑮ 错误分
 
 ## 注入通道
 
-VS Code Copilot 的注入通道为 **`.github/hooks/*.json` 的 `command` stdout**。
+VS Code Copilot 的注入通道为 **hook 配置的 `command` stdout**（node 直调 `.mjs` 产物）。
 
 VS Code 1.129+ 的 Agent Host 架构让同一项目支持多 Agent 并行运行——Copilot、Claude Code 各走各的通道：
 
-| 通道 | 配置位置 | 脚本路径 | 说明 |
+| 通道 | 配置位置 | 产物路径 | 说明 |
 |---|---|---|---|
-| **VS Code 原生** | `.github/hooks/*.json` | `.claude/hooks/xxx.sh` | 10 个 JSON 文件，command 指向完整 Claude 脚本 |
-| **Agent Host (Claude)** | `.claude/settings.json` | `.claude/hooks/xxx.sh` | 同一套脚本，Claude Code agent 直接读取 |
+| **VS Code 原生** | `.vscode/hooks/` | `.vscode/hooks/*.mjs` | 14 入口 node 产物，command 直调 |
+| **Agent Host (Claude)** | `.claude/settings.json` | `.claude/hooks/*.mjs` | 同一套产物，Claude Code agent 直接读取 |
 
 ```
 npx add-coder init --adapter=vscode
         │
-        ├──→ .github/hooks/*.json （10 个，→ .claude/hooks/xxx.sh）
+        ├──→ .vscode/hooks/*.mjs （14 入口，node 直调）
         ├──→ .vscode/settings.json （MCP 配置）
-        ├──→ .vscode/hooks/lib/ （共享库）
         └──→ .claude/ ★ （Agent Host 双通道，含完整 hooks + settings.json + mcp.json）
 ```
 
 | 注入场景 | 触发事件 | 注入内容 | 配置 |
 |---|---|---|---|
-| 会话启动 | SessionStart | 模板索引 | `session-start.json` → `.claude/hooks/lib/preload-templates.sh --index` |
-| 开发触发 | UserPromptSubmit | 13 个模板全文 | `user-prompt-submit.json` → `.claude/hooks/lib/preload-templates.sh --full --top 5 --mark` |
+| 会话启动 | SessionStart | 模板索引 | `.vscode/hooks/session-start.mjs --index` |
+| 开发触发 | UserPromptSubmit | 13 个模板全文 | `.vscode/hooks/preload-templates.mjs --full --top 5 --mark` |
 
 ---
 
 ## 路径约定
 
-VS Code Copilot hooks 必须位于 **项目根目录** 的 `.github/hooks/` 下。`npx add-coder init --adapter vscode` 会将 JSON 文件分发到此路径，而非 `.vscode/` 子目录。
+VS Code Copilot hooks 产物位于 **项目根目录** 的 `.vscode/hooks/`（14 入口 node 产物）。`npx add-coder init --adapter vscode` 会将 TS 源码烘焙分发到此路径；Agent Host（1.129+）同时读取 `.claude/` 双通道。
 
-**Issue #6 背景**：本端的 429 并发问题是最初触发源。轮次 1 优先交付 `session-start.json` + `user-prompt-submit.json` 两个文件，仅这两个 JSON 即可消灭模板读取风暴（429 不再触发）。
+**Issue #6 背景**：本端的 429 并发问题是最初触发源。轮次 1 优先交付 `session-start` + `user-prompt-submit` 两个入口，仅这两个即可消灭模板读取风暴（429 不再触发）。
 
 ---
 
@@ -85,9 +84,9 @@ VS Code Copilot hooks 必须位于 **项目根目录** 的 `.github/hooks/` 下
 
 | 维度 | VS Code Copilot | Claude Code |
 |---|---|---|
-| 配置格式 | `.github/hooks/*.json` | `.claude/settings.json` |
-| 注入通道 | JSON command stdout | stdout → additionalContext |
-| 脚本路径 | `.claude/hooks/xxx.sh`（与 Claude 共享） | `.claude/hooks/xxx.sh` |
+| 配置格式 | `.vscode/hooks/*.mjs`（command 直调） | `.claude/settings.json` |
+| 注入通道 | command stdout | stdout → additionalContext |
+| 产物路径 | `.vscode/hooks/*.mjs`（与 Claude 共享治理层） | `.claude/hooks/*.mjs` |
 | 独有事件 | errorOccurred | PermissionRequest/Denied / StopFailure / Notification / PostToolUseFailure |
 | 子 agent 启动 | ✅ SubagentStart | ✅ SubagentStart |
 | Agent Host 双通道 | ✅ `.claude/` 同步产出 | — |
@@ -96,7 +95,7 @@ VS Code Copilot hooks 必须位于 **项目根目录** 的 `.github/hooks/` 下
 
 ## 自定义 Hook 源切换
 
-VS Code Copilot 的 `.github/hooks/*.json` 默认指向 `.vscode/hooks/xxx.sh`（VS Code 原生完整脚本）。项目同时产出 `.claude/` 目录（含 Claude Code 完整 hook 体系 + settings.json），两套体系可切换。
+VS Code Copilot 的 `.vscode/hooks/*.mjs` 为 VS Code 原生 node 产物（14 入口）。项目同时产出 `.claude/` 目录（含 Claude Code 完整 hook 体系 + settings.json），两套体系可切换。
 
 ### 两套体系对比
 
@@ -107,21 +106,21 @@ VS Code Copilot 的 `.github/hooks/*.json` 默认指向 `.vscode/hooks/xxx.sh`
 | 环境变量 | `$PWD`（VS Code cwd=项目根） | `$CLAUDE_PROJECT_DIR` |
 | 退出码阻断 | ✅ exit 2（与 Claude 相同） | ✅ exit 2 |
 | 上下文注入 | stdout 纯文本（VS Code 格式） | stdout → additionalContext（Claude 格式） |
-| 共享 lib | ✅ `hooks/lib/common.sh` | ✅ `hooks/lib/common.sh` |
+| 共享治理层 | ✅ core governance 内联（0 复制） | ✅ core governance 内联（0 复制） |
 | 治理能力 | 完整四路守卫 + 验收阻断 + 审计 | 完整四路守卫 + 验收阻断 + 审计（与 VS Code 版同等） |
 
-> **两套实现代码质量同等，能力完整，差异仅在于环境变量和输出格式。**
+> **两套实现质量同等，能力完整，差异仅在于环境变量和输出格式。**
 
 ### 切换方式
 
-编辑 `.github/hooks/` 下的任意 JSON 文件，将 `bash` 字段中的路径从 `.vscode/hooks/` 改为 `.claude/hooks/` 即可：
+编辑 hook 配置（settings.json / Agent Host 通道），将 `command` 中的路径从 `.vscode/hooks/` 改为 `.claude/hooks/` 即可：
 
 ```json
 // 默认（VS Code 原生，推荐）
-"bash": "bash .vscode/hooks/pre-tool-use.sh"
+"command": "node .vscode/hooks/pre-tool-use.mjs"
 
-// 切换为 Claude Code 体系（如果同时使用 Claude Code 并希望统一脚本）
-"bash": "bash .claude/hooks/pre-tool-use.sh"
+// 切换为 Claude Code 体系（如果同时使用 Claude Code 并希望统一产物）
+"command": "node .claude/hooks/pre-tool-use.mjs"
 ```
 
 **切换场景建议**：

package/templates/core/governance/audit-bridge.ts

@@ -0,0 +1,47 @@
+// audit-bridge.ts — AuditBridge（审计桥接，Task 8.1 事件面扩展，ADD-7 自动化）
+// 设计（Spec §4 嵌入式三层，回流 R1）:
+//   ① 主路径（现状不动）: 拦截事件 writeHookEvent(jsonl) → MCP 常驻 fs.watch 消费 → devOperation 落库
+//   ② 事件面扩展（本类）: post-tool-use 文件写入 → 写 hook 事件（decision="write"）→ 同一 jsonl 主路径
+//      → MCP 常驻侧自动消费落库（幂等 dedupKey: hook::ts::planKeyword + decision + cmd）
+//   ③ 自然演化: Claude mcp_tool 直调 record_dev_operation 由 handlerTypes 维度声明驱动（TOML 一行切换）
+//
+// 与 writeHookEvent 的关系: 复用其 jsonl 写入 + 轮转逻辑（event.file 真源），
+// 但路径必须用本类 magicDir 构造参数（writeHookEvent 默认 env.MAGIC_DIR || ".qoder"
+// 兜底——core/adapter 入口多数未回写 env.MAGIC_DIR，依赖 env 会错写 .qoder/reports）。
+
+import { writeHookEvent } from "./notify.js"
+
+/**
+ * 审计桥接：post-tool-use 文件写入事件面扩展。
+ * emit() 幂等——同文件同秒重复写入由 MCP 消费端 dedupKey 去重，落库唯一。
+ */
+export class AuditBridge {
+  private readonly projectDir: string
+  private readonly magicDir: string
+
+  constructor(projectDir: string, magicDir: string) {
+    this.projectDir = projectDir
+    this.magicDir = magicDir
+  }
+
+  /**
+   * 文件写入审计事件（decision="write"）。
+   * @param filePath 被写入文件路径（绝对/相对均可，MCP 消费端以 cmd 为 targetId）
+   */
+  emit(filePath: string): void {
+    if (!filePath || filePath === "") return
+    const planKeyword = this.extractPlanKeyword(filePath)
+    writeHookEvent("post-tool-use", "write", filePath, "文件写入审计（ADD-7 自动化）", planKeyword, "none", "", this.magicDir)
+  }
+
+  /**
+   * 从写入路径提取 planKeyword（plans/specs/reviews 目录下命名规范文件）:
+   *   xxx-plan-v1.md / xxx-add-route-v1.md / xxx-review-v1.md → xxx-{suffix}-vN
+   * 其余路径 → "unknown"（与拦截事件缺省语义一致）。
+   */
+  private extractPlanKeyword(filePath: string): string {
+    void this.projectDir
+    const m = filePath.match(/([^/]+-(?:plan|add-route|review)-v\d+)\.md$/)
+    return m ? m[1] : "unknown"
+  }
+}

package/templates/core/governance/common.ts

@@ -0,0 +1,299 @@
+// lib/common.ts — ADD Hook 协议壳（轮次 1 / Task 1.3）
+// 与 bash 版 lib/common.sh 行为逐字对齐:
+//   stdin 解析 / stdout JSON / stderr 文本 / 退出码 0·2 / failClosed
+// 契约红线（Plan §1.2）: stdout 仅 JSON、stderr 仅人类可读文本、exit 0/2
+// 烘焙: scripts/hook-bake.ts bundle 为各 magicDir hooks/lib/common.mjs
+// 本文件被各入口 .ts 与 adapter 私有协议层 import（bundle 时内联，产物自包含）
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { protocol } from "./rules.js"
+import { findUpSync } from "find-up"
+
+/** 退出码常量（真源: hook-protocol-rules.toml [protocol.exit_codes]） */
+export const EXIT_PASS = protocol.exit_codes.pass as number
+export const EXIT_BLOCK = protocol.exit_codes.block as number
+
+/** state 字段分隔符（真源: hook-protocol-rules.toml [protocol.output.field_separator]） */
+export const STATE_SEP = protocol.output.field_separator as string
+
+/** 从 stdin 读取完整 JSON（IDE hook 事件 payload）；TTY 时返回 "{}"（对齐 bash parse_input） */
+export function readHookInput(): string {
+  if (process.stdin.isTTY) return "{}"
+  return readFileSync(0, "utf-8")
+}
+
+/** 从 JSON 提取首个字符串字段值（对齐 bash json_get 的 grep/sed 语义） */
+export function jsonGet(json: string, field: string): string {
+  const re = new RegExp(`"${field}"\\s*:\\s*"([^"]*)"`)
+  const m = re.exec(json)
+  return m?.[1] ?? ""
+}
+
+/** stdout 输出 JSON（机器契约一字不变: additionalContext / hookSpecificOutput / decision） */
+export function emitJson(payload: Record<string, unknown> | string): void {
+  process.stdout.write(
+    (typeof payload === "string" ? payload : JSON.stringify(payload)) + "\n"
+  )
+}
+
+/** stderr 输出文本（Qoder 规范: stderr=人类可读，stdout=机器 JSON） */
+export function emitText(text: string): void {
+  process.stderr.write(text + "\n")
+}
+
+/** 放行（退出码 0） */
+export function exitOk(): never {
+  process.exit(EXIT_PASS)
+}
+
+/** 阻断（退出码 2） */
+export function exitBlock(): never {
+  process.exit(EXIT_BLOCK)
+}
+
+/**
+ * STATUS_UNAVAILABLE 语义: 非零退出 + stderr 说明，禁止静默吞掉。
+ * 默认阻断码 2（hook 冒烟契约 ∈ {0,2}）；bridge 场景可传 3（对齐 bash return 3）。
+ */
+export function failClosed(msg: string, code: number = EXIT_BLOCK): never {
+  process.stderr.write(msg + "\n")
+  process.exit(code)
+}
+
+/**
+ * magicDir 统一解析（Plan §3.2 缺陷修复要求 TS 版唯一解析链）:
+ *   ① 入口注入 MAGIC_DIR 优先（sync 烘焙时 bakeMagicRefs 已硬编码）
+ *   ② 物理位置推导: <projectDir>/<magicDir>/hooks/... 向上找以 . 开头的目录名
+ *   ③ 推导失败 → failClosed（禁止猜测 adapter 名 / 禁止孤儿变量）
+ */
+export function resolveMagicDir(): string {
+  const hit = tryResolveMagicDir()
+  if (hit) return hit
+  return failClosed(
+    `magicDir 未注入且无法从物理位置推导: ${fileURLToPath(import.meta.url)}`
+  )
+}
+
+/**
+ * 非阻断版 magicDir 解析（唯一解析链的柔和变体）:
+ * 与 resolveMagicDir 同一条链，但推导失败时返回 "" 而非 failClosed——
+ * 供 vocabulary 等「文件缺失静默返回空」语义的调用方使用（对齐 bash：禁止猜测 adapter 名）。
+ * find-up 语义（2026-08-14 Task 5.1 补齐）: 以当前文件为锚点向上找「以 . 开头的目录名」
+ * （magicDir 约定形态），替代手写 for 循环——层级变动零漂移（对齐 src/shared/paths.ts 范式）。
+ */
+export function tryResolveMagicDir(): string {
+  const injected = process.env.MAGIC_DIR
+  if (injected) return injected
+  const startDir = dirname(fileURLToPath(import.meta.url))
+  // find-up v8 matcher 约定: 返回命中值（string）或 undefined（未命中）
+  const hit = findUpSync((dir) => (basename(dir).startsWith(".") ? dir : undefined), {
+    cwd: startDir,
+    type: "directory",
+  })
+  return hit ? basename(hit) : ""
+}
+
+/**
+ * PROJECT_DIR 统一解析: 注入优先；否则以 magicDir 为锚点向上查找其父目录（项目根）。
+ * 失败 → failClosed（不猜测项目路径）。
+ * find-up 语义（2026-08-14 Task 5.1 补齐）: 替代手写 for 循环，层级零漂移。
+ */
+export function resolveProjectDir(): string {
+  const injected = process.env.PROJECT_DIR
+  if (injected) return injected
+  const magicDir = resolveMagicDir()
+  const startDir = dirname(fileURLToPath(import.meta.url))
+  const hit = findUpSync((dir) => (basename(dir) === magicDir ? dir : undefined), {
+    cwd: startDir,
+    type: "directory",
+  })
+  return hit ? dirname(hit) : failClosed("PROJECT_DIR 未注入且无法从物理位置推导")
+}
+
+// ── ADD 活跃 Plan 检测（对齐 bash common.sh query_plan_status / detect_active_add）──
+//
+// lifecycle 的唯一真相源是 scoped DB。短生命周期 Hook 不常驻 LISTEN；每次触发
+// 都通过当前 adapter 生成态的机器桥（plan-status-bridge）调用 shared resolver。
+// Handoff/add-route 不参与 active 裁决，禁止跨 adapter 或文件系统 fallback。
+
+export interface PlanStatusResult {
+  stdout: string
+  exitCode: number
+}
+
+/**
+ * 查询活跃 Plan 状态（对齐 bash query_plan_status）:
+ *   - MAGIC_DIR 未注入 → STATUS_UNAVAILABLE（exitCode 3）——对齐 bash：
+ *     未注入且无 HOOK_DIR 时直接放弃，不做物理推导（入口 hook 保证注入）
+ *   - bridge 缺失 → STATUS_UNAVAILABLE（exitCode 3）
+ *   - 否则 spawn `node --import tsx <magicDir>/scripts/plan-status-bridge.ts`
+ */
+export function queryPlanStatus(): PlanStatusResult {
+  const magicDir = process.env.MAGIC_DIR
+  if (!magicDir) {
+    return {
+      stdout: '{"availability":"STATUS_UNAVAILABLE","source":"database","reason":"magicDir 未注入且无法从物理位置推导"}',
+      exitCode: 3,
+    }
+  }
+  const bridge = join(
+    process.env.PROJECT_DIR || process.cwd(),
+    magicDir,
+    "scripts",
+    "plan-status-bridge.ts"
+  )
+  if (!existsSync(bridge)) {
+    return {
+      stdout: '{"availability":"STATUS_UNAVAILABLE","source":"database","reason":"plan-status bridge missing"}',
+      exitCode: 3,
+    }
+  }
+  const r = spawnSync("node", ["--import", "tsx", bridge], {
+    encoding: "utf-8",
+    timeout: 10_000,
+  })
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 }
+}
+
+/**
+ * 活跃 Plan 检测（对齐 bash detect_active_add）:
+ *   - bridge 失败 → "__STATUS_UNAVAILABLE__::<reason>::database::none::none"（调用方 fail-closed）
+ *   - 非 READY/isActive → null（对齐 bash return 1）
+ *   - 活跃 → "plan::done/total::approval::none::none"
+ */
+export function detectActiveAdd(): string | null {
+  const r = queryPlanStatus()
+  if (r.exitCode !== 0) {
+    let reason = "database status unavailable"
+    try {
+      const parsed = JSON.parse(r.stdout) as { reason?: string }
+      if (parsed.reason) reason = parsed.reason
+    } catch {
+      /* 非 JSON 输出 → 默认 reason */
+    }
+    return `__STATUS_UNAVAILABLE__::${reason}::database::none::none`
+  }
+  let snapshot: {
+    availability?: string
+    isActive?: boolean
+    planName?: string
+    approvalStatus?: string
+    progress?: { doneTasks?: number; totalTasks?: number }
+  }
+  try {
+    snapshot = JSON.parse(r.stdout) as typeof snapshot
+  } catch {
+    return null
+  }
+  if (!(snapshot.availability === "READY" && snapshot.isActive === true)) return null
+  const done = snapshot.progress?.doneTasks ?? 0
+  const total = snapshot.progress?.totalTasks ?? 0
+  const approval = snapshot.approvalStatus ?? "none"
+  return `${snapshot.planName}::${done}/${total}::${approval}::none::none`
+}
+
+// ── 时间格式（对齐 bash date 工具链）──
+
+/** 对齐 bash `date -Iseconds`：本地时间 + 时区偏移（如 2026-08-14T11:15:41+08:00） */
+export function localIsoSeconds(): string {
+  const d = new Date()
+  const pad = (n: number) => String(n).padStart(2, "0")
+  const offsetMin = -d.getTimezoneOffset()
+  const sign = offsetMin >= 0 ? "+" : "-"
+  const offAbs = Math.abs(offsetMin)
+  const off = `${sign}${pad(Math.floor(offAbs / 60))}:${pad(offAbs % 60)}`
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${off}`
+  )
+}
+
+// ── Dev Action 追踪（对齐 bash common.sh 标记文件管理）──
+
+/** 项目 hash（对齐 bash echo "${PROJECT_DIR:-$PWD}" | md5sum | cut -c1-8：echo 含换行）——标记文件命名的唯一算法 */
+export function projectHash(): string {
+  try {
+    // bash echo 输出带 \n，md5 对象为 dir + 换行
+    return createHash("md5")
+      .update(`${process.env.PROJECT_DIR || process.cwd()}\n`)
+      .digest("hex")
+      .slice(0, 8)
+  } catch {
+    return "default"
+  }
+}
+
+const DEV_FLAG = `/tmp/add_dev_${projectHash()}`
+
+export function markDevAction(): void {
+  try {
+    writeFileSync(DEV_FLAG, "")
+  } catch {
+    /* ignore */
+  }
+}
+
+export function hasDevAction(): boolean {
+  return existsSync(DEV_FLAG)
+}
+
+export function clearDevAction(): void {
+  try {
+    unlinkSync(DEV_FLAG)
+  } catch {
+    /* ignore */
+  }
+}
+
+// ── 验收完整度检查（对齐 bash check_add_completeness）──
+
+/** 检查 handoff + add-route 的验收完整度，返回问题列表（无问题 → 空数组） */
+export function checkAddCompleteness(handoff: string, addRoute: string): string[] {
+  const issues: string[] = []
+
+  // devlog（内容已回流至 handoff，检查 handoff 是否含验收结果）
+  if (handoff && existsSync(handoff)) {
+    const content = readFileSync(handoff, "utf-8")
+    if (!/验收|收敛|闭环|本轮改了什么|devlog/.test(content)) {
+      issues.push("  [ ] devlog 缺失（handoff 无验收记录）")
+    }
+    const unchecked = (content.match(/\[ \]/g) || []).length
+    if (unchecked > 0) {
+      issues.push(`  [ ] handoff ${unchecked} 项未勾选`)
+    }
+  }
+
+  // add-route Step
+  if (addRoute && existsSync(addRoute)) {
+    const content = readFileSync(addRoute, "utf-8")
+    const unchecked = (content.match(/\[ \]/g) || []).length
+    if (unchecked > 0) {
+      issues.push(`  [ ] add-route ${unchecked} Step 未闭环`)
+    }
+  }
+  return issues
+}
+
+/**
+ * 验收幂等保护（对齐 bash is_already_accepted）:
+ *   add-route Step 8 区段含 "[x].*验证并更新项目状态" 且 handoff 含验收字样 → 已验收。
+ */
+export function isAlreadyAccepted(addRoute: string, handoff: string): boolean {
+  if (addRoute && existsSync(addRoute)) {
+    const content = readFileSync(addRoute, "utf-8")
+    const step8 = content.match(/Step 8[\s\S]{0,2000}/)?.[0] ?? ""
+    if (/\[x\].*验证并更新项目状态/.test(step8)) {
+      if (handoff && existsSync(handoff)) {
+        const h = readFileSync(handoff, "utf-8")
+        if (/✅.*验收|收敛|全部闭环|全部.*完成/.test(h)) {
+          return true
+        }
+      }
+    }
+  }
+  return false
+}

package/templates/core/governance/context-inject.ts

@@ -0,0 +1,53 @@
+// context-inject.ts — 上下文注入模板（bash 版 context-inject.sh 的 TS 同语义实现）
+// 共享库: SessionStart JSON 注入 + Stop 七象限分流 few-shot + 写操作前置守卫
+// 规则真源: hook-context-rules.toml（[context.quadrants] / [context.pretool]）
+// consumed 语义（Task 2.3 死代码象限归档）: true = 有入口消费；false = 死代码象限
+//   （2026-08-14 实态核验: 全端 stop-check 仅消费 no_add_has_dev + has_add_dev_unclosed）
+
+import { context } from "./rules.js"
+
+/** 象限条目（rules.context.quadrants 结构） */
+interface Quadrant {
+  id: string
+  consumed: boolean
+  text: string
+}
+
+/** 结构化 SessionStart JSON 注入（与 bash build_session_start_json 逐字对齐） */
+export function buildSessionStartJson(
+  plan: string,
+  step: string,
+  round: string,
+  handoff: string
+): string {
+  return `{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "上次 ADD 流程未完成:\\n  Plan: ${plan}\\n  轮次: ${round}\\n  当前 Step: ${step} (add-route)\\n  恢复命令: query_audit_logs({ planKeyword: '${plan}' })\\n  handoff: ${handoff}"
+  }
+}
+`
+}
+
+/** 象限文本索引（真源: hook-context-rules.toml [context.quadrants]）
+ * Task 9.4.3 裁剪: 仅加载 consumed=true 象限（no_add_has_dev / has_add_dev_unclosed）——
+ * 死代码象限（consumed=false ×5）从运行索引移除（不可达），文本保留 TOML 真源待归档。 */
+const QUADRANTS: Map<string, Quadrant> = new Map(
+  (((context.quadrants as unknown as Quadrant[]) ?? [])
+    .filter((q) => q.consumed === true)
+    .map((q) => [q.id, q]) as Array<[string, Quadrant]>)
+)
+
+/** Stop 七象限分流 few-shot 上下文（文本真源 = TOML；{{info}} 占位符 replace 插值） */
+export function buildStopContext(quadrant: string, info: string): string {
+  const q = QUADRANTS.get(quadrant)
+  if (!q) return ""
+  return q.text.replaceAll("{{info}}", info)
+}
+
+/** 写操作前置守卫上下文（真源: hook-context-rules.toml [context.pretool]） */
+export function buildPretoolContext(plan: string, round: string): string {
+  const tpl = (context.pretool as { text: string }).text
+  return tpl.replaceAll("{{plan}}", plan).replaceAll("{{round}}", round)
+}