@skitterbyte/skitterspec 21.0.0 → 22.0.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 })
+
   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,7 +480,15 @@ 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
@@ -414,9 +501,195 @@ 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', '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 }) {
+  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' ? '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.
+      command: live.state === 'on' ? '/spec-live main' : 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 +700,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']
 
 /**
  * Which set of buttons a rendered page shows.
@@ -442,8 +715,19 @@ 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.
  */
-const BUTTON_SETS = ['committing', 'midrun']
+const BUTTON_SETS = ['committing', 'midrun', 'authoring', 'refresh']
 const DEFAULT_BUTTON_SET = 'committing'
 
 /**
@@ -584,9 +868,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 +962,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 +1036,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 +1128,141 @@ 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
+
+/**
+ * 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.
+ *
+ * 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 } = {}) {
+  if (!Number.isFinite(Date.parse(since))) return { state: 'unusable' }
+  const nap = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const deadline = Number.isFinite(timeoutMs) && timeoutMs !== null ? Date.now() + timeoutMs : null
+
+  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 && Date.now() >= deadline) return { state: 'timeout' }
+    // Never overshoot the deadline by a whole poll interval.
+    await nap(deadline === null ? pollMs : Math.max(0, Math.min(pollMs, deadline - Date.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
  *
@@ -1005,7 +1486,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 +1526,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 +1562,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 }
 }
 
@@ -1501,6 +2012,11 @@ module.exports = {
   WHOLE_FILE_CONTEXT,
   NOTES_VERSION,
   VERDICTS,
+  ACTIONS,
+  tierAction,
+  surfacesFor,
+  reviewTierStack,
+  reviewTierLine,
   COMMITTING,
   BUTTON_SETS,
   DEFAULT_BUTTON_SET,
@@ -1518,6 +2034,7 @@ module.exports = {
   appendDecision,
   annotateLastDecision,
   reviewPendingPath,
+  PENDING_SUFFIX,
   emptyPending,
   readPending,
   writePending,
@@ -1525,6 +2042,10 @@ module.exports = {
   addPending,
   claimPending,
   passesSince,
+  waitingPasses,
+  waitForPass,
+  WAIT_POLL_MS,
+  passState,
   describePending,
   pendingAge,
   PENDING_CODE_LENGTH,