@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/assets/skills/spec/SKILL.md

@@ -73,25 +73,56 @@ Briefly play back the agreed understanding before writing.
 
 This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
 
-### Write it from the base branch
-
-**Check where you are before creating the folder.** A backlog spec belongs on
-the base branch (`main`). If you are on another spec's branch — most likely
-inside its worktree, because a design question came up part-way through
-implementing it — say so before writing, and offer to author the spec from the
-primary checkout instead.
-
-It matters for more than tidiness: a spec written inside another spec's worktree
-**physically lives on that branch**. It is not on `main` until that spec lands,
-it is invisible to anyone listing `specs/backlog/` meanwhile, and if that spec is
-cancelled the new spec is cancelled with it. Committing it there also mis-stamps
-the commit's ticket trailer, since that is resolved from the branch (see
-`.claude/rules/commit-trailers.md`, installed with a ticketing provider).
-
-**Warn, don't refuse** — doing this deliberately is legitimate, and the user may
-have a reason. If they continue, carry on exactly as normal, and mention that
-the trailer for that commit wants `spec-sync ref <new-spec-name>` rather than the
-bare form.
+### Write it in its own worktree
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no worktree to make and this section does not
+apply — write the folder where you are standing, exactly as before.
+
+**Provision before you write, not after.** Grilling put nothing on disk and the
+spec's name is settled by the time Phase A ends, so this is the one moment where
+a worktree costs nothing to obtain and everything is still ahead of it:
+
+```
+skitterspec spec-env up <name> --docs
+```
+
+Run the commands it prints, then move this session into the worktree with a
+plain `cd` — the Bash working directory persists between calls, so from here on
+the spec is written on its own branch. Confirm the move landed rather than
+reading silence as success (`.claude/rules/negative-checks.md` rule 1):
+`skitterspec spec-env resolve` with no argument must name this spec. If it does
+not, say so and write the spec where you are standing instead; a spec in the
+wrong tree is worse than a spec with no worktree.
+
+**`--docs` is what makes this cheap.** It skips the `setup` commands and the
+Docker stack — everything whose only purpose is making a tree *runnable* — so
+provisioning a worktree to write markdown in is a `git worktree add` and nothing
+else. `/spec-start` re-runs `up` over the same worktree without the flag, and the
+setup runs then, at the first moment the tree is used for code.
+
+**Why the base branch is no longer where this happens.** `main` is where work
+**lands**, not where it happens. Authoring on it meant the spec sat uncommitted
+there for as long as Phase C2's page went unanswered — which is unbounded by
+design, because a reader walking away from a diff is the normal case — and a
+release could not be cut through it. The verdict lands the spec instead, so
+`main` gains it as one commit and is never dirty on the way.
+
+**A spec written in ANOTHER spec's worktree is still the mistake it always was**,
+and this section does not soften that. It physically lives on that branch: not on
+`main` until that spec lands, invisible to anyone listing `specs/backlog/`
+meanwhile, and cancelled along with its host. Committing it there also mis-stamps
+the ticket trailer, which is resolved from the branch (see
+`.claude/rules/commit-trailers.md`, installed with a ticketing provider). The
+difference is whose worktree: **its own** is now the normal path, and someone
+else's is the accident.
+
+So if Phase A ran inside another spec's worktree — most likely because a design
+question came up part-way through implementing it — the provision above is the
+fix rather than something to warn about: it moves the session out of that tree
+and into this spec's own. Where isolation is off and there is no worktree to
+move to, **warn, don't refuse**, and say the trailer for that commit wants
+`spec-sync ref <new-spec-name>` rather than the bare form.
 
 - **Every spec is a folder** — never a bare file, even for a one-line change:
   `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
@@ -266,26 +297,40 @@ phase of the lifecycle ends — on a page, in a verdict.
 skitterspec spec-env review <spec> --docs --buttons authoring
 ```
 
