@skitterbyte/skitterspec-linear 18.3.0 → 19.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/MIGRATION.md CHANGED
@@ -1,5 +1,104 @@
1
1
  # Migration guide
2
2
 
3
+ ## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
4
+
5
+ Skitterspec now tells GitHub about **its own** transitions and nothing
6
+ else. It writes nothing about releases or deployments, and it never reads a
7
+ ticket's state back.
8
+
9
+ ### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
10
+
11
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
12
+ still calling them goes red rather than silently believing it mirrors
13
+ anything. **To migrate**, replace the step with your own script over the
14
+ release's ticket list:
15
+
16
+ ```sh
17
+ skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
18
+ ```
19
+
20
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
21
+ linked), so the script needs no second lookup. Set whatever GitHub field,
22
+ state or release object your process uses from that list. The checkout needs
23
+ `fetch-depth: 0` so the previous tag is visible.
24
+
25
+ ### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
26
+
27
+ The keys are ignored, like any unknown key, so a config carrying them still
28
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
29
+ failure). Delete them when you remove the CI step.
30
+
31
+ ### Breaking change 3 — no state drift
32
+
33
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
34
+ state with the spec's. A ticket someone moved on GitHub is not reported, and
35
+ push still resends state only when the spec itself moves. The edited-description
36
+ warning is unchanged.
37
+
38
+ ## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
39
+
40
+ Skitterspec now tells Azure Boards about **its own** transitions and nothing
41
+ else. It writes nothing about releases or deployments, and it never reads a
42
+ ticket's state back.
43
+
44
+ ### Breaking change 1 — The `release create|deployed|complete` verbs are removed
45
+
46
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
47
+ still calling them goes red rather than silently believing it mirrors
48
+ anything. **To migrate**, replace the step with your own script over the
49
+ release's ticket list:
50
+
51
+ ```sh
52
+ skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
53
+ ```
54
+
55
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
56
+ linked), so the script needs no second lookup. Set whatever Azure Boards field,
57
+ state or release object your process uses from that list. The checkout needs
58
+ `fetch-depth: 0` so the previous tag is visible.
59
+
60
+ ### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
61
+
62
+ The keys are ignored, like any unknown key, so a config carrying them still
63
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
64
+ failure). Delete them when you remove the CI step.
65
+
66
+ ### Breaking change 3 — no state drift
67
+
68
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
69
+ state with the spec's. A ticket someone moved on Azure Boards is not reported, and
70
+ push still resends state only when the spec itself moves. The edited-description
71
+ warning is unchanged.
72
+
73
+ ## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
74
+
75
+ Skitterspec now tells Jira about **its own** transitions and nothing else. It
76
+ writes nothing about releases or deployments, and it never reads an issue's
77
+ status back.
78
+
79
+ ### Breaking change 1 — no status drift
80
+
81
+ `spec-sync status --remote` and `/spec-status` no longer compare Jira's status
82
+ with the spec's. An issue someone moved on Jira is not reported, and push still
83
+ transitions it only when the spec itself moves. The edited-description warning
84
+ is unchanged.
85
+
86
+ ### Breaking change 2 — `release.stages` retired
87
+
88
+ It was accepted and validated before, and never acted on. It is now ignored
89
+ like any unknown key, and `spec-sync doctor` names it as unused config (a
90
+ `warn`, never a failure). Delete it.
91
+
92
+ ### Also — `released --json` names the spec
93
+
94
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
95
+ linked), so CI can record a release, for example as a fix version, without a
96
+ second lookup:
97
+
98
+ ```sh
99
+ skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
100
+ ```
101
+
3
102
  ## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
4
103
 
5
104
  ### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
@@ -275,7 +374,48 @@ can run it.
275
374
  committed file, so it changes for everyone who pulls and leaves that tree dirty.
276
375
  The engine says so when it does.
277
376
 
