@skitterbyte/skitterspec-linear 12.0.0 → 13.0.0

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

@@ -1,10 +1,15 @@
 ---
 name: spec-next
-description: Build the next unfinished phase of the spec in flight for this session — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one, and never builds a spec it is not standing in. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
+description: Build the next unfinished phase of the spec in flight for this session — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one, and builds wherever that spec resolves rather than wherever the session happens to stand. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
 ---
 
 # /spec-next — build the next phase of the spec in flight
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 It assumes the workbench is already set up: a spec is **in flight** on this
 checkout, and this skill implements its next unfinished phase. Putting a spec in
 flight — provisioning, moving it to `in-progress`, getting its branch here — is
@@ -13,7 +18,36 @@ flight — provisioning, moving it to `in-progress`, getting its branch here —
 
 ## 1. Identify the spec in flight
 
-Resolve **in this order**, and stop at the first that answers:
+**`--worktree <path>` answers before anything else.** When the invocation names a
+worktree, that is the spec to build and that is where it is built — cwd is not
+consulted. It is how `/spec-start` carries on into phase 1 without moving your
+session, and you can type it yourself.
+
+**This is not a loosening of the refusal below.** That refusal exists against
+*guessing* which spec to build, and a path someone typed is not a guess. A bare
+`/spec-next` still refuses exactly as it does today.
+
+**Validate the path before writing a line into it.** Run the resolver *from* the
+path, so the answer comes from where you are about to write:
+
+```
+cd "<path>" && skitterspec spec-env resolve
+```
+
+Check the `worktree:` line it prints is that same path. If it is not — or the
+command reports that isolation is not enabled — refuse and stop, naming what you
+were given. A path that is not a provisioned worktree must never become a place
+to write code.
+**Read the output, not the exit status** — it exits 0 even when it
+cannot resolve anything.
+
+**Not `--dir <path>`.** That flag sets the **repo root**, not the worktree to
+resolve from, so it answers a different question: on a repo with two or more
+worktrees it refuses with *"no spec given, and N specs have worktrees"* and
+validates nothing at all. The `cd` form is what makes the path itself the
+evidence.
+
+Otherwise resolve **in this order**, and stop at the first that answers:
 
 1. **The live spec of this checkout** — run
    `skitterspec spec-env live status` and read its `live:` line. `live: yes`
@@ -24,15 +58,60 @@ Resolve **in this order**, and stop at the first that answers:
    opened in one is its own workbench.
 3. **The current branch, in `checkout` mode** — no worktrees exist, so the
    branch the checkout is on names the spec.
+4. **The only spec provisioned in this repo** — ask the engine, with no spec
+   named, from wherever you happen to be standing:
+
+   ```
+   skitterspec spec-env resolve
+   ```
+
+   Take its `spec:` line **only when it names exactly one spec**.
+
+   This is the **durable** rung, and that is the whole reason it exists. Rungs 1
+   to 3 all read *session* state, and session state does not survive a `/clear`,
+   a new terminal tab, or coming back tomorrow — while the provisioned worktree
+   they are each a proxy for is **on disk** and survives all three. `/spec-start`
+   does leave the session standing in the worktree and that `cd` is real; what it
+   is not is durable. Without this rung, a repo holding exactly one answer sends
+   the operator away to re-supply something it already knew.
+
+   It is also the resolution every other bare command in this workflow already
+   uses — the worktree you are standing in, else the sole provisioned spec — so
+   this rung is what stops `/spec-next` being a silent exception to a rule
+   `.claude/rules/spec-planning.md` states has none left.
+
+   **Say which spec you resolved and how**, before writing a line of it:
+   *"not standing in a worktree — `<spec>` is the only spec provisioned"*. Rungs
+   1 to 3 are self-evident to whoever typed the command; this one is not, and
+   the operator cannot see from where they sit what you picked.
+
+   **Several worktrees stay a refusal.** The engine names them and resolves
+   nothing — exactly the ambiguity the refusal below exists for. Relay its list
+   unchanged and stop; never pick from it.
+
+   WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is still
+   a worktree, so a finished spec can go on counting as provisioned. That widens
+   the candidate set, so the failure it produces is an extra candidate — an
+   ambiguity the engine refuses on — and never a wrong spec built. It cannot
+   manufacture an *absence*, which is why the absence below is still worth
+   refusing on.
 
 **If none answers, refuse and stop:**
 `no spec in flight — run /spec-start <name> to start one`.
 
