@skitterbyte/skitterspec-linear 18.3.1 → 19.1.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.
Files changed (36) hide show
  1. package/MIGRATION.md +170 -1
  2. package/README.md +9 -7
  3. package/assets/core/SETUP.md +4 -4
  4. package/assets/core/env.config.md +1 -1
  5. package/assets/core/linear.config.json.example +2 -1
  6. package/assets/core/linear.config.md +59 -48
  7. package/assets/rules/spec-planning.md +35 -12
  8. package/assets/rules/spec-reports.md +47 -6
  9. package/assets/skills/no-spec/SKILL.md +2 -2
  10. package/assets/skills/spec/SKILL.md +32 -9
  11. package/assets/skills/spec-bug/SKILL.md +6 -4
  12. package/assets/skills/spec-hotfix/SKILL.md +4 -2
  13. package/assets/skills/spec-linear-setup/SKILL.md +9 -35
  14. package/assets/skills/spec-list/SKILL.md +13 -1
  15. package/assets/skills/spec-next/SKILL.md +5 -3
  16. package/assets/skills/spec-push/SKILL.md +1 -1
  17. package/assets/skills/spec-status/SKILL.md +30 -26
  18. package/assets/skills/spec-sync/SKILL.md +6 -5
  19. package/package.json +1 -1
  20. package/src/cli.js +114 -28
  21. package/src/env/resolve.js +11 -4
  22. package/src/env/review.js +126 -2
  23. package/src/vendor/linear/api.js +30 -1
  24. package/src/vendor/linear/cli-sync.js +64 -269
  25. package/src/vendor/linear/config.js +30 -49
  26. package/src/vendor/linear/doctor.js +4 -66
  27. package/src/vendor/provider-kit/src/config.js +101 -48
  28. package/src/vendor/provider-kit/src/list-assignee.js +71 -0
  29. package/src/vendor/provider-kit/src/list-rows.js +35 -0
  30. package/src/vendor/provider-kit/src/released.js +27 -77
  31. package/src/vendor/provider-kit/src/specs.js +89 -7
  32. package/src/vendor/sync-core/index.js +3 -4
  33. package/src/vendor/sync-core/src/compare.js +6 -6
  34. package/src/vendor/sync-core/src/normalize.js +60 -59
  35. package/assets/core/ci-stages.md +0 -110
  36. package/src/vendor/provider-kit/src/releases.js +0 -380
package/MIGRATION.md CHANGED
@@ -1,5 +1,133 @@
1
1
  # Migration guide
2
2
 
