spexcode 0.3.0 → 0.4.1

package/spec-cli/src/guide.ts

@@ -62,9 +62,22 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            Drives drift + eval freshness. Many nodes MAY govern the same file (ordinary
            composition); a file governed by > maxOwners nodes warns (the \`owners\` rule — split it). Omit
            for a pure-prose node: a cross-cutting contract no file owns.
+           The entry may pin named units — ANCHORS: one or more \`path#symbol\` rows, ALL on the same
+           base file (\`#Class.method\` for a class method; top-level functions, arrow/const declarations,
+           classes, enums anchor cleanly; a type/interface anchor warns). One-govern counts DISTINCT
+           base paths, so selectors never widen govern past one file. Several selectors are OR: a
+           commit hitting ANY upgrades drift to the blocking \`anchor-drift\` error (one error per
+           entry, naming the hit selectors — a commit counts once). Without an anchor, drift stays
+           advisory forever. A base path is either whole-file (bare) or selector-scoped, never both;
+           duplicates, globs/directories with a selector, and dead/ambiguous units all error loud. A
+           selector-scoped governor claims units, not the file, so it stays out of the \`owners\` bound
+           (spex spec owner still displays it, marked "(scoped)"). Anchors are optional.
   related: files this node REFERENCES but does not own — a YAML list, same path forms. Carries coverage
            (never drift, never eval freshness, nothing to ack); it is the many-to-many net that claims the files
-           govern doesn't. Every listed path must exist (lint integrity error otherwise).
+           govern doesn't. Every listed path must exist (lint integrity error otherwise). A related row
+           may also pin \`path#symbol\`: the node then hears about a commit ONLY when it moves that
+           unit — a hit is a soft \`related-drift\` warn naming the selector, a miss is SILENT (a scoped
+           related file's ordinary file-level nudge is off). Still never blocks, no ack, no eval freshness.
   surface  plugin-system/.plugins nodes only: one or MORE of system (folded into every agent's prompt) |
            command (a /command) | skill (an on-demand SKILL.md the harness loads when a task matches the
            node's desc) | agent (a spawnable sub-agent definition; its \`tools:\` list is the spawned
@@ -84,7 +97,18 @@ Bodies without those headings are read whole. Link sibling nodes with [[node-id]
 a REAL node (lint's mention rule; backtick a placeholder like \`[[node]]\` so it reads as sample text).
 
 WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
-  integrity  (error)  every code:/related: path exists.
+  integrity  (error)  every code:/related: path exists — and every anchor RESOLVES: a dead anchor (unit
+                      deleted/renamed), an ambiguous one (two same-named units in one file), a file that
+                      no longer parses, a language with no designated extractor, or an extractor that
+                      can't run here (e.g. no host typescript — 'npm i -D typescript' or drop the anchor)
+                      all error, never silently pass. So do a relation's STRUCTURAL defects: a duplicate
+                      entry, a base path both bare and selector-scoped, or a selector on a
+                      glob/directory.
+  anchor-drift (error) a commit since the node's version intersected an ANCHORED unit's lines (judged
+                      from the file as it existed AT each commit) and no Spec-OK ack covers it — the
+                      blocking tier of drift. Selectors on one file are OR'd: one error per entry, the
+                      hit selectors named, each commit counted once. Remedy: update the spec, or
+                      \`spex spec ack\` with a real reason (recorded in the ack commit body).
   one-govern (error)  a node governs (code:) at most ONE file — keep the true subject, move the rest
                       to related:.
   living     (error)  no "## vN" changelog headings — the body is current-state.
@@ -98,11 +122,21 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
                       twin; is an intermediate grouping layer missing?
   coverage   (warn)   every source file is claimed by ≥1 node — via code: OR related: (related is the net).
   drift      (warn)   a governed file has commits newer than the node's spec version — it may be stale.
-                      Remedy: edit the spec to the new intent (re-versions the node), OR \`spex spec ack <node>
-                      --reason "…"\` when only mechanics changed and the contract still holds.
-  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never blocks.
-  owners     (warn)   a file governed by > maxOwners nodes (default 3) does too much — SPLIT it so each
-                      governor owns its own module (or merge the nodes, or give it one foundation owner).
+                      ALWAYS advisory: unanchored drift never blocks a commit (the blocking tier is
+                      anchor-drift above). On a selector-SCOPED code file whose window has NO hit (a
+                      miss), this advisory stays by default; the committed \`lint.scopedCodeMiss:
+                      "ignore"\` silences ONLY it (hit blocks, bare drift, integrity, acks, related,
+                      eval freshness all untouched). Remedy: edit the spec to the new intent
+                      (re-versions the node), OR \`spex spec ack <node> --reason "…"\` when only
+                      mechanics changed and the contract still holds.
+  anchor     (warn)   an anchor pins a type/interface — types reshape with every refactor; anchor the
+                      behaviour-bearing unit instead.
+  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never
+                      blocks. A selector-scoped related row instead warns per HIT (selector named);
+                      its file-level misses are silent.
+  owners     (warn)   a file governed WHOLE-FILE by > maxOwners nodes (default 3) does too much — SPLIT
+                      it so each governor owns its own module (or merge the nodes, or give it one
+                      foundation owner). Selector-scoped governors don't count toward the bound.
   confusable-id (warn) two leaf ids one edit apart read as the same word — rename one to read apart.
 
 LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex spec lint\` must reach 0 errors
@@ -125,8 +159,13 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
                \`frontend-e2e, backend-api, cli, desktop, mobile\`). A tag outside the library is rejected —
                use an existing one, or add it to the library to mint it. Tags classify a scenario (surface,
                device) so it can be filtered and, later, routed to the right driver.
-  test         optional. A repo path to a co-located runnable file (a playwright.spec.ts, a script)
-               the agent MAY run by hand. Not a driver — eval never executes it.
+  test         optional. Either a repo-path scalar (the backward-compatible shorthand) or a strict object:
+                 test:
+                   path: tests/auth.spec.ts
+                   name: rejects an expired session
+               Both forms normalize in JSON to \`{ "path": "..." }\` with optional \`"name"\`. The object
+               requires exactly \`path\` + \`name\`; its case name is opaque text preserved for the measuring
+               hand. The path must exist. SpexCode does not parse WDIO/Playwright or execute anything.
   code         optional. The file THIS scenario GOVERNS, ideally one (a comma list / flow list \`[a, b]\` is
                allowed) — its own slice of the code freshness axis, so scenarios on one node go stale
                independently. Absent → it inherits the node's \`code:\` list. A file governed by > maxOwners
@@ -338,9 +377,16 @@ the guard (the flag is the declaration of intent). Reads point anywhere.
   lint.altitude            body budgets: { lineBudget, charBudget, sizeable, dense, steps }
                            (defaults 50 / 4200 / 35 / 1.3 / 3).
   lint.maxChildren         breadth budget: warn at >= this many direct children (default 8).
-  lint.driftErrorThreshold commit-local gate HARD-BLOCKS a commit touching a node >= this many commits
-                           behind (default 3).
-  lint.maxOwners           warn when a file is governed by > this many nodes (default 3).
+  lint.maxOwners           warn when a file is governed WHOLE-FILE by > this many nodes (default 3).
+                           Selector-scoped governors (code: path#symbol) don't count toward the bound.
+                           (lint.driftErrorThreshold is RETIRED: the count-based commit gate is replaced
+                           by code anchors — \`code: path#symbol\` — whose hits error unconditionally; a
+                           leftover key is ignored.)
+  lint.scopedCodeMiss      "warn" (default) | "ignore" — the file-level drift ADVISORY on a selector-
+                           scoped code: file whose window commits hit no selector (a miss). "ignore"
+                           silences ONLY that advisory; it never touches hit blocks (anchor-drift),
+                           bare-path drift, integrity, Spec-OK acks, related semantics, or eval
+                           freshness. A project policy → committed spexcode.json.
   lint.scenarioTags        the closed vocabulary an eval scenario's tags: must draw from (default
                            ["frontend-e2e","backend-api","cli","desktop","mobile"]); extend to mint a tag.
 Example — govern your own source dir and loosen the altitude budget:
@@ -359,9 +405,11 @@ const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and
 
 SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
 measurement) and leaves the MIDDLE — construction — to the harness/agent/test framework; freshness
-stitches the two ends into a closed loop. The footprint follows: the head+tail (.spec, spexcode.json,
-evals) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
-Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
+stitches the two ends into a closed loop. Materialize is the base operation of harness ADAPTATION:
+one pass renders the spec tree into whatever artifacts the selected harness auto-discovers, so that
+is how SpexCode reaches an agent — never a launch-time flag. The footprint follows: the head+tail
+(.spec, spexcode.json, evals) is the ASSET and lives in git like source; everything else is derived
+wiring or a machine fact. Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
 behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 
 ── THE FOUR KINDS (all fixed) ──

package/spec-cli/src/harness.ts

@@ -133,13 +133,21 @@ export interface Harness {
   // grace lives in the caller (sessions.ts liveness), so a still-booting pane reads starting, not offline.
   liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline'
   // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
-  // control socket — OPTIMISTIC-after-liveness (loud failure when the socket is missing/dead or the write can't
-  // flush; once the reply line flushes to a live socket it returns ok, without waiting for an application ack —
-  // see replyViaSocket). codex: JSON-RPC on the same app-server WebSocket the
+  // control socket — an ATOMIC reply+repaint chunk whose `repaint-done` proves the reply was PARSED; a close
+  // before it proves a concurrent connect kicked the chunk (the daemon is single-connection) → resend; a wall
+  // expiry on a still-open connection is a busy-not-lost agent → optimistic ok (see replyViaSocket). codex:
+  // JSON-RPC on the same app-server WebSocket the
   // visible TUI uses — it reads the thread live and either `turn/steer`s the message INTO an in-progress turn
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
   // Returns ok=false with a reason that propagates to the API.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
+  // the ONE pane state where this harness SWALLOWS a prompt that its delivery channel confirms (so no
+  // socket-side check can see it): given the live pane text, return the loud human-readable refusal (naming
+  // the recovery) or null when the pane can take a prompt. sendText captures the pane once and consults this
+  // BEFORE delivering; absent on harnesses with no such state (codex delivery ignores the pane). claude: the
+  // TUI's sessions panel ("← for agents") enqueues an injected reply to the panel context and never drains it
+  // — verified live: parsed + enqueued, no dequeue, no turn, daemon silent.
+  deliveryBlockedBy?(paneText: string): string | null
   // --- materialize: clean (the inverse of write — [[harness-select]] prunes a deselected harness) ---
   // clean is the EXACT inverse of materialize's per-harness write: SURGICALLY remove ONLY SpexCode's own
   // artifacts — the managed contract block (sentinels), the generated shim file, the trust block, and the
@@ -161,11 +169,11 @@ export interface Harness {
 }
 
 // a prompt-dispatch outcome. ok=true means delivery is confirmed at the layer that harness proves it: claude at
-// the TRANSPORT/liveness layer (the reply line flushed to a live rendezvous socket — see replyViaSocket for why
-// it is OPTIMISTIC-after-liveness, not a round-trip ack); codex at the application layer (the app-server accepted
-// `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route (non-2xx)
-// and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts re-exports it for
-// its existing importers.
+// the DAEMON-PARSE layer (the atomic reply+repaint chunk answered `repaint-done`, or the wall expired on a
+// still-open connection — busy, not lost; see replyViaSocket); codex at the application layer (the app-server
+// accepted `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route
+// (non-2xx) and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts
+// re-exports it for its existing importers.
 export type DispatchResult = { ok: boolean; error?: string }
 export type HarnessDeliveryRecord = { session: string; worktreePath?: string; harnessSessionId?: string | null; runtimeDir?: string }
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
@@ -252,50 +260,84 @@ function shQuote(s: string): string {
 const PKG = fileURLToPath(new URL('..', import.meta.url))
 const SPEX = join(PKG, 'bin', 'spex.mjs')
 
-// @@@ replyViaSocket - OPTIMISTIC-after-liveness delivery: connect to the LIVE rendezvous socket and WRITE the
-// `{type:reply}\n` line; once that line FLUSHES to the socket with no immediate transport error, the reply is on
-// the wire and claude submits it the moment it yields the event loop — so we return ok:true right there. We do
-// NOT wait for an application-level acceptance ack. The old code wrote a `{type:repaint}` probe after the reply
-// and waited up to 2500ms for a `{type:repaint-done}` to CONFIRM the reply was processed; the ordering barrier is
-// sound one-way (repaint-done ⟹ delivered) but its ABSENCE is NOT proof of non-delivery — a mid-turn/BUSY claude
-// can't answer the probe within the wall, so a message that actually landed reported a COMMON, misleading false
-// failure. The delivery confirmation therefore lives at the TRANSPORT/liveness layer, not the application layer:
-// deliverViaRendezvous already gates on the socket's existence (liveness), and here the FREE, INSTANT transport
-// signals — a connect that throws, a socket 'error' (ECONNREFUSED / EPIPE), or a 'close' BEFORE the write flushes —
-// are still reported as real failures (they cost no waiting). What we knowingly give up is detection of the narrow
-// alive-but-wedged / reply-rejected / shutting-down cases: a rare silent drop, recoverable because the supervisor
-// sees the worker never transition. That tradeoff is the deliberate contract now — see [[harness-adapter]].
-// Never throws.
-function replyViaSocket(sock: string, text: string): Promise<DispatchResult> {
+// @@@ replyViaSocket - ATOMIC parse-confirmed delivery. The daemon is SINGLE-CONNECTION: a new connect
+// `destroy()`s the previous socket, discarding any received-but-not-yet-parsed line with it — and our own
+// `rendezvousListening` liveness probe IS such a connect, fired for every session on every board snapshot. So
+// the previous optimistic write (return ok once the reply line flushed) LOST prompts whenever a probe landed in
+// the write→parse window, a window that widens exactly when claude is busy mid-turn (field: dashboard messages
+// recorded `sent` with no trace in the claude transcript; measured 2/10 lost under a 20ms probe hammer). The
+// daemon parses a chunk's complete lines in ONE synchronous loop, so writing `{type:reply}` + `{type:repaint}`
+// as ONE chunk makes the pair indivisible — a kick loses BOTH or NEITHER — and the outcome decidable from this
+// connection alone:
+//   `repaint-done` arrives  → the reply line before it was parsed (in-order barrier) → ok, CONFIRMED.
+//   'close' before it       → the chunk was never parsed (kicked by a concurrent connect) → resolve kicked:true
+//                             so deliverViaRendezvous RESENDS — a proven loss, so the retry cannot duplicate.
+//   wall expires, conn open → a busy event loop is DELAYING, not losing (the 2500ms-wall lesson: ack absence is
+//                             NOT non-delivery) → ok, OPTIMISTIC — never a false failure on a busy worker.
+//   `reply-rejected`/`auth-rejected`/`shutting-down` → loud failure, not retried.
+// Other daemon lines (heartbeat, state patches) are ignored. Never throws.
+type ReplyOutcome = DispatchResult & { kicked?: boolean }
+function replyViaSocket(sock: string, text: string, wallMs = 10_000): Promise<ReplyOutcome> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection>
-    const done = (r: DispatchResult) => {
+    const done = (r: ReplyOutcome) => {
       if (settled) return
       settled = true
+      clearTimeout(wall)
       try { c?.destroy() } catch { /* */ }
       resolve(r)
     }
+    const wall = setTimeout(() => done({ ok: true }), wallMs)
     try {
       c = createConnection({ path: sock })
     } catch (e) {
       done({ ok: false, error: `rendezvous socket connect threw: ${String(e)}` })
       return
     }
-    c.on('error', (e: NodeJS.ErrnoException) => done({ ok: false, error: `rendezvous socket connect failed: ${e?.code || String(e)}` }))
-    c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the prompt was written' }))
-    // write the reply line; the write callback fires once it flushes to the live socket → optimistic ok. An
-    // immediate transport 'error'/'close' beats the callback and reports the real failure (done is idempotent).
-    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n', () => done({ ok: true })))
+    // ECONNRESET/EPIPE are the KICK surfacing as an error: the daemon destroy()s the previous connection the
+    // moment a new one connects, and destroying a socket with OUR chunk still unread raises RST — whereas a
+    // parsed chunk answers repaint-done (readable even after a later close) before any clean FIN. So both codes
+    // PROVE the chunk was never parsed → retryable, same as the clean pre-parse close. ECONNREFUSED/ENOENT
+    // (daemon gone) stay loud.
+    c.on('error', (e: NodeJS.ErrnoException) => {
+      const code = e?.code || String(e)
+      const kicked = code === 'ECONNRESET' || code === 'EPIPE'
+      done({ ok: false, ...(kicked ? { kicked } : {}), error: `rendezvous socket error: ${code} — prompt NOT delivered` })
+    })
+    c.on('close', () => done({ ok: false, kicked: true, error: 'rendezvous connection was closed before the daemon parsed the prompt (kicked by a concurrent connect)' }))
+    c.on('connect', () => c.write(JSON.stringify({ type: 'reply', text }) + '\n' + JSON.stringify({ type: 'repaint' }) + '\n'))
+    let buf = ''
+    c.on('data', (d) => {
+      buf += d.toString('utf8')
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        let type = ''
+        try { type = (JSON.parse(line) as { type?: string })?.type ?? '' } catch { continue }
+        if (type === 'repaint-done') return done({ ok: true })
+        if (type === 'reply-rejected' || type === 'auth-rejected') return done({ ok: false, error: `rendezvous daemon rejected the prompt (${type}) — prompt NOT delivered` })
+        if (type === 'shutting-down') return done({ ok: false, error: 'agent is shutting down — prompt NOT delivered' })
+      }
+    })
   })
 }
 // claude's deliver: the pre-write LIVENESS gate — fail loud BEFORE attempting the socket if it isn't there (a
-// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent alive).
-// Then inject the reply optimistically via replyViaSocket (no round-trip ack).
-function deliverViaRendezvous(id: string, text: string): Promise<DispatchResult> {
+// clearer message than a raw connect error, and the delivery's confirmation layer: socket present = agent
+// alive). Then the atomic parse-confirmed write; a KICKED outcome is a proven whole-chunk loss, so it resends
+// (bounded attempts + jitter so re-collision with the probe cadence is unlikely); exhausted retries fail loud.
+const DELIVER_ATTEMPTS = 3
+export async function deliverViaRendezvous(id: string, text: string, wallMs?: number): Promise<DispatchResult> {
   const sock = rvSock(id)
-  if (!existsSync(sock)) return Promise.resolve({ ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` })
-  return replyViaSocket(sock, text)
+  if (!existsSync(sock)) return { ok: false, error: `no rendezvous control socket for session ${id} (socketless/old session, or the agent is offline) — prompt NOT delivered` }
+  let last: ReplyOutcome = { ok: false, error: 'not attempted' }
+  for (let attempt = 1; attempt <= DELIVER_ATTEMPTS; attempt++) {
+    last = await replyViaSocket(sock, text, wallMs)
+    if (last.ok || !last.kicked) return { ok: last.ok, ...(last.error ? { error: last.error } : {}) }
+    await new Promise((r) => setTimeout(r, 60 + Math.random() * 140))
+  }
+  return { ok: false, error: `rendezvous delivery was kicked by concurrent connects ${DELIVER_ATTEMPTS}× — prompt NOT delivered, retry the send` }
 }
 
 type JsonRpc = { id?: number; method?: string; params?: unknown; result?: unknown; error?: { code?: number; message?: string } }
@@ -997,6 +1039,15 @@ export const claudeHarness: Harness = {
   // dead-pane-reads-working bug). See rendezvousListening.
   liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
+  // the TUI's sessions panel ("← for agents"): a reply injected here is parsed + enqueued to the PANEL context
+  // and never drained (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so
+  // the parse-confirmed delivery above would still report a false success into it. Matched on the panel's own
+  // strings — the new-session composer placeholder, or its footer key hints together (either alone could drift
+  // across claude versions; requiring the footer PAIR keeps a prose false-positive unlikely).
+  deliveryBlockedBy: (paneText) =>
+    paneText.includes('describe a task for a new session') || (paneText.includes('enter to return') && paneText.includes('space to reply'))
+      ? 'the claude TUI is focused on its sessions panel ("← for agents"), which silently swallows injected prompts — press Enter in the session terminal to return to the composer, then resend'
+      : null,
   resumeArg: (rec) => `--resume ${rec.session}`,
 }
 

package/spec-cli/src/help.ts

@@ -45,7 +45,7 @@ derived status, title, and attention badges (drift:N · stale:N · issues:N · g
   },
   init: {
     line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
-    body: `Usage: spex init [dir=cwd] [--preset default|careful]
+    body: `Usage: spex init [dir=cwd] [--preset default]
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
@@ -55,15 +55,17 @@ a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
   },
   materialize: {
-    line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
+    line: 'materialize           the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts',
     body: `Usage: spex materialize
 
-Materializes the surface:system plugin nodes into the managed <!-- spexcode --> block of
-CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
-git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
-post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
-has no spex-planted hooks yet (CI, a cloud agent): the artifacts are generated and excluded, so they
-never arrive via git.`,
+The base operation of HARNESS ADAPTATION: one pass renders the spec tree's surface nodes into the
+artifacts each selected harness auto-discovers — the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md, the .claude/.codex shims, the skills/agents — and prints the content hash.
+The outputs are derived and never tracked: to change one, edit its source (.plugins, spexcode.json)
+and re-materialize — never the artifact. Not a one-time setup: it anchors on git-native events
+(init · this verb · session-worktree creation · the pre-commit/post-checkout/post-merge hooks) —
+run it by hand after a toolchain update, or in the setup step of any clone that has no spex-planted
+hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arrive via git.`,
     see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
@@ -121,16 +123,24 @@ owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval fr
 — coverage only), with the verdict spelled out (uncovered / related-only / sanely governed /
 over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).
 
-lint — checks the whole spec↔code graph and exits non-zero on errors (or a blocked commit-local
-drift gate). Errors: integrity (a code:/related: file does not exist) · one-govern (a node governs >1
-file) · living (a "## vN" changelog heading) · id-format (an id char outside the whitelist — ascii
-[a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a leaf id
-reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift ·
-related-drift · owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+lint — checks the whole spec↔code graph and exits non-zero on errors. Errors: integrity (a
+code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` selector; a selector
+whose language has no designated extractor or whose extractor can't run here; a duplicate entry, a
+base path both bare and scoped, or a selector on a glob/directory) · anchor-drift (a
+commit since the spec's version touched an ANCHORED unit's lines, unacked — the blocking tier of
+drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
+governs >1 DISTINCT file) · living (a "## vN" changelog heading) · id-format (an
+id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
+leaf id reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift
+(UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
+"ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
+per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
+confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
 contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
-and the spec's contract still holds. --reason is required but NOT stored. If the intent DID change,
+and the spec's contract still holds. --reason is required and recorded in the ack commit's body
+(quieting an anchor hit is a strong claim — the why must be durable). If the intent DID change,
 edit the spec instead — same commit as the code.`,
     see: 'spex guide spec (the file format + every lint rule) · spex graph (browse the whole tree)',
   },
@@ -192,7 +202,7 @@ ${MENTION_NOTE}`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
@@ -200,6 +210,7 @@ ${MENTION_NOTE}`,
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
+       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest reading
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
        spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache
 
@@ -213,7 +224,7 @@ ls — node-scoped bare (its per-scenario eval history); session-scoped with an
 ✦-marked ahead of the inherited baseline. --export writes that evaluation as ONE self-contained
 HTML artifact (diff · evidence inlined · gates) for CI/sharing.
 
-scenario ls — the DECLARED contracts (name · tags · latest verdict), no evals: bare lists every
+scenario ls — the DECLARED contracts (name · tags · normalized test reference · latest verdict), no evals: bare lists every
 measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
 
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
@@ -222,6 +233,11 @@ stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source
 files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
 commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.
 
+ok — the human's reviewed-and-agreed mark on the scenario's LATEST reading: an appended, monotonic
+sign-off bound to that one immutable reading (a newer reading or staleness releases it on its own —
+no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
+(an agent's judgment on a reading is a remark, never a self-blessing).
+
 retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
 deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
 unmeasured.

package/spec-cli/src/index.ts

@@ -5,7 +5,7 @@ import { Hono } from 'hono'
 import { cors } from 'hono/cors'
 import { etag } from 'hono/etag'
 import { createNodeWebSocket } from '@hono/node-ws'
-import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig } from './specs.js'
+import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadConfig, loadReviewConfig } from './specs.js'
 import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
 import { closeIssue, createIssue, findIssue, issueStores, mergedIssues, promote, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
@@ -16,11 +16,13 @@ import { getBoardJson } from './graphCache.js'
 import { boardStream, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
 import { newSession, listSessions, sendText, rawKey, stopSession, closeSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, superviseQueue } from './sessions.js'
+import { superviseTimeline, readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, launcherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
 import { evalNodes } from '../../spec-eval/src/scenarios.js'
 import { fileHumanReading } from '../../spec-eval/src/filing.js'
+import { fileHumanOk } from '../../spec-eval/src/humanok.js'
 import { buildExportModel, renderExportHtml, buildSessionEvals } from '../../spec-eval/src/sessioneval.js'
 import { saveUpload, MAX_UPLOAD_BYTES } from './uploads.js'
 import { attachViewer, detachViewer, resizeBridge, forwardWheel, superviseBridges, type Viewer } from './pty-bridge.js'
@@ -63,15 +65,19 @@ app.get('/api/specs', async (c) => c.json(await loadSpecs()))
 // the search corpus ([[graph-lean]]): a filesystem-only {id,title,path,desc,body} for every node, NO git. The
 // board omits `body` to stay lean, so the search palette fetches this ONCE when it opens (cached client-side)
 // to rank nodes over their prose — off the board's hot poll. A literal segment, before the `:id` routes.
-// Scenario prose rides the same corpus: the board's `scenarios` fold is slim ({name, tags}), so a measurable
-// node's row here carries its declared scenarios' description/expected (+ per-scenario code) — one fetch
+// Scenario prose rides the same corpus: the board's `scenarios` fold is slim ({name, tags, test}), so a measurable
+// node's row here carries its declared scenarios' description/expected (+ test reference and per-scenario code) — one fetch
 // serves both the palette's scenario plane and the focus-panel preview.
 app.get('/api/specs/lite', (c) => {
   const scByNode = new Map(evalNodes(repoRoot()).map((y) => [y.id, y.scenarios]))
   return c.json(loadSpecsLite().map((row) => {
     const sc = scByNode.get(row.id)
     return sc?.length
-      ? { ...row, scenarios: sc.map((s) => ({ name: s.name, description: s.description, expected: s.expected, ...(s.code?.length ? { code: s.code } : {}) })) }
+      ? { ...row, scenarios: sc.map((s) => ({
+          name: s.name, description: s.description, expected: s.expected,
+          ...(s.test ? { test: s.test } : {}),
+          ...(s.code?.length ? { code: s.code } : {}),
+        })) }
       : row
   }))
 })
@@ -113,6 +119,19 @@ app.post('/api/specs/:id/evals', async (c) => {
   const r = fileHumanReading(c.req.param('id'), b)
   return r.ok ? c.json({ ok: true, reading: r.reading }) : c.json({ error: r.error }, 400)
 })
+// the HUMAN SIGN-OFF write ([[human-ok]]) — the dashboard's ok affordance and `spex eval ok` share this ONE
+// write (LAW L: no dashboard-only path). Identity is SERVER-DERIVED 'human', never the request body (the
+// same rule as /api/remarks). The write appends a monotonic human-ok event bound to the scenario's latest
+// reading and — on the trunk checkout — commits it straight to trunk; the board cache is invalidated
+// atomically with persistence so the writer's own refetch never races a stale cache.
+app.post('/api/specs/:id/evals/ok', async (c) => {
+  const b = await c.req.json().catch(() => null)
+  if (!b || typeof b.scenario !== 'string') return c.json({ error: 'body needs { scenario }' }, 400)
+  const r = fileHumanOk(c.req.param('id'), b.scenario, 'human')
+  if (!r.ok) return c.json({ error: r.error }, 400)
+  notifyBoardChanged('full')
+  return c.json({ ok: true, already: r.already, humanOk: r.humanOk })
+})
 // serve a reading's evidence blob by content hash (bytes never enter git): bad hash → 400, missing → 404,
 // else the bytes with a sniffed MIME and an immutable cache header (the name IS the content hash).
 // HTTP Range is honored — a <video> can only SEEK when the server answers byte ranges (a browser clamps
@@ -157,7 +176,9 @@ app.get('/api/settings', async (c) => c.json({
 // the `surface: command` plugin-root nodes (built/active only) for the new-session `/` dropdown — each with
 // its prompt `body` ({{targets}} placeholder), `kind`, and folder `dir` + co-located `files`. surface is a
 // frontmatter field, not a dir (specs.ts loadSurface); `surface: system` siblings are gathered elsewhere.
-app.get('/api/plugins', (c) => c.json(loadConfig()))
+// `?surface=review` lists the review-track presets instead ([[review-commands]] — the eval detail's
+// remark-composer `/` dropdown); the exposed surfaces stay this explicit whitelist, never a passthrough.
+app.get('/api/plugins', (c) => c.json(c.req.query('surface') === 'review' ? loadReviewConfig() : loadConfig()))
 // the ISSUES read surface ([[issues]]) for the dashboard's issues page — the merged list over every store
 // (local threads + the resident forge slice), the SAME mergedIssues() the CLI drain reads, verbatim
 // (the dashboard computes nothing over it: no re-sort, no salience ranking). The `enabled` flag mirrors
@@ -390,6 +411,14 @@ app.get('/api/sessions/:id/capture', async (c) => {
   if (r.reason === 'offline') return c.text('session offline (no live pane)', 409)
   return c.text('capture failed', 502)
 })
+// the session's persisted interaction history ([[session-timeline]]): authored status transitions (with the
+// FULL note text) + delivered prompts, timestamped, oldest first — what a terminal-free surface renders as
+// the conversation. `?limit=<n>` caps the tail (default 500). 404 for an unknown/non-governed id.
+app.get('/api/sessions/:id/timeline', (c) => {
+  const limit = Number(c.req.query('limit'))
+  const r = readTimeline(c.req.param('id'), Number.isFinite(limit) && limit > 0 ? limit : undefined)
+  return r ? c.json(r) : c.json({ error: 'no such session' }, 404)
+})
 // the session RECORD detail (`spex session show`): the board row (status · node · branch · launcher · …)
 // plus the full originating prompt (the row itself carries only the preview). One id-addressed read backs
 // the CLI's show; 404 for an unknown id.
@@ -461,8 +490,10 @@ app.post('/api/sessions/:id/input', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   if (body?.kind === 'text') {
     // `from` (the sender's session id) rides only an agent-to-agent send → the backend records the comms
-    // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged.
-    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined)
+    // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged. `replyVia:"note"` marks a
+    // terminal-free sender ([[session-timeline]]): the server appends the note-reply insert to the delivery.
+    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined,
+      body?.replyVia === 'note' ? { replyVia: 'note' } : {})
     return c.json(r, r.ok ? 200 : 502)
   }
   if (body?.kind === 'keys') {
@@ -517,6 +548,7 @@ installConnectionReaper(server as unknown as HttpServer)
 injectWebSocket(server)
 superviseBridges()   // keep a warm tmux client per live session, so opening a tab is instant
 superviseQueue()     // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
+superviseTimeline()  // record authored-lifecycle transitions to each session's durable timeline ([[session-timeline]])
 console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`)
 
 // graceful drain (the other half of zero-downtime reload, supervise.ts): on SIGTERM stop accepting new

package/spec-cli/src/init.ts

@@ -11,11 +11,12 @@ const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 
 // the cumulative preset chain, lean → cautious (see [[init-preset]]). `default` is the live `.plugins`
-// instance set (planted from templates/spec); every higher tier is a SEPARATE package under
-// templates/presets/<tier>/ that seeding stacks ON TOP — a superset, so selecting `careful` seeds the
-// default set PLUS the careful package. Selection matters ONLY here at seed time; the running repo just
+// instance set (planted from templates/spec); a higher tier would be a SEPARATE package under
+// templates/presets/<tier>/ that seeding stacks ON TOP — a superset. No non-default tier ships today
+// (the `careful` package was retired); the chain mechanism stays for when one earns its keep.
+// Selection matters ONLY here at seed time; the running repo just
 // walks whatever `.plugins` ended up planted, so there is no launcher-side preset gate.
-const PRESET_TIERS = ['default', 'careful'] as const
+const PRESET_TIERS = ['default'] as const
 const presetRank = (name: string): number => (PRESET_TIERS as readonly string[]).indexOf(name)
 
 // recursively copy srcDir -> destDir, NEVER overwriting an existing file. Returns the repo-relative