@skitterbyte/skitterspec 18.0.0 → 19.0.0

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

@@ -5,6 +5,11 @@ description: Investigate a bug, capture it as a Bug-type spec, and drive it red
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
 
+> 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.
+
 This is the **bug** counterpart to `/spec` (which is for **features**, plan-only).
 Unlike `/spec`, this skill is hands-on and test-first: it reproduces the bug as a
 **failing test (RED)**, captures a lean Bug spec, then works the test to **GREEN**.
@@ -50,7 +55,7 @@ provision from — you'll flesh it out in §4:
   `## Symptom` you established above.
 - Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
   the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
-  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
+  the worktree path, and any `in the worktree, run:` bootstrap steps.
 - Run the printed commands in order. The plan **commits the stub first** — the
   worktree forks from `main`'s last commit, so the stub has to be in it — and
   then adds the worktree. Nothing to move afterwards: the spec is already there.
@@ -67,8 +72,8 @@ provision from — you'll flesh it out in §4:
   edits will prompt.
 - **Do everything below in the worktree**, on the branch — the red test, the fix,
   and the rest of the spec. Act on the worktree with absolute paths /
-  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
-  opener). `main` changes only when the branch merges (at `/spec-complete`).
+  `git -C <worktreePath>`, or open a session rooted at the printed path. `main`
+  changes only when the branch merges (at `/spec-complete`).
 
 ## 3. Write the failing test FIRST (RED) — mandatory
 
@@ -168,6 +173,8 @@ fix narrative and decisions — keep them separate.
 
 
 
+
+
 ### Release gating (only when configured)
 
 **Only when `specs/.core/gating.config.json` exists.** Before writing the spec,
@@ -201,10 +208,108 @@ is a no-op.
 
 
 
+## 5b. Render the page — then offer the review, never write it
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no worktree to read and this step does not exist —
+skip it in silence rather than explaining an absence.
+
+The fix is green and nothing is committed yet. That is the moment the page is
+about, so render it now — **after** the tests pass and **before** the commit:
+
+```
+skitterspec spec-env review <spec>
+```
+
+**This is free.** The engine reads git and splices the patches into a template;
+the diff never passes through you, so a 266KB patch costs nothing.
+
+**Then offer `/spec-diff`. Do not run it.** The written review is the part that
+costs — roughly **700 output tokens**, because writing it means reading the diff
+— and that spend is the operator's call, not a default.
+
+**The offer is the `Review` row of step 6's block** — the counts, the page link
+and a question, in one row:
+
+| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+
+**It ends in a question, addressed to someone.** It was once a fenced block of
+engine output, and it fired on every phase and was never once taken: two quoted
+lines under the test counts, addressed to nobody, with the report then closing
+on *"commit this first"* — the last instruction the reader got was to move on,
+so they did. A row in a labelled table is findable; a question in it is
+answerable. Both halves are load-bearing.
+
+**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
+the page and the question stay in the same row: two adjacent rows about one page
+make the reader resolve a distinction before acting on either. A later edit that
+moves it out of the block, or separates the link from the question, undoes this
+and should be read as a regression rather than tidying.
+
+
+Relay the **`open:`** line rather than the bare path: a path is not clickable in
+any terminal, and a page nobody can open is a page nobody reads.
+
+- **Never write the review unasked**, and **never publish**. Publishing leaves
+  something behind that this tooling cannot remove, so it is always an ask. A
+  `file://` link is no use on a phone, and saying so **is** the ask —
+  `/spec-diff` §6 owns how.
+**Follow the `reader:` line the engine printed — do not sniff for it.** It
+answers where the person reading this is sitting, and the offer changes with it:
+
+- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
+  unknown is the ordinary state of a local machine, and a warning there is an
+  accusation against a healthy session.
+- **`local`** — the `file://` URL.
+- **`remote`** — the engine has already stood its local server up and put a URL
+  the reader can open on `open:`. So there is **nothing special to say**: relay
+  that line like any other. Any `also:` lines under it are the other addresses
+  this machine has, offered because the best-guess one can be wrong — pass them
+  on rather than editing them out.
+
+**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
+not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
+and in `--json`, and a second implementation here could not be tested and would
+drift.
+
+**Serving is the engine's to do; publishing is never.** A `remote` reader
+authorises a local server — one process, ended by one flag, leaving nothing
+behind — and authorises nothing else. Publishing leaves a page this tooling
+cannot remove, so it stays an ask in every case, always. If the engine could not
+serve (a busy port, a machine with no network address) it falls back to the
+`file://` URL with its marker, and that is when publishing is worth naming.
+
+- **Never fatal.** A failed render — no worktree, a git error — is one line, and
+  the fix is still done. The page is a convenience; the repo is the record.
+
 ## 6. Report
 
