@skitterbyte/skitterspec-linear 12.0.0 → 14.0.0

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

@@ -5,22 +5,30 @@ description: Put a spec in flight — provision its branch, move it to in-progre
 
 # /spec-start — put a 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.
+
 One checkout, one spec in flight. This skill is how a spec gets there:
 provision, move it to `in-progress`, refresh the tracker, then hand straight on
 to `/spec-next` for phase 1. Continuing a spec afterwards is `/spec-next`;
 finishing it is `/spec-complete`.
 
-## 1. The gate — refuse unless the workbench is free
+## 1. The gate — what each mode demands of the tree
 
 **Check this first, before resolving anything or touching a file.** What the
 gate demands depends on the mode, because the two modes hold work in different
 places — read `mode` from `specs/.core/env.config.json` (default `worktree`).
 
-**`worktree` mode — the tree must be clean, and that is all.** The spec is built
-in its own worktree, so another spec being in flight is not a conflict; it is the
-parallelism the mode exists for. The only requirement is that this checkout has
-no uncommitted work — *except* the spec you are starting, which `spec-env up`
-commits for you (see below). Nothing is switched here and nothing is parked.
+**`worktree` mode — there is no tree gate.** The spec is built in its own
+worktree, so neither another spec being in flight nor its uncommitted files are a
+conflict; both are the parallelism the mode exists for. `git worktree add`
+carries nothing and forks from a commit, and the one thing this run writes into
+the checkout — the spec's own commit, which `spec-env up` plans for you — names
+its paths on both the `add` and the `commit`, so it cannot reach a file that is
+not this spec's. Work belonging to someone else is **reported and left alone**,
+never a refusal. Nothing is switched here and nothing is parked.
 
 **`checkout` mode — the workbench must be free**: on the base branch (`main`, or
 the configured `baseBranch`) and clean, since the branch is built right here and
@@ -37,21 +45,30 @@ and a half-built phase are each a decision someone must make deliberately — an
 the cost of guessing is another spec's work moved without its author asking. A
 refusal costs one command; the alternative can cost an afternoon.
 
-**The one exception is the spec you are starting.** `spec-env up` classifies the
-uncommitted tree against the target spec and answers one of three ways — relay
-what it says rather than deciding for yourself:
+**What `spec-env up` does with the tree**, in both modes — relay what it says
+rather than deciding for yourself:
 
-| What it found | What it does |
-|---------------|--------------|
-| clean | provisions, as always |
-| every path belongs to this spec | plans `git add` + `git commit` **first**, then the fork |
-| any path does not | refuses, naming the paths that disqualified it |
+| What it found | `worktree` | `checkout` |
+|---------------|-------------|-------------|
+| clean | provisions | provisions |
+| every path is this spec's | commits those paths **first**, then forks | same, then switches |
+| some path is not | commits this spec's, provisions, **reports the rest** | refuses, naming them |
 
 That is membership in an exactly-known set — the spec's own folder plus the
 project's `spec.companionPaths` — and **not** a judgement about whether the
-changes look important. The gate still never decides that. When it plans the
-commit, the paths are printed above the commands, so run them as printed; when it
-refuses, relay the reason and stop.
+changes look important. It never decides that.
+
+**The last row is the only real difference, and it is mechanical.**
+`git switch -c` carries the working tree onto the new branch, so in
+`checkout` mode a colleague's files really would be moved without them asking.
+`git worktree add` carries nothing, so in `worktree` mode the same files are
+simply not this run's business — and refusing over them fired on the commonest
+tree this workflow produces: a second spec authored while the first is still
+uncommitted. When it reports them, say how many and whose in the `Untouched` row
+and **keep the verdict `✅`** — nothing went wrong.
+
+When it plans the commit, the paths are printed above the commands, so run them
+as printed; when it refuses, relay the reason and stop.
 
 It also refuses a **clean** tree whose spec is not in the commit the worktree
 would fork from — otherwise you get a branch missing the very spec it is for.
@@ -71,69 +88,131 @@ would fork from — otherwise you get a branch missing the very spec it is for.
   probably still exists, so this is a re-attach: say so rather than reporting a
   fresh start, and skip the housekeeping that is already done.
 
