sillyspec 3.27.7 → 3.27.11

package/.claude/skills/sillyspec-execute/SKILL.md

@@ -92,7 +92,7 @@ execute 完成时，每个 task 必须有 `review.json` 且 verdict 通过，否
 
 > 🔧 **mechanics 字段不要手算**：`schemaVersion`/`task`/`base`/`head`/`changedFiles`(/跨仓 `repo`) 全部可由 CLI 从 git + task 卡推导。子代理/你只需写**语义字段**（`specVerdict`/`qualityVerdict`/`reviewerNotes`/`requiredEvidence`），mechanics 字段可以瞎填占位（如 `"base": "TODO"`），写完跑 `sillyspec backfill-reviews --change <变更名> --adopt` 一键重算代填（verdict 原样保留）。gate 拦下 mechanics 错误时也跑同一条命令修复。
 
-- 后端 router task 另需产出 API 端点清单：`sillyspec endpoints extract --change <变更名> --task <task-NN>`（CLI 静态扫描 FastAPI/Express/Spring 路由装饰器生成 endpoints.json，verify 探针 5 消费；扫描面默认取 task 卡 allowed_paths ∪ design 清单，也可 `--dir`/`--files` 显式指定）。勿手扫装饰器手写——易漏 endpoint。
+- 后端 router task 另需产出 API 端点清单：`sillyspec endpoints extract --change <变更名> --all-tasks`（聚合逐 task 卡 allowed_paths 提取，与 verify 探针 5 聚合对账口径一致；单 task 可 `--task task-NN`，也可 `--dir`/`--files` 显式指定）。勿手扫装饰器手写——易漏 endpoint；勿只提单 task——局部端点集对账放大假 missing。
 
 ### Stage Review Gate（execute 末尾的 acceptance review.json）
 

package/.npmrc-temp

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.27.7",
+  "version": "3.27.11",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/commit-suggest.js

@@ -71,6 +71,28 @@ function classifyStagePath(p) {
   return null
 }
 
