@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

package/assets/skills/spec-claim/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-claim
-description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
+description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with the repo owning assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
 disable-model-invocation: true
 ---
 
@@ -16,9 +16,17 @@ and the push that follows tells Linear. This skill is how that record changes
 after `/spec-start` has set it — a hand-off mid-flight, a spec picked up from
 someone who moved on, or work a lead is distributing.
 
-**Opt-in.** Needs `specs/.core/linear.config.json` *and* `assignee` in its
-`sync.fieldOwnership`. If either is missing, say which one and stop — without the
-field the stamp would sit in the file doing nothing.
+**Opt-in.** Needs `specs/.core/linear.config.json` *and* the repo to **own**
+`assignee` in its `sync.fieldOwnership` — which `"none"` declines as surely as
+omitting it does. If either is missing, say which one and stop: without the field
+the stamp would sit in the file doing nothing.
+
+**The engine refuses this too, and that is the point.** `spec-sync assign` checks
+the same thing and writes nothing, so the rule holds for a script, a chained
+command, and anyone who reached for the CLI directly. This paragraph was the only
+thing enforcing it for long enough that the engine's own success line —
+`next: push it, so Linear agrees` — was printed over a push that would drop the
+field. Prose in one skill is not a guard; it is a guard's documentation.
 
 ## 1. Identify the target spec
 

package/assets/skills/spec-complete/SKILL.md

@@ -95,8 +95,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
   Do not roll anything back, and do not stop to ask.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
-- **There is no unassign step, and that is not an omission.** With `assignee` in
-  `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
+- **There is no unassign step, and that is not an omission.** Where the repo owns
+  `assignee`, the projection derives it from the spec's lifecycle
   bucket — so moving the folder to `complete`/`cancelled` is *itself* what
   releases the issue, and the push above carries it like any other field. The
   `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:

package/assets/skills/spec-diff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-diff
-description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, or the pasted JSON.
+description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
 ---
 
 # /spec-diff — see the phase before you commit it
@@ -41,13 +41,19 @@ sole candidate or prints the candidates.
 The page has marks on it — `✓ accept` per file, notes against a line or a whole
 file, answers to the checks a written review asked — and it
 **ends in a decision**: `✓ Approve`, `↺ Request changes` or `… Discuss first`.
-A review comes back to you one of two ways, and **both are ordinary**:
+A review comes back to you one of three ways, and **all three are ordinary**:
 
 - **A six-digit code** — `418207`, on its own. A *served* page hands its pass
   straight to the engine, which holds it until someone reads the code out. This
   is the usual way on a phone.
-- **A pasted JSON blob** — a `file://` page has no server to talk to, so it
-  copies. Not legacy: it is the whole story for a local reader.
+- **A verdict word** — `commit`, `commit-continue`, `continue`, `changes` or
+  `discuss`. A `file://` page cannot send anything, so where the reader marked
+  nothing it copies a command carrying the conclusion on its own. Send it with
+  `skitterspec spec-env review <spec> --verdict <word>`; it joins the same merge
+  a claimed pass does, so everything below is unchanged.
+- **A pasted JSON blob** — the same `file://` page, once the reader has marked
+  something up: accepts and notes do not fit on a command line, so the whole
+  pass travels. Not legacy: it is the whole story for a local reader.
 
 Either way, **this is not a request to render anything**: it is a review coming
 back, and these steps replace §3–§5 below.
@@ -151,6 +157,10 @@ back, and these steps replace §3–§5 below.
    absent verdict has always meant "report it and wait" — which is why that is
    what it still means.
 
+   **A pass may carry an `action:` instead**, and then none of the above
+   applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
+   carrying both, so there is never a choice to make between them.
+
 3. **Say what you read, then ask what's up.** Report the accepted count, then
    each open comment as `file:line — note`, then the files you would touch.
    **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -335,6 +345,69 @@ it — and the paste was the one place it broke. The *work* either authorises is
 ordinary phase-sized cost, and step 3 is where the operator decides whether to
 spend it.
 