+## 2b. Bring the review server up — from here, before anything else
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no review server and this step does not exist —
+skip it in silence rather than explaining an absence.
+
+```
+skitterspec spec-env review serve --host 0.0.0.0
+```
+
+**Here is the point.** Right now this session is standing in the
+**primary checkout**, and in a moment step 3 `cd`s into a worktree and stays
+there. A
+daemon started after that `cd` is started *by the worktree's copy of the code* —
+and when `/spec-complete` removes that worktree, the daemon keeps answering on
+its port and fails on every page it is asked for, for every spec. The engine
+defends against that now, but the cheapest fix is to never create the situation:
+start it while you are still somewhere that outlives the spec.
+
+It is also what lets **several specs be reviewed at once**. Reviews all render
+into the primary checkout's `.spec-env/reviews/`, so one server serves every
+provisioned spec — including specs another agent is building in another
+worktree. Starting it here means that one server belongs to the checkout none of
+them can delete.
+
+**Say nothing when it is already up.** The usual outcome is adoption — a server
+is running and this changes nothing — and a line per `/spec-start` about a
+daemon nobody asked about is the narration `.claude/rules/spec-reports.md`
+forbids. Speak only if it could not start.
+
+**Never fatal, never a gate.** A busy port, no network address, a refused
+spawn — say it in one line and **carry on**; provisioning is not conditional on
+it, and the page falls back to its `file://` URL exactly as it does today.
+
+**`--host 0.0.0.0` is the deliberate half.** It binds the server to this
+machine's network addresses so the page opens on a phone, and the engine mints a
+token with that bind as its only guard. On a machine you would rather not expose,
+drop the flag — the server is then reachable from this machine alone and the
+render says so. On **`--plan`** this step does not run at all.
+
 ## 3. Build its branch
 
 ### `worktree` mode
 
+**One path. There is no branching here and none should be added back.**
+
 1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
