@skitterbyte/skitterspec 21.0.0 → 22.1.0

package/assets/rules/spec-reports.md

@@ -35,8 +35,8 @@ 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 |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) |
+| **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) |
 
@@ -87,23 +87,95 @@ the options may be offered after the table.
 
 ## ⏸ Review ready — 7 files, +212 −18
 
-**[Open the page](http://…)** · I'm holding here until you send a verdict.
+- **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
+- **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
+- **remote** — off · `/spec-remote-review` turns it on
+
+live: off — /spec-live to put it live
+
+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
 
 ---
 
-A rule, a heading naming the state and the size, the link in bold, one line
-saying the run is stopped, and the two exits. Nothing else, and never a
-paragraph explaining it.
+A rule, a heading naming the state and the size, **the stack**, the `live:`
+line, one line saying the run is stopped and which tiers it covers, and the two
+exits. Nothing else, and never a paragraph explaining it.
+
+**The `live:` line, and why a rigid contract took a second amendment.** Reading
+a diff is not the only way to judge a change — often the question is whether it
+*works* — and the answer to that lives at the running URL. A reader deciding
+whether to open the page at all wants to know whether it is already running
+somewhere, and finding that out any other way is a trip to a terminal in the
+middle of a review.
+
+**Each line names a command a person types**, rather than describing a
+capability. `live: off — the page can put it live` told the reader that a page
+somewhere could do it and left them to find the verb — and the verb is what they
+need when they are in a terminal rather than on the page. So the lines say
+`/spec-live`, `/spec-live main`, `/spec-remote-review`. Making them *clickable*
+was considered and rejected: the only clickable thing markdown has is a URL, and
+a URL that acts when it is **fetched** is one a link previewer or a prefetcher
+fires with nobody involved.
+
+It is the engine's line, copied like the stack: `spec-env review` prints it and
+`--json` carries the same answer as `live`, from one function, so the report and
+the command cannot disagree. Four states, and only three of them are a line —
+`on` (with the URL when the project configured one), `off`, `held` (naming the
+spec holding the workbench). The fourth, `unavailable`,
+**prints nothing at all**:
+a project with no isolation and a spec with no worktree both land there,
+and a line about a surface that does not exist is an accusation against a
+healthy repo.
+
+**This is the second amendment to this section in two specs**, which is worth
+naming rather than letting pass. The contract earns its rigidity from real
+failures, and two amendments in a row is how a rigid contract quietly becomes a
+negotiable one. Both have carried their reason and both replaced a line rather
+than adding a paragraph.
+**A third should have to argue harder than either did.**
+
+**The stack is the engine's, copied rather than composed.** `spec-env review`
+prints one line per tier and `--json` carries the same thing as `tiers`, so take
+it from there in the order it comes — and do not decide which tiers are worth
+mentioning. The whole reason the stack exists is that the engine was being asked
+to guess where the reader was sitting, and it guessed wrong three separate ways
+in one day; a skill re-deciding that in prose is the same guess one layer up.
+
+**Three tiers, always all three, in this order.**
+
+| Tier | Is | Off when |
+|------|----|----------|
+| `local` | the loopback URL — the machine the run is on | never. With nothing served it is the `file://` page, and says it cannot send a verdict |
+| `network` | the LAN URL — a phone on the same wifi | `review.allowNetwork` is false, or this machine has no network address |
+| `remote` | a published page, for a reader off the network | `review.allowRemote` is false, or nothing has been published |
+
+A tier that is off **keeps its line** and names the one command that turns it
+on. Dropping the line is what left a reader who had walked out of the house with
+nothing on screen to tell them a remote page was even possible — they could not
+ask for what they could not see.
 
 **Only promise a wait the transport can deliver.** The wait itself is real in
 every case; what varies is what carries it back, not whether the run is
 stopped. Three transports, three true sentences:
 
-- **A page the engine SERVES** hands its pass to the local store, which a
-  file-watch sees. The run is woken by the press:
+- **A page the engine SERVES** hands its pass to the local store, and
+  `spec-env review wait` returns when it lands. The run is woken by the press:
   *"I'm holding here until you send a verdict."*
+
+  **That sentence is only true for as long as the wait is actually running**, so
+  the wait is the engine's and never one composed for the occasion. A watcher
+  written per run is proven by nothing: one was written
+  `until [ -f "$P" ] && [ "$x" \> "$y" ]` — valid bash, a syntax error in zsh,
+  a predicate that could never be true — and it spun for five minutes while the
+  report underneath it said the run was holding.
+  **Silence is what made that expensive**:
+  a wait that cannot fire and one patiently working look identical,
+  so nothing seemed wrong until the reader asked. Give the wait no timeout
+  either; it lasts as long as the session, because a reader who walks away from
+  a diff is the normal case and a bounded watch once lost a verdict to a lunch
+  break.
 - **A `file://` page** has no server to POST to, so the pass is copied and
   pasted — the reader's next message is what carries it. The run is stopped just
   the same, and says so:
@@ -112,10 +184,16 @@ stopped. Three transports, three true sentences:
   not a lesser one, and it is not an excuse to ask without waiting.
 - **A PUBLISHED page** writes to the artifact's own store, and nothing pushes
   from there into the conversation. That is the one case where a verdict is
-  genuinely invisible until someone asks for it, so the banner says that instead
-  of claiming a watch:
+  genuinely invisible until someone asks for it, so its line in the stack says
+  that rather than letting the holding line speak for it:
+
+- **remote** — [https://…](https://…) · a verdict here needs `/spec-reviewed`
 
-**[Open the page](https://…)** · press a verdict, then type `/spec-reviewed` — I cannot see it until you do.
+  Where `remote` is the only tier a reader can reach, the holding line says so
+  too: *press a verdict, then type `/spec-reviewed` — I cannot see it until you
+  do.* Where a served tier is reachable as well, the holding line keeps naming
+  the tiers the wait covers, and `remote`'s own caveat sits on `remote`'s line
+  where it belongs.
 
 **A harness with no file-watch does not get an exemption.** It once read
 "change nothing" — keep the row, keep the question, do not wait — and that
@@ -123,15 +201,57 @@ 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
-unfinished work. Its banner names the same state and different exits:
+unfinished work. Its banner names the same state and the same stack, and
+different exits:
+
+…the stack, unchanged…
 
-**[Open the page](http://…)** · I'm holding here until you send a verdict.
+I'm holding here until you send a verdict — the wait covers local and network.
 
 `Continue` carries on · `Request changes` works them now
 
+The stack is written out once, above, and referred to everywhere else. Two
+copies of it is how the two come to disagree about which tiers exist.
+
 **It is not the `none` verdict that was removed.** `none` recorded itself and
 did nothing, which is the record-and-do-nothing ending this contract exists
 against. `Continue` **resumes the run** — it names an action, which is the bar
@@ -145,13 +265,40 @@ block. *Waiting* is what any offer does, and it is what this section governs.
 that is finished. A mid-run render waits without arming — walking away from it
 costs nothing, which is exactly why `Continue` is safe to offer there.
 
-**Exactly one link, never two.** The banner offers the page the reader can
-actually use, and the engine has already decided which that is — a served URL
-when it could serve, a published one only when it could not. Handing over both
-asks the reader to know which door the run is standing behind, and they cannot:
-it was done, and a verdict was pressed on the published page three times while
-each one sat unread under a line claiming the run was waiting. Two links is not
-a convenience with a caveat; it is the caveat existing at all.
+**One link per reachable store, each labelled.** This amends
+*"exactly one link, never two"*, and the evidence that rule was written on is
+the reason it still reads the way it does. Two links were handed over, the wait
+stood behind only one of them, and a verdict was pressed on the published page
+three times while each one sat unread under a line claiming the run was waiting.
+Two links was not a convenience with a caveat; the caveat existing was the bug.
+
+**What that evidence is about is the store, not the count.** A served page hands
+its pass to the local pending store, which `spec-env review wait` watches; a
+published page writes to the artifact's own store, which nothing here can see.
+Two links into two stores asks the reader to know which door the run is standing
+behind, and they cannot.
+
+**Local and network are two doors into one room.** The page POSTs with
+`fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
+opened at `192.168.0.136:7760/…` reach the same server process and the same
+pending store. One wait covers both, and a verdict pressed on either wakes the
+same run. Between those two the objection does not apply — which is why both are
+offered, and why offering them gives nothing up.
+
+**So two things are required, and the second is what the old rule lacked.**
+Every link is **labelled** with its tier, and one line says
+**which tiers the wait covers**.
+Two *unlabelled* links stay forbidden exactly as before, because
+the reader still cannot tell them apart.
+
+**`remote` keeps the caveat it always had.** It is listed so a reader off the
+network knows the surface exists and what turns it on — never as a door the wait
+is claimed to cover. Where it is on and published, its line says what is true of
+it: *a verdict here needs `/spec-reviewed`*.
+
+**Still forbidden**, in the words of the rule this amends: offering two links
+into **different** stores without saying which one the wait is watching. That is
+the failure that cost three unread verdicts, and nothing here touches it.
 
 **This is not the old failure returning**, and the difference is the whole
 justification. The offer used to be two quoted lines in the tail of a long
@@ -247,7 +394,7 @@ behind it — say nothing rather than reporting that there was nothing to report
 | `Landed` | A fast-forward, a tag, a cherry-pick. |
 | `Worktree` | A worktree provisioned, entered, or torn down. |
 | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
-| `Review` | The rendered diff page: files, `+`/`−`, the link. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
+| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
 | `Follow-ups` | **Always.** `none`, or one line each. |
 | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
 
@@ -311,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 |
 
@@ -341,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
 
@@ -357,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.