@skitterbyte/skitterspec-linear 13.0.0 → 14.0.0

package/MIGRATION.md

@@ -1,5 +1,93 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v19 → v20 (a phase owes a verdict)
+
+### Breaking change
+
+**A phase that has ended now refuses to go further until you send a verdict.**
+`/spec-next` **arms** a gate when it finishes a phase and renders its review
+page. While it is armed, two things refuse:
+
+- `/spec-next` will not build the next phase.
+- `git commit` inside **that spec's own worktree** is blocked by a harness hook
+  — which is what covers a bare `git commit`, a chained command, and
+  skittership's `/commit` without skitterspec editing any of them.
+
+Exactly two things clear it, and both are one command:
+
+```
+# press Commit or Commit & Continue on the review page — or:
+skitterspec spec-env review skip "none: additive, nothing to revert"
+```
+
+The skip is deliberately not silent: the reason goes into the review outcome
+log, on the same reasoning as the `Gating:` header — a reason is a decision a
+reviewer can argue with, where silence is an oversight.
+
+**It is on by default** wherever isolation is configured (`env.config.json`
+present). To turn it off for a project, add to `specs/.core/env.config.json`:
+
+```json
+{ "review": { "required": false } }
+```
+
+Three things keep it a push rather than a wall, and they are worth knowing
+before you reach for that setting. It is armed **only by a phase ending**, so a
+mid-phase `/spec-diff` owes nothing. The exit is always one command. And it
+accuses only on a positive signal — no engine, an unreadable payload, a commit
+on the base branch or in another spec's tree, a repo with no isolation: every
+cannot-tell lets the commit through.
+
+### Breaking change
+
+**`.claude/settings.json` is now written by the installer.** `skitterspec init`
+and `skitterspec update` copy `.claude/hooks/review-gate.js` and register it as
+a `PreToolUse` hook in your project's **committed** settings file. That is a
+tracked file in most repos, so expect it in `git status` after upgrading — and
+commit it, because a hook only a fraction of the team has is a gate that holds
+for a fraction of the team.
+
+A settings file that cannot be parsed is **reported and left alone**, never
+rewritten. The hook is an extra layer: the engine and `/spec-next` hold the gate
+without it.
+
+### The review page can now reach your session — deliberately
+
+This inverts an invariant the docs used to state outright: *a device that
+reaches your page cannot reach your conversation*. It no longer holds, and the
+change is the point. `/spec-next` now ends a phase by rendering the page and
+**waiting** on it, so the button you press is what carries the work on — there
+is no command to remember.
+
+What replaced the old guard is two mechanisms and one rule:
+
+- **The serve token** — 48 random bits in the URL path, minted per server —
+  decides who can POST at all.
+- **The wait window** — only a pass that arrives *while the session is waiting*
+  is claimed for you, and two arrivals refuse rather than pick one.
+- Outside that window nothing is claimed unasked. `/spec-reviewed`, or
+  `/spec-reviewed 324199` to name one exactly, is still how a pass sent when
+  nobody was waiting gets picked up — and it is still user-only, so the model
+  cannot claim a pass on its own.
+
+A `file://` page has no server to talk to, so it copies and you paste, exactly
+as before.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Commit `.claude/settings.json` and `.claude/hooks/review-gate.js`.** Both
+   are new in your working tree after the update.
+3. **Nothing else to configure.** `review.required` defaults to `true` and
+   `review.commitWith` defaults to `/commit`; neither needs adding unless you
+   are changing it.
+
+## `@skitterbyte/skitterspec-linear` v13 → v14 (a phase owes a verdict)
+
+The same change as `@skitterbyte/skitterspec` v19 → v20 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
 ## `@skitterbyte/skitterspec` v18 → v19 (starting a spec offers phase 1)
 
 ### Breaking change

package/assets/core/env.config.json.example

@@ -42,7 +42,8 @@
     "reader": "detect",
     "servePort": 7777,
     "serveOnRemote": true,
