@skitterbyte/skitterspec-jira 1.0.0 → 2.0.0

package/MIGRATION.md

@@ -1,5 +1,104 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
+
+Skitterspec now tells GitHub about **its own** transitions and nothing
+else. It writes nothing about releases or deployments, and it never reads a
+ticket's state back.
+
+### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
+
+They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
+still calling them goes red rather than silently believing it mirrors
+anything. **To migrate**, replace the step with your own script over the
+release's ticket list:
+
+```sh
+skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
+```
+
+Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
+linked), so the script needs no second lookup. Set whatever GitHub field,
+state or release object your process uses from that list. The checkout needs
+`fetch-depth: 0` so the previous tag is visible.
+
+### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
+
+The keys are ignored, like any unknown key, so a config carrying them still
+loads. `spec-sync doctor` names them as unused config (a `warn`, never a
+failure). Delete them when you remove the CI step.
+
+### Breaking change 3 — no state drift
+
+`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
+state with the spec's. A ticket someone moved on GitHub is not reported, and
+push still resends state only when the spec itself moves. The edited-description
+warning is unchanged.
+
+## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
+
+Skitterspec now tells Azure Boards about **its own** transitions and nothing
+else. It writes nothing about releases or deployments, and it never reads a
+ticket's state back.
+
+### Breaking change 1 — The `release create|deployed|complete` verbs are removed
+
+They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
+still calling them goes red rather than silently believing it mirrors
+anything. **To migrate**, replace the step with your own script over the
+release's ticket list:
+
+```sh
+skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
+```
+
+Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
+linked), so the script needs no second lookup. Set whatever Azure Boards field,
+state or release object your process uses from that list. The checkout needs
+`fetch-depth: 0` so the previous tag is visible.
+
+### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
+
+The keys are ignored, like any unknown key, so a config carrying them still
+loads. `spec-sync doctor` names them as unused config (a `warn`, never a
+failure). Delete them when you remove the CI step.
+
+### Breaking change 3 — no state drift
+
+`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
+state with the spec's. A ticket someone moved on Azure Boards is not reported, and
+push still resends state only when the spec itself moves. The edited-description
+warning is unchanged.
+
+## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
+
+Skitterspec now tells Jira about **its own** transitions and nothing else. It
+writes nothing about releases or deployments, and it never reads an issue's
+status back.
+
+### Breaking change 1 — no status drift
+
+`spec-sync status --remote` and `/spec-status` no longer compare Jira's status
+with the spec's. An issue someone moved on Jira is not reported, and push still
+transitions it only when the spec itself moves. The edited-description warning
+is unchanged.
+
+### Breaking change 2 — `release.stages` retired
+
+It was accepted and validated before, and never acted on. It is now ignored
+like any unknown key, and `spec-sync doctor` names it as unused config (a
+`warn`, never a failure). Delete it.
+
+### Also — `released --json` names the spec
+
+Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
+linked), so CI can record a release, for example as a fix version, without a
+second lookup:
+
+```sh
+skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
+```
+
 ## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
 
 ### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
@@ -100,6 +199,43 @@ Nothing in `env.config.json` changes.
 **If you added a secrets-hook exception for the printed seed commands**, you
 can remove it now. Nothing shipped prints them any more.
 