+/**
+ * 暂存区快照（坑 same-main-staging-pollution，2026-08-28 用户实证：同 main 两个活跃会话
+ * 共享同一暂存区，A 的 commit 把 B 暂存的文件扫入——本轮竞态事故根因，无任何防护）。
+ * 防护 = 提交前可见：commit 提示里带 `git diff --cached --name-only` 快照 + 他者文件告警。
+ * @param {{ cwd: string, ownFiles?: string[]|null }} opts
+ *   ownFiles：本会话/本变更的精确文件集（apply-pathspec 等）；提供时对快照做差集，
+ *   不在集内的暂存文件 = 他者会话暂存（告警对象）。null/空数组 = 只出快照不做归属判定。
+ * @returns {{ available: boolean, staged: string[], foreign: string[] }}
+ *   available=false：git 不可用/非仓库（调用方静默跳过，不误报）。
+ */
+export function collectStagedArea({ cwd, ownFiles = null }) {
+  const raw = gitQuiet(cwd, ['diff', '--cached', '--name-only'])
+  if (raw === null) return { available: false, staged: [], foreign: [] }
+  const staged = raw.split('\n').filter(Boolean).map(f => f.replace(/\\/g, '/'))
+  let foreign = []
+  if (Array.isArray(ownFiles) && ownFiles.length > 0) {
+    const own = new Set(ownFiles.map(f => String(f).replace(/\\/g, '/')))
+    foreign = staged.filter(f => !own.has(f))
+  }
+  return { available: true, staged, foreign }
+}
+
 /**
  * 收集提交上下文并生成建议 message。
  * @param {{ cwd: string, specDir?: string|null }} opts

package/src/contract-matrix.js

@@ -117,22 +117,50 @@ export function buildContractMatrix(planContent, changeDir) {
 function parseTaskDependencies(registryContent) {
   const deps = {}
 
-  // 方式 1: 任务总表表格形式 | task-04 | ... | 01,02 |
-  // 列前缀用 [^|\d]*（不吃数字）：旧 [^|]* 贪婪会吃掉 deps 列前导 0（" 01" → g2=1 → task-1），
-  // 导致 provider task-1.md 不存在 → contracts 恒空，端点契约管线失效。
-  const tableRows = registryContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|\d]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
-  for (const match of tableRows) {
-    const task = `task-${match[1]}`
-    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
-    deps[task] = depList
+  // 方式 1: 任务总表表格形式（两种常见格式）
+  //   A: | task-04 | Wave | 优先级 | 说明 | 依赖 |  （task-NN 在独立列）
+  //   B: | task | desc | deps |                       （task-NN 在任意列，bare 数字依赖）
+  // 逐行按 | 分列解析，避免旧单正则 [^|]* 跨列贪婪误读说明列数字（409/HTTP 状态码）
+  // 为假依赖（坑 contract-matrix-false-deps）。
+  // deps 列判定：从行尾倒数第一个「非分隔符、非 task 自身、非单数字(Wave/优先级)」的列，
+  // 且须含逗号/task- 引用/bare 两位以上数字。
+  const lines = registryContent.split('\n')
+  for (const line of lines) {
+    const taskIdMatch = line.match(/task-(\d+)/i)
+    if (!taskIdMatch) continue
+    const taskId = `task-${taskIdMatch[1]}`
+
+    const cells = line.split('|').map(c => c.trim()).filter(c => c.length > 0)
+    if (cells.length < 2) continue
+
+    // 从行尾倒数找 deps 列
+    let depCell = null
+    for (let i = cells.length - 1; i >= 0; i--) {
+      const c = cells[i]
+      if (/^-+$/.test(c)) continue                          // 分隔符 "-"
+      if (c.toLowerCase() === taskId.toLowerCase()) continue // task 自身列
+      // deps 列候选：含逗号（多依赖）或含 task- 引用
+      if (/[,，]/.test(c) || /task-\d+/i.test(c)) { depCell = c; break }
+      // bare 数字：须 ≥2 位且位于行尾第2+列（跳过优先级/Wave 列的个位数）
+      if (/^\d{2,}$/.test(c) && i >= cells.length - 2) { depCell = c; break }
+    }
+    if (!depCell) continue
+    const depNums = depCell.match(/\d+/g) || []
+    deps[taskId] = depNums.map(d => `task-${d.padStart(2, '0')}`)
   }
 
   // 方式 2: tasks.md 行内标注 "- [ ] task-04: 名称 (depends_on: task-01,02)"（新家，D-003@v1；
-  // 旧 plan.md checkbox 行内标注同格式兼容）
-  const dependsPattern = registryContent.matchAll(/task-(\d+).*?depends_on.*?(\d+(?:\s*[,，]\s*\d+)*)/gi)
+  // 旧 plan.md checkbox 行内标注同格式兼容）。仅匹配 (depends_on: ...) 括号内内容，
+  // 不在自由文本上全文正则（坑 contract-matrix-false-deps：说明列数字被误读为依赖）。
+  const dependsPattern = registryContent.matchAll(/task-(\d+)\b[^)]*?\(depends_on:\s*([^)]+)\)/gi)
   for (const match of dependsPattern) {
     const task = `task-${match[1]}`
-    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
+    const depStr = match[2]
+    // 兼容两种写法：task-01, task-02 或 01, 02
+    const depList = depStr.split(/[,，]\s*/).map(s => {
+      const num = s.trim().match(/\d+/)
+      return num ? `task-${num[0].padStart(2, '0')}` : null
+    }).filter(Boolean)
     if (!deps[task]) deps[task] = []
     for (const d of depList) {
       if (!deps[task].includes(d)) deps[task].push(d)
@@ -364,10 +392,13 @@ export function _readWorktreeMeta(specBase, scanRoot, changeName) {
 
 /**
  * 取本变更 diff 文件集（parity 前端调用收窄用，坑 probe5-fullrepo-frontend-noise）。
- * 优先 worktree meta 锚点 diff（与 verify 同源）；无 meta 退主仓 git diff HEAD。
+ * 优先 worktree meta 锚点 diff（与 verify 同源）；无 meta 退主仓 git diff HEAD；
+ * 两者皆空再退 apply-pathspec-<change>.txt（apply 落盘的精确清单）。
+ * 兜底链每级都空才返回 null/[]（调用方回退全仓——坑 probe5-single-task-artifact-scope，
+ * 2026-08-28 实证：apply+commit/cleanup 后 diff 为空 → 全仓调用 × 局部端点 = 150 条假 missing）。
  * @returns {string[]|null}
  */
-function _resolveDiffFilesForParity(specBase, scanRoot, changeName) {
+function _resolveDiffFilesForParity(specBase, scanRoot, changeName, runtimeRoot) {
   try {
     const wt = _readWorktreeMeta(specBase, scanRoot, changeName)
     if (wt) {
@@ -401,7 +432,20 @@ function _resolveDiffFilesForParity(specBase, scanRoot, changeName) {
     if (foreign.length > 0) {
       console.warn(`⚠️ parity 对账已排除 ${foreign.length} 个并行会话声明的文件（${foreign.slice(0, 5).map(x => x.file).join(', ')}${foreign.length > 5 ? ' 等' : ''}）`)
     }
-    return own
+    if (own.length > 0) return own
+    // 主仓 diff 空（apply 后已 commit / cleanup 完毕）→ apply-pathspec 兜底：apply 成功时落盘的
+    // 本变更精确文件清单（与 gates 归因提示②同源）。仍拿不到才回 null（调用方退全仓）。
+    try {
+      const pathspecFile = join(runtimeRoot || join(specBase, '.runtime'), `apply-pathspec-${changeName}.txt`)
+      if (existsSync(pathspecFile)) {
+        const fromPathspec = readFileSync(pathspecFile, 'utf8').split('\n').map(l => l.trim()).filter(Boolean)
+        if (fromPathspec.length > 0) {
+          console.log(`ℹ️ parity 前端范围用 apply-pathspec 兜底（主仓 diff 为空，${fromPathspec.length} 文件）`)
+          return fromPathspec
+        }
+      }
+    } catch { /* 兜底失败 → null 交调用方全仓 */ }
+    return null
   } catch { return null }
 }
 
@@ -498,7 +542,7 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
   const frontendRootLabel = frontendRoot === scanRoot ? 'scan-root' : 'worktree'
   if (changeName) {
     try {
-      const changed = _resolveDiffFilesForParity(specBase, scanRoot, changeName)
+      const changed = _resolveDiffFilesForParity(specBase, scanRoot, changeName, runtimeRoot)
       if (changed && changed.length > 0) {
         const changedSet = new Set(changed.map(f => f.replace(/\\/g, '/')))
         frontendCalls = scanFrontendApiCalls(frontendRoot).filter(c => {

package/src/decision-distill.js

@@ -22,7 +22,7 @@
  * 零输出：无 decisions.md 或无入选条目 → skipped 带原因，不写任何文件、不动 INDEX。
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 
 /** FR-02：有实现影响的五类 type（scope 与未知 type 的 confirmed/accepted 不入选） */
 const IMPLEMENTED_TYPES = new Set(['architecture', 'compatibility', 'boundary', 'definition', 'process'])
@@ -244,10 +244,14 @@ function newDomainPreamble(domain) {
   ]
 }
 
-/** 单条目段落渲染（design 接口定义的条目格式，逐字对齐：状态/锚点/最近确认/理由 + rejected 专属两行） */
-function renderBlockLines(entry, headHash, supersedesNote) {
+/** 单条目段落渲染（design 接口定义的条目格式，逐字对齐：状态/锚点/最近确认/理由 + rejected 专属两行）。
+ * 变更：行（2026-08-28，坑 distill-cross-change-supersede）：D-xxx 编号是变更内局部序号，
+ * 跨变更同号（两个 D-002）互不相干——条目必须携带变更名限定，消费方（knowledge-match/
+ * docs-check 的字段行解析）只认各自标签，新增字段行是增量安全。 */
+function renderBlockLines(entry, headHash, supersedesNote, changeName) {
   const lines = [`## ${entry.id} ${oneLine(entry.title)}`.replace(/\s+$/, '')]
   lines.push(`状态：${entry.selected}`)
+  if (changeName) lines.push(`变更：${oneLine(changeName)}`)
   lines.push(`锚点：${oneLine(entry.anchor) || NOT_RECORDED}`)
   lines.push(`最近确认：${oneLine(headHash) || NOT_RECORDED}`)
   lines.push(`理由：${oneLine(entry.answer || entry.normalizedRequirement || entry.question)}`)
@@ -259,7 +263,9 @@ function renderBlockLines(entry, headHash, supersedesNote) {
   return lines
 }
 
-/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头） */
+/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头）。
+ * 段的变更归属取段内 `变更：<name>` 行；无该行的历史条目 → change=null（legacy：
+ * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。 */
 function splitKnowledgeSections(content) {
   const sections = []
   const preamble = []
@@ -275,7 +281,11 @@ function splitKnowledgeSections(content) {
     else preamble.push(line)
   }
   if (cur) sections.push(cur)
-  for (const s of sections) s.id = `${s.number}@v${s.version}`
+  for (const s of sections) {
+    s.id = `${s.number}@v${s.version}`
+    const cm = s.lines.find(l => /^变更[：:]/.test(l))
+    s.change = cm ? cm.replace(/^变更[：:]\s*/, '').trim() || null : null
+  }
   return { preamble, sections }
 }
 
@@ -293,15 +303,20 @@ function joinKnowledgeFile(preamble, sections) {
 
 /**
  * 单条目写入一个域文件的段落集（就地修改 sections）。
- * @returns {{ action: 'append'|'update'|'supersede' }|null} null = 高版本已落库，迟到低版本不降级。
+ * 坑 distill-cross-change-supersede（2026-08-28 用户实证：跨变更同号 D-002 在 knowledge
+ * 里互相 supersede）：幂等键从「号」改为「号+变更」——同号匹配、版本守卫、旧版本段清除
+ * 全部限定在 entry.change 内；他者变更的同号段不参与（共存）。legacy 段（change=null，
+ * 升级前落库）不与任何新条目互认，只共存不误删。
+ * @returns {{ action: 'append'|'update'|'supersede' }|null} null = 同变更同号高版本已落库，迟到低版本不降级。
  */
 function applyEntryToSections(sections, entry, headHash) {
-  const sameNumber = sections.filter(s => s.number === entry.number)
+  const change = entry.change || null
+  const sameNumber = sections.filter(s => s.number === entry.number && (s.change || null) === change)
   if (sameNumber.some(s => s.version > entry.version)) return null
   let action
   let supersedesNote = oneLine(entry.supersedes) || null
   if (sameNumber.length === 0) {
-    sections.push({ number: entry.number, version: entry.version, id: entry.id, title: entry.title, lines: renderBlockLines(entry, headHash, supersedesNote) })
+    sections.push({ number: entry.number, version: entry.version, id: entry.id, title: entry.title, change, lines: renderBlockLines(entry, headHash, supersedesNote, change || undefined) })
     action = 'append'
   } else {
     const same = sameNumber.find(s => s.version === entry.version)
@@ -309,10 +324,10 @@ function applyEntryToSections(sections, entry, headHash) {
     if (!same && !supersedesNote) supersedesNote = `${slot.number}@v${slot.version}`
     slot.version = entry.version
     slot.title = entry.title
-    slot.lines = renderBlockLines(entry, headHash, supersedesNote)
-    // 同号旧版本段（< 新版本）就地清除——同文件内同号只留一个段
+    slot.lines = renderBlockLines(entry, headHash, supersedesNote, change || undefined)
+    // 同变更同号旧版本段（< 新版本）就地清除——同文件内同变更同号只留一个段
     for (let i = sections.length - 1; i >= 0; i--) {
-      if (sections[i].number === entry.number && sections[i] !== slot) sections.splice(i, 1)
+      if (sections[i].number === entry.number && (sections[i].change || null) === change && sections[i] !== slot) sections.splice(i, 1)
     }
     action = same ? 'update' : 'supersede'
   }
@@ -412,6 +427,9 @@ function syncIndexRoutingLines(knowledgeRoot) {
  *   缺否决理由/复潮条件被拦下（该条目未写盘，其余条目照常提炼）。
  */
 export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleIndex = null) {
+  // 变更名限定（坑 distill-cross-change-supersede）：条目幂等键 = 号+变更。changeDir 末段
+  // 即变更名（changes/<name> 与 archive 后的 changes/archive/<name> 同为 <name>）。
+  const changeName = basename(changeDir)
   const parsed = parseDecisions(changeDir)
   if (parsed.missing) {
     return { written: [], skipped: `decisions.md 不存在（${join(changeDir, 'decisions.md')}），零输出`, needsWait: null }
@@ -450,7 +468,7 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
   const taken = new Set()
   for (const e of distillable) {
     const keep = highestByNumber.get(e.number)
-    if (keep && !taken.has(e.number)) { taken.add(e.number); batch.push(keep) }
+    if (keep && !taken.has(e.number)) { taken.add(e.number); keep.change = changeName; batch.push(keep) }
   }
 
   const decisionsDir = join(knowledgeRoot, 'decisions')
@@ -489,7 +507,8 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
     }
   }
 
-  // 跨文件清理：同号 ≤ 新版本的旧段散落其他域文件时移除（同号全局只留最高版本/目标文件）
+  // 跨文件清理：同变更同号 ≤ 新版本的旧段散落其他域文件时移除（同变更同号全局只留最高
+  // 版本/目标文件）；他者变更的同号段不参与（共存，坑 distill-cross-change-supersede）
   let onDisk = []
   try { onDisk = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, '')) } catch { /* 刚创建，走 store */ }
   const allDomains = [...new Set([...onDisk, ...store.keys()])]
@@ -498,7 +517,7 @@ export function distillIntoKnowledge(changeDir, knowledgeRoot, headHash, moduleI
     for (const d of allDomains) {
       if (targets.has(d)) continue
       const st = loadDomain(d)
-      const removed = st.sections.filter(s => s.number === entry.number && s.version <= entry.version)
+      const removed = st.sections.filter(s => s.number === entry.number && s.version <= entry.version && (s.change || null) === (entry.change || null))
       if (removed.length === 0) continue
       st.sections = st.sections.filter(s => !removed.includes(s))
       st.dirty = true

package/src/docs-check.js

@@ -630,10 +630,20 @@ function extractKnownFailureKeys(yamlText) {
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }
-  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?)+)/m)
+  // 坑 verify-known-failures-comment-line-truncation 同款（与 verify-postcheck.extractKnownFailures
+  // 口径互指对齐）：块内注释行/空行打断连续列表项捕获链 → 注释后的键静默丢失。块定义放行
+  // 注释行与空行；提取侧只认 - 项行；行尾注释须 # 前有空白（裸 # 不截）；引号值原样保留。
+  const block = yaml.match(/^known_failures:\s*\n((?:[ \t]+-[ \t].+\n?|[ \t]*#[^\n]*\n?|[ \t]*\n)+)/m)
   if (block) {
     return (block[1].match(/^[ \t]+-[ \t]+(.+)/gm) || [])
-      .map(s => s.replace(/^[ \t]+-[ \t]+/, '').trim().replace(/^['"]|['"]$/g, '').replace(/#.*$/, '').trim())
+      .map(s => {
+        const item = s.replace(/^[ \t]+-[ \t]+/, '').trim()
+        const full = item.match(/^(['"])(.*)\1$/)
+        if (full) return full[2]
+        const stripped = item.replace(/[ \t]+#.*$/, '').trim()
+        const q2 = stripped.match(/^(['"])(.*)\1$/)
+        return q2 ? q2[2] : stripped
+      })
       .filter(Boolean)
   }
   return []

package/src/facade-hint.js

@@ -0,0 +1,170 @@
+/**
+ * facade-hint.js — plan 门「透传必经文件」候选探测（advisory）。
+ *
+ * 坑 plan-facade-files-manual-backfill（2026-08-28 用户实证 ×2）：facade 文件（如
+ * daemon/service.py——新端点/新模块必须在它里面挂载/转发才对外生效）不进 design §6 /
+ * TaskCard allowed_paths，执行期子代理按现实改它 → apply Gate1 拦截 → 人工回补
+ * allowed_paths 两轮。本模块在 plan 完成时做静态引用扫描，把候选透传/聚合文件提前
+ * 亮给 agent（warning 不阻断）：判定是语义，agent 拍板补不补。
+ *
+ * 两个信号（语言覆盖 py/js/ts/mjs/cjs/jsx/tsx/java 的 import/require 静态文本匹配）：
+ *   - direct：仓内文件 import 了 allowed_paths 里的模块（改被 facade 引用的模块，
+ *     facade 常需同步改——转发签名/挂载点）；
+ *   - aggregate：仓内文件 import 了该模块同目录下 ≥2 个模块（聚合器/注册表形态，
+ *     新增同目录模块几乎必然要在此登记——service.py 挂 router 即此形态）。
+ *
+ * 启发式 → 恒 advisory：候选只列不改，由 agent 判定补 allowed_paths / design §6，
+ * 或确认无关忽略。性能护栏：allowed 条目 > 100 或仓内源码文件 > 5000 时静默跳过。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join, dirname, basename, extname, resolve } from 'path'
+
+const SOURCE_EXTS = new Set(['.py', '.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.java'])
+const SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'dist', 'build', 'out', '.next', '__pycache__',
+  '.venv', 'venv', 'env', '.sillyspec', '.worktrees', '.claude', '.runtime',
+  'coverage', 'target', '.idea', '.vscode',
+])
+const MAX_ALLOWED_ENTRIES = 100
+const MAX_REPO_FILES = 5000
+const MAX_FILE_BYTES = 512 * 1024
+
+const toPosix = (p) => String(p).replace(/\\/g, '/')
+
+/** 递归收集仓内源码文件（posix 相对路径），带总量护栏。 */
+function walkSourceFiles(root, out = []) {
+  if (out.length > MAX_REPO_FILES) return out
+  let names
+  try { names = readdirSync(root) } catch { return out }
+  for (const name of names) {
+    if (SKIP_DIRS.has(name)) continue
+    const abs = join(root, name)
+    let st
+    try { st = statSync(abs) } catch { continue }
+    if (st.isDirectory()) walkSourceFiles(abs, out)
+    else if (st.isFile() && SOURCE_EXTS.has(extname(name).toLowerCase()) && st.size <= MAX_FILE_BYTES) {
+      out.push(toPosix(join(root, name)))
+      if (out.length > MAX_REPO_FILES) return out
+    }
+  }
+  return out
+}
+
+/** 从源码文本提取 import/require 说明符（py dotted + js/ts path-ish）。 */
+export function extractImportSpecifiers(text, ext) {
+  const specs = new Set()
+  if (ext === '.py') {
+    // from X import a, b → 记 pkg 本身 + 逐名拼 'X.a'/'X.b'（前者保 from X.y import sym 的
+    // 直接引用形态，后者保 service.py 聚合挂载形态：from daemon.routers import users, orders）
+    for (const m of text.matchAll(/\bfrom\s+([.\w]+)\s+import\s+([^\n#]+)/g)) {
+      specs.add(m[1])
+      const names = m[2].split(',')
+        .map(s => s.trim().split(/\s+as\s+/i)[0].trim())
+        .filter(n => /^\w+$/.test(n))
+      for (const n of names) specs.add(`${m[1]}.${n}`)
+    }
+    for (const m of text.matchAll(/(?:^|\n)\s*import\s+([\w.]+)/g)) specs.add(m[1])
+  } else if (ext === '.java') {
+    for (const m of text.matchAll(/\bimport\s+([\w.]+)\s*;/g)) specs.add(m[1])
+  } else {
+    for (const m of text.matchAll(/(?:from\s+|require\(\s*|import\(\s*)['"]([^'"]+)['"]/g)) specs.add(m[1])
+  }
+  return [...specs]
+}
+
+/** 说明符是否指向模块名 mod（`m` / `pkg.m` / `./m` / `../d/m` 等尾部命中形态）。 */
+export function specRefsModule(spec, mod) {
+  if (!spec || !mod) return false
+  if (spec === mod) return true
+  return spec.endsWith('.' + mod) || spec.endsWith('/' + mod)
+}
+
+/**
+ * 探测 allowed_paths 之外的 facade/聚合候选文件。
+ *
+ * @param {{ cwd: string, allowedPaths: string[] }} opts
+ * @returns {{ skipped: boolean, reason: string|null, candidates: Array<{file: string, via: string[]}> }}
+ */
+export function findFacadeCandidates({ cwd, allowedPaths }) {
+  const root = cwd || process.cwd()
+  const allowed = (allowedPaths || []).map(toPosix).filter(p => !p.includes('*'))
+  if (allowed.length === 0) return { skipped: true, reason: 'no-allowed-paths', candidates: [] }
+  if (allowed.length > MAX_ALLOWED_ENTRIES) return { skipped: true, reason: 'allowed-too-many', candidates: [] }
+
+  const files = walkSourceFiles(root)
+  if (files.length > MAX_REPO_FILES) return { skipped: true, reason: 'repo-too-large', candidates: [] }
+
+  const allowedSet = new Set(allowed)
+  const isAllowed = (abs) => allowed.some(a => abs === a || abs.endsWith('/' + a) || a.endsWith('/' + abs) || abs.replace(/\.[^.]+$/, '') === a.replace(/\.[^.]+$/, ''))
+
+  // 目录 → 该目录下模块名索引（聚合信号用：R import 同目录 ≥2 模块 = 聚合器）
+  const dirModules = new Map()
+  for (const f of files) {
+    const d = dirname(f)
+    if (!dirModules.has(d)) dirModules.set(d, new Set())
+    dirModules.get(d).add(basename(f, extname(f)))
+  }
+
+  // 预读一遍源码 import（file → specs），两信号共用
+  const fileSpecs = []
+  for (const f of files) {
+    if (isAllowed(f)) continue
+    let text
+    try { text = readFileSync(f, 'utf8') } catch { continue }
+    fileSpecs.push({ file: f, specs: extractImportSpecifiers(text, extname(f).toLowerCase()) })
+  }
+
+  // 逐 allowed 文件探测 direct + aggregate 命中
+  const byFile = new Map()
+  for (const p of allowed) {
+    const mod = basename(p, extname(p))
+    // allowed 是相对仓根路径，目录索引键是绝对路径（walk 产物）——resolve 对齐再查
+    const dirKey = toPosix(resolve(root, dirname(p)))
+    const dirLabel = toPosix(dirname(p))
+    const dirModSet = dirModules.get(dirKey) || new Set()
+    for (const { file, specs } of fileSpecs) {
+      const via = []
+      if (specs.some(s => specRefsModule(s, mod))) via.push(`direct import of ${mod}`)
+      // aggregate：R 引用 mod 同目录 ≥2 个不同仓内模块（mod 自身可不在——新增模块形态）
+      const hitMods = new Set()
+      for (const s of specs) {
+        for (const b of dirModSet) {
+          if (specRefsModule(s, b)) { hitMods.add(b); break }
+        }
+      }
+      if (hitMods.size >= 2) via.push(`aggregates ≥2 modules of ${dirLabel === '.' ? './' : dirLabel + '/'}`)
+      if (via.length === 0) continue
+      const existing = byFile.get(file) || []
+      for (const v of via) if (!existing.includes(v)) existing.push(v)
+      byFile.set(file, existing)
+    }
+  }
+  const candidates = [...byFile.entries()]
+    .map(([file, via]) => ({ file: toPosix(file), via }))
+    .sort((a, b) => a.file.localeCompare(b.file))
+  return { skipped: false, reason: null, candidates }
+}
+
+/**
+ * plan 门消费入口：探测 + 打印（advisory，不阻断）。allowed 集与 apply Gate1 同源
+ * （resolveApplyAllowSet 的主仓切片），确保「预检亮出的候选」与「执行期会拦的门」
+ * 用同一份清单口径。
+ */
+export function warnFacadeCandidateFiles({ cwd, changeName, allowSet }) {
+  try {
+    const r = findFacadeCandidates({ cwd, allowedPaths: [...(allowSet || [])] })
+    if (r.skipped || r.candidates.length === 0) return r
+    console.warn(`\n⚠️  plan 预检：${r.candidates.length} 个 allowed_paths 外的「透传/聚合」候选文件（advisory，不阻断）：`)
+    for (const c of r.candidates.slice(0, 10)) {
+      console.warn(`   - ${c.file}（${[...new Set(c.via)].join('; ')}）`)
+    }
+    if (r.candidates.length > 10) console.warn(`   …还有 ${r.candidates.length - 10} 个`)
+    console.warn('   若属「透传必经文件」（facade 转发/路由挂载/注册登记——改 allowed 模块必须同步改它才生效）：')
+    console.warn('   现在补进对应 TaskCard allowed_paths 或 design §6 清单，避免执行期 apply Gate1 拦截后手工回补；')
+    console.warn('   确认无关则忽略。执行期有据越界另有出口（review.json 声明 changedFiles，apply 有审计放行）。')
+    return r
+  } catch (e) {
+    console.warn(`⚠️  facade 候选探测失败（advisory 跳过）: ${e.message}`)
+    return { skipped: true, reason: 'error', candidates: [] }
+  }
+}