spexcode 0.2.7 → 0.3.0

package/spec-cli/src/issues.ts

@@ -3,7 +3,7 @@
 // stored — the local git store ([[local-issues]]) or a remote forge (spec-forge) — is a per-issue property
 // (`store`), not a project mode: a project holds both at once, mixed. This module owns the core type, the
 // forge→Issue translation (the ONLY place a host's node-naming conventions become `nodes[]` — platform
-// differences stay at the adapter boundary), the merged read every surface consumes (CLI `spex issues`,
+// differences stay at the adapter boundary), the merged read every surface consumes (CLI `spex issue ls`,
 // GET /api/issues, the board fold), the STORE-ROUTED reply/close verbs, and the CLI itself. Content writes are
 // owned per store: local ones live in localIssues.ts; a forge write goes through the driver's write verbs
 // (createIssue/createComment/closeIssue — the driver stays the only network toucher; the tracer stays read-only).
@@ -26,7 +26,7 @@ export type Reply = {
   body: string
   rid?: string            // stable per-remark id; a reply is a remark iff this is set. Ref: `<thread-id>#<rid>`
   targetCodeSha?: string  // the reading/codeSha the remark was authored against (worktree HEAD by default)
-  resolved?: boolean      // the ONE mutable teeth bit — false at author, true after a deliberate `spex resolve`
+  resolved?: boolean      // the ONE mutable teeth bit — false at author, true after a deliberate `spex remark resolve`
   resolvedAt?: string
   resolvedBy?: string
 }
@@ -41,7 +41,7 @@ export type Issue = {
   created: string
   body: string
   replies: Reply[]
-  evidence: string[] // yatsu content-addressed blob hashes — the typed cross-node finding reference
+  evidence: string[] // content-addressed evidence hashes — the typed cross-node finding reference
   url?: string       // a forge permalink; a local issue has none
 }
 
@@ -64,7 +64,7 @@ function forgeIssueBody(concern: string, body: string | undefined, nodes: string
   return [
     (body || `(no detail given — ${concern})`).trim(),
     nodes.length ? `Spec: ${nodes.join(', ')}` : '',
-    evidence.length ? `Evidence: ${evidence.join(', ')} (yatsu blob hashes)` : '',
+    evidence.length ? `Evidence: ${evidence.join(', ')} (evidence content hashes)` : '',
   ].filter(Boolean).join('\n\n')
 }
 
