@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

package/assets/rules/spec-planning.md

@@ -1,7 +1,7 @@
 # Spec Planning
 
 Spec-driven development is driven by ten lifecycle skills (plus the
-`/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
+`/spec-connect`, `/spec-live` and `/spec-remote-review` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
 
@@ -20,13 +20,24 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
 **Skills vs commands.** The table above lists **skills** — Claude reads them and
-exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
+exercises judgment. `/spec-connect`, `/spec-live` and `/spec-remote-review` are
+instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
 finding one. They are marked `disable-model-invocation`, meaning
 **only you can run them** — a skill that wants one will tell you to type it
 rather than invoking it.
 
+**`/spec-remote-review`** is the newest and the smallest: it 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 a person can
+act on, and `skitterspec spec-env review allow remote` is not what anyone
+reconstructs from a page they are reading on a phone. Making the line
+*clickable* was considered and rejected — the only clickable thing markdown has
+is a URL, and a URL that acts when it is **fetched** is one a link previewer or
+a prefetcher fires with nobody involved. It **permits** publishing; it publishes
+nothing.
+
 `/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
 convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
 review pass is never claimed unasked. Because the model cannot invoke this
@@ -301,7 +312,7 @@ its verdicts and its fields.
 | **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:///…) |
+| **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) |
 
@@ -333,6 +344,27 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
 workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
 the tracker is never read back or merged.
 
+**One-way means the repo wins, and it now wins *loudly*.** Those are different
+claims and only the first was ever in doubt. A ticket's description is generated
+from the spec, so a person editing it there is writing something the next push
+replaces — which is correct, and which used to happen in silence. The engine now
+compares a hash of what the tracker holds against a hash of what the repo last
+sent, and says *that* it changed and where to read it.
+It **reports and never refuses**: only a person can tell a typo fix from a
+paragraph worth keeping.
+
+**This is still not a pull.** Nothing read is merged, written to a spec, or fed
+into the projection, and the text never enters the conversation — the comparison
+is hashes, and the output is one line for a human. It is the same thing
+`compareStored` has always done for a different question.
+
+**And adoption no longer costs the reporter their words.** When a provider
+adopts an existing ticket — one a PM or colleague filed — the linking push
+replaces its description with the spec. Before that happens the original is
+posted back onto the ticket as a **comment**: a surface one-way sync never
+touches, so no later push can clobber it. Where a provider supports it, this is
+automatic and has an opt-out. See the provider's own docs.
+
 A provider may also ship a **read-only listing** of what the tracker holds. That
 is not a pull: nothing is merged back and no spec file is written. It exists
 because the folder buckets are only the truth *on the branch you are standing

package/assets/rules/spec-reports.md

@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
 | **Branch** | `spec/feat-foo` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **Tests** | 128 passed · npm test |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) |
+| **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) |
 
@@ -87,23 +87,95 @@ the options may be offered after the table.
 
 ## ⏸ Review ready — 7 files, +212 −18
 