-`--docs` reads the spec's own documents from the tree you are standing in, so it
-never wants a worktree — a backlog spec has none. It renders
-**this spec's documents and nobody else's**: several specs are routinely
-authored in one
-checkout, and the file set comes from `spec-env stage`'s `owned` half precisely
-so a colleague's spec cannot land on your page and then be committed under your
-verdict.
+`--docs` reads the spec's own documents from the tree you are standing in, which
+after Phase B is **this spec's own worktree**. It renders
+**this spec's documents and nobody else's**: the `owned` half of
+`spec-env stage` is what supplies the file set, and it stays load-bearing even
+now that the tree holds one spec — a project's `spec.companionPaths` and a
+hand-edited `specs/.core/` both land in the same tree, and only the spec's own
+documents belong under this verdict.
 
 **This is free.** The engine reads git and splices text into a template; the
 diff never passes through you.
 
+**Never pass `--run-reviewers` here.** A spec is prose, and the reviewers
+`review.reviewers` names read code — spending a rate-limited review on a
+paragraph buys nothing. The engine refuses it on a `--docs` render whatever this
+skill asks for, so this is a note about intent rather than a guard you are
+holding: do not add the flag on the assumption that it was an oversight.
+
 **Render nothing when nothing was written.** A `⏸` run — grilling that never
 reached a shared understanding — has no spec to show, and must not ask for a
 verdict on one.
 
 **Arm nothing.** There is no `spec-env review arm` in this path, and that is a
 decision rather than an omission: the gate asserts that *a phase which ended*
-owes an answer, and a backlog spec owes no phase. Walking away from this page
-costs nothing — the spec is simply still uncommitted, which `/spec-start` already
-handles. A `/spec` run must leave `spec-env review gate --check` exiting 0.
+owes an answer, and a backlog spec owes no phase. A `/spec` run must leave
+`spec-env review gate --check` exiting 0.
+
+**And walking away from this page now costs nobody anything**, which is a
+stronger reason than the one that used to sit here. It read *"the spec is simply
+still uncommitted, which `/spec-start` already handles"* — true, and a
+concession: an uncommitted spec meant a dirty base branch, which is everyone's
+problem, so "arm nothing" was tolerating a mess rather than describing a clean
+state. Since Phase B the unanswered spec sits on its own branch in its own
+worktree, where it is in nothing's way: no release is blocked, no other spec has
+to replay over it, and it is still exactly where it was tomorrow morning.
 
 ### The two endings this page offers
 
@@ -294,12 +339,46 @@ committing pair, because "commit and build the next phase" is meaningless for a
 spec with no phase in flight.
 
 - **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
-  passing the pathspec the render reported on `docs.paths`, then run
-  **`/spec-start <name>`** and **stop there**. It never completes, lands or tears
-  anything down, exactly as `commit-continue` stops after `/spec-next`. This is
-  the `commit && /spec-start` that was typed by hand.
-- **`commit`** — the same commit, then finish. The spec stays `Ready` in
-  `backlog`, ready for a `/spec-start` whenever it is wanted.
+  passing the pathspec the render reported on `docs.paths`; **land it** (below);
+  then **keep the worktree** and run **`/spec-start <name>`**, and **stop there**.
+  It never completes or tears anything down, exactly as `commit-continue` stops
+  after `/spec-next`. This is the `commit && /spec-start` that was typed by hand.
+- **`commit`** — the same commit and the same land, then
+  **tear the worktree down** and finish. The spec stays `Ready` in `backlog` —
+  on the base branch, where anyone can see it — ready for a `/spec-start`
+  whenever it is wanted.
+
+**Both committing verdicts land, and that is what keeps the backlog findable.**
+`ls specs/backlog/` is how specs are found, and a folder bucket is only the truth
+on the branch you are standing on — so a spec left on its own branch would be
+invisible to everyone, including the next `/spec` run. The commit goes on the
+branch and then the branch goes onto the base:
+
+```
+skitterspec spec-env integrate <name>
+```
+
+It plans a rebase onto the base branch in the worktree, then a
+`merge --ff-only` in the primary checkout — run the commands it prints. It
+refuses on a dirty tree, which is correct here: the commit ran first, so anything
+still uncommitted at this point is not this spec's and the land must not proceed.
+
+**If the rebase conflicts, stop and say so.** It is unlikely on a
+documents-only branch and not impossible — two specs authored at once can both
+touch `specs/.core/`. Run `git rebase --abort`, leave the commit sitting on the
+branch, and report `❌` with the conflict: there is a standing worktree to clear,
+which is what separates `❌` from `⏸`. Never resolve someone else's conflict to
+get the land through.
+
+**The worktree lifetime follows the verdict, and the asymmetry is deliberate.**
+`commit-start` keeps it because you are carrying straight on, and `/spec-start`
+re-runs `up` over it without `--docs` — which is where the setup commands
+Phase B skipped finally run. Plain `commit` tears it down with
+`skitterspec spec-env down <name>`, because a spec parked in the backlog should
+hold no worktree and no `node_modules`; `/spec-start` provisions from scratch
+whenever it is wanted. Always-keep would leave five backlog specs holding five
+checkouts, and always-teardown would have `commit-start` re-provision seconds
+after destroying the tree it needed.
 - **`changes`** — work the notes into the spec, record a resolution for each one
   so the next render shows it struck through with what changed, then
   **re-render, and wait again**. The reader is still holding a decision, so
