sillyspec 3.32.10 → 3.33.1

package/src/spec-sync.js

@@ -19,6 +19,8 @@ import { createHash } from 'crypto';
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join, relative, sep } from 'path';
 import { bindSyncNoiseRoot, syncConnectionWarn, isConnectionClassStatus, noteSyncSuccess } from './sync-noise.js';
+import { runtimeStatePath } from './runtime-paths.js';
+import { writeAtomicSync } from './fs-atomic.js';
 
 // 与 sillyhub-daemon/src/spec-sync.ts 共用排除口径（task-07 / FR-06 / D-008@v2）：
 // .runtime（有点）/ runtime（无点）/ projects（本地环境文件）在顶层排除；
@@ -63,6 +65,61 @@ export function describeSyncError(err) {
   return err && err.message ? err.message : String(err);
 }
 
+// ── 同步失败连续计数与响应体摘要（2026-10-16 生产索引损坏事故可观测性加固）──
+// 事故：平台 422 业务错误只打状态码（真因 HTTP_422_SPEC_BUNDLE_INVALID+路径要手动重放请求
+// 才拿到），且失败走「下次自动重试」无限静默循环——归档半态（本地已归档、平台仍「进行中」）
+// 挂数小时无人知晓。两道护栏：①非 2xx 响应体解析进告警行；②按 label 连续失败计数持久化，
+// 连续 ≥3 次升级 🚨 显式告警，任一次成功清零。
+const FAIL_STREAK_FILE = join('.runtime', 'state', 'spec-sync-fail-streak.json');
+const FAIL_STREAK_ESCALATE_AT = 3;
+
+export function describeErrorBody(status, rawBody) {
+  if (!rawBody) return '';
+  try {
+    const j = JSON.parse(rawBody);
+    const code = j.code || `HTTP_${status}`;
+    const p = j.details && j.details.path ? ` path=${j.details.path}` : '';
+    return j.message ? `${code}${p}: ${j.message}` : rawBody.slice(0, 200);
+  } catch {
+    return rawBody.slice(0, 200);
+  }
+}
+
+export function readFailStreak(specRoot) {
+  try {
+    return JSON.parse(readFileSync(join(specRoot, FAIL_STREAK_FILE), 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function bumpFailStreak(specRoot, label, detail) {
+  const all = readFailStreak(specRoot);
+  const cur = all[label] || { count: 0 };
+  cur.count += 1;
+  cur.lastAt = new Date().toISOString();
+  if (detail) cur.lastError = String(detail).slice(0, 300);
+  all[label] = cur;
+  try {
+    mkdirSync(join(specRoot, '.runtime'), { recursive: true });
+    writeAtomicSync(join(specRoot, FAIL_STREAK_FILE), JSON.stringify(all, null, 2) + '\n');
+  } catch {
+    // fail-soft：计数落盘失败只影响告警升级，不阻断同步主流程
+  }
+  return cur.count;
+}
+
+export function clearFailStreak(specRoot, label) {
+  const all = readFailStreak(specRoot);
+  if (!all[label]) return;
+  delete all[label];
+  try {
+    writeAtomicSync(join(specRoot, FAIL_STREAK_FILE), JSON.stringify(all, null, 2) + '\n');
+  } catch {
+    // fail-soft：残留计数只是少清一次，下次成功再清
+  }
+}
+
 function _hashBuffer(buf) {
   return createHash('sha256').update(buf).digest('hex');
 }
@@ -331,7 +388,7 @@ const LAST_SUCCESS_MARKER = 'spec-sync-last-success.json';
 
 function readLastSyncTs(specRoot) {
   try {
-    const raw = readFileSync(join(specRoot, '.runtime', LAST_SUCCESS_MARKER), 'utf8');
+    const raw = readFileSync(runtimeStatePath(join(specRoot, '.runtime'), LAST_SUCCESS_MARKER), 'utf8');
     const ts = JSON.parse(raw).ts;
     return Number.isFinite(ts) ? ts : null;
   } catch {
@@ -342,7 +399,7 @@ function readLastSyncTs(specRoot) {
 function writeLastSyncTs(specRoot) {
   try {
     mkdirSync(join(specRoot, '.runtime'), { recursive: true });
-    writeFileSync(join(specRoot, '.runtime', LAST_SUCCESS_MARKER), JSON.stringify({ ts: Date.now() }) + '\n', 'utf8');
+    writeFileSync(runtimeStatePath(join(specRoot, '.runtime'), LAST_SUCCESS_MARKER), JSON.stringify({ ts: Date.now() }) + '\n', 'utf8');
   } catch { /* 标记失败只损失下次的防回推过滤，不影响本次同步结果 */ }
 }
 
@@ -359,7 +416,7 @@ const BASE_SNAPSHOT = 'spec-sync-base.json';
 
 function readBaseSnapshot(specRoot) {
   try {
-    const raw = readFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), 'utf8');
+    const raw = readFileSync(runtimeStatePath(join(specRoot, '.runtime'), BASE_SNAPSHOT), 'utf8');
     const hashes = JSON.parse(raw).hashes;
     return hashes && typeof hashes === 'object' ? hashes : null;
   } catch {
@@ -372,7 +429,7 @@ function writeBaseSnapshot(specRoot, localFiles) {
     const hashes = {};
     for (const f of localFiles) hashes[f.path] = f.hash;
     mkdirSync(join(specRoot, '.runtime'), { recursive: true });
-    writeFileSync(join(specRoot, '.runtime', BASE_SNAPSHOT), JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
+    writeFileSync(runtimeStatePath(join(specRoot, '.runtime'), BASE_SNAPSHOT), JSON.stringify({ ts: Date.now(), hashes }, null, 2) + '\n', 'utf8');
   } catch { /* 快照失败只损失下次的内容级防回推，不影响本次同步结果 */ }
 }
 
@@ -441,7 +498,7 @@ export function partitionConflictPaths(serverVersions, localFiles, baseHashes, l
  */
 function isSamePendingSpecConflict(specRoot, changeName, realPaths) {
   try {
-    const raw = readFileSync(join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`), 'utf8');
+    const raw = readFileSync(runtimeStatePath(join(specRoot, '.runtime'), `spec-sync-conflict-${changeName}.json`), 'utf8');
     const prev = JSON.parse(raw).conflicting_paths;
     if (!Array.isArray(prev) || prev.length !== realPaths.length) return false;
     const prevSet = new Set(prev);
@@ -458,7 +515,7 @@ function isSamePendingSpecConflict(specRoot, changeName, realPaths) {
  */
 function clearSpecConflictMarker(specRoot, changeName) {
   try {
-    const p = join(specRoot, '.runtime', `spec-sync-conflict-${changeName}.json`);
+    const p = runtimeStatePath(join(specRoot, '.runtime'), `spec-sync-conflict-${changeName}.json`);
     if (existsSync(p)) unlinkSync(p);
   } catch { /* 清理失败不影响同步结果 */ }
 }
@@ -497,7 +554,7 @@ export function writeTombstoneAttribution(specRoot, platformDeleted) {
   const byChange = extractTombstonedChanges(platformDeleted);
   const written = [];
   for (const [name, paths] of byChange) {
-    const filePath = join(specRoot, '.runtime', `spec-sync-conflict-${name}.json`);
+    const filePath = runtimeStatePath(join(specRoot, '.runtime'), `spec-sync-conflict-${name}.json`);
     let prev = null;
     try { prev = JSON.parse(readFileSync(filePath, 'utf8')); } catch { /* 首见 */ }
     const record = {
@@ -528,13 +585,17 @@ export function writeTombstoneAttribution(specRoot, platformDeleted) {
  * 清理条数。挂在两个全绿点：POST 成功无冲突分支与无差异跳过分支。
  */
 export function clearStaleTombstoneMarkers(specRoot) {
+  // 2026-10-18 布局分层：冲突文件落 state/；根目录扫描保留旧布局兜底
   const runtimeDir = join(specRoot, '.runtime');
   let files = [];
-  try { files = readdirSync(runtimeDir); } catch { return 0; }
+  const conflictDirs = [join(runtimeDir, 'state'), runtimeDir]
   let cleared = 0;
-  for (const f of files) {
+  for (const dir of conflictDirs) {
+  let dirFiles = [];
+  try { dirFiles = readdirSync(dir); } catch { continue; }
+  for (const f of dirFiles) {
     if (!f.startsWith('spec-sync-conflict-') || !f.endsWith('.json')) continue;
-    const p = join(runtimeDir, f);
+    const p = join(dir, f);
     try {
       const j = JSON.parse(readFileSync(p, 'utf8'));
       const cp = Array.isArray(j.conflicting_paths) ? j.conflicting_paths : null;
@@ -545,6 +606,7 @@ export function clearStaleTombstoneMarkers(specRoot) {
       }
     } catch { /* 损坏文件不动 */ }
   }
+  }
   if (cleared > 0) {
     console.log(`[spec-sync] 全绿同步清理 ${cleared} 条陈旧墓碑冲突记录（被删变更已收敛）`);
   }
@@ -568,7 +630,7 @@ const FOLLOW_REPORT_MARKER = 'spec-sync-follow-reported.json';
  */
 export function isFollowerSetChanged(specRoot, key, list) {
   const sorted = [...(list || [])].sort();
-  const p = join(specRoot, '.runtime', FOLLOW_REPORT_MARKER);
+  const p = runtimeStatePath(join(specRoot, '.runtime'), FOLLOW_REPORT_MARKER);
   let cur = {};
   try { cur = JSON.parse(readFileSync(p, 'utf8')) || {}; } catch { /* 无 marker = 首报 */ }
   const prev = Array.isArray(cur[key]) ? cur[key] : [];
@@ -609,10 +671,20 @@ function attributeChangeLabel(paths) {
   return names.size === 1 ? [...names][0] : 'full-tree'
 }
 
+/**
+ * spec 树增量同步（以服务器清单为锚做全树 diff → POST ops）。
+ *
+ * 返回契约（2026-10-17-archive-half-state-location-stuck-active）：`ok` 字段表达
+ * 「本轮文件树通道是否确认收敛」——ok:true = 确认（无差异 no-op / 推送成功 / 冲突自愈
+ * / 未连接本地合法态）；ok:false = 确认失败（清单/推送 HTTP 失败、异常）；**无 ok 字段
+ * = 未确认**（未决冲突待人裁等，fail-closed）。终态强校验消费方
+ * （run/shared.js triggerSyncTerminalStrict）按 `ok === true` 判收敛——历史调用方
+ * （syncSpecTreeOnly / resolve forcePush 等）不消费该字段，向后兼容。
+ */
 export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   if (!platform || !platform.url || !platform.token) {
     debugLog('[spec-sync] 未连接平台（本地合法状态）；跳过 spec 树增量同步');
-    return { synced: 0 };
+    return { synced: 0, ok: true };
   }
   // 全树入口（platform sync 无 --change，2026-10-11-sync-conflict-tri-fix FR-03）
   // changeName=null：日志用 full-tree 标签，冲突归因见下方 conflictLabel。
@@ -640,17 +712,27 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       // 8 分钟才被后续步骤的同步补上）。失败可见、成功不打扰。
       // 连接类失败（404=端点未就绪 / 5xx）走噪音闸（sync-noise.js）：平台未就绪期每步
       // 自动同步重刷同一行，淹没门禁输出；其余状态码（4xx 业务态）每轮该看见。
-      const line = `[spec-sync] 拉取清单失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}`;
+      const raw = await res.text().catch(() => '');
+      const detail = describeErrorBody(res.status, raw);
+      const failCount = bumpFailStreak(specRoot, logLabel, detail);
+      const line = `[spec-sync] 拉取清单失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
       if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
       else console.warn(line);
-      return { synced: 0 };
+      if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+        console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+      }
+      return { synced: 0, ok: false };
     }
     const body = await res.json().catch(() => ({}));
     serverManifest = body.files || {};
   } catch (err) {
+    const failCount = bumpFailStreak(specRoot, logLabel, describeSyncError(err));
     const line = `[spec-sync] 拉取清单异常（文件树本次未同步，下次自动重试）: ${logLabel}: ${describeSyncError(err)}`;
     syncConnectionWarn(line); // 网络/超时/熔断均连接类
-    return { synced: 0 };
+    if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+      console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+    }
+    return { synced: 0, ok: false };
   }
 
   // 2. walk/hash/diff
@@ -691,7 +773,8 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   if (ops.length === 0) {
     debugLog(`[spec-sync] 无差异，跳过同步: ${logLabel}`);
     clearStaleTombstoneMarkers(specRoot);
-    return { synced: 0 };
+    clearFailStreak(specRoot, logLabel);
+    return { synced: 0, ok: true };
   }
 
   // 3. POST ops
@@ -706,10 +789,16 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       signal: withSignal(30000),
     });
     if (!res.ok) {
-      const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}`;
+      const raw = await res.text().catch(() => '');
+      const detail = describeErrorBody(res.status, raw);
+      const failCount = bumpFailStreak(specRoot, logLabel, detail);
+      const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
       if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
       else console.warn(line);
-      return { synced: 0 };
+      if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+        console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+      }
+      return { synced: 0, ok: false };
     }
     const body = await res.json().catch(() => ({}));
     if (body.conflict) {
@@ -770,7 +859,7 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
           debugLog(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
         }
         console.warn(`⚠️ [spec-sync] 变更 ${conflictLabel} 存在未决 spec 树冲突（${realPaths.length} 个文件待裁决，本轮非冲突改动已照常同步）。处理：sillyspec platform resolve ${conflictLabel} --keep-local | --take-platform | --abort`);
-        return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath: join(specRoot, '.runtime', `spec-sync-conflict-${conflictLabel}.json`), suppressed: true };
+        return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath: runtimeStatePath(join(specRoot, '.runtime'), `spec-sync-conflict-${conflictLabel}.json`), suppressed: true };
       }
       if (followers.length > 0) {
         console.warn(`[spec-sync] ${followers.length} 个本地未改动文件自动跟随服务器（正常多端前进，无需人工裁决）: ${followers.slice(0, 5).join(', ')}${followers.length > 5 ? ' 等' : ''}`);
@@ -780,14 +869,15 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
         writeBaseSnapshot(specRoot, localFiles);
         clearSpecConflictMarker(specRoot, conflictLabel);
         noteSyncSuccess();
+        clearFailStreak(specRoot, logLabel);
         console.log(`[spec-sync] 冲突已自动消解（0 个需人工裁决；本会话改动 ${ops.length - followers.length > 0 ? '已同步' : '无差异'}）: ${conflictLabel}`);
-        return { synced: Math.max(ops.length - followers.length, 0), conflict: false, autoResolved: followers.length };
+        return { synced: Math.max(ops.length - followers.length, 0), ok: true, conflict: false, autoResolved: followers.length };
       }
       let conflictPath = null;
       try {
         const runtimeDir = join(specRoot, '.runtime');
         mkdirSync(runtimeDir, { recursive: true });
-        conflictPath = join(runtimeDir, `spec-sync-conflict-${conflictLabel}.json`);
+        conflictPath = runtimeStatePath(runtimeDir, `spec-sync-conflict-${conflictLabel}.json`);
         writeFileSync(conflictPath, JSON.stringify({
           change: conflictLabel,
           kind: 'spec-tree',
@@ -811,6 +901,7 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       return { synced: 0, conflict: true, serverVersions: real, autoResolved: followers.length, conflictPath };
     }
     noteSyncSuccess();
+    clearFailStreak(specRoot, logLabel);
     console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${logLabel}`);
     // 本轮无冲突 = 此前的未决 spec 树冲突已不存在，清残留标记（否则 status 永久红标、
     // 横幅去重单行提示不消——坑 spec-sync-conflict-banner-spam）。全树入口
@@ -826,11 +917,15 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
     clearStaleTombstoneMarkers(specRoot);
     writeLastSyncTs(specRoot);
     writeBaseSnapshot(specRoot, localFiles);
-    return { synced: ops.length };
+    return { synced: ops.length, ok: true };
   } catch (err) {
+    const failCount = bumpFailStreak(specRoot, logLabel, describeSyncError(err));
     const line = `[spec-sync] 同步异常（文件树本次未同步，下次自动重试）: ${logLabel}: ${describeSyncError(err)}`;
     syncConnectionWarn(line); // 网络/超时/熔断均连接类
-    return { synced: 0 };
+    if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+      console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+    }
+    return { synced: 0, ok: false };
   }
 }
 

package/src/stage-contract.js

@@ -897,7 +897,7 @@ function matrixEvidenceMissing(verdict, evidence) {
  */
 export function extractAcceptanceMatrixSlots(verifyMd) {
   const md = String(verifyMd || '')
-  const out = { present: false, rows: [], unfilled: 0, missingEvidence: 0 }
+  const out = { present: false, rows: [], unfilled: 0, missingEvidence: 0, strayRows: [] }
   const hm = md.match(/^#### 探针 7[：:]/m)
   if (!hm) return out
   out.present = true
@@ -905,15 +905,27 @@ export function extractAcceptanceMatrixSlots(verifyMd) {
   const endMatch = rest.match(/^#{1,4}(?:[ \t]|$)/m)
   const sectionText = endMatch ? rest.slice(0, endMatch.index) : rest
 
+  // 表头武装（坑 carry-orphan-rows，2026-10-16 下游实证）：五列表行只在探针 7 段已被表头行
+  // 武装时才计数；refresh 携载注释块解除武装——其后残行（旧模板占位行/键漂移携载行）是无
+  // 表头归属的孤行，不栽给最近 **task-NN** 锚误报「判定未填」，进独立 strayRows 桶由
+  // validateAcceptanceMatrix 报错要求裁决。武装是段级粘性（首表头武装整段，锚行不重置——
+  // 锚下不重复表头的既有手写/历史形态照旧按锚归属）；只有携载注释块与其后无新表头重新
+  // 武装的窗口内，行才进孤行桶。正常渲染文法（锚行→表头→分隔→数据行）行为与既有口径一致。
   let currentTask = ''
+  let tableArmed = false
   for (const rawLine of sectionText.split(/\r?\n/)) {
     const anchor = rawLine.match(/^\*\*\s*(task-[A-Za-z0-9._-]+)\s*\*\*/)
     if (anchor) { currentTask = anchor[1]; continue }
+    if (/<!--\s*refresh 携载/.test(rawLine)) { tableArmed = false; continue } // 携载注释块：其后表行是孤行（直至新表头重新武装）
     const cells = splitMatrixRowCells(rawLine)
     if (!cells || cells.length !== 5) continue // 列表防御行/不适用行/非五列表行不计槽
     const c = cells.map(x => x.trim())
     if (c.every(x => /^:?-{3,}:?$/.test(x))) continue // 分隔行 |---|---|…|
-    if (c[3] === '判定' && c[4] === '证据') continue // 表头行
+    if (c[3] === '判定' && c[4] === '证据') { tableArmed = true; continue } // 表头行（武装本段）
+    if (!tableArmed) {
+      out.strayRows.push({ task: currentTask, acceptance: c[0], verdict: c[3], evidence: c[4] })
+      continue
+    }
     const verdict = c[3]
     const evidence = c[4]
     const row = { task: currentTask, acceptance: c[0], verdict, evidence }
@@ -985,6 +997,16 @@ function validateAcceptanceMatrix(cwd, changeName, context = {}) {
       `修复：在证据列补测试锚点（如 \`test/foo.test.mjs\` 或 \`src/x.js:42\`）或 non-testable 理由（运行验证移交场景适用：构建回执+移交去向一句话）。`
     )
   }
+  // 孤行报错（坑 carry-orphan-rows，2026-10-16 下游实证）：无表头归属的五列残行（refresh
+  // 携载块后的旧模板占位行/键漂移携载行/手误行）不归属任何 task 锚——不栽给最近锚计
+  // unfilled（旧路径误报「文档同步任务判定未填」），独立报错要求裁决：删或补归属。
+  if ((matrix.strayRows || []).length > 0) {
+    const list = matrix.strayRows.map((r) => `${r.task || '（无 task 锚）'}｜${clip(r.acceptance)}`).join('；')
+    errors.push(
+      `探针 7 验收×测试覆盖矩阵存在 ${matrix.strayRows.length} 行无表头归属的孤行（携载残行/旧模板占位行/手误——不属于任何 task 锚下的有效表，不计入任务矩阵）：${list}。` +
+      `修复：删除这些残行，或补全 **task-NN** 锚行与表头后按五列格式填判定与证据。`
+    )
+  }
 
   // ── partial/uncovered × facts.handover 联动（D-003/FR-04，2026-09-17-pass-cap-semantics task-03）──
   // 部分实现必须有移交去向：矩阵含 partial/uncovered 行且 facts.handover 零有效行（任意

package/src/stage-review.js

@@ -14,6 +14,7 @@
  */
 
 import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs'
+import { runtimeStatePath } from './runtime-paths.js'
 import { writeAtomicSync } from './fs-atomic.js'
 import { join, dirname } from 'path'
 import { createHash } from 'crypto'
@@ -139,7 +140,8 @@ export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier,
     '',
     '> 路径:`{SPEC_ROOT}/.runtime/stage-reviews/' + stageLbl + '-' + runIdLbl + '/review.json`(本次 reviewType=' + reviewType + ',主审查文档=' + mainDocRel + ')',
     ...(changeDir
-      ? ['> **本次完整绝对路径（直接复制给审查子代理，勿手拼 runId/漏阶段前缀——坑 stage-review-path-prefix 2026-10-10 实证：marker 只有裸 runId，子代理按 runId 直写漏「<stage>-」前缀即错位）**: `' + join(dirname(dirname(changeDir)), '.runtime', 'stage-reviews', stageLbl + '-' + runIdLbl, 'review.json') + '`']
+      ? ['> **本次完整绝对路径（直接复制给审查子代理——勿手拼、勿增删任何前缀）**: `' + join(dirname(dirname(changeDir)), '.runtime', 'stage-reviews', stageLbl + '-' + runIdLbl, 'review.json') + '`',
+         '> ⚠️ 坑 stage-review-path-prefix 双向实测：漏「<stage>-」前缀即错位（2026-10-10：marker 只有裸 runId，子代理按 runId 直写）；**多加一层「review-」前缀同样错位**（2026-10-15 复发：手拼成 `<stage>-review-review-…`，空目录残渣+一轮纠正）。唯一可靠做法：整条路径直接粘贴。']
       : []),
     '',
     '### 必填字段(validateStageReviewSchema 硬校验,缺任一即 schema 失败阻断)',
@@ -363,7 +365,7 @@ export function generateStageReviewRunId() {
  */
 export function stageReviewMarkerPath(runtimeRoot, stage, changeName) {
   const suffix = changeName ? `${stage}-${changeName}` : stage
-  return join(runtimeRoot, `current-stage-review-run-id-${suffix}`)
+  return runtimeStatePath(runtimeRoot, `current-stage-review-run-id-${suffix}`)
 }
 
 /**
@@ -852,7 +854,7 @@ export function printStageReviewResult(result, context = {}) {
     // fail-open：无 changeName / 无记录 / 读失败 → 零输出（旧口径）。
     if (changeName && runtimeRoot) {
       try {
-        const recPath = join(runtimeRoot, `review-dispatch-${changeName}.json`)
+        const recPath = runtimeStatePath(runtimeRoot, `review-dispatch-${changeName}.json`)
         if (existsSync(recPath)) {
           const rec = JSON.parse(readFileSync(recPath, 'utf8'))
           if (rec && typeof rec === 'object' && (rec.state === 'in-flight' || rec.state === 'dispatching')) {

package/src/stages/brainstorm.js

@@ -58,7 +58,7 @@ export const definition = {
 - **明显 small**（满足：单上下文可吞吐的纯执行类——改文案/修 bug/样式调整/配置微调，预计无 Wave 编排/上下文分片需求）→ 输出：「此变更规模较小，建议直接走轻量变更」+ 一句依据，给出可照抄建议命令（--input 引号内换行合法）：
 
 \`\`\`
-sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（首行即变更标题）；随后动机与背景
+sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文概括（首行即变更标题，硬区间 10-30 必须、建议 ~20 字）；随后动机与背景
 
 成功标准：
 - <可验证标准>"
@@ -89,7 +89,9 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
       prompt: `### ⚡ 轻量跑判定（P0-3，2026-09-20 对撞实验驱动——需求已收敛来源走全仪探索是纯税）
 **需求来源已收敛**（满足任一：--input 显式声明承接/已澄清/方案已定；fork 或关联会话已多轮澄清过本需求，你已能不问自答全部 P0 歧义；任务书/评审结论直接给定方案与边界）→ 本步可**轻量跑**：A-D 节按已收敛事实直书结论（歧义零清单、范围直裁、决策若已有则引用源会话不重问），一次性完成不再多轮追问。轻量跑不降质量底线：范围结论与决策落盘照常，仅省「明知故问」的交互轮。Grill（Step 7）与规范文件（Step 8）**不适用轻量跑、永不省**。
 
-通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行。提问遵守「一次只问一个」（见 D 节追问策略）：必须问的问题逐个问，能查代码/文档解决的不问；不要把多个歧义打包成一屏清单一次抛给用户（用户记不住、答不全，反而漏掉关键约束）；也不要为凑数把单个问题拖成多轮。
+通过对话探索需求细节、分析原型（如有）、判断拆分/批量、并对歧义点做需求澄清 Grill。本步骤合并了原有的对话探索、原型分析、需求范围评估、需求澄清 Grill 四个环节——按下方 A→D 顺序按需执行。提问遵守「一次只问一个」（见 D 节追问策略——分层口径：P0 逐轮逐问、P1/P2 能自定的自定并标注、只有会改变产物的攒收尾一轮）：必须问的问题逐个问，能查代码/文档解决的不问；不要把多个歧义打包成一屏清单一次抛给用户（用户记不住、答不全，反而漏掉关键约束）；也不要为凑数把单个问题拖成多轮。
+
+**规模重估（对话中如发现该升级，当场说）**：若对话或方案讨论中发现本次变更实际需要 Wave 并行编排、上下文分片或多阶段治理——超出当前档位（例：早期粗判的轻量面变成跨模块改造）——必须**当场向用户说明并给出升级建议**（如改走完整五阶段 / 带 \`--upgrade-thick\`），不静默按原档继续。档位仍由 CLI 客观定价（三轴）落值，你只能建议、不能自行升降档。
 
 ### A. 原型/设计图分析（如用户提供）
 如果用户提供了截图、图片或 HTML 原型，先分析提取：
@@ -106,8 +108,18 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
 2. **提出问题后必须暂停等待用户回答**，不要替用户回答
 3. 根据用户回答判断：信息够了 → 进入 C/D 或正常完成 / 需要追问 → 暂停等待下一个回答
 4. 探索顺序（按需）：目的 → 约束 → 边界 → 成功标准
-5. 多选题优于开放式问题
-6. YAGNI — 砍掉不需要的功能
+5. **先挖为什么**：不只问「要什么」，要问出「为什么现在做、不做会怎样」（动机是后续替你补全没提的那一百个决定的依据）；到本步出口仍说不清动机 → 不许进入「提出 2-3 种方案」，先把动机问出来
+6. **实现方式的选择权归谁**：技术栈/平台/语言/库/存储介质这类「怎么做」的选择，问清哪些是用户有强意见要谈的、哪些是交给你选的；你选的按决策记录规则落盘并把 answer 标注「我的判断」（不是用户同意过的）
+7. 多选题优于开放式问题；被问「你觉得呢/先猜一个」时给一个具体方案并标「我的判断」，不要空转追问
+8. YAGNI — 砍掉不需要的功能
+
+### B2. 分块回放（Playback——边理解边复述，与追问交替）
+每理解到一块就先回放一块，别把回放攒到最后：
+- 回放块 200-300 字，复述「我听到的是」——**凡是猜测都标为猜测，只有用户说过的才写成用户说的**
+- 回放块结尾固定问一句：「哪里不对或漏了什么？」
+- 回放与追问交替进行直到对话结束：回放 → 用户纠正 → 下一块追问 → 下一块回放；最后一块覆盖剩余部分
+- 再次进入本步（\`--continue --answer\` 后）时，回放只复述新增/被纠正的理解，已确认且未被纠正的部分不重复回放（防上下文膨胀）
+- 回放块放「**回放：**」分节、追问放「**追问：**」分节——两者分节标注，用户可分别纠正（回答的是上一轮追问时不影响回放块的语义）
 
 ### C. 需求范围评估（拆分/批量判断）
 1. 根据分析结果判断复杂度。满足以下任意 2 条建议拆分：
@@ -155,19 +167,22 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
 - P1：影响用户场景、验收标准、错误处理、默认值
 - P2：文案、展示细节、低风险交互偏好
 
-**执行规则**：
+**执行规则（分层——2026-10-15-brainstorm-interaction-refine FR-03）**：
 - P1/P2 歧义 0-2 个且无 P0：不进入 Grill 追问，在后续设计中内联处理并记录依据
-- P1/P2 歧义 >= 3 个：按优先级逐个澄清
-- 任意 P0 歧义：必须澄清；如果需要用户判断，暂停问一个问题
+- P1/P2 歧义 >= 3 个：不逐个问——agent 能自行决定的**自行决定**（写进 decisions.md，answer 标注「我的判断」），剩下的攒成收尾一轮；只有「只有用户能答且答案会改变产物」的才问
+- 任意 P0 歧义：必须澄清；逐轮逐问（一次只问一个），深度优先
+- **收尾一轮（一次性问完）**：把「只有用户能答且答案会改变产物」的 P1/P2 项（含 Design Grill 回收的同类项）汇总成**一轮**问题，一次问完；问完即进入「提出 2-3 种方案」，不再追问、不做第二轮
+- 可判定出口：进入「提出 2-3 种方案」前，P1/P2 未决项必须为 0，或已记录为「我的判断」落 decisions.md
 - 不要问用户"要不要 Grill"。由你根据歧义风险决定；只在需要业务判断/取舍时等待用户回答
 
-**追问策略**（进入澄清时）：
-1. **一次只问一个问题**：按 P0 → P1 → P2 顺序，深度优先处理最关键歧义
-2. **能查代码就不问**：问题可由源码、scan 文档、模块文档回答时，先查证并给出结论
-3. **术语碰撞立即指出**：用户用词与 glossary/代码实体/模块文档冲突时，当场说明冲突并要求选择 canonical term
-4. **模糊词精化**：把"账户/任务/状态/会话/执行"这类多义词拆成明确实体或状态
-5. **场景压力测试**：用具体 case 逼出边界（失败重试、部分成功、历史数据、权限不足、并发修改、兼容旧配置）
-6. **前提挑战优先**：如果现有设计或代码已有简单路径，先说明"可能不该新增"
+**追问策略**（进入澄清时，分层口径同上）：
+1. **P0 逐轮逐问**：P0 一次只问一个，深度优先
+2. **P1/P2 能自定就自定**：能由源码/scan 文档/模块文档/既有决策确定，或能凭工程判断定且不改变产物的，直接定；按决策记录规则落 decisions.md 并在 answer 标注「我的判断」；只有真正需要用户判断/取舍的才等用户
+3. **能查代码就不问**：问题可由源码、scan 文档、模块文档回答时，先查证并给出结论
+4. **术语碰撞立即指出**：用户用词与 glossary/代码实体/模块文档冲突时，当场说明冲突并要求选择 canonical term
+5. **模糊词精化**：把"账户/任务/状态/会话/执行"这类多义词拆成明确实体或状态
+6. **场景压力测试**：用具体 case 逼出边界（失败重试、部分成功、历史数据、权限不足、并发修改、兼容旧配置）
+7. **前提挑战优先**：如果现有设计或代码已有简单路径，先说明"可能不该新增"
 
 **决策记录（增量落盘，防会话中断丢失）**：每解决一个有实现影响的问题（不要把闲聊都记录进去），**当场追加**写入 \`{SPEC_ROOT}/changes/<change-name>/decisions.md\`——不要只在对话里留草稿等「写设计文档」步统一落盘：会话随时可能中断，未落盘的决策无法跨会话恢复。落盘规则：
 
@@ -193,19 +208,33 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
 \`\`\`
 
 - 幂等：写入前按 D-xxx@vN 查重，已存在的不重复追加；后续修正走新版本 D-001@v2 + supersedes（见 Design Grill 版本规则）
+- **agent 自行决定的 P1/P2**（见执行规则分层）：source 用 code（查证得来）或 docs（文档依据），answer 标注「我的判断：…」——不写成用户同意过的，用户事后可否决
+- **「只有用户能答且改变产物」的项**：不落 pending 占位条目；先在收尾一轮问出答案，再按 source: user 落盘
 
 ### 铁律 — 不要自问自答 / 等待用户
 - 这是人机协作步骤：提出问题后必须暂停等用户回答，**不要在输出里模拟用户回答然后说"需求已明确"**（命令由 CLI 在下方注入）
 - 需要拆分或批量模式时：列出方案并暂停等用户确认
 - 不需要追问、无歧义、需求已清晰时：可正常完成本步骤（不必强行 --wait）。但「正常完成」的前提是**输出一份可否决的确认清单**——在输出里明确列出「已确认需求点清单」（逐条），让用户能一眼看到并喊停；未与用户确认过任何需求点、纯凭自身判断的场景，不得仅凭「我觉得清晰」直接放行（这是把默认共识伪装成共识的逃逸口）
+- **确认清单逐条带来源标记（两态）**：每条需求点标 \`[用户]\`（用户原话/回答得来）或 \`[推断]\`（agent 推断）——\`[推断]\` 即待用户点头项；未与用户确认过的推断点**不得混入已确认清单**（要么在收尾一轮问掉转 \`[用户]\`，要么显式留在「待确认」区）
 - 2-3 轮问答即进入方案讨论；达到 maxWaitRounds=8 后必须总结已确认内容与剩余风险，不要无限追问
 
+### 自欺逃逸口对照表
+要输出「本步完成」「可以直接进方案讨论」之前，先对表自检一遍：
+
+| 念头 | 现实 |
+|---|---|
+| "我觉得已经够清晰了" | 清晰不等于用户确认过——没确认过的点进清单必须标 \`[推断]\`，并留待收尾一轮问掉 |
+| "这步这么简单，跳过吧" | 简单变复杂的路只有一条：跳过的步骤 |
+| "用户说『听起来不错』" | 认可的是你展示过的东西——你没写出来的描述与你的推断，都不算批准 |
+
 ### 输出
 需求理解摘要（用户确认的需求点列表）+ 拆分/批量结论（如适用）+ 本步新增落盘的 D-xxx@vN 清单 + 剩余风险（如有）
 
+确认清单每条带来源标记 \`[用户]\` / \`[推断]\`；\`[推断]\` 项在收尾一轮问掉或显式留在「待确认」区——两者都不带 \`[用户]\` 标记时不得计入「已确认」。
+
 ### 注意
 - 第一次进入此步骤时，按 A→D 顺序处理；有原型先分析，再探索，再判规模，再澄清
-- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行，此时检查是否需要追问或可以结束；再次执行时输出只需增量汇报（新结论 + 新落盘决策），已落盘内容不要重复输出`,
+- 用户通过 \`--continue --answer "回答"\` 回答后，本步骤会再次执行，此时检查是否需要追问或可以结束；再次执行时输出只需增量汇报（**新回放块 + 新追问 + 新落盘决策**），已确认且未被纠正的内容不重复回放、已落盘内容不重复输出`,
       outputHint: '需求理解与决策落盘清单',
       optional: false
     },
@@ -251,7 +280,8 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
 4. 分段设计含新机制时同上检索（固定动作）：设计的分段内容引入新机制词（例词为举例非机制，不构成封闭清单）时，先跑 \`sillyspec knowledge search --query "<机制词>"\`，命中条目必读（尤其 status=rejected 的防复潮条目）再定稿设计
 5. 确认变更名（格式：\`YYYY-MM-DD-<简短描述>\`，例如 \`2026-05-13-user-auth\`——CLI 已强制：新建/改名不带日期前缀直接 exit 2）
 6. 按「HTML 原型分级」三选一必填：生成原型 / 登记复用既有原型 / 写出跳过原因（见下）
-7. 暂停等待用户确认或修改意见
+7. 展示时附一节「**我替你做的决定**」（2026-10-15-brainstorm-interaction-refine FR-04）：从 \`decisions.md\` 摘出 \`source\` 非 user 的条目（代码/文档查证得来的 + agent 自行决定的 P1/P2），逐条列 D-xxx@vN + 一句话决定 + 一句依据——让用户边读方案边核这些点，不要埋在决策文件里让他自己去翻；无此类条目时写「无（全部决定均来自你的选择）」
+8. 暂停等待用户确认或修改意见
 
 ### HTML 原型分级（按改动程度，不是"是否碰前端文件"）
 判定对象是**改造后的界面相对现状的变化程度**：
@@ -272,10 +302,10 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
   - 纯后端逻辑/CLI/配置/文档，无任何界面变化
 
 ### 生成要求（定稿原型＝真码产物，不是手绘图）
-入口文件保存到 \`{SPEC_ROOT}/changes/<change-name>/prototype-<名称>.html\`（目录不存在则先创建；该命名是 execute 注入契约，不改）。真码五要素：
-- **与实现同方言**：用项目真实前端栈构建——组件库/设计 token/样式从项目源码或 node_modules 真实引入（例：React 项目挂真实组件而非仿制标签、Vue 项目用真实 SFC；例词非封闭清单），不手搓仿制样式
-- **可复跑**：能被本项目工具链跑起来（dev server / 组件文档页 / 构建产物均可，入口 HTML 从本地 node_modules 引真实库也行）——先查 scan 文档与现有前端代码就近发现项目原型管线，已有则复用，没有则搭最小入口并留在项目惯例位置
-- **高保真＝组件即实现原料**：布局/组件/交互按真实效果呈现，execute 阶段直接对照搬组件，不经过"看图重新翻译"
+入口文件保存到 \`{SPEC_ROOT}/changes/<change-name>/prototype-<名称>.html\`（目录不存在则先创建；该命名是 execute 注入契约，不改）。**本仓 local.yaml ui_prototype 段登记的形态约定优先于本节默认阶梯**（form: real-code | single-html；豁免须带 ruling 用户裁决留痕；多仓变更按触达子仓 repos override 优先——方案对比步须知会注入本仓登记态）。真码五要素：
+- **与实现同方言**：用项目真实前端栈构建——组件库/设计 token/样式从项目源码或 node_modules 真实引入（例：React 项目挂真实组件而非仿制标签、Vue 项目用真实 SFC；例词非封闭清单），不手搓仿制样式；**把 token 数值抄进自定义 CSS 变量＝复刻≠引入，仍属手搓仿制**（2026-10-15 knowledge-search 实证误读）
+- **可复跑**：能被本项目工具链跑起来（dev server / 组件文档页 / 构建产物均可，入口 HTML 从本地 node_modules 引真实库也行）——先查 scan 文档与现有前端代码就近发现项目原型管线，已有则复用；**历史原型先例同为单文件不构成管线存在**（51 个手绘先例是惯例债不是证据）；查无真码管线时**先单开一个轻量变更搭最小入口**（bootstrap 与业务变更分离），本变更按登记形态或降级声明执行
+- **高保真＝组件即实现原料，不是「看起来像」**：布局/组件/交互按真实效果呈现，execute 阶段直接对照搬组件，不经过"看图重新翻译"；**生成档输出必带素材来源声明**（真值 token 源文件路径 / 组件来源 / 入口位置——缺声明＝无源可查，2026-10-15 server-logs-panel 实证零声明）
 - **手绘单文件（自造样式）仅限一次性粗选对比，不得作为定稿原型**（frontend-apple-style 实证：手绘定稿后每条意见都要反向翻译回真实代码）；粗选定了方向，升级真码再收口
 - **例外与降级**：项目本身即单文件 HTML 方言（纯静态站）时单文件即真码，不适用手绘限定；无法同方言真码化（如目标平台无 HTML 运行面）时显式声明降级与理由请用户裁决留痕——静默降级会被收口「UI 视觉证据」探针拦下
 
@@ -284,7 +314,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句中文概括（
 - 原型生成、复用登记或跳过声明必须在暂停**之前**完成（复用登记＝原型文件已按 \`prototype-<名称>.html\` 落在变更目录）——暂停是本步骤最后动作，用户确认后直接进入写 design.md，不会回头补
 
 ### 输出
-完整设计方案 + 变更名 + 原型文件路径 或 复用声明（来源+覆盖面+登记后路径）或 跳过原因（三选一必填；跳过时写明分级依据，用户可当场否决要求补）
+完整设计方案 + 变更名 + 原型文件路径 或 复用声明（来源+覆盖面+登记后路径）或 跳过原因（三选一必填；跳过时写明分级依据，用户可当场否决要求补） + **「我替你做的决定」节**（source≠user 的 D-xxx@vN 逐条；无则写明）
 
 ### 注意
 - 不要一次输出大段文字，按模块/Phase 分段
@@ -478,6 +508,20 @@ ${REVIEW_CHECKLISTS.brainstorm.slice(3).map((item) => '- ' + item).join('\n')}
    - P0/P1 未决项必须进入 Unresolved Blockers，不能带着进入 plan。
 4. 用户回答后，更新 design.md 和 decisions.md；如果推翻旧决策，新增版本 D-xxx@v2，而不是覆盖 D-xxx@v1。
 
+### 实现者视角追问（builder check——与上方交叉审查并行执行，不替代它）
+交叉审查问「文档自身矛盾吗」；本节问「照这份文档，我能建出它吗」。两问正交，都要做（tier=self 时你依次自问两遍并分节输出）：
+- **tier=independent（S2/S3）**：把下列四要素追加进审查子代理的派发 prompt（作为同一子代理的第二项任务，不额外计请求预算）：
+  - 你是一位有才华的 [领域] 工程师，被交予本设计文档，要据此制定实现计划，**你联系不到写文档的人**
+  - 只报告你「必须被回答、否则得靠猜、而猜错会出事」的问题；每条附「为什么答案会改变产物」，按重要性排序
+  - 跳过：文档已显式留给实现者的部分、你自己能合理决定的、措辞挑刺
+  - 没有重要问题 → 回答 \`nothing important left\`
+  - 写成 review.json 的 \`reviewerNotes\` 一节：\`## 实现者视角追问\` + 逐条问题与理由（**不新增 schema 字段**——去向钉在现有 reviewerNotes，Stage Review Gate 照常读）
+- **tier=self（S0/S1）**：以实现者身份快读一遍 design.md，同样三个跳过条件，输出「实现者视角追问」小节（可空 = nothing important left）
+- **回收分三堆**（两档都适用）：
+  1. **文档/对话已答** → 把答案补进 design.md 对应章节，不改决策
+  2. **minor（不改变产物的猜测点）** → 你自己定，按决策记录格式落 decisions.md 并标注「我的判断」
+  3. **只有用户能答且会改变产物** → 进「对话式探索」的收尾一轮（一次性问完，不做第二轮）；无法回退到前一步时挂 Unresolved Blockers
+
 ### decisions.md 版本规则
 \`\`\`markdown
 ## D-001@v2: 缓存异常时的 fallback 语义
@@ -514,6 +558,12 @@ status: passed | needs-user-input | blocked | skipped
 | needs_thinking | N | 需要用户判断 |
 | unresolved | N | 真正设计漏洞 |
 
+## 实现者视角追问
+（四要素口径；无重要问题写 "nothing important left"）
+| ID | 问题 | 为什么答案会改变产物 | 分堆（已答/我的判断/需用户） |
+|---|---|---|---|
+| B-001 | ... | ... | ... |
+
 ## Unresolved Blockers
 | ID | priority | 问题 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|
@@ -521,6 +571,7 @@ status: passed | needs-user-input | blocked | skipped
 
 ### 铁律 — 等待用户
 - 发现 P0/P1 结构性矛盾且需要用户判断时，暂停等用户（命令由 CLI 在下方注入）
+- 「只有用户能答且会改变产物」的问题（本步交叉审查 + 实现者视角追问合计）攒成**一轮**问完即止，不做第二轮
 - 用户显式跳过时必须在 decisions.md 记录 accepted risk；P0/P1 skip 仍必须写入 Unresolved Blockers
 - 完成前必须确认没有 P0/P1 unresolved blocker，否则不能进入 plan。`,
       outputHint: 'Design Grill 交叉审查结果',

package/src/stages/plan-postcheck.js

@@ -88,9 +88,14 @@ export function parseAllowedPaths(content) {
     // 剥首尾成对反引号（坑7 家族：`src/a.js` 整项以反引号开头时 js-yaml/正则路径带 ` 匹配失败报未覆盖；
     // 与 change-list.js 的 cell 归一化同语义——剥两端包裹引号，不动路径内部字符）
     return blockMatch[1].match(/[ \t]*-[ \t]+(.+)/g)?.map(s => {
-      const raw = s.replace(/^[ \t]*-[ \t]+/, '').trim()
+      let raw = s.replace(/^[ \t]*-[ \t]+/, '').trim()
+      // 双横线归一化（2026-10-15-zcode-engine-appserver 归档期实证：手编辑残留 "-   - path"
+      // 嵌套子弹，剥一层外子弹后仍带 "- " 前缀 → 幽灵路径进 allow 面 → apply 越权误拦）。
+      // 循环剥除连续子弹前缀（"- " / "-   " 等任意空白形态）。
+      while (/^-[ \t]+/.test(raw)) raw = raw.replace(/^-+[ \t]+/, '').trim()
       return raw.replace(/^`([^`]*)`$/, '$1').replace(/^['"]|['"]$/g, '').trim()
-    }).filter(Boolean) || []
+    }).filter(Boolean)
+      .filter((v, i, arr) => arr.indexOf(v) === i) // 去重（同卡重复条目不产生重复 allow 项）
   }
   return []
 }
@@ -2308,6 +2313,12 @@ async function executePlanPostcheckRun(context, { autoAdoptBudget = 0 } = {}) {
   const miGen = await generatePlanModuleImpactFirstVersion(changeDir, cwd, specRoot)
   if (miGen.status === 'generated') {
     console.log(`  ✅ module-impact.md 首版已由 CLI 自动生成（归类 ${miGen.matchedCount} 个文件，未匹配 ${miGen.unmatchedCount} 个；影响类型列由 execute/verify 回填）`)
+  } else if (miGen.status === 'skipped' && (miGen.reason === 'no-module-map' || miGen.reason === 'no-declared-files')) {
+    // 坑 plan-module-impact-autogen-missing（2026-10-14 实证：指引说勿手写等 CLI 生成，
+    // 无 module-map/无声明清单时静默 skip → gate 报缺失空转两轮）。非 small 变更在此显式
+    // 告知生成前提缺失 + 逃生口径，agent 不再靠 gate 撞墙才知道。
+    console.warn(`  ⚠️ module-impact.md 首版未能自动生成（${miGen.reason === 'no-module-map' ? '本仓无 .sillyspec/docs/<项目>/modules/_module-map.yaml 模块图' : 'design.md 文件变更清单 main 段无声明文件'}）——gate 仍要求该文件在场`)
+    console.warn('     逃生口径：按 gate 模板手写骨架（章节标题逐字「## 模块影响矩阵」「## 未匹配文件」+「## 更新结果」表骨架 pending，execute/verify 回填），或先跑 sillyspec run scan 建模块图')
   }
 
   // ── 1e. 阶段完成产物校验（plan stage contract）──