@skitterbyte/skitterspec-linear 14.0.0 → 17.0.0

package/src/env/classify.js

@@ -45,7 +45,18 @@ function expandCompanion(pattern, spec, config) {
   const tokens = { slug: spec.slug }
   if (/\{identifier\}/.test(pattern)) {
     const field = config && config.branch && config.branch.identifierField
-    const identifier = readFrontmatterField(spec.path, field)
+    // NO PATH IS CANNOT-TELL, not an error. Callers hand in spec objects of two
+    // shapes: `resolveSpec` returns a full one, and `allSpecs` returns
+    // `{folder, slug, worktreePath}` with no `path` at all. Reading the
+    // frontmatter of `undefined` threw, and the throw surfaced as
+    // `render failed: The "path" argument must be of type string` on the review
+    // server's index — every spec, not just one.
+    //
+    // It routes to the same answer a missing identifier already routes to:
+    // expand nothing, so the pattern matches nothing and the path is not
+    // claimed as this spec's. Being wrong here costs a companion file left
+    // unstaged; throwing cost the whole page.
+    const identifier = spec.path ? readFrontmatterField(spec.path, field) : null
     if (!identifier) return null
     tokens.identifier = identifier
   }
@@ -88,4 +99,78 @@ function classifyDirtyTree(spec, dirtyPaths, config) {
   return { owned, foreign }
 }
 
-module.exports = { classifyDirtyTree, expandCompanion }
+// git quotes a path containing unusual bytes and C-escapes it. Unquote what we
+// can; anything we cannot parse confidently is returned as-is, which makes it
+// fail the spec-folder comparison and land in `foreign` — a refusal, which is the
+// safe direction to be wrong in.
+function unquotePath(p) {
+  if (!p.startsWith('"') || !p.endsWith('"')) return p
+  try {
+    return JSON.parse(p)
+  } catch {
+    return p
+  }
+}
+
+/**
+ * Repo-relative paths of everything uncommitted. Returns null when git could not
+ * be read at all — the caller must treat that as "nobody looked", never "clean".
+ *
+ * Two prefix-free listings rather than `git status --porcelain`, deliberately.
+ * Porcelain prefixes every path with a two-character status field, and the shared
+ * git reader TRIMS its output — which eats the leading space of the first line
+ * only, so a fixed-offset parse silently returned `EADME.md` for `README.md`.
+ * These emit bare paths, so there is no offset to get wrong. `--others` also
+ * lists untracked files INDIVIDUALLY, where porcelain collapses them into their
+ * topmost untracked directory — reporting a brand-new spec as `specs/backlog/`,
+ * an ancestor attributable to no single spec, and so refusing the very tree this
+ * gate exists to accept. Both were found by running it, not by reading it.
+ */
+function dirtyPaths(git) {
+  const lists = [
+    git(['diff', '--name-only', 'HEAD']),
+    git(['ls-files', '--others', '--exclude-standard']),
+  ]
+  if (lists.every((l) => l === null)) return null
+  const out = []
+  for (const list of lists) {
+    if (!list) continue
+    for (const line of list.split('\n')) {
+      const q = line.trim()
+      if (q) out.push(unquotePath(q))
+    }
+  }
+  return out
+}
+
+/**
+ * A spec's own uncommitted documents in one tree: `{tree, owned}`, or a reason.
+ *
+ * SHARED ON PURPOSE. Two surfaces render a spec's documents — the CLI's
+ * `review --docs` and the review server's route for a spec with no worktree —
+ * and if they classified separately they could disagree about what the page
+ * shows. A reader's verdict is about the page they read, so the served page and
+ * the written page have to be the same page.
+ *
+ * Three states, never two (`.claude/rules/negative-checks.md` rule 4). An
+ * unreadable git is `cannot tell`, and must not collapse into an empty file
+ * set: an empty set renders a page saying nothing changed, which is the one
+ * reading that is certainly wrong.
+ *
+ * WHAT WOULD FOOL THIS: a document of this spec's that is already committed.
+ * `dirtyPaths` answers about the uncommitted tree only, so a spec whose files
+ * are all committed reports `empty` rather than showing its own text. That is
+ * the intended reading — there is no change to review — and it is why `empty`
+ * is a distinct answer rather than an error.
+ *
+ * @returns {{tree: string, owned: string[]}|{error: string}|{empty: true}}
+ */
+function specDocsIn(tree, spec, config, git) {
+  const paths = dirtyPaths(git)
+  if (paths === null) return { error: 'git could not be read' }
+  const { owned } = classifyDirtyTree(spec, paths, config)
+  if (!owned.length) return { empty: true }
+  return { tree, owned }
+}
+
+module.exports = { classifyDirtyTree, expandCompanion, unquotePath, dirtyPaths, specDocsIn }

package/src/env/config.js

@@ -43,11 +43,98 @@
  *   }
  */
 
