@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/src/env/review.js

@@ -44,6 +44,24 @@ function isNoise(relPath) {
   return relPath.startsWith('specs/') || relPath.startsWith('.spec-env/')
 }
 
+/**
+ * Is this path one of `folder`'s own spec documents, in any bucket?
+ *
+ * Every bucket, for the same reason `classifyDirtyTree` checks every bucket: a
+ * tree mid-`git mv` is dirty in two of them at once and both halves are the
+ * same spec's.
+ *
+ * It exists because `isNoise` above is exactly wrong for the `docs` mode. That
+ * rule — everything under `specs/` is bookkeeping — is right for a phase's code
+ * diff, where the spec's own checkbox edits are not what anyone came to read.
+ * On a page whose SUBJECT is the spec, applying it folds away every file and
+ * renders a page with nothing open on it.
+ */
+function isSpecDocOf(relPath, folder) {
+  const parts = String(relPath).split('/')
+  return parts.length > 3 && parts[0] === 'specs' && parts[2] === folder
+}
+
 /**
  * A git runner bound to one checkout, returning stdout **untrimmed**.
  *
@@ -174,12 +192,21 @@ function numstatFor(git, ref, file, untracked) {
  * `remote` — somewhere else, so it does not.
  * `unknown` — CANNOT TELL, and that is a real answer rather than a soft `local`.
  *
- * **This decides wording and nothing else.** Nothing in the engine serves,
- * publishes or refuses on the strength of it, because being wrong has to stay
- * cheap in both directions: a wrong `local` prints a dead link (the bug this
- * exists to fix), and a wrong `remote` acted upon would publish something the
- * tooling cannot remove, unprompted. `unknown` is therefore wired to exactly the
- * behaviour that existed before any of this.
+ * **This decides two things: the WORDING, and WHAT THE SERVER BINDS TO.** It
+ * does not decide *whether* to serve — `review.serve` does — and it never
+ * decides to publish. Being wrong therefore stays cheap in both directions: a
+ * wrong `local` binds loopback, which is reachable from the machine holding the
+ * page and says so; a wrong `remote` binds every interface, which is the
+ * existing behaviour and is announced on the render.
+ *
+ * IT DID DECIDE WHETHER TO SERVE, ONCE, and this comment claimed otherwise
+ * throughout — the sentence above used to read "nothing in the engine serves on
+ * the strength of it" while `cli.js` served only for a `remote` reader. The bill
+ * was a `file://` link on a local machine, and a `file://` page has no server to
+ * POST to, so the verdict buttons on it had nowhere to go: the loop the page
+ * exists to close was absent from the sessions easiest to use. If you are here
+ * wondering whether to make detection load-bearing again, that is what it cost
+ * the last time, and `env-serve-start-proof` now fails if you do.
  *
  * `env` is passed in, never read from `process` here, so a test states the world
  * it is testing instead of inheriting the machine the suite happens to run on.
@@ -234,17 +261,44 @@ function resolveReader(config, env = {}) {
  * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
  * caller's declaration about the work, not a reading of the gate.
  */