+## `@skitterbyte/skitterspec-azure-boards` v0 → v1 (first release)
+
+Nothing to migrate: this is the distribution's first release. It is a superset
+of `@skitterbyte/skitterspec` — install exactly one of the base or one
+superset. Coming from the base, run `npx @skitterbyte/skitterspec-azure-boards
+update` and run `/spec-azure-setup`
+(or `skitterspec-azure-boards spec-sync init-config --org-url … --project …`).
+
+**Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
+trackers: swap the distribution, configure Azure as above, set
+`refs.foreignPatterns` to the old team key (e.g. `"ERQ-\\d+"`), then push each
+backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
+in-progress` and `--all backlog`) to link it to a new work item. Finished specs
+keep their old stamps (`linear_identifier`, …) as history; nothing rewrites
+them. Old `Refs: ERQ-12` trailers stay in the log, and `spec-sync released`
+counts them as `historical` rather than as missing a ref. New commits carry
+`Refs: AB#n`. Delete the old `linear.config.json` / `jira.config.json` once the
+open specs are linked.
+
+## `@skitterbyte/skitterspec-github` v0 → v1 (first release)
+
+Nothing to migrate: this is the distribution's first release. It is a superset
+of `@skitterbyte/skitterspec` — install exactly one of the base or one
+superset. Coming from the base, run `npx @skitterbyte/skitterspec-github
+update`, make a Projects v2 board for the repo, and run `/spec-github-setup`
+(or `skitterspec-github spec-sync init-config --owner … --repo … --project N`).
+
+**Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
+trackers: swap the distribution, configure GitHub as above, then push each
+backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
+in-progress` and `--all backlog`) to link it to a new issue. Finished specs keep
+their old stamps (`linear_identifier`, …) as history; nothing rewrites them.
+Old `Refs: SKS-12` trailers stay in the log, and `spec-sync released` counts
+them as `historical` rather than as missing a ref. New commits carry
+`Refs: #N`. Delete the old `linear.config.json` / `jira.config.json` once the
+open specs are linked.
+
 ## `@skitterbyte/skitterspec-jira` v0 → v1 (first release)
 
 Nothing to migrate: this is the distribution's first release. It is a superset
@@ -238,7 +374,48 @@ can run it.
 committed file, so it changes for everyone who pulls and leaves that tree dirty.
 The engine says so when it does.
 
-## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
+## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
+
+Skitterspec now tells Linear about **its own** transitions and nothing
+else. It writes nothing about releases or deployments, and it never reads a
+ticket's state back.
+
+### Breaking change 1 — The `spec-sync stage` verb is removed
+
+It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
+still calling it goes red rather than silently believing it mirrors
+anything. **To migrate**, replace the step with your own script over the
+release's ticket list:
+
+```sh
+skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
+```
+
+Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
+linked), so the script needs no second lookup. Set whatever Linear field,
+state or release object your process uses from that list. The checkout needs
+`fetch-depth: 0` so the previous tag is visible.
+
+### Breaking change 2 — `release.stages` (the deployment ladder) is retired
+
+The keys are ignored, like any unknown key, so a config carrying them still
+loads. `spec-sync doctor` names them as unused config (a `warn`, never a
+failure). Delete them when you remove the CI step.
+
+### Breaking change 3 — no state drift
+
+`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
+state with the spec's. A ticket someone moved on Linear is not reported, and
+push still resends state only when the spec itself moves. The edited-description
+warning is unchanged.
+
+**A ladder rung no longer reads as `complete`.** Where a state was a
+`release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
+keep it reading as finished, list it as an alias:
+`"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
+refused as an unknown flag.
+
+### Also — hotfix land runs the release itself
 
 The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
 distribution composes the same engine. Read that entry; nothing here is

package/README.md

@@ -37,7 +37,9 @@ skitterspec-jira spec-sync credentials set
 every layer.
 
 Not yet shipped for Jira (the Linear superset has them): assignment/`/spec-claim`,
-the release-stage ladder, `retarget`, `reattach`, `spec-sanitise`.
+`retarget`, `reattach`, `spec-sanitise`. Releases and deploys are the host
+project's to record on every provider: `spec-sync released <range> --json`
+lists a range's tickets for its CI to act on.
 
 This package's `bin/`, `src/` and `assets/` are composed at build time from the
 skitterspec monorepo — see the repo for sources and development.

package/assets/core/SETUP.md

@@ -114,7 +114,7 @@ every configured status exists in the project's workflows.
 `/spec-push <spec>` computes the plan, applies it, stamps the returned keys
 into the spec's frontmatter (`jira_identifier` / `jira_url` /
 `jira_issue_id`), verifies the round-trip by words, and records the snapshot
-later drift is measured against. From then on the lifecycle skills keep the
+later pushes diff against. From then on the lifecycle skills keep the
 mirror fresh on their own.
 
 ---

package/assets/core/env.config.md

@@ -143,6 +143,10 @@ through to a documented conservative default; see the field notes below.
   // exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
   // expand (the cwd is already the worktree, so {worktreePath} is usually
   // redundant). Example: ["pnpm install --frozen-lockfile"].
+  // An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
+  // IGNORED here — a fresh worktree always runs every setup step — and exists
+  // so `afterLand` can re-run that step after a land that changes its inputs
+  // (`{ "setup": true }`, below).
   "setup": [],
 
   // Commands to run in the PRIMARY checkout after a land — the counterpart of
@@ -160,6 +164,51 @@ through to a documented conservative default; see the field notes below.
   // failure, report it as a caveat, and never undo the land or block
   // teardown. Literal strings — tokens are NOT expanded, because they run on
   // the base branch where a spec's {slug} or {portOffset} mean nothing.
+  //
+  // CONDITIONAL ENTRIES. A plain string always runs. An entry may instead be
+  // { "run": "<cmd>", "when": ["<glob>", ...] } (a single string `when` is
+  // fine), which runs only when the land changes a file one of its globs
+  // matches — so a generate or an install costs nothing on a land that does
+  // not need it, and is not forgotten on one that does:
+  //
+  //   "afterLand": [
+  //     { "run": "pnpm install --frozen-lockfile", "when": ["pnpm-lock.yaml", "**/package.json"] },
+  //     { "run": "pnpm run db:generate", "when": ["prisma/schema.prisma"] },
+  //     "pnpm db:data-migration"
+  //   ]
+  //
+  // Globs are repo-relative: `*` stays within a directory, `**` crosses them
+  // (`**/package.json` matches the root one too), `?` is one character. An
+  // entry whose `when` holds no usable glob is DROPPED, never widened to
+  // always-run.
+  //   The changed files are what the land brings into the base branch:
+  //   `base...branch` for `integrate` (read before the rebase, so it is the
+  //   branch's own changes), and the carried fix commits — minus the release's
+  //   version commit — for `hotfix land`.
+  //   When that cannot be known, the conditional entries RUN. That is the
+  //   "already landed" plan (the land happened elsewhere, so its range is not
+  //   here) and any diff git would not answer. A redundant generate costs
+  //   seconds; a skipped one leaves the base red with nothing pointing at why.
+  //   A land that changed no files is known, not unknown, and skips them.
+  // The plan says why for every entry: a matched one ends in
+  // `# <path> changed`, an unknown one in `# range unknown` with a line saying
+  // so, and the rest are listed under `skipped (nothing in the land matched):`
+  // with their globs. The reason is a shell comment, so a line run as printed
+  // stays one command. Skipped lines are information — run only the list
+  // under `then, … run`.
+  //
+  // REUSING A SETUP STEP. `{ "setup": true }` expands, in place, to every
+  // `setup` entry that declares `when`, so the trigger lives in one list:
+  //
+  //   "setup": [
+  //     { "run": "pnpm install --frozen-lockfile", "when": ["pnpm-lock.yaml", "**/package.json"] },
+  //     { "run": "pnpm run db:generate", "when": ["prisma/schema.prisma"] }
+  //   ],
+  //   "afterLand": [{ "setup": true }, "pnpm db:data-migration"]
+  //
+  // Plain setup strings carry no trigger and are never pulled in. The command
+  // is copied literally — afterLand expands no tokens — so a setup step that
+  // relies on {slug}-style tokens is a poor one to reuse.
   "afterLand": [],
 
   // Host dev servers `spec-env dev up <spec>` starts on the spec's port block
