@skitterbyte/skitterspec-linear 13.0.0 → 15.0.0

package/src/cli.js

@@ -68,15 +68,26 @@ const {
   readPending,
   writePending,
   claimPending,
+  passesSince,
   describePending,
   pendingAge,
   reviewPendingPath,
   validateResolutions,
   mergeNotes,
   applyResolutions,
+  COMMITTING,
+  BUTTON_SETS,
+  DEFAULT_BUTTON_SET,
+  reviewGatePath,
+  readGate,
+  writeGate,
+  armGate,
+  disarmGate,
+  gateState,
 } = require('./env/review.js')
 const { planUp, planCheckoutUp } = require('./env/provision.js')
 const { classifyDirtyTree } = require('./env/classify.js')
+const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
 const { planIntegrate, planIntegrateCheckout } = require('./env/integrate.js')
@@ -1624,11 +1635,217 @@ function verdictSaid(v) {
   // thing that will happen to the repo and the reader should see it coming.
   if (v.effective === 'commit') return `committing with ${v.commitWith}`
   if (v.effective === 'commit-continue') return `committing with ${v.commitWith}, then the next phase`
+  // Names what it does NOT do, because the reader of a mid-run page has just
+  // pressed a green button and must not read it as a commit.
+  if (v.effective === 'continue') return 'read — carrying on, nothing committed'
   if (v.effective === 'changes') return 'changes requested'
   return 'discuss first'
 }
 
