@skitterbyte/skitterspec 21.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

@@ -1,15 +1,16 @@
 # Spec Planning
 
 Spec-driven development is driven by ten lifecycle skills (plus the
-`/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
+`/spec-connect`, `/spec-live` and `/spec-remote-review` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
 
 | 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) |
@@ -20,13 +21,24 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
 **Skills vs commands.** The table above lists **skills** — Claude reads them and
-exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
+exercises judgment. `/spec-connect`, `/spec-live` and `/spec-remote-review` are
+instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
 finding one. They are marked `disable-model-invocation`, meaning
 **only you can run them** — a skill that wants one will tell you to type it
 rather than invoking it.
 
+**`/spec-remote-review`** is the newest and the smallest: it toggles
+`review.allowRemote`, and takes `on`/`off` when you would rather say which.
+It exists because a render's `remote:` line has to name something a person can
+act on, and `skitterspec spec-env review allow remote` is not what anyone
+reconstructs from a page they are reading on a phone. Making the line
+*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 **permits** publishing; it publishes
+nothing.
+
 `/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
 convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
 review pass is never claimed unasked. Because the model cannot invoke this
@@ -41,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
@@ -87,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
@@ -118,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
@@ -133,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
@@ -226,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
@@ -300,8 +454,8 @@ 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 |
-| **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) |
 
@@ -333,6 +487,27 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
 workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
 the tracker is never read back or merged.
 
+**One-way means the repo wins, and it now wins *loudly*.** Those are different
+claims and only the first was ever in doubt. A ticket's description is generated
+from the spec, so a person editing it there is writing something the next push
+replaces — which is correct, and which used to happen in silence. The engine now
+compares a hash of what the tracker holds against a hash of what the repo last
+sent, and says *that* it changed and where to read it.
+It **reports and never refuses**: only a person can tell a typo fix from a
+paragraph worth keeping.
+
+**This is still not a pull.** Nothing read is merged, written to a spec, or fed
+into the projection, and the text never enters the conversation — the comparison
+is hashes, and the output is one line for a human. It is the same thing
+`compareStored` has always done for a different question.
+
+**And adoption no longer costs the reporter their words.** When a provider
+adopts an existing ticket — one a PM or colleague filed — the linking push
+replaces its description with the spec. Before that happens the original is
+posted back onto the ticket as a **comment**: a surface one-way sync never
+touches, so no later push can clobber it. Where a provider supports it, this is
+automatic and has an opt-out. See the provider's own docs.
+
 A provider may also ship a **read-only listing** of what the tracker holds. That
 is not a pull: nothing is merged back and no spec file is written. It exists
 because the folder buckets are only the truth *on the branch you are standing
@@ -381,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.