@skitterbyte/skitterspec 21.0.0 → 22.0.0

package/MIGRATION.md

@@ -1,5 +1,203 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v21 → v22 (a review port per repo, and every render serves)
+
+### Breaking change 1 — `review.serveOnRemote` is now `review.serve`
+
+**Every render now stands the review server up**, and hands back an `http://`
+URL instead of a `file://` one. It used to serve only when it detected that you
+were reading from somewhere else — and that detection reads three environment
+variables, so a plain local terminal got a `file://` page. A `file://` page has
+**no server to POST to**, so the verdict buttons on it had nowhere to go: the
+press-a-button-and-the-work-continues loop was missing from exactly the sessions
+that are easiest to use.
+
+**Which interfaces it listens on is `review.allowNetwork`** — see breaking
+change 3, below. The change here is narrower than it looks: `file://` →
+`http://127.0.0.1`, a page that opens on the machine holding it and, unlike
+`file://`, can answer. Serving more never means listening wider; that is one
+setting, and it is not this one.
+
+**What to change.** `review.serveOnRemote: false` is still read as the new
+`review.serve: "never"`, so a config that turned serving off keeps working. The
+key is renamed because the old name would now claim to govern remote renders
+while governing every one of them:
+
+```jsonc
+// specs/.core/env.config.json — before
+"review": { "serveOnRemote": false }
+// after
+"review": { "serve": "never" }
+```
+
+`serveOnRemote: true` needs no translation — `"always"` is the default and does
+what it did. Note what `"never"` costs you: the page falls back to `file://`,
+and its buttons copy a command for you to paste rather than sending anything.
+
+**A render that could not serve now says why** — `review.serve is "never"`, or
+the failure naming the port to free — on the `open:` line and in `--json` as
+`notServed`. A `file://` link with nothing said about it used to be the ordinary
+outcome; now it can only mean the ask did not land.
+
+**A spec with no worktree is served too.** A spec you have only just written has
+no branch of its own, and the served route used to refuse it — so its page
+existed and 404'd. It is now served as its own documents, listed in the index,
+and accepts a verdict.
+
+### Breaking change 2 — a review port per repo
+
+**`review.servePort` now defaults to `"auto"`, not `7777`.** A repo that does
+not pin the key moves to a port derived from its own path —
+`7700 + hash(realpath(repoRoot)) % 100` — the first time `spec-env review serve`
+starts after the upgrade.
+
+**The one-time break is a link, and only a link.** A review page open on a
+phone at that moment points at `7777`, and `7777` is no longer this repo's
+server. The verdict you press there goes nowhere. **Re-render the page** —
+`/spec-diff`, or `/spec-next`'s own render — and the new link works. Nothing on
+disk is lost, no pass is dropped, and this happens once.
+
+**Why not simply keep 7777.** It was shared by every repo on the machine, so the
+second repo to start was refused, whoever hit that passed `--port`, and the
+links they had already handed out pointed at another repo's daemon — a `404`,
+reported in a grey line in the page footer. A derived port is stable for a given
+tree across a restart, a reboot and a `--stop`, which is what a link handed out
+yesterday needs.
+
+### To keep a fixed port
+
+Pin it, and nothing derives:
+
+```jsonc
+// specs/.core/env.config.json
+"review": { "servePort": 7777 }
+```
+
+An explicit number always wins, exactly as it did before. Pin one when you want
+a port you can memorise, or when two repos happen to derive the same one — a
+hundred slots is a small chance of that, not no chance, and the server still
+refuses a busy port rather than moving itself aside.
+
+`spec-env review serve --status` now prints the port **and which of the three chose it** —
+`--port`, `review.servePort`, or the derivation.
+
+### Breaking change 3 — the reader no longer decides the bind: `review.allowNetwork` does
+
+**Two new keys, and one of them changes a default.** The engine used to guess
+where you were reading and pick a surface for you. It guessed 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 when detection flipped mid-session. So it stopped guessing:
+every render now lists every tier, labelled, in a fixed order.
+
+```jsonc
+// specs/.core/env.config.json — the new keys, with their defaults
+"review": {
+  "allowNetwork": true,   // the server binds every interface, so the page opens on your phone
+  "allowRemote": false    // publishing is permitted at all — it permits, it never publishes
+}
+```
+
+**`allowNetwork` defaults to `true`, and that is the behaviour change to read before upgrading.**
+Before, a local or unknown reader got a loopback bind and a
+remote one got every interface; now the setting decides, and its default is the
+wide bind — which is what a remote reader already got, applied to every render.
+The URL still carries the **serve token**, 48 random bits minted per server,
+which remains the only thing deciding who can POST a verdict. A machine you
+would rather not expose sets `"allowNetwork": false`, and `network:` then reads
+`off` with the command that turns it back on.
+
+**`allowRemote` defaults to `false`** and permits publishing without performing
+it — a published page is one skitterspec cannot delete, so it stays an explicit
+ask either way.
+
+**`review.reader` still exists** and now decides only how a page's location is
+*worded*. It no longer chooses the bind and no longer chooses which tiers appear.
+
+### `/spec-remote-review` — a new slash command
+
+Toggles `review.allowRemote`, and takes `on`/`off` when you would rather say
+which. It exists because a render's `remote:` line has to name something you can
+act on, and `skitterspec spec-env review allow remote` is not what anyone
+reconstructs from a page they are reading on a phone. `init` and `update`
+install it with the other commands; like them it is user-only, so nothing but you
+can run it.
+
+**It writes `specs/.core/env.config.json` in the primary checkout** — a
+committed file, so it changes for everyone who pulls and leaves that tree dirty.
+The engine says so when it does.
+
+## `@skitterbyte/skitterspec-linear` v16 → v17 (a review port per repo, and every render serves)
+
+The same two changes as `@skitterbyte/skitterspec` v21 → v22 above — this
+distribution composes the same engine. Read that entry; nothing here is
+Linear-specific.
+
+**If you are coming from v15, read the v15 → v16 entry below as well.** 16.0.0
+was bumped in the repo and never published, so npm went 15 → 17 and both
+entries apply to you.
+
+## `@skitterbyte/skitterspec-linear` v15 → v16 (assignment is on by default)
+
+### Breaking change
+
+**A spec's Linear issue is now assigned to whoever is building it.**
+`sync.fieldOwnership.assignee` defaults to `"push"`; it was absent
+before, and absent meant inert. From this version `/spec-start` stamps the
+developer on the spec and the push assigns the issue, and `/spec-complete`
+releases it — on every repo that has not said otherwise.
+
+**To decline it**, one line in `specs/.core/linear.config.json`:
+
+```jsonc
+"sync": {
+  "fieldOwnership": {
+    "assignee": "none"
+  }
+}
+```
+
+`none` is a new value in the ownership enum (`both|pull|push|none`) and means
+*this repo does not own the field*: nothing is written, no hash is recorded in a
+snapshot, and `spec-sync status` prints no assignee line — identical in every
+respect to the old behaviour of never listing it. It has to be a value rather
+than an omitted key, because the map merges **per key** onto the defaults: once
+a field is owned by default, there is nothing an absent key can subtract.
+
+**An explicit `"assignee": "push"` you already had is now redundant and harmless.**
+Nothing rewrites it and nothing needs to.
+
+### It cannot overwrite a PM's triage, and that is by construction
+
+The concern this default has to answer is whether upgrading re-assigns or
+un-assigns issues someone else owns. It cannot, for two reasons that predate it:
+
+- **A spec that records no assignee sends none.** Only a spec the repo itself
+  stamped is ever pushed, so an issue a PM assigned in Linear is left alone.
+- **A snapshot with no assignee key means "never pushed", not "was null".** Every
+  spec linked before this existed has exactly such a snapshot, and the diff emits
+  a *clear* only against an assignee it has a recorded hash for.
+
+So the flip widens who gets **assigned** — specs you start from now on — and
+cannot widen who gets **unassigned**. There is a regression test pinning this
+(`sync-assignee-projection.test.js`, "THE UPGRADE CASE").
+
+### `spec-sync init-config --assign` is gone; `--no-assign` replaces it
+
+The flag's meaning inverted with the default, so it is removed rather than kept
+as a silent no-op — a flag that still parses and does nothing would read as
+"assignment configured" to anyone who wrote it before v16. `--assign` now fails
+as an unknown flag, which is the louder and more useful answer. `--no-assign`
+writes the `"none"` opt-out above.
+
+### `spec-sync assign` now refuses a field the repo does not own
+
+Previously it stamped the frontmatter in any repo and printed
+`next: push it, so Linear agrees` — while `toFieldSet` dropped the field, so the
+push never carried it. It now refuses, naming `sync.fieldOwnership.assignee` and
+the value that enables it. Only `/spec-claim` enforced this before, so a script
+or a direct CLI call got the untrue sentence.
+
 ## `@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
