@skitterbyte/skitterspec-linear 12.0.0 → 13.0.0

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

@@ -5,6 +5,11 @@ description: Finish a spec — verify all phases are genuinely done, update prog
 
 # /spec-complete — verify, finalise, archive a spec
 
+> 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.
+
 ## 1. Identify the target spec
 
 - Use the name/path argument if given, else the spec **in context**. If unclear,
@@ -90,6 +95,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
 
@@ -100,26 +111,74 @@ 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.
+
 Then **commit the completion edits** — steps 3–4 are this skill's own output, so
-it finishes its own work rather than handing you a dirty tree:
+it finishes its own work rather than handing you a dirty tree. Ask the engine
+which paths are this spec's, then stage and commit **exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): complete <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): complete <name>" -- <the owned paths>
 ```
 
-Step 2 established the tree was otherwise clean, so this commits exactly the
-status flip and the move — nothing of yours rides along.
+**Never `git add specs/`.** That stages a *directory*, so a spec another
+session is part-way through writing lands in this commit under this spec's
+ticket. The `--` on the **commit** is the other half: a checkout has one
+`.git/index`, shared by every session standing in it, so a bare `git commit`
+takes whatever else is staged there however carefully you staged your own.
+`.claude/rules/spec-planning.md` carries the full account.
+
+So this commits exactly the status flip and the move, and nothing of yours — or
+of anyone else's — rides along.
 **This is what lets step 6 land:** `integrate` refuses a dirty worktree, so
 without committing here the skill would block on the very edits it just made.
 Do not `git push`.
 
 ## 5. Report
 
-Confirm the move, the commit, the final test result, and list anything deferred.
+**The block is emitted when the run ends, not where this section sits.** The
+sections below run after it, so their outcome belongs in the block — write it
+once, at the end, with what actually happened.
+
+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**
+
+- `✅` — every phase done, tests green, landed, torn down.
+- `⚠️` — finished, with something worth knowing: teardown declined, a tracker
+  refresh that failed, a hotfix tag still waiting to be pushed.
+- `❌` — it acted and stopped part-way — a conflicted rebase, a failed
+  cherry-pick, a red base after landing. Say what state the repo is in and quote
+  the failure; there is a mess to clear and the reader needs to know where.
+- `⏸` — phases are unfinished, tests are red, or the tree is dirty. Nothing
+  moved.
+
+**Fields:** `Tracker` · `Spec` · `Tests` · `Landed` · `Worktree` ·
+`Follow-ups` · `Next`
+
+**Report this spec and no other.** A completion is the moment it is most
+tempting to survey what is left — what else is in flight, what is in the
+backlog, which worktrees are still standing — and it is the moment it helps
+least: the reader has just finished something and cannot tell whether a line
+about another spec followed from it. `Next` is one action for this spec, and
+`/spec-list` is where the wider picture lives if they want it.
+
+`Landed` says how, because the two ways differ: a fast-forward names the base
+and the commit, a hotfix names the deploy tag and the `main` cherry-pick — and
+a deploy tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
+what was reclaimed, including any orphaned volumes swept, or that teardown was
+declined and the worktree still stands.
 
 ## 6. Land the branch (opt-in, only if isolated)
 
@@ -221,22 +280,22 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    canonical ports go back to the primary checkout.
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
-**Standing in the worktree? Leave it before you tear it down.** If this
-session's cwd is inside the spec's own worktree, get out **first**, then run the
-teardown commands. How you leave depends on how you got in:
-
-- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
-  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
-  directory it started from *and* clears the caches still pointing at the
-  worktree, which a bare `cd` does not: after a `cd` the session stays registered
-  against the tree and asks you about it again when it ends.
-- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
-  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
-  nothing, but the `cd` is what relocates you.
-
-**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
-entered by path in any case, and the `spec-env down` plan below has to stay the
-single thing that deletes — a second deleter is how the teardown guards get
+**Standing in the worktree? Leave it before you tear it down.** If this session's
+cwd is inside the spec's own worktree — the normal case in `worktree` mode, since
+`/spec-start` moves you there — get out **first**, then run the teardown commands.
+One instruction covers it:
+
+```
+cd <primary checkout>
+```
+
+That is the whole mechanism, and it does not matter how you got in: the session
+was moved by a `cd` and it leaves by one. There is no tool to call here, and none
+should be reached for — the move in is a plain `cd` precisely because a tool that
+asks for approval is unusable on a phone.
+
+**`spec-env down` stays the single thing that deletes a worktree.** The plan
+below is the only deleter, because a second one is how the teardown guards get
 bypassed.
 
 Not because git refuses — it does not. `git worktree remove` **succeeds** on the
@@ -256,9 +315,19 @@ only ordering that survives.
    worktree without `--force`), so if it *does* refuse, relay that and stop
    rather than reaching for `--force`.
 
+   **The unpushed half of that guard cannot fire here, by construction.**
+   Step 6 landed the branch, so `merged` is true and `planDown` skips the check
+   entirely (`env/teardown.js`) — completing a spec never meets it, however the
+   branch was or was not published. `/spec-cancel` is where it does fire, because
+   a cancelled spec is unlanded and its worktree really is the only copy; the
+   publish-or-`--force` path therefore lives in that skill and this one needs no
+   equivalent. A refusal reaching this step is about a **dirty tree** instead,
+   which means something wrote into the worktree after the landing — read it,
+   don't force it.
+
    **If the plan prints a `remote branch — confirm with the user first:` section, ask before running it.**
-   `/spec-start` pushed this branch when it provisioned, so the remote copy
-   outlives teardown unless someone deletes it. The planner only ever offers
+   Nothing published this branch for you, so a remote copy exists only because
+   you pushed it by hand — and it outlives teardown unless someone deletes it. The planner only ever offers
    this for a branch that has **landed**, so say so plainly when you ask — the
    commits are on the base branch (or captured by the deploy tag), so deleting
    the remote branch loses nothing. On a yes, run the printed