dsh-vibe-math 2.2.1 → 2.3.0

package/audit-persona-sensitivity.mjs

@@ -0,0 +1,249 @@
+// ============================================================
+// PERSONA SURFACE SENSITIVITY PROBES
+//
+// `audit-persona-surface.test.mjs` compares each preset's persona prompt against the tools
+// that preset actually registers. It is the only guard against two failures that no other
+// suite can see (they all call apply(ctx) directly and never load the YAML):
+//
+//   · a registered tool that the persona never names  → the agent cannot discover it;
+//   · a persona that names an unregistered tool       → the agent is told to call a tool
+//     that does not exist.
+//
+// The Lean formal-verification feature shipped with both, in three of four presets. This
+// script proves the guard is not vacuous: each probe copies the preset tree, applies ONE
+// mutation, and requires the suite to go RED.
+//
+// False-green traps handled (see AUDIT-CHECKLIST.md §2):
+//   1. a probe whose own spawn fails — reported as SETUP-FAIL, never as a detection;
+//   2. a suite that ignores its override env var — `PERSONA_ROOT` is exercised in both
+//      directions (a NON-mutated copy must keep the suite GREEN before any probe runs);
+//   3. a semantically inert mutation — the anchor must match an exact, asserted count, and
+//      for YAML probes the mutated copy must still yield the persona's two literal blocks;
+//   4. a mutation that breaks syntax — every mutated `.js` copy is `node --check`ed, and a
+//      mutated `.yml` whose persona markers are damaged is a SETUP-FAIL, not a detection.
+//
+// Run: node audit-persona-sensitivity.mjs
+// ============================================================
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, cpSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const REPO = fileURLToPath(new URL('.', import.meta.url))
+const SUITE = join(REPO, 'audit-persona-surface.test.mjs')
+const PRESETS = [
+  { dir: 'vibe-math-v2', js: 'vibe-math-v2.js' },
+  { dir: 'vibe-math-v3', js: 'vibe-math-v3.js' },
+  { dir: 'vibe-math-v4', js: 'vibe-math-v4.js' },
+  { dir: 'vibe-math-v5', js: 'vibe-math-v5.js' },
+]
+
+/** Prepare a private copy of every preset (persona + plugin), so one probe cannot leak. */
+function prepareRoot() {
+  const root = mkdtempSync(join(tmpdir(), 'persona-sens-'))
+  for (const P of PRESETS) {
+    mkdirSync(join(root, P.dir), { recursive: true })
+    cpSync(join(REPO, P.dir, 'agent.cordis.yml'), join(root, P.dir, 'agent.cordis.yml'))
+    cpSync(join(REPO, P.dir, P.js), join(root, P.dir, P.js))
+  }
+  return root
+}
+
+/** The persona's two literal blocks must survive a YAML mutation, or the probe is unfair. */
+function yamlStillHasPersona(yml) {
+  if (!/^\s*-\s*id:\s*persona\s*$/m.test(yml)) return false
+  const markers = yml.match(/^\s*(?:prefix|text):\s*\|-?\s*$/gm) || []
+  return markers.length === 2
+}
+
+function runSuite(root) {
+  const env = Object.assign({}, process.env, { PERSONA_ROOT: root })
+  const r = spawnSync(process.execPath, [SUITE], { env, encoding: 'utf8', cwd: REPO })
+  return { status: r.status, error: r.error, out: String(r.stdout || '') + String(r.stderr || '') }
+}
+
+// A sanity gate first: the UNMUTATED copy must be GREEN through the override, otherwise
+// every probe below would "detect" the override itself rather than the mutation (trap 2).
+const sanityRoot = prepareRoot()
+{
+  const r = runSuite(sanityRoot)
+  if (r.status !== 0) {
+    console.error('  SETUP-FAIL - the suite is RED on an unmutated copy through PERSONA_ROOT:')
+    console.error(r.out.split('\n').filter((l) => l.includes('FAIL')).slice(0, 8).join('\n'))
+    rmSync(sanityRoot, { recursive: true, force: true })
+    process.exit(1)
+  }
+  console.log('  ok   - control: unmutated copy is GREEN through PERSONA_ROOT (the override works)')
+}
+rmSync(sanityRoot, { recursive: true, force: true })
+
+const probes = [
+  // ── v2 ─────────────────────────────────────────────────────────────────────
+  {
+    name: 'v2-lean-tools-line-removed',
+    preset: 'vibe-math-v2', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: 'the three Lean tools must be named in the persona the main agent receives',
+    from: '      - vibe_math_lean_run / vibe_math_lean_archive / vibe_math_lean_lib — Lean formal\n        verification (execute / archive / list the reuse library). The scheduler\'s child agents\n        use them too; they work in every mode.\n',
+    to: '',
+  },
+  {
+    name: 'v2-phantom-tool-mentioned',
+    preset: 'vibe-math-v2', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: 'the persona must not advertise a tool that is not registered (the agent would call it and fail)',
+    from: '      - vibe_math_lean_run / vibe_math_lean_archive / vibe_math_lean_lib — Lean formal',
+    to: '      - vibe_math_lean_exec / vibe_math_lean_run / vibe_math_lean_archive / vibe_math_lean_lib — Lean formal',
+  },
+
+  // ── v3 ─────────────────────────────────────────────────────────────────────
+  {
+    name: 'v3-persona-tool-name-typo',
+    preset: 'vibe-math-v3', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: 'a typo in a persona tool name must be caught (an agent copying it calls a tool that does not exist)',
+    from: 'vibe_math_lean_archive',
+    to: 'vibe_math_lean_archiv',
+  },
+  {
+    name: 'v3-tool-registered-but-not-documented',
+    preset: 'vibe-math-v3', file: 'vibe-math-v3.js', nth: 'first', expect: 2,
+    guarantee: 'a newly registered tool must be documented in the persona (or the snapshot updated on purpose)',
+    from: "  registerTool('vibe_math_lean_run', '(member) Execute the Lean toolchain",
+    to: "  registerTool('vibe_math_extra_tool', 'x', objParams({}), async function () { return {} })\n  registerTool('vibe_math_lean_run', '(member) Execute the Lean toolchain",
+  },
+
+  // ── v4 ─────────────────────────────────────────────────────────────────────
+  {
+    name: 'v4-formal-mode-renamed-in-persona',
+    preset: 'vibe-math-v4', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: 'the persona must spell the three mode names exactly as the parameter accepts them',
+    from: "        - 'off' (default, no extra requirement) | 'encourage' (the residents decide by implementation\n          difficulty whether to formalize in Lean; once a Lean run passes, their unanimous vote becomes\n          a FIDELITY review — do the Lean definitions/objects/conditions/assumptions/conclusion match\n          the proposition as stated) | 'require' (same, plus a gate: a unanimous true/false verdict is",
+    to: "        - 'off' (default, no extra requirement) | 'encourage' (the residents decide by implementation\n          difficulty whether to formalize in Lean; once a Lean run passes, their unanimous vote becomes\n          a FIDELITY review — do the Lean definitions/objects/conditions/assumptions/conclusion match\n          the proposition as stated) | 'forced' (same, plus a gate: a unanimous true/false verdict is",
+  },
+  {
+    name: 'v4-formal-report-tool-hidden',
+    preset: 'vibe-math-v4', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: 'the formal-report tool must be named in the persona (it is the coordinator-facing Lean view)',
+    from: '        - vibe_v4_formal_report — human-readable Lean formal-verification mirror (mode, Lean-passed',
+    to: '        - vibe_v4_formal_reportX — human-readable Lean formal-verification mirror (mode, Lean-passed',
+  },
+
+  // ── v5 ─────────────────────────────────────────────────────────────────────
+  {
+    name: 'v5-prefix-text-drift',
+    preset: 'vibe-math-v5', file: 'agent.cordis.yml', nth: 'second', expect: 2,
+    guarantee: 'prefix and text must stay identical apart from line 0 (old and new hosts must see the same surface)',
+    from: 'TRUST RULE: only Verified/',
+    to: 'TRUST RULE (amended): only Verified/',
+  },
+  {
+    name: 'v5-tool-renamed-in-plugin',
+    preset: 'vibe-math-v5', file: 'vibe-math-v5.js', nth: 'first', expect: 1,
+    guarantee: 'renaming a registered tool must be caught (the persona still advertises the old name)',
+    from: "  registerTool('vibe_v5_meeting',",
+    to: "  registerTool('vibe_v5_meeting2',",
+  },
+  {
+    name: 'v4-usage-advertises-phantom-subcommand',
+    preset: 'vibe-math-v4', file: 'vibe-math-v4.js', nth: 'first', expect: 1,
+    guarantee: 'the unknown-subcommand usage string must not advertise a subcommand that no branch implements',
+    from: "usage:'configure|start|resume|pause|abort|status|report|message <to|all> <content>|meeting|members|add|remove|set'",
+    to: "usage:'configure|start|resume|pause|abort|status|report|message <to|all> <content>|meeting|members|add|remove|scan|set'",
+  },
+  {
+    name: 'v4-hint-advertises-unimplemented-subcommand',
+    preset: 'vibe-math-v4', file: 'vibe-math-v4.js', nth: 'first', expect: 1,
+    guarantee: 'the typing hint must not advertise a subcommand the handler does not implement',
+    from: "message <to|all> <content>|meeting|members|add|remove|set]'",
+    to: "message <to|all> <content>|meeting|add|remove|set]'",
+  },
+  {
+    name: 'v5-persona-slash-list-drops-add-remove',
+    preset: 'vibe-math-v5', file: 'agent.cordis.yml', nth: 'all', expect: 2,
+    guarantee: "the persona's /v5 list must match the command hint (a human reading the persona must see every subcommand)",
+    from: 'meeting|hire|fire|add|remove|set)',
+    to: 'meeting|hire|fire|set)',
+  },
+]
+
+let ok = 0
+let bad = 0
+console.log('')
+console.log('-- persona surface sensitivity probes --')
+console.log('(a probe passes when breaking the guarantee turns audit-persona-surface.test.mjs RED)')
+console.log('')
+
+for (const p of probes) {
+  const root = prepareRoot()
+  const target = join(root, p.preset, p.file)
+  const original = readFileSync(target, 'utf8')
+  // The repo's YAML files are CRLF; anchors are written with \n. Normalise both directions so
+  // a multi-line anchor matches regardless of the checkout's line endings.
+  const eol = original.includes('\r\n') ? '\r\n' : '\n'
+  const from = p.from.split('\n').join(eol)
+  const to = p.to.split('\n').join(eol)
+  p.from = from
+  p.to = to
+  const occurrences = original.split(p.from).length - 1
+  if (occurrences !== p.expect) {
+    console.error(`  SETUP-FAIL - ${p.name}: anchor matched ${occurrences} times (need ${p.expect})`)
+    bad++
+    rmSync(root, { recursive: true, force: true })
+    continue
+  }
+  let mutated
+  if (p.nth === 'all') mutated = original.split(p.from).join(p.to)
+  else if (p.nth === 'first') mutated = original.replace(p.from, p.to)
+  else if (p.nth === 'second') {
+    const i = original.indexOf(p.from)
+    const j = original.indexOf(p.from, i + 1)
+    mutated = original.slice(0, j) + p.to + original.slice(j + p.from.length)
+  } else throw new Error('unknown nth ' + p.nth)
+
+  if (mutated === original) {
+    console.error(`  SETUP-FAIL - ${p.name}: the mutation is a no-op`)
+    bad++
+    rmSync(root, { recursive: true, force: true })
+    continue
+  }
+  if (p.file.endsWith('.yml') && !yamlStillHasPersona(mutated)) {
+    console.error(`  SETUP-FAIL - ${p.name}: the mutated persona no longer has its two literal blocks (unfair mutation)`)
+    bad++
+    rmSync(root, { recursive: true, force: true })
+    continue
+  }
+  writeFileSync(target, mutated, 'utf8')
+
+  if (p.file.endsWith('.js')) {
+    const chk = spawnSync(process.execPath, ['--check', target], { encoding: 'utf8' })
+    if (chk.status !== 0) {
+      console.error(`  SETUP-FAIL - ${p.name}: the mutated copy has a syntax error:\n` + String(chk.stderr || '').split('\n').slice(0, 4).join('\n'))
+      bad++
+      rmSync(root, { recursive: true, force: true })
+      continue
+    }
+  }
+
+  const r = runSuite(root)
+  if (r.status === null) {
+    console.error(`  SETUP-FAIL - ${p.name}: the suite could not be started (${String(r.error && r.error.message)})`)
+    bad++
+    rmSync(root, { recursive: true, force: true })
+    continue
+  }
+  if (r.status !== 0) {
+    const firstFail = (r.out.split('\n').find((l) => l.trim().startsWith('FAIL')) || '').trim().slice(0, 110)
+    ok++
+    console.log(`  ok - ${p.name} [${p.preset}] => suite went RED as required  [${p.guarantee}]`)
+    if (firstFail) console.log(`         ${firstFail}`)
+  } else {
+    bad++
+    console.error(`  BLIND SPOT - ${p.name} [${p.preset}] => suite stayed GREEN, so it does NOT detect: ${p.guarantee}`)
+  }
+  rmSync(root, { recursive: true, force: true })
+}
+
+console.log('')
+console.log(`persona sensitivity: ${ok} probes detected the break, ${bad} problems`)
+if (bad) process.exit(1)
+console.log('ALL PERSONA PROBES RED AS REQUIRED')
+process.exit(0)