@@ -137,7 +137,7 @@ export function fromForge(slice: ForgeSlice, nodeIds: string[]): Issue[] {
 // freshness — the server passes the resident cache's state (instant, background reconcile), the CLI a
 // live pull — so the merge itself stays pure. Eval-remark threads are SPLIT OUT read-time (isEvalConcern):
 // they are the eval scoreboard's data, not issues, so every issue surface this feeds — the Threads tab, the
-// board issue badge, the `spex issues` drain — is free of them by construction (they reach the EVAL side
+// board issue badge, the `spex issue ls` drain — is free of them by construction (they reach the EVAL side
 // through loadEvalRemarkTracks / the reading overlay instead).
 export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue[] {
   const remote = forge ? fromForge(forge, nodeIds) : []
@@ -147,7 +147,7 @@ export function mergedIssues(forge: ForgeSlice | null, nodeIds: string[]): Issue
 }
 
 // @@@ createIssue - the ONE creation port, store-routed ([[issues]]): the dashboard's New form
-// (POST /api/issues) and `spex issues open [--store <store>]` run this SAME routine. Default local commits
+// (POST /api/issues) and `spex issue open [--store <store>]` run this SAME routine. Default local commits
 // to the trunk store; a forge store creates the REAL forge issue through that store's driver, its body
 // carrying the `Spec: <nodes>` marker so the existing tracer read links it straight back — no promote
 // round-trip needed when the concern is born forge-visible.
@@ -197,7 +197,7 @@ export async function promote(id: string, opts: { author?: string } = {}): Promi
   const body = [
     t.body,
     t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
-    t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (yatsu blob hashes)` : '',
+    t.evidence.length ? `\nEvidence: ${t.evidence.join(', ')} (evidence content hashes)` : '',
     `\n---\nPromoted from the local issue \`${id}\` (opened by ${t.by} @ ${t.created}; promoted by ${author}).`,
   ].filter(Boolean).join('\n')
   const { number, url } = await driver.createIssue({ title: t.concern, body })
@@ -254,23 +254,87 @@ const fl = (args: string[], name: string): string | undefined => {
 }
 const hasFlag = (args: string[], name: string) => args.includes(`--${name}`)
 
-// `spex issues …` — the ONE issues surface. Bare (with filters) it is THE read over every store: the
-// drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all] [--json]`. A write
-// first-positional (open|reply|on|off|status|nudge — localIssues.ts) routes to the store's
-// write verbs (open and reply are themselves store-routed: `open --store <host>` / a `<host>#<n>` id go
-// through the driver); `close` is the store-routed lifecycle verb (the SAME closeIssue the dashboard's
-// Close button calls); `promote` is the one cross-store verb. The list imposes NO salience ranking —
-// replies are a signal the drain WEIGHS by judgment, never an automatic priority
-// order. The forge slice is a LIVE pull; an unreachable forge degrades loudly to local-only (one stderr
-// note) — local reading never hostages on a network.
+// the CLI's live forge pull — `ls` and `show` own their freshness (a live driver read), degrading LOUDLY
+// to local-only (one stderr note) when the forge is unreachable: local reading never hostages on a network.
+async function liveForgeSlice(verb: string): Promise<ForgeSlice | null> {
+  try {
+    const host = resolveForgeHost()
+    const driver = forgeDriverFor(host)
+    if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
+    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
+    return { host: driver.host, state: { issues, prs } }
+  } catch (e) {
+    console.error(`spex issue ${verb}: forge unreachable — local only (${e instanceof Error ? e.message.split('\n')[0] : e})`)
+    return null
+  }
+}
+
+// the single-issue read behind `spex issue show` AND `GET /api/issues/:id` — find the thread in the SAME
+// merged, eval-remark-free read every issue surface consumes (never a second lookup path: an eval-remark
+// thread is not an issue, so `show` can't see one either). A local id needs no forge slice; a forge id
+// (`<host>#<n>`) reads from the caller-supplied slice (live pull on the CLI, resident cache on the server).
+export function findIssue(id: string, forge: ForgeSlice | null, nodeIds: string[]): Issue | undefined {
+  return mergedIssues(id.includes('#') ? forge : null, nodeIds).find((i) => i.id === id)
+}
+
+function renderIssue(t: Issue): string {
+  const L: string[] = []
+  L.push(`${t.concern}  [${t.id}]`)
+  L.push(`  ${[t.store, t.status, t.nodes.length ? `re: ${t.nodes.join(', ')}` : '', t.by ? `by ${t.by}` : '', t.created].filter(Boolean).join('  ·  ')}`)
+  if (t.url) L.push(`  ${t.url}`)
+  if (t.evidence.length) L.push(`  evidence: ${t.evidence.join(', ')}`)
+  L.push('', t.body)
+  for (const r of t.replies) {
+    L.push('', `── ${isRemark(r) ? `remark ${t.id}#${r.rid}${r.resolved ? ` (resolved by ${r.resolvedBy})` : ' (unresolved)'}` : 'reply'}: ${r.by} @ ${r.at} ──`)
+    L.push(r.body)
+  }
+  return L.join('\n')
+}
+
+// `spex issue <verb>` — the ONE issue surface, a noun drawer ([[cli-surface]]). `ls` is THE read over
+// every store: the drain view a supervisor/human works from, `[--node id] [--store local|<host>] [--all]
+// [--json]`; `show <id>` is the single-thread detail (the same read GET /api/issues/:id serves). The
+// write verbs (open|reply — localIssues.ts) are store-routed (`open --store <host>` / a `<host>#<n>` id
+// go through the driver); `close` is the store-routed lifecycle verb (the SAME closeIssue the dashboard's
+// Close button calls); `promote` is the one cross-store verb; `links` is the read-only forge→spec trace
+// (spec-forge). The list imposes NO salience ranking — replies are a signal the drain WEIGHS by judgment,
+// never an automatic priority order. The forge slice is a LIVE pull that degrades loudly to local-only.
+// (`nudge` left this drawer for `spex internal nudge` — only the post-merge hook calls it; the old
+// on|off|status toggle verbs are gone — the switch is the `issues.enabled` settings key.)
 export async function runIssues(args: string[]): Promise<number> {
+  // the drawer's READ verbs (ls/show) surface a store failure exactly as the writes do
+  // ([[issues-store-rename]]'s both-exist teeth): one clean `spex issue: <message>` line + exit 1, never a
+  // raw stack — the message carries the repair, the stack is internals. The verbs that already catch with
+  // a more specific prefix (open/reply/close/promote) return before this guard ever sees their errors.
+  try { return await issueVerbs(args) }
+  catch (e) { console.error(`spex issue: ${e instanceof Error ? e.message : e}`); return 1 }
+}
+async function issueVerbs(args: string[]): Promise<number> {
   if (ISSUE_WRITE_SUBS.has(args[0])) return runIssueWrite(args)
+  if (args[0] === 'on' || args[0] === 'off' || args[0] === 'status') {
+    // v0.3.0 signpost — report the new home, never run ([[cli-surface]]: a removed spelling only points).
+    console.error(`spex: \`spex issue ${args[0]}\` was removed in v0.3.0 — the switch is the \`issues.enabled\` key in spexcode.json (edit the JSON; \`spex guide settings\` documents it, \`spex doctor\` reports its state)`)
+    return 2
+  }
+  if (args[0] === 'show') {
+    const id = args[1]
+    if (!id || id.startsWith('--')) { console.error('usage: spex issue show <issue-id> [--json]   (a local id, or a forge id like github#12)'); return 2 }
+    const nodeIds = loadSpecsLite().map((s) => s.id)
+    const t = findIssue(id, id.includes('#') ? await liveForgeSlice('show') : null, nodeIds)
+    if (!t) { console.error(`spex issue show: no issue '${id}' (see \`spex issue ls --all\`)`); return 1 }
+    console.log(hasFlag(args, 'json') ? JSON.stringify(t, null, 2) : renderIssue(t))
+    return 0
+  }
+  if (args[0] === 'links') {
+    const { runIssueLinks } = await import('../../spec-forge/src/cli.js')
+    return runIssueLinks(args.slice(1))
+  }
   if (args[0] === 'close') {
     // the CLI leg of the ONE close verb ([[issues]] closeIssue — the same routing POST /api/issues/:id/close
     // runs): a local id resolves the thread `landed`, a forge id (`<host>#<n>`) closes the remote issue
     // through the driver. Lifecycle on the issue object, never node state.
     const id = args[1]
-    if (!id || id.startsWith('--')) { console.error('usage: spex issues close <issue-id>   (a local id, or a forge id like github#12)'); return 2 }
+    if (!id || id.startsWith('--')) { console.error('usage: spex issue close <issue-id>   (a local id, or a forge id like github#12)'); return 2 }
     try {
       const r = await closeIssue(id)
       console.log(r.store === 'local'
@@ -278,37 +342,29 @@ export async function runIssues(args: string[]): Promise<number> {
         : `closed '${id}' on ${r.store}${r.url ? `  ${r.url}` : ''}`)
       return 0
     } catch (e) {
-      console.error(`spex issues close: ${e instanceof Error ? e.message : e}`)
+      console.error(`spex issue close: ${e instanceof Error ? e.message : e}`)
       return 1
     }
   }
   if (args[0] === 'promote') {
     const id = args[1]
-    if (!id || id.startsWith('--')) { console.error('usage: spex issues promote <local-issue-id>'); return 2 }
+    if (!id || id.startsWith('--')) { console.error('usage: spex issue promote <local-issue-id>'); return 2 }
     try {
       const r = await promote(id)
       console.log(`promoted '${id}' → ${r.host}#${r.number}  ${r.url}\n  local thread closed landed (permalink recorded in its reply trail)`)
       return 0
     } catch (e) {
-      console.error(`spex issues promote: ${e instanceof Error ? e.message : e}`)
+      console.error(`spex issue promote: ${e instanceof Error ? e.message : e}`)
       return 1
     }
   }
-  if (args[0] && !args[0].startsWith('--')) {
-    console.error(`spex issues: unknown subcommand '${args[0]}'`)
+  if (args[0] !== 'ls') {
+    console.error(`spex issue: unknown verb '${args[0]}' — ls | show | open | reply | close | promote | links  (spex help issue)`)
     return 2
   }
+  args = args.slice(1)
   const nodeIds = loadSpecsLite().map((s) => s.id)
-  let forge: ForgeSlice | null = null
-  try {
-    const host = resolveForgeHost()
-    const driver = forgeDriverFor(host)
-    if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
-    const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
-    forge = { host: driver.host, state: { issues, prs } }
-  } catch (e) {
-    console.error(`spex issues: forge unreachable — listing local only (${e instanceof Error ? e.message.split('\n')[0] : e})`)
-  }
+  const forge = await liveForgeSlice('ls')
   let issues = mergedIssues(forge, nodeIds)
   const node = fl(args, 'node')
   const store = fl(args, 'store')
@@ -325,6 +381,6 @@ export async function runIssues(args: string[]): Promise<number> {
     if (p.replies.length) console.log(`    ${p.replies.length} reply(ies) in thread`)
     if (p.url) console.log(`    ${p.url}`)
   }
-  if (!issuesEnabled()) console.log('\n(the issues workflow is OFF — `spex issues on` to re-enable writes/nudges)')
+  if (!issuesEnabled()) console.log('\n(the issues workflow is OFF — set `"issues": { "enabled": true }` in spexcode.json to re-enable writes/nudges)')
   return 0
 }

package/spec-cli/src/layout.ts

@@ -9,7 +9,7 @@ type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
   mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
   branchPrefix?: string            // how a branch names its node (default: "node/")
-  preset?: string                  // the SELECTED init preset — which cumulative .config tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
+  preset?: string                  // the SELECTED init preset — which cumulative .plugins tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
   // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
   // tracked now (one residence behavior: the per-clone exclude, plus the content filter for a mixed
   // contract file), so the field is IGNORED with a loud non-fatal notice (materialize's retiredAxisNotice);
@@ -47,7 +47,7 @@ type Config = {
     }
   }
   issues?: {
-    enabled?: boolean                // the [[local-issues]] issues-workflow on/off switch (default ON). OFF silences the post-merge nudge + hides the dashboard view; flip with `spex issues on|off`. (Pre-rename `proposals.enabled` still reads — localIssues.ts issuesEnabled.)
+    enabled?: boolean                // the [[local-issues]] issues-workflow on/off switch (default ON). OFF silences the post-merge nudge + hides the dashboard view; flip by editing this key (no CLI toggle verb — v0.3.0). A legacy `proposals.enabled` is NOT read; `spex doctor` reports it.
   }
   forge?: {
     host?: string                    // explicit forge host id ('github'|'gitlab'|…) overriding the origin-remote derivation ([[forge-host]] — read by spec-forge drivers.ts resolveForgeHost, not here). A project fact → committed spexcode.json.
@@ -130,7 +130,7 @@ export function mainCheckout(proj?: string): string {
 // agents in one folder never clobber, and grouped PER PROJECT (mirroring Claude's ~/.claude/projects/<enc>/)
 // so the board enumerates ONE directory. This is the single seam that knows where the store sits; sessions.ts
 // and the shell hooks resolve through the SAME scheme (the hooks reimplement it in bash, so any change here
-// must be mirrored in .config/core/*/). SPEXCODE_HOME overrides the root for test isolation.
+// must be mirrored in .plugins/core/*/). SPEXCODE_HOME overrides the root for test isolation.
 export function spexcodeHome(): string {
   return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
 }
@@ -151,7 +151,7 @@ export function runtimeRoot(proj?: string): string {
   return join(spexcodeHome(), 'projects', encodeProject(dirname(gcd)))
 }
 // the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
-// products that are a pure function of ONE tree's .config (hooks-manifest, content-hash, plugin-folders).
+// products that are a pure function of ONE tree's .plugins (hooks-manifest, content-hash, plugin-folders).
 // Slotted per tree exactly like sessions/<id> is slotted per session: the old single global file made the
 // last-materialized tree win, so dispatch ran tree A's compiled hook set inside tree B's sessions
 // ([[hook-dispatch]]). Key = the sessions encodeProject transform over `rev-parse --show-toplevel`, the
@@ -198,7 +198,7 @@ export type RawRecord = {
 //       `SPEXCODE_SESSION_ID`.
 // Claude is UNCHANGED: its `sessionEnvVar` (CLAUDE_CODE_SESSION_ID) already EQUALS its record id, so tier (1)
 // resolves to that very id — the same value `SPEXCODE_SESSION_ID` would have returned; there is no shared
-// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-yatsu
+// app-server to contaminate it. No worktree fallback. (sessions.ts's `ownSessionId` delegates here; spec-eval
 // reads it to resolve the current node.)
 export function envSessionId(): string | null {
   for (const h of HARNESSES) {

package/spec-cli/src/lint.ts

@@ -15,7 +15,7 @@ export type LintConfig = {
   maxChildren: number        // breadth budget: warn at >= this many direct children
   driftErrorThreshold: number// commit-local gate HARD-BLOCKS a commit touching a node >= this many commits behind
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
-  scenarioTags: string[]     // the closed vocabulary a yatsu scenario's `tags:` must draw from; extend it to mint a new tag
+  scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
@@ -55,7 +55,7 @@ export function normalizeConfig(cfg: LintConfig): LintConfig {
 }
 
 // the source-file matcher, built from the configurable `sourceExtensions` knob. Coverage uses it to decide
-// which tracked files must be governed; yatsu's `yatsu-uncovered` reuses THE SAME knob so ONE setting
+// which tracked files must be governed; eval lint's `eval-coverage` reuses THE SAME knob so ONE setting
 // defines "source" for both coverage axes — a non-web project (Rust/Go/Python .rs/.go/.py) sets it once and
 // both the coverage warning and the loss-signal blind-spot check follow, with no second web-only allowlist.
 export const sourceExtRe = (extensions: string[]) => new RegExp(`\\.(${extensions.join('|')})$`)
@@ -140,7 +140,7 @@ export async function specLint(): Promise<Finding[]> {
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
       owners.set(f, [...(owners.get(f) ?? []), s.id])
     }
-    // one-govern: a node is source of truth for at most ONE file, so drift/yatsu/ack have a single
+    // one-govern: a node is source of truth for at most ONE file, so drift/eval/ack have a single
     // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
     // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
     if (s.code.length > 1)
@@ -148,7 +148,7 @@ export async function specLint(): Promise<Finding[]> {
   }
   // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
-  // related, not govern (see [[governed-related]]). It carries coverage but never drift/yatsu.
+  // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
   const claimed = new Set<string>(owners.keys())
   for (const s of specs) for (const f of s.related) {
     if (!existsSync(join(root, f)))
@@ -156,6 +156,71 @@ export async function specLint(): Promise<Finding[]> {
     claimed.add(f)
   }
 
+  // id-format: a node id (its leaf dir basename) passes an EXACT per-character whitelist — an ascii char
+  // must be [a-z0-9-]; a non-ascii char must be a unicode letter/number (judged on NFC, the mint's
+  // canonical form) — and is UNIQUE tree-wide (ERROR). This is THE id vocabulary, defined once (the
+  // spec-lint node's rule table) and referenced by [[mentions]] / [[id-url-safe]]: CJK and every other
+  // letter script is first-class, exactly what the script-agnostic resolve machinery already accepts.
+  // Everything else is forbidden by construction, no heuristics — space, '/', uppercase Latin (lowercase
+  // is the Latin norm), control chars, and '_' (reserved as the mint's parent-qualification join; a '_'
+  // inside a basename would make that join ambiguous). One optional leading dot is allowed — the
+  // reflexive plugin root `.plugins` is dot-prefixed by design. Uniqueness is what keeps the leaf THE id:
+  // on a collision the mint must parent-qualify with `_`, so every surface suddenly speaks a longer id
+  // than the dir name — legal to the machinery, illegible to people.
+  const ID_RE = /^\.?(?:[a-z0-9-]|(?![\x00-\x7F])[\p{L}\p{N}])+$/u
+  const leafOf = (p: string) => { const segs = p.split('/'); return segs[segs.length - 2] }
+  const byLeaf = new Map<string, string[]>()
+  for (const s of specs) {
+    const leaf = leafOf(s.path)
+    byLeaf.set(leaf, [...(byLeaf.get(leaf) ?? []), s.path])
+    if (!ID_RE.test(leaf.normalize('NFC')))
+      out.push({ level: 'error', rule: 'id-format', spec: s.id, msg: `node dir '${leaf}' is not a valid id — each char is ascii [a-z0-9-] or a non-ascii unicode letter/number (one optional leading dot); space, '/', '_', uppercase Latin and control chars are forbidden; rename the directory` })
+  }
+  for (const [leaf, paths] of byLeaf) {
+    if (paths.length > 1)
+      out.push({ level: 'error', rule: 'id-format', msg: `leaf id '${leaf}' names ${paths.length} nodes [${paths.map((p) => p.replace(/\/spec\.md$/, '')).join(', ')}] — a leaf id is unique tree-wide; rename all but one` })
+  }
+
+  // confusable-id: two leaf ids one edit apart read as the same word (WARN — a typo in either reaches a
+  // real, wrong node). Deliberately conservative: distance exactly 1, so hierarchy naming like
+  // graph/graph-delivery (a whole suffix apart) and verb pairs like evidence-put/evidence-get (distance 2)
+  // never warn — better to miss a borderline pair than to nag legitimate siblings. Distance is measured
+  // in CODE POINTS, script-agnostic: a CJK pair one character apart (节点/结点 — a classic homophone
+  // IME slip) warns like an ascii pair, an astral char counts as one edit (not two surrogate units), and
+  // a pure-CJK id can never sit one edit from a pure-ascii one.
+  const lev1 = (a: string, b: string): boolean => {
+    const A = [...a], B = [...b]
+    if (Math.abs(A.length - B.length) > 1 || a === b) return false
+    let i = 0
+    while (i < A.length && i < B.length && A[i] === B[i]) i++
+    const rest = (x: string[], k: number) => x.slice(k).join('')
+    return rest(A, i + 1) === rest(B, i + 1) || rest(A, i + 1) === rest(B, i) || rest(A, i) === rest(B, i + 1)
+  }
+  const leaves = [...byLeaf.keys()]
+  for (let i = 0; i < leaves.length; i++) for (let j = i + 1; j < leaves.length; j++) {
+    if (lev1(leaves[i], leaves[j]))
+      out.push({ level: 'warn', rule: 'confusable-id', msg: `leaf ids '${leaves[i]}' and '${leaves[j]}' are one edit apart — easily confused; if they are distinct concepts, rename one to read apart` })
+  }
+
+  // mention: a `[[id]]` in a body must name a real node (ERROR — a dangling mention is a broken edge in
+  // the very graph the tree exists to keep honest). Checked against the SAME minted ids every other
+  // surface resolves ([[id-url-safe]]). Prose only: a fenced block or inline `code span` is sample text
+  // (`[[node]]`, `[[<id>]]` placeholders live there), not a reference.
+  const idSet = new Set(specs.map((s) => s.id))
+  const MENTION_RE = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/gu
+  for (const s of specs) {
+    let inFence = false
+    for (const rawLine of s.body.split('\n')) {
+      if (/^\s*```/.test(rawLine)) { inFence = !inFence; continue }
+      if (inFence) continue
+      const line = rawLine.replace(/`[^`]*`/g, '')
+      for (const m of line.matchAll(MENTION_RE)) {
+        if (!idSet.has(m[1]))
+          out.push({ level: 'error', rule: 'mention', spec: s.id, msg: `'${s.id}' mentions [[${m[1]}]] — no such node; retarget or drop it (backtick it if it is sample text)` })
+      }
+    }
+  }
+
   // living: a spec body describes the node's CURRENT intent — it is not a changelog. Version history
   // (every content commit, its reason/session/line-diff) is read from git and shown in the dashboard's
   // recent/history tabs, so a `## vN`-style heading in the body is duplicated, drift-prone state.
@@ -224,7 +289,7 @@ export async function specLint(): Promise<Finding[]> {
 
   // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's
   // version — a nudge that a dependency shifted. Same ancestry basis as govern drift, but WARN-only,
-  // never reaching the commit gate (driftGate reads govern) or yatsu. It is COMMON (shared substrate and
+  // never reaching the commit gate (driftGate reads govern) or eval freshness. It is COMMON (shared substrate and
   // faces change often without re-versioning every referrer), so per-file it is a wall; like
   // too-many-owners it collapses to ONE summary line, with the per-file detail riding the board
   // (relatedDriftFiles). It stays a soft edge, never a per-file interruption.
@@ -233,7 +298,7 @@ export async function specLint(): Promise<Finding[]> {
     const byNode = new Map<string, number>()
     for (const d of rd) byNode.set(d.id, (byNode.get(d.id) ?? 0) + 1)
     const worst = [...byNode].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([id, n]) => `${id}(${n})`).join(', ')
-    out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no yatsu). Most: ${worst}` })
+    out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no eval staleness). Most: ${worst}` })
   }
 
   return out
@@ -242,13 +307,13 @@ export async function specLint(): Promise<Finding[]> {
 export const DRIFT_GUIDANCE = `DRIFT — a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth
 broke along  raw intent → expanded spec → code: link → code structure → implementation, fix THAT layer.
 
-  Inspect:  spex lint                                                       which files, against which spec
+  Inspect:  spex spec lint                                                       which files, against which spec
             the node's spec.md                                             its raw source + expanded spec
             git diff $(git log -1 --format=%H -- <spec.md>)..HEAD -- <file>   the code delta since the spec
 
 Diagnose, then apply the one honest remedy:
   • contract changed        → rewrite the spec body to the new intent, commit it (re-versions the node)
-  • only mechanics changed  → spex ack <node>   "checked — spec still valid"   (give a real reason)
+  • only mechanics changed  → spex spec ack <node>   "checked — spec still valid"   (give a real reason)
   • implementation is WRONG → the spec is right; fix the CODE back toward it, then ack
   • wrong code: link        → the node shouldn't own this file (or owns it too broadly); fix frontmatter
   • expanded spec ≠ raw     → the spec drifted from human intent; fix the expanded spec to serve the raw