@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
@@ -188,9 +188,31 @@ not write the spec until this is resolved.
188
188
  Stop grilling when there are no unresolved branches that would change the spec.
189
189
  Briefly play back the agreed understanding before writing.
190
190
 
191
+ ### Propose the kind — feature or chore
192
+
193
+ This skill writes two kinds of spec, and
194
+ **you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
195
+ The
196
+ line that decides it: a **chore** is anything that is not work end users see or
197
+ functions they use within the app — tooling, CI, dependency bumps, internal
198
+ refactors. Everything user-facing is a **feature**. So the proposal reads like
199
+ *"no user-visible surface → chore"* or *"adds an endpoint users call → feature"*.
200
+
201
+ The kind is recorded twice, and both follow from the answer: the folder prefix
202
+ (`feat-` / `chore-`) and the `> **Type:**` header (`Feature` / `Chore`). A chore
203
+ also defaults its `Gating:` to `none: not user-facing` (only when gating is
204
+ configured — offer the default, let the user override it like any other
205
+ answer), and its commits default to `chore`/`refactor`/`ci` types with no
206
+ `Release-Note:` (see `.claude/rules/spec-planning.md`).
207
+
208
+ There is no `/spec-chore` and none should be added: one entry point, one grill,
209
+ and the kind is an output of understanding the work rather than a door the user
210
+ must pick before describing it.
211
+
191
212
  ## Phase B — write the spec
192
213
 
193
- This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
214
+ This skill is for **features and chores**. For bugs, use `/spec-bug`
215
+ (test-first, red→green).
194
216
 
195
217
  ### Write it in its own worktree
196
218
 
@@ -257,8 +279,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
257
279
  that phase's goal, its task checkboxes (tests included), and any phase-specific
258
280
  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
259
281
  into `00-overview.md`. This keeps each phase easy to dive into on its own.
260
- - Choose a short kebab-case name and **prefix it `feat-`** (the bug counterpart
261
- uses `bug-`).
282
+ - Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
283
+ a feature, `chore-` for a chore (the bug counterpart uses `bug-`).
262
284
 
263
285
  Use this template (keep it **as concise as possible** — no filler, no restating
264
286
  the codebase, link rather than duplicate):
@@ -266,8 +288,8 @@ the codebase, link rather than duplicate):
266
288
  ```markdown
267
289
  # <Feature title>
268
290
 
269
- > **Type:** Feature
270
- > **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
291
+ > **Type:** <Feature or Chore — the kind proposed after Phase A>
292
+ > **Name:** <feat- or chore-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
271
293
  > **Status:** Ready — not started
272
294
  > **Author:** <git user.name — `git config user.name`>
273
295
  > **Developer:** —
@@ -276,7 +298,8 @@ the codebase, link rather than duplicate):
276
298
  > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
277
299
  > services; only acted on when isolation is enabled — see Phase A item 9>
278
300
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
279
- > is configured; omit the line entirely otherwise. An empty value or a bare
301
+ > is configured; omit the line entirely otherwise. A chore defaults to
302
+ > "none: not user-facing". An empty value or a bare
280
303
  > "none" is not a valid outcome — see Phase A item 10>
281
304
 
282
305
  ## Problem
@@ -538,8 +561,8 @@ the verdict — and the reader's conclusion is about what the page showed them.
538
561
 
539
562
  **A watch that dies is re-armed on the same window**, silently and bounded by
540
563
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
541
- including when to stop and what the banner says instead. Do not restate it
542
- here.
564
+ including when to stop, what the banner says instead, and when the
565
+ engine's `re-show:` brings the banner back. Do not restate it here.
543
566
 
544
567
  ```
545
568
  skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
@@ -647,7 +670,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
647
670
  an update the issue already has a project (or deliberately has none), and that
648
671
  placement is **Linear's to own**: never send `project` on an update, and never
649
672
  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.
673
+ must not be reported or overwritten on the next push.
651
674
 
652
675
  1. **List the candidates.** Ask the engine:
