@skitterbyte/skitterspec 22.1.0 → 22.3.0

package/assets/review/page.html

@@ -222,6 +222,22 @@ input:focus-visible,
 }
 .tree-file.is-noise .nm { color: var(--muted); }
 
+/* THE FILE YOU ARE READING — the card crossing the top of the viewport.
+   An INSET SHADOW rather than a border or a left padding: either of those
+   would change the row's size, so the highlight moving down the list would
+   shunt every name sideways as it went. A shadow paints inside the box the
+   row already occupies.
+
+   A DIFFERENT CHANNEL FROM HOVER, deliberately. Hover owns the `--panel-2`
+   background, and the current row is very often NOT the row under your
+   finger — you scroll with one and point with the other. Sharing the
+   treatment would make the two indistinguishable at exactly the moment they
+   disagree, so this is a bar and a colour, and the background is left alone.
+   Leaving it alone also keeps `.ct` masking the names scrolling under it,
+   which is a background the row inherits. */
+.tree-file.is-current { box-shadow: inset 3px 0 0 var(--accent); }
+.tree-file.is-current .nm { color: var(--accent); font-weight: 600; }
+
 .file {
   border: 1px solid var(--line);
   border-radius: 10px;
@@ -417,6 +433,26 @@ tr.note-row td {
   border-top: 1px solid var(--note-line);
   border-bottom: 1px solid var(--note-line);
 }
+/* A NOTE IS PROSE, AND IT WRAPS TO THE PANE — never to the file.
+   The cell it sits in is a column of `table.diff`, so its width is the longest
+   line of source in this file (`td.src` is white-space:pre): 4,900px for a
+   wrapped markdown spec is ordinary, and a `width:100%` note inside that is four
+   screens wide. It scrolled sideways instead of wrapping, which is what a reader
+   sees as a box that keeps growing.
+   Sticky for the same reason `td.gutter` is: the row can be reached while the
+   pane is scrolled right, and a note you cannot see while typing it is no
+   better. `--pane-w`/`--gutter-w` are measured per code box by `sizeNotes` —
+   measured rather than summed from `--ln-w`, because the gutter is ONE sticky
+   cell precisely so nobody has to do that arithmetic.
+   `max-width` caps it at the cell, so the note can never be the thing that
+   widens the table. */
+.note-body {
+  position: sticky;
+  left: var(--gutter-w, 0px);
+  width: var(--pane-w, 100%);
+  max-width: 100%;
+  box-sizing: border-box;
+}
 .note-meta { font-size: .72rem; color: var(--muted); display: block; margin-bottom: .15rem; }
 .note-text { overflow-wrap: anywhere; }
 .note-row.is-resolved .note-text { text-decoration: line-through; opacity: .75; }
@@ -517,6 +553,19 @@ button:disabled { color: var(--muted); background: var(--panel-2); border-style:
 button:disabled:hover { color: var(--muted); border-color: var(--line); }
 .verdict-log { font-size: .8rem; color: var(--muted); margin: .45rem 0 0; }
 .verdict-log[hidden] { display: none; }
+/* Not muted, unlike the log beneath it: this one is the reason a press did
+   nothing, and a grey line under a bar that appeared to ignore you reads as a
+   broken page. */
+.verdict-warn {
+  font-size: .85rem;
+  color: var(--flag-fg);
+  background: var(--flag-bg);
+  border-left: 3px solid var(--flag-fg);
+  border-radius: 0 6px 6px 0;
+  padding: .45rem .6rem;
+  margin: .5rem 0 0;
+}
+.verdict-warn[hidden] { display: none; }
 /* Which engine drew this page. A render is always current and a stale RENDERER
    is invisible without it — the counts move, the date moves, the diff is right. */
 .drawn-by { font-size: .75rem; color: var(--muted); margin: .9rem 0 0; }
@@ -570,6 +619,37 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
    border it read as part of it rather than as the way back to the diff. */
 .decided-toggle { font-size: .78rem; margin-top: .8rem; }
 
+/* STILL ASKING. The window between the pass landing on the server and the
+   engine saying whether a session took it — up to seven seconds, and until now
+   the page filled it with the pessimistic answer and retracted it afterwards.
+   A spinner is the honest shape for a question with no answer yet. */
+.pickup-wait {
+  display: flex;
+  align-items: center;
+  gap: .5rem;
+  margin: 0 0 .8rem;
+  color: var(--muted);
+  font-size: .88rem;
+}
+.pickup-wait[hidden] { display: none; }
+.pickup-spin {
+  width: .85rem;
+  height: .85rem;
+  flex: none;
+  border: 2px solid var(--line);
+  /* One side in the accent is what makes a ring read as turning. */
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: pickup-spin .8s linear infinite;
+}
+@keyframes pickup-spin { to { transform: rotate(360deg); } }
+/* A STATIC RING, not a hidden one. Someone who asked for less motion still
+   needs to see that something is in progress, and the sentence beside it is
+   doing most of that work anyway. */
+@media (prefers-reduced-motion: reduce) {
+  .pickup-spin { animation: none; border-top-color: var(--accent); }
+}
+
 /* WHY THE CHANGE EXISTS — the PR description this page never had. It is prose
    to be read rather than data to be scanned, so it gets a measure, air, and a
    quieter voice than the diff below it. It was once full-bleed 15px text at
@@ -794,6 +874,14 @@ a.ticket:hover { border-color: var(--accent); }
     <section class="decided" id="decided" hidden>
       <p class="decided-what" id="decided-what"></p>
       <p class="decided-note" id="decided-note"></p>
+      <!-- SHOWN ONLY WHILE THE PAGE IS ACTUALLY ASKING. A tab reopened
+           tomorrow over a stored `null` is reading history, not watching a
+           live poll, so it gets the command instead — a spinner that can never
+           resolve is worse than no spinner. -->
+      <p class="pickup-wait" id="pickup-wait" hidden>
+        <span class="pickup-spin" aria-hidden="true"></span>
+        <span id="pickup-wait-text">Sent — waiting for Claude to pick it up…</span>
+      </p>
       <!-- THE ONE THING LEFT TO DO, and it lives HERE rather than under the
            verdict bar because that is where it was being missed: a grey line
            below a bar that had just closed, in the type size of a footnote,
@@ -863,6 +951,12 @@ a.ticket:hover { border-color: var(--accent); }
         <button id="verdict-discuss" type="button">… Discuss first</button>
         <span class="verdict-count" id="verdict-count" aria-live="polite"></span>
       </div>
+      <!-- UNSENT TEXT, named at the moment it would have been destroyed. It sits
+           directly under the bar rather than beside the editor, because the
+           press that raises it happens here and the editor may be a screen
+           away. `assertive`: the reader is mid-decision and a polite region
+           would be read out after they have pressed again. -->
+      <p class="verdict-warn" id="verdict-warn" hidden aria-live="assertive"></p>
       <!-- WHERE THE BUTTONS CANNOT DELIVER, the commands stand in their place.
            A `file://` page has no server to POST to and no store to write to,
            so a verdict button there only ever built a blob for the reader to
@@ -1145,6 +1239,56 @@ a.ticket:hover { border-color: var(--accent); }
     table.appendChild(body)
     box.appendChild(table)
     host.appendChild(box)
+    sizeNotes(box)
+    watchPane(host)
+  }
+
+  /**
+   * Publish this code box's visible width, for the note bodies inside it.
+   *
+   * A note has to wrap at the width of what the reader can SEE, and the cell it
+   * lives in is a diff-table column sized by the longest line of source in the
+   * file. So the pane's own width is measured here and handed to the CSS.
+   *
+   * MEASURED, NEVER SUMMED. The gutter's width is `--ln-w` plus the +/- column
+   * plus padding plus a border, in whatever font the reader has — and `td.gutter`
+   * is one sticky cell rather than three precisely so that nobody has to get
+   * that arithmetic right. Asking the element is the same decision one layer up.
+   *
+   * A BOX MEASURED AT NOTHING PUBLISHES NOTHING. A file whose <details> has
+   * never been opened reports 0 for everything, and 0 is not a narrow pane —
+   * it is a box that has not been laid out. Writing it would give every note in
+   * that file a zero-width editor on the one render that matters, so the
+   * cannot-tell case leaves whatever was there alone and the CSS falls back to
+   * its own defaults.
+   */
+  function sizeNotes(box) {
+    if (!box || !box.style) return
+    var g = box.querySelector('td.gutter')
+    var gw = (g && g.offsetWidth) || 0
+    var pane = box.clientWidth || 0
+    if (!pane || !gw) return
+    box.style.setProperty('--gutter-w', gw + 'px')
+    box.style.setProperty('--pane-w', Math.max(0, pane - gw) + 'px')
+  }
+
+  // Re-measure when the layout moves under it — a rotated phone, a window
+  // dragged narrower, the file tree folding away. The HOST is watched rather
+  // than the box: a box is rebuilt on every band expansion, and an observer
+  // holding the old ones would keep a whole file's worth of detached rows alive
+  // for the life of the page. Observing the same host twice replaces the
+  // observation, so re-renders cost nothing.
+  //
+  // A browser without ResizeObserver keeps the width it opened at, which is
+  // wrong only for someone who then resizes. Nothing accuses, nothing breaks.
+  var paneWatch = typeof ResizeObserver === 'function'
+    ? new ResizeObserver(function (entries) {
+        entries.forEach(function (e) { sizeNotes(e.target.querySelector('.code')) })
+      })
+    : null
+
+  function watchPane(host) {
+    if (paneWatch && host) paneWatch.observe(host)
   }
 
   // Every note about one line: what the engine stored, plus anything written on
@@ -1161,13 +1305,14 @@ a.ticket:hover { border-color: var(--accent); }
     var tr = el('tr', 'note-row' + (c.resolved ? ' is-resolved' : ''))
     tr.appendChild(el('td', 'gutter', '💬'))
     var td = el('td', 'src')
+    var body = el('div', 'note-body')
     var meta = c.line == null ? 'on this file' : 'line ' + c.line
     if (c.check) meta += ' · answering the review'
     if (!c.raisedAt) meta += ' · not sent yet'
-    td.appendChild(el('span', 'note-meta', meta))
-    td.appendChild(el('span', 'note-text', c.note))
+    body.appendChild(el('span', 'note-meta', meta))
+    body.appendChild(el('span', 'note-text', c.note))
     if (c.resolved) {
-      td.appendChild(el('span', 'note-resolution', '↳ ' + (c.resolved.note || 'resolved')))
+      body.appendChild(el('span', 'note-resolution', '↳ ' + (c.resolved.note || 'resolved')))
     }
     if (!c.raisedAt) {
       var actions = el('div', 'note-actions')
@@ -1179,8 +1324,9 @@ a.ticket:hover { border-color: var(--accent); }
         refresh()
       })
       actions.appendChild(del)
-      td.appendChild(actions)
+      body.appendChild(actions)
     }
