@skitterbyte/skitterspec-linear 14.0.0 → 17.0.0

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
@@ -473,7 +506,7 @@ sub-issue jump from Backlog straight to Done, with nothing visible in between.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
 
-## 6b. Render the page — then offer the review, never write it
+## 6b. Render the page, arm the gate, then wait for the verdict
 
 **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
 present). Without it there is no worktree to read and this step does not exist —
@@ -489,53 +522,61 @@ skitterspec spec-env review <spec>
 **This is free.** The engine reads git and splices the patches into a template;
 the diff never passes through you, so a 266KB patch costs nothing.
 
-**Then offer `/spec-diff`. Do not run it.** The written review is the part that
-costs — roughly **700 output tokens**, because writing it means reading the diff
-— and that spend is the operator's call, not a default.
-
-**The offer is the `Review` row of step 6's block** — the counts, the page link
-and a question, in one row:
-
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
-
-**It ends in a question, addressed to someone.** It was once a fenced block of
-engine output, and it fired on every phase and was never once taken: two quoted
-lines under the test counts, addressed to nobody, with the report then closing
-on *"commit this first"* — the last instruction the reader got was to move on,
-so they did. A row in a labelled table is findable; a question in it is
-answerable. Both halves are load-bearing.
-
-**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
-the page and the question stay in the same row: two adjacent rows about one page
-make the reader resolve a distinction before acting on either. A later edit that
-moves it out of the block, or separates the link from the question, undoes this
-and should be read as a regression rather than tidying.
+**Then arm the gate**, so the fix now owes a verdict:
 
+```
+skitterspec spec-env review arm <spec>
+```
 
-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.
+**Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
+than reading a second copy here: note the moment you start waiting, watch the
+pending store, end your turn, and let `--claim-since` pick the one pass that
+arrived inside the window. The banner it describes is what this skill emits in
+place of a `Review` row, and the routing on the verdict is `/spec-diff` §2 and
+§4, as it is everywhere.
+
+**Why this skill arms as well as waits.** Waiting is what any offer does;
+**arming** asserts an obligation that outlives the turn, and belongs only to
+work that is finished. A hotfix is a completed unit — red→green against a
+released tag — so it qualifies, and a wait with nothing owed behind it is a
+suggestion rather than a gate.
+
+**A hotfix is the case where reading it matters most.** This change is about to
+be tagged and shipped to production from a release line, not merged into a
+branch someone else will read first. The verdict is the only review it gets.
+
+**It is user-visible, and that is deliberate.** Once armed, a `git commit` in
+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 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
@@ -578,10 +619,16 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
 `Review` · `Follow-ups` · `Next`
 
+**`Review` is emitted only where step 6b did not run** — a project with no
+isolation, or a render that failed. Where the run is waiting, the banner carries
+the whole subject and the row is dropped, per `.claude/rules/spec-reports.md`.
+
 **The base tag goes in the verdict clause** — `✅ /spec-hotfix · hotfix-foo ·
 green on v2.3.1`. Which released version this was fixed against is the first
 thing anyone needs, and it is not a field: the clause is where the run says
 where it got to.
 
-Step 6b's offer is the `Review` row, not a paragraph after the block — the
-counts, the link and the question in one row. Nothing follows the block.
+Step 6b ends in the **banner**, not a paragraph and not a row — the run is
+waiting on a verdict, and the banner is the shape that says so. Nothing follows
+it. Where the run is not waiting it asks nothing at all: a `Review` row carries
+the counts and the link, and no question (*asking implies waiting*).

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

@@ -105,12 +105,24 @@ Ensure it exists. If missing, create it documenting:
 Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.
 
