sillyspec 3.28.7 → 3.28.9

package/src/constants.js

@@ -43,6 +43,9 @@ export function isPointerStale(pointer) {
   if (!pointer.completedAt) return false
   const completed = new Date(pointer.completedAt)
   const age = Date.now() - completed.getTime()
+  // 非法时间串得 NaN，NaN > x 恒 false——损坏指针永不被标 STALE（2026-09-12 审查批 D-④）；
+  // 判 STALE 让损坏可见（CORRUPTED 通道只覆盖字段缺失形态）
+  if (!Number.isFinite(age)) return true
   return age > 24 * 60 * 60 * 1000
 }
 

package/src/db.js

@@ -1,5 +1,5 @@
 import { openDatabase, applyPragmas, runTransaction } from './db-engine.js';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
 import { dirname } from 'path';
 
 // DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
@@ -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 已在引擎层处理大部分等待；
@@ -171,6 +171,12 @@ export class DB {
           }
         }
         if (!copied) throw lastErr;
+        // SQLite 官方要求：替换 db 文件时必须删除伴生 WAL/SHM——旧 -wal 的 salt 与 db 内容
+        // 不绑定，打开恢复库时会对其跑 recovery，把损坏库的脏页回放到 .bak 内容上（再次损坏
+        // /混态）。copy 成功后、open 之前清侧车（2026-09-12 审查批 B-①）。
+        for (const suffix of ['-wal', '-shm']) {
+          try { rmSync(this.dbPath + suffix, { force: true }); } catch { /* 清理失败不阻断：open 若读到坏 WAL 会走损坏兜底 */ }
+        }
         return openDatabase(this.dbPath);
       }
     }
@@ -246,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
       )
@@ -265,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
       )
     `);
 
@@ -364,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');
   }
 
   /**
@@ -374,8 +388,11 @@ export class DB {
   _migrateAddColumn(table, column, type) {
     try {
       this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
-    } catch {
-      // 列已存在，静默跳过
+    } catch (e) {
+      // 仅「列已存在」可吞（幂等迁移的常态）：catch-all 会把 SQLITE_BUSY（并发 init 撞锁）、
+      // 磁盘满、未来 DDL 拼写错误一并吞掉——列实际未加却被当已存在，后续 INSERT 报
+      // "table has no column"，错误现场远离根因（2026-09-12 审查批 B-①）
+      if (!/duplicate column name/i.test(String(e && e.message || e))) throw e;
     }
   }
 }

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,7 +21,7 @@
  *   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'
@@ -134,6 +134,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 +182,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 +223,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} 前缀声明新模块`)
       }
     }
   }

package/src/docs-check.js

@@ -14,10 +14,95 @@
  * 仅「目录递归」「目录单层」「字面路径」三形态）；Windows 路径归一化；兼容 CRLF/LF。
  */
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, resolve as pathResolve, relative as pathRelative, sep as pathSep } from 'node:path'
+import { execFileSync } from 'node:child_process'
 import jsYaml from 'js-yaml'
 import { parseModuleMapSimple } from './modules.js'
 
