@skitterbyte/skitterspec-linear 14.0.0 → 17.0.0

package/MIGRATION.md

@@ -1,5 +1,303 @@
 # 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
+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.
+
+**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
+`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
@@ -41,8 +339,10 @@ 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
+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.
@@ -76,8 +376,8 @@ 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.
+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.

package/README.md

@@ -69,6 +69,39 @@ Add `--diff` to see those changes as a unified diff before deciding whether to
 re-apply your edits on top, or `--force` to take the package version and lose
 them. Your `specs/` content and live `.core` config are never touched.
 
+## Everything it ships
+
+<!-- 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 |
+| `/spec-push` | Repo → Linear, one-way |
+| `/spec-status` | Read-only drift report |
+| `/spec-list` | What the tracker holds, with each spec's folder name |
+| `/spec-claim` | Take a spec, hand it back, or hand it to a teammate |
+| `/spec-sync` | The `spec-sync` engine, for CI and local runs |
+| `/spec-linear-setup` | Connect this repo to a Linear team |
+<!-- commands:end -->
+
+**The whole base is here**, because this is a strict superset — install this
+*instead of* `@skitterbyte/skitterspec`, never alongside it. The base README
+documents the review loop, the gate and the `review.*` keys; everything below is
+what the Linear half adds on top.
+
 ## What the superset adds
 
 On top of the base skills (`/spec`, `/spec-start`, `/spec-next`, isolation, …):
@@ -126,7 +159,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/SETUP.md

@@ -234,18 +234,22 @@ Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog
 **Open questions**) are stripped from the pushed description — they never leave
 the repo.
 
-### Assignment (opt-in)
+### Assignment (on by default)
 
-Add `"assignee": "push"` to `sync.fieldOwnership` and the spec issue is assigned
-to whoever is building it: `/spec-start` records them, and the issue is released
-automatically when the spec completes. Left out, nothing about it happens at all
-— see **Assignment** in `linear.config.md` for the full rules.
+The spec issue is assigned to whoever is building it: `/spec-start` records them,
+and the issue is released automatically when the spec completes. To decline it,
+set `"assignee": "none"` in `sync.fieldOwnership` (or pass `--no-assign` to
+`spec-sync init-config`) — see **Assignment** in `linear.config.md` for the full
+rules.
+
+It cannot overwrite an assignment a PM made in Linear: a spec that records nobody
+sends nothing, and only an assignee this repo pushed is ever cleared.
 
 You do not configure *who you are*: it comes from your own API key. Check it
 with `skitterspec spec-sync whoami` (`--set` overrides it if the key is shared or
 a bot's), and `skitterspec spec-sync users <name-or-email>` looks somebody up.
 `skitterspec spec-sync doctor` reports the resolved identity, and stays quiet
-about it in a project that has not opted in.
+about it in a project that declined the field.
 
 ## 7. What to commit
 

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