-   `to provision, run:` commands it prints and confirm they succeeded, **except**
-   the `open.command` line, which belongs to the hand-off in 3 below.
-
-2. **Enter the worktree — this session, no new window.** The spec is built in its
-   worktree; that is what the mode is for, and it is why `main` stays free and
-   several specs run at once. So put *this* session there rather than opening
-   another one: call **`EnterWorktree`** with the worktree path.
-
-   **Do it immediately after `git worktree add`, before bootstrap and before the step 4 housekeeping.**
-   Once the session is the worktree, `setup` runs in place and the housekeeping
-   is plain `git` — the `cd` and the `git -C <worktreePath>` prefix both
-   disappear. **Never `cd` into the worktree first:** `EnterWorktree` refuses a
-   path that is already the working directory
-   (`is the current working directory`), so a bootstrap `cd` does not merely
-   make the call redundant, it makes it fail.
-
-   Then run the planner's **`then, in the worktree, run:`** steps in order (file
-   seeding, then `setup`) — a fresh worktree has no dependencies and none of the
-   repo's gitignored files, so hooks, typechecks and tests fail until they are
-   there. Do the step 4 housekeeping, then say to run **`/spec-next`**, here.
-
-   **Do not move the branch into this checkout**, and do not ask the operator to.
-   Entering the worktree is the opposite of moving the branch out of it — the
-   branch never leaves. `/spec-live` is for testing a finished-enough spec on the
-   already-running dev server; it is not the way work gets started, and reaching
-   for it here is what used to split a start across two invocations.
-
-3. **When you cannot enter, hand off as before.** Two cases, and
-   **decide from cwd before calling**, not by calling and catching — an error
-   surfaced mid-skill reads as a bug, and both conditions are knowable in
-   advance:
-
-   - **This session's cwd is already inside a worktree.** `EnterWorktree` only
-     allows a worktree→worktree switch when the target lives under
-     `.claude/worktrees/`, and a project's worktree root usually does not
-     (`../{repo}-wt` is the shipped shape). Do not "fix" this by relocating the
-     root: starting a spec from the base branch is the documented path anyway.
-   - **`EnterWorktree` is unavailable** — a harness without it. There is no CLI
-     counterpart to fall back on, so the skill degrades rather than fails.
-
-   On either, do exactly what this skill did before: bootstrap with
-   `cd "<worktreePath>"`, housekeep with `git -C <worktreePath>`, run
-   `open.command` if one is configured, print the worktree path, and say to run
-   **`/spec-next`** from a session in it.
-   **Trust the worktree first** on this path: `spec-env up` wrote the printed
-   `trusted:` root into `.claude/settings.local.json`, but that file will not
-   hot-reload in this session — run `/add-dir <trusted root>` before editing into
-   the worktree, or the first write prompts. (Entering the worktree makes both
-   moot: the writes are then in-cwd.)
-
-   `EnterWorktree` is gated on being told to work in a worktree by the user or by
-   project instructions. A lifecycle skill directing it **is** project
-   instruction, so the call is in contract here.
-
-**`/spec-next` is unchanged by this.** Its rule 2 — "the worktree you are
-standing in" — is what answers once the session has actually moved; nothing about
-its resolution is loosened, and it must not be. The refusal exists so the wrong
-branch is never built.
+   `to provision, run:` commands it prints and confirm they succeeded.
+
+2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
+   `.claude/settings.local.json`, but that file does not hot-reload in this
+   session — run **`/add-dir <trusted root>`** before editing into the worktree,
+   or the first write prompts. This is not tab machinery: worktrees live outside
+   the checkout, and the trust entry is what stops the prompt.
+
+3. **Bootstrap it, and move into it.** The `cd` is in the command itself, and it
+   **moves this session** — that is what it is for, not a side effect of it. The
+   Bash working directory persists between calls, so from here on this session is
+   standing in the worktree, which is what lets a bare `/spec-next` resolve the
+   spec on its own:
+
+   ```
+   cd "<worktreePath>" && <the planner's "then, in the worktree, run:" steps>
+   ```
+
+   Run the seeding steps before `setup`: a fresh worktree has no dependencies and
+   none of the repo's gitignored files, so hooks, typechecks and tests fail until
+   both have happened.
+
+   **Then confirm the move landed — never assume it.** Ask for a positive signal
+   rather than reading silence as success (`.claude/rules/negative-checks.md`
+   rule 1): run `skitterspec spec-env resolve` with **no argument** and read the
+   `spec:` line it prints.
+
+   ```
+   skitterspec spec-env resolve        # must name this spec
+   ```
+
+   Three states, not two. It names this spec → carry on. It names something else,
+   or resolves nothing → **the `cd` did not take**. Say so plainly and fall back
+   to the stop-here ending in step 6, printing the path so the operator can open
+   a session there themselves; do not build a phase from a session whose location
+   you could not confirm. A failed `cd` leaves you in the primary checkout on the
+   base branch, where a phase's worth of code looks entirely normal at the time.
+
+4. **Housekeep with `git -C <worktreePath>`** — step 4 below, against the
+   worktree.
+
+   **Keep the `-C` prefix**, even though the session is inside the worktree now
+   and a bare `git` would usually do the same thing. It is immune to the one
+   failure this sequence can have — a `cd` that silently did not take — where a
+   bare `git` would instead write the spec's move into the primary checkout on
+   the base branch. It costs nothing and removes a whole failure mode, so do not
+   tidy it away.
+
+5. **Print the worktree path.** What happens next is step 6 — it is offered
+   there, not decided here.
+
+**The session moves into the worktree, and nothing opens a window.** Those are
+two different claims and both are load-bearing. The move is real, and the `cd` in
+step 3 is its whole mechanism — no tool call, because an approval prompt is
+unusable on a phone and leaves the session stuck. Nothing is *spawned*: no new
+terminal, no tab, no editor sent anywhere, because that machinery had nothing
+left to do and was removed deliberately.
+
+**Do not move the branch into this checkout**, and do not ask the operator to.
+`/spec-live` is for testing a finished-enough spec on the already-running dev
+server; it is not how work gets started.
+
+**`/spec-next`'s refusal is unchanged by this.** Its rule 2 — "the worktree you
+are standing in" — is what answers afterwards, and step 3 is what puts the session
+there; nothing about rules 1 to 3 is loosened, and it must stay that way, because
+the refusal exists so the wrong branch is never built. What changed is where the
+session stands, not how weakly the rules read: a bare `/spec-next` typed from
+somewhere that is neither a worktree nor a live checkout still refuses exactly as
+it did. `--worktree <path>` survives untouched beside it — it answers before those
+rules and cannot be reached by guessing.
+
+**And the `cd` is a convenience, not the only thing holding this together.**
+`/spec-next`'s **rule 4** asks the engine for the sole provisioned spec, so a
+bare `/spec-next` resolves this spec from anywhere in the repo — after a
+`/clear`, from a new tab, tomorrow morning. That is what makes step 6's
+stop-here ending an honest offer rather than a promise only this session can
+keep. Do not delete rule 4 as redundant with the `cd`: the `cd` is session state,
+and rule 4 is what is left once it is gone.
 
 ### `checkout` mode
 
@@ -145,20 +224,149 @@ refusal and stop.
 ## 4. Move the spec into development
 
 **Do this before you report anything**, so no path can end with a provisioned