+/**
+ * Resolve the spec and its page path for a gate verb, or say why not.
+ *
+ * Shared by `arm`, `gate` and `skip` so all three answer about the same
+ * sidecar the render writes beside the page — `--out` moves them together, and
+ * a gate keyed to a different path than its page is a gate nobody can clear.
+ *
+ * It never throws. Resolution failure is a cannot-tell for these verbs, not an
+ * error: `gate --check` is called by a commit hook, and a hook that fails on a
+ * repo it could not resolve would block every commit in it.
+ */
+function gateTarget(dir, config, specArg) {
+  try {
+    const spec = resolveSpecWithWorktree(dir, config, specArg)
+    return { spec, out: reviewOutPath(dir, spec.folder), reason: null }
+  } catch (err) {
+    return { spec: null, out: null, reason: err.message }
+  }
+}
+
+// `review arm` — a phase ended, and its diff is now owed a verdict.
+function specEnvReviewArm(dir, config, specArg, flags) {
+  const target = gateTarget(dir, config, specArg)
+  if (!target.spec) {
+    // Arming is a best-effort half of a phase ending; the phase is still built.
+    process.stdout.write(`spec-env review arm: cannot tell which spec — ${target.reason}\n`)
+    return
+  }
+  const read = readGate(target.out, target.spec.folder)
+  if (read.corrupt) {
+    // Same rule as every other sidecar: never write over a file we could not
+    // read. Here that also means never claiming to have armed something.
+    process.stdout.write(
+      `spec-env review arm: ${reviewGatePath(target.out)} is not readable JSON — ` +
+        'move it aside rather than losing the history it holds.\n',
+    )
+    return
+  }
+  const phase = flags.phase === undefined ? null : flags.phase
+  const before = read.gate
+  const gate = armGate(before, { at: new Date().toISOString(), phase })
+  writeGate(target.out, gate)
+  const again = before.armed && gate.armedAt === before.armedAt
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ spec: target.spec.folder, armed: true, armedAt: gate.armedAt, phase: gate.phase, alreadyArmed: again }, null, 2) + '\n')
+    return
+  }
+  process.stdout.write(
+    `spec-env review arm: ${target.spec.folder} is awaiting a verdict` +
+      `${gate.phase ? ` (phase ${gate.phase})` : ''}` +
+      `${again ? ' — already was, since ' + String(gate.armedAt).slice(0, 19) : ''}\n`,
+  )
+}
+
+/**
+ * `review gate` — is anything owed?
+ *
+ * `--check` is the one call a commit hook makes, and it exits non-zero ONLY on
+ * `armed`: a positive signal, read from a present and parseable sidecar. Every
+ * other state — cleared, unreadable, versioned past this engine, switched off
+ * — exits 0 and says which, because a check that accuses on an absence accuses
+ * healthy repos (`.claude/rules/negative-checks.md`).
+ */
+function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
+  // `--for-command` is the hook's half: it asks about a command line rather
+  // than about the repo, and a command that is not a commit is simply not this
+  // check's business. Answered FIRST and in silence, because the overwhelming
+  // majority of tool calls land here and every one of them must cost nothing
+  // and say nothing.
+  if (flags.forCommand !== undefined && !isGitCommit(flags.forCommand)) return
+
+  const target = gateTarget(dir, config, specArg)
+  let judged = target.spec
+    ? gateState({ ...readGate(target.out, target.spec.folder), required: config.review.required })
+    : { state: 'unknown', reason: target.reason, gate: null }
+
+  // ASKED ABOUT A COMMAND, the question is narrower than "is anything owed in
+  // this repo": it is "does the commit happening HERE owe a verdict". The bare
+  // resolution answers with the sole provisioned spec wherever you stand, which
+  // is right for a person typing the verb and wrong for this — it denied a
+  // commit on the base branch because some other spec was mid-review, which is
+  // exactly how a backlog spec authored from the primary checkout (the thing
+  // `commit-trailers.md` asks for) would be blocked by unrelated work.
+  //
+  // So it wants a POSITIVE signal (`.claude/rules/negative-checks.md` rule 1):
+  // this commit is running inside that spec's own worktree. Anything else —
+  // the primary checkout, another spec's tree, a path that cannot be resolved —
+  // is a cannot-tell, and cannot-tell allows.
+  if (flags.forCommand !== undefined && judged.state === 'armed') {
+    const inside = (child, parent) => {
+      try {
+        const rel = path.relative(fs.realpathSync(parent), fs.realpathSync(child))
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+      } catch {
+        return false
+      }
+    }
+    if (!inside(invokedFrom, target.spec.worktreePath)) {
+      judged = {
+        state: 'unknown',
+        reason: `this command is not running inside ${target.spec.folder}'s worktree`,
+        gate: judged.gate,
+      }
+    }
+  }
+
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          spec: target.spec ? target.spec.folder : null,
+          state: judged.state,
+          reason: judged.reason,
+          armedAt: judged.gate ? judged.gate.armedAt : null,
+          phase: judged.gate ? judged.gate.phase : null,
+          required: config.review.required,
+          log: judged.gate && Array.isArray(judged.gate.log) ? judged.gate.log : [],
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+  } else if (judged.state === 'armed') {
+    const g = judged.gate
+    process.stdout.write(
+      `spec-env review gate: ${target.spec.folder} is awaiting a verdict` +
+        `${g.phase ? ` (phase ${g.phase})` : ''}` +
+        `${g.armedAt ? ` since ${String(g.armedAt).slice(0, 19)}` : ''}\n` +
+        '  read the page and send a verdict, or record why you are moving on:\n' +
+        '    skitterspec spec-env review skip "<reason>"\n',
+    )
+  } else if (judged.state === 'clear') {
+    process.stdout.write(`spec-env review gate: ${target.spec.folder} owes nothing — ${judged.reason}\n`)
+  } else {
+    process.stdout.write(
+      `spec-env review gate: cannot tell — ${judged.reason}.\n` +
+        '  nothing is being claimed, and nothing is blocked.\n',
+    )
+  }
+
+  // The exit status is the whole interface for a hook, so it is set from the
+  // one state that is evidence and never from the two that are not.
+  if (flags.check && judged.state === 'armed') process.exitCode = 1
+}
+
+// `review skip` — move on without a verdict, on the record.
+function specEnvReviewSkip(dir, config, reason, flags) {
+  const said = String(reason || '').trim()
+  if (!said) {
+    // The reason IS the feature. A skip with no reason is the silence this
+    // whole gate exists to replace, so it is refused rather than defaulted.
+    process.stdout.write(
+      'spec-env review skip: needs a reason — skitterspec spec-env review skip "<why>"\n',
+    )
+    process.exitCode = 1
+    return
+  }
+  const target = gateTarget(dir, config, null)
+  if (!target.spec) {
+    process.stdout.write(`spec-env review skip: cannot tell which spec — ${target.reason}\n`)
+    process.exitCode = 1
+    return
+  }
+  const read = readGate(target.out, target.spec.folder)
+  if (read.corrupt) {
+    process.stdout.write(
+      `spec-env review skip: ${reviewGatePath(target.out)} is not readable JSON — ` +
+        'move it aside rather than losing the history it holds.\n',
+    )
+    process.exitCode = 1
+    return
+  }
+  const result = disarmGate(read.gate, { at: new Date().toISOString(), by: 'skip', reason: said })
+  if (!result.logged) {
+    // Nothing was owed, so nothing is recorded: a log entry here would claim a
+    // decision was taken about an obligation that did not exist.
+    process.stdout.write(`spec-env review skip: ${target.spec.folder} owes nothing — nothing to skip\n`)
+    return
+  }
+  writeGate(target.out, result.gate)
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ spec: target.spec.folder, skipped: true, reason: said }, null, 2) + '\n')
+    return
+  }
+  process.stdout.write(
+    `spec-env review skip: ${target.spec.folder} moved on without a verdict\n  reason: ${said}\n`,
+  )
+}
+
 async function specEnvReview(dir, config, specArg, flags) {
+  // REFUSED BY NAME, never coerced to the default. A typo'd button set silently
+  // rendering the committing page is the same failure the verdict validator
+  // refuses for the same reason: a caller asking for the mid-run page and
+  // getting the committing one would offer a reader a commit on unfinished
+  // work, and nothing would have said so.
+  if (flags.buttons !== null && !BUTTON_SETS.includes(flags.buttons)) {
+    process.stdout.write(
+      `spec-env review: --buttons ${JSON.stringify(flags.buttons)} is not one of ` +
+        `${BUTTON_SETS.join(', ')} — nothing rendered.\n`,
+    )
+    return
+  }
+  const buttons = flags.buttons || DEFAULT_BUTTON_SET
+
   // An unknown name throws here rather than falling back to the branch: a review
   // of the wrong spec looks exactly like a review of the right one.
   const spec = resolveSpecWithWorktree(dir, config, specArg)
@@ -1690,11 +1907,51 @@ async function specEnvReview(dir, config, specArg, flags) {
   let sentVerdict = null
   let claimed = null
 
+  // `--claim-since <iso>` resolves to a code and then joins the ordinary claim
+  // path below. THE ENGINE PICKS SO THE AGENT DOES NOT: an agent left to find
+  // "the pass that just arrived" reads the store and chooses, and the rule that
+  // it must not choose becomes a request. Here the window is the only input, and
+  // an answer of anything but exactly one pass acts on nothing.
+  let claimCode = flags.claim
+  if (!claimCode && flags.claimSince) {
+    const heldRead = readPending(out, spec.folder)
+    if (heldRead.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
+          'move it aside rather than losing the passes it holds.\n',
+      )
+      return
+    }
+    const window = passesSince(heldRead.pending, flags.claimSince)
+    if (!window.usable) {
+      process.stdout.write(
+        `spec-env review: --claim-since ${flags.claimSince} is not a timestamp — nothing claimed\n`,
+      )
+      return
+    }
+    if (window.codes.length === 0) {
+      process.stdout.write(
+        `spec-env review: no pass has arrived since ${flags.claimSince} — nothing claimed\n`,
+      )
+      return
+    }
+    if (window.codes.length > 1) {
+      // Names the count, never the codes — the same silence a wrong `--claim`
+      // keeps, for the same reason. The operator has them; the page prints them.
+      process.stdout.write(
+        `spec-env review: ${window.codes.length} passes arrived in that window — ` +
+          'claim one by its code rather than guessing between them.\n',
+      )
+      return
+    }
+    claimCode = window.codes[0]
+  }
+
   // A CLAIM IS A DELIVERY MECHANISM, not a second kind of review. It lifts a
   // pass out of the holding area and hands it to exactly the same merge a
   // pasted blob goes through, so nothing downstream can tell — or behave
   // differently — by how the pass arrived.
-  if (flags.claim) {
+  if (claimCode) {
     const heldRead = readPending(out, spec.folder)
     if (heldRead.corrupt) {
       // Same rule as the notes sidecar: a file we cannot parse is not "nothing
@@ -1705,7 +1962,7 @@ async function specEnvReview(dir, config, specArg, flags) {
       )
       return
     }
-    const result = claimPending(heldRead.pending, String(flags.claim).trim())
+    const result = claimPending(heldRead.pending, String(claimCode).trim())
     if (!result.pass) {
       // NO FALLBACK, EVER. Not "the only one", not "the most recent" — either
       // would let a pass nobody read out reach the review, which is the whole
@@ -1869,6 +2126,29 @@ async function specEnvReview(dir, config, specArg, flags) {
       // read the config itself — one answer, from the engine that owns it.
       commitWith: config.review.commitWith,
     }
+
+    // A COMMITTING verdict is what the gate was waiting for, so it clears it —
+    // and only it. `changes` leaves the gate armed deliberately: the work
+    // happens, the page re-renders, and the next verdict is the exit. `discuss`
+    // likewise, including a REFUSED commit, which did not happen and must not
+    // clear an obligation on the strength of having been asked for.
+    if (judged.honoured && COMMITTING.includes(judged.effective)) {
+      const gateRead = readGate(out, spec.folder)
+      if (!gateRead.corrupt) {
+        const result = disarmGate(gateRead.gate, {
+          at: new Date().toISOString(),
+          by: 'verdict',
+          reason: judged.effective,
+        })
+        if (result.logged) {
+          writeGate(out, result.gate)
+          verdictReport.gateCleared = true
+        }
+      }
+      // A corrupt gate is left exactly as it is. It already reads as
+      // cannot-tell everywhere, so it refuses nothing — there is no obligation
+      // to clear, and writing over it would lose the log it holds.
+    }
   }
 
   // What the last decision PRODUCED — written after the thing it asked for has
@@ -1898,8 +2178,14 @@ async function specEnvReview(dir, config, specArg, flags) {
   // request rather than a discipline.
   const waiting = describePending(readPending(out, spec.folder).pending)
 
+  // Read AFTER the verdict half above, so a claim that just cleared the gate
+  // renders as cleared rather than as still owing. Corrupt contributes nothing:
+  // the page is a convenience and the gate is not what it is for.
+  const gateNow = readGate(out, spec.folder)
+  const gate = gateNow.corrupt ? null : gateNow.gate
+
   const now = new Date().toISOString()
-  let data = collectReview({ spec, git, mode, ref, base, now, notes })
+  let data = collectReview({ spec, git, mode, ref, base, now, notes, gate, buttons })
 
   // A CLEAN WORKING TREE IS NOT "NOTHING TO REVIEW". It is the state a phase
   // ends in: the page is rendered before the commit, the commit happens
@@ -1931,6 +2217,8 @@ async function specEnvReview(dir, config, specArg, flags) {
         base: fallbackBase,
         now,
         notes,
+        gate,
+        buttons,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -2023,6 +2311,10 @@ async function specEnvReview(dir, config, specArg, flags) {
           urlFile,
           url,
           notesFile: reviewNotesPath(out),
+          // Absent stays absent, exactly as it is in the page payload: the
+          // committing set is what a caller that did not ask always got, so
+          // reporting it would make every existing consumer see a new key.
+          ...(data.buttons ? { buttons: data.buttons } : {}),
           reviewed: Boolean(data.review),
           totals: data.totals,
           notes: data.notes,
@@ -3176,6 +3468,7 @@ async function specEnv(rest) {
     outcome: null,
     claim: null,
     drop: null,
+    buttons: null,
     json: false,
   }
   for (let i = 0; i < args.length; i++) {
@@ -3190,14 +3483,19 @@ async function specEnv(rest) {
     else if (args[i] === '--port') flags.port = args[++i]
     else if (args[i] === '--host') flags.host = args[++i]
     else if (args[i] === '--publish-copy') flags.publishCopy = true
+    else if (args[i] === '--buttons') flags.buttons = args[++i]
     else if (args[i] === '--out') flags.out = args[++i]
     else if (args[i] === '--review') flags.review = args[++i]
     else if (args[i] === '--notes') flags.notes = args[++i]
     else if (args[i] === '--resolve') flags.resolve = args[++i]
     else if (args[i] === '--outcome') flags.outcome = args[++i]
     else if (args[i] === '--claim') flags.claim = args[++i]
+    else if (args[i] === '--claim-since') flags.claimSince = args[++i]
     else if (args[i] === '--drop') flags.drop = args[++i]
     else if (args[i] === '--json') flags.json = true
+    else if (args[i] === '--check') flags.check = true
+    else if (args[i] === '--for-command') flags.forCommand = args[++i]
+    else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
@@ -3259,6 +3557,24 @@ async function specEnv(rest) {
         await specEnvReviewServe(dir, config, flags)
         break
       }
+      // The gate verbs sit here for the same reason `serve` does: they answer
+      // about the page this command renders, keyed to the same path, and a
+      // sibling verb would have to re-derive every bit of that.
+      if (positional[0] === 'arm') {
+        specEnvReviewArm(dir, config, positional[1], flags)
+        break
+      }
+      if (positional[0] === 'gate') {
+        specEnvReviewGate(dir, config, positional[1], flags, invokedFrom)
+        break
+      }
+      if (positional[0] === 'skip') {
+        // The one positional is the REASON, not a spec: the two are
+        // indistinguishable as free text, and the spec is the one thing this
+        // engine can already resolve from where you are standing.
+        specEnvReviewSkip(dir, config, positional[1], flags)
+        break
+      }
       await specEnvReview(dir, config, positional[0], flags)
       break
     case 'live':
@@ -3266,8 +3582,14 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--json] [--record-primary] [--assert-primary-clean]\n' +
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n' +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
+          '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
+          '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
+          '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +
+          '  review skip "<reason>"                 move on without one, on the record\n' +
+          '  review [spec] --claim-since <iso>      claim the one pass that arrived since <iso>\n' +
+          '  review [spec] --buttons midrun         the page offers Continue, not a commit\n' +
           '  [spec] is optional everywhere: omit it and the worktree you are standing\n' +
           '  in is used, else the sole provisioned spec (several -> it lists them).\n' +
           '  A bare `live` takes that spec when the workbench is free, and prints the\n' +

package/src/env/commitcmd.js

@@ -0,0 +1,108 @@
+'use strict'
+
+/**
+ * Is this shell command a `git commit`?
+ *
+ * Asked by the review-gate hook, which is handed the command line a tool is
+ * about to run and has to decide whether the gate is even relevant. It lives
+ * here rather than inside the hook script for one reason: **a check that blocks
+ * a commit is an accusation** (`.claude/rules/negative-checks.md`), and an
+ * accusation that cannot be unit-tested will be wrong in ways nobody finds. The
+ * hook is a stdin shim over `spec-env review gate --check --for-command`; this
+ * is the part with the judgement in it.
+ *
+ * It answers TRUE only on a positive reading — a `git` invocation whose first
+ * non-option argument is `commit`. Everything it cannot parse confidently reads
+ * FALSE, because the cost of the two mistakes is not symmetric: a false
+ * negative lets one commit through a gate the skills also enforce, while a
+ * false positive blocks a command that has nothing to do with reviewing and
+ * leaves the operator with no idea why.
+ */
+
+// Shell metacharacters that end one command and begin another. `|` covers `||`
+// too, and `&` covers `&&`; over-splitting is harmless here because each
+// fragment is judged on its own.
+const SEPARATORS = /[;&|\n]+/
+
+/**
+ * Remove every quoted span. Pure.
+ *
+ * THE POINT IS WHAT THIS PREVENTS, twice over. `echo "deploy && git commit"`
+ * must not read as a commit — splitting a raw string on `&&` would manufacture
+ * a fragment out of someone's prose. And `git commit -m "fix the git log"`
+ * must still read as one: emptying the quotes leaves the real argv intact,
+ * because a verb is never inside quotes.
+ *
+ * An UNTERMINATED quote empties the rest of the line, so a half-written command
+ * reads as nothing rather than as something — the cannot-tell case going to the
+ * harmless branch, again.
+ */
+function stripQuoted(command) {
+  let out = ''
+  let quote = null
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]
+    if (quote) {
+      if (c === '\\' && quote === '"') {
+        i++
+        continue
+      }
+      if (c === quote) quote = null
+      continue
+    }
+    if (c === '"' || c === "'") {
+      quote = c
+      continue
+    }
+    out += c
+  }
+  return out
+}
+
+// git's own options, before the subcommand. Those taking a separate value have
+// to be skipped WITH their value, or `git -C /tmp commit` reads its verb as the
+// path. The `=` forms carry their value already.
+const GIT_OPTS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
+
+/**
+ * Does this one fragment invoke `git commit`? Pure.
+ *
+ * `env`, `sudo`, `time` and the like are NOT unwrapped: a wrapper is not the
+ * common case and guessing at one is how a false positive gets built. The
+ * binary may be a path (`/usr/bin/git`), because that is ordinary.
+ */
+function fragmentCommits(fragment) {
+  const tokens = fragment.trim().split(/\s+/).filter(Boolean)
+  const at = tokens.findIndex((t) => t === 'git' || /(^|\/)git$/.test(t))
+  if (at === -1) return false
+
+  for (let i = at + 1; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (GIT_OPTS_WITH_VALUE.has(t)) {
+      i++
+      continue
+    }
+    if (t.startsWith('-')) continue
+    // The first non-option token is the subcommand, whatever it is. Only one
+    // word is a commit.
+    return t === 'commit'
+  }
+  return false
+}
+
+/**
+ * Does this command line run `git commit` anywhere in it? Pure.
+ *
+ * WHAT WOULD FOOL THIS, named here so the next reader does not have to
+ * rediscover it: a commit hidden inside a quoted script (`sh -c 'git commit'`),
+ * behind an alias, or built by string interpolation reads as FALSE. All three
+ * are deliberate — they are the unknown case, and the unknown case does not
+ * accuse. The gate is still enforced by `/spec-next`, which does not depend on
+ * reading anybody's shell.
+ */
+function isGitCommit(command) {
+  if (typeof command !== 'string' || !command.trim()) return false
+  return stripQuoted(command).split(SEPARATORS).some(fragmentCommits)
+}
+
+module.exports = { isGitCommit, stripQuoted, fragmentCommits }

package/src/env/config.js

@@ -126,7 +126,19 @@ const DEFAULT_CONFIG = Object.freeze({
   // a verdict that records itself and does nothing. A review is the guard in
   // front of an action; recording an approval for SOMEONE ELSE to act on is a
   // different mechanism, not a value of this key.
-  review: Object.freeze({ reader: 'detect', servePort: 7777, serveOnRemote: true, commitWith: '/commit' }),
+  //
+  // `required` decides whether a phase that ended owes a verdict before its
+  // work can be committed or the next phase built. It defaults TRUE: the push
+  // toward reading the diff is the point, and a project that would rather not
+  // be pushed says so once. It is the only key anything reads to decide
+  // whether the gate refuses, so turning it off turns off the hook with it.
+  review: Object.freeze({
+    reader: 'detect',
+    servePort: 7777,
+    serveOnRemote: true,
+    commitWith: '/commit',
+    required: true,
+  }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -338,6 +350,10 @@ function mergeConfig(base, parsed) {
     // here. There is nothing it could mean instead: the hand-off has no off
     // switch, so a blank value is a typo rather than an instruction.
     assign(base.review, parsed.review, 'commitWith', 'string')
+    // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
+    // leaves the gate ON. Turning off a check that refuses must be something
+    // someone WROTE, never something a typo achieved on their behalf.
+    assign(base.review, parsed.review, 'required', 'boolean')
   }
 
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {