sillyspec 3.27.1 → 3.27.2

package/src/change-list.js

@@ -18,6 +18,22 @@ export function normalizePath(raw) {
     .trim()
 }
 
+/**
+ * 组合路径单元格拆分（坑 design-combined-cell-mismatch，2026-08-22 实证："router.py + service.py"
+ * 一行两文件整体当单路径，字面匹配对账不过）。拆分符：+ 、 ／ | ; ；——每 token 独立校验
+ * （looksLikePath 不过的丢弃，防自由文本混入）；无分隔符返回单元素数组（零变化）。
+ * 不含空白要求（"a.py+b.py" 与 "a.py + b.py" 都拆）。
+ * @param {string} cell 路径单元格（normalizePath 后）
+ * @returns {string[]}
+ */
+function splitCombinedPaths(cell) {
+  const raw = String(cell || '').trim()
+  if (!raw) return []
+  const tokens = raw.split(/\s*[+|；;、]\s*|／/).map(t => t.trim()).filter(Boolean)
+  const valid = tokens.filter(t => !isPlaceholder(t) && looksLikePath(t) && !t.startsWith('.sillyspec/'))
+  return valid.length > 0 ? valid : (looksLikePath(raw) ? [raw] : [])
+}
+
 /**
  * glob → 正则：双星（globstar）跨零或多段目录（含零段，bash 语义）、
  * 单星 → 单段（[^/]*）、问号 → 单字符（[^/]），其余转义。
@@ -226,8 +242,12 @@ function _parseFileListDetailed(designMdPath, { keepSillyspecDocs = false } = {}
       // incidental：说明列（非路径列的所有 cell）+ 路径 cell 原始值（剥注释前的括号内容）
       const incidental = cells.some((c, i) => i !== pathColIdx && INCIDENTAL_RE.test(c))
         || INCIDENTAL_RE.test(cells[pathColIdx] || '')
-      if (listMode === 'exclude') { entries.delete(filePath); continue }
-      entries.set(filePath, { path: filePath, operation, incidental })
+      // 组合路径单元格拆分（坑 design-combined-cell-mismatch，2026-08-22 实证：单元格写
+      // "router.py + service.py" 一行两文件——整体当单路径字面匹配对账不过，逼文档写法服务
+      // 校验器）。拆分符：+ / ／ / | / 、 / ; / ；——每个 token 独立过校验入表；单路径零变化。
+      const pathTokens = splitCombinedPaths(filePath)
+      if (listMode === 'exclude') { for (const t of pathTokens) entries.delete(t); continue }
+      for (const t of pathTokens) entries.set(t, { path: t, operation, incidental })
       continue
     }
 

package/src/contract-matrix.js

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs'
 import { join, resolve, basename, relative } from 'path'
+import { gitQuiet } from './git-helper.js'
 import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
@@ -332,6 +333,43 @@ export function buildContractFieldInjection(changeDir, taskName) {
 
 // ─── Verify 阶段：parity check ──────────────────────────────────────────
 
+/**
+ * 取本变更 diff 文件集（parity 前端调用收窄用，坑 probe5-fullrepo-frontend-noise）。
+ * 优先 worktree meta 锚点 diff（与 verify 同源）；无 meta 退主仓 git diff HEAD。
+ * @returns {string[]|null}
+ */
+function _resolveDiffFilesForParity(scanRoot, changeName) {
+  try {
+    const metaPath = join(scanRoot, '.sillyspec', '.runtime', 'worktrees', changeName, 'meta.json')
+    if (existsSync(metaPath)) {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+      const diffBase = meta.baselineCommit || meta.actualBaseHash || meta.baseHash
+      const gitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+        ? meta.worktreePath : scanRoot
+      if (diffBase) {
+        const out = gitQuiet(gitDir, ['diff', '--name-only', `${diffBase}..HEAD`], { timeout: 30000 })
+        if (out !== null) {
+          const files = out.split('\n').filter(Boolean)
+          // 并入 worktree 未提交（子代理默认不 commit 的形态，与 resolveVerifyChangedFiles 同口径）
+          try {
+            const wtStatus = gitQuiet(gitDir, ['status', '--porcelain'], { timeout: 30000, trim: false })
+            for (const line of String(wtStatus || '').split('\n')) {
+              if (!line || line.length < 4) continue
+              const p = line.slice(3).trim().split(' -> ').pop() || ''
+              const clean = p.replace(/^"|"$/g, '')
+              if (clean) files.push(clean)
+            }
+          } catch {}
+          return [...new Set(files)]
+        }
+      }
+    }
+    // 无 meta（brownfield/已 cleanup）：主仓未提交 diff
+    const out = gitQuiet(scanRoot, ['diff', '--name-only', 'HEAD'], { timeout: 30000 })
+    return out !== null ? out.split('\n').filter(Boolean) : null
+  } catch { return null }
+}
+
 /**
  * verify 阶段执行 API parity check
  * @param {string} specBase - .sillyspec 目录
@@ -372,17 +410,63 @@ export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = nu
     return { ok: true, missingBackend: [], unusedBackend: [], summary: 'No scan root for parity check', backendCount: allProviderEndpoints.length, frontendCount: 0 }
   }
 
-  const frontendCalls = scanFrontendApiCalls(scanRoot)
-  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, allProviderEndpoints)
+  // ── 现算端点并入基线（坑 probe5-endpoint-baseline-stale，2026-08-22 实证：endpoints 基线
+  // 是 execute 时落的存量 artifacts，verify 时主仓已被并行会话/部署扰动推进——存量基线与当前
+  // 代码失配 → 前端调用（当前代码）对不上旧端点集 → missingBackend 全量误报。现算当前代码的
+  // 后端端点并入比对集：missingBackend 判定以「当前真实代码 ∪ 存量基线」为准（现算覆盖大部分、
+  // 存量补充跨仓/已删代码）；unusedBackend 只对现算端点算（存量过期端点不再误报 unused）。
+  let liveEndpoints = []
+  try { liveEndpoints = scanBackendEndpoints(scanRoot) } catch { /* 现算失败退回纯存量基线 */ }
+  const liveKeys = new Set(liveEndpoints.map(e => `${e.method} ${e.path}`))
+  const mergedProviderEndpoints = [...allProviderEndpoints]
+  for (const e of liveEndpoints) {
+    const key = `${e.method} ${e.path}`
+    if (!allProviderEndpoints.some(p => `${p.method} ${p.path}` === key)) {
+      mergedProviderEndpoints.push(e)
+    }
+  }
+
+  // ── 前端调用收窄到本变更 diff（坑 probe5-fullrepo-frontend-noise，2026-08-23 实证：
+  // 「全仓前端调用 × 本变更局部登记」口径下，未受本变更影响的存量调用对不上局部端点集
+  // → 143 个 missing 全是误报噪音）。比对口径 = 本变更 diff 文件内的调用 ∪ 全仓（仅当
+  // 端点登记源也是全仓时——无 changeName 的 CLI contractScan 场景）。diff 不可得时退回
+  // 全仓（不静默跳过对账）。
+  let frontendCalls = []
+  let frontendScope = 'full-repo'
+  if (changeName) {
+    try {
+      const changed = _resolveDiffFilesForParity(scanRoot, changeName)
+      if (changed && changed.length > 0) {
+        const changedSet = new Set(changed.map(f => f.replace(/\\/g, '/')))
+        frontendCalls = scanFrontendApiCalls(scanRoot).filter(c => {
+          const src = String(c.source || '').replace(/\\/g, '/')
+          return changedSet.has(src) || [...changedSet].some(cf => src.endsWith(cf) || cf.endsWith(src))
+        })
+        frontendScope = `change-diff (${changed.length} files)`
+      } else {
+        frontendCalls = scanFrontendApiCalls(scanRoot)
+      }
+    } catch { frontendCalls = scanFrontendApiCalls(scanRoot) }
+  } else {
+    frontendCalls = scanFrontendApiCalls(scanRoot)
+  }
+
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, mergedProviderEndpoints)
+  // unusedBackend 收窄到现算端点（存量 artifact 的过期端点不参与——它不在当前代码里，
+  // 「前端未调用」可能是端点已被重构掉而非真泄漏）
+  const narrowedUnused = unusedBackend.filter(u => {
+    const key = `${u.method} ${u.path}`
+    return liveKeys.has(key) || liveEndpoints.length === 0
+  })
 
   const ok = missingBackend.length === 0
   let summary = ok
