@skitterbyte/skitterspec 19.0.0 → 20.0.0

package/assets/review/page.html

@@ -411,20 +411,103 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   padding: .5rem;
 }
 .copy-out[hidden] { display: none; }
-.context { margin: 0 0 1rem; padding: .75rem .9rem; border: 1px solid var(--line); border-radius: 6px; background: var(--panel, transparent); }
-.context h3 { font-size: .78rem; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: .9rem 0 .35rem; }
+/* THE REVIEW, ONCE IT IS OVER. A verdict that has actually been handed over
+   ends the page: the diff fades out and what you decided takes its place. The
+   fade is a transition on a class rather than a timer, so nothing depends on
+   JavaScript finishing, and `Show the diff anyway` brings it back — read-only,
+   with the buttons dead. */
+.reviewable { transition: opacity .35s ease; }
+.is-decided .reviewable { display: none; }
+.is-decided.show-diff .reviewable { display: block; opacity: .75; }
+.is-decided.show-diff .reviewable:hover { opacity: 1; }
+/* Bringing the diff back must not resurrect a section that was hidden for its
+   own reasons — a spec with no context ships `#context` hidden, and the rule
+   above would have shown an empty panel. The second selector is there for
+   specificity: `.is-decided.show-diff .reviewable` outranks a bare
+   `.reviewable[hidden]`. */
+.reviewable[hidden],
+.is-decided.show-diff .reviewable[hidden] { display: none; }
+
+.decided {
+  margin: 0 0 1.25rem;
+  padding: 1.1rem 1.2rem;
+  border: 1px solid var(--line);
+  border-left: 4px solid var(--accent);
+  border-radius: 10px;
+  background: var(--panel);
+  animation: decided-in .35s ease;
+}
+@keyframes decided-in { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: none; } }
+.decided[hidden] { display: none; }
+.decided-what { margin: 0 0 .35rem; font-size: 1.05rem; font-weight: 650; line-height: 1.4; }
+.decided-note { margin: 0 0 .8rem; color: var(--muted); font-size: .88rem; line-height: 1.5; max-width: 62ch; }
+.decided-note:last-child { margin-bottom: 0; }
+.decided-toggle { font-size: .78rem; }
+
+/* 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
+   1.5 in a tight box, which read as a wall and got skipped. */
+.context {
+  margin: 0 0 1.5rem;
+  padding: 1.1rem 1.3rem;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--panel, transparent);
+}
+.context h3 {
+  font-size: .72rem;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color: var(--muted);
+  font-weight: 650;
+  margin: 1.4rem 0 .5rem;
+}
 .context h3:first-child { margin-top: 0; }
-.context p { margin: 0 0 .5rem; line-height: 1.5; }
+/* A MEASURE. Prose set the full width of a 1400px page is measurably harder to
+   read — the eye loses the line it is returning to. */
+.context p { margin: 0 0 .7rem; font-size: .92rem; line-height: 1.65; max-width: 72ch; }
 .context p:last-child { margin-bottom: 0; }
-.context table { border-collapse: collapse; width: 100%; font-size: .85rem; }
-.context th, .context td { text-align: left; padding: .2rem .5rem .2rem 0; vertical-align: top; }
-.context th { color: var(--muted); font-weight: 600; }
-.context ul { margin: 0; padding-left: 1.1rem; }
-.context li { margin: .15rem 0; line-height: 1.45; }
+.context table { border-collapse: collapse; width: 100%; font-size: .84rem; margin: .2rem 0 .3rem; }
+.context th, .context td { text-align: left; padding: .35rem .8rem .35rem 0; vertical-align: top; }
+.context th {
+  color: var(--muted);
+  font-weight: 600;
+  font-size: .72rem;
+  text-transform: uppercase;
+  letter-spacing: .05em;
+  border-bottom: 1px solid var(--line);
+  padding-bottom: .3rem;
+}
+.context tbody tr + tr td { border-top: 1px solid var(--line); }
+.context ul { margin: 0; padding-left: 1.15rem; max-width: 72ch; }
+.context li { margin: .3rem 0; font-size: .92rem; line-height: 1.6; }
+/* The disclosure is a CONTROL, not a panel. Full-width and boxed, it read as a
+   section header that happened to be clickable. */
+.context-more { margin: .9rem 0 0; }
+.context-more > summary {
+  display: inline-block;
+  width: auto;
+  cursor: pointer;
+  font-size: .78rem;
+  color: var(--muted);
+  padding: .25rem .7rem;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  list-style: none;
+}
+.context-more > summary::-webkit-details-marker { display: none; }
+.context-more > summary:hover { color: var(--accent); border-color: var(--accent); }
+.context-more[open] > summary { margin-bottom: .6rem; }
 .context li.done { color: var(--muted); }
 .context-more > summary { cursor: pointer; color: var(--muted); font-size: .85rem; margin-top: .6rem; }
 .copy-hint { font-size: .8rem; color: var(--muted); margin: .4rem 0 0; }
 .sent-cmd { display: flex; gap: .4rem; align-items: stretch; margin: .4rem 0 0; }