-worktree and a spec still reading `Ready` in `specs/backlog/`. Having entered the
-worktree (step 3.2) this is plain `git` — you are standing in it. On the hand-off
-path (step 3.3) run it against the worktree with `git -C <worktreePath>` instead;
-in `checkout` mode the branch is already here.
+worktree and a spec still reading `Ready` in `specs/backlog/`. In `worktree` mode
+run it against the worktree with `git -C <worktreePath>`; in `checkout` mode the
+branch is already here.
 
 - `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
   already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
 - 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
+`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.
+
+**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
+is a cosmetic gap that `/spec-claim` closes later.
+
+1. **Work out who you are.** Run `skitterspec spec-sync whoami --json`.
+   - `ok: true` → use `id` and `name`. Nothing to ask.
+   - `source: "mcp"` or the command reports no API key → call the discovered
+     user-read tool with `me`, then cache it:
+     `skitterspec spec-sync whoami --set <id> --name "<name>"`.
+   - `ok: false` → identity is **unknown**, which is an ordinary state (a shared
+     or bot key, an offline machine). Go to step 2.
+2. **Unknown identity — three states, not two.** Decide by what is actually
+   reachable, and route the third to inaction:
+   - **Linear reachable *and* this is an interactive session** → offer a short
+     user search (`skitterspec spec-sync users <name-or-email>`, or the
+     user-list tool on MCP), let the operator pick, and offer to cache it with
+     `whoami --set` so this is asked once per machine rather than once per spec.
+   - **Not reachable, or not interactive** → say so in one line
+     (`assignment skipped — no Linear identity`) and **carry on**. Do not prompt
+     for something you could not act on, and never stall a `/spec-start` on it.
+3. **Record it on the spec** — through the engine, never by hand-editing
+   frontmatter:
+
+   ```
+   skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
+   ```
+
+4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
+   seam already set it, and this seam must not overwrite it with the tracker's
+   display name.
+
+   Those two names are the same person and often not the same string, and the
+   git one is the one everything else in the spec already uses: `Author:`, every
+   **State log** `By` row, and every commit. Writing the tracker's name into this
+   one field would leave a spec whose own audit trail contradicts its header —
+   a worse problem than the one it would solve. Anyone wanting a different name
+   on their specs sets `git config user.name`, and it stays consistent
+   everywhere.
+
+   The header names **who is building this**; the stamp in step 3 names
+   **which tracker account it is assigned to**. They answer different questions,
+   so they need not be the same string. The one place that reasoning does not hold
+   is handing a spec to *someone else* — there is no local git name for them —
+   and that case belongs to `/spec-claim --to`, which sets the header from the
+   tracker deliberately.
+
+**Nothing is pushed here.** `assign` writes the repo only, and the refresh these
+skills already run sends it. Assignment is an ordinary field of the projection,
+not a side errand with its own network call.
+
+**There is no unassign step anywhere.** The projection derives the assignee from
+the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
+issue through the push they already make. The stamp deliberately stays in the
+file: who actioned the work outlives who is currently holding it.
+
 - Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