3
+ ## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
4
+
5
+ Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
6
+ provider can map spec kinds to its own idiom. Configs without a mapping keep
7
+ working unchanged: an unmapped kind mints the provider's default type exactly
8
+ as before, and `System.Description` stays Azure's body field unless a type is
9
+ mapped away from it. `skitterspec update` ships the new skills and rules.
10
+
11
+ **Create tracker types and states before mapping them.** A mapping names
12
+ something the tracker must already have:
13
+
14
+ - **Azure Boards** — create the custom inherited type (e.g. `Chore`) and its
15
+ states in your process, then set
16
+ `azure.workItemTypeByKind: { "chore": "Chore" }`. To fill a Bug form's Repro
17
+ Steps instead of the hidden Description, set
18
+ `azure.bodyFieldByType: { "Bug": "Microsoft.VSTS.TCM.ReproSteps" }` — it
19
+ applies symmetrically to create, update, read-back and the edited-hash
20
+ compare, so `/spec-status` stays quiet after a push. Bugs minted before the
21
+ mapping keep reading their Description until the next push rewrites them.
22
+ `spec-sync doctor --check-remote` verifies every mapped type exists and
23
+ carries its body field.
24
+ - **GitHub** — `github.labelsByKind: { "chore": "chore" }` adds the kind's
25
+ label beside the spec marker.
26
+ - **Jira** — `jira.issueTypeByKind: { "bug": "Bug", "chore": "Task" }` picks
27
+ the mint type per kind; the type must exist in the project.
28
+ - **Linear** — `linear.labelsByKind: { "chore": "Chore" }` labels the mint;
29
+ the label must already exist on the team (a missing one is a one-line note,
30
+ never a failed push).
31
+
32
+ ## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
33
+
34
+ Skitterspec now tells GitHub about **its own** transitions and nothing
35
+ else. It writes nothing about releases or deployments, and it never reads a
36
+ ticket's state back.
37
+
38
+ ### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
39
+
40
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
41
+ still calling them goes red rather than silently believing it mirrors
42
+ anything. **To migrate**, replace the step with your own script over the
43
+ release's ticket list:
44
+
45
+ ```sh
46
+ skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
47
+ ```
48
+
49
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
50
+ linked), so the script needs no second lookup. Set whatever GitHub field,
51
+ state or release object your process uses from that list. The checkout needs
52
+ `fetch-depth: 0` so the previous tag is visible.
53
+
54
+ ### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
55
+
56
+ The keys are ignored, like any unknown key, so a config carrying them still
57
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
58
+ failure). Delete them when you remove the CI step.
59
+
60
+ ### Breaking change 3 — no state drift
61
+
62
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
63
+ state with the spec's. A ticket someone moved on GitHub is not reported, and
64
+ push still resends state only when the spec itself moves. The edited-description
65
+ warning is unchanged.
66
+
67
+ ## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
68
+
69
+ Skitterspec now tells Azure Boards about **its own** transitions and nothing
70
+ else. It writes nothing about releases or deployments, and it never reads a
71
+ ticket's state back.
72
+
73
+ ### Breaking change 1 — The `release create|deployed|complete` verbs are removed
74
+
75
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
76
+ still calling them goes red rather than silently believing it mirrors
77
+ anything. **To migrate**, replace the step with your own script over the
78
+ release's ticket list:
79
+
80
+ ```sh
81
+ skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
82
+ ```
83
+
84
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
85
+ linked), so the script needs no second lookup. Set whatever Azure Boards field,
86
+ state or release object your process uses from that list. The checkout needs
87
+ `fetch-depth: 0` so the previous tag is visible.
88
+
89
+ ### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
90
+
91
+ The keys are ignored, like any unknown key, so a config carrying them still
92
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
93
+ failure). Delete them when you remove the CI step.
94
+
95
+ ### Breaking change 3 — no state drift
96
+
97
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
98
+ state with the spec's. A ticket someone moved on Azure Boards is not reported, and
99
+ push still resends state only when the spec itself moves. The edited-description
100
+ warning is unchanged.
101
+
102
+ ## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
103
+
104
+ Skitterspec now tells Jira about **its own** transitions and nothing else. It
105
+ writes nothing about releases or deployments, and it never reads an issue's
106
+ status back.
107
+
108
+ ### Breaking change 1 — no status drift
109
+
110
+ `spec-sync status --remote` and `/spec-status` no longer compare Jira's status
111
+ with the spec's. An issue someone moved on Jira is not reported, and push still
112
+ transitions it only when the spec itself moves. The edited-description warning
113
+ is unchanged.
114
+
115
+ ### Breaking change 2 — `release.stages` retired
116
+
117
+ It was accepted and validated before, and never acted on. It is now ignored
118
+ like any unknown key, and `spec-sync doctor` names it as unused config (a
119
+ `warn`, never a failure). Delete it.
120
+
121
+ ### Also — `released --json` names the spec
122
+
123
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
124
+ linked), so CI can record a release, for example as a fix version, without a
125
+ second lookup:
126
+
127
+ ```sh
128
+ skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
129
+ ```
130
+
3
131
  ## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
4
132
 
5
133
  ### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
@@ -275,7 +403,48 @@ can run it.
275
403
  committed file, so it changes for everyone who pulls and leaves that tree dirty.
276
404
  The engine says so when it does.
277
405
 
278
- ## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
406
+ ## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
407
+
408
+ Skitterspec now tells Linear about **its own** transitions and nothing
409
+ else. It writes nothing about releases or deployments, and it never reads a
410
+ ticket's state back.
411
+
412
+ ### Breaking change 1 — The `spec-sync stage` verb is removed
413
+
414
+ It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
415
+ still calling it goes red rather than silently believing it mirrors
416
+ anything. **To migrate**, replace the step with your own script over the
417
+ release's ticket list:
418
+
419
+ ```sh
420
+ skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
421
+ ```
422
+
423
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
424
+ linked), so the script needs no second lookup. Set whatever Linear field,
425
+ state or release object your process uses from that list. The checkout needs
426
+ `fetch-depth: 0` so the previous tag is visible.
427
+
428
+ ### Breaking change 2 — `release.stages` (the deployment ladder) is retired
429
+
430
+ The keys are ignored, like any unknown key, so a config carrying them still
431
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
432
+ failure). Delete them when you remove the CI step.
433
+
434
+ ### Breaking change 3 — no state drift
435
+
436
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
437
+ state with the spec's. A ticket someone moved on Linear is not reported, and
438
+ push still resends state only when the spec itself moves. The edited-description
439
+ warning is unchanged.
440
+
441
+ **A ladder rung no longer reads as `complete`.** Where a state was a
442
+ `release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
443
+ keep it reading as finished, list it as an alias:
444
+ `"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
445
+ refused as an unknown flag.
446
+
447
+ ### Also — hotfix land runs the release itself
279
448
 
