sillyspec 3.28.11 → 3.28.13

package/src/change-risk-profile.js

@@ -6,7 +6,7 @@
  * integration-critical / deployment-critical），产出门控验证需求。
  */
 import { readFileSync, statSync } from 'fs'
-import { join } from 'path'
+import { join, isAbsolute } from 'path'
 
 // ============ 向后兼容：旧的 INTEGRATION_CRITICAL_PATTERNS ============
 
@@ -312,7 +312,16 @@ export function detectChangeRisk({ designContent = '', planContent = '', changed
 // classifyReceiptCommandSource（facts.integrationRan 判定）与本分类同族口径，两处正则族
 // 保持同步演进）。smoke 冒烟命令族计 cross-layer（D-006 退役判据：批次 C commands.smoke
 // 落地后由 smoke 回执一票判定「集成实测已跑」——起服务冒烟即跨层实测，不得默认 build 误拦金路径）。
-const RECEIPT_SOURCE_CROSS_LAYER_RE = new RegExp([
+//
+// 来源标记直判（2026-09-17-api-coverage-smoke task-02 / Grill B-1 修正，FR-03）：条目 source
+// 标记 'cli-noai-smoke'（verify-probes ensureSmokeReceiptSection 注入的机器段行尾注，
+// parseEvidenceSlots additive 解析回填）→ 直判 cross-layer，**优先于命令词正则分类**——
+// 修正点在标记识别而非命令词增补：node scripts/smoke.mjs / bash smoke.sh / python smoke.py
+// 等脚本形态在既有正则下全判 build 会误拦金路径，且脚本形态词表不可枚举（正则族两文件零词
+// 变动）。对齐目标：verify-probes.js classifyReceiptCommandSource（judgeIntegrationRan 消费）
+// 同款 sourceMark 参数与标记族——**任一侧增改标记族必须双侧同步**（G-3 先例：producer 侧
+// 曾漏 smoke 一词致口径分裂）。
+export const RECEIPT_SOURCE_CROSS_LAYER_RE = new RegExp([
   '\\bcurl\\b', '\\bwget\\b', '\\bhttpie\\b', '\\bInvoke-WebRequest\\b', '\\bInvoke-RestMethod\\b',
   '\\biwr\\b', '\\birm\\b', 'https?://',
   'spring-boot:run', '\\bjava\\b[^|\\n]*\\s-jar\\b',
@@ -320,8 +329,11 @@ const RECEIPT_SOURCE_CROSS_LAYER_RE = new RegExp([
   '\\bdotnet\\s+run\\b', '\\bflask\\s+run\\b', '\\buvicorn\\b', '\\bgunicorn\\b',
   '\\b(?:nc|netcat|telnet|socat)\\b',
 ].join('|'), 'i')
-const RECEIPT_SOURCE_UNIT_RE = /\bJUnitCore\b|\bnode\s+--test\b|\bmocha\b|\bjest\b|\bvitest\b|\bpytest\b|\bphpunit\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b/i
-function classifyReceiptSourceTag(command) {
+export const RECEIPT_SOURCE_UNIT_RE = /\bJUnitCore\b|\bnode\s+--test\b|\bmocha\b|\bjest\b|\bvitest\b|\bpytest\b|\bphpunit\b|\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test\b/i
+/** CLI 机器段来源标记（与 verify-probes.js SMOKE_RECEIPT_SOURCE_MARK / task-01 记录 source 同值，双侧同步） */
+export const CLI_SMOKE_SOURCE_MARK = 'cli-noai-smoke'
+function classifyReceiptSourceTag(command, sourceMark) {
+  if (sourceMark === CLI_SMOKE_SOURCE_MARK) return 'cross-layer'
   const cmd = String(command || '')
   if (RECEIPT_SOURCE_CROSS_LAYER_RE.test(cmd)) return 'cross-layer'
   if (RECEIPT_SOURCE_UNIT_RE.test(cmd)) return 'unit'
@@ -430,18 +442,28 @@ export function checkIntegrationEvidence(verifyContent, requiredVerification, op
  * 缺省按回执 command 来源就地分类（classifyReceiptSourceTag），未定类默认 'build'（向后
  * 兼容的 fail-closed 缺省）；sourceTag ∈ {build, unit} 的回执不作集成实测绿判据（四条件
  * 全过也只到 non-green，reason 点名来源）——verify-postcheck 不在本调用链上，不受影响。
+ *
+ * r.source（2026-09-17-api-coverage-smoke task-02 / FR-03，Grill B-1）：条目级来源标记
+ * （parseEvidenceSlots additive 第五字段，CLI 机器段行 'cli-noai-smoke' 尾注回填）透传给
+ * classifyReceiptSourceTag 直判 cross-layer——优先级在调用方 opts.sourceTag 声明源之下、
+ * 命令词正则分类之上；无标记条目分类路径逐字节不变。
  */
 function auditRuntimeReceipt(r, opts) {
   const out = { claim: r && r.claim, logPath: r && r.logPath, sourceTag: null, green: false, logExists: null, mtimeInWindow: null, failSignatures: 0, exitCode: r && typeof r.exitCode === 'number' ? r.exitCode : null, reason: '' }
   // 打标依据 = 命令来源声明（不解析日志内容，X-10）：opts.sourceTag 调用方声明源优先，
+  // 其次条目 source 标记直判（task-02 Grill B-1——'cli-noai-smoke' 直判 cross-layer），
   // 否则按回执 command 分类；非法/缺省走分类，未定类默认 build。
   const declaredSource = opts && typeof opts.sourceTag === 'string'
     && ['cross-layer', 'build', 'unit'].includes(opts.sourceTag) ? opts.sourceTag : null
-  out.sourceTag = declaredSource || classifyReceiptSourceTag(r && r.command)
+  out.sourceTag = declaredSource || classifyReceiptSourceTag(r && r.command, r && r.source)
   if (!r || !r.logPath) { out.reason = '回执缺 logPath'; return out }
+  // 绝对路径直读（2026-09-17-api-coverage-smoke task-02）：CLI 机器段（source=cli-noai-smoke）
+  // 的 logPath 是 quality-scan 记录的绝对路径实录——join(cwd, 绝对路径) 会拼出破损路径
+  // 误报「日志不存在」，isAbsolute 时跳过 join（verify-postcheck 测试输出解析同款口径）。
+  const resolveLog = (p) => (opts.cwd && !isAbsolute(String(p)) ? join(opts.cwd, p) : p)
   let content = null
   try {
-    const abs = opts.cwd ? join(opts.cwd, r.logPath) : r.logPath
+    const abs = resolveLog(r.logPath)
     content = readFileSync(abs, 'utf8')
     out.logExists = true
   } catch {
@@ -452,7 +474,7 @@ function auditRuntimeReceipt(r, opts) {
   if (opts.verifyStartAt) {
     try {
       const startAt = new Date(opts.verifyStartAt).getTime()
-      out.mtimeInWindow = statSync(opts.cwd ? join(opts.cwd, r.logPath) : r.logPath).mtimeMs >= startAt - 60_000
+      out.mtimeInWindow = statSync(resolveLog(r.logPath)).mtimeMs >= startAt - 60_000
       if (!out.mtimeInWindow) { out.reason = `日志 mtime 早于 verifyStartAt（${r.logPath}）`; return out }
     } catch { out.mtimeInWindow = null }
   }

package/src/commit-guard.js

@@ -0,0 +1,119 @@
+/**
+ * commit-guard.js — pre-commit 提交边界守卫（fail-open，只警告不阻断）。
+ *
+ * 为什么需要（2026-09-17 实证）：多会话共享仓里 git 暂存区是共享状态——他会话 git add 过的
+ * 文件会被本会话的裸 git commit 一并带走（当日事故：add 带 pathspec 但 commit 裸跑，并行
+ * 会话 5 个 staged 文件被扫入 fb5bc11，事后 reset --soft + pathspec 重提交外科手术拆回）。
+ * AGENTS.md 第 18 条已加厚为「add/commit 同清单 pathspec」，本守卫是同一约束的工具化兜底：
+ * 纪理会漏，钩子卡点不会漏（与 write-audit / concurrent-detect 同族——确定性的事 CLI 兜）。
+ *
+ * 信号（只警告，exit 恒 0）：
+ *   S1 quick 声明面对账：staged 含 .sillyspec/quicklog/patches/ql-<id>.json 时，读其
+ *      rows[].declared 声明面——staged 中超出声明面的文件（quicklog 账本/补丁自身除外）
+ *      即警告「疑似扫入他者文件」。
+ *   S2 跨变更目录：staged 里 .sillyspec/changes/<name>/（含 archive/）命中 ≥2 个不同
+ *      name → 警告「正常提交只携带一个变更的面」。
+ * 命中即 stderr 警告 + appendWriteAudit 留痕（via: 'commit-guard'）。
+ *
+ * fail-open 硬约束（钩子挂在所有会话共享的 .husky/ 上，守卫自身绝不拦任何人的提交）：
+ *   非 git 仓 / git 失败 / ql json 损坏 / 任何异常 → 静默 exit 0；钩子侧再垫 || true 双保险。
+ */
+import { execFileSync } from 'child_process'
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { pathToFileURL } from 'url'
+import { appendWriteAudit } from './write-audit.js'
+
+const QUICKLOG_PREFIX = '.sillyspec/quicklog/'
+const QL_PATCH_JSON_RE = /^\.sillyspec\/quicklog\/patches\/ql-[^/]+\.json$/
+const CHANGES_RE = /^\.sillyspec\/changes\/(?:archive\/)?([^/]+)\//
+
+/**
+ * S1+S2 纯函数：staged 面 + ql patch json 映射 → 警告数组（无 git/文件系统依赖，可直测）。
+ * @param {string[]} stagedFiles staged 相对路径
+ * @param {Record<string, any>} qlPatches { json路径 → 解析结果 }（损坏的已由调用方跳过）
+ * @returns {{signal: string, files: string[], message: string}[]}
+ */
+export function analyzeStagedFace(stagedFiles, qlPatches) {
+  const staged = Array.isArray(stagedFiles) ? stagedFiles.filter((f) => typeof f === 'string' && f) : []
+  const warnings = []
+  // S1 quick 声明面对账
+  const qlJsons = staged.filter((f) => QL_PATCH_JSON_RE.test(f))
+  if (qlJsons.length > 0) {
+    const declared = new Set()
+    for (const j of qlJsons) {
+      const parsed = (qlPatches || {})[j]
+      if (!parsed || !Array.isArray(parsed.rows)) continue
+      for (const r of parsed.rows) {
+        if (r && r.declared && typeof r.path === 'string') declared.add(r.path)
+      }
+    }
+    if (declared.size > 0) {
+      const offending = staged.filter((f) => !f.startsWith(QUICKLOG_PREFIX) && !declared.has(f))
+      if (offending.length > 0) {
+        warnings.push({
+          signal: 'quick_declared_face_exceeded',
+          files: offending,
+          message: `staged 超出 quick 声明面（${qlJsons.map((f) => f.split('/').pop()).join(', ')}）：${offending.join('、')}——疑似扫入他者文件，核对是否该随本提交带走`,
+        })
+      }
+    }
+  }
+  // S2 跨变更目录
+  const changeNames = new Set()
+  for (const f of staged) {
+    const m = f.match(CHANGES_RE)
+    if (m) changeNames.add(m[1])
+  }
+  if (changeNames.size >= 2) {
+    warnings.push({
+      signal: 'multi_change_dirs_staged',
+      files: staged.filter((f) => CHANGES_RE.test(f)),
+      message: `staged 同时含 ${changeNames.size} 个变更目录（${[...changeNames].join('、')}）——正常提交只携带一个变更的面，疑似夹带并行会话产物`,
+    })
+  }
+  return warnings
+}
+
+function main() {
+  const cwd = process.cwd()
+  let staged = []
+  try {
+    staged = execFileSync('git', ['diff', '--cached', '--name-only'], {
+      cwd,
+      encoding: 'utf8',
+      // stderr 必须管道化：execFileSync 默认把子进程 stderr 透传给父进程——非 git 目录下
+      // git 落 --no-index 模式报 unknown option 的 usage 长文会漏进守卫 stderr（噪声）。
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean)
+  } catch {
+    return 0 // 非 git 仓 / git 异常 → 放行
+  }
+  if (staged.length === 0) return 0
+  const qlPatches = {}
+  for (const f of staged) {
+    if (!QL_PATCH_JSON_RE.test(f)) continue
+    try {
+      qlPatches[f] = JSON.parse(readFileSync(join(cwd, f), 'utf8'))
+    } catch { /* 单个 json 损坏 → 跳过该信号源，不连坐 */ }
+  }
+  const warnings = analyzeStagedFace(staged, qlPatches)
+  if (warnings.length === 0) return 0
+  for (const w of warnings) process.stderr.write(`⚠️ [commit-guard] ${w.message}\n`)
+  const specDir = join(cwd, '.sillyspec')
+  if (existsSync(specDir)) {
+    appendWriteAudit(specDir, {
+      via: 'commit-guard',
+      files: [...new Set(warnings.flatMap((w) => w.files))].slice(0, 20),
+      detail: { signals: warnings.map((w) => ({ signal: w.signal, files: w.files.slice(0, 20) })) },
+    })
+  }
+  return 0
+}
+
+// 直接执行（node src/commit-guard.js）才跑 main；被 import 时不跑
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+if (invokedDirectly) process.exit(main())

package/src/config-schema.js

@@ -70,6 +70,7 @@ export const LOCAL_YAML_SCHEMA = {
         { path: 'commands.build', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '构建命令。', example: 'npm run build' },
         { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断；quick --done 触及 src/test 时同款实测（P0-2 门禁）。', example: 'npm test' },
         { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'runQuickTestLintGate (src/run/quick-audit.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令——quick --done 触及 src/test 时 CLI 亲自执行（P0-2 门禁，失败阻断完成）。', example: 'npm run lint' },
+        { path: 'commands.smoke', type: 'string', optional: true, status: 'live', readers: ['executeVerifyQualityScan (src/run/verify-quality-scan.js)'], desc: '接口冒烟命令——verify 阶段 CLI 亲跑（脚本自理服务生命周期：后台起服+轮询就绪+finally 杀），300s 超时帽，失败/超时只记失败态不阻断本步、触发 PASS 封顶（D-002）；指纹含此键，未变不重跑。', example: 'node scripts/smoke.mjs' },
         { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
       ],
     },
@@ -316,6 +317,7 @@ commands:
   build: npm run build
   test: npm test
   lint: npm run lint
+  # smoke: node scripts/smoke.mjs   # verify 冒烟命令（可选；脚本自理服务生命周期，失败只封顶 PASS 不阻断）
   # install: npm install   # worktree 依赖安装命令
 
 # ── SillyHub MCP 客户端凭据（派发到 worker 用）──

package/src/decision-distill.js

@@ -211,8 +211,9 @@ function parseModulePathsSubset(content) {
 /** 未注入 moduleIndex 时的尽力发现：knowledgeRoot 同级 docs/<项目>/modules/_module-map.yaml。
  * 多子项目仓（如本仓 sillyspec+dashboard）各项目有自己的 map——dogfood 实证（2026-08-24）：
  * 只取首个命中会把主项目条目全部误落 unmapped（dashboard 的 map 按字母序先命中）。
- * 改为合并全部项目的 map（同名模块合并 paths/core_files 去重），失败归 null → 全部 unmapped。 */
-function discoverModuleIndex(knowledgeRoot) {
+ * 改为合并全部项目的 map（同名模块合并 paths/core_files 去重），失败归 null → 全部 unmapped。
+ * 2026-09-18-fr-index-l1：导出供 fr-index 域解析复用。 */
+export function discoverModuleIndex(knowledgeRoot) {
   try {
     const docsDir = join(dirname(knowledgeRoot), 'docs')
     if (!existsSync(docsDir)) return null
@@ -319,15 +320,19 @@ function renderBlockLines(entry, headHash, supersedesNote, changeName) {
   return lines
 }
 
-/** 知识文件切段：preamble 行 + D-xxx@vN 条目段（段边界 = 下一 `## D-` 头）。
+/** 知识文件切段：preamble 行 + 条目段（段边界 = 下一节头）。
  * 段的变更归属取段内 `变更：<name>` 行；无该行的历史条目 → change=null（legacy：
- * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。 */
-function splitKnowledgeSections(content) {
+ * 升级前落库的条目，不参与新条目的同号匹配/supersede——只共存不误删）。
+ * 2026-09-18-fr-index-l1 参数化：sectionRegex/buildId 经参（decisions 缺省不变；fr 侧传 FR 节头
+ * 正则与恒等 id），decisions 调用点零改动。 */
+export function splitKnowledgeSections(content, opts = {}) {
+  const sectionRegex = opts.sectionRegex || /^## (D-\d+)@v(\d+)\s*(.*)$/
+  const buildId = opts.buildId || ((n, v) => `${n}@v${v}`)
   const sections = []
   const preamble = []
   let cur = null
   for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
-    const m = line.match(/^## (D-\d+)@v(\d+)\s*(.*)$/)
+    const m = line.match(sectionRegex)
     if (m) {
       if (cur) sections.push(cur)
       cur = { number: m[1], version: parseInt(m[2], 10), title: m[3].trim(), lines: [line] }
@@ -338,7 +343,7 @@ function splitKnowledgeSections(content) {
   }
   if (cur) sections.push(cur)
   for (const s of sections) {
-    s.id = `${s.number}@v${s.version}`
+    s.id = buildId(s.number, s.version)
     const cm = s.lines.find(l => /^变更[：:]/.test(l))
     s.change = cm ? cm.replace(/^变更[：:]\s*/, '').trim() || null : null
   }
@@ -346,7 +351,7 @@ function splitKnowledgeSections(content) {
 }
 
 /** 段落重组落盘文本（幂等归一：段间恰好一个空行 + 文件单一尾换行） */
-function joinKnowledgeFile(preamble, sections) {
+export function joinKnowledgeFile(preamble, sections) {
   const parts = []
   const pre = preamble.join('\n').replace(/\s+$/, '')
   if (pre) parts.push(pre)
@@ -394,19 +399,21 @@ function applyEntryToSections(sections, entry, headHash) {
 // INDEX.md decisions 路由行幂等维护（FR-05：写入责任在本模块；只动 ## Decisions 段内指向 decisions/ 的行）
 // ---------------------------------------------------------------------------
 
-/** INDEX 路由行格式与 knowledge-match 解析口径一致：`- <域>|decision|决策 → [decisions/<域>.md](decisions/<域>.md)` */
-function routingLine(domain) {
-  return `- ${domain}|decision|决策 → [decisions/${domain}.md](decisions/${domain}.md)`
-}
-
-const ROUTING_TARGET_RE = /^-\s+.*→\s*\[[^\]]*\]\(decisions\/([^)#]+?)(?:\.md)?(?:#[^)]*)?\)\s*$/
-
-/** 域文件实况 ↔ ## Decisions 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行 */
-function syncIndexRoutingLines(knowledgeRoot) {
-  const decisionsDir = join(knowledgeRoot, 'decisions')
+/**
+ * 域文件实况 ↔ INDEX 段路由行对账：缺行补、失效行删、重复行去重；不动其他类别行。
+ * 2026-09-18-fr-index-l1 参数化：section/subdir/makeLine/matchTarget 经参（decisions 缺省不变），
+ * fr 侧传 'FR 需求索引' 段与 fr/ 子目录——两类路由行各守各段互不干扰。
+ */
+export function syncIndexRoutingLines(knowledgeRoot, opts = {}) {
+  const sectionName = opts.section || 'Decisions'
+  const subdir = opts.subdir || 'decisions'
+  const makeLine = opts.makeLine || ((d) => `- ${d}|decision|决策 → [${subdir}/${d}.md](${subdir}/${d}.md)`)
+  const esc = subdir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const targetRe = opts.matchTarget || new RegExp(`^-\\s+.*→\\s*\\[[^\\]]*\\]\\(${esc}/([^)#]+?)(?:\\.md)?(?:#[^)]*)?\\)\\s*$`)
+  const domainDir = join(knowledgeRoot, subdir)
   let domains
   try {
-    domains = readdirSync(decisionsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
+    domains = readdirSync(domainDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
   } catch { return false }
   if (domains.length === 0) return false
 
@@ -417,29 +424,29 @@ function syncIndexRoutingLines(knowledgeRoot) {
   }
   const lines = original ? original.replace(/\r\n/g, '\n').split('\n') : ['# Knowledge Index', '']
 
-  // 定位 ## Decisions 段边界
+  // 定位段边界（参数化段名）
   let secStart = -1
   let secEnd = lines.length
   for (let i = 0; i < lines.length; i++) {
     const h = lines[i].match(/^##\s+(.+?)\s*$/)
     if (!h) continue
     if (secStart === -1) {
-      if (h[1] === 'Decisions') secStart = i + 1
+      if (h[1] === sectionName) secStart = i + 1
     } else { secEnd = i; break }
   }
 
-  const desired = domains.map(routingLine)
+  const desired = domains.map(makeLine)
   if (secStart === -1) {
     // 无段则追加（保留原文件其余内容）
     while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
-    lines.push('', '## Decisions', ...desired)
+    lines.push('', `## ${sectionName}`, ...desired)
   } else {
     const body = lines.slice(secStart, secEnd)
     const kept = []
     const seen = new Set()
     const domainSet = new Set(domains)
     for (const l of body) {
-      const m = l.match(ROUTING_TARGET_RE)
+      const m = l.match(targetRe)
       if (!m) { kept.push(l); continue } // 非路由行（注释/空行）原样保留
       // 目标域文件仍存在的路由行原样保留（关键词可能被人工扩充）；失效行（文件已不存在）与重复行删
       if (domainSet.has(m[1]) && !seen.has(m[1])) { seen.add(m[1]); kept.push(l) }
@@ -448,7 +455,7 @@ function syncIndexRoutingLines(knowledgeRoot) {
     const tail = []
     while (kept.length > 0 && kept[kept.length - 1].trim() === '') tail.unshift(kept.pop())
     for (const d of desired) {
-      const m = d.match(ROUTING_TARGET_RE)
+      const m = d.match(targetRe)
       if (m && !seen.has(m[1])) kept.push(d) // 缺行补
     }
     kept.push(...tail)

package/src/diagnostic-codes.js

@@ -0,0 +1,95 @@
+/**
+ * diagnostic-codes.js — machine-interface 族诊断码表单一源
+ *
+ * 为什么需要：信封 errors/warnings 是自由文本中文句子，程序化消费方（SillyHub/未来 MCP
+ * 消费者）无法按错误类型稳定分支——提示语改一个字就是一次静默破坏性变更。本表给
+ * gate/derive/progress show 三面的自产错误配稳定 snake_case 身份码（2026-09-17
+ * OpenSpec 源码对比三轮评审②号项，change 2026-09-17-mi-diagnostic-codes）。
+ *
+ * 纪律（D-002@v1 硬边界）：
+ *   - 恰 10 码：信封级 4（exit 2 面）+ check 级 6（gate/derive 失败面）。
+ *   - 只码 machine-interface 族自产错误——stage-contract 校验器散文、doctor/validate/
+ *     scope-audit 面首期不碰（码标识失败面，不标识每条消息）。
+ *   - 扩码走变更流程追加；本表是码身份唯一源——契约文档诊断码目录（interface-contract.md）
+ *     与运行时发射不得出现表外码，test/diagnostic-codes-parity.test.mjs 双向钉死
+ *     （OpenSpec 的 agent-contract 无 parity 测试，此为反超点）。
+ *
+ * 零依赖叶子模块（不 import 仓内任何其他 src 模块，防环）。
+ */
+
+/**
+ * 码 → { surface: 消费命令面, exit: 该失败面的退出码语义, trigger: 触发条件 }。
+ * surface 取值 ∈ gate / derive / progress show（CLI 子命令视角）。
+ */
+export const DIAGNOSTIC_CODES = Object.freeze({
+  // ── 信封级（无法核验，exit 2）──
+  db_missing: {
+    surface: ['gate', 'derive', 'progress show'],
+    exit: 2,
+    trigger: '进度库不存在（只读契约：不为其建库，fail-closed）',
+  },
+  change_not_found: {
+    surface: ['gate', 'derive'],
+    exit: 2,
+    trigger: '变更名在进度库无记录',
+  },
+  unknown_facet: {
+    surface: ['derive'],
+    exit: 2,
+    trigger: 'facet ∉ FACETS 白名单（用法错）',
+  },
+  internal_error: {
+    surface: ['gate', 'derive', 'progress show'],
+    exit: 2,
+    trigger: '内部异常兜底（stdout 仍为合法 JSON）',
+  },
+  // ── check 级（事实性阻断，exit 1）──
+  artifacts_invalid: {
+    surface: ['gate', 'derive'],
+    exit: 1,
+    trigger: 'runValidators 失败（gate artifacts check 与 derive artifacts facet 同源）',
+  },
+  design_file_ref_invalid: {
+    surface: ['gate'],
+    exit: 1,
+    trigger: 'design 文件清单行级核验失败（直承 design-facts.js 既有稳定码）',
+  },
+  transition_blocked: {
+    surface: ['gate'],
+    exit: 1,
+    trigger: 'checkTransition 不允许（含 failed_post_check 门控）',
+  },
+  execute_evidence_unchanged: {
+    surface: ['gate', 'derive'],
+    exit: 1,
+    trigger: 'base..head 无代码变更（checkbox ≠ implementation）',
+  },
+  task_reviews_invalid: {
+    surface: ['gate', 'derive'],
+    exit: 1,
+    trigger: 'validateTaskReviews 失败（review.json 缺失/schema/verdict=fail）',
+  },
+  verify_test_failed: {
+    surface: ['gate', 'derive'],
+    exit: 1,
+    trigger: 'commands.test 实测失败',
+  },
+});
+
+/** gate check id → 失败码（六 check 全覆盖；表外 id 返回 undefined，调用方不挂键）。 */
+const CHECK_ID_TO_CODE = Object.freeze({
+  artifacts: 'artifacts_invalid',
+  'design-file-list': 'design_file_ref_invalid',
+  transition: 'transition_blocked',
+  'execute-evidence': 'execute_evidence_unchanged',
+  'task-reviews': 'task_reviews_invalid',
+  'verify-test': 'verify_test_failed',
+});
+
+/**
+ * @param {string} checkId - gate check id（artifacts/design-file-list/transition/execute-evidence/task-reviews/verify-test）
+ * @returns {string|undefined} 对应失败码；表外 id 返回 undefined（信封不挂 code 键）
+ */
+export function checkCode(checkId) {
+  return CHECK_ID_TO_CODE[checkId];
+}

package/src/doctor-diagnostics.js

@@ -33,6 +33,9 @@ import { pruneTimestampedEntries } from './runtime-hygiene.js';
 import { CHECK_SEVERITY } from './constants.js';
 import { checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME, QUICK_SID_RE, resolveRuntimeRoot } from './run/shared.js';
 import { readFrictionLedger } from './friction-ledger.js';
+// FR 索引消费（2026-09-18-fr-index-l1 L1，D-007）：D14 第四检查——epoch 后归档的索引在场+取代完整。
+// fr-index 是纯 fs 叶子链（仅 decision-distill 底座），doctor 静态引入无环。
+import { FR_INDEX_EPOCH, scanFrIndex, parseChangeRequirements } from './fr-index.js';
 
 // db 角色标签
 const DB_ROLE = {
@@ -1125,6 +1128,170 @@ export function detectSelfMaintenanceTax(cwd, authoritySpecDir) {
   }
 }
 
+/**
+ * D14 归档完整性重扫（archive_integrity，2026-09-17 OpenSpec validate --archived 对标）。
+ *
+ * 为什么需要：归档前的完成门禁很严（review.json 驱动勾选 / Wave 断言 / verify 对账），
+ * 但目录搬进 changes/archive/ 后**没有任何机制回头看**——手工挪目录绕流程的自愈只在
+ * 下次 CLI 触碰时生效，归档后手改 tasks.md / 删 plan.md 无人发现。本维度补事后重扫：
+ *   ① 任务 checkbox 全勾（tasks.md 优先，回退 plan.md——读侧兼容同 D5/progress 口径；
+ *      归档后 runtime 工件已 prune，review.json 不可用，checkbox 是归档目录里唯一持久的完成面）
+ *   ② plan.md 在场（archive 自愈 findAlreadyArchivedDir 的基准文件）
+ *   ③ 注册表文件存在但读不了 → finding（OpenSpec #205 教训：读不了 ≠ 没任务，
+ *      检查不许在什么都没看的情况下静默通过）
+ * 语义：WARNING advisory 不阻断、只读无修复（钩子/门禁挂载是后续独立策略裁决）；
+ * 无 archive 目录 / 无 task 行 → pass（无任务视为完备，同 OpenSpec "nothing to complete"）。
+ */
+function detectArchiveIntegrity(cwd, authoritySpecDir) {
+  const base = { name: 'archive_integrity', label: '归档完整性重扫', safe_actions: [] };
+  if (!authoritySpecDir) {
+    return { ...base, pass: true, severity: null, findings: ['无权威 specDir，跳过'] };
+  }
+  const archiveDir = join(authoritySpecDir, 'changes', 'archive');
+  if (!existsSync(archiveDir)) {
+    return { ...base, pass: true, severity: null, findings: ['无 changes/archive 目录（未归档/新仓），跳过'] };
+  }
+  let entries;
+  try {
+    entries = readdirSync(archiveDir, { withFileTypes: true });
+  } catch (e) {
+    return { ...base, pass: false, severity: CHECK_SEVERITY.WARNING, findings: [`changes/archive 目录不可读（${e?.message || e}）——人工排查，不静默跳过`] };
+  }
+  const names = entries
+    .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+    .map((d) => d.name)
+    .sort();
+  if (names.length === 0) {
+    return { ...base, pass: true, severity: null, findings: ['changes/archive 为空（无已归档变更）'], archive_count: 0, offenders: [] };
+  }
+  const offenders = [];
+  // FR 索引面（D14 第四检查数据源，循环外一次扫描复用；fr/ 不存在=仓未启用，全跳不误报）
+  const frKnowledgeRoot = join(authoritySpecDir, 'knowledge');
+  const frEnabled = existsSync(join(frKnowledgeRoot, 'fr'));
+  const frEntries = frEnabled ? scanFrIndex(frKnowledgeRoot) : [];
+  for (const name of names) {
+    const dir = join(archiveDir, name);
+    const reasons = [];
+    // ② plan.md 在场性
+    const planPath = join(dir, 'plan.md');
+    const hasPlan = existsSync(planPath);
+    if (!hasPlan) reasons.push('plan.md 缺失（归档自愈基准文件）');
+    // ①③ 任务注册表：tasks.md 优先回退 plan.md；存在但不可读必须显式报（区分「缺席」与「读不了」）。
+    // 2026-08-20-task-truth-unify 之前的旧归档完成态勾在 plan.md（tasks.md 是留给后人的未勾任务清单）——
+    // tasks.md 有 checkbox 行但 0 勾、而 plan.md 有 ≥1 勾时，完成证据在 plan.md，切 plan.md 为完成源
+    // （真实仓首扫实证：2026-05-31-sqlite-migration tasks 0/15 + plan 15/15，43 份 offenders 大半为此误报）。
+    const tasksPath = join(dir, 'tasks.md');
+    const readRegistry = (p) => {
+      const content = readFileSync(p, 'utf8');
+      // 与 progress.js readPlanCheckboxStatus 同正则（task- 前缀锚定，x/X 计勾）
+      const re = /^\s*[-*]\s+\[([ xX])\]\s+task-\d+/gm;
+      let t = 0;
+      let c = 0;
+      let m;
+      while ((m = re.exec(content)) !== null) {
+        t++;
+        if (m[1] !== ' ') c++;
+      }
+      return { total: t, checked: c };
+    };
+    const regPath = existsSync(tasksPath) ? tasksPath : hasPlan ? planPath : null;
+    if (regPath) {
+      try {
+        let stat = readRegistry(regPath);
+        if (regPath === tasksPath && stat.total > 0 && stat.checked === 0 && hasPlan) {
+          try {
+            const planStat = readRegistry(planPath);
+            if (planStat.total > 0 && planStat.checked > 0) stat = planStat;
+          } catch { /* plan.md 不可读 → 维持 tasks.md 0 勾口径（本就报未勾） */ }
+        }
+        if (stat.total > 0 && stat.checked < stat.total) {
+          reasons.push(`${stat.total - stat.checked} 个任务未勾（${stat.checked}/${stat.total}）`);
+        }
+      } catch (e) {
+        reasons.push(`任务注册表不可读（${relative(archiveDir, regPath)}：${e?.code || e?.message || e}）`);
+      }
+    }
+    // ── ④ FR 索引在场与取代完整（2026-09-18-fr-index-l1 L1，D-007：epoch 分界第四检查）──
+    // 豁免面：fr/ 目录不存在（仓未启用索引，全跳）；无日期前缀/epoch 前归档（存量不回填）；
+    // quick-* 与无 requirements.md（quick/scale:small 无索引义务）。违者并入 offenders（豁免走既有账本）。
+    if (frEnabled) {
+      const dm = name.match(/^(\d{4}-\d{2}-\d{2})-/);
+      if (dm && dm[1] >= FR_INDEX_EPOCH && existsSync(join(dir, 'requirements.md'))) {
+        if (!frEntries.some((e) => e.change === name)) {
+          reasons.push('FR 索引缺失（epoch 后归档应有索引条目——归档时 indexRequirements 未落，查 archive 步降级日志）');
+        } else {
+          try {
+            const reqParsed = parseChangeRequirements(dir);
+            const refIds = new Set();
+            for (const fr of reqParsed.frs) for (const r of fr.supersedes) refIds.add(r);
+            for (const refId of refIds) {
+              if (!frEntries.some((e) => e.id === refId && e.supersededBy)) {
+                reasons.push(`承接未翻取代（${refId} 被引用但索引中未标 superseded）`);
+              }
+            }
+          } catch { /* requirements 解析失败归任务注册表口径，此处不重复报 */ }
+        }
+      }
+    }
+    if (reasons.length > 0) offenders.push({ name, reasons });
+  }
+
+  // 豁免账本（2026-09-17 收尾裁决）：老归档历史形态（早于 plan.md 流程的手工归档/远古命名）逐份豁免——
+  // 照 docs-check skip 清单先例（39 处历史快照冻结），不伪造 plan.md 篡改历史；账本外继续亮红；
+  // 纪律：新欠账禁止入账（入账须变更流程裁决）；账本解析失败按无豁免 fail-safe。
+  const exemptPath = join(authoritySpecDir, 'archive-integrity-exempt.yaml');
+  let exemptNames = new Set();
+  const exemptNotes = [];
+  if (existsSync(exemptPath)) {
+    try {
+      const doc = jsYaml.load(readFileSync(exemptPath, 'utf8'));
+      const entries = Array.isArray(doc && doc.entries) ? doc.entries : [];
+      exemptNames = new Set(entries.filter((e) => e && typeof e.name === 'string').map((e) => e.name));
+    } catch (e) {
+      exemptNotes.push(`豁免账本解析失败（${e?.message || e}）——按无豁免处理，红灯保持`);
+    }
+  }
+  const exempted = offenders.filter((o) => exemptNames.has(o.name));
+  const effective = offenders.filter((o) => !exemptNames.has(o.name));
+  const staleExemptions = [...exemptNames].filter((n) => !offenders.some((o) => o.name === n));
+  if (exempted.length > 0) {
+    exemptNotes.push(`${exempted.length} 份豁免在案（历史形态，账本 archive-integrity-exempt.yaml）`);
+  }
+  if (staleExemptions.length > 0) {
+    exemptNotes.push(`${staleExemptions.length} 条豁免已失效（对应归档不再欠账）可清理：${staleExemptions.slice(0, 5).join(', ')}${staleExemptions.length > 5 ? ' …' : ''}`);
+  }
+
+  if (effective.length === 0) {
+    const findings = [`${names.length} 份归档完整（任务全勾 + plan.md 在场${exempted.length > 0 ? `，另有 ${exempted.length} 份豁免在案` : ''}）`];
+    findings.push(...exemptNotes);
+    return {
+      ...base,
+      pass: true,
+      severity: null,
+      findings,
+      archive_count: names.length,
+      offenders: [],
+      exempted_count: exempted.length,
+      stale_exemptions: staleExemptions,
+    };
+  }
+  const findings = effective.slice(0, 10).map((o) => `${o.name}：${o.reasons.join('；')}`);
+  if (effective.length > 10) findings.push(`…还有 ${effective.length - 10} 份`);
+  findings.push(...exemptNotes);
+  findings.push('语义：归档=全勾终态；未勾/缺文件多为归档后手改或手工搬目录绕流程——git log 定位改动来源，doctor 只读不自动修');
+  return {
+    ...base,
+    pass: false,
+    severity: CHECK_SEVERITY.WARNING,
+    findings,
+    safe_actions: [{ dimension: 'archive_integrity', action: 'manual_inspect', risk: 'manual_edit', rationale: '归档完整性破损', next_step: '逐份核对 offenders：git log --follow .sillyspec/changes/archive/<name>/tasks.md 定位改动者与意图，确属历史遗留走变更流程裁决入豁免账本（新欠账禁止入账），勿改语义' }],
+    archive_count: names.length,
+    offenders: effective,
+    exempted_count: exempted.length,
+    stale_exemptions: staleExemptions,
+  };
+}
+
 /**
  * renderDoctorSummary（FR-01，全新输出契约——2026-09-09-doctor-noai）：逐维
  * ✅/⚠️/❌ + label + findings 首行 + safe_actions 提示行。顶层非 --json 命令与
@@ -1177,7 +1344,9 @@ export async function runDoctorDiagnostics({ cwd }) {
   const applyManifestDrift = detectApplyManifestDrift(cwd, authoritySpecDir)
   // task-02（2026-09-15-tax-governance）：自维护税面（活跃 tally 列示 + 台账聚合 + 税重阈值，只读）
   const selfMaintenanceTax = detectSelfMaintenanceTax(cwd, authoritySpecDir)
-  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, buildEnv, mcpEndpoints, applyManifestDrift, selfMaintenanceTax];
+  // D14（2026-09-17 archive-rescan，OpenSpec validate --archived 对标）：归档完整性事后重扫（只读 WARNING）
+  const archiveIntegrity = detectArchiveIntegrity(cwd, authoritySpecDir)
+  const dimensions = [multiDb, pointerHealth, changesSplit, changeDb, executeMismatch, docBloat, repoNativeChain, lifecycleDoc, worktreeHealth, buildEnv, mcpEndpoints, applyManifestDrift, selfMaintenanceTax, archiveIntegrity];
 
   return {
     dimensions,