dsh-vibe-math 2.7.3 → 2.8.0

package/tests/audit-persona-surface.test.mjs

@@ -1,431 +1,431 @@
-#!/usr/bin/env node
-/**
- * PERSONA SURFACE — prompt/allocation consistency for the four presets.
- *
- * DEFECT CLASS (why this guard exists; it belongs to the dual-persona-block parity family of §3)
- *   "capability advertised but never granted, or granted but never advertised": the persona block is
- *   the main agent view of the tool surface, so a registered-but-unnamed tool is invisible and a
- *   named-but-unregistered tool is a trap. Every other suite calls apply(ctx) directly and never
- *   parses the YAML, so this class cannot fail anywhere else.
- *
- * Run: node tests/audit-persona-surface.test.mjs
- *
- * WHY THIS EXISTS
- *   The persona row of each `agent.cordis.yml` is the prompt the MAIN agent actually
- *   receives, and it is the only place the main agent learns which `vibe_*` tools exist
- *   and which parameters it may tune. Two failure modes are invisible to every other
- *   suite, because those suites call `apply(ctx)` directly and never load the YAML:
- *
- *     1. a tool is registered but never named in the persona  → the agent does not know
- *        the capability exists (it cannot even guess the exact name);
- *     2. the persona names a tool that is NOT registered       → the agent calls a tool
- *        that will fail, and (in the worst case) is told to rely on it.
- *
- *   The Lean formal-verification feature shipped with exactly this bug in three of four
- *   presets: the three `*_lean_*` tools were registered unconditionally but the v2/v3/v4
- *   personas never listed them (v5's did), and v4's `vibe_v4_set` parameter list omitted
- *   `formalVerify`/`leanCommand`/`leanArgs`/`leanTimeoutMs`, so the coordinator could not
- *   discover the switch at all. Nothing in the build noticed. Hence this guard.
- *
- * INVARIANTS (per preset)
- *   A. the persona row carries both `prefix` and `text` literal blocks, and both parse
- *      into a non-empty body (both keys are required for DSH schema/back-compat);
- *   B. the two blocks are IDENTICAL apart from their first line — an old host that uses
- *      `text` must not receive a different tool surface from a new host that uses `prefix`;
- *   C. mentions ⊆ registered: every `vibe_*` token in the persona is a registered tool
- *      (a `name*` mention is allowed when some registered tool carries that prefix);
- *   D. every registered tool is either MENTIONED in the persona or consciously ALLOW-LISTED, and the
- *      allow-list is itself validated (real tools only, empty by default) — so adding a tool forcing a
- *      decision: name it, or add it to the list with a reason. (Earlier this was a snapshot equality,
- *      which went red whenever a legitimately newly-named tool emptied the "undocumented" set.)
- *      without documenting it (or deleting a tool the persona still advertises) fails
- *      loudly and forces the author to make a decision;
- *   E. the parameter surface of the Lean feature (the four names) and its semantics
- *      (three modes, the fidelity switch, the project/global paths) appear in BOTH blocks.
- *
- * The snapshots below are the reviewed answer to "is this tool intentionally absent from
- * the coordinator's persona?" — virtually all of them are `(member)` / `(academician)` /
- * `(resident)` tools that only subagents call.
- */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs'
-import { join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const ROOT = fileURLToPath(new URL('../', import.meta.url))
-/**
- * `PERSONA_ROOT` points the preset lookup at a prepared copy. It exists so that
- * `audit-persona-sensitivity.mjs` can prove this suite is not vacuous: each probe mutates a
- * copy of one persona (or one plugin) and requires this suite to go RED. Without the
- * override the mutation would never be loaded and every probe would be a false green.
- * `docs/formal-verification.md` is always read from the repository root, because the
- * shared contract is not part of a preset copy.
- */
-const BASE = process.env.PERSONA_ROOT ? resolve(process.env.PERSONA_ROOT) : ROOT
-
-let passed = 0
-let failed = 0
-const failures = []
-function ok(cond, msg) {
-  if (cond) { passed++; return true }
-  failed++
-  failures.push(msg)
-  return false
-}
-function eq(actual, expected, msg) {
-  const a = JSON.stringify(actual)
-  const e = JSON.stringify(expected)
-  return ok(a === e, `${msg}\n      expected: ${e}\n      actual:   ${a}`)
-}
-
-/**
- * Extract a YAML literal block scalar (`prefix: |-`) by indentation. Deliberately does
- * not depend on a YAML library: this file must run inside the published package, where
- * only the DSH host (not this repo) has one. The block's own indentation is stripped so
- * the `prefix` and `text` bodies can be compared line by line.
- */
-function literalBlocks(yml) {
-  const out = {}
-  const lines = yml.split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const m = /^(\s*)([A-Za-z_][\w-]*):\s*\|-?\s*$/.exec(lines[i])
-    if (!m) continue
-    const ind = m[1].length
-    const body = []
-    for (let j = i + 1; j < lines.length; j++) {
-      const L = lines[j]
-      if (L.trim() === '') { body.push(''); continue }
-      const li = L.length - L.trimStart().length
-      if (li <= ind) break
-      body.push(L.slice(ind + 2))
-    }
-    out[m[2]] = body
-  }
-  return out
-}
-
-/**
- * The slice of a plugin that describes and implements its `/vN` slash command: the
- * `commands.register({...})` block, plus — for v2/v3, which dispatch through a named function —
- * the `dispatchVibeCommand` body (that is where their branch list and usage string live).
- * The anchor includes the `{` on purpose: the files also mention `commands.register()` in a
- * prose comment *before* the real call, and anchoring on the call's object literal skips it.
- */
-function commandRegion(src) {
-  const i = src.indexOf('commands.register({')
-  if (i < 0) return null
-  const end = src.indexOf('\n  }))', i)
-  let region = src.slice(i, end > i ? end : Math.min(src.length, i + 8000))
-  if (!/cmd\s*===\s*'/.test(region)) {
-    const d = src.indexOf('dispatchVibeCommand(cmd, args)')
-    if (d >= 0) {
-      const dEnd = src.indexOf('\n  }', d)
-      region += '\n' + src.slice(d, dEnd > d ? dEnd : d + 8000)
-    }
-  }
-  return region
-}
-
-/** Split a `a|b <x|y>|c` advertised list into bare subcommand names. */
-function cmdsFrom(list) {
-  const out = []
-  const bare = String(list).replace(/\[[^\]]*\]/g, ' ').replace(/<[^>]*>/g, ' ')
-  for (const tok of bare.split('|')) {
-    const t = tok.trim()
-    if (!t || t === '...') continue
-    const name = t.split(/\s+/)[0]
-    if (/^[a-z][a-z0-9-]*$/.test(name)) out.push(name)
-  }
-  return out
-}
-
-const PRESETS = [
-  {
-    dir: 'vibe-math-v2',
-    js: 'vibe-math-v2.js',
-    prefix: 'vibe_math_',
-    tools: 28,
-    // D. registered \ mentioned ⊆ allow-list: EVERY registered tool must be mentioned in the persona,
-    // unless its name is listed here as a conscious exception (the allow-list is empty by default, so a
-    // newly registered tool cannot slip in unnamed). An entry must be a REAL registered tool, and a
-    // preset may also pin names that must be mentioned (never allow-listed).
-    allowList: [],
-    required: [],
-    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib', 'vibe_math_lean_read', 'vibe_math_lean_job'], extra: [] },
-    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
-    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
-    math: { tools: ['math_computation'] },
-  },
-  {
-    dir: 'vibe-math-v3',
-    js: 'vibe-math-v3.js',
-    prefix: 'vibe_math_',
-    tools: 36,
-    // `vibe_math_sync_meta` is named by the promotion-contract line, and the write-lock pair is now
-    // named too (the lock is described in the persona, so leaving the two tools unmentioned was the
-    // last hole). Both stay REQUIRED: they must be mentioned, never allow-listed.
-    allowList: [],
-    required: ['vibe_math_claim_write', 'vibe_math_release_write'],
-    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib', 'vibe_math_lean_read', 'vibe_math_lean_job'], extra: [] },
-    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
-    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
-    math: { tools: ['math_computation'] },
-  },
-  {
-    dir: 'vibe-math-v4',
-    js: 'vibe-math-v4.js',
-    prefix: 'vibe_v4_',
-    tools: 35,
-    // Member-facing tools (mail, library cards, task board, write lock) that the v4 persona describes
-    // GENERICALLY rather than naming one by one; the coordinator drives residents through
-    // vibe_v4_message / _meeting / _add_member. Allow-listed ON PURPOSE, so a NEWLY registered tool
-    // still has to be named (or added here consciously).
-    allowList: [
-      'vibe_v4_send_message', 'vibe_v4_publish_progress', 'vibe_v4_record_proposition',
-      'vibe_v4_record_method', 'vibe_v4_record_subproblem', 'vibe_v4_read_progress',
-      'vibe_v4_list_residents', 'vibe_v4_propose_task', 'vibe_v4_claim_task',
-      'vibe_v4_task_done', 'vibe_v4_list_tasks', 'vibe_v4_report_context',
-      'vibe_v4_claim_write', 'vibe_v4_release_write',
-    ],
-    required: [],
-    lean: { tools: ['vibe_v4_lean_run', 'vibe_v4_lean_archive', 'vibe_v4_lean_lib', 'vibe_v4_lean_read', 'vibe_v4_lean_job'], extra: ['vibe_v4_formal_report'] },
-    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
-    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
-    math: { tools: ['math_computation'] },
-  },
-  {
-    dir: 'vibe-math-v5',
-    js: 'vibe-math-v5.js',
-    prefix: 'vibe_v5_',
-    tools: 40,
-    // Member- and academician-facing tools that the v5 persona describes GENERICALLY; the office (main
-    // agent) holds only the institute-level controls plus the hiring authority. The final-paper pair is
-    // an OFFICE control and IS named in the persona (vibe_v5_paper / vibe_v5_finalize_paper), so it must
-    // NOT be allow-listed here. Allow-listed ON PURPOSE: a NEWLY registered tool still has to be named.
-    allowList: [
-      'vibe_v5_wait', 'vibe_v5_record_progress', 'vibe_v5_record_proposition',
-      'vibe_v5_record_method', 'vibe_v5_record_subproblem', 'vibe_v5_read_library',
-      'vibe_v5_propose_verify', 'vibe_v5_verdict', 'vibe_v5_task_create',
-      'vibe_v5_task_list', 'vibe_v5_task_get', 'vibe_v5_task_update',
-      'vibe_v5_overview', 'vibe_v5_assign', 'vibe_v5_prioritize', 'vibe_v5_nudge',
-    ],
-    required: [],
-    lean: { tools: ['vibe_v5_lean_run', 'vibe_v5_lean_archive', 'vibe_v5_lean_lib', 'vibe_v5_lean_read', 'vibe_v5_lean_job'], extra: [] },
-    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
-    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
-    math: { tools: ['math_computation'] },
-  },
-]
-
-const LEAN_PARAMS = ['formalVerify', 'leanCommand', 'leanArgs', 'leanTimeoutMs', 'leanAsync', 'leanJobsMaxParallel', 'leanInitiative', 'leanSearchPaths']
-
-for (const P of PRESETS) {
-  const ymlPath = join(BASE, P.dir, 'agent.cordis.yml')
-  const jsPath = join(BASE, P.dir, P.js)
-  const yml = readFileSync(ymlPath, 'utf8')
-  const src = readFileSync(jsPath, 'utf8')
-
-  // ---- registered tools -------------------------------------------------
-  // Two registration shapes exist now:
-  //   1. a literal `registerTool('<name>', …)` (most tools, including the shared math tool in
-  //      v2/v3, which register it by its frozen prefix-less name);
-  //   2. the shared math tool in v4/v5, where the plugin only wires a host callback and the module
-  //      calls `host.register(MATH_TOOL_NAME, …)`. The module's name is FROZEN
-  //      (MATH_TOOL_NAME = 'math_computation', INTERFACE-FREEZE.md §3), so a source that wires
-  //      `registerMathComputation(` contributes exactly that one tool. Without this the shared tool
-  //      would be invisible to this guard on v4/v5 - a silent coverage hole.
-  const registered = new Set()
-  for (const m of src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)) registered.add(m[1])
-  if (/registerMathComputation\s*\(/.test(src)) registered.add('math_computation')
-  eq(registered.size, P.tools, `${P.dir}: registered tool count changed (update this snapshot deliberately)`)
-  for (const tool of (P.math ? P.math.tools : [])) ok(registered.has(tool), `${P.dir}: the shared math tool ${tool} is not registered`)
-
-  // ---- A. both literal blocks exist and are non-empty -------------------
-  const blocks = literalBlocks(yml)
-  const hasPersona = /^\s*-\s*id:\s*persona\s*$/m.test(yml)
-  ok(hasPersona, `${P.dir}: no persona row in agent.cordis.yml`)
-  for (const key of ['prefix', 'text']) {
-    ok(Array.isArray(blocks[key]) && blocks[key].length > 0, `${P.dir}: persona.config.${key} is missing or not a literal block`)
-  }
-  if (!blocks.prefix || !blocks.text) { ok(false, `${P.dir}: cannot continue without both blocks`); continue }
-
-  // ---- B. the two blocks must not drift --------------------------------
-  const trimTail = (a) => { const b = a.slice(); while (b.length && b[b.length - 1] === '') b.pop(); return b }
-  const p = trimTail(blocks.prefix)
-  const t = trimTail(blocks.text)
-  eq(p.length, t.length, `${P.dir}: prefix and text have different line counts`)
-  const drift = []
-  for (let i = 1; i < Math.max(p.length, t.length); i++) if (p[i] !== t[i]) drift.push(i)
-  ok(drift.length === 0, `${P.dir}: prefix and text differ on line(s) ${drift.slice(0, 5).join(', ')} (only line 0 may differ)`)
-  ok(/\{\{model\}\}/.test(p[0]) || /\{\{model\}\}/.test(t[0]), `${P.dir}: line 0 does not interpolate {{model}}`)
-
-  // ---- C/D. mention <-> registry ----------------------------------------
-  for (const key of ['prefix', 'text']) {
-    const body = blocks[key].join('\n')
-    const mentioned = new Set()
-    const wildcards = new Set()
-    // Uppercase is part of the token class on purpose: a drifted name such as
-    // `vibe_v4_formal_reportX` must be captured whole and judged unregistered, instead of
-    // being read as a mention of the registered `vibe_v4_formal_report`.
-    // Names that do NOT carry this preset's prefix (the shared `math_computation`) are added to the
-    // alternation from the registry, so "every registered tool must be mentioned" stays true for
-    // them too instead of forcing them into the `undocumented` snapshot.
-    const prefixRoot = P.prefix.replace(/_$/, '')
-    const prefixless = [...registered].filter((n) => !new RegExp('^' + prefixRoot + '_').test(n))
-    const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    const re = new RegExp('\\b' + prefixRoot + '_[A-Za-z0-9_]+' + (prefixless.length ? '|\\b' + prefixless.map(escapeRe).join('\\b|\\b') + '\\b' : ''), 'g')
-    for (const m of body.matchAll(re)) {
-      if (body[m.index + m[0].length] === '*') { wildcards.add(m[0]); continue }
-      mentioned.add(m[0])
-    }
-    const stale = [...mentioned].filter((n) => !registered.has(n)).sort()
-    eq(stale, [], `${P.dir} [${key}]: persona advertises tool(s) that are not registered`)
-    for (const w of wildcards) {
-      ok([...registered].some((n) => n.startsWith(w)), `${P.dir} [${key}]: wildcard mention ${w}* matches no registered tool`)
-    }
-    const unmentioned = [...registered].filter((n) => !mentioned.has(n)).sort()
-    // ALLOW-LIST design (replaces the old "equals a reviewed snapshot" equality): a registered tool may
-    // be absent from the persona ONLY if its name is consciously allow-listed for this preset. The
-    // allow-list is empty by default (v2/v3), so a newly registered tool turns this red until it is
-    // either mentioned in the persona or deliberately added to the list with a reason.
-    const allowed = new Set(P.allowList || [])
-    const illegal = unmentioned.filter((n) => !allowed.has(n))
-    ok(illegal.length === 0, `${P.dir} [${key}]: every registered tool is mentioned in the persona, or explicitly allow-listed`,
-      'unmentioned and not allow-listed: ' + JSON.stringify(illegal))
-    const staleAllowed = [...allowed].filter((n) => !registered.has(n)).sort()
-    ok(staleAllowed.length === 0, `${P.dir} [${key}]: every allow-list entry is a real registered tool`,
-      'allow-listed but not registered: ' + JSON.stringify(staleAllowed))
-    for (const must of (P.required || [])) {
-      ok(mentioned.has(must) && !allowed.has(must), `${P.dir} [${key}]: ${must} must be MENTIONED in the persona (never allow-listed)`)
-    }
-  }
-
-  // ---- F. the slash-command surface -------------------------------------
-  // The persona enumerates the `/vN` subcommands; the plugin advertises them twice more
-  // (the command `hint` the user sees while typing, and the `usage` string returned by the
-  // unknown-subcommand path) and implements them in a third place. A `/v4` usage string once
-  // advertised a `message` subcommand that no branch implemented; the v5 persona and plan
-  // omitted `add|remove` although the handler implements them. All three surfaces must agree.
-  const region = commandRegion(src)
-  if (!ok(region !== null, `${P.dir}: no commands.register(...) block found`)) continue
-  const hinted = cmdsFrom(region.match(/hint:\s*'\[(.*)\]'/)?.[1] || '')
-  // The LAST `usage:` is the unknown-subcommand advertisement; earlier ones are inline
-  // per-branch usage hints (e.g. `/v4 message <to|all> <content>`).
-  const usageMatches = [...region.matchAll(/usage:\s*'([^']*)'/g)]
-  const used = cmdsFrom(usageMatches.length ? usageMatches[usageMatches.length - 1][1] : '')
-  const implemented = [...new Set([...region.matchAll(/cmd\s*===\s*'([a-z0-9_-]+)'/g)].map((m) => m[1]))].sort()
-  const hintOpen = /\.\.\./.test(region.match(/hint:\s*'\[(.*)\]'/)?.[1] || '')
-  ok(hinted.length > 0 && implemented.length > 0, `${P.dir}: could not extract the slash-command surface (hint ${hinted.length}, branches ${implemented.length})`)
-  eq(hinted.filter((c) => !implemented.includes(c)).sort(), [], `${P.dir}: the slash hint advertises subcommand(s) that no branch implements`)
-  if (!hintOpen) eq(implemented.filter((c) => !hinted.includes(c)).sort(), [], `${P.dir}: implemented slash subcommand(s) are missing from the hint`)
-  eq(used.sort(), implemented, `${P.dir}: the usage string and the implemented slash subcommands disagree`)
-  const personaEnum = /slash command mirrors[^(]*\(([\s\S]*?)\)/.exec(blocks.prefix.join('\n') + '\n' + blocks.text.join('\n'))
-  // An ellipsis must NOT switch this check off (that is how a dropped `paper` entry survived here),
-  // and `...` inside an argument placeholder (`set <k=v>...`) is not an abbreviation at all. So the
-  // persona is compared against the BRANCHES (the ground truth), and every implemented subcommand
-  // must be named EXPLICITLY. Only a HINT that is itself abbreviated makes the reverse direction
-  // (persona ⊆ hint) unprovable, so only that direction is relaxed then.
-  if (!personaEnum) {
-    ok(false, `${P.dir}: the persona never enumerates its /vN subcommands (list them so a human can see every one)`)
-  } else {
-    const personaCmds = cmdsFrom(personaEnum[1].replace(/^\s*\/[a-z0-9]+\s+/, ''))
-    ok(personaCmds.length > 0, `${P.dir}: no slash subcommand could be parsed from the persona's /vN list`)
-    eq(personaCmds.filter((c) => !implemented.includes(c)).sort(), [], `${P.dir}: the persona enumerates slash subcommand(s) the handler does not implement`)
-    eq(implemented.filter((c) => !personaCmds.includes(c)).sort(), [], `${P.dir}: the persona's /vN list omits subcommand(s) the handler implements — list them explicitly, do not hide behind "..."`)
-    if (!hintOpen) eq(personaCmds.slice().sort(), implemented.slice().sort(), `${P.dir}: the persona's /vN list and the command hint disagree`)
-  }
-
-  // ---- E. the Lean feature's prompt surface ----------------------------
-  const names = (s) => new RegExp('\\b' + s + '\\b')
-  for (const key of ['prefix', 'text']) {
-    const body = blocks[key].join('\n')
-    for (const tool of P.lean.tools) ok(names(tool).test(body), `${P.dir} [${key}]: Lean tool ${tool} is never named`)
-    for (const tool of P.lean.extra) ok(names(tool).test(body), `${P.dir} [${key}]: ${tool} is never named`)
-    for (const prm of LEAN_PARAMS) ok(names(prm).test(body), `${P.dir} [${key}]: Lean parameter ${prm} is never named`)
-    for (const mode of ['off', 'encourage', 'require']) ok(body.includes(`'${mode}'`), `${P.dir} [${key}]: Lean mode ${mode} is never spelled out`)
-    ok(/FIDELITY|忠实性/.test(body), `${P.dir} [${key}]: the fidelity switch of a passing Lean run is not stated`)
-    ok(body.includes('Formal/Lib') && body.includes('Formal/Proved'), `${P.dir} [${key}]: the cross-project Lean library paths are not stated`)
-    ok(body.includes('Verified/Lean'), `${P.dir} [${key}]: the archived-proof path Verified/Lean is not stated`)
-  }
-}
-
-// ---- the shared contract must stay in step with the personas -----------
-try {
-  const contract = readFileSync(join(ROOT, 'docs', 'formal-verification.md'), 'utf8')
-  for (const prm of LEAN_PARAMS) ok(contract.includes(prm), `docs/formal-verification.md: parameter ${prm} is not documented`)
-  for (const sec of ['off', 'encourage', 'require']) ok(new RegExp('`' + sec + '`').test(contract), `docs/formal-verification.md: mode ${sec} is not documented`)
-  ok(contract.includes('Verified/Lean'), 'docs/formal-verification.md: the archived-proof path is not documented')
-  ok(contract.includes('Formal/Lib') && contract.includes('Formal/Proved'), 'docs/formal-verification.md: the global library paths are not documented')
-} catch (e) {
-  ok(false, `docs/formal-verification.md: cannot read the shared contract (${e.message})`)
-}
-
-// ---- G. the human-reviewable persona corpus (shipped) -------------------
-// Assertions are not enough: the reviewer must be able to READ what the main agent receives
-// without digging through YAML (see AUDIT-CHECKLIST §2.4). This writes the exact persona text
-// of all four presets to `prompt-corpus-persona/` and is skipped when running against a copy
-// (PERSONA_ROOT), so a mutation probe can never overwrite the shipped corpus.
-{
-  const rows = PRESETS.map((P) => {
-    const yml = readFileSync(join(BASE, P.dir, 'agent.cordis.yml'), 'utf8')
-    const b = literalBlocks(yml)
-    const src = readFileSync(join(BASE, P.dir, P.js), 'utf8')
-    const registered = [...new Set([...src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)].map((m) => m[1]))].sort()
-    const region = commandRegion(src) || ''
-    return {
-      preset: P.dir,
-      tools: registered.length,
-      prefix: (b.prefix || []).join('\n'),
-      text: (b.text || []).join('\n'),
-      slashHint: (region.match(/hint:\s*'\[(.*)\]'/) || [])[1] || '',
-    }
-  })
-  eq(rows.length, PRESETS.length, 'persona corpus: not every preset was captured')
-  ok(rows.every((r) => r.prefix.length > 0 && r.text.length > 0), 'persona corpus: a preset has an empty persona block')
-  const corpusDir = join(ROOT, 'prompt-corpus-persona')
-  if (!process.env.PERSONA_ROOT) {
-    const md = ['# 四个预设的 persona 原文（主代理实际收到的提示词）', '',
-      '> 本文件由 `audit-persona-surface.test.mjs` 生成，供人工复核：四个预设的主代理分别被告知了',
-      '> 哪些工具、哪些参数、哪些斜杠子命令。`prefix` 与 `text` 两个块**只允许第 0 行不同**。', '']
-    for (const r of rows) {
-      md.push(`## ${r.preset}`, '', `- 注册工具数：**${r.tools}**`, `- 斜杠命令 hint：\`${r.slashHint}\``, '',
-        '### config.prefix', '', '```text', r.prefix, '```', '', '### config.text', '', '```text', r.text, '```', '')
-    }
-    mkdirSync(corpusDir, { recursive: true })
-    // CONCURRENCY FIX: `audit-persona-sensitivity` spawns this suite with PERSONA_ROOT, and those child
-    // runs READ these two shipped files while a parallel `run-tests` job may be WRITING them. A plain
-    // writeFileSync let a reader observe a half-written JSON (the flake: sensitivity red only under
-    // concurrency 4, SETUP-FAIL in its control run). Write a unique temp file in the same directory and
-    // rename it into place, so a reader sees either the old or the new file, never a partial one.
-    const writeAtomic = (target, data) => {
-      const tmp = target + '.tmp-' + process.pid + '-' + Math.random().toString(36).slice(2)
-      writeFileSync(tmp, data, 'utf8')
-      renameSync(tmp, target)
-    }
-    writeAtomic(join(corpusDir, 'persona-corpus.md'), md.join('\n'))
-    writeAtomic(join(corpusDir, 'persona-corpus.json'), JSON.stringify({ presets: rows }, null, 2) + '\n')
-  }
-  // Round-trip check: the shipped corpus must name all four presets and carry line 0 of each block.
-  // Skipped under PERSONA_ROOT: there `rows` describe the mutated copy while the corpus on disk
-  // describes the real presets, so comparing them would be meaningless.
-  if (process.env.PERSONA_ROOT) {
-    ok(existsSync(join(corpusDir, 'persona-corpus.md')) && existsSync(join(corpusDir, 'persona-corpus.json')),
-      'persona corpus: the shipped corpus files are missing from the repository')
-  } else {
-    try {
-      const back = readFileSync(join(corpusDir, 'persona-corpus.md'), 'utf8')
-      for (const r of rows) {
-        ok(back.includes(`## ${r.preset}`), `persona corpus: ${r.preset} is missing from the shipped corpus`)
-        ok(back.includes(r.prefix.split('\n')[0]), `persona corpus: ${r.preset} prefix line 0 is missing from the shipped corpus`)
-      }
-      const backJson = JSON.parse(readFileSync(join(corpusDir, 'persona-corpus.json'), 'utf8'))
-      eq(backJson.presets.length, PRESETS.length, 'persona corpus (json): not every preset was captured')
-    } catch (e) {
-      ok(false, `persona corpus: cannot read back the shipped corpus (${e.message})`)
-    }
-  }
-}
-
-console.log('')
-for (const f of failures) console.log('  FAIL ' + f)
-console.log(`\n=== PERSONA SURFACE RESULT: ${passed} passed, ${failed} failed ===`)
-process.exit(failed === 0 ? 0 : 1)
+#!/usr/bin/env node
+/**
+ * PERSONA SURFACE — prompt/allocation consistency for the four presets.
+ *
+ * DEFECT CLASS (why this guard exists; it belongs to the dual-persona-block parity family of §3)
+ *   "capability advertised but never granted, or granted but never advertised": the persona block is
+ *   the main agent view of the tool surface, so a registered-but-unnamed tool is invisible and a
+ *   named-but-unregistered tool is a trap. Every other suite calls apply(ctx) directly and never
+ *   parses the YAML, so this class cannot fail anywhere else.
+ *
+ * Run: node tests/audit-persona-surface.test.mjs
+ *
+ * WHY THIS EXISTS
+ *   The persona row of each `agent.cordis.yml` is the prompt the MAIN agent actually
+ *   receives, and it is the only place the main agent learns which `vibe_*` tools exist
+ *   and which parameters it may tune. Two failure modes are invisible to every other
+ *   suite, because those suites call `apply(ctx)` directly and never load the YAML:
+ *
+ *     1. a tool is registered but never named in the persona  → the agent does not know
+ *        the capability exists (it cannot even guess the exact name);
+ *     2. the persona names a tool that is NOT registered       → the agent calls a tool
+ *        that will fail, and (in the worst case) is told to rely on it.
+ *
+ *   The Lean formal-verification feature shipped with exactly this bug in three of four
+ *   presets: the three `*_lean_*` tools were registered unconditionally but the v2/v3/v4
+ *   personas never listed them (v5's did), and v4's `vibe_v4_set` parameter list omitted
+ *   `formalVerify`/`leanCommand`/`leanArgs`/`leanTimeoutMs`, so the coordinator could not
+ *   discover the switch at all. Nothing in the build noticed. Hence this guard.
+ *
+ * INVARIANTS (per preset)
+ *   A. the persona row carries both `prefix` and `text` literal blocks, and both parse
+ *      into a non-empty body (both keys are required for DSH schema/back-compat);
+ *   B. the two blocks are IDENTICAL apart from their first line — an old host that uses
+ *      `text` must not receive a different tool surface from a new host that uses `prefix`;
+ *   C. mentions ⊆ registered: every `vibe_*` token in the persona is a registered tool
+ *      (a `name*` mention is allowed when some registered tool carries that prefix);
+ *   D. every registered tool is either MENTIONED in the persona or consciously ALLOW-LISTED, and the
+ *      allow-list is itself validated (real tools only, empty by default) — so adding a tool forcing a
+ *      decision: name it, or add it to the list with a reason. (Earlier this was a snapshot equality,
+ *      which went red whenever a legitimately newly-named tool emptied the "undocumented" set.)
+ *      without documenting it (or deleting a tool the persona still advertises) fails
+ *      loudly and forces the author to make a decision;
+ *   E. the parameter surface of the Lean feature (the four names) and its semantics
+ *      (three modes, the fidelity switch, the project/global paths) appear in BOTH blocks.
+ *
+ * The snapshots below are the reviewed answer to "is this tool intentionally absent from
+ * the coordinator's persona?" — virtually all of them are `(member)` / `(academician)` /
+ * `(resident)` tools that only subagents call.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = fileURLToPath(new URL('../', import.meta.url))
+/**
+ * `PERSONA_ROOT` points the preset lookup at a prepared copy. It exists so that
+ * `audit-persona-sensitivity.mjs` can prove this suite is not vacuous: each probe mutates a
+ * copy of one persona (or one plugin) and requires this suite to go RED. Without the
+ * override the mutation would never be loaded and every probe would be a false green.
+ * `docs/formal-verification.md` is always read from the repository root, because the
+ * shared contract is not part of a preset copy.
+ */
+const BASE = process.env.PERSONA_ROOT ? resolve(process.env.PERSONA_ROOT) : ROOT
+
+let passed = 0
+let failed = 0
+const failures = []
+function ok(cond, msg) {
+  if (cond) { passed++; return true }
+  failed++
+  failures.push(msg)
+  return false
+}
+function eq(actual, expected, msg) {
+  const a = JSON.stringify(actual)
+  const e = JSON.stringify(expected)
+  return ok(a === e, `${msg}\n      expected: ${e}\n      actual:   ${a}`)
+}
+
+/**
+ * Extract a YAML literal block scalar (`prefix: |-`) by indentation. Deliberately does
+ * not depend on a YAML library: this file must run inside the published package, where
+ * only the DSH host (not this repo) has one. The block's own indentation is stripped so
+ * the `prefix` and `text` bodies can be compared line by line.
+ */
+function literalBlocks(yml) {
+  const out = {}
+  const lines = yml.split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(\s*)([A-Za-z_][\w-]*):\s*\|-?\s*$/.exec(lines[i])
+    if (!m) continue
+    const ind = m[1].length
+    const body = []
+    for (let j = i + 1; j < lines.length; j++) {
+      const L = lines[j]
+      if (L.trim() === '') { body.push(''); continue }
+      const li = L.length - L.trimStart().length
+      if (li <= ind) break
+      body.push(L.slice(ind + 2))
+    }
+    out[m[2]] = body
+  }
+  return out
+}
+
+/**
+ * The slice of a plugin that describes and implements its `/vN` slash command: the
+ * `commands.register({...})` block, plus — for v2/v3, which dispatch through a named function —
+ * the `dispatchVibeCommand` body (that is where their branch list and usage string live).
+ * The anchor includes the `{` on purpose: the files also mention `commands.register()` in a
+ * prose comment *before* the real call, and anchoring on the call's object literal skips it.
+ */
+function commandRegion(src) {
+  const i = src.indexOf('commands.register({')
+  if (i < 0) return null
+  const end = src.indexOf('\n  }))', i)
+  let region = src.slice(i, end > i ? end : Math.min(src.length, i + 8000))
+  if (!/cmd\s*===\s*'/.test(region)) {
+    const d = src.indexOf('dispatchVibeCommand(cmd, args)')
+    if (d >= 0) {
+      const dEnd = src.indexOf('\n  }', d)
+      region += '\n' + src.slice(d, dEnd > d ? dEnd : d + 8000)
+    }
+  }
+  return region
+}
+
+/** Split a `a|b <x|y>|c` advertised list into bare subcommand names. */
+function cmdsFrom(list) {
+  const out = []
+  const bare = String(list).replace(/\[[^\]]*\]/g, ' ').replace(/<[^>]*>/g, ' ')
+  for (const tok of bare.split('|')) {
+    const t = tok.trim()
+    if (!t || t === '...') continue
+    const name = t.split(/\s+/)[0]
+    if (/^[a-z][a-z0-9-]*$/.test(name)) out.push(name)
+  }
+  return out
+}
+
+const PRESETS = [
+  {
+    dir: 'vibe-math-v2',
+    js: 'vibe-math-v2.js',
+    prefix: 'vibe_math_',
+    tools: 28,
+    // D. registered \ mentioned ⊆ allow-list: EVERY registered tool must be mentioned in the persona,
+    // unless its name is listed here as a conscious exception (the allow-list is empty by default, so a
+    // newly registered tool cannot slip in unnamed). An entry must be a REAL registered tool, and a
+    // preset may also pin names that must be mentioned (never allow-listed).
+    allowList: [],
+    required: [],
+    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib', 'vibe_math_lean_read', 'vibe_math_lean_job'], extra: [] },
+    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
+    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
+    math: { tools: ['math_computation'] },
+  },
+  {
+    dir: 'vibe-math-v3',
+    js: 'vibe-math-v3.js',
+    prefix: 'vibe_math_',
+    tools: 36,
+    // `vibe_math_sync_meta` is named by the promotion-contract line, and the write-lock pair is now
+    // named too (the lock is described in the persona, so leaving the two tools unmentioned was the
+    // last hole). Both stay REQUIRED: they must be mentioned, never allow-listed.
+    allowList: [],
+    required: ['vibe_math_claim_write', 'vibe_math_release_write'],
+    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib', 'vibe_math_lean_read', 'vibe_math_lean_job'], extra: [] },
+    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
+    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
+    math: { tools: ['math_computation'] },
+  },
+  {
+    dir: 'vibe-math-v4',
+    js: 'vibe-math-v4.js',
+    prefix: 'vibe_v4_',
+    tools: 35,
+    // Member-facing tools (mail, library cards, task board, write lock) that the v4 persona describes
+    // GENERICALLY rather than naming one by one; the coordinator drives residents through
+    // vibe_v4_message / _meeting / _add_member. Allow-listed ON PURPOSE, so a NEWLY registered tool
+    // still has to be named (or added here consciously).
+    allowList: [
+      'vibe_v4_send_message', 'vibe_v4_publish_progress', 'vibe_v4_record_proposition',
+      'vibe_v4_record_method', 'vibe_v4_record_subproblem', 'vibe_v4_read_progress',
+      'vibe_v4_list_residents', 'vibe_v4_propose_task', 'vibe_v4_claim_task',
+      'vibe_v4_task_done', 'vibe_v4_list_tasks', 'vibe_v4_report_context',
+      'vibe_v4_claim_write', 'vibe_v4_release_write',
+    ],
+    required: [],
+    lean: { tools: ['vibe_v4_lean_run', 'vibe_v4_lean_archive', 'vibe_v4_lean_lib', 'vibe_v4_lean_read', 'vibe_v4_lean_job'], extra: ['vibe_v4_formal_report'] },
+    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
+    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
+    math: { tools: ['math_computation'] },
+  },
+  {
+    dir: 'vibe-math-v5',
+    js: 'vibe-math-v5.js',
+    prefix: 'vibe_v5_',
+    tools: 40,
+    // Member- and academician-facing tools that the v5 persona describes GENERICALLY; the office (main
+    // agent) holds only the institute-level controls plus the hiring authority. The final-paper pair is
+    // an OFFICE control and IS named in the persona (vibe_v5_paper / vibe_v5_finalize_paper), so it must
+    // NOT be allow-listed here. Allow-listed ON PURPOSE: a NEWLY registered tool still has to be named.
+    allowList: [
+      'vibe_v5_wait', 'vibe_v5_record_progress', 'vibe_v5_record_proposition',
+      'vibe_v5_record_method', 'vibe_v5_record_subproblem', 'vibe_v5_read_library',
+      'vibe_v5_propose_verify', 'vibe_v5_verdict', 'vibe_v5_task_create',
+      'vibe_v5_task_list', 'vibe_v5_task_get', 'vibe_v5_task_update',
+      'vibe_v5_overview', 'vibe_v5_assign', 'vibe_v5_prioritize', 'vibe_v5_nudge',
+    ],
+    required: [],
+    lean: { tools: ['vibe_v5_lean_run', 'vibe_v5_lean_archive', 'vibe_v5_lean_lib', 'vibe_v5_lean_read', 'vibe_v5_lean_job'], extra: [] },
+    // the shared math-computation tool (docs/math-computation.md) is prefix-less by
+    // design (INTERFACE-FREEZE.md §3), so it is pinned explicitly here.
+    math: { tools: ['math_computation'] },
+  },
+]
+
+const LEAN_PARAMS = ['formalVerify', 'leanCommand', 'leanArgs', 'leanTimeoutMs', 'leanAsync', 'leanJobsMaxParallel', 'leanInitiative', 'leanSearchPaths']
+
+for (const P of PRESETS) {
+  const ymlPath = join(BASE, P.dir, 'agent.cordis.yml')
+  const jsPath = join(BASE, P.dir, P.js)
+  const yml = readFileSync(ymlPath, 'utf8')
+  const src = readFileSync(jsPath, 'utf8')
+
+  // ---- registered tools -------------------------------------------------
+  // Two registration shapes exist now:
+  //   1. a literal `registerTool('<name>', …)` (most tools, including the shared math tool in
+  //      v2/v3, which register it by its frozen prefix-less name);
+  //   2. the shared math tool in v4/v5, where the plugin only wires a host callback and the module
+  //      calls `host.register(MATH_TOOL_NAME, …)`. The module's name is FROZEN
+  //      (MATH_TOOL_NAME = 'math_computation', INTERFACE-FREEZE.md §3), so a source that wires
+  //      `registerMathComputation(` contributes exactly that one tool. Without this the shared tool
+  //      would be invisible to this guard on v4/v5 - a silent coverage hole.
+  const registered = new Set()
+  for (const m of src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)) registered.add(m[1])
+  if (/registerMathComputation\s*\(/.test(src)) registered.add('math_computation')
+  eq(registered.size, P.tools, `${P.dir}: registered tool count changed (update this snapshot deliberately)`)
+  for (const tool of (P.math ? P.math.tools : [])) ok(registered.has(tool), `${P.dir}: the shared math tool ${tool} is not registered`)
+
+  // ---- A. both literal blocks exist and are non-empty -------------------
+  const blocks = literalBlocks(yml)
+  const hasPersona = /^\s*-\s*id:\s*persona\s*$/m.test(yml)
+  ok(hasPersona, `${P.dir}: no persona row in agent.cordis.yml`)
+  for (const key of ['prefix', 'text']) {
+    ok(Array.isArray(blocks[key]) && blocks[key].length > 0, `${P.dir}: persona.config.${key} is missing or not a literal block`)
+  }
+  if (!blocks.prefix || !blocks.text) { ok(false, `${P.dir}: cannot continue without both blocks`); continue }
+
+  // ---- B. the two blocks must not drift --------------------------------
+  const trimTail = (a) => { const b = a.slice(); while (b.length && b[b.length - 1] === '') b.pop(); return b }
+  const p = trimTail(blocks.prefix)
+  const t = trimTail(blocks.text)
+  eq(p.length, t.length, `${P.dir}: prefix and text have different line counts`)
+  const drift = []
+  for (let i = 1; i < Math.max(p.length, t.length); i++) if (p[i] !== t[i]) drift.push(i)
+  ok(drift.length === 0, `${P.dir}: prefix and text differ on line(s) ${drift.slice(0, 5).join(', ')} (only line 0 may differ)`)
+  ok(/\{\{model\}\}/.test(p[0]) || /\{\{model\}\}/.test(t[0]), `${P.dir}: line 0 does not interpolate {{model}}`)
+
+  // ---- C/D. mention <-> registry ----------------------------------------
+  for (const key of ['prefix', 'text']) {
+    const body = blocks[key].join('\n')
+    const mentioned = new Set()
+    const wildcards = new Set()
+    // Uppercase is part of the token class on purpose: a drifted name such as
+    // `vibe_v4_formal_reportX` must be captured whole and judged unregistered, instead of
+    // being read as a mention of the registered `vibe_v4_formal_report`.
+    // Names that do NOT carry this preset's prefix (the shared `math_computation`) are added to the
+    // alternation from the registry, so "every registered tool must be mentioned" stays true for
+    // them too instead of forcing them into the `undocumented` snapshot.
+    const prefixRoot = P.prefix.replace(/_$/, '')
+    const prefixless = [...registered].filter((n) => !new RegExp('^' + prefixRoot + '_').test(n))
+    const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const re = new RegExp('\\b' + prefixRoot + '_[A-Za-z0-9_]+' + (prefixless.length ? '|\\b' + prefixless.map(escapeRe).join('\\b|\\b') + '\\b' : ''), 'g')
+    for (const m of body.matchAll(re)) {
+      if (body[m.index + m[0].length] === '*') { wildcards.add(m[0]); continue }
+      mentioned.add(m[0])
+    }
+    const stale = [...mentioned].filter((n) => !registered.has(n)).sort()
+    eq(stale, [], `${P.dir} [${key}]: persona advertises tool(s) that are not registered`)
+    for (const w of wildcards) {
+      ok([...registered].some((n) => n.startsWith(w)), `${P.dir} [${key}]: wildcard mention ${w}* matches no registered tool`)
+    }
+    const unmentioned = [...registered].filter((n) => !mentioned.has(n)).sort()
+    // ALLOW-LIST design (replaces the old "equals a reviewed snapshot" equality): a registered tool may
+    // be absent from the persona ONLY if its name is consciously allow-listed for this preset. The
+    // allow-list is empty by default (v2/v3), so a newly registered tool turns this red until it is
+    // either mentioned in the persona or deliberately added to the list with a reason.
+    const allowed = new Set(P.allowList || [])
+    const illegal = unmentioned.filter((n) => !allowed.has(n))
+    ok(illegal.length === 0, `${P.dir} [${key}]: every registered tool is mentioned in the persona, or explicitly allow-listed`,
+      'unmentioned and not allow-listed: ' + JSON.stringify(illegal))
+    const staleAllowed = [...allowed].filter((n) => !registered.has(n)).sort()
+    ok(staleAllowed.length === 0, `${P.dir} [${key}]: every allow-list entry is a real registered tool`,
+      'allow-listed but not registered: ' + JSON.stringify(staleAllowed))
+    for (const must of (P.required || [])) {
+      ok(mentioned.has(must) && !allowed.has(must), `${P.dir} [${key}]: ${must} must be MENTIONED in the persona (never allow-listed)`)
+    }
+  }
+
+  // ---- F. the slash-command surface -------------------------------------
+  // The persona enumerates the `/vN` subcommands; the plugin advertises them twice more
+  // (the command `hint` the user sees while typing, and the `usage` string returned by the
+  // unknown-subcommand path) and implements them in a third place. A `/v4` usage string once
+  // advertised a `message` subcommand that no branch implemented; the v5 persona and plan
+  // omitted `add|remove` although the handler implements them. All three surfaces must agree.
+  const region = commandRegion(src)
+  if (!ok(region !== null, `${P.dir}: no commands.register(...) block found`)) continue
+  const hinted = cmdsFrom(region.match(/hint:\s*'\[(.*)\]'/)?.[1] || '')
+  // The LAST `usage:` is the unknown-subcommand advertisement; earlier ones are inline
+  // per-branch usage hints (e.g. `/v4 message <to|all> <content>`).
+  const usageMatches = [...region.matchAll(/usage:\s*'([^']*)'/g)]
+  const used = cmdsFrom(usageMatches.length ? usageMatches[usageMatches.length - 1][1] : '')
+  const implemented = [...new Set([...region.matchAll(/cmd\s*===\s*'([a-z0-9_-]+)'/g)].map((m) => m[1]))].sort()
+  const hintOpen = /\.\.\./.test(region.match(/hint:\s*'\[(.*)\]'/)?.[1] || '')
+  ok(hinted.length > 0 && implemented.length > 0, `${P.dir}: could not extract the slash-command surface (hint ${hinted.length}, branches ${implemented.length})`)
+  eq(hinted.filter((c) => !implemented.includes(c)).sort(), [], `${P.dir}: the slash hint advertises subcommand(s) that no branch implements`)
+  if (!hintOpen) eq(implemented.filter((c) => !hinted.includes(c)).sort(), [], `${P.dir}: implemented slash subcommand(s) are missing from the hint`)
+  eq(used.sort(), implemented, `${P.dir}: the usage string and the implemented slash subcommands disagree`)
+  const personaEnum = /slash command mirrors[^(]*\(([\s\S]*?)\)/.exec(blocks.prefix.join('\n') + '\n' + blocks.text.join('\n'))
+  // An ellipsis must NOT switch this check off (that is how a dropped `paper` entry survived here),
+  // and `...` inside an argument placeholder (`set <k=v>...`) is not an abbreviation at all. So the
+  // persona is compared against the BRANCHES (the ground truth), and every implemented subcommand
+  // must be named EXPLICITLY. Only a HINT that is itself abbreviated makes the reverse direction
+  // (persona ⊆ hint) unprovable, so only that direction is relaxed then.
+  if (!personaEnum) {
+    ok(false, `${P.dir}: the persona never enumerates its /vN subcommands (list them so a human can see every one)`)
+  } else {
+    const personaCmds = cmdsFrom(personaEnum[1].replace(/^\s*\/[a-z0-9]+\s+/, ''))
+    ok(personaCmds.length > 0, `${P.dir}: no slash subcommand could be parsed from the persona's /vN list`)
+    eq(personaCmds.filter((c) => !implemented.includes(c)).sort(), [], `${P.dir}: the persona enumerates slash subcommand(s) the handler does not implement`)
+    eq(implemented.filter((c) => !personaCmds.includes(c)).sort(), [], `${P.dir}: the persona's /vN list omits subcommand(s) the handler implements — list them explicitly, do not hide behind "..."`)
+    if (!hintOpen) eq(personaCmds.slice().sort(), implemented.slice().sort(), `${P.dir}: the persona's /vN list and the command hint disagree`)
+  }
+
+  // ---- E. the Lean feature's prompt surface ----------------------------
+  const names = (s) => new RegExp('\\b' + s + '\\b')
+  for (const key of ['prefix', 'text']) {
+    const body = blocks[key].join('\n')
+    for (const tool of P.lean.tools) ok(names(tool).test(body), `${P.dir} [${key}]: Lean tool ${tool} is never named`)
+    for (const tool of P.lean.extra) ok(names(tool).test(body), `${P.dir} [${key}]: ${tool} is never named`)
+    for (const prm of LEAN_PARAMS) ok(names(prm).test(body), `${P.dir} [${key}]: Lean parameter ${prm} is never named`)
+    for (const mode of ['off', 'encourage', 'require']) ok(body.includes(`'${mode}'`), `${P.dir} [${key}]: Lean mode ${mode} is never spelled out`)
+    ok(/FIDELITY|忠实性/.test(body), `${P.dir} [${key}]: the fidelity switch of a passing Lean run is not stated`)
+    ok(body.includes('Formal/Lib') && body.includes('Formal/Proved'), `${P.dir} [${key}]: the cross-project Lean library paths are not stated`)
+    ok(body.includes('Verified/Lean'), `${P.dir} [${key}]: the archived-proof path Verified/Lean is not stated`)
+  }
+}
+
+// ---- the shared contract must stay in step with the personas -----------
+try {
+  const contract = readFileSync(join(ROOT, 'docs', 'formal-verification.md'), 'utf8')
+  for (const prm of LEAN_PARAMS) ok(contract.includes(prm), `docs/formal-verification.md: parameter ${prm} is not documented`)
+  for (const sec of ['off', 'encourage', 'require']) ok(new RegExp('`' + sec + '`').test(contract), `docs/formal-verification.md: mode ${sec} is not documented`)
+  ok(contract.includes('Verified/Lean'), 'docs/formal-verification.md: the archived-proof path is not documented')
+  ok(contract.includes('Formal/Lib') && contract.includes('Formal/Proved'), 'docs/formal-verification.md: the global library paths are not documented')
+} catch (e) {
+  ok(false, `docs/formal-verification.md: cannot read the shared contract (${e.message})`)
+}
+
+// ---- G. the human-reviewable persona corpus (shipped) -------------------
+// Assertions are not enough: the reviewer must be able to READ what the main agent receives
+// without digging through YAML (see AUDIT-CHECKLIST §2.4). This writes the exact persona text
+// of all four presets to `prompt-corpus-persona/` and is skipped when running against a copy
+// (PERSONA_ROOT), so a mutation probe can never overwrite the shipped corpus.
+{
+  const rows = PRESETS.map((P) => {
+    const yml = readFileSync(join(BASE, P.dir, 'agent.cordis.yml'), 'utf8')
+    const b = literalBlocks(yml)
+    const src = readFileSync(join(BASE, P.dir, P.js), 'utf8')
+    const registered = [...new Set([...src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)].map((m) => m[1]))].sort()
+    const region = commandRegion(src) || ''
+    return {
+      preset: P.dir,
+      tools: registered.length,
+      prefix: (b.prefix || []).join('\n'),
+      text: (b.text || []).join('\n'),
+      slashHint: (region.match(/hint:\s*'\[(.*)\]'/) || [])[1] || '',
+    }
+  })
+  eq(rows.length, PRESETS.length, 'persona corpus: not every preset was captured')
+  ok(rows.every((r) => r.prefix.length > 0 && r.text.length > 0), 'persona corpus: a preset has an empty persona block')
+  const corpusDir = join(ROOT, 'prompt-corpus-persona')
+  if (!process.env.PERSONA_ROOT) {
+    const md = ['# 四个预设的 persona 原文（主代理实际收到的提示词）', '',
+      '> 本文件由 `audit-persona-surface.test.mjs` 生成，供人工复核：四个预设的主代理分别被告知了',
+      '> 哪些工具、哪些参数、哪些斜杠子命令。`prefix` 与 `text` 两个块**只允许第 0 行不同**。', '']
+    for (const r of rows) {
+      md.push(`## ${r.preset}`, '', `- 注册工具数：**${r.tools}**`, `- 斜杠命令 hint：\`${r.slashHint}\``, '',
+        '### config.prefix', '', '```text', r.prefix, '```', '', '### config.text', '', '```text', r.text, '```', '')
+    }
+    mkdirSync(corpusDir, { recursive: true })
+    // CONCURRENCY FIX: `audit-persona-sensitivity` spawns this suite with PERSONA_ROOT, and those child
+    // runs READ these two shipped files while a parallel `run-tests` job may be WRITING them. A plain
+    // writeFileSync let a reader observe a half-written JSON (the flake: sensitivity red only under
+    // concurrency 4, SETUP-FAIL in its control run). Write a unique temp file in the same directory and
+    // rename it into place, so a reader sees either the old or the new file, never a partial one.
+    const writeAtomic = (target, data) => {
+      const tmp = target + '.tmp-' + process.pid + '-' + Math.random().toString(36).slice(2)
+      writeFileSync(tmp, data, 'utf8')
+      renameSync(tmp, target)
+    }
+    writeAtomic(join(corpusDir, 'persona-corpus.md'), md.join('\n'))
+    writeAtomic(join(corpusDir, 'persona-corpus.json'), JSON.stringify({ presets: rows }, null, 2) + '\n')
+  }
+  // Round-trip check: the shipped corpus must name all four presets and carry line 0 of each block.
+  // Skipped under PERSONA_ROOT: there `rows` describe the mutated copy while the corpus on disk
+  // describes the real presets, so comparing them would be meaningless.
+  if (process.env.PERSONA_ROOT) {
+    ok(existsSync(join(corpusDir, 'persona-corpus.md')) && existsSync(join(corpusDir, 'persona-corpus.json')),
+      'persona corpus: the shipped corpus files are missing from the repository')
+  } else {
+    try {
+      const back = readFileSync(join(corpusDir, 'persona-corpus.md'), 'utf8')
+      for (const r of rows) {
+        ok(back.includes(`## ${r.preset}`), `persona corpus: ${r.preset} is missing from the shipped corpus`)
+        ok(back.includes(r.prefix.split('\n')[0]), `persona corpus: ${r.preset} prefix line 0 is missing from the shipped corpus`)
+      }
+      const backJson = JSON.parse(readFileSync(join(corpusDir, 'persona-corpus.json'), 'utf8'))
+      eq(backJson.presets.length, PRESETS.length, 'persona corpus (json): not every preset was captured')
+    } catch (e) {
+      ok(false, `persona corpus: cannot read back the shipped corpus (${e.message})`)
+    }
+  }
+}
+
+console.log('')
+for (const f of failures) console.log('  FAIL ' + f)
+console.log(`\n=== PERSONA SURFACE RESULT: ${passed} passed, ${failed} failed ===`)
+process.exit(failed === 0 ? 0 : 1)