sillyspec 3.28.8 → 3.28.10

package/src/cross-repo-reconcile.js

@@ -0,0 +1,134 @@
+/**
+ * cross-repo-reconcile.js — 跨仓 task 卡 target_files 的 per-repo 对账（零环新模块）。
+ *
+ * 坑 cross-repo-reconcile-blindness（2026-09-15 复盘实证：三端变更的对账表只有主仓机器可见，
+ * 22 个跨仓文件在归档表全标「计划未动」、探针5 报「0 frontend calls」，跨仓全靠人工到对应仓
+ * 解释）：reconcileTargetFiles 主链按 D-004 把跨仓卡从声明侧剔除——主仓 actual 永远对不上跨仓
+ * 声明，剔除本身正确；但「留待后续分期」一直没有兑现，跨仓侧零机器可见性。
+ *
+ * 本模块兑现该分期：对每张跨仓卡声明的 repo key，读 local.yaml repos 注册表解析仓根，在**该仓**
+ * 取 actual（diff HEAD~1..HEAD ∪ status porcelain untracked，与 resolveVerifyChangedFiles 跨仓
+ * 分支同源口径），按主仓同款三类差集对账（matched / missing / undeclared + 脚手架软桶）。
+ *
+ * 定位与边界（与主仓对账的差异，显式声明防误读）：
+ * - **advisory 不阻断**：跨仓 diff 锚点是 HEAD~1..HEAD 最近提交窗口（多 task 同仓时只反映最近
+ *   一笔，精确范围要 task 卡 base/head 锡点——verify-postcheck:1119 先例同款限制），锚点脆弱期
+ *   （已 commit 多笔 / 全在 working-tree）会产②类假信号，故只报告不翻转 verify 状态。
+ * - 仓未注册 / 路径不可达 / 非 git 仓 → 该 repo degraded 一行说明，不炸整体。
+ * - 不 import verify-postcheck（后者 import 本模块，反向成环）；路径归一/大小写折叠与主仓
+ *   normalizeReconcilePath/pathKey 同口径本地实现，注释锚定不漂移。
+ */
+import { existsSync, readFileSync } from 'fs'
+import { join, isAbsolute, resolve } from 'path'
+import { gitQuiet } from './git-helper.js'
+import { parseRepoRegistry } from './stages/plan-postcheck.js'
+import { filterDeliverableFiles, classifyToolScaffold } from './worktree-apply.js'
+
+// 与 verify-postcheck normalizeReconcilePath 同口径（本地实现防环）：剥 ./ 前缀、反斜杠归一
+function normalizeRepoPath(p) {
+  return String(p || '').trim().replace(/^\.\//, '').replace(/\\/g, '/')
+}
+
+// 与 verify-postcheck reconcileTargetFiles 的 foldCase 同口径：win32/darwin 文件系统大小写
+// 不敏感，两形指同一文件；Linux 保持敏感
+const foldCase = process.platform === 'win32' || process.platform === 'darwin'
+const pathKey = (p) => {
+  const n = normalizeRepoPath(p)
+  return foldCase ? n.toLowerCase() : n
+}
+
+// 与 verify-postcheck parsePorcelainFilePaths 同口径（本地实现防环）：剥 XY 状态列、rename 取
+// -> 后新路径、剥包裹引号、反斜杠归一
+function parsePorcelain(raw) {
+  return String(raw || '').split('\n')
+    .map(l => l.slice(3).trim())
+    .map(p => (p.includes(' -> ') ? p.slice(p.lastIndexOf(' -> ') + 4) : p).trim())
+    .map(p => p.replace(/^"|"$/g, ''))
+    .map(p => p.replace(/\\/g, '/'))
+    .filter(Boolean)
+}
+
+/**
+ * 跨仓声明对账。declarationsByRepo 由声明侧收集（collectDeclaredTargetFiles 跨仓卡分支）：
+ * `{ [repoKey]: Array<{task, path, isNew}> }`——path 相对该仓根（跨仓卡口径）。
+ *
+ * @param {{ specBase: string, cwd: string, declarationsByRepo: Record<string, Array<{task:string,path:string,isNew:boolean}>> }} args
+ * @returns {Array<{repo:string, repoPath:string|null, declaredCount:number, actualCount:number,
+ *   matched:string[], missing:Array<{task:string,path:string,isNew?:boolean}>,
+ *   undeclared:string[], scaffoldCount:number, degradedReason:string|null}>}
+ *   每 repo 一项；degradedReason 非空时 matched/missing/undeclared 为空数组（该仓无结论）。
+ */
+export function reconcileCrossRepoDeclarations({ specBase, cwd, declarationsByRepo }) {
+  const results = []
+  const repos = declarationsByRepo && typeof declarationsByRepo === 'object' ? Object.keys(declarationsByRepo) : []
+  if (repos.length === 0) return results
+
+  let registry = new Map()
+  try {
+    const yamlPath = join(specBase || '', 'local.yaml')
+    if (specBase && existsSync(yamlPath)) {
+      registry = parseRepoRegistry(readFileSync(yamlPath, 'utf8'))
+    }
+  } catch { /* local.yaml 不可读 → 空注册表，各 repo 落「未注册」degraded */ }
+
+  for (const repoKey of repos) {
+    const declarations = declarationsByRepo[repoKey] || []
+    const base = { repo: repoKey, repoPath: null, declaredCount: declarations.length, actualCount: 0,
+      matched: [], missing: [], undeclared: [], scaffoldCount: 0, degradedReason: null }
+
+    const rawPath = registry.get(repoKey)
+    if (!rawPath) {
+      results.push({ ...base, degradedReason: `repo key「${repoKey}」未在 local.yaml repos 注册——跨仓对账不可达，请人工到对应仓核对` })
+      continue
+    }
+    const repoPath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath)
+    base.repoPath = repoPath
+    if (!existsSync(repoPath)) {
+      results.push({ ...base, degradedReason: `注册路径不可达：${repoPath}` })
+      continue
+    }
+
+    // actual 双源（resolveVerifyChangedFiles 跨仓分支同源）：已提交窗口 + working-tree 未提交
+    const union = new Set()
+    let anySource = false
+    const diffOut = gitQuiet(repoPath, ['diff', '--name-only', 'HEAD~1..HEAD'], { timeout: 30 * 1000 })
+    if (diffOut !== null) {
+      anySource = true
+      for (const f of String(diffOut).split('\n')) {
+        const n = normalizeRepoPath(f)
+        if (n) union.add(n)
+      }
+    }
+    const statusOut = gitQuiet(repoPath, ['status', '--porcelain', '--untracked-files=all'], { timeout: 30 * 1000, trim: false })
+    if (statusOut !== null) {
+      anySource = true
+      for (const f of parsePorcelain(statusOut)) union.add(f)
+    }
+    if (!anySource) {
+      results.push({ ...base, degradedReason: '该仓 git 不可用/非仓库（diff 与 status 双失败）' })
+      continue
+    }
+
+    const actualFiles = [...new Set(filterDeliverableFiles([...union]).filter(Boolean))].sort()
+    base.actualCount = actualFiles.length
+    const actualKeySet = new Set(actualFiles.map(pathKey))
+    const declaredPaths = [...new Set(declarations.map(d => d.path))].sort()
+    const declaredKeySet = new Set(declaredPaths.map(pathKey))
+    for (const path of declaredPaths) {
+      if (actualKeySet.has(pathKey(path))) base.matched.push(path)
+    }
+    for (const d of declarations) {
+      if (!actualKeySet.has(pathKey(d.path))) {
+        base.missing.push(d.isNew ? { task: d.task, path: d.path, isNew: true } : { task: d.task, path: d.path })
+      }
+    }
+    // 脚手架软桶（主仓 reconcileTargetFiles 同口径）：工具/平台设施文件不进③类逐条清单
+    for (const path of actualFiles) {
+      if (declaredKeySet.has(pathKey(path))) continue
+      if (classifyToolScaffold(path)) { base.scaffoldCount++; continue }
+      base.undeclared.push(path)
+    }
+    results.push(base)
+  }
+  return results
+}