-## 4a. The review-gate hook (`.claude/hooks/review-gate.js`)
-
-`skitterspec init` installs the hook script and registers it in the project's
-**committed** `.claude/settings.json` as a `PreToolUse` hook on `Bash`. It runs
-one engine call per Bash tool call and refuses a `git commit` in a worktree
-whose phase is still awaiting a verdict.
+## 4a. The review-gate hook (`.claude/hooks/review-gate.cjs`)
+
+`skitterspec init` **and `skitterspec update`** install the hook script and
+register it in the project's **committed** `.claude/settings.json` as a
+`PreToolUse` hook on `Bash`. It runs one engine call per Bash tool call and
+refuses a `git commit` in a worktree whose phase is still awaiting a verdict.
+
+**Both commands, and that is not a detail.** Copying the script and registering
+it are one operation, and they were once split across two code paths — so
+`update` landed the file, reported `created:`, and wired nothing, on every
+project that upgraded. Landing the script is not installing the hook.
+
+**`.cjs`, and the extension is load-bearing.** The script lands inside the
+target project, where *that* project's `package.json` decides how node parses a
+`.js` — so CommonJS shipped as `.js` crashes in any `"type": "module"` project,
+on every Bash tool call. `.cjs` settles it at the file. A registration left over
+from the release that named `.js` is rewritten in place, keeping any wrapping
+the operator added, rather than gaining a second entry beside it.
 
 **Committed, not machine-local**, and the difference is the point: the trusted
 worktree root is one machine's absolute path, while *a phase that ended owes an

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]
 ```
 

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

@@ -154,6 +154,24 @@ Before writing any code for this phase, get the workspace clean:
   being *"I am moving on"*, which is what keeps this a push rather than a wall —
   a gate with no exit gets switched off wholesale instead of answered.
 
+- **Report anything left waiting, and claim none of it.** Ask the engine once:
+
+  ```
+  skitterspec spec-env review waiting
+  ```
+
+  A pass listed here arrived when nothing was watching — a wait that never ran,
+  a session cleared, a terminal closed overnight — and no watcher can recover
+  those, however good. Relay what it prints: the spec, the code, the verdict and
+  the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
+  disown it.
+
+  **It is information, not a gate.** It never refuses, nothing here is
+  conditional on it, and **you never claim one** — `/spec-diff` §0 stands
+  unchanged, and a pass sitting there when you arrived was not sent to you.
+  Silent when nothing is waiting, which is the usual case: say nothing rather
+  than reporting that there was nothing to report.
+
 ## 3. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,
@@ -184,8 +202,8 @@ once it is over. Without a provider this is a no-op and nothing below changes.
     them. Skip it and a started spec stays mirrored as a phase-less issue.
 - **Never mint the spec issue.** An unlinked spec is skipped, not created —
   `/spec-push` is how someone opts in.
-- **Backfill a missing assignee silently; never ask.** Only when
-  `sync.fieldOwnership` includes `assignee`. If the spec records nobody and
+- **Backfill a missing assignee silently; never ask.** Only when the repo owns
+  `assignee` (it does by default; `"none"` declines it). If the spec records nobody and
   `skitterspec spec-sync whoami --json` answers, stamp it with
   `skitterspec spec-sync assign <spec> --to <id> --name "<name>"` and let the
   push above carry it. If identity is unknown, skip it in silence.
@@ -323,6 +341,12 @@ skitterspec spec-env review <spec>
 the diff never passes through you, so a 266KB patch costs nothing. Report the
 path it prints and move on.
 
+**This render takes the committing button set**, which is the default — so
+`--buttons` is not passed. That is a statement about the work, not about the
+gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
+verbs for it. A render part-way through a run takes `--buttons midrun` and
+offers `Continue` instead; `/spec-diff` owns that case.
+
 **Then arm the gate**, so the phase now owes a verdict:
 
 ```
@@ -347,41 +371,72 @@ so one subject lives in one place:
 
 ## ⏸ Review ready — <N> files, +<a> −<d>
 