278
- ## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
377
+ ## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
378
+
379
+ Skitterspec now tells Linear about **its own** transitions and nothing
380
+ else. It writes nothing about releases or deployments, and it never reads a
381
+ ticket's state back.
382
+
383
+ ### Breaking change 1 — The `spec-sync stage` verb is removed
384
+
385
+ It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
386
+ still calling it goes red rather than silently believing it mirrors
387
+ anything. **To migrate**, replace the step with your own script over the
388
+ release's ticket list:
389
+
390
+ ```sh
391
+ skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
392
+ ```
393
+
394
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
395
+ linked), so the script needs no second lookup. Set whatever Linear field,
396
+ state or release object your process uses from that list. The checkout needs
397
+ `fetch-depth: 0` so the previous tag is visible.
398
+
399
+ ### Breaking change 2 — `release.stages` (the deployment ladder) is retired
400
+
401
+ The keys are ignored, like any unknown key, so a config carrying them still
402
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
403
+ failure). Delete them when you remove the CI step.
404
+
405
+ ### Breaking change 3 — no state drift
406
+
407
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
408
+ state with the spec's. A ticket someone moved on Linear is not reported, and
409
+ push still resends state only when the spec itself moves. The edited-description
410
+ warning is unchanged.
411
+
412
+ **A ladder rung no longer reads as `complete`.** Where a state was a
413
+ `release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
414
+ keep it reading as finished, list it as an alias:
415
+ `"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
416
+ refused as an unknown flag.
417
+
418
+ ### Also — hotfix land runs the release itself
279
419
 
280
420
  The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
281
421
  distribution composes the same engine. Read that entry; nothing here is
package/README.md CHANGED
@@ -93,7 +93,7 @@ them. Your `specs/` content and live `.core` config are never touched.
93
93
  | `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
94
94
  | `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
95
95
  | `/spec-push` | Repo → Linear, one-way |
96
- | `/spec-status` | Read-only drift report |
96
+ | `/spec-status` | Read-only report: what would push, and any edited description |
97
97
  | `/spec-list` | What the tracker holds, with each spec's folder name |
98
98
  | `/spec-claim` | Take a spec, hand it back, or hand it to a teammate |
99
99
  | `/spec-sync` | The `spec-sync` engine, for CI and local runs |
@@ -109,9 +109,10 @@ what the Linear half adds on top.
109
109
 
110
110
  On top of the base skills (`/spec`, `/spec-start`, `/spec-next`, isolation, …):
111
111
 
112
- - **`/spec-status`** — read-only drift report: what the next push would create /
113
- update, any workflow-state drift, and any phase whose status signals disagree
114
- (see **Phase status** below). Changes nothing.
112
+ - **`/spec-status`** — read-only report: what the next push would create /
113
+ update, a description someone edited in Linear since the last push, and any
114
+ phase whose status signals disagree (see **Phase status** below). It never
115
+ reads a ticket's state back. Changes nothing.
115
116
  - **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
116
117
  last-pushed snapshot and applies only what changed (issue description + state,
117
118
  phase sub-issues), stamping the returned ids back into the spec.
@@ -198,8 +199,9 @@ description as a read-only checklist (`mapping.tasks: "checklist"`, the default;
198
199
  `"none"` keeps the Goal line alone) — no issue is created per task, and a box
199
200
  ticked in Linear is overwritten by the next push. Priority, labels, cycles and comments are **Linear-native triage** — the
200
201
  PM's to set in Linear; one-way sync neither pushes nor reads them, so they're
201
- never clobbered. A workflow-state a teammate moves in Linear is surfaced by
202
- `/spec-status` as drift and overwritten on the next push. **Last-pushed snapshots**
202
+ never clobbered. A workflow-state a teammate moves in Linear is left alone —
203
+ skitterspec never reads state back, and push resends it only when the spec
204
+ itself moves. **Last-pushed snapshots**
203
205
  (`specs/.core/linear-base/`, content hashes) are committed so push sends only what
204
206
  changed.