@@ -21,6 +219,26 @@ The upgrade migrates you: your existing `PreToolUse` entry has its path
 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.
 
+**Check whether you already had a `review-gate.cjs` of your own.** `.cjs` is the
+obvious way to work around the v20 crash, so anyone who fixed it by hand most
+likely picked this exact filename — and this upgrade is the moment skitterspec
+starts managing that path. A file already sitting there is **kept**, the real
+hook is therefore never installed, and `review-gate.js` is pruned out from under
+it. A hand-written shim that only `require`d the old script then fails open, so
+the gate is silently absent under an update that reported success.
+
+Two lines settle it:
+
+```
+head -3 .claude/hooks/review-gate.cjs        # ours opens with a 'use strict' + a doc comment
+npx @skitterbyte/skitterspec update --check  # a line naming this path means yours was kept
+```
+
+If it is yours, take ours — `npx @skitterbyte/skitterspec update --force`, or
+delete the file and re-run `update`. Later versions report this case in its own
+words rather than as `your edit — kept`, but the manifest records the path after
+the first upgrade, so that wording cannot reach anyone who has already run one.
+
 ### Bug fix
 
 **`skitterspec update` now registers the hook.** v20's notes said `init` and

package/README.md

@@ -9,11 +9,31 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
                           ↳ /spec-diff — read what the phase changed
 ```
 
-Ships the spec-lifecycle skills (`/spec`, `/spec-start`, `/spec-next`, `/spec-complete`,
-`/spec-cancel`, `/spec-bug`, `/spec-hotfix`, `/spec-review`, `/spec-diff`,
-`/spec-init`) plus per-spec **isolation** — a git worktree per in-progress spec,
-Docker on demand, host dev servers on reserved ports, and `/spec-connect` to test
-a worktree at your normal `localhost` URL.
+Ships per-spec **isolation** — a git worktree per in-progress spec, Docker on
+demand, host dev servers on reserved ports — and everything below.
+
+<!-- commands:start -->
+| | |
+|---|---|
+| `/spec` | Grill to a shared understanding, then write a groomed spec |
+| `/spec-bug` | Reproduce with a failing test, then drive it red→green |
+| `/spec-hotfix` | Fix the released version: fork from a tag, land by tag + cherry-pick |
+| `/spec-review` | Re-validate a spec against the code; refresh what drifted |
+| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 |
+| `/spec-next` | Build the next phase of the spec in flight |
+| `/spec-diff` | Read what a phase changed, on a page you can mark up |
+| `/spec-reviewed` | Pick up a verdict pressed when nothing was waiting for it |
+| `/spec-to-main` | Land the branch mid-spec, without finishing it |
+| `/spec-complete` | Verify, land, tear down |
+| `/spec-cancel` | Record why, stamp the header, tear down |
+| `/spec-init` | Bootstrap or repair the workflow in a project |
+| `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
+| `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
+| `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
+<!-- commands:end -->
+
+The last three are **slash commands** rather than skills: each pre-executes one
+`skitterspec spec-env` verb and relays it, so only you can run them.
 
 ```sh
 npx @skitterbyte/skitterspec init
@@ -78,6 +98,93 @@ is; the optional *written* review (a short read plus `flag`/`confirm`/`good`
 notes) is the part that costs, and it is offered rather than assumed. Publishing
 is always opt-in, and one page per spec — later phases update the same link.
 
+### The page takes a verdict back, and the phase waits for it
+
+Reading is half of it. The page also takes marks — tick `✓ accept` per file as
+you read, write a note against a line or a whole file, answer the questions a
+written review asked — and then **ends in a decision**:
+
+| Button | Does |
+|--------|------|
+| `✓ Commit` | commits the phase, and stops |
+| `✓ Commit & Continue` | commits, then builds the next phase — and stops there |
+| `✓ Commit & Start` | on a freshly written spec: commits it and puts it in flight. The `commit && /spec-start` you would otherwise type |
+| `↺ Request changes` | sends your notes straight back to be worked |
+| `… Discuss first` | reports what you wrote and asks what's up |
+
+The last one appears only on a spec's own page — a spec with no phase in flight
+has nothing to continue — and `▶ Put it live` sits above them all, which is not
+a verdict: it commits the phase, checks the branch out where your dev server can
+see it, and hands you back the same page. It clears no gate.
+
+**`/spec-next` ends a phase by rendering the page and then watching for that press**,
+so the button is what carries the work on — there is no command to
+remember. A press on a page the engine served reaches it directly; a `file://`
+page has no server to talk to, so it copies the pass and you paste it.
+
+**A verdict sent when nothing was watching is not lost.** Type
+**`/spec-reviewed`** to pick it up — bare when one is waiting, or
+`/spec-reviewed 324199` to name one exactly, which matters only when two are.
+It is the only path the harness itself enforces: the model cannot run it, so a
+pass picked up that way is only ever picked up because a person asked.
+
+Fixes come back as **resolutions**, so the next render shows each note struck
+through with a one-line account of what changed — you verify the fix rather than
+trusting it. An accept remembers the file's content, so it lapses by itself when
+that file changes again, announced rather than silent.
+**The marks are information, never a gate**:
+nothing counts them, and the verdict is the one thing you choose, once.
+
+### A phase that ended owes an answer
+
+The **gate** is armed when a phase ends and its page is rendered, and exactly two
+things clear it: a committing verdict, or
+`skitterspec spec-env review skip "<reason>"`. While it is armed `/spec-next`
+refuses to build the next phase, and — where the hook is installed —
+`git commit` refuses in that worktree. Mid-phase renders arm nothing, every
+cannot-tell exits 0 and says nothing, and `review.required: false` turns it off
+for a project. The exit is always one command, and one of them is *"I am moving
+on"* with the reason on the record.
+
+### Where the page can be read
+
+Every render prints one line per surface, labelled, so you pick the one that
+reaches you rather than the engine guessing:
+
+```
+local:   http://127.0.0.1:7760/7e9e123e7540/feat-orders
+network: http://192.168.0.136:7760/7e9e123e7540/feat-orders
+remote:  off — turn on with: /spec-remote-review
+live:    off — /spec-live to put it live
+```
+
+`local` and `network` are two doors into one room — the same server, the same
+waiting verdict — so the wait covers both. `remote` is a published page, which
+is a separate store: a verdict there needs `/spec-reviewed`, and it is off until
+you type `/spec-remote-review`. The `live:` line is the other way to judge a
+change: whether it is also **running**, and the page has a button to put it
+there.
+
+The random-looking segment in the URL is a **serve token** — 48 bits minted per
+server, and the only thing deciding who can POST a verdict at all. That, and why
+`/spec-reviewed` is user-only, are written up in
+`.claude/rules/spec-reports.md` and `.claude/rules/spec-planning.md`, which
+`init` installs into your project.
+
+### The `review.*` config keys
+
+All optional, in `specs/.core/env.config.json`:
+
+| Key | Default | Does |
+|-----|---------|------|
+| `review.serve` | `"always"` | whether a render stands the local server up. `"never"` gives you a `file://` page, whose buttons copy a command instead of sending |
+| `review.allowNetwork` | `true` | whether that server binds every interface, so the page opens on your phone |
+| `review.allowRemote` | `false` | whether publishing is permitted at all. `/spec-remote-review` toggles it; it permits publishing, it does not publish |
+| `review.required` | `true` | whether a finished phase owes a verdict |
+| `review.commitWith` | `"/commit"` | the skill a committing verdict hands off to |
+| `review.reader` | `"detect"` | where you are reading — `local`, `remote`, or detect it |
+| `review.servePort` | derived | the port, normally derived from the repo's path |
+
 `/spec-next` writes the page at the end of every phase. Nothing about it depends
 on where your shell is.
 