+    td.appendChild(body)
     tr.appendChild(td)
     return tr
   }
@@ -1190,8 +1336,9 @@ a.ticket:hover { border-color: var(--accent); }
     var tr = el('tr', 'note-row')
     tr.appendChild(el('td', 'gutter', '💬'))
     var td = el('td', 'src')
-    td.appendChild(el('span', 'note-meta', row ? 'line ' + (row.n == null ? '—' : row.n) : 'on this file'))
-    td.appendChild(noteEditor(function (text) {
+    var body = el('div', 'note-body')
+    body.appendChild(el('span', 'note-meta', row ? 'line ' + (row.n == null ? '—' : row.n) : 'on this file'))
+    body.appendChild(noteEditor(function (text) {
       addDraft(st, text, row ? row.n : null, row ? row.text : null, null)
       st.draftAt = null
       renderFile(st)
@@ -1199,6 +1346,7 @@ a.ticket:hover { border-color: var(--accent); }
       st.draftAt = null
       renderFile(st)
     }))
+    td.appendChild(body)
     tr.appendChild(td)
     return tr
   }
@@ -1287,6 +1435,11 @@ a.ticket:hover { border-color: var(--accent); }
     var f = st.file
     var d = el('details', 'file')
     d.id = 'f-' + encodeURIComponent(f.path)
+    // Read back by the current-file observer, which is handed elements rather
+    // than files. The id would do — it is the same path, encoded — but decoding
+    // an id to recover data the element could simply carry is a round trip
+    // through a format that exists for a different reason.
+    d.setAttribute('data-path', f.path)
     var s = el('summary')
     s.appendChild(el('span', 'path', f.path))
     s.appendChild(el('span', 'chip', f.status))
@@ -1370,12 +1523,126 @@ a.ticket:hover { border-color: var(--accent); }
     return root
   }
 
+  // --- which file am I reading? --------------------------------------------
+  // The tree row for each path, captured as the tree is built. A lookup rather
+  // than a query, because this is answered on every scroll: a `querySelector`
+  // per event would walk the whole sidebar to find something the build already
+  // had in its hand.
+  var rowByPath = {}
+  var currentPath = null
+
+  /**
+   * Mark one file as the one being read.
+   *
+   * ONE ROW AT A TIME, and the previous one is cleared through the same map
+   * rather than by querying for `.is-current`. A map cannot report a row the
+   * tree no longer has, and it cannot miss one a selector spelled slightly
+   * differently.
+   */
+  function setCurrent(path) {
+    if (path === currentPath) return
+    var prev = rowByPath[currentPath]
+    if (prev) prev.className = prev.className.replace(/ ?is-current/, '')
+    currentPath = path
+    var row = rowByPath[path]
+    if (!row) return
+    row.className += ' is-current'
+    followCurrent(row)
+  }
+
+  /**
+   * Drop the highlight entirely.
+   *
+   * For the decided page, where the diff is hidden and no card can qualify —
+   * leaving a row lit there would point at something the reader can no longer
+   * see.
+   */
+  function clearCurrent() {
+    var prev = rowByPath[currentPath]
+    if (prev) prev.className = prev.className.replace(/ ?is-current/, '')
+    currentPath = null
+  }
+
+  /**
+   * Scroll the tree ONLY when the marked row has left its own scrollport.
+   *
+   * The sidebar is a bounded box (`max-height: calc(100vh - 2rem)`), so on a
+   * long diff the highlight is invisible unless the row can be brought in —
+   * and on a short one nothing should ever move. `block: 'nearest'` keeps the
+   * nudge a nudge: re-centring would put the sidebar in constant motion beside
+   * a reader who is already moving, which is the thing a fixed map is for.
+   *
+   * A browser that withholds `getBoundingClientRect` gets the highlight and no
+   * follow. Guessing a position from nothing is how a sidebar ends up scrolled
+   * somewhere arbitrary.
+   */
+  function followCurrent(row) {
+    var box = document.getElementById('tree-wrap')
+    if (!box || !row.getBoundingClientRect || !box.getBoundingClientRect) return
+    var r = row.getBoundingClientRect()
+    var b = box.getBoundingClientRect()
+    if (r.top >= b.top && r.bottom <= b.bottom) return
+    if (row.scrollIntoView) row.scrollIntoView({ block: 'nearest' })
+  }
+
+  // What is currently crossing the band, keyed by path. A SET rather than a
+  // running answer: entries arrive for what CHANGED, so the observer never
+  // hands over the whole picture and the page has to keep it.
+  var onScreen = {}
+
+  /**
+   * The topmost file on screen, in document order.
+   *
+   * NOTHING ON SCREEN IS NOT AN ANSWER, and this returning without calling
+   * `setCurrent` is the whole of that. Scrolled above the first card, past the
+   * last, or with the current file hidden by the noise filter, the previous
+   * row stays lit — clearing it would flicker the highlight off every time a
+   * card boundary crossed the band, and a stale "you were here" is worth more
+   * than nothing at all.
+   */
+  function pickCurrent() {
+    for (var i = 0; i < state.length; i++) {
+      if (onScreen[state[i].file.path]) return setCurrent(state[i].file.path)
+    }
+  }
+
+  /**
+   * Watch the cards against a band at the top of the viewport.
+   *
+   * THE BOTTOM MARGIN IS THE WHOLE TRICK. Pulled up by three quarters of the
+   * viewport, only the top slice counts as "on screen" — so the answer changes
+   * as you scroll. Without it every card on a tall screen intersects at once
+   * and the topmost is whatever is furthest up the document, which is the same
+   * file from the first scroll to the last.
+   *
+   * A browser without IntersectionObserver keeps a page with no highlight and
+   * no error — the shape `paneWatch` takes for ResizeObserver above. Nothing
+   * accuses and nothing breaks; the tree is still a tree.
+   */
+  var currentWatch = typeof IntersectionObserver === 'function'
+    ? new IntersectionObserver(function (entries) {
+        entries.forEach(function (e) {
+          var p = e.target.getAttribute('data-path')
+          if (!p) return
+          if (e.isIntersecting) onScreen[p] = true
+          else delete onScreen[p]
+        })
+        pickCurrent()
+      }, { rootMargin: '0px 0px -75% 0px' })
+    : null
+
   function reveal(f) {
     if (f.noise && !noiseBox.checked) { noiseBox.checked = true; applyNoise() }
     var d = document.getElementById('f-' + encodeURIComponent(f.path))
     if (!d) return
     d.open = true
     d.scrollIntoView({ block: 'start' })
+    // Mark it NOW rather than waiting for the scroll to settle. A click on the
+    // tree is a reader saying which file they mean, and the observer would
+    // agree a moment later — but the moment is visible, and a row that lights
+    // up after you have already looked away reads as a lag rather than an
+    // answer.
+    setCurrent(f.path)
   }
 
   /**
@@ -1472,6 +1739,9 @@ a.ticket:hover { border-color: var(--accent); }
         ct.appendChild(el('span', 'd', '-' + entry.file.deletions))
         b.appendChild(ct)
         b.addEventListener('click', function () { reveal(entry.file) })
+        // The path, not the name: two directories can hold a `README.md`, and
+        // the tree deliberately shows the leaf only.
+        rowByPath[entry.file.path] = b
         li.appendChild(b)
         ul.appendChild(li)
       })
@@ -1487,6 +1757,17 @@ a.ticket:hover { border-color: var(--accent); }
     document.getElementById('tree-wrap').open = false
   }
 
+  // AFTER the tree, because a mark with no row to put it on is nothing at all.
+  //
+  // It runs on a narrow screen too, where the tree is a collapsed <details> and
+  // nothing is visible: the class is still correct, so a reader who opens the
+  // sidebar half-way down a diff finds it already pointing at where they are,
+  // and `scrollIntoView` inside a closed <details> is a no-op rather than a
+  // special case to write.
+  if (currentWatch) {
+    state.forEach(function (st) { if (st.details) currentWatch.observe(st.details) })
+  }
+
   // --- page-level controls -------------------------------------------------
   document.getElementById('expand-all').addEventListener('click', function () {
     state.forEach(function (st) {
@@ -1625,6 +1906,11 @@ a.ticket:hover { border-color: var(--accent); }
     refresh: ['commit', 'changes', 'discuss'],
     nospec: ['commit-land', 'commit', 'changes', 'discuss'],
     committing: ['commit', 'commit-continue', 'changes', 'discuss'],
+    // A SINGLE-PASS FIX: the committing set minus the verb it cannot honour.
+    // `/spec-bug` and `/spec-hotfix` render this when the repair took one pass,
+    // because `Commit & Continue` names a next phase a spec with no phase files
+    // does not have. Same three buttons as `refresh`, a different subject.
+    fix: ['commit', 'changes', 'discuss'],
   }
   var OFFERED = OFFERS[data.buttons] || OFFERS.committing
   Object.keys(verdictBtns).forEach(function (key) {
@@ -1665,6 +1951,7 @@ a.ticket:hover { border-color: var(--accent); }
   var verdictEl = document.getElementById('verdict')
   var verdictCount = document.getElementById('verdict-count')
   var verdictLog = document.getElementById('verdict-log')
+  var verdictWarn = document.getElementById('verdict-warn')
   var copyOut = document.getElementById('copy-out')
   var wrapEl = document.getElementById('wrap')
   var decidedBox = document.getElementById('decided')
@@ -1683,6 +1970,52 @@ a.ticket:hover { border-color: var(--accent); }
   var failLead = document.getElementById('send-failed-lead')
   var failText = document.getElementById('send-failed-text')
   var failCopy = document.getElementById('send-failed-copy')
+  var pickupWait = document.getElementById('pickup-wait')
+
+  // IS A POLL RUNNING RIGHT NOW? Deliberately not persisted, and that is the
+  // whole of what it buys: a stored decision reloaded tomorrow carries the same
+  // `picked: null` — nothing was ever established — but nothing is asking any
+  // more, so it must not spin. Session state answers a question about the
+  // session.
+  var asking = false
+
+  // Has the close already been scheduled? `drawDecided` runs on every redraw
+  // once a page is decided, so without this a redraw would queue another timer.
+  var closing = false
+
+  // Long enough for the confirmation to register, short enough not to read as
+  // a hang. It only matters where the close is actually permitted.
+  var CLOSE_AFTER_MS = 900
+
+  /**
+   * This tab's job is over — best-effort, and only from the one state that
+   * earns it.
+   *
+   * ONLY ON CONFIRMED PICKUP. Reached from the branch where the engine has
+   * SAID a session claimed the pass, which is the only ending with provably
+   * nothing left on the page to read: no code to quote, no command to run, no
+   * blob to paste. Every other one — still asking, established-nobody-did, a
+   * poll that failed, a `file://` page whose pass is on the clipboard, a
+   * published page whose verdict needs `/spec-reviewed` — keeps the tab,
+   * because each leaves something the reader still needs.
+   *
+   * BEST-EFFORT BY CONSTRUCTION, not by caution. Browsers refuse
+   * `window.close()` on a tab the script did not open, and that is every tab
+   * here: somebody typed the URL or tapped a link. So the confirmation is
+   * drawn FIRST and the close attempted after it — a refused close leaves
+   * exactly the right ending standing, and a permitted one still reads as
+   * acknowledgement rather than a tab vanishing under the press.
+   */
+  function closeWhenDone() {
+    if (closing) return
+    closing = true
+    if (typeof window.close !== 'function' || !window.setTimeout) return
+    window.setTimeout(function () {
+      // A refusal can throw as well as do nothing, depending on the browser.
+      // Neither is a failure of the review, so neither reaches the reader.
+      try { window.close() } catch (e) {}
+    }, CLOSE_AFTER_MS)
+  }
 
   function pending() {
     var b = buildBlob()
@@ -1764,6 +2097,10 @@ a.ticket:hover { border-color: var(--accent); }
     verdictBtns.continue.disabled = false
     verdictBtns.changes.disabled = false
     verdictBtns.discuss.disabled = false
+    // Adding the note is the ordinary way out of a warning, and every mark comes
+    // through here — so the line goes when the situation it described does,
+    // rather than standing over a page where nothing is unsent any more.
+    clearWarn()
     save()
   }
 
@@ -1789,6 +2126,10 @@ a.ticket:hover { border-color: var(--accent); }
       'Sent to Claude' + (when ? ' on ' + when : '') + ' — this review is ' + said + '. ' +
       'Nothing here reaches Claude any more, so the verdict buttons are closed.'
     wrapEl.className = wrapEl.className.replace(/\s*\bis-decided\b/g, '') + ' is-decided'
+    // The diff is hidden from here on, so there is no card to be reading and
+    // nothing for the tree to point at. `drawDecided` runs on every redraw once
+    // a page is decided, and clearing something already cleared is free.
+    clearCurrent()
     // The commands go with the bar. A decided page offers no way to decide
     // again, whichever shape it was offering.
     if (cmdList) cmdList.hidden = true
@@ -1811,12 +2152,34 @@ a.ticket:hover { border-color: var(--accent); }
     // quietly changing its mind a day later.
     copyHint.hidden = true
     copyOut.hidden = true
+    pickupWait.hidden = true
+    // STILL ASKING — and saying so, which is the state this panel used not to
+    // have. `watchPass` takes up to seven seconds to establish whether a
+    // session claimed the pass, and the page used to spend that window
+    // asserting the pessimistic answer: "still waiting to be picked up", with
+    // a command under it, retracted a moment later on the usual outcome. The
+    // reader was being told to run something they almost never needed, in the
+    // same words used when running it is the only thing that saves their
+    // review.
+    //
+    // `asking` and not merely `picked === null`. A tab reopened over a stored
+    // decision has the same `null` — nothing was ever established — but no
+    // poll is running to resolve it, so it falls through to the command below.
+    // A spinner that can never stop is worse than no spinner.
+    // (`.claude/rules/negative-checks.md` rule 4: the cannot-tell case takes
+    // the harmless branch, which here is claiming neither answer.)
+    if (decided.picked === null && asking) {
+      sentCmd.hidden = true
+      pickupWait.hidden = false
+      return
+    }
     if (decided.picked === true) {
       // NOTHING TO RUN, and so nothing offered. This is the whole point of
       // asking: the command used to appear here on every single ending, which
       // taught the reader it was decoration.
       sentCmd.hidden = true
       decidedNote.textContent += ' Claude picked this up — there is nothing to run.'
+      closeWhenDone()
       return
     }
     // THE HAND-OFF SURVIVES THE ENDING — but only where there is something
@@ -2318,6 +2681,9 @@ a.ticket:hover { border-color: var(--accent); }
           // command here unconditionally — the same sentence whether a session
           // was waiting to claim the pass or nothing was — because it had no
           // way to find out. It has one now.
+          // Set BEFORE the draw, so the first render of the decided panel is
+          // already the waiting shape rather than the pessimistic one.
+          asking = true
           markDecided(verdict, '/spec-reviewed ' + code, null)
           watchPass(code, verdict)
         } else {
@@ -2475,6 +2841,10 @@ a.ticket:hover { border-color: var(--accent); }
     var url = location.pathname + '?pass=' + encodeURIComponent(code)
 
     function stop(picked) {
+      // Every exit from the poll comes through here — claimed, out of rounds,
+      // a server that stopped answering — so this is the one place the spinner
+      // can be retired without listing the ways it might end.
+      asking = false
       markDecided(verdict, '/spec-reviewed ' + code, picked)
     }
 
@@ -2781,6 +3151,67 @@ a.ticket:hover { border-color: var(--accent); }
     ask()
   }
 
