spexcode 0.2.8 → 0.4.0

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

@@ -4,7 +4,7 @@ import { repoRoot, headSha, driftIndex, stagedFiles, git } from '../../spec-cli/
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { loadConfig, sourceExtRe } from '../../spec-cli/src/lint.js'
 import { mainBranch, envSessionId, readRawRecord } from '../../spec-cli/src/layout.js'
-import { yatsuNodes, validateScenarios, resolveYatsuNode, YATSU_FILE, type YatsuNode } from './yatsu.js'
+import { evalNodes, validateScenarios, resolveEvalNode, scenarioHash, EVAL_FILE, type EvalNode } from './scenarios.js'
 import { readReadings, readSidecar, appendReading, appendRetraction, latestPerScenario, evidenceOf, isJsonBlob, type Reading, type Verdict, type Evidence, type EvidenceKind, type Retraction } from './sidecar.js'
 import { staleAxes, contentProbeFor } from './freshness.js'
 import { scenarioIndex } from './scenariofresh.js'
@@ -29,13 +29,13 @@ const has = (args: string[], name: string) => args.includes(`--${name}`)
 const positional = (args: string[]) => args.find((a) => !a.startsWith('--'))
 
 // join by node directory (not id) so a reparent/rename is seen the way lint sees it
-type EvalNode = YatsuNode & { codeFiles: string[] }
+type ScoredNode = EvalNode & { codeFiles: string[] }
 