+/* A `display` rule BEATS the browser's own `[hidden] { display: none }`, so
+   every element this page hides in JavaScript needs its own override or the
+   hide silently does nothing. It shipped without one and a finished review kept
+   showing an empty command box. `assets-review` guards the whole class now. */
+.sent-cmd[hidden] { display: none; }
 .sent-cmd-text {
   flex: 1; min-width: 0; font-family: var(--mono, ui-monospace, monospace);
   font-size: .85rem; padding: .35rem .5rem; color: var(--fg);
@@ -437,7 +520,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
 </style>
 </head>
 <body>
-<div class="wrap">
+<div class="wrap" id="wrap">
 <header>
   <h1 id="title"></h1>
   <p class="sub" id="sub"></p>
@@ -459,15 +542,23 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
          engine from the spec's own files — nothing here passed through the
          model, so it is free however large the diff. Absent entirely for a spec
          whose overview cannot be read: the page worked without it before. -->
-    <section class="context" id="context" hidden>
+    <!-- WHAT YOU DECIDED, once the pass has actually been handed over. It sits
+         above everything because on a re-open it is the only thing you need:
+         the review is over, and this says how it ended. -->
+    <section class="decided" id="decided" hidden>
+      <p class="decided-what" id="decided-what"></p>
+      <p class="decided-note" id="decided-note"></p>
+      <button type="button" class="decided-toggle" id="decided-toggle">Show the diff anyway</button>
+    </section>
+    <section class="context reviewable" id="context" hidden>
       <div class="context-why" id="context-why"></div>
       <details class="context-more" id="context-more" hidden>
         <summary id="context-more-summary">More</summary>
         <div id="context-rest"></div>
       </details>
     </section>
-    <div id="review-block">__REVIEW_BLOCK__</div>
-    <div id="files"></div>
+    <div id="review-block" class="reviewable">__REVIEW_BLOCK__</div>
+    <div id="files" class="reviewable"></div>
     <!-- THE VERDICT SITS AT THE END, where reading finishes. It began in the
          header and the first person to use it could not find it: you read a
          350-line diff downward, and the control asking for your conclusion was
@@ -613,6 +704,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // Best effort, both ways. Safari refuses storage on file:// by THROWING, and
   // a review page that fails to render because it could not autosave would be a
   // far worse bug than a lost pass.
+  // What this reader concluded, once it was actually HANDED OVER — never on a
+  // clipboard copy, which is a pass still sitting in the reader's hands.
+  var decided = null
   var STORE_KEY = 'skitterspec-review:' + data.spec + ':' + data.generatedAt
   function save() {
     try {
@@ -622,7 +716,10 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
         accepts[st.file.path] = st.accept
         st.drafts.forEach(function (d) { drafts.push(d) })
       })
-      window.localStorage.setItem(STORE_KEY, JSON.stringify({ seq: seq, accepts: accepts, drafts: drafts, replies: replies }))
+      window.localStorage.setItem(
+        STORE_KEY,
+        JSON.stringify({ seq: seq, accepts: accepts, drafts: drafts, replies: replies, decided: decided }),
+      )
     } catch (e) { /* no storage, or a quota — the pass still works, it just is not saved */ }
   }
   function restore() {
@@ -633,6 +730,10 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     try { saved = JSON.parse(raw) } catch (e) { return }
     seq = saved.seq || 0
     replies = saved.replies || {}
+    // THE DECISION OUTLIVES THE TAB. Keyed to this render like every other
+    // mark, so the next render — the one after the commit — is a live page
+    // again rather than a page that thinks it is finished.
+    if (saved.decided && saved.decided.verdict) decided = saved.decided
     var byPath = {}
     state.forEach(function (st) { byPath[st.file.path] = st })
     Object.keys(saved.accepts || {}).forEach(function (path) {
@@ -1122,7 +1223,15 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // here, and the shared block below follows for free — the same reason the
   // engine keeps a `COMMITTING` list rather than a second condition.
   var COMMITTERS = ['commit', 'commit-continue']
-  var LABELS = { commit: '✓ Commit', 'commit-continue': '✓ Commit & Continue' }
+  // ALL FOUR, because this is now the one place a verdict gets a reader-facing
+  // name: `refresh` relabels only the committing pair, but the decided panel
+  // has to name whichever verdict was actually sent.
+  var LABELS = {
+    commit: '✓ Commit',
+    'commit-continue': '✓ Commit & Continue',
+    changes: '↺ Request changes',
+    discuss: '… Discuss first',
+  }
   var TITLES = {
     commit: 'Commit what you just read, and stop there',
     // Says what it will NOT do: a reader must not press this expecting the
@@ -1133,6 +1242,11 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   var verdictCount = document.getElementById('verdict-count')
   var verdictLog = document.getElementById('verdict-log')
   var copyOut = document.getElementById('copy-out')
+  var wrapEl = document.getElementById('wrap')
+  var decidedBox = document.getElementById('decided')
+  var decidedWhat = document.getElementById('decided-what')
+  var decidedNote = document.getElementById('decided-note')
+  var decidedToggle = document.getElementById('decided-toggle')
   var copyHint = document.getElementById('copy-hint')
   var sentCmd = document.getElementById('sent-cmd')
   var sentCmdText = document.getElementById('sent-cmd-text')
@@ -1164,6 +1278,10 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // the moment the last note goes and a phone tab switch mid-review costs
   // nothing.
   function refresh() {
+    // A decided page is finished. `refresh` runs on every mark and re-enables
+    // the two committing buttons unconditionally, so without this it would undo
+    // the ending every time anything redrew.
+    if (decided) return drawDecided()
     var n = pending()
     var open = openNotes()
     verdictCount.textContent = n
@@ -1204,12 +1322,104 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     save()
   }
 
-  // The last honoured verdict, as history. It is why the page can look
-  // untouched after an approval: the verdict was consumed, not stored.
+  /**
+   * End the review, and say how it ended.
+   *
+   * A verdict that has been handed over is the END of this page's job, and the
+   * page used to carry on as if it were not: the diff stayed, the four buttons
+   * stayed live, and a line of small grey text under them said "Sent." A reader
+   * coming back to that tab has no way to tell a sent review from an unsent
+   * one, and pressing a button again reaches an agent that stopped listening.
+   *
+   * So the diff goes, what was decided takes its place, and the controls die
+   * with a reason on them.
+   */
+  function drawDecided() {
+    if (!decided) return
+    var said = SAID[decided.verdict] || decided.verdict
+    var when = String(decided.at || '').slice(0, 10)
+    decidedBox.hidden = false
+    decidedWhat.textContent = 'You chose: ' + (LABELS[decided.verdict] || decided.verdict)
+    decidedNote.textContent =
+      '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'
+    // EVERY button, not only the committing pair: `refresh` re-enables those two
+    // by design, and a decided page must beat it.
+    Object.keys(verdictBtns).forEach(function (key) {
+      var btn = verdictBtns[key]
+      btn.disabled = true
+      btn.title = 'Already sent — ' + said
+    })
+    verdictCount.textContent = 'Sent — ' + said
+    // ONE STATEMENT, NOT FOUR. The panel, the bar, the history line and the
+    // command box all said the same thing at once. The log line is the panel's
+    // sentence again in smaller type, so it goes.
+    verdictLog.hidden = true
+
+    // THE HAND-OFF SURVIVES THE ENDING — but only where there is something
+    // worth carrying. A code is six digits to transcribe, and the box and its
+    // Copy button exist for exactly that. A bare `/spec-reviewed` is a word the
+    // reader is about to type into the terminal they are already sitting in;
+    // dressing it as a copyable artefact makes the ending look unfinished.
+    if (decided.cmd && /\s/.test(decided.cmd)) {
+      copyHint.hidden = false
+      copyHint.textContent = 'Sent. Run this where Claude is:'
+      showCommand(decided.cmd)
+      return
+    }
+    copyHint.hidden = true
+    sentCmd.hidden = true
+    copyOut.hidden = true
+    if (decided.cmd) {
+      decidedNote.textContent +=
+        ' If Claude was not already waiting, run ' + decided.cmd + ' where it is.'
+    }
+  }
+
+  /** Record a verdict that was actually delivered, and end the page on it. */
+  function markDecided(verdict, cmd) {
+    decided = { verdict: verdict, at: new Date().toISOString(), cmd: cmd || null }
+    save()
+    drawDecided()
+  }
+
+  // A WAY BACK IN, read-only. "It is finished" and "I cannot see what I
+  // approved" are different things, and only the first one is true.
+  decidedToggle.addEventListener('click', function () {
+    var showing = / \bshow-diff\b/.test(' ' + wrapEl.className)
+    wrapEl.className = wrapEl.className.replace(/\s*\bshow-diff\b/g, '') + (showing ? '' : ' show-diff')
+    decidedToggle.textContent = showing ? 'Show the diff anyway' : 'Hide the diff'
+  })
+
+  // How a logged verdict reads. EVERY VERDICT NAMED, and an unknown one says
+  // so: the fallback was `discussed`, which quietly relabelled `commit` — and a
+  // page that tells you a commit was a discussion is worse than one that admits
+  // it does not know the word.
+  var SAID = {
+    approve: 'committed',
+    commit: 'committed',
+    'commit-continue': 'committed, then carried on',
+    changes: 'changes requested',
+    discuss: 'discussed',
+    skip: 'moved on without a verdict',
+  }
+
+  // The last thing that happened here, as history. It is why the page can look
+  // untouched after a commit: the verdict was consumed, not stored. A SKIP is
+  // history of exactly the same kind — it is the recorded decision to move on,
+  // and hiding it would make a skipped review indistinguishable from one that
+  // never ended.
   function drawLog() {
     var last = data.notes && data.notes.lastDecision
+    var skip = data.gate && data.gate.lastSkip
+    // Whichever is more recent. Both are timestamped, and comparing is what
+    // stops an old verdict shadowing a skip taken after it.
+    if (skip && (!last || String(skip.at || '') > String(last.at || ''))) {
+      last = { verdict: 'skip', at: skip.at, note: skip.reason }
+    }
     if (!last) return
-    var said = last.verdict === 'approve' ? 'approved' : last.verdict === 'changes' ? 'changes requested' : 'discussed'
+    var said = SAID[last.verdict] || ('recorded as "' + last.verdict + '"')
     var when = String(last.at || '').slice(0, 10)
     verdictLog.hidden = false
     verdictLog.textContent = said + ' earlier' + (when ? ' · ' + when : '') + (last.note ? ' · ' + last.note : '')
@@ -1366,7 +1576,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
    * you read six digits out, where a paste costs context in proportion to how
    * much you wrote.
    */
-  function post(json) {
+  function post(json, verdict) {
     copyHint.hidden = false
     copyHint.textContent = 'Sending…'
     fetch(location.pathname, {
@@ -1392,12 +1602,14 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
         if (code) {
           copyHint.textContent = 'Sent. Run this where Claude is:'
           showCommand('/spec-reviewed ' + code)
+          markDecided(verdict, '/spec-reviewed ' + code)
         } else {
           // NO CODE, NO COMMAND. A `/spec-reviewed` with nothing after it still
           // works — it picks up the single waiting pass — but the page cannot
           // claim the server named THIS one, so it does not put words in its
           // mouth. Bare is what the reader is told, because bare is what is true.
           copyHint.textContent = 'Sent — run /spec-reviewed to pick it up.'
+          markDecided(verdict)
         }
       })
     }, function () {
@@ -1407,17 +1619,83 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     })
   }
 
+  /**
+   * Is this page running as a published Artifact?
+   *
+   * A CAPABILITY CHECK, not a hostname one. `window.claude.use` is the whole
+   * contract for reaching anything the viewer grants, and it exists only where
+   * a viewer is there to grant it — so its presence is what distinguishes the
+   * published page from the two the engine serves, without this file knowing
+   * anything about where it was published.
+   */
+  function isArtifact() {
+    return Boolean(window.claude && typeof window.claude.use === 'function')
+  }
+
+  /**
+   * Hand the pass to the artifact's own store.
+   *
+   * THE THIRD TRANSPORT, for the reader no local server can reach: a phone on
+   * mobile data, or anyone away from the LAN the engine serves on. The pass
+   * lands in a document Claude reads back and deletes, so it is consumed
+   * exactly like a claimed one.
+   *
+   * `use` is asked only once the reader has pressed something. Asking at load
+   * would spend a consent prompt on every render, including the ones nobody
+   * ends in a verdict.
+   */
+  function sendToStore(json, verdict) {
+    copyHint.hidden = false
+    copyHint.textContent = 'Sending…'
+    var landed = false
+    window.claude.use('db').then(function (db) {
+      // `null` means this view cannot run db — not granted, not served, failed
+      // to load, all indistinguishable by design. The clipboard is still there,
+      // so the pass is recoverable rather than lost.
+      if (!db) {
+        showFallback(json, 'Could not reach the store. Copy this, then paste it to Claude.')
+        return
+      }
+      return db
+        .collection('passes')
+        .add({ spec: data.spec, at: new Date().toISOString(), render: data.generatedAt, blob: JSON.parse(json) })
+        .then(function () {
+          landed = true
+          // NO CODE HERE, and none invented. Six digits are the engine's, minted
+          // by the holding area this pass never went through — so the page says
+          // the one thing that is true and actionable.
+          copyHint.textContent = 'Sent. Run this where Claude is:'
+          showCommand('/spec-reviewed')
+          markDecided(verdict, '/spec-reviewed')
+        })
+    }).then(null, function (err) {
+      if (landed) return
+      showFallback(
+        json,
+        'Could not store the pass' + (err && err.code ? ' (' + err.code + ')' : '') +
+          '. Copy this, then paste it to Claude.',
+      )
+    })
+  }
+
   function send(verdict) {
     var json = JSON.stringify(buildBlob(verdict), null, 2)
-    // DECIDED FROM WHAT THE PAGE IS, not from what it can guess. A page opened
-    // over http was served by the engine and can hand the pass straight back; a
-    // `file://` page has no server to talk to and never will.
+    // DECIDED FROM WHAT THE PAGE IS, not from what it can guess. A published
+    // page has a store and no server; a page opened over http was served by the
+    // engine and can hand the pass straight back; a `file://` page has no server
+    // to talk to and never will.
     //
     // NOT "try the POST and fall back on failure": a failed POST and an absent
     // one look identical to the reader, so the fallback would hide a server
-    // that is refusing passes behind a message about copying.
+    // that is refusing passes behind a message about copying. The published page
+    // is exactly that trap — its POST would go to claude.ai and fail — which is
+    // why it is answered first, by what the page IS rather than by what failed.
+    if (isArtifact()) {
+      sendToStore(json, verdict)
+      return
+    }
     if (location.protocol !== 'file:') {
-      post(json)
+      post(json, verdict)
       return
     }
     // `file://` is not a secure context everywhere, and the clipboard API is
@@ -1449,12 +1727,20 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // read its own version says nothing rather than claiming "unknown" — an
   // absence here is about the lookup, not about the page.
   if (data.engine) {
-    document.getElementById('drawn-by').textContent = 'rendered by skitterspec ' + data.engine
+    // `0.0.0` is what the unpublished source package carries, so a page drawn
+    // from a working copy would otherwise claim a version that has never been
+    // released. This line exists to answer "which engine drew this" — and a
+    // string that LOOKS like a version and is not one answers it wrongly, which
+    // is worse than not answering. The field itself is untouched: the serve
+    // daemon compares it to spot a stale renderer, and it must stay a version.
+    document.getElementById('drawn-by').textContent =
+      'rendered by skitterspec ' + (data.engine === '0.0.0' ? '(unreleased build)' : data.engine)
   }
 
   restore()
   drawContext()
   drawLog()
+  drawDecided()
   wireChecks()
   state.forEach(function (st) {
     var btn = st.details && st.details.querySelector('.accept')

package/assets/rules/spec-planning.md

@@ -29,11 +29,17 @@ rather than invoking it.
 
 `/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
 convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
-review pass is never claimed unasked. A pass can be POSTed by anything that
-reaches the page; what it cannot reach is the conversation. Because the model
-cannot invoke this skill, a pass is only ever picked up because a person typed
-the command, and typing it **is** the human signal. Prose alone did not hold
-that line once already.
+review pass is never claimed unasked. Because the model cannot invoke this
+skill, a pass named this way is only ever picked up because a person typed the
+command, and typing it **is** the human signal. Prose alone did not hold that
+line once already.
+
+It is **no longer the only way in**, and the difference is worth stating
+precisely. A phase that ends now *waits* on its page, and a pass arriving inside
+that wait is claimed by the engine (`--claim-since`) without anyone typing
+anything — scoped to the window, refusing when two arrive. `/spec-reviewed` is
+what answers everything outside it: a pass sent when nobody was waiting, two
+passes to choose between, and every harness with no file-watch to wait with.
 
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
@@ -174,13 +180,24 @@ paste, exactly as before. The clipboard path is **not legacy**: it is the whole
 story for a local reader.
 
 The code is **not a secret** — it is printed on the page, and it cannot be a
-gate against Claude either, because the store is a file Claude can read. What
-actually holds is narrower and stronger:
-**a device that reaches your page cannot reach your conversation.**
-So a pass it queues sits in the holding area
-forever, and the rule that keeps it there is that
-**Claude never claims a pass it was not asked to** — stated in `/spec-diff` step
-0, because nothing enforces it.
+gate against Claude either, because the store is a file Claude can read.
+
+It was once true that a device reaching your page
+**could not reach your conversation**, and that fact was the whole guard: a pass sat in the holding
+area until you typed `/spec-reviewed`. It is no longer true, deliberately —
+a phase that ends **waits** for its verdict, so the button you press on the page
+is what carries the work on. What replaced the guard is two mechanisms and one
+rule. The **serve token** — 48 bits of randomness in the URL path, minted per
+server — decides who can POST at all. The **wait window** decides which pass may
+be claimed without you naming it: the engine's `--claim-since` takes the one
+pass that arrived *while this session was waiting*, acts on nothing when none
+did, and refuses to choose when two did. And outside that window the rule stands
+unchanged and absolute: **Claude never claims a pass it was not asked to**
+(`/spec-diff` step 0, because nothing enforces it).
+
+What you give up is real and worth naming: the page can now act. What you get is
+the loop closing without anyone remembering a command — which is the failure the
+old design traded it for.
 
 What the code *does* is let you **tell two passes apart** — it is an address,
 never a password. One waiting pass is claimed and acted on the moment you type
@@ -218,6 +235,41 @@ never ticked block nothing — an unticked file is something you said nothing
 about, and requiring every one of them would be the tally this design exists to
 avoid.
 
+**The gate — a phase that ended owes an answer.** That is the second refusal,
+and it is a different kind: not a count, and not about the marks at all.
+`/spec-next` **arms** it when a phase ends and renders its page, and exactly two
+things clear it — a **committing verdict**, or
+`skitterspec spec-env review skip "<reason>"`. Until one of them happens,
+`/spec-next` refuses to build the next phase and (where the hook is installed)
+`git commit` refuses in that worktree. `skitterspec spec-env review gate
+[--check] [--json]` is what both ask.
+
+**The hook is the half that cannot be talked past.** `skitterspec init` installs
+`.claude/hooks/review-gate.js` and registers it in the project's committed
+`.claude/settings.json`, so a `git commit` is refused by the harness rather than
+by prose — which is what covers a bare `git commit`, a chained command, and
+skittership's own `/commit` without skitterspec ever editing it. It decides
+nothing itself: it hands the command line to
+`spec-env review gate --check --for-command` and turns one exit status into an
+answer. It refuses only where the commit is running
+**inside that spec's own worktree** — a commit on the base branch, or in
+another spec's tree, is not this obligation's business — and it fails **open** on everything else: no engine, an
+unreadable payload, a crash, a timeout, a repo with no isolation.
+
+Three things keep it a push rather than a wall. It is armed
+**only by a phase ending**, so reading your own half-finished work mid-phase
+owes nothing.
+It has an **exit that is always one command**, and one of them is
+*"I am moving on"* — with a reason, because `none: additive, nothing to revert` is a decision
+a reviewer can argue with while silence is an oversight. And it accuses
+**only on a positive signal**: an unreadable sidecar, a project that set
+`review.required: false`, a spec the engine could not resolve — every
+cannot-tell exits 0 and says nothing (`.claude/rules/negative-checks.md`).
+
+It is on by default wherever isolation is configured. That is the point: the
+push toward reading the diff is the normal path, and stepping off it is the
+thing you have to do deliberately.
+
 **The verdict names the action**, and that is why it is `commit` rather than
 `approve`: a review is the guard in front of an action, and an approval that
 only recorded itself was the one control on the page that did not describe what