+// ── HEAD 模式内容解析层（坑 docs-gate-shared-worktree-parallel-block，2026-09-08 实证）──
+// pre-push gate 校验的语义对象是「被推送的提交树」，而磁盘工作区混有并行会话的未提交
+// 改动——活文档锚点被在途编辑瞬时漂移，任何会话此时推送都被拦（移动靶，5→7 波动实证）。
+// --against HEAD 模式：文档与源码内容一律取 HEAD 版本——干净文件磁盘直读（与 HEAD
+// 逐字节一致，零额外开销）、脏文件（M/D/R）git show 取 HEAD 内容、未跟踪（??）视为
+// 不存在（不随推送走，本就不该校验）。已知边界（接受并留档）：工作区未提交删除的
+// tracked 文档不出现在磁盘 doc 枚举里（walkGlob 扫盘）——其 HEAD 版本确属推送树，
+// 此边角漏检远轻于移动靶误拦；裸名引用仅命中「工作区已删」源文件时层1 找不到候选。
+// 模块级 active reader（set/try/finally restore，quicklog setQuickFileNotes 同款先例）：
+// readLines / resolveCandidates / runDocsCheck / collectInvalidDocRefs 的读统一经此层，
+// reader 未激活时行为与磁盘直读逐字节等价（既有调用方/单测零感知）。
+let _headReader = null
+/** 测试与 runDocsCheck 内部使用：激活/恢复 HEAD reader（返回前值供 finally 还原）。 */
+export function _setHeadReaderForCheck(reader) {
+  const prev = _headReader
+  _headReader = reader
+  return prev
+}
+
+function _rdText(absPath) {
+  if (!_headReader) {
+    try { return readFileSync(absPath, 'utf8') } catch { return null }
+  }
+  return _headReader.readText(absPath)
+}
+
+function _rdExists(absPath) {
+  if (!_headReader) return existsSync(absPath)
+  return _headReader.existsAt(absPath)
+}
+
+/**
+ * 构造 HEAD 模式 reader。非 git 仓 / projectRoot 非 git 根（porcelain 路径相对仓根，
+ * 归一失配）/ git 调用失败 → 返回 null（调用方回退磁盘模式并 warn）。
+ * git status 只列差异文件：不在 status 里的 tracked 文件 = 干净（磁盘读即 HEAD 读）；
+ * ?? 未跟踪 → HEAD 无此文件（existsAt=false, readText=null）；M/D/R → HEAD 仍在
+ * （existsAt=true），内容经 git show（带缓存，脏文件数量级 = 并行会话在途编辑数）。
+ */
+export function createHeadReader(projectRoot, ref = 'HEAD') {
+  const root = pathResolve(projectRoot)
+  const git = (args) => execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let toplevel
+  try { toplevel = git(['rev-parse', '--show-toplevel']).trim() } catch { return null }
+  if (toplevel.split(/[\\/]/).join('/') !== root.split(/[\\/]/).join('/')) return null
+  const status = new Map() // rel(正斜杠) → 'M' | 'D' | 'U'
+  try {
+    for (const line of git(['status', '--porcelain', '--', '.']).split(/\r?\n/)) {
+      if (!line) continue
+      const code = line.slice(0, 2)
+      let p = line.slice(3)
+      if (code.includes('R')) p = p.split(' -> ').pop() // 重命名记新路径
+      p = p.replace(/^"|"$/g, '')
+      const st = code.includes('?') ? 'U' : code.includes('D') ? 'D' : 'M'
+      status.set(p, st)
+    }
+  } catch { return null }
+  const showCache = new Map()
+  const relOf = (abs) => pathRelative(root, pathResolve(abs)).split(pathSep).join('/')
+  return {
+    ref,
+    readText(absPath) {
+      const rel = relOf(absPath)
+      const st = status.get(rel)
+      if (st === undefined) {
+        try { return readFileSync(absPath, 'utf8') } catch { return null } // 干净：磁盘即 HEAD
+      }
+      if (st === 'U') return null // 未跟踪：HEAD 无此文件
+      if (showCache.has(rel)) return showCache.get(rel)
+      let text = null
+      try { text = git(['show', `${ref}:${rel}`]) } catch { text = null }
+      showCache.set(rel, text)
+      return text
+    },
+    existsAt(absPath) {
+      const st = status.get(relOf(absPath))
+      if (st === 'U') return false // 未跟踪 → HEAD 不存在
+      if (st === 'D' || st === 'M') return true // 工作区删/改 → HEAD 仍在
+      return existsSync(absPath)
+    },
+  }
+}
+
 /** 提取 file.js:line / file.js:start-end 引用（反引号包裹与裸文本均命中，全文扫描 D-006）。
  * 扩展名覆盖（archify 借鉴 P1b，2026-09-04）：js/mjs/cjs/ts/tsx/jsx/py/java/go——
  * scan 产物面向任意技术栈项目（如 SillyHub = Python + TypeScript），只认 .js 会让
@@ -268,16 +353,19 @@ function findInTree(dir, baseName, rel = '', treeCache = null) {
 export function resolveCandidates(projectRoot, refFile, treeCache = null) {
   if (refFile.includes('/')) {
     const direct = join(projectRoot, refFile)
-    if (existsSync(direct)) return [direct]
+    if (_rdExists(direct)) return [direct]
     const inSrc = join(projectRoot, 'src', refFile)
-    if (existsSync(inSrc)) return [inSrc]
+    if (_rdExists(inSrc)) return [inSrc]
     const slash = refFile.lastIndexOf('/')
     const baseName = slash === -1 ? refFile : refFile.slice(slash + 1)
     return findInTree(join(projectRoot, 'src'), baseName, '', treeCache)
       .filter((rel) => ('src/' + rel).endsWith('/' + refFile) || 'src/' + rel === 'src/' + refFile)
       .map((rel) => join(projectRoot, 'src', rel))
+      .filter((abs) => _rdExists(abs)) // HEAD 模式：未跟踪源文件不进推送树，不作候选
   }
-  return findInTree(join(projectRoot, 'src'), refFile, '', treeCache).map((rel) => join(projectRoot, 'src', rel))
+  return findInTree(join(projectRoot, 'src'), refFile, '', treeCache)
+    .map((rel) => join(projectRoot, 'src', rel))
+    .filter((abs) => _rdExists(abs))
 }
 
 /**
@@ -301,9 +389,8 @@ export function collectInvalidDocRefs(projectRoot, docEntries) {
   const linesCache = new Map()
   for (const { name, absPath } of docEntries) {
     let content
-    try {
-      content = readFileSync(absPath, 'utf8')
-    } catch {
+    content = _rdText(absPath)
+    if (content === null) {
       readFailures++
       continue
     }
@@ -355,7 +442,9 @@ function readLines(absPath, linesCache = null) {
     return lines
   }
   try {
-    const lines = readFileSync(absPath, 'utf8').split(/\r?\n/)
+    const text = _rdText(absPath)
+    if (text === null) return null
+    const lines = text.split(/\r?\n/)
     if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
     return lines
   } catch { return null }
@@ -479,6 +568,28 @@ function relDisplay(absPath, projectRoot) {
  * @throws {DocsCheckConfigError} glob 形态不支持
  */
 export function runDocsCheck(opts) {
+  // --against <ref>（坑 docs-gate-shared-worktree-parallel-block）：pre-push gate 校验
+  // 「被推送的提交树」而非工作区——激活 HEAD reader 隔离并行会话在途编辑（移动靶）。
+  // 非 git 仓/子目录/git 异常 → 回退磁盘模式并附 warning。--fix 路径不经此（applyFixes
+  // 恒操作工作区磁盘内容，against 对 fix 无意义，CLI 层已拒绝组合）。
+  const against = opts && opts.against ? String(opts.against) : null
+  if (!against) return _runDocsCheckCore(opts)
+  const reader = createHeadReader(opts.projectRoot, against)
+  if (!reader) {
+    const r = _runDocsCheckCore(opts)
+    r.warnings = [...(r.warnings || []),
+      `--against ${against} 不可用（非 git 仓 / 非 git 根子目录 / git 异常），已回退磁盘模式——并行在途编辑可能造成移动靶误拦`]
+    return r
+  }
+  const prev = _setHeadReaderForCheck(reader)
+  try {
+    return _runDocsCheckCore(opts)
+  } finally {
+    _setHeadReaderForCheck(prev)
+  }
+}
+
+function _runDocsCheckCore(opts) {
   // paths/docs 显式传 null（readDocsCheckConfig 无 local.yaml 段时的回退值）须落回缺省 glob，
   // 解构默认值只挡 undefined 不挡 null——docs-check 无配置裸跑曾因此 null.flatMap 崩溃。
   const {
@@ -511,7 +622,10 @@ export function runDocsCheck(opts) {
 
   for (const docRel of docFiles) {
     const docAbs = join(projectRoot, docRel)
-    if (!existsSync(docAbs)) {
+    // HEAD 模式：未跟踪文档（walkGlob 扫盘枚举到但不随推送走）静默跳过——不是失效，
+    // 也不该以「文档不存在」入 invalid（它存在于工作区，只是不属于被推送的提交树）。
+    if (_headReader && !_rdExists(docAbs)) { skippedExempt++; continue }
+    if (!_rdExists(docAbs)) {
       invalid.push({
         doc: docRel, docLine: 0, ref: '', reason: '文档不存在',
         fix: { fixable: false, reason: '文档不存在，无法自动定位' },
@@ -521,7 +635,16 @@ export function runDocsCheck(opts) {
     // 豁免双通道（FR-3 / D-003）：路径段判定免 IO（readFileSync 前）；
     // frontmatter 判定需读文件（读取后）。豁免文档整体跳过不计 invalid。
     if (exempt && isExemptDocPath(docRel)) { skippedExempt++; continue }
-    const md = readFileSync(docAbs, 'utf8')
+    const md = _rdText(docAbs)
+    if (md === null) {
+      // HEAD 模式下未跟踪文档（不随推送走，walkGlob 扫盘枚举到此）——不计失效不报警
+      if (_headReader) { skippedExempt++; continue }
+      invalid.push({
+        doc: docRel, docLine: 0, ref: '', reason: '文档不可读',
+        fix: { fixable: false, reason: '文档不可读（权限/路径异常）' },
+      })
+      continue
+    }
     if (exempt && isExemptDocFrontmatter(md)) { skippedExempt++; continue }
     const refs = collectDocRefs(md)
     const mdLines = md.split(/\r?\n/)
@@ -836,10 +959,12 @@ export const DECISIONS_DEFAULT_BEHIND_THRESHOLD = 10
  * @param {string} yamlText local.yaml 全文
  * @returns {string[]} 键列表；无声明返回 []
  */
-function extractKnownFailureKeys(yamlText) {
+export function extractKnownFailureKeys(yamlText) {
   if (!yamlText) return []
   const yaml = String(yamlText).replace(/\r\n?/g, '\n')
-  const inline = yaml.match(/^known_failures:\s*\[([^\]]*)\]\s*(?:#.*)?$/m)
+  // 贪婪 .* 同 verify-postcheck.extractKnownFailures（坑 known-failures-inline-nested-bracket：
+  // 值内 ] 使 [^\]]* 截断、整表静默清空；两处复刻必须同口径互指）
+  const inline = yaml.match(/^known_failures:\s*\[(.*)\]\s*(?:#.*)?$/m)
   if (inline) {
     return inline[1].split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
   }

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
@@ -77,10 +153,13 @@ export async function runDocsGate(opts = {}, checkOpts = {}) {
       skip: checkOpts.skip || cfg.skip,
       keywordAssert: checkOpts.keywordAssert ?? cfg.keywordAssert,
       crossRepoRoots: checkOpts.crossRepoRoots || cfg.crossRepoRoots,
+      // 坑 docs-gate-shared-worktree-parallel-block：--against <ref> 透传——按提交树校验
+      //（pre-push 语义），隔离并行会话在途编辑的锚点瞬时漂移（移动靶）
+      ...(checkOpts.against ? { against: checkOpts.against } : {}),
     });
   } 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;
   }
@@ -88,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,
+  };
 }