653
676
  `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
@@ -571,8 +571,8 @@ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
571
571
 
572
572
  **A watch that dies is re-armed on the same window**, silently and bounded by
573
573
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
574
- including when to stop and what the banner says instead. Do not restate it
575
- here.
574
+ including when to stop, what the banner says instead, and when the
575
+ engine's `re-show:` brings the banner back. Do not restate it here.
576
576
 
577
577
  **Why this skill arms as well as waits.** Waiting is what any offer does;
578
578
  **arming** asserts an obligation that outlives the turn, and belongs only to
@@ -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
@@ -506,8 +506,8 @@ reading — and that is the gap the whole gate exists to close.
506
506
 
507
507
  **A watch that dies is re-armed on the same window**, silently and bounded by
508
508
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
509
- including when to stop and what the banner says instead. Do not restate it
510
- here.
509
+ including when to stop, what the banner says instead, and when the
510
+ engine's `re-show:` brings the banner back. Do not restate it here.
511
511
 
512
512
  Then **end your turn**. Do not poll it and do not hold the turn open: the
513
513
  point is that the reader has the terminal back while they read.
@@ -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
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: spec-status
3
- description: Show a spec's one-way sync status against Linear — a read-only drift report naming what would push, and whether the tracker's workflow-state has drifted from the spec's. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
3
+ description: Show a spec's one-way sync status against Linear — a read-only report naming what would push, and whether someone edited the issue's description since the last push. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
- # /spec-status — one-way sync drift report
7
+ # /spec-status — one-way sync report
8
8
 
9
9
  > Stay silent while this runs — speak only to ask something you cannot answer
10
10
  > yourself, or to report a failure at the moment it happens. Read
@@ -15,13 +15,17 @@ Read-only. Reports two things and writes nothing:
15
15
 
16
16
  1. **Pending push** — has the spec changed since the last push (is there an issue
17
17
  description/state or any phase sub-issue to create or update)?
18
- 2. **State drift** — does Linear's issue workflow-state differ from the spec's
19
- status? (The repo wins on the next push; this is just a heads-up, e.g. a card
20
- moved in Linear.)
18
+ 2. **Description edited** — did someone edit the issue's description on Linear
19
+ since the last push? The next push replaces it, so this is worth reading
20
+ first.
21
+
22
+ **Status is not compared, deliberately.** Skitterspec tells Linear about its
23
+ own transitions and never reads a status back: a card someone moved by hand is
24
+ theirs to have moved, and push resends State only when the spec itself moves.
21
25
 
22
26
  The repo is the source of truth; Linear is a generated mirror, so there is no
23
- per-field "conflict" — only "what would the next push send" and "did the mirror
24
- drift".
27
+ per-field "conflict" — only "what would the next push send" and "did someone
28
+ write over the mirror's text".
25
29
 
26
30
  **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
27
31
  tell the user how to enable Linear sync and stop.
@@ -30,18 +34,16 @@ tell the user how to enable Linear sync and stop.
30
34
 
31
35
  Use the argument, else the spec in context; ask if unclear.
32
36
 
33
- ## 2. Fetch the Linear issue (optional, for drift)
37
+ ## 2. Fetch the Linear issue (optional, for the description check)
34
38
 
35
39
  If the spec has a `linear_identifier`, discover the Linear MCP read tool
36
- (`get_issue`) and write the issue JSON to a temp file. If Linear isn't connected,
37
- skip the drift lines (still report pending-push).
40
+ (`get_issue`) and write the issue JSON to a temp file. If Linear isn't
41
+ connected, skip the description check (still report pending-push).
38
42
 
39
- **Write the whole issue, including its `description`.** The engine reports two
40
- independent kinds of drift off that one file: the workflow-state someone moved,
41
- and the **description someone edited**. Write only the state fields and the
42
- second check has nothing to look at — and it says nothing rather than guessing,
43
- so the loss is silent. Keep `url` too: it is what the description line points
44
- the reader at.
43
+ **Write the whole issue, including its `description`.** That is the field the
44
+ check reads; without it the check has nothing to look at — and it says nothing
45
+ rather than guessing, so the loss is silent. Keep `url` too: it is what the
46
+ description line points the reader at.
45
47
 
46
48
  **The description itself never enters the conversation.** The engine hashes it
47
49
  and compares hashes; what it prints is *that* the text changed, plus where to
@@ -58,8 +60,9 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
58
60
  ```