205
207
 
@@ -240,7 +242,7 @@ sub-issue. `/spec-push` and `/spec-status` print the mode that resolved. See
240
242
  **Which Project a spec lands in** is asked once, when the issue is first created
241
243
  — a filterable list of your team's projects, defaulting to `linear.projectId` and
242
244
  always offering *None*. It's passed on the create call only and never stored, so
243
- re-homing a spec issue in Linear sticks: it won't read as drift and won't be moved
245
+ re-homing a spec issue in Linear sticks: it isn't reported and won't be moved
244
246
  back on the next push.
245
247
 
246
248
  **Starting from an issue** (the `intake` block in the config): `/spec SKI-123`
@@ -70,7 +70,7 @@ claude mcp list
70
70
  ```
71
71
 
72
72
  > Read-only trial: use `https://mcp.linear.app/mcp/readonly` to exercise
73
- > `/spec-status` (drift report) without granting write access. `/spec-push`
73
+ > `/spec-status` (read-only report) without granting write access. `/spec-push`
74
74
  > needs the full (writable) endpoint.
75
75
 
76
76
  ## 3. Configure — run `/spec-linear-setup`
@@ -200,7 +200,7 @@ Two ways to get there:
200
200
 
201
201
  | Command | Direction | What it does |
202
202
  |---------|-----------|--------------|
203
- | `/spec-status` | — | Read-only drift report: what would push (create/update), and whether Linear's workflow-state drifted from the spec. Writes nothing. |
203
+ | `/spec-status` | — | Read-only report: what would push (create/update), and whether the issue's description was edited in Linear since the last push. Writes nothing. |
204
204
  | `/spec-push` | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (issue description/state, phase sub-issues), stamping new ids back into the spec. |
205
205
  | `/spec-claim` | repo → Linear | Take a spec over, `--release` it, or hand it `--to` a teammate. Records the owner in the spec, then pushes. Needs assignment enabled (below). |
206
206
  | `/spec-list` | Linear → you | Read-only listing of every spec Linear holds — id, title, state, who holds it and the local spec name to start it by. Filters by state, backlog order, or assignee. Writes nothing. |
@@ -221,8 +221,8 @@ have not got.
221
221
 
222
222
  Tasks, priority, labels, cycles and comments are **Linear-native triage** (or
223
223
  repo-only) — never pushed, so they're never clobbered. A workflow-state a teammate
224
- moves in Linear is surfaced by `/spec-status` as drift and overwritten on the next
225
- push.
224
+ moves in Linear is left alone: skitterspec never reads state back, and push
225
+ resends it only when the spec itself moves.
226
226
 
227
227
  The spec is one issue and each phase a **sub-issue** (`parentId` = the spec
228
228
  issue). The link ids live in frontmatter — `linear_identifier` on the overview,
@@ -7,7 +7,7 @@ a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
7
7
  that sub-issue's description as a read-only checklist. Content is
8
8
  pushed up and never read back or merged — `/spec-push` diffs the spec against a
9
9
  committed **last-pushed snapshot** and applies only what changed; `/spec-status`
10
- is a read-only drift report. The `sync.fieldOwnership` map now just selects the
10
+ is a read-only report of what would push. The `sync.fieldOwnership` map now just selects the
11
11
  projection field set (every field is repo-owned and pushed).
12
12
 
13
13
  **Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
@@ -90,14 +90,9 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
90
90
  "overviewFile": "00-overview.md"
91
91
  },
92
92
 
93
- // The project's OWN deployment ladder — where a ticket goes AFTER its spec is
94
- // complete. Empty (the default) means no ladder is declared and every
95
- // stage-aware path is unused. See "The deployment ladder" below.
96
- //
97
- // `ignorePaths` is what `released`/`stage` treat as BOOKKEEPING rather than
98
- // shipped work — see "Bookkeeping commits" below. `[]` opts out.
93
+ // `ignorePaths` is what `released` treats as BOOKKEEPING rather than shipped
94
+ // work — see "Bookkeeping commits" below. `[]` opts out.
99
95
  "release": {
100
- "stages": [],
101
96
  "ignorePaths": ["specs/"]
102
97
  },