-**[Open the page](<the `open:` URL>)** · I'm holding here until you send a verdict.
+- **local** — <the `local:` URL>
+- **network** — <the `network:` URL, or off with the command that turns it on>
+- **remote** — <the `remote:` URL, or off with the command that turns it on>
 
-`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+<the `live:` line, exactly as the engine printed it — omitted when it printed none>
 
-**One link, and the engine has already chosen it.** Where it served, the
-banner carries the served URL and the wait is real. Where it could not serve —
-a busy port, a machine with no network address — that is the case publishing
-exists for, and then the banner carries the published URL with what is true of
-it: *press a verdict, then type `/spec-reviewed`*, because nothing pushes from
-the artifact store into this conversation.
+I'm holding here until you send a verdict — the wait covers local and network.
 
-**Never offer both.** Publishing while the server is reachable adds a second
-door the reader cannot tell apart from the first, and the wait only stands
-behind one of them — that was done, and three verdicts were pressed on the
-published page while each sat unread under a line saying I was holding. The
-published page is for the reader the server cannot reach, and for nobody
-else.
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+
+**The stack is the engine's — copy it, do not compose it.** `spec-env review`
+printed one line per tier, in that order, and `--json` carries the same thing as
+`tiers`. Relay all three whatever they say, including the ones that are off with
+the command that turns them on: a reader who has left the house cannot ask for a
+remote page they were never shown.
+
+**Do not pick one for them.** The engine used to, and the guess failed three
+separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
+why the *one link, never two* rule now reads
+**one link per reachable store, each labelled** —
+local and network are two doors into one room, so the wait
+covers both. `remote` is a second store, so its own line carries its own caveat:
+*a verdict here needs `/spec-reviewed`*, because nothing pushes from
+the artifact store into this conversation. Never let the holding line promise a
+wait over that tier.
+
+**Publishing is still never yours to do.** `remote` reading `off` is the normal
+state, and the fix for it is the command on that line — typed by the operator,
+or pressed on the page, because a published page is one this tooling cannot
+remove and permitting it is not publishing it.
+
+**The `live:` line goes with the stack**, and it is the engine's line too —
+copied as printed, and **absent when the engine printed none**. The page can act
+on it: a press puts the spec live or takes it down and hands the reader back the
+same page, which is `/spec-diff` §2b's routing and not this skill's. What
+matters here is that an action **never clears the gate this phase armed** — the
+reader has looked at it running and concluded nothing, so the phase still owes a
+verdict.
 
 ---
 
-**Where you are not waiting, it stays the `Review` row** — the counts, the page
-link and a question, in one row:
+**Where you are not waiting, it stays the `Review` row** — the counts and the
+page link, and **no question**:
+
+| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+At the end of a phase you are always waiting, so this shape belongs to the
+renders that are not this step: a mid-phase `/spec-diff`, a page produced
+alongside other work. A row cannot be waited on, so a question in one is
+unanswerable however findable it is.
 
 **Both shapes are addressed to someone, and that is the constraint.** The offer
 was once a fenced block of engine output: two quoted lines under the test
 counts, addressed to nobody, with the report then closing on *"commit this
 first"* — the last instruction the reader got was to move on, so they did. A row
-in a labelled table is findable; a question in it is answerable; a banner says
-the work has stopped. What must never come back is something unaddressed,
-unfindable, or fenced.
+in a labelled table is findable; a banner says the work has stopped. What must
+never come back is something unaddressed, unfindable, or fenced.
+
+**The row asks nothing, and that is not a weakening of the above.** A row cannot
+be waited on, so a question in one is unanswerable however findable it is —
+which is the failure `spec-reports.md` records under *asking implies waiting*.
+The row names the page; the banner is what asks, because the banner is the shape
+the run is standing behind.
 
 **Never bury it and never split it.** The row sits above the last two rows of
-the block, and the page and the question stay in the same row; the banner
+the block, and the page and its counts stay in the same row; the banner
 replaces the row rather than joining it. Two places naming one page make the reader
 resolve a distinction before acting on either — which is the same failure
 whether the two places are adjacent rows or a row and a banner.
@@ -390,16 +445,25 @@ whether the two places are adjacent rows or a row and a banner.
 
 The row is findable, but a row cannot make the continuation follow from the
 reading — and that is the gap the whole gate exists to close.
-**Where this harness can watch a file and wake the session on a change, use it.** The pass
-arrives at the engine's holding area, the watch fires, and the verdict the
-reader pressed is what carries the work on.
+
+**The wait is a command. Do not write one.**
 
 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
    the whole scope of what you may claim.
-2. **Watch the pending store** for the spec —
-   `.spec-env/reviews/<spec>.pending.json` in the primary checkout — and
-   **end your turn**. Do not poll, and do not hold the turn open: the point is that
-   the reader has the terminal back while they read.
+2. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <the timestamp>
+   ```
+
+   It returns when a pass arrives inside that window, and
+   **it takes no timeout unless you pass one** —
+   the wait lasts as long as your session, because a reader who walks away from
+   a diff is the normal case rather than the edge one. Do not give it a duration
+   of your own.
+
+   Then **end your turn**. Do not poll it and do not hold the turn open: the
+   point is that the reader has the terminal back while they read.
 3. **On waking, let the engine pick**:
 
    ```
@@ -407,11 +471,26 @@ reader pressed is what carries the work on.
    ```
 
    It claims the one pass that arrived inside the window, and acts on nothing