+## 2b. An action changes something, then hands the page back
+
+Only on a pass carrying an **action**. Three of them, and
+**all three end the same way**:
+do the thing, re-render (§4), and wait again (§4b) — because the reader
+still has a decision in front of them and has not made it.
+
+| Action | Do | Then |
+|--------|----|------|
+| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
+| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
+| `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
+
+**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
+live is about the diff on screen; handing the whole instance back to `main` is a
+workspace decision with nothing to do with this review. The `live:` line names
+`/spec-live main` for it — a command the operator types, which is also why no
+skill runs it.
+
+**AN ACTION IS NOT A VERDICT, and the gate is untouched by all three.** A phase
+that ended armed the gate, and it is discharged by a committing verdict or a
+recorded skip and by nothing else — so after any of these the phase still owes
+an answer, and that is exactly why the run waits again rather than finishing.
+The engine enforces this rather than trusting it: `ACTIONS` is disjoint from
+`VERDICTS` and `COMMITTING`, so nothing that routes on a verdict can see one.
+
+**`live-on` commits first, and the commit is a precondition rather than an answer.**
+`live take` refuses a dirty worktree, and even without that guard
+uncommitted work stays behind in the worktree — so what went live would be the
+*previous* commit while the page claimed to be showing this one. Hand off to
+`review.commitWith` exactly as §2a does (do not restate its rules here), then
+take the instance. The reader has not approved anything by pressing it.
+
+**It re-renders `--branch` afterwards**, because the working view is now empty:
+the commit just happened, and the branch range is what still answers "what am I
+looking at". §4's clean-tree fallback reaches the same place on its own, so
+passing `--branch` is belt and braces rather than a separate rule.
+
+**A mid-phase page does not get the commit.** Where the render took
+`--buttons midrun`, the work is half a phase — committing it to look at it
+running splits one phase across two commits and leaves a mess nobody asked for.
+Say the phase needs to land first, re-render, and wait.
+
+**Relay every refusal, and work around none of them.** `live take` refuses a
+workbench another spec holds, a hotfix, a stateful spec, a branch touching
+migrations, and a tree with no dev server listening. Each refusal names its own
+way out. **Never park another spec's live session** to make room — that is
+someone else's work, and freeing it is their decision. Re-render and wait, so
+the reader can choose something else.
+
+**`allow` writes a committed file, and that is worth a sentence.** It edits
+`specs/.core/env.config.json` in the **primary checkout**, so it changes
+behaviour for everyone who pulls and leaves that tree dirty — unlike the live
+actions, which move a branch and write a gitignored receipt. The engine prints
+the absolute path and whose tree it dirtied; relay that rather than letting a
+shared setting change land silently. And it is **enable-only**: there is no
+action that turns a tier off, because turning `network` off from a page reached
+over the network kills the page doing the turning.
+
+**`allow remote` permits publishing. It does not publish.** Publishing stays an
+explicit ask in every case (§6), because the page it leaves behind is one this
+tooling cannot remove.
+
 ## 3. Gate it on nothing
 
 **This skill has no preconditions and must never grow one.** Not tests passing,
@@ -367,15 +440,17 @@ skitterspec spec-env review <spec> --branch     # everything since the base bran
 skitterspec spec-env review serve               # every spec, on localhost
 ```
 
-**The engine handles the switch.** A file when the reader is at this machine, a
-served URL when they are not: on a `remote` reader it stands its own server up
-and puts a URL the reader can open on the `open:` line. Both are free and neither
-publishes anything. You are not choosing between them; you are relaying whichever
-one the engine printed.
+**There is no switch left to handle.** The engine serves and prints a **stack** —
+one line per tier, `local`, `network`, `remote`, each either a URL or the one
+command that turns it on. All of it is free and none of it publishes anything.
+You are not choosing between them; you are relaying every line it printed.
+`.claude/rules/spec-reports.md` carries the shape and why.
 
-The operator who does not want a LAN listener started for them sets
-`review.serveOnRemote: false` in `env.config.json`, and the `file://` link with
-its *will not open where you are reading* marker comes back.
+The operator who does not want a LAN listener sets `review.allowNetwork: false`
+in `env.config.json` — `network` then reads `off` with the command that turns it
+back on, and `local` is the loopback page. Turning serving off entirely is
+`review.serve: "never"`, and then `local` is the `file://` page, which says on
+its own line that it cannot send a verdict.
 
 `serve` renders **per request**, so nothing it shows can be stale, and it lists
 every spec with a worktree rather than one. `--host 0.0.0.0` binds beyond
@@ -428,21 +503,29 @@ committing verdict or a recorded skip.
 
 **On `--page-only`, stop here** and report the path.
 