-Summarise: root cause, the failing→passing test, the fix, and the full test
-result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it (**when isolated**, the fix lives on the bug's branch, and
-`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
-user asks.
+Do **not** `git commit` unless the user asks. The spec stays in `in-progress`;
+`Next` names the commit and then `/spec-complete`, as
+`/commit, then /spec-complete` — this skill leaves the fix uncommitted, and
+`/spec-complete` §2 refuses on pre-existing uncommitted changes, so naming only
+the second half sends the reader into a refusal. `/spec-complete` then verifies
+and archives it (**when isolated**, the fix lives on the bug's branch, and it
+merges that back to `main`).
+
+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**
+
+- `✅` — red→green, the fix is in and the suite passes.
+- `⚠️` — green, with something worth knowing (a narrowed repro, a mirror that
+  did not refresh).
+- `❌` — the test is still red, or a later test broke. Quote the failure.
+- `⏸` — the bug could not be reproduced, so nothing was written. Say what was
+  tried; an unreproduced bug is a finding, not a failed run.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
+`Review` · `Follow-ups` · `Next`
+
+`Cause` is the root cause in one clause and `Built` is the fix — the
+failing→passing test belongs in `Tests`, named, so the evidence is a test name
+rather than an adjective.
+
+Step 5b's offer is the `Review` row, not a paragraph after the block — the
+counts, the link and the question in one row. Nothing follows the block.

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

@@ -5,6 +5,11 @@ description: Cancel a spec — capture the reason, record final progress, stamp
 
 # /spec-cancel — record, stamp a reason, 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,
@@ -54,12 +59,22 @@ move the whole folder).
 
 
 Then **commit the cancellation edits** — this skill wrote them, so it commits
-them:
+them. Ask the engine which paths are this spec's, then stage and commit
+**exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): cancel <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): cancel <name>" -- <the owned paths>
 ```
 
+**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.
+
 **This matters more here than anywhere else.** Teardown (step 7) refuses a dirty
 worktree and offers `--force` as the way through — and forcing would destroy the
 cancellation record this skill just wrote. Committing first means teardown never
@@ -67,7 +82,31 @@ needs `--force`. Do not `git push`.
 
 ## 6. Report
 
-Confirm the cancellation, the reason recorded, the new location, and the commit.
+**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**
+
+- `✅` — stamped, moved to `cancelled`, committed, torn down.
+- `⚠️` — cancelled, with something worth knowing: teardown declined, a tracker
+  refresh that failed, unpushed commits the operator chose to let go.
+- `❌` — it acted and stopped part-way. Say what is where.
+- `⏸` — no reason given, or no such spec. Nothing changed.
+
+**Fields:** `Tracker` · `Spec` · `Worktree` · `Follow-ups` · `Next`
+
+**The reason goes in the verdict clause** — `✅ /spec-cancel · feat-foo ·
+superseded by feat-bar`. It is the one thing anyone reading this later wants,
+and a cancellation is an ordinary successful run, so it must not be mistaken for
+a `Why`: that field is for a run that did not do what it set out to.
+
+`Worktree` says what was reclaimed, or that teardown was declined and the
+worktree still stands — on a cancelled spec that worktree may hold the only copy
+of the work, so an unreclaimed one is worth a line rather than a silence.
 
 ## 7. Tear down the environment (opt-in, only if configured)
 
@@ -78,22 +117,22 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 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.
-**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
@@ -108,6 +147,32 @@ only ordering that survives.
    remove the worktree/stack and free the slot. It respects the teardown guards
    (won't destroy a dirty/unpushed worktree without `--force`).
 
+   **When it refuses over unpushed commits, relay both ways out.**
+   A cancelled spec is normally unlanded, so this is the one moment in the
+   lifecycle where that guard genuinely fires — and it fires about real loss.
+   The worktree is the only copy of this work: the branch is on no remote and
+   not merged into the base branch, so removing it ends it. Say that plainly,
+   relay the engine's reason, and give both endings:
+
+   ```
+   publish it first — keeps the work reachable, then re-run /spec-cancel:
+     git -C <worktreePath> push -u origin <branch>
+
+   or accept the loss (the worktree and its commits go):
+     skitterspec spec-env down <name> --force
+   ```
+
+   **Print the push; never run it.** Publishing abandoned work to a shared
+   remote is the same unasked-for act this workflow took out of `/spec-start`,
+   and it is no more wanted here — someone may well want this branch to exist
+   nowhere but their own machine. Offer the command and wait for an answer.
+
+   **Never reach for `--force` yourself either.** The engine's own message names
+   only that half, which is the whole reason this step exists: meeting a wall
+   labelled *--force to tear down anyway* at the exact moment a backup is still
+   cheap is how work gets thrown away. Both options, then stop — the choice is
+   a decision about someone's work, and it is theirs.
+
    If the plan prints a `remote branch — confirm with the user first:` section,
    **ask before running that line** — it is a `git push <remote> --delete`, and
    the branch is merged, so it loses nothing. Usually there is nothing to ask:

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,
@@ -73,21 +78,63 @@ specs — `git log`/the per-spec State log give the completion order.
 
 
 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)
 
@@ -189,22 +236,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
@@ -224,9 +271,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