@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

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

@@ -5,16 +5,20 @@ description: Push a spec up to its linked Linear issue (repo → Linear, one-way
 
 # /spec-push — send a spec up to Linear (one-way)
 
-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 sub-issue's description as
-written — its prose, its sections, and its tasks as a read-only checklist, never
-as issues of their own. Only the phase's h1 and `> **Status:**` line are left
-out, because both are pushed as fields of their own (the sub-issue's title and
-state). This skill
-computes what changed since the last push and applies it — it never reads Linear
-content back or merges. A person editing the mirror in Linear will see it
-overwritten on the next push.
+> 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
+sub-issue's description as written — its prose, its sections, and its tasks as
+a read-only checklist, never as issues of their own. Only the phase's h1 and
+`> **Status:**` line are left out, because both are pushed as fields of their
+own (the sub-issue's title and state). This skill computes what changed since
+the last push and applies it — it never reads Linear content back or merges. A
+person editing the mirror in Linear will see it overwritten on the next push.
 
 **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
 tell the user how to enable Linear sync and stop.
@@ -68,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):
@@ -190,10 +194,10 @@ skitterspec spec-sync verify <spec> --stored <file>
 
 It compares against what the engine sent, ignoring the reformatting Linear
 legitimately applies (renumbered ordered lists, `-`→`*`, collapsed table
-separators, checkbox case, whitespace) and reporting only lost or altered **word
-characters**. Relay any divergence — it prints both sides around the first
-difference. It exits 0 either way: the repo is unaffected and still correct, so
-this is a warning, not a failure.
+separators, checkbox case, whitespace) and reporting only lost or altered
+**word characters**. Relay any divergence — it prints both sides around the
+first difference. It exits 0 either way: the repo is unaffected and still
+correct, so this is a warning, not a failure.
 
 This is **not a pull**. Nothing read here is merged, stamped, or written
 anywhere; the repo remains the only source of truth. Do it before step 5 so a
@@ -231,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.
 
