@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/assets/core/env.config.md

@@ -5,7 +5,7 @@ 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
+<up|nospec|main|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
@@ -21,8 +21,27 @@ port block, and no `.env`.
 exactly as it does today.
 
 The loader (`src/env/config.js` → `loadEnvConfig`) merges your file over the
-frozen defaults below and returns `{ config, present }`; `present:false` means
-no live `env.config.json` was found.
+frozen defaults below and returns `{ config, present, unknown }`;
+`present:false` means no live `env.config.json` was found.
+
+**A key not listed below is ignored — and says so.** Every `spec-env` command
+prints one advisory line per unrecognised key, top-level or nested:
+
+```
+spec-env: env.config.json — unknown key "docker.portbase" is ignored.
+```
+
+It is advisory in the strongest sense: the key is dropped exactly as it always
+was, nothing refuses, and the exit status is unchanged. It exists because the
+two things an unknown key can be — a deliberate forward-compat entry and a typo
+— are indistinguishable from here, and only one of them is a mistake you would
+want to hear about. A mis-typed `review.required` leaves the commit gate on and
+a mis-typed `teardown.deleteRemoteBranch` reverts to `prompt`; before this, the
+only signal either gave was that nothing happened.
+
+A **known** key whose value is rejected — `mode: "Checkout"`,
+`teardown.deleteRemoteBranch: "yes"` — is not reported here. Each of those falls
+through to a documented conservative default; see the field notes below.
 
 ## Fields
 
@@ -61,6 +80,12 @@ no live `env.config.json` was found.
     // worktree-only. false = every spec is worktree-only and the escalation is
     // hidden. (Was "always provision Docker" in the pre-Stack engine.)
     "enabled": true,
+    // Passed as `-f` to `docker compose` on up and down, but ONLY when the file
+    // is actually there — a project whose file has a name docker finds by
+    // itself keeps working untouched. It is also the signal that lets a spec
+    // with no `Stack:` header inherit `enabled` above: the switch is a
+    // project-wide default, the file is evidence there is a stack to bring up.
+    // An explicit header is checked first and never consults it.
     "composeFile": "docker-compose.yml",
     "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
     "portBase": 3000,          // first port of slot 0's block
@@ -85,6 +110,10 @@ no live `env.config.json` was found.
   //          worktree). The main checkout is resolved robustly at run time via
   //          `git rev-parse --git-common-dir` — no hardcoded repo name or path.
   // Shorthand: `"seedFiles": [".env", …]` == `{ "mode": "symlink", "files": […] }`.
+  // `.env` is an ILLUSTRATION, not an expectation — skitterspec never reads any
+  // of these files, it only links or copies them. Name whatever your stack keeps
+  // out of git: `appsettings.Development.json` or a user-secrets file, `.envrc`,
+  // `local.settings.json`, `config/local.yml`.
   // Seeded files are gitignored, so they never make the worktree "dirty" and
   // never block teardown; they vanish with the worktree at `spec-env down`.
   // [] (or absent) = seed nothing (current behaviour).
@@ -222,13 +251,15 @@ no live `env.config.json` was found.
 
   // 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).
+  // `reader` decides how the page's LOCATION IS WORDED. It no longer decides
+  // the bind — `allowNetwork` does, see below — and it no longer decides which
+  // tiers are offered, because every tier is now listed whatever it says.
+  // WHAT THE SERVER
+  // BINDS TO — and nothing else. It never decides whether to serve (`serve`
+  // does) and never decides to PUBLISH. Three values:
+  //   "local"  — you are at the machine holding the page; it binds 127.0.0.1.
+  //   "remote" — you are not; it binds every interface so the page opens.
+  //   "detect" — work it out (the default); cannot-tell binds 127.0.0.1.
   // 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
@@ -238,25 +269,81 @@ no live `env.config.json` was found.
   // 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.
+  // `servePort` is the port for `spec-env review serve`, which renders every
+  // spec's diff per request on one local server. Two forms:
   //