59
61
 
60
62
  - Reports `push: pending — N to create, M to update` or `up to date`.
61
- - With `--remote`, adds a `drift:` line comparing Linear's issue workflow-state
62
- to the spec's status.
63
+ - With `--remote`, adds a `drift:` line when the issue's description was
64
+ edited on Linear since the last push, and nothing otherwise. It never
65
+ reports the issue's state.
63
66
  - With `--workspace-states`, fails loudly if a configured state name isn't in the
64
67
  workspace (Linear would silently no-op it).
65
68
 
@@ -92,18 +95,19 @@ the shape; this section carries only what is specific here.
92
95
  **Verdicts**
93
96
 
94
97
  - `✅` — in sync; nothing would push.
95
- - `⚠️` — drift: N objects would push, Linear's workflow state was moved by hand,
96
- or the issue's **description** was edited on Linear since the last push. None
97
- is an error — the repo wins on the next push — but all are the reason someone
98
- ran this. **Say which**, since the three call for different things: a pending
99
- push is routine, a moved state is usually someone else's automation, and an
100
- edited description means a person wrote something that the next push replaces.
98
+ - `⚠️` — N objects would push, or the issue's **description** was edited on
99
+ Linear since the last push. Neither is an error, but both are the reason
100
+ someone ran this. **Say which**, since they call for different things: a
101
+ pending push is routine, and an edited description means a person wrote
102
+ something that the next push replaces.
103
+ An `assignee` drift line is the third case: the assignee is a field the repo
104
+ owns, so the next push restores the spec's record.
101
105
  - `⏸` — no config, or the spec is not linked. Nothing to compare.
102
106
 
103
107
  **Fields:** `Tracker` · `Follow-ups` · `Next`
104
108
 
105
- `Tracker` is the drift in one line — what would push, and whether the tracker's
106
- state diverged. `Next` is `/spec-push` when a push is pending, and nothing to do
109
+ `Tracker` is the answer in one line — what would push, and whether the
110
+ description was edited. `Next` is `/spec-push` when a push is pending, and nothing to do
107
111
  when it is not.
108
112
 
109
113
  A **`phases: <mode>`** line names the phase mode that resolved for this spec's
@@ -46,8 +46,7 @@ In a project that installs the Linear superset the binary is
46
46
  | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
47
47
  | "is the team key stale?", "did Linear get renamed?" | `retarget` |
48
48
  | "what ticket am I on?", writing a commit | `ref` |
49
- | "what shipped in this release?" | `released` |
50
- | "move the shipped tickets on", "what's on test?" | `stage` — dry run unless `--apply` |
49
+ | "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
51
50
  | "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and key in one |
52
51
  | "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
53
52
  | "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
@@ -67,7 +66,7 @@ Two front doors to one write path is worse than none:
67
66
 
68
67
  - **Push one spec** → `/spec-push`. It owns the transport choice, the
69
68
  workspace-state gate, the plan, the apply, the stamping and the snapshot.
70
- - **Per-spec drift** ("is this spec in sync?", "what would push?") →
69
+ - **Per-spec status** ("is this spec in sync?", "what would push?") →
71
70
  `/spec-status`.
72
71
 
73
72
  Say which skill you're handing to and stop; don't reimplement either.
@@ -169,8 +168,10 @@ and never write `Refs: none`.
169
168
 
170
169
  `released` reports the tickets in a commit range — by default since the most
171
170
  recent tag, and it always prints the range it chose so a wrong default is
