spexcode 0.4.0 → 0.4.1

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,6 +16,7 @@ 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'
@@ -64,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
   }))
 })
@@ -171,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
@@ -404,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.
@@ -475,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') {
@@ -531,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/lint.ts

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { repoRoot, git, driftIndex, historyIndex, rowsFor } from './git.js'
 import { loadSpecs } from './specs.js'
@@ -16,6 +16,10 @@ export type LintConfig = {
   maxChildren: number        // breadth budget: warn at >= this many direct children
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
   scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
+  scopedCodeMiss: 'warn' | 'ignore' // the file-level drift ADVISORY on a selector-scoped code: file whose window has no
+                             // selector hit ([[code-anchor]]). 'warn' (default) keeps today's drift warning; 'ignore'
+                             // silences ONLY that advisory — hit blocks, bare code drift, integrity, acks, related
+                             // semantics, and eval freshness are all untouched by this knob.
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
@@ -26,6 +30,7 @@ const DEFAULT_CONFIG: LintConfig = {
   maxChildren: 8,
   maxOwners: 3,
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
+  scopedCodeMiss: 'warn',
 }
 export function loadConfig(root: string): LintConfig {
   // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
@@ -44,6 +49,10 @@ export function loadConfig(root: string): LintConfig {
 //    ROOT-level files and leaks every nested test into coverage. A slash-less glob is a basename intent →
 //    prepend "**/" so it matches that basename at any depth (the default "**/*.test.*" already does).
 export function normalizeConfig(cfg: LintConfig): LintConfig {
+  // a mistyped enum silently reverting to the default would green-wash (or over-warn) exactly the
+  // advisory the author meant to tune — same fail-loud rule as a malformed spexcode.json.
+  if (cfg.scopedCodeMiss !== 'warn' && cfg.scopedCodeMiss !== 'ignore')
+    throw new Error(`spexcode.json lint.scopedCodeMiss must be "warn" or "ignore", got ${JSON.stringify(cfg.scopedCodeMiss)}`)
   const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
   return {
     ...cfg,
@@ -131,15 +140,25 @@ export async function specLint(): Promise<Finding[]> {
   const specs = await loadSpecs()
   const out: Finding[] = []
 
-  // integrity + build the file -> owners map.
+  // integrity + build the file -> owners map. A relation's STRUCTURAL problems (a duplicate entry,
+  // bare/scoped mixing on one base path, a selector on a glob — all from parseRelation,
+  // [[code-anchor]]) are integrity errors: malformed edges block like broken ones.
   const owners = new Map<string, string[]>()
+  const claimed = new Set<string>()
   for (const s of specs) {
+    for (const p of s.relationProblems)
+      out.push({ level: 'error', rule: 'integrity', spec: s.id, msg: `'${s.id}' ${p}` })
+    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
     for (const f of s.code) {
       if (!existsSync(join(root, f)))
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
-      owners.set(f, [...(owners.get(f) ?? []), s.id])
+      claimed.add(f)
+      // a selector-SCOPED entry claims named units, not the whole file, so it stays out of the owners
+      // bound below ([[code-anchor]]) — `spex spec owner` still displays it as a (scoped) governor.
+      if (!scopedPaths.has(f)) owners.set(f, [...(owners.get(f) ?? []), s.id])
     }
-    // one-govern: a node is source of truth for at most ONE file, so drift/eval/ack have a single
+    // one-govern: a node is source of truth for at most ONE file — DISTINCT base paths; several
+    // `path#symbol` selectors on the same file are one subject — so drift/eval/ack have a single
     // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
     // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
     if (s.code.length > 1)
@@ -148,7 +167,6 @@ export async function specLint(): Promise<Finding[]> {
   // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
   // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
-  const claimed = new Set<string>(owners.keys())
   for (const s of specs) for (const f of s.related) {
     if (!existsSync(join(root, f)))
       out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
@@ -276,55 +294,73 @@ export async function specLint(): Promise<Finding[]> {
     out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
   }
 
-  // code anchors ([[code-anchor]]): a code: entry may pin one named unit (`path#symbol`). The anchor is
-  // the BLOCKING tier of drift: a window commit (spec's last version..HEAD, non-merge, touching the
-  // governed file) whose --unified=0 hunks intersect the unit's line range — extracted from the file AS
-  // OF that commit, by the extension's ONE designated extractor — is an anchor-drift ERROR unless a
-  // Spec-OK ack covers it. Resolution failures are never silent: a dead or ambiguous anchor, an
-  // unparseable working-tree file, an extension with no designated extractor, and a designated extractor
-  // that can't run here (no host typescript) all ERROR with the repair spelled out.
+  // code anchors ([[code-anchor]]): a code:/related: entry may pin named units (`path#symbol` — any
+  // number per base file, OR'd). On code:, the anchor is the BLOCKING tier of drift: a window
+  // commit (spec's last version..HEAD, non-merge, touching the governed file) whose --unified=0 hunks
+  // intersect any pinned unit's line range — extracted from the file AS OF that commit, by the
+  // extension's ONE designated extractor — is ONE anchor-drift ERROR naming the hit selectors, unless a
+  // Spec-OK ack covers it. On related:, the SAME engine yields only a soft warn on a hit — a scoped
+  // related miss is silent (never blocks, no ack, no eval freshness). Resolution failures are never
+  // silent for either relation: a dead or ambiguous selector, a selector on a directory, an unparseable
+  // working-tree file, an extension with no designated extractor, and a designated extractor that can't
+  // run here (no host typescript) all ERROR with the repair spelled out.
   const regs = extractors(root)
   const [didx, hidx] = await Promise.all([driftIndex(root), historyIndex(root)])
   const readyWarned = new Set<string>()
   for (const s of specs) {
-    for (const { path, anchor } of s.anchors) {
-      const x = extractorFor(regs, extOf(path))
-      if (!x) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${anchor}, but no extractor is designated for '.${extOf(path)}' files — this language has no anchor support yet: add a LangSpec row (anchors.ts) or drop the #${anchor}` })
-        continue
-      }
-      const ready = x.ready()
-      if (ready !== true) {
-        // once per (extractor, reason), even across several anchored nodes — one repair, one message.
-        if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); out.push({ level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` }) }
-        continue
-      }
-      if (!existsSync(join(root, path))) continue // the missing FILE already errored above
-      let units
-      try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${anchor} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
-        continue
-      }
-      const res = resolveAnchor(units, anchor)
-      if ('dead' in res) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${anchor} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's code: entry to follow it` })
-        continue
-      }
-      if ('ambiguous' in res) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${anchor} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
-        continue
-      }
-      if (res.ok.typeOnly)
-        out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${anchor} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
-      const since = rowsFor(hidx, s.path)[0]?.hash || ''
-      const win = windowCommits(didx, since, path)
-      if (!win.length) continue
-      const hits = await anchorHitCommits(root, win, path, anchor, x)
-      const unparseable = hits.filter((h) => h.unparseable)
-      if (hits.length) {
+    for (const { relation, entries } of [{ relation: 'code' as const, entries: s.codeScoped }, { relation: 'related' as const, entries: s.relatedScoped }]) {
+      for (const { path, selectors } of entries) {
+        const x = extractorFor(regs, extOf(path))
+        if (!x) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — this language has no anchor support yet: add a LangSpec row (anchors.ts) or drop the selector(s)` })
+          continue
+        }
+        const ready = x.ready()
+        if (ready !== true) {
+          // once per (extractor, reason), even across several anchored nodes — one repair, one message.
+          if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); out.push({ level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` }) }
+          continue
+        }
+        if (!existsSync(join(root, path))) continue // the missing FILE already errored above
+        if (statSync(join(root, path)).isDirectory()) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` })
+          continue
+        }
+        let units
+        try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
+          continue
+        }
+        // each selector resolves (or errors) on its own; only the live ones feed the window engine.
+        const live: string[] = []
+        for (const sym of selectors) {
+          const res = resolveAnchor(units, sym)
+          if ('dead' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's ${relation}: entry to follow it` })
+            continue
+          }
+          if ('ambiguous' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
+            continue
+          }
+          if (res.ok.typeOnly)
+            out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${sym} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
+          live.push(sym)
+        }
+        if (!live.length) continue
+        const since = rowsFor(hidx, s.path)[0]?.hash || ''
+        const win = windowCommits(didx, since, path)
+        if (!win.length) continue
+        const hits = await anchorHitCommits(root, win, path, live, x)
+        if (!hits.length) continue
+        const hitSyms = [...new Set(hits.flatMap((h) => h.selectors))]
         const shas = hits.map((h) => h.commit.slice(0, 8)).join(', ')
+        const unparseable = hits.filter((h) => h.unparseable)
         const parseNote = unparseable.length ? ` (${unparseable.length} of these could not be parsed at that commit — counted as hits conservatively)` : ''
-        out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${anchor} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds` })
+        if (relation === 'code')
+          out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${hitSyms.join(', #')} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds` })
+        else
+          out.push({ level: 'warn', rule: 'related-drift', spec: s.id, file: path, msg: `related ${path}#${hitSyms.join(', #')} ('${s.id}') was changed by ${hits.length} commit(s) since v${s.version} [${shas}]${parseNote} — a scoped dependency shifted, worth a glance (SOFT: never blocks, no ack, no eval staleness)` })
       }
     }
   }
@@ -334,9 +370,15 @@ export async function specLint(): Promise<Finding[]> {
   // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
   // parent-edge reachability, the equivalent of `rev-list <version>..HEAD -- <file>`), never a
   // log-position or timestamp guess.
+  // A selector-SCOPED code file keeps this file-level advisory by default (a miss still nudges); the
+  // committed `lint.scopedCodeMiss: "ignore"` silences ONLY this advisory for scoped entries — the
+  // anchor engine's verdicts above (hit = block, resolution failures = integrity) are untouched.
   for (const s of specs) {
-    for (const d of s.driftFiles)
+    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
+    for (const d of s.driftFiles) {
+      if (cfg.scopedCodeMiss === 'ignore' && scopedPaths.has(d.file)) continue
       out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
+    }
   }
 
   // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's

package/spec-cli/src/migrate-table.ts

@@ -5,6 +5,11 @@
 // else is flagged for review, never rewritten.
 export type MigrateAsset = { rel: string; template: string; oldShas: string[] }
 export const TEMPLATE_ASSETS: MigrateAsset[] = [
+  {
+    "rel": "commands/spec.md",
+    "template": "templates/spec/project/.plugins/commands/spec.md",
+    "oldShas": []
+  },
   {
     "rel": "core/idle/idle.sh",
     "template": "templates/spec/project/.plugins/core/idle/idle.sh",
@@ -155,7 +160,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "distill/digest.mjs",
-    "template": "templates/spec/project/.plugins/distill/digest.mjs",
+    "template": "templates/spec/project/.plugins/skills/distill/digest.mjs",
     "oldShas": [
       "b596d196d35688130157698ca90950d412bf527f",
       "faff3509b004e8529d5c7f3abd29512fb389ceb9"
@@ -163,7 +168,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "distill/spec.md",
-    "template": "templates/spec/project/.plugins/distill/spec.md",
+    "template": "templates/spec/project/.plugins/skills/distill/spec.md",
     "oldShas": [
       "3e3fd25db1d465f72b636e6af8bcd873c0ceb3c2",
       "4a0b547ad63e15aa80ed7f826581ad90ca02d0f4",
@@ -172,7 +177,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "extract/spec.md",
-    "template": "templates/spec/project/.plugins/extract/spec.md",
+    "template": "templates/spec/project/.plugins/commands/extract/spec.md",
     "oldShas": [
       "064efd8321925bd0cff7ee725771b500a7baf6e7",
       "45c2b0fe12224ebc124b5f5fecafd1e8d82de93e",
@@ -209,7 +214,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "regroup/spec.md",
-    "template": "templates/spec/project/.plugins/regroup/spec.md",
+    "template": "templates/spec/project/.plugins/commands/regroup/spec.md",
     "oldShas": [
       "37f632450faba3e9c5290468b52535e766faf45e",
       "aa3097a1b7ff51c4a8a0bfab82ac06a585081caa",
@@ -227,6 +232,11 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
       "fc3c060af70b01b2073163880a42d002e285ddc5"
     ]
   },
+  {
+    "rel": "skills/spec.md",
+    "template": "templates/spec/project/.plugins/skills/spec.md",
+    "oldShas": []
+  },
   {
     "rel": "spec.md",
     "template": "templates/spec/project/.plugins/spec.md",
@@ -247,7 +257,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "supervisor/spec.md",
-    "template": "templates/spec/project/.plugins/supervisor/spec.md",
+    "template": "templates/spec/project/.plugins/commands/supervisor/spec.md",
     "oldShas": [
       "036d5602a038e2565cd968e4a8a443ce80026025",
       "05963c00bc1031ba0d4f91ea68d60b1731f475f2",
@@ -269,7 +279,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "tidy/spec.md",
-    "template": "templates/spec/project/.plugins/tidy/spec.md",
+    "template": "templates/spec/project/.plugins/commands/tidy/spec.md",
     "oldShas": [
       "096fc1dd48a1692aeb87614a93bcce2473f2050a",
       "16ccbf044e74765a5c9cc212fba38356950a7e69",

package/spec-cli/src/session-timeline.ts

@@ -0,0 +1,148 @@
+import { watch, existsSync, readFileSync, appendFileSync, mkdirSync, type FSWatcher } from 'node:fs'
+import { sessionsRoot, sessionStoreDir, sessionArtifactPath, listSessionIds, readAliasedRawRecord } from './layout.js'
+import type { Lifecycle, Proposal } from './sessions.js'
+
+// @@@ session-timeline - the PERSISTED interaction history of a session: every authored-lifecycle
+// transition (status + proposal + the FULL note text) and every delivered prompt, timestamped, appended to
+// `timeline.ndjson` in the session's global store dir. This is what a TERMINAL-FREE surface (the phone face,
+// [[mobile-ui]]) renders instead of a live pane: without the terminal, the declaration notes ARE the agent's
+// replies, and the timeline is the whole conversation.
+//
+// WHY an observer, not writer instrumentation: the lifecycle has a writer the TS layer never sees — the
+// mark-active hook value-replaces status/proposal/note in session.json with pure-shell sed ([[state]]).
+// Instrumenting every writer would always miss that one, so the recorder OBSERVES the store instead: one
+// fs.watch on the sessions root (debounced) plus a slow reconcile tick (the fs.watch is best-effort, same
+// stance as [[graph-stream]]'s source 1), and on each tick it diffs every governed record's
+// (status, proposal, note) against the last seen and appends what moved. One mechanism covers every writer
+// by construction. Granularity is the debounce window — a flap faster than ~100ms can collapse, exactly like
+// the board itself.
+//
+// The recorder runs ONLY in the serve process (superviseTimeline is called from index.ts) so exactly one
+// process appends; timestamps are observation times, honest to within the debounce. Only the AUTHORED axis
+// is recorded — liveness (offline/starting/unknown) is a present-tense derivation ([[state]]), re-derived
+// per probe and never history, so it stays off the durable log; a surface shows the CURRENT liveness from
+// the board row. The timeline lives and dies with the session record (close sweeps the store dir), like
+// comms.ndjson. `sent` events are appended by sendText on a CONFIRMED delivery (all prompt deliveries flow
+// through it: dashboard/phone input, `spex session send`, the merge dispatch); `from` is the sending
+// session's id, null = a human surface.
+
+export type TimelineEvent =
+  | { ts: string; kind: 'status'; status: Lifecycle; proposal: Proposal | null; note: string | null; display?: string }
+  | { ts: string; kind: 'sent'; text: string; from: string | null; replyVia?: 'note' }
+
+const timelinePath = (id: string): string => sessionArtifactPath(id, 'timeline.ndjson')
+
+function append(id: string, ev: TimelineEvent): void {
+  try {
+    mkdirSync(sessionStoreDir(id), { recursive: true })
+    appendFileSync(timelinePath(id), JSON.stringify(ev) + '\n')
+  } catch { /* best-effort: a failed history append must never break the state machine or a delivery */ }
+}
+
+function readEvents(id: string): TimelineEvent[] {
+  try {
+    const p = timelinePath(id)
+    if (!existsSync(p)) return []
+    return readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+      try { return JSON.parse(l) as TimelineEvent } catch { return null }
+    }).filter((e): e is TimelineEvent => e != null && (e.kind === 'status' || e.kind === 'sent'))
+  } catch { return [] }
+}
+
+// the display word for an authored state — the SAME composition reconcile uses for the authored axis
+// (awaiting → its proposal's label, active → working), duplicated here as a tiny read-time map rather than
+// importing the state machine (sessions.ts imports THIS module for recordSent; a value import back would
+// be a cycle — the Lifecycle/Proposal imports above are type-only, erased at runtime).
+const PROPOSAL_DISPLAY: Record<string, string> = { merge: 'review', nothing: 'done', close: 'close-pending' }
+const displayOf = (e: { status: Lifecycle; proposal: Proposal | null }): string =>
+  e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
+  : e.status === 'active' ? 'working' : e.status
+
+// ---- the recorder (serve-process only) ----
+
+// id → fingerprint of the last recorded (status, proposal, note); seeded per id from the persisted last
+// status line so a server restart appends nothing for a session that didn't move while the server was down —
+// and DOES append (with an honest observed-now timestamp) when it did.
+const lastSeen = new Map<string, string>()
+const fpOf = (status: string, proposal: string | null, note: string | null): string => JSON.stringify([status, proposal, note])
+
+function lastStatusEvent(id: string): { status: string; proposal: string | null; note: string | null } | null {
+  const evs = readEvents(id)
+  for (let i = evs.length - 1; i >= 0; i--) { const e = evs[i]; if (e.kind === 'status') return e }
+  return null
+}
+
+function scan(): void {
+  let ids: string[] = []
+  try { ids = listSessionIds() } catch { return }
+  for (const id of ids) {
+    try {
+      const raw = readAliasedRawRecord(id)
+      if (!raw || !raw.governed) continue
+      const status = (raw.status || 'active') as Lifecycle
+      const proposal = (raw.proposal || null) as Proposal | null
+      const note = raw.note || null
+      const fp = fpOf(status, proposal, note)
+      if (lastSeen.get(id) === fp) continue
+      if (!lastSeen.has(id)) {
+        const last = lastStatusEvent(id)
+        if (last && fpOf(last.status, last.proposal ?? null, last.note ?? null) === fp) { lastSeen.set(id, fp); continue }
+      }
+      lastSeen.set(id, fp)
+      append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note })
+    } catch { /* one bad record must not stall the sweep */ }
+  }
+  const live = new Set(ids)
+  for (const k of [...lastSeen.keys()]) if (!live.has(k)) lastSeen.delete(k)
+}
+
+let watcher: FSWatcher | null = null
+let debounce: ReturnType<typeof setTimeout> | null = null
+let reconcile: ReturnType<typeof setInterval> | null = null
+
+// start the recorder: one debounced fs.watch on the store (a lifecycle write lands as a session.json write)
+// backstopped by a slow reconcile tick, plus an immediate first sweep. Idempotent; never throws — the
+// timeline is an accessory record, and its failure must never take the server down.
+export function superviseTimeline(): void {
+  if (!reconcile) reconcile = setInterval(scan, 60000)
+  if (!watcher) {
+    const root = sessionsRoot()
+    try { mkdirSync(root, { recursive: true }) } catch { /* best-effort */ }
+    try {
+      watcher = watch(root, { recursive: true }, () => {
+        if (debounce) return
+        debounce = setTimeout(() => { debounce = null; scan() }, 100)
+      })
+    } catch { watcher = null /* the reconcile tick still covers */ }
+  }
+  scan()
+}
+
+// record a CONFIRMED prompt delivery (called by sendText after the harness accepted it). `text` is the
+// caller's message BEFORE any mechanism insert (the note-reply hint is transport, not conversation);
+// `replyVia` marks that the hint rode along so a surface can badge it.
+export function recordSent(id: string, text: string, from: string | null, replyVia?: 'note'): void {
+  try { if (!readAliasedRawRecord(id)?.governed) return } catch { return }
+  append(id, { ts: new Date().toISOString(), kind: 'sent', text, from, ...(replyVia ? { replyVia } : {}) })
+}
+
+// the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each
+// status event carrying its composed display word. null = no such session (the route 404s).
+// Adjacent status lines with identical (status, proposal, note) fold into their first: TWO serve processes
+// observing one store (a throwaway worktree/eval serve beside the live one) each keep their own lastSeen,
+// so a single record move can append twice — cross-process write locking isn't worth buying, so the log
+// stays best-effort append-only and the read is where duplicates die, same stance as the board.
+export function readTimeline(id: string, limit = 500): { events: TimelineEvent[] } | null {
+  let raw: ReturnType<typeof readAliasedRawRecord>
+  try { raw = readAliasedRawRecord(id) } catch { return null }
+  if (!raw || !raw.governed) return null
+  const folded: TimelineEvent[] = []
+  for (const e of readEvents(id)) {
+    const prev = folded[folded.length - 1]
+    if (e.kind === 'status' && prev?.kind === 'status' && prev.status === e.status
+      && (prev.proposal ?? null) === (e.proposal ?? null) && (prev.note ?? null) === (e.note ?? null)) continue
+    folded.push(e)
+  }
+  const tail = folded.slice(Math.max(0, folded.length - Math.max(1, limit)))
+  return { events: tail.map((e) => (e.kind === 'status' ? { ...e, display: displayOf(e) } : e)) }
+}

package/spec-cli/src/sessions.ts

@@ -10,6 +10,7 @@ import { loadSpecs } from './specs.js'
 import { defaultHarness, defaultLauncher, harnessById, resolveLauncher, rvSock, rendezvousListening, type Harness, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, readAliasedRawRecord, envSessionId, type RawRecord } from './layout.js'
+import { recordSent } from './session-timeline.js'
 import { stripRefSigil } from './mentions.js'
 
 // @@@ sessions - the WORKTREE is the durable unit; tmux is a disposable runtime handle. The per-session
@@ -863,6 +864,14 @@ export function withSenderHint(text: string, sender: MsgSender | null): string {
   const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`
   return `${text}\n\n— from ${who}. To reply: spex session send ${sender.id} "<your reply>"`
 }
+// @@@ withNoteReplyHint - the TERMINAL-FREE sender's insert, withSenderHint's sibling: a phone (or any
+// no-terminal surface, [[mobile-ui]]) cannot read the pane, so the only text that ever reaches its human is
+// the declaration NOTE ([[session-timeline]]). This one-line insert tells the agent exactly that, so its
+// next stop carries the complete answer in `--note` instead of prose that dies in an unseen terminal.
+// Appended server-side (the input route passes replyVia:'note'), so the phrase lives in ONE place and any
+// surface — desktop included, later — can opt in with the same flag.
+export const withNoteReplyHint = (text: string): string =>
+  `${text}\n\n— sent from a terminal-free client: the sender CANNOT see your terminal output. When you next stop (done/ask/park), put your COMPLETE reply to this message in the declaration's --note (e.g. spex session done --note "<full answer>") — the note is the only text that reaches them.`
 async function postJSON(path: string, body: unknown): Promise<void> {
   try {
     await fetch(`${await apiBase()}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
@@ -1843,21 +1852,37 @@ export async function watchSessions(emit: (line: string) => void, opts: WatchOpt
 }
 
 // @@@ sendText - PROMPT control for a session, delivered through the session's HARNESS ADAPTER
-// ([[harness-adapter]]) — claude the rendezvous control socket (optimistic-after-liveness: the reply line flushes
-// to a live socket), codex app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent
+// ([[harness-adapter]]) — claude the rendezvous control socket (atomic reply+repaint chunk: repaint-done proves
+// the daemon parsed it, a kicked connection resends, wall expiry on a live connection is busy-not-lost → ok),
+// codex app-server JSON-RPC into the visible TUI's thread. Either way there is NO silent
 // fallback: a prompt that can't be delivered — no socket / dead agent (claude), no app-server/thread (codex) — FAILS LOUD, returning
 // ok:false with a reason that propagates to the caller (API non-2xx, `spex session send`, the merge dispatch),
 // instead of reporting a false success. The harness is resolved from the record; an unknown id fails before any
 // harness transport is addressed. (The separate RAW nav-key channel keeps its own `tmux send-keys` path — see rawKey.)
-export async function sendText(id: string, text: string, from?: string): Promise<DispatchResult> {
+export async function sendText(id: string, text: string, from?: string, opts: { replyVia?: 'note' } = {}): Promise<DispatchResult> {
   if (!text) return { ok: false, error: 'empty prompt — nothing to dispatch' }
   const rec = readRecord(id)
   if (!rec) return { ok: false, error: `no session record for ${id} — prompt NOT delivered` }
   const h = harnessById(rec.harness || defaultHarness.id)
-  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, text)
+  // the pane guard ([[harness-adapter]] deliveryBlockedBy): the ONE pane state where the harness swallows a
+  // prompt its channel confirms (claude's sessions panel), checkable only from the pane — refuse loudly with
+  // the recovery named instead of reporting a false success. A missing pane (window gone, probe failure) skips
+  // the guard: the delivery channel itself is the authority on whether the agent is reachable.
+  if (h.deliveryBlockedBy) {
+    try {
+      const blocked = h.deliveryBlockedBy(await tmux(['capture-pane', '-p', '-t', id], TMUX_PROBE_TIMEOUT_MS))
+      if (blocked) return { ok: false, error: blocked }
+    } catch { /* no pane to consult — let the delivery channel decide */ }
+  }
+  // a terminal-free sender's dispatch carries the note-reply insert ([[session-timeline]]); appended here,
+  // beside the delivery, so every input surface shares the one phrase and the timeline records the message
+  // WITHOUT it (the hint is transport, not conversation).
+  const r = await h.deliver({ ...rec, runtimeDir: runtimeRoot() }, opts.replyVia === 'note' ? withNoteReplyHint(text) : text)
   // record the delivered agent-to-agent message ([[comms-edge]]): only when it carries a sender (an agent
   // send, not a raw human dispatch) and actually landed. Fire-and-forget — never gates the send result.
   if (r.ok && from) void recordComms(id, from)
+  // the durable interaction history ([[session-timeline]]): every confirmed delivery is a `sent` event.
+  if (r.ok) recordSent(id, text, from ?? null, opts.replyVia)
   return r
 }