-function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null }) {
+function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null }) {
+  // WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
+  // reads the spec's worktree, and for those the two are the same path — so
+  // `treePath` left null keeps the existing behaviour exactly. The `docs` mode
+  // has no worktree to read, which is the whole reason it exists.
+  const root = treePath || spec.worktreePath
+
+  // AN EXPLICIT FILE SET, or every changed file. `only` is a whitelist of
+  // repo-relative paths, and it exists because the `docs` mode reads a tree
+  // several sessions write into: rendering everything uncommitted there would
+  // put another spec's documents on this page and then commit them under this
+  // page's verdict. Null — every other caller — filters nothing.
+  const wanted = only ? new Set(only) : null
+  const keep = (f) => !wanted || wanted.has(f.path)
+
+  // WHAT COUNTS AS BOOKKEEPING, and it inverts for the `docs` mode. Everywhere
+  // else the spec's own documents are the bookkeeping beside the code; on a
+  // docs page they are the code, and the companions the project declared (a
+  // tracker snapshot, say) are what belongs folded away.
+  const noiseOf = (p) => (mode === 'docs' ? !isSpecDocOf(p, spec.folder) : isNoise(p))
+
+  // THE SURFACES BLOCK, built here so the page never has to know which tiers
+  // exist or which of them can be turned on. `null` when the caller passed
+  // neither a live state nor a stack — an absent key, not an empty one.
+  const surfaces = surfacesFor({ live, tiers, buttons })
+
   const files = []
   for (const f of trackedFiles(git, ref)) {
+    if (!keep(f)) continue
     const { patch, whole } = patchFor(git, ref, f, false)
     const { additions, deletions, binary } = numstatFor(git, ref, f, false)
-    files.push({ ...f, additions, deletions, binary, whole, noise: isNoise(f.path), patch })
+    files.push({ ...f, additions, deletions, binary, whole, noise: noiseOf(f.path), patch })
   }
   for (const f of untrackedFiles(git)) {
+    if (!keep(f)) continue
     const { patch, whole } = patchFor(git, ref, f, true)
     const { additions, deletions, binary } = numstatFor(git, ref, f, true)
-    files.push({ ...f, additions, deletions, binary, whole, noise: isNoise(f.path), patch })
+    files.push({ ...f, additions, deletions, binary, whole, noise: noiseOf(f.path), patch })
   }
 
   // Content hashes and the stored review state, folded on before the totals so
@@ -261,7 +315,7 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
   // Every bucket, because a page is rendered for specs in `in-progress/` and for
   // finished ones in `complete/` — and the finished one is the case this exists
   // for. `null` when it cannot tell, and the page leaves its button alone.
-  const specDir = spec.worktreePath ? findSpecDirIn(spec.worktreePath, spec.folder) : null
+  const specDir = root ? findSpecDirIn(root, spec.folder) : null
   const phases = specDir ? readPhases(specDir) : null
   // The PR description this page never had: why the change exists, what it
   // touches, and what this phase set out to do.
@@ -280,7 +334,11 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
     spec: spec.folder,
     title: spec.folder,
     branch: spec.branch,
-    worktree: spec.worktreePath,
+    // The tree the diff was read from. Identical to the worktree for every
+    // mode but `docs`, where there is no worktree and this is the checkout the
+    // documents actually live in — saying `worktree` there would name a path
+    // that does not exist.
+    worktree: root,
     mode,
     base,
     ref,
@@ -304,6 +362,27 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
     // Same rule again: a gate that was never armed and never skipped adds no
     // key at all.
     ...(gateForPage(gate) ? { gate: gateForPage(gate) } : {}),
+    // THE PATHS A COMMITTING VERDICT HERE MUST COMMIT, carried on the payload
+    // so the skill that routes on the verdict never recomputes them. It matters
+    // that they travel with the page rather than being asked for again: a
+    // checkout is shared, so the set of this spec's uncommitted documents can
+    // differ between the render and the verdict — and the reader's conclusion is
+    // about what the page showed them.
+    //
+    // Absent for every other mode, which is what keeps their payloads identical.
+    ...(only ? { docs: { paths: only } } : {}),
+    // WHERE ELSE THIS REVIEW CAN BE REACHED, and whether it is also running.
+    //
+    // The page had no idea the other tiers existed — it is opened AT one URL
+    // and knows nothing about the rest — so an enable press needs somewhere to
+    // live, and that is this block. It carries only what the reader can act on:
+    // the live state, each tier that is OFF with the action that turns it on,
+    // and the `network` URL when it is on, which is the one address a reader
+    // wants that is not the one they are standing on.
+    //
+    // ABSENT STAYS ABSENT, exactly as `phases` and `gate` do: a caller that
+    // passes neither renders the payload it rendered before this existed.
+    ...(surfaces ? { surfaces } : {}),
     // THE DEFAULT ADDS NO KEY, so a caller that did not ask for a button set —
     // and a caller that asked for the default by name — renders the payload it
     // rendered before this existed. Opting in is the only thing that shows.
@@ -401,12 +480,28 @@ const NOTES_VERSION = 1
  * THE VERDICT NAMES THE ACTION. It was `approve` once, and an approval that
  * only recorded itself is the one thing on a review page that does not describe
  * what happens — a review is the guard in front of an action, so the word is
- * the action: `commit`, `commit-continue`, `changes`, `discuss`.
+ * the action: `commit`, `commit-continue`, `commit-start`, `changes`,
+ * `discuss`.
+ *
+ * `commit-start` is the authoring verdict: commit the spec that was just
+ * written, then put it in flight. It is its own word rather than a
+ * context-dependent reading of `commit-continue` for exactly the reason above —
+ * a verdict that means `/spec-start` on one page and `/spec-next` on another
+ * names neither, and the outcome log would record the same word for two
+ * different actions with no way to tell them apart afterwards.
  *
  * `discuss` is the default because it is the behaviour that existed before any
  * verdict did. So a blob from an older page, or one a reader sent without
  * choosing, keeps doing exactly what it always did.
  *
+ * `commit-land` is the `/no-spec` verdict: commit this work, fast-forward the
+ * base branch to it, and tear the worktree down. It is its own word for exactly
+ * the reason `commit-start` is — reusing plain `commit` would make one verdict
+ * mean "commit and stop" on a phase page and "commit, land and destroy the
+ * worktree" on a `/no-spec` page, which is the context-dependent reading this
+ * vocabulary exists to prevent. The outcome log would then record the same word
+ * for two very differently destructive actions.
+ *
  * `continue` is the mid-run verdict: *I have read it, carry on*. It names an
  * action, which is what separates it from the `none` verdict that was removed —
  * `none` recorded itself and did nothing, while this one resumes the run. What
@@ -414,9 +509,222 @@ const NOTES_VERSION = 1
  * below and is therefore structurally incapable of clearing an armed gate: a
  * phase that ended still owes a committing verdict or a recorded skip.
  */
-const VERDICTS = ['commit', 'commit-continue', 'continue', 'changes', 'discuss']
+const VERDICTS = [
+  'commit',
+  'commit-continue',
+  'commit-start',
+  'commit-land',
+  'continue',
+  'changes',
+  'discuss',
+]
 const DEFAULT_VERDICT = 'discuss'
 
+/**
+ * Actions the page can send INSTEAD of a verdict.
+ *
+ * AN ACTION IS NOT A VERDICT, and keeping the two vocabularies apart is the
+ * whole point rather than tidiness. A verdict is a conclusion about the work,
+ * consumed once by the thing it asked for. An action changes what is *running*
+ * — or which tiers are permitted — and then puts the reader back on the same
+ * page with the same options, so a run answering one has concluded nothing.
+ *
+ * THERE IS NO `live-off`, and its absence is the decision. Putting *this* change
+ * live is about the diff on screen; handing the whole instance back to `main` is
+ * a workspace decision with nothing to do with this review, and a control for it
+ * on a review page invites the reader to make it while thinking about something
+ * else. The `live:` line names `/spec-live main` instead, which is what a person
+ * types.
+ *
+ * Three consequences follow from that, and all three are structural rather than
+ * remembered:
+ *
+ * - It is absent from `VERDICTS`, so nothing that routes on a verdict can see
+ *   it.
+ * - It is absent from `COMMITTING`, so it is **incapable** of clearing an armed
+ *   gate: a phase that ended still owes a verdict after the reader has looked
+ *   at it running. The commit that a `live-on` performs first is the mechanical
+ *   precondition for `live take` (which refuses a dirty worktree), not the
+ *   reader's answer.
+ * - A blob may carry a verdict or an action, never both. Two answers in one
+ *   pass would need a rule about which wins, and any such rule would sometimes
+ *   act on the half the reader did not mean.
+ *
+ * `allow-network`/`allow-remote` turn a review TIER on, and they exist here
+ * because the page can now act — which is the premise
+ * `feat-three-review-links` decision 5 rejected a page toggle on, having
+ * recorded it as open to reopening. Two things replace the limit it rested on.
+ * **Only a reader who can already reach the page can press one**, so widening
+ * loopback→network can only be pressed from the machine itself, where the
+ * command was available anyway, and the serve token still decides who reaches
+ * the page at all. And `allow-remote` **permits publishing without
+ * publishing** — the permanent claude.ai page still takes an explicit ask.
+ *
+ * There is no disable direction, and `tierAction` is where that is enforced:
+ * turning `network` off from a page reached over the network kills the page
+ * doing the turning.
+ */
+const ACTIONS = ['live-on', 'allow-network', 'allow-remote']
+
+/**
+ * The action a tier that is OFF offers, or null.
+ *
+ * ENABLE-ONLY, and that is a decision rather than an omission: turning
+ * `network` off from a page you reached over the network kills the page doing
+ * the turning, and the reader gains nothing they could not get by typing the
+ * command. `local` has no setting at all — it is the machine the page is on.
+ */
+function tierAction(tier) {
+  if (!tier || !tier.off) return null
+  if (tier.tier === 'network') return 'allow-network'
+  if (tier.tier === 'remote') return 'allow-remote'
+  return null
+}
+
+/**
+ * What the page shows above the verdicts: where this review can be reached, and
+ * whether it is also running. Pure.
+ *
+ * ONLY WHAT THE READER CAN ACT ON. An `on` tier the reader is already standing
+ * on is not information — they are reading it — so the only tier URL carried is
+ * `network`'s, which is the one address someone on a laptop wants for their
+ * phone. Everything else here is a state plus the one press that changes it.
+ *
+ * `null` RATHER THAN AN EMPTY BLOCK when there is nothing to say: an
+ * `unavailable` live state and no stack means a caller that never asked, and
+ * the payload must then be byte-identical to what it was before this key
+ * existed.
+ */
+function surfacesFor({ live, tiers, buttons = null }) {
+  // A MID-PHASE PAGE CANNOT PUT ANYTHING LIVE, so it is not offered the press.
+  //
+  // `live take` refuses a dirty worktree, so the action commits the phase
+  // first — and `/spec-diff` §2b is explicit that half a phase is not
+  // committed to look at it running: that splits one phase across two commits
+  // and leaves a mess nobody asked for. So mid-run the press could only ever be
+  // declined, and a control that always refuses teaches the reader that the
+  // buttons on this page are decorative — the same failure
+  // `.claude/rules/spec-reports.md` records for the offer nothing was watching.
+  //
+  // The row stays, with the command in place of the button: the reader still
+  // learns the surface exists and what to type, which is exactly the trade the
+  // strip already makes on a `file://` page.
+  //
+  // ONLY `live-on`. `allow-network` and `allow-remote` write a config file
+  // and commit nothing, so they are as valid mid-phase as at the end of one.
+  const canCommit = buttons !== 'midrun'
+  const rows = []
+
+  // `unavailable` contributes nothing — the cannot-tell state, routed to
+  // silence exactly as `liveStateLine` routes it (`env/live.js`).
+  if (live && live.state && live.state !== 'unavailable') {
+    rows.push({
+      kind: 'live',
+      state: live.state,
+      url: live.url || null,
+      reason: live.reason || null,
+      // ONE DIRECTION ONLY. `off` offers the press; `on` and `held` offer none —
+      // `on` because handing the instance back to `main` is not this review's
+      // business, and `held` because the way out is another spec's to take and a
+      // button here would either park someone else's work or do nothing.
+      action: live.state === 'off' && canCommit ? 'live-on' : null,
+      // The command for the direction the page does not offer, so the reader is
+      // never left knowing what they want and not what to type. Mid-run that is
+      // `/spec-live` itself, since the press is withheld above.
+      command:
+        live.state === 'on' ? '/spec-live main' : live.state === 'off' && !canCommit ? '/spec-live' : null,
+    })
+  }
+
+  for (const t of tiers || []) {
+    const action = tierAction(t)
+    // ONLY WHAT THE READER CAN ACT ON. An `on` tier contributes nothing: the
+    // reader is standing on one of them, and the terminal render is where they
+    // got the link — printing it again here would be two places naming one page,
+    // which is the split `.claude/rules/spec-reports.md` records as a failure.
+    if (!action) continue
+    rows.push({
+      kind: 'tier',
+      tier: t.tier,
+      state: 'off',
+      url: null,
+      // SAID BEFORE THE PRESS, not after it. Unlike the live action, which
+      // touches no tracked file, `allow` edits `specs/.core/env.config.json` in
+      // the primary checkout — changing behaviour for everyone who pulls and
+      // leaving that tree dirty. A setting change of that reach must not land
+      // because someone tapped a button labelled only `Allow remote`.
+      note: t.note || 'writes env.config.json — committed, and shared',
+      // The same thing from a terminal, for the reader who is nowhere near the
+      // page. Only `remote` has a command of its own: `network` is ON by
+      // default, so turning it off is a rare deliberate act and a slash command
+      // per tier is clutter for the one nobody touches.
+      command: t.tier === 'remote' ? '/spec-remote-review' : null,
+      action,
+    })
+  }
+
+  return rows.length ? rows : null
+}
+
+/**
+ * The three review tiers, in a FIXED ORDER, each either a URL or the reason it
+ * is not one. Pure: it takes what the caller already resolved.
+ *
+ * Fixed order matters more than it looks. A reader who has learnt which line
+ * their phone opens should not have to re-read the labels every render, and a
+ * stack that reordered itself by availability would make them.
+ *
+ * WHY A STACK AT ALL, when the rule said exactly one link: the engine cannot
+ * know where the reader is sitting, and every attempt to guess failed the
+ * moment they moved. `local` and `network` are two doors into ONE room — the
+ * page POSTs to `location.pathname`, so both reach the same server and the same
+ * pending store, and one wait covers both. `remote` is a second store, which is
+ * why it carries the line saying so.
+ */
+function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
+  const tiers = []
+  const loopbackUrl = served && served.loopbackUrl ? served.loopbackUrl : null
+
+  tiers.push(
+    loopbackUrl
+      ? { tier: 'local', url: loopbackUrl }
+      : { tier: 'local', url: fileUrl, note: 'a file:// page cannot send a verdict' },
+  )
+
+  if (!config.review.allowNetwork) {
+    tiers.push({ tier: 'network', off: true, enable: 'skitterspec spec-env review allow network' })
+  } else if (served && !served.loopback && served.url) {
+    tiers.push({ tier: 'network', url: served.url, alternates: served.alternates || [] })
+  } else {
+    // Permitted, but there is no address to offer — a machine with no network,
+    // or a server that could not take one. Not a problem to report as an error.
+    tiers.push({ tier: 'network', unavailable: true, note: 'no network address on this machine' })
+  }
+
+  if (!config.review.allowRemote) {
+    // THE COMMAND A PERSON TYPES. `/spec-remote-review` toggles, so the same
+    // line works whichever way the tier currently is — and nobody has to
+    // reconstruct `spec-env review allow remote` from a render they are reading
+    // on a phone.
+    tiers.push({ tier: 'remote', off: true, enable: '/spec-remote-review' })
+  } else if (publishedUrl) {
+    tiers.push({ tier: 'remote', url: publishedUrl, note: 'a verdict here needs /spec-reviewed' })
+  } else {
+    tiers.push({ tier: 'remote', unavailable: true, note: 'publishing is an ask — nothing published yet' })
+  }
+
+  return tiers
+}
+
+// One tier as a line, padded so the labels form a column the eye can run down.
+function reviewTierLine(t) {
+  const label = `  ${t.tier}:`.padEnd(11)
+  if (t.url) return `${label}${t.url}${t.note ? `   (${t.note})` : ''}`
+  if (t.off) return `${label}off — turn on with: ${t.enable}`
+  return `${label}—   (${t.note})`
+}
+
+
 // The verdicts that COMMIT, and are therefore blocked by an open comment. One
 // list, so a fifth verdict cannot become a way around the single refusal this
 // engine makes — adding a committing verdict means adding it here, and the
@@ -427,7 +735,7 @@ const DEFAULT_VERDICT = 'discuss'
 // obligation that outlives the turn. A mid-run reader saying "carry on" has
 // answered the offer in front of them and nothing else, so the gate a finished
 // phase armed must survive it untouched.
-const COMMITTING = ['commit', 'commit-continue']
+const COMMITTING = ['commit', 'commit-continue', 'commit-start', 'commit-land']
 
 /**
  * Which set of buttons a rendered page shows.
@@ -442,8 +750,32 @@ const COMMITTING = ['commit', 'commit-continue']
  * `committing` is the default, so a caller that says nothing keeps today's page
  * exactly — the key is left off the payload entirely rather than written out as
  * the default, so an unchanged caller renders an unchanged page.
+ *
+ * `authoring` is the set for a spec that has just been written: its committing
+ * pair is `commit-start` and `commit` — put it in flight now, or keep it for
+ * later. `commit-continue` is absent because there is no phase in flight to
+ * continue, and `continue` is absent because the run has nothing left to resume.
+ *
+ * `refresh` is the set for a spec that was re-validated rather than written:
+ * `commit`, `changes`, `discuss`, and NO start verdict. A refreshed spec may
+ * already be in progress, so offering to put it in flight would be wrong for
+ * half this set's inputs — and wrong in the expensive direction, since it would
+ * offer to provision a worktree for a spec that already has one.
+ *
+ * `nospec` is the set for work with no spec document: its committing pair is
+ * `commit-land` and `commit` — finish it now, or commit and leave the branch
+ * standing. `commit-continue` is absent because there is no next phase, and
+ * `commit-start` because there is nothing to put in flight.
+ *
+ * REUSING `refresh` HERE WAS THE OBVIOUS MOVE AND IT IS WRONG. The three
+ * remaining buttons are identical, so the temptation is to let `/no-spec` take
+ * that set and treat plain `commit` as "commit, land, tear down". That makes one
+ * verdict word mean two different things depending on which skill rendered the
+ * page — precisely what having separate words for `commit-start` and
+ * `commit-continue` exists to avoid, and worse here, because one of the two
+ * readings destroys a worktree.
  */
-const BUTTON_SETS = ['committing', 'midrun']
+const BUTTON_SETS = ['committing', 'midrun', 'authoring', 'refresh', 'nospec']
 const DEFAULT_BUTTON_SET = 'committing'
 
 /**
@@ -584,9 +916,13 @@ function writeNotes(outPath, notes) {
 
 const PENDING_VERSION = 1
 
-// Beside the page and the notes sidecar, under gitignored `.spec-env/`.
+// Beside the page and the notes sidecar, under gitignored `.spec-env/`. The
+// suffix is named once so the cross-spec scan recognises a store by the same
+// spelling that writes one.
+const PENDING_SUFFIX = '.pending.json'
+
 function reviewPendingPath(outPath) {
-  return outPath.replace(/\.html$/, '') + '.pending.json'
+  return outPath.replace(/\.html$/, '') + PENDING_SUFFIX
 }
 
 function emptyPending(specFolder) {
@@ -674,6 +1010,59 @@ function addPending(pending, { blob, at, render }, mint = mintPendingCode) {
   return { pending: next, code }
 }
 
+/**
+ * What became of ONE pass, by its code. Reads; writes nothing, refuses nothing.
+ *
+ * The served page POSTs, is handed six digits, and then has to end on one of
+ * two sentences — Claude picked this up, or here is the command that picks it
+ * up. It cannot know which at send time, so it asks, and this answers.
+ *
+ * Three states, and the third is the point:
+ *
+ * - `waiting` — the code IS in the holding area. Nobody has claimed it.
+ * - `claimed` — the decision log NAMES the code. Somebody did.
+ * - `unknown` — neither could be established.
+ *
+ * BOTH ANSWERS REST ON SOMETHING PRESENT, which is what stops this being the
+ * fourth row in the table at the top of `.claude/rules/negative-checks.md`. The
+ * tempting cheap version reads `claimed` off the code being ABSENT from the
+ * holding area — and absence there has four causes, of which exactly one is a
+ * claim: `--drop` removes a pass and writes no decision, a store written under
+ * a different `--out` is a store this never opens, and a mistyped folder finds
+ * an empty one. Three of those four would report a pass as picked up while it
+ * sits in a file nobody is reading, which is this spec's own bug told back to
+ * the reader with confidence.
+ *
+ * So `unknown` answers everything that is not a positive signal, and the caller
+ * turns it back into the command. That direction is deliberate: a command
+ * nobody needed to run costs a glance, and a pass nobody claims costs the
+ * review.
+ *
+ * A code that is not six digits never reaches disk. It cannot be one this
+ * engine minted, so there is nothing to look up, and answering it from the
+ * filesystem would make a reachable endpoint into a path-shaped probe.
+ */
+function passState(outPath, specFolder, code) {
+  const wanted = typeof code === 'string' ? code.trim() : ''
+  if (!new RegExp(`^\\d{${PENDING_CODE_LENGTH}}$`).test(wanted)) return { state: 'unknown' }
+
+  const held = readPending(outPath, specFolder)
+  // A store we could not parse is not an empty one. It holds somebody's passes
+  // and we simply cannot see them, so neither answer is available.
+  if (held.corrupt) return { state: 'unknown' }
+  if ((held.pending.passes || []).some((p) => p && p.code === wanted)) return { state: 'waiting' }
+
+  const stored = readNotes(outPath, specFolder)
+  if (stored.corrupt) return { state: 'unknown' }
+  const decisions = Array.isArray(stored.notes.decisions) ? stored.notes.decisions : []
+  if (decisions.some((d) => d && d.code === wanted)) return { state: 'claimed' }
+
+  // Gone from the holding area and unnamed in the log. It may have been
+  // dropped, it may predate this field, the store may not be the one the page
+  // was served from. Say so.
+  return { state: 'unknown' }
+}
+
 /**
  * What is waiting, as the render should describe it. Pure.
  *
@@ -695,6 +1084,11 @@ function describePending(pending) {
       // `approve`, and the operator must be offered the word that describes
       // what claiming it would do.
       verdict: readVerdict((p.blob && p.blob.verdict) || null) || null,
+      // AN ACTION IS REPORTED AS AN ACTION. A pass carrying one has no verdict,
+      // and listing it as `no verdict` would describe the instruction it does
+      // carry as an absence — which is the reading that makes a reader claim it
+      // expecting a conclusion.
+      action: (p.blob && p.blob.action) || null,
       at: p.at || null,
     }))
     .sort((a, b) => String(a.at).localeCompare(String(b.at)) || a.code.localeCompare(b.code))
@@ -782,6 +1176,185 @@ function passesSince(pending, since) {
   return { codes, usable: true }
 }
 
+/* ==========================================================================
+ * The wait — one implementation, because improvised ones cannot be tested
+ *
+ * The skills used to say "watch the pending store and end your turn" and stop
+ * there, so every run wrote its own watcher in shell. Three failed in two days,
+ * each reaching the operator as "I pressed the button and nothing happened" —
+ * and the worst of them was `until [ -f "$P" ] && [ "$x" \\> "$y" ]`, valid bash
+ * and a syntax error in zsh, which spun for five minutes writing to a stderr
+ * nobody reads.
+ *
+ * What made that expensive was not the typo. It is that SILENCE WAS THE SUCCESS
+ * SIGNAL: from outside, a watcher that can never fire and one patiently working
+ * look exactly alike. So the comparison lives here, in one place, where a test
+ * can hand it a store that gains a pass mid-flight and watch it return.
+ * ========================================================================== */
+
+const WAIT_POLL_MS = 400
+
+// How often a running wait says it is still running. Five minutes, against a
+// 400ms poll: this is not part of the poll at all, it is proof of life for
+// whatever is supervising the process.
+const WAIT_HEARTBEAT_MS = 5 * 60 * 1000
+
+/**
+ * Block until exactly one pass arrives inside a window. Impure only in that it
+ * reads the store and sleeps; it writes nothing and claims nothing.
+ *
+ * Four outcomes, and they are distinct because the caller acts differently on
+ * each:
+ *
+ * - `{ state: 'arrived', code }` — one pass, inside the window. Claim it.
+ * - `{ state: 'ambiguous', count }` — more than one. NAMES NO CODE, because
+ *   choosing between two is exactly the guess `claimPending` refuses to make.
+ * - `{ state: 'timeout' }` — only when a timeout was asked for.
+ * - `{ state: 'unusable' }` — the window could not be parsed, so there is
+ *   nothing to wait inside. Returns AT ONCE rather than blocking forever on a
+ *   comparison that can never be satisfied — which is the failure this whole
+ *   function exists to stop.
+ *
+ * NO TIMEOUT UNLESS ASKED. `timeoutMs` omitted means wait as long as the
+ * process lives, and that is the default the skills use: any fixed number is a
+ * guess about how long someone reads, and a reader who walks away from a diff
+ * is the normal case rather than the edge one. An hour was picked once and a
+ * lunch break beat it.
+ *
+ * IT SAYS IT IS STILL RUNNING, on `onHeartbeat`. A backgrounded wait produced
+ * no output between starting and finding a pass, and over a long idle it was
+ * killed — three sessions lost their wait over one lunch break. Whether the
+ * trigger is process silence or session idleness was never established, so the
+ * cheap half is done here: the process stops being silent. The other half is
+ * the caller re-arming, which covers it either way.
+ *
+ * The cadence is INDEPENDENT of the poll. Polling stays at 400ms because that
+ * is how fast a press should be noticed; the heartbeat is minutes apart because
+ * it is addressed to a supervisor, not to a reader.
+ *
+ * WHAT WOULD FOOL A LOOSER VERSION: treating an absent, empty, or older-only
+ * store as a reason to return. None of those is a pass — they are the ordinary
+ * state of a review nobody has answered yet — and a wait that ended on one
+ * would report "no pass" as an outcome (`.claude/rules/negative-checks.md`
+ * rule 3 has a test for each).
+ */
+async function waitForPass(
+  readStore,
+  since,
+  {
+    timeoutMs = null,
+    pollMs = WAIT_POLL_MS,
+    sleep,
+    onHeartbeat = null,
+    heartbeatMs = WAIT_HEARTBEAT_MS,
+    now = () => Date.now(),
+  } = {},
+) {
+  if (!Number.isFinite(Date.parse(since))) return { state: 'unusable' }
+  const nap = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const startedAt = now()
+  const deadline = Number.isFinite(timeoutMs) && timeoutMs !== null ? startedAt + timeoutMs : null
+  // Counted from the start rather than scheduled, so a slow poll cannot make
+  // the heartbeat drift and a fast one cannot make it fire twice.
+  let beats = 0
+
+  for (;;) {
+    // A store that will not parse is not an empty one, and it is not a pass
+    // either — keep waiting rather than reading someone's unreadable passes as
+    // an answer. `readPending` already reports `corrupt` rather than throwing.
+    const read = readStore()
+    if (read && !read.corrupt) {
+      const window = passesSince(read.pending, since)
+      if (window.usable) {
+        if (window.codes.length === 1) return { state: 'arrived', code: window.codes[0] }
+        if (window.codes.length > 1) return { state: 'ambiguous', count: window.codes.length }
+      }
+    }
+    if (deadline !== null && now() >= deadline) return { state: 'timeout' }
+
+    // SAID ON THE WAY ROUND, never on the way out. A line printed when the wait
+    // ends would only ever appear for the waits that already worked, which is
+    // the half that never needed proof.
+    if (onHeartbeat && heartbeatMs > 0) {
+      const elapsed = now() - startedAt
+      const due = Math.floor(elapsed / heartbeatMs)
+      if (due > beats) {
+        beats = due
+        onHeartbeat({ elapsedMs: elapsed, since })
+      }
+    }
+
+    // Never overshoot the deadline by a whole poll interval.
+    await nap(deadline === null ? pollMs : Math.max(0, Math.min(pollMs, deadline - now())))
+  }
+}
+
+/**
+ * Every waiting pass, across every spec. Reads; writes, claims and refuses
+ * nothing.
+ *
+ * A wait that never fired, a session cleared, a terminal closed overnight —
+ * none of those is recoverable by any watcher, however good. This is what finds
+ * the pass afterwards, so recovery stops depending on the operator happening to
+ * suspect something.
+ *
+ * IT READS THE SIDECAR DIRECTORY, NEVER THE PROVISIONED LIST, and that is the
+ * load-bearing decision rather than an implementation detail. `specEnvStatus`
+ * walks specs that have a **worktree**; the ten passes that motivated this all
+ * belonged to specs that had been completed and torn down. Scoping the scan to
+ * provisioned specs would therefore make it blind to precisely the case that
+ * produced it. A `<spec>.pending.json` is here because a pass was received —
+ * a positive signal (`.claude/rules/negative-checks.md` rule 1), and one that
+ * outlives the spec's worktree, its branch and its folder.
+ *
+ * WHAT WOULD FOOL THIS: a store that will not parse. It holds someone's passes
+ * and reading it as empty would report "nothing waiting", which is the one
+ * answer that is certainly wrong — so it comes back named in `unreadable`
+ * rather than counted as zero (rule 4).
+ *
+ * Oldest first and stable, ties broken on the code, exactly as
+ * `describePending` orders one spec's own.
+ */
+function waitingPasses(reviewsDirPath) {
+  let entries
+  try {
+    entries = fs.readdirSync(reviewsDirPath)
+  } catch {
+    // No directory means no review has ever been rendered here. That is the
+    // ordinary state of a fresh repo, not a failure to report.
+    return { passes: [], unreadable: [] }
+  }
+
+  const passes = []
+  const unreadable = []
+  for (const name of entries.sort()) {
+    if (!name.endsWith(PENDING_SUFFIX)) continue
+    const folder = name.slice(0, -PENDING_SUFFIX.length)
+    // The engine's own reader, so "corrupt" means here what it means everywhere.
+    const read = readPending(path.join(reviewsDirPath, `${folder}.html`), folder)
+    if (read.corrupt) {
+      unreadable.push(folder)
+      continue
+    }
+    for (const pass of read.pending.passes || []) {
+      if (pass && pass.code) {
+        passes.push({
+          spec: folder,
+          code: pass.code,
+          verdict: readVerdict(pass.blob && pass.blob.verdict),
+          action: (pass.blob && pass.blob.action) || null,
+          at: pass.at || null,
+        })
+      }
+    }
+  }
+  passes.sort((a, b) => {
+    const at = String(a.at || '').localeCompare(String(b.at || ''))
+    return at !== 0 ? at : a.code.localeCompare(b.code)
+  })
+  return { passes, unreadable }
+}
+
 /* ==========================================================================
  * The gate — a standing obligation to review, not a message in flight
  *
@@ -799,6 +1372,39 @@ function passesSince(pending, since) {
 
 const GATE_VERSION = 1
 
+/**
+ * The reason a BYPASS records, and it is deliberately a fixed string.
+ *
+ * A skip normally carries what the operator typed. This one is chosen from a
+ * picker with nothing typed, so the record has to say that for itself — and a
+ * string nobody would write by hand is what keeps a tapped bypass tellable from
+ * a considered one when both appear in the same log.
+ *
+ * It stays `by: 'skip'` rather than minting a third `DISARMED_BY` verb: the
+ * sidecar's vocabulary is versioned, and a distinct reason already buys the only
+ * thing a third verb would have.
+ */
+const GATE_BYPASS_REASON = 'none: chose to commit without reading the diff'
+
+/**
+ * The way out of an armed gate, declared beside the refusal rather than left
+ * for a caller to reconstruct.
+ *
+ * A BYPASS, NOT A SATISFY: the phase still owes a verdict and nobody has read
+ * it, so this steps past a guard that is still unsatisfied — which is exactly
+ * why it is recorded and a `satisfy` is not.
+ *
+ * WHAT THIS IS NOT: a `--force`. One was asked for and rejected, because a
+ * reasonless lift is indistinguishable from nobody having looked. The exits
+ * this gate has are unchanged — a committing verdict, or a recorded skip — and
+ * this is the second of those two at an address a person will actually reach.
+ */
+const GATE_BYPASS_OFFER = Object.freeze({
+  kind: 'bypass',
+  label: 'Commit without reading the diff — recorded as such',
+  command: `skitterspec spec-env review skip "${GATE_BYPASS_REASON}"`,
+})
+
 // How a disarm happened. `verdict` is a review that reached a committing
 // conclusion; `skip` is the operator saying, on the record, that they are
 // moving on without one.