+  /**
+   * TEXT STILL IN AN EDITOR — the one thing on this page a verdict destroys.
+   *
+   * Typing in the box is not a note; `Add note` is. So a reader who writes three
+   * lines and then presses a verdict sends a pass that does not contain them,
+   * `drawDecided` takes the diff away, and the text goes with it. Nothing said
+   * so, and there is nothing to go back to.
+   *
+   * WARNED, NOT REFUSED, and the distinction is the whole design. Discarding it
+   * is often exactly what the reader means — half a sentence, a note they
+   * thought better of — and this page makes ONE refusal on purpose (an open
+   * note blocks a committing verdict, mirroring `judgeVerdict`) and must not
+   * grow a second one it invented. So the first press says what would be lost
+   * and sends nothing; the same press again sends.
+   *
+   * THE CONFIRMATION IS OF WHAT THE READER WAS SHOWN, which is why the text
+   * itself is remembered and not just the verdict. Otherwise a warning raised
+   * over one note would silently carry away a second one written after it.
+   */
+  var warned = null
+
+  function unsentEditors() {
+    var out = []
+    Array.prototype.forEach.call(document.querySelectorAll('.note-input'), function (b) {
+      if (String(b.value || '').trim()) out.push(b)
+    })
+    return out
+  }
+
+  function clearWarn() {
+    warned = null
+    if (!verdictWarn) return
+    verdictWarn.hidden = true
+    verdictWarn.textContent = ''
+  }
+
+  function mayLose(verdict) {
+    var open = unsentEditors()
+    // Whitespace is not unfinished work, and neither is an editor opened and
+    // left empty. A page that stopped on those would teach the reader to press
+    // everything twice, which is how a warning stops being read.
+    if (!open.length) { clearWarn(); return true }
+    var text = open.map(function (b) { return b.value }).join('\u0000')
+    if (warned && warned.verdict === verdict && warned.text === text) { clearWarn(); return true }
+    warned = { verdict: verdict, text: text }
+    if (verdictWarn) {
+      verdictWarn.hidden = false
+      verdictWarn.textContent =
+        open.length + (open.length === 1 ? ' note is' : ' notes are') +
+        ' still in the box and not added. Press “Add note” to keep ' +
+        (open.length === 1 ? 'it' : 'them') + ', or press “' + (LABELS[verdict] || verdict) +
+        '” again to send without ' + (open.length === 1 ? 'it' : 'them') + '.'
+    }
+    // Take the reader to the first one. The bar is at the foot of the page and
+    // the editor can be a screen away, so a line naming a note they cannot see
+    // is only half an answer.
+    open[0].scrollIntoView()
+    open[0].focus()
+    return false
+  }
+
   Object.keys(verdictBtns).forEach(function (verdict) {
     verdictBtns[verdict].addEventListener('click', function () {
       // A disabled or hidden button does not fire in a browser; the guard is
@@ -2788,6 +3219,7 @@ a.ticket:hover { border-color: var(--accent); }
       // facts rather than styles — a verdict this render never offered must not
       // be reachable by dispatching at it.
       if (verdictBtns[verdict].disabled || verdictBtns[verdict].hidden) return
+      if (!mayLose(verdict)) return
       send(verdict)
     })
   })