-- **Commit it, and push the branch.** One commit, the spec's own — it records the
-  in-progress state for everyone and fires the tracker's automation. Do this
-  *before* the tracker refresh below, so the snapshot that refresh writes is
-  swept up by the phase's own commit rather than left dirty.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec's overview
+carries a `linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
+this step changes.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
+moved to `in-progress/` and been stamped with a developer — two real state
+changes, and the tracker is a generated mirror of them. It costs one engine call
+and no model tokens when a Linear API key is set (see `apply.transport` in
+`linear.config.md`).
+
+- **Never mint.** An unlinked spec is skipped, not created. A spec kept
+  deliberately local should stay that way — `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The spec is in flight in the repo
+  regardless; the mirror is disposable and the next push repairs it. Do not roll
+  the provisioning 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.
+
+### Why it sits here
+
+Pinned **after the `git mv` and before the commit**, and both halves matter:
+
+- **After the move**, because the projection reads a spec's workflow state from
+  its folder bucket. Push while the folder is still in `backlog/` 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` that follows sweeps both up with
+  the status change; push after it instead and those files are left uncommitted —
+  which strands a dirty worktree on the hand-off, and makes `spec-env integrate`
+  refuse to land the branch.
+
+### Why this is not the refresh `/spec-next` already runs
+
+It was once reasoned that a push here would send the same thing twice, one commit
+apart, because `/spec-next` refreshes the moment it starts. That holds only in
+`checkout` mode, where `/spec-next` follows immediately. In `worktree` mode the
+spec is built elsewhere and the refresh can be hours away or never come — and
+until it does, the issue sits in its old workflow state with nobody assigned
+while the repo reads `in-progress` with a developer on it.
+
+The two pushes are not duplicates either way. This one carries the issue's
+workflow state and its assignee; the one `/spec-next` runs carries phase 1
+starting. Every other lifecycle skill mirrors the state change it makes, and this
+is the seam that stops `/spec-start` being the exception.
+
+- **Commit it.** One commit, the spec's own — it records the in-progress state on
+  the branch, and sweeps up everything above so the worktree is clean when you
+  hand it over.
+
+**Publishing that branch is yours to do, and nothing here does it for you.**
+Whenever you want the work somewhere other than this machine:
+
+```
+git -C <worktreePath> push -u origin <branch>
+```
+
+Print it if it is useful; never run it. This skill once pushed here, justified as
+recording the state "for everyone" and firing the tracker's automation — and
+neither half survives reading. The automation needs `{identifier}` in
+`branch.pattern` (see `env.config.md`) to put an issue id in the branch name, and
+the shipped default carries none, so the tracker has nothing to match. Nor was it
+an invariant: `/spec-bug` provisions a worktree the same way and has never
+pushed, and `/spec-hotfix` forbids it outright. This was the odd one out.
+
+**It also kept a guard from ever firing.** `refuseTeardownIfUnpushed` blocks
+teardown on commits that are unpushed and unlanded — which described no branch at
+all while this skill published every one of them at provisioning. It can fire now,
+and the place it does is `/spec-cancel`, where the work really is about to be
+destroyed: that skill relays the refusal and offers both ways out. Nothing to do
+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.
@@ -193,18 +401,75 @@ marks phase 1 started, refreshes the mirror again, builds it with tests and
 reports. Do not stop and ask the operator to run it: the branch is here and they
 asked to start the spec.
 
-**`worktree` mode — the spec is built in its worktree**, and step 3.2 put this
-session there, so end by saying the worktree path is now the session's and to run
-**`/spec-next`** here. On the hand-off path (step 3.3) the session did not move:
-say so plainly, print the path, and tell them to run `/spec-next` from a session
-in it.
-
-`/spec-next` resolves the spec it is *standing in* — the live spec of the
-checkout, the worktree its cwd is inside, or the branch in `checkout` mode — and
-a name argument narrows a re-run rather than selecting a spec elsewhere. That
-refusal is deliberate: building the wrong spec's phase writes commits on a branch
-nobody asked for. **Do not work around it**, and do not offer to build the phase
-from here.
+**`worktree` mode — offer it, then do what they say.** Step 3 left this session
+standing in the worktree, so both endings happen right here and neither needs a
+second session opened anywhere. In prose: say the worktree is ready and name its
+path, then ask **"build phase 1 now?"** — recommending that they do, and naming
+both endings so the decline is a real answer rather than a formality.
+
+**Never fence that question.** A grey box is read as an artefact to skim rather
+than as something someone is being asked, which is the whole reason
+`.claude/rules/spec-reports.md` bans fencing a message to the reader. This step
+prescribed a fenced block for a long time and an operator read straight past it,
+which is the evidence, not a preference.
+
+- **Build it here** — carry on into a bare **`/spec-next`**. Bare is right: the
+  session is in the worktree, so its rule 2 resolves this spec with nothing
+  passed and nothing guessed.
+- **Stop here** — the operator is left standing in the worktree on a provisioned
+  branch, which is a perfectly good place to leave things. Nothing has to be
+  reopened or handed anywhere, and `/spec-next` typed an hour later — from this
+  session or a fresh one — does exactly what it would have done now.
+
+**Ask rather than deciding for them, and mean it.** Provisioning is cheap and
+reversible; a phase build is neither, and one yes should not cover both. A large
+phase is often better started in a session of its own with a whole context budget
+to spend, and only the operator knows which this is. On **`--plan`** this step
+does not run at all — nothing was provisioned to build in.
+
+**`--worktree <path>` is still there, and is still not a way around the refusal.**
+It builds a spec the session is *not* standing in, which after step 3 is the
+exception rather than the normal path. Reach for it in exactly two cases: the
+confirm in step 3 reported the `cd` did not take, or you deliberately mean to
+build some other spec's phase from here. A path someone typed is not a path
+anything guessed, which is why it was never a loosening of the refusal and still
+is not.
+
+## 7. Report
+
+**When step 6 carried on into `/spec-next`, emit no block here.** That skill ends
+with its own, and its `Branch` and `Spec` fields already carry everything this
+one would say. Two blocks for one run is the noise the contract exists to
+remove — this section is for the run that stops at step 6.
+
+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 branch is provisioned, the spec is `in-progress`, the session is
+  standing in the worktree.
+- `⚠️` — provisioned, with something worth knowing (dev servers that did not
+  come up, a mirror that did not refresh, a missing gating decision).
+- `❌` — provisioning failed part-way and left something behind. Say what, and
+  where.
+- `⏸` — the gate refused: in `checkout` mode a dirty tree or someone else's
+  unfinished work, in either mode a spec whose own files are not in the commit
+  the worktree would fork from. Nothing changed. Another spec's uncommitted work
+  is **not** on this list in `worktree` mode — it is an `Untouched` row on a
+  `✅`.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Follow-ups` · `Next`
+
+`Worktree` carries the path, because the session is now standing in it and the
+operator's next command depends on knowing that. `Next` is `/spec-next`.
+
+`Untouched` appears only when `spec-env up` reported uncommitted work that was
+not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing
+went wrong: a worktree carries nothing, so that work was never in play.
+
+On **`--plan`** nothing was provisioned, so the verdict is `⏸` and `Built`
+carries the plan rather than a claim about the repo.
 
 ## Opt-outs
 
