sillyspec 3.29.4 → 3.31.0

package/src/machine-draft.js

@@ -0,0 +1,128 @@
+/**
+ * machine-draft.js — MACHINE-DRAFT 指纹三件套泛化（R7 切片三 task-04 / D-004 / FR-08）。
+ *
+ * 从 verify-draft.js（verify 填槽制 v2 件二）抽出通用原语，供 flow 四件机器稿（flow-draft）
+ * 复用；verify-draft 改为消费方（导出签名与行为逐字不动，零回归硬门）。
+ *
+ * 三件套语义（护栏#2：守卫必须是验收侧的机制，永远不是生成侧的劝说）：
+ *   - wrapSection：机器预填段以 MACHINE-DRAFT begin/end 注释对包裹，begin 内嵌段内容
+ *     sha256（CRLF 归一）；amendCmd 按消费方参数化（verify-result 指向 verify-probes
+ *     --amend-draft，flow 稿指向 flow amend-draft——勿把 agent 引向错误命令）；
+ *   - verifyMarkers：三态拒收判定——标记缺失（被删/整份重写）/内容哈希失配（改写）/
+ *     手工重锚未审计（标记哈希与台账不一致）；
+ *   - reanchorText：按当前内容重锚哈希的纯文本变换（amend 留痕通道的机械半边；
+ *     台账审计与落盘归消费方）。
+ *
+ * 本模块纯函数（无 fs）——md 文本与台账对象由消费方读写；段 key 命名空间归消费方
+ * （verify-result 单文件段键 / flow 按文件名+段键组合）。
+ */
+import { createHash } from 'node:crypto'
+
+export const MARK_BEGIN_RE = /^<!--\s*MACHINE-DRAFT:([\w.-]+):([0-9a-f]{64}):begin.*-->\s*$/
+const MARK_END_RE = /^<!--\s*MACHINE-DRAFT:([\w.-]+):end.*-->\s*$/
+
+/**
+ * 任务勾选态归一（2026-09-25-thin-done-gate-calibration 坑1）：勾选是 flow start 横幅教的
+ * 预期写面（收口哨兵的证据面），不该参与「被改写」判定——哈希前把 `- [x] task-NN` 归一回
+ * `- [ ]`（draft 产出恒 [ ]，存量台账两侧归一后同哈希，兼容；真实改写任务文本/增删行仍失配）。
+ * 口径只认 task-NN 行，普通清单勾选行不归一（不扩大书写面）。
+ */
+const TASK_CHECK_STATE_RE = /^([-*] \[)[ xX]\](?= task-\d)/gm
+function normalizeTaskCheckboxState(s) {
+  return String(s).replace(TASK_CHECK_STATE_RE, '$1 ]')
+}
+
+/** 段内容哈希（CRLF 归一——跨平台写盘行尾漂移不炸指纹；task-NN 勾选态归一——见上）。 */
+export function bodyHash(s) {
+  return createHash('sha256').update(normalizeTaskCheckboxState(String(s).replace(/\r\n/g, '\n'))).digest('hex')
+}
+
+/**
+ * 包裹机器段（begin 标记 + body + end 标记 + 尾空行）。标记格式与既有 MARK_*_RE 逐字兼容。
+ * @returns {string} 四行块（含尾空行，消费方按原位替换）
+ */
+export function wrapSection({ key, body, amendCmd, guardNote = '整段改写会被 verify --done 拒收' }) {
+  return [
+    `<!-- MACHINE-DRAFT:${key}:${bodyHash(body)}:begin 机器预填段——${guardNote}；确要修改：${amendCmd} 留痕重锚 -->`,
+    body,
+    `<!-- MACHINE-DRAFT:${key}:end -->`,
+    '',
+  ].join('\n')
+}
+
+/**
+ * 解析 md 中全部标记段（CRLF 归一）。
+ * @returns {{key:string, markerHash:string, contentLines:string[]}[]}
+ */
+export function parseMarkerBlocks(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n')
+  const blocks = []
+  let current = null
+  for (const line of lines) {
+    const b = line.match(MARK_BEGIN_RE)
+    if (b) { current = { key: b[1], markerHash: b[2], contentLines: [] }; blocks.push(current); continue }
+    const e = line.match(MARK_END_RE)
+    if (e) { current = null; continue }
+    if (current) current.contentLines.push(line)
+  }
+  return blocks
+}
+
+/**
+ * 三态拒收判定（--done 验收侧承重件的纯函数半边）。
+ * @param {object} p
+ * @param {string} p.text md 全文
+ * @param {Object<string,{hash:string}>} p.sections 台账段哈希（sidecar.sections 形态）
+ * @param {string} p.amendCmd 修复指引命令文案（消费方参数化）
+ * @returns {string[]} violations（空=干净；文案含修复指引）
+ */
+export function verifyMarkers({ text, sections, amendCmd }) {
+  const blocks = parseMarkerBlocks(text)
+  const byKey = new Map(blocks.map((b) => [b.key, b]))
+  const violations = []
+  const fix = (key) => `还原机器段原文，或确要修改时跑 ${amendCmd} 留痕重锚（段键 ${key}）`
+  for (const [key, rec] of Object.entries(sections || {})) {
+    const b = byKey.get(key)
+    if (!b) {
+      violations.push(`机器段「${key}」的 MACHINE-DRAFT 标记缺失（被删除或整份重写）——${fix(key)}`)
+      continue
+    }
+    const actual = bodyHash(b.contentLines.join('\n'))
+    if (actual !== rec.hash) {
+      violations.push(`机器段「${key}」内容与指纹失配（被改写）——${fix(key)}`)
+    } else if (b.markerHash !== rec.hash) {
+      // 内容未动但标记哈希与台账不一致 = 标记被手工重锚而未经 amend 审计
+      violations.push(`机器段「${key}」标记指纹与 sidecar 台账不一致（未经 --amend-draft 的手工重锚）——${fix(key)}`)
+    }
+  }
+  return violations
+}
+
+/**
+ * 按当前内容重锚全部标记段（纯文本变换；不落盘不记台账——消费方持 mdPath/台账）。
+ * @returns {{text:string, keys:string[], contentByKey:Object<string,string>}}
+ */
+export function reanchorText({ text, amendCmd, guardNote = '整段改写会被 verify --done 拒收' }) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n')
+  const contentLinesByKey = new Map()
+  let current = null
+  for (const line of lines) {
+    const b = line.match(MARK_BEGIN_RE)
+    if (b) { current = b[1]; contentLinesByKey.set(current, []); continue }
+    const e = line.match(MARK_END_RE)
+    if (e) { current = null; continue }
+    if (current) contentLinesByKey.get(current).push(line)
+  }
+  const keys = [...contentLinesByKey.keys()]
+  const next = lines.map((line) => {
+    const b = line.match(MARK_BEGIN_RE)
+    if (!b) return line
+    const content = (contentLinesByKey.get(b[1]) || []).join('\n')
+    return `<!-- MACHINE-DRAFT:${b[1]}:${bodyHash(content)}:begin 机器预填段——${guardNote}；确要修改：${amendCmd} 留痕重锚 -->`
+  }).join('\n')
+  const contentByKey = {}
+  for (const k of keys) contentByKey[k] = (contentLinesByKey.get(k) || []).join('\n')
+  return { text: next, keys, contentByKey }
+}
+
+export default { wrapSection, parseMarkerBlocks, verifyMarkers, reanchorText, bodyHash, MARK_BEGIN_RE }