@@ -328,6 +407,11 @@ the verdict — and the reader's conclusion is about what the page showed them.
    verdict to a lunch break.
 3. **On waking, let the engine pick:**
 
+**A watch that dies is re-armed on the same window**, silently and bounded by
+the age of that window — `.claude/rules/spec-reports.md` carries the contract,
+including when to stop and what the banner says instead. Do not restate it
+here.
+
    ```
    skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
    ```
@@ -391,15 +475,25 @@ the shape; this section carries only what is specific here.
 
 - `✅` — a `Ready` spec is written to `specs/backlog/<name>/`.
 - `⚠️` — written as `Draft`; open questions were deliberately left. Name them.
+- `❌` — the spec was committed and the land failed part-way: the rebase
+  conflicted, or the fast-forward was refused. There is a standing worktree and a
+  branch to deal with, so say where both are.
 - `⏸` — grilling did not reach a shared understanding, so nothing was written.
   That is the skill working: a spec written over an unresolved requirement is
   the outcome Phase A exists to prevent.
 
-**Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
+**Fields:** `Tracker` · `Spec` · `Built` · `Landed` · `Worktree` · `Follow-ups` ·
+`Next`
 
 `Built` is the spec's path and phase count; `Spec` is its status and bucket;
 `Tracker` appears only when a provider is installed and linked it.
 