280
449
  The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
281
450
  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,
@@ -580,7 +580,7 @@ through to a documented conservative default; see the field notes below.
580
580
  - `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
581
581
  - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
582
582
  (safe for a `COMPOSE_PROJECT_NAME`).
583
- - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
583
+ - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
584
584
 
585
585
  ## Pruning orphaned test-DB volumes
586
586
 
@@ -2,7 +2,8 @@
2
2
  "linear": {
3
3
  "teamKey": "",
4
4
  "teamId": "",
5
- "projectId": ""
5
+ "projectId": "",
6
+ "labelsByKind": {}
6
7
  },
7
8
  "intake": {
8
9
  "label": "",
@@ -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`
@@ -34,7 +34,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
34
34
  "teamKey": "", // human-facing key, e.g. "ENG" — the RECORDED key;
35
35
  // see "Renaming a team" below (optional)
36
36
  "teamId": "", // Linear team UUID (the issue's team)
37
- "projectId": "" // DEFAULT for the project picker (see below)
37
+ "projectId": "", // DEFAULT for the project picker (see below)
38
+ "labelsByKind": {} // one label per spec kind (feature/bug/hotfix/chore,
39
+ // from the folder prefix), applied at mint —
40
+ // e.g. { "chore": "Chore" }. The label must already
41
+ // exist on the team; a missing one is a one-line
42
+ // note, never a failed push
38
43
  },
39
44
 
40
45
  // Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
@@ -90,14 +95,9 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
90
95
  "overviewFile": "00-overview.md"
91
96
  },
92
97
 
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.
98
+ // `ignorePaths` is what `released` treats as BOOKKEEPING rather than shipped
99
+ // work — see "Bookkeeping commits" below. `[]` opts out.
99
100
  "release": {
100
- "stages": [],
101
101
  "ignorePaths": ["specs/"]
102
102
  },
103
103
 
@@ -139,6 +139,32 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
139
139
  }