@@ -93,7 +200,7 @@ a question it cannot answer itself or a failure at the moment it happens:
 | **Branch** | `spec/feat-orders` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **Tests** | 128 passed · npm test |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 

package/assets/claude-md-section.md

@@ -20,24 +20,35 @@ every phase.
 
 **Handing the review back.** The page takes marks: tick `✓ accept` per file as
 you read, note anything against a line or a whole file, answer the questions a
-written review asked — then **end it in a decision**. Three buttons, each
-carrying its own verdict:
-`✓ Commit` commits it, `✓ Commit & Continue` commits and builds the next phase,
-`↺ Request changes` sends it straight back to be worked, `… Discuss first` asks
-you what's up. A **served** page hands the pass to
-the engine, which **holds** it and shows a six-digit code. Type `/spec-reviewed`
-and the waiting pass is picked up and acted on; paste the code after it
-(`/spec-reviewed 324199`) to name one exactly, which matters only when two are
-waiting. **Nothing pushes** — a device that reaches your page cannot reach this
-conversation, which is what keeps a stray approval out of your review, and is
-why the code is an address rather than a password. A `file://` page has no server to talk to, so it
-copies and you paste, as before. Approve is unavailable while a note is open —
-you asked for something, so it cannot also be fine — and it hands off to your
-own commit skill (`review.commitWith`, `/commit` by default) rather than a copy
-living here. Fixes come back as resolutions, so the next render shows each note
-struck through with what changed. An accept remembers the file's content, so it
-lapses by itself when that file changes again. The marks are information —
-nothing gates on them; the verdict is the one thing you choose, once.
+written review asked — then **end it in a decision**. At the end of a phase the
+buttons are `✓ Commit`, `✓ Commit & Continue` (commit, then build the next
+phase), `↺ Request changes` and `… Discuss first`. A spec that has just been
+written gets `✓ Commit & Start` instead — the `commit-start` verdict, which is
+the `commit && /spec-start` you would otherwise type. A **served** page hands
+the pass to the engine, which **holds** it and shows a six-digit code. Committing
+is unavailable while a note is open — you asked for something, so it cannot also
+be fine — and it hands off to your own commit skill (`review.commitWith`,
+`/commit` by default) rather than a copy living here. Fixes come back as
+resolutions, so the next render shows each note struck through with what changed.
+An accept remembers the file's content, so it lapses by itself when that file
+changes again. The marks are information — nothing gates on them; the verdict is
+the one thing you choose, once.
+
+**Above the verdicts sits one line that is not a verdict.** `▶ Put it live`
+commits the phase, checks the branch out where your dev server can see it, and
+hands you back the same page with the same options — so you can judge the change
+by *using* it, not only by reading it. It clears no gate: you have looked at it
+running and concluded nothing, so the phase still owes an answer.
+
+**Every render lists where the page can be read**, labelled, in a fixed order —
+`local`, `network`, `remote` — each either a URL or the one command that turns it
+on, plus a `live:` line saying whether the change is also running. `local` and
+`network` are two doors into one room: the same server and the same waiting
+verdict, so one wait covers both. `remote` is a published page, a second store —
+a verdict there needs `/spec-reviewed`, and it stays off until someone types
+**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
+command, never performed by it: a published page is one this tooling cannot
+remove.
 
 **One ending.** Every spec skill finishes with the same block — a verdict
 (`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,

package/assets/commands/spec-remote-review.md

@@ -0,0 +1,22 @@
+---
+description: Permit or forbid publishing a review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
+argument-hint: "[on | off]"
+allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+**Bare toggles.** That is the common case: you are looking at a render whose
+`remote:` line says which way it currently is, and what you want is the other
+one. `on` and `off` are there for when you are not looking at it.
+
+**It permits publishing; it publishes nothing.** A published page is one
+skitterspec cannot delete, so publishing stays an explicit ask
+(`/spec-diff` §6) — and a verdict pressed on one needs `/spec-reviewed`, because
+nothing pushes from an artifact's store into a conversation.
+
+**It writes a committed file.** `specs/.core/env.config.json` in the primary
+checkout, whichever tree you ran this from — so it changes for everyone who
+pulls and leaves that tree dirty. The engine says so; do not soften it.

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

@@ -40,8 +40,10 @@
   },
   "review": {
     "reader": "detect",
-    "servePort": 7777,
-    "serveOnRemote": true,
+    "servePort": "auto",
+    "serve": "always",
+    "allowNetwork": true,
+    "allowRemote": false,
     "commitWith": "/commit",
     "required": true
   },

package/assets/core/env.config.md

@@ -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
 
@@ -222,13 +241,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 +259,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:
+  //
+  //   "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.
   //
-  // `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.
+  // 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
@@ -289,8 +366,8 @@ no live `env.config.json` was found.
   // place rather than quietly disabling it. Default: true.
   "review": {
     "reader": "detect",
-    "servePort": 7777,
-    "serveOnRemote": true,
+    "servePort": "auto",
+    "serve": "always",
     "commitWith": "/commit",
     "required": true
   }