103
98
 
@@ -139,6 +134,32 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
139
134
  }
140
135
  ```
141
136
 
137
+ ## More than one name per bucket — read-only aliases
138
+
139
+ A board usually has more states than the four buckets: "Blocked", "Next
140
+ Sprint", "Released". A bucket's value may be an **array** instead of a string:
141
+
142
+ ```jsonc
143
+ "states": {
144
+ "in-progress": ["Active", "Blocked"],
145
+ "complete": ["Closed", "Released"]
146
+ }
147
+ ```
148
+
149
+ - **The first name is the only one push writes**, and only when the spec
150
+ itself moves. The rest are never written.
151
+ - **The rest are read as that bucket** by the listing: the live
152
+ `spec-sync list` hides every `complete` / `cancelled` name, `--state <bucket>`
153
+ matches all of them, and `spec-sync states` lists each alias under its
154
+ bucket.
155
+ - **Nothing is pulled.** An alias changes what the report *says* about a
156
+ ticket, never the spec.
157
+ - A plain string works exactly as before. An alias that also names another
158
+ bucket is refused at load. An alias the tracker lacks is reported by
159
+ `spec-sync states` but never blocks a push, because it is never written.
160
+ - `spec-sync status` never reads a ticket's state at all, aliased or not —
161
+ see "One direction" below.
162
+
142
163
  ## Assignment (`sync.fieldOwnership.assignee`)
143
164
 
144
165
  **On by default since v16.** The spec issue is assigned to whoever is building
@@ -201,54 +222,37 @@ reusing the identity above rather than a second copy of it. It writes nothing,
201
222
  and it says what it did not show — the count, the archived exclusion, and any
202
223
  cap — rather than implying a completeness it never checked.
203
224
 
204
- ## The deployment ladder (`release.stages`)
225
+ ## Releases and deploys — the host project's to write
205
226
 
206
- A spec's lifecycle stops at `complete`. Where a ticket goes **after** that —
207
- deployed to test, approved for demo, live in prod — is a fact about an
208
- **environment**, and nothing under `specs/` can derive it. `release.stages` is
209
- where a project declares that ladder in its own vocabulary:
227
+ Skitterspec tells Linear about **its own** transitions: a spec starting,
228
+ a phase finishing, a spec completing or being cancelled. It never reads a
229
+ ticket's state back, and it writes nothing about releases or deployments. Where
230
+ a ticket goes after its spec is `complete` — on test, in prod — belongs to the
231
+ environment, and the project's own CI or scripts record it however they like.
210
232
 
211
- ```jsonc
212
- "release": {
213
- "stages": [
214
- { "key": "test", "state": "On Test" },
215
- { "key": "demo", "state": "Ready for Demo" },
216
- { "key": "prod", "state": "Done" }
217
- ]
218
- }
219
- ```
220
-
221
- - **`key`** is what CI names (`spec-sync stage test …`); **`state`** is the
222
- Linear issue state it moves to. Pipelines reference the *key*, never the state
223
- name, so renaming a Linear column is one edit here rather than a hunt through
224
- pipeline YAML.
225
- - **Every `state` is checked against the workspace** alongside `states`, at push
226
- and setup time. Linear **silently ignores** an unknown issue state, so an
227
- unchecked typo would deploy cleanly and move nothing, forever.
228
- - **Order is recorded, not enforced.** It drives reporting and the doctor check;
229
- a rollback from test, or a hotfix going straight to prod, is legitimate and is
230
- never refused.
231
- - **Keys must be unique**, and a malformed entry is a hard error at load — the
232
- same treatment `sync.fieldOwnership` and `mapping.phases` get.
233
- - **Absent or empty = the opt-out.** Nothing about the ladder affects a project
234
- that has not declared one.
233
+ The one release question skitterspec answers is
234
+ **which tickets a range contains**, because only the `Refs:` trailers know:
235
235
 
236
- Unlike `states` and `mapping.phases`, this is **not** keyed by lifecycle bucket:
237
- the buckets are a closed set the repo derives, and a deployment stage never is.
236
+ ```sh
237
+ skitterspec spec-sync released "<previous-tag>..<tag>" --json
238
+ ```
238
239
 
239
- Run `skitterspec spec-sync states` to see the whole configured vocabulary — the
240
- bucket map and the ladder — against what the workspace actually has.
240
+ Each row carries the `ref`, its commit count, the `spec` that stamped it and its
241
+ `url` — `null` for a ref no spec has linked, never a guess. Pipe that into the
242
+ Linear API or CLI to set whatever field, label or state your process uses.
241
243
 
244
+ `release.stages` and the `spec-sync stage` command are **retired**: `stage`
245
+ exits 1 naming `released --json`, and `spec-sync doctor` flags a leftover
246
+ `release.stages` as unused config (a warning, never a failure).
242
247
 
243
248
  ## Bookkeeping commits (`release.ignorePaths`)
244
249
 
245
- `spec-sync released` and `spec-sync stage` answer "what did this release
246
- contain?" from the `Refs:` trailers in the range. Left alone, that over-answers:
250
+ `spec-sync released` answers "what did this release contain?" from the
251
+ `Refs:` trailers in the range. Left alone, that over-answers:
247
252
  a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
248
253
  code it describes, but lands **after** the tag that shipped that code — so the
249
254
  ticket turns up in two consecutive release ranges, once for its code and once
250
- for its paperwork. Downstream, a deployment ladder then drags an issue that had
251
- already reached the top back down a rung.
255
+ for its paperwork, and anything downstream acting on the list acts twice.
252
256
 
253
257
  `release.ignorePaths` names the repo-relative prefixes that are paperwork:
254
258
 
@@ -663,8 +667,10 @@ most specific destination. Leave a list empty and nothing routes through it.
663
667
  The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
664
668
  current spec against the committed **last-pushed snapshot** and sends only what
665
669
  changed — creates for unlinked items, updates for changed ones. A workflow-state a
666
- teammate moves in Linear is surfaced by `/spec-status` as **drift** (advisory) and
667
- overwritten on the next push. Priority, labels, cycles and comments are
670
+ teammate moves in Linear is **not skitterspec's business**: it is never read
671
+ back or reported, and push resends State only when the spec itself moves. A
672
+ **description** someone edited there is reported by `/spec-status`, because
673
+ the next push replaces it. Priority, labels, cycles and comments are
668
674
  Linear-native triage and are never touched. No base merge, no conflicts, no
669
675
  `--force`.
670
676
 
@@ -492,9 +492,19 @@ missing alias.
492
492
  Sync is **one-way**: the repo is the source of truth and the tracker is a
493
493
  **generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
494
494
  against a committed last-pushed snapshot and applies it) and `/spec-status`
495
- (read-only drift report — what would push, and whether the tracker's
496
- workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
497
- the tracker is never read back or merged.
495
+ (read-only — what would push, and whether someone edited a description there),
496
+ backed by a `spec-sync` CLI. There is no content pull — the tracker is never
497
+ read back or merged.
498
+
499
+ **It tells, it doesn't track.** Skitterspec sends the tracker its own
500
+ transitions — a spec starting, a phase finishing, a spec completing or being
501
+ cancelled — and nothing else. A status someone changes on the tracker is
502
+ theirs to have changed: it is never read back, never reported, and only
503
+ overwritten when the spec itself next moves. Releases and deployments are the
504
+ host project's to record. The one release question skitterspec answers is which
505
+ tickets a commit range contains (`spec-sync released <range> --json`, each row
506
+ with its spec and url), because only the `Refs:` trailers know. What the
507
+ project's CI does with that list is its own business.
498
508
 
499
509
  **One-way means the repo wins, and it now wins *loudly*.** Those are different
500
510
  claims and only the first was ever in doubt. A ticket's description is generated
@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
36
36
  | **Branch** | `spec/feat-foo` · 3 commits, clean |
37
37
  | **Built** | POST /orders handler, orders schema |
38
38
  | **Tests** | 128 passed · dotnet test |
39
- | **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 |
39
+ | **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 |
40
40
  | **Follow-ups** | none |
41
41
  | **Next** | `/spec-next` → phase 3 (Auth) |
42
42
 
@@ -89,6 +89,7 @@ the options may be offered after the table.
89
89
 
90
90
  - **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
91
91
  - **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
92
+ - also — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
92
93
  - **remote** — off · `/spec-remote-review` turns it on
93
94
 
94
95
  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
156
157
  nothing on screen to tell them a remote page was even possible — they could not
157
158
  ask for what they could not see.
158
159
 
160
+ **The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
161
+ The engine offers the other addresses this machine has (a
162
+ tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
163
+ labelled; `--json` carries them as that tier's `alternates`, labelled the same
164
+ way. Copy them as indented sub-bullets under the network bullet, verbatim,
165
+ labels included. This is not an amendment to the tier rule: the stack is the
166
+ engine's, copied rather than composed, and the engine was already printing
167
+ these — a contract that made the skill edit them out was the composing this
168
+ section forbids. A machine with no alternates renders the banner exactly as
169
+ above, minus the sub-bullet.
170
+
159
171
  **Only promise a wait the transport can deliver.** The wait itself is real in
160
172
  every case; what varies is what carries it back, not whether the run is
161
173
  stopped. Three transports, three true sentences:
@@ -298,8 +310,11 @@ behind, and they cannot.
298
310
  `fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