140
140
  ```
141
141
 
142
+ ## More than one name per bucket — read-only aliases
143
+
144
+ A board usually has more states than the four buckets: "Blocked", "Next
145
+ Sprint", "Released". A bucket's value may be an **array** instead of a string:
146
+
147
+ ```jsonc
148
+ "states": {
149
+ "in-progress": ["Active", "Blocked"],
150
+ "complete": ["Closed", "Released"]
151
+ }
152
+ ```
153
+
154
+ - **The first name is the only one push writes**, and only when the spec
155
+ itself moves. The rest are never written.
156
+ - **The rest are read as that bucket** by the listing: the live
157
+ `spec-sync list` hides every `complete` / `cancelled` name, `--state <bucket>`
158
+ matches all of them, and `spec-sync states` lists each alias under its
159
+ bucket.
160
+ - **Nothing is pulled.** An alias changes what the report *says* about a
161
+ ticket, never the spec.
162
+ - A plain string works exactly as before. An alias that also names another
163
+ bucket is refused at load. An alias the tracker lacks is reported by
164
+ `spec-sync states` but never blocks a push, because it is never written.
165
+ - `spec-sync status` never reads a ticket's state at all, aliased or not —
166
+ see "One direction" below.
167
+
142
168
  ## Assignment (`sync.fieldOwnership.assignee`)
143
169
 
144
170
  **On by default since v16.** The spec issue is assigned to whoever is building
@@ -201,54 +227,37 @@ reusing the identity above rather than a second copy of it. It writes nothing,
201
227
  and it says what it did not show — the count, the archived exclusion, and any
202
228
  cap — rather than implying a completeness it never checked.
203
229
 
204
- ## The deployment ladder (`release.stages`)
230
+ ## Releases and deploys — the host project's to write
205
231
 
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:
232
+ Skitterspec tells Linear about **its own** transitions: a spec starting,
233
+ a phase finishing, a spec completing or being cancelled. It never reads a
234
+ ticket's state back, and it writes nothing about releases or deployments. Where
235
+ a ticket goes after its spec is `complete` — on test, in prod — belongs to the
236
+ environment, and the project's own CI or scripts record it however they like.
210
237
 
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.
238
+ The one release question skitterspec answers is
239
+ **which tickets a range contains**, because only the `Refs:` trailers know:
235
240
 
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.
241
+ ```sh
242
+ skitterspec spec-sync released "<previous-tag>..<tag>" --json
243
+ ```
238
244
 
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.
245
+ Each row carries the `ref`, its commit count, the `spec` that stamped it and its
246
+ `url` — `null` for a ref no spec has linked, never a guess. Pipe that into the
247
+ Linear API or CLI to set whatever field, label or state your process uses.
241
248
 
249
+ `release.stages` and the `spec-sync stage` command are **retired**: `stage`
250
+ exits 1 naming `released --json`, and `spec-sync doctor` flags a leftover
251
+ `release.stages` as unused config (a warning, never a failure).
242
252
 
243
253
  ## Bookkeeping commits (`release.ignorePaths`)
244
254
 
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:
255
+ `spec-sync released` answers "what did this release contain?" from the
256
+ `Refs:` trailers in the range. Left alone, that over-answers:
247
257
  a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
248
258
  code it describes, but lands **after** the tag that shipped that code — so the
249
259
  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.
260
+ for its paperwork, and anything downstream acting on the list acts twice.
252
261
 
253
262
  `release.ignorePaths` names the repo-relative prefixes that are paperwork:
254
263
 
@@ -663,8 +672,10 @@ most specific destination. Leave a list empty and nothing routes through it.
663
672
  The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
664
673
  current spec against the committed **last-pushed snapshot** and sends only what
665
674
  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
675
+ teammate moves in Linear is **not skitterspec's business**: it is never read
676
+ back or reported, and push resends State only when the spec itself moves. A
677
+ **description** someone edited there is reported by `/spec-status`, because
678
+ the next push replaces it. Priority, labels, cycles and comments are
668
679
  Linear-native triage and are never touched. No base merge, no conflicts, no
669
680
  `--force`.
670
681
 
@@ -7,7 +7,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
7
7
 
8
8
  | Skill | Purpose | Status | Folder |
9
9
  |-------|---------|--------|--------|
10
- | `/spec` | (Feature) Grill to a clear shared understanding, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
10
+ | `/spec` | (Feature/Chore) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
11
11
  | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
12
12
  | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
13
13
  | `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
@@ -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
@@ -577,23 +587,36 @@ none of them describes.
577
587
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
578
588
  (architecture, code style, testing, database, etc.) rather than restating them.
579
589
 
580
- ## Spec types — Feature, Bug, Hotfix
590
+ ## Spec types — Feature, Chore, Bug, Hotfix
581
591
 
582
- Every spec is one of three types, recorded **both** in the header and the filename:
592
+ Every spec is one of four types, recorded **both** in the header and the filename:
583
593
 