172
- visible. It is **read-only**: it does not move anything in Linear. A release can
173
- be cut and never deployed, so transitioning tickets stays a deliberate act.
171
+ visible. It is **read-only**: it does not move anything in Linear. Each ticket
172
+ row names the `spec` and `url` behind it (`null` when no spec linked the ref),
173
+ so `--json` is what a project's CI pipes into its own tooling to record a
174
+ release or a deploy. Recording those is the project's job, not skitterspec's.
174
175
 
175
176
  Relay the **unreferenced count** even when it is zero. A chore commit
176
177
  legitimately carries no ticket and a *missed* trailer looks identical, so
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "18.3.1",
3
+ "version": "19.1.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -88,6 +88,8 @@ const {
88
88
  collectReview,
89
89
  reviewTierStack,
90
90
  reviewTierLine,
91
+ isTailnetAddress,
92
+ tailnetLabel,
91
93
  renderReviewPage,
92
94
  renderReviewBlock,
93
95
  reviewOutPath,
@@ -117,6 +119,9 @@ const {
117
119
  passesSince,
118
120
  waitForPass,
119
121
  WAIT_HEARTBEAT_MS,
122
+ WAIT_RESHOW_EVERY,
123
+ recordWaitStart,
124
+ reshowDue,
120
125
  waitingPasses,
121
126
  describePending,
122
127
  pendingAge,
@@ -901,7 +906,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
901
906
  try {
902
907
  spec = resolveSpecWithWorktree(dir, config, specArg)
903
908
  } catch (err) {
904
- const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
909
+ const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore)-./.test(specArg)
905
910
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
906
911
  throw err
907
912
  }
@@ -2759,6 +2764,74 @@ function resolveHeartbeatMs(flags) {
2759
2764
  return seconds * 1000
2760
2765
  }
2761
2766
 
