@skitterbyte/skitterspec 18.0.0 → 20.0.0

package/assets/core/env.config.md

@@ -1,11 +1,12 @@
 # `env.config.json` — per-spec isolation config
 
 Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
-stack + host dev servers + a front-door proxy + an optional opener per
-in-progress spec). Provisioning is folded into `/spec-start`, teardown into
-`/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
-`skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
-beneath them.
+stack + host dev servers + a front-door proxy per in-progress spec).
+Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
+`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
+is `/spec-diff`; the `skitterspec spec-env
+<up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
+the engine beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-start` gives
 **every** in-progress spec its own git worktree automatically. Docker is a
@@ -31,11 +32,12 @@ no live `env.config.json` was found.
   // Where a spec's branch gets built.
   //
   //   "worktree"  (default) — every spec gets its own git worktree. Several
-  //               specs run side by side and `main` stays free, at the cost of
-  //               one terminal session per spec (`/spec-start` sets it up for you).
+  //               specs run side by side and `main` stays free. `/spec-start`
+  //               moves your session into the spec's worktree with a `cd`, so
+  //               the terminal you are already in follows the work.
   //   "checkout"  — the branch is built in the primary checkout instead. One
-  //               spec at a time, but no second session and no hand-off: the
-  //               terminal you are already in follows the work.
+  //               spec at a time, and nowhere else to stand: the work comes to
+  //               your terminal rather than your terminal going to it.
   //
   // Pick it for how you work, not for what this repo contains — a project with
   // no dev servers may still want several specs in flight. An unrecognised
@@ -124,24 +126,6 @@ no live `env.config.json` was found.
     "host": "127.0.0.1"     // bind host for the canonical ports
   },
 
-  // Optional, editor/terminal-agnostic opener — the FALLBACK for reaching a
-  // worktree. `/spec-start` normally moves the session you typed into into the
-  // worktree, and then there is nothing to open: it runs this only when it
-  // could not switch in place (the session is already inside another worktree,
-  // or the harness cannot move it). Run after provisioning and bootstrap, so
-  // the session opens onto a tree that is ready to work in. The template is
-  // expanded with {worktreePath}, {slug}, {branch}, {projectName},
-  // {portOffset}.
-  // Empty = nothing is opened (the path is just printed), which is how you turn
-  // the auto-open off, and the right value unless you actually want a second
-  // window on the fallback path. A non-interactive run skips it either way — an
-  // opened window nobody is sitting at helps no one.
-  // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
-  // or a "warp://..." deeplink for Warp users.
-  "open": {
-    "command": ""
-  },
-
   // Machine-local slot registry (spec → slot index). Resolved against the
   // primary checkout root, shared by all worktrees, gitignored.
   "registry": ".spec-env/registry.json",
@@ -193,9 +177,10 @@ no live `env.config.json` was found.
     "refuseTeardownIfUnpushed": true
   },
 
-  // What teardown cleans up beyond this machine. `/spec-start` pushes the spec
-  // branch when it provisions, so without this a completed spec leaves a merged
-  // branch on the remote forever. `deleteRemoteBranch`:
+  // What teardown cleans up beyond this machine. Nothing publishes a spec
+  // branch for you, so a remote copy exists only because you pushed it by hand —
+  // and without this a completed spec leaves that merged branch on the remote
+  // forever. `deleteRemoteBranch`:
   //   "prompt"  (default) — plan `git push <remote> --delete <branch>` in its own
   //             "confirm with the user first" section; /spec-complete and
   //             /spec-cancel ask before running it.
@@ -232,6 +217,81 @@ no live `env.config.json` was found.
     "bump": "patch",
     "cherryPickMain": true,
     "targets": []
+  },
+
+  // Reading a spec's diff (`spec-env review`, `/spec-diff`).
+  //
+  // `reader` decides how the page's LOCATION IS WORDED, and — through
+  // `serveOnRemote` below — whether the engine stands its local server up so a
+  // remote reader gets a link that opens. It never decides to PUBLISH. Three
+  // values:
+  //   "local"  — you are at the machine holding the page; a file:// URL opens.
+  //   "remote" — you are not; it does not, so the page is served instead.
+  //   "detect" — work it out (the default).
+  // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
+  // you are reading, and no signal outranks being told. Detection is only the
+  // default, and it has three outcomes rather than two — local, remote, and
+  // unknown. Unknown behaves exactly as the tool did before any of this existed
+  // (the file:// URL, no warning), because a wrong "local" prints a dead link
+  // and a wrong "remote" warns at someone whose link works fine. An
+  // unrecognised value falls through to "detect", so a typo cannot become a
+  // confident answer. Default: detect.
+  //
+  // `servePort` is the default port for `spec-env review serve`, which renders
+  // every spec's diff per request on one local server. `--port` overrides it per
+  // run. The server binds 127.0.0.1 unless `--host 0.0.0.0` is passed, which
+  // mints an unguessable path token and prints the LAN URL including it —
+  // anyone holding that URL can read every spec's diff while it runs.
+  // Default: 7777.
+  //
+  // `serveOnRemote` is whether a "remote" reader may have that server started
+  // FOR them. On (the default) the engine brings it up, binds 0.0.0.0, and puts
+  // the served URL on the `open:` line — best-guess network address first, the
+  // rest listed under it, because the guess reads interface names and a VPN or
+  // an unusual adapter will fool it. Off, you get the file:// URL with its
+  // "will not open where you are reading" marker and the command to type.
+  // Either way NOTHING IS PUBLISHED on a detection: a server is one process
+  // ended by one flag, while a published page is one this tooling cannot
+  // remove, so that half stays an explicit ask. Teardown names a server that
+  // served the last spec, and `spec-env prune` reaps a pidfile whose process is
+  // gone. Default: true.
+  //
+  // `commitWith` names the skill a COMMITTING verdict hands off to. A review
+  // page ends in a verdict — commit, commit & continue, request changes,
+  // discuss — and the point of the first two is that the commit follows from
+  // the reading rather than costing a separate decision. Skitterspec never
+  // commits through a skill it vendored: `/commit` ships with skittership, a
+  // different package, and a copy living here would fork it. Two shapes:
+  //   "/commit"  — the default; hand off to skittership's commit skill.
+  //   "<name>"   — any other skill your project installs.
+  // With the named skill unavailable, the committing branch commits directly —
+  // stage, typecheck, test, conventional message — and SAYS it took that path,
+  // because a commit made under rules nobody configured must not read as one
+  // made under /commit.
+  //
+  // THERE IS NO OFF SWITCH. `"none"` existed and was removed: it produced a
+  // verdict that records itself and does nothing, which is the one thing a
+  // 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",
+    "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 }