-   at all when none did (the watch can fire on a write that was not a pass) or
-   when two did (two sittings, or two people — the operator has the codes).
+   at all when none did (the wait can be woken by something that was not a
+   pass) or when two did (two sittings, or two people — the operator has the
+   codes).
 4. **Route on the verdict** exactly as `/spec-diff` §2 and §4 describe. Do not
    restate that routing here.
 
+**WHY A COMMAND RATHER THAN A LOOP YOU COMPOSE.** This step used to say "watch
+the pending store" and stop, so every run invented its own watcher in shell —
+and three failed in two days, each reaching the operator as *"I pressed the
+button and nothing happened"*. The worst wrote
+`until [ -f "$P" ] && [ "$x" \> "$y" ]`: valid bash, a syntax error in zsh, a
+predicate that could never be true. It spun for five minutes writing to a
+stderr nobody reads.
+
+**The bug is not the lesson — the silence is.** A watcher that can never fire
+and one patiently working are indistinguishable from outside, so nothing about
+that run looked wrong until the operator asked. `review wait` says it has
+started, is written once, and is tested against a store that gains a pass
+mid-flight. A predicate composed fresh each time is proven by nothing.
+
 **WHY THIS IS SAFE, AND WHAT IT COSTS.** It was once true that a device
 reaching your page could not reach your conversation, and that fact was the
 whole guard: a pass sat in the holding area until a person typed
@@ -425,46 +504,52 @@ is that the page can now act, so the token has become a credential rather than
 a convenience — and `--claim-since` refusing to choose between two passes is
 what stops a race becoming a wrong commit.
 
-**Where the harness cannot watch a file, change nothing.** The `Review` row and
-`/spec-reviewed` are the whole story, exactly as before. The gate still holds
-either way: it is the engine's, not the watch's.
+**Where the harness cannot run something in the background, you still wait** —
+the turn ending is the wait. Say the page is rendered and that you are holding
+for the pass, then end your turn; the reader's next message is what carries it,
+and `/spec-diff` picks it up from the paste exactly as it always has. The gate
+holds either way: it is the engine's, not the wait's.
+
+This once read *"change nothing"* — keep the row, keep the question, do not
+wait — and that exemption is the hatch a whole class of unanswerable questions
+came through. Every harness can end a turn.
 
 **It still does not break a chained run.** `/commit && /spec-next` is typed as
 one line; by the time this step is reached the chain has finished, so waiting
 here stops nothing that was still going to happen.
 
