@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/src/env/review.js

@@ -285,7 +285,7 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
   // 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 surfaces = surfacesFor({ live, tiers, buttons })
 
   const files = []
   for (const f of trackedFiles(git, ref)) {
@@ -494,6 +494,14 @@ const NOTES_VERSION = 1
  * 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
@@ -501,7 +509,15 @@ 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', 'commit-start', 'continue', 'changes', 'discuss']
+const VERDICTS = [
+  'commit',
+  'commit-continue',
+  'commit-start',
+  'commit-land',
+  'continue',
+  'changes',
+  'discuss',
+]
 const DEFAULT_VERDICT = 'discuss'
 
 /**
@@ -579,7 +595,24 @@ function tierAction(tier) {
  * the payload must then be byte-identical to what it was before this key
  * existed.
  */
-function surfacesFor({ live, tiers }) {
+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
@@ -594,10 +627,12 @@ function surfacesFor({ live, tiers }) {
       // `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,
+      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.
-      command: live.state === 'on' ? '/spec-live main' : null,
+      // 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,
     })
   }
 
@@ -700,7 +735,7 @@ function reviewTierLine(t) {
 // 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', 'commit-start']
+const COMMITTING = ['commit', 'commit-continue', 'commit-start', 'commit-land']
 
 /**
  * Which set of buttons a rendered page shows.
@@ -726,8 +761,21 @@ const COMMITTING = ['commit', 'commit-continue', 'commit-start']
  * 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', 'authoring', 'refresh']
+const BUTTON_SETS = ['committing', 'midrun', 'authoring', 'refresh', 'nospec']
 const DEFAULT_BUTTON_SET = 'committing'
 
 /**
@@ -1146,6 +1194,11 @@ function passesSince(pending, since) {
 
 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.
@@ -1168,16 +1221,42 @@ const WAIT_POLL_MS = 400
  * 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 } = {}) {
+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 deadline = Number.isFinite(timeoutMs) && timeoutMs !== null ? Date.now() + timeoutMs : null
+  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
@@ -1191,9 +1270,22 @@ async function waitForPass(readStore, since, { timeoutMs = null, pollMs = WAIT_P
         if (window.codes.length > 1) return { state: 'ambiguous', count: window.codes.length }
       }
     }
-    if (deadline !== null && Date.now() >= deadline) return { state: 'timeout' }
+    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 - Date.now())))
+    await nap(deadline === null ? pollMs : Math.max(0, Math.min(pollMs, deadline - now())))
   }
 }
 
@@ -1280,6 +1372,39 @@ function waitingPasses(reviewsDirPath) {
 
 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.
@@ -1290,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: [] }
 }
 
 /**
@@ -1318,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,
@@ -1335,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.
  *
@@ -1344,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 }
 }
 
 /**
@@ -1416,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 }),
+  }
 }
 
 /**
@@ -1871,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">')
@@ -1879,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>')
@@ -1897,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.
  *
@@ -1958,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'
 }
@@ -2044,6 +2339,7 @@ module.exports = {
   passesSince,
   waitingPasses,
   waitForPass,
+  WAIT_HEARTBEAT_MS,
   WAIT_POLL_MS,
   passState,
   describePending,
@@ -2055,9 +2351,15 @@ module.exports = {
   emptyGate,
   readGate,
   writeGate,
+  renderRecordPath,
+  readRenderRecord,
+  writeRenderRecord,
   armGate,
   disarmGate,
   gateState,
+  markGateOffered,
+  GATE_BYPASS_OFFER,
+  GATE_BYPASS_REASON,
   gateForPage,
   mergeNotes,
   applyResolutions,
@@ -2078,6 +2380,8 @@ module.exports = {
   escapeIsland,
   escapeHtml,
   renderReviewBlock,
+  renderReviewerStrip,
+  reviewerSaid,
   reviewUrlPath,
   reviewPublishPath,
   readReviewUrl,