@skitterbyte/skitterspec-linear 15.0.0 → 17.0.0

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.
@@ -353,30 +371,51 @@ 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.
+
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
 
-**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.
+**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 and the
 page link, and **no question**:
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) |
+| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
 
 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
@@ -406,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**:
 
    ```
@@ -423,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
@@ -441,11 +504,11 @@ 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, 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 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
@@ -455,38 +518,38 @@ came through. Every harness can end a turn.
 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

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

@@ -120,8 +120,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:
@@ -146,6 +146,67 @@ names it. This is why the commit no longer stages `specs/` wholesale: the one
 file outside the spec's folder that had to be swept up is addressable, so the
 breadth bought nothing and cost another session's work.
 
+## 4b. Hand the refresh back on a page, then wait
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present) **and this review actually changed something.** Either missing → skip
+the whole step in silence.
+
+A refreshed spec is a rewrite of a document someone is about to work from, so it
+gets read before it is committed — the same ending `/spec` now has:
+
+```
+skitterspec spec-env review <spec> --docs --buttons refresh
+```
+
+`--docs` reads the spec's own documents from the tree you are standing in, so it
+wants no worktree and works for a spec in any bucket. These documents are
+**tracked**, so the diff against `HEAD` is a patch rather than a set of new
+files — which is exactly what the reader wants here: what drifted, and what you
+rewrote.
+
+**Render nothing when nothing changed.** `/spec-review` frequently concludes a
+spec is still accurate, and that is a success rather than a gap. A page showing
+an empty diff under a commit button asks for a verdict on nothing, and the
+engine refuses it for the same reason — `nothing to review`. Take that refusal
+as the answer and report the `⏸`/`✅` you already had.
+
+**Arm nothing.** No `review arm` here: the gate asserts that a phase which ended
+owes an answer, and a re-validated spec has ended no phase. Walking away leaves
+an uncommitted spec, which is the state this skill has always finished in.
+
+### The three endings
+
+`--buttons refresh` offers `Commit`, `Request changes` and `Discuss`.
+
+**No start verdict, deliberately.** The spec this skill refreshed may already be
+in progress — that is half of what it is used for — so `Commit & Start` would
+offer to provision a worktree for a spec that already has one.
+
+- **`commit`** — hand off to `review.commitWith` (`/commit` by default) with the
+  pathspec the render reported on `docs.paths`, then finish. The spec keeps
+  whatever status step 4 left it in.
+- **`changes`** — work the notes into the spec, record a resolution for each so
+  the next render strikes it through with what changed, re-render, and wait
+  again.
+- **`discuss`** — report and talk. Claim nothing, change nothing.
+
+### Then wait for it
+
+**The wait is a command. Do not write one.** Note the moment you start waiting
+as an ISO timestamp, run the engine's wait in the background, and end your turn:
+
+```
+skitterspec spec-env review wait <spec> --since <the timestamp>
+```
+
+Pass no timeout. On waking, let the engine pick the pass —
+`skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json`
+— and route on the verdict above.
+
+**Where the page is `file://`** the pass is copied and pasted, so the wait is the
+turn ending and the banner says so. Do not start a watch that cannot fire.
+
 ## 5. Report
 
 Do **not** `git commit` unless the user asks.
@@ -166,6 +227,32 @@ the shape; this section carries only what is specific here.
 API that moved, a task the code already does. `Spec` carries the status the
 review leaves it in, which is the answer to "can I start this?".
 
+**Where step 4b rendered a page the run is waiting**, so the block omits the
+`Review` row and ends on the banner from `.claude/rules/spec-reports.md` — the
+tier stack copied from the engine's own lines, never one link chosen for the
+reader:
+
+---
+
+## ⏸ 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` commits the refresh · `Request changes` works them now
+
+---
+
+`Next` then names the page rather than a command, because the button is what
+carries the work on.
+
+Where nothing was rendered — no isolation, or no drift to show — `Next` is
+`/commit, then /spec-start <name>`, since this skill does not commit and
+`/spec-start` refuses a tree holding anything that is not the spec's.
+
 **Drift found and not fixed is a `Follow-up`, not a silence.** A spec this skill
 declared reviewed is one nobody will re-read; something it noticed and left
 undone has to leave the session in writing or it did not happen.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-reviewed
-description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly, and be asked which only when two are waiting. Use when the user says "/spec-reviewed", "I approved it", "I've reviewed it", "pick up my review", "I pressed approve", or otherwise says they have finished reviewing a rendered diff.
+description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly, or pass the verdict itself ("/spec-reviewed commit") when the page could not send and copied you a command instead. Use when the user says "/spec-reviewed", "I approved it", "I've reviewed it", "pick up my review", "I pressed approve", or otherwise says they have finished reviewing a rendered diff.
 disable-model-invocation: true
 ---
 
@@ -70,16 +70,42 @@ Several provisioned and none resolved is a refusal — relay its list and stop,
 never pick from it. See `.claude/rules/spec-planning.md`; do not restate the
 rule here.
 
