sillyspec 3.27.12 → 3.28.2

package/src/agent-session-log.js

@@ -18,7 +18,11 @@
  *   - codex：无可靠 env 标记，按 mtime 活跃窗口扫 <home>/.codex/sessions/YYYY/MM/DD/
  *       rollout-*.jsonl，读首行 session_meta.cwd 精确匹配 CLI cwd（并带出 originator，
  *       如 sillyhub-daemon，供平台关联派发来源）
- *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl
+ *   - zcode：env ZCODE_* 门控；<home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含
+ *       subagent 会话，文件名带 sess_subagent_agent_ 前缀）。rollout 目录全局共享（所有
+ *       ZCode 窗口/项目混居），读首块系统提示词工作目录标记与 cwd 精确匹配——主会话
+ *       `Primary working directory:` / subagent `<env>` 块 `Working directory:` 两形态均
+ *       实证；标记读不出 fail-closed 不登（错登比漏登危害大，SILLYSPEC_AGENT_LOG 兜底）
  *   - pi：目录名即 cwd 编码（--<路径非字母数字替'-'>--），无需 env 门控；
  *       <home>/.pi/agent/sessions/<safePath>/session.jsonl
  *   - deepseek-dsh（@deepseek-ai/dsh）：同 pi 构但 ':' 删除；
@@ -121,6 +125,51 @@ function readFirstLineJson(filePath, maxBytes = 16384) {
   }
 }
 