-  // `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.
+  //   "auto" (the default) — derive it from this repo's path, as
+  //     7700 + hash(realpath(repoRoot)) % 100. Two repos on one machine stop
+  //     competing for one shared port without anyone configuring anything, and
+  //     — the part that matters — THE SAME REPO GETS THE SAME PORT EVERY TIME.
+  //     The derivation reads nothing on disk, so the port survives a restart, a
+  //     reboot and a `--stop`, which is what lets a link handed out yesterday
+  //     still resolve. A symlinked spelling of the tree resolves first, so one
+  //     repo never lands on two ports.
+  //   <a number> — pin it. An explicit number always wins, and pinning is what
+  //     you do when you want a port you can memorise, or when two repos derive
+  //     the same one.
+  //
+  // A derived port CAN still collide — a hundred slots is a small chance, not
+  // no chance — and the server refuses rather than moving itself aside. The fix
+  // it names is `servePort`, because that is what the next link is built from;
+  // `--port` moves one run and leaves every link already handed out pointing at
+  // the busy port. `spec-env review serve --status` prints the port and which
+  // of the three chose it.
+  //
+  // An unrecognised value falls through to "auto", like every other typed key
+  // here. Default: "auto".
+  //
+  // 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.
+  //
+  // `serve` is whether a render stands the local server up at all:
+  //   "always" — every render does (the default), so `local:` and `network:`
+  //              are both http URLs the page can POST a verdict back to. The
+  //              LAN address comes first with the rest listed under it, because
+  //              the guess reads interface names and a VPN or an unusual
+  //              adapter will fool it.
+  //   "never"  — `local:` is a file:// URL instead. Note what that costs: a
+  //              file:// page has no server to POST to, so its verdict buttons
+  //              copy a command for you to paste rather than sending anything.
+  // It replaced `serveOnRemote`, which gated serving on the reader — and so
+  // handed a local machine a page it could read and not answer. A legacy
+  // `serveOnRemote: false` is still read as `serve: "never"`.
   // 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.
   //
+  // `allowNetwork` and `allowRemote` decide WHICH TIERS a render offers, and
+  // they replaced the engine guessing where the reader was sitting. It guessed
+  // for a while and got it wrong three separate ways in one day: a file:// page
+  // on a session detected `unknown`, a LAN URL for a phone that had left the
+  // network, and an address that changed underneath a reader mid-session. So
+  // every tier is listed, labelled, and either a URL or the one command that
+  // turns it on — and you pick the one that reaches you.
+  //
+  //   `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
+  //                    page opens on your phone, or loopback only. THIS IS WHAT
+  //                    CHOOSES THE BIND; `reader` no longer does. Default: true,
+  //                    which matches what the engine already did.
+  //   `allowRemote`  — whether PUBLISHING is permitted at all. It permits it; it
+  //                    publishes nothing. Default: FALSE, because a published
+  //                    page is one skitterspec cannot delete, so it must never
+  //                    happen unasked.
+  //
+  // `local` and `network` are two doors into ONE ROOM — the page POSTs to
+  // `location.pathname`, so both reach the same server and the same waiting
+  // verdict, and one wait covers both. `remote` is a second store: a verdict
+  // pressed on a published page needs `/spec-reviewed`, because nothing pushes
+  // from an artifact's store into a conversation.
+  //
+  // Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
+  // empty value toggles — which is what `/spec-remote-review` runs. It writes
+  // THIS FILE in the primary checkout, so it changes for everyone who pulls and
+  // leaves that tree dirty; the engine says so when it does.
+  //
   // `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
@@ -287,12 +374,83 @@ no live `env.config.json` was found.
   //            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.