+`Landed` and `Worktree` belong to the **verdict** half of the run and appear
+only once one has been acted on — a run that is still waiting on the page has
+neither. `Landed` says the base branch fast-forwarded and to what; `Worktree`
+says kept (on `commit-start`) or removed (on `commit`), with the path. Neither
+appears where isolation is off: nothing was provisioned and nothing was landed.
+
 **`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
 waiting on a verdict, so the block **omits the `Review` row** and ends on the
 banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
@@ -422,6 +516,11 @@ I'm holding here until you send a verdict — the wait covers local and network.
 There `Next` names the page rather than a command, because the button is what
 carries the work on.
 
+**Neither exit leaves the spec anywhere awkward**, and the banner does not
+explain that — the whole point of Phase B is that there is nothing to warn
+about. Both buttons commit and land, so either way the spec reaches the base
+branch as one commit; the only difference is whether the worktree stays.
+
 Where no page was rendered — isolation is not configured, or nothing was
 written — `Next` is `/spec-start <name>`, with the name spelled the way it must
 be typed.

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

@@ -239,6 +239,11 @@ wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here
 The banner it describes is what this skill emits in place of a `Review` row,
 and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
 
+**A watch that dies is re-armed on the same window**, silently and bounded by
+the age of that window — `.claude/rules/spec-reports.md` carries the contract,
+including when to stop and what the banner says instead. Do not restate it
+here.
+
 **Why this skill arms as well as waits.** Waiting is what any offer does;
 **arming** asserts an obligation that outlives the turn, and belongs only to
 work that is finished. A bug fix is a completed unit — red→green, suite

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

@@ -114,6 +114,35 @@ of the work, so an unreclaimed one is worth a line rather than a silence.
 reclaim the cancelled spec's environment. On confirmation, run the `spec-env` CLI
 directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
 
+0. **Name a pass still waiting for THIS spec — before anything is removed.**
+
+   ```
+   skitterspec spec-env review waiting --json
+   ```
+
+   Filter to the spec being cancelled and say nothing about any other: a run
+   reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
+   one, give the code, the verdict and the age, then the two exits — claim it
+   now with `/spec-reviewed <code>` **while the worktree still stands**, or
+   disown it with `skitterspec spec-env review <spec> --drop <code>`.
+
+   **Why here and not anywhere else.** Nothing is about to become unreachable —
+   a pass can be disowned long after its spec is gone. What is about to pass is
+   the last moment the verdict can still be **honoured**: before teardown a
+   `commit` pass can be claimed and acted on, after it there is no branch left
+   to commit to and disowning is all that remains. On a cancelled spec that is
+   sharper still — the worktree may hold the only copy of the work, so a pass
+   approving it is the one thing that might argue for keeping it.
+
+   **It reports, and it never blocks.** No refusal, no confirmation of its own,
+   no non-zero exit — this step already asks before it reclaims anything, and a
+   waiting pass is information rather than a second gate.
+   And **it never claims** — reporting a pass is not taking one, and
+   `/spec-diff` §0 is untouched by this step.
+
+   Put what you found in the report's `Notes` row.
+   Silent when nothing is waiting, which is the usual case.
+
 1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
    main` first to free the canonical ports.
 2. `skitterspec spec-env dev down <name>` — stop its host dev servers.

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

@@ -231,6 +231,31 @@ nothing left to protect.
 worktree and branch are being kept, and go straight to sub-step 4. Mention
 `skitterspec spec-env up <name>` re-attaches it later either way.
 
+0. **Name a pass still waiting for THIS spec — before anything is removed.**
+
+   ```
+   skitterspec spec-env review waiting --json
+   ```
+
+   Filter to the spec being completed and say nothing about any other: a run
+   reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
+   one, give the code, the verdict and the age, then the two exits — claim it
+   now with `/spec-reviewed <code>` **while the worktree still stands**, or
+   disown it with `skitterspec spec-env review <spec> --drop <code>`.
+
+   **Why here and not anywhere else.** Nothing is about to become unreachable —
+   a pass can be disowned long after its spec is gone. What is about to pass is
+   the last moment the verdict can still be **honoured**: before teardown a
+   `commit` pass can be claimed and acted on, after it there is no branch left
+   to commit to and disowning is all that remains.
+
+   **It reports, and it never blocks.** No refusal, no confirmation of its own,
+   no non-zero exit. And **it never claims** — reporting a pass is not taking
+   one, and `/spec-diff` §0 is untouched by this step.
+
+   Put what you found in the report's `Notes` row.
+   Silent when nothing is waiting, which is the usual case.
+
 1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
    names this spec, run `skitterspec spec-env connect main` first so the
    canonical ports go back to the primary checkout.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-diff
-description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
+description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase, and takes --reviewers to run the project's configured code reviewers. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", "run the reviewers", or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
 ---
 
 # /spec-diff — see the phase before you commit it
@@ -161,6 +161,13 @@ back, and these steps replace §3–§5 below.
    applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
    carrying both, so there is never a choice to make between them.
 
+   **It is on the `claimed:` line** — `· action: live-on` at the end of it, and
+   `claimed.action` under `--json`. Read it there rather than inferring one
+   from a pass that merged nothing: a claim reporting no verdict and no counts
+   used to be the only trace a press left, which made every action look like a
+   reader who had concluded nothing. If the line carries no action, there was
+   none.
+
 3. **Say what you read, then ask what's up.** Report the accepted count, then
    each open comment as `file:line — note`, then the files you would touch.
    **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -395,6 +402,14 @@ way out. **Never park another spec's live session** to make room — that is
 someone else's work, and freeing it is their decision. Re-render and wait, so
 the reader can choose something else.
 