-    ? `✅ API parity check passed: ${allProviderEndpoints.length} backend endpoints, ${frontendCalls.length} frontend calls`
-    : `❌ API parity check failed: ${missingBackend.length} frontend calls have no matching backend endpoint`
+    ? `✅ API parity check passed: ${mergedProviderEndpoints.length} backend endpoints (live ${liveEndpoints.length} + artifact ${allProviderEndpoints.length}), ${frontendCalls.length} frontend calls [scope: ${frontendScope}]`
+    : `❌ API parity check failed: ${missingBackend.length} frontend calls have no matching backend endpoint [scope: ${frontendScope}]`
 
-  if (unusedBackend.length > 0) {
-    summary += ` | ${unusedBackend.length} backend endpoints unused by frontend`
+  if (narrowedUnused.length > 0) {
+    summary += ` | ${narrowedUnused.length} backend endpoints unused by frontend`
   }
 
-  return { ok, missingBackend, unusedBackend, summary, backendCount: allProviderEndpoints.length, frontendCount: frontendCalls.length }
+  return { ok, missingBackend, unusedBackend: narrowedUnused, summary, backendCount: mergedProviderEndpoints.length, frontendCount: frontendCalls.length }
 }

package/src/index.js

@@ -85,6 +85,7 @@ SillySpec CLI — 规范驱动开发工具包
   sillyspec config cat [--json]           读取 local.yaml 实际内容（自动定位真实路径，worktree 内解析到主仓）
   sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
   sillyspec dispatch <probe | hint>       SillyHub 派发能力探测 + 策略生成（agent 调用桥，仅渲染不执行 tool）