-**Three argument shapes, and they cannot collide.** A **six-digit code**
-matches `^\d{6}$`; a **tracker id** carries a letter and a hyphen; a
-**spec name** is neither. So the parse needs no flag, and nothing has to be
-guessed at from context.
+**Four argument shapes, and they cannot collide.** A **six-digit code**
+matches `^\d{6}$`; a **verdict** is one of a closed list of six words;
+a **tracker id** carries a letter and a hyphen;
+a **spec name** is none of them and always carries a lifecycle prefix
+(`feat-`, `bug-`, `hotfix-`), which no verdict does. So the parse needs no flag,
+and nothing has to be guessed at from context.
 
 A **six-digit code** is a pass the operator read off their own page. It says
 **which pass**, not which spec — so resolve the spec exactly as a bare
 invocation does, above, and claim the code *there*. Then go to step 4 — a named
 pass has nothing to disambiguate.
 
+A **verdict word** — `commit`, `commit-continue`, `commit-start`, `continue`,
+`changes`, `discuss` — is the conclusion itself, arriving without a pass behind
+it. It is
+what a **`file://` page** hands over: that page has no server to POST to and no
+store to write to, so it copies a command instead of sending anything, and this
+is the command. Resolve the spec as a bare invocation does, then send the word
+through the engine:
+
+```
+skitterspec spec-env review <spec> --verdict <word>
+```
+
+It joins the same merge a claimed pass goes through, so the routing in step 4
+is unchanged: a commit over open notes is refused exactly as it would be, the
+outcome log records it, and the gate a phase armed is cleared. Then go to step
+4 — there is nothing to disambiguate.
+
+**A word carries a verdict and nothing else**, and that is a property of the
+transport, not a shortcut. Accepts and comments do not fit on a command line,
+so the page only ever offers the words while the reader has marked nothing —
+the moment they tick an accept or write a note it goes back to handing over the
+blob. If someone tells you they marked things up *and* gives you a word, ask
+for the pass: the word would land a verdict with their notes silently dropped.
+
 A **name** targets that spec instead. A **tracker id** does too, but only
 through a **provider seam**: the base knows nothing about tracker ids, so
 resolve one by asking whichever provider is installed for its listing —

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

@@ -233,10 +233,14 @@ branch is already here.
 - Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
 - Set **Developer** if it is still `—` (`git config user.name`).
 
-**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
@@ -371,6 +375,25 @@ here beyond knowing it is no longer dead code.
 A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
 it is well-formed first.
 
+- **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.
+
+
 ## 4b. Note a missing gating decision (only if configured)
 
 **Only when `specs/.core/gating.config.json` exists.** Run

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

@@ -33,9 +33,20 @@ Use the argument, else the spec in context; ask if unclear.
 ## 2. Fetch the Linear issue (optional, for drift)
 
 If the spec has a `linear_identifier`, discover the Linear MCP read tool
-(`get_issue`) and write the issue JSON to a temp file — this lets the report
-compare workflow-state. If Linear isn't connected, skip the drift line (still
-report pending-push).
+(`get_issue`) and write the issue JSON to a temp file. If Linear isn't connected,
+skip the drift lines (still report pending-push).
+
+**Write the whole issue, including its `description`.** The engine reports two
+independent kinds of drift off that one file: the workflow-state someone moved,
+and the **description someone edited**. Write only the state fields and the
+second check has nothing to look at — and it says nothing rather than guessing,
+so the loss is silent. Keep `url` too: it is what the description line points
+the reader at.
+
+**The description itself never enters the conversation.** The engine hashes it
+and compares hashes; what it prints is *that* the text changed, plus where to
+read it. Do not open the temp file, and do not paste the description into your
+report.
 
 Optionally fetch the workspace issue-state names to a file to validate the
 configured `states` at the same time.
@@ -81,9 +92,12 @@ the shape; this section carries only what is specific here.
 **Verdicts**
 
 - `✅` — in sync; nothing would push.
-- `⚠️` — drift: N objects would push, or Linear's workflow state was moved by
-  hand. Neither is an error — the repo wins on the next push — but both are the
-  reason someone ran this.
+- `⚠️` — drift: N objects would push, Linear's workflow state was moved by hand,
+  or the issue's **description** was edited on Linear since the last push. None
+  is an error — the repo wins on the next push — but all are the reason someone
+  ran this. **Say which**, since the three call for different things: a pending
+  push is routine, a moved state is usually someone else's automation, and an
+  edited description means a person wrote something that the next push replaces.
 - `⏸` — no config, or the spec is not linked. Nothing to compare.
 
 **Fields:** `Tracker` · `Follow-ups` · `Next`

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

@@ -42,6 +42,7 @@ In a project that installs the Linear superset the binary is
 | "what specs are there?", "what's in the backlog?", "what is Jane on?" | `list` — or hand to `/spec-list` |
 | "did the mirror survive the push?" | `verify <spec> --stored <file>` |
 | "link this spec to KEY-1 by hand" | `stamp <spec> --issue KEY-1` |
+| "this spec lost its link", "a push made a duplicate issue" | `reattach <spec>` — or `--to KEY-1` to name one |
 | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
 | "is the team key stale?", "did Linear get renamed?" | `retarget` |
 | "what ticket am I on?", writing a commit | `ref` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "15.0.0",
-  "description": "Spec-driven development for Claude Code, with one-way Linear sync \u2014 a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status \u00b7 /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
+  "version": "17.0.0",
+  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",
     "claude-code",