@@ -213,14 +478,29 @@ from here.
   that the work lands wherever you are (usually the base branch); reserve it for
   a trivial change or an explicit request.
 
-There is no `--here`: `/spec-start` **is** here. It puts the branch in the
-checkout you are in, which is what the old opt-out was reaching for.
-
-## Why there is no tracker seam here
-
-This skill creates no spec and mints no issue, so it has nothing to link — the
-intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`. The
-state change it *does* make (the spec moving to `in-progress`) is mirrored by
-the refresh `/spec-next` runs the moment it starts, which pushes the issue state
-and the phase states together. Adding a push here would send the same thing
-twice, one commit apart.
+There is no `--here`. It existed to ask for the branch in the checkout you are
+standing in — and in `checkout` mode that is already what happens, while in
+`worktree` mode `--no-worktree` is the way to say it.
+
+## Why this skill links nothing, but does mirror what it changes
+
+This skill creates no spec and mints no issue, so it has **nothing to link** —
+the intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`.
+
+It does push, though, and that is step 4's seam. The state change it makes — the
+spec moving to `in-progress` with a developer stamped on it — is mirrored by the
+skill that makes it, exactly as `/spec-complete`, `/spec-cancel` and
+`/spec-review` mirror theirs. It was once reasoned that the refresh `/spec-next`
+runs would cover it, so a push here would send the same thing twice one commit
+apart. That only ever held in `checkout` mode, where `/spec-next` follows
+immediately; in `worktree` mode it can be hours away or never come, and the
+issue sits in its old state with nobody assigned meanwhile.
+
+The **assignment** seam just above it is still not a push, and does not need to
+be. This is the one moment in the lifecycle where "who is building this" is
+actually decided — the branch is being provisioned for someone, and that someone
+is at the keyboard. It stamps the spec file and stops there, so it costs no
+tracker call and rides out on the push below like every other field. Deferring
+the stamp to `/spec-next` would be worse than untidy: in `worktree` mode the two
+can be separated by hours, and a spec in flight with nobody named on it is
+exactly the gap assignment exists to close.

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

@@ -6,6 +6,11 @@ disable-model-invocation: true
 
 # /spec-status — one-way sync drift report
 
+> 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.
+
 Read-only. Reports two things and writes nothing:
 
 1. **Pending push** — has the spec changed since the last push (is there an issue
@@ -67,8 +72,25 @@ a hand edit misses some (it has, twice).
 
 ## 4. Report
 
-Relay the engine's output verbatim. Suggest `/spec-push` if a push is pending.
-Never write to either side.
+Relay the engine's output **verbatim, above the block** — it is the answer, and
+the block is the verdict on it. Never write to either side.
+
+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**
+
+- `✅` — 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.
+- `⏸` — no config, or the spec is not linked. Nothing to compare.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` is the drift in one line — what would push, and whether the tracker's
+state diverged. `Next` is `/spec-push` when a push is pending, and nothing to do
+when it is not.
 
 A **`phases: <mode>`** line names the phase mode that resolved for this spec's
 lifecycle bucket, and appears only when it is not the default `subissue`.