package/src/machine-interface.js

@@ -15,17 +15,17 @@
  * 仅依赖 Node 18+ 原生 API，零新增外部依赖。
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { ProgressManager, resolveSpecDir } from './progress.js';
 import { resolveRuntimeRoot } from './run/shared.js';
 import { runValidators, checkTransition, checkExecuteCodeEvidence } from './stage-contract.js';
 import { validateTaskReviews, resolveLatestExecuteRunId } from './task-review.js';
 import { runVerifyTestCheck } from './verify-postcheck.js';
+import { computeGateFingerprint, lookupGreenCache, storeGreenCache, greenCacheNotice } from './run/green-cache.js';
 import { checkCode } from './diagnostic-codes.js';
 
 // ============ 退出码常量（D-004@v1）============
-
 export const EXIT_OK = 0;          // 核验通过（可含 warnings）
 export const EXIT_BLOCKED = 1;     // 事实性阻断（JSON 含 errors）
 export const EXIT_UNKNOWN = 2;     // 无法核验（用法错/变更不存在/环境错/内部异常）
@@ -117,7 +117,31 @@ export function buildEnvelope({
  *   让两函数按 ctx 切跨仓 gitDir / per-repo cwd。null 时两函数按既有单仓行为零回归。
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
-export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null } = {}) {
+/**
+ * verify 门禁 check 的绿结果缓存包装（R8 对撞修复 2026-09-23，实现见 src/run/green-cache.js）。
+ * 同指纹（HEAD+代码脏面+local.yaml）近期真跑的绿结果复用：命中 → synth(hit) 合成等价结果
+ * （带 cached 披露字段，调用方进 warnings——「结果是真的、本次没跑」必须明示）；未命中 →
+ * 真跑，status==='passed' 时写缓存。fail-open：无根/指纹失败/缓存异常一律回退真跑（零回归）。
+ */
+function greenCachedCheck({ kind, greenRoot, cwd, specBase, changeName }, runReal, synth) {
+  if (!greenRoot) return runReal();
+  let fingerprint = null;
+  try { fingerprint = computeGateFingerprint({ cwd, specBase }); } catch { fingerprint = null; }
+  if (!fingerprint) return runReal();
+  const scope = `change:${changeName}`;
+  let hit = null;
+  try { hit = lookupGreenCache({ runtimeRoot: greenRoot, scope, kind, fingerprint }); } catch { hit = null; }
+  if (hit) return synth(hit);
+  const result = runReal();
+  try {
+    if (result && result.status === 'passed') {
+      storeGreenCache({ runtimeRoot: greenRoot, scope, kind, fingerprint, result: { status: 'passed', exitCode: result.exitCode ?? 0, mode: result.mode ?? null } });
+    }
+  } catch { /* best-effort 写缓存 */ }
+  return result;
+}
+
+export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null, full = false } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
   // A4：pm 用 specRoot（而非默认 resolveSpecDir(cwd)）——--spec-dir/平台模式下 specBase 是真实
   // specDir，默认解析会指向本地孤儿库，与下方 planContent/changeDir 的 specRoot 两套事实源混拼。