package/assets/rules/spec-reports.md

@@ -201,6 +201,16 @@ escape hatch is what let a whole class of runs go on asking questions nobody was
 listening for. Where a watch is unavailable the wait is the turn ending, which
 every harness can do.
 
+**Run it under a persistent watch primitive where the harness has one** — one
+that lives for the whole session and whose deliberate stop is an explicit act
+(Claude Code: the `Monitor` tool with `persistent: true`, ended by `TaskStop`).
+A backgrounded shell is reclaimed on a long idle — that is the death the next
+paragraph recovers from — where a session-length primitive is designed to
+survive it. Where the harness has none, background the command exactly as
+before. The engine's wait stays the one watcher either way: its heartbeat goes
+to stderr, so stdout carries only the start line and the arrival, and the exit
+ends the watch.
+
 **A watch that dies is re-armed, silently, on the same window.** A backgrounded
 wait does not always survive a long idle: three sessions lost theirs over one
 lunch break, and two in another were killed at 43 and 30 minutes. So a wait that
@@ -212,11 +222,17 @@ would strand exactly that pass.
 **Say nothing when you do it.** Nothing happened and the window is unchanged; a
 line on every death turns a working loop into a stream of non-events.
 
-**An operator who stopped it is not a death.** Re-arming over a deliberate stop
-makes the wait unstoppable, which is worse than a wait that stops. Where the two
-cannot be told apart, treat it as deliberate and leave it
-(`.claude/rules/negative-checks.md` rule 4): the cost of being wrong is one
-`/spec-reviewed`, against a loop nobody can break.
+**An operator who stopped it is not a death** — re-arming over a deliberate
+stop makes the wait unstoppable, which is worse than a wait that stops. But a
+deliberate stop is an **explicit act with positive evidence**: this session
+called TaskStop, or the operator said to stop waiting. A bare killed-task
+notification carries neither and is read as a **death**. This clause once said
+to treat the ambiguous kill as deliberate, and that safe branch ate the
+recovery whole: every observed kill was the harness reclaiming an idle shell
+and none was a person, so the case it protected against does not occur — while
+the `/spec-reviewed` it charged was paid on every idle review. The deliberate
+stop is the positive signal, so its absence is what a death looks like
+(`.claude/rules/negative-checks.md` rule 1).
 
 **It is bounded by the age of the window, not by a count of retries.** Keep
 re-arming while the window is younger than **12 hours**, then stop. A count means