-**[Open the page](http://…)** · I'm holding here until you send a verdict.
+- **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
+- **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
+- **remote** — off · `/spec-remote-review` turns it on
+
+live: off — /spec-live to put it live
+
+I'm holding here until you send a verdict — the wait covers local and network.
 
 `/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
 
 ---
 
-A rule, a heading naming the state and the size, the link in bold, one line
-saying the run is stopped, and the two exits. Nothing else, and never a
-paragraph explaining it.
+A rule, a heading naming the state and the size, **the stack**, the `live:`
+line, one line saying the run is stopped and which tiers it covers, and the two
+exits. Nothing else, and never a paragraph explaining it.
+
+**The `live:` line, and why a rigid contract took a second amendment.** Reading
+a diff is not the only way to judge a change — often the question is whether it
+*works* — and the answer to that lives at the running URL. A reader deciding
+whether to open the page at all wants to know whether it is already running
+somewhere, and finding that out any other way is a trip to a terminal in the
+middle of a review.
+
+**Each line names a command a person types**, rather than describing a
+capability. `live: off — the page can put it live` told the reader that a page
+somewhere could do it and left them to find the verb — and the verb is what they
+need when they are in a terminal rather than on the page. So the lines say
+`/spec-live`, `/spec-live main`, `/spec-remote-review`. Making them *clickable*
+was considered and rejected: the only clickable thing markdown has is a URL, and
+a URL that acts when it is **fetched** is one a link previewer or a prefetcher
+fires with nobody involved.
+
+It is the engine's line, copied like the stack: `spec-env review` prints it and
+`--json` carries the same answer as `live`, from one function, so the report and
+the command cannot disagree. Four states, and only three of them are a line —
+`on` (with the URL when the project configured one), `off`, `held` (naming the
+spec holding the workbench). The fourth, `unavailable`,
+**prints nothing at all**:
+a project with no isolation and a spec with no worktree both land there,
+and a line about a surface that does not exist is an accusation against a
+healthy repo.
+
+**This is the second amendment to this section in two specs**, which is worth
+naming rather than letting pass. The contract earns its rigidity from real
+failures, and two amendments in a row is how a rigid contract quietly becomes a
+negotiable one. Both have carried their reason and both replaced a line rather
+than adding a paragraph.
+**A third should have to argue harder than either did.**
+
+**The stack is the engine's, copied rather than composed.** `spec-env review`
+prints one line per tier and `--json` carries the same thing as `tiers`, so take
+it from there in the order it comes — and do not decide which tiers are worth
+mentioning. The whole reason the stack exists is that the engine was being asked
+to guess where the reader was sitting, and it guessed wrong three separate ways
+in one day; a skill re-deciding that in prose is the same guess one layer up.
+
+**Three tiers, always all three, in this order.**
+
+| Tier | Is | Off when |
+|------|----|----------|
+| `local` | the loopback URL — the machine the run is on | never. With nothing served it is the `file://` page, and says it cannot send a verdict |
+| `network` | the LAN URL — a phone on the same wifi | `review.allowNetwork` is false, or this machine has no network address |
+| `remote` | a published page, for a reader off the network | `review.allowRemote` is false, or nothing has been published |
+
+A tier that is off **keeps its line** and names the one command that turns it
+on. Dropping the line is what left a reader who had walked out of the house with
+nothing on screen to tell them a remote page was even possible — they could not
+ask for what they could not see.
 
 **Only promise a wait the transport can deliver.** The wait itself is real in
 every case; what varies is what carries it back, not whether the run is
 stopped. Three transports, three true sentences:
 
-- **A page the engine SERVES** hands its pass to the local store, which a
-  file-watch sees. The run is woken by the press:
+- **A page the engine SERVES** hands its pass to the local store, and
+  `spec-env review wait` returns when it lands. The run is woken by the press:
   *"I'm holding here until you send a verdict."*
+
+  **That sentence is only true for as long as the wait is actually running**, so
+  the wait is the engine's and never one composed for the occasion. A watcher
+  written per run is proven by nothing: one was written
+  `until [ -f "$P" ] && [ "$x" \> "$y" ]` — valid bash, a syntax error in zsh,
+  a predicate that could never be true — and it spun for five minutes while the
+  report underneath it said the run was holding.
+  **Silence is what made that expensive**:
+  a wait that cannot fire and one patiently working look identical,
+  so nothing seemed wrong until the reader asked. Give the wait no timeout
+  either; it lasts as long as the session, because a reader who walks away from
+  a diff is the normal case and a bounded watch once lost a verdict to a lunch
+  break.
 - **A `file://` page** has no server to POST to, so the pass is copied and
   pasted — the reader's next message is what carries it. The run is stopped just
   the same, and says so:
@@ -112,10 +184,16 @@ stopped. Three transports, three true sentences:
   not a lesser one, and it is not an excuse to ask without waiting.
 - **A PUBLISHED page** writes to the artifact's own store, and nothing pushes
   from there into the conversation. That is the one case where a verdict is
-  genuinely invisible until someone asks for it, so the banner says that instead
-  of claiming a watch:
+  genuinely invisible until someone asks for it, so its line in the stack says
+  that rather than letting the holding line speak for it:
 
-**[Open the page](https://…)** · press a verdict, then type `/spec-reviewed` — I cannot see it until you do.
+- **remote** — [https://…](https://…) · a verdict here needs `/spec-reviewed`
+
+  Where `remote` is the only tier a reader can reach, the holding line says so
+  too: *press a verdict, then type `/spec-reviewed` — I cannot see it until you
+  do.* Where a served tier is reachable as well, the holding line keeps naming
+  the tiers the wait covers, and `remote`'s own caveat sits on `remote`'s line
+  where it belongs.
 
 **A harness with no file-watch does not get an exemption.** It once read
 "change nothing" — keep the row, keep the question, do not wait — and that
@@ -126,12 +204,18 @@ every harness can do.
 **The `Continue` ending, and why the banner's exits differ mid-run.** A page
 rendered part-way through a run offers `Continue` — *I have read it, carry on* —
 in place of the committing verdicts, because "commit" is the wrong verb for
-unfinished work. Its banner names the same state and different exits:
+unfinished work. Its banner names the same state and the same stack, and
+different exits:
+
+…the stack, unchanged…
 
-**[Open the page](http://…)** · I'm holding here until you send a verdict.
+I'm holding here until you send a verdict — the wait covers local and network.
 
 `Continue` carries on · `Request changes` works them now
 
+The stack is written out once, above, and referred to everywhere else. Two
+copies of it is how the two come to disagree about which tiers exist.
+
 **It is not the `none` verdict that was removed.** `none` recorded itself and
 did nothing, which is the record-and-do-nothing ending this contract exists
 against. `Continue` **resumes the run** — it names an action, which is the bar
@@ -145,13 +229,40 @@ block. *Waiting* is what any offer does, and it is what this section governs.
 that is finished. A mid-run render waits without arming — walking away from it
 costs nothing, which is exactly why `Continue` is safe to offer there.
 
-**Exactly one link, never two.** The banner offers the page the reader can
-actually use, and the engine has already decided which that is — a served URL
-when it could serve, a published one only when it could not. Handing over both
-asks the reader to know which door the run is standing behind, and they cannot:
-it was done, and a verdict was pressed on the published page three times while
-each one sat unread under a line claiming the run was waiting. Two links is not
-a convenience with a caveat; it is the caveat existing at all.
+**One link per reachable store, each labelled.** This amends
+*"exactly one link, never two"*, and the evidence that rule was written on is
+the reason it still reads the way it does. Two links were handed over, the wait
+stood behind only one of them, and a verdict was pressed on the published page
+three times while each one sat unread under a line claiming the run was waiting.
+Two links was not a convenience with a caveat; the caveat existing was the bug.
+
+**What that evidence is about is the store, not the count.** A served page hands
+its pass to the local pending store, which `spec-env review wait` watches; a
+published page writes to the artifact's own store, which nothing here can see.
+Two links into two stores asks the reader to know which door the run is standing
+behind, and they cannot.
+
+**Local and network are two doors into one room.** The page POSTs with
+`fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
+opened at `192.168.0.136:7760/…` reach the same server process and the same
+pending store. One wait covers both, and a verdict pressed on either wakes the
+same run. Between those two the objection does not apply — which is why both are
+offered, and why offering them gives nothing up.
+
+**So two things are required, and the second is what the old rule lacked.**
+Every link is **labelled** with its tier, and one line says
+**which tiers the wait covers**.
+Two *unlabelled* links stay forbidden exactly as before, because
+the reader still cannot tell them apart.
+
+**`remote` keeps the caveat it always had.** It is listed so a reader off the
+network knows the surface exists and what turns it on — never as a door the wait
+is claimed to cover. Where it is on and published, its line says what is true of
+it: *a verdict here needs `/spec-reviewed`*.
+
+**Still forbidden**, in the words of the rule this amends: offering two links
+into **different** stores without saying which one the wait is watching. That is
+the failure that cost three unread verdicts, and nothing here touches it.
 
 **This is not the old failure returning**, and the difference is the whole
 justification. The offer used to be two quoted lines in the tail of a long
@@ -247,7 +358,7 @@ behind it — say nothing rather than reporting that there was nothing to report
 | `Landed` | A fast-forward, a tag, a cherry-pick. |
 | `Worktree` | A worktree provisioned, entered, or torn down. |
 | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
-| `Review` | The rendered diff page: files, `+`/`−`, the link. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
+| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
 | `Follow-ups` | **Always.** `none`, or one line each. |
 | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
 

package/assets/skills/spec/SKILL.md

@@ -105,11 +105,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.
 
 ## Phase A — reach a clear shared understanding (grill first)
 
@@ -339,6 +368,104 @@ open questions, `Draft` when you deliberately left some unresolved. Either way
 the next step is `/spec-start`. The Report section below is where all of that
 reaches the user — do not narrate it here as well.
 
+## Phase C2 — render the spec, then wait for the verdict
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no page and this phase does not exist — skip it in
+silence rather than explaining an absence.
+
+A spec is the one artefact whose whole purpose is to be
+**read before work begins**, and until now it was the only one with no reading
+surface: `/spec`
+finished, the spec sat uncommitted, and `/spec-start` had to point that out and
+commit it as a side effect of provisioning. So this phase ends where every other
+phase of the lifecycle ends — on a page, in a verdict.
+
+```
+skitterspec spec-env review <spec> --docs --buttons authoring
+```
+
+`--docs` reads the spec's own documents from the tree you are standing in, so it
+never wants a worktree — a backlog spec has none. It renders
+**this spec's documents and nobody else's**: several specs are routinely
+authored in one
+checkout, and the file set comes from `spec-env stage`'s `owned` half precisely
+so a colleague's spec cannot land on your page and then be committed under your
+verdict.
+
+**This is free.** The engine reads git and splices text into a template; the
+diff never passes through you.
+
+**Render nothing when nothing was written.** A `⏸` run — grilling that never
+reached a shared understanding — has no spec to show, and must not ask for a
+verdict on one.
+
+**Arm nothing.** There is no `spec-env review arm` in this path, and that is a
+decision rather than an omission: the gate asserts that *a phase which ended*
+owes an answer, and a backlog spec owes no phase. Walking away from this page
+costs nothing — the spec is simply still uncommitted, which `/spec-start` already
+handles. A `/spec` run must leave `spec-env review gate --check` exiting 0.
+
+### The two endings this page offers
+
+`--buttons authoring` offers `Commit & Start` and `Commit` in place of the
+committing pair, because "commit and build the next phase" is meaningless for a
+spec with no phase in flight.
+
+- **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
+  passing the pathspec the render reported on `docs.paths`, then run
+  **`/spec-start <name>`** and **stop there**. It never completes, lands or tears
+  anything down, exactly as `commit-continue` stops after `/spec-next`. This is
+  the `commit && /spec-start` that was typed by hand.
+- **`commit`** — the same commit, then finish. The spec stays `Ready` in
+  `backlog`, ready for a `/spec-start` whenever it is wanted.
+- **`changes`** — work the notes into the spec, record a resolution for each one
+  so the next render shows it struck through with what changed, then
+  **re-render, and wait again**. The reader is still holding a decision, so
+  ending the turn and
+  making them type `/spec-diff` would reopen the loop this exists to close.
+- **`discuss`** — report and talk. Claim nothing, change nothing.
+
+**Take the pathspec from the render, not from the tree.** A checkout is shared,
+so the set of this spec's uncommitted documents can differ between the render and
+the verdict — and the reader's conclusion is about what the page showed them.
+
+### Then wait for it
+
+**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. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <the timestamp>
+   ```
+
+   It takes no timeout unless you pass one, and you must not pass one: a reader
+   who walks away from a spec is the normal case, and a bounded watch once lost a
+   verdict to a lunch break.
+3. **On waking, let the engine pick:**
+
+   ```
+   skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
+   ```
+
+   It claims the one pass that arrived inside the window, acts on nothing when
+   none did, and refuses to choose when two did.
+4. **Route on the verdict** as above.
+
+**Where the page is `file://`** — the engine could not serve — there is no server
+to POST to, so the pass is copied and pasted and the reader's next message is
+what carries it. **Do not start a watch that cannot fire**: a wait on the pending
+store would spin forever while the report underneath it claimed to be holding,
+which is the exact failure `.claude/rules/spec-reports.md` records. The wait is
+the turn ending, and the banner says so.
+
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three, in that order — never the bare `page:` path. `.claude/rules/spec-reports.md`
+carries the shape and why every tier is named rather than one being chosen.
+
 ## Phase D — record the isolation stack (only if configured)
 
 **Only when `specs/.core/env.config.json` exists** (per-spec isolation is
@@ -468,9 +595,39 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
 
 `Built` is the spec's path and phase count; `Spec` is its status and bucket;
-`Next` is `/spec-start <name>`, with the name spelled the way it must be typed.
 `Tracker` appears only when a provider is installed and linked it.
 
+**`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
+waiting on a verdict, so the block **omits the `Review` row** and ends on the
+banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
+this page's two exits:
+
+---
+
+## ⏸ Review ready — &lt;N&gt; files, +&lt;a&gt; −&lt;d&gt;
+
+- **local** — &lt;the `local:` URL&gt;
+- **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
+- **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
+
+I'm holding here until you send a verdict — the wait covers local and network.
+
+`Commit & Start` puts it in flight · `Commit` keeps it for later
+
+---
+
+There `Next` names the page rather than a command, because the button is what
+carries the work on.
+
+Where no page was rendered — isolation is not configured, or nothing was
+written — `Next` is `/spec-start <name>`, with the name spelled the way it must
+be typed.
+
+**A spec written without a page is still uncommitted**, so that `Next` relies on
+`/spec-start` committing the spec when it is all that is uncommitted. Say
+`/commit, then /spec-start <name>` when anything else is uncommitted too, or the
+row sends the reader to a refusal.
+
 **`Follow-ups` is almost always `none` here.** This skill's whole job is to
 capture work, so anything it surfaced belongs in the spec it just wrote rather
 than in a follow-up line beneath it.

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

@@ -104,11 +104,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. Reproduce & isolate (light investigation)
 
@@ -309,10 +338,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
@@ -474,11 +507,13 @@ skitterspec spec-env review arm <spec>
 ```
 
 **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.
+than reading a second copy here: note the moment, run
+`skitterspec spec-env review wait <spec> --since <that moment>` in the
+background, end your turn, and let `--claim-since` pick the one pass that
+arrived inside the window. **Do not compose a watcher**, and do not give the
+wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
+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
@@ -499,30 +534,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-cancel/SKILL.md

@@ -76,8 +76,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: