sillyspec 3.28.3 → 3.28.5

package/src/docs-check.js

@@ -36,8 +36,11 @@ import { parseModuleMapSimple } from './modules.js'
  * 展开循环每次迭代必含括号段 → 划分唯一 → 线性。 */
 const REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]*(?:\([A-Za-z0-9_.\-\/]+\)[A-Za-z0-9_.\-\/]*)*\.(?:js|mjs|cjs|ts|tsx|jsx|py|java|go)):(\d+)(?:-(\d+))?/g
 
-/** 缺省扫描范围：docs/ + .sillyspec/docs/（scan/modules 产物同是文档，失效即该暴露；2026-08-16 用户裁决改缺省，见 doc-consistency-debt.md §八） */
-export const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
+/** 缺省扫描范围：docs/ + .sillyspec/docs/（scan/modules 产物同是文档，失效即该暴露；2026-08-16 用户裁决改缺省，见 doc-consistency-debt.md §八）
+ * + .sillyspec/changes/ + .sillyspec/knowledge/（P1-1，noai-ir-roadmap §4：最活跃、最易产生
+ * 漂移引用的变更目录与决策库此前零校验——纳入后 verify/archive 收尾的 autoReanchorDocRefs
+ * 同时覆盖变更文档（archive/ 路径段与 doc_type: snapshot 双通道豁免不变，归档件不回检）。 */
+export const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md', '.sillyspec/changes/**/*.md', '.sillyspec/knowledge/**/*.md']
 
 /**
  * 读 local.yaml 的 docs-check 段（best-effort，绝不抛；缺文件/无段 → 全缺省）。
@@ -73,6 +76,32 @@ export function readDocsCheckConfig(projectRoot) {
 /** 配置错误（glob 形态不支持等）→ CLI exit 2 */
 export class DocsCheckConfigError extends Error {}
 