+That now answers a real absence — no worktree anywhere, the engine included —
+rather than a session that merely lost track of where it was standing.
+
 **Never fall back to the spec "in context".** A spec discussed in conversation
 is not a spec in flight, and this skill writes real code: building the wrong
 spec's phase produces commits on a branch nobody asked for. The refusal is
 cheap; the mistake is not.
 
+**Rung 4 is not that fallback wearing a hat.** A provisioned worktree is a
+record that someone ran `/spec-start`: it is on disk, the engine reads it, and it
+either names one spec or refuses. A spec named in conversation is a guess about
+intent with nothing underneath it, and no number of them ever resolves to one.
+
 A **name argument** is accepted, but it must *match* the spec in flight — it
 narrows a re-run, it does not select a different spec. A mismatch refuses,
 naming both.
@@ -79,6 +158,17 @@ 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
+  `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.
+  **Do not prompt**: an assignment question in the middle of a build is an
+  interruption with no deadline, and `/spec-claim` answers it whenever the
+  operator likes.
+- **A spec assigned to someone else is left alone.** Say so once
+  (`assigned to <name> — /spec-claim to take it`) and change nothing. Picking up
+  a colleague's spec is a decision, not a side effect of running the next phase.
 - **Never fatal.** If the push fails — offline, no key, a Linear error — say so
   and **carry on with the build**. The repo is correct regardless; the mirror is
   disposable and the next push repairs it.
@@ -89,6 +179,33 @@ once it is over. Without a provider this is a no-op and nothing below changes.
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.
 
+**Before building, compare the worktree against where you are standing.** Take
+the `worktree:` line from `skitterspec spec-env resolve <spec>` and compare it
+with this session's cwd, resolving both paths first so a symlinked or
+trailing-slash spelling of one tree does not read as two.
+
+Same tree — the ordinary case, since `/spec-start` leaves the session standing
+in it — and the rest of this step is inert.
+**Different trees, and the discipline below applies however the spec was resolved.**
+`--worktree <path>` is one way to get here and §1's rung 4 is another: a bare
+`/spec-next` typed from the primary checkout resolves the sole provisioned spec
+and builds it somewhere this session is not. What makes the discipline necessary
+is the two trees, so that is what it is conditioned on — not the shape of the
+invocation, which cannot see rung 4 at all.
+
+Record the baseline before you write anything:
+
+```
+skitterspec spec-env resolve <spec> --record-primary
+```
+
+Then build as below, with one discipline on top.
+**The session is not standing in the worktree**, so every write takes an
+absolute path under it and every command
+is prefixed `cd "<worktreePath>" &&` — typecheck and tests included. A single
+relative path lands the work in the primary checkout, on the base branch, and
+nothing about it looks wrong at the time. Step 4b is what catches it.
+
 Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
 
 - Work task by task through the phase file. Make focused edits that match
@@ -134,8 +251,184 @@ 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.
 
-## 5. Report
+## 4b. Prove nothing leaked into the primary checkout
+
+**Only when the resolved worktree is not this session's cwd** — the same
+comparison step 3 made, and it holds however the spec was resolved. Standing in
+the worktree there is no second tree to have written into, so this step does not
+apply and there is nothing to check.
+
+WHAT WOULD FOOL THIS CHECK: it watches the **primary checkout** and nothing
+else, so a build run from inside *another* spec's worktree would leak there
+unseen. That is left unhandled deliberately rather than overlooked — reaching it
+takes an explicit `--worktree` typed from a second worktree — and the cost of the
+gap is a missed leak, never a false accusation.
+
+The phase is built and its progress recorded — all of it written into a tree this
+session is not standing in. Before reporting any of it as done:
+
+```
+skitterspec spec-env resolve <spec> --assert-primary-clean
+```
+
+- **Exit 0, "primary checkout clean"** — carry on.
+- **Non-zero** — stop and relay the engine's message unchanged. It names the
+  paths and both readings: this build wrote them and they belong in the worktree,
+  or something else did and the baseline wants re-recording.
+  **Do not guess which, and do not delete anything.**
+  A path that appeared is not proof of who put it there.
+- **"cannot tell"** — no baseline, or one from another spec. It exits 0 and
+  claims nothing; say so in one line and carry on. An absence is not evidence.
+
+## 5. Render the page — then offer the review, never write it
+
+**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.
+
+The phase is built, its tests are green, and nothing is committed yet. That is
+the moment the page is about, so render it now — **after** the tests pass and
+**before** the commit:
+
+```
+skitterspec spec-env review <spec>
+```
+
+**This is free.** It is the engine reading git and splicing text into a template;
+the diff never passes through you, so a 266KB patch costs nothing. Report the
+path it prints and move on.
+
+**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.
+
+**Non-blocking, deliberately.** Do not end your turn waiting on the answer.
+Phases get chained — `/commit && /spec-next` typed as one line — and a question
+that stops the run taxes every phase to fix a problem the row already fixes.
+
+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.
+
+- **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. 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.
+
+- **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.
+- If the project has no isolation config, skip the whole step in silence rather
+  than explaining an absence.
+
+## 6. Report
+
+Do **not** `git commit` unless the user asks — finish, verify, and wait.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the phase is built and its tests are green.
+- `⚠️` — built and green, with something worth knowing (a mirror that did not
+  refresh, a deviation from the plan).
+- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
+- `⏸` — no spec in flight, or the name given does not match the one that is.
+
+**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Snags` · `Review` ·
+`Follow-ups` · `Next`
+
+## 6a. End in a picker
+
+The block says what happened; this is what to do about it. Offer the same four
+endings the review page carries, so a review finishes the same way wherever the
+reader is standing — the page, a pasted code, or here.
+
+| Option | Does |
+|--------|------|
+| `Reviewed` | Claims the waiting pass and routes on its verdict |
+| `Commit` | Runs the project's commit skill, and stops |
+| `Commit & Continue` | Commits, then `/spec-next` — and **stops there** |
+| `Discuss` | Asks what is up; changes nothing |
+
+**`Reviewed` only when a pass is actually waiting.** The render's `pending:`
+block already says. Offering a pickup with nothing to pick up is the empty
+gesture this exists against — the other three stand on their own.
+
+**Do not restate the routing.** `/spec-diff` §2, §2a and §4 own it, including
+the commit hand-off through `review.commitWith` and what `commit-continue` does
+after. Two copies of a routing rule is how the two come to disagree.
+
+**It does not break a chained run.** `/commit && /spec-next` is typed as one
+line and the picker appears at the **end**, by which point the chain has already
+finished. The cost that was feared here — a question stopping a run mid-way — is
+not a cost this placement has.
+
+**Nothing may claim a pass without a pick.** `/spec-reviewed` is user-only by
+*harness enforcement*, because prose alone once failed to stop an agent claiming
+a pass nobody asked it to. A pick keeps the **property** that makes that safe —
+a person in the conversation chose, and a device that reaches the page cannot —
+while routing around the **mechanism**, since the claim runs downstream of the
+pick. That trade is deliberate and it has exactly one condition: a run that
+shows no picker claims nothing, and a picker nobody answered claims nothing.
+
+WHAT WOULD FOOL THIS: a picker shown reflexively at the end of every run trains
+the reader to dismiss it, and a dismissed picker is indistinguishable from a
+considered decline. So offer it where there is a real choice, and let the `Next`
+row carry the rest.
+
+`Next` names the commit and then the phase, as
+`/commit, then /spec-next → phase 3 (Auth)`, so the block says what to do and
+which phase is next without a line of prose for either.
+
+**The commit is not optional politeness.** Step 6 above deliberately leaves the
+phase uncommitted, and §2 of this very skill refuses to build the next phase on
+top of an uncommitted one — so a `Next` that names only `/spec-next` sends the
+reader straight into that refusal. The two halves are four hundred lines apart,
+which is exactly how they drifted.
 