299
311
  opened at `192.168.0.136:7760/…` reach the same server process and the same
300
312
  pending store. One wait covers both, and a verdict pressed on either wakes the
301
- same run. Between those two the objection does not apply — which is why both are
302
- offered, and why offering them gives nothing up.
313
+ same run. A `network` alternate — the `also:` tailnet address — is one more
314
+ door into the same room: the same server answers on it, so the wait-coverage
315
+ line stays true with nothing added to it. Between all of those the objection
316
+ does not apply — which is why they are offered, and why offering them gives
317
+ nothing up.
303
318
 
304
319
  **So two things are required, and the second is what the old rule lacked.**
305
320
  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
410
425
  | `Landed` | A fast-forward, a tag, a cherry-pick. |
411
426
  | `Worktree` | A worktree provisioned, entered, or torn down. |
412
427
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
413
- | `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. |
428
+ | `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. |
414
429
  | `Follow-ups` | **Always.** `none`, or one line each. |
415
430
  | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
416
431
 
@@ -647,7 +647,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
647
647
  an update the issue already has a project (or deliberately has none), and that
648
648
  placement is **Linear's to own**: never send `project` on an update, and never
649
649
  record the choice in the spec file or the snapshot. A PM re-homing a spec issue
650
- must not show up as drift or be overwritten on the next push.
650
+ must not be reported or overwritten on the next push.
651
651
 