+  //
+  // `reviewers` lists EXTERNAL CODE REVIEWERS whose findings render on the page
+  // as CHECKS, beside (or instead of) a written review. Empty by default, and
+  // `init` never writes one.
+  //
+  //   READ THIS BEFORE ADDING ONE. A reviewer is a command run in the spec's
+  //   worktree, and every hosted one sends that worktree's diff to a third
+  //   party. Nothing else in skitterspec leaves your machine — the page is a
+  //   local file, the server binds your own network, and the diff never reaches
+  //   a model. Configuring a reviewer changes that, deliberately and only
+  //   because you asked. Every finding on the page is badged with the reviewer
+  //   that produced it, so it stays visible where the code went.
+  //
+  // Two entry shapes, told apart by which key is present:
+  //   { "use": "<adapter>" }
+  //       A bundled adapter. The engine owns its command line and its parser,
+  //       so this is the whole configuration. One ships today: "coderabbit",
+  //       which drives `cr review --agent` (a free tier, rate-limited per
+  //       hour; `cr auth login` first). A `use` this build does not have is
+  //       reported on stderr and does not run.
+  //       Its adapter also does the one thing a shell script cannot: it tells
+  //       ITS OWN refusals — not authenticated, rate limited, no network —
+  //       apart from a review that ran and found nothing.
+  //   { "name": "<label>", "command": "<shell>", "format": "rdjsonl" }
+  //       Bring your own. `name` is what the page badges findings with, and
+  //       `command` is a shell line run with the worktree as its cwd.
+  // Both take an optional `timeout` in seconds (default 180).
+  //
+  // `format` is the output contract, and today there is one: `rdjsonl` — one
+  // JSON object per line, reviewdog's diagnostic shape:
+  //   {"path":"src/a.js","range":{"start":{"line":12}},"severity":"ERROR","message":"…"}
+  // A flat `"line": 12` is read too. Most linters already emit this, so a
+  // project gets non-AI checks on the same page for free, and an adapter for
+  // anything else is a twenty-line script that prints rdjsonl.
+  //
+  // `command` may carry `${scope}` (`working` | `branch`), `${base}`,
+  // `${spec}` and `${worktree}`. `scope` matches the render's own two modes —
+  // a phase-end render is `working` (uncommitted + untracked in the worktree)
+  // and `--branch` is the whole spec against its base — so what the page shows
+  // is what was reviewed. An unknown `${…}` is left verbatim rather than
+  // blanked, so a typo shows up in the command that failed instead of silently
+  // becoming an empty argument.
+  //
+  // `severity` maps to the page's levels: `ERROR` → `flag`, everything else →
+  // `confirm`. Never `good` — that means "I read this and it is right", which
+  // is a thing a person says.
+  //
+  // FINDINGS NEVER GATE A COMMIT. They are checks, and `judgeVerdict` refuses a
+  // committing verdict only while a COMMENT is unresolved. A comment is
+  // something a person asked for; twelve machine findings are not. Reply to one
+  // on the page and that reply IS a comment — which does gate, because now
+  // someone asked. There is deliberately no severity threshold that blocks:
+  // that is the counting gate this whole design exists against, and it makes a
+  // reviewer's bad day into a wall.
+  //
+  // A REVIEWER THAT COULD NOT RUN SAYS SO, rather than staying silent — the one
+  // place `.claude/rules/negative-checks.md` inverts. Silence is normally the
+  // safe branch; here a rate-limited or unauthenticated reviewer would render
+  // identically to one that read the diff and found nothing, on the page a
+  // commit decision is made from. So every configured reviewer gets a line:
+  // `12 findings` · `clean` · `cached` · `did not run — <why>`. Nothing exits
+  // non-zero and nothing refuses — a reviewer that could not run never blocks a
+  // render, a verdict or a commit.
+  //
+  // They run in SEQUENCE, at the end of a phase and on demand (`/spec-diff
+  // --reviewers`), and the results are cached against a hash of the diff — so
+  // re-rendering unchanged work reuses them rather than spending another review
+  // against an hourly limit. An entry that is neither shape is dropped and
+  // REPORTED on stderr; it cannot be caught by the unknown-key check, because
+  // this default is an array. Default: [].
   "review": {
     "reader": "detect",
-    "servePort": 7777,
-    "serveOnRemote": true,
+    "servePort": "auto",
+    "serve": "always",
     "commitWith": "/commit",
-    "required": true
+    "required": true,
+    "reviewers": []
   }
 }
 ```

package/assets/hooks/main-guard.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Main guard — the harness half.
+ *
+ * `main` is where work **lands**, not where it happens. The skills say so, and
+ * a skill is prose: it can be chained past, typed around, or simply not read.
+ * So the rule is also enforced one level down, where an `Edit` or a `Write` is
+ * a tool call the harness has to ask about first.
+ *
+ * IT REFUSES THE FIRST WRITE, NOT THE COMMIT, and that is the whole reason it
+ * is a different hook from `review-gate.cjs` rather than another branch inside
+ * it. Nothing has been written when this fires, so the fix costs one command —
+ * `/no-spec <name>` and carry on. A commit-time gate fires once the work
+ * already exists in the primary checkout, and in worktree mode moving it is the
+ * genuinely painful part: the primary checkout cannot `switch -c` out from
+ * under the other worktrees.
+ *
+ * THIS SCRIPT DECIDES NOTHING. It reads the tool call, hands the directory to
+ * `spec-env main check`, and turns one exit status into an answer. Every
+ * judgement — is isolation configured, is this the primary checkout, is HEAD
+ * the base branch, is an allow in force — 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, for the same reasons `review-gate.cjs` does and
+ * with more at stake, because this one fires far more often. No engine, an
+ * unreadable payload, a repo with no isolation, a crash of its own — all of
+ * them allow the write. Being wrong the permissive way costs one edit on a rule
+ * the skills also carry; being wrong the other way costs someone their work
+ * with no idea why (`.claude/rules/negative-checks.md`).
+ */
+
+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 the
+// overwhelming majority of invocations must do.
+function allow() {
+  process.exit(0)
+}
+
+/**
+ * Refuse, and say what to do instead.
+ *
+ * The JSON route rather than exit-2, because the reason reaches **Claude** —
+ * which is who has to act on it, by moving the work rather than by asking the
+ * user to switch the guard off. The 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. Identical to `review-gate.cjs`'s, deliberately: 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`.
+ */
+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'
+}
+
+// The tools that write a file. A matcher is configured too, but a hook that is
+// reached some other way must still be inert rather than guessing.
+//
+// WHAT WOULD FOOL THIS: a write that does not go through a write TOOL — a shell
+// heredoc, `sed -i`, an editor outside the session. Those are left unguarded on
+// purpose. Covering them would mean parsing arbitrary shell for filesystem
+// effects, which cannot be done reliably, and the failure mode of getting it
+// wrong is refusing a command that has nothing to do with writing files. The
+// skills carry the rule for everything this matcher cannot see.
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
+
+function main() {
+  const payload = readPayload()
+  if (!payload) allow()
+
+  if (!WRITE_TOOLS.has(payload.tool_name)) allow()
+
+  // The write's own directory decides the answer — a worktree is its own
+  // checkout, and only the primary one is this guard's business.
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
+  const session = typeof payload.session_id === 'string' ? payload.session_id : ''
+
+  const argv = ['spec-env', 'main', 'check', '--dir', cwd]
+  if (session) argv.push('--session', session)
+
+  const result = spawnSync(findEngine(cwd), argv, { 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())
+}
+
+// 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 write through.
+    allow()
+  }
+}
+
+module.exports = { findEngine, WRITE_TOOLS }

package/assets/hooks/review-gate.cjs

@@ -121,9 +121,14 @@ function main() {
 
   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>"',
+      '\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
+      'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
+      'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
+      'reason recorded.\n\nAll three are theirs to type. /spec-skip is the same ' +
+      'exit as \'skitterspec spec-env review skip "<reason>"\' — a command ' +
+      'rather than an incantation, because the long form is what nobody retypes ' +
+      'and a gate with an unreachable exit gets switched off wholesale instead ' +
+      'of answered.',
   )
 }