-Summarise what was implemented, the test result (quote failures if any), and
-which phase is next. Do **not** `git commit` unless the user asks — finish,
-verify, and wait.
+**Step 5's offer is the `Review` row.** It is not a paragraph after the block,
+because nothing is after the block: the counts, the page link and the question
+go in one row, above `Follow-ups` and `Next`. Step 5 renders before the commit
+and this step is where its offer lands, so the two must not disagree about where
+it goes.

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

@@ -5,6 +5,11 @@ description: Push a spec up to its linked Linear issue (repo → Linear, one-way
 
 # /spec-push — send a spec up to Linear (one-way)
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 Repo → Linear. The repo is the **source of truth**; Linear is a
 **generated mirror**. A spec is a Linear **issue**; each phase is a
 **sub-issue** (a child issue), and the phase file is mirrored into that
@@ -67,7 +72,7 @@ get past a failing check.
 ## 3. Get the plan from the engine
 
 ```
-skitterspec spec-sync push <spec> --workspace-states <file> --json
+skitterspec spec-sync plan <spec> --workspace-states <file> --json
 ```
 
 The engine prints a JSON **plan** (no network, no remote read):
@@ -230,14 +235,33 @@ branch so the mirror-link rides in the PR.
 
 ## 6. Report
 
-Summarise what was created/updated in Linear (the spec issue and its
-sub-issues), **say which transport was used**, and confirm the snapshot was
-recorded. There is no pull — Linear is a generated mirror.
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the mirror matches the repo and the snapshot is recorded.
+- `⚠️` — pushed, with something worth knowing: Linear stored different text, a
+  project picker that could not be offered, `phasesDeferred` phases not yet
+  minted.
+- `❌` — it wrote some objects and failed on another. Name what exists in Linear
+  now; `apply` stamps each id as it goes, so the re-run is an update, never a
+  duplicate.
+- `⏸` — no config, no `linear_identifier`, an unvalidated state list, or a
+  pre-9.0 mirror. Nothing was written.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` carries what was created and updated — the spec issue and its
+sub-issues — **the transport that did it**, and that the snapshot was recorded.
+
+**Say the transport, every time.** On the API path you never saw the
+descriptions, so "pushed 12 sub-issues" is the engine's report rather than your
+observation, and that distinction is the difference between a fact and a
+paraphrase. If it warned that Linear stored different text, relay it: the repo
+is still correct and a re-push overwrites the mirror.
 
-Saying the transport matters: on the API path you never saw the descriptions, so
-"pushed 12 sub-issues" is the engine's report, not your observation. If it warned
-that Linear stored different text, relay that — the repo is still correct, and a
-re-push overwrites the mirror.
+There is no pull — Linear is a generated mirror.
 
 ### Picking the Linear Project
 

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

@@ -5,6 +5,11 @@ description: Re-validate an existing spec against the current codebase — detec
 
 # /spec-review — bring a spec back in sync with the codebase
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 Specs rot: the code moves on while a spec sits in the backlog or pauses
 mid-build. This skill re-validates a spec against the **current** code and
 rewrites the stale parts so it's safe to act on. It plans only — it does not
@@ -115,6 +120,12 @@ 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
+  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:
+  they record who actioned the work, which outlives who is holding it.
 
 ### Why it sits here
 
@@ -125,12 +136,36 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
   its folder bucket. Push while the folder is still in `in-progress/` and the
   issue is set to the state the spec is *leaving*.
 - **Before the commit**, because the push stamps ids into the spec and writes a
-  snapshot under `specs/.core/`. The `git add specs/` that follows sweeps both up
-  with the status change; push after it instead and those files are left
+  snapshot under `specs/.core/`. Push after the commit instead and both are left
   uncommitted, which makes `spec-env integrate` refuse to land the branch.
 
+The snapshot is reached **by name**, not by breadth. It is a declared
+`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
+so `spec-env stage` returns it among this spec's owned paths and the commit below
+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.
+
 ## 5. Report
 
-Summarise the drift found, what you changed, any questions still open, and
-whether the spec is now safe to `/spec-start` (or should drop back to `Draft` until
-the open questions are resolved). Do **not** `git commit` unless the user asks.
+Do **not** `git commit` unless the user asks.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — checked against the code and brought up to date; safe to `/spec-start`.
+- `⚠️` — updated, but dropped back to `Draft`: questions are open that only the
+  operator can answer. Name them.
+- `⏸` — no such spec, or nothing to review. Nothing changed.
+
+**Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
+
+`Built` is the drift found and what you changed about it — a renamed file, an
+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?".
+
+**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.