+  sillyspec agent-log [--detect] [--json]  本地 agent 会话日志查询/现场探测（run 命令自动上报平台 POST /api/agent-logs 并本地留底）
 
   sillyspec workflow check <name> [--project <p>] [--change <c>] [--json] [--save]
                                       全局 workflow 校验（--save 归档到 .sillyspec/.runtime/workflow-runs/）
@@ -1843,6 +1844,13 @@ SillySpec worktree — git worktree 隔离管理
       }
       break;
     }
+    case 'agent-log': {
+      // 本地 agent 会话日志路径查询/探测（平台会话解析入口）：读 <runtimeRoot>/agent-session-log.json
+      //（run 命令在 agent 环境内自动登记），--detect 现场探测不落盘。协议见 docs/platform-agent-log-protocol.md。
+      const { cmdAgentLog } = await import('./agent-session-log.js');
+      await cmdAgentLog(filteredArgs.slice(1), { json, cwd: dir, specDir });
+      break;
+    }
     case 'dispatch': {
       // SillyHub 派发抽象层的 agent 调用桥（design.md §Phase2 / D-007@v1）：
       // 仅做能力探测（probe）与派发策略生成（hint），**不执行任何 tool 调用**——
@@ -2696,6 +2704,7 @@ SillySpec config — local.yaml 配置键速查
         'quick-guard.json': 'quick baseline 守卫（旧位置）',
         'worktrees': 'worktree meta（hooks 侧）',
         'user-inputs.md': '步骤输出/输入历史追加日志',
+        'agent-session-log.json': '本地 agent 会话日志登记留底（run 命令自动 REST 上报平台 POST /api/agent-logs，见 docs/platform-agent-log-protocol.md）',
         'current-quick-run-id': '当前 quick sessionId 指针（--done 无 --change 时 fallback）',
         'scan-runs': '平台模式 scan/workflow 取证目录',
         'artifacts': '派生产物目录（init 预建）',
@@ -2733,7 +2742,7 @@ SillySpec config — local.yaml 配置键速查
       break;
     }
     default: {
-      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
+      const topCommands = ['init', 'setup', 'run', 'progress', 'worktree', 'dispatch', 'agent-log', 'local', 'workflow', 'gate', 'derive', 'backfill-reviews', 'register-stage-review', 'modules', 'change-rename', 'knowledge', 'platform', 'scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore', 'status', 'doctor', 'auto', 'runtime'];
       const suggestion = didYouMean(command, topCommands);
       console.error(`❌ 未知命令: ${command}`);
       if (command === '--status') {

package/src/quicklog.js

@@ -265,10 +265,18 @@ export function deriveTitleFromLinkedChange(specBase, change) {
     try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
     const m = content.match(/^#\s+(.+?)\s*$/m)
     if (!m) continue
-    const raw = m[1].trim()
-    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    let raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc。
+    // 固定前缀显式剥（坑 linked-task-placeholder-title，2026-08-22 实证：标题「# 提案书（Proposal）:
+    // xxx」或「# 提案书（Proposal）」无破折号时 dash 匹配失败，整串前缀落进 tasks.md 追加行）——
+    // 先剥固定模板词（含全/半角冒号分隔形态），再剥破折号；剥完为空（纯模板标题）继续找下一文档
+    for (const prefix of [/^提案书（Proposal）\s*[：:—\-]?\s*/, /^设计文档（Design）\s*[：:—\-]?\s*/, /^Proposal\s*[：:—\-]?\s*/i, /^Design\s*[：:—\-]?\s*/i]) {
+      raw = raw.replace(prefix, '').trim()
+    }
+    if (!raw) continue
     const dash = raw.match(/[—-]\s*(.+)$/)
-    return dash ? dash[1].trim() : raw
+    const title = dash ? dash[1].trim() : raw
+    if (title) return title
   }
   return ''
 }

package/src/run/command.js

@@ -163,6 +163,9 @@ sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${
  * sillyspec run <stage> 主命令
  */
 export async function runCommand(args, cwd, specDir = null, opts = {}) {
+  // 原始 cwd 快照（下方 cwd 纠正前）：agent 在子目录启动时，其会话 transcript 挂在子目录
+  // 对应的 harness 项目目录下，agent-log 探测须用原始 cwd（纠正后的是项目根，探测会扑空）
+  const invokedCwd = cwd
   // W1-B: run <stage> 暂不支持 --json。之前 --json 进 knownFlags 白名单却从不读取（静默吞），
   // agent 按 gate/derive 契约期望 envelope 实则拿到混合人类文本。显式 fail-fast 杜绝歧义；
   // 完整 run envelope 待 outputStep 重构（W6）后支持（prompt + nextAction 结构化）。
@@ -366,6 +369,29 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // let：下方 worktree 副本漂移守卫命中时锚回 wt.mainSpecBase（task-05/D-03）
   let specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
 
+  // ── 本地 agent 会话日志登记 + 上报（平台会话展示用，best-effort）──
+  // 平台/daemon 模式下 SillyHub 只能看到 CLI 阶段信息，看不到本地 agent 的实际执行日志。
+  // 在此探测当前 agent 环境（Claude Code / Codex / ZCode transcript / SILLYSPEC_AGENT_LOG
+  // 覆盖），把日志本地路径登记进 <runtimeRoot>/agent-session-log.json（留底）并立即
+  // REST 上报平台（POST /api/agent-logs，与进度上报同风格；协议见
+  // docs/platform-agent-log-protocol.md）。探测不到不发不写；任何失败只 warn 一行，
+  // 绝不阻断 run 主流程。
+  try {
+    const { recordAgentLogInvocation } = await import('../agent-session-log.js')
+    const r = await recordAgentLogInvocation({
+      cwd,
+      invokedCwd,
+      platformOpts,
+      specBase,
+      // 只记 flag 名不记值（--output 等 flag 值是 agent 工作文本，不进产物）
+      command: [stageName, ...flags.filter(t => typeof t === 'string' && t.startsWith('--'))].join(' '),
+    })
+    if (r && r.isNew && r.latestLogPath) {
+      const pushNote = r.pushed === true ? '已上报平台' : r.pushed === false ? '上报失败（本地已留底）' : '本地留底'
+      console.log(`📄 本地 agent 日志已登记（${pushNote}）: ${r.latestLogPath}`)
+    }
+  } catch { /* best-effort：登记失败不影响 run 主流程 */ }
+
   // 漂移提醒:cwd 祖先链 ≥2 个 .sillyspec = monorepo 多实例,当前命中的「最近」实例
   // 可能不是用户意图的项目(如 cd 进被独立 scan 的子项目跑测试后忘回根)。
   // 平台模式 / 显式 --spec-dir 跳过(已明确指定,无歧义)。仅提醒不阻断。
@@ -1076,6 +1102,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     progress = pm.read(cwd, effectiveChange) || progress
   }
 
+  // --file-notes 非末步静默忽略前置 warn（坑 quick-file-notes-nonfinal-ignored，2026-08-22 实证：
+  // step2 --done 传 --file-notes 被静默丢——CLI 短进程，注入随进程结束即丢，白传一轮）。
+  // 放此处：ensureStageSteps 之后 progress 已就绪可判步骤状态；仅 quick + 带了 --file-notes +
+  // 非「唯一 pending 的末步 --done」时提示。末步 --done 是消费点，不提示。
+  if (quickFileNotes !== '' && stageName === 'quick' && !isStatus) {
+    try {
+      const qSteps = progress?.stages?.quick?.steps
+      const pendingCount = Array.isArray(qSteps) ? qSteps.filter(st => ['pending', 'in-progress'].includes(st?.status)).length : 0
+      if (!isDone || pendingCount > 1) {
+        console.warn(`⚠️ --file-notes 本次不会生效：它只在 quick 末步（暂存和更新记录）--done 时随收尾消费——CLI 是短进程，本次注入随进程结束即丢。请在末步 --done 时连同 --output 一起传。`)
+      }
+    } catch { /* 判定失败不提示（fail-open） */ }
+  }
+
   // --status
   if (isStatus) {
     // D9：状态展示末尾附「下一步该跑什么」。pm 持有状态机，按 progress 实际进度算出精确命令；

package/src/run/complete.js

@@ -167,6 +167,38 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
       steps[_staleIdx].status = 'pending'
       currentIdx = _staleIdx
       console.log(`⚠️  --confirm 收尾：把 stale 步骤 "${steps[_staleIdx].name}" 拉回当前步骤走完成管线，其余 stale 由回填门控一并确认。`)
+    } else if (stageData?.status !== 'completed' && steps.length > 0) {
+      // ── 矛盾态自愈（坑 execute-status-machine-contradiction，2026-08-23 实证：--done 报
+      // 「没有待完成的步骤」而 status 显示 15 步未完成——并发进程写入竞争后 DB 步骤行停在
+      // completed 但阶段 status 未推进的矛盾态，用户只能靠 verify 启动碰运气自愈）。
+      // 自愈 = 重播种：ensureStageSteps 按 def 步骤名重建步骤行（保留同名完成态），矛盾行
+      // （DB 有但 def 无的幽灵行/半写行）被清掉；重读后再走正常管线。自愈失败再报错给精确指引。
+      console.warn(`⚠️ 检测到状态机矛盾：阶段 ${stageName} 无 pending/in-progress 步骤但 status=${stageData.status}（并发写入竞争的半写态）。自动重播种修复…`)
+      try {
+        const { ensureStageSteps } = await import('./command.js')
+        const reseeded = await ensureStageSteps(progress, stageName, cwd, platformOpts?.specRoot || null)
+        if (reseeded && effectiveChange) {
+          pm._write(cwd, progress, effectiveChange)
+          progress = pm.read(cwd, effectiveChange) || progress
+        }
+        const freshSteps = progress?.stages?.[stageName]?.steps || []
+        const freshPending = freshSteps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+        if (freshPending !== -1) {
+          console.log(`✅ 重播种成功：${freshSteps.filter(s => s.status === 'pending').length} 个待完成步骤恢复，继续完成管线`)
+          currentIdx = freshPending
+          steps.length = 0
+          steps.push(...freshSteps)
+          stageData.steps = freshSteps
+        } else {
+          console.error(`重播种后仍无待完成步骤（阶段 status=${progress?.stages?.[stageName]?.status ?? '未知'}）。`)
+          console.error(`   手动修复：sillyspec run ${stageName} --reset${changeName ? ` --change ${changeName}` : ''} 从头重跑，或 sillyspec doctor 诊断。`)
+          process.exit(1)
+        }
+      } catch (e) {
+        console.error(`❌ 矛盾态自愈失败: ${e.message}`)
+        console.error(`   手动修复：sillyspec run ${stageName} --reset${changeName ? ` --change ${changeName}` : ''}，或 sillyspec doctor`)
+        process.exit(1)
+      }
     } else {
       console.error(`没有待完成的步骤（阶段 ${stageName} 已无 pending/in-progress 步骤）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
       process.exit(1)
@@ -679,7 +711,12 @@ async function autoCheckPlanFromReviews({ stageName, changeName, cwd, platformOp
     return { autoChecked: false, checkedCount: 0, skippedCount: 0 }
   }
   try {
-    const specBaseLc = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    // 勾选写入目标漂移锚定（坑 autocheck-worktree-tasks-lost，2026-08-23 实证：agent 在
+    // worktree 内跑 execute --done 且 drift 守卫未拦（非平台模式+无 specDriftAnchor 透传的
+    // 直调路径）时，tasks.md 勾选写进 worktree 的 .sillyspec/changes/ 副本——worktree 被
+    // cleanup 整目录删除后勾选丢失，主仓 tasks.md 停在未勾态需手动补。runtimeRoot 已走
+    // resolveRuntimeRoot（drift-aware），changeDir 同步对齐：specDriftAnchor > specRoot > cwd。
+    const specBaseLc = platformOpts?.specDriftAnchor || platformOpts?.specRoot || join(cwd, '.sillyspec')
     const changeDir = join(specBaseLc, 'changes', changeName)
     // 2026-08-20-task-truth-unify D-001@v1：勾选写入目标从 plan.md 迁 tasks.md（任务唯一真相；
     // plan.md Wave 引用行无 checkbox，无处可勾）。tasks.md 存在性作前置。

package/src/run/quick-audit.js

@@ -35,6 +35,13 @@ export function printQuickAuditReview(review) {
       console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
       console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
       console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件；--allow-delete 允许删除文件）`)
+      // 两套开关明示（坑 files-flag-not-unlock-protected，2026-08-22 实证：模块文档被判危险
+      // 文件，追加 --files 边界不解锁仍被拦——「追加边界」与「解锁拦截」是两套开关，交互上易误解
+      // 前者能解决后者）。命中危险文件 reason 时点名：--files 只改归属口径（哪些文件计入本
+      // 会话），不改变危险判定；受保护/危险文件的放行开关唯 --force-baseline。
+      if (review.reasons.some(r => r.startsWith('危险文件变更'))) {
+        console.error(`   ⛔ 注意：追加 --files 边界不会解锁受保护/危险文件的拦截（两套开关——--files 只声明哪些文件计入本会话，不改变危险判定）。改这类文件必须 --force-baseline。`)
+      }
     }
   } else if (review.status === 'warning') {
     console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
@@ -51,6 +58,16 @@ export function printQuickAuditReview(review) {
       console.log(`\n✅ quick 变更边界审计 — SAFE (本轮新增变更 ${review.changedFiles.length} 个文件)`)
     }
   }
+  // 关联变更遗留放行提示（坑 linked-change-leftover-false-block，独立于三态都打——放行可见
+  // 可审计，不静默）：这些文件属关联变更目录但不在本会话归属（启动后出现的他者遗留），
+  // 已剔除出本会话文件行，由关联变更自己的流程收尾。
+  if (Array.isArray(review.linkedChangeLeftovers) && review.linkedChangeLeftovers.length > 0) {
+    console.warn(`
+🧹 关联变更目录检测到 ${review.linkedChangeLeftovers.length} 个遗留脏文件（他者/上个 session 残留，非本会话改动）——已放行不计入本会话：`)
+    for (const f of review.linkedChangeLeftovers) console.warn(`   - ${f}`)
+    console.warn(`   它们归关联变更自己的流程管；若确系本会话需要改，用 --files 显式声明归属。`)
+  }
+
   // D-8 文档欠账显性化（advisory，独立于 status 三态都打）：改了源码没动文档 → 一行欠账标记。
   // 不阻断、不解锁、纯显性化——累积欠账可事后审计 QUICKLOG reasons 追溯。
   if (review.docSyncHint && review.docSyncHint.touchedSource > 0 && review.docSyncHint.docFiles.length === 0) {

package/src/run/shared.js

@@ -902,10 +902,26 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
 
       // 检查危险文件（除非 force-baseline）
       if (file.startsWith('.sillyspec/') && !isQuickMetadata(file, guard.linkedChanges) && !forceBaseline) {
+        // 关联变更目录遗留放行（坑 linked-change-leftover-false-block，2026-08-22 实证：并发下
+        // 关联变更目录里他者/上个 session 的遗留脏文件——审计时不在本会话 baseline（启动后出现）
+        // 且 isQuickMetadata 对关联变更目录不豁免 → 落「危险文件」blocked，只能 --force-baseline。
+        // quick 无法区分「他者遗留」与「本次偷改」，按用户裁决放行降 warning：完全剔除出本会话
+        // 归属（changedFiles/newFiles/deletedFiles 均退栈），不计文件行、不触发危险/新增/越界
+        // 三道门，遗留给关联变更自己的流程收尾。非关联的 .sillyspec/ 仍 blocked。
+        const linkedDir = (Array.isArray(guard.linkedChanges) ? guard.linkedChanges : [])
+          .find(lc => file.startsWith(`.sillyspec/changes/${String(lc).replace(/\\/g, '/')}/`))
+        if (linkedDir) {
+          result.changedFiles.pop()
+          if (status === '??') result.newFiles.pop()
+          if (rawStatus[0] === 'D' || rawStatus[1] === 'D') result.deletedFiles.pop()
+          result.linkedChangeLeftovers = result.linkedChangeLeftovers || []
+          result.linkedChangeLeftovers.push(file)
+          continue
+        }
         result.reasons.push(`危险文件变更: ${file}`)
       }
 
-      if (DANGEROUS_PATTERNS.some(p => file === p || file.startsWith(p)) && !forceBaseline) {
+      if (DANGEROUS_PATTERNS.some(p => p === file || file.startsWith(p)) && !forceBaseline) {
         result.reasons.push(`危险文件变更: ${file}`)
       }
     }
@@ -1069,6 +1085,13 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
           console.warn(`   - ${f}`)
           console.warn(`     分离：git add -p ${f}（交互选你的 hunk）或 git diff ${f} > mine.patch（编辑留你的）+ git apply --cached mine.patch`)
         }
+        // 宽严差异明示（坑 concurrent-policy-inconsistency，2026-08-22 实证：quick 同文件并发只
+        // warn 不阻断、plan 阶段同 Wave 同文件却硬拦——两阶段宽严不一致易误判边界）。差异是设计
+        // 使然：quick 是轻量流程无子代理并行，同文件并发最坏后果是 commit 夹带他者 hunk（git 可
+        // 分离，提示分离命令即可）；plan 的同 Wave 同文件会让 execute 的并行子代理互相覆盖（不可
+        // 自动恢复），必须设计期硬拦。
+        console.warn(`   ℹ️ 边界说明：quick 对同文件并发只提示不阻断（最坏后果=commit 夹带他者 hunk，git 可分离）；`)
+        console.warn(`      plan 阶段同 Wave 同文件是硬错误（execute 并行子代理会互相覆盖，不可自动恢复）——两阶段宽严不同是设计使然，勿以 quick 的宽松推断 plan 的边界。`)
       }
     }
 

