@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,306 @@
+---
+name: spec-push
+description: Push a spec up to its linked Jira issue (repo → Jira, one-way). The repo is the source of truth and Jira a generated mirror, so content is never read back or merged. A spec is an issue and each phase a subtask. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-push", "push to Jira", "update the Jira issue from this spec".
+---
+
+# /spec-push — send a spec up to Jira (one-way)
+
+> 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.
+
+Repo → Jira. The repo is the **source of truth**; Jira is a
+**generated mirror**. A spec is a Jira **issue**; each phase is a **subtask**,
+and the phase file is mirrored into that subtask's description as written — its
+prose, its sections, and its tasks as a read-only checklist, never as issues of
+their own. Only the phase's h1 and `> **Status:**` line are left out, because
+both are pushed as fields of their own (the subtask's summary and status). This
+skill computes what changed since the last push and applies it — it never reads
+Jira content back or merges. A person editing the mirror in Jira will see it
+overwritten on the next push.
+
+**Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
+tell the user how to enable Jira sync and stop.
+
+## 1. Identify the target spec
+
+Use the argument, else the spec in context; ask if unclear.
+
+## 2. Pick the transport, and get the project's statuses
+
+**Ask the engine first — it decides, not you:**
+
+```
+skitterspec spec-sync states --json
+```
+
+With Jira credentials set (`JIRA_EMAIL` + `JIRA_API_TOKEN`, or whatever
+`auth.emailEnv`/`auth.tokenEnv` name) the engine talks to Jira Cloud directly.
+That is the **fast path**, and it is the default whenever credentials resolve:
+descriptions never pass through you, in either direction. Without them it falls
+back to MCP and everything below works as it always has.
+
+- **`transport = api`** → the command prints the project's status names as a
+  JSON array. Write it to a file and carry on to step 3.
+  **Skip the MCP tool discovery entirely** — you make no Jira calls here.
+- **`transport = mcp`** → do the MCP work: discover the issue
+  **read + create/update** tools at runtime on Atlassian's official remote MCP
+  server (mcp.atlassian.com) — `getJiraIssue`, `createJiraIssue`,
+  `editJiraIssue`, plus `transitionJiraIssue` for status moves. If Jira isn't
+  connected or a needed tool is missing, relay the fix and stop,
+  **writing nothing**. Then fetch the project's status **names** yourself and
+  write them to a file as a JSON array
+  (e.g. `["To Do","In Progress","Done"]`).
+
+Either way you end up with a states file. Step 3 requires it:
+`push` **refuses to run** without one, because a Jira status is reached by
+**workflow transition** — the engine resolves the transition to the mapped
+status and refuses loudly when none reaches it, and it never path-finds through
+intermediate statuses. A configured name the project lacks would therefore fail
+mid-apply, after the description already landed, so it is checked before
+anything is written. If the check reports a name that isn't in the project,
+stop and fix `specs/.core/jira.config.json`.
+
+**If the check refuses, offer to fix it.** The refusal lists every configured
+name the project lacks, the project's real status names, and — where the bucket
+makes it unambiguous — which one to use instead. Relay that, then offer to
+apply it to `specs/.core/jira.config.json` → `states`, and do so on the user's
+confirmation. Never edit their config without asking, and never guess a bucket
+the refusal made no suggestion for — ask which status they want.
+
+`--skip-state-check` exists for the deliberate exception; do not reach for it to
+get past a failing check.
+
+## 3. Get the plan from the engine
+
+```
+skitterspec spec-sync plan <spec> --workspace-states <file> --json
+```
+
+The engine prints a JSON **plan** (no network, no remote read):
+
+```json
+{
+  "issue": { "description": "…", "state": "in-progress" },
+  "subIssues": {
+    "create": [{ "ref": "01-outbox", "name": "Outbox", "goal": "…", "state": "backlog" }],
+    "update": [{ "id": "PROJ-2", "name": "…", "goal": "…", "state": "in-progress" }]
+  }
+}
+```
+
+An empty plan (no `issue`, no subtask create/update) means the mirror is up to
+date — say so and stop. The plan's `subIssues` key is where the subtasks live.
+`state` values are local buckets
+(`backlog`/`in-progress`/`complete`/`cancelled`); map each to the Jira STATUS
+name via `config.states` at apply time.
+
+A **`phasesDeferred`** field means `mapping.phases` is `"deferred"` and this spec
+has not started, so its phases are deliberately absent from the plan — the issue
+pushes alone and the subtasks are minted by the push that follows `/spec-start`.
+Relay the count; it is not a sign the phase files failed to parse. Nothing else
+about applying the plan changes.
+
+The plan always carries a **`phaseMode`** field — `subissue`, `deferred` or
+`inline` — the mode that resolved for THIS spec's lifecycle bucket.
+`mapping.phases` may be a per-bucket map, so the config alone no longer tells you
+which mode a given spec got. Relay it whenever it is not `subissue`:
+
+- **`inline`** — no subtasks are created at all. Each unlinked phase is a
+  section of the spec issue's own description, and the `## Phases` index stays as
+  its table of contents. A plan with no subtask creates is the expected shape,
+  not a parse failure. A phase that already carries an id keeps its subtask and
+  still appears under `subIssues` — apply those normally.
+- **`deferred`** — as above; the `phasesDeferred` count says how many are waiting.
+
+Nothing about how you apply the plan changes in either mode: apply exactly the
+`issue` and `subIssues` the plan lists.
+
+## 4. Apply the plan
+
+**On `transport = api`, this is one command:**
+
+```
+skitterspec spec-sync apply <spec> --plan plan.json
+```
+
+It creates and updates the issue and its subtasks, reads each description back
+and runs the same check as step 4b, stamps every returned key into the spec, and
+records the snapshot. **Steps 4a–5 below are then already done** — skip to step 6
+and report what it printed, including the transport.
+
+Two things it guarantees, so you don't have to manage them:
+
+- **It writes nothing until everything checkable has been checked** — a missing
+  key or a `config.states` name the project lacks fails before the first write.
+- **It stamps each key the moment its object exists.** If a run is interrupted,
+  re-run the same command: the objects it already created are linked, so the new
+  plan sees them as updates and no duplicate is minted. Never "start again" by
+  hand.
+
+If it prints **`transport = mcp`** it has written nothing and is telling you to
+apply the plan yourself — do steps 4a, 4b and 5 below. Pass `--via mcp` to force
+that deliberately.
+
+There is no project to pick, on either path: a minted issue lands in the
+configured `jira.projectKey` by construction.
+
+## 4a. Apply it yourself — the MCP path (order matters)
+
+**First, check whether you are about to overwrite someone.** On the API path
+`apply` does this for itself, off the read-back it already makes. On the MCP
+path nothing has read the issue yet, so ask before you write:
+
+```
+skitterspec spec-sync status <spec> --remote <issuefile>
+```
+
+using the same issue JSON step 2 fetched — it must carry the `description`. A
+`drift: … description was edited on Jira since the last push` line means a
+person wrote something there that step 1 below replaces.
+
+**It is a warning and never a gate.** The repo is the source of truth and the
+push still goes ahead; relay the line, name the issue, and carry on. What is
+forbidden is doing it *silently* — someone's paragraph disappearing with nothing
+said about it is the failure this exists to end. Nothing printed means nothing to
+say, which includes every case the engine could not tell.
+
+1. **Spec issue** → if the overview has no `jira_identifier`, this push
+   **mints** it: create it with `createJiraIssue` (`project` = `jira.projectKey`;
+   issue type = `jira.issueType`; summary from the spec title; description from
+   `plan.issue.description`), then move it with `transitionJiraIssue` to the
+   status `config.states` maps `plan.issue.state` to. Keep the returned key and
+   url for step 5 — don't hand-edit frontmatter. If it already exists and
+   `plan.issue` is present, **update it by key** with `editJiraIssue`, and
+   transition only when the status actually differs.
+2. **Subtasks create** → for each, `createJiraIssue` with `parent` = the spec
+   issue key and issue type = `jira.subtaskType` (`name` → summary, `goal` →
+   description), then transition to the mapped status. Keep each returned key
+   against its `ref` (the phase-file basename).
+3. **Subtasks update** → `editJiraIssue` by key (summary/description), plus
+   `transitionJiraIssue` where the status changed.
+
+Priority, labels, sprints and comments are Jira-native triage — do **not** push
+them; they're the PM's.
+
+## 4b. Verify what Jira actually stored — the MCP path
+
+*(On the API path `apply` already did this. Skip.)*
+
+Jira stores descriptions as **ADF** (Atlassian Document Format), not markdown:
+the adapter renders markdown to ADF on push and reduces what Jira holds back to
+text on read-back, so the comparison is **words rather than bytes**. Check
+before you record the push as good.
+
+For each issue you created or updated in step 4a, read its `description` back
+(`getJiraIssue`) and write what you got to a JSON file:
+
+```json
+{ "issue": "<stored description>", "subIssues": { "01-outbox": "<stored>" } }
+```
+
+Then:
+
+```
+skitterspec spec-sync verify <spec> --stored <file>
+```
+
+It compares against what the engine sent, ignoring the formatting that
+legitimately does not survive the ADF round-trip and reporting only lost or
+altered **word characters**. Relay any divergence — it prints both sides around
+the first difference. It exits 0 either way: the repo is unaffected and still
+correct, so this is a warning, not a failure.
+
+This is **not a pull**. Nothing read here is merged, stamped, or written
+anywhere; the repo remains the only source of truth. Do it before step 5 so a
+corrupted push is visible before the snapshot records it as good.
+
+## 5. Stamp the keys, then record the snapshot — the MCP path
+
+*(On the API path `apply` already did both. Skip.)*
+
+Write every key you collected back into the spec in **one** call — the engine
+does the file edits, so there is no hand-editing of frontmatter:
+
+```
+skitterspec spec-sync stamp <spec> \
+  --issue PROJ-11 --url https://your-site.atlassian.net/browse/PROJ-11 \
+  --sub 01-outbox=PROJ-12 --sub 02-api=PROJ-13
+```
+
+Pass `--issue`/`--url` only on the push that minted the spec issue; pass one
+`--sub <ref>=<key>` for every subtask **created** in step 4a.2 (updates already
+have their key). It validates every ref and key **before** writing anything and
+exits non-zero having changed nothing if any is wrong — so a typo can't leave the
+spec half-stamped, pointing at an issue that isn't there. Fix what it reports and
+re-run; it is safe to repeat.
+
+Then record what was pushed:
+
+```
+skitterspec spec-sync record <spec>
+```
+
+This writes the last-pushed snapshot from the now-stamped files, so the next
+`/spec-push` produces an empty plan. Commit the stamped spec + snapshot into the
+branch so the mirror-link rides in the PR.
+
+## 5b. A refused mint, and the way back
+
+Two refusals reach you from `apply`, and neither is a failure to retry.
+
+**`N already exists and no spec claims it`** — the push was about to mint, and
+an issue with **exactly** this title is sitting there unheld. That is almost
+always the spec's own issue, whose link was lost: a bad merge, a hand edit, a
+stray `sed` over the frontmatter. Adopt it rather than creating a twin. The
+Linear provider ships `reattach` for this; the Jira provider does not yet, so
+the fix is the manual escape hatch — read the issue key back to the user,
+confirm it is the spec's own issue, then:
+
+```
+skitterspec spec-sync stamp <spec> --issue <PROJ-N>
+```
+
+**`N exists in Jira but could not be recorded`** — the create landed and the
+stamp did not, so Jira holds an issue the repo does not point at.
+**Do not re-run**:
+the plan still reads the spec as unlinked, so a re-run mints a second.
+`stamp` with the key the refusal named is the fix here too.
+
+Everything else — a rate limit, a refusal that says waiting will not help — is
+reported with Jira's own explanation and whether retrying can help. Relay it;
+do not paraphrase.
+
+## 6. 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 mirror matches the repo and the snapshot is recorded.
+- `⚠️` — pushed, with something worth knowing: Jira stored different words, or
+  `phasesDeferred` phases not yet minted.
+- `❌` — it wrote some objects and failed on another. Name what exists in Jira
+  now; `apply` stamps each key as it goes, so the re-run is an update, never a
+  duplicate.
+- `⏸` — no config, no `jira_identifier`, or an unvalidated status list. Nothing
+  was written.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` carries what was created and updated — the spec issue and its
+subtasks — **the transport that did it**, and that the snapshot was recorded.
+
+**Say the transport, every time.** On the API path you never saw the
+descriptions, so "pushed 12 subtasks" is the engine's report rather than your
+observation, and that distinction is the difference between a fact and a
+paraphrase. If it warned that Jira stored different words, relay it: the repo
+is still correct and a re-push overwrites the mirror.
+
+There is no pull — Jira is a generated mirror.
+
+Jira has no project picker: a minted issue lands in the configured
+`jira.projectKey` by construction, decided once in `specs/.core/jira.config.json`.
+There is nothing to ask.

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

@@ -0,0 +1,256 @@
+---
+name: spec-review
+description: Re-validate an existing spec against the current codebase — detect drift (renamed/removed files, changed APIs, tasks already done in code, stale decisions), grill where a decision is needed, and update the spec so it's relevant again. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-review", "is this spec still accurate", "this spec has gone stale", or before picking up an old backlog spec.
+---
+
+# /spec-review — bring a spec back in sync with the codebase
+
+> 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.
+
+Specs rot: the code moves on while a spec sits in the backlog or pauses
+mid-build. This skill re-validates a spec against the **current** code and
+rewrites the stale parts so it's safe to act on. It plans only — it does not
+implement anything (that's `/spec-next`).
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate the spec folder under `specs/` (any bucket). Entry point is its
+  `00-overview.md`; read it **and every phase file** (`01-<slug>.md`, `02-…`)
+  listed in its phase index (legacy specs may be a bare `<name>.md`).
+
+## 2. Validate against the codebase — evidence first
+
+Read the spec, then check every claim it makes against the real code. Don't
+trust the spec's own wording — verify:
+
+- **Referenced things still exist.** Grep/read for each `file:line`, module,
+  function, route, model, type, or symbol the spec names. Flag anything renamed,
+  moved, or deleted.
+- **Impact map matches reality.** Walk every row of the `## Impact` table and
+  verify against the code: does the named surface (endpoint, schema/model, DB
+  table/migration, domain object, route, business rule) exist, and does its
+  stated `Change` (add/update/remove) still hold? A stale Impact map is the
+  highest-signal drift — each row is a named, checkable surface, so a wrong row
+  is exactly the "obvious mistake" the map exists to surface. Flag/refresh stale
+  rows (and add rows for surfaces the spec now touches but omits).
+- **Tasks already done.** For each `- [ ]`, check whether the code already
+  implements it (it may have landed via other work). Tick `- [x]` what's done.
+- **Decisions still valid.** Re-check each `## Decisions` entry against the
+  current architecture and `.claude/rules/*.md`. Flag any that now conflict with
+  how the codebase actually works (a changed convention, a superseded approach).
+- **New constraints.** Note rules/patterns introduced since the spec was written
+  that it must now honour (e.g. a new required field, a new error type, a new
+  pattern the rest of the code now follows).
+- **Backward compatibility.** Re-confirm the planned API/schema changes are still
+  additive/safe given the current code (see the project's compatibility rules).
+
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>`. A spec it names has no recorded gating
+decision — or a bare `none` that records nothing — and that is
+**drift like any other**: the question was never asked, or its answer was lost. Grill for it in
+step 3 and write the header in step 4, exactly as you would a stale file path.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
+## 3. Grill only where a decision is needed
+
+Where the drift forces a choice (the old approach no longer fits, a referenced
+thing is gone, scope is now ambiguous), grill the user like `/spec` Phase A —
+**batching independent questions, each with a recommended answer** — but scoped
+tightly to the drift. Don't re-litigate decisions that still hold. If you can
+resolve it by reading the code, do that instead of asking.
+
+## 4. Update the spec
+
+- Rewrite stale **Decisions** / **Solution overview** and refresh the
+  **Impact map** in `00-overview.md`, and stale **tasks** in the phase files,
+  so they match the current code and the resolved questions. Add/remove tasks
+  within a phase file; add a new phase by creating a `0N-<slug>.md` file
+  **and** a matching overview index row, or drop a dead phase by removing both.
+  Keep the index and files in sync; **preserve completed `[x]` history**.
+- **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
+  It is mirrored in that file's `> **Status:**` line and in the matching
+  `00-overview.md` phase-index row, but the **heading is the authoritative one**:
+  tooling reads it, and a heading carrying no emoji reads as *not started*. So a
+  finished phase marked only by a `**Status:** done` line is silently wrong
+  everywhere except the file itself. Set all three together.
+- **Especially when you create phase files.** Migrating a legacy spec (a bare
+  `<name>.md`, or a `00-overview.md` with inline phases) into the folder +
+  phase-file form means authoring `0N-<slug>.md` headings from scratch — carry
+  each phase's real status onto its H1 as you split it out, rather than
+  defaulting every new file to `⬜`. A ticketing provider projects that emoji as
+  the phase's state in the tracker, so getting it wrong mirrors a
+  complete phase as not-started.
+- Tick tasks already satisfied by the code; re-open `## Open questions` for
+  anything still undecided.
+- Add a dated **Changelog** entry summarising the review (e.g. `- <date> —
+  Reviewed vs codebase: retargeted Phase 2 onto X, dropped Y (removed), ticked Z
+  (already done)`).
+- **Status:** if drift is minor, leave status as-is. If a `Ready` spec needs real
+  re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
+  **State log** row).
+
+**Only when `specs/.core/jira.config.json` exists** and the spec's overview
+carries a `jira_identifier`. Either missing → **skip**, in one line
+(`not linked to Jira — /spec-push to mirror it`), and carry on. Nothing else in
+this step changes.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this spec's state, and the tracker is a generated mirror
+of it — leaving them to diverge until someone remembers to push by hand is the
+gap this exists to close. It costs one engine call and no model tokens when
+Jira credentials are set (see `apply.transport` in `jira.config.md`).
+
+- **Never mint.** An unlinked spec is skipped, not created. An issue born `Done`
+  is tracker noise, and a spec kept deliberately local should stay that way —
+  `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no credentials, a Jira error —
+  say so and **finish the operation anyway**. The spec is
+  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
+  and the next push repairs it. Do not roll anything back, and do not stop to
+  ask.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+- **There is no assignment to release here.** Assignment sync is not yet
+  supported by the Jira provider; the `> **Developer:**` header stays put as the
+  repo's own record of who actioned the work.
+
+### Why it sits here
+
+In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
+**after the `git mv` and before the commit**, and both halves matter:
+
+- **After the move**, because the projection reads a spec's workflow status from
+  its folder bucket. Push while the folder is still in `in-progress/` and the
+  issue is set to the status the spec is *leaving*.
+- **Before the commit**, because the push stamps keys into the spec and writes a
+  snapshot under `specs/.core/`. Push after the commit instead and both are left
+  uncommitted, which makes `spec-env integrate` refuse to land the branch.
+
+The snapshot is reached **by name**, not by breadth. It is a declared
+`spec.companionPaths` entry (`specs/.core/jira-base/{identifier}.base.json`),
+so `spec-env stage` returns it among this spec's owned paths and the commit below
+names it. This is why the commit no longer stages `specs/` wholesale: the one
+file outside the spec's folder that had to be swept up is addressable, so the
+breadth bought nothing and cost another session's work.
+
+## 4b. Hand the refresh back on a page, then wait
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present) **and this review actually changed something.** Either missing → skip
+the whole step in silence.
+
+A refreshed spec is a rewrite of a document someone is about to work from, so it
+gets read before it is committed — the same ending `/spec` now has:
+
+```
+skitterspec spec-env review <spec> --docs --buttons refresh
+```
+
+`--docs` reads the spec's own documents from the tree you are standing in, so it
+wants no worktree and works for a spec in any bucket. These documents are
+**tracked**, so the diff against `HEAD` is a patch rather than a set of new
+files — which is exactly what the reader wants here: what drifted, and what you
+rewrote.
+
+**Render nothing when nothing changed.** `/spec-review` frequently concludes a
+spec is still accurate, and that is a success rather than a gap. A page showing
+an empty diff under a commit button asks for a verdict on nothing, and the
+engine refuses it for the same reason — `nothing to review`. Take that refusal
+as the answer and report the `⏸`/`✅` you already had.
+
+**Arm nothing.** No `review arm` here: the gate asserts that a phase which ended
+owes an answer, and a re-validated spec has ended no phase. Walking away leaves
+an uncommitted spec, which is the state this skill has always finished in.
+
+### The three endings
+
+`--buttons refresh` offers `Commit`, `Request changes` and `Discuss`.
+
+**No start verdict, deliberately.** The spec this skill refreshed may already be
+in progress — that is half of what it is used for — so `Commit & Start` would
+offer to provision a worktree for a spec that already has one.
+
+- **`commit`** — hand off to `review.commitWith` (`/commit` by default) with the
+  pathspec the render reported on `docs.paths`, then finish. The spec keeps
+  whatever status step 4 left it in.
+- **`changes`** — work the notes into the spec, record a resolution for each so
+  the next render strikes it through with what changed, re-render, and wait
+  again.
+- **`discuss`** — report and talk. Claim nothing, change nothing.
+
+### Then wait for it
+
+**The wait is a command. Do not write one.** Note the moment you start waiting
+as an ISO timestamp, run the engine's wait in the background, and end your turn:
+
+```
+skitterspec spec-env review wait <spec> --since <the timestamp>
+```
+
+Pass no timeout. On waking, let the engine pick the pass —
+`skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json`
+— and route on the verdict above.
+
+**Where the page is `file://`** the pass is copied and pasted, so the wait is the
+turn ending and the banner says so. Do not start a watch that cannot fire.
+
+## 5. Report
+
+Do **not** `git commit` unless the user asks.
+
+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**
+
+- `✅` — checked against the code and brought up to date; safe to `/spec-start`.
+- `⚠️` — updated, but dropped back to `Draft`: questions are open that only the
+  operator can answer. Name them.
+- `⏸` — no such spec, or nothing to review. Nothing changed.
+
+**Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
+
+`Built` is the drift found and what you changed about it — a renamed file, an
+API that moved, a task the code already does. `Spec` carries the status the
+review leaves it in, which is the answer to "can I start this?".
+
+**Where step 4b rendered a page the run is waiting**, so the block omits the
+`Review` row and ends on the banner from `.claude/rules/spec-reports.md` — the
+tier stack copied from the engine's own lines, never one link chosen for the
+reader:
+
+---
+
+## ⏸ 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` commits the refresh · `Request changes` works them now
+
+---
+
+`Next` then names the page rather than a command, because the button is what
+carries the work on.
+
+Where nothing was rendered — no isolation, or no drift to show — `Next` is
+`/commit, then /spec-start <name>`, since this skill does not commit and
+`/spec-start` refuses a tree holding anything that is not the spec's.
+
+**Drift found and not fixed is a `Follow-up`, not a silence.** A spec this skill
+declared reviewed is one nobody will re-read; something it noticed and left
+undone has to leave the session in writing or it did not happen.