-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.
+**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.
+
+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
@@ -44,6 +49,19 @@ trust the spec's own wording — verify:
 - **Backward compatibility.** Re-confirm the planned API/schema changes are still
   additive/safe given the current code (see the project's compatibility rules).
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>`. A spec it names has no recorded gating
+decision — or a bare `none` that records nothing — and that is
+**drift like any other**: the question was never asked, or its answer was lost. Grill for it in
+step 3 and write the header in step 4, exactly as you would a stale file path.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 3. Grill only where a decision is needed
 
 Where the drift forces a choice (the old approach no longer fits, a referenced
@@ -54,12 +72,12 @@ resolve it by reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
-- Rewrite stale **Decisions** / **Solution overview** and refresh the **Impact
-  map** in `00-overview.md`, and stale **tasks** in the phase files, so they
-  match the current code and the resolved questions. Add/remove tasks within a phase file; add a new phase by
-  creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
-  dead phase by removing both. Keep the index and files in sync; **preserve
-  completed `[x]` history**.
+- Rewrite stale **Decisions** / **Solution overview** and refresh the
+  **Impact map** in `00-overview.md`, and stale **tasks** in the phase files,
+  so they match the current code and the resolved questions. Add/remove tasks
+  within a phase file; add a new phase by creating a `0N-<slug>.md` file
+  **and** a matching overview index row, or drop a dead phase by removing both.
+  Keep the index and files in sync; **preserve completed `[x]` history**.
 - **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
   It is mirrored in that file's `> **Status:**` line and in the matching
   `00-overview.md` phase-index row, but the **heading is the authoritative one**:
@@ -102,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
 
@@ -112,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.

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

@@ -0,0 +1,241 @@
+---
+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.
+disable-model-invocation: true
+---
+
+# /spec-reviewed — pick up the review you just approved
+
+> 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.
+
+You read the diff somewhere else, pressed a verdict, and the engine is holding
+the pass. This is how it gets picked up.
+
+## What this is for, now that the picker exists
+
+`/spec-next` and `/spec-diff` both end in a picker carrying these same endings,
+so the usual way to pick a review up is to choose one there. This command is
+what covers the case that picker cannot.
+
+**A picker is consumed when the turn ends.** Nobody scrolls back and answers one
+an hour later. So a review read over lunch, a session cleared, a fresh terminal
+tomorrow morning — in every one of those the control is gone and the pass is
+still waiting, and this is the way in. That is a narrower job than it once had,
+and not an absent one.
+
+**It is also the only claim path the harness itself enforces** — see below.
+Deleting this skill as redundant with the picker would leave no path that has
+the mechanism at all, only paths that have the property.
+
+## Why this is user-only, and why that is the whole point
+
+`disable-model-invocation: true` is not ergonomics here — it is the enforcement
+of `/spec-diff` step 0's central rule:
+**never claim a pass you were not asked to claim**.
+
+That rule exists because a review pass can be POSTed by anything that reaches
+the page, and what it cannot reach is **this conversation**. So a stranger's pass
+sits in the holding area forever — unless an agent goes and fetches it, which is
+exactly what happened once: an agent found a waiting approval, read its code off
+disk, claimed it, and reported the round-trip working.
+
+Prose alone did not prevent that. The harness does —
+**the model cannot invoke this skill** — so a pass is only ever picked up
+because a person typed the command. Typing it *is* the human signal. A later edit that makes this skill
+model-invocable does not make it more convenient — it removes the only thing
+standing between a stray approval and someone's repo.
+
+## 1. Resolve the spec
+
+Bare, exactly as every other bare command in this workflow: the worktree you are
+standing in, else the sole provisioned spec. Ask the engine rather than guessing:
+
+```
+skitterspec spec-env resolve
+```
+
+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.
+
+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 **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 —
+
+```
+skitterspec spec-sync linked --json
+```
+
+— which answers `[{ spec, bucket, identifier }]`, and match on `identifier`.
+**With no provider installed an id resolves to nothing**, and that is the right
+answer rather than a guess: a `SKS-227`-shaped string is not evidence that a
+tracker exists. Say the id matched no spec and stop.
+
+## 1a. Targeting another spec? Get into its worktree first
+
+**Only when the resolved spec's worktree is not where this session stands.**
+Compare the `worktree:` line from `skitterspec spec-env resolve <spec>` against
+cwd, resolving both paths first so a symlinked or trailing-slash spelling of one
+tree does not read as two. **Same tree — say nothing and carry on.** That is the
+ordinary case, and a line about it is narration.
+
+**Different trees, and it matters for what comes after, not for the claim.**
+Claiming is harmless from anywhere: the sidecar lives in the primary checkout.
+But an honoured `commit` verdict **commits**, and `changes` **edits files**, and
+both must land in *that spec's* worktree — done from here they would land in
+this one, on the wrong branch, looking entirely normal at the time.
+
+So **ask, then move**:
+
+*"`feat-orders` lives in `../repo-wt/orders`, and picking its review up means
+committing there — move this session over to carry on?"*
+
+- **On a yes**, move with a plain `cd "<worktreePath>"`. That is the whole
+  mechanism, exactly as `/spec-start` does it — not a tool call, because an
+  approval prompt is unusable on a phone.
+  Then **confirm the move landed** rather than assuming it
+  (`.claude/rules/negative-checks.md` rule 1): run `skitterspec spec-env resolve`
+  with no argument and check its `spec:` line names the target. If it does not,
+  stop — do not claim a pass you are about to act on from a tree you could not
+  confirm.
+- **On a no, stop without claiming.** A pass claimed here and acted on there is
+  exactly the split this guard exists to prevent, and claiming first would spend
+  the code for nothing.
+
+**A target with no worktree is a refusal.** There is nowhere for a commit to
+land. Name it, suggest `/spec-start <name>`, and stop.
+
+**Why not simply refuse unless you are on the base branch?** Because that bans a
+legitimate case — standing in one spec, picking up another's review — while
+*still* leaving the work to be done in a tree you are not in. The relocation is
+needed either way, so the relocation is the guard.
+
+## 2. Read what is waiting
+
+```
+skitterspec spec-env review <spec>
+```
+
+Its `pending:` block lists each waiting pass — code, verdict, age:
+
+```
+pending: 1 waiting
+  792969 · commit · 1 min ago
+```
+
+**Never open `.spec-env/reviews/<spec>.pending.json`.** The render carries
+everything a decision needs, so there is nothing to go looking for, and going
+looking is the bypass step 0 forbids. The file is right there and readable; that
+is precisely why the rule is written down rather than assumed.
+
+**Nothing waiting is an ordinary answer.** Say so and stop. Do not hunt through
+other specs, and do not treat an empty holding area as a problem — a `file://`
+page copies to the clipboard instead of sending, so mention that the pass may be
+on their clipboard waiting to be pasted, and finish.
+
+## 3. One pass waiting? Act on it
+
+**Claim it and go to step 4.** Do not read the code out, and do not ask whether
+it is theirs. The operator typed this command, which is the whole signal — and
+this skill is the one place in the workflow where that signal cannot be
+manufactured, because the model cannot invoke it.
+
+**The code was never an authorisation.** A later edit must not restore it as
+one. It earned its keep when the *page* pushed: the agent went looking, found
+a pass, and had to prove which one it had. That channel is gone. What stops a
+stranger's approval reaching your repo is that a device on your network can
+reach your page and cannot reach this conversation — the confirmation step
+added nothing to that, and cost a round-trip on every review.
+
+So the code has exactly one job left: **telling two passes apart**. That is
+disambiguation, not a gate.
+
+**Two or more waiting is a refusal to guess.** Name them all — code, verdict,
+age — and ask which. Never take the newest, the oldest, or the only `commit`:
+this is the one case where a stranger's pass really is sitting beside theirs,
+and the six digits are the only thing that separates them.
+
+*"Two are waiting — 792969 (commit, 1 min ago) and 324199 (commit-continue,
+just now). Which is yours?"*
+
+**A pasted code skips even that.** `/spec-reviewed 324199` names the pass
+outright, so there is nothing to disambiguate and nothing to ask — claim it and
+act.
+
+**On "that isn't mine"**, leave it and offer to drop it:
+
+```
+skitterspec spec-env review <spec> --drop <code>
+```
+
+A pass that stays is reported on every render until the operator stops reading
+the line — which is how the real one gets missed.
+
+## 4. Claim it and act
+
+```
+skitterspec spec-env review <spec> --claim <code>
+```
+
+Then **route on the verdict exactly as `/spec-diff` §2 does** — its steps 2, 2a
+and 4 own that routing, including the commit hand-off through
+`review.commitWith` and what `commit-continue` does after it. Follow it; do not
+restate it here, because two copies of a routing rule is how the two come to
+disagree.
+
+That includes the one rule worth knowing before you invoke anything:
+`commit-continue` runs `/spec-next` and **stops there**. It never completes,
+lands or tears anything down.
+
+**A code that matches nothing refuses, and names nothing.** The engine answers
+that way and you relay it unchanged: do not list what *is* waiting, and never
+fall back to "the only one". Both would hand a guesser the answer, and the
+second is exactly the fallback that would let an unread pass through. A mistyped
+digit is the ordinary cause — say the code matched nothing and let the operator
+look again.
+
+That holds whichever door the code came through, the paste included. A wrong
+code is a wrong code.
+
+A claim is a **delivery mechanism, not a second kind of review**: a pass that
+arrived this way means exactly what the same pass pasted into the chat would
+mean — or picked from `/spec-next`'s picker, which is the same conclusion
+reached by a third route.
+
+## 5. Report
+
+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**
+
+- `✅` — a pass was claimed and its verdict acted on.
+- `⚠️` — claimed and acted on, with something worth knowing.
+- `❌` — it acted and stopped part-way; the commit failed, or the work did.
+  Quote it.
+- `⏸` — nothing was waiting, the operator said the waiting pass was not theirs,
+  they declined the move to another spec's worktree, or the target has no
+  worktree at all. Nothing changed, and none of those is a failure.
+
+**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Worktree` ·
+`Follow-ups` · `Next`
+
+`Worktree` appears only when this run **moved the session** — the path it moved
+to, because the operator's next command depends on knowing where they now are.
+A run that stayed put omits it.
+
+`Built` is what the verdict produced — the commit, or the commented files
+worked. A run that claimed nothing built nothing and omits it.