652
652
  1. **List the candidates.** Ask the engine:
653
653
  `skitterspec spec-sync projects --json`. On the API path it returns the team's
@@ -448,7 +448,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
448
448
  an update the issue already has a project (or deliberately has none), and that
449
449
  placement is **Linear's to own**: never send `project` on an update, and never
450
450
  record the choice in the spec file or the snapshot. A PM re-homing a spec issue
451
- must not show up as drift or be overwritten on the next push.
451
+ must not be reported or overwritten on the next push.
452
452
 
453
453
  1. **List the candidates.** Ask the engine:
454
454
  `skitterspec spec-sync projects --json`. On the API path it returns the team's
@@ -614,7 +614,9 @@ underneath a reader when detection flipped mid-session.
614
614
 
615
615
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
616
616
  `network` — the other addresses this machine has, offered because the
617
- best-guess one can be wrong — so pass them on rather than editing them out.
617
+ best-guess one can be wrong — so pass them on rather than editing them out: in
618
+ the banner they are indented sub-bullets under **network**, labels
619
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
618
620
 
619
621
  **Never read an environment variable to decide anything about the offer** — not
620
622
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -480,7 +480,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
480
480
  an update the issue already has a project (or deliberately has none), and that
481
481
  placement is **Linear's to own**: never send `project` on an update, and never