+/**
+ * 符号锚正则（P1-2，noai-ir-roadmap §4）：`file.js::symbol` 形态——校验时解析符号定义行，
+ * 天然免疫行号漂移（重锚从「每次代码移动」降为「仅改名时」）。文件段与 REF_RE 同款（含
+ * repo:// 跨仓前缀与括号路径组展开），`::` 后只认 ASCII 标识符（自然语言/中文括注不触发，
+ * QUICKLOG file-notes 的 `path::注` 约定因注解非标识符而天然互斥）。与 REF_RE 互斥：
+ * `::ident` 无数字不匹配行号式；`file.js:12` 无 `::` 不匹配符号式。
+ */
+const SYMBOL_REF_RE = /(?:repo:\/\/([A-Za-z0-9_.\-]+)\/)?([A-Za-z0-9_.\-\/]*(?:\([A-Za-z0-9_.\-\/]+\)[A-Za-z0-9_.\-\/]*)*\.(?:js|mjs|cjs|ts|tsx|jsx|py|java|go))::([A-Za-z_$][A-Za-z0-9_$]*)/g
+
+/**
+ * 符号定义行定位（与 classifyFix 的 defRe 同款形态，单一判定口径）：function/const/let/
+ * class/def（含 export/async 前缀）后的精确符号名。命中返回 1-based 行号；文件内仅
+ * 「使用」未「定义」（import 消费/注释提及）不算命中——符号锚指向定义文件。
+ * @param {string[]} lines 源文件行数组
+ * @param {string} symbol 符号名（须为合法标识符）
+ * @returns {number|null}
+ */
+export function findSymbolDefLine(lines, symbol) {
+  if (!Array.isArray(lines) || !symbol || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(symbol)) return null
+  const defRe = new RegExp(`(?:export\\s+)?(?:async\\s+)?(?:function\\*?\\s+|class\\s+|(?:const|let|var)\\s+|def\\s+)${escapeReLocal(symbol)}\\b`)
+  for (let i = 0; i < lines.length; i++) {
+    if (defRe.test(lines[i])) return i + 1
+  }
+  return null
+}
+
 /**
  * 纯函数：从 markdown 全文提取全部 file:line 引用。
  * @param {string} md 文档全文
@@ -101,6 +130,22 @@ export function collectDocRefs(md) {
       docLine: line,
     })
   }
+  // 符号锚引用（P1-2）：独立正则二遍扫描（与行号式互斥，无重叠去重需求）。
+  // 符号式引用量级远小于行号式，docLine 逐个 O(index) 计算不构成退化面。
+  const symRe = new RegExp(SYMBOL_REF_RE.source, 'g')
+  let sm
+  while ((sm = symRe.exec(md)) !== null) {
+    refs.push({
+      ref: sm[0],
+      repo: sm[1] !== undefined ? sm[1] : null,
+      file: sm[2],
+      symbol: sm[3],
+      kind: 'symbol',
+      start: null,
+      end: null,
+      docLine: md.slice(0, sm.index).split('\n').length,
+    })
+  }
   return refs
 }
 
@@ -452,6 +497,8 @@ export function runDocsCheck(opts) {
   let skippedExempt = 0
   // 模糊路径引用数（含 `...` 省略号，跳过校验——FR-1.2）
   let skippedFuzzy = 0
+  // 符号锚（P1-2）命中数（计入 total，单独计数供可见性）
+  let symbolChecked = 0
   // per-call 缓存：裸名引用的 src/ 全树扫描结果 + 候选文件行数组——100 文档 × 10 裸名引用
   // 此前 = 1000 次全树 walk + 同文件 N 次重读（2026-08-21 性能审查 PERF-5）。仅本次调用
   // 生命周期内有效，不跨调用（防测试流程中途改树后读到陈旧结果）
@@ -522,6 +569,24 @@ export function runDocsCheck(opts) {
         })
         continue
       }
+      // 符号锚（P1-2）：按「候选文件内存在符号定义行」判定——不校验行号（校验时解析，
+      // 行漂移天然免疫），层 2 关键词断言由符号本身命中自动满足。失效只可能是符号拼错/
+      // 文件归属错/符号被删改名——均非重锚能修，fix 显式不可自动。
+      if (r.kind === 'symbol') {
+        let hit = false
+        for (const candAbs of candidates) {
+          const lines = readLines(candAbs, linesCache)
+          if (lines === null) continue
+          if (findSymbolDefLine(lines, r.symbol) !== null) { hit = true; break }
+        }
+        if (hit) { symbolChecked++; continue }
+        invalid.push({
+          doc: docRel, docLine: r.docLine, ref: r.ref,
+          reason: `符号锚未命中：候选文件内无 \`${r.symbol}\` 的定义行（function/const/let/var/class/def 形态）——符号锚不随行号漂移，失效即符号拼错/归属错/已删改名`,
+          fix: { fixable: false, reason: '符号锚失效非重锚可修：核对符号拼写或文件归属（改名请同步文档符号）' },
+        })
+        continue
+      }
       // 多候选宽容：逐候选跑层1+层2，任一全过即通过
       const tokens = keywordAssert
         ? extractExpectedTokensFromLine(mdLines[r.docLine - 1] || '')
@@ -558,7 +623,7 @@ export function runDocsCheck(opts) {
     }
   }
 
-  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped, skippedExempt, skippedFuzzy }
+  return { ok: invalid.length === 0, total, invalid, warnings, kwChecked, crossRepoSkipped, skippedExempt, skippedFuzzy, symbolChecked }
 }
 
 /**
@@ -1122,3 +1187,37 @@ export function runChangeNameAdvisory(opts) {
   findings.sort((a, b) => a.doc.localeCompare(b.doc) || a.docLine - b.docLine || a.name.localeCompare(b.name))
   return { empty: scanned === 0, scannedDocs: scanned, mentions, uniqueNames: seenNames.size, findings, exempted }
 }
+
+/**
+ * 行号漂移自动重锚（quick --done 接线面，2026-09-08 用户反馈②）：活文档 file:line 硬编码
+ * 随任何源码插入失效，每回手跑 `docs check --fix` 是机械活。本函数 = --fix 主链路的编程化
+ * 封装：对给定文档集跑一次失效收集 → 取分类器判定确定性的条目（fixable 唯一/优选命中，
+ * 与 index.js --fix 同源构造 fixes）→ applyFixes 写回 → 同口径复跑得回执。
+ *
+ * 边界（与 --fix 的既定红线一致）：歧义/零命中条目不动（无 --force 逃生口）；仅改写
+ * fixable 条目的行号段，文件名与 token 原样。任何异常上抛由调用方 fail-open。
+ *
+ * @param {string} projectRoot 源码仓根
+ * @param {string[]} docs 本次改动文档的相对路径列表（audit 口径：changedFiles 中的 .md）
+ * @param {{ crossRepoRoots?: string[] }} [cfg] docs-check 配置（readDocsCheckConfig 产物）
+ * @returns {{ applied: number, invalidBefore: number, invalidAfter: number, remaining: number }}
+ *   applied=0 时 invalidBefore/After 同值（无可自动修条目，调用方维持纯 advisory）
+ */
+export function autoReanchorDocRefs(projectRoot, docs, cfg = {}) {
+  // 与 index.js --fix 完全同口径（skip/keywordAssert 透传；undefined 时 runDocsCheck 解构
+  // 默认值兜底：paths 缺省 glob、keywordAssert=true、exempt=true）
+  const scope = { projectRoot, docs, skip: cfg.skip, keywordAssert: cfg.keywordAssert, crossRepoRoots: cfg.crossRepoRoots };
+  const before = runDocsCheck(scope);
+  const fixes = [];
+  for (const inv of before.invalid) {
+    if (inv.fix && inv.fix.fixable === true && Number.isInteger(inv.fix.newLine)) {
+      fixes.push({ doc: inv.doc, docLine: inv.docLine, ref: inv.ref, newRef: inv.ref.replace(/(\d+)(?:-\d+)?$/, String(inv.fix.newLine)) });
+    }
+  }
+  if (fixes.length === 0) {
+    return { applied: 0, invalidBefore: before.invalid.length, invalidAfter: before.invalid.length, remaining: before.invalid.length };
+  }
+  const applied = applyFixes(projectRoot, fixes);
+  const after = runDocsCheck(scope);
+  return { applied: applied.applied, invalidBefore: before.invalid.length, invalidAfter: after.invalid.length, remaining: after.invalid.length };
+}

package/src/doctor-diagnostics.js

@@ -16,6 +16,8 @@
  *   - 不删除/移动任何文件；orphan db 仅报告，处理交给后续 --dump-db / --confirm 流程。
  *   - execute-progress-plan-mismatch 维度同样只读：仅读 plan.md checkbox + 只读查 stages 表，
  *     绝不调用 ProgressManager 写方法（写操作是 progress.alignExecuteToPlan 的职责，D-001@v2 诊断/写分离）。
+ *   - 写动作是独立 opt-in 导出（--cleanup-ghosts / --gc-unstamped-runs / --cleanup-remnant），
+ *     与 --json 诊断路径分离；默认 dry-run，--confirm 才落盘。
  *
  * 风格对齐 scan-postcheck.js：checks 用 CHECK_SEVERITY，formatter 产出 schema_version JSON，
  * writer 落盘到 <authoritySpecDir>/.runtime/。
@@ -23,8 +25,10 @@
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { safeGit } from './git-helper.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
-import { join } from 'path';
+import { join, relative, resolve, dirname } from 'path';
+import { gitQuiet } from './git-helper.js'
 import jsYaml from 'js-yaml';
+import { pruneTimestampedEntries } from './runtime-hygiene.js';
 import { CHECK_SEVERITY } from './constants.js';
 import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE } from './run/shared.js';
 
