sillyspec 3.28.6 → 3.28.8

package/src/scope-audit.js

@@ -19,6 +19,7 @@
  * 纯读：不落盘、不改 guard/进度库。Windows 路径 \\→/ 归一，ESM-only，零新依赖。
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { join, dirname } from 'node:path'
 import { locateQuickSessionGuard, auditQuickCompletion, resolveRuntimeRoot, collectOtherQuickSessionDeclarations, ancestorSpecDirs } from './run/shared.js'
 import { safeGit } from './git-helper.js'
@@ -41,7 +42,9 @@ function toPosix(p) {
 function extractRenameTarget(raw) {
   const brace = raw.match(/^(.*)\{([^{}]*)=>([^{}]*)\}(.*)$/)
   if (brace) {
-    const merged = brace[1] + brace[3] + brace[4]
+    // git 花括号形态 `src/{old => new}.js`：组3 带前导对齐空格须剥（审查 C-F03——
+    // 不剥则拼出 `src/ new.js` 键错，改名文件落 untracked wc-l 档记成整文件新增）
+    const merged = brace[1] + brace[3].replace(/^ /, '') + brace[4]
     return merged.replace(/\/{2,}/g, '/')
   }
   const arrow = raw.indexOf(' => ')
@@ -262,6 +265,21 @@ function filterPatchForFiles(patchText, filesSet) {
   return out.join('\n')
 }
 
+/**
+/** patch 内容 sha256（A-F01 防篡改锚——写入方存 json.patchSha256，读取方校验） */
+function sha256Text(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/**
+ * 冻结 patch 完整性校验（A-F01）：json 记录的 patchSha256 与 patch 实文比对。
+ * @returns {boolean|null} true=一致；false=不匹配（可能被篡改）；null=未记录 hash（旧记录）
+ */
+function verifyPatchIntegrity(recordedSha, patchText) {
+  if (!recordedSha || typeof recordedSha !== 'string') return null
+  return sha256Text(patchText) === recordedSha
+}
+
 /**
  * 冻结 patch 生成（quick-359a48f1 审计级 / quick-90015473 归属口径修正）：tracked 改动 =
  * `git diff --no-color <baseRef>` 后**按 files 过滤段**（与 rows 同归属口径，不含并行会话
@@ -438,8 +456,12 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
     }
   }
 
+  // 审查 C-F05：patch 文件集对齐落盘 rows（declared+soft）——undeclared 可能是并行会话的
+  // 改动，冻结进本会话审计 patch 违背 filterPatchForFiles 的归属契约（json rows 落盘时
+  // complete-handlers 滤 undeclared，patch 必须同口径）
+  const patchFiles = [...new Set([...attributed, ...softSet])]
   const frozenPatch = collectPatch
-    ? buildFrozenPatch(sessionRoot, rowFiles, { baseRef: 'HEAD' })
+    ? buildFrozenPatch(sessionRoot, patchFiles, { baseRef: 'HEAD' })
     : undefined
 
   return {
@@ -462,7 +484,7 @@ async function computeQuickAudit({ cwd, platformOpts, sessionId, located, collec
  * only；baseAnchor 缺失 → 行数按 HEAD 未提交窗口兜底（quick 模式同口径，不再恒 —）；
  * 归档且实时窗口空 → execute 时点快照记录态（快照也缺 → 空表诚实说明）。
  */
-async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, collectPatch }) {
+async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, collectPatch, freshActual }) {
   const sb = specBase || join(cwd, '.sillyspec')
   const runtimeRoot = resolveRuntimeRoot(platformOpts, sb)
   const changeDirInfo = resolveChangeDir(sb, changeName)
@@ -474,7 +496,30 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
   const hasWorktreeMeta = existsSync(join(sb, '.runtime', 'worktrees', changeName, 'meta.json'))
   const hasBranch = !!safeGit(cwd, ['rev-parse', '--verify', '--quiet', `sillyspec/${changeName}^{commit}`], { timeout: 15 * 1000 }).value
   const hasAuditTag = !!safeGit(cwd, ['rev-parse', '--verify', '--quiet', `sillyspec-audit/sillyspec/${changeName}^{commit}`], { timeout: 15 * 1000 }).value
-  if (!hasWorktreeMeta && !hasBranch && !hasAuditTag) {
+  // 审查 C-F02：预执行判定必须排除归档（归档=流程走完，58/77 归档变更三信号全缺被误判
+  // 「未执行」实证——tag 只在分支被 review 引用时才打）+ 补四类证据：快照文件本身 /
+  // execute-runs change 戳（task-review readExecuteRunChangeStamp 同口径）/ apply-pathspec /
+  // execute-cleanup 回执。任一命中 = 进过 execute。
+  const hasSnapshotFile = changeDirInfo
+    ? existsSync(join(changeDirInfo.dir, 'scope-audit.json')) || existsSync(join(runtimeRoot, `scope-audit-${changeName}.json`))
+    : existsSync(join(runtimeRoot, `scope-audit-${changeName}.json`))
+  const hasApplyPathspec = existsSync(join(runtimeRoot, `apply-pathspec-${changeName}.txt`))
+  const hasCleanupReceipt = existsSync(join(runtimeRoot, `execute-cleanup-${changeName}.json`))
+  let hasExecuteRunStamp = false
+  if (!hasWorktreeMeta && !hasBranch && !hasAuditTag && !hasSnapshotFile && !hasApplyPathspec && !hasCleanupReceipt) {
+    try {
+      const runsDir = join(runtimeRoot, 'execute-runs')
+      if (existsSync(runsDir)) {
+        for (const e of readdirSync(runsDir)) {
+          try {
+            if (readFileSync(join(runsDir, e, 'change'), 'utf8').trim() === changeName) { hasExecuteRunStamp = true; break }
+          } catch { /* 无戳 run 跳过 */ }
+        }
+      }
+    } catch { /* 扫描失败视为无证据（fail-open 到预执行视图，note 有 hedge） */ }
+  }
+  const isArchived = !!(changeDirInfo && changeDirInfo.archived)
+  if (!isArchived && !hasWorktreeMeta && !hasBranch && !hasAuditTag && !hasSnapshotFile && !hasApplyPathspec && !hasCleanupReceipt && !hasExecuteRunStamp) {
     const emptyBase = {
       mode: 'full-flow', ok: true, degradedReason: null, baseAnchor: null,
       totals: { files: 0, additions: 0, deletions: 0 }, rows: [],
@@ -495,8 +540,8 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
       totals: { files: preRows.length, additions: 0, deletions: 0 },
       rows: preRows,
       note: preRows.length > 0
-        ? '变更尚未进入 execute（无 worktree/分支/审计 tag）——下表为 design 清单（全部待实现）；工作区其他未提交改动归属各自会话/变更，不在本表（若确已执行过但三信号均被手工清理，此处会误判——git log 核实）'
-        : '变更尚未进入 execute（无 worktree/分支/审计 tag）且 design 无可解析清单——暂无可对账内容',
+        ? '变更尚未进入 execute（无 worktree/分支/审计 tag/快照/execute-run 戳/apply 记录）——下表为 design 清单（全部待实现）；工作区其他未提交改动归属各自会话/变更，不在本表（若确已执行过但全部执行证据被清理，此处会误判——git log 核实）'
+        : '变更尚未进入 execute（无 worktree/分支/审计 tag/快照/execute-run 戳/apply 记录）且 design 无可解析清单——暂无可对账内容',
     }
   }
 
@@ -558,7 +603,9 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
   // 快照即冻结记录（含行数）——已收尾一律先出快照；实时窗口（开放区间）只作快照缺失的兜底，
   // note 明示会漂。tag 封闭区间不可用：分支上仅 baseline checkpoint（并行 WIP 快照），本变更
   // 改动经工作树 apply 从未 commit 到分支。 ——
-  const settled = changeDirInfo && (changeDirInfo.archived || actual.form === 'post-apply')
+  // freshActual（审查 C-F01）：verify 漂移 current 侧走快照捷径会变成快照比快照恒「一致」
+  // （假阴性）；execute --done 采集重跑也会陈旧回写——两处传 true 绕过，快照捷径只留给查询面
+  const settled = !freshActual && changeDirInfo && (changeDirInfo.archived || actual.form === 'post-apply')
   if (settled) {
     const snap = readScopeSnapshot(changeDirInfo.dir, runtimeRoot, changeName)
     if (snap && snap.rows.length > 0) {
@@ -571,7 +618,9 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
       const needsStats = rows.some(r => r && !Number.isFinite(r.additions) && r.kind !== 'binary')
       if (needsStats && actual && actual.ok && actual.baseAnchor) {
         const paths = rows.map(r => (r && r.path ? toPosix(r.path) : '')).filter(Boolean)
-        const stats = collectNumstatByPath(cwd, paths, { baseRef: actual.baseAnchor })
+        // 审查 C-F04：补采执行根走共享 resolveDiffRoot（form=worktree 时必须对 worktree 跑，
+        // 与主链路 :629/:636 同源配对——直用 cwd 会基点×根错位）
+        const stats = collectNumstatByPath(resolveDiffRoot(sb, changeName, actual.form, cwd), paths, { baseRef: actual.baseAnchor })
         let recovered = 0
         rows = rows.map(r => {
           if (!r || !r.path || Number.isFinite(r.additions) || r.kind === 'binary') return r
@@ -591,6 +640,8 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
           excluded: snap.excluded && Array.isArray(snap.excluded.foreignDeclared)
             ? snap.excluded
             : { foreignDeclared: [] },
+          patchSha256: snap.patchSha256 || null,
+          patchStatus: snap.patchStatus || null,
           note: `${settleLabel}——execute --done 时点冻结快照${snap.savedAt ? '（' + String(snap.savedAt).replace('T', ' ').slice(0, 19) + ' 落盘）' : ''}：文件集封闭在 apply 时点，主仓后续新文件不进表；行数按锚 ${actual.baseAnchor.slice(0, 7)}→当前工作树 补采（同文件后续演进会计入）`,
         }
       }
@@ -606,6 +657,8 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
         excluded: snap.excluded && Array.isArray(snap.excluded.foreignDeclared)
           ? snap.excluded
           : { foreignDeclared: [] },
+        patchSha256: snap.patchSha256 || null,
+        patchStatus: snap.patchStatus || null,
         note: `${settleLabel}——execute --done 时点冻结快照${snap.savedAt ? '（' + String(snap.savedAt).replace('T', ' ').slice(0, 19) + ' 落盘）' : ''}：范围封闭在 apply 时点，主仓后续改动不反映到本表；需要看当前工作区实时状态请跑 git status`,
       }
     }
@@ -715,7 +768,7 @@ async function computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, c
  *   excluded: { foreignDeclared: Array<{ file: string, sessions: string[] }> },
  *   note?: string|null }>}
  */
-export async function computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts, collectPatch } = {}) {
+export async function computeChangeScopeAudit({ cwd, specBase, changeName, platformOpts, collectPatch, freshActual } = {}) {
   const empty = {
     mode: 'full-flow', ok: false, degradedReason: null, baseAnchor: null,
     totals: { files: 0, additions: 0, deletions: 0 },
@@ -746,6 +799,8 @@ export async function computeChangeScopeAudit({ cwd, specBase, changeName, platf
             ? rec.record.excluded
             : { foreignDeclared: [] },
           frozenPatchPath: rec.patchPath,
+          patchSha256: rec.record.patchSha256 || null,
+          patchStatus: rec.record.patchStatus || null,
           note: `quick 会话已收尾——记录态（quicklog/patches/${rec.qlId}，${rec.record.savedAt ? String(rec.record.savedAt).replace('T', ' ').slice(0, 19) + ' 落盘' : '--done 时点冻结'}）`,
         }
       }
@@ -755,7 +810,7 @@ export async function computeChangeScopeAudit({ cwd, specBase, changeName, platf
         degradedReason: `quick 会话 ${changeName} 不存在（guard 已清理且 quicklog/patches/ 无记录——会话未产生改动或早于记录机制）`,
       }
     }
-    return await computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, collectPatch })
+    return await computeFullFlowAudit({ cwd, specBase, changeName, platformOpts, collectPatch, freshActual })
   } catch (e) {
     // fail-soft 兜底（D-006 / 兼容策略）：注入点只打一行提示，不阻断阶段完成
     return {
@@ -789,16 +844,36 @@ export async function getFileDiff({ cwd, specBase, changeName, platformOpts, fil
     // —— 真·当时内容比对（quick-359a48f1）：已收尾变更优先冻结 patch 切片 ——
     // ① quick 记录态自带 frozenPatchPath；② full-flow 变更目录 scope-audit.patch。
     // patch 冻结在收尾时点，不含后续演进——实时锚 diff 只作 patch 缺失的兜底（口径标注）。
-    const frozenPatch = (result.frozenPatchPath
-        && (() => { try { return readFileSync(result.frozenPatchPath, 'utf8') } catch { return null } })())
-      || readFrozenPatch(resolveChangeDir(sb, changeName)?.dir || null)
-    if (frozenPatch) {
+    // A-F01：读取时按 json 记录的 patchSha256 校验，不匹配显式告警（防低级篡改）。
+    const patchRecord = result.frozenPatchPath
+      ? { path: result.frozenPatchPath, sha: result.patchSha256 || null }
+      : (() => { const d = resolveChangeDir(sb, changeName); return d ? { path: join(d.dir, 'scope-audit.patch'), sha: null } : null })()
+    let recordedSha = patchRecord ? patchRecord.sha : null
+    if (patchRecord && !recordedSha && result.rows) {
+      // json 里未直接带回 hash（记录态捷径不透传）→ 读 json 原文取（快照/quick 记录都存该字段）
+      try {
+        const snapRaw = JSON.parse(readFileSync(result.frozenPatchPath
+          ? result.frozenPatchPath.replace(/\.patch$/, '.json')
+          : join(resolveChangeDir(sb, changeName).dir, 'scope-audit.json'), 'utf8'))
+        recordedSha = snapRaw.patchSha256 || null
+      } catch { /* json 不可读 → 无 hash 可校验（null=不校验） */ }
+    }
+    const frozenPatch = (patchRecord
+        && (() => { try { return readFileSync(patchRecord.path, 'utf8') } catch { return null } })())
+    if (frozenPatch !== null && frozenPatch !== undefined && patchRecord) {
+      const integrity = verifyPatchIntegrity(recordedSha, frozenPatch)
+      if (integrity === false) {
+        return { ok: false, mode: result.mode, root: cwd, baseRef: null, anchorLabel: '冻结 patch', diff: null, note: '⚠️ 冻结 patch 与快照记录的 patchSha256 不匹配——记录可能被篡改，审计前人工核验（git 历史比对）' }
+      }
       const sliced = slicePatchForFile(frozenPatch, norm)
       if (sliced) {
         return { ok: true, mode: result.mode, root: cwd, baseRef: null, anchorLabel: '冻结 patch（收尾时点内容，无后续演进混入）', diff: sliced, note: null }
       }
       return { ok: true, mode: result.mode, root: cwd, baseRef: null, anchorLabel: '冻结 patch', diff: null, note: '该文件不在冻结 patch 内（窗口外文件）' }
     }
+    if (result.patchStatus === 'failed') {
+      return { ok: true, mode: result.mode, root: cwd, baseRef: null, anchorLabel: '冻结记录', diff: null, note: '冻结 patch 当时采集失败（非无改动）——退实时锚比对' }
+    }
 
     // 锚点解析（语义锚 head-uncommitted-window → 实际 baseRef 'HEAD'；无锚同兜底并标注）
     let baseRef = 'HEAD'

package/src/semantic-guard.js

@@ -0,0 +1,207 @@
+/**
+ * semantic-guard.js — quick 语义护栏聚合模块（change: 2026-09-11-cross-change-decision-guard，
+ * task-03，FR-03/FR-04，D-001@v1）：近因他者交付归因 + 断言重写检测 + advisory 渲染 + 总开关。
+ *
+ * 被 run/prompt.js（task-05，进场注入）与 run/quick-audit.js（task-06，--done 断言 WARNING）
+ * 两端消费。纯模块纪律：不 console（渲染返回字符串，输出留给消费端）、不写盘、
+ * 不 import run/ 下模块（避免与 task-05/06 循环依赖）。
+ *
+ * git 交互一律走 git-helper 的 safeGit（数组参数不经 shell，Windows 路径安全）；失败静默
+ * 降级空结果不抛（acceptance：git 不可用 → 全部降级空结果）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { safeGit } from './git-helper.js'
+import { matchDecisionsByFiles } from './knowledge-match.js'
+
+/** 路径反斜杠归一 POSIX（Windows 调用方传 \ 分隔时不丢匹配；与 matchDecisionsByFiles 双侧归一口径一致） */
+function toPosix(p) {
+  return String(p || '').trim().replace(/\\/g, '/')
+}
+
+// ───────────────────────── 交付归因（FR-03） ─────────────────────────
+
+/** 提交信息里的完整变更名标记：init 生成的 change 目录名形态（2026-09-11-cross-change-decision-guard） */
+const CHANGE_NAME_RE = /\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*/g
+/** quicklog 条目 ID 标记：ql-YYYYMMDD-NNN-xxxx（quick 会话提交信息的归因键） */
+const QL_ID_RE = /ql-\d{8}-\d{3}-[a-z0-9]{4}/g
+
+/** 单条提交信息 → 两类标记列表（按出现位置排序；两类正则无交集，ql-ID 的日期段无连字符） */
+function extractChangeMarkers(subject) {
+  const found = []
+  for (const re of [CHANGE_NAME_RE, QL_ID_RE]) {
+    for (const m of subject.matchAll(re)) found.push({ token: m[0], at: m.index })
+  }
+  return found.sort((a, b) => a.at - b.at).map(f => f.token)
+}
+
+/**
+ * 近因他者交付归因：每文件查最近 days 天提交信息（--format=%s，仅 subject），解析变更名 /
+ * ql-ID 两类标记，取最新一条非 currentChange 标记 → { [file]: changeName }。
+ * git log 输出行为提交 subject，无 porcelain 首行前导空格语义（git-helper.js:88 的
+ * trim 坑不影响此处），safeGit 默认 trim 安全。
+ * @param {{ cwd?: string, files?: string[], currentChange?: string, days?: number }} opts
+ * @returns {{ [file]: string }} 键 = POSIX 归一路径；无标记 / 仅本变更标记 / git 失败 /
+ *   第 20 个之后的文件 → 不记
+ */
+export function collectRecentForeignDelivery({ cwd, files, currentChange, days = 7 } = {}) {
+  const result = {}
+  if (!cwd || !Array.isArray(files)) return result
+  const list = files.map(toPosix).filter(Boolean).slice(0, 20)
+  for (const file of list) {
+    const r = safeGit(cwd, ['log', `--since=${days}.days`, '--format=%s', '--', file])
+    if (r.error || !r.value) continue
+    // git log 新→旧：逐提交找第一条非 currentChange 标记，命中即止（取最新他者标记）
+    for (const subject of r.value.split('\n')) {
+      const foreign = extractChangeMarkers(subject).find(m => m !== currentChange)
+      if (foreign) {
+        result[file] = foreign
+        break
+      }
+    }
+  }
+  return result
+}
+
+// ───────────────────────── 断言重写检测（FR-04） ─────────────────────────
+
+/** 删除侧断言 token：expect( / assert / t.equal / toBe / toEqual / strictEqual / should. */
+const ASSERTION_TOKEN_RE = /expect\(|assert|t\.equal|toBe|toEqual|strictEqual|should\./
+
+/** 测试文件判定：test/ 前缀 或 *.test.* / *_test.* 命名（路径先 POSIX 归一） */
+function isTestFilePath(p) {
+  return p.startsWith('test/') || /\.test\./.test(p) || /_test\./.test(p)
+}
+
+/**
+ * 断言重写检测：测试文件跑 git diff HEAD -U0（HEAD 口径非 index——quick step3 先 git add
+ * 暂存的时序下裸 diff 恒空转，坑 Grill X-001），hunk 删除侧（- 行）含断言 token → 命中；
+ * 纯新增 hunk（无 - 行）不算；样例行封顶 5/文件。
+ * @param {{ cwd?: string, files?: string[] }} opts
+ * @returns {{ [file]: string[] }} 键 = POSIX 归一测试文件路径，值 = 删除侧含 token 的原行
+ *   （去 - 前缀）；非测试文件不查；无命中 / git 失败 → 不记
+ */
+export function detectAssertionRewrites({ cwd, files } = {}) {
+  const result = {}
+  if (!cwd || !Array.isArray(files)) return result
+  for (const raw of files) {
+    const file = toPosix(raw)
+    if (!file || !isTestFilePath(file)) continue
+    const r = safeGit(cwd, ['diff', 'HEAD', '-U0', '--', file])
+    if (r.error || !r.value) continue
+    const samples = []
+    let inHunk = false
+    let deletedLines = []
+    const flushHunk = () => {
+      if (!inHunk || deletedLines.length === 0) return // 纯新增 hunk（无 - 行）不算
+      for (const line of deletedLines) {
+        if (samples.length >= 5) break
+        if (ASSERTION_TOKEN_RE.test(line)) samples.push(line)
+      }
+    }
+    for (const line of r.value.split('\n')) {
+      if (line.startsWith('@@')) {
+        flushHunk()
+        inHunk = true
+        deletedLines = []
+        continue
+      }
+      if (!inHunk) continue // 文件头（diff --git / index / --- / +++）不进 hunk 统计
+      if (line.startsWith('-')) deletedLines.push(line.slice(1)) // + 行与 "\ No newline" 行跳过
+    }
+    flushHunk()
+    if (samples.length > 0) result[file] = samples
+  }
+  return result
+}
+
+// ───────────────────────── advisory 渲染（FR-03/FR-04 组合） ─────────────────────────
+
+/**
+ * advisory 文本段渲染：决策命中（matchDecisionsByFiles，knowledge 目录 = specBase/knowledge，
+ * task-02 契约）+ 交付归因（collectRecentForeignDelivery 默认 7 天窗）组合成注入文本，
+ * 供 task-05 进场注入 / task-06 --done WARNING 拼接；两类均零命中 → ''（不留空段）。
+ * @param {{ specBase?: string, cwd?: string, candidateFiles?: string[], currentChange?: string }} opts
+ * @returns {string}
+ */
+export function renderSemanticGuardBlock({ specBase, cwd, candidateFiles, currentChange } = {}) {
+  if (!Array.isArray(candidateFiles) || candidateFiles.length === 0) return ''
+  const files = [...new Set(candidateFiles.map(toPosix).filter(Boolean))]
+  if (files.length === 0) return ''
+  const decisions = specBase
+    ? matchDecisionsByFiles(join(specBase, 'knowledge'), files)
+    : {}
+  const delivery = cwd
+    ? collectRecentForeignDelivery({ cwd, files, currentChange })
+    : {}
+  const decisionFiles = files.filter(f => Array.isArray(decisions[f]) && decisions[f].length > 0)
+  const deliveryFiles = files.filter(f => delivery[f])
+  if (decisionFiles.length === 0 && deliveryFiles.length === 0) return ''
+  const lines = ['【语义护栏】改动文件触及既有决策 / 近期他者交付，动手前请对照：']
+  if (decisionFiles.length > 0) {
+    lines.push(`■ 决策库命中（${decisionFiles.length} 文件）`)
+    for (const f of decisionFiles) {
+      for (const hit of decisions[f]) {
+        const rejected = hit.status === 'rejected'
+        lines.push(`  - ${f} → ${hit.id} ${hit.title}［${rejected ? 'rejected，已否决，勿复潮' : hit.status || 'unknown'}］`)
+        lines.push(`      理由：${hit.reason || '（未记录）'}`)
+        if (hit.file) lines.push(`      详见：knowledge/${hit.file}`)
+      }
+    }
+  }
+  if (deliveryFiles.length > 0) {
+    lines.push('■ 近 7 天他者交付归因（最后交付的非本变更标记）')
+    for (const f of deliveryFiles) lines.push(`  - ${f} ← ${delivery[f]}`)
+  }
+  return lines.join('\n')
+}
+
+// ───────────────────────── 总开关（D-001@v1） ─────────────────────────
+
+/** YAML 布尔宽松解析：仅显式 false（含引号形态）为关，其余值一律 true（fail-open，先例 friction-tally R-05） */
+function parseEnabledValue(raw) {
+  const v = String(raw || '').trim().replace(/^['"]|['"]$/g, '')
+  return v.toLowerCase() !== 'false'
+}
+
+/**
+ * 读 specBase/local.yaml 的 semantic_guard.enabled 总开关（D-001@v1）：默认 true；
+ * 缺键 / 文件缺失 / 解析异常 → true（fail-open——配置读取异常不该把护栏误判为关）。
+ * 轻量行式解析不引 yaml 依赖（先例 friction-tally readFrictionHintEnabled 同款形态），
+ * 兼容嵌套（semantic_guard:\n  enabled: false）与 flat（semantic_guard.enabled: false）；
+ * 行尾先归一（Windows CRLF 残留致行式正则整体失配）。
+ * @param {string} specBase - spec 根（local.yaml 所在目录）
+ * @returns {boolean}
+ */
+export function readSemanticGuardEnabled(specBase) {
+  try {
+    const yamlPath = join(specBase, 'local.yaml')
+    if (!existsSync(yamlPath)) return true
+    const text = String(readFileSync(yamlPath, 'utf8')).replace(/\r\n?/g, '\n')
+    let inSection = false
+    let sectionIndent = -1
+    for (const line of text.split('\n')) {
+      // flat 形态优先：键名带点，不与嵌套段头冲突
+      const flat = line.match(/^\s*semantic_guard\.enabled\s*:\s*(.*?)\s*(?:#.*)?$/)
+      if (flat) return parseEnabledValue(flat[1])
+      const section = line.match(/^(\s*)semantic_guard\s*:\s*(?:#.*)?$/)
+      if (section) {
+        inSection = true
+        sectionIndent = section[1].length
+        continue
+      }
+      if (!inSection) continue
+      if (line.trim() === '' || line.trim().startsWith('#')) continue
+      // 缩进回落到段头层级（或更浅）= semantic_guard 段结束，之后的 enabled 不属于它
+      if (/^\s*/.exec(line)[0].length <= sectionIndent) {
+        inSection = false
+        continue
+      }
+      const kv = line.match(/^\s*enabled\s*:\s*(.*?)\s*(?:#.*)?$/)
+      if (kv) return parseEnabledValue(kv[1])
+    }
+    return true
+  } catch {
+    return true
+  }
+}

package/src/sillyhub-mcp/client.js

@@ -282,9 +282,14 @@ export class SillyHubMcpClient {
     }
 
     if (!res.ok) {
+      // 401 状态留痕（2026-09-11 用户实测反馈：token 失效被 probe 报成 daemon-unreachable，
+      // 误导排障方向——吊销/过期的 shmcp_ 是「重连再配对」能解的，不是 daemon 的问题）。
+      // getLastInitStatus() 供 probeSillyHub 类型化 reason；成功/其他失败置 null（不误判旧状态）。
+      this._lastInitHttpStatus = res.status;
       if (!quiet) console.warn(`[sillyhub-mcp] initialize → HTTP ${res.status}`);
       return false;
     }
+    this._lastInitHttpStatus = null;
 
     // 优先取 header mcp-session-id（FastMCP 实测返回）；缺失再查 body _meta.sessionId。
     // ⚠️ 无论 header 是否有 session，都必须读完 body（消费 SSE 流）——FastMCP 在
@@ -391,6 +396,15 @@ export class SillyHubMcpClient {
     return result !== null;
   }
 
+  /**
+   * 最近一次 initialize 握手的 HTTP 状态码（null = 无记录/成功/非 HTTP 失败）。
+   * 消费方：probeSillyHub 的 token 失效类型化（401 → reason='mcp-token-invalid'，
+   * 区别于 daemon-unreachable——2026-09-11 用户实测：吊销 token 被误报 daemon 不可达）。
+   */
+  getLastInitStatus() {
+    return this._lastInitHttpStatus ?? null;
+  }
+
   /**
    * 列出 daemon 暴露的 MCP tools（JSON-RPC `tools/list`，task-11 路径A 探测用）。
    *

package/src/spec-sync.js

@@ -124,6 +124,9 @@ export function hashFiles(entries) {
       hash: _hashBuffer(buf),
       mtime: Math.floor(e.mtimeMs / 1000),
       absPath: e.absPath,
+      // 批 E-①：buf 随行携带（computeSpecOps 的 update/add 直接取用）——消除变更文件二次
+      // readFileSync（大文件双读）。docs 树为文本内容、量级有限，整批驻留可接受。
+      buf,
     };
   });
 }
@@ -177,20 +180,22 @@ export function computeSpecOps(serverManifest, localFiles) {
     return [];
   }
 
-  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同
+  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同。
+  // 批 E-①：候选新路径按 hash 建索引 O(N+M)——旧双重循环 O(N×M)，万级文件树明显变慢。
   const renames = [];
-  const consumedNew = new Set();
+  const newByHash = new Map(); // hash → 未被服务器收录且未被消费的新路径队列
+  for (const [newPath, entry] of localMap) {
+    if (serverSet.has(newPath)) continue
+    const list = newByHash.get(entry.hash)
+    if (list) list.push(newPath); else newByHash.set(entry.hash, [newPath])
+  }
   for (const oldPath of serverPaths) {
-    if (localSet.has(oldPath)) continue;
-    const cachedEntry = server[oldPath];
-    for (const newPath of localMap.keys()) {
-      if (serverSet.has(newPath)) continue;
-      if (consumedNew.has(newPath)) continue;
-      if (localMap.get(newPath).hash === cachedEntry.hash) {
-        renames.push({ oldPath, newPath });
-        consumedNew.add(newPath);
-        break;
-      }
+    if (localSet.has(oldPath)) continue
+    const candidates = newByHash.get(server[oldPath].hash)
+    if (candidates && candidates.length > 0) {
+      const newPath = candidates.shift()
+      renames.push({ oldPath, newPath })
+      if (candidates.length === 0) newByHash.delete(server[oldPath].hash)
     }
   }
   const renamedOld = new Set(renames.map((r) => r.oldPath));
@@ -212,7 +217,7 @@ export function computeSpecOps(serverManifest, localFiles) {
     if (localSet.has(p)) {
       const localEntry = localMap.get(p);
       if (localEntry.hash !== server[p].hash) {
-        const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+        const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
         ops.push({
           op: 'update',
           path: p,
@@ -235,7 +240,7 @@ export function computeSpecOps(serverManifest, localFiles) {
     if (renamedNew.has(p)) continue;
     if (!serverSet.has(p)) {
       const localEntry = localMap.get(p);
-      const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+      const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
       ops.push({
         op: 'add',
         path: p,

package/src/stage-contract-spec.js

@@ -317,10 +317,11 @@ const PLAN_RULES = [
     target: { root: 'change', path: 'design.md', scope: 'full' },
     data: {
       messageMissingList: 'design.md 缺少「文件变更清单」章节（或清单解析为空），无法做文件覆盖对账。该章节在 brainstorm 模板中为必填；请在 design.md 补上完整的文件变更清单（列出本次新增/修改/删除的源码文件）后重试。',
-      messageUncovered: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。',
+      messageUncovered: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。\n   若跨仓文件被标为 [main]：多为仓变更段头未被识别（段头须为「## <repo-key> 仓变更」），先核对段头格式再补 task。',
+      messageMalformedHeader: 'design.md「文件变更清单」内疑似仓变更段头但格式无法解析：「${line}」\n   该段下文件会被记到上一段仓（或 main）→ 文件覆盖对账整段错位（误报未覆盖或漏检）。\n   修复：段头写成「## <repo-key> 仓变更」（repo-key 限字母数字._-，可加编号前缀与（…）备注后缀）；若这是下一章节标题而非段头，请改名避免形如「<词> 仓变更…」。',
     },
-    spec: 'design.md「文件变更清单」中的每个源码文件,必须被至少一个 task 的 allowed_paths 覆盖(前缀/glob 容差匹配),否则 execute 子代理无权改它→必然漏改。有 task 卡片但 design 缺「文件变更清单」章节也阻断(清单是覆盖对账的基准)。',
-    failMessage: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。',
+    spec: 'design.md「文件变更清单」中的每个源码文件,必须被至少一个 task 的 allowed_paths 覆盖(前缀/glob 容差匹配),否则 execute 子代理无权改它→必然漏改。有 task 卡片但 design 缺「文件变更清单」章节也阻断(清单是覆盖对账的基准)。疑似仓变更段头但格式解析不了(repo-key 非法/仓变更后接自由文本)同样阻断并点名该行——段头错记仓会让对账整段错位。',
+    failMessage: 'design.md 文件变更清单中 ${count} 个文件未被任何 task 的 allowed_paths 覆盖：\n${files}\n   这些文件在 execute 阶段将无 task 有权修改 → 必然漏改。\n   修复：为每个遗漏文件新建/补充 task 并在其 allowed_paths 声明，或在 design.md「不修改文件」章节说明不改原因。\n   若跨仓文件被标为 [main]：多为仓变更段头未被识别（段头须为「## <repo-key> 仓变更」），先核对段头格式再补 task。',
   },
   // task-plan-reconciliation(custom):plan.md 声明任务 ↔ tasks/ 卡片双向对账（债单 D-2b）。
   // 修复场景：plan 列 17 个任务只生成 12 张卡（尾部文档同步类任务漏卡），execute 审计只看

package/src/stage-review.js

@@ -13,7 +13,8 @@
  *   （平台模式落 <runtimeRoot>/stage-reviews/...，与 execute-runs 同构）
  */
 
-import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs'
+import { writeAtomicSync } from './fs-atomic.js'
 import { join } from 'path'
 import { createHash } from 'crypto'
 import jsYaml from 'js-yaml'
@@ -561,7 +562,7 @@ export function validateStageReviewWithAutoRefresh(opts) {
     reviewerNotes: `${result.review.reviewerNotes || ''}\ndocHash auto-refreshed at ${refreshedAt}（gate 检测主文档改版，机械重算；verdict 保留，结论是否仍适用需人工确认）`.trim(),
   }
   try {
-    writeFileSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
+    writeAtomicSync(reviewPath, JSON.stringify(refreshed, null, 2) + '\n')
   } catch {
     return { result, autoRefreshed: false } // 写失败回落原失败结果，不静默放行
   }
@@ -698,7 +699,7 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
       reviewedFiles,
       reviewerNotes: `${existing.reviewerNotes || ''}\ndocHash refreshed at ${refreshedAt}（主文档改版后机械重算；verdict 结论是否仍适用需人工确认）`.trim(),
     }
-    writeFileSync(existingPath, JSON.stringify(review, null, 2) + '\n')
+    writeAtomicSync(existingPath, JSON.stringify(review, null, 2) + '\n')
     const schemaRecheck = validateStageReviewSchema(review)
     if (!schemaRecheck.ok) {
       throw new Error(`register-stage-review: refresh 后 schema 自检失败 — ${schemaRecheck.errors.join('; ')}（原 review 字段异常，先修原文件）`)
@@ -750,7 +751,7 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
   const reviewDir = join(runtimeRoot, 'stage-reviews', `${stage}-${reviewRunId}`)
   const reviewPath = join(reviewDir, 'review.json')
   mkdirSync(reviewDir, { recursive: true })
-  writeFileSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
+  writeAtomicSync(reviewPath, JSON.stringify(review, null, 2) + '\n')
   // stage-reviews 回收不在此处（ql-20260908-005 已定分野）：变更归属类证据走归档时精确
   // 回收（pruneArchivedChangeRuntime 按 reviewedFiles 归属）；写入侧滚动是启发式，
   // 活跃变更的 review 可能因他端高频写而跌出 keep 窗，不进证据类目录。
@@ -760,7 +761,7 @@ export function registerStageReview({ changeName, stage, fromFile, cwd, platform
     console.warn(`⚠️ register-stage-review: marker 已存在 ${markerPath}，将被覆盖为 ${reviewRunId}`)
   }
   mkdirSync(runtimeRoot, { recursive: true })
-  writeFileSync(markerPath, reviewRunId + '\n')
+  writeAtomicSync(markerPath, reviewRunId + '\n')
 
   // self-check（fail-closed）：刚写的 review 必过 schema + docHash 真实性。只验 mechanics，
   // 不判 verdict（verdict 是 agent/子代理的审查结论，even fail 也如实落盘，由 Stage Review Gate 裁决）。

package/src/stages/brainstorm.js

@@ -293,7 +293,7 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 仅改内部实现、无对外字段变动时，说明列照常写「新增 xx 方法」即可，无需数据流。
 
    **跨仓变更写法**（本次变更涉及 local.yaml repos: 注册的其他仓时必读；纯主仓变更跳过）：
-   - 清单**按仓分段**：每个仓一个小节，标题格式固定 \`## <repo-key> 仓变更\`（如 \`## sub-grid-security 仓变更\`）。plan-postcheck 文件覆盖对账按此段头解析仓归属，写成「前端仓 / backend」等其他标题 → 对账不上
+   - 清单**按仓分段**：每个仓一个小节，标题格式固定 \`## <repo-key> 仓变更\`（如 \`## sub-grid-security 仓变更\`；可加编号前缀或（跨仓，X1-X4）这类括号备注后缀，其余后缀/写法解析不了）。plan-postcheck 文件覆盖对账按此段头解析仓归属，写成「前端仓 / backend」等其他标题 → 对账不上且会点名段头格式错误
    - 段内路径相对**该仓根**写（\`src/routes/x.js\`）；❌ 禁止带仓库名前缀（\`sub-grid-security/src/routes/x.js\`）、❌ 禁止绝对路径/盘符路径（\`C:/repo/src/...\`）——后续 TaskCard 的 allowed_paths 与 review 对账（\`git -C <仓根> diff\` 产仓根相对路径）都用同一口径，前缀/绝对路径永不命中
    - 主仓文件放在第一个段头之前（无段头区域 = main），或单独写 \`## main 仓变更\` 段
    - repo-key 必须是 local.yaml repos: 段已注册的键（未注册先跑 \`sillyspec local register-repo <key> <仓根路径>\`，main 隐式不用注册）

package/src/stages/execute.js

@@ -1074,6 +1074,10 @@ ${crossLines}${crossWorktreeSection}${crossLegacySection}
       `  - task-${i.taskNum} (repo: ${i.repo}) → workdir: "${i.workdir}"`
     ).join('\n')
     worktreeSection = `
+### task 进行中标记（中断续跑的半成品归属，2026-09-12 起）
+
+每个 task **开工/完工各跑一条命令**（低摩擦，主代理或子代理均可）：开工「sillyspec task start --change {CHANGE_NAME} --task task-NN --note 一句话在做什么」；完工「sillyspec task finish --change {CHANGE_NAME} --task task-NN」。中断续跑时主代理用「sillyspec task list --change {CHANGE_NAME}」点名接管（>2h 标红为中断遗留），不再靠翻 git 工作区猜哪个半成品是谁的。
+
 ### 工作目录（per-task）
 
 调用 Task 工具启动子代理时，**workdir 参数是强制必传的**，且本 Wave 内不同 task 的 workdir 不同（主仓 task vs 跨仓 task）。
@@ -1213,7 +1217,8 @@ ${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 也有真实锚点）
+   - **使用 \`sillyspec wt-commit --change <change-name> -- <task-files>\` 串行提交**（坑 wt-parallel-commit-race：同一 Wave 多子代理共享 worktree，裸 \`git add -A\` 互卷 WIP / 撞 index.lock；\`git add -A\` 还会把并行子代理未提交的半成品一并暂存——**禁 \`git add -A\`**；sillyspec wt-commit 自动处理分支切换与序列化，无需手动 git 操作；未 commit 的新文件不在 base commit 也不在 index，apply --3way 报 "does not exist in index"）
+   - commit 后 base..HEAD diff 完整、apply 顺畅，review.json 的 head 也有真实锚点
    - **写 review.json 即可**（checkbox 由 CLI 自动勾选，见下方 Task Review Gate）
    - **任务边界上报（每任务一次，主仓根目录）**：review write 落盘（CLI 已自动勾选）后跑一次 \`sillyspec platform sync --change <change-name>\`——以任务粒度把「最后信号」（last_pushed_at）与 tasks.md 勾选状态推上平台（变更中心「进行中」可见性）；未连接平台时该命令静默跳过，无需先检查连接状态
    - **既跑 lint check 也跑 formatter**：凡变更涉及的源码跑项目的 lint 检查 **和** 格式化（如 \`ruff format\` / \`prettier --write\`），不要只跑 check——只 check 不 format 会把格式问题留到 commit 时被 pre-commit hook 拦截（worktree 内二进制可能缺失，先 \`which <bin>\` 确认，缺则 \`uv tool install\` / \`uv sync\`）