package/assets/skills/no-spec/SKILL.md

@@ -113,7 +113,9 @@ because writing it means reading the diff, and that spend is the user's call.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <name> --since <the timestamp>

package/assets/skills/spec/SKILL.md

@@ -396,7 +396,9 @@ the verdict — and the reader's conclusion is about what the page showed them.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <the timestamp>

package/assets/skills/spec-bug/SKILL.md

@@ -218,12 +218,25 @@ The fix is green and nothing is committed yet. That is the moment the page is
 about, so render it now — **after** the tests pass and **before** the commit:
 
 ```
-skitterspec spec-env review <spec>
+skitterspec spec-env review <spec> --buttons fix
 ```
 
 **This is free.** The engine reads git and splices the patches into a template;
 the diff never passes through you, so a 266KB patch costs nothing.
 
+**`--buttons fix` drops `Commit & Continue`**, because a fix that took one pass
+has no next phase and that verb names work which does not exist. The page has a
+guard for this and cannot see these specs: it dims the button on
+`data.phases.hasNextPhase === false`, and `readPhases` returns `null` for a
+folder with no phase files — deliberately, since that is also a legacy layout
+whose phases live inline in the overview. The set is the caller's declaration
+about the work, so the declaration is here.
+
+**Where §5 split the fix into phase files, drop the flag.** Then a next phase
+genuinely exists, `/spec-next` will build it, and the committing set is right —
+so take the default by passing no `--buttons` at all, exactly as `/spec-next`
+does.
+
 **Then arm the gate**, so the fix now owes a verdict:
 
 ```
@@ -232,8 +245,9 @@ skitterspec spec-env review arm <spec>
 
 **Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
 than reading a second copy here: note the moment, run
-`skitterspec spec-env review wait <spec> --since <that moment>` in the
-background, end your turn, and let `--claim-since` pick the one pass that
+`skitterspec spec-env review wait <spec> --since <that moment>` under the
+harness's persistent watch primitive where one exists (else in the
+background), end your turn, and let `--claim-since` pick the one pass that
 arrived inside the window. **Do not compose a watcher**, and do not give the
 wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
 The banner it describes is what this skill emits in place of a `Review` row,

package/assets/skills/spec-diff/SKILL.md

@@ -385,6 +385,16 @@ uncommitted work stays behind in the worktree — so what went live would be the
 `review.commitWith` exactly as §2a does (do not restate its rules here), then
 take the instance. The reader has not approved anything by pressing it.
 
+**The gate permits that one commit, and nothing more.** A phase that ended
+armed the gate, so the commit this action needs is the very commit the gate
+refuses — which made the press unachievable in the only state it is offered in.
+Claiming a `live-on` pass therefore records a **permit** on the gate, bound to
+the worktree's HEAD, and the commit hook honours it. It dies the moment that
+commit lands, so a second one is refused exactly as before, and the gate stays
+**armed** throughout: the phase still owes a verdict and `/spec-next` still
+refuses to build the next one. Nothing is typed to get it — if a commit here is
+still refused, that is the ordinary gate and the exits are the ordinary three.
+
 **It re-renders `--branch` afterwards**, because the working view is now empty:
 the commit just happened, and the branch range is what still answers "what am I
 looking at". §4's clean-tree fallback reaches the same place on its own, so
@@ -614,7 +624,9 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
 
 1. **Note the moment**, as an ISO timestamp, before you start. That instant is
    the entire scope of what may be claimed without a person naming it.
-2. **Run the engine's wait in the background, and end the turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <timestamp>

package/assets/skills/spec-hotfix/SKILL.md

@@ -240,12 +240,18 @@ The fix is green and nothing is committed yet. That is the moment the page is
 about, so render it now — **after** the tests pass and **before** the commit:
 
 ```
-skitterspec spec-env review <spec>
+skitterspec spec-env review <spec> --buttons fix
 ```
 
 **This is free.** The engine reads git and splices the patches into a template;
 the diff never passes through you, so a 266KB patch costs nothing.
 
+**`--buttons fix` drops `Commit & Continue`**, because a hotfix has no next
+phase for `/spec-next` to build and that verb would name work which does not
+exist. There is no exception to this the way there is in `/spec-bug`: a hotfix
+is a single pass against a released tag by construction, so it never has phase
+files and the flag is unconditional here.
+
 **Then arm the gate**, so the fix now owes a verdict:
 
 ```

package/assets/skills/spec-next/SKILL.md

