spexcode 0.2.3 → 0.2.5

package/spec-yatsu/src/evaltab.ts

@@ -4,7 +4,7 @@ import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { loadEvalRemarkTracks, trackKey, type RemarkTrack, type Issue, type Reply } from '../../spec-cli/src/issues.js'
 import { yatsuNodes, type YatsuNode } from './yatsu.js'
 import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, type Verdict, type EvidenceKind, type Retraction } from './sidecar.js'
-import { staleAxes, codeDrift, type StaleAxis } from './freshness.js'
+import { staleAxes, codeDrift, contentProbeFor, type StaleAxis } from './freshness.js'
 import { scenarioIndex, type ScenarioIndex } from './scenariofresh.js'
 import { hasBlob, getBlob, MISS_BLOB } from './cache.js'
 
@@ -164,6 +164,9 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
   // one raw sidecar read: the effective readings feed the scoreboard rows below; the retraction events ride
   // along as the undo trace (newest-first, like the readings).
   const { readings: rawReadings, retractions } = readSidecar(ynode.sidecarPath)
+  // the off-history content fallback ([[yatsu-core]]): fed to both git axes so a rebased/folded-away
+  // anchor with byte-identical governed content reads fresh. Lazy — an in-history reading never probes.
+  const probe = contentProbeFor(root)
   const readings: EvalEntry[] = applyRetractions(rawReadings, retractions).map((r) => {
     // a scenario's own `code` is its freshness code axis when it declares one; else the whole node's list.
     const sc = byName.get(r.scenario)
@@ -172,9 +175,9 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
     // read-time overlay below; freshness never depends on that pin.
     const cf = sc?.code?.length ? sc.code : codeFiles
     const axes = staleAxes(r, cf, ynode.yatsuPath, idx, scidx,
-      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })))
+      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe)
     // when the code axis is stale, explain it: which of THIS reading's governed files moved, by how many commits.
-    const drift = axes.includes('code') ? codeDrift(idx, r.codeSha, cf) : []
+    const drift = axes.includes('code') ? codeDrift(idx, r.codeSha, cf, probe) : []
     // the reading's evidence list, each entry resolved to its live blob state; the primary (video-first, else
     // first) drives the scalar compat fields for single-evidence consumers.
     const evidence: EvidenceView[] = evidenceOf(r).map((e) => ({ hash: e.hash, kind: e.kind, state: hasBlob(e.hash) ? 'present' : 'miss' }))

package/spec-yatsu/src/filing.ts

@@ -1,5 +1,5 @@
 import { repoRoot, headSha } from '../../spec-cli/src/git.js'
-import { yatsuNodes } from './yatsu.js'
+import { yatsuNodes, resolveYatsuNode } from './yatsu.js'
 import { appendReading, readReadings, isJsonBlob, type Reading, type EvidenceKind } from './sidecar.js'
 import { putBlob } from './cache.js'
 
