@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/check-judgment-drift.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * check-judgment-drift.mjs —— **判断面漂移**门禁（P0 0.1–0.4 的可跑形式；2026-10-03）
+ *
+ * 为什么有它：契约（`core/contracts/argent.contracts.json#judgments`）一旦和代码分家，
+ * "判断留在 CLI 里"就只剩一句口号 —— 而且**两种分家都是坏的**：
+ *   · 契约声明了、代码里没有 ⇒ 宿主按契约调，拿到的是幻觉（假绿）；
+ *   · 代码里实现了、契约没声明 ⇒ 新判断**绕过了清单**，宿主不可能知道它存在（漏报）。
+ * 所以本门禁是**双向**的，且**清单与 token 全部从契约文件读**（门禁里不另写第二份判据，
+ * 否则门禁自己就变成第二个真源 —— 那正是 `scripts/check-sop-consistency.mjs:4-11` 记录过的事故）。
+ *
+ * ## R1 契约↔代码（0 容忍：drift 必须为 0）
+ * | 检查 | 方向 | 判据 |
+ * |---|---|---|
+ * | R1a | 契约 → 代码 | `argent.contracts.json#verbs` 的每个 verb 必须能被 CLI 枚举到（`--help --json`） |
+ * | R1b | 代码 → 契约 | CLI 枚举到的每个 verb / 组内子命令都必须在契约里声明 |
+ * | R1c | 契约 → 代码 | `judgments[*].implementations[*].at` 必须存在，且 anchor 落在 `[行号±ownerSlackLines]` 内 |
+ * | R1d | 代码 → 契约 | anchor 出现在扫描面（`judgmentMeta.scan`）里的**任何未声明文件** ⇒ 漂移 |
+ * | R1e | 契约 → 代码 | A2 适配层（`reasonScanGlobs`）里发出的 reason 短码必须在 `reasonCodes` 里 |
+ * | R1f | 契约自洽 | `argent.contracts.json#verbs` ↔ `verbs.schema.json#verbs` ↔ `scope` 三向逐键对齐 |
+ * | R1g | schema → MCP | `verbs.schema.json` 里标了 `surface:["mcp"]` 的 verb 必须有同名 MCP tool（`argent_<verb>`），反之亦然（P1 第二批加：`argent_preflight` 曾**没有 verb 块** ⇒ 这一向恒绿） |
+ * | R1h | 契约自洽 | 组 verb 的 `subcommands` 必须与 schema 里同名组的 `subcommands` **逐键对齐**（否则子命令可以只写在一边） |
+ *
+ * ⚠️ R1a/R1b 的"代码侧"来自 `core/cli/argent.mjs --help --json`，它报的是**代码里真的实现了**的
+ * verb/子命令（P1 第二批改；此前直接照抄契约 ⇒ 这两向恒绿，属于假绿空间）。
+ *
+ * ## R2 SKILL/提示词**复述**判断（首日允许非零，只 warn；`--strict` 才红）
+ * §P0-A V1 / P0 0.4：判断常量**允许提及、禁止定义**——同一行命中 ≥2 个 `restateTokens`
+ * 且无引用点（`restateScan.citationTokens`）⇒ 记一条。基线见实施方案 §2.3 D5。
+ *
+ * ## 用法与退出码
+ * ```
+ * node scripts/check-judgment-drift.mjs                 # 只报告，**恒 exit 0**
+ * node scripts/check-judgment-drift.mjs --strict        # R1 或 R2 有命中 ⇒ exit 1
+ * node scripts/check-judgment-drift.mjs --strict-contract  # 只有 R1（契约↔代码）有命中才 exit 1
+ * node scripts/check-judgment-drift.mjs --json          # 机器可读
+ * node scripts/check-judgment-drift.mjs --root <dir>    # 换根（夹具自测用；仍然只读）
+ * ```
+ * ## 纪律
+ *   · **只读**：不改文件、不写数据目录/台账、不联网；唯一子进程是 `node <CLI> --help --json`（枚举 verb）。
+ *   · **默认不失败**：形态照 `scripts/check-docs-drift.mjs`（文档漂移常年存在，接进 run-tests 就是恒红陷阱）。
+ *     回归只覆盖 `scripts/tests/judgment-drift.test.mjs` 的**纯夹具**（夹具注入漂移 ⇒ 必红）。
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = resolve(HERE, '..')
+
+// ── 参数 ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined }
+if (has('-h') || has('--help')) {
+  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').trim())
+  process.exit(0)
+}
+const STRICT = has('--strict')
+const STRICT_CONTRACT = has('--strict-contract')
+const AS_JSON = has('--json')
+const ROOT = resolve(val('--root') || SELF_ROOT)
+
+// ── 契约（唯一真源）──────────────────────────────────────────────────────────
+const CONTRACTS_REL = 'core/contracts/argent.contracts.json'
+const SCHEMA_REL = 'core/contracts/verbs.schema.json'
+const CLI_REL = 'core/cli/argent.mjs'
+
+const contractsPath = join(ROOT, CONTRACTS_REL)
+const schemaPath = join(ROOT, SCHEMA_REL)
+
+/** 读文件（失败返回 null，由调用方转成 finding —— 不抛栈）。 */
+function readText(p) {
+  try { return readFileSync(p, 'utf8') } catch { return null }
+}
+
+/** glob → 正则（`*` = 段内任意；`**` = 跨段任意；**`**\/` = 零段或多段**，故 `scripts/**\/*.py` 也匹配
+ * `scripts/flow_case.py`）。与 kernel-purity 的 `.*` 略有差别（那条要求至少一段）—— 本门禁取更宽的语义，
+ * 宁可多扫，也不留"顶层脚本不在扫描面"的假绿空间。 */
+export function globToRe(glob) {
+  const s = String(glob)
+  let re = ''
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i]
+    if (c === '*') {
+      if (s[i + 1] === '*') {
+        if (s[i + 2] === '/') { re += '(?:.*/)?'; i += 2 } else { re += '.*'; i++ }
+      } else re += '[^/]*'
+      continue
+    }
+    if ('\\^$.|?+()[]{}'.includes(c)) { re += `\\${c}`; continue }
+    re += c
+  }
+  return new RegExp(`^${re}$`)
+}
+
+const toPosix = (p) => p.split(sep).join('/')
+
+/** 递归列出 `dir` 下所有文件（仓库相对 POSIX 路径）。 */
+export function walkFiles(dir, base = dir, out = []) {
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    if (e.name === '__pycache__' || e.name === '.git' || e.name === 'node_modules') continue
+    const p = join(dir, e.name)
+    let st = null
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) walkFiles(p, base, out)
+    else if (st.isFile()) out.push(toPosix(relative(base, p)))
+  }
+  return out
+}
+
+/** 按 globs（可带 excludeGlobs）筛出仓库相对文件清单。 */
+export function selectFiles(root, globs, excludeGlobs = []) {
+  const inc = (globs || []).map(globToRe)
+  const exc = (excludeGlobs || []).map(globToRe)
+  const all = walkFiles(root)
+  return all.filter((f) => inc.some((r) => r.test(f)) && !exc.some((r) => r.test(f))).sort()
+}
+
+/** `file:line` → `{file, line}`；不合法 ⇒ null。 */
+export function parseAt(at) {
+  const m = /^(.*):(\d+)$/.exec(String(at || ''))
+  if (!m) return null
+  return { file: m[1], line: Number(m[2]) }
+}
+
+/**
+ * R1：契约↔代码双向漂移（纯函数；`deps` 便于夹具注入）。
+ * @returns {{findings: object[], stats: object}}
+ */
+export function checkContractDrift({ root, contracts, schema, cliVerbs, cliError = null, mcpTools = null, mcpError = null, readFile = (p) => readText(p), files = null }) {
+  const findings = []
+  const push = (rule, message, extra = {}) => findings.push({ rule, message, ...extra })
+  const meta = contracts.judgmentMeta || {}
+  const slack = Number(meta.ownerSlackLines || 0)
+  const scan = meta.scan || { globs: [], excludeGlobs: [] }
+  const scanFiles = files || selectFiles(root, scan.globs, scan.excludeGlobs)
+
+  // ── R1a/R1b：verb 与子命令 ────────────────────────────────────────────────
+  const declared = Object.keys(contracts.verbs || {})
+  if (cliError) {
+    push('R1a', `无法从 CLI 枚举 verb（${CLI_REL} --help --json 失败）：${cliError}`, { at: CLI_REL })
+  } else {
+    for (const v of declared) {
+      if (!cliVerbs.verbs.includes(v)) push('R1a', `契约声明了 verb \`${v}\`，CLI 里没有（假绿：宿主按契约调会拿到幻觉）`, { id: v, at: CLI_REL })
+    }
+    for (const v of cliVerbs.verbs) {
+      if (!declared.includes(v)) push('R1b', `CLI 里有 verb \`${v}\`，契约没声明（漏报：新判断绕过了清单）`, { id: v, at: CLI_REL })
+    }
+    for (const v of declared) {
+      const sub = (contracts.verbs[v] || {}).subcommands
+      if (!sub) continue
+      const actual = (cliVerbs.subcommands || {})[v] || []
+      for (const s of Object.keys(sub)) {
+        if (!actual.includes(s)) push('R1a', `契约声明了 \`${v} ${s}\`，CLI 里没有这个子命令`, { id: `${v} ${s}`, at: CLI_REL })
+      }
+      for (const s of actual) {
+        if (!Object.keys(sub).includes(s)) push('R1b', `CLI 里有子命令 \`${v} ${s}\`，契约没声明`, { id: `${v} ${s}`, at: CLI_REL })
+      }
+    }
+  }
+
+  // ── R1g/R1h：schema ↔ MCP tools、组 verb 的 subcommands 逐键对齐（P1 第二批加）──
+  // R1g：`surface` 标了 mcp 的 verb ⇒ 必须有同名 tool；每个 tool（`argent_<verb>`）⇒ 必须有 verb 块。
+  // `mcpTools === null`（server 文件不在场 / 枚举失败）时**不判红**（夹具根没有 core/mcp/server.mjs；
+  // 真仓库里枚举失败会以 fatal 计 —— 见 run() 的 mcpError 分支）。
+  if (Array.isArray(mcpTools)) {
+    const toolOf = (v) => `argent_${v}`
+    const verbsMcp = Object.entries(schema.verbs || {}).filter(([, v]) => (v.surface || []).includes('mcp')).map(([k]) => k)
+    for (const v of verbsMcp) {
+      if (!mcpTools.includes(toolOf(v))) push('R1g', `schema 的 \`${v}\` 标了 mcp 面，但 MCP server 没有 tool \`${toolOf(v)}\`（标注说谎）`, { id: v, at: 'core/mcp/server.mjs' })
+    }
+    for (const t of mcpTools) {
+      const v = String(t).replace(/^argent_/, '')
+      if (!schema.verbs || !schema.verbs[v]) push('R1g', `MCP tool \`${t}\` 没有对应的 verb 块（**自洽检查会漏**：它绕过了判断面清单）`, { id: v, at: 'core/contracts/verbs.schema.json' })
+    }
+  } else if (mcpError) {
+    push('R1g', `无法枚举 MCP tools（core/mcp/server.mjs tools/list 失败）：${mcpError}`, { at: 'core/mcp/server.mjs' })
+  }
+
+  // R1h：组 verb 的子命令：契约（唯一口径）与 schema（宿主读的那份）必须逐键一致。
+  // 只看**两边都声明了 subcommands** 的 verb —— 契约里没有 `subcommands` 的 verb 不管（它不是组）。
+  // 形状容忍：契约里 `subcommands` 是**对象**（子命令 → 说明），schema 里可以是**数组**（只列名字）。
+  const subNames = (v) => (Array.isArray(v) ? v.map(String) : (v && typeof v === 'object' ? Object.keys(v) : null))
+  for (const [v, c] of Object.entries(contracts.verbs || {})) {
+    const cSubs = c.subcommands ? subNames(c.subcommands) : null
+    if (!cSubs) continue
+    const sSubs = schema.verbs && schema.verbs[v] ? subNames(schema.verbs[v].subcommands) : null
+    if (!sSubs) { push('R1h', `契约的组 verb \`${v}\` 声明了子命令，schema 里却没有 subcommands（宿主读不到子命令清单）`, { id: v }); continue }
+    for (const s of cSubs) if (!sSubs.includes(s)) push('R1h', `契约声明了 \`${v} ${s}\`，schema 的 subcommands 里没有`, { id: `${v} ${s}` })
+    for (const s of sSubs) if (!cSubs.includes(s)) push('R1h', `schema 声明了 \`${v} ${s}\`，契约的 subcommands 里没有`, { id: `${v} ${s}` })
+  }
+
+  // ── R1c/R1d：judgment 实现位置与 anchor ──────────────────────────────────
+  const judgments = contracts.judgments || {}
+  let anchorChecked = 0
+  for (const [key, j] of Object.entries(judgments)) {
+    const impls = j.implementations || []
+    if (!impls.length) push('R1c', `判断 ${key} 没有 implementations（契约必须点名实现位置）`, { id: key })
+    const declaredFiles = new Set()
+    for (const im of impls) {
+      const at = parseAt(im.at)
+      if (!at) { push('R1c', `判断 ${key} 的 at 不是 file:line 形态：${im.at}`, { id: key }); continue }
+      declaredFiles.add(at.file)
+      const text = readFile(join(root, at.file))
+      if (text === null) { push('R1c', `判断 ${key} 的实现文件不存在：${at.file}`, { id: key, at: im.at }); continue }
+      const lines = text.split('\n')
+      if (at.line < 1 || at.line > lines.length) {
+        push('R1c', `判断 ${key} 的行号越界：${im.at}（文件只有 ${lines.length} 行）`, { id: key, at: im.at })
+        continue
+      }
+      anchorChecked++
+      const lo = Math.max(1, at.line - slack)
+      const hi = Math.min(lines.length, at.line + slack)
+      const inWindow = lines.slice(lo - 1, hi).some((l) => l.includes(im.anchor))
+      if (inWindow) continue
+      const foundAt = lines.findIndex((l) => l.includes(im.anchor)) + 1
+      push('R1c', `判断 ${key} 的 anchor 不在声明位置附近：${im.at}（±${slack} 行内没有 ${JSON.stringify(im.anchor)}`
+        + (foundAt ? `；该文件实际在第 ${foundAt} 行` : '；该文件里根本没有这个 anchor') + '）',
+      { id: key, at: im.at, anchor: im.anchor })
+    }
+    if (j.owner && parseAt(j.owner) && impls.length && j.owner !== impls[0].at) {
+      push('R1c', `判断 ${key} 的 owner（${j.owner}）必须等于 implementations[0].at（${impls[0].at}）—— 契约自身不能有两份主实现位置`, { id: key })
+    }
+    const anchors = impls.map((i) => i.anchor).filter(Boolean)
+    for (const f of scanFiles) {
+      if (declaredFiles.has(f)) continue
+      const text = readFile(join(root, f))
+      if (text === null) continue
+      for (const a of anchors) {
+        if (text.includes(a)) {
+          push('R1d', `扫描面里出现未声明的实现位置：${f} 含判断 ${key} 的 anchor ${JSON.stringify(a)}`
+            + '（要么把它写进 judgments 的 implementations，要么把 anchor 改精确）', { id: key, file: f, anchor: a })
+          break
+        }
+      }
+    }
+  }
+
+  // ── R1e：reason 短码词表 ────────────────────────────────────────────────
+  const codes = new Set(Object.keys(contracts.reasonCodes || {}).filter((k) => !k.startsWith('_')))
+  for (const f of (meta.reasonScanGlobs || [])) {
+    const text = readFile(join(root, f))
+    if (text === null) { push('R1e', `reasonScanGlobs 里的文件不存在：${f}`, { at: f }); continue }
+    for (const m of text.matchAll(/reason:\s*'([a-z][a-z0-9_]*)'/g)) {
+      if (!codes.has(m[1])) push('R1e', `${f} 发出的 reason 短码 ${JSON.stringify(m[1])} 不在契约 reasonCodes 里（宿主无法分支）`, { file: f, anchor: m[1] })
+    }
+  }
+
+  return {
+    findings,
+    stats: { verbs: declared.length, cliVerbs: (cliVerbs && cliVerbs.verbs || []).length, judgments: Object.keys(judgments).length, anchors: anchorChecked, scanFiles: scanFiles.length },
+  }
+}
+
+/**
+ * R2：SKILL/提示词复述判断常量（只 warn）。
+ * 判据 = 一行命中 ≥2 个 restateTokens 且该行**无引用点**。
+ */
+export function checkRestatement({ root, contracts, readFile = (p) => readText(p), files = null }) {
+  const meta = contracts.judgmentMeta || {}
+  const rs = meta.restateScan || { globs: [], excludeGlobs: [], citationTokens: [] }
+  const tokens = []
+  for (const [key, j] of Object.entries(contracts.judgments || {})) {
+    for (const t of j.restateTokens || []) tokens.push({ token: t, judgment: key })
+  }
+  const scanFiles = files || selectFiles(root, rs.globs, rs.excludeGlobs)
+  const minTokens = Number(rs.minTokens || 2)      // 阈值也是契约数据（不写死在门禁里）
+  const out = []
+  if (!tokens.length) return { findings: out, stats: { files: scanFiles.length, tokens: 0 } }
+  for (const f of scanFiles) {
+    const text = readFile(join(root, f))
+    if (text === null) continue
+    text.split('\n').forEach((line, i) => {
+      const hit = [...new Set(tokens.filter((t) => line.includes(t.token)).map((t) => t.token))]
+      if (hit.length < minTokens) return
+      if ((rs.citationTokens || []).some((c) => line.includes(c))) return
+      out.push({ rule: 'R2', file: f, line: i + 1, tokens: hit, text: line.trim().slice(0, 160) })
+    })
+  }
+  return { findings: out, stats: { files: scanFiles.length, tokens: tokens.length } }
+}
+
+/**
+ * 枚举 MCP server 里**实际存在**的 tools（`tools/list`）。
+ * 与 `cliVerbsOf` 对称：门禁的"MCP 侧"来源必须是被检对象自己报的，而不是契约抄一遍。
+ * @returns {{ok:boolean, tools?:string[], skipped?:boolean, error?:string}}
+ *   `skipped` = `core/mcp/server.mjs` 不在场（夹具根）⇒ 这一向不判（**不是**放行真仓库：真仓库里它必须在场）
+ */
+export function mcpToolsOf(root) {
+  const server = join(root, 'core', 'mcp', 'server.mjs')
+  if (!existsSync(server)) return { ok: false, skipped: true }
+  try {
+    const input = [
+      JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05' } }),
+      JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
+      '',
+    ].join('\n')
+    const out = execFileSync(process.execPath, [server], { encoding: 'utf8', input, timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'] })
+    for (const line of String(out).split('\n')) {
+      const s = line.trim()
+      if (!s) continue
+      let m = null
+      try { m = JSON.parse(s) } catch { continue }
+      if (m && m.id === 2) {
+        const tools = m.result && Array.isArray(m.result.tools) ? m.result.tools.map((t) => String(t.name)) : null
+        if (tools) return { ok: true, tools }
+        if (m.error) return { ok: false, error: String(m.error.message || JSON.stringify(m.error)).slice(0, 200) }
+      }
+    }
+    return { ok: false, error: 'tools/list 没有返回 tools 数组' }
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e).slice(0, 200) }
+  }
+}
+
+/** 枚举 CLI 里**实际存在**的 verb（`--help --json`；失败退化为文本解析）。 */
+export function cliVerbsOf(root) {
+  const cli = join(root, CLI_REL)
+  if (!existsSync(cli)) return { ok: false, error: `${CLI_REL} 不存在` }
+  try {
+    const out = execFileSync(process.execPath, [cli, '--help', '--json'], { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const doc = JSON.parse(out.slice(out.indexOf('{')))
+    return { ok: true, verbs: (doc.verbs || []).map((v) => v.name), subcommands: Object.fromEntries((doc.verbs || []).filter((v) => v.subcommands).map((v) => [v.name, v.subcommands])) }
+  } catch (e) {
+    // 退化为文本解析（老版本 CLI 没有 --help --json）：这是**兼容**，不是第二份判据（verb 仍由 CLI 自己报）
+    try {
+      const out = execFileSync(process.execPath, [cli, '--help'], { encoding: 'utf8', timeout: 30000 })
+      return { ok: true, verbs: [...out.matchAll(/^ {2}([a-z][a-z-]*)\s/gm)].map((m) => m[1]), subcommands: {} }
+    } catch (e2) {
+      return { ok: false, error: String((e2 && e2.message) || e.message) }
+    }
+  }
+}
+
+// ── 主流程 ──────────────────────────────────────────────────────────────────
+export function run({ root = ROOT, strict = STRICT, strictContract = STRICT_CONTRACT } = {}) {
+  const contractsText = readText(join(root, CONTRACTS_REL))
+  const schemaText = readText(join(root, SCHEMA_REL))
+  if (contractsText === null || schemaText === null) {
+    return { ok: false, fatal: `契约文件缺失：${contractsText === null ? CONTRACTS_REL : SCHEMA_REL}`, drift: [], restate: [], stats: {} }
+  }
+  const contracts = JSON.parse(contractsText)
+  const schema = JSON.parse(schemaText)
+
+  // 契约自身自洽（这也是"契约有代码没有"的一类：schema 与 contracts 必须逐键对齐）
+  const selfFindings = []
+  const cVerbs = Object.keys(contracts.verbs || {})
+  const sVerbs = Object.keys(schema.verbs || {})
+  for (const v of cVerbs) if (!sVerbs.includes(v)) selfFindings.push({ rule: 'R1f', message: `argent.contracts.json 声明了 \`${v}\`，verbs.schema.json 里没有`, id: v })
+  for (const v of sVerbs) {
+    const isCli = ((schema.verbs[v] || {}).surface || []).includes('cli')
+    if (isCli && !cVerbs.includes(v)) selfFindings.push({ rule: 'R1f', message: `verbs.schema.json 的 \`${v}\` 标了 cli 面，argent.contracts.json 里没有`, id: v })
+  }
+  const scopeAll = [...((schema.scope || {}).local || []), ...((schema.scope || {}).account || [])]
+  for (const v of sVerbs) if (!scopeAll.includes(v)) selfFindings.push({ rule: 'R1f', message: `verbs.schema.json 的 \`${v}\` 没有 scope 归属`, id: v })
+  for (const v of scopeAll) if (!sVerbs.includes(v)) selfFindings.push({ rule: 'R1f', message: `scope 表里的 \`${v}\` 不是 schema 里的 verb`, id: v })
+
+  const cli = cliVerbsOf(root)
+  const cliVerbs = cli.ok ? { verbs: cli.verbs, subcommands: cli.subcommands } : { verbs: [], subcommands: {} }
+  const mcp = mcpToolsOf(root)
+  const r1 = checkContractDrift({
+    root, contracts, schema, cliVerbs, cliError: cli.ok ? null : cli.error,
+    mcpTools: mcp.ok ? mcp.tools : null,
+    mcpError: mcp.skipped || mcp.ok ? null : (mcp.error || '未知错误'),
+  })
+  const r2 = checkRestatement({ root, contracts })
+  const drift = [...selfFindings, ...r1.findings]
+  return {
+    ok: drift.length === 0,
+    drift,
+    restate: r2.findings,
+    stats: { ...r1.stats, mcpTools: mcp.ok ? mcp.tools.length : 0, restateFiles: r2.stats.files, restateTokens: r2.stats.tokens },
+    strict, strictContract,
+  }
+}
+
+if (isDirectRun(import.meta.url)) {
+  const res = run()
+  if (AS_JSON) console.log(JSON.stringify(res, null, 2))
+  else {
+    console.log('\n【R1 契约 ↔ 代码（双向；0 容忍）】')
+    if (res.fatal) console.log(`  ❌ ${res.fatal}`)
+    else if (!res.drift.length) console.log('  ✅ 漂移 0 条'
+      + `（verb ${res.stats.verbs} 个 / CLI 实报 ${res.stats.cliVerbs} 个 / MCP tools ${res.stats.mcpTools} 个 ｜ judgment ${res.stats.judgments} 条 / anchor ${res.stats.anchors} 处 ｜ 扫描面 ${res.stats.scanFiles} 文件）`)
+    else for (const f of res.drift) console.log(`  ❌ [${f.rule}] ${f.message}`)
+    console.log('\n【R2 SKILL/提示词复述判断（首日基线；--strict 才红）】')
+    if (!res.restate.length) console.log(`  ✅ 复述告警 0 条（扫 ${res.stats.restateFiles} 文件 / ${res.stats.restateTokens} token）`)
+    else {
+      console.log(`  ⚠️ 复述告警 ${res.restate.length} 条（扫 ${res.stats.restateFiles} 文件）—— 命中判断常量却无引用点：`)
+      for (const f of res.restate.slice(0, 40)) console.log(`     · ${f.file}:${f.line} [${f.tokens.join(' + ')}] ${f.text}`)
+      if (res.restate.length > 40) console.log(`     …（其余 ${res.restate.length - 40} 条省略；--json 看全量）`)
+    }
+    console.log(`\n  结论：契约漂移 ${res.drift.length} 条 ｜ 复述告警 ${res.restate.length} 条`
+      + `${res.strict || res.strictContract ? '' : '（默认只报告 ⇒ exit 0）'}`)
+  }
+  const fail = res.fatal ? true : (STRICT ? (res.drift.length + res.restate.length) > 0 : (STRICT_CONTRACT ? res.drift.length > 0 : false))
+  process.exit(fail ? 1 : 0)
+}

package/engine/scripts/check-license.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * check-license —— 离线许可状态**只读**自检（2026-09-30）
+ *
+ * 用途：客户机上不登录问述账号也能回答四个问题 ——
+ *   ① 这份许可**是不是我们签的**（验签）；② 买了哪些能力/业务线；③ 什么时候到期、是否已在宽限期；
+ *   ④ **这条流程/这个能力现在许不许跑**（`--cap` / `--vertical`，供 flow-trigger 的许可闸门判定）。
+ * 不写任何文件、不联网（断网/无账号令牌都能跑）。
+ *
+ * 用法：
+ *   node scripts/check-license.mjs [--file <path>] [--cap <id>]… [--vertical <id>] [--now <ISO>] [--json]
+ * 缺省文件：`$ARGENT_DATA_DIR/license.json`（未设则 `~/.dsh/argent/license.json`）。
+ * 密钥来源：`ARGENT_LICENSE_SECRET` 或 `~/.dsh/argent/license.secret`（600）——都没有 ⇒ 明确报 no_secret。
+ *
+ * 退出码（与 scripts/lease.py 同一套口径，便于流程里 `&&` 串联）：
+ *   0 允许（验签通过且在有效期内，且 `--cap`/`--vertical` 都命中）
+ *   3 宽限（已过期但在宽限期内 ⇒ 放行但必须告警；能力判定此时仍算命中）
+ *   1 拒绝（缺失/坏签名/超期/无密钥/**能力或业务线未授权**）
+ *   2 用法错误
+ *
+ * ⚠️ 与旧版的唯一语义差别：给了 `--cap` 时，**能力未授权 ⇒ exit 1**（此前只看许可整体有效性）。
+ *    不给 `--cap` 时行为逐字不变。消费方请一律解析 `--json` 的字段，**不要 grep 中文**。
+ */
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defaultLicensePath, defaultSecretPath, capabilityAllowed } from '../core/lib/license-file.mjs'
+import { licenseVerdict, stateOf } from '../core/lib/license-verdict.mjs'
+
+/**
+ * 取参数（可重复的参数用 `allOf`）。
+ * 未知 `--xxx` 一律忽略（历史行为；`--cap` 未识别时也不能把别人带的参数当值吃掉）。
+ */
+const allOf = (name) => {
+  const out = []
+  process.argv.forEach((a, i) => { if (a === name) out.push(process.argv[i + 1]) })
+  return out.filter((v) => v !== undefined && v !== null && v !== '')
+}
+const argOf = (name, dflt = null) => {
+  const i = process.argv.indexOf(name)
+  return i > -1 ? process.argv[i + 1] ?? dflt : dflt
+}
+const die = (m) => { console.error(`✗ ${m}`); process.exit(2) }
+const parseNow = (s) => {
+  if (s === null || s === undefined || s === '') return null
+  const t = Date.parse(String(s))
+  return Number.isFinite(t) ? t : NaN
+}
+
+/**
+ * 三态归一 —— **实现已搬到 `core/lib/license-verdict.mjs`**（唯一判定入口：验签 + 到期 + **设备绑定**）。
+ * 本文件只把它**再导出**：既有消费方（`scripts/tests/license-gate.test.mjs` 等）继续按老路径 import，
+ * 但**判据只有一份**（§3.5① 纪律 1：判定点唯一，不许在脚本里再写一遍三态）。
+ */
+export { stateOf }
+
+function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log('用法：node scripts/check-license.mjs [--file <path>] [--cap <id>]… [--vertical <id>] [--now <ISO>] [--json]')
+    console.log('退出码：0 有效/允许 ｜ 3 宽限 ｜ 1 拒绝（含能力未授权、设备不匹配超宽限） ｜ 2 用法错误')
+    process.exit(0)
+  }
+
+  const nowArg = parseNow(argOf('--now'))
+  if (Number.isNaN(nowArg)) die(`--now 不是可解析的时间：${argOf('--now')}`)
+
+  const file = argOf('--file') ? resolve(argOf('--file')) : defaultLicensePath()
+  const asJson = process.argv.includes('--json')
+  const caps = allOf('--cap')
+  const vertical = argOf('--vertical')
+  const now = nowArg === null ? Date.now() : nowArg
+
+  // 唯一判定入口（三态 + 设备绑定；`signatureVersion`/`device.signed` 由验签结果带出，本脚本不重算）
+  const r = licenseVerdict({ file, now })
+  const granted = r.capabilities.map((c) => [c, capabilityAllowed(r, c, { now })])
+  const capGrants = Object.fromEntries(granted)
+  const capsOk = caps.every((c) => capabilityAllowed(r, c, { now }))
+  const verticals = Array.isArray(r.verticals) ? r.verticals.map(String) : []
+  // 业务线口径与能力**不同**（见 license-file.mjs 头注释）：verticals 空 = 不限业务线。
+  const verticalOk = !vertical || verticals.length === 0 || verticals.includes(String(vertical))
+  // 设备这一侧已经进 `r.ok`（grace 放行 / denied 拒绝）⇒ allowed 必须带上它，否则"设备已拒绝"会被能力门洗白
+  const allowed = r.ok === true && capsOk && verticalOk
+  const gateReason = allowed ? null
+    : (r.ok !== true
+      // 许可/设备这一侧拒绝：把**自解释的设备 reason**（device_mismatch / rebind_exhausted）透出去。
+      // ⚠️ 只在**许可本身验签通过**（`baseOk`）时才让设备原因当顶层 reason —— 否则"这份文件根本没验过签"
+      //    会被"设备不匹配"盖住（v2 起尤其要紧：改 `device` 会被判 bad_signature，报设备不匹配 = 误导）。
+      ? (r.device && r.device.state === 'denied' && r.device.binding === 'mismatch' && r.baseOk === true ? r.device.reason : null)
+      : (capsOk ? 'vertical_not_allowed' : 'cap_not_allowed'))
+
+  const exitCode = allowed ? (r.inGrace ? 3 : 0) : 1
+
+  // 人类可读的结论（--json 时也打一份，方便日志里直接看到判据）
+  const reasonText = {
+    ok: '验签通过（有效期内）',
+    in_grace: '验签通过，但**已过期**（宽限期内 ⇒ 放行，请尽快续期）',
+    missing: `许可文件不存在：${file}`,
+    unreadable: '许可文件读不出来',
+    malformed: '许可文件不是合法的许可 JSON（字段缺失或时间不可解析）',
+    bad_version: '许可版本不支持（本客户端只认 v1/v2）',
+    bad_signature: '**验签失败**：文件被改动过，或者不是本机该用的密钥（拒绝）',
+    expired: '许可已过期且超出宽限期（拒绝）',
+    no_secret: `本机没有签名密钥：设置 ARGENT_LICENSE_SECRET，或放入 ${defaultSecretPath()}（600）`,
+  }[r.reason] || r.reason
+  // 设备这一项到底有没有进签名：文案按**签名版本**动态化（v2 不再说"未进签名"）
+  const deviceSignedText = (() => {
+    const dev = r.device || {}
+    if (r.signatureVersion === 2) {
+      return dev.present
+        ? '签名版本 **v2**：`device` **已进签名**（载荷 10 项，含 device{code,algo,issuedAt}）'
+          + ' ⇒ 改它/摘它/降 v 重拼都会验签失败；⚠️ 签名仍是 HMAC（对称密钥）⇒ 不防"持有密钥的人重签"'
+        : '签名版本 **v2**：本许可**未声明**设备（unbound）—— **缺位也被签名覆盖**（事后加 `device` 会验签失败）⇒ 不做比对、放行'
+    }
+    return '`device` **未进签名**（v1 只签 9 项）⇒ 它是“服务端声明 + 客户端比对”，不是防伪'
+  })()
+  const gateText = {
+    cap_not_allowed: `许可里没有这个能力（要 ${caps.join(',')}，许可只有 ${r.capabilities.join(',') || '（空）'}）⇒ 拒绝`,
+    vertical_not_allowed: `许可不含业务线 ${vertical}（许可业务线：${verticals.join(',') || '（空=不限）'}）⇒ 拒绝`,
+    // 设备不匹配的两种拒绝形态：把 `device.note`（含"下一步做什么"）原样透出，不另写一套文案
+    device_mismatch: r.device ? r.device.note : null,
+    rebind_exhausted: r.device ? r.device.note : null,
+  }[gateReason] || null
+
+  const out = {
+    ok: allowed,
+    state: r.state,
+    reason: r.reason,
+    conclusion: [reasonText, gateText].filter(Boolean).join(' ｜ '),
+    path: file,
+    mode: r.mode === null || r.mode === undefined ? null : `0${r.mode.toString(8)}`,
+    userId: r.userId,
+    capabilities: r.capabilities,
+    verticals: r.verticals,
+    seats: r.seats,
+    issuedAt: r.issuedAt,
+    expiresAt: r.expiresAt,
+    graceDays: r.graceDays,
+    graceUntil: r.graceUntil,
+    inGrace: r.inGrace,
+    // 宽限来自哪一侧（`expiry` 许可到期 ｜ `device` 设备不匹配 ｜ `expiry+device` 两侧都命中）——
+    // 空/异常结果必须能一眼分出"真没有"与"被别的判据盖住"（A2 的回显纪律）
+    graceSource: r.graceSource,
+    // ── 签名版本（1｜2｜null）+ 设备是否进签名（v1 ⇒ signed:false；v2 ⇒ signed:true）──
+    signatureVersion: r.signatureVersion === 2 ? 2 : (r.signatureVersion === 1 ? 1 : null),
+    deviceSigned: r.deviceSigned === true,
+    signature: {
+      version: r.signatureVersion === 2 ? 2 : (r.signatureVersion === 1 ? 1 : null),
+      // 验签本身的结论（ok/in_grace/bad_signature/expired/malformed/bad_version/no_secret/…）
+      reason: r.reason,
+      // `device` 这一项是否被签名载荷覆盖（**只有 v2 ∧ 验签通过**才为 true，见 license-file.mjs 头注释）
+      deviceSigned: r.deviceSigned === true,
+      algorithm: 'HMAC-SHA256',
+    },
+    // ── 设备绑定（§3.6；`device.signed:true` = v2 已进签名；`false` = v1 未进签名：服务端声明 + 客户端比对）──
+    device: r.device,
+    // ── 请求侧（闸门判定）──────────────────────────────────────────
+    requestedCaps: caps,
+    requestedVertical: vertical || null,
+    // 有效 = 验签过 ∧ 设备这一侧放行 ∧ 请求的能力都授权 ∧ 业务线匹配（没请求就只看许可本身）
+    allowed,
+    gateReason,
+    // 能力门禁的可用形态：`--json` 的消费方（脚本/宿主）可以直接照此判
+    capabilityGate: capGrants,
+    warnings: r.warnings,
+  }
+  if (asJson) {
+    console.log(JSON.stringify(out, null, 2))
+  } else {
+    const mark = allowed ? (r.inGrace ? '⚠️' : '✅') : '❌'
+    const graceFrom = { expiry: '到期', device: '设备不匹配', 'expiry+device': '到期 + 设备不匹配' }[r.graceSource]
+    console.log(`${mark} 离线许可：${reasonText}${graceFrom ? `（宽限来自：${graceFrom}）` : ''}`)
+    console.log(`   文件：${file}${out.mode ? `（权限 ${out.mode}${out.mode === '0600' ? '' : ' ⚠️ 建议 600'}）` : ''}`)
+    console.log(`   签名版本：${out.signatureVersion === null ? '判不出（缺文件/缺密钥/坏文件 ⇒ 见上面的 reason）' : `v${out.signatureVersion}`}`
+      + ` ｜ device 进签名：${out.signature.deviceSigned ? '是' : '否'}`)
+    if (r.expiresAt) {
+      console.log(`   账号：${r.userId || '(未写)'} ｜ 席位：${r.seats}`)
+      console.log(`   能力：${r.capabilities.join(',') || '(未列能力 ⇒ 客户端拒一切能力)'}`)
+      console.log(`   业务线：${r.verticals.join(',') || '(空 = 不限)'}`)
+      console.log(`   签发：${r.issuedAt} ｜ 到期：${r.expiresAt} ｜ 宽限 ${r.graceDays} 天（至 ${r.graceUntil}）`)
+    }
+    if (r.device) {
+      console.log(`   设备绑定：${r.device.binding}（${r.device.reason}）`
+        + `${r.device.present ? ` ｜ 许可设备码 ${String(r.device.code).slice(0, 12)}…` : ''}`
+        + `${r.device.machineCode ? ` ｜ 本机设备码 ${r.device.machineCode.slice(0, 12)}…` : ''}`
+        + ` ｜ 自助重绑还剩 ${r.device.rebindsLeft} 次`)
+      console.log(`     ${deviceSignedText}`)
+      if (r.device.note) console.log(`     · ${r.device.note}`)
+    }
+    if (caps.length || vertical) {
+      console.log(`   本次询问：能力=${caps.join(',') || '(未指定)'} ｜ 业务线=${vertical || '(未指定)'}`)
+      console.log(`   判定：${allowed ? '允许' : '拒绝'}${gateText ? `（${gateText}）` : ''}`)
+    }
+    for (const w of r.warnings) console.log(`   ⚠️ ${w}`)
+  }
+  process.exit(exitCode)
+}
+
+// 只在**直接运行**时执行：被 import（回归测试要用 stateOf）时不得产生副作用
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) main()
+