+// zcode model-io 无结构化 cwd 字段，归属数据源 = 首行首个请求系统提示词的环境段工作目录标记。
+// 两形态均本机实证：主会话 `Primary working directory: <path>\n- Is a git repository: yes`；
+// subagent 会话 `<env>\nWorking directory: <path>\nIs directory a git repository`。
+const ZCODE_WORKDIR_RE = /[Ww]orking directory: /;
+
+/**
+ * 从 zcode model-io 文件首块字节提取会话工作目录（cwd 归属判定的数据源）。
+ *
+ * 文件是 JSONL：首行 = 首个模型请求（含完整系统提示词），路径以 JSON 字符串内嵌形态出现
+ * ——分隔符双写（`\\`）、行尾是字面 `\n` 两字符。因此取值不能裸 indexOf 截 `\n`：Windows
+ * 路径普遍含 `\n` 字面序列（`\node_modules`、`\notifications`…），须按转义逐字符扫描，
+ * 直到未转义的换行转义（提示词行边界）为止。只读首块不整行 JSON.parse（首行可达 MB 级）。
+ * @returns {string|null} 未命中标记/文件不可读/值为空返回 null（调用方 fail-closed 丢弃）
+ */
+function extractZcodeWorkdir(filePath, maxBytes = 64 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(filePath, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const n = readSync(fd, buf, 0, maxBytes, 0);
+    const text = buf.subarray(0, n).toString('utf8');
+    const m = ZCODE_WORKDIR_RE.exec(text);
+    if (!m) return null;
+    const s = text.slice(m.index + m[0].length);
+    let out = '';
+    for (let j = 0; j < s.length;) {
+      const c = s[j];
+      if (c !== '\\') { out += c; j += 1; continue; }
+      const e = s[j + 1];
+      if (e === undefined || e === 'n') break; // 行尾换行转义 → 值结束
+      if (e === 'u' && /^[0-9a-fA-F]{4}$/.test(s.slice(j + 2, j + 6))) {
+        out += String.fromCharCode(parseInt(s.slice(j + 2, j + 6), 16));
+        j += 6;
+      } else if (e === 'r') { out += '\r'; j += 2; }
+      else if (e === 't') { out += '\t'; j += 2; }
+      else { out += e === '/' ? '/' : e; j += 2; } // \\ \" \/ 等：取转义次字符
+    }
+    return out || null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) { try { closeSync(fd) } catch { /* best effort */ } }
+  }
+}
+
 // 活跃文件收集：dir 内 suffix 结尾文件，mtime 在窗口内，mtime 新→旧
 function listActiveFiles(dir, { now, windowMs, limit }) {
   let names;
@@ -233,21 +282,39 @@ function detectCodex(ctx) {
 /**
  * ZCode：env ZCODE_* 门控（本机实证子进程可见 ZCODE_APP_VERSION/ZCODE_ENV 等）；
  * <home>/.zcode/cli/rollout/model-io-sess_<id>.jsonl（含 subagent 会话，文件名带
- * sess_subagent_agent_ 前缀），完整模型 I/O。无 cwd 字段 → env 门控即归属依据。
+ * sess_subagent_agent_ 前缀），完整模型 I/O。
+ *
+ * cwd 归属：rollout 目录全局共享（所有 ZCode 窗口/项目混居），env 门控只证明「CLI 正被
+ * 某个 ZCode 实例驱动」，证明不了「该文件属于本项目」——多窗口并行时另一项目的活跃会话
+ * 会被整体误登（2026-08-31 实证：sillyspec run 把 multi-agent-platform 会话上报为本地
+ * agent 日志）。修法对齐 codex 的 session_meta.cwd 精确匹配：读首块工作目录标记
+ * （extractZcodeWorkdir）与 cwdCandidates 等值比较；标记读不出 fail-closed 丢弃
+ * （错登比漏登危害大——平台把该文件当本会话权威日志解析展示；env 覆盖是兜底通道）。
  */
 function detectZcode(ctx) {
   const { cwdCandidates, env, homeDir, now, windowMs } = ctx;
   const inZcode = Boolean(env.ZCODE_APP_VERSION || env.ZCODE_ENV || env.ZCODE_RUNTIME_ENV);
   if (!inZcode) return [];
   const rolloutDir = join(homeDir, '.zcode', 'cli', 'rollout');
-  const cwdPosix = toPosix(cwdCandidates[0] || '');
-  return listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS }).map(f => ({
-    harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-env-marker',
-    log_path: toPosix(f.full), agent_cwd: cwdPosix,
-    session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
-    originator: null,
-    mtime_ms: f.mtimeMs,
-  }));
+  // 预筛多扫一倍再按 cwd 过滤：窗口内其他项目的活跃会话不应在过滤前挤占 MAX_PER_HARNESS 名额
+  const candidates = listActiveFiles(rolloutDir, { now, windowMs, limit: MAX_PER_HARNESS * 2 });
+  const entries = [];
+  for (const f of candidates) {
+    const workdir = extractZcodeWorkdir(f.full);
+    if (!workdir || !cwdCandidates.some(c => c && cwdsMatch(c, workdir))) {
+      debugLog(`zcode rollout cwd 不匹配/无标记，跳过: ${f.name} workdir=${workdir || '(none)'}`);
+      continue;
+    }
+    entries.push({
+      harness: 'zcode', format: 'zcode-model-io-jsonl', detected_via: 'zcode-workdir-marker',
+      log_path: toPosix(f.full), agent_cwd: toPosix(workdir),
+      session_id: f.name.replace(/^model-io-sess_/, '').replace(/\.jsonl$/, ''),
+      originator: null,
+      mtime_ms: f.mtimeMs,
+    });
+    if (entries.length >= MAX_PER_HARNESS) break;
+  }
+  return entries;
 }
 
 /**

package/src/archive-delta.js

@@ -0,0 +1,419 @@
+/**
+ * archive-delta — 归档变更 delta 聚合器（Before/Delta/After 三段式 delta.md 纯函数）
+ * （change: 2026-09-07-ir-stage-p3d，task-01，D-001@v1/D-002@v1/D-003@v1）
+ *
+ * 职责（设计文档「总体方案」的五源采集 fail-soft + 三段式渲染，CLI/archive 接线在 task-02）：
+ *   1. collectDeltaSources({ changeDir, specRoot, project, runtimeRoot, cwd })：五源采集——
+ *      ①reconcile：runtimeRoot/verify-runs/<ts>/reconcile-result.json 按 ts 倒序、change 字段
+ *      过滤后取最新（R-01 跨变更串台防护：不同变更的 run 混存于同一 verify-runs/）；
+ *      全无命中 → runtimeRoot/apply-pathspec-<change>.txt 逐行交付清单兜底（D-003，reconcile=null）。
+ *      ②verifyFacts：changeDir/verify-facts.json（JSON.parse fail-soft → null）。
+ *      ③moduleMap：复用 design-facts loadModuleMap；归属推导复用 deriveActualModules（P3d 导出）。
+ *      ④decisions：changeDir/decisions.md 文本 → parseDecisionDomains（null-safe，文件缺 → null）。
+ *      ⑤endpointBaseline + currentEndpoints（change: 2026-09-07-endpoint-baseline，task-03）：
+ *      基线 runtimeRoot/endpoint-baselines/<change>.json（readJsonSafe fail-soft → null）；
+ *      现算 scanBackendEndpoints(scanRoot)——capture 同口径但不落盘（scanRoot=cwd 显式传入，
+ *      缺省 dirname(specRoot)：本地模式 specRoot=<repoRoot>/.sillyspec → 即主仓根），异常 → null。
+ *   2. buildDeltaReport(...)：三段式 md（D-002）——Before（受影响模块 map 注册摘要 + 声明域并集）/
+ *      Delta（交付文件×模块归属表 + missing/undeclared 差集附注 + 决策清单 + 探针 metrics 摘要）/
+ *      After（module-impact.md「更新结果」表引用 + scan 刷新建议 + 端点基线提示节）。
+ *      缺源逐段降级注记（「（无 X：原因）」），不因缺源失败（兼容策略：存量变更仍生成）。
+ *
+ * 端点基线提示节（2026-09-07-endpoint-baseline Wave2）：门控沿用 probe5 backendEndpoints>0
+ * （Gap-4：无端点变更不收噪音注记，条件不动防断言面扩大），节标题沿用「### 端点基线提示」；
+ * 节内三态——基线+现算可得 → diffEndpointSets 增删表（added/removed 各自格行，changed 不配对
+ * 天然呈独立行；空 → 「无增删」一行）；基线缺失 → 「无基线（变更未拍 baseline）」降级注记
+ * （替代 P3d 旧「独立立项」提示行）；基线在但现算不可得 → 现算失败降级注记。
+ *
+ * 依赖方向（单向防环）：archive-delta → design-facts / modules / endpoint-baseline /
+ * endpoint-extractor，被依赖者均不反向 import 本模块。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { parseDecisionDomains, loadModuleMap, deriveActualModules } from './design-facts.js'
+import { parseModuleMapSimple } from './modules.js'
+import { scanBackendEndpoints } from './endpoint-extractor.js'
+import { diffEndpointSets } from './endpoint-baseline.js'
+
+// ---------------------------------------------------------------------------
+// 小工具（全部 fail-soft：读不到/解析失败 → null / []，不抛出）
+// ---------------------------------------------------------------------------
+
+/** 读 JSON 文件 → 对象；不存在/解析失败 → null */
+function readJsonSafe(p) {
+  if (!p || !existsSync(p)) return null
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null }
+}
+
+/** 读文本文件 → 字符串；不存在/读失败 → null */
+function readTextSafe(p) {
+  if (!p || !existsSync(p)) return null
+  try { return readFileSync(p, 'utf8') } catch { return null }
+}
+
+/** verify-runs/ 下 ts 形目录名（YYYYMMDDHHMMSS 纯数字）倒序列表 */
+function listRunTsDescending(runsDir) {
+  try {
+    return readdirSync(runsDir).filter(n => /^\d+$/.test(n)).sort().reverse()
+  } catch { return [] }
+}
+
+/**
+ * 单文件 × prefixPairs 前缀匹配 → 全部命中模块 id（design-facts deriveActualModules 同款
+ * 语义：全等或目录前缀——但取全部命中而非首命中即断，供归属表展示一文件多模块的真实形态）。
+ * @returns {string[]} 命中模块 id（prefixPairs 顺序去重）
+ */
+function matchFileModules(file, prefixPairs) {
+  const t = String(file || '').replace(/\\/g, '/').replace(/\/+$/, '')
+  const ids = []
+  if (!t) return ids
+  for (const { id, path: p } of prefixPairs) {
+    if ((t === p || t.startsWith(p + '/')) && !ids.includes(id)) ids.push(id)
+  }
+  return ids
+}
+
+/** 读 _module-map.yaml → Map<id, status>（Before 注册摘要的 status 列；loadModuleMap 只回
+ *  ids/prefixPairs 不含标量字段，此处复用 modules.js canonical 解析再读一遍——只读不改） */
+function loadModuleStatuses(specRoot, project) {
+  if (!specRoot || !project) return null
+  const text = readTextSafe(join(specRoot, 'docs', project, 'modules', '_module-map.yaml'))
+  if (text === null) return null
+  let parsed = {}
+  try { parsed = parseModuleMapSimple(text) || {} } catch { return null }
+  const st = new Map()
+  for (const [id, m] of Object.entries(parsed)) st.set(id, (m && m.status) || '未标注')
+  return st
+}
+
+/** 提取 module-impact.md「## 更新结果」小节正文（不含标题行本身，到下一 `## ` 标题或文末；
+ *  引用正文嵌入 After 段 H3 小节下，原 H2 标题混入会破坏标题层级）；无文件/无小节 → null */
+function extractUpdateResultSection(mdPath) {
+  const text = readTextSafe(mdPath)
+  if (text === null) return null
+  const lines = text.replace(/\r\n/g, '\n').split('\n')
+  const start = lines.findIndex(l => /^##\s+更新结果/.test(l))
+  if (start < 0) return null
+  const out = []
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break
+    out.push(lines[i])
+  }
+  const body = out.join('\n').trim()
+  return body || null
+}
+
+/** verifyFacts 探针 metrics 一行渲染：`key=value` 以「 / 」连接；probe5 形态随演进（P3b
+ *  fail-soft 原则）——metrics 缺失/空时整行降级注记而非报错 */
+function renderProbeLine(name, probe) {
+  const metrics = (probe && probe.metrics) || {}
+  const kv = Object.entries(metrics).map(([k, v]) => `${k}=${String(v)}`)
+  return kv.length > 0 ? `- ${name}：${kv.join(' / ')}` : `- ${name}：（无 metrics）`
+}
+
+const probe5BackendEndpoints = (verifyFacts) => {
+  const m = (verifyFacts && verifyFacts.probes && verifyFacts.probes.probe5
+    && verifyFacts.probes.probe5.metrics) || {}
+  return typeof m.backendEndpoints === 'number' ? m.backendEndpoints : null
+}
+
+// ---------------------------------------------------------------------------
+// 五源采集（Gap-2 兜底：deliverables 仅在 reconcile 全无命中时填充；
+// ⑤ endpointBaseline/currentEndpoints 为 2026-09-07-endpoint-baseline task-03 第五源）
+// ---------------------------------------------------------------------------
+
+/**
+ * 纯函数：聚合变更 delta 的五源数据（fail-soft，任一/全部缺源不抛出）。
+ * @param {{ changeDir?: string, specRoot?: string, project?: string, runtimeRoot?: string, cwd?: string }} opts
+ *   changeDir=变更目录（basename 即 changeName，active changes/ 或 archive/ 下均可）；
+ *   specRoot=规范根（.sillyspec）；project=子项目名；runtimeRoot=运行时根（.sillyspec/.runtime）；
+ *   cwd=⑤现算扫描根（缺省 dirname(specRoot)——本地模式即主仓根，capture 同口径锚定）
+ * @returns {{ reconcile: object|null, verifyFacts: object|null, moduleMap: object|null,
+ *             decisions: Array<{id, domains}>|null, deliverables: string[],
+ *             endpointBaseline: object|null, currentEndpoints: Array<{method,path,source,line}>|null }}
+ *   reconcile=按 change 过滤取最新的对账产物；verifyFacts=探针底稿；moduleMap=loadModuleMap
+ *   返回形态；decisions=当前版本 D 条目模块域（decisions.md 缺 → null）；deliverables=
+ *   reconcile 全无命中时的 apply-pathspec 兜底清单（否则 []）；endpointBaseline=基线文件
+ *   payload（缺/损坏 → null）；currentEndpoints=scanBackendEndpoints 现算端点集（不落盘，
+ *   扫描异常/无扫描根 → null）
+ */
+export function collectDeltaSources({ changeDir, specRoot, project, runtimeRoot, cwd } = {}) {
+  const change = changeDir ? basename(changeDir) : ''
+
+  // ① reconcile（R-01：先按 change 字段过滤再取最新，跨变更 run 不串台）
+  let reconcile = null
+  if (runtimeRoot && change) {
+    for (const ts of listRunTsDescending(join(runtimeRoot, 'verify-runs'))) {
+      const data = readJsonSafe(join(runtimeRoot, 'verify-runs', ts, 'reconcile-result.json'))
+      if (data && data.change === change) { reconcile = data; break }
+    }
+  }
+
+  // 兜底（Gap-2/D-003）：全无 reconcile → apply-pathspec-<change>.txt 逐行路径作交付清单
+  let deliverables = []
+  if (!reconcile && runtimeRoot && change) {
+    const text = readTextSafe(join(runtimeRoot, `apply-pathspec-${change}.txt`))
+    if (text !== null) {
+      deliverables = text.split(/\r?\n/).map(s => s.trim()).filter(Boolean)
+    }
+  }
+
+  // ② verifyFacts（JSON.parse fail-soft null）
+  const verifyFacts = changeDir
+    ? readJsonSafe(join(changeDir, 'verify-facts.json'))
+    : null
+
+  // ③ moduleMap（design-facts 单一真相源）
+  const moduleMap = loadModuleMap(specRoot, project)
+
+  // ④ decisions（null-safe：文件缺 → null；存在但无条目 → []）
+  let decisions = null
+  if (changeDir) {
+    const text = readTextSafe(join(changeDir, 'decisions.md'))
+    if (text !== null) decisions = parseDecisionDomains(text)
+  }
+
+  // ⑤ endpointBaseline（2026-09-07-endpoint-baseline task-03）：基线 JSON fail-soft → null
+  const endpointBaseline = (runtimeRoot && change)
+    ? readJsonSafe(join(runtimeRoot, 'endpoint-baselines', `${change}.json`))
+    : null
+
+  // ⑤ currentEndpoints：归档时现算（capture 同口径 scanBackendEndpoints，不落盘）。
+  // 扫描根三择一：显式 cwd > dirname(specRoot)（本地模式 specRoot=<repoRoot>/.sillyspec →
+  // 主仓根）> 无（→ null）；扫描异常 fail-soft → null（报告端降级注记，不阻断）。
+  const scanRoot = cwd || (specRoot ? dirname(specRoot) : null)
+  let currentEndpoints = null
+  if (scanRoot) {
+    try { currentEndpoints = scanBackendEndpoints(scanRoot) } catch { currentEndpoints = null }
+  }
+
+  return { reconcile, verifyFacts, moduleMap, decisions, deliverables, endpointBaseline, currentEndpoints }
+}
+
+// ---------------------------------------------------------------------------
+// 三段式渲染（Before/Delta/After，缺源逐段降级注记）
+// ---------------------------------------------------------------------------
+
+/**
+ * 纯函数：生成 delta.md 全文（三段式，D-002；不落盘——写盘/幂等由 CLI task-02 负责）。
+ * @param {{ changeDir?: string, specRoot?: string, project?: string, runtimeRoot?: string, cwd?: string, now?: string }} opts
+ *   前五项同 collectDeltaSources（cwd=⑤现算扫描根，缺省 dirname(specRoot)）；now=生成时刻
+ *   ISO（缺省当前时刻，测试可注入）
+ * @returns {string} delta.md 全文（LF 行尾，单一尾换行）
+ */
+export function buildDeltaReport({ changeDir, specRoot, project, runtimeRoot, cwd, now } = {}) {
+  const change = changeDir ? basename(changeDir) : '<变更名>'
+  const {
+    reconcile, verifyFacts, moduleMap, decisions, deliverables,
+    endpointBaseline, currentEndpoints,
+  } = collectDeltaSources({ changeDir, specRoot, project, runtimeRoot, cwd })
+  const statuses = loadModuleStatuses(specRoot, project)
+
+  // 差集路径归一（missing={task,path,isNew?} / undeclared={path,suspectTask?|string}——
+  // 生产端 verify-postcheck.js :2087/:2088 钉死的形态；字符串形态按存量容忍）
+  const undeclaredPaths = (reconcile && Array.isArray(reconcile.undeclared))
+    ? reconcile.undeclared.map(u => (u && typeof u === 'object' ? u.path : u)).filter(Boolean)
+    : []
+  const affectedFiles = reconcile
+    ? [...(Array.isArray(reconcile.matched) ? reconcile.matched : []), ...undeclaredPaths]
+    : deliverables
+  const deliveredFiles = reconcile
+    ? (Array.isArray(reconcile.matched) ? reconcile.matched : [])
+    : deliverables
+
+  // 受影响模块集 + 未匹配文件（R-02：未命中任何模块 paths 的文件显式列出不猜）
+  const affectedModules = moduleMap ? [...deriveActualModules(affectedFiles, moduleMap.prefixPairs)] : null
+  const unmatchedFiles = moduleMap
+    ? affectedFiles.filter(f => matchFileModules(f, moduleMap.prefixPairs).length === 0)
+    : [...affectedFiles]
+
+  // 声明域并集（NEW: 前缀 → 「（新模块）」标记；decisions.md 的模块域可选字段）
+  const declaredDomains = []
+  if (Array.isArray(decisions)) {
+    for (const { domains } of decisions) {
+      for (const d of domains || []) if (!declaredDomains.includes(d)) declaredDomains.push(d)
+    }
+  }
+
+  const L = []
+
+  // ---- frontmatter（generated_at + 来源四项命中状态）----
+  L.push('---')
+  L.push(`generated_at: ${String(now || '').trim() || new Date().toISOString()}`)
+  L.push(`sources_reconcile: ${reconcile
+    ? `命中（ran_at=${reconcile.ran_at || '?'}，verify-runs 按 change 过滤取最新）`
+    : `未命中（apply-pathspec 兜底，${deliverables.length} 项）`}`)
+  L.push(`sources_verify_facts: ${verifyFacts ? '命中' : '缺失'}`)
+  L.push(`sources_module_map: ${moduleMap ? '命中' : '缺失'}`)
+  L.push(`sources_decisions: ${decisions === null ? '缺失' : '命中'}`)
+  L.push('---')
+  L.push('')
+  L.push(`# 变更 Delta — ${change}`)
+  L.push('')
+
+  // ---- Before（变更前状态）----
+  L.push('## Before（变更前状态）')
+  L.push('')
+  L.push('### 受影响模块（module-map 注册摘要）')
+  L.push('')
+  if (!moduleMap) {
+    L.push(`（无 module-map：docs/${project || '?'}/modules/_module-map.yaml 不存在或不可解析——模块归属推导跳过，交付文件全部按未匹配列出）`)
+    L.push('')
+  } else if (affectedModules.length === 0) {
+    L.push('（受影响模块集为空——交付/差集文件均未命中任何模块 paths）')
+    L.push('')
+  } else {
+    L.push('| 模块 | status | paths+core_files 条目数 |')
+    L.push('|---|---|---|')
+    for (const id of affectedModules) {
+      const status = (statuses && statuses.get(id)) || '—'
+      const count = moduleMap.prefixPairs.filter(p => p.id === id).length
+      L.push(`| ${id} | ${status} | ${count} |`)
+    }
+    L.push('')
+  }
+  if (unmatchedFiles.length > 0) {
+    L.push(`未匹配文件（不归属任何模块 paths，人工裁量）：${unmatchedFiles.join('、')}`)
+    L.push('')
+  }
+  L.push('### 声明域并集（decisions.md 模块域）')
+  L.push('')
+  if (decisions === null) {
+    L.push(`（无 decisions.md：${join(changeDir || '?', 'decisions.md')} 不存在——声明域缺位）`)
+  } else if (declaredDomains.length === 0) {
+    L.push(`（decisions.md 解析出 ${decisions.length} 条当前版本决策，均未填写模块域——声明域为空）`)
+  } else {
+    L.push(declaredDomains.map(d => (d.startsWith('NEW:') ? `${d}（新模块）` : d)).join('、'))
+  }
+  L.push('')
+
+  // ---- Delta（做了什么）----
+  L.push('## Delta（做了什么）')
+  L.push('')
+  L.push('### 交付文件 × 模块归属')
+  L.push('')
+  if (!reconcile && deliveredFiles.length === 0) {
+    L.push(`（无 reconcile 产物且无 apply-pathspec-${change}.txt——交付文件清单不可得，本节缺位）`)
+    L.push('')
+  } else {
+    if (!reconcile) {
+      L.push(`（无 reconcile 产物（变更先于 P3a 或 verify 未落盘），清单取 apply-pathspec——文件级，无 missing/undeclared 差集）`)
+      L.push('')
+    }
+    L.push('| 交付文件 | 模块归属 |')
+    L.push('|---|---|')
+    for (const f of deliveredFiles) {
+      const ids = moduleMap ? matchFileModules(f, moduleMap.prefixPairs) : []
+      const cell = !moduleMap ? '—（无 module-map）' : (ids.length > 0 ? ids.join('、') : '—（未匹配）')
+      L.push(`| ${f} | ${cell} |`)
+    }
+    L.push('')
+  }
+  if (reconcile) {
+    L.push(`- 对账基线：status=${reconcile.status || '?'} / form=${reconcile.form || '?'} / sources=${(Array.isArray(reconcile.sources) ? reconcile.sources : []).join('、') || '?'}`)
+    const missing = Array.isArray(reconcile.missing) ? reconcile.missing : []
+    if (missing.length > 0) {
+      L.push(`- missing（声明未落盘，${missing.length} 项）：${missing.map(m => (m && typeof m === 'object'
+        ? `${m.task}：${m.path}${m.isNew ? '（NEW: 声明，路径已剥前缀）' : ''}`
+        : String(m))).join('；')}`)
+    } else {
+      L.push('- missing（声明未落盘）：无')
+    }
+    if (undeclaredPaths.length > 0) {
+      const items = (Array.isArray(reconcile.undeclared) ? reconcile.undeclared : [])
+        .map(u => (u && typeof u === 'object' ? `${u.path}${u.suspectTask ? `（疑似归因 ${u.suspectTask}）` : ''}` : String(u)))
+      L.push(`- undeclared（落盘未声明，${undeclaredPaths.length} 项）：${items.join('；')}`)
+    } else {
+      L.push('- undeclared（落盘未声明）：无')
+    }
+    L.push('')
+  }
+  L.push('### 决策清单（id × 模块域）')
+  L.push('')
+  if (decisions === null) {
+    L.push(`（无 decisions.md：${join(changeDir || '?', 'decisions.md')} 不存在——决策清单缺位）`)
+    L.push('')
+  } else if (decisions.length === 0) {
+    L.push('（decisions.md 无当前版本 D 条目——决策清单为空）')
+    L.push('')
+  } else {
+    L.push('| 决策 | 模块域 |')
+    L.push('|---|---|')
+    for (const { id, domains } of decisions) {
+      L.push(`| ${id} | ${(domains || []).join('、') || '（未填写）'} |`)
+    }
+    L.push('')
+  }
+  L.push('### 探针 metrics 摘要（验证结论表的机器半边）')
+  L.push('')
+  if (!verifyFacts || !verifyFacts.probes) {
+    L.push(`（无 verify-facts.json：${join(changeDir || '?', 'verify-facts.json')} 不存在或不可解析——探针指标快照缺位，可跑 sillyspec verify-probes --change ${change} --init 补）`)
+  } else {
+    if (verifyFacts.generatedAt) L.push(`快照时刻：${verifyFacts.generatedAt}`)
+    const order = ['probe1', 'probe3', 'probe5', 'probe6']
+    const names = [...order, ...Object.keys(verifyFacts.probes).filter(n => !order.includes(n))]
+    for (const n of names) L.push(renderProbeLine(n, verifyFacts.probes[n]))
+  }
+  L.push('')
+
+  // ---- After（建议动作）----
+  L.push('## After（建议动作）')
+  L.push('')
+  L.push('### 模块卡同步状态（module-impact.md「更新结果」）')
+  L.push('')
+  const updateResult = changeDir ? extractUpdateResultSection(join(changeDir, 'module-impact.md')) : null
+  if (updateResult) {
+    L.push('（引自变更目录 module-impact.md，人工维护为准）')
+    L.push('')
+    L.push(updateResult)
+  } else if (changeDir && existsSync(join(changeDir, 'module-impact.md'))) {
+    L.push('（module-impact.md 存在但无「## 更新结果」小节——模块卡同步状态引用缺位）')
+  } else {
+    L.push(`（无 module-impact.md：${join(changeDir || '?', 'module-impact.md')} 不存在——模块卡同步状态引用缺位）`)
+  }
+  L.push('')
+  L.push('### scan 刷新建议')
+  L.push('')
+  if (affectedModules && affectedModules.length > 0) {
+    L.push(`- \`sillyspec scan facts\` 下次刷新重点关注：${affectedModules.join('、')}（共 ${affectedModules.length} 个模块）`)
+  } else if (!moduleMap) {
+    L.push(`- （无 module-map：docs/${project || '?'}/modules/_module-map.yaml 不存在——受影响模块无法推导，建议先跑 sillyspec modules 同步补索引）`)
+  } else {
+    L.push('- （受影响模块集为空——无重点刷新面）')
+  }
+  if (unmatchedFiles.length > 0) {
+    L.push(`- 未匹配文件补录提示：以下文件未命中任何模块 paths——建议补录 _module-map.yaml（新文件）或核对归属（人工裁量）：${unmatchedFiles.join('、')}`)
+  }
+  L.push('')
+  // 端点基线提示（2026-09-07-endpoint-baseline task-03）：门控沿用 probe5 backendEndpoints>0
+  // 不动（Gap-4：无端点变更不收噪音注记），节标题沿用防断言面扩大；节内三态（基线×现算 →
+  // diffEndpointSets 增删表 / 基线缺失 → 降级注记 / 现算不可得 → 降级注记）。
+  const backendEndpoints = probe5BackendEndpoints(verifyFacts)
+  if (backendEndpoints !== null && backendEndpoints > 0) {
+    L.push('### 端点基线提示')
+    L.push('')
+    const baselineEps = (endpointBaseline && Array.isArray(endpointBaseline.endpoints))
+      ? endpointBaseline.endpoints
+      : null
+    if (!baselineEps) {
+      L.push(`- 无基线（变更未拍 baseline）：${join(runtimeRoot || '?', 'endpoint-baselines', `${change}.json`)} 不存在或不可解析——端点增删不可比（backendEndpoints=${backendEndpoints}（>0））`)
+    } else {
+      const endpointDiff = diffEndpointSets(baselineEps, currentEndpoints)
+      if (!endpointDiff) {
+        L.push(`- 基线已拍（${baselineEps.length} 端点）但现算不可得（scanBackendEndpoints 扫描失败）——端点增删不可比`)
+      } else if (endpointDiff.added.length === 0 && endpointDiff.removed.length === 0) {
+        L.push(`- 端点增删：无增删（基线 ${baselineEps.length} 端点 × 现算 ${currentEndpoints.length} 端点，method+归一 path 全一致）`)
+      } else {
+        L.push(`- 端点 diff：基线 ${baselineEps.length} 端点 × 现算 ${currentEndpoints.length} 端点（method+归一 path 集合运算；changed 不配对，天然呈独立行）`)
+        L.push('')
+        L.push('| 增删 | method | path | source |')
+        L.push('|---|---|---|---|')
+        for (const e of endpointDiff.added) L.push(`| + 新增 | ${e.method} | ${e.path} | ${e.source} |`)
+        for (const e of endpointDiff.removed) L.push(`| - 删除 | ${e.method} | ${e.path} | ${e.source} |`)
+      }
+    }
+    L.push('')
+  }
+
+  return L.join('\n')
+}

