sillyspec 3.26.14 → 3.26.15

package/src/verify-probes.js

@@ -0,0 +1,264 @@
+/**
+ * verify-probes.js — `sillyspec verify-probes` 的机械探针实现 + verify-result.md 骨架生成
+ * （2026-08-21 agent-手工产出审计第三批 H1/H3/H5/H7/F9）。
+ *
+ * verify-probes.md 模板定义六个探针，agent 此前逐条手跑 grep/递归查找/git 对账再手工拼表格。
+ * 本模块把纯机械的四个探针命令化（语义判断的留 agent，输出里显式标注）：
+ *   探针1 未实现标记扫描：design §6 清单的具体文件逐行 grep TODO/FIXME/尚未实现 等
+ *   探针3 测试覆盖：逐 task 按 allowed_paths 定位模块目录，递归找测试文件（co-located tests/ 陷阱）
+ *   探针5 API 契约对账：复用 contract-matrix.verifyApiParity（endpoints.json × 前端调用）+ 表格渲染
+ *   探针6 删除对账：git diff --name-status HEAD 的 D/R × design 声明操作三态判定
+ * 探针2（关键词提取半语义）/探针3.4 集成盲区/3.5 断言抽查/探针4（决策追踪语义）留 agent。
+ *
+ * verify-result.md 骨架：七章节固定结构 + 探针结果机械预填 + 其余章节 <!--TODO--> 占位。
+ * 结论章节留「待填」——extractVerifyConclusion 找不到 PASS/FAIL 关键词即判不过，骨架不能
+ * 直接过门（与 symbol-impact 骨架同款防偷懒语义）。
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import { join, dirname, basename } from 'path'
+import { gitQuiet } from './git-helper.js'
+import { parseFileChangeListDetailed } from './change-list.js'
+import { parseAllowedPaths } from './stages/plan-postcheck.js'
+import { verifyApiParity } from './contract-matrix.js'
+import { resolveSpecDir, resolveRuntimeRoot } from './run/shared.js'
+
+const TODO_MARKER_RE = /尚未实现|TODO|FIXME|HACK|XXX/
+const TEST_FILE_RE = /test|spec/i
+const PROBE1_MAX_MATCHES = 200
+
+function listTaskIds(tasksPath) {
+  if (!existsSync(tasksPath)) return []
+  const ids = []
+  for (const line of readFileSync(tasksPath, 'utf8').split('\n')) {
+    const m = line.match(/^[-*]\s*\[[ xX]\]\s*(task-\d+)\b/)
+    if (m) ids.push(m[1])
+  }
+  return ids
+}
+
+/** 递归找测试文件（排除 node_modules/.git/dist 等；返回 posix 相对 cwd 路径，封顶展示） */
+function findTestFiles(rootDir, cwd, cap = 10) {
+  const found = []
+  const skip = new Set(['node_modules', '.git', '.gradle', '__pycache__', '.venv', 'dist', 'build', 'target', 'out'])
+  const walk = (d) => {
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      const full = join(d, e.name)
+      if (e.isDirectory()) {
+        if (!skip.has(e.name)) walk(full)
+      } else if (e.isFile() && TEST_FILE_RE.test(basename(e.name))) {
+        found.push(full.split('\\').join('/').replace(cwd.split('\\').join('/').replace(/\/$/, '') + '/', ''))
+        if (found.length >= cap) return
+      }
+    }
+  }
+  if (existsSync(rootDir)) walk(rootDir)
+  return found
+}
+
+/**
+ * 跑四个机械探针。
+ * @param {{ cwd: string, changeName: string, specDir?: string|null }} opts
+ * @returns {{ probe1: object, probe3: object, probe5: object, probe6: object }}
+ */
+export function runVerifyProbes({ cwd, changeName, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const changeDir = join(specBase, 'changes', changeName)
+  const designPath = join(changeDir, 'design.md')
+  const detailed = existsSync(designPath) ? parseFileChangeListDetailed(designPath) : []
+  const designOps = new Map(detailed.map(e => [e.path, e.operation]))
+
+  // ── 探针 1：未实现标记扫描（design 清单具体文件；glob 项列出让 agent 展开）──
+  const probe1 = { matches: [], globEntries: [], skippedFiles: [] }
+  for (const e of detailed) {
+    if (e.path.startsWith('.sillyspec/')) continue
+    if (/[*?[\]]/.test(e.path)) {
+      probe1.globEntries.push(e.path)
+      continue
+    }
+    const abs = join(cwd, e.path)
+    if (!existsSync(abs)) {
+      probe1.skippedFiles.push(e.path)
+      continue
+    }
+    try {
+      const lines = readFileSync(abs, 'utf8').split('\n')
+      lines.forEach((line, i) => {
+        if (probe1.matches.length >= PROBE1_MAX_MATCHES) return
+        if (TODO_MARKER_RE.test(line)) probe1.matches.push({ file: e.path, line: i + 1, content: line.trim().slice(0, 160) })
+      })
+    } catch {
+      probe1.skippedFiles.push(e.path)
+    }
+  }
+
+  // ── 探针 3：验收标准测试覆盖（task 卡 allowed_paths → 模块目录递归找测试文件）──
+  const tasksPath = join(changeDir, 'tasks.md')
+  const probe3 = { tasks: [], note: '集成盲区（路由/跨模块装配）与断言有效性抽查是语义判断，留给 agent 逐 task 标注 ⚠️' }
+  for (const taskId of listTaskIds(tasksPath)) {
+    const cardPath = join(changeDir, 'tasks', `${taskId}.md`)
+    let allowed = []
+    if (existsSync(cardPath)) allowed = parseAllowedPaths(readFileSync(cardPath, 'utf8'))
+    const moduleDirs = [...new Set(allowed.map(p => dirname(p.split('\\').join('/'))).filter(d => d && d !== '.'))]
+    const testFiles = []
+    for (const d of moduleDirs) {
+      for (const f of findTestFiles(join(cwd, d), cwd)) {
+        if (!testFiles.includes(f)) testFiles.push(f)
+      }
+    }
+    probe3.tasks.push({
+      task: taskId,
+      moduleDirs,
+      testFiles: testFiles.slice(0, 10),
+      testFileCount: testFiles.length,
+      hasTest: testFiles.length > 0,
+      located: moduleDirs.length > 0,
+    })
+  }
+
+  // ── 探针 5：API 契约对账（复用 verifyApiParity：endpoints.json × 前端调用）──
+  const runtimeRoot = resolveRuntimeRoot({ specRoot: specDir }, specBase)
+  const probe5 = verifyApiParity(specBase, cwd, runtimeRoot, changeName)
+
+  // ── 探针 6：代码删除对账（git diff --name-status HEAD 的 D/R × design 声明三态）──
+  const probe6 = { deletions: [], note: '以 git 事实为准（真实 > 声明）；是否 FAIL blocker 由 agent 诚实判定' }
+  const nsOut = gitQuiet(cwd, ['diff', '--name-status', 'HEAD']) || ''
+  for (const row of nsOut.split('\n').filter(Boolean)) {
+    const [status, ...paths] = row.split('\t')
+    const st = (status || '').trim().toUpperCase()
+    if (!/^[DRC]/.test(st)) continue
+    // R/C 的旧路径等价删除（paths[0]）；D 的唯一路径
+    const target = (st.startsWith('D') ? paths[0] : paths[0]) || ''
+    const posix = target.split('\\').join('/')
+    if (!posix || posix.startsWith('.sillyspec/') || posix === 'meta.json' || basename(posix) === 'meta.json') continue
+    const op = designOps.get(posix)
+    let verdict
+    if (op && /删除|delete|del/i.test(op)) verdict = '✅ 合规（design 声明删除）'
+    else if (op) verdict = `❌ 高风险（design 声明「${op}」却整文件删除）`
+    else verdict = '⚠️ 未声明删除（design 清单未列出）'
+    probe6.deletions.push({ path: posix, status: st, designOp: op || null, verdict })
+  }
+
+  return { probe1, probe3, probe5, probe6 }
+}
+
+/**
+ * 渲染探针结果为 markdown（可直接粘进 verify-result.md「探针结果」章节）。
+ */
+export function renderVerifyProbesReport(result) {
+  const L = []
+  const { probe1, probe3, probe5, probe6 } = result
+
+  L.push('#### 探针 1：未实现标记扫描（design 清单文件）')
+  if (probe1.matches.length === 0) {
+    L.push('- ✅ 无 TODO/FIXME/尚未实现 标记命中')
+  } else {
+    for (const m of probe1.matches) L.push(`- ⚠️ \`${m.file}:${m.line}\` ${m.content}`)
+  }
+  if (probe1.globEntries.length > 0) L.push(`- ℹ️ glob 项未展开（agent 手动展开扫描）：${probe1.globEntries.join('、')}`)
+  if (probe1.skippedFiles.length > 0) L.push(`- ℹ️ 清单文件不存在（跳过）：${probe1.skippedFiles.join('、')}`)
+  L.push('')
+
+  L.push('#### 探针 2：设计关键词覆盖')
+  L.push('<!--TODO: 半语义探针——从 design 提取能力关键词逐个 grep 确认实现（agent 执行）-->')
+  L.push('')
+
+  L.push('#### 探针 3：验收标准测试覆盖')
+  if (probe3.tasks.length === 0) {
+    L.push('- ℹ️ tasks.md 无 checkbox 任务')
+  } else {
+    for (const t of probe3.tasks) {
+      if (!t.located) {
+        L.push(`- ⚠️ ${t.task}: 无 task 卡/allowed_paths，无法定位模块目录（agent 手查）`)
+      } else if (t.hasTest) {
+        L.push(`- ✅ ${t.task}: 模块目录（${t.moduleDirs.join('、')}）找到 ${t.testFileCount} 个测试文件（${t.testFiles.slice(0, 5).join('、')}${t.testFileCount > 5 ? ' …' : ''}）`)
+      } else {
+        L.push(`- ⚠️ ${t.task}: 模块目录（${t.moduleDirs.join('、')}）递归未找到测试文件（含 co-located tests/）`)
+      }
+    }
+  }
+  L.push(`- ℹ️ ${probe3.note}`)
+  L.push('')
+
+  L.push('#### 探针 4：决策追踪覆盖')
+  L.push('<!--TODO: 语义探针——D-xxx@vN → FR-xxx → plan/task 引用 → 证据回指闭环（agent 执行）-->')
+  L.push('')
+
+  L.push('#### 探针 5：API Contract Parity')
+  L.push(`- ${probe5.summary || `backend ${probe5.backendCount ?? 0} 端点 / frontend ${probe5.frontendCount ?? 0} 调用`}`)
+  if ((probe5.missingBackend || []).length > 0) {
+    L.push('')
+    L.push('| 状态 | 前端调用 | 后端端点 | 文件 |')
+    L.push('|---|---|---|---|')
+    for (const m of probe5.missingBackend) {
+      L.push(`| ❌ missing | ${m.method} ${m.path} | — | ${m.consumerFile || '?'}${m.consumerLine ? ':' + m.consumerLine : ''} |`)
+    }
+    L.push('')
+    L.push('- ❌ contract gap 是真实集成缺陷——诚实判 FAIL 并回 execute 补端点（CLI 仅 advisory 不硬阻断）')
+  }
+  if ((probe5.unusedBackend || []).length > 0) {
+    L.push(`- ⚠️ ${probe5.unusedBackend.length} 个后端端点前端未调用（warning 不阻断）：${probe5.unusedBackend.slice(0, 5).map(u => `${u.method} ${u.path}`).join('、')}${probe5.unusedBackend.length > 5 ? ' …' : ''}`)
+  }
+  L.push('')
+
+  L.push('#### 探针 6：代码删除对账')
+  if (probe6.deletions.length === 0) {
+    L.push('- ✅ git diff 无整文件删除（D/R/C）记录')
+  } else {
+    for (const d of probe6.deletions) {
+      L.push(`- ${d.verdict} \`${d.path}\`（git 状态 ${d.status}）`)
+    }
+  }
+  L.push(`- ℹ️ ${probe6.note}`)
+  return L.join('\n')
+}
+
+/**
+ * 生成 verify-result.md 骨架（七章节；探针结果机械预填，语义章节 <!--TODO--> 占位）。
+ * 结论章节留「待填」——extractVerifyConclusion 无 PASS/FAIL 关键词即判不过，骨架不能直接过门。
+ * @returns {string|null} 骨架全文；无 design.md/tasks.md（非完整流程变更）→ null
+ */
+export function generateVerifyResultSkeleton(result) {
+  const L = [
+    '# 验证报告（骨架由 `sillyspec verify-probes --change <变更名> --init` 生成）',
+    '',
+    '> 探针结果已机械预填；其余章节把 `<!--TODO-->` 替换为真实内容。**结论必须写明 PASS / FAIL**——',
+    '> 留「待填」会被 gate 判不过（fail-closed）。',
+    '',
+    '## 结论：<待填：PASS 或 FAIL（+一句话理由）>',
+    '',
+    '## 任务完成度',
+    '<!--TODO: 逐 task 对照 tasks.md 勾选与验收标准，完成/未完成/存疑三态-->',
+    '',
+    '## 设计一致性',
+    '<!--TODO: 实现与 design.md 的偏差（无偏差也显式写「一致」）-->',
+    '',
+    '## 探针结果（CLI 机械预填）',
+    renderVerifyProbesReport(result),
+    '',
+    '## 测试结果',
+    '<!--TODO: 测试命令 + 结果（通过数/失败数；known_failures 豁免逐条注明）-->',
+    '',
+    '## 决策追踪矩阵（如存在 decisions.md；无则删本节）',
+    '<!--TODO: | 决策 ID | FR | Task | Evidence | 状态 |（D-xxx@vN → FR-xxx → task → 证据回指闭环）-->',
+    '',
+    '## 技术债务',
+    '<!--TODO: TODO/FIXME/HACK 统计（探针 1 的命中已预填在上方探针结果）-->',
+    '',
+    '## 变更风险等级',
+    '<!--TODO: doc-only / unit-sufficient / contract-required / integration-critical / deployment-critical；若 design.md frontmatter 有 risk_level 显式声明，写明「显式声明 = <等级>」+ 理由（豁免可审计）-->',
+    '',
+    '## Runtime Evidence',
+    '<!--TODO: 关键命令输出/时间戳/commit hash 证据链；integration/deployment-critical 必填，按实际触碰的运行时组件写（启动命令/端点/请求响应/日志片段/生命周期终态断言/失败模式排除），未涉及的行写「不涉及」-->',
+    '',
+    '## 代码审查',
+    '<!--TODO: 问题列表 + 总体评价-->',
+    '',
+  ]
+  return L.join('\n')
+}

package/src/workspace.js

@@ -0,0 +1,125 @@
+/**
+ * workspace.js — `sillyspec workspace add/remove/status` 的多项目工作区管理
+ * （2026-08-21 agent-手工产出审计第四批 C-1）。
+ *
+ * workspace skill 此前纯手写：`.sillyspec/projects/<name>.yaml` 5 字段 YAML 手编、remove 手删
+ * 文件手 commit、status 用 bash for-loop + grep/sed 解析 YAML 逐项目 cd 探测——skill 明言
+ * 「CLI 没有 workspace 命令」。本模块命令化全部机械面：
+ *   - add：YAML 外科写入（name/path/status 必填 + role/repo 可选追加，已有字段保留）、路径校验
+ *   - remove：删 yaml（--commit 时顺带 git add 该删除）
+ *   - status：逐项目探测（yaml 解析 + .sillyspec 产物存在性），输出 skill 原格式的三态表
+ * init 语义对齐（skill L75）：init 只写 name/path/status 三字段，role/repo 是 add 专属追加。
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, mkdirSync } from 'fs'
+import { join, basename, resolve } from 'path'
+import { resolveSpecDir } from './run/shared.js'
+
+function parseSimpleYaml(text) {
+  const out = {}
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/)
+    if (m) out[m[1]] = m[2].trim()
+  }
+  return out
+}
+
+function readProjectYaml(specBase, name) {
+  const p = join(specBase, 'projects', `${name}.yaml`)
+  if (!existsSync(p)) return null
+  return parseSimpleYaml(readFileSync(p, 'utf8'))
+}
+
+/**
+ * 新增/更新子项目登记。
+ * @param {{ cwd: string, name: string, path: string, role?: string|null, repo?: string|null, specDir?: string|null }} opts
+ * @returns {{ file: string, created: boolean, fieldsKept: string[] }}
+ * @throws {Error} name 非法 / path 不存在
+ */
+export function workspaceAdd({ cwd, name, path: projPath, role = null, repo = null, specDir = null }) {
+  if (!name || !/^[A-Za-z0-9_.\-]+$/.test(name)) {
+    throw new Error(`子项目名非法: "${name}"（限字母数字 . _ -，作 yaml 文件名）`)
+  }
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const abs = resolve(cwd, projPath)
+  if (!existsSync(abs)) {
+    throw new Error(`路径不存在: ${abs}`)
+  }
+  const yamlPath = join(specBase, 'projects', `${name}.yaml`)
+  const existed = existsSync(yamlPath)
+  const prev = existed ? parseSimpleYaml(readFileSync(yamlPath, 'utf8')) : {}
+  // init 三字段 + add 追加字段；已有值优先保留（幂等重跑不覆盖手调内容）
+  const fields = {
+    name,
+    path: projPath.replace(/\\/g, '/'),
+    status: prev.status || 'active',
+  }
+  if (role) fields.role = role
+  else if (prev.role) fields.role = prev.role
+  if (repo) fields.repo = repo
+  else if (prev.repo) fields.repo = prev.repo
+  const fieldsKept = Object.keys(prev).filter(k => fields[k] === prev[k] && k !== 'name' && k !== 'path')
+  mkdirSync(join(specBase, 'projects'), { recursive: true })
+  // 追加不认识的手写字段（防整文件重序列化丢内容）
+  for (const k of Object.keys(prev)) {
+    if (!(k in fields)) fields[k] = prev[k]
+  }
+  const text = Object.entries(fields).map(([k, v]) => `${k}: ${v}`).join('\n') + '\n'
+  writeFileSync(yamlPath, text)
+  return { file: yamlPath, created: !existed, fieldsKept }
+}
+
+/**
+ * 移除子项目登记（删 yaml；git add 由调用方/CLI 层做）。
+ * @returns {{ file: string }} @throws {Error} 不存在
+ */
+export function workspaceRemove({ cwd, name, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const yamlPath = join(specBase, 'projects', `${name}.yaml`)
+  if (!existsSync(yamlPath)) throw new Error(`子项目不存在: ${yamlPath}`)
+  unlinkSync(yamlPath)
+  return { file: yamlPath }
+}
+
+/**
+ * 工作区状态探测（skill 3d 的命令化）：逐项目 yaml 解析 + 三态探测。
+ * @returns {{ projects: Array<{name, path, role, state, detail}>, sharedDocs: string[] }}
+ *   state ∈ initialized（有 .sillyspec）/ scanned（docs/<name>/scan 有文档）/ unregistered（无 .sillyspec）
+ */
+export function workspaceStatus({ cwd, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const projects = []
+  const projDir = join(specBase, 'projects')
+  if (existsSync(projDir)) {
+    for (const f of readdirSync(projDir).filter(f => f.endsWith('.yaml')).sort()) {
+      const y = parseSimpleYaml(readFileSync(join(projDir, f), 'utf8'))
+      const name = y.name || basename(f, '.yaml')
+      const projAbs = resolve(cwd, y.path || '.')
+      let state
+      let detail
+      if (!existsSync(projAbs)) {
+        state = 'missing'
+        detail = '路径不存在（yaml 的 path 失效）'
+      } else if (!existsSync(join(projAbs, '.sillyspec'))) {
+        state = 'unregistered'
+        detail = '未初始化（无 .sillyspec）'
+      } else {
+        const scanDir = join(projAbs, '.sillyspec', 'docs', name, 'scan')
+        let scanCount = 0
+        try { scanCount = readdirSync(scanDir).filter(x => x.endsWith('.md')).length } catch {}
+        if (scanCount > 0) {
+          state = 'scanned'
+          detail = `已扫描（${scanCount} 份文档）`
+        } else {
+          state = 'initialized'
+          detail = '已初始化（未扫描）'
+        }
+      }
+      projects.push({ name, path: y.path || '?', role: y.role || '', state, detail })
+    }
+  }
+  let sharedDocs = []
+  try {
+    sharedDocs = readdirSync(join(specBase, 'shared')).filter(f => f.endsWith('.md')).sort()
+  } catch {}
+  return { projects, sharedDocs }
+}

package/src/worktree-apply.js

@@ -12,7 +12,7 @@
  * 8. 成功后自动 cleanup
  */
 
-import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync, readFileSync } from 'fs';
+import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync, readFileSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { WorktreeManager } from './worktree.js';
@@ -694,6 +694,20 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
     result.ok = true;
 
+    // --- 7.5 提交复用 pathspec（坑 apply-commit-pathspec-sweep，2026-08-21 实证）---
+    // apply 后主仓常混有无关未提交文件（他者会话/并行 quick），agent 习惯 `git add <目录>/`
+    // 会把无关文件扫进暂存需手工剔除。落盘本变更精确 pathspec 供提交直接复用：
+    // 文件 + result 字段（CLI 输出可照抄 git add -- … / 长清单用 --pathspec-from-file）。
+    try {
+      const commitFiles = [...new Set(patchFiles)].sort().filter(Boolean);
+      result.commitPathspec = commitFiles;
+      const runtimeRoot = join(projectRoot, '.sillyspec', '.runtime');
+      mkdirSync(runtimeRoot, { recursive: true });
+      const pathspecFile = join(runtimeRoot, `apply-pathspec-${changeName}.txt`);
+      writeFileSync(pathspecFile, commitFiles.join('\n') + '\n');
+      result.pathspecFile = pathspecFile;
+    } catch { /* pathspec 落盘失败不影响 apply 结果 */ }
+
     // --- 8. 成功后自动 cleanup（失败不影响整体结果） ---
     try {
       wm.cleanup(changeName, { force: true });

package/src/worktree.js

@@ -907,11 +907,32 @@ export class WorktreeManager {
 
     // 4. 删除分支（fail-closed：task review 引用可达性校验。force 也不绕过——force 语义 =
     //    丢弃内容，不含丢弃审计链；确要删用 git branch -D 手动执行）
+    //    升级（坑 cleanup-branch-review-anchor-tag，2026-08-21 实证）：分支被 review.json 引用
+    //    时不再只能手动保留——打 `sillyspec-audit/<branch>` 轻量 tag 锚定分支 tip（ref 前缀独立
+    //    于 sillyspec/* 分支族，doctor 孤儿分支扫描不误伤），commit 经 tag 保持可达（gc 安全），
+    //    随后正常删分支。tag 创建失败 → 回退保留（宁保留勿丢审计链）。
     try {
       const reviewRefs = this._branchReviewReferences(branch);
       if (reviewRefs.length > 0) {
-        details.push(`branch kept: ${reviewRefs.length} 个 task review.json 引用分支上的 commit（base/head 审计保护）`);
-        console.log(`🔗 分支保留：${branch} 上有 ${reviewRefs.length} 个 task review.json 引用其 commit（apply 只复制文件内容，ref 删除后 base/head 悬空无法复核）。确要删除：git branch -D ${branch}`);
+        const tagName = 'sillyspec-audit/' + branch;
+        let tagOk = false;
+        try {
+          if (!gitQuiet(this.cwd, ['rev-parse', '--verify', '--quiet', `refs/tags/${tagName}`])) {
+            git(this.cwd, ['tag', tagName, branch]);
+          }
+          tagOk = true;
+        } catch (e) {
+          details.push(`audit tag creation failed: ${e.message}`);
+        }
+        if (tagOk) {
+          gitQuiet(this.cwd, ['branch', '-D', branch]);
+          details.push(`branch deleted after anchoring tip to tag ${tagName} (audit 链可达)`);
+          console.log(`🔗 审计锚定：${branch} 被 ${reviewRefs.length} 个 task review.json 引用其 commit——已打 tag ${tagName} 锚定（commit 保持可达，gc 安全）并删除分支 ref。`);
+          console.log(`   确认不再需要该审计链后可删 tag：git tag -d ${tagName}`);
+        } else {
+          details.push(`branch kept: ${reviewRefs.length} 个 task review.json 引用分支上的 commit（base/head 审计保护）`);
+          console.log(`🔗 分支保留：${branch} 上有 ${reviewRefs.length} 个 task review.json 引用其 commit（apply 只复制文件内容，ref 删除后 base/head 悬空无法复核）。确要删除：git branch -D ${branch}`);
+        }
       } else {
         gitQuiet(this.cwd, ['branch', '-D', branch]);
         details.push('branch deleted');
@@ -1388,6 +1409,13 @@ export class WorktreeManager {
    * 将主工作区未提交变更同步到 worktree（dirty baseline overlay）
    * 覆盖 staged + unstaged 的文件变更，以及 untracked 文件。
    * 使用 git diff + git apply 确保正确处理删除/rename/binary。
+   *
+   * .sillyspec/ 隔离（坑 baseline-overlay-cross-change-contamination，2026-08-21 实证）：
+   * overlay 原样全量吸收主仓未提交改动——多变更并行时其他变更的 spec 文档
+   * （changes/<他变更>/、ROADMAP.md、quicklog 等 39 个文件实测）被 checkpoint 进本变更
+   * baseline，apply 回 main 即随本变更交付，需人工隔离。spec 文档不参与 worktree 内
+   * 构建/测试（execute 的 spec 读写经 specDriftAnchor 锚回主仓），排除零功能损失；
+   * 排除清单显式打印保持可见（哪些跨变更文件被隔离、去哪了）。
    * @param {string} mainCwd - 主工作区路径
    * @param {string} worktreePath - worktree 路径
    * @returns {Array<string>} overlay 的文件列表
@@ -1395,15 +1423,26 @@ export class WorktreeManager {
   _overlayBaseline(mainCwd, worktreePath) {
     const files = [];
     const errors = [];
+    // git pathspec 排除（execFileSync 数组传参不经 shell，字面安全）：.sillyspec/ 整目录
+    const EXCLUDE_PATHSPEC = ':(exclude).sillyspec';
+    const collectExcluded = (raw, excluded) => {
+      for (const f of raw.split('\n').filter(Boolean)) {
+        const norm = f.replace(/\\/g, '/')
+        if (norm === '.sillyspec' || norm.startsWith('.sillyspec/')) excluded.push(f)
+      }
+    }
 
     try {
-      // staged 变更
-      const staged = gitQuiet(mainCwd, ['diff', '--cached', '--name-only'], { timeout: 30000 }) || '';
+      const excludedSpecFiles = [];
+      // staged 变更（pathspec 排除 .sillyspec/——跨变更 spec 文档不进 baseline）
+      const staged = gitQuiet(mainCwd, ['diff', '--cached', '--name-only', '--', '.', EXCLUDE_PATHSPEC], { timeout: 30000 }) || ''
+      const stagedAll = gitQuiet(mainCwd, ['diff', '--cached', '--name-only'], { timeout: 30000 }) || ''
+      collectExcluded(stagedAll, excludedSpecFiles)
       if (staged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
           // QUAL-01 收口：git-helper 新增 encoding:'buffer' 支持（二进制输出专用，跳过 trim）
-          const patchBuf = git(mainCwd, ['diff', '--cached', '--binary'], { encoding: 'buffer', timeout: 30000 });
+          const patchBuf = git(mainCwd, ['diff', '--cached', '--binary', '--', '.', EXCLUDE_PATHSPEC], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
             try {
@@ -1421,12 +1460,14 @@ export class WorktreeManager {
         files.push(...staged.split('\n').filter(Boolean));
       }
 
-      // unstaged 变更
-      const unstaged = gitQuiet(mainCwd, ['diff', '--name-only'], { timeout: 30000 }) || '';
+      // unstaged 变更（同上 pathspec 排除）
+      const unstaged = gitQuiet(mainCwd, ['diff', '--name-only', '--', '.', EXCLUDE_PATHSPEC], { timeout: 30000 }) || ''
+      const unstagedAll = gitQuiet(mainCwd, ['diff', '--name-only'], { timeout: 30000 }) || ''
+      collectExcluded(unstagedAll, excludedSpecFiles)
       if (unstaged) {
         try {
           // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏（QUAL-01 收口，同上）
-          const patchBuf = git(mainCwd, ['diff', '--binary'], { encoding: 'buffer', timeout: 30000 });
+          const patchBuf = git(mainCwd, ['diff', '--binary', '--', '.', EXCLUDE_PATHSPEC], { encoding: 'buffer', timeout: 30000 });
           if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
             try {
@@ -1448,6 +1489,8 @@ export class WorktreeManager {
       const skippedDirs = [];
       if (untracked) {
         for (const f of untracked.split('\n').filter(Boolean)) {
+          const norm = f.replace(/\\/g, '/')
+          if (norm === '.sillyspec' || norm.startsWith('.sillyspec/')) { excludedSpecFiles.push(f); continue }
           const r = copyUntrackedEntry(join(mainCwd, f), join(worktreePath, f));
           if (r.status === 'copied') files.push(f);
           else if (r.status === 'skipped-dir') skippedDirs.push(f);
@@ -1457,6 +1500,13 @@ export class WorktreeManager {
       if (skippedDirs.length > 0) {
         console.log(`ℹ️  baseline overlay 跳过 ${skippedDirs.length} 个 untracked 目录（不读目录避免 EISDIR，坑 execute-worktree-overlay-untracked-dir-eisdir）`);
       }
+      // 跨变更 spec 文档隔离可见性：列出被排除的 .sillyspec/ 文件（去重，截断展示），
+      // 让「ROADMAP 被谁改动、为何不在本 baseline」在 create 时刻可查，不需事后考古
+      const excludedUnique = [...new Set(excludedSpecFiles)]
+      if (excludedUnique.length > 0) {
+        const preview = excludedUnique.slice(0, 8).join(', ') + (excludedUnique.length > 8 ? ` …（共 ${excludedUnique.length} 个）` : '')
+        console.log(`🧹 baseline overlay 已隔离 ${excludedUnique.length} 个 .sillyspec/ 未提交文件（跨变更 spec 文档不进本变更 baseline，留在主仓各自归属）：${preview}`)
+      }
 
       if (files.length > 0) {
         console.log(`📁 baseline overlay: ${files.length} 个未提交文件已同步到 worktree`);

package/templates/claude-instruction.md

@@ -18,6 +18,6 @@
 12. **hook 拦截提交时禁止跳过**（`.husky/pre-push`），修复问题后再提交。
 13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
 14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
-15. **quicklog 手动精修**：CLI 只写骨架，`--done` 后手动补语义化标题 / 文件多行带括注 / 结果四段。
+15. **quicklog 结构化落盘**：末步 `--done` 用四参数 `--req/--cause/--solution/--result`（CLI 合成结构化 output 并自动提取标题/四段分行）；文件括注用 `--file-notes "path::注 || path2"`。骨架由 CLI 接管，`--done` 后按需核对即可，勿手拼模板。
 16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
 17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。

package/templates/prompts/taskcard-rules.md

@@ -25,4 +25,4 @@ TaskCard 格式规则（必须严格遵守）：
   - **规范约定字段**（应填但不硬校验，缺失不阻断完成、只影响规范性）：author、created_at、priority、depends_on、blocks
   - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
   - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
-- 写完后用 Write tool 保存到文件
+- **生成方式**：用 `sillyspec taskcard <change-name> --task task-NN [--all]` 生成安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改

package/templates/prompts/verify-probes.md

@@ -1,14 +1,11 @@
 ### 自动探针（必须先执行）
-在检查前，依次运行以下六个探针，将结果作为验证输入：
 
-**探针 1：未实现标记扫描（仅变更文件）**
-只扫描本次变更涉及的文件，不要全项目扫描——历史 TODO 与本次变更无关，徒增噪音与 token。变更文件 = design.md「文件变更清单」列出的源码文件（你已在「加载规范」步骤读取 design.md，glob 路径需展开为具体文件）：
-```bash
-grep -n "尚未实现\|TODO\|FIXME\|HACK\|XXX" <design 清单中的源码文件>
-```
-记录每个匹配的文件、行号和内容。
+> 🔧 **先跑 CLI 机械探针（一条命令）**：`sillyspec verify-probes --change <change-name> [--init]`
+> 输出已包含四个纯机械探针的结果（可直接进验证报告）：**探针 1** 未实现标记扫描（design 清单文件逐行 TODO/FIXME 命中 + 行号）、**探针 3** 测试文件递归查找（含 co-located tests/，逐 task 覆盖）、**探针 5** API 契约对账表（endpoints.json × 前端调用 diff）、**探针 6** 删除对账三态（git 事实 × design 声明）。`--init` 顺带生成 verify-result.md 九章节骨架（探针结果已预填，`<!--TODO-->` 占位替换即可）。
+>
+> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
 
-**探针 2：设计关键词覆盖探针**
+**探针 2：设计关键词覆盖探针（你执行——关键词提取是语义）**
 1. 读取 design.md，从中提取所有能力关键词（如"登录"、"导出"、"批量"、"删除"、"搜索"等动作词）
 2. 对每个关键词，在源码目录中 grep 确认是否有对应的实现代码：
 ```bash
@@ -16,14 +13,11 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 ```
 3. 如果某个关键词在源码中完全没有匹配，标记为 ⚠️ 可能未实现
 
-**探针 3：验收标准测试覆盖探针**
-1. 读取变更目录下的 tasks.md，提取所有 checkbox 任务
-2. 对每个 task，**递归**检查对应模块目录及其**所有子目录**下是否存在测试文件（*test*、*spec*、*Test*、*Spec*）——包括模块内 co-located 的 tests/ 目录（如 `backend/app/modules/*/tests/`），**不要只看顶层 `tests/`**，否则会把测试就在模块内部的项目误判为“无测试”
-3. 没有测试文件的 task 标记为 ⚠️ 缺少测试
-4. **集成盲区提示**：测试文件存在 ≠ 集成正确——路由/layout 守卫重定向、跨模块装配这类集成 bug 组件单测覆盖不到，只有集成/冒烟/E2E 才暴露。对路由/layout/跨进程装配敏感的 task，额外检查是否有集成冒烟覆盖；无则标 ⚠️ 集成层未验证（需人工或部署确认）
-5. **断言有效性抽查（与 execute「测试用例设计」闭环）**：测试文件存在 ≠ 测试有效。对最能代表本次变更行为的 2-3 个核心测试做抽查：① 断言验证真实输出/副作用，不是只"不抛错"的空断言、只测 getter/setter；② 覆盖边界/异常分支，不只业务正例；③ 走公开 API 测行为，不测实现细节（重构后功能不变测试不应失败）。不达标标 ⚠️ 断言薄弱或无效（advisory：CLI 不阻断，是否 FAIL 由你诚实判定；execute 已按「测试用例设计」写的，这里只抽查核验，不重审全量）
+**探针 3 补充（CLI 已查存在性，你补语义）**
+- **集成盲区提示**：测试文件存在 ≠ 集成正确——路由/layout 守卫重定向、跨模块装配这类集成 bug 组件单测覆盖不到，只有集成/冒烟/E2E 才暴露。对路由/layout/跨进程装配敏感的 task，额外检查是否有集成冒烟覆盖；无则标 ⚠️ 集成层未验证（需人工或部署确认）
+- **断言有效性抽查（与 execute「测试用例设计」闭环）**：测试文件存在 ≠ 测试有效。对最能代表本次变更行为的 2-3 个核心测试做抽查：① 断言验证真实输出/副作用，不是只"不抛错"的空断言、只测 getter/setter；② 覆盖边界/异常分支，不只业务正例；③ 走公开 API 测行为，不测实现细节（重构后功能不变测试不应失败）。不达标标 ⚠️ 断言薄弱或无效（advisory：CLI 不阻断，是否 FAIL 由你诚实判定；execute 已按「测试用例设计」写的，这里只抽查核验，不重审全量）
 
-**探针 4：决策追踪覆盖探针（如存在 decisions.md）**
+**探针 4：决策追踪覆盖探针（如存在 decisions.md——闭环图机械，证据真伪是语义）**
 1. 从 decisions.md 提取所有当前版本 D-xxx@vN
 2. 检查 requirements.md 是否引用每个 D-xxx@vN，并映射到 FR-xxx
 3. 检查 plan.md 或 tasks/task-NN.md 是否引用每个 FR-xxx/D-xxx@vN
@@ -31,36 +25,8 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 5. 任意 D-xxx@vN 无下游覆盖时标记为 ⚠️ 决策未闭环
 6. 任意 P0/P1 unresolved/blocking 决策标记为 FAIL blocker
 
-**探针 5：API Contract Parity Check（跨前后端契约对账）**
-此探针仅在以下条件满足时执行：
-- 存在 \.sillyspec/.runtime/contract-artifacts/ 目录（说明 execute 阶段生成了 endpoint artifact）
-- 或者项目同时有 backend/ 和 frontend/ 目录
-
-执行步骤：
-1. 收集所有 provider endpoint artifacts：
-   - 读取 .sillyspec/.runtime/contract-artifacts/*/endpoints.json
-   - 汇总为 backend 端点清单
-2. 扫描前端 API 调用：
-   - 在 frontend/ 目录中搜索 apiFetch/request/axios/fetch 调用
-   - 提取所有 API 路径（归一化动态参数为 {param}）
-3. Diff 对账：
-   - 前端调用路径在 backend 端点清单中找不到 → **❌ Missing backend endpoint**（advisory：CLI 复核后仅 warn，不硬阻断归档；但 contract gap 是真实集成缺陷，应诚实标 FAIL 并回 execute 补端点）
-   - backend 端点在前端无调用 → ⚠️ Unused backend endpoint（warning，不阻断）
-4. 输出对账结果表格（示例用通用占位路径，实际填本仓真实文件）：
-
-   | 状态 | 前端调用 | 后端端点 | 文件 |
-   |---|---|---|---|
-   | ❌ missing | GET /api/<域>/<资源>/<param> | — | <前端调用所在文件，如 src/lib/<模块>.ts> |
-
-如果发现 Missing backend endpoint，在验证报告中标记为 ❌ contract gap（CLI 仅 advisory 提示、不硬阻断归档；但缺口真实存在——诚实判 FAIL 并回 execute 补齐端点，勿因 CLI 不拦而放行）。
+**探针 5 补充（CLI 已出对账表，你做诚实判定）**
+CLI 的 missing backend endpoint 是 advisory（不硬阻断归档）——但 contract gap 是真实集成缺陷，应诚实标 FAIL 并回 execute 补端点，勿因 CLI 不拦而放行。后端 router 的端点清单可用 `sillyspec endpoints extract --change <变更名> --task <task-NN>` 重新静态提取（勿手扫装饰器）。
 
-**探针 6：代码删除对账（切斯特顿栅栏护栏）**
-静默删除代码是 verify 的盲区——agent 删一段它看不懂的旧代码，只要路径合规、不碰风险关键词，其他探针都不会响。用 git 事实客观对账，不要凭记忆：
-1. 运行 `git diff --name-status HEAD`（本次变更已 apply 到主仓、未 commit，删除的文件在工作树消失但仍在 HEAD，显示 `D`）
-2. 筛出状态以 `D` 开头的行（删除）；`R`/`C` 开头的旧路径等价删除
-3. 对每个删除文件，核对 design.md「文件变更清单」声明的操作：
-   - design 声明「删除」→ ✅ 合规（预期删除）
-   - design 声明「新增/修改」却整文件删除 → ❌ 高风险（声明与事实矛盾）
-   - design 清单未列出 → ⚠️ 未声明删除
-4. 排除 `.sillyspec/` 与 `meta.json`（文档 churn 不算删除信号）
-5. verify --done 时 CLI 会用同一 git 事实 advisory 复核（打印警告，不硬阻断归档）——是否 FAIL blocker 由你诚实判定，务必如实记录
+**探针 6 补充（CLI 已出三态判定，你做终审）**
+以 git 事实为准（真实 > 声明）；CLI 的三态（合规/高风险/未声明）是机械判定，是否构成 FAIL blocker 由你诚实判定，务必如实记录——静默删除代码是 verify 的最大盲区。