spexcode 0.4.0 → 0.4.3

package/spec-dashboard/src/reviewQuery.js

@@ -0,0 +1,174 @@
+// The ONE token-query engine ([[review-query]]) — pure JS, no React/DOM. Both review ListViews, the
+// route layer's legacy replay, and any consumer minting canonical eval/issue addresses import from HERE:
+// the visible query TEXT is the single source of truth, and every tab/menu/autocomplete is only a
+// BUILDER that rewrites tokens in it (GitHub-measured semantics).
+
+export const ISSUE_QUERY_DEFAULT = 'is:issue state:open'
+export const EVAL_QUERY_DEFAULT = 'is:eval'
+// the session doors' scoped-list address: the default view, scoped — the text shows exactly that.
+export const scopedEvalQuery = (sessionId) => setToken(EVAL_QUERY_DEFAULT, 'scope', sessionId)
+// the aggregate score/count doors' address ([[eval-score-badge]]): the default view, node-filtered.
+export const nodeEvalQuery = (nodeId) => setToken(EVAL_QUERY_DEFAULT, 'node', nodeId)
+
+const KEY_RE = /^([A-Za-z][A-Za-z0-9-]*):(.*)$/s
+const unquote = (v) => (v.length >= 2 && v.startsWith('"') && v.endsWith('"') ? v.slice(1, -1) : v)
+export const quoteValue = (v) => (/\s/.test(String(v)) ? `"${v}"` : String(v))
+
+// segment scan preserving EVERY character — whitespace runs and tokens (a `"` swallows spaces until it
+// closes), each with [start,end) offsets — so the aria-hidden highlight overlay mirrors the input
+// glyph-for-glyph and the autocomplete can find the token under the caret.
+export function scanQuery(text) {
+  const s = String(text ?? '')
+  const out = []
+  let i = 0
+  while (i < s.length) {
+    let j = i
+    if (/\s/.test(s[i])) {
+      while (j < s.length && /\s/.test(s[j])) j++
+      out.push({ ws: true, raw: s.slice(i, j), start: i, end: j })
+    } else {
+      while (j < s.length && !/\s/.test(s[j])) {
+        if (s[j] === '"') {
+          j++
+          while (j < s.length && s[j] !== '"') j++
+          if (j < s.length) j++
+        } else j++
+      }
+      const raw = s.slice(i, j)
+      const m = KEY_RE.exec(raw)
+      out.push(m
+        ? { ws: false, raw, start: i, end: j, key: m[1].toLowerCase(), value: unquote(m[2]) }
+        : { ws: false, raw, start: i, end: j, key: null, value: unquote(raw) })
+    }
+    i = j
+  }
+  return out
+}
+
+export const tokenize = (text) => scanQuery(text).filter((seg) => !seg.ws)
+export const serialize = (tokens) => tokens.map((t) => t.raw).join(' ')
+export const normalizeQuery = (text) => serialize(tokenize(text))
+export const sameQuery = (a, b) => normalizeQuery(a) === normalizeQuery(b)
+
+// duplicate qualifiers: the LAST occurrence wins; bare words all apply.
+export const effectiveTokens = (tokens) => {
+  const last = new Map()
+  for (const t of tokens) if (t.key != null) last.set(t.key, t)
+  return tokens.filter((t) => t.key == null || last.get(t.key) === t)
+}
+
+export const readToken = (text, key) => {
+  const tokens = tokenize(text)
+  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].key === key) return tokens[i].value
+  return ''
+}
+
+// token SURGERY: rewrite the key at its first position, drop later duplicates, append when absent,
+// remove the key entirely on an empty value. Every other token — known or not — survives verbatim.
+export function setToken(text, key, value) {
+  const next = value == null || String(value) === ''
+    ? null
+    : { ws: false, raw: `${key}:${quoteValue(value)}`, key, value: String(value) }
+  const out = []
+  let placed = false
+  for (const t of tokenize(text)) {
+    if (t.key === key) {
+      if (next && !placed) { out.push(next); placed = true }
+      continue
+    }
+    out.push(t)
+  }
+  if (next && !placed) out.push(next)
+  return serialize(out)
+}
+
+// MATCHING is deliberately NOT here: this module owns text — scan/serialize/surgery/suggestions and the
+// canonical-address discipline — while the conjunctive field matching (including the unknown-qualifier
+// IMPOSSIBLE state) lives in the ONE [[review-filters]] engine, reached through its tokenFilterState
+// bridge. A second predicate here would be the exact fork the fusion removed.
+
+// canonical address discipline: the default view is the BARE page address; any other state is exactly
+// ?q=<raw text>. An emptied submit falls back to the default (→ bare).
+export const queryParam = (text, defaultText) => {
+  const trimmed = String(text ?? '').trim()
+  if (!trimmed || sameQuery(trimmed, defaultText)) return null
+  return { q: trimmed }
+}
+
+// A query/filter action resets by omitting page; a PAGINATION action passes a page (including 1) and
+// therefore records GitHub's explicit page=1 history form. The distinction is the action, not equivalence.
+export const reviewRouteQuery = (text, defaultText, page = null) => {
+  const query = queryParam(text, defaultText) || {}
+  if (page != null) query.page = String(page)
+  return Object.keys(query).length ? query : null
+}
+
+// LEGACY structured params → token pairs. `kind=all` maps to nothing: the evidence default IS all.
+const LEGACY_PARAMS = {
+  state: (v) => ['state', v],
+  concluded: (v) => (v === '1' ? ['state', 'closed'] : null),
+  ok: (v) => (v === '1' ? ['state', 'reviewed'] : null),
+  verdict: (v) => ['verdict', v],
+  freshness: (v) => ['freshness', v],
+  kind: (v) => (v === 'all' ? null : ['evidence', v]),
+  store: (v) => ['store', v],
+  author: (v) => ['author', v],
+  node: (v) => ['node', v],
+  filer: (v) => ['filer', v],
+  live: (v) => (v === '1' ? ['session', 'present'] : null),
+  session: (v) => ['scope', v],
+}
+
+export const hasLegacyParams = (query) =>
+  Object.keys(LEGACY_PARAMS).some((k) => query?.[k] != null && query[k] !== '')
+
+// the legacy free q was ONE substring search — it must replay as ONE text token. Quote it whenever the
+// tokenizer would read it as anything else: spaces (several words), a colon (q=drift:check would become
+// an unknown qualifier and match zero), or a stray quote (which would swallow neighbours).
+const freeTextToken = (v) => (/[\s:"]/.test(v) ? `"${v.replace(/"/g, '')}"` : v)
+
+// a legacy LIST address replays as the FULL visible state: the page's default tokens with each legacy
+// param surgically applied (live=1→session:present, session=<id>→scope:<id>, ok=1→state:reviewed,
+// kind→evidence:), the free-text q appended as ONE bare/phrase token preserving the old
+// single-substring search. Returns null when nothing legacy is present.
+export function legacyQueryText(defaultText, query) {
+  if (!hasLegacyParams(query)) return null
+  let text = defaultText
+  for (const [param, toPair] of Object.entries(LEGACY_PARAMS)) {
+    const v = query[param]
+    if (v == null || v === '') continue
+    const pair = toPair(String(v))
+    if (pair) text = setToken(text, pair[0], pair[1])
+  }
+  const free = String(query.q ?? '').trim()
+  if (free) text = `${text} ${freeTextToken(free)}`.trim()
+  return text
+}
+
+// inline autocomplete at the caret — client-side and BOUNDED. A bare prefix completes qualifier KEYS
+// (insert `key:`, keep typing); a `key:prefix` completes VALUES from the page-supplied candidate list
+// only (data-derived; scope = sessions on the current board), capped at 8. Everything else stays
+// hand-typable and submits verbatim.
+export function suggestAt(text, caret, keys = [], values = {}) {
+  const s = String(text ?? '')
+  const at = Math.max(0, Math.min(caret ?? s.length, s.length))
+  const seg = scanQuery(s).find((g) => !g.ws && g.start < at && at <= g.end)
+  if (!seg) return { start: at, end: at, items: [] }
+  const typed = s.slice(seg.start, at)
+  const m = KEY_RE.exec(typed)
+  if (!m) {
+    const w = typed.toLowerCase()
+    if (!w || w.includes('"')) return { start: seg.start, end: seg.end, items: [] }
+    const items = keys.filter((k) => k.startsWith(w)).slice(0, 8)
+      .map((k) => ({ type: 'key', key: k, insert: `${k}:` }))
+    return { start: seg.start, end: seg.end, items }
+  }
+  const key = m[1].toLowerCase()
+  const prefix = m[2].replace(/^"/, '').replace(/"$/, '').toLowerCase()
+  const pool = values[key] || []
+  const items = pool
+    .filter((c) => String(c.value).toLowerCase().startsWith(prefix) && String(c.value).toLowerCase() !== prefix)
+    .slice(0, 8)
+    .map((c) => ({ type: 'value', key, value: String(c.value), label: c.label || null, insert: `${key}:${quoteValue(c.value)} ` }))
+  return { start: seg.start, end: seg.end, items }
+}

package/spec-dashboard/src/session.js

@@ -0,0 +1,167 @@
+// status→colour values are theme tokens (styles.css :root) so the palette stays single-sourced; var() resolves in inline styles.
+export const STATUS_COLOR = {
+  working: 'var(--green)', parked: 'var(--green)',
+  asking: 'var(--yellow)', review: 'var(--yellow)', done: 'var(--yellow)',
+  error: 'var(--red)',
+  idle: 'var(--muted)', starting: 'var(--muted)', queued: 'var(--muted)',
+  'close-pending': 'var(--muted)', offline: 'var(--muted)',
+  unknown: 'var(--yellow)',   // liveness probe FAILED (box overloaded) — death unproven, so warn, never read as dead
+}
+
+// compact one-line surfaces (the console's terminal-styled sidebar) render the status as a SINGLE glyph
+// instead of the word — STATUS_COLOR still paints it, and the exact word stays in the title/aria for hover +
+// a11y. One terminal-ish mark per lifecycle; same four-hue traffic-light meaning as the word it replaces.
+export const STATUS_GLYPH = {
+  working: '●', parked: '‖',
+  asking: '?', review: '◑', done: '✓',
+  error: '✕',
+  idle: '·', starting: '◌', queued: '⋯', 'close-pending': '⊘', offline: '○', unknown: '⁇',
+}
+
+// the three triage zones the session list groups into — "whose turn is it?". `offline` = the process is
+// DEAD/dormant (can't act until relaunched) — checked FIRST, because a session whose process died while
+// asking/review/error keeps that pre-death lifecycle, yet it belongs at the bottom, not under Needs You.
+// `need` = the ball is with the HUMAN (asking / review / done / close-pending / error → answer, review,
+// close, fix); `run` = self-driving, the agent's turn (working / parked / starting / queued / idle — booting
+// counts as running, not dead). Closed sessions aren't on the board at all. Same partition drives every
+// session-list surface.
+const NEED_STATUS = new Set(['asking', 'review', 'done', 'close-pending', 'error'])
+export const sessionZone = (s) => {
+  if (s?.liveness === 'offline' || s?.status === 'offline') return 'offline'
+  return NEED_STATUS.has(s?.status) ? 'need' : 'run'
+}
+export const ZONE_ORDER = ['need', 'run', 'offline']
+// the ONE liveness join: resolve an id against the board sessions and return the
+// session only while it is ALIVE (listed and not offline) — the same alive/offline judgment the originator
+// chip renders (Thread.jsx). A non-session id ('human', a github
+// login) resolves to null, honestly.
+export const liveSession = (sessions, id) => {
+  const s = id ? (sessions || []).find((x) => x.id === id) : null
+  return s && sessionZone(s) !== 'offline' ? s : null
+}
+// the ONE source-session PRESENCE join ([[live-session-filter]] — the session:present|missing facet):
+// does the id still resolve to a session on the current board at ALL, any zone? Presence, not liveness —
+// the facet asks "is the source still around", never "is it online".
+export const sessionPresent = (sessions, id) => {
+  const s = id ? (sessions || []).find((x) => x.id === id) : null
+  return s || null
+}
+// zone-partition the list: needs-you first, self-running next, offline (dormant) at the bottom; and WITHIN
+// each zone the NEWEST session on top (descending effective time) — the fresh, recently-touched work you
+// actually reach for, not the oldest.
+const effOf = (s) => (s?.sortKey != null ? s.sortKey : (s?.created ?? 0))
+export const zoneSort = (sessions) => {
+  const rank = { need: 0, run: 1, offline: 2 }
+  return [...sessions].sort((a, b) => rank[sessionZone(a)] - rank[sessionZone(b)] || effOf(b) - effOf(a))
+}
+
+// the session's display strings are DERIVED SERVER-SIDE ([[session-label]]): the wire carries `label`
+// (stable handle) and `headline` (the live line a human reads), computed once in toSession; the bare parts
+// (rename `name`, prompt-truncation `title`) don't ride the wire at the top level, so a surface CANNOT
+// re-derive its own chain — these two accessors are the only doors, and the legacy chain below each exists
+// solely as the old-backend fallback, confined to THIS file. Reach for s.raw.name / s.raw.title only for an
+// explicitly raw consumer (the rename prefill).
+//
+// `sessionHandle` is the STABLE handle — its ONLY sanctioned uses are the avatar/hover TOOLTIP, mobile's
+// handle-line, and search MATCHING. On a current backend the wire always carries `label`, so this door
+// short-circuits there: what search matches IS the label (a rename name or the prompt truncation);
+// raw id/node/branch fragments are deliberately NOT promised searchable.
+// It is NEVER a visible one-line title: EVERY surface where a human reads "which session is this" (board
+// rows, the map window, Enter tabs, the console strip, the search palette, the @-mention dropdown, and the
+// node-menu overlay list) renders `sessionHeadline`. Naming the stable door `Handle`, not `Name`, is the
+// architectural guard: a dev wanting "the name to show" reaches for the headline by reflex and can no longer
+// grab the handle by mistake — the divergence that kept recurring ([[session-activity]]: one name everywhere).
+export const sessionHandle = (s) =>
+  s?.label || s?.name || s?.node || s?.title || s?.branch || s?.id
+
+export const sessionHeadline = (s) =>
+  s?.headline || s?.name || s?.activity || s?.promptPreview || s?.node || s?.title || s?.branch || s?.id
+
+// @@@ session nesting ([[session-nesting]]) — a session launched by `spex new` from INSIDE another carries
+// that spawner's id as `parent`. Fold it into a forest, DERIVED here at read time (never stored on the child):
+// a child nests under its parent ONLY IF that parent is present in this list, so a closed parent's children
+// auto-promote to top-level on the next board read. Returns the top-level `roots` (a real parent or an orphan
+// whose parent is gone) and `childrenOf` (parentId → its direct children), both recursive to any depth.
+export function nestSessions(sessions) {
+  const present = new Set(sessions.map((s) => s?.id))
+  const childrenOf = new Map()
+  const roots = []
+  for (const s of sessions) {
+    const p = s?.parent && s.parent !== s.id && present.has(s.parent) ? s.parent : null
+    if (p) { const arr = childrenOf.get(p) || []; arr.push(s); childrenOf.set(p, arr) }
+    else roots.push(s)
+  }
+  return { roots, childrenOf }
+}
+
+// Present ancestors of one session, nearest first. This mirrors nestSessions' rule that a missing parent
+// makes its child a root, and bounds malformed cycles so an external jump can safely reveal the row.
+export function sessionAncestorIds(sessions, id) {
+  const byId = new Map(sessions.map((s) => [s?.id, s]))
+  const ids = []
+  const seen = new Set([id])
+  let cur = byId.get(id)
+  while (cur?.parent && !seen.has(cur.parent)) {
+    const parent = byId.get(cur.parent)
+    if (!parent) break
+    ids.push(parent.id)
+    seen.add(parent.id)
+    cur = parent
+  }
+  return ids
+}
+
+// @@@ subtree rollup ([[session-nesting]]) — the disclosure-triangle COLOUR: a PURELY informational summary of
+// the hidden subtree that must NOT touch the parent's own status/glyph/zone/sort. Dark-yellow if ANY descendant
+// needs attention (the needs-you zone, error folded in — the widest signal wins); else green if any descendant
+// is actively running (a STATUS_COLOR-green status: working/parked); else neutral (all idle/offline). Reuses
+// the STATUS_COLOR hues so the triangle speaks the same four-hue language as every other status mark.
+export function subtreeRollup(id, childrenOf) {
+  let need = false, run = false, count = 0
+  const walk = (pid, seen) => {
+    for (const c of childrenOf.get(pid) || []) {
+      if (seen.has(c.id)) continue
+      seen.add(c.id)
+      count++
+      if (NEED_STATUS.has(c.status)) need = true
+      else if (STATUS_COLOR[c.status] === STATUS_COLOR.working) run = true
+      walk(c.id, seen)
+    }
+  }
+  walk(id, new Set([id]))
+  return { color: need ? STATUS_COLOR.asking : run ? STATUS_COLOR.working : STATUS_COLOR.idle, count }
+}
+
+// @@@ the ordered render list ([[session-nesting]]) both session-list surfaces share. Roots are zone-sorted by
+// their OWN status (no aggregation), each carrying a zone header when the zone changes; a parent's children
+// follow it (zone-sorted among themselves) ONLY when `isExpanded(id)` — collapsed by default, so a fleet reads
+// as one row. Emits {type:'zone',zone} and {type:'row', s, depth, expandable, expanded, rollup, guides}; the
+// visible row order is also what ↑/↓ nav and drag-reorder walk, so a collapsed child is never a hidden nav
+// target. `guides` is the file-tree rail vector, one bool per connector column (length === depth): the LAST
+// entry marks whether THIS row has a following sibling (branch tee vs end elbow), each earlier entry whether
+// the ancestor in that column continues (draw a pass-through vertical line vs blank).
+export function sessionForest(sessions, isExpanded) {
+  const { roots, childrenOf } = nestSessions(sessions)
+  const items = []
+  const emit = (s, depth, seen, guides) => {
+    const kids = childrenOf.get(s.id) || []
+    const expandable = kids.length > 0
+    const expanded = expandable && !!isExpanded(s.id)
+    const roll = expandable ? subtreeRollup(s.id, childrenOf) : null
+    items.push({ type: 'row', s, depth, expandable, expanded, rollup: roll?.color ?? null, kin: roll?.count ?? 0, guides })
+    if (expanded) {
+      const vis = zoneSort(kids).filter((c) => !seen.has(c.id))
+      vis.forEach((c, i) => { seen.add(c.id); emit(c, depth + 1, seen, [...guides, i < vis.length - 1]) })
+    }
+  }
+  const seen = new Set()
+  let prevZone = null
+  for (const r of zoneSort(roots)) {
+    if (seen.has(r.id)) continue
+    seen.add(r.id)
+    const z = sessionZone(r)
+    if (z !== prevZone) { items.push({ type: 'zone', zone: z }); prevZone = z }
+    emit(r, 0, seen, [])
+  }
+  return items
+}

package/spec-eval/src/cli.ts

@@ -2,9 +2,10 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join, relative, dirname } from 'node:path'
 import { repoRoot, headSha, driftIndex, stagedFiles, git } from '../../spec-cli/src/git.js'
 import { loadSpecs } from '../../spec-cli/src/specs.js'
-import { loadConfig, sourceExtRe } from '../../spec-cli/src/lint.js'
+import { loadConfig } from '../../spec-cli/src/lint.js'
+import { trackedSourceFiles } from '../../spec-cli/src/source-files.js'
 import { mainBranch, envSessionId, readRawRecord } from '../../spec-cli/src/layout.js'
-import { evalNodes, validateScenarios, resolveEvalNode, scenarioHash, EVAL_FILE, type EvalNode } from './scenarios.js'
+import { evalNodes, validateScenarios, resolveEvalNode, scenarioHash, EVAL_FILE, type EvalNode, type ScenarioTestReference } 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'
@@ -53,9 +54,9 @@ 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 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.
+// consumed by the session-eval's `uncoveredFrontend` blindspot, NOT by eval lint's coverage check. Scan uses
+// the shared tracked-source classifier instead, 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,10 +72,15 @@ function changedSinceBase(root: string): Set<string> {
   return out
 }
 
-// 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
+// A node owns the files under its spec dir except those under a descendant node. Its other selection axis
+// is the supplied code list — node code for per-node findings, effective scenario code for drift.
+export function nodeChanged(dirRel: string, codeFiles: readonly string[], changed: Set<string>, nodeDirs: Iterable<string> = []): boolean {
+  const descendants = [...nodeDirs].filter((d) => d !== dirRel && d.startsWith(dirRel + '/'))
+  for (const c of changed) {
+    const inNodeDir = c === dirRel || c.startsWith(dirRel + '/')
+    const inDescendant = descendants.some((d) => c === d || c.startsWith(d + '/'))
+    if (inNodeDir && !inDescendant) return true
+  }
   return codeFiles.some((cf) => {
     if (changed.has(cf)) return true
     const dir = cf.replace(/\/+$/, '') + '/'
@@ -87,9 +93,9 @@ export function nodeChanged(dirRel: string, codeFiles: string[], changed: Set<st
 async function scan(args: string[] = []): Promise<number> {
   const root = repoRoot()
   const cfg = loadConfig(root)
-  // 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)
+  // eval-coverage fires on ANY governed source file per the same classifier as spec coverage, not just
+  // frontend — so backend/CLI/non-web source is held to the loss discipline too, not exempted.
+  const sourceFiles = new Set(trackedSourceFiles(root, cfg.governedRoots, cfg))
   const changedOnly = has(args, 'changed')
   const changed = changedOnly ? changedSinceBase(root) : null
   const idx = await driftIndex(root)
@@ -106,42 +112,51 @@ async function scan(args: string[] = []): Promise<number> {
   // 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(evalNodes(root).map((n) => [relative(root, n.dir), n]))
+  const nodeDirs = specs.map((s) => dirname(s.path))
   let flaggedNodes = 0, malformed = 0, staleScores = 0, missingScores = 0, uncovered = 0, danglingTracks = 0
   for (const s of specs) {
     const dirRel = dirname(s.path)
-    if (changed && !nodeChanged(dirRel, s.code, changed)) continue
+    const nodeSelected = !changed || nodeChanged(dirRel, s.code, changed, nodeDirs)
     const y = yByDir.get(dirRel)
     const findings: string[] = []
     if (y) {
       // 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, EVAL_FILE), 'utf8'), cfg.scenarioTags)) {
-        malformed++
-        findings.push(`  • eval-schema: '${s.id}' ${e} — fix ${y.evalPath}`)
+      if (nodeSelected) {
+        for (const e of validateScenarios(readFileSync(join(y.dir, EVAL_FILE), 'utf8'), cfg.scenarioTags, root)) {
+          malformed++
+          findings.push(`  • eval-schema: '${s.id}' ${e} — fix ${y.evalPath}`)
+        }
       }
       const latest = latestPerScenario(readReadings(y.sidecarPath))
       for (const sc of y.scenarios) {
         // a scenario's own `code` narrows its freshness CODE axis to a subset; a path that does not exist
         // would make that axis silently immortal (changedSince finds no commits for it), so flag it LOUD as a
         // malformed declaration — the same loud-fail spirit as a bad node `code:`.
-        for (const [field, paths] of [['code', sc.code], ['related', sc.related]] as const) {
-          const ghosts = (paths ?? []).filter((p) => !existsSync(join(root, p)))
-          if (ghosts.length) {
-            malformed++
-            findings.push(`  • eval-schema: '${s.id}' scenario '${sc.name}' \`${field}\` path(s) not found: ${ghosts.join(', ')} — fix ${y.evalPath}`)
+        if (nodeSelected) {
+          for (const [field, paths] of [['code', sc.code], ['related', sc.related]] as const) {
+            const ghosts = (paths ?? []).filter((p) => !existsSync(join(root, p)))
+            if (ghosts.length) {
+              malformed++
+              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
+        const driftSelected = !changed || nodeChanged(dirRel, codeFiles, changed, nodeDirs)
         // 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 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(`  • eval-missing: '${s.id}' scenario '${sc.name}'${tagStr} has no eval yet — measure with \`spex eval add ${s.id}\``)
+          if (nodeSelected) {
+            missingScores++
+            findings.push(`  • eval-missing: '${s.id}' scenario '${sc.name}'${tagStr} has no eval yet — measure with \`spex eval add ${s.id}\``)
+          }
           continue
         }
+        if (!driftSelected) 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.evalPath, idx, scidx, remSignals, probe, sc)
         if (axes.length) {
@@ -163,12 +178,12 @@ async function scan(args: string[] = []): Promise<number> {
       // (`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) {
+      if (nodeSelected && 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(`  • 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))) {
+    } else if (nodeSelected && s.code.some((p) => sourceFiles.has(p))) {
       uncovered++
       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`)
     }
@@ -444,7 +459,7 @@ async function okCmd(args: string[]): Promise<number> {
     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`).')
+    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 an eval is a remark (`spex remark add`).')
     return 1
   }
   const sel = positional(args)
@@ -463,10 +478,10 @@ async function okCmd(args: string[]): Promise<number> {
   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`)
+    console.log(`spex eval ok: '${res.node.id}' scenario '${scenario}' eval @ ${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(`  ☑ '${res.node.id}' scenario '${scenario}' eval @ ${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)')
@@ -512,7 +527,7 @@ function checkStaged(): number {
   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)
+    const errs = validateScenarios(readFileSync(abs, 'utf8'), tagLibrary, root)
     if (!errs.length) continue
     bad = true
     console.error(`✗ SpexCode eval: ${rel} — invalid scenario schema:`)
@@ -578,6 +593,34 @@ export function formatTimeline(tl: EvalTimeline): string {
 // (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.
+export type ScenarioListRow = {
+  node: string
+  scenario: string
+  tags?: string[]
+  test?: ScenarioTestReference
+  measured: boolean
+  latest?: { verdict?: Verdict; ts: string }
+}
+
+export function scenarioListRows(nodes: EvalNode[], unmeasuredOnly = false): ScenarioListRow[] {
+  const rows: ScenarioListRow[] = []
+  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 } : {}),
+        ...(sc.test ? { test: sc.test } : {}),
+        measured: !!r,
+        ...(r ? { latest: { ...(r.verdict ? { verdict: r.verdict } : {}), ts: r.ts } } : {}),
+      })
+    }
+  }
+  return rows
+}
+
 async function scenarioLs(args: string[]): Promise<number> {
   for (const a of args) {
     if (!a.startsWith('--')) continue
@@ -598,21 +641,7 @@ async function scenarioLs(args: string[]): Promise<number> {
     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 } } : {}),
-      })
-    }
-  }
+  const rows = scenarioListRows(nodes, unmeasuredOnly)
   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}'` : ''}`)