-    "commitWith": "/commit"
+    "commitWith": "/commit",
+    "required": true
   },
   "live": {
     "migrations": []

package/assets/core/env.config.md

@@ -274,11 +274,24 @@ no live `env.config.json` was found.
   // review page must not offer — a review is the guard in front of an action.
   // Recording an approval for SOMEONE ELSE to act on is a separate mechanism,
   // not a value of this key. Default: "/commit".
+  //
+  // `required` decides whether a phase that has ended owes a verdict before its
+  // work is committed or the next phase is built. The gate is armed when a
+  // phase's page is rendered and cleared by exactly two things: a COMMITTING
+  // verdict, or `spec-env review skip "<reason>"` — allowed, and on the record,
+  // which is the whole difference between skipping and drifting.
+  //   true   — the default. A review is the normal exit from a phase.
+  //   false  — nothing is ever owed; `review gate` answers "cannot tell" and
+  //            the commit hook (if installed) defers to it, so this one key
+  //            turns the whole thing off.
+  // Only a literal `false` opts out: a typo leaves a check that REFUSES in
+  // place rather than quietly disabling it. Default: true.
   "review": {
     "reader": "detect",
     "servePort": 7777,
     "serveOnRemote": true,
-    "commitWith": "/commit"
+    "commitWith": "/commit",
+    "required": true
   }
 }
 ```

package/assets/hooks/review-gate.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Review gate — the harness half.
+ *
+ * `/spec-next` refuses to build the next phase while a review is owed, but a
+ * skill is prose: it can be chained past, typed around, or simply not read. So
+ * a phase ending is also enforced one level down, where a `git commit` is a
+ * tool call the harness has to ask about first.
+ *
+ * THIS SCRIPT DECIDES NOTHING. It reads the tool call, hands the command line
+ * to `spec-env review gate --check --for-command`, and turns one exit status
+ * into an answer. Every judgement — is this a commit, is a verdict owed, is
+ * this project even using the gate — lives in the engine, where it is unit
+ * tested. A hook with its own opinions is a second implementation that nothing
+ * can test and nobody remembers to update.
+ *
+ * IT FAILS OPEN, EVERYWHERE. No engine on the machine, an unreadable payload, a
+ * repo with no isolation, a spec it cannot resolve, a crash of its own — all of
+ * them allow the commit. Blocking one is an accusation
+ * (`.claude/rules/negative-checks.md`), and the only thing worth accusing on is
+ * the engine saying, positively, that this spec owes a verdict. Being wrong the
+ * other way costs one unreviewed commit, on a gate the skills also enforce;
+ * being wrong this way costs someone their commit with no idea why.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+// Let the call through, saying nothing. Exit 0 with no JSON is "no opinion" —
+// the tool proceeds exactly as if this hook did not exist, which is what almost
+// every invocation must do.
+function allow() {
+  process.exit(0)
+}
+
+/**
+ * Refuse, and say what would clear it.
+ *
+ * The JSON route rather than exit-2, because the reason reaches **Claude** —
+ * which is who has to act on it. A commit blocked with no route onward is how a
+ * gate gets switched off wholesale instead of answered, so the three exits are
+ * named in the refusal itself.
+ */
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  )
+  process.exit(0)
+}
+
+function readPayload() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    // Unreadable or unparseable stdin is the cannot-tell case, not evidence.
+    return null
+  }
+}
+
+/**
+ * Where the engine is, in the order most likely to be right. Pure but for the
+ * existence check.
+ *
+ * A hook process does not inherit a package manager's `node_modules/.bin` on
+ * PATH, so the local install is looked for by path first — walking up from the
+ * project, because a git worktree's checkout has its own `node_modules`. PATH
+ * is the fallback for a global install, and `SKITTERSPEC_BIN` overrides
+ * everything for anyone whose layout is neither.
+ */
+function findEngine(projectDir) {
+  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
+  let at = projectDir
+  for (let i = 0; i < 6 && at; i++) {
+    for (const name of ['skitterspec', 'skitterspec-linear']) {
+      const candidate = path.join(at, 'node_modules', '.bin', name)
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return 'skitterspec'
+}
+
+function main() {
+  const payload = readPayload()
+  if (!payload) allow()
+
+  // Only Bash runs a commit. A matcher is configured too, but a hook that is
+  // reached some other way must still be inert rather than guessing.
+  if (payload.tool_name !== 'Bash') allow()
+
+  const command = payload.tool_input && payload.tool_input.command
+  if (typeof command !== 'string' || !command.trim()) allow()
+
+  // The commit's own directory decides which spec this is about — a worktree is
+  // its own checkout, and the answer differs per worktree.
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
+
+  const result = spawnSync(
+    findEngine(cwd),
+    ['spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
+    { cwd, encoding: 'utf8', timeout: 8000 },
+  )
+
+  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
+  // process never ran or was killed, and neither is a refusal.
+  if (result.error || result.status === null) allow()
+  if (result.status !== 1) allow()
+
+  deny(
+    (result.stdout || '').trim() +
+      '\n\nThis phase is waiting on a verdict. Read the page and send one, ' +
+      'type /spec-reviewed if a pass is already waiting, or record why you are ' +
+      'moving on:\n  skitterspec spec-env review skip "<reason>"',
+  )
+}
+
+// Guarded so the pieces above can be required and tested without the script
+// reading stdin and exiting.
+if (require.main === module) {
+  try {
+    main()
+  } catch {
+    // Even a bug in this file lets the commit through.
+    allow()
+  }
+}
+
+module.exports = { findEngine }