-const { readFileSync } = require('node:fs')
-const { join } = require('node:path')
+const { createHash } = require('node:crypto')
+const { readFileSync, realpathSync } = require('node:fs')
+const { join, resolve } = require('node:path')
 
 const CONFIG_FILE = join('specs', '.core', 'env.config.json')
 
+// The window `servePort: "auto"` derives a port from. 7700-7799 keeps the
+// familiar neighbourhood — 7777, the old shared default, is inside it — while
+// giving every repo on a machine its own slot without anyone configuring one.
+//
+// A hundred slots is a SMALL chance of two repos landing together, not no
+// chance. That case is not papered over: the server still refuses the busy
+// port and names `servePort` as the durable fix. Walking up to the next free
+// port would remove the refusal and keep the staleness, because the port would
+// then depend on which repo started first.
+const PORT_BASE = 7700
+const PORT_SPAN = 100
+
+/**
+ * The repo path the derivation hashes — `realpath`ed ONCE, here.
+ *
+ * A symlinked spelling of one tree (`/tmp` → `/private/tmp` on macOS, a
+ * convenience symlink into a worktree root) is the same repo, and hashing the
+ * two spellings separately would hand out two different ports for it — two
+ * different URLs, one of them dead. Resolving once is what makes the port a
+ * property of the tree rather than of how you typed it.
+ *
+ * WHAT WOULD FOOL THIS: `realpathSync` throws on a path that does not exist, so
+ * it falls back to `resolve`. That is the cannot-tell branch and it is routed
+ * to inaction (.claude/rules/negative-checks.md rule 4) — an absolute path is
+ * still deterministic, so the worst case is a stable port for a directory that
+ * is not there, never a crash on an unrelated command.
+ */
+function servePortRoot(dir) {
+  try {
+    return realpathSync(resolve(dir))
+  } catch {
+    return resolve(dir)
+  }
+}
+
+/**
+ * `PORT_BASE + hash(path) % PORT_SPAN` — a PURE function of the path.
+ *
+ * Purity is the whole point, not an implementation detail. A port that is
+ * merely *free* is not a port a link handed out yesterday can still resolve, so
+ * nothing here may read the registry, `.spec-env/`, or any other state on disk:
+ * a port that depends on a file changes when the file is deleted, and this
+ * exists precisely so it does not change. The same tree gets the same port
+ * across a restart, a reboot, and a `--stop`.
+ *
+ * sha256 rather than a hand-rolled hash because its distribution is not
+ * something this file has to argue for — with a hundred slots, clustering is
+ * the only way the derivation could fail at its job.
+ */
+function derivedServePort(root) {
+  const digest = createHash('sha256').update(root).digest()
+  return PORT_BASE + (digest.readUInt32BE(0) % PORT_SPAN)
+}
+
+/**
+ * The port `spec-env review serve` should use, and HOW it was chosen.
+ *
+ * Three sources, in precedence order: `--port` on this run, an explicit number
+ * in `review.servePort`, else the derivation. The `source` rides along so
+ * `--status` can answer "why is this on 7742?" from the tool rather than from
+ * reading this file.
+ *
+ * Returns `{ port, source, root? }`; `root` is the resolved path that was
+ * hashed, present only on a derived port.
+ */
+function resolveServePort(config, dir, override) {
+  const flag = Number(override)
+  if (override != null && override !== '' && Number.isFinite(flag)) {
+    return { port: flag, source: 'flag' }
+  }
+  const configured = config && config.review ? config.review.servePort : undefined
+  if (typeof configured === 'number' && Number.isFinite(configured)) {
+    return { port: configured, source: 'configured' }
+  }
+  const root = servePortRoot(dir)
+  return { port: derivedServePort(root), source: 'derived', root }
+}
+
+/** One sentence naming how a resolved port was chosen, for `--status`. */
+function servePortReason(source) {
+  if (source === 'flag') return 'this run only, from --port'
+  if (source === 'configured') return 'pinned by review.servePort'
+  if (source === 'derived') return "derived from this repo's path"
+  return ''
+}
+
 const DEFAULT_CONFIG = Object.freeze({
   // Where a spec's branch is built. "worktree" gives every spec its own checkout
   // — parallel specs, `main` left free — at the cost of a terminal session per
@@ -110,9 +197,11 @@ const DEFAULT_CONFIG = Object.freeze({
   // planned for a LANDED branch — see teardown.js.
   teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
 
-  // `reader` decides how a diff's location is worded, and — via
-  // `serveOnRemote` — whether the engine stands the local server up so a remote
-  // reader gets a link that opens. It never decides to PUBLISH: publishing
+  // `reader` decides how a diff's location is WORDED, and nothing else. It
+  // once also decided whether the engine served — a gate that produced the
+  // `file://` link on a local machine, where a `file://` page cannot POST and
+  // so the verdict buttons had nowhere to go. `serve` owns that now.
+  // It never decides to PUBLISH: publishing
   // leaves a page this tooling cannot remove, so it stays an explicit ask.
   // `detect` sniffs; `local`/`remote` are the operator's own answer and are
   // believed without sniffing, because they know where they are reading and no
@@ -132,10 +221,34 @@ const DEFAULT_CONFIG = Object.freeze({
   // toward reading the diff is the point, and a project that would rather not
   // be pushed says so once. It is the only key anything reads to decide
   // whether the gate refuses, so turning it off turns off the hook with it.
+  // `serve` decides whether a render stands the local server up: `always`
+  // (the default) or `never`. It replaced `serveOnRemote`, whose name would now
+  // claim to govern remote renders while governing every one of them — and a
+  // config key that lies is what made a wrong fix look right. A legacy
+  // `serveOnRemote: false` is still read as `serve: "never"`.
+  //
+  // THE BIND IS NOT THIS KEY'S BUSINESS, and that separation is what keeps
+  // serving-everywhere free of new exposure: `reader` still decides it, so a
+  // remote reader binds every interface exactly as before and a local or
+  // unknown one binds loopback. Serving more never means listening wider.
+  // `allowNetwork` and `allowRemote` are the two tiers a project permits. They
+  // exist because the engine CANNOT KNOW where the reader is sitting and kept
+  // being asked to guess: detection reported `unknown` on a local session and
+  // produced a page whose buttons cannot POST, reported `remote` and produced a
+  // LAN URL a phone off the network could not reach, and flipped mid-session
+  // and changed the address underneath a reader. Each was fixed on its own; the
+  // next reader position would have produced a fourth.
+  //
+  // So the reader picks instead. `allowNetwork` decides THE BIND — on binds
+  // every interface, off binds loopback — which is the last decision detection
+  // had. `allowRemote` PERMITS publishing; it never publishes, because each
+  // publish leaves a page skitterspec cannot delete.
   review: Object.freeze({
     reader: 'detect',
-    servePort: 7777,
-    serveOnRemote: true,
+    servePort: 'auto',
+    serve: 'always',
+    allowNetwork: true,
+    allowRemote: false,
     commitWith: '/commit',
     required: true,
   }),
@@ -155,6 +268,47 @@ function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * List the keys in a parsed config that `mergeConfig` will not read, as dotted
+ * paths (`open`, `review.readr`). Advisory only — nothing here refuses, and the
+ * merge below is unchanged: unknown keys are still dropped, they are just no
+ * longer dropped in silence.
+ *
+ * The known set is DEFAULT_CONFIG itself rather than a list written out beside
+ * it. That is not a shortcut: every key `mergeConfig` reads is necessarily a key
+ * of the defaults, because a key with no default has nothing to merge onto — so
+ * a hand-written list would be a second copy of the same contract, and a second
+ * copy is how the two come to disagree. Adding a key to `mergeConfig` without
+ * adding its default is already impossible; this check inherits that.
+ *
+ * It descends only where the DEFAULT is a plain object. An array's elements are
+ * data, not keys — `dev` entries, `setup` commands, `spec.companionPaths`,
+ * `live.migrations`, `hotfix.targets` — and walking into them would report every
+ * path in the list as an unknown key.
+ *
+ * WHAT IT DELIBERATELY DOES NOT REPORT: a KNOWN key whose value was rejected for
+ * its type or for not matching an enum (`mode: "Checkout"`,
+ * `teardown.deleteRemoteBranch: "yes"`). Those already fall through to a
+ * documented conservative default, each with a comment saying why, and folding
+ * them in here would change what this line means from "I ignored a key you wrote"
+ * to "I disagreed with a value you wrote".
+ */
+function collectUnknownKeys(parsed, known = DEFAULT_CONFIG, prefix = '') {
+  if (!isObject(parsed)) return []
+  const out = []
+  for (const key of Object.keys(parsed)) {
+    const dotted = prefix ? `${prefix}.${key}` : key
+    if (!Object.prototype.hasOwnProperty.call(known, key)) {
+      out.push(dotted)
+      continue
+    }
+    if (isObject(known[key]) && isObject(parsed[key])) {
+      out.push(...collectUnknownKeys(parsed[key], known[key], dotted))
+    }
+  }
+  return out
+}
+
 // A fresh, deeply-mutable copy of the defaults to merge onto.
 function defaults() {
   return {
@@ -341,11 +495,38 @@ function mergeConfig(base, parsed) {
     if (reader === 'local' || reader === 'remote' || reader === 'detect') {
       base.review.reader = reader
     }
-    assign(base.review, parsed.review, 'servePort', 'number')
-    // Opting OUT is the only thing this key can do — a non-boolean leaves the
-    // default in place rather than being read as a refusal, so a typo cannot
-    // quietly restore the dead `file://` link on a remote reader.
-    assign(base.review, parsed.review, 'serveOnRemote', 'boolean')
+    // Two accepted forms: a finite number pins the port, and the string "auto"
+    // derives it from the repo's path. Anything else is refused BY NAME — the
+    // default stands — exactly as `reader`, `mode` and `deleteRemoteBranch`
+    // refuse a value they do not recognise.
+    //
+    // Falling through costs nothing here, and that is worth stating rather than
+    // assuming: the only value a typo can fall through to is "auto", which is
+    // also the only string that would have been accepted. So a misspelt "auto"
+    // behaves identically to the spelling that was meant, and a misspelt number
+    // was never a number. There is no reading of this key where silence hides a
+    // port the author pinned.
+    if (typeof parsed.review.servePort === 'number' && Number.isFinite(parsed.review.servePort)) {
+      base.review.servePort = parsed.review.servePort
+    } else if (parsed.review.servePort === 'auto') {
+      base.review.servePort = 'auto'
+    }
+    // `always` | `never`; anything else leaves the default standing, so a typo
+    // cannot quietly restore the dead `file://` link this key exists to end.
+    if (parsed.review.serve === 'always' || parsed.review.serve === 'never') {
+      base.review.serve = parsed.review.serve
+    }
+    // TOLERANCE, NOT MIGRATION — the same rule `readVerdict` follows for the
+    // old `approve` spelling. These configs are committed, so a rename with no
+    // tolerance breaks every other checkout on the next pull. Only `false` is
+    // read: `serveOnRemote: true` said "serve where it matters", which is what
+    // `always` now does anyway, so it needs no translation.
+    //
+    // An explicit `serve` wins, so a config carrying both is read the way its
+    // author most recently meant.
+    if (parsed.review.serve === undefined && parsed.review.serveOnRemote === false) {
+      base.review.serve = 'never'
+    }
     // An empty string leaves `/commit` standing, like every other string key
     // here. There is nothing it could mean instead: the hand-off has no off
     // switch, so a blank value is a typo rather than an instruction.
@@ -354,6 +535,10 @@ function mergeConfig(base, parsed) {
     // leaves the gate ON. Turning off a check that refuses must be something
     // someone WROTE, never something a typo achieved on their behalf.
     assign(base.review, parsed.review, 'required', 'boolean')
+    // Same shape as the two above: a non-boolean leaves the default standing, so
+    // a typo cannot quietly widen a bind or permit a publish.
+    assign(base.review, parsed.review, 'allowNetwork', 'boolean')
+    assign(base.review, parsed.review, 'allowRemote', 'boolean')
   }
 
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
@@ -377,10 +562,15 @@ function mergeConfig(base, parsed) {
 
 /**
  * Load and normalise `specs/.core/env.config.json` from `dir` (default cwd).
- * Returns `{ config, present }`:
- *   - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
- *   - present      → `{ config: merged,   present: true }`
+ * Returns `{ config, present, unknown }`:
+ *   - missing file → `{ config: defaults, present: false, unknown: [] }`
+ *     (opt-out; never throws)
+ *   - present      → `{ config: merged,   present: true,  unknown: [...] }`
  * Malformed JSON → throws a clear Error (callers exit non-zero).
+ *
+ * `unknown` lists the dotted paths the merge ignored, for a caller to report.
+ * It is advisory in the strongest sense: nothing here acts on it, and a config
+ * full of strays loads exactly as it always did.
  */
 function loadEnvConfig(dir = process.cwd()) {
   const base = defaults()
@@ -390,7 +580,7 @@ function loadEnvConfig(dir = process.cwd()) {
   try {
     raw = readFileSync(file, 'utf-8')
   } catch (error) {
-    if (error.code === 'ENOENT') return { config: base, present: false }
+    if (error.code === 'ENOENT') return { config: base, present: false, unknown: [] }
     throw error
   }
 
@@ -401,11 +591,18 @@ function loadEnvConfig(dir = process.cwd()) {
     throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
   }
 
-  return { config: mergeConfig(base, parsed), present: true }
+  return { config: mergeConfig(base, parsed), present: true, unknown: collectUnknownKeys(parsed) }
 }
 
 module.exports = {
   loadEnvConfig,
+  resolveServePort,
+  derivedServePort,
+  servePortRoot,
+  servePortReason,
+  PORT_BASE,
+  PORT_SPAN,
+  collectUnknownKeys,
   mergeConfig,
   DEFAULT_CONFIG,
   CONFIG_FILE,

package/src/env/hooks.js

@@ -18,8 +18,21 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const HOOK_SCRIPT = '.claude/hooks/review-gate.js'
+// `.cjs`, and the extension is load-bearing. This file is copied INTO the target
+// project, where that project's `package.json` decides how node parses a `.js` —
+// so the CommonJS script shipped as `review-gate.js` died on its own first
+// `require` in every `"type": "module"` project, printing a stack trace over
+// every Bash tool call. `.cjs` settles the parse mode at the file, independently
+// of the one file skitterspec does not control.
+const HOOK_STEM = '.claude/hooks/review-gate'
+const HOOK_SCRIPT = `${HOOK_STEM}.cjs`
 const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+
+// Our script under ANY extension, so a registration naming the retired `.js` is
+// recognised as ours and migrated rather than duplicated. The trailing lookahead
+// is the boundary: without it `review-gate-extra.js` — somebody else's hook —
+// matches on the stem and gets silently rewritten.
+const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(?![\w.-])/
 // Seconds. The engine call behind this is one git-free read of a small JSON
 // file, so anything approaching this is a wedge rather than slow work — and a
 // hook that times out fails OPEN, which is the answer we want for a wedge.
@@ -55,13 +68,21 @@ function hookEntry() {
  * run it twice and look like a bug in the gate.
  */
 function alreadyRegistered(preToolUse) {
-  if (!Array.isArray(preToolUse)) return false
-  return preToolUse.some(
-    (group) =>
-      isObject(group) &&
-      Array.isArray(group.hooks) &&
-      group.hooks.some((h) => isObject(h) && typeof h.command === 'string' && h.command.includes(HOOK_SCRIPT)),
-  )
+  return registeredHooks(preToolUse).length > 0
+}
+
+// Every hook object under `PreToolUse` whose command names our script, whatever
+// extension it names it under. Pure.
+function registeredHooks(preToolUse) {
+  if (!Array.isArray(preToolUse)) return []
+  const out = []
+  for (const group of preToolUse) {
+    if (!isObject(group) || !Array.isArray(group.hooks)) continue
+    for (const h of group.hooks) {
+      if (isObject(h) && typeof h.command === 'string' && HOOK_SCRIPT_RE.test(h.command)) out.push(h)
+    }
+  }
+  return out
 }
 
 /**
@@ -69,6 +90,7 @@ function alreadyRegistered(preToolUse) {
  * Idempotent and non-destructive. Returns `{ changed, reason }`:
  *   - `created`   — no settings file; one was written
  *   - `added`     — merged into an existing file
+ *   - `migrated`  — registered under a retired path; the path was rewritten
  *   - `present`   — already registered (no write)
  *   - `malformed` — the file exists but is not parseable JSON (left untouched)
  */
@@ -98,7 +120,22 @@ function ensureReviewGateHook(dir) {
 
   const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
   const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
-  if (alreadyRegistered(preToolUse)) return { changed: false, reason: 'present' }
+
+  // Registered already — but possibly under a path that no longer exists, since
+  // the script's extension changed. Rewrite the path IN PLACE rather than
+  // replacing the command: an operator who wrapped our hook, added a flag or
+  // changed the interpreter has registered it their way, and the thing that
+  // moved is the file, not their command. Adding a fresh entry beside theirs
+  // would run the gate twice and read as a bug in the gate; leaving the old one
+  // alone would aim the harness at a file this same upgrade retires.
+  const registered = registeredHooks(preToolUse)
+  if (registered.length) {
+    const stale = registered.filter((h) => !h.command.includes(HOOK_SCRIPT))
+    if (!stale.length) return { changed: false, reason: 'present' }
+    for (const h of stale) h.command = h.command.replace(HOOK_SCRIPT_RE, HOOK_SCRIPT)
+    writeSettings(file, parsed)
+    return { changed: true, reason: 'migrated' }
+  }
 
   writeSettings(file, {
     ...parsed,
@@ -110,8 +147,11 @@ function ensureReviewGateHook(dir) {
 module.exports = {
   ensureReviewGateHook,
   alreadyRegistered,
+  registeredHooks,
   hookEntry,
   settingsPath,
+  HOOK_STEM,
   HOOK_SCRIPT,
+  HOOK_SCRIPT_RE,
   HOOK_COMMAND,
 }

package/src/env/live.js

@@ -85,6 +85,98 @@ function summarizeReceipt(receipt) {
   )
 }
 
+// --- is this spec live? ---------------------------------------------------
+
+/**
+ * Whether a spec is currently live, in a form a page can carry. Pure.
+ *
+ * FOUR STATES, NOT TWO, and the fourth is what keeps this quiet in a healthy
+ * repo. `on` and `off` are the two a reader acts on; `held` is another spec
+ * holding the workbench, which is a refusal with a named way out; and
+ * `unavailable` is **cannot tell** — routed to silence rather than to a warning
+ * (`.claude/rules/negative-checks.md` rule 4). A project with no isolation and a
+ * spec with no worktree both land there, and both are perfectly healthy.
+ *
+ * THE BRANCH IS THE AUTHORITY, NOT THE RECEIPT, exactly as this file's header
+ * says: the receipt is metadata for `live status` and crash recovery. So an
+ * unreadable or absent receipt costs the *holder's name* and nothing else — the
+ * state still comes from which branch the primary checkout is on. Deriving the
+ * state from the receipt instead would report `off` for a checkout plainly
+ * sitting on a feature branch, which is the one answer that would let something
+ * act.
+ *
+ * WHAT WOULD FOOL THIS: `onBase` and `primaryBranch` are read from the primary
+ * checkout by the caller. A caller that passes a *worktree's* git reader would
+ * describe the worktree's HEAD and call it the workbench — so `ctx` is built by
+ * `assertPrimaryOnMain` against the repo root and nowhere else.
+ *
+ * ctx: { isolated, onBase, primaryBranch, receipt, worktreeExists, url }
+ * @returns {{state:'on'|'off'|'held'|'unavailable', holder:string|null, url:string|null, reason:string|null}}
+ */
+function liveStateFor(spec, ctx) {
+  const c = ctx || {}
+  const unavailable = (reason) => ({ state: 'unavailable', holder: null, url: null, reason })
+
+  if (!spec || !spec.branch) return unavailable('no spec to ask about')
+  if (c.isolated === false) return unavailable('isolation is not configured')
+
+  // Not on base — something holds the workbench. Which something is the only
+  // question left, and the branch answers it without the receipt.
+  if (c.onBase === false) {
+    const branch = c.primaryBranch || null
+    if (branch && branch === spec.branch) {
+      return { state: 'on', holder: null, url: c.url || null, reason: null }
+    }
+    const holder = c.receipt && c.receipt.spec ? String(c.receipt.spec) : null
+    const on = branch || '(detached)'
+    return {
+      state: 'held',
+      holder,
+      url: null,
+      // Every way out, because this is the only explanation the reader gets —
+      // the same reasoning `planTake`'s guard 1 records for its own refusal.
+      reason: holder
+        ? `${holder} holds the workbench (branch ${on})`
+        : `the workbench is on ${on} — no receipt; switched by hand?`,
+    }
+  }
+
+  // `onBase` is deliberately three-valued: anything but a definite `true` here
+  // is a checkout we could not read, and that is not evidence the spec is off.
+  if (c.onBase !== true) return unavailable('could not read the primary checkout')
+  if (!c.worktreeExists) return unavailable('no worktree to put live')
+
+  return { state: 'off', holder: null, url: null, reason: null }
+}
+
+/**
+ * The one line the render prints for a live state, or null for `unavailable`.
+ * Pure.
+ *
+ * NULL IS THE POINT. `unavailable` prints nothing at all — not a dash, not an
+ * explanation — because every input that produces it is a healthy repo that
+ * simply has no live surface, and a line about one is an accusation.
+ */
+function liveStateLine(live) {
+  if (!live || live.state === 'unavailable') return null
+  const label = '  live:'.padEnd(11)
+  // IT NAMES THE COMMAND, not the capability. This line read
+  // `off — the page can put it live`, which told the reader a page somewhere
+  // could do it and left them to find the verb — and the verb is the thing they
+  // actually need when they are in a terminal rather than on the page. It is
+  // `/spec-live` rather than `spec-env live take` because that command is what a
+  // person types: it is user-only by its own marking, and the model cannot run
+  // it either way.
+  if (live.state === 'on') {
+    return (
+      `${label}on${live.url ? ` — running at ${live.url}` : ''}` +
+      '; /spec-live main to restore main'
+    )
+  }
+  if (live.state === 'held') return `${label}held — ${live.reason}`
+  return `${label}off — /spec-live to put it live`
+}
+
 // --- stateful detection (glob matching) -----------------------------------
 
 // Translate a restricted glob into an anchored RegExp: `**` matches across path
@@ -378,4 +470,6 @@ module.exports = {
   planTake,
   planRelease,
   planAbort,
+  liveStateFor,
+  liveStateLine,
 }

package/src/env/resolve.js

@@ -167,7 +167,37 @@ function parsePhase(text, name) {
 }
 
 /**
- * The spec's own `## Problem` and `## Impact`, for the page's header.
+ * The tracker ticket a spec is linked to, as `{ id, url }`, or null.
+ *
+ * Read straight out of the overview's frontmatter, where every provider stamps
+ * it. The base is tracker-free, so this knows nothing about Linear beyond the
+ * two key names a provider writes — an unlinked spec, or a project with no
+ * provider installed, simply has neither and gets `null`.
+ *
+ * ONLY http(s) URLS SURVIVE. The value comes out of a file someone edits, and
+ * the page turns it into an `href`; `javascript:` in that position is script
+ * execution on a page served over the network. An id with an unusable url is
+ * still worth having, so the id is kept and the link dropped rather than the
+ * whole ticket.
+ */
+function readTicket(text) {
+  const fm = /^---\n([\s\S]*?)\n---/.exec(text)
+  if (!fm) return null
+  const field = (name) => {
+    const m = new RegExp(`^${name}:\\s*(.*)$`, 'm').exec(fm[1])
+    if (!m) return null
+    const v = m[1].trim().replace(/^["']|["']$/g, '').trim()
+    return v || null
+  }
+  const id = field('linear_identifier')
+  if (!id) return null
+  const url = field('linear_url')
+  return { id, url: url && /^https?:\/\//i.test(url) ? url : null }
+}
+
+/**
+ * The spec's own `## Problem` and `## Impact`, plus its tracker ticket, for the
+ * page's header.
  *
  * WHAT WOULD FOOL THIS: a spec that renames those headings, or a legacy bare
  * `<name>.md` with no overview at all. Both yield `null`, which the caller
@@ -183,10 +213,14 @@ function readOverview(specDir, { overviewFile = '00-overview.md' } = {}) {
   }
   const problem = sectionOf(text, 'Problem') || sectionOf(text, 'Symptom')
   const impact = impactRows(sectionOf(text, 'Impact'))
-  if (!problem && !impact) return null
+  const ticket = readTicket(text)
+  // The ticket counts towards "is there anything to say": a spec linked to a
+  // tracker but carrying neither section still has a header worth drawing.
+  if (!problem && !impact && !ticket) return null
   return {
     ...(problem ? { problem } : {}),
     ...(impact ? { impact } : {}),
+    ...(ticket ? { ticket } : {}),
   }
 }