@skitterbyte/skitterspec 19.0.0 → 21.0.0

package/MIGRATION.md

@@ -1,5 +1,175 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v20 → v21 (the gate installs, and asking implies waiting)
+
+If you upgraded to v20 and the commit gate never once fired, this is why. Two
+independent bugs, either of which alone made it a no-op.
+
+### Breaking change
+
+**The hook ships as `.claude/hooks/review-gate.cjs`**, renamed from
+`review-gate.js`. The script is CommonJS and it is copied *into your* project,
+where your `package.json` decides how node parses a `.js` — so in any
+`"type": "module"` project it died on its own first `require`, printing a stack
+trace on **every Bash tool call**. `.cjs` settles the parse mode at the file,
+which is the only place independent of the one file skitterspec does not
+control. An ESM rewrite would have inverted the same problem onto CommonJS
+projects, which are still the default for anything with no `"type"` set.
+
+The upgrade migrates you: your existing `PreToolUse` entry has its path
+**rewritten in place** — so a wrapper, a flag or a different interpreter you
+added all survive — and the retired `review-gate.js` is deleted. If you edited
+that file yourself it is **kept**, with a warning, and left for you to remove.
+
+### Bug fix
+
+**`skitterspec update` now registers the hook.** v20's notes said `init` and
+`update` both did; only `init` did. `update` copied the script, reported
+`created: .claude/hooks/review-gate.js`, and wired nothing — so every project
+that upgraded into v20 got a hook file and no hook, with nothing saying so.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Commit `.claude/settings.json` and `.claude/hooks/review-gate.cjs`**, and
+   the deletion of `.claude/hooks/review-gate.js`. A hook only a fraction of the
+   team has is a gate that holds for a fraction of the team.
+3. **Check it is actually on** — the update reports
+   `updated: .claude/settings.json (review-gate hook)` the first time, and
+   `unchanged` afterwards. If it says neither, your settings file could not be
+   parsed; it was left untouched and the hook is not registered.
+
+### Behaviour change — a bug fix and a hotfix now owe a verdict
+
+**`/spec-bug` and `/spec-hotfix` now arm the review gate**, as `/spec-next`
+already did. Both render the page at the end of red→green work, and both now
+wait for your verdict instead of finishing — so in that spec's worktree a
+`git commit` is **refused** until one of two things happens:
+
+- you send a verdict from the page (or `/spec-reviewed` picks up one already
+  waiting), or
+- you run `skitterspec spec-env review skip "<reason>"`, which records the
+  decision to move on.
+
+The gate is still only armed by work that **finished**, it still fails open on
+every cannot-tell, and `review.required: false` in `specs/.core/env.config.json`
+still turns it off for a project.
+
+**Why.** Those two skills used to render the page, ask *"want a written review
+before you commit?"* and finish with nothing watching. A verdict pressed on that
+page sat in the holding area until someone typed `/spec-reviewed` — which they
+had no reason to do, because the run had said the page was *ready* rather than
+that it was *waiting*. Two verdicts were stranded that way on one spec, and the
+second existed only because the first appeared to do nothing.
+
+### New, and not breaking — the `Continue` verdict
+
+**A page rendered part-way through a run offers `Continue`** — *I have read it,
+carry on* — instead of the committing buttons, via
+`spec-env review <spec> --buttons midrun`. The default is unchanged, so a caller
+that passes nothing renders exactly the page it rendered before. `Continue` can
+never clear an armed gate: that still takes a committing verdict or a recorded
+skip.
+
+Nothing else changes: `review.required` still defaults to `true`, and the engine
+and `/spec-next` held the gate throughout regardless of the hook.
+
+## `@skitterbyte/skitterspec-linear` v14 → v15 (the gate installs, and asking implies waiting)
+
+The same change as `@skitterbyte/skitterspec` v20 → v21 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
+## `@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 the hook script and register it as a `PreToolUse`
+hook in your project's **committed** settings file. (In v20 `update` copied
+without registering, and the script was named `review-gate.js` — both fixed in
+v21; read that entry above if you are landing on the current release.) 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 the hook script.** 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

@@ -74,8 +74,9 @@ no live `env.config.json` was found.
   // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
   // fresh linked worktree (which starts with none of the repo's gitignored files)
   // has the .env / local secret overrides / local config that setup steps and
-  // git hooks depend on. Without this a step like `prisma generate` hard-fails in
-  // the new worktree because .env (its datasource URL) isn't there.
+  // git hooks depend on. Without this any setup step that reads .env — a schema
+  // or client generator, a codegen pass — hard-fails in the new worktree
+  // because the file it expects isn't there.
   //   mode   "symlink" (default) points the worktree file at the main file, so it
   //          stays in sync; "copy" makes an independent copy.
   //   files  repo-relative paths to seed. A source absent in main is a printed
@@ -274,11 +275,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.cjs

@@ -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 }