@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/assets/rules/offered-unblocks.md

@@ -0,0 +1,100 @@
+# Offered Unblocks
+
+A refusal says what is wrong. Some refusals can also say **what would fix it**,
+and where the engine declares that, a skill may offer it rather than leaving the
+operator at a dead end.
+
+This file is the whole contract. A skill's own text says only *that* it acts on
+an offer, never how.
+
+## The engine declares; the skill relays
+
+An offer is a field on a refusal, never a judgement a caller makes from the
+reason text:
+
+```json
+{
+  "blocked": true,
+  "reason": "feat-x's worktree has uncommitted changes — commit or stash them…",
+  "offer": { "kind": "satisfy", "label": "Commit first, then go live", "command": "/commit" }
+}
+```
+
+**Absent stays absent.** Most refusals carry no `offer` at all, and that is the
+correct, common answer. Where there is none, relay the refusal and stop.
+
+**Never infer one.** If the engine did not declare an offer, there is not one —
+however obviously the reason seems to name a fix. The boundary that matters most
+lives in that decision, and it must not be re-litigated per skill:
+**work that is not the operator's is never offered up.** A live workbench another
+spec holds is that spec's operator's to free, so it declares nothing, and a
+helpful picker is exactly how that would creep back in.
+
+## Two kinds
+
+| `kind` | Means | Recorded |
+|--------|-------|----------|
+| `satisfy` | do what the guard asked for | no — nothing was weakened |
+| `bypass` | step past a guard still unsatisfied | **yes** |
+
+## Relay first, then offer
+
+In that order, and never instead. A picker that replaced the refusal would hide
+what is wrong behind a choice about what to do next — and the refusal text is
+where every exit is named, including the ones the picker does not offer.
+
+Then, only where `offer` is present, put **two** options to the operator: the
+offer's `label`, and Cancel.
+
+- **`satisfy`** — run the command, then retry the original operation.
+- **`bypass`** — run the command, then carry on.
+- **Cancel** — stop. Record nothing: declining to bypass is not a decision
+  anyone needs to audit.
+
+**The label is the engine's, shown verbatim.** Never reword a bypass into
+something easier-sounding, never pre-select it, and never add a third option. A
+bypass that arrives pre-selected is a bypass by default wearing a question mark.
+
+## A bypass is offered once per obligation
+
+The engine enforces this; a skill does not count anything. Spend the offer by
+recording it **when you raise the picker**:
+
+```
+skitterspec spec-env review gate <spec> --offered
+```
+
+After that the gate declares no offer for the same arming, so the next refused
+commit is a plain refusal with its exits named in the text. A new phase ending
+arms the gate again and is asked in its own right.
+
+**Spent by being made, not by being taken.** An operator who declines still saw
+it, and re-offering on every attempt is how a deliberate step becomes the
+default.
+
+**Do not spend it by reading.** `review gate --json` is asked on every
+`/spec-next` run; only raising the picker spends the offer.
+
+## What this is not
+
+**Not a `--force`.** One was asked for and rejected: a reasonless lift is
+indistinguishable from nobody having looked, where
+`none: additive, nothing to revert` is a decision a reviewer can argue with. The
+gate's exits are unchanged — a committing verdict, or a recorded skip — and a
+bypass is the second of those at an address a person will reach.
+
+**Not a replacement for the refusal.** A picker exists only in a harness. The
+engine and the `PreToolUse` hook keep refusing regardless, so this is a layer on
+top of a guard and never the guard itself.
+
+**Not Claude lifting a guard aimed at Claude.** `spec-planning.md` draws that
+line for `/allow-main` and `/spec-skip`, and a bypass offer survives it because
+three things hold at once, where a `--force` had none of them:
+
+1. **The operator answers.** Claude may raise the question and cannot answer it.
+2. **The choice is recorded** — a fixed reason, distinct from anything typed,
+   which shows on the next render as history.
+3. **It is offered once**, held by the sidecar rather than by prose, so it
+   survives a `/clear`, a compaction and a fresh session.
+
+Remove any one of those and the objection returns.

package/assets/rules/spec-planning.md