+**A refusal may declare the way out of itself.** Ask with
+`skitterspec spec-env live take <spec> --json` and read its `offer` field:
+where one is present, relay the refusal and **then** offer it, exactly as
+`.claude/rules/offered-unblocks.md` describes. Do not re-decide from the reason
+text, and do not infer an offer that is not there — the boundary that keeps
+another spec's workbench out of this lives in that field rather than in prose
+here.
+
 **`allow` writes a committed file, and that is worth a sentence.** It edits
 `specs/.core/env.config.json` in the **primary checkout**, so it changes
 behaviour for everyone who pulls and leaves that tree dirty — unlike the live
@@ -437,9 +452,26 @@ help someone give one.
 ```
 skitterspec spec-env review <spec>              # uncommitted work (the default)
 skitterspec spec-env review <spec> --branch     # everything since the base branch
+skitterspec spec-env review <spec> --run-reviewers   # …and run review.reviewers
 skitterspec spec-env review serve               # every spec, on localhost
 ```
 
+**`--run-reviewers` is opt-in here, and a BARE `/spec-diff` MUST NOT PASS IT.**
+`/spec-next` runs the project's configured reviewers once per phase, where the
+cost is paid against work that is finished. This skill answers at any point,
+including several times in one phase — and each run spends a review against
+whatever hourly limit the reviewer has, which on the tiers this was built for is
+measured in single figures.
+
+So pass it when the operator asked for it: `/spec-diff --reviewers`, or they said
+in words that they want the second opinion. Otherwise render without it. The
+cached findings from the phase-end run still show on the page whenever the diff
+has not moved, so the usual mid-phase read loses nothing by not asking.
+
+Where it does run, say what it cost — a reviewer takes 30s–3min — and nothing
+else. The page's own strip reports each reviewer's outcome, and a reviewer that
+could not run is that strip's business rather than yours.
+
 **There is no switch left to handle.** The engine serves and prints a **stack** —
 one line per tier, `local`, `network`, `remote`, each either a URL or the one
 command that turns it on. All of it is free and none of it publishes anything.

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

@@ -27,8 +27,10 @@ clobber customised content. Finish with a summary of created vs already-present.
 > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
 > `--reset` (reset needs `--yes`) drive the stronger actions.
 
-The system is **twelve skills**: `spec` (feature), `spec-bug` (bug),
-`spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
+The system is **thirteen skills**: `spec` (feature), `spec-bug` (bug),
+`spec-hotfix` (a bug fixed on a released tag),
+`no-spec` (work that genuinely has none — off the base branch all the same),
+`spec-review`, `spec-start`,
 `spec-next`, `spec-diff` (read a spec's diff as a page),
 `spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
 `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,

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

@@ -148,6 +148,12 @@ Before writing any code for this phase, get the workspace clean:
   anything is owed (`.claude/rules/negative-checks.md`). Do not mention it: a
   line about a gate nobody armed is an accusation against a healthy repo.
 
+  **It may also declare the way out.** An `armed` answer can carry an `offer`,
+  and where it does, relay the refusal and **then** offer it — once — exactly as
+  `.claude/rules/offered-unblocks.md` describes, spending it with
+  `skitterspec spec-env review gate <spec> --offered` as you raise it. Where
+  there is no `offer`, the three exits in the `Next` row are the whole answer.
+
   **This refusal counts nothing.** It is not a tally of ticked boxes — those
   still gate nothing and still are not counted. It asserts one thing: a phase
   that ended has an answer. And the exit is always **one command**, one of them
@@ -280,13 +286,34 @@ the moment the page is about, so render it now — **after** the tests pass and
 **before** the commit:
 
 ```