package/src/db.js

@@ -7,7 +7,7 @@ import { dirname } from 'path';
 // 每次 new ProgressManager 都过 init，靠版本戳跳过建表省开销）。
 // node:sqlite（DatabaseSync）是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
 // _createSchema 内 DDL 直接落盘，无需额外 _save。
-const DB_SCHEMA_VERSION = 5;
+const DB_SCHEMA_VERSION = 6;
 
 // SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）：WAL 单写者模型，并发写第二者在
 // busy_timeout=5000（init PRAGMA）后抛 SQLITE_BUSY。busy_timeout 已在引擎层处理大部分等待；
@@ -252,7 +252,7 @@ export class DB {
       CREATE TABLE IF NOT EXISTS project (
         id INTEGER PRIMARY KEY DEFAULT 1,
         name TEXT NOT NULL,
-        schema_version INTEGER DEFAULT 5,
+        schema_version INTEGER DEFAULT 6,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       )
@@ -271,7 +271,8 @@ export class DB {
         platform_change_id INTEGER,
         platform_workspace_id INTEGER,
         platform_last_sync TEXT,
-        platform_sync_enabled INTEGER DEFAULT 0
+        platform_sync_enabled INTEGER DEFAULT 0,
+        owner_session TEXT
       )
     `);
 
@@ -370,6 +371,13 @@ export class DB {
     // 已语义化，title/quicklog_id 留空。不纳入平台同步脏度（本地展示用元信息）。
     this._migrateAddColumn('changes', 'title', 'TEXT');
     this._migrateAddColumn('changes', 'quicklog_id', 'TEXT');
+
+    // v6（2026-09-14-change-ownership-guards task-01，D-005@v1）：changes 表加 owner_session——
+    // change 级所有权载体（接管类操作对他人活跃 change 拒绝执行的心跳窗口判定数据源）。
+    // NULL=无主（存量行迁移后即此态，任何会话可接管——向后兼容零行为变化）；写入方=
+    // change-registry 首建/claimChangeOwner（task-02 接线会话标识）；消费方=assertChangeOwnership
+    // （task-02）+ serializeForSync 平台同步投影。幂等 ALTER（列存在跳过，v5 先例同款）。
+    this._migrateAddColumn('changes', 'owner_session', 'TEXT');
   }
 
   /**

package/src/decision-distill.js

@@ -80,6 +80,10 @@ function applyField(entry, label, value) {
     case '模块域': case '模块': case 'domains': case 'domain': entry.domains = parseListValue(value); break
     // 文件字段（FR-01/D-001@v1，2026-09-11-cross-change-decision-guard）：列表语义同模块域 + 逐项反斜杠归一 POSIX
     case '文件': case 'files': entry.files = parseListValue(value).map(s => s.replace(/\\/g, '/')); break
+    // 故障面/退役判据（FR-01/D-001@v1，2026-09-15-tax-governance）：自维护税治理字段——本决策
+    // 引入的新失败模式 / 出现什么信号时简化或删除本机制；单值语义，仅中文标签（模板同源）
+    case '故障面': entry.failureMode = value; break
+    case '退役判据': entry.retireWhen = value; break
     case '否决理由': case 'reject_reason': case 'rejectreason': entry.rejectReason = value; break
     case '复潮条件': case 'revisit_when': case 'revisitwhen': entry.revisitWhen = value; break
     case 'supersedes': entry.supersedes = value; break
@@ -95,7 +99,8 @@ function applyField(entry, label, value) {
  * @returns {{ entries: Array<{
  *   id: string, number: string, version: number, title: string,
  *   type?: string, status?: string, question?: string, answer?: string,
- *   anchor?: string, domains?: string[], files?: string[], rejectReason?: string, revisitWhen?: string,
+ *   anchor?: string, domains?: string[], files?: string[], failureMode?: string, retireWhen?: string,
+ *   rejectReason?: string, revisitWhen?: string,
  *   supersedes?: string, impacts?: string, normalizedRequirement?: string,
  *   selected: 'implemented'|'rejected'|null, raw: string }>, missing: boolean }}
  *   missing=true = decisions.md 不存在；selected = FR-02 入选裁决，null 表示解析保留但不入选。
@@ -166,8 +171,10 @@ export function parseDecisions(changeDir) {
   return { entries, missing: false, zeroWithContent: hasDecisionLike && entries.length === 0 }
 }
 
-/** applyField 认识的字段标签白名单（行内 ｜ 分段与缩进子项只按白名单进字段，散文误伤为零） */
-const FIELD_LABEL_RE = /^(type|types|status|question|问题|answer|答案|锚点|anchor|模块域|模块|domains|domain|否决理由|reject_reason|rejectreason|复潮条件|revisit_when|revisitwhen|supersedes|impacts|影响|文件|files|normalized_requirement|状态|类型)$/i
+/** applyField 认识的字段标签白名单（行内 ｜ 分段与缩进子项只按白名单进字段，散文误伤为零）。
+ *  故障面/退役判据（2026-09-15-tax-governance FR-01）：白名单双触点之二——缺收录则两标签
+ *  永远留 raw 静默丢弃（applyField case 缺一不可）。 */
+const FIELD_LABEL_RE = /^(type|types|status|question|问题|answer|答案|锚点|anchor|模块域|模块|domains|domain|否决理由|reject_reason|rejectreason|复潮条件|revisit_when|revisitwhen|supersedes|impacts|影响|文件|files|normalized_requirement|状态|类型|故障面|退役判据)$/i
 
 // ---------------------------------------------------------------------------
 // 域三级兜底（FR-03）
@@ -300,6 +307,11 @@ function renderBlockLines(entry, headHash, supersedesNote, changeName) {
   lines.push(`最近确认：${oneLine(headHash) || NOT_RECORDED}`)
   lines.push(`理由：${oneLine(entry.answer || entry.normalizedRequirement || entry.question)}`)
   if (supersedesNote) lines.push(`supersedes：${oneLine(supersedesNote)}`)
+  // 故障面/退役判据行（FR-01/D-001@v1，2026-09-15-tax-governance）：仅非空渲染——存量条目零迁移、
+  // 幂等重归档不添空行（先例 :298-299 文件行）；位置在「理由：/supersedes：」之后、rejected 专属行
+  // 之前——绝不插在「锚点：」与「文件：」行之间（decision-file-field.test 行序断言红线）
+  if (entry.failureMode) lines.push(`故障面：${oneLine(entry.failureMode)}`)
+  if (entry.retireWhen) lines.push(`退役判据：${oneLine(entry.retireWhen)}`)
   if (entry.selected === 'rejected') {
     lines.push(`否决理由：${oneLine(entry.rejectReason)}`)
     lines.push(`复潮条件：${oneLine(entry.revisitWhen)}`)

package/src/design-facts.js

@@ -21,10 +21,11 @@
  *   decision_module_ref_invalid（ERROR）/ decision_module_domain_gap（WARNING）/
  *   decision_module_check_skipped（skipped 原因字符串，接线层包 code）。
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { parseDecisions } from './decision-distill.js'
 import { parseFileChangeListDetailed } from './change-list.js'
+import { parseDesignCoverageByRepo, parseRepoRegistry } from './stages/plan-postcheck.js'
 import { parseModuleMapSimple } from './modules.js'
 
 // ---------------------------------------------------------------------------
@@ -134,6 +135,26 @@ export function loadModuleMap(specRoot, project) {
   return { ids, prefixPairs }
 }
 
+/**
+ * 在兄弟项目的 map 里定位模块 id 归属（多项目仓 docs/<其他项目>/modules/_module-map.yaml）。
+ * 幻觉 ERROR 的消歧源（2026-09-14 quick，用户反馈①）：id 真实存在但属另一子项目时报
+ * 「归属 + 本次核验只认当前项目 map」，堵 agent 按占位提示误读子项目 map 的死胡同。
+ * @param {string} specRoot 规范根目录
+ * @param {string} currentProject 当前核验项目（跳过自身）
+ * @param {string} id 模块 id
+ * @returns {string | null} 命中的项目名（docs/ 下第一段目录名），无命中/不可读 → null
+ */
+function locateIdInSiblingProjects(specRoot, currentProject, id) {
+  let entries
+  try { entries = readdirSync(join(specRoot, 'docs'), { withFileTypes: true }) } catch { return null }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name === currentProject) continue
+    const m = loadModuleMap(specRoot, e.name)
+    if (m && m.ids.has(id)) return e.name
+  }
+  return null
+}
+
 // ---------------------------------------------------------------------------
 // 核验（FR-02 分级：ERROR / WARNING / skipped）
 // ---------------------------------------------------------------------------
@@ -162,7 +183,8 @@ export function deriveActualModules(filePaths, prefixPairs) {
  * 核验变更决策的模块域引用（FR-02/D-002/D-004；brainstorm「生成规范文件」步 --done gate 本体，
  * 接线在 task-02）。分级：
  *   - ERROR（decision_module_ref_invalid）：
- *     · 模块域项 ∉ _module-map.yaml 且无 NEW: 前缀（模块幻觉）——出路提示二选一；
+ *     · 模块域项 ∉ _module-map.yaml 且无 NEW: 前缀（模块幻觉）——出路提示二选一；消息内嵌
+ *       当前项目 map 路径 + 合法 id 示例，id 命中兄弟项目 map 时改报归属消歧（仍拦）；
  *     · 裸项 'NEW:'（`NEW: <名>` 冒号后带空格被列表切分）——书写错误，附正确写法。
  *   - WARNING（decision_module_domain_gap）：
  *     · design.md 文件清单推导的实改模块集 × 声明域并集差异（双向，措辞留人工裁量）；
@@ -202,7 +224,16 @@ export function validateDecisionModuleRefs({ changeDir, specRoot, project } = {}
       } else if (item.startsWith('NEW:')) {
         // 新模块声明：豁免存在性核验（D-002/D-004），原样保留
       } else if (!moduleMap.ids.has(item)) {
-        errors.push(`[decision_module_ref_invalid] ${id} 模块域含未注册模块 "${item}"——补录 _module-map.yaml 或改用 NEW:${item} 前缀声明新模块`)
+        // 消息自足（2026-09-14 quick，用户反馈①）：内嵌解析出的 map 路径 + 合法 id 示例，
+        // agent 不必再猜「合法 id 从哪张 map 取」；多项目仓先查兄弟项目 map 消歧——id 真实
+        // 存在但属其他子项目时报归属，而非笼统「模块幻觉」（语义不变：仍 ERROR 拦）。
+        const mapRel = `docs/${project}/modules/_module-map.yaml`
+        const ids = [...moduleMap.ids]
+        const sample = `${ids.slice(0, 5).join('、')}${ids.length > 5 ? ' 等' : ''}`
+        const sibling = locateIdInSiblingProjects(specRoot, project, item)
+        errors.push(sibling
+          ? `[decision_module_ref_invalid] ${id} 模块域含未注册模块 "${item}"——该 id 属于子项目 ${sibling}（docs/${sibling}/modules/_module-map.yaml），本次核验只认当前项目 ${mapRel} 的 id（合法示例：${sample}，共 ${ids.length} 个）；跨项目引用请补录当前项目 map 或改用 NEW:${item} 前缀`
+          : `[decision_module_ref_invalid] ${id} 模块域含未注册模块 "${item}"——合法 id 来源：${mapRel}（示例：${sample}，共 ${ids.length} 个）；补录该 map 或改用 NEW:${item} 前缀声明新模块`)
       }
     }
   }
@@ -393,25 +424,63 @@ export function validateDesignFileList({ changeDir, cwd } = {}) {
     if (!existsSync(designPath)) {
       return { ok: true, errors, warnings: ['design 清单核验跳过：design.md 不存在'] }
     }
-    const entries = parseFileChangeListDetailed(designPath, { keepSillyspecDocs: true })
-    if (!Array.isArray(entries) || entries.length === 0) {
-      return { ok: true, errors, warnings: ['design 清单核验跳过：design.md 无文件变更清单段（small 变更可无清单）'] }
+
+    // 单段存在性核验内核：NEW:/glob/占位符口径与原实现一致，仅把「根」参数化
+    const checkAgainstRoot = (root, rawPaths, repoLabel) => {
+      for (const raw of rawPaths) {
+        const rawPath = String(raw || '').trim()
+        if (!rawPath) continue
+        if (rawPath.startsWith('NEW:')) continue // 计划新建豁免（与 validateTargetFiles 同语义）
+        if (rawPath.includes('*') || rawPath.includes('?')) {
+          warnings.push(`design 清单条目含 glob 字符跳过存在性核验：${rawPath}`)
+          continue
+        }
+        const normalized = stripPathPlaceholders(rawPath)
+        if (!normalized || normalized === '.') continue
+        if (!existsSync(join(root, normalized))) {
+          errors.push({
+            path: rawPath,
+            message: `design_file_ref_invalid：文件变更清单条目「${rawPath}」在${repoLabel}（${root}）下不存在且无 NEW: 前缀（幻觉路径/书写错误）——修正路径，或计划新建的文件改为 NEW:${rawPath} 前缀`,
+          })
+        }
+      }
+    }
+
+    // 坑 design-file-ref-cross-repo-blind（2026-09-15 wp 会话实证，41 条误报）：存在性核验
+    // 此前恒以主仓 cwd 为根——design §6 按仓分段（D-014）下的跨仓「修改」条目（如
+    // sub-grid-security 的 src/common/router.js）在其自己仓里明明存在，却被逼标 NEW: 前缀
+    // 过 gate（标「修改」的既有文件被迫声明为计划新建，语义撒谎）。对齐
+    // validateDesignFileCoverage 的分段口径：复用 parseDesignCoverageByRepo 按 `## <repo>
+    // 仓变更` 段头切分，main 段核主仓根，跨仓段核 local.yaml repos: 注册根；无段头时
+    // 整章归 main（原行为零回归）。
+    const { byRepo, hasSegmentHeader, malformedHeaders } = parseDesignCoverageByRepo(designPath)
+    for (const h of malformedHeaders) {
+      warnings.push(`design 清单疑似仓变更段头格式异常（该段文件可能被记到上一段仓，覆盖对账会点名）：${h}`)
     }
-    for (const e of entries) {
-      const raw = String((e && e.path) || '').trim()
-      if (!raw) continue
-      if (raw.startsWith('NEW:')) continue // 计划新建豁免（与 validateTargetFiles 同语义）
-      if (raw.includes('*') || raw.includes('?')) {
-        warnings.push(`design 清单条目含 glob 字符跳过存在性核验：${raw}`)
-        continue
+
+    if (!hasSegmentHeader) {
+      const entries = parseFileChangeListDetailed(designPath, { keepSillyspecDocs: true })
+      if (!Array.isArray(entries) || entries.length === 0) {
+        return { ok: true, errors, warnings: [...warnings, 'design 清单核验跳过：design.md 无文件变更清单段（small 变更可无清单）'] }
       }
-      const normalized = stripPathPlaceholders(raw)
-      if (!normalized || normalized === '.') continue
-      if (!existsSync(join(cwd, normalized))) {
-        errors.push({
-          path: raw,
-          message: `design_file_ref_invalid：文件变更清单条目「${raw}」既不存在也无 NEW: 前缀（幻觉路径/书写错误）——修正路径，或计划新建的文件改为 NEW:${raw} 前缀`,
-        })
+      checkAgainstRoot(cwd, entries.map(e => e.path), '主仓')
+      return { ok: errors.length === 0, errors, warnings }
+    }
+
+    // 有段头：逐段按其仓根核验。跨仓注册表读侧口径 = <cwd>/.sillyspec/local.yaml
+    // （与 execute MultiRepoContext / register-repo 写侧一致，parseRepoRegistry 自带 CRLF 容差）
+    let registry = null
+    const localYamlPath = join(cwd, '.sillyspec', 'local.yaml')
+    if (existsSync(localYamlPath)) {
+      try { registry = parseRepoRegistry(readFileSync(localYamlPath, 'utf8')) } catch { registry = null }
+    }
+    for (const [repo, paths] of byRepo) {
+      if (repo === 'main') {
+        checkAgainstRoot(cwd, paths, '主仓')
+      } else if (registry && registry.has(repo)) {
+        checkAgainstRoot(registry.get(repo), paths, `${repo} 仓`)
+      } else {
+        warnings.push(`design 清单「${repo} 仓变更」段的 repo 未在 local.yaml repos: 注册，跳过该段存在性核验（execute 启动会 fail-closed 拦截，先跑 sillyspec local register-repo ${repo} <仓根路径>）`)
       }
     }
     return { ok: errors.length === 0, errors, warnings }

package/src/docs-gate.js

@@ -11,10 +11,19 @@
  *
  * exit code：0 过（≤基线）/ 1 拦（>基线）/ 2 配置或 IO 错误（含无基线）。
  * 纯判定逻辑（evaluateRatchet）与 IO 面（runDocsGate）分离，前者可单测。
+ *
+ * 坑 docs-gate-stale-baseline（ql-20260915-004，2026-09-15 用户实证）：基线文件是静态快照，
+ * 远端 origin/main 已合入的失效消化/新增不会回流本地基线——出现「基线 371 < origin/main
+ * 实测 379、本地 current 379」时 ratchet 拦 379>371，但本次推送零增量（不劣于远端）——
+ * ratchet 本质=拦增量，被陈旧基线破坏成拦存量。修复：current > baseline 分支先实测
+ * origin/main 树（临时 detach worktree 跑 runDocsCheck），current ≤ 实测值即放行 + 提示
+ * 重锚；实测失败/无远端 ref fail-open 回原拦。快路径（current ≤ baseline）零成本零变化。
  */
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError } from './docs-check.js';
+import { safeGit } from './git-helper.js';
 
 /** 基线文件名（相对 specBase/.sillyspec 根；specBase 由调用方传入完整路径锚） */
 export const BASELINE_FILENAME = 'docs-check-baseline';
@@ -58,6 +67,73 @@ export function writeBaseline(specBase, value) {
   writeFileSync(join(specBase, BASELINE_FILENAME), `${value}\n`, 'utf8');
 }
 
+/**
+ * 实测远端基准树的 docs check 失效数（坑 docs-gate-stale-baseline，ql-20260915-004）。
+ *
+ * 为什么临时 worktree 而非 runDocsCheck 的 --against reader：against reader 的干净文件
+ * 走磁盘直读（磁盘 == HEAD 才成立，docs-check.js createHeadReader :88）——ref=origin/main
+ * 时本地领先 origin 的已提交内容会被误当 origin 版，实测失真。临时 detach worktree
+ * （`git worktree add --detach <tmp> origin/main`）检出的是真远端树，磁盘即实测基。
+ *
+ * 配置口径：读树内 local.yaml（gitignored → 通常缺省 → DEFAULT_DOC_PATHS，与远端真实
+ * CI 口径一致——设备本地 skip 定制不污染远端实测）。清理含 .git 锁容错：worktree remove
+ * 失败 → prune + rmSync 兜底；仍失败 stderr 一行不抛（临时目录残留 OS 清理，不阻断 gate）。
+ *
+ * @param {string} projectRoot 源码仓根
+ * @param {string[]} [remoteRefs] 候选远端 ref（origin/main 优先；master 缺省仓兜底）
+ * @returns {Promise<{ originCount: number|null, ref: string|null, error: string|null }>}
+ *   originCount null = 未实测（无 ref / worktree 建/跑失败——调用方 fail-open 回原拦）
+ */
+export async function measureRemoteBaselineCount(projectRoot, remoteRefs = ['origin/main', 'origin/master']) {
+  let ref = null;
+  for (const r of remoteRefs) {
+    if ((safeGit(projectRoot, ['rev-parse', '--verify', '--quiet', r]) || {}).value) { ref = r; break; }
+  }
+  if (!ref) return { originCount: null, ref: null, error: 'no-remote-ref' };
+
+  const tmp = mkdtempSync(join(tmpdir(), 'sillyspec-docsgate-remote-'));
+  let originCount = null;
+  let error = null;
+  try {
+    // git worktree add 接受已存在的空目录（mkdtempSync 产物）；失败 fail-open 由调用方回原拦
+    const added = safeGit(projectRoot, ['worktree', 'add', '--detach', tmp, ref], { timeout: 120000 });
+    if (added.error) {
+      error = added.error;
+      return { originCount: null, ref, error };
+    }
+    try {
+      const cfg = readDocsCheckConfig(tmp);
+      const res = runDocsCheck({
+        projectRoot: tmp,
+        paths: cfg.paths,
+        skip: cfg.skip,
+        keywordAssert: cfg.keywordAssert,
+        crossRepoRoots: cfg.crossRepoRoots,
+      });
+      originCount = res.invalid.length;
+    } catch (e) {
+      if (e instanceof DocsCheckConfigError) {
+        error = e.message;
+        originCount = null;
+      } else {
+        throw e;
+      }
+    }
+  } finally {
+    try {
+      const removed = safeGit(projectRoot, ['worktree', 'remove', '--force', tmp]);
+      if (removed.error) {
+        // .git 锁/并发竞争容错：prune 清注册残留 + 直删目录兜底
+        safeGit(projectRoot, ['worktree', 'prune']);
+        try { rmSync(tmp, { recursive: true, force: true }); } catch { /* 目录已不在 */ }
+      }
+    } catch {
+      try { rmSync(tmp, { recursive: true, force: true }); } catch { /* 同上 */ }
+    }
+  }
+  return { originCount, ref, error };
+}
+
 /**
  * IO 入口：跑一次 gate。
  * @param {{ projectRoot: string, specBase: string, initBaseline?: boolean }} opts
@@ -83,7 +159,7 @@ export async function runDocsGate(opts = {}, checkOpts = {}) {
     });
   } catch (e) {
     if (e instanceof DocsCheckConfigError) {
-      return { exitCode: 2, ok: false, current: null, baseline: null, delta: null, message: `docs gate 配置错误：${e.message}`, inited: false };
+      return { exitCode: 2, ok: false, current: null, baseline: null, delta: null, originCount: null, message: `docs gate 配置错误：${e.message}`, inited: false };
     }
     throw e;
   }
@@ -91,20 +167,43 @@ export async function runDocsGate(opts = {}, checkOpts = {}) {
 
   if (initBaseline) {
     writeBaseline(specBase, current);
-    return { exitCode: 0, ok: true, current, baseline: current, delta: 0, message: `📌 docs gate: 基线已初始化为当前实测 ${current} 处失效（${baselineDisplay(specBase)}）`, inited: true };
+    return { exitCode: 0, ok: true, current, baseline: current, delta: 0, originCount: null, message: `📌 docs gate: 基线已初始化为当前实测 ${current} 处失效（${baselineDisplay(specBase)}）`, inited: true };
   }
 
   const baseline = readBaseline(specBase);
   if (baseline === null) {
     return {
-      exitCode: 2, ok: false, current, baseline: null, delta: null,
+      exitCode: 2, ok: false, current, baseline: null, delta: null, originCount: null,
       message: `❌ docs gate: 无基线文件（${baselineDisplay(specBase)}）。首次使用先跑 sillyspec docs gate --init-baseline（以当前实测数立基线，存量既往不咎只拦增量）`,
       inited: false,
     };
   }
   if (Number.isNaN(baseline)) {
-    return { exitCode: 2, ok: false, current, baseline: null, delta: null, message: `❌ docs gate: 基线文件损坏（非非负整数），手工修正或 --init-baseline 重置`, inited: false };
+    return { exitCode: 2, ok: false, current, baseline: null, delta: null, originCount: null, message: `❌ docs gate: 基线文件损坏（非非负整数），手工修正或 --init-baseline 重置`, inited: false };
   }
   const v = evaluateRatchet({ current, baseline });
-  return { exitCode: v.ok ? 0 : 1, ok: v.ok, current, baseline, delta: v.delta, message: v.message, inited: false };
+  if (v.ok) {
+    // 快路径（current ≤ baseline）：原路零变化——不触远端实测（零 git 成本零行为漂移）
+    return { exitCode: 0, ok: true, current, baseline, delta: v.delta, originCount: null, message: v.message, inited: false };
+  }
+  // 坑 docs-gate-stale-baseline（ql-20260915-004）：current > baseline 时 origin 实测兜底——
+  // ratchet 本质=拦增量；基线是静态快照，远端已合入的失效增长不回流基线会造成「未劣于远端
+  // 也被拦」的假拦。实测 origin/main 树：current ≤ 实测值 = 本次不劣于远端 → 放行 + 提示
+  // 重锚；无远端 ref / 实测失败 fail-open 回原拦；current > 实测值 = 真增量劣于远端 → 拦。
+  const measured = await measureRemoteBaselineCount(projectRoot);
+  if (measured.originCount !== null && current <= measured.originCount) {
+    return {
+      exitCode: 0, ok: true, current, baseline, delta: v.delta, originCount: measured.originCount,
+      message: `⚠️ docs gate: 基线陈旧：基线 ${baseline} < ${measured.ref} 实测 ${measured.originCount}，本次 ${current} 处失效未劣于远端不拦——建议 sillyspec docs gate --init-baseline 重锚锁定（以当前实测 ${current} 立线，存量既往不咎只拦增量）`,
+      inited: false,
+    };
+  }
+  const remoteNote = measured.originCount !== null
+    ? `，且劣于 ${measured.ref} 实测 ${measured.originCount} 处（真增量）`
+    : '';
+  return {
+    exitCode: 1, ok: false, current, baseline, delta: v.delta, originCount: measured.originCount,
+    message: `❌ docs gate: ${current} 处失效 > 基线 ${baseline}（新增 ${v.delta} 处）${remoteNote}，拦截。修掉新增引用或显式 --init-baseline 重置基线（需你确认存量合法）`,
+    inited: false,
+  };
 }