@@ -7,9 +7,10 @@ and lifecycle stay consistent. Each sets a status on the spec header
 
 | Skill | Purpose | Status | Folder |
 |-------|---------|--------|--------|
-| `/spec` | (Feature) Grill to a clear shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
+| `/spec` | (Feature) Grill to a clear shared understanding, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
 | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
+| `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
 | `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
 | `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
@@ -52,6 +53,81 @@ anything — scoped to the window, refusing when two arrive. `/spec-reviewed` is
 what answers everything outside it: a pass sent when nobody was waiting, two
 passes to choose between, and every harness with no file-watch to wait with.
 
+**`/no-spec` is the one row that writes no spec**, and it is in the table
+because it is the same lane: a branch, a worktree, a review page, a verdict, a
+land. What it leaves out is the document, because mechanical work — a version
+bump, a lockfile refresh, a rename — genuinely has none, and a one-phase spec
+written for it is a document nobody reads. What it does **not** leave out is the
+branch. Doing that work in the primary checkout leaves the base branch dirty for
+every in-flight spec to replay over, and renders no page, so it is the one kind
+of change that reaches the base branch unreviewed. It is model-invocable, which
+matters: it is where Claude is sent when it would otherwise write on the base
+branch. Beneath it, `skitterspec spec-env nospec <name>` records the branch —
+and that record is what makes a name with nothing under `specs/**` resolvable by
+`review`, `integrate`, `down` and a bare `resolve`.
+
+**`/allow-main` is the fourth command.** It is user-only for a different reason
+from the other three: `/spec-connect`, `/spec-live` and `/spec-remote-review`
+are marked that way because there is no judgment to apply. This one is marked that
+way because **Claude must not be able to lift a guard aimed at Claude.**
+
+The guard is `.claude/hooks/main-guard.cjs`, a `PreToolUse` hook on the write
+tools, and it refuses an `Edit` or a `Write` in the **primary checkout** while
+it is on the **base branch**. `main` is where work lands, not where it happens:
+work done there leaves the base branch dirty for every in-flight spec to replay
+over, and renders no review page at all, so it is the one kind of change that
+arrives unreviewed. It refuses the FIRST write rather than the commit, because
+nothing has been written yet and the fix is one command — where a commit-time
+gate fires once the work already exists in a checkout that cannot `switch -c`
+out from under the other worktrees.
+
+It fires only on a **positive signal** — isolation configured, the guard not
+switched off, this directory IS the primary checkout, HEAD IS the base branch —
+and every cannot-tell allows the write in silence: no repo, no config, a
+worktree, an unresolvable base, a missing or crashed engine
+(`.claude/rules/negative-checks.md`). `skitterspec spec-env main
+<check|allow|status>` is the engine, and `guards.mainIsLandingZone` in
+`env.config.json` turns it off for a project. It is
+**on by default wherever isolation is configured**, matching the review gate.
+
+There is **no allowlist**, and it is empty by construction rather than by
+omission: `/spec` authors into its own worktree and `/no-spec` catches ad-hoc
+work, so no legitimate writer to the base branch is left. `/spec-init` looks
+like the exception and is not one — it bootstraps a repo with no
+`env.config.json` yet, so the guard never fires there.
+
+**Two exits, and they are not equal.** `/no-spec <name>` and `/spec-start
+<name>` move the work, and Claude takes those on its own; `/allow-main` lifts
+the guard, and only a person can type it. That asymmetry is the same line
+`/spec-reviewed` draws, and `spec-planning.md` already records that prose alone
+did not hold it once.
+
+**`/spec-skip` is the fifth command**, and it is user-only for `/allow-main`'s
+reason rather than the mild one: it lifts the review gate, which is a guard
+aimed at Claude. It pre-executes `skitterspec spec-env review skip "<reason>"`
+and relays it — the same exit that always existed, at an address a person will
+actually type. The long form stays exactly as valid and is what the engine
+prints; what changed is that a refusal now names something reachable, because a
+gate whose exit nobody can find gets switched off wholesale instead of answered.
+
+**It is not a `--force`, and one was asked for.** A reasonless lift reopens
+precisely what the reason requirement closed: `none: additive, nothing to
+revert` is a decision a reviewer can argue with, and silence is an oversight.
+So a bare `/spec-skip` refuses and asks for a reason, and the two things that
+discharge a phase's obligation are still a committing verdict and a recorded
+skip — never a flag. Putting the flag on `/commit` was the other suggestion and
+is worse: `/commit` belongs to skittership, which is why the gate is enforced
+by a hook rather than by editing that skill.
+
+**A refusal may OFFER its own exit, and that is a different thing again.**
+Where the engine declares one, a skill relays the refusal and **then** offers it
+— once per obligation, with the choice recorded, and answered by the operator
+rather than by Claude. `.claude/rules/offered-unblocks.md` is the whole
+contract. The three properties named there are what let a Claude-raised bypass
+survive the rule above, where a reasonless `--force` did not: the operator
+answers, the choice is on the record, and it is offered once. Remove any one and
+the objection returns.
+
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
 subcommands) — but they are marked user-only too, since nobody reaches them
@@ -98,7 +174,7 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
+<up|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
 engine. **Omit the spec name anywhere and it uses the worktree you are standing in**,
 else the sole provisioned spec — with no exceptions left: a bare
 `/spec-connect` connects, and a bare `/spec-live` takes, where both once meant
@@ -129,11 +205,42 @@ stateful ones (`Stack: worktree + docker`, or a branch touching migrations) —
 `/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
 Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
 
-**Staging one spec and not another (`spec-env stage`).** Several specs are
-authored at once — that is what the worktree mode is for — and they all land in
-the same `specs/` folder until they are committed. A `git add specs/` there
-stages a *directory*, sweeping whatever another session happens to have written
-into this spec's commit, under this spec's ticket trailer.
+**Authoring a spec is work, so it happens off the base branch too (`/spec`).**
+`main` is where work **lands**, not where it happens, and a spec document is no
+exception. With isolation configured, `/spec` grills first — which puts nothing
+on disk — then provisions the new spec's own worktree with
+`spec-env up <name> --docs`, moves the session into it, and writes the spec
+there. `--docs` skips the `setup` commands and Docker, so a tree to write
+markdown in costs one `git worktree add`; `/spec-start` re-runs `up` without the
+flag and the install happens then, at the first moment the tree holds code.
+
+**The committing verdict is what puts it on the base branch.** Phase C2's page
+offers `Commit & Start` and `Commit`, and **both** commit on the branch and then
+`spec-env integrate` — rebase, fast-forward — so the base gains the spec as one
+commit. That is not optional tidiness: `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 unlanded is invisible to everyone. They differ only in the
+worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
+`commit` tears it down, because a spec parked in the backlog should hold no
+checkout.
+
+**What this bought is the reason it changed.** The page waits for a verdict
+without a timeout — deliberately, because a reader walking away from a diff is
+the normal case — and while the spec was authored in the primary checkout that
+wait held the base branch dirty for as long as it lasted, so a release could not
+be cut through it. Now an unanswered spec sits on its own branch in its own
+worktree, in nothing's way. Phase C2 still **arms nothing**: the gate asserts
+that a phase which ended owes an answer, and a backlog spec owes no phase — and
+walking away from it now costs nobody anything rather than leaving a mess
+someone else has to work around.
+
+With isolation **absent** none of this applies: there is no worktree to make and
+no land to do, so `/spec` writes the folder where the session is standing,
+exactly as it always did.
+
+**Staging one spec and not another (`spec-env stage`).** A `git add specs/`
+stages a *directory*, sweeping whatever else happens to be sitting in it into
+this spec's commit, under this spec's ticket trailer.
 `skitterspec spec-env stage [<spec>] [--json]` is how a skill asks instead of
 guessing: it splits the uncommitted tree into the paths that are this spec's —
 its folder in **any** bucket, so a tree mid-`git mv` is handled, plus each
@@ -144,6 +251,14 @@ the primary checkout outside, and prints which. The `owned` half is the spec's
 the commits this bounds are the lifecycle ones. Nothing here refuses, writes, or
 exits non-zero — `foreign` is a list of paths to leave alone, not an accusation.
 
+**And it stays load-bearing now that `/spec` authors in its own worktree**, even
+though that tree holds one spec. It was once justified by several specs sharing
+one `specs/` folder, and that justification is gone; what replaces it is smaller
+and just as real. A project's `spec.companionPaths`, a hand-edited
+`specs/.core/`, and a tracker snapshot all land in the same tree as the spec, and
+only the spec's own documents belong under its authoring verdict. Where isolation
+is absent the original reason applies unchanged.
+
 **Naming the paths is necessary and not sufficient**, which is why every spec
 commit is also pathspec-limited: `git add -- <paths>` **and**
 `git commit -m "…" -- <paths>`. A checkout has one `.git/index` and every session
@@ -237,6 +352,34 @@ silently. All of it lives beside the page in gitignored `.spec-env/`, and
 **the marks are information, never a gate**: nothing counts them and nothing
 refuses on them.
 
+**A second opinion, from something that did not write the code (`review.reviewers`).**
+The page can also carry findings from code reviewers
+that run from a CLI — CodeRabbit's has a free tier, PR-Agent and Kodus are
+self-hosted — and they arrive as **checks**, the same shape a written review
+uses. `/spec-next` runs them once per phase before the render, so the page is
+populated when it is opened; `/spec-diff --reviewers` is the opt-in mid-phase
+run, and a bare `/spec-diff` never spends one. Results are cached against a hash
+of the diff, so re-reading unchanged work costs nothing.
+
+**They inform; they never gate.** A check is not a comment, so a page carrying
+twenty findings still offers `Commit` — and a reader who replies to one creates
+a comment, which does gate, because then a person has asked for something. There
+is deliberately no severity threshold that blocks: that is the counting gate
+this whole design exists against, wearing a vendor's name.
+
+**And a reviewer that could not run says so**, which is the one place
+`.claude/rules/negative-checks.md` inverts. Silence is normally the safe branch;
+here a rate-limited or unauthenticated reviewer would render identically to one
+that read the diff and approved of it, on the page a commit decision is made
+from. So each gets a line — `12 findings` · `clean` · `did not run — <why>` —
+and none of it ever refuses a render, a verdict or a commit.
+
+The list is **empty by default** and `init` never writes one: configuring a
+hosted reviewer sends the worktree's diff to a third party, which is a real
+change for a tool that otherwise touches nothing outside `.spec-env/`. Every
+finding on the page is badged with the reviewer that produced it. `env.config.md`
+carries the field reference.
+
 **The verdict is chosen, never derived.** A verdict is one person's conclusion,
 sent once per pass; a counting gate is a refusal computed from how many boxes
 are ticked, and it stays forbidden. The one refusal here is not a count of
@@ -311,7 +454,7 @@ its verdicts and its fields.
 | **Tracker** | [ABC-88](https://example.invalid/ABC-88) · `feat-orders` · phase 2 moved |
 | **Branch** | `spec/feat-orders` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
-| **Tests** | 128 passed · npm test |
+| **Tests** | 128 passed · dotnet test |
 | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
@@ -413,9 +556,15 @@ The spec skills tell you to run "your project's typecheck and test commands" and
 to "honour project conventions". Make those concrete here so specs stay
 consistent with the codebase:
 
-- **Typecheck command:** `<e.g. npm run typecheck>`
-- **Test command:** `<e.g. npm test>` (single file/dir: `<e.g. npx vitest run path>`)
-- **Lint/format:** `<e.g. npm run lint>`
+Skitterspec never runs these itself and knows nothing about what this project
+is written in — it shells out to `git`, and to whatever you write below. The
+examples span several stacks on purpose: pick the shape that fits, or write one
+none of them describes.
+
+- **Typecheck command:** `<e.g. npm run typecheck · dotnet build · mypy . · go vet ./...>`
+- **Test command:** `<e.g. npm test · dotnet test · pytest · go test ./...>`
+  (single file/dir: `<e.g. npx vitest run path · dotnet test --filter · pytest path>`)
+- **Lint/format:** `<e.g. npm run lint · dotnet format · ruff check · golangci-lint run>`
 - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
   (architecture, code style, testing, database, etc.) rather than restating them.
 

package/assets/rules/spec-reports.md

@@ -35,7 +35,7 @@ A verdict sentence, a blank line, then a two-column table:
 | **Tracker** | [ABC-88](https://example.invalid/ABC-88) · `feat-foo` · phase 2 moved |
 | **Branch** | `spec/feat-foo` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
-| **Tests** | 128 passed · npm test |
+| **Tests** | 128 passed · dotnet test |
 | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
@@ -201,6 +201,42 @@ escape hatch is what let a whole class of runs go on asking questions nobody was
 listening for. Where a watch is unavailable the wait is the turn ending, which
 every harness can do.
 
+**A watch that dies is re-armed, silently, on the same window.** A backgrounded
+wait does not always survive a long idle: three sessions lost theirs over one
+lunch break, and two in another were killed at 43 and 30 minutes. So a wait that
+ends **without a verdict** and **was not stopped by the operator** is started
+again on the **same** `--since`. Not a fresh one — a pass that arrived during
+the gap is still inside the original window, and re-arming on a new timestamp
+would strand exactly that pass.
+
+**Say nothing when you do it.** Nothing happened and the window is unchanged; a
+line on every death turns a working loop into a stream of non-events.
+
+**An operator who stopped it is not a death.** Re-arming over a deliberate stop
+makes the wait unstoppable, which is worse than a wait that stops. Where the two
+cannot be told apart, treat it as deliberate and leave it
+(`.claude/rules/negative-checks.md` rule 4): the cost of being wrong is one
+`/spec-reviewed`, against a loop nobody can break.
+
+**It is bounded by the age of the window, not by a count of retries.** Keep
+re-arming while the window is younger than **12 hours**, then stop. A count means
+something different depending on whether deaths come five minutes or forty-five
+apart, and the observed interval already varies that much. Twelve hours
+deliberately does not cover an overnight gap — the pass is never lost, and
+`/spec-reviewed` is the designed recovery — because the alternative is waking
+the session every half hour all night for a review nobody is returning to
+before morning.
+
+**Past the bound the banner degrades**, to the sentence this file already
+defines for a transport that cannot push into the conversation:
+
+*press a verdict, then type `/spec-reviewed` — I cannot see it until you do.*
+
+That is a new **state** for an existing sentence, not a new sentence. The
+holding line is only ever printed while a wait is actually running, which is the
+rule this section has always carried: *only promise a wait the transport can
+deliver.*
+
 **The `Continue` ending, and why the banner's exits differ mid-run.** A page
 rendered part-way through a run offers `Continue` — *I have read it, carry on* —
 in place of the committing verdicts, because "commit" is the wrong verb for
@@ -422,10 +458,10 @@ fenced block **above** the table, where a fence means what a fence should mean:
 
 | | |
 |---|---|
-| **Why** | 3 assertions fail in `orders.test.js`; nothing committed |
+| **Why** | 3 assertions fail in `test_orders.py`; nothing committed |
 | **Branch** | `spec/feat-foo` · 2 commits, dirty |
 | **Built** | POST /orders handler, orders schema |
-| **Tests** | 125 passed, 3 failed · npm test |
+| **Tests** | 125 passed, 3 failed · pytest |
 | **Follow-ups** | none |
 | **Next** | fix the failures, then `/spec-next` to finish phase 2 |
 
@@ -452,11 +488,16 @@ finish, so it outlives the session:
   canonical port; not in scope here.
 ```
 
-**Say where the spec would be written.** These skills run inside the spec's own
-worktree, and a spec authored there physically lives on that branch — invisible
-from the base branch, and cancelled along with its host if the host is
-cancelled. So the offer names the primary checkout as the place to write it.
-`spec-planning.md` and `commit-trailers.md` carry the reasoning.
+**The offer needs no caveat about where.** These skills run inside the spec's own
+worktree, and a follow-up spec authored *there* would physically live on that
+branch — invisible from the base branch, and cancelled along with its host. That
+used to make the offer name the primary checkout as the place to write it.
+It no longer does: `/spec` provisions the **new** spec's own worktree before it
+writes anything and moves the session there, so the follow-up lands on its own
+branch and its own ticket without anyone naming a location. Take the offer and
+let `/spec` handle it. Where isolation is absent there is no worktree to move to,
+and the old caveat applies — `spec-planning.md` and `commit-trailers.md` carry
+the reasoning.
 
 ## Worked examples
 
@@ -468,7 +509,7 @@ cancelled. So the offer names the primary checkout as the place to write it.
 |---|---|
 | **Branch** | `spec/feat-foo` · 4 commits, clean |
 | **Built** | Auth middleware, session table |
-| **Tests** | 140 passed · npm test |
+| **Tests** | 140 passed · go test ./... |
 | **Follow-ups** | Session expiry is read from two places; phase 4 leans on one |
 | **Next** | `/spec-next` → phase 4 (Docs) |
 

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

@@ -0,0 +1,219 @@
+---
+name: no-spec
+description: Do a piece of work that genuinely has no spec — a version bump, a lockfile refresh, a rename — on its own branch in its own worktree, reviewed on a page and landed on the verdict. Never on the base branch. Use when the user says "/no-spec", or asks for mechanical work that does not warrant a spec and should not sit on main.
+---
+
+# /no-spec — work with no spec, off the base branch
+
+> 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.
+
+Some work has no spec and should not have one. Bumping four projects to a new
+version, refreshing a lockfile, a rename across a package: writing a one-phase
+document for it produces a spec nobody reads, and `spec --quick` would have been
+that under a friendlier name.
+
+**What it is not is an excuse to work on the base branch.** Two things follow
+from doing it there, and both cost someone else something: the tree is left
+dirty, so every in-flight spec has to replay over it and a release cannot be
+cut; and no page is ever rendered, so the work gets no review at all. This skill
+is the same lane every spec uses — branch, worktree, page, verdict, land —
+with the document left out because there is nothing to put in it.
+
+**It writes no spec, moves nothing through the lifecycle, and mints no ticket.**
+There is no bucket, no status, no phase index and no `Refs:` trailer. If you
+find yourself wanting any of those, the work wanted `/spec`.
+
+## 1. Name it
+
+Take a kebab-case name from the invocation. It becomes the branch
+(`chore/<name>`) and the worktree folder, so it should describe the work:
+`bump-deps`, `rename-widget-props`, `lockfile-refresh`.
+
+**Ask if none was given.** Do not invent one — a name nobody chose is a branch
+nobody recognises a week later, and this is the one thing the skill cannot infer
+from the work.
+
+**Refuse a name that is already a spec**, which the engine does for you: two
+things answering to one name is how a teardown removes the wrong tree.
+
+## 2. Provision
+
+```
+skitterspec spec-env nospec <name>
+```
+
+It records the name as a **specless branch** and prints the plan. 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 work
+happens 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 branch, and report `no spec` as its bucket. If it
+names something else, stop — say so and do nothing further, because the failure
+this guards against is a session that writes a branch's worth of work into the
+primary checkout while everything looks normal at the time.
+
+**The record is not bookkeeping.** It is the only thing that makes a name with
+nothing under `specs/**` resolvable, so without it `review`, `integrate`, `down`
+and a bare `resolve` would all refuse this branch as a spec that does not exist.
+
+**Where isolation is not configured** (`specs/.core/env.config.json` absent)
+there is no worktree to make. Say so in one line and stop: this skill exists to
+move work off the base branch, and without isolation there is nowhere to move it
+to. Do not silently do the work in place — that is the outcome it exists to
+prevent.
+
+## 3. Do the work
+
+Follow the project's rules in `.claude/rules/*.md` and `CLAUDE.md`, exactly as a
+phase would. Tests are part of the work and not after it: extend or add whatever
+covers the change, then run the project's typecheck and test commands. Do not
+proceed to the page until they are green — and if they cannot be made green, say
+so where it happens and report `❌`.
+
+**Mechanical does not mean untested.** A version bump that breaks a build is the
+commonest thing in this lane, which is why the gate is the same one a phase has.
+
+## 4. Render the page and arm the gate
+
+The work is done, the tests are green, and nothing is committed yet:
+
+```
+skitterspec spec-env review <name> --buttons nospec --run-reviewers
+```
+
+**This is free.** The engine reads git and splices text into a template; the
+diff never passes through you however large it is.
+
+`--buttons nospec` offers `Commit & Land` and `Commit`. It is its own set
+because neither of the usual pairs fits: there is no next phase to continue and
+nothing to put in flight.
+
+**Then arm the gate:**
+
+```
+skitterspec spec-env review arm <name>
+```
+
+**This skill arms, and `/spec` does not.** That asymmetry is the rule in
+`.claude/rules/spec-reports.md` rather than a choice made here: the gate asserts
+that *finished work* owes an answer, and this is finished work. A written spec
+owes no phase, so authoring arms nothing.
+
+**Then offer `/spec-diff`. Do not run it.** The written review costs real tokens
+because writing it means reading the diff, and that spend is the user's call.
+
+## 5. Wait for the verdict
+
+**The wait is a command. Do not write one.**
+
+1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
+   the whole scope of what you may claim.
+2. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <name> --since <the timestamp>
+   ```
+
+   Pass no timeout. A reader who walks away from a diff is the normal case, and
+   a bounded watch once lost a 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 <name> --claim-since <the timestamp> --json
+   ```
+
+   It claims the one pass that arrived inside the window, acts on nothing when
+   none did, and refuses to choose when two did.
+
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three, in that order — never the bare `page:` path.
+`.claude/rules/spec-reports.md` carries the shape and why every tier is named.
+
+### Route on the verdict
+
+- **`commit-land`** — hand off to `review.commitWith` (`/commit` by default),
+  then land it, then tear the worktree down:
+
+  ```
+  skitterspec spec-env integrate <name>
+  skitterspec spec-env down <name>
+  ```
+
+  `integrate` plans a rebase onto the base branch and a `merge --ff-only`; run
+  the commands it prints. `down` removes the worktree, deletes the branch and
+  **forgets the specless record**, which is what stops a torn-down name going on
+  answering to every verb with a path that is no longer there.
+
+  **If the rebase conflicts, stop.** `git rebase --abort`, leave the commit on
+  the branch, tear nothing down, and report `❌` with the conflict — there is a
+  standing worktree, which is what separates `❌` from `⏸`.
+
+- **`commit`** — the same commit, and **stop there**. The branch stands with the
+  work on it, which is the right ending for work that turned out to be bigger
+  than one sitting. Say in `Next` that `/spec-to-main` lands it later.
+- **`changes`** — work the notes, 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.
+- **`discuss`** — report and talk. Claim nothing, change nothing, tear nothing
+  down.
+
+**Never tear the worktree down on anything but `commit-land`.** It is the only
+verdict that says the work is finished, and the cost of being wrong is somebody
+else's branch removed from disk.
+
+## Report
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the work is done, the tests are green, and the verdict was acted on.
+- `⚠️` — done and green, with something worth knowing.
+- `❌` — the tests are red, or the land failed part-way. Quote the failure and
+  say what is standing.
+- `⏸` — refused before acting: no name given, the name is already a spec, the
+  `cd` did not take, or the project has no isolation. Nothing changed.
+
+**Fields:** `Branch` · `Built` · `Tests` · `Notes` · `Landed` · `Worktree` ·
+`Review` · `Follow-ups` · `Next`
+
+**No `Tracker` and no `Spec`, ever.** There is no ticket and no document, and a
+row saying so would report an absence with nothing behind it — which
+`spec-reports.md` forbids for exactly this reason.
+
+`Landed` and `Worktree` appear only once a verdict has been acted on; a run
+waiting on the page has neither, and **omits the `Review` row** in favour of the
+banner, which carries the counts, the stack and the two exits:
+
+---
+
+## ⏸ Review ready — &lt;N&gt; files, +&lt;a&gt; −&lt;d&gt;
+
+- **local** — &lt;the `local:` URL&gt;
+- **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
+- **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
+
+I'm holding here until you send a verdict — the wait covers local and network.
+
+`Commit & Land` finishes it · `Commit` keeps the branch
+
+---
+
+There `Next` names the page rather than a command, because the button is what
+carries the work on.
+
+**`Follow-ups` is where a spec gets offered.** This lane is for work with no
+spec, so the thing it most often surfaces is work that *does* want one. Offer to
+`/spec` it on the spot — and `/spec` provisions its own worktree, so there is
+no caveat about where to write it.