@@ -15,8 +15,11 @@ export function fileHumanReading(
   input: { scenario: string; status: 'pass' | 'fail'; note?: string; transcript?: string; by?: string },
 ): FileResult {
   const root = repoRoot()
-  const node = yatsuNodes(root).find((n) => n.id === nodeId)
-  if (!node) return { ok: false, error: `no yatsu node '${nodeId}' (a node needs a yatsu.md)` }
+  // the same loud resolution the CLI applies ([[yatsu-core]]): exact canonical id, else a unique bare
+  // leaf; an ambiguous leaf returns the candidate list instead of filing against an arbitrary node.
+  const res = resolveYatsuNode(yatsuNodes(root), nodeId)
+  if (!res.ok) return { ok: false, error: res.error }
+  const node = res.node
   const sc = node.scenarios.find((s) => s.name === input.scenario)
   if (!sc) return { ok: false, error: `'${nodeId}' has no scenario '${input.scenario}'` }
   if (input.status !== 'pass' && input.status !== 'fail') return { ok: false, error: 'status must be pass or fail' }
@@ -42,10 +45,12 @@ export function fileHumanReading(
 // The session that filed the LATEST reading for (node, scenario) — the ORIGINATOR an eval-comment thread
 // loops in on a reply ([[mentions]] implicit loop-in). Null when the node/scenario has no reading, or the
 // latest reading is legacy (no `by`). Store-agnostic: the caller resolves this id to a live session or nobody.
-export function evalReadingFiler(nodeId: string, scenario: string): string | null {
-  const root = repoRoot()
-  const node = yatsuNodes(root).find((n) => n.id === nodeId)
-  if (!node) return null
-  const forScenario = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
+// `root` defaults to the trunk; the loop-in chain also passes each LIVE session's worktree here, because an
+// in-flight reading (filed on an unmerged branch) is invisible to the trunk sidecar — exactly the
+// review-time case where the remark must still reach its filer ([[remark-polish]] strand 2).
+export function evalReadingFiler(nodeId: string, scenario: string, root: string = repoRoot()): string | null {
+  const res = resolveYatsuNode(yatsuNodes(root), nodeId)
+  if (!res.ok) return null
+  const forScenario = readReadings(res.node.sidecarPath).filter((r) => r.scenario === scenario)
   return forScenario.length ? forScenario[forScenario.length - 1].by ?? null : null
 }

package/spec-yatsu/src/freshness.ts

@@ -1,11 +1,67 @@
-import { ancestorsOf, inAncestors, type DriftIndex } from '../../spec-cli/src/git.js'
+import { git, headSha, ancestorsOf, inAncestors, type DriftIndex } from '../../spec-cli/src/git.js'
 import type { Reading } from './sidecar.js'
 import { isEvaluatorStale } from './evaluator.js'
-import { scenarioChangeCommits, type ScenarioIndex } from './scenariofresh.js'
+import { scenarioChangeCommits, scenarioBlocksAt, type ScenarioIndex } from './scenariofresh.js'
 
 // the CODE axis is touch-based (DriftIndex), so a code-file rename is out of scope — the same blind spot lint's code-drift has
 
-export type StaleAxis = 'code' | 'scenario' | 'evaluator' | 'remark'
+export type StaleAxis = 'code' | 'scenario' | 'evaluator' | 'remark' | 'anchor'
+
+// @@@ off-history content fallback - ancestry can't testify for a codeSha that isn't reachable from HEAD
+// (fold/rebase/squash-merge/cherry-pick all orphan the anchor), but the TREES still can: while the anchor
+// commit object exists locally, `git diff <anchor> HEAD` names exactly the paths whose content differs, so
+// a history rewrite that left governed content byte-identical reads FRESH instead of false-positive stale.
+// The probe is fed at the call sites (like the remark track) so the decision functions stay pure over their
+// inputs and the in-history fast path pays no extra git call; only when the commit object is truly gone
+// (gc'd orphan) does the conservative rule remain — surfaced as the 'anchor' axis, so "anchor lost" reads
+// differently from "content moved". No probe fed → the old always-conservative rule.
+export type ContentProbe = {
+  // paths whose content differs between the anchor commit's tree and HEAD's; null = anchor object gone
+  changedPaths(anchorSha: string): Set<string> | null
+  // did THIS scenario's semantic block (description+expected) move between anchor and HEAD ([[scenariofresh]])
+  scenarioDiffers(anchorSha: string, yatsuPath: string, scenario: string): boolean
+  // codeDrift's display detail: commits in anchor..HEAD touching path (floored at 1 — the content differs)
+  behind(anchorSha: string, path: string): number
+}
+
+// (anchor, HEAD) name two immutable trees, so entries never invalidate; the LRU only bounds memory.
+const diffMemo = new Map<string, Set<string> | null>()
+const behindMemo = new Map<string, number>()
+function memo<V>(m: Map<string, V>, k: string, build: () => V): V {
+  if (m.has(k)) { const v = m.get(k)!; m.delete(k); m.set(k, v); return v }
+  const v = build()
+  m.set(k, v)
+  if (m.size > 512) m.delete(m.keys().next().value!)
+  return v
+}
+
+export function contentProbeFor(root: string): ContentProbe {
+  let head: string | undefined
+  const headOf = () => (head ??= headSha(root))
+  return {
+    changedPaths(sha) {
+      return memo(diffMemo, `${root}\x1f${sha}\x1f${headOf()}`, () => {
+        try {
+          return new Set(git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--name-only', '--no-renames', sha, headOf()])
+            .split('\n').map((s) => s.trim()).filter(Boolean))
+        } catch { return null }   // the anchor commit object is gone — content can't testify
+      })
+    },
+    scenarioDiffers(sha, yatsuPath, scenario) {
+      const a = scenarioBlocksAt(root, sha, yatsuPath)
+      if (!a) return true   // yatsu.md unreadable at the anchor (renamed/absent) → can't prove → stale
+      return a.get(scenario) !== scenarioBlocksAt(root, headOf(), yatsuPath)?.get(scenario)
+    },
+    behind(sha, path) {
+      return memo(behindMemo, `${root}\x1f${sha}\x1f${headOf()}\x1f${path}`, () => {
+        try {
+          const n = Number(git(['-C', root, 'rev-list', '--count', `${sha}..${headOf()}`, '--', path]).trim())
+          return Number.isFinite(n) && n > 0 ? n : 1
+        } catch { return 1 }
+      })
+    },
+  }
+}
 
 // the REMARK axis's input ([[remark-teeth]]): the teeth read only the resolvable bit + when it was resolved,
 // not the whole remark — so freshness stays a PURE function, fed the scenario's remark track at the call
@@ -23,39 +79,51 @@ export function remarkStale(reading: { ts: string }, remarks: RemarkSignal[]): b
 
 // true iff some commit touched `path` that is NOT an ancestor of `sinceSha` — i.e. it lies in
 // `sinceSha..HEAD` by true DAG reachability, never a log-position/date compare (which under-reports on
-// branchy history). ONE conservative rule for an off-history `sinceSha` — whether rebased away (orphan)
-// or on a reachable-but-unmerged branch: we can't prove freshness from HEAD's history, so it reads
-// stale rather than silently pass.
-export function changedSince(idx: DriftIndex, sinceSha: string, path: string): boolean {
+// branchy history). An off-history `sinceSha` falls back to the content probe when one is fed (see
+// ContentProbe above); without a probe — or when the anchor object is gone — freshness can't be proven
+// from HEAD's history, so it reads stale rather than silently pass.
+export function changedSince(idx: DriftIndex, sinceSha: string, path: string, probe?: ContentProbe): boolean {
   const anc = ancestorsOf(idx, sinceSha)
-  if (!anc) return true
-  return (idx.fileCommits.get(path) ?? []).some((h) => !inAncestors(idx, anc, h))
+  if (anc) return (idx.fileCommits.get(path) ?? []).some((h) => !inAncestors(idx, anc, h))
+  const diff = probe?.changedPaths(sinceSha)
+  return diff ? diff.has(path) : true
 }
 
 // the code axis's DISPLAY detail: which governed files drifted since a reading, and by HOW MANY commits — so
 // a stale eval can say "EvalsFeed.jsx +3" instead of a bare "code moved". Same DAG reachability as
 // changedSince (a commit touching the file that is NOT an ancestor of the reading's sha lies in sinceSha..HEAD);
-// an off-history sinceSha counts every touch (conservative, matching changedSince's stale-rather-than-pass rule).
+// an off-history sinceSha reports through the same content fallback (only files whose content differs, counted
+// by rev-list); with no probe or a gone anchor it counts every touch (conservative, matching changedSince).
 // Reporting only — it never decides freshness (staleAxes does); it explains a decision already made.
-export function codeDrift(idx: DriftIndex, sinceSha: string, codeFiles: string[]): { file: string; behind: number }[] {
+export function codeDrift(idx: DriftIndex, sinceSha: string, codeFiles: string[], probe?: ContentProbe): { file: string; behind: number }[] {
   const anc = ancestorsOf(idx, sinceSha)
+  const diff = anc ? undefined : probe?.changedPaths(sinceSha)
   const out: { file: string; behind: number }[] = []
   for (const f of codeFiles) {
     const commits = idx.fileCommits.get(f) ?? []
-    const behind = anc ? commits.filter((h) => !inAncestors(idx, anc, h)).length : commits.length
+    const behind = anc ? commits.filter((h) => !inAncestors(idx, anc, h)).length
+      : diff ? (diff.has(f) ? probe!.behind(sinceSha, f) : 0)
+      : commits.length
     if (behind > 0) out.push({ file: f, behind })
   }
   return out
 }
 
-// scenario freshness is PER-SCENARIO, not per-file: a reading stales only when ITS OWN scenario block moved
-// (edited/added/removed) in scenarioSha..HEAD, never when a sibling in the same yatsu.md did. Reads exactly
-// like the code axis's changedSince — the per-scenario change-commits ([[scenariofresh]], rename-followed so a
-// bare git-mv reparent isn't a change) tested for ancestry — off-history codeSha → conservatively stale.
-function scenarioMoved(scIdx: ScenarioIndex, didx: DriftIndex, sinceSha: string, yatsuPath: string, scenario: string): boolean {
+// scenario freshness is PER-SCENARIO and SEMANTIC, not per-file: a reading stales only when ITS OWN
+// scenario's semantic block (description+expected — [[scenariofresh]]'s blockContent projection) moved in
+// scenarioSha..HEAD — never when a sibling in the same yatsu.md did, and never on a metadata-only edit
+// (tags/test/code/related). Reads exactly like the code axis's changedSince — the per-scenario
+// change-commits ([[scenariofresh]], rename-followed so a bare git-mv reparent isn't a change) tested for
+// ancestry — and an off-history codeSha takes the same content fallback at the same granularity and the
+// same projection: an unchanged yatsu.md clears it outright, a changed one stales only if THIS scenario's
+// semantic block differs between the anchor and HEAD.
+function scenarioMoved(scIdx: ScenarioIndex, didx: DriftIndex, sinceSha: string, yatsuPath: string, scenario: string, probe?: ContentProbe): boolean {
   const anc = ancestorsOf(didx, sinceSha)
-  if (!anc) return true
-  return scenarioChangeCommits(scIdx, yatsuPath, scenario).some((h) => !inAncestors(didx, anc, h))
+  if (anc) return scenarioChangeCommits(scIdx, yatsuPath, scenario).some((h) => !inAncestors(didx, anc, h))
+  const diff = probe?.changedPaths(sinceSha)
+  if (!diff) return true
+  if (!diff.has(yatsuPath)) return false   // whole file byte-identical → this block too
+  return probe!.scenarioDiffers(sinceSha, yatsuPath, scenario)
 }
 
 export function staleAxes(
@@ -65,10 +133,16 @@ export function staleAxes(
   didx: DriftIndex,
   scIdx: ScenarioIndex,
   remarks: RemarkSignal[] = [],
+  probe?: ContentProbe,
 ): StaleAxis[] {
   const axes: StaleAxis[] = []
-  if (codeFiles.some((f) => changedSince(didx, reading.codeSha, f))) axes.push('code')
-  if (scenarioMoved(scIdx, didx, reading.codeSha, yatsuPath, reading.scenario)) axes.push('scenario')
+  if (probe && !ancestorsOf(didx, reading.codeSha) && probe.changedPaths(reading.codeSha) === null) {
+    // the anchor commit object is GONE — neither git axis can testify; say that, not "content changed"
+    axes.push('anchor')
+  } else {
+    if (codeFiles.some((f) => changedSince(didx, reading.codeSha, f, probe))) axes.push('code')
+    if (scenarioMoved(scIdx, didx, reading.codeSha, yatsuPath, reading.scenario, probe)) axes.push('scenario')
+  }
   if (isEvaluatorStale(reading.evaluator)) axes.push('evaluator')
   if (remarkStale(reading, remarks)) axes.push('remark')
   return axes
@@ -81,6 +155,7 @@ export function isStale(
   didx: DriftIndex,
   scIdx: ScenarioIndex,
   remarks: RemarkSignal[] = [],
+  probe?: ContentProbe,
 ): boolean {
-  return staleAxes(reading, codeFiles, yatsuPath, didx, scIdx, remarks).length > 0
+  return staleAxes(reading, codeFiles, yatsuPath, didx, scIdx, remarks, probe).length > 0
 }

package/spec-yatsu/src/proof.ts

@@ -3,7 +3,7 @@ import { git, gitA, repoRoot, driftIndex, historyIndex, type ReviewDiffFile } fr
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { mainBranch } from '../../spec-cli/src/layout.js'
 import { reviewPayload } from '../../spec-cli/src/sessions.js'
-import { evalTimeline, evalContext, readBlobByHash, type EvalEntry } from './evaltab.js'
+import { evalTimeline, evalContext, readBlobByHash, type EvalEntry, type EvalTimeline } from './evaltab.js'
 import { isUiPath } from './cli.js'
 
 // ---- the model ----
@@ -112,7 +112,7 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   for (const [nid, files] of byNode) {
     const spec = specById.get(nid)
     const tl = await evalTimeline(nid, ctx)
-    const latest = latestPerScenario(tl.readings)
+    const latest = declaredLatest(tl)
     const readings = await Promise.all(latest.map(toProofReading))
     for (const r of latest) {
       total++
@@ -220,6 +220,17 @@ function latestPerScenario(readings: EvalEntry[]): EvalEntry[] {
   return out
 }
 
+// the DECLARED scenarios' latest reading — the SAME declared-bounded computation every other eval face reads
+// (score.jsx's scenarioStates for the node badge and the eval tab). A reading whose scenario is no longer in
+// yatsu.md is residual: the append-only sidecar still carries it, but it is not current loss, so it must not
+// become a proof reading card, a passed/total tick, or a node score. The proof was the one face driven by the
+// readings that happen to exist rather than the scenarios that are declared — this bounds it like the rest, so
+// a retired scenario's stale reading can't make the proof disagree with the dashboard (phantom card, off ribbon).
+export function declaredLatest(tl: EvalTimeline): EvalEntry[] {
+  const declared = new Set(tl.scenarios.map((s) => s.name))
+  return latestPerScenario(tl.readings).filter((r) => declared.has(r.scenario))
+}
+
 // ---- scoring (mirrors the dashboard's score.jsx vocabulary, on the EvalEntry shape) ----
 
 const verdictMark = (r: { verdict?: EvalEntry['verdict'] }) =>
@@ -234,7 +245,7 @@ function readingScore(r: EvalEntry): ScoreState {
 
 // worst-first aggregate over the latest reading per scenario: any fresh fail → fail; else any stale → grey
 // (✗ if any stale last-failed, else ✓); else any unscored scenario → empty; else every scenario fresh-passes.
-function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
+export function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
   if (!hasYatsu) return null
   if (!latest.length) return 'empty'
   if (latest.some((r) => r.fresh && verdictMark(r) === 'cross')) return 'fail'

package/spec-yatsu/src/scenariofresh.ts

@@ -1,27 +1,35 @@
 import { spawn } from 'node:child_process'
-import { gitA, headSha } from '../../spec-cli/src/git.js'
+import { git, gitA, headSha } from '../../spec-cli/src/git.js'
 import { parseScenarios } from './yatsu.js'
 
 // @@@ per-scenario content freshness — the SCENARIO axis, sub-file
 // A yatsu.md holds many scenarios, but a reading measures ONE. yatsu-core's contract says "a scenario is the
 // unit of measurement, so its freshness is its OWN — two scenarios stale independently." Git has no sub-file
-// history, so we build it: for each scenario NAME in a yatsu.md, the commits where THAT scenario's block
-// content changed (added / removed / edited), rename-followed. `scenarioMoved` then reads exactly like the
-// code axis's `changedSince` — a pure ancestry lookup over this per-scenario commit list — so editing one
-// scenario never re-stales its siblings (the file-granular bug this replaces).
+// history, so we build it: for each scenario NAME in a yatsu.md, the commits where THAT scenario's SEMANTIC
+// block content (description + expected — see blockContent) changed (added / removed / edited),
+// rename-followed. `scenarioMoved` then reads exactly like the code axis's `changedSince` — a pure ancestry
+// lookup over this per-scenario commit list — so editing one scenario never re-stales its siblings (the
+// file-granular bug this replaces), and retagging one never re-stales itself.
 
 const RS = '\x1e'
 
 // yatsuPath (head path) -> scenario name -> commit hashes that changed that scenario's block (newest-first)
 export type ScenarioIndex = Map<string, Map<string, string[]>>
 
-// the block content that stales a reading: everything a measurement is taken AGAINST, minus the name (the
-// join key — a renamed scenario is a remove+add, surfaced as a change-commit on each name). parseScenarios
-// already folds YAML block scalars, so a pure prose re-wrap yields the same string and does NOT stale.
+// the block content that stales a reading: the scenario's SEMANTIC fields only — description (what to
+// measure) + expected (what zero loss looks like), the contract a measurement is taken AGAINST. The name is
+// the join key (a renamed scenario is a remove+add, surfaced as a change-commit on each name), and the
+// metadata fields are OUT: tags route a scenario to a measuring hand, test/code/related point at files —
+// none of them changes what an already-taken reading proved, so a tags sweep or a coverage retune must not
+// re-stale every reading in the tree. Both freshness paths (the in-history change-commits and the
+// off-history scenarioDiffers probe) read THIS one projection — narrowing it here narrows both at once, and
+// because freshness is derived live from git, historical metadata-only commits stop registering as scenario
+// changes with no migration. parseScenarios already folds YAML block scalars, so a pure prose re-wrap
+// yields the same string and does NOT stale.
 function blockContent(src: string): Map<string, string> {
   const m = new Map<string, string>()
   for (const s of parseScenarios(src)) {
-    m.set(s.name, JSON.stringify({ d: s.description, e: s.expected, t: s.tags ?? [], c: s.code ?? [], r: s.related ?? [], x: s.test ?? '' }))
+    m.set(s.name, JSON.stringify({ d: s.description, e: s.expected }))
   }
   return m
 }
@@ -100,11 +108,14 @@ function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>
   return new Promise((resolve, reject) => {
     const env = { ...process.env }
     delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-    const p = spawn('git', ['-C', root, 'cat-file', '--batch'], { env })
+    const p = spawn('git', ['-C', root, 'cat-file', '--batch'], { env, timeout: Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000), killSignal: 'SIGKILL' })
     const chunks: Buffer[] = []
     p.stdout.on('data', (c: Buffer) => chunks.push(c))
     p.on('error', reject)
-    p.on('close', () => {
+    p.on('close', (_code, signal) => {
+      // a child that never exited was SIGKILLed at the timeout (a hung git must not pin this promise —
+      // same bound as git.ts's helpers); warn loudly and parse whatever arrived.
+      if (signal === 'SIGKILL') console.warn(`spec-yatsu: git cat-file --batch killed after timeout — child never exited`)
       const buf = Buffer.concat(chunks)
       let i = 0
       while (i < buf.length) {
@@ -160,3 +171,19 @@ export function scenarioIndex(root: string, yatsuPaths: string[]): Promise<Scena
 export function scenarioChangeCommits(idx: ScenarioIndex, yatsuPath: string, scenario: string): string[] {
   return idx.get(yatsuPath)?.get(scenario) ?? []
 }
+
+// canonical per-scenario SEMANTIC blocks of `rev:path` (the blockContent projection), for the off-history
+// content fallback ([[yatsu-core]]'s ContentProbe): resolve the blob oid first — oids are content-addressed,
+// so an unchanged file usually hits blockByOid straight from the index build — and parse only on a genuine
+// miss. null = the path is unreadable at that rev (absent, renamed since, or the rev itself is gone).
+export function scenarioBlocksAt(root: string, rev: string, path: string): Map<string, string> | null {
+  let oid: string
+  try { oid = git(['-C', root, 'rev-parse', `${rev}:${path}`]).trim() } catch { return null }
+  const hit = blockByOid.get(oid)
+  if (hit) return hit
+  try {
+    const m = blockContent(git(['-C', root, 'cat-file', 'blob', oid]))
+    blockByOid.set(oid, m)
+    return m
+  } catch { return null }
+}

package/spec-yatsu/src/yatsu.ts

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
+import { mintIds } from '../../spec-cli/src/specs.js'
 
 export const YATSU_FILE = 'yatsu.md'
 export const SIDECAR_FILE = 'yatsu.evals.ndjson'
@@ -16,7 +17,7 @@ export type Scenario = {
 }
 
 export type YatsuNode = {
-  id: string            // the node's leaf dir name (its spec-node id)
+  id: string            // the node's CANONICAL spec id (leaf name, '_'-disambiguated on a leaf collision)
   dir: string           // absolute node directory
   yatsuPath: string     // repo-relative path to yatsu.md — the SCENARIO freshness axis
   sidecarPath: string   // absolute path to yatsu.evals.ndjson
@@ -173,53 +174,76 @@ export function validateScenarios(src: string, tagLibrary: string[] = []): strin
   return errs
 }
 
-// walk `.spec` for every dir holding a yatsu.md; a node's id is its leaf dir name (the same its spec.md carries)
+// walk `.spec` for every dir holding a yatsu.md; the node id is its CANONICAL spec id ([[id-url-safe]]) —
+// minted by the SAME rule as specs.ts's loader (mintIds: the leaf dir name, or on a leaf collision the
+// shortest globally-unique '_'-joined trailing suffix) over the SAME universe (every dir holding a spec.md,
+// not just the yatsu subset — a leaf that collides among spec nodes is disambiguated even when only one of
+// them measures). So the id yatsu answers to is exactly the id board/scan/search already print — never a
+// second, diverging bare-leaf scheme. A yatsu.md beside no spec.md keeps its leaf name (no spec id to align with).
+function assembleNodes(root: string, specDirs: string[], hits: { dir: string; src: string }[]): YatsuNode[] {
+  const specBase = join(root, '.spec')
+  const ids = mintIds(specDirs.map((d) => relative(specBase, d).split(/[/\\]/)))
+  const idByDir = new Map(specDirs.map((d, i) => [d, ids[i]]))
+  return hits
+    .map(({ dir, src }) => ({
+      id: idByDir.get(dir) ?? basename(dir),
+      dir,
+      yatsuPath: relative(root, join(dir, YATSU_FILE)),
+      sidecarPath: join(dir, SIDECAR_FILE),
+      scenarios: parseScenarios(src),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id))
+}
+
 export function yatsuNodes(root: string): YatsuNode[] {
   const specDir = join(root, '.spec')
-  const out: YatsuNode[] = []
+  const specDirs: string[] = []
+  const hits: { dir: string; src: string }[] = []
   const stack = existsSync(specDir) ? [specDir] : []
   while (stack.length) {
     const dir = stack.pop()!
     let ents
     try { ents = readdirSync(dir, { withFileTypes: true }) } catch { continue }
-    if (existsSync(join(dir, YATSU_FILE))) {
-      const yatsuPath = relative(root, join(dir, YATSU_FILE))
-      out.push({
-        id: basename(dir),
-        dir,
-        yatsuPath,
-        sidecarPath: join(dir, SIDECAR_FILE),
-        scenarios: parseScenarios(readFileSync(join(dir, YATSU_FILE), 'utf8')),
-      })
-    }
+    if (existsSync(join(dir, 'spec.md'))) specDirs.push(dir)
+    if (existsSync(join(dir, YATSU_FILE))) hits.push({ dir, src: readFileSync(join(dir, YATSU_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
-  return out.sort((a, b) => a.id.localeCompare(b.id))
+  return assembleNodes(root, specDirs, hits)
 }
 
 // async twin of yatsuNodes for the HOT board build ([[board-cache]]): reading each yatsu.md through
 // fs/promises YIELDS the event loop between files, so the walk no longer stalls a `/health` probe in one
-// ~600ms uninterrupted stretch. Same output (id-sorted) as yatsuNodes; only buildBoard uses it, other
-// callers keep the sync form.
+// ~600ms uninterrupted stretch. Same output (canonical ids, id-sorted) as yatsuNodes; only buildBoard uses
+// it, other callers keep the sync form.
 export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
   const specDir = join(root, '.spec')
-  const out: YatsuNode[] = []
+  const specDirs: string[] = []
+  const hits: { dir: string; src: string }[] = []
   const stack = existsSync(specDir) ? [specDir] : []
   while (stack.length) {
     const dir = stack.pop()!
     let ents
     try { ents = await readdir(dir, { withFileTypes: true }) } catch { continue }
-    if (existsSync(join(dir, YATSU_FILE))) {
-      const yatsuPath = relative(root, join(dir, YATSU_FILE))
-      out.push({
-        id: basename(dir),
-        dir,
-        yatsuPath,
-        sidecarPath: join(dir, SIDECAR_FILE),
-        scenarios: parseScenarios(await readFile(join(dir, YATSU_FILE), 'utf8')),
-      })
-    }
+    if (existsSync(join(dir, 'spec.md'))) specDirs.push(dir)
+    if (existsSync(join(dir, YATSU_FILE))) hits.push({ dir, src: await readFile(join(dir, YATSU_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
-  return out.sort((a, b) => a.id.localeCompare(b.id))
+  return assembleNodes(root, specDirs, hits)
+}
+
+export type YatsuResolution<T> = { ok: true; node: T } | { ok: false; ambiguous: boolean; error: string }
+
+// resolve a user-supplied node ref against the yatsu set: an EXACT canonical id always wins; a bare leaf
+// name stays the convenience it always was while it names exactly ONE yatsu node; a leaf several nodes
+// share fails LOUD listing the candidate canonical ids — never an arbitrary first hit, so a reading can
+// only land on the node the caller actually named.
+export function resolveYatsuNode<T extends Pick<YatsuNode, 'id' | 'dir'>>(nodes: T[], ref: string): YatsuResolution<T> {
+  const exact = nodes.find((n) => n.id === ref)
+  if (exact) return { ok: true, node: exact }
+  const byLeaf = nodes.filter((n) => basename(n.dir) === ref)
+  if (byLeaf.length === 1) return { ok: true, node: byLeaf[0] }
+  if (byLeaf.length > 1) {
+    return { ok: false, ambiguous: true, error: `'${ref}' is ambiguous — ${byLeaf.length} yatsu nodes share that leaf name; use a canonical id: ${byLeaf.map((n) => n.id).sort().join(', ')}` }
+  }
+  return { ok: false, ambiguous: false, error: `no yatsu node '${ref}' (a node needs a yatsu.md)` }
 }