spexcode 0.2.8 → 0.3.0

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

@@ -10,9 +10,9 @@ import { isUiPath } from './cli.js'
 
 type ScoreState = 'pass' | 'fail' | 'stalePass' | 'staleFail' | 'empty' | null
 
-// one yatsu reading rendered for the proof: the latest measurement of one scenario, with its evidence
+// one eval reading rendered for the export: the latest measurement of one scenario, with its evidence
 // resolved to inline bytes (an image data-URI, or transcript text) so the document is self-contained.
-export type ProofReading = {
+export type ExportReading = {
   scenario: string
   expected: string
   verdict?: EvalEntry['verdict']
@@ -32,7 +32,7 @@ export type ProofReading = {
 }
 
 // patch ''/old·new null = nothing to show (added → no old, deleted → no new), past the enrichment cap (omitted), or too large (truncated)
-export type ProofFile = ReviewDiffFile & {
+export type ExportFile = ReviewDiffFile & {
   patch: string
   oldText: string | null
   newText: string | null
@@ -41,24 +41,24 @@ export type ProofFile = ReviewDiffFile & {
 }
 
 // one changed spec node: its diff slice (the files this node owns that the session touched) joined with its
-// measured loss (latest reading per scenario). A frontend node with no yatsu.md is an honest blind spot.
-export type ProofNode = {
+// measured loss (latest reading per scenario). A frontend node with no eval.md is an honest blind spot.
+export type ExportNode = {
   id: string
   title: string
   hue: number
   desc: string
-  files: ProofFile[]
+  files: ExportFile[]
   additions: number
   deletions: number
-  hasYatsu: boolean
+  hasEvalFile: boolean
   uncoveredFrontend: boolean
   score: ScoreState
-  readings: ProofReading[]
+  readings: ExportReading[]
 }
 
-export type ProofGate = { label: string; ok: boolean; detail: string }
+export type ExportGate = { label: string; ok: boolean; detail: string }
 
-export type ProofModel = {
+export type ExportModel = {
   id: string
   node: string | null
   branch: string | null
@@ -66,14 +66,14 @@ export type ProofModel = {
   generatedAt: string
   ahead: number
   dirtyNonRuntime: number
-  gates: ProofGate[]
-  score: { passed: number; total: number; fresh: number }   // the yatsu summary across all nodes
-  nodes: ProofNode[]
-  otherFiles: ProofFile[]        // changed files no spec node claims
+  gates: ExportGate[]
+  score: { passed: number; total: number; fresh: number }   // the eval summary across all nodes
+  nodes: ExportNode[]
+  otherFiles: ExportFile[]        // changed files no spec node claims
 }
 
 // null when no session has that id (route → 404).
-export async function buildProofModel(id: string): Promise<ProofModel | null> {
+export async function buildExportModel(id: string): Promise<ExportModel | null> {
   const payload = await reviewPayload(id)
   if (!payload) return null
   const specs = await loadSpecs()
@@ -89,7 +89,7 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   // extra fetch. Capped at MAX_ENRICHED_FILES so a huge changeset can't bloat the page; the rest keep their
   // row but say so (omitted), never silently blank.
   const base = wtPath ? (await gitA(['-C', wtPath, 'merge-base', mainBranch(), 'HEAD'])).trim() : ''
-  const enriched = new Map<string, ProofFile>()
+  const enriched = new Map<string, ExportFile>()
   let budget = MAX_ENRICHED_FILES
   for (const f of payload.diff) {
     if (wtPath && base && budget > 0) { enriched.set(f.path, await enrichFile(wtPath, base, f)); budget-- }
@@ -97,8 +97,8 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   }
 
   // group the session's real changes (merge-base diff) by the spec node that owns each file.
-  const byNode = new Map<string, ProofFile[]>()
-  const otherFiles: ProofFile[] = []
+  const byNode = new Map<string, ExportFile[]>()
+  const otherFiles: ExportFile[] = []
   for (const f of payload.diff) {
     const nid = nodeForFile(f.path, specs, payload.node)
     const pf = enriched.get(f.path)!
@@ -108,13 +108,13 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   // the session's primary node always appears, even if it has no file in the diff yet.
   if (payload.node && specById.has(payload.node) && !byNode.has(payload.node)) byNode.set(payload.node, [])
 
-  const nodes: ProofNode[] = []
+  const nodes: ExportNode[] = []
   let passed = 0, total = 0, fresh = 0
   for (const [nid, files] of byNode) {
     const spec = specById.get(nid)
     const tl = await evalTimeline(nid, ctx)
     const latest = declaredLatest(tl)
-    const readings = await Promise.all(latest.map(toProofReading))
+    const readings = await Promise.all(latest.map(toExportReading))
     for (const r of latest) {
       total++
       if (r.fresh) fresh++
@@ -128,9 +128,9 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
       files,
       additions: files.reduce((a, f) => a + f.additions, 0),
       deletions: files.reduce((a, f) => a + f.deletions, 0),
-      hasYatsu: tl.hasYatsu,
-      uncoveredFrontend: !tl.hasYatsu && (spec?.code ?? []).some(isUiPath),
-      score: nodeScore(tl.hasYatsu, latest),
+      hasEvalFile: tl.hasEvalFile,
+      uncoveredFrontend: !tl.hasEvalFile && (spec?.code ?? []).some(isUiPath),
+      score: nodeScore(tl.hasEvalFile, latest),
       readings,
     })
   }
@@ -156,8 +156,8 @@ export async function buildProofModel(id: string): Promise<ProofModel | null> {
   }
 }
 
-// the gate checklist, derived from the cockpit payload's gates (the SAME numbers `spex review` prints).
-function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): ProofGate[] {
+// the gate checklist, derived from the cockpit payload's gates (the SAME numbers `spex session review` prints).
+function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): ExportGate[] {
   const g = p.gates
   return [
     { label: 'lint', ok: g.lint.errorCount === 0, detail: `${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)` },
@@ -170,7 +170,7 @@ function gateRows(p: NonNullable<Awaited<ReturnType<typeof reviewPayload>>>): Pr
 // gitA returns '' for a missing path — exactly the added/deleted (and best-effort rename) side; each side capped to MAX_FILE_BYTES
 const MAX_ENRICHED_FILES = 60
 const MAX_FILE_BYTES = 200_000
-async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Promise<ProofFile> {
+async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Promise<ExportFile> {
   const run = (args: string[]) => gitA(['-C', wtPath, '-c', 'core.quotePath=false', ...args])
   const [patchRaw, oldRaw, newRaw] = await Promise.all([
     run(['diff', '-M', `${base}..HEAD`, '--', f.path]),
@@ -190,9 +190,9 @@ async function enrichFile(wtPath: string, base: string, f: ReviewDiffFile): Prom
 }
 
 // resolve a reading's evidence to inline bytes so the proof is a self-contained file: an image → a base64
-// data-URI; a transcript → its text; the cache miss / no-capture states pass through. yatsu owns the bytes
+// data-URI; a transcript → its text; the cache miss / no-capture states pass through. the eval cache owns the bytes
 // (the content-addressed cache) — the proof only asks for them by hash.
-async function toProofReading(r: EvalEntry): Promise<ProofReading> {
+async function toExportReading(r: EvalEntry): Promise<ExportReading> {
   const base = {
     scenario: r.scenario, expected: r.expected, verdict: r.verdict, fresh: r.fresh,
     staleAxes: r.staleAxes, score: readingScore(r), evaluator: r.evaluator, ts: r.ts,
@@ -223,7 +223,7 @@ function latestPerScenario(readings: EvalEntry[]): EvalEntry[] {
 
 // the DECLARED scenarios' latest reading — the SAME declared-bounded computation every other eval face reads
 // (score.jsx's scenarioStates for the node badge and the eval tab). A reading whose scenario is no longer in
-// yatsu.md is residual: the append-only sidecar still carries it, but it is not current loss, so it must not
+// eval.md is residual: the append-only sidecar still carries it, but it is not current loss, so it must not
 // become a proof reading card, a passed/total tick, or a node score. The proof was the one face driven by the
 // readings that happen to exist rather than the scenarios that are declared — this bounds it like the rest, so
 // a retired scenario's stale reading can't make the proof disagree with the dashboard (phantom card, off ribbon).
@@ -246,8 +246,8 @@ function readingScore(r: EvalEntry): ScoreState {
 
 // worst-first aggregate over the latest reading per scenario: any fresh fail → fail; else any stale → grey
 // (✗ if any stale last-failed, else ✓); else any unscored scenario → empty; else every scenario fresh-passes.
-export function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
-  if (!hasYatsu) return null
+export function nodeScore(hasEvalFile: boolean, latest: EvalEntry[]): ScoreState {
+  if (!hasEvalFile) return null
   if (!latest.length) return 'empty'
   if (latest.some((r) => r.fresh && verdictMark(r) === 'cross')) return 'fail'
   const stale = latest.filter((r) => !r.fresh && verdictMark(r))
@@ -258,9 +258,9 @@ export function nodeScore(hasYatsu: boolean, latest: EvalEntry[]): ScoreState {
 
 // ---- file → node mapping ----
 
-// which spec node owns a changed file: a file inside a node's directory (its spec.md / yatsu.md / sidecar)
+// which spec node owns a changed file: a file inside a node's directory (its spec.md / eval.md / sidecar)
 // belongs to the NEAREST such node; otherwise the node whose governed `code:` claims it (exact path,
-// directory prefix, or `*` glob — the same matching `spex yatsu scan --changed` uses). A shared file is
+// directory prefix, or `*` glob — the same matching `spex eval lint --changed` uses). A shared file is
 // governed by MANY nodes (ordinary composition); when the session has a primary node that also governs it,
 // attribute it THERE so a node/<id> session's stake in cli.ts/index.ts groups under its own node, not
 // whichever sibling sorts first.
@@ -324,7 +324,7 @@ function verdictBadge(v: EvalEntry['verdict']): string {
   return `<span class="verdict note" title="${esc(v.note ?? '')}">≈ note</span>`
 }
 
-function renderReading(r: ProofReading): string {
+function renderReading(r: ExportReading): string {
   const ev = r.evidence
   const body =
     ev.kind === 'image' ? `<img class="shot" src="${ev.dataUri}" alt="${esc(r.scenario)}">`
@@ -333,9 +333,9 @@ function renderReading(r: ProofReading): string {
     : ev.kind === 'data' ? `<pre class="transcript data">${esc(ev.text)}</pre>`
     : ev.kind === 'miss' ? `<div class="noev">⌀ miss original file — the evidence bytes were pruned</div>`
     : `<div class="noev">attested without a capture</div>`
-  const stale = r.fresh ? '' : `<span class="stale" title="${esc(r.staleAxes.join(', '))} changed since the reading">stale</span>`
+  const stale = r.fresh ? '' : `<span class="stale" title="${esc(r.staleAxes.join(', '))} changed since this eval">stale</span>`
   const note = r.verdict?.note ? `<div class="rnote"><b>note</b> ${esc(r.verdict.note)}</div>` : ''
-  return `<div class="reading">
+  return `<div class="eval-entry">
     <div class="rhead">
       ${scoreBadge(r.score, r.fresh ? undefined : `stale: ${r.staleAxes.join(', ')}`)}
       <span class="scenario">${esc(r.scenario)}</span>
@@ -359,7 +359,7 @@ function renderPatch(patch: string): string {
   }).join('')
 }
 
-function renderFile(f: ProofFile): string {
+function renderFile(f: ExportFile): string {
   const row = `<span class="fstatus ${esc(f.status)}">${esc(f.status)}</span> <span class="fpath">${esc(f.path)}</span> <span class="fnum"><span class="add">+${f.additions}</span> <span class="del">−${f.deletions}</span></span>`
   if (f.omitted) return `<div class="file flat"><div class="frow">${row}<span class="note">diff omitted — large changeset</span></div></div>`
   if (!f.patch && f.oldText == null && f.newText == null) return `<div class="file flat"><div class="frow">${row}</div></div>`
@@ -372,14 +372,14 @@ function renderFile(f: ProofFile): string {
     <div class="file-body">${f.patch ? `<div class="patch">${renderPatch(f.patch)}</div>` : '<div class="note">no textual diff</div>'}${cmp}</div></details>`
 }
 
-function renderNode(n: ProofNode): string {
+function renderNode(n: ExportNode): string {
   const stat = `<span class="diffstat"><span class="add">+${n.additions}</span> <span class="del">−${n.deletions}</span> · ${n.files.length} file(s)</span>`
   const fileList = n.files.length ? `<div class="files">${n.files.map(renderFile).join('')}</div>` : ''
   let proof: string
   if (n.readings.length) proof = n.readings.map(renderReading).join('')
-  else if (n.uncoveredFrontend) proof = `<div class="blindspot">⚠ a frontend node with no yatsu.md — no loss signal measured. Give it a scenario so this change can be proven.</div>`
-  else if (n.hasYatsu) proof = `<div class="blindspot">declares scenarios but has no reading yet — measure with <code>spex yatsu eval ${esc(n.id)}</code></div>`
-  else proof = `<div class="noev">no measurable surface (no yatsu.md)</div>`
+  else if (n.uncoveredFrontend) proof = `<div class="blindspot">⚠ a frontend node with no eval.md — its loss is unmeasured. Give it a scenario so this change can be verified.</div>`
+  else if (n.hasEvalFile) proof = `<div class="blindspot">declares scenarios but has no eval yet — measure with <code>spex eval add ${esc(n.id)}</code></div>`
+  else proof = `<div class="noev">no measurable surface (no eval.md)</div>`
   return `<article class="node" style="--hue:${n.hue}">
     <div class="nhead">
       <span class="huedot"></span>
@@ -390,15 +390,15 @@ function renderNode(n: ProofNode): string {
     </div>
     ${n.desc ? `<div class="ndesc">${esc(n.desc)}</div>` : ''}
     ${fileList}
-    <div class="readings">${proof}</div>
+    <div class="eval-list">${proof}</div>
   </article>`
 }
 
-export function renderProofHtml(m: ProofModel): string {
+export function renderExportHtml(m: ExportModel): string {
   const idShort = m.id.slice(0, 8)
   const ribbon = [
     ...m.gates.map((g) => `<span class="chip ${g.ok ? 'ok' : 'bad'}" title="${esc(g.detail)}">${g.ok ? '✓' : '✗'} ${esc(g.label)}</span>`),
-    m.score.total ? `<span class="chip ${m.score.passed === m.score.total ? 'ok' : 'warn'}" title="scenarios fresh-passing (of those measured); ${m.score.fresh}/${m.score.total} fresh">★ ${m.score.passed}/${m.score.total} passing</span>` : `<span class="chip warn" title="no yatsu readings on the changed nodes">★ no measured loss</span>`,
+    m.score.total ? `<span class="chip ${m.score.passed === m.score.total ? 'ok' : 'warn'}" title="scenarios fresh-passing (of those measured); ${m.score.fresh}/${m.score.total} fresh">★ ${m.score.passed}/${m.score.total} passing</span>` : `<span class="chip warn" title="no evals filed on the changed nodes">★ no measured loss</span>`,
   ].join('')
   const gates = m.gates.map((g) => `<li class="${g.ok ? 'ok' : 'bad'}"><span class="gmark">${g.ok ? '✓' : '✗'}</span><span class="glabel">${esc(g.label)}</span><span class="gdetail">${esc(g.detail)}</span></li>`).join('')
   const otherBlock = m.otherFiles.length
@@ -409,12 +409,12 @@ export function renderProofHtml(m: ProofModel): string {
 <html lang="en"><head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>proof · ${esc(m.title)}</title>
+<title>evals · ${esc(m.title)}</title>
 <style>${STYLE}</style>
 </head><body>
-<main class="proof">
+<main class="evals">
   <header class="masthead">
-    <div class="eyebrow">SpexCode · review proof</div>
+    <div class="eyebrow">SpexCode · session eval export</div>
     <h1 class="claim">${esc(m.title)}</h1>
     <div class="meta">session <code>${esc(idShort)}</code>${m.branch ? ` · <code>${esc(m.branch)}</code>` : ''}${m.node ? ` · node <code>${esc(m.node)}</code>` : ''} · ${m.ahead} commit(s) · ${m.nodes.length} node(s) · <span class="ts">${esc(m.generatedAt)}</span></div>
     <div class="ribbon">${ribbon}</div>
@@ -428,12 +428,12 @@ export function renderProofHtml(m: ProofModel): string {
     <h2>Merge gates</h2>
     <ul class="gates">${gates}</ul>
   </section>
-  <footer>Generated by <code>spex review proof ${esc(idShort)}</code> — the optimizer's measured loss, presented for the merge decision. A spec is the loss; commits are the optimizer; yatsu is the evaluation.</footer>
+  <footer>Generated by <code>spex eval ls --session ${esc(idShort)} --export</code> — the optimizer's measured loss, presented for the merge decision. A spec is the loss; commits are the optimizer; eval keeps the score.</footer>
 </main>
 </body></html>`
 }
 
-// the document's inline stylesheet — dark, matching the board's palette and the yatsu score colours, so the
+// the document's inline stylesheet — dark, matching the board's palette and the eval score colours, so the
 // proof reads as one surface with the dashboard. Self-contained (no external font/asset).
 const STYLE = `
 :root{--bg:#0b0e14;--panel:#11161f;--panel2:#0e131b;--ink:#c9d4e3;--dim:#7c899c;--line:#1e2733;--accent:#4cc2a0;--green:#3fb950;--red:#f85149;--grey:#6e7b8c;--amber:#d29922}
@@ -441,7 +441,7 @@ const STYLE = `
 body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;-webkit-font-smoothing:antialiased}
 code,pre,.mono{font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace}
 code{background:#0006;padding:.05em .35em;border-radius:4px;font-size:.88em;color:#aee1d2}
-.proof{max-width:920px;margin:0 auto;padding:40px 24px 80px}
+.evals{max-width:920px;margin:0 auto;padding:40px 24px 80px}
 .masthead{padding:30px 30px 26px;border:1px solid var(--line);border-radius:16px;background:radial-gradient(1200px 240px at 0% 0%,#16352c66,transparent),linear-gradient(160deg,#141b26,#0d121a);box-shadow:0 20px 60px -30px #000}
 .eyebrow{font:600 11px/1 ui-monospace,monospace;letter-spacing:.18em;text-transform:uppercase;color:var(--accent)}
 .claim{margin:14px 0 10px;font-size:30px;line-height:1.2;font-weight:700;color:#eef3fa;letter-spacing:-.01em}
@@ -485,8 +485,8 @@ h2{margin:42px 0 16px;font-size:14px;letter-spacing:.14em;text-transform:upperca
 .side-h{font:600 10px/1 ui-monospace,monospace;text-transform:uppercase;letter-spacing:.08em;color:var(--dim);padding:0 0 6px}
 .side pre{margin:0;padding:10px 12px;background:#05080d;border:1px solid var(--line);border-radius:8px;max-height:440px;overflow:auto;font:11px/1.5 ui-monospace,monospace;color:#aebccd;white-space:pre}
 .abs{color:var(--dim);font-style:italic}
-.readings{margin-top:8px}
-.reading{margin-top:14px;padding:14px 16px;border:1px solid var(--line);border-radius:10px;background:var(--panel2)}
+.eval-list{margin-top:8px}
+.eval-entry{margin-top:14px;padding:14px 16px;border:1px solid var(--line);border-radius:10px;background:var(--panel2)}
 .rhead{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
 .scenario{font-weight:600;color:#dde7f1}
 .rmeta{margin-left:auto;font:11px/1 ui-monospace,monospace;color:var(--dim)}
@@ -515,10 +515,10 @@ h2{margin:42px 0 16px;font-size:14px;letter-spacing:.14em;text-transform:upperca
 footer{margin-top:48px;padding-top:20px;border-top:1px solid var(--line);color:var(--dim);font-size:12px;text-align:center}
 `
 
-// ---- the session EVAL model ([[review-proof]]'s interactive face) ----
-// The lean, TIERED counterpart of buildProofModel: the same worktree-rooted marshaling, but rows only —
+// ---- the session EVAL model ([[session-eval]]'s interactive face) ----
+// The lean, TIERED counterpart of buildExportModel: the same worktree-rooted marshaling, but rows only —
 // no diff enrichment, no inlined evidence bytes (the dashboard's Eval tab rides the shared eval
-// components: blobs stream lazily from /api/yatsu/blob on open). Each reading carries `inSession`
+// components: blobs stream lazily from /api/evidence on open). Each reading carries `inSession`
 // (this session filed it, or its codeSha is one of the branch's own commits — a diagnostic session
 // that changed no code still owns the readings it filed at the merge-base) so the tab can lead with
 // what THIS session measured, ✦-marked, over the inherited baseline.
@@ -527,7 +527,7 @@ export type SessionEvalNode = {
   title: string
   hue: number
   desc: string
-  hasYatsu: boolean
+  hasEvalFile: boolean
   uncoveredFrontend: boolean
   scenarios: { name: string; expected: string; tags?: string[] }[]
   // each reading carries the trunk eval-concern thread for its (node, scenario) ([[remark-teeth]] / directive
@@ -543,7 +543,7 @@ export type SessionEvals = {
   title: string
   ahead: number
   dirtyNonRuntime: number
-  gates: ProofGate[]
+  gates: ExportGate[]
   nodes: SessionEvalNode[]
 }
 
@@ -572,8 +572,8 @@ export async function buildSessionEvals(id: string): Promise<SessionEvals | null
       title: spec?.title ?? nid,
       hue: spec?.hue ?? 210,
       desc: spec?.desc ?? '',
-      hasYatsu: tl.hasYatsu,
-      uncoveredFrontend: !tl.hasYatsu && (spec?.code ?? []).some(isUiPath),
+      hasEvalFile: tl.hasEvalFile,
+      uncoveredFrontend: !tl.hasEvalFile && (spec?.code ?? []).some(isUiPath),
       scenarios: tl.scenarios,
       // the per-scenario trunk thread rides each reading as `EvalEntry.thread` (evalTimeline's overlay), so
       // the event detail has the comment/remark track inline — no extra join here. A reading is the

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

@@ -27,6 +27,12 @@ export type Evidence = { hash: string; kind: EvidenceKind }
 export type Reading = {
   scenario: string
   codeSha: string
+  // content hash of the scenario's semantic text (description+expected, normalized — scenarios.ts
+  // scenarioHash) as DECLARED at filing time: the record of which contract this measurement was taken
+  // against. When present it alone decides the scenario freshness axis (a pure compare against the current
+  // declaration's hash); a legacy reading without it is decided by the git-derived rule instead — one
+  // track per reading, never both ([[eval-core]]).
+  scenarioHash?: string
   evidence?: Evidence[]
   // legacy scalar evidence — read for old readings, never written by new filings.
   blob?: string | null
@@ -103,7 +109,7 @@ export function applyRetractions(readings: Reading[], retractions: Retraction[])
 // the EFFECTIVE readings — what the scoreboard sees: every reading minus the retracted. Every score
 // consumer (freshness, scan, clean's referenced set, the eval tab, the proof) reads through here, so a
 // retract undoes a botched filing on ALL of them at once — the previous reading becomes the latest again,
-// or the scenario honestly returns to yatsu-missing.
+// or the scenario honestly returns to eval-missing.
 export function readReadings(sidecarPath: string): Reading[] {
   const { readings, retractions } = readSidecar(sidecarPath)
   return applyRetractions(readings, retractions)

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

@@ -22,7 +22,7 @@ const V2_EVENT_KEYS = new Set(['at', 'step', 'node'])
 const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node'])
 
 // validate LOUD — every violation named, [] when well-formed. Both schema versions are accepted: v1 (legacy
-// time axis, `tMs`) and v2 (axis-tagged, `at`). The key set is closed per version (like the yatsu.md
+// time axis, `tMs`) and v2 (axis-tagged, `at`). The key set is closed per version (like the eval.md
 // scenario schema): a malformed timeline is rejected at filing time, never silently reshaped. The `axis`
 // string itself is open — only its ABSENCE is an error, never an unrecognized value.
 export function validateTimeline(raw: unknown): string[] {

package/spec-forge/src/__fixtures__/github-forge.json

@@ -1,10 +1,10 @@
 {
-  "_note": "Fixture mirroring githubDriver output (the vendor-neutral ForgeIssue[]/ForgePR[] a `gh issue/pr list` collapses to) for a sample repo. Drives the needs-yatsu-eval resolver test with no network.",
+  "_note": "Fixture mirroring githubDriver output (the vendor-neutral ForgeIssue[]/ForgePR[] a `gh issue/pr list` collapses to) for a sample repo. Drives the needs-eval resolver test with no network.",
   "issues": [
     {
       "number": 1,
       "title": "login redirect is broken on /logout",
-      "body": "Steps to repro: click logout, land on a 404.\n\nSpec: sessions\nneeds-yatsu-eval\n",
+      "body": "Steps to repro: click logout, land on a 404.\n\nSpec: sessions\nneeds-eval\n",
       "url": "https://github.com/acme/repo/issues/1",
       "state": "open",
       "labels": []
@@ -15,7 +15,7 @@
       "body": "The open-issue badge over-counts.\n\nSpec: dashboard-issues",
       "url": "https://github.com/acme/repo/issues/2",
       "state": "open",
-      "labels": ["bug", "needs-yatsu-eval"]
+      "labels": ["bug", "needs-eval"]
     },
     {
       "number": 3,
@@ -27,8 +27,8 @@
     },
     {
       "number": 4,
-      "title": "old freshness drift already verified",
-      "body": "Spec: freshness\nNeeds-Yatsu-Eval\n",
+      "title": "old forge-cache drift already verified",
+      "body": "Spec: forge-cache\nNeeds-Eval\n",
       "url": "https://github.com/acme/repo/issues/4",
       "state": "closed",
       "labels": []
@@ -36,18 +36,18 @@
     {
       "number": 5,
       "title": "flagged but names no node",
-      "body": "This one is flagged but carries no Spec: marker and no closing PR.\n\nneeds-yatsu-eval\n",
+      "body": "This one is flagged but carries no Spec: marker and no closing PR.\n\nneeds-eval\n",
       "url": "https://github.com/acme/repo/issues/5",
       "state": "open",
-      "labels": ["needs-yatsu-eval"]
+      "labels": ["needs-eval"]
     },
     {
       "number": 6,
       "title": "fixed via an open PR, no marker on the issue",
-      "body": "A worked bug; the node comes transitively from the closing PR.\n\nneeds-yatsu-eval: ignore-the-trailing-text",
+      "body": "A worked bug; the node comes transitively from the closing PR.\n\nneeds-eval: ignore-the-trailing-text",
       "url": "https://github.com/acme/repo/issues/6",
       "state": "open",
-      "labels": ["needs-yatsu-eval"]
+      "labels": ["needs-eval"]
     }
   ],
   "prs": [

package/spec-forge/src/cli.ts

@@ -2,7 +2,7 @@ import { loadSpecs } from '../../spec-cli/src/specs.js'
 import type { ForgeDriver, ForgeIssue, ForgePR } from './port.js'
 import { FORGE_DRIVERS, forgeDriverFor, resolveForgeHost } from './drivers.js'
 import { resolveLinks, type NodeLinks } from './links.js'
-import { resolveEvalPending, type NodeEvalPending } from './needs-yatsu-eval.js'
+import { resolveEvalPending, type NodeEvalPending } from './needs-eval.js'
 
 // tiny flag reader over this command's own arg slice (everything after `forge`), so cli.ts stays routing-only.
 function flag(args: string[], name: string): string | undefined {
@@ -14,10 +14,12 @@ const has = (args: string[], name: string) => args.includes(`--${name}`)
 async function readForge(
   args: string[],
 ): Promise<{ driver: ForgeDriver; nodeIds: string[]; issues: ForgeIssue[]; prs: ForgePR[] } | null> {
-  const host = flag(args, 'host') ?? resolveForgeHost()
+  // the forge is a VALUE, never a command ([[cli-surface]]): `--store <host>` names it, mirroring the
+  // store axis every other issue verb uses.
+  const host = flag(args, 'store') ?? resolveForgeHost()
   const driver = forgeDriverFor(host)
   if (!driver) {
-    console.error(`forge: unknown host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
+    console.error(`spex issue links: unknown --store '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
     return null
   }
   const nodeIds = (await loadSpecs()).map((s) => s.id)
@@ -49,7 +51,7 @@ async function links(args: string[]): Promise<number> {
 
   const only = flag(args, 'node')
   if (only) {
-    if (!nodeIds.includes(only)) { console.error(`forge: no such node '${only}'`); return 1 }
+    if (!nodeIds.includes(only)) { console.error(`spex issue links: no such node '${only}'`); return 1 }
     resolved = resolved.filter((n) => n.node === only)
   }
 
@@ -58,7 +60,7 @@ async function links(args: string[]): Promise<number> {
   const nPRs = resolved.reduce((a, n) => a + n.prs.length, 0)
   console.log(
     `spec-forge · ${driver.host} · ${resolved.length} linked node(s) · ${nIssues} issue(s), ${nPRs} pr(s)` +
-      ` · scanned ${issues.length} issue(s), ${prs.length} pr(s)`,
+      ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`,
   )
   if (resolved.length) console.log(render(resolved))
   return 0
@@ -81,7 +83,7 @@ async function evalPending(args: string[]): Promise<number> {
 
   const only = flag(args, 'node')
   if (only) {
-    if (!nodeIds.includes(only)) { console.error(`forge: no such node '${only}'`); return 1 }
+    if (!nodeIds.includes(only)) { console.error(`spex issue links: no such node '${only}'`); return 1 }
     resolved = resolved.filter((n) => n.node === only)
   }
 
@@ -89,16 +91,15 @@ async function evalPending(args: string[]): Promise<number> {
   const nPending = resolved.reduce((a, n) => a + n.pending.length, 0)
   console.log(
     `spec-forge · ${driver.host} · ${resolved.length} node(s) with eval pending · ${nPending} issue(s)` +
-      ` · scanned ${issues.length} issue(s), ${prs.length} pr(s)`,
+      ` · traced ${issues.length} issue(s), ${prs.length} pr(s)`,
   )
   if (resolved.length) console.log(renderPending(resolved))
   return 0
 }
 
-export async function runForge(args: string[]): Promise<number> {
-  const sub = args[0]
-  if (sub === 'links') return links(args.slice(1))
-  if (sub === 'eval-pending') return evalPending(args.slice(1))
-  console.error('spex forge: links [--host github] [--node <id>] [--json] | eval-pending [--host github] [--node <id>] [--json]')
-  return 2
+// `spex issue links [--pending]` ([[cli-surface]]): the read-only forge→spec trace, folded into the issue
+// drawer (the forge drawer is dissolved — a forge is a value, `--store`). Bare = every linked node's open
+// issues/PRs; --pending narrows to the threads still awaiting an eval reading (the old eval-pending view).
+export async function runIssueLinks(args: string[]): Promise<number> {
+  return has(args, 'pending') ? evalPending(args) : links(args)
 }

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

@@ -1,13 +1,13 @@
 import type { ForgeIssue, ForgePR } from './port.js'
 import { resolveLinks, type LinkedIssue } from './links.js'
 
-export const NEEDS_YATSU_EVAL = 'needs-yatsu-eval'
+export const NEEDS_EVAL = 'needs-eval'
 
-// a bare-marker body line: the name alone, case-insensitive, any indent, optional trailing colon — content after it (`needs-yatsu-eval: foo`) is NOT a match
-const BODY_MARKER = new RegExp(`^\\s*${NEEDS_YATSU_EVAL}\\s*:?\\s*$`, 'im')
+// a bare-marker body line: the name alone, case-insensitive, any indent, optional trailing colon — content after it (`needs-eval: foo`) is NOT a match
+const BODY_MARKER = new RegExp(`^\\s*${NEEDS_EVAL}\\s*:?\\s*$`, 'im')
 
-export function isNeedsYatsuEval(issue: ForgeIssue): boolean {
-  if (issue.labels.some((l) => l.trim().toLowerCase() === NEEDS_YATSU_EVAL)) return true
+export function isNeedsEval(issue: ForgeIssue): boolean {
+  if (issue.labels.some((l) => l.trim().toLowerCase() === NEEDS_EVAL)) return true
   return BODY_MARKER.test(issue.body || '')
 }
 
@@ -19,7 +19,7 @@ export function resolveEvalPending(
   prs: ForgePR[],
   nodeIds: string[],
 ): NodeEvalPending[] {
-  const flagged = new Set(issues.filter(isNeedsYatsuEval).map((i) => i.number))
+  const flagged = new Set(issues.filter(isNeedsEval).map((i) => i.number))
   if (!flagged.size) return []
   const out: NodeEvalPending[] = []
   for (const { node, issues: linked } of resolveLinks(issues, prs, nodeIds)) {