@@ -289,14 +313,21 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
 
     // ── d. verify 阶段追加 verify-test（CLI 实测 local.yaml commands.test）──
     if (stage === 'verify') {
-      const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
+      // 绿缓存根：与 runtimeRoot 解析同源（drift 锚主仓口径）；解析失败 null → 不缓存不命中
+      let greenRoot = null;
+      try { greenRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot); } catch { greenRoot = null; }
+      const vt = greenCachedCheck({ kind: 'test', greenRoot, cwd, specBase: specRoot, changeName },
+        () => runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx }),
+        (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, resultPath: null, mode: null, fallbackReason: null, exemptedCount: 0, cached: true, reason: greenCacheNotice(hit, 'verify-test') }));
       const vtWarnings = [];
+      if (vt.cached) vtWarnings.push(vt.reason);
       if (vt.status === 'skipped') {
         vtWarnings.push(`⚠️ verify-test SKIPPED — gate 未核验测试（${vt.reason || 'local.yaml 未配置 commands.test 或显式无测试'}）。本次 gate 结论不含测试客观核验，driver 不应据 exit 0 判定测试通过；integration-critical 变更应在 verify 阶段降级 FAIL`);
       }
       // known_failures 豁免披露：本次 PASS 含豁免，driver 应提示人工复核清单是否过宽
