spexcode 0.2.8 → 0.4.0

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

@@ -2,8 +2,8 @@ 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 { readSidecar, applyRetractions, evidenceOf, isJsonBlob, type Verdict, type EvidenceKind, type Retraction } from './sidecar.js'
+import { evalNodes, type EvalNode } from './scenarios.js'
+import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, humanOkFor, 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'
 import { hasBlob, getBlob, MISS_BLOB } from './cache.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 }[]
@@ -64,6 +64,10 @@ export type EvalEntry = {
   // so the eval detail pane reads its whole comment thread from the reading overlay — the counterpart to
   // splitting eval-remark threads OUT of the issue surfaces (mergedIssues). Absent until the first remark.
   thread?: Issue
+  // the human sign-off bound to THIS reading ([[human-ok]]) — present only on the exact reading an ok row
+  // anchors (by scenario + ts), so a newer reading arrives unblessed and the feed's hide releases itself.
+  // Rides the board fold verbatim (latestPerScenario is a filter, never a projection).
+  humanOk?: { by: string; ts: string }
 }
 
 // a remark overlaid onto its display host (a reading, above) → the RemarkView the surfaces read.
@@ -89,16 +93,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 +119,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 +135,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()
@@ -163,9 +167,9 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
     ...(s.tags?.length ? { tags: s.tags } : {}), ...(s.code?.length ? { code: s.code } : {}),
   }))
   // 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
+  // along as the undo trace (newest-first, like the readings), the human-ok events as the sign-off overlay.
+  const { readings: rawReadings, retractions, oks } = readSidecar(ynode.sidecarPath)
+  // 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,14 +179,17 @@ 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
     // 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' }))
     const primary = evidence.find((e) => e.kind === 'video') ?? evidence[0]
+    // the sign-off join ([[human-ok]]): the ok binds by exact (scenario, ts), so only the very reading the
+    // human blessed carries it — a newer or retract-revealed reading reads unblessed.
+    const okRow = humanOkFor(oks, r.scenario, r.ts)
     return {
       scenario: r.scenario,
       expected: byName.get(r.scenario)?.expected ?? '',
@@ -200,6 +207,7 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
       ...(drift.length ? { codeDrift: drift } : {}),
       blobState: primary ? primary.state : 'none',
       ...(threadFor(r.scenario) ? { thread: threadFor(r.scenario) } : {}),
+      ...(okRow ? { humanOk: { by: okRow.by, ts: okRow.ts } } : {}),
     }
   })
   readings.reverse()   // newest-first
@@ -215,7 +223,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 +240,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 +250,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-eval/src/humanok.ts

@@ -0,0 +1,43 @@
+import { relative } from 'node:path'
+import { repoRoot } from '../../spec-cli/src/git.js'
+import { commitTrunkData } from '../../spec-cli/src/localIssues.js'
+import { evalNodes, resolveEvalNode } from './scenarios.js'
+import { readReadings, readSidecar, appendHumanOk, humanOkFor, type HumanOk } from './sidecar.js'
+
+// @@@ human-ok - the human sign-off on an eval reading ([[human-ok]]). One write, both surfaces: the CLI
+// (`spex eval ok`) and the HTTP route (`POST /api/specs/:id/evals/ok`, identity server-derived 'human')
+// call THIS. The ok binds to ONE immutable reading — the scenario's latest effective reading at ok-time,
+// anchored by its (ts, codeSha) — and is MONOTONIC: no un-ok verb exists, because a newer reading is a
+// different object the ok never transfers to, and staleness is computed live; both bring the scenario back
+// on their own. Durability follows the checkout: on the trunk checkout the append is committed straight to
+// trunk (`--no-verify`, path-scoped, under the shared store lock — the [[local-issues]] discipline,
+// commitTrunkData); on a linked worktree the append stays in that tree and the session's own ritual commit
+// carries it, exactly like every other sidecar write.
+export type OkResult =
+  | { ok: true; humanOk: HumanOk; already: boolean; landed: 'committed' | 'uncommitted' }
+  | { ok: false; error: string }
+
+export function fileHumanOk(nodeId: string, scenario: string, by: string): OkResult {
+  const root = repoRoot()
+  // the same loud resolution every eval verb applies ([[eval-core]]): exact canonical id, else a unique
+  // bare leaf; an ambiguous leaf returns the candidate list instead of blessing an arbitrary node.
+  const res = resolveEvalNode(evalNodes(root), nodeId)
+  if (!res.ok) return { ok: false, error: res.error }
+  const node = res.node
+  if (!node.scenarios.some((s) => s.name === scenario) &&
+      !readSidecar(node.sidecarPath).readings.some((r) => r.scenario === scenario))
+    return { ok: false, error: `'${node.id}' has no scenario '${scenario}'` }
+  // the ok's one possible target: the latest EFFECTIVE reading — an ok is a judgment on a measurement that
+  // exists and currently counts; an unmeasured (or fully-retracted) scenario has nothing to bless.
+  const forScenario = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
+  if (!forScenario.length) return { ok: false, error: `'${node.id}' scenario '${scenario}' has no effective reading — nothing to ok` }
+  const latest = forScenario[forScenario.length - 1]
+  // a duplicate ok is idempotent success (the store already IS the requested state — the local-issue
+  // close's `already` semantics), never an error and never a second appended row.
+  const existing = humanOkFor(readSidecar(node.sidecarPath).oks, scenario, latest.ts)
+  if (existing) return { ok: true, humanOk: existing, already: true, landed: 'committed' }
+  const row: HumanOk = { kind: 'human-ok', scenario, okTs: latest.ts, okSha: latest.codeSha, by, ts: new Date().toISOString() }
+  appendHumanOk(node.sidecarPath, row)
+  const landed = commitTrunkData(relative(root, node.sidecarPath), `eval(${node.id}): human-ok '${scenario}' @ ${latest.ts} by ${by}`)
+  return { ok: true, humanOk: row, already: false, landed: landed === 'not-primary' ? 'uncommitted' : 'committed' }
+}

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 }