@@ -436,7 +436,9 @@ reading — and that is the gap the whole gate exists to close.
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Run the engine's wait in the background, and end your turn:**
+2. **Run the engine's wait, and end your turn** — under the harness's
+   persistent watch primitive where one exists, else in the background
+   (`.claude/rules/spec-reports.md` carries the preference):
 
    ```
    skitterspec spec-env review wait <spec> --since <the timestamp>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.1.0",
+  "version": "22.3.0",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -131,6 +131,8 @@ const {
   disarmGate,
   gateState,
   markGateOffered,
+  grantPermit,
+  permitHonoured,
 } = require('./env/review.js')
 const {
   CHECKS_VERSION,
@@ -856,9 +858,42 @@ function specEnvNospec(dir, config, name, flags = {}) {
 }
 
 function specEnvUp(dir, config, specArg, flags = {}) {
-  const spec = resolveSpecWithWorktree(dir, config, specArg)
   const docs = flags.docs === true
 
+  // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
+  // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
+  // phase 2), so the name resolves to nothing at exactly the moment this runs.
+  // It opens only on a positive signal, all three parts: the not-found refusal
+  // itself (by code, never by message), `--docs`, and a spec-shaped name — so a
+  // typo'd `up` without the flag, or with a name no spec could have, refuses
+  // exactly as before. Worktree mode only: in checkout mode `/spec` writes
+  // where the session stands and there is nothing to provision first.
+  let spec
+  let authoring = false
+  try {
+    spec = resolveSpecWithWorktree(dir, config, specArg)
+  } catch (err) {
+    const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
+    if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
+      throw err
+    }
+    // Record first, then plan — the same order `nospec` keeps, for the same
+    // reason: the record is what makes the name resolvable (a bare `resolve`
+    // in the fresh worktree must name this spec before its folder exists), so
+    // a caller that runs the printed commands must never own a worktree the
+    // engine cannot name. `spec: true` is what makes the record resolve with
+    // the spec's own type and slug rather than as `/no-spec` work.
+    const beforeAuth = readRegistry(dir, config)
+    const resolved = resolveSpecless(specArg, dir, config, { spec: true })
+    writeRegistry(
+      dir,
+      config,
+      recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
+    )
+    spec = resolved
+    authoring = true
+  }
+
   // Checkout mode: the branch is built in the primary checkout, so none of the
   // worktree machinery below applies — no slot, no trust entry and no bootstrap.
   // Handled first precisely so none of that runs by accident.
@@ -898,8 +933,13 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   const upGit = gitReader(dir)
   const upStatus = upGit(['status', '--porcelain'])
   const upDirtyPaths = dirtyPaths(upGit)
-  const upOnFork = specOnForkPoint(dir, upGit, spec)
-  const upSpecUntracked = specIsUntracked(dir, upGit, spec)
+  // An authoring run does not ask whether the spec is on the fork point — it is
+  // known to be nowhere, and that is the healthy state of the lane, not the
+  // "would fork without the spec it is for" refusal. `onFork: undefined` is the
+  // gate's cannot-tell branch, which allows (negative-checks rule 4). The
+  // untracked read is skipped the same way: there is no folder to ask about.
+  const upOnFork = authoring ? { onFork: undefined, foundOn: null } : specOnForkPoint(dir, upGit, spec)
+  const upSpecUntracked = authoring ? false : specIsUntracked(dir, upGit, spec)
 
   // Trust the shared worktree root so edits into the freshly-provisioned worktree
   // don't prompt. One absolute entry (the root) covers every spec; self-heals on
@@ -988,6 +1028,12 @@ function specEnvUp(dir, config, specArg, flags = {}) {
   if (plan.docs) {
     out.push('  docs:      documents only — no setup commands, no docker')
   }
+  // Positive, so an operator reading the plan knows the missing spec folder is
+  // the lane working rather than something the engine failed to find.
+  if (authoring) {
+    out.push('  authoring: no spec document yet — /spec writes it in the worktree')
+    out.push(`  recorded:  added to ${config.registry} until the spec is written`)
+  }
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
@@ -2310,6 +2356,22 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
         reason: `this command is not running inside ${target.spec.folder}'s worktree`,
         gate: judged.gate,
       }
+    } else if (permitHonoured(judged.gate, { head: gitReader(target.spec.worktreePath)(['rev-parse', 'HEAD']) })) {
+      // A PRECONDITION, NOT AN ANSWER. The operator pressed `live-on`, whose
+      // handling commits the phase before `live take` will touch it, so this
+      // commit is the thing they asked for rather than a way around them. The
+      // permit is bound to the HEAD it was granted against, so it covers this
+      // one commit and dies the moment it lands — `grantPermit` carries the
+      // reasoning.
+      //
+      // `permitted` rather than `clear`: the obligation is untouched and the
+      // word should not say otherwise. It exits 0 like every other non-`armed`
+      // state, and only `armed` ever sets a non-zero status.
+      judged = {
+        state: 'permitted',
+        reason: `a claimed ${judged.gate.permit.for} press needs this commit first`,
+        gate: judged.gate,
+      }
     }
   }
 
@@ -2341,6 +2403,10 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
           armedAt: judged.gate ? judged.gate.armedAt : null,
           phase: judged.gate ? judged.gate.phase : null,
           required: config.review.required,
+          // Absent stays absent, so a gate with no permit is byte-identical to
+          // what it was before this existed. Present, it is the visible form of
+          // the one commit an armed gate will not refuse.
+          ...(judged.gate && judged.gate.permit ? { permit: judged.gate.permit } : {}),
           // Absent stays absent: only an `armed` gate has a way out to declare,
           // and every cannot-tell state carries none.
           ...(judged.offer ? { offer: judged.offer } : {}),
@@ -2361,6 +2427,14 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
     )
   } else if (judged.state === 'clear') {
     process.stdout.write(`spec-env review gate: ${target.spec.folder} owes nothing — ${judged.reason}\n`)
+  } else if (judged.state === 'permitted') {
+    // Says what it let through AND what is still owed, in that order. A line
+    // that only said "permitted" would read as the gate having been cleared,
+    // which is the one thing this state does not do.
+    process.stdout.write(
+      `spec-env review gate: ${target.spec.folder} — ${judged.reason}.\n` +
+        '  the phase still owes a verdict; this permits the commit and nothing else.\n',
+    )
   } else {
     process.stdout.write(
       `spec-env review gate: cannot tell — ${judged.reason}.\n` +
@@ -2915,6 +2989,47 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
       action: parsed.action || null,
     }
     merged = { accepted: claimed.accepted, unaccepted: claimed.unaccepted, comments: claimed.comments }
+
+    // THE ONE COMMIT THIS ACTION DEPENDS ON, permitted here because the press
+    // is the positive signal. `live take` refuses a dirty worktree, so
+    // `/spec-diff` §2b commits the phase first — and the gate this phase armed
+    // would otherwise deny exactly that commit, which made the button
+    // unachievable in the only state it is offered in.
+    //
+    // IT IS NOT A VERDICT AND CLEARS NOTHING. The gate stays armed, so
+    // `/spec-next` still refuses the next phase; `grantPermit` is where the
+    // three signals it needs are documented.
+    //
+    // Read from the SPEC'S WORKTREE rather than `readFrom`, which follows the
+    // work to the primary checkout while a spec is live. The gate guards the
+    // worktree, so that is the tree whose HEAD the permit is bound to — and a
+    // spec that is already live has nothing to put live anyway.
+    //
+    // Best-effort throughout: an unreadable tree, an unwritable sidecar, a gate
+    // we could not parse all grant nothing and say nothing. Being wrong that
+    // way costs the refusal that already happens today; being wrong the other
+    // way is a hole in the one thing here that refuses.
+    if (claimed.action) {
+      const wtGit = gitReader(spec.worktreePath)
+      const status = wtGit(['status', '--porcelain'])
+      const head = wtGit(['rev-parse', 'HEAD'])
+      const gateRead = readGate(out, spec.folder)
+      if (!gateRead.corrupt) {
+        const granted = grantPermit(gateRead.gate, {
+          at: new Date().toISOString(),
+          action: claimed.action,
+          head,
+          dirty: status !== null && status.length > 0,
+        })
+        if (granted.granted) {
+          try {
+            writeGate(out, granted.gate)
+          } catch {
+            /* the refusal it would have lifted is the one that happens anyway */
+          }
+        }
+      }
+    }
   }
 
 

package/src/env/resolve.js

