@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/assets/rules/commit-trailers.md

@@ -0,0 +1,96 @@
+# Commit Trailers
+
+Extends `commit-messages.md` — the format, length limits and `Release-Note:`
+grammar there all still apply. This file adds one trailer, and it is only
+installed when a ticketing provider is.
+
+## `Refs:` — the ticket this commit belongs to
+
+A commit carries the Jira issue **its own changes** belong to, as the **last**
+trailer in the message:
+
+```
+fix(sync): verify no longer flags every update
+
+- Key the apply read-back by ref, resolving id via the projection
+
+Release-Note: Pushing a spec whose phases already exist in Jira no
+longer reports every one of them as a possible stale reference.
+
+Refs: PROJ-29
+```
+
+Get the value from the engine rather than reading it off a spec by hand:
+
+```
+pnpm exec skitterspec-jira spec-sync ref
+```
+
+Bare, that answers **from the branch** — correct whenever you are committing
+that branch's own implementation work, which is nearly always.
+
+## When the branch and the commit disagree
+
+The branch is a proxy for "what this commit is about", and it is a good one
+right up until you commit something that is not this branch's work.
+
+**Where isolation is configured, `/spec` closes the usual way in.** It
+provisions the new spec's own `--docs` worktree before writing a line of it and
+moves the session there, so the spec commit happens on the new spec's branch —
+and the **bare** command is then correct, because the branch and the commit's
+subject are the same spec. This is the normal path, and it needs nothing typed.
+
+**Without isolation the split is still real.** Part-way through a spec a design
+question warrants its own spec, `/spec` writes it into `specs/backlog/` on the
+branch you are standing on, and that commit is **entirely the new spec's** while
+the bare command answers with the old spec's ticket.
+
+Name the spec instead — still the engine, never a hand-written id:
+
+```
+pnpm exec skitterspec-jira spec-sync ref feat-distance-prescriptions
+```
+
+The branch is not consulted, so this works from `main` too. An unknown spec name
+fails rather than falling back to the branch, so a typo can't become a
+confidently wrong ref.
+
+**A spec in ANOTHER spec's worktree is still the thing to avoid**, and the fix
+is no longer "author from the base branch" — it is the provision above, which
+moves the session out of that tree and into the new spec's own. What was always
+true of the accident stays true: a spec written inside another spec's worktree
+physically lives on that branch, so it is not on `main` until that spec lands,
+and it is cancelled along with it.
+
+## Rules
+
+- **The ref names the commit's subject, not your location.** If they disagree,
+  the commit's subject wins — resolve it with `spec-sync ref <spec>`.
+- **Omit the trailer entirely when there is no ref.** `spec-sync ref` exits
+  non-zero and prints nothing on a commit that has no ticket — on `main`, or on
+  a spec kept deliberately local. Never invent one, and never write
+  `Refs: none`: the release report counts unreferenced commits, and a fabricated
+  ref is worse than an honest gap.
+- **One ref per commit.** A commit belongs to one spec. If work genuinely spans
+  two tickets, that is two commits — and that is the fix when a single commit
+  would mix a branch's own work with another spec's files.
+- **Never use Jira's smart-commit commands** — `#comment`, `#time`,
+  `#<transition>` (`#done`, `#in-progress`, …). Those act on the issue the
+  moment the commit is scanned — posting comments, logging time, transitioning
+  the ticket — which is wrong here: a ticket moves when its work is
+  **released**, not when it merges. `Refs:` is deliberately inert to Jira's
+  automation.
+- **Blank line before it**, like `Release-Note:` — it is a git trailer, not body
+  text.
+- Put it **after** `Release-Note:` when both are present, so the human-facing
+  note reads first.
+
+## Why it exists
+
+The repo lands specs with `merge --ff-only`, so history is linear and branch
+names never reach it. The commit message is the only artefact that survives into
+the range a release scans, which is what lets
+`spec-sync released <range>` report the tickets a release contains. A ref that
+names the wrong ticket does not merely lose information — it moves a commit onto
+another ticket's release report, which is worse than the gap it was meant to
+close.

package/assets/rules/negative-checks.md

@@ -0,0 +1,69 @@
+# Checks That Accuse
+
+A check **accuses** when being wrong costs something: it deletes, it exits
+non-zero, or it tells the user their code is broken. Those checks earn the four
+rules below. An ordinary conditional does not — this is about the ones that act
+on what they conclude.
+
+Almost every accusation begins as an **absence**: a name not in a list, a
+directory not on disk, a version not in a response. An absence is evidence only
+once you have established that the lookup could have seen the thing. Three
+times in one day, in unrelated code, we established nothing and acted anyway:
+
+| Absence observed | Concluded | What had blinded the lookup |
+|------------------|-----------|-----------------------------|
+| ref not in the issue list | "it does not exist" | the query excluded archived issues, and capped at 250 |
+| version not in the registry's list | "the publish failed" | the registry is eventually consistent |
+| lifecycle folder not on disk | "half-installed" | git does not store an empty directory |
+
+The bills: 146 healthy refs accused, a valid release tag deleted, a non-zero
+exit on a healthy repo. Each blind spot was knowable in advance.
+
+## 1. Prefer a positive signal to an absence
+
+Assert something that must be **present**, not something that must not be
+missing. A positive signal fails loudly when you are wrong about it; an absence
+fails silently whenever the lookup was narrower than you assumed.
+
+The scaffold check above stopped asking "is the lifecycle folder there?" — a
+folder git drops as soon as it empties — and started asking whether the config
+folder the installer always writes into is there. Same intent, and the new
+question has an answer.
+
+Where no positive signal exists, widen the lookup until absence means
+something (include the archived rows, ask the API for the one id rather than
+scanning a page) — or do not conclude.
+
+## 2. Name the blind spot beside the check
+
+A comment naming what could make this lookup lie is what makes the next reader
+check it. Not what the code does — what would fool it:
+
+```js
+// A LIFECYCLE FOLDER IS NOT CHECKED, deliberately. git does not track empty
+// directories, so it disappears whenever the bucket empties and returns the
+// moment something lands in it.
+```
+
+Write it when you write the check, while you still know why it is safe.
+
+## 3. Pair every accusation with a stays-silent test
+
+For each accusing check, a test that feeds it a **healthy but unusual** input
+and asserts it says nothing: the empty bucket, the archived record, the
+just-published version, the file the user edited on purpose. The positive test
+proves the check can fire; only this one proves it does not fire at everyone
+else. All three incidents would have been caught by it, and prose alone had
+already failed to prevent them.
+
+## 4. Bias the unknown case toward inaction
+
+Three states, not two: yes, no, and *cannot tell*. Route the third to the
+harmless branch — skip, warn, keep, retry — never to the destructive one.
+
+The install manifest classifies a file whose hash it does not recognise as
+`customized` rather than stale, so a resync **keeps** it (`managedState`,
+`packages/common/src/init.js`). An unrecognised hash could mean a user's edit or
+a lost manifest; only one of those readings is safe to act on, so it takes that
+one. Being wrong there costs a redundant file on disk. The opposite default
+costs the user their work.

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.