+      // （quick-E，2026-09-20 报告问题 E：提示原不带清单位置，复核要先翻一遍才找到——带路径）
       if (vt.exemptedCount > 0) {
-        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）`);
+        vtWarnings.push(`⚠️ verify-test PASS 含 ${vt.exemptedCount} 个 known_failures 豁免（${vt.reason || ''}）；driver 应提示人工复核豁免清单是否过宽（避免误豁免本变更引入的真实失败）——清单位置：${join(specRoot, 'local.yaml')} 的 known_failures 键`);
       }
       // 全量 fallback 明示：跑了全量 commands.test 但非变更范围子集，失败可能含未变更
       // 模块的预存错误——driver 不应据 exit 0 判定本次变更范围已客观测试（见 3.24 verify 坑1）。
@@ -311,6 +342,7 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
         warnings: vtWarnings,
         data: {
           status: vt.status,
+          cached: vt.cached === true,
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
@@ -318,6 +350,127 @@ export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, s
           fallbackReason: vt.fallbackReason ?? null,
         },
       });
+
+      // ── d2. verify-lint（parity 补齐，2026-09-21 R4-S-F 实证）──
+      // gate verify 原先只查 test 不查 lint，而 verify --done 的 lint 隔离快照门会拦——
+      // gate PASS / --done FAIL 两套口径并存，误导 agent 诊断 16 分钟（对撞会话 db 实证）。
+      // 本检查与 --done 同引擎（runVerifyLintCheck + triageLintOwnership 归属降档）；口径差异
+      // 永久明示：gate 在工作树直跑 lint，--done 在隔离快照（HEAD+归属文件 overlay）跑——
+      // 不一致时以 --done 为准。lint 未配置/不可跑 → informational，不阻断只读查询。
+      try {
+        const { runVerifyLintCheck, triageLintOwnership, resolveVerifyChangedFiles } = await import('./verify-postcheck.js');
+        const lc = greenCachedCheck({ kind: 'lint', greenRoot, cwd, specBase: specRoot, changeName },
+          () => runVerifyLintCheck({ cwd, specBase: specRoot }),
+          (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, failureFiles: [], cached: true, reason: greenCacheNotice(hit, 'verify-lint') }));
+        if (lc.status === 'skipped') {
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: true,
+            informational: true,
+            warnings: [`verify-lint SKIPPED — ${lc.reason || 'local.yaml 未配置 commands.lint'}；本次 gate 结论不含 lint 客观核验`],
+            data: { status: lc.status },
+          });
+        } else {
+          const lcWarnings = [
+            '口径说明：gate verify 的 lint 在工作树直跑；verify --done 的 lint 在隔离快照（HEAD+归属文件 overlay）跑——两口径不一致时以 --done 为准。',
+          ];
+          if (lc.cached) lcWarnings.push(lc.reason);
+          let ownership = null;
+          let lintOk = lc.status !== 'failed';
+          if (lc.status === 'failed') {
+            const changed = resolveVerifyChangedFiles(cwd, changeName, null, { specBase: specRoot }) || [];
+            ownership = triageLintOwnership({ failureFiles: lc.failureFiles || [], changeFiles: changed });
+            if (ownership.verdict === 'pre-existing') {
+              lintOk = true; // 存量债不拦只读查询（与 --done 的 advisory 降档同口径）
+              lcWarnings.push('lint 失败文件与本变更零交集（HEAD 存量债）→ 本 check 降档放行；--done 同口径 advisory，建议顺手清偿解锁全仓 lint 门。');
+            }
+          }
+          checks.push({
+            id: 'verify-lint',
+            code: checkCode('verify-lint'),
+            ok: lintOk,
+            errors: !lintOk ? [`lint 失败（工作树口径）: ${lc.reason || ''}`] : [],
+            warnings: lcWarnings,
+            data: {
+              status: lc.status,
+              cached: lc.cached === true,
+              exitCode: lc.exitCode,
+              durationMs: lc.durationMs,
+              ownership: ownership ? ownership.verdict : null,
+              overlap: ownership ? ownership.overlap : [],
+            },
+          });
+        }
+      } catch (e) {
+        checks.push({
+          id: 'verify-lint',
+          code: checkCode('verify-lint'),
+          ok: true,
+          informational: true,
+          warnings: [`verify-lint 检查装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+          data: { status: 'error' },
+        });
+      }
+    }
+
+    // ── e. --full 只读预检档（P1 / FR-01 / D-002@batch3，2026-09-21-r5-efficiency-batch3 task-03）──
+    // 覆盖 --done 独有的贵门（batch2 实证四类盲区：reconcile 两轮/stage review 缺失各吃一整 agent
+    // 回合）：①target_files reconcile 只读跑（reconcileTargetFiles 纯计算不落盘，--done 的写结果
+    // 文件在其调用方）；②stage review 在场探测（marker+review.json——缺则报预期路径，同 --done
+    // Stage Review Gate 口径，只报缺不生成）。全只读零副作用；未传 full 零行为变化。
+    if (full && (stage === 'verify' || stage === 'execute')) {
+      // e1. reconcile（verify --done 的 target_files 对账门）
+      if (stage === 'verify') {
+        try {
+          const { reconcileTargetFiles } = await import('./verify-postcheck.js');
+          const rec = reconcileTargetFiles({ cwd, specBase: specRoot, changeName });
+          const recOk = rec.status !== 'missing_declared';
+          checks.push({
+            id: 'full-target-files-reconcile',
+            code: checkCode('full-target-files-reconcile') || 'full_target_files_reconcile',
+            ok: recOk,
+            errors: !recOk
+              ? (rec.missing || []).map((m) => `task-${m.task || '?'}: ${m.path} 声明未做（②类计划落空）——补做交付或按声明修正通道改卡（与 review 结论一致）`)
+              : [],
+            warnings: (rec.undeclared || []).length > 0
+              ? [`${(rec.undeclared || []).length} 个未声明文件（warning 级，${(rec.undeclared || []).slice(0, 3).map((u) => u.path).join('、')}${(rec.undeclared || []).length > 3 ? ' 等' : ''}）——并行会话归因噪音或漏声明，verify 报告须裁决`]
+              : [],
+            data: { status: rec.status, matched: (rec.matched || []).length, missing: (rec.missing || []).length, undeclared: (rec.undeclared || []).length },
+          });
+        } catch (e) {
+          checks.push({
+            id: 'full-target-files-reconcile',
+            code: 'full_target_files_reconcile',
+            ok: true,
+            informational: true,
+            warnings: [`--full reconcile 检查装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+          });
+        }
+      }
+      // e2. stage review 在场探测（verify/execute --done 的 Stage Review Gate）
+      try {
+        const { getLatestStageReviewRunId } = await import('./stage-review.js');
+        const rrRoot = runtimeRoot || join(specRoot, '.runtime');
+        const runId = getLatestStageReviewRunId(rrRoot, stage, changeName);
+        checks.push({
+          id: 'full-stage-review',
+          code: checkCode('full-stage-review') || 'full_stage_review_missing',
+          ok: !!runId,
+          errors: !runId
+            ? [`缺 ${stage} 阶段的 stage review.json（tier=independent 要求独立审查产出）——--done 将被 Stage Review Gate 拦；可先 sillyspec register-stage-review --change ${changeName} --stage ${stage} 生成骨架再填（降级条款照 review.json reviewerNotes 首行留痕）`]
+            : [],
+          data: { runId: runId || null },
+        });
+      } catch (e) {
+        checks.push({
+          id: 'full-stage-review',
+          code: 'full_stage_review_missing',
+          ok: true,
+          informational: true,
+          warnings: [`--full stage review 探测装配失败（fail-open）: ${e && e.message ? e.message : e}`],
+        });
+      }
     }
 
     // ── 综合结论：所有非 informational check 均 ok ──
@@ -461,9 +614,14 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
 
       // ── b. verify-test：真实执行测试命令并取证 ──
       case 'verify-test': {
-        const vt = runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx });
+        let greenRoot = null;
+        try { greenRoot = resolveRuntimeRoot({ runtimeRoot, specDriftAnchor }, specRoot); } catch { greenRoot = null; }
+        const vt = greenCachedCheck({ kind: 'test', greenRoot, cwd, specBase: specRoot, changeName },
+          () => runVerifyTestCheck({ cwd, specBase: specRoot, changeName, ctx }),
+          (hit) => ({ status: 'passed', exitCode: 0, durationMs: 0, resultPath: null, mode: null, fallbackReason: null, exemptedCount: 0, cached: true, reason: greenCacheNotice(hit, 'verify-test') }));
         data = {
           status: vt.status,
+          cached: vt.cached === true,
           exitCode: vt.exitCode,
           durationMs: vt.durationMs,
           resultPath: vt.resultPath,
@@ -472,7 +630,9 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
         };
         ok = vt.status !== 'failed';
         errors = vt.status === 'failed' ? [`测试失败: ${vt.reason || ''}`] : [];
-        warnings = vt.status === 'skipped'
+        warnings = vt.cached
+          ? [vt.reason]
+          : vt.status === 'skipped'
           ? ['测试被跳过']
           : (vt.mode === 'full' && vt.fallbackReason)
             ? [`⚠️ verify-test 跑的是全量 commands.test（${vt.fallbackReason}）；失败可能含未变更模块的预存错误`]
@@ -667,3 +827,30 @@ export function runStatusOverview({ cwd, specBase } = {}) {
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ gate 失败明细稳定路径落盘（quick-D，2026-09-20 报告问题 D）============
+
+/**
+ * `sillyspec gate <stage> --change <name>` 的失败信封落盘（稳定路径，每次覆盖）。
+ * 背景：gate 失败明细只在 stdout——宿主把长命令转后台截断输出后 ❌ 段落实际取不回
+ * （2026-09-20 实证：agent 靠推断绕 3 轮）。runGate 本体保持只读契约（D-002@v1，不写
+ * sillyspec.db），落盘由本函数承担（CLI 层调用，fail-soft）——审计附件非状态。
+ * @param {{ specBase: string, stage: string, changeName: string, envelope: object }} opts
+ * @returns {string|null} 成功返回落盘路径；失败返回 null
+ */
+export function writeGateResultArtifact({ specBase, stage, changeName, envelope }) {
+  try {
+    const runsDir = join(specBase, '.runtime', 'verify-runs')
+    const resultPath = join(runsDir, `gate-${stage}-${changeName}.json`)
+    mkdirSync(runsDir, { recursive: true })
+    writeFileSync(resultPath, JSON.stringify({
+      written_at: new Date().toISOString(),
+      stage,
+      change: changeName,
+      envelope,
+    }, null, 2) + '\n')
+    return resultPath
+  } catch {
+    return null // fail-soft：落盘是审计附件，失败只缺附件不误门
+  }
+}

package/src/mcp-server.js

@@ -93,6 +93,7 @@ function runCli(cliArgs) {
       cwd: process.cwd(),
       env: process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
     })
     let out = ''
     let err = ''

package/src/module-impact.js

@@ -48,7 +48,15 @@ export function parseModuleMapPaths(yamlText) {
     }
     if (inPaths && currentModule) {
       const item = line.match(/^      - (.+)$/)
-      if (item) map.get(currentModule).push(item[1].trim().replace(/\\/g, '/'))
+      if (item) {
+        // 引号剥离（坑 map-quoted-path-deadmatch，2026-09-21 R4-L 实证）：docs/<p>/modules/
+        // _module-map.yaml 存在带引号条目（"frontend/src/app/page.tsx"）——只 trim 不剥引号时
+        // classifyFile 的 === / startsWith 恒失配，引号条目全是死路径（frontend map 790 条
+        // 几乎全带引号＝整图失效）。仅首尾成对引号才剥（路径内部引号不动）。
+        const raw = item[1].trim()
+        const unquoted = raw.replace(/^(['"])([\s\S]*)\1$/, '$2')
+        map.get(currentModule).push(unquoted.replace(/\\/g, '/'))
+      }
     }
   }
   return map
@@ -89,18 +97,33 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
   // 复用 generateModuleImpactSkeleton 的 map 发现 + 归类（diff 来源）
   const skel = generateModuleImpactSkeleton({ cwd, changeName, specDir })
   if (!skel) return { synced: [], unmatched: [], skipped: [], reason: '无 module-map 或无 diff 可归类' }
-  const modulesDir = findModulesDir(specBase)
-  if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
-  // 从骨架 markdown 反解归类结果（命中模块集合 + 未匹配清单）
-  const hitModules = [...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1])
-  const unmatched = [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
+  // 结构化归类直用（classified 含 project 归属；multimap-first-found-mismatch 同坑修复面）——
+  // 不再反解 markdown（正则脆且丢 project 维度）。classified 缺席时兜底反解 + 首个 modules 目录。
+  let mods = []
+  if (Array.isArray(skel.classified) && skel.classified.length >= 0) {
+    const seen = new Set()
+    for (const r of skel.classified) {
+      const key = r.project + '/' + r.module
+      if (seen.has(key)) continue
+      seen.add(key)
+      mods.push({ project: r.project, module: r.module, modulesDir: join(specBase, 'docs', r.project, 'modules') })
+    }
+  } else {
+    const modulesDir = findModulesDir(specBase)
+    if (!modulesDir) return { synced: [], unmatched: [], skipped: [], reason: 'modules 目录不存在' }
+    mods = [...new Set([...skel.markdown.matchAll(/^\| (\S+) \| `([^`]+)`/gm)].map(m => m[1]))]
+      .map(mod => ({ project: null, module: mod, modulesDir }))
+  }
+  const unmatched = Array.isArray(skel.unmatchedFiles)
+    ? skel.unmatchedFiles
+    : [...skel.markdown.matchAll(/^- `([^`]+)` /gm)].map(m => m[1])
   const synced = []
   const skipped = []
-  for (const mod of [...new Set(hitModules)]) {
+  for (const { project: proj, module: mod, modulesDir } of mods) {
     const sidecarPath = join(modulesDir, `${mod}.changelog.md`)
     let sidecar = ''
     try { sidecar = readFileSync(sidecarPath, 'utf8') } catch { sidecar = '' }
-    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(mod); continue }
+    if (sidecar.includes(`- ${changeName} |`)) { skipped.push(proj ? `${proj}/${mod}` : mod); continue }
     const NL = String.fromCharCode(10)
     const line = `- ${changeName} | ${note || '(见该变更 quicklog/归档)'}`
     const base = sidecar
@@ -114,7 +137,7 @@ export function syncModuleDocSidecars({ cwd, changeName, note, specDir = null })
       const stamped = card.replace(/^updated_at:.*$/m, `updated_at: ${new Date().toISOString().slice(0, 19) + '+08:00'}`)
       if (stamped !== card) writeFileSync(cardPath, stamped)
     } catch { /* 卡不存在——sidecar 照写，卡内容留给 agent */ }
-    synced.push(mod)
+    synced.push(proj ? `${proj}/${mod}` : mod)
   }
   return { synced, unmatched, skipped }
 }
@@ -133,22 +156,22 @@ function findModulesDir(specBase) {
 export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null, sourceFiles = null, origin = null }) {
   const specBase = resolveSpecDir(cwd, { specDir })
 
-  // 找 _module-map.yaml（docs/<p>/modules/；多项目取首个含 modules 索引的）
-  let moduleMapPath = null
+  // 多项目 map 联合归类（坑 multimap-first-found-mismatch，2026-09-21 R4-L 实证）：docs/ 下
+  // 各项目可各带 _module-map.yaml（对撞仓 5 个），原「取首个命中」让 daemon/frontend 文件对
+  // 按目录序排前的 backend map 全失配——24 文件全未匹配、sidecar 也写错项目目录。联合口径：
+  // 逐项目 classify、目录序首个命中 wins（单项目时联合退化为一图，行为不变）。
+  const moduleMaps = []
   try {
     for (const p of readdirSync(join(specBase, 'docs'), { withFileTypes: true })) {
       if (!p.isDirectory()) continue
       const candidate = join(specBase, 'docs', p.name, 'modules', '_module-map.yaml')
       if (existsSync(candidate)) {
-        moduleMapPath = candidate
-        break
+        const pm = parseModuleMapPaths(readFileSync(candidate, 'utf8'))
+        if (pm.size > 0) moduleMaps.push({ project: p.name, modulePaths: pm })
       }
     }
   } catch { /* 无 docs/ */ }
-  if (!moduleMapPath) return null
-
-  const modulePaths = parseModuleMapPaths(readFileSync(moduleMapPath, 'utf8'))
-  if (modulePaths.size === 0) return null
+  if (moduleMaps.length === 0) return null
 
   let sourceFileList
   if (sourceFiles) {
@@ -169,12 +192,18 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   if (sourceFileList.length === 0) return null
 
   const byModule = new Map()
+  const classified = [] // {project, module, file}——syncModuleDocSidecars 按 project 落 sidecar 用
   const unmatched = []
   for (const f of sourceFileList) {
-    const mod = classifyFile(f, modulePaths)
-    if (mod) {
-      if (!byModule.has(mod)) byModule.set(mod, [])
-      byModule.get(mod).push(f)
+    let hit = null
+    for (const m of moduleMaps) {
+      const mod = classifyFile(f, m.modulePaths)
+      if (mod) { hit = { project: m.project, moduleId: mod }; break }
+    }
+    if (hit) {
+      if (!byModule.has(hit.moduleId)) byModule.set(hit.moduleId, [])
+      byModule.get(hit.moduleId).push(f)
+      classified.push({ project: hit.project, module: hit.moduleId, file: f })
     } else {
       unmatched.push(f)
     }
@@ -234,5 +263,5 @@ export function generateModuleImpactSkeleton({ cwd, changeName, specDir = null,
   L.push('规则：execute/verify 完成文档同步后把对应行回填 done；确定不同步的行改 skipped 并在操作列写明原因。')
   L.push('')
 
-  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length }
+  return { markdown: L.join('\n'), matchedCount: sourceFileList.length - unmatched.length, unmatchedCount: unmatched.length, classified, unmatchedFiles: unmatched }
 }

package/src/module-resolve.js

@@ -78,8 +78,10 @@ export function collectModuleMaps({ cwd, specBase }) {
 /**
  * 路径归一：反斜杠→正斜杠，剥尾部 glob（/** 与 /*）与目录斜杠。
  * `backend/**` / `backend/` / `backend` → `backend`。
+ * （导出供 flow-parity.reconcileModuleDocs 复用——2026-09-27-thin-module-scope-persist：
+ * 模块对账与模块卡解析同一归一口径，防两处漂移）
  */
-function normalizeMapPath(raw) {
+export function normalizeMapPath(raw) {
   return String(raw).replace(/\\/g, '/').replace(/\/\*\*$/, '').replace(/\/\*$/, '').replace(/\/$/, '')
 }