@@ -239,15 +243,18 @@ function detectPointerHealth(pointer, cwd = null) {
     if (cwd) {
       const decl = checkPlatformManaged(cwd);
       if (decl) {
+        // 悬空声明检测（2026-09-09 §7-2，会话实证：.sillyspec-platform-managed 指向已删除的
+        // tmp 目录会挡住一切 CLI 命令）：声明 specRoot 不存在 = 平台会话已死/测试残留——
+        // disconnect 是唯一正解，点名前置（防用户对着死路径反复重建指针）。
+        const declDead = !!decl.specRoot && !existsSync(decl.specRoot)
         return {
           name: 'pointer_health',
           label: '平台指针健康',
           pass: false,
           severity: CHECK_SEVERITY.WARNING,
           findings: [
-            `pointer_missing_but_managed: 平台接管声明存在但恢复指针缺失（原 specRoot: ${decl.specRoot || '(未记录)'}）——` +
-            `裸调命令将 fail-closed 拒绝静默落本地。恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；` +
-            `② sillyspec platform disconnect（删除接管声明，彻底脱离平台）；③ 显式 --spec-dir <路径> 临时指定。`,
+            `pointer_missing_but_managed: 平台接管声明存在但恢复指针缺失（原 specRoot: ${decl.specRoot || '(未记录)'}${declDead ? '——⚠️ 该路径已不存在（平台会话已死/测试残留），重建指针无意义' : ''}）——` +
+            `裸调命令将 fail-closed 拒绝静默落本地。恢复：${declDead ? '建议直接 sillyspec platform disconnect（删除接管声明，脱离平台后走本地库）；' : '① 重跑平台 scan/init（带 --spec-root）重建指针；② sillyspec platform disconnect（删除接管声明，彻底脱离平台）；'}③ 显式 --spec-dir <路径> 临时指定。`,
           ],
           safe_actions: [{ dimension: 'pointer_health', action: 'recreate_pointer', risk: 'confirm_required', rationale: '接管声明存在但指针缺失，需重建指针或显式脱离平台', next_step: '重跑平台 scan（带 --spec-root）或 sillyspec platform disconnect' }],
         };
@@ -738,6 +745,191 @@ export function detectDocBloat(specRoot) {
     ? { ...dim, findings: ['模块卡与知识库体量在软限内'], pass: true, severity: CHECK_SEVERITY.PASSED }
     : { ...dim, pass: false, severity: CHECK_SEVERITY.WARNING };
 }
+// ══ 2026-09-09-doctor-noai：净增三类探测器（只读 fail-soft，skipped 带内降级）══
+
+/**
+ * worktree 健康（FR-02）：复用 WorktreeManager.doctor()（薄适配不重复探测——设计审查附加
+ * gap 修正）+ sillyspec/* 残留分支对账（vs changes/ 活跃目录）。锚定主仓根
+ * .sillyspec/.runtime/worktrees（worktree.js:24——勿用 runtimeRoot，平台模式分离只影响
+ * execute-runs 族）。
+ */
+export function detectWorktreeHealth(cwd) {
+  const base = { name: 'worktree_health', label: 'worktree 隔离健康', safe_actions: [] }
+  try {
+    const { WorktreeManager } = require_wtm()
+    const wm = new WorktreeManager(cwd)
+    const r = wm.doctor(cwd)
+    const findings = []
+    for (const iss of r.issues || []) findings.push(`worktree: ${typeof iss === 'string' ? iss : JSON.stringify(iss)}`)
+    // 残留分支对账（sillyspec/* vs 活跃变更目录）
+    try {
+      const branches = gitQuiet(cwd, ['branch', '--list', 'sillyspec/*']) || ''
+      const activeDirs = new Set()
+      // 活跃变更目录锚定主仓根（审查 B-01：worktree 内 cwd/.sillyspec/changes 只含 archive——
+      // 活跃变更不入 git；git common-dir 反推主仓根，失败回退 cwd）
+      let mainRoot = cwd
+      try {
+        const commonDir = gitQuiet(cwd, ['rev-parse', '--git-common-dir'])
+        if (commonDir) mainRoot = resolve(dirname(resolve(cwd, String(commonDir).trim())))
+      } catch { /* 回退 cwd */ }
+      const changesDir = join(mainRoot, '.sillyspec', 'changes')
+      if (existsSync(changesDir)) {
+        for (const d of readdirSync(changesDir)) {
+          if (!d.startsWith('archive')) activeDirs.add(d)
+        }
+      }
+      for (const line of branches.split('\n')) {
+        // 剥 */+ 两前缀（审查 B-01：+ 是 worktree checkout 中标记，未剥致分支名与删除命令双重语法坏）
+        const b = line.trim().replace(/^[*+][ ]*/, '').replace(/^sillyspec\//, '')
+        if (b && !activeDirs.has(b)) findings.push(`残留分支 sillyspec/${b}（变更已归档/删除）——git branch -d sillyspec/${b} 或 sillyspec worktree cleanup`)
+      }
+    } catch { /* 分支读失败跳过该子项 */ }
+    return findings.length === 0
+      ? { ...base, findings: ['worktree 与会话目录健康'], pass: true, severity: CHECK_SEVERITY.PASSED }
+      : { ...base, findings, pass: false, severity: CHECK_SEVERITY.WARNING }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（git 不可用或非仓库：${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+/**
+ * 构建环境（FR-02）：node 版本 vs package.json engines.node（^/>=/= 前缀简化比较，
+ * 复杂区间 unknown 不判红）+ 包管理器存在性。无 package.json → skipped 注记。
+ */
+export function detectBuildEnv(cwd) {
+  const base = { name: 'build_env', label: '构建环境', safe_actions: [] }
+  try {
+    const pkgPath = join(cwd, 'package.json')
+    if (!existsSync(pkgPath)) return { ...base, findings: ['无 package.json（非 Node 项目）——skipped'], pass: true, severity: null, skipped: true }
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const findings = []
+    const want = pkg.engines && pkg.engines.node
+    if (want) {
+      const cur = process.version.replace(/^v/, '')
+      const m = String(want).match(/^(\^|>=|=)?\s*(\d+)\.?(\d+)?\.?(\d+)?/)
+      if (m) {
+        const [_, op, a, b, c] = m
+        const w = [Number(a), Number(b || 0), Number(c || 0)]
+        const cu = cur.split('.').map(Number)
+        const ge = cu[0] > w[0] || (cu[0] === w[0] && (cu[1] > w[1] || (cu[1] === w[1] && cu[2] >= w[2])))
+        const ok = op === '^' ? (cu[0] === w[0] && ge) : ge
+        if (!ok) findings.push(`node ${process.version} 不满足 engines.node ${want}`)
+      } else {
+        findings.push(`engines.node 区间复杂（${want}）——unknown 不判红`)
+      }
+    }
+    // 包管理器
+    const pm = (pkg.packageManager || '').split('@')[0]
+      || (existsSync(join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(cwd, 'yarn.lock')) ? 'yarn' : 'npm')
+    findings.push(`node ${process.version} / 包管理器 ${pm}${pkg.packageManager ? `（packageManager 锁定）` : '（lockfile 推断）'}`)
+    return findings.some(f => f.includes('不满足'))
+      ? { ...base, findings, pass: false, severity: CHECK_SEVERITY.WARNING }
+      : { ...base, findings, pass: true, severity: CHECK_SEVERITY.PASSED }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+/**
+ * MCP 端点配置在场性（FR-02）：项目级 .mcp.json / .cursor/mcp.json 查 Context7/grep.app
+ * 键——零网络请求。无配置 → skipped 注记（不判红——MCP 是可选增强）。
+ */
+export function detectMcpEndpoints(cwd) {
+  const base = { name: 'mcp_endpoints', label: 'MCP 端点配置', safe_actions: [] }
+  try {
+    const candidates = [join(cwd, '.mcp.json'), join(cwd, '.cursor', 'mcp.json')]
+    const found = candidates.find(p => existsSync(p))
+    if (!found) return { ...base, findings: ['无项目级 MCP 配置（.mcp.json/.cursor/mcp.json）——可选增强，skipped'], pass: true, severity: null, skipped: true }
+    const text = readFileSync(found, 'utf8')
+    const findings = [`配置文件：${relative(cwd, found)}`]
+    for (const key of ['context7', 'grep.app', 'grepapp']) {
+      if (text.toLowerCase().includes(key)) findings.push(`${key} 端点已配置 ✅`)
+    }
+    return { ...base, findings, pass: true, severity: CHECK_SEVERITY.PASSED }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+/**
+ * 模块文档健康（2026-09-09-doctor-noai 审查 B-02 补维，FR-01 step1 承诺）：
+ * _module-map.yaml 的 needs_review=true 清单（卡缺失/精确校验归 modules rebuild/status）。
+ * 只读 fail-soft。
+ */
+function detectModuleDocHealth(cwd) {
+  const base = { name: 'module_doc_health', label: '模块文档健康', safe_actions: [] }
+  try {
+    let mapText = null
+    const docsDir = join(cwd, '.sillyspec', 'docs')
+    if (existsSync(docsDir)) {
+      for (const d of readdirSync(docsDir)) {
+        const cand = join(docsDir, d, 'modules', '_module-map.yaml')
+        if (existsSync(cand)) { mapText = readFileSync(cand, 'utf8'); break }
+      }
+    }
+    if (!mapText) return { ...base, findings: ['无 _module-map.yaml（未 scan）——skipped'], pass: true, severity: null, skipped: true }
+    const findings = []
+    // needs_review 清单（模块块内 needs_review: true）
+    const blocks = mapText.split(/\n(?=  \\w)/)
+    for (const blk of blocks) {
+      const idM = blk.match(/^  ([\w.-]+):/)
+      if (idM && /needs_review:\s*true/.test(blk)) {
+        const reasons = (blk.match(/review_reasons:\s*\[([^\]]*)\]/) || [])[1] || ''
+        findings.push(`${idM[1]} needs_review=true${reasons ? `（${reasons.trim()}）` : ''}——按卡指引复核`)
+      }
+    }
+    return findings.length === 0
+      ? { ...base, findings: ['模块卡 needs_review 清零'], pass: true, severity: CHECK_SEVERITY.PASSED }
+      : { ...base, findings, pass: false, severity: CHECK_SEVERITY.WARNING }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+/**
+ * 决策版本漂移（审查 B-02 补维）：knowledge/decisions/ 条目计数 + 提示精确复核链归属
+ * （behind 精确计算归 verify evidence-auto / docs-check 决策规则族——此处只做在场概览）。
+ * 只读 fail-soft。
+ */
+function detectDecisionDrift(cwd) {
+  const base = { name: 'decision_drift', label: '决策版本漂移', safe_actions: [] }
+  try {
+    const decDir = join(cwd, '.sillyspec', 'knowledge', 'decisions')
+    if (!existsSync(decDir)) return { ...base, findings: ['无 knowledge/decisions/——skipped'], pass: true, severity: null, skipped: true }
+    let count = 0
+    for (const f of readdirSync(decDir)) {
+      if (!f.endsWith('.md')) continue
+      count += (readFileSync(join(decDir, f), 'utf8').match(/^## D-\d+@\d+/gm) || []).length
+    }
+    return { ...base, findings: [`decisions 库 ${count} 条（behind 精确复核在 verify evidence-auto 与 docs-check 决策规则族）`], pass: true, severity: CHECK_SEVERITY.PASSED }
+  } catch (e) {
+    return { ...base, findings: [`探测降级（${e?.message || e}）——skipped`], pass: true, severity: null, skipped: true }
+  }
+}
+
+/**
+ * renderDoctorSummary（FR-01，全新输出契约——2026-09-09-doctor-noai）：逐维
+ * ✅/⚠️/❌ + label + findings 首行 + safe_actions 提示行。顶层非 --json 命令与
+ * _cliAction 步共用。
+ */
+export function renderDoctorSummary(diagnostics) {
+  const L = ['🩺 SillySpec 项目自检诊断', '']
+  for (const d of (diagnostics.dimensions || [])) {
+    if (!d || !d.name) continue
+    const icon = d.pass === false && d.severity === CHECK_SEVERITY.FAILED ? '❌' : d.pass === false ? '⚠️' : '✅'
+    L.push(`${icon} ${d.label || d.name}`)
+    for (const f of (d.findings || []).slice(0, 3)) L.push(`   · ${f}`)
+    if ((d.findings || []).length > 3) L.push(`   · …还有 ${d.findings.length - 3} 条`)
+    for (const a of (d.safe_actions || []).slice(0, 2)) L.push(`   🔧 ${a.action}：${a.next_step || a.rationale || ''}`)
+  }
+  L.push('')
+  return L.join('\n')
+}
+
+// worktree.js 延迟引用（防环：worktree 不 import doctor-diagnostics）
+import * as _wtm from './worktree.js'
+function require_wtm() { return _wtm }
+
 export async function runDoctorDiagnostics({ cwd }) {
   const pointer = resolvePointer(cwd);
   const multiDb = detectMultiDb(cwd, pointer);
@@ -759,7 +951,10 @@ export async function runDoctorDiagnostics({ cwd }) {
   // P2-2-②：file-lifecycle 文档欠账（git behind 事实计算，治「改了生命周期代码忘同步文档」）
   const lifecycleDoc = detectLifecycleDocStaleness(cwd);
 
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc];
+  const worktreeHealth = detectWorktreeHealth(cwd)
+  const buildEnv = detectBuildEnv(cwd)
+  const mcpEndpoints = detectMcpEndpoints(cwd)
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, buildEnv, mcpEndpoints];
 
   return {
     dimensions,
@@ -1169,3 +1364,244 @@ export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false
     if (db) { try { db.close(); } catch { /* 忽略关闭失败 */ } }
   }
 }
+
+// ── 存量无戳 execute-runs 清扫（doctor --gc-unstamped-runs）────────────────
+
+const TASK_ID_RE = /\btask-(\d+)\b/gi
+const CHANGE_PATH_RE = /(?:^|\/)changes\/([^/]+)\//
+const TASK_DIR_RE = /^task-(\d+)$/i
+
+function normTaskId(digits) {
+  return `task-${String(digits).padStart(2, '0')}`
+}
+
+function parseTaskIdsFromText(text) {
+  const ids = new Set()
+  if (!text) return ids
+  const re = new RegExp(TASK_ID_RE.source, TASK_ID_RE.flags)
+  for (const m of String(text).matchAll(re)) ids.add(normTaskId(m[1]))
+  return ids
+}
+
+function setEq(a, b) {
+  if (a.size !== b.size) return false
+  for (const x of a) if (!b.has(x)) return false
+  return true
+}
+
+function isSubset(small, big) {
+  for (const x of small) if (!big.has(x)) return false
+  return true
+}
+
+function listDirNames(dir) {
+  if (!dir || !existsSync(dir)) return []
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  } catch {
+    return []
+  }
+}
+
+function loadTasksMd(changeDir) {
+  const p = join(changeDir, 'tasks.md')
+  if (!existsSync(p)) return new Set()
+  try {
+    return parseTaskIdsFromText(readFileSync(p, 'utf8'))
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * 扫一个 execute-run 目录：戳 / reviewedFiles 路径首段 / task-NN 目录名。
+ * reviewedFiles 取全部条目（不只 [0]），路径段精确相等——login 不命中 2026-08-01-login。
+ */
+function inspectExecuteRun(runDir) {
+  const stampFile = join(runDir, 'change')
+  let stamp = ''
+  if (existsSync(stampFile)) {
+    try { stamp = readFileSync(stampFile, 'utf8').trim() } catch { /* 读失败当无戳 */ }
+  }
+  const pathOwners = new Set()
+  const taskIds = new Set()
+  const tasksDir = join(runDir, 'tasks')
+  if (existsSync(tasksDir)) {
+    let entries = []
+    try { entries = readdirSync(tasksDir, { withFileTypes: true }) } catch { entries = [] }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const tm = e.name.match(TASK_DIR_RE)
+      if (tm) taskIds.add(normTaskId(tm[1]))
+      const rjPath = join(tasksDir, e.name, 'review.json')
+      if (!existsSync(rjPath)) continue
+      try {
+        const rj = JSON.parse(readFileSync(rjPath, 'utf8'))
+        const files = Array.isArray(rj.reviewedFiles) ? rj.reviewedFiles : []
+        for (const f of files) {
+          const m = String(f || '').replace(/\\/g, '/').match(CHANGE_PATH_RE)
+          if (m) pathOwners.add(m[1])
+        }
+      } catch { /* 坏 JSON 不据此猜归属 */ }
+    }
+  }
+  return { hasStamp: stamp.length > 0, stamp, pathOwners, taskIds }
+}
+
+/**
+ * 无戳 run 的归属判定。禁 mtime。命中活跃变更一律 skip。
+ *
+ * 1. reviewedFiles 路径 `changes/<name>/` 首段精确命中：
+ *    - ∩ active → matches_active
+ *    - ∩ archive 多个 → ambiguous_archive
+ *    - ∩ archive 恰好 1：若 tasks.md 有任务且 run 有多余 task-NN → tasks_md_mismatch；否则 via path
+ * 2. 无路径（或路径名既不在 active 也不在 archive）：
+ *    - taskIds 空 → no_attribution
+ *    - 与恰好一个归档 tasks.md **集合全等**且无 active 全等 → via tasks_md
+ *      （子集太弱：task-01 几乎每个变更都有）
+ */
+function classifyUnstampedRun(inspected, { active, archive, archiveTasks, activeTasks }) {
+  const pathActive = [...inspected.pathOwners].filter((n) => active.has(n))
+  if (pathActive.length) {
+    return { skip: true, reason: 'matches_active' }
+  }
+  const pathArchived = [...inspected.pathOwners].filter((n) => archive.has(n))
+  if (pathArchived.length > 1) {
+    return { skip: true, reason: 'ambiguous_archive' }
+  }
+  if (pathArchived.length === 1) {
+    const owner = pathArchived[0]
+    const mdTasks = archiveTasks.get(owner) || new Set()
+    if (mdTasks.size > 0 && inspected.taskIds.size > 0 && !isSubset(inspected.taskIds, mdTasks)) {
+      return { skip: true, reason: 'tasks_md_mismatch', owner }
+    }
+    return { delete: true, owner, via: 'path' }
+  }
+
+  if (inspected.taskIds.size === 0) {
+    return { skip: true, reason: 'no_attribution' }
+  }
+  const activeEquals = [...active].filter((n) => setEq(inspected.taskIds, activeTasks.get(n) || new Set()))
+  if (activeEquals.length) {
+    return { skip: true, reason: 'matches_active' }
+  }
+  const archivedEquals = [...archive].filter((n) => setEq(inspected.taskIds, archiveTasks.get(n) || new Set()))
+  if (archivedEquals.length === 1) {
+    return { delete: true, owner: archivedEquals[0], via: 'tasks_md' }
+  }
+  if (archivedEquals.length > 1) {
+    return { skip: true, reason: 'ambiguous_archive' }
+  }
+  return { skip: true, reason: 'no_attribution' }
+}
+
+/**
+ * 存量无戳 execute-runs 一次性清扫（ql-20260908-006-5f04）。
+ *
+ * 不进 archive 热路径：pruneArchivedChangeRuntime 故意不猜无戳 run（禁 mtime）。
+ * 本函数是 doctor 旁路，对齐 --cleanup-ghosts：默认 dry-run，--confirm 才 rmSync。
+ * 只处理 execute-runs/<runId>/（有 change 戳的留给归档精确回收；stage-reviews / verify-runs 本轮不动）。
+ *
+ * @param {{ cwd: string, specDir?: string|null, confirm?: boolean }} opts
+ */
+export async function gcUnstampedExecuteRuns({ cwd, specDir = null, confirm = false }) {
+  const pointer = resolvePointer(cwd)
+  const localSpec = specDir && existsSync(specDir) ? specDir : join(cwd, '.sillyspec')
+  const authoritySpecRoot = (pointer.present && pointer.specRoot && existsSync(pointer.specRoot))
+    ? pointer.specRoot
+    : localSpec
+  const runtimeRoot = (pointer.runtimeRoot && existsSync(pointer.runtimeRoot))
+    ? pointer.runtimeRoot
+    : join(authoritySpecRoot, '.runtime')
+  const execDir = join(runtimeRoot, 'execute-runs')
+  if (!existsSync(execDir)) {
+    return {
+      action: 'skipped',
+      reason: '未找到 execute-runs 目录',
+      runtime_root: runtimeRoot,
+      candidates: [],
+      skipped: [],
+      errors: [],
+      count: 0,
+    }
+  }
+
+  const activeNames = listChanges(authoritySpecRoot)
+  const archiveNames = listDirNames(join(authoritySpecRoot, 'changes', 'archive'))
+    .filter((n) => n !== 'archive')
+  const active = new Set(activeNames)
+  const archive = new Set(archiveNames)
+  const archiveTasks = new Map()
+  for (const n of archiveNames) {
+    archiveTasks.set(n, loadTasksMd(join(authoritySpecRoot, 'changes', 'archive', n)))
+  }
+  const activeTasks = new Map()
+  for (const n of activeNames) {
+    activeTasks.set(n, loadTasksMd(join(authoritySpecRoot, 'changes', n)))
+  }
+
+  const candidates = []
+  const skipped = []
+  const errors = []
+  let entries = []
+  try {
+    entries = readdirSync(execDir, { withFileTypes: true })
+  } catch (e) {
+    return {
+      action: 'error',
+      reason: e.message,
+      runtime_root: runtimeRoot,
+      candidates: [],
+      skipped: [],
+      errors: [{ error: e.message }],
+      count: 0,
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const runId = entry.name
+    const runDir = join(execDir, runId)
+    let inspected
+    try {
+      inspected = inspectExecuteRun(runDir)
+    } catch (e) {
+      errors.push({ runId, error: e.message })
+      continue
+    }
+    if (inspected.hasStamp) {
+      skipped.push({ runId, reason: 'has_stamp' })
+      continue
+    }
+    const verdict = classifyUnstampedRun(inspected, { active, archive, archiveTasks, activeTasks })
+    if (verdict.skip) {
+      skipped.push({ runId, reason: verdict.reason, owner: verdict.owner || null })
+      continue
+    }
+    candidates.push({ runId, owner: verdict.owner, via: verdict.via })
+  }
+
+  const removed = []
+  if (confirm) {
+    for (const c of candidates) {
+      try {
+        rmSync(join(execDir, c.runId), { recursive: true, force: true })
+        removed.push(c.runId)
+      } catch (e) {
+        errors.push({ runId: c.runId, error: e.message })
+      }
+    }
+  }
+
+  return {
+    action: confirm ? 'deleted' : 'dry_run',
+    runtime_root: runtimeRoot,
+    candidates,
+    skipped,
+    errors,
+    removed: confirm ? removed : [],
+    count: candidates.length,
+  }
+}