482
482
  record the choice in the spec file or the snapshot. A PM re-homing a spec issue
483
- must not show up as drift or be overwritten on the next push.
483
+ must not be reported or overwritten on the next push.
484
484
 
485
485
  1. **List the candidates.** Ask the engine:
486
486
  `skitterspec spec-sync projects --json`. On the API path it returns the team's
@@ -625,7 +625,9 @@ underneath a reader when detection flipped mid-session.
625
625
 
626
626
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
627
627
  `network` — the other addresses this machine has, offered because the
628
- best-guess one can be wrong — so pass them on rather than editing them out.
628
+ best-guess one can be wrong — so pass them on rather than editing them out: in
629
+ the banner they are indented sub-bullets under **network**, labels
630
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
629
631
 
630
632
  **Never read an environment variable to decide anything about the offer** — not
631
633
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -147,36 +147,14 @@ never apply one they didn't agree to), and re-run with the `--state` flags. If i
147
147
  made no suggestion for a bucket, **ask** which state means "finished" here rather
148
148
  than guessing.
149
149
 
150
- ## 7. Does this repo deploy through stages? (optional)
150
+ ## 7. Deploys are the project's own to record
151
151
 
152
- A spec's lifecycle ends at `complete`. Where a ticket goes **after** that —
153
- deployed to test, approved for demo, live in production — is a fact about an
154
- environment, and nothing in the repo can derive it. If the team runs a deploy
155
- pipeline, it can declare that ladder here and CI moves tickets along it with
156
- `spec-sync stage`.
157
-
158
- **Ask, do not assume.** Most projects have no ladder, and an invented one is
159
- worse than none: `spec-sync stage` refuses cleanly when none is declared, whereas
160
- a wrong ladder is a pipeline quietly moving tickets to the wrong column. If the
161
- user does not raise deployment, offer it once in a line and take "no" for an
162
- answer.
163
-
164
- If they do want one, ask for the stages **in deployment order**, and map each to
165
- a state from the `list_issue_statuses` names you already have:
166
-
167
- ```
168
- --stage test="On Test" --stage demo="Ready for Demo" --stage prod="Done"
169
- ```
170
-
171
- - The **key** (`test`) is what a pipeline names; the **state** is the Linear
172
- column. Pipelines reference the key, so renaming the column later is one edit
173
- here.
174
- - Order is recorded, not enforced — a rollback and a hotfix straight to prod are
175
- both legitimate and are never refused.
176
- - **Ask what closes an issue.** If the last rung is not a completed-type state,
177
- tickets that finish the ladder never reach Done. That is fine when Linear
178
- automation closes them and a problem otherwise — `spec-sync doctor` warns about
179
- it either way, so say which it is.
152
+ Nothing to ask here. Skitterspec moves a Linear issue only at its own
153
+ transitions, and a spec's lifecycle ends at `complete`. Where a ticket goes
154
+ after that is the host project's: its CI can list a release's tickets with
155
+ `skitterspec spec-sync released "<previous-tag>..<tag>" --json` and set whatever
156
+ Linear state or label it likes. If the user asks about deploy tracking, say that
157
+ in one line and point at "Releases and deploys" in `linear.config.md`.
180
158
 
181
159
  ## 7b. Assignment is on — does this team want it off?
182
160
 