@@ -488,17 +488,26 @@ function assertPrimaryOnMain(config, git) {
  */
 function resolveSpecless(name, dir, config, entry = {}) {
   const { repo, repoSlug } = repoInfo(dir)
-  const slug = name
+  // AN AUTHORING RECORD RESOLVES AS THE SPEC IT WILL BE. `spec: true` marks a
+  // record written by `up --docs` for a spec not written yet (the `/spec`
+  // authoring lane), so type and slug come from the name's own prefix — the
+  // branch and worktree it answers with MUST equal what the written spec will
+  // later resolve to, or the confirm step lands in one tree and the documents
+  // in another. A plain `/no-spec` record keeps the whole name as its slug,
+  // byte-identical to before.
+  const authored = entry && entry.spec === true
+  const slug = authored ? splitPrefix(name).slug : name
   const tokens = { repo, repoSlug, slug }
   const spec = {
     folder: name,
     bucket: null,
     path: null,
-    type: (entry && entry.type) || 'chore',
+    type: authored ? splitPrefix(name).type : (entry && entry.type) || 'chore',
     slug,
     stack: 'worktree',
     baseRef: null,
     specless: true,
+    unwritten: authored,
   }
   const branch = (entry && entry.branch) || branchFor(spec, config)
   const worktreeRoot = expandTokens(config.worktree.root, tokens)
@@ -532,10 +541,14 @@ function resolveSpec(specArg, dir, config, opts = {}) {
     }
     // Name the roots we looked under: the usual cause is a spec that only exists
     // on its own branch, and the message should say where we didn't find it.
-    throw new Error(
+    // The code is what lets `up --docs` catch exactly this refusal and open the
+    // authoring lane — matching on the message would make its wording API.
+    const err = new Error(
       `spec not found under specs/**: ${specArg} ` +
         `(searched: ${[...preferDirs, dir, ...searchDirs].join(', ')})`,
     )
+    err.code = 'SPEC_NOT_FOUND'
+    throw err
   }
 
   const { type, slug } = splitPrefix(found.folder)
@@ -643,7 +656,14 @@ function allSpecs(dir, config, worktreePaths, specless = {}) {
   // not. Leaving them out is what would make a `/no-spec` worktree invisible to
   // `status` and to every bare resolution — the outcome decision 7 rejected for
   // a plain git branch, arrived at by omission instead.
+  //
+  // A FOLDER SHADOWS ITS OWN RECORD. An authoring record (`up --docs` on an
+  // unwritten spec) shares its name with the folder `/spec` then writes, and
+  // once that folder exists it is the answer — listing the record beside it
+  // would show one spec twice.
+  const collected = new Set(specs.map((s) => s.folder))
   for (const name of Object.keys(specless).sort()) {
+    if (collected.has(name)) continue
     const spec = resolveSpecless(name, dir, config, specless[name])
     specs.push({
       folder: spec.folder,

package/src/env/review.js

@@ -301,6 +301,21 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
     files.push({ ...f, additions, deletions, binary, whole, noise: noiseOf(f.path), patch })
   }
 
+  // NOTHING TO BE BOOKKEEPING BESIDE. The flag is relative — a spec's own
+  // checkbox edits are not what anyone came to read WHEN THERE IS A DIFF TO
+  // READ — and applying it with no relative left folds the whole change away,
+  // rendering a page whose subject is invisible until the reader happens to
+  // click a file in the tree. A change that is entirely bookkeeping IS the
+  // change, so it opens.
+  //
+  // WHAT WOULD FOOL A LOOSER VERSION OF THIS: one source file in the diff. The
+  // test is EVERY file, so the moment there is something else to read the
+  // margin notes go back to being margin notes — which is the flag's whole
+  // point and has its own stays-silent test.
+  if (files.length && files.every((f) => f.noise)) {
+    for (const f of files) f.noise = false
+  }
+
   // Content hashes and the stored review state, folded on before the totals so
   // the page and `--json` see one shape.
   const store = notes || emptyNotes(spec.folder)
@@ -774,8 +789,27 @@ const COMMITTING = ['commit', 'commit-continue', 'commit-start', 'commit-land']
  * 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.
+ *
+ * `fix` is the set for a SINGLE-PASS fix — a bug or hotfix spec whose whole
+ * repair is one `## Fix` list and no phase files. It is `committing` minus
+ * `commit-continue`, because there is no next phase for `/spec-next` to build:
+ * the page used to offer that verb anyway, the press committed correctly, and
+ * `/spec-next` then refused with nothing to do.
+ *
+ * THE PAGE ALREADY HAS A GUARD FOR THIS AND IT CANNOT SEE THESE SPECS. It dims
+ * the button on `data.phases.hasNextPhase === false`, and `readPhases` returns
+ * `null` for a folder with no phase files — deliberately, because that is also
+ * a legacy layout whose phases live inline in the overview. So the caller says
+ * it instead, which is what the `buttons` parameter is for.
+ *
+ * REUSING `refresh` WAS THE OBVIOUS MOVE HERE TOO, and is wrong for the reason
+ * above one line up rather than the one above the paragraph: the three buttons
+ * are identical, but `refresh` means a re-validated spec DOCUMENT and this is a
+ * render of code. The word is stored in the render record and read back by the
+ * serve daemon, so one name covering two renders would be ambiguous exactly
+ * where it is used to decide something.
  */
-const BUTTON_SETS = ['committing', 'midrun', 'authoring', 'refresh', 'nospec']
+const BUTTON_SETS = ['committing', 'midrun', 'authoring', 'refresh', 'nospec', 'fix']
 const DEFAULT_BUTTON_SET = 'committing'
 
 /**
@@ -1415,7 +1449,7 @@ function reviewGatePath(outPath) {
 }
 
 function emptyGate(specFolder) {
-  return { version: GATE_VERSION, spec: specFolder, armed: false, armedAt: null, phase: null, offeredAt: null, log: [] }
+  return { version: GATE_VERSION, spec: specFolder, armed: false, armedAt: null, phase: null, offeredAt: null, permit: null, log: [] }
 }
 
 /**
@@ -1447,6 +1481,11 @@ function readGate(outPath, specFolder) {
         // 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,
+        // Same rule as `offeredAt`: a sidecar written before this existed reads
+        // as no permit, which is the state that refuses. Anything that is not
+        // an object is read as absent rather than trusted — this file is the
+        // one thing standing between an armed gate and a commit.
+        permit: parsed.permit && typeof parsed.permit === 'object' ? parsed.permit : null,
         log: Array.isArray(parsed.log) ? parsed.log : [],
       },
       corrupt: false,
@@ -1536,7 +1575,13 @@ function armGate(gate, { at, phase = null }) {
   if (gate.armed && gate.phase === phase) return gate
   // 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 }
+  //
+  // AND A NEW OBLIGATION STARTS WITH NO WAY PAST IT. A permit is granted
+  // against one arming — the commit one pressed `live-on` depends on — so
+  // carrying it into the next phase would hand that phase a hole nobody asked
+  // for. It is bound to a HEAD as well, so this is belt and braces; both are
+  // cheap and only one of them has to hold.
+  return { ...gate, armed: true, armedAt: at, phase, offeredAt: null, permit: null }
 }
 
 /**
@@ -1559,6 +1604,82 @@ function markGateOffered(gate, { at }) {
   return { gate: { ...gate, offeredAt: at }, marked: true }
 }
 
+/**
+ * The actions whose handling REQUIRES a commit in the spec's own worktree.
+ *
+ * One, and the list exists so the answer is looked up rather than remembered.
+ * `allow-network` and `allow-remote` write a config key and commit nothing, so
+ * neither has a precondition to permit — and a permit granted for an action
+ * that never commits is a hole with no commit to close it.
+ */
+const PERMITTED_ACTIONS = ['live-on']
+
+/**
+ * Record that ONE commit is a claimed action's mechanical precondition. Pure.
+ *
+ * WHY THIS EXISTS. The page offers `live-on` only on a non-midrun render, which
+ * is what a finished phase produces — and a finished phase arms the gate. The
+ * action is deliberately not a verdict, so it clears nothing; but `live take`
+ * refuses a dirty worktree, so handling the press means committing the phase
+ * first. That commit is a `git commit` in the spec's own worktree, which is
+ * exactly what the armed gate denies. Without this the button could never
+ * succeed in the only state it was ever offered in.
+ *
+ * WHAT IT IS NOT: a verdict, a skip, or a lift. The gate stays `armed`, so
+ * `/spec-next` still refuses the next phase and the obligation is still
+ * discharged by a committing verdict or a recorded skip and by nothing else.
+ * This widens one commit, not the guard.
+ *
+ * THREE POSITIVE SIGNALS, all required (`.claude/rules/negative-checks.md`
+ * rule 1), and every cannot-tell grants nothing:
+ *
+ * - The gate is ARMED. Nothing is refusing otherwise, so there is nothing to
+ *   permit past — and a permit written onto a clear gate would sit there
+ *   waiting for the next phase to arm.
+ * - The action is one that COMMITS. See `PERMITTED_ACTIONS` above.
+ * - The worktree is DIRTY, and a `head` was readable. A clean tree has no
+ *   precondition, so granting one would leave a permit lying around to cover
+ *   some later commit made for an entirely different reason.
+ *
+ * BOUND TO A HEAD, which is what makes it exactly one commit rather than a
+ * standing permission. `permitHonoured` compares the worktree's HEAD against
+ * the one recorded here, so the permit dies the instant its commit lands — and
+ * a commit that FAILED (red tests, a rejected message) leaves HEAD alone, so
+ * the retry is still covered. Spending it on the check instead would have made
+ * that retry a refusal.
+ */
+function grantPermit(gate, { at, action, head, dirty }) {
+  if (!gate || !gate.armed) return { gate, granted: false }
+  if (!PERMITTED_ACTIONS.includes(action)) return { gate, granted: false }
+  if (dirty !== true || !head) return { gate, granted: false }
+  return {
+    gate: { ...gate, permit: { for: action, at, head, phase: gate.phase === undefined ? null : gate.phase } },
+    granted: true,
+  }
+}
+
+/**
+ * Does this gate's permit cover a commit happening at `head`? Pure.
+ *
+ * WHAT WOULD FOOL THIS: nothing here checks WHERE the commit is running. That
+ * is deliberate — the caller has already established that it is inside this
+ * spec's own worktree, which is the same positive signal `--for-command` wants
+ * before it refuses at all, and duplicating it here would be a second copy free
+ * to drift from the first.
+ *
+ * A permit for an action not in `PERMITTED_ACTIONS` is ignored rather than
+ * trusted. The sidecar is gitignored and hand-editable, and an older engine
+ * meeting a newer word should refuse, not guess.
+ */
+function permitHonoured(gate, { head }) {
+  if (!gate || !gate.armed) return false
+  const permit = gate.permit
+  if (!permit || typeof permit !== 'object') return false
+  if (!PERMITTED_ACTIONS.includes(permit.for)) return false
+  if (!permit.head || !head) return false
+  return permit.head === head
+}
+
 /**
  * Disarm it, and say how. Pure.
  *
@@ -1571,7 +1692,10 @@ function disarmGate(gate, { at, by, reason = null }) {
   if (!gate.armed) return { gate, logged: false }
   const log = Array.isArray(gate.log) ? gate.log.slice() : []
   log.push({ by, at, phase: gate.phase === undefined ? null : gate.phase, reason })
-  return { gate: { ...gate, armed: false, armedAt: null, phase: null, log }, logged: true }
+  // The permit goes with the obligation it was a way through. Nothing refuses
+  // once the gate is clear, so a surviving one could only ever apply to the
+  // next phase's arming — which is not what anybody pressed.
+  return { gate: { ...gate, armed: false, armedAt: null, phase: null, permit: null, log }, logged: true }
 }
 
 /**
@@ -2358,6 +2482,9 @@ module.exports = {
   disarmGate,
   gateState,
   markGateOffered,
+  PERMITTED_ACTIONS,
+  grantPermit,
+  permitHonoured,
   GATE_BYPASS_OFFER,
   GATE_BYPASS_REASON,
   gateForPage,

package/src/env/serve.js

@@ -205,13 +205,47 @@ ${body}
  * answer — including the ones we cannot work out. Never throws: a page is a
  * convenience and a git that will not read is not evidence of anything.
  */
+/**
+ * Project bookkeeping, as opposed to somebody's unfinished work.
+ *
+ * `specs/.core/` holds the project's own configuration and whatever a tracker
+ * provider writes beside it — a push snapshot, most often. None of it is a
+ * spec's documents and none of it is code, so finding it in an authoring tree
+ * says nothing about whether a spec is being written there.
+ *
+ * WHAT WOULD FOOL A WIDER VERSION OF THIS: anything outside `specs/`. A source
+ * file in the tree IS evidence that the tree is being used for something else,
+ * and that answer must stay unchanged — see the stays-silent test.
+ */
+function isProjectBookkeeping(p) {
+  return String(p).startsWith('specs/.core/')
+}
+
 function docsWorktree(wt, spec, config) {
   if (!spec || spec.bucket !== 'backlog') return null
   const paths = dirtyPaths(trimmedGitReader(wt))
   // Cannot tell — not "no documents".
   if (paths === null) return null
   const { owned, foreign } = classifyDirtyTree(spec, paths, config)
-  if (!owned.length || foreign.length) return null
+  // A TRACKER SNAPSHOT IS NOT SOMEBODY ELSE'S WORK, and requiring a
+  // foreign-free tree cost the whole page for the commonest authoring tree
+  // there is. The linking push writes `specs/.core/linear-base/<ID>.base.json`
+  // into this tree moments before the page is opened, and a project that never
+  // declared it in `spec.companionPaths` — which is the default — has one
+  // foreign path by construction. The view fell through to `worktree`, where
+  // every `specs/**` path is bookkeeping: seven files changed, seven folded
+  // away, nothing on screen.
+  //
+  // What the foreign test is actually for survives untouched: real work sitting
+  // in the tree still disqualifies it, because that is a tree being used for
+  // something other than writing this spec.
+  //
+  // THE RENDERED FILE SET DOES NOT WIDEN WITH IT. The page still shows `owned`,
+  // which is what `--docs` showed from the CLI — a served page that listed a
+  // file the run's own report did not would be a different page from the one
+  // the reader was told about.
+  const intruders = foreign.filter((p) => !isProjectBookkeeping(p))
+  if (!owned.length || intruders.length) return null
   return { owned }
 }
 
@@ -429,10 +463,20 @@ function receivePass(dir, config, spec, blob) {
  * `nospec`; a phase in a worktree is `committing`. Those three are exactly the
  * sets that describe what the work IS, so they are read off what the work is.
  *
- * THE RECORD ANSWERS WHETHER THE RUN HAD FINISHED, which no tree can show.
- * `midrun` and `refresh` exist for that — one offers `Continue` in place of the
- * committing pair, the other drops the start verdict — and only the caller that
- * rendered knew. So they, and nothing else, are taken from the record.
+ * THE RECORD ANSWERS WHAT NO TREE CAN SHOW, which is two things rather than
+ * one. `midrun` and `refresh` answer whether the run had FINISHED — one offers
+ * `Continue` in place of the committing pair, the other drops the start
+ * verdict. `fix` answers whether the work was ever PHASED: a single-pass bug or
+ * hotfix has no phase files, and a folder with no phase files is also a legacy
+ * inline-phase layout, so the tree cannot tell the two apart and `readPhases`
+ * returns `null` for both. Only the caller that rendered knew, in all three
+ * cases. So they, and nothing else, are taken from the record.
+ *
+ * LEAVING `fix` OFF THIS LIST IS THE BUG IT WAS ADDED TO FIX, wearing the
+ * daemon's clothes: the CLI render would drop `Commit & Continue` and every
+ * SERVED re-render of the same URL would fall through to the tree's
+ * `committing` family and hand it straight back. The first page anyone opens
+ * looks right, and each refresh is wrong.
  *
  * WHICH MAKES THE RECORD NARROWING-ONLY. A word it does not recognise, a word
  * that would WIDEN the offer, an unreadable file, no file at all: every one of
@@ -444,7 +488,7 @@ function receivePass(dir, config, spec, blob) {
  * so every `/no-spec` page served over http offered to put nothing in flight,
  * and the pass came back naming a verdict its own skill could not act on.
  */
-const NARROWING_SETS = ['midrun', 'refresh']
+const NARROWING_SETS = ['midrun', 'refresh', 'fix']
 
 function buttonsForView(viewKind, spec, recorded) {
   if (NARROWING_SETS.includes(recorded)) return recorded