package/src/config-schema.js

@@ -68,8 +68,8 @@ export const LOCAL_YAML_SCHEMA = {
       note: 'detect 核验 package.json(或对应构建文件) scripts 存在性后才写对应键；缺失则不写。agent 可改。',
       keys: [
         { path: 'commands.build', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '构建命令。', example: 'npm run build' },
-        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断。', example: 'npm test' },
-        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令。', example: 'npm run lint' },
+        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断；quick --done 触及 src/test 时同款实测（P0-2 门禁）。', example: 'npm test' },
+        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
       ],
     },

package/src/contract-matrix.js

@@ -15,6 +15,7 @@ import { splitOwnVsForeignDiffFiles } from './foreign-declared.js'
 import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
+  scanMountPrefixes,
   normalizePath,
   diffApiParity,
 } from './endpoint-extractor.js'
@@ -558,7 +559,16 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
     frontendCalls = scanFrontendApiCalls(frontendRoot)
   }
 
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, mergedProviderEndpoints)
+  // ── 挂载前缀收集（坑 endpoints-mount-prefix-gap，2026-08-31 用户实证）：endpoints 提取的是
+  // 「router 自身前缀 + 装饰器路径」，不含挂载点前缀（main.py 的 include_router(prefix=)/app.use
+  // 与 router 文件分离，静态扫描不做导入图关联）→ 前端全路径调用（/api/xxx）对不上欠前缀端点
+  // （/xxx）→ 17 个存量端点全量假 missing、人工逐条定性。对账时按前缀集合剥除前端调用前缀对齐。
+  const mountPrefixes = new Set()
+  for (const { root } of liveByRoot) {
+    try { for (const p of scanMountPrefixes(root)) mountPrefixes.add(p) } catch { /* 单根失败不拖垮整体 */ }
+  }
+
+  const { missingBackend, unusedBackend, prefixAlignedCount } = diffApiParity(frontendCalls, mergedProviderEndpoints, [...mountPrefixes])
   // unusedBackend 收窄到现算端点（存量 artifact 的过期端点不参与——它不在当前代码里，
   // 「前端未调用」可能是端点已被重构掉而非真泄漏）
   const narrowedUnused = unusedBackend.filter(u => {
@@ -575,6 +585,9 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
   if (narrowedUnused.length > 0) {
     summary += ` | ${narrowedUnused.length} backend endpoints unused by frontend`
   }
+  if (prefixAlignedCount > 0) {
+    summary += ` | ${prefixAlignedCount} calls matched after mount-prefix alignment (artifact paths exclude include_router/app.use prefixes)`
+  }
 
-  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, scanRoots: liveByRoot.map(r => r.root) }
+  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length, prefixAlignedCount, scanRoots: liveByRoot.map(r => r.root) }
 }