2767
+ /**
2768
+ * Every this-many re-arms the stack is printed again. Default 5, `0` disables.
2769
+ * A value that is not a whole number takes the DEFAULT rather than disabling
2770
+ * (`.claude/rules/negative-checks.md` rule 4), the same as `--heartbeat`.
2771
+ */
2772
+ function resolveReshowEvery(flags) {
2773
+ if (flags.reshowEvery === undefined || flags.reshowEvery === null) return WAIT_RESHOW_EVERY
2774
+ const n = Number(flags.reshowEvery)
2775
+ if (!Number.isInteger(n) || n < 0) return WAIT_RESHOW_EVERY
2776
+ return n
2777
+ }
2778
+
2779
+ /**
2780
+ * The review server that is running, read and never touched — or null.
2781
+ *
2782
+ * NOT `ensureReviewServer`. That one adopts, and where a server is stale it
2783
+ * replaces it, and a re-show that restarted the server would kill the link
2784
+ * open on the reader's phone in order to remind them of it. This reads the
2785
+ * pidfile and the settings and stops there.
2786
+ *
2787
+ * WHAT WOULD FOOL THIS: a pidfile left by a crash names a pid the OS may have
2788
+ * reused for something else. `isAlive` cannot tell those apart, so the URL it
2789
+ * offers could point at nothing — the same blind spot every adopt has, and the
2790
+ * cost is a dead link in a reminder, never a lost pass.
2791
+ */
2792
+ function readRunningReviewServer(dir, config) {
2793
+ const abs = (rel) => path.resolve(dir, rel)
2794
+ const settingsFile = `${stateDirLabel(config)}/review-serve.json`
2795
+ const proc = serveProcFor(config, abs(settingsFile), { root: dir })
2796
+ const pid = readPid(abs(proc.pidFile))
2797
+ if (!pid || !isAlive(pid)) return null
2798
+ let settings = null
2799
+ try {
2800
+ settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
2801
+ } catch {
2802
+ return null
2803
+ }
2804
+ if (!settings || !settings.port) return null
2805
+ return {
2806
+ port: settings.port,
2807
+ token: settings.token || null,
2808
+ loopback: settings.host === '127.0.0.1' || settings.host === 'localhost',
2809
+ }
2810
+ }
2811
+
2812
+ /**
2813
+ * The stack a re-show prints: the same tiers and `live` a render reports, from
2814
+ * the same functions, with nothing rendered and nothing started.
2815
+ */
2816
+ function reshowStack(dir, config, spec, out) {
2817
+ const cfg = withSpecRemote(config, out)
2818
+ const up = readRunningReviewServer(dir, cfg)
2819
+ const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
2820
+ const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg })
2821
+ let live = null
2822
+ try {
2823
+ const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
2824
+ live = liveStateFor(
2825
+ spec,
2826
+ liveContext(dir, cfg, spec, { onBase: primaryState.onBase, primaryBranch: primaryState.branch }),
2827
+ )
2828
+ } catch {
2829
+ // Cannot tell whether it is live — print no line rather than a wrong one.
2830
+ live = null
2831
+ }
2832
+ return { tiers, live }
2833
+ }
2834
+
2762
2835
  async function specEnvReviewWait(dir, config, specArg, flags) {
2763
2836
  let spec
2764
2837
  try {
@@ -2792,10 +2865,28 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
2792
2865
  // SAID BEFORE THE FIRST POLL, not after it. The whole point is that a caller
2793
2866
  // knows the wait is running; a line printed on the way out would arrive only
2794
2867
  // for the waits that already worked.
2868
+ //
2869
+ // WHICH START THIS IS, counted per window. A wait that dies is re-armed on the
2870
+ // same `--since`, and every re-arm leaves a trace in the conversation, so
2871
+ // after enough of them the banner and its links have scrolled out of sight.
2872
+ // Every `reshowEvery`th re-arm prints the stack again, read-only, for the
2873
+ // skill to relay as the banner.
2874
+ const reshowEvery = resolveReshowEvery(flags)
2875
+ const started = recordWaitStart(out, spec.folder, flags.since)
2876
+ const rearm = started ? started.rearm : null
2877
+ const reshow = reshowDue(rearm, reshowEvery)
2878
+ const stack = reshow ? reshowStack(dir, config, spec, out) : null
2879
+
2795
2880
  if (!flags.json) {
2796
2881
  process.stdout.write(
2797
2882
  `spec-env review wait: ${spec.folder} — waiting for a verdict sent since ${flags.since}` +
2798
- `${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}\n`,
2883
+ `${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}` +
2884
+ `${rearm ? ` (re-arm ${rearm})` : ''}\n` +
2885
+ (stack
2886
+ ? ` re-show: banner (re-arm ${rearm})\n` +
2887
+ stack.tiers.map((t) => reviewTierLine(t) + '\n').join('') +
2888
+ (liveStateLine(stack.live) ? `${liveStateLine(stack.live)}\n` : '')
2889
+ : ''),
2799
2890
  )
2800
2891
  }
2801
2892
 
@@ -2825,7 +2916,20 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
2825
2916
  })
2826
2917
 
2827
2918
  if (flags.json) {
2828
- process.stdout.write(`${JSON.stringify({ spec: spec.folder, since: flags.since, ...result }, null, 2)}\n`)
2919
+ process.stdout.write(
2920
+ `${JSON.stringify(
2921
+ {
2922
+ spec: spec.folder,
2923
+ since: flags.since,
2924
+ rearm,
2925
+ reshow,
2926
+ ...(stack ? { tiers: stack.tiers, live: stack.live } : {}),
2927
+ ...result,
2928
+ },
2929
+ null,
2930
+ 2,
2931
+ )}\n`,
2932
+ )
2829
2933
  }
2830
2934
 