-skitterspec spec-env review <spec>
+skitterspec spec-env review <spec> --run-reviewers
 ```
 
 **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.
 
+**`--run-reviewers` is free to *you* as well, and costs wall-clock.** Where the
+project configured any (`review.reviewers` — empty in most projects, and then
+this flag does nothing at all), the engine runs each one against the diff before
+rendering, so the page is already populated when it is opened. Their findings
+come back as JSON and land on the page as **checks**; the patch still never
+passes through you. What it spends is 30s–3min once, after the tests are green —
+which is the cheap half of a step that is about to wait on a person for far
+longer. A re-render of unchanged work reuses the cached findings rather than
+spending another review.
+
+**Findings never gate.** A check is not a comment, so a page carrying twenty of
+them still offers `Commit`; a reader who replies to one creates a comment, and
+that does gate, because then a person has asked for something. Nothing here
+counts them, and nothing here acts on them — you render and wait exactly as you
+would have.
+
+**A reviewer that could not run is reported by the page**, not by you. Do not
+re-state its outcome, do not investigate it, and never treat it as a failure of
+the phase: the strip on the page says `clean` or `did not run — <why>` for each
+one, which is where a reader deciding whether to commit will look.
+
 **This render takes the committing button set**, which is the default — so
 `--buttons` is not passed. That is a statement about the work, not about the
 gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
@@ -315,7 +342,7 @@ so one subject lives in one place:
 
 ---
 
-## ⏸ Review ready — <N> files, +<a> −<d>
+## ⏸ Review ready — <N> files, +<a> −<d><, <n> flagged by <reviewer> — only where one found something>
 
 - **local** — <the `local:` URL>
 - **network** — <the `network:` URL, or off with the command that turns it on>
@@ -327,6 +354,19 @@ 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
 
+**The findings count goes in the COUNTS, and nowhere else.** Where `--json`
+reported a reviewer in the `findings` state, its count joins the heading — the
+slot that already says `7 files, +212 −18` — and that is the whole of it. No
+extra line, no extra row, and nothing at all when every reviewer was `clean`,
+`cached` or could not run: the page's own strip is where the per-reviewer
+outcomes belong, and repeating them here would be the second place naming one
+subject that `.claude/rules/spec-reports.md` exists to prevent.
+
+**This is not a third amendment to that contract.** The counts slot is already
+there and already carries numbers about the same diff; nothing about the
+banner's shape, its lines or its exits changes. A reader who has configured no
+reviewer sees the heading they have always seen.
+
 **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
@@ -408,6 +448,11 @@ reading — and that is the gap the whole gate exists to close.
    a diff is the normal case rather than the edge one. Do not give it a duration
    of your own.
 
+**A watch that dies is re-armed on the same window**, silently and bounded by
+the age of that window — `.claude/rules/spec-reports.md` carries the contract,
+including when to stop and what the banner says instead. Do not restate it
+here.
+
    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**:

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

@@ -82,9 +82,9 @@ A **six-digit code** is a pass the operator read off their own page. It says
 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
+A **verdict word** — `commit`, `commit-continue`, `commit-start`,
+`commit-land`, `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

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

@@ -73,6 +73,20 @@ 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.
 
+**A spec that `/spec` already landed is the HEALTHY case of that check.**
+It is not the refusal. `/spec` authors in its own `--docs` worktree and its committing
+verdict fast-forwards the base branch, so by the time `/spec-start` runs the
+spec is already in the commit the worktree forks from and the tree is clean —
+which is exactly what that check is looking for. Do not read "clean tree,
+nothing to commit" as a sign something was skipped: it means the landing worked.
+
+**And the worktree may already exist**, because `Commit & Start` keeps it. That
+is a re-attach, not a clash: `spec-env up` plans the attach form rather than a
+second `-b` fork, and its `then, in the worktree, run:` step is where the
+`setup` commands `--docs` deliberately skipped finally run. So run the plan as
+printed — the install belongs to this moment, the first at which the tree is
+used for code — and report a re-attach rather than a fresh provision.
+
 ## 2. Identify the spec
 
 - Use the name/path argument when given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",