spexcode 0.2.8 → 0.3.0

package/{spec-yatsu → spec-eval}/src/evaltab.ts

@@ -2,7 +2,7 @@ import { relative, dirname } from 'node:path'
 import { repoRoot, driftIndex, historyIndex, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
 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 { evalNodes, type EvalNode } from './scenarios.js'
 import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, type Verdict, type EvidenceKind, type Retraction } from './sidecar.js'
 import { staleAxes, codeDrift, contentProbeFor, type StaleAxis } from './freshness.js'
 import { scenarioIndex, type ScenarioIndex } from './scenariofresh.js'
@@ -18,7 +18,7 @@ export type EvidenceView = { hash: string; kind: EvidenceKind; state: 'present'
 // per-reading display attachment.
 export type RemarkView = {
   rid: string
-  ref: string             // `<thread-id>#<rid>` — the address `spex resolve`/`spex retract` take
+  ref: string             // `<thread-id>#<rid>` — the address `spex remark resolve`/`spex remark retract` take
   by: string
   at: string
   body: string
@@ -53,7 +53,7 @@ export type EvalEntry = {
   fresh: boolean
   staleAxes: StaleAxis[]
   blobState: 'present' | 'miss' | 'none'
-  // the code axis's drift detail for a code-stale reading ([[yatsu-core]]'s codeDrift): each governed file
+  // the code axis's drift detail for a code-stale reading ([[eval-core]]'s codeDrift): each governed file
   // that moved since this reading + how many commits behind, so the eval detail can EXPLAIN the staleness
   // ("EvalsFeed.jsx +3") rather than just flag it. Absent when the reading isn't code-stale.
   codeDrift?: { file: string; behind: number }[]
@@ -89,16 +89,16 @@ export type DanglingTrack = { scenario: string; threadId: string; thread: Issue;
 
 export type ScenarioInfo = { name: string; expected: string; tags?: string[]; code?: string[] }
 
-// `hasYatsu` distinguishes a node that declares no scenarios (no yatsu.md) from one that declares some but
+// `hasEvalFile` distinguishes a node that declares no scenarios (no eval.md) from one that declares some but
 // has no readings yet — the tab says different things for each. `scenarios` is the declared set; `readings`
 // is NEWEST-FIRST (the sidecar is append-only oldest→newest; the tab leads with the latest measurement,
 // like the history tab).
 export type EvalTimeline = {
   node: string
-  hasYatsu: boolean
+  hasEvalFile: boolean
   scenarios: ScenarioInfo[]
   readings: EvalEntry[]
-  // retraction events ([[yatsu-core]]'s retract verb), newest first — the sanctioned-undo TRACE. `readings`
+  // retraction events ([[eval-core]]'s retract verb), newest first — the sanctioned-undo TRACE. `readings`
   // above is already the effective view (a retracted reading is dropped from the scoreboard everywhere);
   // this list is how a surface still shows that the undo happened: which (scenario, ts) was withdrawn,
   // by whom, why. Additive — a consumer that ignores it sees exactly the effective scoreboard.
@@ -115,13 +115,13 @@ export type EvalContext = {
   idx: DriftIndex
   hidx: HistoryIndex
   scidx: ScenarioIndex   // per-scenario block-change history ([[scenariofresh]]) — the SCENARIO axis, built ONCE per build
-  ynodes: YatsuNode[]
+  ynodes: EvalNode[]
   // the trunk remark tracks ([[remark-teeth]]), keyed (node, scenario) — loaded ONCE per board/proof build
   // and reused for every node, so the fold never re-reads the issue store per node.
   remarks: Map<string, RemarkTrack>
 }
 
-// build the shared context with ONE yatsu walk, reusing the caller's already-computed specs + the two
+// build the shared context with ONE eval-file walk, reusing the caller's already-computed specs + the two
 // HEAD-keyed git indices (drift for the code axis, history for the rename-safe scenario axis — both warm
 // hits, loadSpecs already derived them). The remark tracks are the fourth, non-git freshness input
 // ([[remark-teeth]]); a caller that omits them gets a live load, so a bare evalTimeline still has teeth.
@@ -131,28 +131,28 @@ export async function evalContext(
   idx: DriftIndex,
   hidx: HistoryIndex,
   remarks?: Map<string, RemarkTrack>,
-  ynodes?: YatsuNode[],   // the hot board build precomputes these off the event loop (yatsuNodesAsync); a bare caller walks sync
+  ynodes?: EvalNode[],   // the hot board build precomputes these off the event loop (evalNodesAsync); a bare caller walks sync
 ): Promise<EvalContext> {
-  const nodes = ynodes ?? yatsuNodes(root)
-  const scidx = await scenarioIndex(root, nodes.map((n) => n.yatsuPath))
+  const nodes = ynodes ?? evalNodes(root)
+  const scidx = await scenarioIndex(root, nodes.map((n) => n.evalPath))
   return { root, specs, idx, hidx, scidx, ynodes: nodes, remarks: remarks ?? loadEvalRemarkTracks() }
 }
 
 export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalTimeline> {
   const root = ctx?.root ?? repoRoot()
-  // short-circuit a non-yatsu node on the (short) yatsu walk — the board attaches `evals` to every node, so
-  // this is the common case and must stay cheap (a list the size of the few yatsu nodes, not the whole tree).
-  const ynode = (ctx?.ynodes ?? yatsuNodes(root)).find((n) => n.id === id)
-  if (!ynode) return { node: id, hasYatsu: false, scenarios: [], readings: [], retractions: [], dangling: [] }
+  // short-circuit a non-measurable node on the (short) eval-file walk — the board attaches `evals` to every node, so
+  // this is the common case and must stay cheap (a list the size of the few measurable nodes, not the whole tree).
+  const ynode = (ctx?.ynodes ?? evalNodes(root)).find((n) => n.id === id)
+  if (!ynode) return { node: id, hasEvalFile: false, scenarios: [], readings: [], retractions: [], dangling: [] }
   // the governed `code:` files are the freshness CODE axis; read them from the canonical spec loader so a
-  // reparent/rename is seen the same way `spex lint` and `spex yatsu eval` see it (joined by directory).
+  // reparent/rename is seen the same way `spex spec lint` and `spex eval add` see it (joined by directory).
   const specs = ctx?.specs ?? await loadSpecs()
   const codeFiles = specs.find((s) => dirname(s.path) === relative(root, ynode.dir))?.code ?? []
   const idx = ctx?.idx ?? await driftIndex(root)
   const hidx = ctx?.hidx ?? await historyIndex(root)
   // the SCENARIO axis: per-scenario block-change history, built once per HEAD (cached). A bare call builds it
-  // for the WHOLE yatsu set (not just this node) so the shared HEAD-keyed cache is complete for later callers.
-  const scidx = ctx?.scidx ?? await scenarioIndex(root, (ctx?.ynodes ?? yatsuNodes(root)).map((n) => n.yatsuPath))
+  // for the WHOLE measurable set (not just this node) so the shared HEAD-keyed cache is complete for later callers.
+  const scidx = ctx?.scidx ?? await scenarioIndex(root, (ctx?.ynodes ?? evalNodes(root)).map((n) => n.evalPath))
   const byName = new Map(ynode.scenarios.map((s) => [s.name, s]))   // join each reading to its scenario's expected + code
   // the trunk remark track per scenario ([[remark-teeth]]) — the non-git freshness input, fed to the teeth.
   const tracks = ctx?.remarks ?? loadEvalRemarkTracks()
@@ -165,7 +165,7 @@ 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
+  // the off-history content fallback ([[eval-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) => {
@@ -175,8 +175,8 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
     // remark makes it remark-stale (T1). Display attachment (which reading each remark pins to) is a separate
     // 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 })), probe)
+    const axes = staleAxes(r, cf, ynode.evalPath, idx, scidx,
+      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe, sc)
     // 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, probe) : []
     // the reading's evidence list, each entry resolved to its live blob state; the primary (video-first, else
@@ -215,7 +215,7 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
     const rows = readings.filter((r) => r.scenario === track.scenario)
     if (!rows.length) {
       // no reading joins this track. If the scenario is still DECLARED it is just a blind spot (unmeasured),
-      // not orphaned — its remarks wait for a reading. Only a scenario that is BOTH gone from yatsu.md AND
+      // not orphaned — its remarks wait for a reading. Only a scenario that is BOTH gone from eval.md AND
       // has no reading is truly dangling (renamed/deleted), and that is the one we surface at node level.
       if (!declared.has(track.scenario)) {
         dangling.push({
@@ -232,7 +232,7 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
       ;(host.remarks ??= []).push(toRemarkView(rm, track.threadId, !target))
     }
   }
-  return { node: id, hasYatsu: true, scenarios, readings, retractions: [...retractions].reverse(), dangling }
+  return { node: id, hasEvalFile: true, scenarios, readings, retractions: [...retractions].reverse(), dangling }
 }
 
 const HEX64 = /^[0-9a-f]{64}$/
@@ -242,7 +242,7 @@ export type BlobResult =
   | { ok: false; reason: 'invalid' | 'miss'; message: string }
 
 export function readBlobByHash(hash: string, dir?: string): BlobResult {
-  if (!HEX64.test(hash)) return { ok: false, reason: 'invalid', message: 'bad blob hash' }
+  if (!HEX64.test(hash)) return { ok: false, reason: 'invalid', message: 'bad evidence hash' }
   const bytes = getBlob(hash, dir)   // undefined dir → the live cache (cache.ts default); a temp dir in tests
   if (!bytes) return { ok: false, reason: 'miss', message: MISS_BLOB }
   return { ok: true, bytes, mime: sniffBlobMime(bytes) }

package/{spec-yatsu → spec-eval}/src/filing.ts

@@ -1,5 +1,5 @@
 import { repoRoot, headSha } from '../../spec-cli/src/git.js'
-import { yatsuNodes, resolveYatsuNode } from './yatsu.js'
+import { evalNodes, resolveEvalNode, scenarioHash } from './scenarios.js'
 import { appendReading, readReadings, isJsonBlob, type Reading, type EvidenceKind } from './sidecar.js'
 import { putBlob } from './cache.js'
 
@@ -7,7 +7,7 @@ export type FileResult = { ok: true; reading: Reading } | { ok: false; error: st
 
 // the eval seam over DATA (no argv, no file paths): a caller with a verdict in hand — the HTTP eval route,
 // a programmatic filer — appends through the SAME seam the CLI uses. Optional evidence arrives as text (a
-// report referencing the clip by hash) → a transcript blob in the same content-addressed cache. yatsu
+// report referencing the clip by hash) → a transcript blob in the same content-addressed cache. eval
 // still runs nothing — this only records. The dashboard files nothing through this: [[event-detail]] is
 // read-side on readings.
 export function fileHumanReading(
@@ -15,9 +15,9 @@ export function fileHumanReading(
   input: { scenario: string; status: 'pass' | 'fail'; note?: string; transcript?: string; by?: string },
 ): FileResult {
   const root = repoRoot()
-  // the same loud resolution the CLI applies ([[yatsu-core]]): exact canonical id, else a unique bare
+  // the same loud resolution the CLI applies ([[eval-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)
+  const res = resolveEvalNode(evalNodes(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)
@@ -30,6 +30,8 @@ export function fileHumanReading(
   const reading: Reading = {
     scenario: sc.name,
     codeSha: headSha(root),
+    // the contract this measurement was taken against — the HTTP filer stamps it exactly like the CLI
+    scenarioHash: scenarioHash(sc),
     ...(blob ? { evidence: [{ hash: blob, kind: (buf && isJsonBlob(buf) ? 'data' : 'transcript') as EvidenceKind }] } : {}),
     // the filing session (caller-passed — the human annotator has no reachable session, so it stays absent
     // there and the eval-comment loop-in is silent, per [[mentions]])
@@ -48,7 +50,7 @@ export function fileHumanReading(
 // 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)
+  const res = resolveEvalNode(evalNodes(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 → spec-eval}/src/freshness.ts

@@ -1,5 +1,6 @@
 import { git, headSha, ancestorsOf, inAncestors, type DriftIndex } from '../../spec-cli/src/git.js'
 import type { Reading } from './sidecar.js'
+import { scenarioHash, type Scenario } from './scenarios.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
@@ -18,7 +19,7 @@ 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
+  scenarioDiffers(anchorSha: string, evalPath: 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
 }
@@ -50,10 +51,10 @@ export function contentProbeFor(root: string): ContentProbe {
         } 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)
+    scenarioDiffers(sha, evalPath, scenario) {
+      const a = scenarioBlocksAt(root, sha, evalPath)
+      if (!a) return true   // eval.md unreadable at the anchor (renamed/absent) → can't prove → stale
+      return a.get(scenario) !== scenarioBlocksAt(root, headOf(), evalPath)?.get(scenario)
     },
     behind(sha, path) {
       return memo(behindMemo, `${root}\x1f${sha}\x1f${headOf()}\x1f${path}`, () => {
@@ -112,39 +113,59 @@ export function codeDrift(idx: DriftIndex, sinceSha: string, codeFiles: string[]
   return out
 }
 
-// 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 {
+// @@@scenario axis decides by stored contract hash - a reading filed since #61 carries `scenarioHash`, the
+// content hash of the semantic text it was measured against (scenarios.ts scenarioHash — normalized
+// description+expected). For such a reading the scenario axis is a PURE TEXT COMPARE: recorded hash vs the
+// CURRENT declaration's hash — no git walk, no chain, no ancestry. That is what makes it converge under
+// fleet-parallel filing+merging: a sibling scenario's edit, a sidecar-only commit, a merge's textual shift,
+// a whitespace re-wrap — none of them move THIS scenario's hash, so none can re-stale its reading; only the
+// contract actually changing (or the scenario disappearing from eval.md — `current` undefined) does. A
+// LEGACY reading without the hash is decided by the git-derived per-scenario rule below, unchanged — the
+// one-shot degradation: exactly ONE track decides each reading (hash if present, else git), never both
+// OR-ed together.
+function scenarioStaleByHash(reading: Reading, current: Scenario | undefined): boolean | undefined {
+  if (reading.scenarioHash === undefined) return undefined   // legacy → the git rule decides
+  return current ? scenarioHash(current) !== reading.scenarioHash : true
+}
+
+// LEGACY scenario freshness (readings filed before the stored contract hash) — 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 eval.md did, and never on a metadata-only edit (tags/test/code/related). Reads 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. Known limit (#61, why the hash replaced it for new
+// readings): the change-commit chain is built off a LINEARIZED log walk, so parallel branches editing one
+// eval.md cross-attribute each other's edits and can false-stale a sibling's reading across a merge.
+function scenarioMoved(scIdx: ScenarioIndex, didx: DriftIndex, sinceSha: string, evalPath: string, scenario: string, probe?: ContentProbe): boolean {
   const anc = ancestorsOf(didx, sinceSha)
-  if (anc) return scenarioChangeCommits(scIdx, yatsuPath, scenario).some((h) => !inAncestors(didx, anc, h))
+  if (anc) return scenarioChangeCommits(scIdx, evalPath, 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)
+  if (!diff.has(evalPath)) return false   // whole file byte-identical → this block too
+  return probe!.scenarioDiffers(sinceSha, evalPath, scenario)
 }
 
 export function staleAxes(
   reading: Reading,
   codeFiles: string[],
-  yatsuPath: string,
+  evalPath: string,
   didx: DriftIndex,
   scIdx: ScenarioIndex,
   remarks: RemarkSignal[] = [],
   probe?: ContentProbe,
+  current?: Scenario,   // the scenario's CURRENT declaration (undefined = gone from eval.md) — the hash compare's other side
 ): StaleAxis[] {
   const axes: StaleAxis[] = []
+  const byHash = scenarioStaleByHash(reading, current)
   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"
+    // the anchor commit object is GONE — neither git axis can testify; say that, not "content changed".
+    // The stored contract hash needs no anchor, so it still decides the scenario axis when present.
     axes.push('anchor')
+    if (byHash) axes.push('scenario')
   } 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 (byHash ?? scenarioMoved(scIdx, didx, reading.codeSha, evalPath, reading.scenario, probe)) axes.push('scenario')
   }
   if (remarkStale(reading, remarks)) axes.push('remark')
   return axes
@@ -153,11 +174,12 @@ export function staleAxes(
 export function isStale(
   reading: Reading,
   codeFiles: string[],
-  yatsuPath: string,
+  evalPath: string,
   didx: DriftIndex,
   scIdx: ScenarioIndex,
   remarks: RemarkSignal[] = [],
   probe?: ContentProbe,
+  current?: Scenario,
 ): boolean {
-  return staleAxes(reading, codeFiles, yatsuPath, didx, scIdx, remarks, probe).length > 0
+  return staleAxes(reading, codeFiles, evalPath, didx, scIdx, remarks, probe, current).length > 0
 }

package/{spec-yatsu → spec-eval}/src/scenariofresh.ts

@@ -1,11 +1,11 @@
 import { spawn } from 'node:child_process'
 import { git, gitA, headSha } from '../../spec-cli/src/git.js'
-import { parseScenarios } from './yatsu.js'
+import { parseScenarios } from './scenarios.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
+// An eval.md holds many scenarios, but a reading measures ONE. eval-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 SEMANTIC
+// history, so we build it: for each scenario NAME in an eval.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
@@ -13,7 +13,7 @@ import { parseScenarios } from './yatsu.js'
 
 const RS = '\x1e'
 
-// yatsuPath (head path) -> scenario name -> commit hashes that changed that scenario's block (newest-first)
+// evalPath (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: the scenario's SEMANTIC fields only — description (what to
@@ -42,7 +42,7 @@ const EMPTY: Map<string, string> = new Map()
 // already parsed, which is what lets a worktree's freshness build stay cheap instead of re-reading everything.
 const blockByOid = new Map<string, Map<string, string>>()
 
-// ONE `git log --raw` walk over all yatsu.md → per head-path version chain [{hash, oid}], newest-first,
+// ONE `git log --raw` walk over all eval.md → per head-path version chain [{hash, oid}], newest-first,
 // rename-followed via the `alias` idiom (git.ts buildIndex): the newest sighting of a path IS its head path;
 // an `R` row remaps the older `from` path onto that head. The raw row carries the new blob OID directly, so
 // no per-version path resolution and no `git show`. --full-history is REQUIRED: default pathspec
@@ -53,8 +53,13 @@ const blockByOid = new Map<string, Map<string, string>>()
 async function fileChains(root: string, wanted: Set<string>): Promise<Map<string, { hash: string; oid: string }[]>> {
   const chains = new Map<string, { hash: string; oid: string }[]>()
   const alias = new Map<string, string>()
+  // DUAL pathspec — the live name AND the archived one ([[eval-core]]): this walk reads IMMUTABLE history,
+  // and pre-rename commits touched files literally named yatsu.md, so an archive answers only to its
+  // archive name. A single '*eval.md' pathspec truncates every chain at the yatsu.md→eval.md rename commit,
+  // making the rename read as each scenario's birth — a change-commit newer than every pre-rename reading's
+  // codeSha — and false-stales whole adopter corpora (the scenariofresh.test.ts regression pins this).
   const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log',
-    '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*yatsu.md'])
+    '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*eval.md', '*yatsu.md']) // dead-words-ok: archived pathspec — immutable pre-rename history is read under its archived name
   for (const rec of out.split(RS)) {
     const nl = rec.indexOf('\n')
     if (nl < 0) continue
@@ -115,7 +120,7 @@ function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>
     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`)
+      if (signal === 'SIGKILL') console.warn(`spec-eval: git cat-file --batch killed after timeout — child never exited`)
       const buf = Buffer.concat(chunks)
       let i = 0
       while (i < buf.length) {
@@ -139,8 +144,8 @@ function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>
 
 // TWO git subprocesses for the whole index (was F logs + V shows): one `--raw` log for the rename-followed
 // chains, one `cat-file --batch` for every distinct blob not already memoized. Then a pure in-memory diff.
-async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
-  const chains = await fileChains(root, new Set(yatsuPaths))
+async function build(root: string, evalPaths: string[]): Promise<ScenarioIndex> {
+  const chains = await fileChains(root, new Set(evalPaths))
   const need = new Set<string>()
   for (const chain of chains.values()) for (const v of chain) if (v.oid !== ZERO && !blockByOid.has(v.oid)) need.add(v.oid)
   if (need.size) {
@@ -148,7 +153,7 @@ async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex>
     for (const [oid, src] of blobs) blockByOid.set(oid, blockContent(src))
   }
   const idx: ScenarioIndex = new Map()
-  for (const p of yatsuPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))   // every asked path gets an entry (empty if untracked)
+  for (const p of evalPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))   // every asked path gets an entry (empty if untracked)
   return idx
 }
 
@@ -156,20 +161,20 @@ async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex>
 // whatever the caller. Holds the in-flight promise so concurrent board builds share one build.
 const SLOTS = 16
 const cache = new Map<string, Promise<ScenarioIndex>>()
-export function scenarioIndex(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
+export function scenarioIndex(root: string, evalPaths: string[]): Promise<ScenarioIndex> {
   let head: string
-  try { head = headSha(root) } catch { return build(root, yatsuPaths) }
+  try { head = headSha(root) } catch { return build(root, evalPaths) }
   const hit = cache.get(head)
   if (hit) { cache.delete(head); cache.set(head, hit); return hit }
-  const p = build(root, yatsuPaths)
+  const p = build(root, evalPaths)
   p.catch(() => cache.delete(head))
   cache.set(head, p)
   while (cache.size > SLOTS) cache.delete(cache.keys().next().value!)
   return p
 }
 
-export function scenarioChangeCommits(idx: ScenarioIndex, yatsuPath: string, scenario: string): string[] {
-  return idx.get(yatsuPath)?.get(scenario) ?? []
+export function scenarioChangeCommits(idx: ScenarioIndex, evalPath: string, scenario: string): string[] {
+  return idx.get(evalPath)?.get(scenario) ?? []
 }
 
 // (root, sha, path) -> the blob oid at that commit ('' = unresolvable: path absent there, or the commit
@@ -194,7 +199,7 @@ function oidAt(root: string, rev: string, path: string): string {
 }
 
 // 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 (memoized above for a full
+// content fallback ([[eval-core]]'s ContentProbe): resolve the blob oid first (memoized above for a full
 // sha) — 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).
@@ -204,7 +209,7 @@ export function scenarioBlocksAt(root: string, rev: string, path: string): Map<s
   const hit = blockByOid.get(oid)
   if (hit) return hit
   try {
-    const m = blockContent(git(['-C', root, 'cat-file', 'blob', oid]))
+    const m = blockContent(git(['-C', root, 'cat-file', 'blob', oid])) // dead-words-ok: git plumbing — 'blob' is git's object type, not our vocabulary
     blockByOid.set(oid, m)
     return m
   } catch { return null }

package/{spec-yatsu/src/yatsu.ts → spec-eval/src/scenarios.ts}

@@ -1,10 +1,11 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 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'
+export const EVAL_FILE = 'eval.md'
+export const SIDECAR_FILE = 'evals.ndjson'
 
 export type Scenario = {
   name: string
@@ -16,11 +17,11 @@ export type Scenario = {
   related?: string[]
 }
 
-export type YatsuNode = {
+export type EvalNode = {
   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
+  evalPath: string     // repo-relative path to eval.md — the SCENARIO freshness axis
+  sidecarPath: string   // absolute path to evals.ndjson
   scenarios: Scenario[]
 }
 
@@ -32,7 +33,7 @@ const LIST_KEYS: readonly ScenarioKey[] = ['tags', 'code', 'related']
 // carried — kept (not dropped) so the validator can name a typo'd field instead of silently swallowing it.
 type RawItem = { fields: Partial<Record<ScenarioKey, string>>; unknownKeys: string[] }
 
-// tiny indentation parser for yatsu.md's frontmatter `scenarios:` block (no YAML dep), shared by parseScenarios and validateScenarios so they can't disagree; reports hasFrontmatter/hasKey so the validator can tell "none declared" from "malformed"
+// tiny indentation parser for eval.md's frontmatter `scenarios:` block (no YAML dep), shared by parseScenarios and validateScenarios so they can't disagree; reports hasFrontmatter/hasKey so the validator can tell "none declared" from "malformed"
 function walkScenarios(src: string): { hasFrontmatter: boolean; hasKey: boolean; items: RawItem[] } {
   const m = src.match(/^---\n([\s\S]*?)\n---/)
   if (!m) return { hasFrontmatter: false, hasKey: false, items: [] }
@@ -117,6 +118,20 @@ function assignField(cur: RawItem, kv: string, lines: string[], idx: number, key
 
 const unquote = (s: string) => s.replace(/^["'](.*)["']$/, '$1').trim()
 
+// @@@scenario contract hash - the deterministic content hash of a scenario's SEMANTIC text, stamped on each
+// reading at filing time ([[eval-core]]'s scenario freshness axis). Hashes ONLY the measurement contract —
+// description (what to measure) + expected (what zero loss looks like) — never name/tags/test/code/related.
+// Normalization (spec'd, don't drift): each field independently collapses every whitespace run (space, tab,
+// CR, LF) to a single space and trims its ends, so a prose re-wrap, an indent shift, CRLF churn or trailing
+// whitespace never changes the hash; the two normalized fields join with a single '\n' (neither can contain
+// one after normalization, so the join is unambiguous) and sha256-hex the UTF-8 bytes. The hash is pure text
+// over the parsed declaration — no git, no file position — so it is identical wherever and however the same
+// contract text is read.
+const normSemantic = (s: string) => s.replace(/\s+/g, ' ').trim()
+export function scenarioHash(s: Pick<Scenario, 'description' | 'expected'>): string {
+  return createHash('sha256').update(`${normSemantic(s.description)}\n${normSemantic(s.expected)}`, 'utf8').digest('hex')
+}
+
 // a scenario's optional list field (`code:`/`related:`) is a comma-separated path list (a YAML flow list
 // `[a, b]` or bare `a, b`, or a single path) — the tiny parser stays scalar-only, so it is split here.
 function parseCodeList(raw: string): string[] {
@@ -148,7 +163,7 @@ export function parseScenarios(src: string): Scenario[] {
 // disables only the membership check, never the ≥1-tag requirement.
 export function validateScenarios(src: string, tagLibrary: string[] = []): string[] {
   const { hasFrontmatter, hasKey, items } = walkScenarios(src)
-  if (!hasFrontmatter) return ['no frontmatter block — a yatsu.md must declare a `scenarios:` list']
+  if (!hasFrontmatter) return ['no frontmatter block — an eval.md must declare a `scenarios:` list']
   if (!hasKey) return ['frontmatter has no `scenarios:` key — declare at least one scenario']
   if (!items.length) return ['`scenarios:` declares no scenarios — add one (name + description + expected)']
   const errs: string[] = []
@@ -170,17 +185,17 @@ export function validateScenarios(src: string, tagLibrary: string[] = []): strin
     for (const u of it.unknownKeys) errs.push(`${label}: unknown field \`${u}\` (allowed: ${SCENARIO_KEYS.join(', ')})`)
     if (it.fields.name) counts.set(it.fields.name, (counts.get(it.fields.name) ?? 0) + 1)
   })
-  for (const [n, c] of counts) if (c > 1) errs.push(`duplicate scenario name '${n}' (${c}×) — names must be unique within a yatsu.md`)
+  for (const [n, c] of counts) if (c > 1) errs.push(`duplicate scenario name '${n}' (${c}×) — names must be unique within an eval.md`)
   return errs
 }
 
-// walk `.spec` for every dir holding a yatsu.md; the node id is its CANONICAL spec id ([[id-url-safe]]) —
+// walk `.spec` for every dir holding an eval.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[] {
+// not just the eval subset — a leaf that collides among spec nodes is disambiguated even when only one of
+// them measures). So the id eval verbs answer to is exactly the id board/scan/search already print — never a
+// second, diverging bare-leaf scheme. An eval.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 }[]): EvalNode[] {
   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]]))
@@ -188,14 +203,14 @@ function assembleNodes(root: string, specDirs: string[], hits: { dir: string; sr
     .map(({ dir, src }) => ({
       id: idByDir.get(dir) ?? basename(dir),
       dir,
-      yatsuPath: relative(root, join(dir, YATSU_FILE)),
+      evalPath: relative(root, join(dir, EVAL_FILE)),
       sidecarPath: join(dir, SIDECAR_FILE),
       scenarios: parseScenarios(src),
     }))
     .sort((a, b) => a.id.localeCompare(b.id))
 }
 
-export function yatsuNodes(root: string): YatsuNode[] {
+export function evalNodes(root: string): EvalNode[] {
   const specDir = join(root, '.spec')
   const specDirs: string[] = []
   const hits: { dir: string; src: string }[] = []
@@ -205,17 +220,17 @@ export function yatsuNodes(root: string): YatsuNode[] {
     let ents
     try { ents = readdirSync(dir, { withFileTypes: true }) } catch { continue }
     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') })
+    if (existsSync(join(dir, EVAL_FILE))) hits.push({ dir, src: readFileSync(join(dir, EVAL_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
   return assembleNodes(root, specDirs, hits)
 }
 
-// async twin of yatsuNodes for the HOT board build ([[board-cache]]): reading each yatsu.md through
+// async twin of evalNodes for the HOT board build ([[graph-cache]]): reading each eval.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 (canonical ids, id-sorted) as yatsuNodes; only buildBoard uses
+// ~600ms uninterrupted stretch. Same output (canonical ids, id-sorted) as evalNodes; only buildBoard uses
 // it, other callers keep the sync form.
-export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
+export async function evalNodesAsync(root: string): Promise<EvalNode[]> {
   const specDir = join(root, '.spec')
   const specDirs: string[] = []
   const hits: { dir: string; src: string }[] = []
@@ -225,25 +240,25 @@ export async function yatsuNodesAsync(root: string): Promise<YatsuNode[]> {
     let ents
     try { ents = await readdir(dir, { withFileTypes: true }) } catch { continue }
     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') })
+    if (existsSync(join(dir, EVAL_FILE))) hits.push({ dir, src: await readFile(join(dir, EVAL_FILE), 'utf8') })
     for (const e of ents) if (e.isDirectory()) stack.push(join(dir, e.name))
   }
   return assembleNodes(root, specDirs, hits)
 }
 
-export type YatsuResolution<T> = { ok: true; node: T } | { ok: false; ambiguous: boolean; error: string }
+export type EvalResolution<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
+// resolve a user-supplied node ref against the measurable set: an EXACT canonical id always wins; a bare leaf
+// name stays the convenience it always was while it names exactly ONE measurable 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> {
+export function resolveEvalNode<T extends Pick<EvalNode, 'id' | 'dir'>>(nodes: T[], ref: string): EvalResolution<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: true, error: `'${ref}' is ambiguous — ${byLeaf.length} measurable 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)` }
+  return { ok: false, ambiguous: false, error: `no measurable node '${ref}' (a node needs an eval.md)` }
 }