2831
2935
  if (result.state === 'arrived') {
@@ -4258,6 +4362,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4258
4362
  // use, and the engine cannot know — that guess failed three separate ways
4259
4363
  // in one day. Now every tier is listed, labelled, and either a URL or the
4260
4364
  // one command that turns it on.
4365
+ // The runners-up print as `also:` lines inside the network tier's own
4366
+ // rendering — `reviewTierLine` carries them, which is what puts them
4367
+ // under `network:` rather than dangling after the stack (they used to
4368
+ // print below `remote:`, against the comment that placed them).
4261
4369
  reviewTierStack({
4262
4370
  served,
4263
4371
  fileUrl: reviewFileUrl(out),
@@ -4266,11 +4374,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4266
4374
  })
4267
4375
  .map((t) => reviewTierLine(t) + '\n')
4268
4376
  .join('') +
4269
- // The runners-up sit UNDER the network tier, because that is what they are
4270
- // alternatives to — and virtual adapters are gone from them entirely.
4271
- (served && !served.loopback && (served.alternates || []).length
4272
- ? served.alternates.map((u) => ` also: ${u}${tailnetLabel(u)}\n`).join('')
4273
- : '') +
4274
4377
  // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
4275
4378
  // `network` are two doors into one room — the page POSTs to
4276
4379
  // `location.pathname`, so both reach this server and this pending store.
@@ -4583,26 +4686,6 @@ function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
4583
4686
  .map((e) => e.address)
4584
4687
  }
4585
4688
 
4586
- // 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
4587
- //
4588
- // WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
4589
- // the same range on a utun adapter is offered too. That costs one dud `also:`
4590
- // line, where filtering it hides the only link a reader off the wifi can open.
4591
- function isTailnetAddress(address) {
4592
- const m = /^100\.(\d+)\./.exec(address)
4593
- return !!m && Number(m[1]) >= 64 && Number(m[1]) <= 127
4594
- }
4595
-
4596
- // The suffix on an `also:` line whose host is a tailnet address, so it reads
4597
- // apart from the LAN one — a reader off the wifi needs to know which to tap.
4598
- function tailnetLabel(url) {
4599
- let host = ''
4600
- try {
4601
- host = new URL(url).hostname
4602
- } catch {}
4603
- return isTailnetAddress(host) ? ' (tailnet)' : ''
4604
- }
4605
-
4606
4689
  /**
4607
4690
  * Bring the review server up, or adopt the one already running.
4608
4691
  *
@@ -5636,6 +5719,7 @@ async function specEnv(rest) {
5636
5719
  claim: null,
5637
5720
  offered: false,
5638
5721
  heartbeat: null,
5722
+ reshowEvery: null,
5639
5723
  drop: null,
5640
5724
  buttons: null,
5641
5725
  json: false,
@@ -5671,6 +5755,7 @@ async function specEnv(rest) {
5671
5755
  else if (args[i] === '--claim') flags.claim = args[++i]
5672
5756
  else if (args[i] === '--claim-since') flags.claimSince = args[++i]
5673
5757
  else if (args[i] === '--heartbeat') flags.heartbeat = args[++i]
5758
+ else if (args[i] === '--reshow-every') flags.reshowEvery = args[++i]
5674
5759
  else if (args[i] === '--since') flags.since = args[++i]
5675
5760
  else if (args[i] === '--timeout') flags.timeout = args[++i]
5676
5761
  else if (args[i] === '--drop') flags.drop = args[++i]
@@ -5850,6 +5935,7 @@ async function specEnv(rest) {
5850
5935
  ' review skip [spec] "<reason>" move on without one, on the record\n' +
5851
5936
  ' review gate [spec] --offered record that the bypass was offered (spends it)\n' +
5852
5937
  ' review wait [spec] --heartbeat <secs> proof-of-life cadence on stderr; 0 disables\n' +
5938
+ ' review wait [spec] --reshow-every <n> print the stack again every nth re-arm (5); 0 disables\n' +
5853
5939
  ' review wait [spec] --since <iso> block until a verdict arrives ([--timeout <s>])\n' +
5854
5940
  ' review waiting [--json] every pass waiting, across every spec\n' +
5855
5941
  ' review [spec] --claim-since <iso> claim the one pass that arrived since <iso>\n' +