-Relay the **`open:`** line the engine prints, not 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 —
+never the bare `page:` path: a path is not clickable in any terminal, and a page
+nobody can open is a page nobody reads.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always something
   someone asks for. A `file://` link is no use on a phone, and saying so **is**
   the ask — publishing is the answer to it, and `/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.
-
-**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
-behind — and authorises nothing else. A reader the server CAN reach is not a
-reason to publish as well: the page they can already open is the page to name. Publishing leaves a page this tooling
-cannot remove, so it stays an ask in every case, always. If the engine could not
-serve (a busy port, a machine with no network address) it falls back to the
-`file://` URL with its marker, and that is when publishing is worth naming.
+**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.** The server is one
+process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
+decides whether it binds wide — no detection involved. A reader the server CAN
+reach is not a reason to publish as well: the tiers they can already open are on
+the stack. Publishing leaves a page this tooling cannot remove, so it stays an
+ask in every case, always — which is why `remote` shows the command rather than
+a URL until someone types it.
 
 - **Never fatal.** A failed render — no worktree, a git error — is one line and
   the phase is still done. The page is a convenience; the repo is the record.

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

@@ -155,6 +155,24 @@ the chosen project through as `--project <id>`.
 
 ## 4a. Apply it yourself — the MCP path (order matters)
 
+**First, check whether you are about to overwrite someone.** On the API path
+`apply` does this for itself, off the read-back it already makes. On the MCP
+path nothing has read the issue yet, so ask before you write:
+
+```
+skitterspec spec-sync status <spec> --remote <issuefile>
+```
+
+using the same issue JSON step 2 fetched — it must carry the `description`. A
+`drift: … description was edited on Linear since the last push` line means a
+person wrote something there that step 1 below replaces.
+
+**It is a warning and never a gate.** The repo is the source of truth and the
+push still goes ahead; relay the line, name the issue, and carry on. What is
+forbidden is doing it *silently* — someone's paragraph disappearing with nothing
+said about it is the failure this exists to end. Nothing printed means nothing to
+say, which includes every case the engine could not tell.
+
 1. **Spec issue** → if the overview has no `linear_identifier`, this push
    **mints** it: run the picker in **Picking the Linear Project** below, then
    create it with `save_issue` (`team` = `linear.teamId`; `project` = the picked
@@ -233,6 +251,33 @@ This writes the last-pushed snapshot from the now-stamped files, so the next
 `/spec-push` produces an empty plan. Commit the stamped spec + snapshot into the
 branch so the mirror-link rides in the PR.
 
+## 5b. A refused mint, and the way back
+
+Two refusals reach you from `apply`, and neither is a failure to retry.
+
+**`N already exists and no spec claims it`** — the push was about to mint, and
+an issue with **exactly** this title is sitting there unheld. That is almost
+always the spec's own issue, whose link was lost: a bad merge, a hand edit, a
+stray `sed` over the frontmatter. Adopt it rather than creating a twin:
+
+```
+skitterspec spec-sync reattach <spec> --to <ISSUE-REF>
+```
+
+Bare, `reattach` searches by title itself and stamps the one unclaimed match;
+it refuses when several match and names them, because choosing between two is
+a guess. `--force-new` is the escape when the duplicate title is genuine.
+
+**`N exists in Linear but could not be recorded`** — the create landed and the
+stamp did not, so Linear holds an issue the repo does not point at.
+**Do not re-run**:
+the plan still reads the spec as unlinked, so a re-run mints a second.
+`reattach --to <the named id>` is the fix.
+
+Everything else — a rate limit, a refusal that says waiting will not help — is
+reported with Linear's own explanation and whether retrying can help. Relay it;
+do not paraphrase.
+
 ## 6. Report
 
 End with the block defined in `.claude/rules/spec-reports.md`. That file carries