@@ -642,12 +671,18 @@ export async function runEval(args: string[]): Promise<number> {
   if (sub === 'retract') return retractCmd(args.slice(1))
   if (sub === 'clean') return clean(args.slice(1))
   if (sub === 'ls') return show(args.slice(1))
+  if (sub === 'matrix') {
+    // the live-behavior matrix runner ([[live-matrix]]) — lazily imported so the heavy session machinery
+    // never loads for the plain filing/reading verbs.
+    const { runMatrix } = await import('./matrix.js')
+    return runMatrix(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]')
+  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] | matrix <launcher> [--node <id>] [--rows k1,k2] | lint [--changed] | ok <node> [--scenario <name>] | retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>] | clean [--keep-latest|--all]')
   return 2
 }
 

package/spec-eval/src/evaltab.ts

@@ -2,7 +2,7 @@ import { relative, dirname } from 'node:path'
 import { repoRoot, driftIndex, historyIndex, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { loadEvalRemarkTracks, trackKey, type RemarkTrack, type Issue, type Reply } from '../../spec-cli/src/issues.js'
-import { evalNodes, type EvalNode } from './scenarios.js'
+import { evalNodes, type EvalNode, type ScenarioTestReference } 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'
@@ -91,7 +91,7 @@ function toRemarkView(rm: Reply, threadId: string, dangling: boolean): RemarkVie
 // at NODE level. `scenario` is the orphaned name (rendered struck-through / gone); `remarks` are all dangling.
 export type DanglingTrack = { scenario: string; threadId: string; thread: Issue; remarks: RemarkView[] }
 
-export type ScenarioInfo = { name: string; expected: string; tags?: string[]; code?: string[] }
+export type ScenarioInfo = { name: string; expected: string; tags?: string[]; test?: ScenarioTestReference; code?: string[] }
 
 // `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`
@@ -164,7 +164,8 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
   const threadFor = (scenario: string): Issue | undefined => tracks.get(trackKey(id, scenario))?.thread
   const scenarios: ScenarioInfo[] = ynode.scenarios.map((s) => ({
     name: s.name, expected: s.expected,
-    ...(s.tags?.length ? { tags: s.tags } : {}), ...(s.code?.length ? { code: s.code } : {}),
+    ...(s.tags?.length ? { tags: s.tags } : {}), ...(s.test ? { test: s.test } : {}),
+    ...(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), the human-ok events as the sign-off overlay.

package/spec-eval/src/humanok.ts

@@ -30,7 +30,7 @@ export function fileHumanOk(nodeId: string, scenario: string, by: string): OkRes
   // 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` }
+  if (!forScenario.length) return { ok: false, error: `'${node.id}' scenario '${scenario}' has no effective eval — 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.