-async function gatherNodes(root: string): Promise<EvalNode[]> {
+async function gatherNodes(root: string): Promise<ScoredNode[]> {
   const specs = await loadSpecs()
   const codeByDir = new Map<string, string[]>()
   for (const s of specs) codeByDir.set(dirname(s.path), s.code)   // s.path = repo-relative spec.md path
-  return yatsuNodes(root).map((n) => ({ ...n, codeFiles: codeByDir.get(relative(root, n.dir)) ?? [] }))
+  return evalNodes(root).map((n) => ({ ...n, codeFiles: codeByDir.get(relative(root, n.dir)) ?? [] }))
 }
 
 // resolve `.` → the node this worktree works on: the session record's `node` (the authoritative ref a
@@ -53,8 +53,8 @@ function currentNodeId(root: string): string | null {
 }
 
 // isUiPath answers a FRONTEND-specific question — "does this node need a real BROWSER reading?" — and is
-// consumed by the review-proof's `uncoveredFrontend` blindspot, NOT by scan's uncovered check. Scan keys off
-// the general `sourceExtensions` knob instead (see the `yatsu-uncovered` branch below), so a non-web project's
+// consumed by the session-eval's `uncoveredFrontend` blindspot, NOT by eval lint's coverage check. Scan keys off
+// the general `sourceExtensions` knob instead (see the `eval-coverage` branch below), so a non-web project's
 // sources are held to the loss discipline too; this stays web-shaped on purpose.
 const UI_FILE = /\.(jsx|tsx|vue|svelte|css)$/
 export const isUiPath = (p: string) => UI_FILE.test(p) || p.includes('spec-dashboard/')
@@ -71,7 +71,7 @@ function changedSinceBase(root: string): Set<string> {
   return out
 }
 
-// a node is "changed" if the branch touched its node dir (spec.md / yatsu.md / sidecar all live there) or
+// a node is "changed" if the branch touched its node dir (spec.md / eval.md / sidecar all live there) or
 // any governed code path — matched as an exact file, a directory prefix, or a `*` glob.
 export function nodeChanged(dirRel: string, codeFiles: string[], changed: Set<string>): boolean {
   for (const c of changed) if (c === dirRel || c.startsWith(dirRel + '/')) return true
@@ -87,25 +87,25 @@ export function nodeChanged(dirRel: string, codeFiles: string[], changed: Set<st
 async function scan(args: string[] = []): Promise<number> {
   const root = repoRoot()
   const cfg = loadConfig(root)
-  // yatsu-uncovered fires on ANY governed source file (per the shared `sourceExtensions` knob), not just
+  // eval-coverage fires on ANY governed source file (per the shared `sourceExtensions` knob), not just
   // frontend — so a backend/CLI/non-web project's sources are held to the loss discipline too, not exempted.
   const srcRe = sourceExtRe(cfg.sourceExtensions)
   const changedOnly = has(args, 'changed')
   const changed = changedOnly ? changedSinceBase(root) : null
   const idx = await driftIndex(root)
-  // the off-history content fallback ([[yatsu-core]]): a rebased/folded-away anchor with byte-identical
+  // the off-history content fallback ([[eval-core]]): a rebased/folded-away anchor with byte-identical
   // governed content reads fresh instead of false-positive stale. Lazy — in-history readings never probe.
   const probe = contentProbeFor(root)
-  const scidx = await scenarioIndex(root, yatsuNodes(root).map((n) => n.yatsuPath))
+  const scidx = await scenarioIndex(root, evalNodes(root).map((n) => n.evalPath))
   const specs = await loadSpecs()
   // the non-git REMARK freshness axis ([[remark-teeth]]): the trunk remark track, read ONCE — the CLI is the
-  // whole model, so `spex yatsu scan` shows a remark-stale scenario with no server running.
+  // whole model, so `spex eval lint` shows a remark-stale scenario with no server running.
   const remarkTracks = loadEvalRemarkTracks()
   // a file may be governed by several nodes — ordinary composition, not a hub to skip (see governed-related).
-  // A change to a shared governed file legitimately triggers EVERY governing node's yatsu, mirroring how
+  // A change to a shared governed file legitimately triggers EVERY governing node's eval signal, mirroring how
   // lint's drift now fans to every owner; nobody's loss signal is suppressed. An over-owned file is lint's
   // `owners` concern (split it), not a reason to go silent here.
-  const yByDir = new Map(yatsuNodes(root).map((n) => [relative(root, n.dir), n]))
+  const yByDir = new Map(evalNodes(root).map((n) => [relative(root, n.dir), n]))
   let flaggedNodes = 0, malformed = 0, staleScores = 0, missingScores = 0, uncovered = 0, danglingTracks = 0
   for (const s of specs) {
     const dirRel = dirname(s.path)
@@ -113,11 +113,11 @@ async function scan(args: string[] = []): Promise<number> {
     const y = yByDir.get(dirRel)
     const findings: string[] = []
     if (y) {
-      // schema first: a malformed yatsu.md is the loudest gap — report each violation, then still scan its
+      // schema first: a malformed eval.md is the loudest gap — report each violation, then still scan its
       // (leniently-parsed) scenarios for stale/missing so a typo doesn't mask a real freshness gap.
-      for (const e of validateScenarios(readFileSync(join(y.dir, YATSU_FILE), 'utf8'), cfg.scenarioTags)) {
+      for (const e of validateScenarios(readFileSync(join(y.dir, EVAL_FILE), 'utf8'), cfg.scenarioTags)) {
         malformed++
-        findings.push(`  • yatsu-schema: '${s.id}' ${e} — fix ${y.yatsuPath}`)
+        findings.push(`  • eval-schema: '${s.id}' ${e} — fix ${y.evalPath}`)
       }
       const latest = latestPerScenario(readReadings(y.sidecarPath))
       for (const sc of y.scenarios) {
@@ -128,49 +128,49 @@ async function scan(args: string[] = []): Promise<number> {
           const ghosts = (paths ?? []).filter((p) => !existsSync(join(root, p)))
           if (ghosts.length) {
             malformed++
-            findings.push(`  • yatsu-schema: '${s.id}' scenario '${sc.name}' \`${field}\` path(s) not found: ${ghosts.join(', ')} — fix ${y.yatsuPath}`)
+            findings.push(`  • eval-schema: '${s.id}' scenario '${sc.name}' \`${field}\` path(s) not found: ${ghosts.join(', ')} — fix ${y.evalPath}`)
           }
         }
         const codeFiles = sc.code?.length ? sc.code : s.code   // scenario's own subset, else the node's list
         // carry the scenario's tags on the finding line — its SURFACE (e.g. frontend-e2e = browser-measured)
         // is what routes a drift/missing gap to the right measuring hand, so the proactive nudge and a human
-        // reading `spex yatsu scan` both see whether this stale score needs a real e2e/browser pass to refresh.
+        // reading `spex eval lint` both see whether this stale score needs a real e2e/browser pass to refresh.
         const tagStr = sc.tags?.length ? ` [${sc.tags.join(',')}]` : ''
         const r = latest.get(sc.name)
         if (!r) {
           missingScores++
-          findings.push(`  • yatsu-missing: '${s.id}' scenario '${sc.name}'${tagStr} has no reading yet — measure with \`spex yatsu eval ${s.id}\``)
+          findings.push(`  • eval-missing: '${s.id}' scenario '${sc.name}'${tagStr} has no eval yet — measure with \`spex eval add ${s.id}\``)
           continue
         }
         const remSignals = (remarkTracks.get(trackKey(s.id, sc.name))?.remarks ?? []).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt }))
-        const axes = staleAxes(r, codeFiles, y.yatsuPath, idx, scidx, remSignals, probe)
+        const axes = staleAxes(r, codeFiles, y.evalPath, idx, scidx, remSignals, probe, sc)
         if (axes.length) {
           staleScores++
           // a remark-stale scenario is unlocked by a second-party resolve, then a fresh reading; the git axes
-          // by a re-measure. Both read the same word: "re-measure with spex yatsu eval". The anchor axis is
+          // by a re-measure. Both read the same word: "re-measure with spex eval add". The anchor axis is
           // a LOSS, not a change — the reading's commit object no longer exists, so content can't testify.
           const others = axes.filter((a) => a !== 'anchor')
           const why = [
             ...(axes.includes('anchor') ? [`anchor commit ${r.codeSha.slice(0, 7)} is gone — history rewritten and pruned`] : []),
             ...(others.length ? [`${others.join(', ')} changed since ${r.codeSha.slice(0, 7)}`] : []),
           ].join('; ')
-          findings.push(`  • yatsu-drift: '${s.id}' scenario '${sc.name}'${tagStr} is stale (${why}) — re-measure with \`spex yatsu eval ${s.id}\``)
+          findings.push(`  • eval-drift: '${s.id}' scenario '${sc.name}'${tagStr} is stale (${why}) — re-measure with \`spex eval add ${s.id}\``)
         }
       }
       // DANGLING remark tracks (directive 5): a (node, scenario) remark track whose scenario is gone from
-      // yatsu.md AND has no reading (renamed/deleted) — its remarks would surface nowhere on the loss signal.
+      // eval.md AND has no reading (renamed/deleted) — its remarks would surface nowhere on the loss signal.
       // One note per node so the orphan is visible; the remarks stay resolvable/retractable via their refs
-      // (`spex resolve`/`spex retract`), and they age nothing (there is no reading to stale).
+      // (`spex remark resolve`/`spex remark retract`), and they age nothing (there is no reading to stale).
       const declared = new Set(y.scenarios.map((sc) => sc.name))
       const orphans = [...remarkTracks.values()].filter((tr) => tr.node === s.id && tr.remarks.length && !declared.has(tr.scenario) && !latest.has(tr.scenario))
       if (orphans.length) {
         danglingTracks += orphans.length
         const names = orphans.map((o) => `'${o.scenario}' (${o.threadId}, ${o.remarks.length} remark${o.remarks.length > 1 ? 's' : ''})`).join(', ')
-        findings.push(`  • yatsu-dangling: '${s.id}' has ${orphans.length} orphaned remark track(s) — scenario ${names} renamed/deleted; resolve/retract via \`spex resolve <ref>\` / \`spex retract <ref>\` or restore the scenario name`)
+        findings.push(`  • eval-dangling: '${s.id}' has ${orphans.length} orphaned remark track(s) — scenario ${names} renamed/deleted; resolve/retract via \`spex remark resolve <ref>\` / \`spex remark retract <ref>\` or restore the scenario name`)
       }
     } else if (s.code.some((p) => srcRe.test(p))) {
       uncovered++
-      findings.push(`  • yatsu-uncovered: '${s.id}' governs source code but has no yatsu.md — give it a scenario (description + expected) so its loss can be measured`)
+      findings.push(`  • eval-coverage: '${s.id}' governs source code but has no eval.md — give it a scenario (description + expected) so its loss can be measured`)
     }
     if (!findings.length) continue
     flaggedNodes++
@@ -186,13 +186,13 @@ async function scan(args: string[] = []): Promise<number> {
     if (over.length) {
       overOwned = over.length
       const top = over.slice(0, 5).map(([f, c]) => `${f.split('/').pop()}(${c})`).join(', ')
-      console.error(`  • yatsu-owners: ${over.length} file(s) are governed by > ${maxOwners} scenarios — each carries more separately-measured behaviour than one file should. Worst: ${top}. SPLIT the file so each scenario measures its own surface.`)
+      console.error(`  • eval-owners: ${over.length} file(s) are governed by > ${maxOwners} scenarios — each carries more separately-measured behaviour than one file should. Worst: ${top}. SPLIT the file so each scenario measures its own surface.`)
     }
   }
   const scope = changedOnly ? ' --changed' : ''
   const ownersNote = overOwned ? `, ${overOwned} over-owned` : ''
   const danglingNote = danglingTracks ? `, ${danglingTracks} dangling` : ''
-  console.error(`spex yatsu scan${scope}: ${flaggedNodes} node(s) flagged (${malformed} malformed, ${staleScores} stale, ${missingScores} missing, ${uncovered} uncovered${danglingNote}${ownersNote})`)
+  console.error(`spex eval lint${scope}: ${flaggedNodes} node(s) flagged (${malformed} malformed, ${staleScores} stale, ${missingScores} missing, ${uncovered} coverage gap(s)${danglingNote}${ownersNote})`)
   return 0
 }
 
@@ -225,19 +225,19 @@ async function evalCmd(args: string[]): Promise<number> {
   const root = repoRoot()
   const bad = rejectUnknownEvalFlag(args)
   if (bad) {
-    console.error(`spex yatsu eval: unknown flag '${bad}' — accepts --scenario --pass --fail --note --image --result --video --timeline`)
+    console.error(`spex eval add: unknown flag '${bad}' — accepts --scenario --pass --fail --note --image --result --video --timeline`)
     return 2
   }
   const sel = positional(args)
   const ref = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)   // node args tolerate @/[[ ]] sigils ([[mentions]])
-  if (!ref) { console.error('spex yatsu eval .: no current node (no .session/node-branch here) — name a node'); return 2 }
-  // resolve LOUD ([[yatsu-core]]): exact canonical id, else a unique bare leaf; an ambiguous leaf lists its
+  if (!ref) { console.error('spex eval add .: no current node (no .session/node-branch here) — name a node'); return 2 }
+  // resolve LOUD ([[eval-core]]): exact canonical id, else a unique bare leaf; an ambiguous leaf lists its
   // candidate canonical ids instead of filing against an arbitrary node.
-  const res = resolveYatsuNode(await gatherNodes(root), ref)
-  if (!res.ok) { console.error(`spex yatsu eval: ${res.error}`); return 1 }
+  const res = resolveEvalNode(await gatherNodes(root), ref)
+  if (!res.ok) { console.error(`spex eval add: ${res.error}`); return 1 }
   const node = res.node
   const id = node.id
-  if (!node.scenarios.length) { console.error(`spex yatsu eval: '${id}' declares no scenarios in its yatsu.md`); return 1 }
+  if (!node.scenarios.length) { console.error(`spex eval add: '${id}' declares no scenarios in its eval.md`); return 1 }
 
   // which scenario this measurement is OF: --scenario, or the sole scenario when there is exactly one.
   const names = node.scenarios.map((s) => s.name)
@@ -245,13 +245,13 @@ async function evalCmd(args: string[]): Promise<number> {
   let scenario = scName ? node.scenarios.find((s) => s.name === scName) : node.scenarios.length === 1 ? node.scenarios[0] : undefined
   if (!scenario) {
     const why = scName ? `has no scenario '${scName}'` : `declares ${node.scenarios.length} scenarios — name one with --scenario <name>`
-    console.error(`spex yatsu eval: '${id}' ${why} — declared: ${names.join(', ')}`)
+    console.error(`spex eval add: '${id}' ${why} — declared: ${names.join(', ')}`)
     return 1
   }
 
   // the verdict the agent reached (required — a measurement without one is the legacy shape, not a filing).
   const verdict = parseVerdict(args)
-  if (!verdict) { console.error('spex yatsu eval: a verdict is required — --pass or --fail (either may add --note <text>)'); return 2 }
+  if (!verdict) { console.error('spex eval add: a verdict is required — --pass or --fail (either may add --note <text>)'); return 2 }
 
   // the evidence the agent captured (optional; a LIST now — REPEATABLE --image plus an optional --result
   // and/or --video, in any combination). The bytes go to the content-addressed cache exactly the same
@@ -278,12 +278,12 @@ async function evalCmd(args: string[]): Promise<number> {
   const timeline = flag(args, 'timeline')
   let timelineBlob: string | undefined
   if (timeline !== undefined) {
-    if (!evidence.length) { console.error('spex yatsu eval: --timeline needs axis-bearing evidence — attach the --video/--image/--result whose axis its steps anchor to'); return 2 }
+    if (!evidence.length) { console.error('spex eval add: --timeline needs axis-bearing evidence — attach the --video/--image/--result whose axis its steps anchor to'); return 2 }
     let parsed: unknown
-    try { parsed = JSON.parse(readFileSync(timeline, 'utf8')) } catch { console.error(`spex yatsu eval: --timeline ${timeline} is not readable JSON`); return 2 }
+    try { parsed = JSON.parse(readFileSync(timeline, 'utf8')) } catch { console.error(`spex eval add: --timeline ${timeline} is not readable JSON`); return 2 }
     const terrs = validateTimeline(parsed)
     if (terrs.length) {
-      console.error('spex yatsu eval: invalid step-timeline:')
+      console.error('spex eval add: invalid step-timeline:')
       for (const e of terrs) console.error(`    ${e}`)
       return 2
     }
@@ -291,7 +291,7 @@ async function evalCmd(args: string[]): Promise<number> {
     const present = new Set(evidence.map((e) => AXIS_FOR_KIND[e.kind]))
     if (!present.has(axis)) {
       const have = evidence.map((e) => `${e.kind}→${AXIS_FOR_KIND[e.kind]}`).join(', ')
-      console.error(`spex yatsu eval: --timeline axis '${axis}' matches none of this reading's evidence (${have}) — a step-map's axis must be the axis of an attached evidence entry`)
+      console.error(`spex eval add: --timeline axis '${axis}' matches none of this eval's evidence (${have}) — a step-map's axis must be the axis of an attached evidence entry`)
       return 2
     }
     timelineBlob = putBlob(Buffer.from(JSON.stringify(parsed)))
@@ -300,6 +300,8 @@ async function evalCmd(args: string[]): Promise<number> {
   const reading: Reading = {
     scenario: scenario.name,
     codeSha: headSha(root),
+    // the contract this measurement was taken against — decides the scenario freshness axis by pure compare
+    scenarioHash: scenarioHash(scenario),
     ...(evidence.length ? { evidence } : {}),
     ...(timelineBlob ? { timelineBlob } : {}),
     // the filing session — the originator an eval-comment thread loops in ([[mentions]]); absent if unknown
@@ -312,17 +314,17 @@ async function evalCmd(args: string[]): Promise<number> {
     ? evidence.map((e) => `${e.kind} ${e.hash.slice(0, 12)}…`).join(', ') + (timelineBlob ? ' +timeline' : '')
     : 'no evidence'
   console.log(`  ✓ '${id}' scenario '${scenario.name}' → ${verdictText(verdict)} @ ${reading.codeSha.slice(0, 7)} (${ev})`)
-  console.log(`spex yatsu eval: 1 measurement filed`)
+  console.log(`spex eval add: 1 measurement filed`)
 
   // @@@mis-anchor guard - a codeSha names a COMMIT, never a working tree: filed over uncommitted governed
   // edits, this reading claims a verdict at HEAD while HEAD lacks the code actually measured — wrong from
   // birth, and the stale flag after the next commit is freshness exposing it, not an engine bug. Warn,
   // never block: the honest flow is measure on the tree until green → commit that tested tree → file.
-  const dirty = dirtyGoverned(root, [...(scenario.code?.length ? scenario.code : node.codeFiles), node.yatsuPath])
+  const dirty = dirtyGoverned(root, [...(scenario.code?.length ? scenario.code : node.codeFiles), node.evalPath])
   if (dirty.length) {
-    console.error(`  ⚠ mis-anchored reading: uncommitted changes in governed ${dirty.join(', ')}`)
-    console.error(`    this reading anchors to HEAD ${reading.codeSha.slice(0, 7)}, which does NOT contain those edits — it claims a ${verdict.status} for code that never ran, and the commit that lands them will (correctly) read it stale.`)
-    console.error(`    the honest flow: measure on the tree until green → commit that just-tested tree (code+spec) → THEN file the reading against the clean HEAD (retract this one if it recorded the dirty run).`)
+    console.error(`  ⚠ mis-anchored eval: uncommitted changes in governed ${dirty.join(', ')}`)
+    console.error(`    this eval anchors to HEAD ${reading.codeSha.slice(0, 7)}, which does NOT contain those edits — it claims a ${verdict.status} for code that never ran, and the commit that lands them will (correctly) read it stale.`)
+    console.error(`    the honest flow: measure on the tree until green → commit that just-tested tree (code+spec) → THEN file the eval against the clean HEAD (retract this one if it recorded the dirty run).`)
   }
   return 0
 }
@@ -355,11 +357,11 @@ function parseVerdict(args: string[]): Verdict | null {
 const RETRACT_VALUE_FLAGS = new Set(['scenario', 'ts', 'note'])
 const RETRACT_BOOL_FLAGS = new Set(['last'])
 
-// `spex yatsu retract` — the sanctioned inverse of eval: undo a botched filing through the SAME surface
+// `spex eval retract` — the sanctioned inverse of eval: undo a botched filing through the SAME surface
 // that wrote it. It appends a RETRACTION event to the sidecar (append-only stays true; the target line
 // stays as history; git carries who/when/why) — never a deleted line. The effective scoreboard then drops
 // the retracted reading everywhere at once: the previous reading becomes the latest again, or the scenario
-// honestly returns to yatsu-missing. Default target is the scenario's LATEST effective reading (--last is
+// honestly returns to eval-missing. Default target is the scenario's LATEST effective reading (--last is
 // that default made explicit — repeated retracts peel junk e2e/smoke filings back one at a time); --ts
 // pins an exact reading by its timestamp.
 async function retractCmd(args: string[]): Promise<number> {
@@ -370,41 +372,41 @@ async function retractCmd(args: string[]): Promise<number> {
     const name = a.slice(2)
     if (RETRACT_VALUE_FLAGS.has(name)) { i++; continue }
     if (RETRACT_BOOL_FLAGS.has(name)) continue
-    console.error(`spex yatsu retract: unknown flag '${a}' — accepts --scenario --last --ts --note`)
+    console.error(`spex eval retract: unknown flag '${a}' — accepts --scenario --last --ts --note`)
     return 2
   }
   const sel = positional(args)
   const ref = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
-  if (!ref) { console.error('spex yatsu retract .: no current node (no .session/node-branch here) — name a node'); return 2 }
+  if (!ref) { console.error('spex eval retract .: no current node (no .session/node-branch here) — name a node'); return 2 }
   // node resolution mirrors eval's: exact canonical id, else a unique bare leaf, ambiguous fails loud.
-  const res = resolveYatsuNode(yatsuNodes(root), ref)
-  if (!res.ok) { console.error(`spex yatsu retract: ${res.error}`); return 1 }
+  const res = resolveEvalNode(evalNodes(root), ref)
+  if (!res.ok) { console.error(`spex eval retract: ${res.error}`); return 1 }
   const node = res.node
   const id = node.id
 
   // which scenario, resolved exactly as eval resolves it: --scenario, or the sole declared scenario. A
   // reading for a since-deleted scenario is still retractable by naming it — the sidecar knows names the
-  // yatsu.md may have dropped.
+  // eval.md may have dropped.
   const scName = flag(args, 'scenario')
   const declared = node.scenarios.map((s) => s.name)
   const scenario = scName ?? (declared.length === 1 ? declared[0] : undefined)
   if (!scenario) {
-    console.error(`spex yatsu retract: '${id}' declares ${declared.length} scenarios — name one with --scenario <name> (declared: ${declared.join(', ')})`)
+    console.error(`spex eval retract: '${id}' declares ${declared.length} scenarios — name one with --scenario <name> (declared: ${declared.join(', ')})`)
     return 1
   }
 
   const ts = flag(args, 'ts')
-  if (ts !== undefined && has(args, 'last')) { console.error('spex yatsu retract: --ts and --last conflict — pin one reading or take the latest, not both'); return 2 }
+  if (ts !== undefined && has(args, 'last')) { console.error('spex eval retract: --ts and --last conflict — pin one eval or take the latest, not both'); return 2 }
   const effective = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
   if (!effective.length) {
     const { readings } = readSidecar(node.sidecarPath)
     const had = readings.some((r) => r.scenario === scenario)
-    console.error(`spex yatsu retract: '${id}' scenario '${scenario}' has no ${had ? 'un-retracted ' : ''}reading${had ? ' left' : ''} — nothing to retract`)
+    console.error(`spex eval retract: '${id}' scenario '${scenario}' has no ${had ? 'un-retracted ' : ''}eval${had ? ' left' : ''} — nothing to retract`)
     return 1
   }
   const target = ts !== undefined ? effective.find((r) => r.ts === ts) : effective[effective.length - 1]
   if (!target) {
-    console.error(`spex yatsu retract: '${id}' scenario '${scenario}' has no un-retracted reading @ ${ts} — readings: ${effective.map((r) => r.ts).join(', ')}`)
+    console.error(`spex eval retract: '${id}' scenario '${scenario}' has no un-retracted eval @ ${ts} — evals: ${effective.map((r) => r.ts).join(', ')}`)
     return 1
   }
 
@@ -420,9 +422,54 @@ async function retractCmd(args: string[]): Promise<number> {
   const left = readReadings(node.sidecarPath).filter((r) => r.scenario === scenario)
   const now = left.length
     ? `latest is now ${left[left.length - 1].ts} (${verdictText(left[left.length - 1].verdict)})`
-    : 'the scenario is unmeasured again (yatsu-missing)'
-  console.log(`  ⟲ '${id}' scenario '${scenario}' reading @ ${target.ts} (${verdictText(target.verdict)}) retracted — ${now}`)
-  console.log('spex yatsu retract: 1 reading retracted (an appended event — commit the sidecar so the retraction is attributed)')
+    : 'the scenario is unmeasured again (eval-missing)'
+  console.log(`  ⟲ '${id}' scenario '${scenario}' eval @ ${target.ts} (${verdictText(target.verdict)}) retracted — ${now}`)
+  console.log('spex eval retract: 1 eval retracted (an appended event — commit the sidecar so the retraction is attributed)')
+  return 0
+}
+
+// `spex eval ok` — the HUMAN sign-off on a scenario's latest reading ([[human-ok]]): appends a monotonic
+// human-ok event bound to that one immutable reading (a newer reading or live-computed staleness brings the
+// scenario back on its own — no un-ok verb exists). CLI parity with the dashboard's affordance (LAW L);
+// identity is the surface's: 'human' here — and a GOVERNED session is REFUSED, because the sign-off is the
+// human's own deliberate judgment and an agent blessing its own reading would hide it from exactly the
+// review the ok certifies (the no-self-resolve analogue). Flag set closed, like every eval verb.
+async function okCmd(args: string[]): Promise<number> {
+  const root = repoRoot()
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (!a.startsWith('--')) continue
+    if (a === '--scenario') { i++; continue }
+    console.error(`spex eval ok: unknown flag '${a}' — accepts --scenario`)
+    return 2
+  }
+  if (envSessionId()) {
+    console.error('spex eval ok: refusing under a governed session — human-ok is the HUMAN\'s sign-off, never an agent\'s self-blessing. Ask the human to ok it from the dashboard or their own terminal; an agent\'s judgment on a reading is a remark (`spex remark add`).')
+    return 1
+  }
+  const sel = positional(args)
+  if (!sel || sel === '.') { console.error('spex eval ok: name a node — usage: spex eval ok <node> --scenario <name>'); return 2 }
+  const node = stripRefSigil(sel)
+  const scName = flag(args, 'scenario')
+  const res = resolveEvalNode(evalNodes(root), node)
+  if (!res.ok) { console.error(`spex eval ok: ${res.error}`); return 1 }
+  const declared = res.node.scenarios.map((s) => s.name)
+  const scenario = scName ?? (declared.length === 1 ? declared[0] : undefined)
+  if (!scenario) {
+    console.error(`spex eval ok: '${res.node.id}' declares ${declared.length} scenarios — name one with --scenario <name> (declared: ${declared.join(', ')})`)
+    return 1
+  }
+  const { fileHumanOk } = await import('./humanok.js')
+  const r = fileHumanOk(res.node.id, scenario, 'human')
+  if (!r.ok) { console.error(`spex eval ok: ${r.error}`); return 1 }
+  if (r.already) {
+    console.log(`spex eval ok: '${res.node.id}' scenario '${scenario}' reading @ ${r.humanOk.okTs} is already human-ok'd (by ${r.humanOk.by}, ${r.humanOk.ts}) — monotonic, nothing appended`)
+    return 0
+  }
+  console.log(`  ☑ '${res.node.id}' scenario '${scenario}' reading @ ${r.humanOk.okTs} (${r.humanOk.okSha.slice(0, 7)}) human-ok'd`)
+  console.log(r.landed === 'committed'
+    ? 'spex eval ok: 1 sign-off filed (committed straight to the trunk)'
+    : 'spex eval ok: 1 sign-off filed (an appended event — commit the sidecar so the sign-off lands)')
   return 0
 }
 
@@ -444,7 +491,7 @@ async function clean(args: string[]): Promise<number> {
   const before = listBlobs().length
   const removed = gc(referenced)
   const mode = all ? 'all' : keepLatest ? 'keep-latest' : 'unreferenced'
-  console.log(`spex yatsu clean: removed ${removed.length} blob(s), kept ${before - removed.length} (${mode})`)
+  console.log(`spex eval clean: removed ${removed.length} evidence file(s), kept ${before - removed.length} (${mode})`)
   return 0
 }
 
@@ -457,18 +504,18 @@ function checkStaged(): number {
   const blobs = staged.filter(isStrayBlob)
   if (blobs.length) {
     bad = true
-    console.error('✗ SpexCode yatsu: stray evidence blob(s) staged — blobs live in the shared git common dir, never in the tree:')
+    console.error('✗ SpexCode eval: stray evidence file(s) staged — evidence lives in the shared git common dir, never in the tree:')
     for (const o of blobs) console.error(`    ${o}`)
-    console.error('  Unstage them (git rm --cached <path>); a reading references its blob by hash, it never commits the bytes.')
+    console.error('  Unstage them (git rm --cached <path>); an eval references its evidence by hash, it never commits the bytes.')
   }
 
-  for (const rel of staged.filter((p) => p === YATSU_FILE || p.endsWith('/' + YATSU_FILE))) {
+  for (const rel of staged.filter((p) => p === EVAL_FILE || p.endsWith('/' + EVAL_FILE))) {
     const abs = join(root, rel)
     if (!existsSync(abs)) continue   // staged deletion — nothing to validate
     const errs = validateScenarios(readFileSync(abs, 'utf8'), tagLibrary)
     if (!errs.length) continue
     bad = true
-    console.error(`✗ SpexCode yatsu: ${rel} — invalid scenario schema:`)
+    console.error(`✗ SpexCode eval: ${rel} — invalid scenario schema:`)
     for (const e of errs) console.error(`    ${e}`)
   }
 
@@ -479,12 +526,12 @@ async function show(args: string[]): Promise<number> {
   const root = repoRoot()
   const sel = positional(args)
   const ref = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
-  if (!ref) { console.error('spex yatsu show .: no current node (no .session/node-branch here) — name a node'); return 2 }
+  if (!ref) { console.error('spex eval ls .: no current node (no .session/node-branch here) — name a node'); return 2 }
   // resolve LOUD before the timeline: an ambiguous bare leaf must list its candidate canonical ids, never
-  // fall through to a false "declares no scenarios". A ref matching NO yatsu node still renders the honest
-  // hasYatsu:false line — a spec node without a yatsu.md is not an error to look at.
-  const res = resolveYatsuNode(yatsuNodes(root), ref)
-  if (!res.ok && res.ambiguous) { console.error(`spex yatsu show: ${res.error}`); return 1 }
+  // fall through to a false "declares no scenarios". A ref matching NO measurable node still renders the honest
+  // hasEvalFile:false line — a spec node without an eval.md is not an error to look at.
+  const res = resolveEvalNode(evalNodes(root), ref)
+  if (!res.ok && res.ambiguous) { console.error(`spex eval ls: ${res.error}`); return 1 }
   const tl = await evalTimeline(res.ok ? res.node.id : ref)   // no ctx → evalTimeline derives specs + driftIndex itself for this one id
   if (has(args, 'json')) { console.log(JSON.stringify(tl, null, 2)); return 0 }
   console.log(formatTimeline(tl))
@@ -501,12 +548,12 @@ function verdictText(v: Verdict | undefined): string {
 }
 
 export function formatTimeline(tl: EvalTimeline): string {
-  if (!tl.hasYatsu) return `spex yatsu show: '${tl.node}' declares no scenarios (no yatsu.md)`
+  if (!tl.hasEvalFile) return `spex eval ls: '${tl.node}' declares no scenarios (no eval.md)`
   // the retraction trace, newest first — the undo stays visible through the same surface that shows readings.
   const retractLines = (tl.retractions ?? []).map((x) =>
-    `  ⟲ retracted: scenario '${x.scenario}' reading @ ${x.retracts}${x.note ? ` — ${x.note}` : ''}${x.by ? `  by ${x.by}` : ''}  ${x.ts}`)
+    `  ⟲ retracted: scenario '${x.scenario}' eval @ ${x.retracts}${x.note ? ` — ${x.note}` : ''}${x.by ? `  by ${x.by}` : ''}  ${x.ts}`)
   if (!tl.readings.length) {
-    const head = `spex yatsu show: '${tl.node}' has scenarios but no reading yet — run \`spex yatsu eval ${tl.node}\``
+    const head = `spex eval ls: '${tl.node}' has scenarios but no eval yet — run \`spex eval add ${tl.node}\``
     return retractLines.length ? [head, '', ...retractLines].join('\n') : head
   }
   const w = Math.max(...tl.readings.map((r) => r.scenario.length))
@@ -519,63 +566,132 @@ export function formatTimeline(tl: EvalTimeline): string {
     const ev = list.length
       ? list.map((e) => e.state === 'miss' ? 'miss original file' : `${e.kind} ${(e.hash ?? '').slice(0, 12)}…`).join(', ')
       : 'no evidence'
-    const head = `  ${r.scenario.padEnd(w)}  ${verdictText(r.verdict)}  ${badge}  ${r.codeSha.slice(0, 7)}  ${ev}  ${r.ts}`
+    const okTag = r.humanOk ? `  ☑ human-ok (${r.humanOk.by})` : ''
+    const head = `  ${r.scenario.padEnd(w)}  ${verdictText(r.verdict)}  ${badge}${okTag}  ${r.codeSha.slice(0, 7)}  ${ev}  ${r.ts}`
     return r.expected ? [head, `  ${' '.repeat(w)}  expected: ${r.expected}`] : [head]
   })
-  return [`spex yatsu show: '${tl.node}' — ${tl.readings.length} reading(s), newest first`, '', ...lines, ...retractLines].join('\n')
+  return [`spex eval ls: '${tl.node}' — ${tl.readings.length} eval(s), newest first`, '', ...lines, ...retractLines].join('\n')
 }
 
-export async function runYatsu(args: string[]): Promise<number> {
+// `spex eval scenario ls [<node>|.] [--unmeasured] [--json]` — the DECLARED half of the scoreboard: list
+// scenarios (the measurement contracts) rather than readings. Bare = every measurable node's scenarios
+// (the collection view); a <node>/`.` scopes to one node. --unmeasured keeps only scenarios with NO
+// effective reading — never measured, or every filing retracted — the blind-spot worklist a measuring
+// hand picks from. Flag set closed, like every eval verb.
+async function scenarioLs(args: string[]): Promise<number> {
+  for (const a of args) {
+    if (!a.startsWith('--')) continue
+    const name = a.slice(2)
+    if (name !== 'unmeasured' && name !== 'json') {
+      console.error(`spex eval scenario ls: unknown flag '${a}' — accepts --unmeasured --json`)
+      return 2
+    }
+  }
+  const root = repoRoot()
+  const sel = positional(args)
+  let nodes = evalNodes(root)
+  if (sel) {
+    const ref = sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
+    if (!ref) { console.error('spex eval scenario ls .: no current node (no session/node-branch here) — name a node'); return 2 }
+    const res = resolveEvalNode(nodes, ref)
+    if (!res.ok) { console.error(`spex eval scenario ls: ${res.error}`); return 1 }
+    nodes = [res.node]
+  }
+  const unmeasuredOnly = has(args, 'unmeasured')
+  type Row = { node: string; scenario: string; tags?: string[]; measured: boolean; latest?: { verdict?: Verdict; ts: string } }
+  const rows: Row[] = []
+  for (const n of nodes) {
+    const latest = latestPerScenario(readReadings(n.sidecarPath))
+    for (const sc of n.scenarios) {
+      const r = latest.get(sc.name)
+      if (unmeasuredOnly && r) continue
+      rows.push({
+        node: n.id, scenario: sc.name,
+        ...(sc.tags?.length ? { tags: sc.tags } : {}),
+        measured: !!r,
+        ...(r ? { latest: { ...(r.verdict ? { verdict: r.verdict } : {}), ts: r.ts } } : {}),
+      })
+    }
+  }
+  if (has(args, 'json')) { console.log(JSON.stringify(rows, null, 2)); return 0 }
+  if (!rows.length) {
+    console.log(`spex eval scenario ls: ${unmeasuredOnly ? 'no unmeasured scenarios' : 'no scenarios declared'}${sel ? ` on '${nodes[0]?.id ?? sel}'` : ''}`)
+    return 0
+  }
+  const w = Math.max(...rows.map((r) => r.node.length))
+  for (const r of rows) {
+    const tagStr = r.tags?.length ? ` [${r.tags.join(',')}]` : ''
+    const state = r.measured ? `${verdictText(r.latest!.verdict)}  ${r.latest!.ts}` : '∅ unmeasured'
+    console.log(`  ${r.node.padEnd(w)}  ${r.scenario}${tagStr}  —  ${state}`)
+  }
+  const un = rows.filter((r) => !r.measured).length
+  console.log(`spex eval scenario ls: ${rows.length} scenario(s)${unmeasuredOnly ? ', all unmeasured' : un ? ` (${un} unmeasured)` : ''}`)
+  return 0
+}
+
+// the `spex eval` drawer's node-scoped verbs ([[cli-surface]]): add (file a measurement) · ls (a node's
+// reading timeline) · scenario ls (the declared contracts, --unmeasured = blind spots) · lint (the
+// measurement-layer lint — advisory, always exit 0) · ok (the human sign-off) · retract · clean.
+// The session-scoped read (`spex eval ls --session <SEL>`) is intercepted in cli.ts before this runs;
+// `check-staged` is hook plumbing, exported separately for `spex internal check-staged`.
+export async function runEval(args: string[]): Promise<number> {
   const sub = args[0]
-  if (sub === 'scan') return scan(args.slice(1))
-  if (sub === 'eval') return evalCmd(args.slice(1))
+  if (sub === 'lint') return scan(args.slice(1))
+  if (sub === 'add') return evalCmd(args.slice(1))
+  if (sub === 'ok') return okCmd(args.slice(1))
   if (sub === 'retract') return retractCmd(args.slice(1))
   if (sub === 'clean') return clean(args.slice(1))
-  if (sub === 'show') return show(args.slice(1))
-  if (sub === 'check-staged') return checkStaged()
-  console.error('spex yatsu: scan [--changed] | eval [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>] [--image <path> …repeatable] [--result <path|->] [--video <path>] [--timeline <json>] | retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>] | show [.|<node>] [--json] | clean [--keep-latest|--all]')
+  if (sub === 'ls') return show(args.slice(1))
+  if (sub === 'scenario') {
+    if (args[1] === 'ls') return scenarioLs(args.slice(2))
+    console.error('spex eval scenario: ls [<node>|.] [--unmeasured] [--json] — list declared scenarios (the measurement contracts)')
+    return 2
+  }
+  console.error('spex eval: add [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>] [--image <path> …repeatable] [--result <path|->] [--video <path>] [--timeline <json>] | ls [.|<node>] [--json] | ls --session <SEL> [--export] | scenario ls [<node>|.] [--unmeasured] [--json] | lint [--changed] | ok <node> [--scenario <name>] | retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>] | clean [--keep-latest|--all]')
   return 2
 }
 
-// `spex blob put <file|->` / `spex blob get <hash> [-o <file>]` ([[blob-put]], [[blob-get]]) — the bare
+export { checkStaged }
+
+// `spex evidence put <file|->` / `spex evidence get <hash> [-o <file>]` ([[evidence-put]], [[evidence-get]]) — the bare
 // evidence-transport pair: put stashes bytes in the shared content-addressed cache and prints the hash,
-// WITHOUT filing a reading (`yatsu eval --video` couples the two); get is its symmetric read — hash in,
+// WITHOUT filing a reading (`eval add --video` couples the two); get is its symmetric read — hash in,
 // bytes out. putBlob is idempotent by content, so re-putting re-seeds a checkout whose cache lacks a blob
 // some thread already references by hash (the clone-evidence-404 repair).
-export async function runBlob(args: string[]): Promise<number> {
+export async function runEvidence(args: string[]): Promise<number> {
   if (args[0] === 'put' && args[1] !== undefined) return blobPut(args[1])
   if (args[0] === 'get') return blobGet(args.slice(1))
-  console.error('spex blob: put <file|-> — stash bytes in the shared evidence cache, print the content hash')
-  console.error('           get <hash> [-o <file>] — read a blob back: local cache first, backend fallback')
+  console.error('spex evidence: put <file|-> — stash bytes in the shared evidence cache, print the content hash')
+  console.error('           get <hash> [-o <file>] — read evidence back: local cache first, backend fallback')
   return 2
 }
 
 function blobPut(file: string): number {
   let bytes: Buffer
   try { bytes = readFileSync(file === '-' ? 0 : file) } catch (e) {
-    console.error(`spex blob put: cannot read ${file}: ${(e as Error).message}`)
+    console.error(`spex evidence put: cannot read ${file}: ${(e as Error).message}`)
     return 2
   }
-  if (bytes.length === 0) { console.error('spex blob put: refusing an empty blob'); return 2 }
+  if (bytes.length === 0) { console.error('spex evidence put: refusing empty evidence'); return 2 }
   console.log(putBlob(bytes))
   return 0
 }
 
 // the read half: ① the local content-addressed cache (the evidence usually IS on this disk — no backend
-// needed), ② on a local miss the same GET /api/yatsu/blob/:hash the dashboard streams from (the blob may
+// needed), ② on a local miss the same GET /api/evidence/:hash the dashboard streams from (the blob may
 // have been pruned here, or put on another machine sharing the backend), ③ both missed → fail loud naming
 // both paths. No third read mechanism — this reuses readBlobByHash and the existing endpoint verbatim.
 async function blobGet(args: string[]): Promise<number> {
   const oIdx = args.indexOf('-o')
   const out = oIdx >= 0 ? args[oIdx + 1] : undefined
-  if (oIdx >= 0 && (out === undefined || out.startsWith('-'))) { console.error('spex blob get: -o needs a <file>'); return 2 }
+  if (oIdx >= 0 && (out === undefined || out.startsWith('-'))) { console.error('spex evidence get: -o needs a <file>'); return 2 }
   const hash = args.find((a, i) => (oIdx < 0 || (i !== oIdx && i !== oIdx + 1)) && !a.startsWith('-'))
-  if (!hash) { console.error('spex blob get: usage: spex blob get <hash> [-o <file>]'); return 2 }
+  if (!hash) { console.error('spex evidence get: usage: spex evidence get <hash> [-o <file>]'); return 2 }
   const local = readBlobByHash(hash)   // validates 64-hex before touching the fs, then reads the shared cache
   if (local.ok) return emitBlob(local.bytes, out)
-  if (local.reason === 'invalid') { console.error(`spex blob get: bad hash '${hash}' — a blob hash is 64 hex chars`); return 2 }
+  if (local.reason === 'invalid') { console.error(`spex evidence get: bad hash '${hash}' — an evidence hash is 64 hex chars`); return 2 }
   const { apiBase } = await import('../../spec-cli/src/sessions.js')
-  const url = `${await apiBase()}/api/yatsu/blob/${hash}`
+  const url = `${await apiBase()}/api/evidence/${hash}`
   let backendMiss: string
   try {
     const r = await fetch(url)
@@ -584,8 +700,8 @@ async function blobGet(args: string[]): Promise<number> {
   } catch (e) {
     backendMiss = `unreachable (${(e as Error).message})`
   }
-  console.error(`spex blob get: ${hash} — not found on either path:`)
-  console.error(`  local cache: ${blobPath(hash)} — no such blob (pruned, or put on another machine)`)
+  console.error(`spex evidence get: ${hash} — not found on either path:`)
+  console.error(`  local cache: ${blobPath(hash)} — no such evidence (pruned, or put on another machine)`)
   console.error(`  backend:     ${url} — ${backendMiss}`)
   return 1
 }
@@ -595,12 +711,12 @@ async function blobGet(args: string[]): Promise<number> {
 function emitBlob(bytes: Buffer, out?: string): number {
   if (out !== undefined) {
     try { writeFileSync(out, bytes) } catch (e) {
-      console.error(`spex blob get: cannot write ${out}: ${(e as Error).message}`)
+      console.error(`spex evidence get: cannot write ${out}: ${(e as Error).message}`)
       return 2
     }
     return 0
   }
-  if (process.stdout.isTTY) console.error(`spex blob get: writing ${bytes.length} raw bytes to a tty — pipe it or use -o <file>`)
+  if (process.stdout.isTTY) console.error(`spex evidence get: writing ${bytes.length} raw bytes to a tty — pipe it or use -o <file>`)
   process.stdout.write(bytes)
   return 0
 }