@@ -292,8 +341,11 @@ through to a documented conservative default; see the field notes below.
   // one. Empty (the default) = the built-in tagger.
   //
   // `bump` is the built-in tagger's strategy: "patch" (v33.16.4 -> v33.16.5) or
-  // "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...; a base
-  // that is already a hotfix tag continues its line). Any other value is refused
+  // "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...). Under
+  // either, a base that is already a hotfix tag continues its line
+  // (v36.2.3-hotfix.4 -> v36.2.3-hotfix.5), so "patch" never takes a number the
+  // mainline owns. When the patch tag already exists, the refusal names the
+  // free hotfix tag that "hotfix-suffix" would cut. Any other value is refused
   // when `hotfix land` runs. Tags order X.Y.Z-rc.N < X.Y.Z < X.Y.Z-hotfix.N <
   // X.Y.(Z+1), the same as skittership.
   //

package/assets/core/jira.config.md

@@ -16,7 +16,7 @@ NAMES — never a credential. Credentials live in the user-level store
 | `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
 | `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
 | `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
-| `release.stages` / `release.ignorePaths` | The deployment ladder and bookkeeping path prefixes, exactly as the Linear provider defines them. | `[]` / `specs/`, changelogs |
+| `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
 
 Descriptions are stored as ADF (Atlassian Document Format): the adapter
 renders markdown to ADF on push and reduces ADF back to text on read-back, so
@@ -24,6 +24,31 @@ verification compares words, not bytes. Phase checklists render as live ADF
 task lists — still a read-only mirror: a box ticked in Jira is overwritten on
 the next push.
 
+## More than one name per bucket — read-only aliases
+
+A board usually has more states than the four buckets: "Blocked", "Next
+Sprint", "Released". A bucket's value may be an **array** instead of a string:
+
+```jsonc
+"states": {
+  "in-progress": ["Active", "Blocked"],
+  "complete": ["Closed", "Released"]
+}
+```
+
+- **The first name is the only one push writes**, and only when the spec
+  itself moves. The rest are never written.
+- **The rest are read as that bucket** wherever a listing interprets a status.
+  The array is parsed and validated like every other provider's, so one config
+  shape works across all of them. `spec-sync status` never reads a ticket's
+  status at all: skitterspec tells Jira about its own transitions and nothing
+  else.
+- **Nothing is pulled.** An alias changes what the report *says* about a
+  ticket, never the spec.
+- A plain string works exactly as before. An alias that also names another
+  bucket is refused at load. An alias the tracker lacks is reported by
+  `spec-sync states` but never blocks a push, because it is never written.
+
 ## Choosing your status map
 
 Map the four buckets to **work** statuses, never to deployment stages. The
@@ -44,8 +69,9 @@ the map honest:
   type keeps the pipeline — subtasks genuinely have no delivery lifecycle, and
   Jira lets you say so structurally.
 - **Track "which release contains this" with fix versions** — the Releases