package/src/run/stage.js

@@ -162,6 +162,29 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     } catch { /* 预警失败不阻断 execute */ }
   }
 
+  // ── 共享主仓竞态防护（坑 parallel-shared-main-race，2026-08-23 实证：并行会话共享主仓
+  // 工作区/共享部署库的竞态——文件被清、alembic 被推进、staged 混入他者文件）。execute/verify
+  // 启动时探测三类信号并 advisory（不阻断——并发是合法工作模式，但要让 agent 知道环境在变）：
+  //   1. 主仓未提交改动中含非本变更文件（staged 混入：commit 时注意 pathspec）
+  //   2. worktree 存在时 base..HEAD 主仓推进（主仓在他者 apply 后已前进，diff 口径注意）
+  // best-effort：异常静默。
+  if ((stageName === 'execute' || stageName === 'verify') && changeName) {
+    try {
+      const mainDirty = (safeGit(cwd, ['status', '--porcelain'], { trim: false }).value || '')
+        .split('\n').filter(Boolean).map(l => l.slice(3).trim().split(' -> ').pop() || '')
+        .map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/'))
+        .filter(p => p && !p.startsWith('.sillyspec/'))
+      const myFiles = (await import('../verify-postcheck.js')).resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true }) || []
+      const mySet = new Set(myFiles.map(f => f.replace(/\\/g, '/')))
+      const foreign = mainDirty.filter(p => !mySet.has(p))
+      if (foreign.length > 0) {
+        console.warn(`⚠️ 主仓含 ${foreign.length} 个非本变更的未提交文件（并行会话工作/部署产物混入）——`)
+        console.warn(`   提交时用精确 pathspec（勿 git add -A / 目录级 add 夹带）：${foreign.slice(0, 4).join(', ')}${foreign.length > 4 ? ` …` : ''}`)
+        console.warn(`   交接物核对（文件被清/迁移被推进类异常）先确认是否他者会话所谓，再判定本变更问题。`)
+      }
+    } catch { /* 探测失败不阻断 */ }
+  }
+
   // 自动探测 currentChange
   if (autoDetectChange(progress, cwd)) {
     progress.lastActive = new Date().toLocaleString('zh-CN', { hour12: false })

package/src/stages/execute.js

@@ -1143,6 +1143,7 @@ ${taskList}
    - 最后一个 Wave 完成后做一次全量编译验证
    - 用户明确要求编译时
 4. 每个任务完成后：
+   - **在 worktree 内 git add -A && git commit -m "<task-NN 摘要>"**（坑 subagent-uncommitted-newfile-apply3way，2026-08-22 实证：纯新增文件不 commit 时 apply 的 git apply --3way 报 "does not exist in index" 直接炸——未 commit 的新文件不在 base commit 也不在 index，patch 生成取不到。commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点）
    - **先写 review.json 再勾选 checkbox**（见下方 Task Review Gate）
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）
    - 记录改动文件和测试结果

package/src/stages/plan-postcheck.js

@@ -448,7 +448,9 @@ export function validateBlueprintConsistency(changeDir) {
       if (ts.length > 1) {
         errors.push(
           `路径 ${p} 被 Wave ${w} 内 ${ts.length} 个 task 修改: ${ts.join(', ')} — 同 Wave 任务 execute 强制并行（execute.js:603），` +
-          `子代理会互相覆盖该文件。解法：把它们拆到不同 Wave（串行）。`
+          `子代理会互相覆盖该文件。解法：把它们拆到不同 Wave（串行）。` +
+          `（注：quick 阶段对同文件并发只提示不阻断——那是轻量流程无并行子代理、最坏后果 git 可分离；` +
+          `此处硬拦是因并行覆盖不可自动恢复，两阶段宽严不同是设计使然）`
         )
       }
     }

package/src/stages/plan.js

@@ -473,6 +473,9 @@ ${taskList}
 \`\`\`
 你是一个专注的 TaskCard 生成器。你的任务是为指定 batch 生成全部 TaskCard。
 
+## ⚠️ 格式形态（第一眼必读，坑 taskcard-body-section-rework）
+TaskCard 的契约字段全部在 **frontmatter**（首对 --- 包裹的 YAML 键值对：id/title/title_zh/allowed_paths/goal/...）——**不是 body 章节**（## 标题下的段落）。goal 是 frontmatter 的 \`goal: >\` 多行标量、implementation/acceptance/verify/constraints 是 frontmatter 的列表项；写成 body 章节（\`## goal\` / \`## Goal\` 等）会三组校验全挂返工。先跑骨架命令再 Edit 填充，骨架即正确形态。
+
 ## 输入
 - 变更目录：${changeDir}
 - 当前时间：<now-datetime>（frontmatter 的 created_at 使用此值）

package/src/sync.js

@@ -783,6 +783,38 @@ export class SyncManager {
    * @param {{base_ts?: string|null, local_modified_ts?: string|null, platform_last_pushed_at?: string|null, platform_progress?: object|null}} info
    * @returns {string|null} 冲突文件路径（specDir 不可达返回 null）
    */
+  /**
+   * 六表内容比对（坑 pull-deploy-noise-conflict 自愈用）：本地 serializeForSync 快照与平台
+   * 拉回的 JSON 逐表深度比对，忽略时间戳/同步元数据列（last_active/last_synced_platform_ts/
+   * last_local_modified_ts/started_at/completed_at/pushed_at/checked_at/completed_at 等——部署
+   * 噪声重推会刷新这些列但内容不变）。任一实质差异 → false。
+   * @param {object} local - serializeForSync 输出
+   * @param {object} platform - 平台 GET progress JSON（serializeForSync 同构）
+   * @returns {boolean}
+   */
+  _progressContentEquals(local, platform) {
+    try {
+      const IGNORE_KEYS = new Set([
+        'last_active', 'last_synced_platform_ts', 'last_local_modified_ts',
+        'started_at', 'completed_at', 'pushed_at', 'last_pushed_at', 'created_at',
+        'deps_checked_at', 'checked_at', 'waited_at', 'completedat',
+      ]);
+      const strip = (v) => {
+        if (Array.isArray(v)) return v.map(strip);
+        if (v && typeof v === 'object') {
+          const out = {};
+          for (const [k, val] of Object.entries(v).sort()) {
+            if (IGNORE_KEYS.has(k)) continue;
+            out[k] = strip(val);
+          }
+          return out;
+        }
+        return v;
+      };
+      return JSON.stringify(strip(local)) === JSON.stringify(strip(platform));
+    } catch { return false }
+  }
+
   _writeConflictFile(changeName, info = {}) {
     const specDir = safePlatformSpecDir(this.cwd);
     if (!specDir) return null;
@@ -965,6 +997,28 @@ export class SyncManager {
           }
         } catch { /* 重读失败维持原判（fail-closed 到真冲突分支） */ }
       }
+      // ── 内容一致自愈（坑 pull-deploy-noise-conflict，2026-08-22 实证：并行会话部署扰动——
+      // 他机 push 了内容相同的进度（如重启/重部署触发重推），本地脏 + 平台 ts 更新 → 拉冲突落
+      // sync-conflict 文件需人工 resolve，但内容其实无分歧。比对平台 JSON 与本地 serializeForSync
+      // 的六表内容（忽略时间戳列），一致 → 跳过 import（本地为准）+ base_ts 推进到平台 ts——
+      // 与 resolve --keep-local 同语义，自动闭环。内容不同 → 真冲突，维持原判。
+      if (localDirty && platformNewer && platformProgress) {
+        try {
+          const { ProgressManager } = await import('./progress.js');
+          const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+          const localSnapshot = pm.serializeForSync(this.cwd, changeName);
+          if (localSnapshot && this._progressContentEquals(localSnapshot, platformProgress)) {
+            try {
+              const db = pm._ensureDB(this.cwd).getDb();
+              db.prepare(
+                'UPDATE changes SET last_synced_platform_ts = MAX(?, COALESCE(last_synced_platform_ts, ?)) WHERE name = ?'
+              ).run(platformPushedAt, platformPushedAt, changeName);
+            } catch {}
+            debugLog(`[sync] pull 内容一致自愈: 平台 ts ${platformPushedAt} 为部署噪声重推（六表内容与本地一致），base_ts 已推进，不落冲突文件`);
+            return { ok: true, imported: false, conflict: false, reason: '平台重推内容与本地一致（部署噪声），base_ts 已推进' };
+          }
+        } catch { /* 比对失败维持原判（fail-closed 到真冲突分支） */ }
+      }
       if (localDirty && platformNewer) {
         console.warn('');
         console.warn('⚠️⚠️⚠️════════════════════════════════════════════════════');

package/src/worktree-deps.js

@@ -426,6 +426,18 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
       result.depsMethod = linkedModules[0].method;
       result.depsSource = 'main-checkout';
     }
+    // 子模块 link 后验证（坑 modules-submodule-link-verify，2026-08-23 实证：Windows 下漏链
+    // frontend node_modules——linkOneDir 报 linked 但 junction 实际未建或 main 侧本就没有）。
+    // linked 状态的子模块逐一核验 wt/<mp>/node_modules 实存：缺失降 failed 并给兜底指引
+    //（不静默放行——跑测试时才发现就晚了）。
+    for (const m of moduleResults) {
+      if (m.status !== 'linked') continue
+      const nmPath = join(worktreePath, m.path, 'node_modules')
+      if (!existsSync(nmPath)) {
+        m.status = 'failed'
+        m.error = `linked 后验证失败：${m.path}/node_modules 不存在（报成功但实际未落盘）。兜底：New-Item -ItemType Junction -Path "<wt>/${m.path}/node_modules" -Target "<主仓>/${m.path}/node_modules"`
+      }
+    }
     const failedModules = moduleResults.filter(m => m.status === 'failed');
     if (failedModules.length > 0) {
       const fmsg = failedModules.map(m => `${m.path}: ${m.error}`).join('; ');