-## 4a. Read the `reader:` line — never sniff for it yourself
-
-`spec-env review` reports where it believes the reader is, and
-**that is the only place this question is answered.** Three states:
-
-| `reader:` | What to offer |
-|-----------|---------------|
-| absent (`unknown`) | the `file://` URL, exactly as always. **Do not warn** — unknown is the ordinary state of a local machine |
-| `local` | the `file://` URL |
-| `remote` | the `open:` line as printed — the engine already served it. Pass on any `also:` lines too |
-
-**Never read an environment variable to decide this.** Not `SSH_CONNECTION`, not
-`CLAUDE_CODE_*`, not a tty check — the engine already did it, reports the answer
-on that line and in `--json`, and a second implementation here could not be
-tested and would drift from the first. The ranking and the traps
+## 4a. Relay the stack — every tier, never one you picked
+
+`spec-env review` prints one line per tier and `--json` carries the same thing
+as `tiers`. **Relay all of them, in that order**, whatever the `reader:` line
+says:
+
+| Tier | Carries |
+|------|---------|
+| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
+| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
+| `remote` | the published URL and *a verdict here needs `/spec-reviewed`* — or `off` with the command that turns it on |
+
+**The `reader:` line decides nothing here any more.** It is still printed and
+still the only place that question is answered, but the offer no longer branches
+on it — because branching on it is what produced a `file://` page for a session
+detected `unknown`, a LAN URL for a phone off the network, and an address that
+changed underneath a reader mid-session. A tier that is off keeps its line, so a
+reader who has left the house can see the surface exists and ask for it.
+
+**Never read an environment variable to decide anything about the offer.** Not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check — there is nothing left
+for a detection to decide, and a second implementation of one could not be
+tested and would drift. The ranking and the traps
 (`CLAUDE_CODE_ENTRYPOINT` describes the *process*, not the reader; stdin is never
 a tty under Claude Code) live in `review.js` beside the code, which is where they
 belong.
@@ -461,8 +544,9 @@ answer left.
 
 `review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
 operator settle where they are reading, and an explicit value is believed without
-sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
-act on it.
+sniffing. What the engine may *do* is settled by the tier settings instead —
+`review.serve` (`always` · `never`), `review.allowNetwork` and
+`review.allowRemote` — not by the reader.
 
 ## 4b. Wait for the verdict — because asking for one means waiting for it
 
@@ -483,8 +567,8 @@ said the page was **ready** rather than that it was **waiting**.
 **So the question is not "can I watch a file".** It is "am I asking?" — and the
 transport only decides what carries the answer back:
 
-- **A served page** posts to the local store; a file-watch sees it, and the
-  steps below are that watch.
+- **A served page** posts to the local store; the engine's own wait returns when
+  it lands, and the steps below run it.
 - **A `file://` page** has nothing to post to, so the reader pastes the pass and
   their next message carries it. Say you are holding and **end the turn** — that
   is the same wait, carried by the conversation. It is not a lesser one.
@@ -498,9 +582,20 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
 
 1. **Note the moment**, as an ISO timestamp, before you start. That instant is
    the entire scope of what may be claimed without a person naming it.
-2. **Watch** `.spec-env/reviews/<spec>.pending.json` in the primary checkout,
-   and **end the turn**. Not a poll and not a held-open turn: the operator has
-   their terminal back, and the session costs nothing while they read.
+2. **Run the engine's wait in the background, and end the turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <timestamp>
+   ```
+
+   **Never a watcher of your own, and never a timeout.** It lasts as long as the
+   session, because a reader who walks away from a diff is the normal case — and
+   a loop composed here would be proven by nothing, which is how one written as
+   `[ "$x" \> "$y" ]` spun for five minutes in zsh and looked exactly like
+   patience. `/spec-next` §5 carries the full account.
+
+   Not a poll and not a held-open turn: the operator has their terminal back,
+   and the session costs nothing while they read.
 3. **On waking, let the engine choose:**
 
    ```
@@ -711,8 +806,8 @@ consumed rather than stored.
 purpose; someone who forgot they had voted has not, and only the report tells
 them apart.
 
-`Review` carries the files and `+`/`−`, the page's `open:` line, and the
-published URL when there is one. Where the page holds a review pass, it also
+`Review` carries the files and `+`/`−`, and the tier stack — labelled, run
+together with `·` because a row is one cell. Where the page holds a review pass, it also
 carries the three totals — files accepted, comments open, comments answered.
 `--json` reports those under `notes.totals`; read that, never the diff.
 

package/assets/skills/spec-hotfix/SKILL.md

@@ -111,11 +111,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
   description (an **update** to the existing issue, plus a sub-issue per phase).
   Recording a snapshot here would declare the mirror already in sync and strand
   the issue showing the raw report forever.
+- **Preserve the original, before anything replaces it.** Run this the moment
+  the spec file exists and **before the linking push**:
+
+  ```
+  skitterspec spec-sync preserve <spec>
+  ```
+
+  It posts the issue's current description onto the issue as a comment — the one
+  surface one-way sync never touches, so no push can clobber it. On the API path
+  it reads the description itself; without a key it prints the body and the
+  marker, and you post it with the Linear comment tool after checking the
+  comments for that marker.
+
+  **The ordering is the whole correctness condition.** Run before the push, this
+  keeps what the reporter filed. Run after it, it would keep the generated spec
+  and report success — which is why it is a step of its own here rather than a
+  line in the push sequence. The engine warns when it can tell it is late, but it
+  cannot always tell.
+
+  **It never fails the adoption.** A project that set
+  `intake.preserveOriginal: false`, an unreachable Linear, an issue with no
+  description, a comment Linear refused — every one of them exits 0 and says so.
+  Relay what it printed and carry on.
 - **Say what will happen** in the finish-up message. The linking step runs right
   after the spec is written, so the issue's description is replaced by the spec