584
- - **Header field:** `> **Type:** Feature`, `> **Type:** Bug`, or
585
- `> **Type:** Hotfix` (authoritative, greppable:
594
+ - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
595
+ `> **Type:** Bug`, or `> **Type:** Hotfix` (authoritative, greppable:
586
596
  `grep -rl 'Type:.*Hotfix' specs/`).
587
- - **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs,
588
- `hotfix-<name>` for hotfixes (visible in listings; glob-safe — never use
589
- `[BUG]`/`[FEATURE]` brackets).
597
+ - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
598
+ `bug-<name>` for bugs, `hotfix-<name>` for hotfixes (visible in listings;
599
+ glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
600
+
601
+ A **Chore** is work no end user sees — tooling, CI, dependency bumps, internal
602
+ refactors. The line: anything that is not work end users see or functions they
603
+ use within the app is a chore; everything user-facing is a feature. There is no
604
+ separate entry skill — `/spec` **proposes** feature or chore from what the
605
+ grilling defined, with a one-line reason, and the user confirms. A chore
606
+ defaults its `Gating:` to `none: not user-facing` (where gating is configured),
607
+ and its commits default to `chore`/`refactor`/`ci` types with **no**
608
+ `Release-Note:` footer — a chore is by definition not user-visible, so it has
609
+ no release note to write. Feature specs keep `feat`; bug specs keep `fix`.
610
+ Where a ticketing provider maps kinds to tracker types (e.g. Azure's
611
+ `workItemTypeByKind`), the chore mapping is what keeps tooling work off the
612
+ customer-facing release ladder.
590
613
 
591
614
  A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
592
615
  carries an extra `> **Base version:** <tag>` header, forks its worktree from that
593
616
  tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
594
617
  fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
595
618
 
596
- All three types share the same lifecycle folders below — type is orthogonal to
619
+ All four types share the same lifecycle folders below — type is orthogonal to
597
620
  status.
598
621
 
599
622
  ## Header fields & State log (audit trail)
@@ -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:
@@ -219,8 +231,34 @@ again on the **same** `--since`. Not a fresh one — a pass that arrived during
219
231
  the gap is still inside the original window, and re-arming on a new timestamp
220
232
  would strand exactly that pass.
221
233
 
222
- **Say nothing when you do it.** Nothing happened and the window is unchanged; a
223
- line on every death turns a working loop into a stream of non-events.
234
+ **Say as little as the harness allows when you do it.** Nothing happened and
235
+ the window is unchanged; a line on every death turns a working loop into a
236
+ stream of non-events. Where the harness lets a turn end on the tool call, the
237
+ tool call is the whole turn. Where it insists on visible text — Claude Code
238
+ does, after a monitor event — that text is one fixed line,
239
+ `Still waiting for the verdict.`, and nothing else: not the spec, not the age,
240
+ not the links. The wait's own start line arriving as an event is answered the
241
+ same way.
242
+
243
+ **Every fifth re-arm, show the banner again.** Even one line per re-arm adds
244
+ up: over a long idle they push the verdict line and the banner's links out of
245
+ sight, and a reader who comes back has to scroll for the URL that lets them
246
+ answer. So `review wait` counts the starts on each window, and on every fifth
247
+ re-arm its start line is followed by `re-show: banner (re-arm N)` and the stack.
248
+ Relay that as the run's **verdict line** — copied from the block when it is
249
+ still in context, dropped rather than reconstructed when it is not — and then
250
+ **the banner** in its current state, with its stack copied from the `re-show:`
251
+ lines. Not the table: that would be a second block.
252
+
253
+ **A count here, not an age**, and the bound below is unaffected. What buries
254
+ the banner is how many re-arms have scrolled past it, and a death every five
255
+ minutes and one every forty-five push it up the same distance each. The age of
256
+ the window still decides when to stop.
257
+
258
+ **And it is not a third control after the block.** It is the banner this file
259
+ already defines, repeated in whatever state it is in — past the bound, that is
260
+ the degraded sentence below. No block is repeated, so nothing follows a second
261
+ one, and nothing about the banner's shape changes.
224
262
 
225
263
  **An operator who stopped it is not a death** — re-arming over a deliberate
226
264
  stop makes the wait unstoppable, which is worse than a wait that stops. But a
@@ -298,8 +336,11 @@ behind, and they cannot.
298
336
  `fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
299
337
  opened at `192.168.0.136:7760/…` reach the same server process and the same
300
338
  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.
339
+ same run. A `network` alternate — the `also:` tailnet address — is one more
340
+ door into the same room: the same server answers on it, so the wait-coverage
341
+ line stays true with nothing added to it. Between all of those the objection
342
+ does not apply — which is why they are offered, and why offering them gives
343
+ nothing up.
303
344
 
304
345
  **So two things are required, and the second is what the old rule lacked.**
305
346
  Every link is **labelled** with its tier, and one line says
@@ -410,7 +451,7 @@ behind it — say nothing rather than reporting that there was nothing to report
410
451
  | `Landed` | A fast-forward, a tag, a cherry-pick. |
411
452
  | `Worktree` | A worktree provisioned, entered, or torn down. |
412
453
  | `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. |
454
+ | `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
455
  | `Follow-ups` | **Always.** `none`, or one line each. |
415
456
  | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
416
457
 
@@ -142,8 +142,8 @@ because writing it means reading the diff, and that spend is the user's call.
142
142
 
143
143
  **A watch that dies is re-armed on the same window**, silently and bounded by
144
144
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
145
- including when to stop and what the banner says instead. Do not restate it
146
- here.
145
+ including when to stop, what the banner says instead, and when the
146
+ engine's `re-show:` brings the banner back. Do not restate it here.
147
147
 
148
148
  ```
149
149
  skitterspec spec-env review <name> --claim-since <the timestamp> --json