package/audit-persona-surface.test.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * PERSONA SURFACE — prompt/allocation consistency for the four presets.
+ *
+ * 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. registered \ mentioned equals an explicit, reviewed snapshot — so adding a tool
+ *      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 } 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 this file's own directory, 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: 25,
+    // member-facing write-lock / scheduler-metadata tools; the v2 coordinator never
+    // writes Markdown itself, so they stay out of its persona.
+    undocumented: [],
+    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib'], extra: [] },
+  },
+  {
+    dir: 'vibe-math-v3',
+    js: 'vibe-math-v3.js',
+    prefix: 'vibe_math_',
+    tools: 33,
+    undocumented: ['vibe_math_claim_write', 'vibe_math_release_write', 'vibe_math_sync_meta'],
+    lean: { tools: ['vibe_math_lean_run', 'vibe_math_lean_archive', 'vibe_math_lean_lib'], extra: [] },
+  },
+  {
+    dir: 'vibe-math-v4',
+    js: 'vibe-math-v4.js',
+    prefix: 'vibe_v4_',
+    tools: 32,
+    // resident-facing tools (mail, library cards, task board, write lock). The
+    // coordinator drives residents through vibe_v4_message / _meeting / _add_member.
+    undocumented: [
+      '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',
+    ],
+    lean: { tools: ['vibe_v4_lean_run', 'vibe_v4_lean_archive', 'vibe_v4_lean_lib'], extra: ['vibe_v4_formal_report'] },
+  },
+  {
+    dir: 'vibe-math-v5',
+    js: 'vibe-math-v5.js',
+    prefix: 'vibe_v5_',
+    tools: 35,
+    // member- and academician-facing tools; the office (main agent) holds only the
+    // institute-level controls plus the hiring authority.
+    undocumented: [
+      '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',
+    ],
+    lean: { tools: ['vibe_v5_lean_run', 'vibe_v5_lean_archive', 'vibe_v5_lean_lib'], extra: [] },
+  },
+]
+
+const LEAN_PARAMS = ['formalVerify', 'leanCommand', 'leanArgs', 'leanTimeoutMs']
+
+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 -------------------------------------------------
+  const registered = new Set()
+  for (const m of src.matchAll(/registerTool\(\s*'([A-Za-z0-9_]+)'/g)) registered.add(m[1])
+  eq(registered.size, P.tools, `${P.dir}: registered tool count changed (update this snapshot deliberately)`)
+
+  // ---- 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`.
+    const re = new RegExp('\\b' + P.prefix.replace(/_$/, '') + '_[A-Za-z0-9_]+', '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 undocumented = [...registered].filter((n) => !mentioned.has(n)).sort()
+    eq(undocumented, [...P.undocumented].sort(), `${P.dir} [${key}]: undocumented-tool snapshot changed`)
+  }
+
+  // ---- 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'))
+  if (personaEnum && personaEnum[1].includes('|')) {
+    const personaCmds = cmdsFrom(personaEnum[1].replace(/^\s*\/[a-z0-9]+\s+/, ''))
+    if (personaCmds.length) {
+      eq(personaCmds.filter((c) => !hinted.includes(c)).sort(), [], `${P.dir}: the persona enumerates slash subcommand(s) the hint does not know`)
+      if (!/\.\.\./.test(personaEnum[1]) && !hintOpen) eq(personaCmds.slice().sort(), hinted.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 })
+    writeFileSync(join(corpusDir, 'persona-corpus.md'), md.join('\n'), 'utf8')
+    writeFileSync(join(corpusDir, 'persona-corpus.json'), JSON.stringify({ presets: rows }, null, 2) + '\n', 'utf8')
+  }
+  // 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)