-  **then** — not on some later manual push. The reporter's words are not lost:
-  they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
-  keeps the original in the issue's history.
+  **then** — not on some later manual push. Say both halves: the description
+  becomes the spec, **and** the original is preserved as a comment on the same
+  issue, so the reporter can still read what they wrote.
+
+  **Do not send anyone to the issue's history for it.** This used to say Linear
+  keeps the original there, and that is true and useless: history is a diff
+  viewer nobody opens, it is not quotable, and it degrades to "it is in there
+  somewhere". The comment is the answer, and the other half is the spec's own
+  **Problem** (or **Symptom**) section quoting the reporter.
 
 ## 1. Establish the base version (the tag)
 
@@ -333,10 +362,14 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
-**Only when all three hold**: `specs/.core/linear.config.json` exists, its
-`sync.fieldOwnership` includes `assignee`, and the spec carries a
+**Only when all three hold**: `specs/.core/linear.config.json` exists, the repo
+**owns** `assignee` in its `sync.fieldOwnership`, and the spec carries a
 `linear_identifier`. Any one missing → skip this step silently and carry on; a
-project that has not opted in must see no trace of assignment.
+project that declined must see no trace of assignment.
+
+Ownership is the **value**, not the key: `assignee` is owned by default, and
+`"none"` is how a project declines it. Testing whether the key is *present* would
+read as opted-in everywhere, since the default puts it in every config.
 
 **Never blocks, never fails the skill.** Everything below is best-effort: the
 branch is provisioned and the spec is moving either way, and an unassigned issue
@@ -517,30 +550,33 @@ this worktree is refused until a verdict is sent or
 `skitterspec spec-env review skip "<reason>"` records the decision to move on.
 The exit is always one command, and one of them is *"I am moving on"*.
 
-Relay the **`open:`** line rather than the bare path: a path is not clickable in
-any terminal, and a page nobody can open is a page nobody reads.
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three — rather than the bare `page:` path: a path is not clickable in any
+terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
+line with it where the engine printed one, and nothing where it did not.
+`.claude/rules/spec-reports.md` carries the shape, including why a rigid
+contract took that line.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always an ask. A
   `file://` link is no use on a phone, and saying so **is** the ask —
   `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
 
 **Serving is the engine's to do; publishing is never.** A `remote` reader
 authorises a local server — one process, ended by one flag, leaving nothing

package/assets/skills/spec-linear-setup/SKILL.md

@@ -178,19 +178,27 @@ a state from the `list_issue_statuses` names you already have:
   automation closes them and a problem otherwise — `spec-sync doctor` warns about
   it either way, so say which it is.
 
-## 7b. Should a spec's issue be assigned to whoever is building it? (optional)
+## 7b. Assignment is on — does this team want it off?
 
-Ask it plainly, in one line: with this on, `/spec-start` records the developer
-and their Linear issue is assigned to them, released again when the spec
-completes. Off, nothing about assignment happens at all.
+Say what it does, in one line: `/spec-start` records the developer and their
+Linear issue is assigned to them, released again when the spec completes. Then
+ask whether to turn it **off**.
 
-**Offer once and take "no" for an answer.** It is off by default deliberately —
-a team whose PM owns assignment in Linear does not want the repo writing that
-field, and the cost of guessing wrong is somebody else's triage being
-overwritten.
+**The question inverted at v16, and the reason is which mistake is recoverable.**
+While it was opt-in, a repo that simply never added the line was
+indistinguishable from one that had decided against it — so the only signal was
+someone noticing weeks later that nobody was on the issue. On by default, a team
+that does not want it says so once, here, and the answer is on the record.
 
-If they want it, pass **`--assign`** in step 8. Then settle who *they* are, so
-`/spec-start` never has to stop and ask:
+**It cannot overwrite a PM's triage either way**, which is what makes the default
+safe rather than merely convenient: a spec that records no assignee sends none,
+and a snapshot with no assignee key means "never pushed" rather than "was null".
+Assignment only ever writes specs *this repo* started.
+
+If they want it off, pass **`--no-assign`** in step 8, and skip the rest of this
+step — there is no identity to settle for a repo that does not assign.
+
+Otherwise settle who *they* are, so `/spec-start` never has to stop and ask:
 
 ```
 skitterspec spec-sync whoami
@@ -210,7 +218,7 @@ setup.
 skitterspec spec-sync init-config \
   --team-id <uuid> [--team-key KEY] [--project-id <uuid>] \
   [--intake-label <name>] [--bug-labels a,b] [--hotfix-labels a,b] \
-  [--state <bucket>=<name> …] [--assign] \
+  [--state <bucket>=<name> …] [--no-assign] \
   --states <statesfile> [--force] [--json]
 ```