@@ -809,7 +1415,7 @@ function reviewGatePath(outPath) {
 }
 
 function emptyGate(specFolder) {
-  return { version: GATE_VERSION, spec: specFolder, armed: false, armedAt: null, phase: null, log: [] }
+  return { version: GATE_VERSION, spec: specFolder, armed: false, armedAt: null, phase: null, offeredAt: null, log: [] }
 }
 
 /**
@@ -837,6 +1443,10 @@ function readGate(outPath, specFolder) {
         armed: parsed.armed === true,
         armedAt: parsed.armedAt || null,
         phase: parsed.phase === undefined ? null : parsed.phase,
+        // A sidecar written before this field existed reads as never-offered,
+        // which is the correct and harmless default. These files are gitignored,
+        // so there is no fleet to migrate and `GATE_VERSION` does not move.
+        offeredAt: parsed.offeredAt || null,
         log: Array.isArray(parsed.log) ? parsed.log : [],
       },
       corrupt: false,
@@ -854,6 +1464,64 @@ function writeGate(outPath, gate) {
   return p
 }
 
+/* ==========================================================================
+ * The render record — what the caller DECLARED, for the re-render to read
+ * ========================================================================== */
+
+// Same stem as the other sidecars, so one spec's set still reads as one set.
+function renderRecordPath(outPath) {
+  return outPath.replace(/\.html$/, '') + '.render.json'
+}
+
+/**
+ * The button set the last CLI render of this spec declared, or null.
+ *
+ * WHY THIS EXISTS AT ALL. `--buttons` is declared by the caller — `BUTTON_SETS`
+ * above says why it is never derived — and the review daemon is not that
+ * caller. It re-renders a spec's page per request from the tree, so without a
+ * record it can only guess, and what it guessed was the default: every
+ * `/no-spec` page served over http offered `Commit & Start`.
+ *
+ * WHAT WOULD FOOL A CONSUMER THAT TRUSTED THIS OUTRIGHT: it is a file on disk
+ * and the tree moves underneath it. A spec rendered as `--docs` and then put in
+ * flight has a day-old record saying `authoring` and a worktree saying
+ * otherwise. So `buttonsForView` in `serve.js` takes only NARROWING words from
+ * here and reads the family off the tree — this function's job is to report
+ * what was written, not to decide whether it still holds.
+ *
+ * Three states, like `readNotes` and `readGate`: absent is the ordinary case,
+ * and corrupt is reported rather than hidden so neither reads as a declaration.
+ */
+function readRenderRecord(outPath, specFolder) {
+  let raw
+  try {
+    raw = fs.readFileSync(renderRecordPath(outPath), 'utf8')
+  } catch {
+    // Absent is ordinary: most pages are opened off the index without the CLI
+    // ever having rendered that spec.
+    return { buttons: null, corrupt: false, present: false }
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    const buttons = typeof parsed.buttons === 'string' && parsed.buttons ? parsed.buttons : null
+    // The folder is checked, not trusted: a record found under this spec's stem
+    // that names another spec is not this spec's declaration.
+    if (parsed.spec && specFolder && parsed.spec !== specFolder) {
+      return { buttons: null, corrupt: false, present: true }
+    }
+    return { buttons, corrupt: false, present: true }
+  } catch {
+    return { buttons: null, corrupt: true, present: true }
+  }
+}
+
+function writeRenderRecord(outPath, record) {
+  const p = renderRecordPath(outPath)
+  fs.mkdirSync(path.dirname(p), { recursive: true })
+  fs.writeFileSync(p, JSON.stringify(record, null, 2) + '\n')
+  return p
+}
+
 /**
  * Arm the gate. Pure.
  *
@@ -863,8 +1531,32 @@ function writeGate(outPath, gate) {
  * for a DIFFERENT phase is re-armed, because that is a new obligation.
  */
 function armGate(gate, { at, phase = null }) {
+  // Idempotent within a phase — a re-render must not restart the clock, and it
+  // must not hand back an offer this arming has already spent.
   if (gate.armed && gate.phase === phase) return gate
-  return { ...gate, armed: true, armedAt: at, phase }
+  // A NEW ARMING GETS A NEW OFFER. Each phase that ends is its own obligation,
+  // so the once-only rule is scoped to the arming rather than to the file.
+  return { ...gate, armed: true, armedAt: at, phase, offeredAt: null }
+}
+
+/**
+ * Record that the bypass was offered for this arming. Pure.
+ *
+ * SPENT BY BEING MADE, not by being taken. A reader who declines still saw it,
+ * and re-offering on the next refused commit is how a bypass becomes the default
+ * rather than a deliberate step.
+ *
+ * NOT DONE AS A SIDE EFFECT OF READING THE GATE, deliberately. `/spec-next`
+ * asks `review gate --json` on every single run, so a read that spent the
+ * offer would burn it with no picker ever raised — and the operator would never
+ * be offered the thing this exists to offer them.
+ *
+ * Marking an unarmed gate changes nothing: there is no obligation, so there is
+ * nothing to have offered a way out of.
+ */
+function markGateOffered(gate, { at }) {
+  if (!gate.armed || gate.offeredAt) return { gate, marked: false }
+  return { gate: { ...gate, offeredAt: at }, marked: true }
 }
 
 /**
@@ -935,7 +1627,15 @@ function gateState({ gate, corrupt, present, required }) {
     }
   }
   if (!gate.armed) return { state: 'clear', reason: 'nothing is awaiting a verdict', gate }
-  return { state: 'armed', reason: 'a phase is awaiting a verdict', gate }
+  // The refusal is unchanged by the offer having been spent — what is withheld
+  // is the way out, never the guard. A second refused commit still refuses, and
+  // still names its exits in the text; the operator simply is not asked again.
+  return {
+    state: 'armed',
+    reason: 'a phase is awaiting a verdict',
+    gate,
+    ...(gate.offeredAt ? {} : { offer: GATE_BYPASS_OFFER }),
+  }
 }
 
 /**
@@ -1005,7 +1705,20 @@ function validateNotesBlob(blob, specFolder) {
     }
     verdict = named
   }
-  return { accepted, unaccepted, comments, verdict }
+  // AN ACTION, refused by name for the same reason a misspelt verdict is: a
+  // dropped `action: "live-onn"` would read as a pass carrying no instruction
+  // at all, reported as if the press had been honoured.
+  let action = null
+  if (blob.action !== undefined && blob.action !== null) {
+    if (typeof blob.action !== 'string' || !ACTIONS.includes(blob.action)) {
+      fail(`action ${JSON.stringify(blob.action)} is not one of ${ACTIONS.join(', ')}`)
+    }
+    action = blob.action
+  }
+  if (action && verdict) {
+    fail(`carries both a verdict (${verdict}) and an action (${action}) — send one`)
+  }
+  return { accepted, unaccepted, comments, verdict, action }
 }
 
 /**
@@ -1032,7 +1745,15 @@ function validateNotesBlob(blob, specFolder) {
  * failure we can afford.
  */
 function judgeVerdict(verdict, notes) {
-  const sent = readVerdict(verdict) || null
+  const read = readVerdict(verdict) || null
+  // A WORD THIS ENGINE DOES NOT KNOW IS NOT HONOURED AS ONE. Every door into
+  // here validates first — `validateNotesBlob` refuses an unknown verdict by
+  // name and refuses an action in the verdict slot, and `--verdict` checks the
+  // list — so nothing reaches this today. It used to pass such a word straight
+  // through with `honoured: true`, which routes cannot-tell to the branch that
+  // acts (`.claude/rules/negative-checks.md` rule 4 inverted). Closing it costs
+  // nothing and means a fifth door added later cannot reopen it.
+  const sent = read && VERDICTS.includes(read) ? read : null
   const asked = sent || DEFAULT_VERDICT
   const open = (notes.comments || []).filter((c) => !c.resolved)
   const openFiles = [...new Set(open.map((c) => c.file))]
@@ -1060,9 +1781,18 @@ function judgeVerdict(verdict, notes) {
  * commit something nobody read. What is kept is the account of what was
  * decided, when, and eventually what it produced.
  */
-function appendDecision(notes, { verdict, at, note = null }) {
+function appendDecision(notes, { verdict, at, note = null, code = null }) {
   const decisions = Array.isArray(notes.decisions) ? notes.decisions.slice() : []
-  decisions.push({ verdict, at, note: note === undefined ? null : note })
+  // `code` NAMES THE PASS this decision came out of, and it is the only present
+  // thing anyone can assert to conclude that a pass was picked up. Four
+  // different things make a code vanish from the holding area and only one of
+  // them is a claim — `--drop` is another, a moved store and a mistyped folder
+  // are two more — so `passState` reads this, and never reads an absence.
+  //
+  // `null` for every other path in: a pasted blob and a `--verdict` word carry
+  // no code, and inventing one would put a pass in the record that never
+  // existed.
+  decisions.push({ verdict, at, note: note === undefined ? null : note, code: code || null })
   return { ...notes, updatedAt: at, decisions }
 }
 
@@ -1360,6 +2090,7 @@ function renderReviewBlock(review) {
   if (review.summary) {
     parts.push(`<p class="review-summary">${escapeHtml(review.summary)}</p>`)
   }
+  parts.push(...renderReviewerStrip(review.reviewers))
   const checks = Array.isArray(review.checks) ? review.checks : []
   if (checks.length) {
     parts.push('<ul class="checks">')
@@ -1368,16 +2099,31 @@ function renderReviewBlock(review) {
       // reviewer's note because it was tagged oddly is worse than showing it
       // under a neutral heading.
       const level = CHECK_LEVELS.includes(c.level) ? c.level : 'confirm'
-      const file = c.file ? `<span class="check-file">${escapeHtml(c.file)}</span>` : ''
+      // `file:line` where a line is known, and the whole thing is a button so a
+      // finding can be read against the code it is about. A check with no line
+      // renders exactly as it always did — the written review supplies none, and
+      // its output must not change because machine findings now exist.
+      const hasLine = Number.isInteger(c.line) && c.line > 0
+      const label = c.file ? escapeHtml(c.file) + (hasLine ? `:${c.line}` : '') : ''
+      const file = c.file
+        ? `<button type="button" class="check-file" data-goto="${escapeHtml(c.file)}"` +
+          `${hasLine ? ` data-goto-line="${c.line}"` : ''}>${label}</button>`
+        : ''
+      // WHO SAID IT. Absent for a written review, which is what it has always
+      // been; present the moment two authors can appear on one page, because a
+      // reader weighing a finding needs to know whether a person read the code
+      // or a tool matched a pattern.
+      const src = c.source ? `<span class="check-src">${escapeHtml(c.source)}</span>` : ''
       // The id is positional and therefore stable for THIS render, which is all
       // a reply needs: it travels back in the same blob the page was built from.
       // `data-file` is what lets an answer land on the file the check is about.
       const id = `k${i}`
       const fileAttr = c.file ? ` data-file="${escapeHtml(c.file)}"` : ''
+      const lineAttr = hasLine ? ` data-line="${c.line}"` : ''
       parts.push(
-        `<li class="check ${level}" data-check="${id}"${fileAttr}>` +
+        `<li class="check ${level}" data-check="${id}"${fileAttr}${lineAttr}>` +
           `<span class="check-level">${level}</span>` +
-          `${file}<span class="check-note">${escapeHtml(c.note || '')}</span></li>`,
+          `${src}${file}<span class="check-note">${escapeHtml(c.note || '')}</span></li>`,
       )
     })
     parts.push('</ul>')
@@ -1386,6 +2132,65 @@ function renderReviewBlock(review) {
   return parts.join('\n')
 }
 
+/**
+ * One line per configured reviewer, saying what its run ended as.
+ *
+ * PRESENT EVEN WHEN EVERY REVIEWER FOUND NOTHING, which is the whole point and
+ * the one place `.claude/rules/negative-checks.md` inverts here. Silence is
+ * normally the safe branch; on this page it is not, because a reviewer that was
+ * rate-limited renders identically to one that read the diff and approved of it
+ * — and the reader is about to decide whether to commit. So the strip reports
+ * the RUN, which is a positive signal, rather than accusing the code.
+ *
+ * Absent entirely when no reviewer is configured: every project that exists
+ * today is in that state, and a strip saying "no reviewers" would be an absence
+ * reported at everyone.
+ */
+function renderReviewerStrip(outcomes) {
+  const list = Array.isArray(outcomes) ? outcomes : []
+  if (!list.length) return []
+  const parts = ['<ul class="reviewers">']
+  for (const o of list) {
+    const state = typeof o.state === 'string' ? o.state : 'failed'
+    parts.push(
+      `<li class="reviewer ${escapeHtml(state)}">` +
+        `<span class="reviewer-name">${escapeHtml(o.name || 'reviewer')}</span>` +
+        `<span class="reviewer-said">${escapeHtml(reviewerSaid(o))}</span></li>`,
+    )
+  }
+  parts.push('</ul>')
+  return parts
+}
+
+/**
+ * What one reviewer's outcome reads as. Pure.
+ *
+ * A STATE THIS BUILD DOES NOT KNOW IS SHOWN, not dropped — the same rule the
+ * check level follows. An unrecognised state means a newer engine wrote the
+ * cache, and losing the line entirely would read as a reviewer that was never
+ * configured.
+ */
+function reviewerSaid(o) {
+  const n = Number.isInteger(o.count) ? o.count : 0
+  const detail = o.detail ? ` — ${o.detail}` : ''
+  switch (o.state) {
+    case 'findings':
+      return `${n} finding${n === 1 ? '' : 's'}${detail}`
+    case 'cached':
+      return n ? `${n} finding${n === 1 ? '' : 's'} · cached` : 'clean · cached'
+    case 'clean':
+      return 'clean'
+    case 'missing':
+      return `did not run${o.detail ? ` — ${o.detail}` : ''}`
+    case 'timeout':
+      return 'did not run — timed out'
+    case 'failed':
+      return `did not run${o.detail ? ` — ${o.detail}` : ''}`
+    default:
+      return `${o.state}${detail}`
+  }
+}
+
 /**
  * Where a spec's published URL is remembered, and what it currently says.
  *
@@ -1447,8 +2252,9 @@ function reviewServerNotice({ running, othersServed }) {
   ]
 }
 
-// The publish-ready copy, beside the page it came from. Same stem, so the three
-// sidecars (`.notes.json`, `.url`, `.publish.html`) all read as one spec's set.
+// The publish-ready copy, beside the page it came from. Same stem, so every
+// sidecar (`.notes.json`, `.url`, `.publish.html`, `.render.json`) reads as one
+// spec's set.
 function reviewPublishPath(outPath) {
   return outPath.replace(/\.html$/, '') + '.publish.html'
 }
@@ -1501,6 +2307,11 @@ module.exports = {
   WHOLE_FILE_CONTEXT,
   NOTES_VERSION,
   VERDICTS,
+  ACTIONS,
+  tierAction,
+  surfacesFor,
+  reviewTierStack,
+  reviewTierLine,
   COMMITTING,
   BUTTON_SETS,
   DEFAULT_BUTTON_SET,
@@ -1518,6 +2329,7 @@ module.exports = {
   appendDecision,
   annotateLastDecision,
   reviewPendingPath,
+  PENDING_SUFFIX,
   emptyPending,
   readPending,
   writePending,
@@ -1525,6 +2337,11 @@ module.exports = {
   addPending,
   claimPending,
   passesSince,
+  waitingPasses,
+  waitForPass,
+  WAIT_HEARTBEAT_MS,
+  WAIT_POLL_MS,
+  passState,
   describePending,
   pendingAge,
   PENDING_CODE_LENGTH,
@@ -1534,9 +2351,15 @@ module.exports = {
   emptyGate,
   readGate,
   writeGate,
+  renderRecordPath,
+  readRenderRecord,
+  writeRenderRecord,
   armGate,
   disarmGate,
   gateState,
+  markGateOffered,
+  GATE_BYPASS_OFFER,
+  GATE_BYPASS_REASON,
   gateForPage,
   mergeNotes,
   applyResolutions,
@@ -1557,6 +2380,8 @@ module.exports = {
   escapeIsland,
   escapeHtml,
   renderReviewBlock,
+  renderReviewerStrip,
+  reviewerSaid,
   reviewUrlPath,
   reviewPublishPath,
   readReviewUrl,