-  hub, the analogue of what `spec-sync released` computes from `Refs:`
-  trailers. (Available on every plan; in the current "Spaces" UI it is not a
+  hub. Your CI can fill it from `spec-sync released "<prev>..<tag>" --json`,
+  which lists the tickets a range contains from their `Refs:` trailers, each
+  with its spec and url. (Available on every plan; in the current "Spaces" UI it is not a
   Features toggle but a **tab** — add it with `+` in the space's tab bar.)
 - **Let CI/CD integrations stamp environment position** (the deployments
   panel), so it never needs to be a status at all.
@@ -56,6 +82,7 @@ status's board category, the closest match when one is missing, and the
 one-line remap. Run it whenever the wiring feels uncertain; it changes
 nothing.
 
-Walking the parent through pipeline stages at *release* time is the
-`release.stages` ladder — deferred in this provider's v1 — not a job for the
-lifecycle skills.
+Walking the parent through pipeline stages at *release* time is the host
+project's job, not skitterspec's: it writes nothing about releases or
+deployments on any provider. A leftover `release.stages` is flagged by
+`spec-sync doctor` as unused config.

package/assets/hooks/main-guard.cjs

@@ -85,7 +85,7 @@ function findEngine(projectDir) {
   if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
   let at = projectDir
   for (let i = 0; i < 6 && at; i++) {
-    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
+    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
       const candidate = path.join(at, 'node_modules', '.bin', name)
       if (fs.existsSync(candidate)) return candidate
     }

package/assets/hooks/review-gate.cjs

@@ -82,7 +82,7 @@ function findEngine(projectDir) {
   if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
   let at = projectDir
   for (let i = 0; i < 6 && at; i++) {
-    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
+    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
       const candidate = path.join(at, 'node_modules', '.bin', name)
       if (fs.existsSync(candidate)) return candidate
     }

package/assets/rules/spec-planning.md

@@ -492,9 +492,19 @@ missing alias.
 Sync is **one-way**: the repo is the source of truth and the tracker is a
 **generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
 against a committed last-pushed snapshot and applies it) and `/spec-status`
-(read-only drift report — what would push, and whether the tracker's
-workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
-the tracker is never read back or merged.
+(read-only — what would push, and whether someone edited a description there),
+backed by a `spec-sync` CLI. There is no content pull — the tracker is never
+read back or merged.
+
+**It tells, it doesn't track.** Skitterspec sends the tracker its own
+transitions — a spec starting, a phase finishing, a spec completing or being
+cancelled — and nothing else. A status someone changes on the tracker is
+theirs to have changed: it is never read back, never reported, and only
+overwritten when the spec itself next moves. Releases and deployments are the
+host project's to record. The one release question skitterspec answers is which
+tickets a commit range contains (`spec-sync released <range> --json`, each row
+with its spec and url), because only the `Refs:` trailers know. What the
+project's CI does with that list is its own business.
 
 **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

package/assets/rules/spec-reports.md

@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
 | **Branch** | `spec/feat-foo` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **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 |
+| **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/…) also [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 
@@ -89,6 +89,7 @@ the options may be offered after the table.
 
 - **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)
+  - also — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
 - **remote** — off · `/spec-remote-review` turns it on
 
 live: off — /spec-live to put it live
@@ -156,6 +157,17 @@ 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.
 
+**The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
+The engine offers the other addresses this machine has (a
+tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
+labelled; `--json` carries them as that tier's `alternates`, labelled the same
+way. Copy them as indented sub-bullets under the network bullet, verbatim,
+labels included. This is not an amendment to the tier rule: the stack is the
+engine's, copied rather than composed, and the engine was already printing
+these — a contract that made the skill edit them out was the composing this
+section forbids. A machine with no alternates renders the banner exactly as
+above, minus the sub-bullet.
+
 **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:
@@ -298,8 +310,11 @@ behind, and they cannot.
 `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.
+same run. A `network` alternate — the `also:` tailnet address — is one more
+door into the same room: the same server answers on it, so the wait-coverage
+line stays true with nothing added to it. Between all of those the objection
+does not apply — which is why they 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
@@ -410,7 +425,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, `+`/`−`, 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. |
+| `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, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), 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. |
 

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

@@ -174,7 +174,10 @@ three, in that order — never the bare `page:` path.
   **Between the two, run the after-land commands.** Where the `integrate` plan
   ends with a `then, in the primary checkout (<path>), run:` section — the
   project's `afterLand` — run those commands there, in order, once the
-  fast-forward has succeeded, and on an already-landed no-op too. A lockfile
+  fast-forward has succeeded, and on an already-landed no-op too. Run only the
+  lines under that heading; a `skipped (nothing in the land matched):` block
+  lists conditional entries this land did not need, and is information, never
+  commands. A lockfile
   refresh is exactly the land that needs them.
   **Stop at the first non-zero exit**: the run becomes `⚠️`, naming the command that failed and the ones that
   did not run, and it **never undoes the land and never stops the `down`**.
@@ -205,8 +208,8 @@ the shape; this section carries only what is specific here.
 
 - `✅` — the work is done, the tests are green, and the verdict was acted on.
 - `⚠️` — done and green, with something worth knowing — an after-land command
-  that failed, for one. `Notes` carries what the after-land commands ran, or
-  where they stopped; nothing about them when none are configured.
+  that failed, for one. `Notes` carries what the after-land commands ran and
+  skipped, or where they stopped; nothing about them when none are configured.
 - `❌` — 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

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

@@ -527,7 +527,9 @@ underneath a reader when detection flipped mid-session.
 
 So: **relay all three tier lines, every time.** Any `also:` lines sit under
 `network` — the other addresses this machine has, offered because the
-best-guess one can be wrong — so pass them on rather than editing them out.
+best-guess one can be wrong — so pass them on rather than editing them out: in
+the banner they are indented sub-bullets under **network**, labels
+(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
 
 **Never read an environment variable to decide anything about the offer** — not
 `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left

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

@@ -169,8 +169,8 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Spec` · `Tests` · `Notes` · `Landed` · `Worktree` ·
 `Follow-ups` · `Next`
 
-`Notes` carries the after-land commands step 6 ran, and where — or, on a
-failure, the command that failed and the ones that did not run. A project with
+`Notes` carries the after-land commands step 6 ran, and where, and any it
+skipped because the land matched no `when` — or, on a failure, the command that failed and the ones that did not run. A project with
 no `afterLand` says nothing about it.
 
 **Report this spec and no other.** A completion is the moment it is most
@@ -287,7 +287,10 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
 3. **Run the after-land commands.** Where the plan ends with a
    `then, in the primary checkout (<path>), run:` section — the project's
    `afterLand`, such as a data migration — run those commands in that
-   directory, in order, after the fast-forward succeeds. **Also on the no-op**:
+   directory, in order, after the fast-forward succeeds. Run only the lines under that
+   heading; a `skipped (nothing in the land matched):` block lists conditional
+   entries this land did not need, and is information, never commands.
+   **Also on the no-op**:
    the engine prints them there deliberately, because a land made on another
    machine leaves them pending here. **Stop at the first non-zero exit** — a
    later command may depend on it — and carry on with the rest of the skill:

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

@@ -538,7 +538,9 @@ underneath a reader when detection flipped mid-session.
 
 So: **relay all three tier lines, every time.** Any `also:` lines sit under
 `network` — the other addresses this machine has, offered because the
-best-guess one can be wrong — so pass them on rather than editing them out.
+best-guess one can be wrong — so pass them on rather than editing them out: in
+the banner they are indented sub-bullets under **network**, labels
+(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
 
 **Never read an environment variable to decide anything about the offer** — not
 `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left

package/assets/skills/spec-jira-setup/SKILL.md

@@ -189,7 +189,8 @@ Then name the next step:
 
 - `/spec` — write a spec; with Jira configured it creates the linked issue in
   the configured project and stamps the key.
-- `/spec-status` — read-only drift report, the safe way to prove the link works.
+- `/spec-status` — read-only report of what would push, the safe way to prove
+  the link works.
 - `/spec-push` — send a spec up.
 
 Mention what setup did **not** configure, so the defaults aren't mistaken for

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

@@ -574,7 +574,9 @@ underneath a reader when detection flipped mid-session.
 
 So: **relay all three tier lines, every time.** Any `also:` lines sit under
 `network` — the other addresses this machine has, offered because the
-best-guess one can be wrong — so pass them on rather than editing them out.
+best-guess one can be wrong — so pass them on rather than editing them out: in
+the banner they are indented sub-bullets under **network**, labels
+(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
 
 **Never read an environment variable to decide anything about the offer** — not
 `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left