add-coder 0.3.25 → 0.3.27

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

@@ -7,6 +7,19 @@ import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shar
 import { prisma } from "../shared/prisma.js"
 import type { PlanRow } from "../shared/db-types.js"
 import { PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
+import { getRuntimeContext } from "../shared/env.js"
+import { assertPathInRuntimeScope } from "../shared/runtime-context.js"
+import { resolvePlanStatus } from "../shared/plan-lifecycle.js"
+import { createPrismaPlanStatusStore } from "../shared/plan-status-store.js"
+import {
+  trackPlanAndPublish,
+  type PlanTrackingDatabase,
+} from "../shared/plan-tracking-mutation.js"
+import {
+  closePlanRoundAndPublish,
+  type PlanRoundDatabase,
+} from "../shared/plan-round-mutation.js"
+import { queryPlanRounds, type PlanRoundReadClient } from "../shared/plan-round-store.js"
 
 // 无类型边界单点（zod 托管）：动态加载的 prisma client 在此一次性转为运行期校验的泛型委托
 const db = {
@@ -14,6 +27,14 @@ const db = {
 }
 
 export function registerPlanTools(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext()
+  const statusStore = createPrismaPlanStatusStore(prisma)
+  const parseStructuredState = (value: string, field: string): Record<string, unknown> | unknown[] => {
+    let parsed: unknown
+    try { parsed = JSON.parse(value) } catch { throw new Error(`${field} 必须是有效 JSON`) }
+    if (parsed === null || typeof parsed !== "object") throw new Error(`${field} 必须是非 null JSON 对象或数组`)
+    return parsed as Record<string, unknown> | unknown[]
+  }
 
   // ===== plan_track =====
   server.registerTool("plan_track", {
@@ -24,7 +45,7 @@ export function registerPlanTools(server: ToolRegistrar) {
     }),
   }, async (args: Record<string, unknown>) => {
     try {
-      const { planName, scanAll } = args as { planName?: string; scanAll?: boolean }
+      const { planName } = args as { planName?: string; scanAll?: boolean }
       const pn = typeof planName === "string" ? planName : ""
       const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
       const specsDir = join(PROJECT_ROOT, MAGIC_DIR, "specs")
@@ -32,7 +53,7 @@ export function registerPlanTools(server: ToolRegistrar) {
 
       if (!existsSync(plansDir)) return errorResponse(`plans 目录不存在: ${plansDir}`)
 
-      let targets: { name: string; path: string; keyword: string }[] = []
+      const targets: { name: string; path: string; keyword: string }[] = []
       const newPlans: string[] = []
       const allFiles = await readdirRecursive(plansDir)
       // 排除 .hitl.md（HITL 提案不是 Plan 本体，避免 plan_track 误扫为独立 Plan）
@@ -84,7 +105,6 @@ export function registerPlanTools(server: ToolRegistrar) {
         )
         const addRoutePath = addRouteFile ? join(plansDir, addRouteFile) : undefined
         // upsert PlanRecord
-        const existing = await db.plan.findFirst({ where: { planName: t.name } })
         const data: Partial<PlanRow> = {
           planPath: t.path,
           specPath: existsSync(specPath) ? specPath : undefined,
@@ -94,11 +114,16 @@ export function registerPlanTools(server: ToolRegistrar) {
           totalTasks, doneTasks, checklistT, checklistTDone, checklistR,
           planKeyword: keyword,
         }
-        if (existing) {
-          await db.plan.update({ where: { id: existing.id }, data })
+        assertPathInRuntimeScope(runtimeContext, t.path)
+        const tracked = await trackPlanAndPublish(prisma as unknown as PlanTrackingDatabase, {
+          context: runtimeContext,
+          planName: t.name,
+          planPath: t.path,
+          projection: data,
+        })
+        if (!tracked.created) {
           results.push(`  ✅ 已更新 (totalTasks=${totalTasks}, done=${doneTasks})` + (addRoutePath ? `, addRoute` : ``))
         } else {
-          await db.plan.create({ data: { ...data, planName: t.name, planPath: t.path } })
           results.push(`  ✅ 已创建 (totalTasks=${totalTasks}, done=${doneTasks})` + (addRoutePath ? `, addRoute` : ``))
           newPlans.push(t.name.replace(/-plan-v\d+$/, ""))
         }
@@ -106,7 +131,13 @@ export function registerPlanTools(server: ToolRegistrar) {
       // ── 孤儿对账（全量扫描时）：PlanRecord 存在但 planPath 文件缺失 → 悬空清单。
       //    来源：create_hitl 预置行被中断 / 用户放弃未清理。允许暂时存在，不允许不可见。 ──
       if (!pn) {
-        const allPlans = await db.plan.findMany({ orderBy: { createdAt: "desc" } })
+        const allPlans = await db.plan.findMany({
+          where: {
+            projectKey: runtimeContext.projectKey,
+            adapterKey: runtimeContext.adapterKey,
+          },
+          orderBy: { createdAt: "desc" },
+        })
         const orphans = allPlans.filter(p => !existsSync(p.planPath))
         if (orphans.length > 0) {
           results.push("", `⚠️ 悬空 Plan（记录在、文件缺失）— 续写或清理:`)
@@ -137,17 +168,35 @@ export function registerPlanTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const plan = await db.plan.findFirst({ where: { planName } })
-      if (!plan) return textResponse(`📋 Plan: 未跟踪\nplanName: ${planName}\n\n操作: plan_track({ planName: "${planName}" })`)
-      const t = plan.totalTasks || 0
-      const d = plan.doneTasks || 0
-      const ct = plan.checklistT || 0
-      const ctd = plan.checklistTDone || 0
+      const resolution = await resolvePlanStatus(statusStore, runtimeContext, planName)
+      if (resolution.availability === "STATUS_UNAVAILABLE") {
+        return errorResponse(`Plan status 不可用（禁止按文件猜测）: ${resolution.reason}`)
+      }
+      if (resolution.planName === null) {
+        return textResponse(`📋 Plan: 未跟踪\nplanName: ${planName}\nsource: database\ncontextId: ${runtimeContext.contextId}\n\n操作: plan_track({ planName: "${planName}" })`)
+      }
+      const plan = await db.plan.findFirst({
+        where: {
+          projectKey: runtimeContext.projectKey,
+          adapterKey: runtimeContext.adapterKey,
+          planName,
+        },
+      })
+      if (!plan) return errorResponse(`Plan status 解析后记录消失，请重试: ${planName}`)
+      const t = resolution.progress.totalTasks
+      const d = resolution.progress.doneTasks
+      const ct = resolution.progress.checklistT
+      const ctd = resolution.progress.checklistTDone
       const cr = plan.checklistR || 0
       const taskPct = t > 0 ? Math.round((d / t) * 100) : 0
       const lines = [
         `📊 ${planName}`,
         ``,
+        `lifecycle:    ${resolution.lifecycle} (${resolution.isActive ? "active" : "inactive"})`,
+        `approval:     ${resolution.approvalStatus ?? "—"}`,
+        `revision:     ${resolution.revision}`,
+        `source:       database`,
+        `contextId:    ${runtimeContext.contextId}`,
         `tasks.md:     ${d}/${t} (${taskPct}%) ${taskPct >= 100 ? "✅" : d > 0 ? "🔄" : "⬜"}`,
         `checklist:    [T] ${ctd}/${ct} | [R] ${cr} 项`,
         `planKeyword:  ${plan.planKeyword || "—"}`,
@@ -156,6 +205,7 @@ export function registerPlanTools(server: ToolRegistrar) {
         // P3 #5 契约角色展示（PlanRecord 已设置时）
         plan.contractRole ? `contractRole: ${plan.contractRole}` : null,
         plan.contractName ? `contractName: ${plan.contractName}` : null,
+        `machine:      ${JSON.stringify(resolution)}`,
       ].filter(Boolean)
       return textResponse(lines.join("\n"))
     } catch (e) {
@@ -172,9 +222,16 @@ export function registerPlanTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const plan = await db.plan.findFirst({ where: { planName } })
+      const plan = await db.plan.findFirst({
+        where: {
+          projectKey: runtimeContext.projectKey,
+          adapterKey: runtimeContext.adapterKey,
+          planName,
+        },
+      })
       if (!plan) return errorResponse(`PlanRecord 未找到: ${planName}`)
       const planPath = plan.planPath
+      assertPathInRuntimeScope(runtimeContext, planPath)
       if (!existsSync(planPath)) return errorResponse(`Plan 文件不存在: ${planPath}`)
       const content = readFileSync(planPath, "utf-8")
       const t = plan.totalTasks || 0
@@ -195,7 +252,6 @@ export function registerPlanTools(server: ToolRegistrar) {
       ].join("\n")
       // 用 indexOf 安全替换（不用跨行正则）
       const marker = "## 📊 Plan 进度快照"
-      const markerEnd = "\n## 📊 Plan 进度快照"
       // 找到现有快照区块的结束位置
       const startIdx = content.indexOf(marker)
       let newContent: string
@@ -217,4 +273,73 @@ export function registerPlanTools(server: ToolRegistrar) {
     }
   })
 
+  // ===== plan_round_close =====
+  server.registerTool("plan_round_close", {
+    description: "关闭一个逻辑 PlanRound：在当前 RuntimeContextKey 内幂等写入 ROUND_CLOSED，并于同一 Prisma transaction 发布 PostgreSQL 唤醒通知。不会关闭整个 Plan，也不会修改 lifecycle/revision。",
+    inputSchema: z.object({
+      planName: z.string().min(1),
+      round: z.number().int().positive(),
+      beforeState: z.string().describe("非 null JSON 对象或数组字符串"),
+      afterState: z.string().describe("非 null JSON 对象或数组字符串，包含本轮产出摘要"),
+      reason: z.string().optional(),
+      operationKey: z.string().optional(),
+    }),
+  }, async (args: Record<string, unknown>) => {
+    try {
+      const input = args as { planName: string; round: number; beforeState: string; afterState: string; reason?: string; operationKey?: string }
+      const result = await closePlanRoundAndPublish(prisma as unknown as PlanRoundDatabase, {
+        context: runtimeContext,
+        planName: input.planName,
+        round: input.round,
+        beforeState: parseStructuredState(input.beforeState, "beforeState"),
+        afterState: parseStructuredState(input.afterState, "afterState"),
+        reason: input.reason,
+        operationKey: input.operationKey,
+      })
+      return textResponse([
+        "✅ PlanRound 已关闭",
+        `planName: ${result.plan.planName}`,
+        `round: ${input.round}`,
+        `operationId: ${result.operation.id}`,
+        `targetId: ${result.operation.targetId}`,
+        `lifecycle: ${result.plan.lifecycle} (未修改)`,
+        `revision: ${result.plan.revision} (未修改)`,
+        "source: database",
+      ].join("\n"))
+    } catch (e) {
+      return errorResponse(`plan_round_close 失败: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  })
+
+  // ===== plan_round_status =====
+  server.registerTool("plan_round_status", {
+    description: "查询当前 RuntimeContextKey 下的 ROUND_CLOSED 记录。数据库是权威状态；通知仅负责唤醒订阅者调用本查询。",
+    inputSchema: z.object({
+      planName: z.string().min(1),
+      round: z.number().int().positive().optional(),
+    }),
+  }, async (args: Record<string, unknown>) => {
+    try {
+      const input = args as { planName: string; round?: number }
+      const snapshot = await queryPlanRounds(prisma as unknown as PlanRoundReadClient, {
+        context: runtimeContext,
+        planName: input.planName,
+        round: input.round,
+      })
+      if (!snapshot.planId) return textResponse(`📋 PlanRound: 未找到 scoped Plan\nplanName: ${input.planName}\ncontextId: ${runtimeContext.contextId}`)
+      const lines = [
+        `📋 PlanRound: ${snapshot.planName}`,
+        `contextId: ${runtimeContext.contextId}`,
+        `source: database`,
+        `records: ${snapshot.rounds.length}`,
+      ]
+      for (const record of snapshot.rounds) {
+        lines.push(`- ${record.targetId} | ${record.createdAt.toISOString()} | operationId=${record.id}`)
+      }
+      return textResponse(lines.join("\n"))
+    } catch (e) {
+      return errorResponse(`plan_round_status 失败: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  })
+
 }

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

@@ -7,6 +7,8 @@ import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shar
 import { prisma } from "../shared/prisma.js"
 import type { PlanRow, ReviewRow } from "../shared/db-types.js"
 import { PlanRowSchema, ReviewRowSchema, validatedDelegate } from "../shared/db-types.js"
+import { getRuntimeContext } from "../shared/env.js"
+import { assertPathInRuntimeScope } from "../shared/runtime-context.js"
 
 const db = {
   get review() { return validatedDelegate<ReviewRow>(prisma.reviewRecord, ReviewRowSchema, "ReviewRecord") },
@@ -34,6 +36,7 @@ function countIssueType(content: string): { p0: number; p1: number; backflow: nu
 }
 
 export function registerReviewTools(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext()
 
   // ===== review_track =====
   server.registerTool("review_track", {
@@ -44,7 +47,7 @@ export function registerReviewTools(server: ToolRegistrar) {
     }),
   }, async (args: Record<string, unknown>) => {
     try {
-      const { planName, scanAll } = args as { planName?: string; scanAll?: boolean }
+      const { planName } = args as { planName?: string; scanAll?: boolean }
       const pn = typeof planName === "string" ? planName : ""
       const reviewsDir = join(PROJECT_ROOT, MAGIC_DIR, "reviews")
       if (!existsSync(reviewsDir)) return errorResponse(`reviews 目录不存在: ${reviewsDir}`)
@@ -57,7 +60,7 @@ export function registerReviewTools(server: ToolRegistrar) {
         const fullPath = join(reviewsDir, rf)
         // 从文件名推导 planName
         // 格式: {plan-name}-review-v1.md 或 {plan-name}-review-implementation.md
-        let derivedPlan = basename(rf, ".md")
+        const derivedPlan = basename(rf, ".md")
           .replace(/-review-.*$/, "")
           .replace(/-implementation.*$/, "")
           .replace(/-runtime.*$/, "")
@@ -69,7 +72,11 @@ export function registerReviewTools(server: ToolRegistrar) {
         // 而 derivedPlan 为 {planPrefix}（从 review 文件名中去掉了 -review-v{n}）
         // 需要用 contains 匹配，而不是 exact match
         const planMatch = await db.plan.findFirst({
-          where: { planName: { contains: derivedPlan } },
+          where: {
+            projectKey: runtimeContext.projectKey,
+            adapterKey: runtimeContext.adapterKey,
+            planName: { contains: derivedPlan },
+          },
         })
         const actualPlanName = planMatch
           ? planMatch.planName
@@ -81,7 +88,12 @@ export function registerReviewTools(server: ToolRegistrar) {
         const rtype = detectReviewType(rf)
         const stats = countIssueType(content)
         const record = await db.review.findFirst({
-          where: { planName: actualPlanName, type: rtype },
+          where: {
+            projectKey: runtimeContext.projectKey,
+            adapterKey: runtimeContext.adapterKey,
+            planName: actualPlanName,
+            type: rtype,
+          },
         })
 
         const data = {
@@ -95,7 +107,13 @@ export function registerReviewTools(server: ToolRegistrar) {
           results.push(`🔄 ${rf} (${rtype}) P0=${stats.p0} P1=${stats.p1}`)
         } else {
           await db.review.create({
-            data: { planName: actualPlanName, type: rtype, ...data },
+            data: {
+              projectKey: runtimeContext.projectKey,
+              adapterKey: runtimeContext.adapterKey,
+              planName: actualPlanName,
+              type: rtype,
+              ...data,
+            },
           })
           results.push(`✅ ${rf} (${rtype}) P0=${stats.p0} P1=${stats.p1}`)
         }
@@ -118,7 +136,11 @@ export function registerReviewTools(server: ToolRegistrar) {
     try {
       const { planName } = args as { planName: string }
       const rows = await db.review.findMany({
-        where: { planName },
+        where: {
+          projectKey: runtimeContext.projectKey,
+          adapterKey: runtimeContext.adapterKey,
+          planName,
+        },
         orderBy: { type: "asc" },
       })
 
@@ -130,9 +152,9 @@ export function registerReviewTools(server: ToolRegistrar) {
 
       const lines = [`📝 Review: ${planName}`, ``]
       for (const r of rows) {
-        const p0 = r.p0Count as number || 0
-        const p1 = r.p1Count as number || 0
-        const br = r.backflowRate as number || 0
+        const p0 = r.p0Count || 0
+        const p1 = r.p1Count || 0
+        const br = r.backflowRate || 0
         const total = p0 + p1
         lines.push(
           `  [${r.type}] P0=${p0} P1=${p1} (合计 ${total}) 回流=${br}`,
@@ -140,8 +162,8 @@ export function registerReviewTools(server: ToolRegistrar) {
         )
       }
       // 汇总
-      const tP0 = rows.reduce((s: number, r) => s + (r.p0Count as number || 0), 0)
-      const tP1 = rows.reduce((s: number, r) => s + (r.p1Count as number || 0), 0)
+      const tP0 = rows.reduce((s: number, r) => s + (r.p0Count || 0), 0)
+      const tP1 = rows.reduce((s: number, r) => s + (r.p1Count || 0), 0)
       lines.push(``, `总计: P0=${tP0} P1=${tP1}`)
       return textResponse(lines.join("\n"))
     } catch (e) {
@@ -158,7 +180,13 @@ export function registerReviewTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { planName } = args as { planName: string }
-      const rows = await db.review.findMany({ where: { planName } })
+      const rows = await db.review.findMany({
+        where: {
+          projectKey: runtimeContext.projectKey,
+          adapterKey: runtimeContext.adapterKey,
+          planName,
+        },
+      })
 
       if (!rows.length) return errorResponse(`无 ReviewRecord: ${planName}`)
 
@@ -169,10 +197,11 @@ export function registerReviewTools(server: ToolRegistrar) {
           results.push(`⚠️ 文件不存在: ${rp || r.type}`)
           continue
         }
+        assertPathInRuntimeScope(runtimeContext, rp)
         const content = readFileSync(rp, "utf-8")
-        const p0 = r.p0Count as number || 0
-        const p1 = r.p1Count as number || 0
-        const br = r.backflowRate as number || 0
+        const p0 = r.p0Count || 0
+        const p1 = r.p1Count || 0
+        const br = r.backflowRate || 0
 
         const metaLines = [
           "<!-- REVIEW_META",

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

@@ -1,6 +1,17 @@
 import { McpServer } from "@modelcontextprotocol/server"
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"
 import { registerAll } from "./mcp-server/index.js"
+import { redact } from "./mcp-server/shared/redact.js"
+import { DATABASE_URL, getRuntimeContext } from "./mcp-server/shared/env.js"
+import { prisma } from "./mcp-server/shared/prisma.js"
+import { resolvePlanStatus } from "./mcp-server/shared/plan-lifecycle.js"
+import { createPrismaPlanStatusStore } from "./mcp-server/shared/plan-status-store.js"
+import {
+  createPgLifecycleListenClient,
+  PlanLifecycleSubscriber,
+} from "./mcp-server/shared/plan-lifecycle-subscriber.js"
+import { PlanRoundSubscriber } from "./mcp-server/shared/plan-round-subscriber.js"
+import { queryPlanRounds, type PlanRoundReadClient } from "./mcp-server/shared/plan-round-store.js"
 
 async function main() {
   const server = new McpServer(
@@ -10,10 +21,58 @@ async function main() {
   registerAll(server)
   const transport = new StdioServerTransport()
   await server.connect(transport)
+  let lifecycleSubscriber: PlanLifecycleSubscriber | undefined
+  let planRoundSubscriber: PlanRoundSubscriber | undefined
+  if (/^postgres(ql)?:\/\//.test(DATABASE_URL)) {
+    const context = getRuntimeContext()
+    const store = createPrismaPlanStatusStore(prisma)
+    lifecycleSubscriber = new PlanLifecycleSubscriber({
+      context,
+      clientFactory: () => createPgLifecycleListenClient(DATABASE_URL),
+      resolveStatus: ({ context: subscriberContext, planId }) => resolvePlanStatus(
+        store,
+        subscriberContext,
+        planId ? { planId } : { activeOnly: true },
+      ),
+      onSnapshot: (snapshot, envelope) => {
+        const trigger = envelope ? `notify:${envelope.eventId}` : "initial"
+        console.error(`[ADD-MCP] lifecycle pull (${trigger}) ${JSON.stringify(snapshot)}`)
+      },
+      onError: (error) => console.error(`[ADD-MCP] lifecycle subscriber: ${redact(error.message)}`),
+    })
+    await lifecycleSubscriber.start().catch((error: unknown) => {
+      console.error(`[ADD-MCP] lifecycle initial pull failed: ${redact(error instanceof Error ? error.message : String(error))}`)
+    })
+    planRoundSubscriber = new PlanRoundSubscriber({
+      context,
+      clientFactory: () => createPgLifecycleListenClient(DATABASE_URL),
+      queryRounds: ({ context: subscriberContext, planId }) => queryPlanRounds(
+        prisma as unknown as PlanRoundReadClient,
+        { context: subscriberContext, planId },
+      ),
+      onSnapshot: (snapshot, envelope) => {
+        const trigger = envelope ? `notify:${envelope.eventId}` : "initial"
+        console.error(`[ADD-MCP] PlanRound pull (${trigger}) ${JSON.stringify({
+          contextId: snapshot.context.contextId,
+          planId: snapshot.planId,
+          planName: snapshot.planName,
+          records: snapshot.rounds.length,
+        })}`)
+      },
+      onError: (error) => console.error(`[ADD-MCP] PlanRound subscriber: ${redact(error.message)}`),
+    })
+    await planRoundSubscriber.start().catch((error: unknown) => {
+      console.error(`[ADD-MCP] PlanRound initial pull failed: ${redact(error instanceof Error ? error.message : String(error))}`)
+    })
+  }
+  process.stdin.once("end", () => {
+    void lifecycleSubscriber?.stop()
+    void planRoundSubscriber?.stop()
+  })
   console.error("[ADD-MCP] add-dev-tools MCP server started on stdio")
 }
 
 main().catch((error) => {
-  console.error("[ADD-MCP] Fatal error:", error)
+  console.error("[ADD-MCP] Fatal error:", redact(error instanceof Error ? error.message : String(error)))
   process.exit(1)
 })

package/templates/core/scripts/plan-status-bridge.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { getRuntimeContext } from "./mcp-server/shared/env.js"
+import { prisma } from "./mcp-server/shared/prisma.js"
+import { resolvePlanStatus } from "./mcp-server/shared/plan-lifecycle.js"
+import { createPrismaPlanStatusStore } from "./mcp-server/shared/plan-status-store.js"
+
+async function main(): Promise<void> {
+  const context = getRuntimeContext()
+  const store = createPrismaPlanStatusStore(prisma)
+  const snapshot = await resolvePlanStatus(store, context, { activeOnly: true })
+  process.stdout.write(`${JSON.stringify(snapshot)}\n`)
+  if (snapshot.availability === "STATUS_UNAVAILABLE") process.exitCode = 3
+}
+
+main()
+  .catch((error: unknown) => {
+    process.stderr.write(`[ADD plan-status-bridge] ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 3
+  })
+  .finally(async () => {
+    const runtimeClient = prisma as unknown as Record<string, unknown>
+    const disconnect = runtimeClient.$disconnect
+    if (typeof disconnect === "function") {
+      await Reflect.apply(disconnect, prisma, []).catch(() => undefined)
+    }
+  })

package/templates/core/skills/add-paradigm/SKILL.md

@@ -379,7 +379,7 @@ Plan 级闭包: {业务功能描述}
 
 **活跃判定规则**：
 
-1. **判定输入**：指定 magicDir 下的 `plans/` 目录（按当前端优先回退——以 Claude IDE 宿主环境为例：`.claude/plans/` → `.qoder/plans/` → `.add/plans/`，其他 IDE 同理取各自的 magicDir）
+1. **判定输入**：当前 adapter 自己的 `{{magicDir}}/plans/`。各 adapter 的 Plan/Spec/Route/Review/HITL 相互独立，禁止跨 adapter fallback
 2. **索引优先**：先读 `plans/index.md` 匹配 planKeyword → 无匹配才 glob `*-plan-v*.md`
 3. **活跃定义**：读 add-route 文件 → 存在 `[ ]` 未勾选的 Step 产出项 = 活跃（进行中）；全部 `[x]` = 已收敛（不活跃）
 4. **多 Plan 冲突**：多个 Plan 均有 `[ ]` → 取 add-route 文件最近修改时间（`mtime`）最大的 Plan
@@ -863,7 +863,7 @@ check_add_route_completeness({ planKeyword: "<Plan 核心关键词>" })
 
 ### 3.5.3 生成实现审查文档
 
-按 HITL temporary.md 流程执行：读取 `review-implementation-template.md` → 先写 `{name}-review-implementation.temporary.md`（只含 HITL 发现总览表）→ 人类一次性拍板 → 逐条展开详细分析 → 写入 `.qoder/reviews/`（guard 放行）→ 删除 temporary。详见上方模板生成规则处的 Review HITL 磋商说明。
+读取 `review-implementation-template.md`，将实现审查发现整理为 `dimensions`，调用 `create_hitl({ planName: "{name}-review-implementation", type: "PLAN_REVIEW", dimensions })`。`create_hitl` 自动生成 `*.hitl.md` 审批提案并写入 HITL 记录；人类审核后调用 `update_hitl` 完成拍板。通过 `status_hitl` 确认状态为 `TONGYI` 后，方可逐条展开详细分析并写入 `{{magicDir}}/reviews/`；若为 `BOHUI`，修订发现后调用 `create_hitl` 新建 round。
 
 ### 3.5.4 生成运行时审查文档（所有 [T] 项通过后）
 

package/templates/core/templates/add-route-template.schema.json

@@ -1,58 +1,61 @@
 {
+    "_generated": true,
+    "_generated_source": "guard-rules.toml",
     "template": "add-route-template.md",
-    "shared_by": [
-        "add-route-template.md",
-        "add-route-template-heavyweight.md"
-    ],
     "sections": [
         {
             "id": "step0",
-            "heading": "## Step 0",
-            "required": true
+            "required": true,
+            "heading": "## Step 0"
         },
         {
             "id": "step0_plan_track",
-            "pattern": "plan_track\\(\\{ planName:",
             "required": true,
+            "anchor": "plan_track",
             "within": "## Step 0",
+            "pattern": "plan_track\\(\\{ planName:",
             "description": "Step 0 产出必须包含 plan_track 落库步骤"
         },
         {
             "id": "step1",
-            "heading": "## Step 1",
-            "required": true
+            "required": true,
+            "heading": "## Step 1"
         },
         {
             "id": "step2",
-            "heading": "## Step 2",
-            "required": true
+            "required": true,
+            "heading": "## Step 2"
         },
         {
             "id": "step3",
-            "heading": "## Step 3",
-            "required": true
+            "required": true,
+            "heading": "## Step 3"
         },
         {
             "id": "step3_5",
-            "heading": "## Step 3.5",
-            "required": false
+            "required": false,
+            "heading": "## Step 3.5"
         },
         {
             "id": "step4",
-            "heading": "## Step 4",
-            "required": true
+            "required": true,
+            "heading": "## Step 4"
         },
         {
             "id": "step5",
-            "heading": "## Step 5",
-            "required": true
+            "required": true,
+            "heading": "## Step 5"
         },
         {
             "id": "step8",
-            "heading": "## Step 8",
-            "required": true
+            "required": true,
+            "heading": "## Step 8"
         }
     ],
+    "shared_by": [
+        "add-route-template.md",
+        "add-route-template-heavyweight.md"
+    ],
     "placeholders": [
         "{需求域名}",
         "{核心内容}",
@@ -71,38 +74,3 @@
         "阶段"
     ]
 }
-{
-    "template": "add-route-template.md",
-    "shared_by": [
-        "add-route-template.md",
-        "add-route-template-heavyweight.md"
-    ],
-    "sections": [
-        {
-            "id": "step0",
-            "heading": "## Step 0",
-            "required": true
-        },
-        {
-            "id": "step3",
-            "heading": "## Step 3",
-            "required": true
-        },
-        {
-            "id": "step8",
-            "heading": "## Step 8",
-            "required": true
-        }
-    ],
-    "placeholders": [
-        "{需求域名}",
-        "{核心内容}",
-        "{版本号}"
-    ],
-    "forbidden_terms": [
-        "Phase",
-        "Round",
-        "轮次",
-        "阶段"
-    ]
-}

package/templates/core/templates/collab-contract-template.md

@@ -169,7 +169,7 @@
 | 发起时机 | 契约新建 / 契约重大变更（参与者增减、边界重划、触发条件变更） |
 | round 机制 | 复用 HitlRecord.round（同一契约多次变更递增 round） |
 | 与子 Plan 审批关系 | 契约审批是**总控级**（planName=总控 Plan）；子 Plan 审批独立进行（互不阻塞） |
-| 哨兵 | `.qoder/hitl/.tongyi-{contractName}`（复用现有哨兵机制） |
+| 哨兵 | `{{magicDir}}/hitl/.tongyi-{contractName}`（复用当前 adapter 的哨兵机制） |
 | 审计 | 契约审批记录入 HitlRecord（type=COLLAB_CONTRACT）→ query_audit_logs 可查 |
 
 ---