@@ -227,11 +205,6 @@ shows this repo's choices and keeps inheriting everything else. `--force` is
227
205
  required to replace an existing config — never pass it without the user having
228
206
  asked for a rewrite in step 1.
229
207
 
230
- Every `--stage` state is checked against the workspace exactly like a bucket
231
- state, and a bad one is refused the same way — as `release.stages[test]` rather
232
- than `states.complete`. There is no suggestion for a rung: the vocabulary is the
233
- project's own, so ask rather than guess.
234
-
235
208
  **Relay the engine's report as printed.** It names the team, the project (or
236
209
  "team only"), the intake labels, and how many state names were checked against
237
210
  the workspace — that report is the evidence the setup is right, so don't
@@ -312,7 +285,8 @@ Then name the next step:
312
285
 
313
286
  - `/spec` — write a spec; with Linear configured it offers the project picker,
314
287
  creates the linked issue and stamps the id.
315
- - `/spec-status` — read-only drift report, the safe way to prove the link works.
288
+ - `/spec-status` — read-only report of what would push, the safe way to prove
289
+ the link works.
316
290
  - `/spec-push` — send a spec up.
317
291
 
318
292
  **Never ask for the API key.** `doctor`'s `key` row already reports whether one
@@ -49,6 +49,18 @@ flags themselves (`--state`, `--all`, `--next`, `--in-progress`) are
49
49
  **alternatives**, and the engine refuses any two of them rather than letting one
50
50
  win silently.
51
51
 
52
+ **Every row shows the board's state and the spec's own status side by side.**
53
+ The spec status is read from the spec's **own worktree** when one exists, so an
54
+ in-flight spec reads `in-progress` even on the base branch, where its folder
55
+ still says `backlog`. `≠ <bucket>` marks a row whose board state maps to a
56
+ different bucket than its spec; a state that maps to no bucket never gets one.
57
+ `—` means the spec is not on this machine. Relay it as printed; never "correct"
58
+ either column from the other. The board says where the ticket is, and the spec
59
+ says where the work is.
60
+
61
+ `--state` also takes a lifecycle bucket: `--state in-progress` matches every
62
+ board state configured for it (`states` aliases included).
63
+
52
64
  `--next N` is **backlog-only and ordered**, so it does not combine with
53
65
  `--state` or `--all`; the engine refuses that pair rather than picking a winner.
54
66
  It reproduces Linear's own Backlog order — priority first, then the manual
@@ -58,7 +70,7 @@ then a person's arrangement rather than a ranking.
58
70
  ## 2. Run the engine
59
71
 
60
72
  ```
61
- skitterspec spec-sync list [--state <name> …|--all] [--limit N] [--archived] [--json]
73
+ skitterspec spec-sync list [--state <name|bucket> …|--all] [--limit N] [--archived] [--json]
62
74
  ```
63
75
 
64
76
  - **`transport = api`** (a key is set) → it queried Linear and printed the
@@ -583,7 +583,9 @@ underneath a reader when detection flipped mid-session.
583
583
 
584
584
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
585
585
  `network` — the other addresses this machine has, offered because the
586
- best-guess one can be wrong — so pass them on rather than editing them out.
586
+ best-guess one can be wrong — so pass them on rather than editing them out: in
587
+ the banner they are indented sub-bullets under **network**, labels
588
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
587
589
 
588
590
  **Never read an environment variable to decide anything about the offer** — not
589
591
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -314,7 +314,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
314
314
  an update the issue already has a project (or deliberately has none), and that
315
315
  placement is **Linear's to own**: never send `project` on an update, and never
316
316
  record the choice in the spec file or the snapshot. A PM re-homing a spec issue
317
- must not show up as drift or be overwritten on the next push.
317
+ must not be reported or overwritten on the next push.
318
318
 
319
319
  1. **List the candidates.** Ask the engine:
320
320
  `skitterspec spec-sync projects --json`. On the API path it returns the team's