@skitterbyte/skitterspec-linear 15.0.0 → 17.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 (59) hide show
  1. package/MIGRATION.md +218 -0
  2. package/README.md +37 -1
  3. package/assets/claude-md-section.md +42 -18
  4. package/assets/commands/allow-main.md +33 -0
  5. package/assets/commands/spec-remote-review.md +22 -0
  6. package/assets/commands/spec-skip.md +24 -0
  7. package/assets/core/SETUP.md +10 -6
  8. package/assets/core/env.config.json.example +6 -3
  9. package/assets/core/env.config.md +183 -25
  10. package/assets/core/linear.config.json.example +2 -1
  11. package/assets/core/linear.config.md +49 -22
  12. package/assets/hooks/main-guard.cjs +145 -0
  13. package/assets/hooks/review-gate.cjs +8 -3
  14. package/assets/review/page.html +1174 -101
  15. package/assets/rules/commit-trailers.md +17 -7
  16. package/assets/rules/offered-unblocks.md +100 -0
  17. package/assets/rules/spec-planning.md +195 -14
  18. package/assets/rules/spec-reports.md +181 -29
  19. package/assets/skills/no-spec/SKILL.md +219 -0
  20. package/assets/skills/spec/SKILL.md +277 -21
  21. package/assets/skills/spec-bug/SKILL.md +73 -30
  22. package/assets/skills/spec-cancel/SKILL.md +31 -2
  23. package/assets/skills/spec-claim/SKILL.md +12 -4
  24. package/assets/skills/spec-complete/SKILL.md +27 -2
  25. package/assets/skills/spec-diff/SKILL.md +164 -37
  26. package/assets/skills/spec-hotfix/SKILL.md +61 -25
  27. package/assets/skills/spec-init/SKILL.md +4 -2
  28. package/assets/skills/spec-linear-setup/SKILL.md +19 -11
  29. package/assets/skills/spec-next/SKILL.md +168 -60
  30. package/assets/skills/spec-push/SKILL.md +45 -0
  31. package/assets/skills/spec-review/SKILL.md +89 -2
  32. package/assets/skills/spec-reviewed/SKILL.md +31 -5
  33. package/assets/skills/spec-start/SKILL.md +40 -3
  34. package/assets/skills/spec-status/SKILL.md +20 -6
  35. package/assets/skills/spec-sync/SKILL.md +1 -0
  36. package/package.json +2 -2
  37. package/src/cli.js +1612 -172
  38. package/src/env/classify.js +87 -2
  39. package/src/env/config.js +333 -19
  40. package/src/env/hooks.js +102 -33
  41. package/src/env/live.js +124 -1
  42. package/src/env/mainguard.js +240 -0
  43. package/src/env/provision.js +106 -10
  44. package/src/env/registry.js +70 -6
  45. package/src/env/resolve.js +128 -5
  46. package/src/env/review.js +854 -29
  47. package/src/env/reviewers/coderabbit.js +228 -0
  48. package/src/env/reviewers.js +517 -0
  49. package/src/env/serve.js +474 -50
  50. package/src/env/supervise.js +8 -1
  51. package/src/env/teardown.js +12 -1
  52. package/src/init.js +185 -24
  53. package/src/vendor/linear/api.js +111 -2
  54. package/src/vendor/linear/cli-sync.js +661 -11
  55. package/src/vendor/linear/config.js +41 -13
  56. package/src/vendor/linear/doctor.js +6 -5
  57. package/src/vendor/sync-core/index.js +11 -3
  58. package/src/vendor/sync-core/src/compare.js +65 -0
  59. package/src/vendor/sync-core/src/normalize.js +26 -0
@@ -105,11 +105,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
105
105
  description (an **update** to the existing issue, plus a sub-issue per phase).
106
106
  Recording a snapshot here would declare the mirror already in sync and strand
107
107
  the issue showing the raw report forever.
108
+ - **Preserve the original, before anything replaces it.** Run this the moment
109
+ the spec file exists and **before the linking push**:
110
+
111
+ ```
112
+ skitterspec spec-sync preserve <spec>
113
+ ```
114
+
115
+ It posts the issue's current description onto the issue as a comment — the one
116
+ surface one-way sync never touches, so no push can clobber it. On the API path
117
+ it reads the description itself; without a key it prints the body and the
118
+ marker, and you post it with the Linear comment tool after checking the
119
+ comments for that marker.
120
+
121
+ **The ordering is the whole correctness condition.** Run before the push, this
122
+ keeps what the reporter filed. Run after it, it would keep the generated spec
123
+ and report success — which is why it is a step of its own here rather than a
124
+ line in the push sequence. The engine warns when it can tell it is late, but it
125
+ cannot always tell.
126
+
127
+ **It never fails the adoption.** A project that set
128
+ `intake.preserveOriginal: false`, an unreachable Linear, an issue with no
129
+ description, a comment Linear refused — every one of them exits 0 and says so.
130
+ Relay what it printed and carry on.
108
131
  - **Say what will happen** in the finish-up message. The linking step runs right
109
132
  after the spec is written, so the issue's description is replaced by the spec
110
- **then** — not on some later manual push. The reporter's words are not lost:
111
- they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
112
- keeps the original in the issue's history.
133
+ **then** — not on some later manual push. Say both halves: the description
134
+ becomes the spec, **and** the original is preserved as a comment on the same
135
+ issue, so the reporter can still read what they wrote.
136
+
137
+ **Do not send anyone to the issue's history for it.** This used to say Linear
138
+ keeps the original there, and that is true and useless: history is a diff
139
+ viewer nobody opens, it is not quotable, and it degrades to "it is in there
140
+ somewhere". The comment is the answer, and the other half is the spec's own
141
+ **Problem** (or **Symptom**) section quoting the reporter.
113
142
 
114
143
  ## Phase A — reach a clear shared understanding (grill first)
115
144
 
@@ -163,25 +192,56 @@ Briefly play back the agreed understanding before writing.
163
192
 
164
193
  This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
165
194
 
166
- ### Write it from the base branch
195
+ ### Write it in its own worktree
196
+
197
+ **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
198
+ present). Without it there is no worktree to make and this section does not
199
+ apply — write the folder where you are standing, exactly as before.
167
200
 
168
- **Check where you are before creating the folder.** A backlog spec belongs on
169
- the base branch (`main`). If you are on another spec's branch — most likely
170
- inside its worktree, because a design question came up part-way through
171
- implementing it — say so before writing, and offer to author the spec from the
172
- primary checkout instead.
201
+ **Provision before you write, not after.** Grilling put nothing on disk and the
202
+ spec's name is settled by the time Phase A ends, so this is the one moment where
203
+ a worktree costs nothing to obtain and everything is still ahead of it:
173
204
 
174
- It matters for more than tidiness: a spec written inside another spec's worktree
175
- **physically lives on that branch**. It is not on `main` until that spec lands,
176
- it is invisible to anyone listing `specs/backlog/` meanwhile, and if that spec is
177
- cancelled the new spec is cancelled with it. Committing it there also mis-stamps
178
- the commit's ticket trailer, since that is resolved from the branch (see
179
- `.claude/rules/commit-trailers.md`, installed with a ticketing provider).
205
+ ```
206
+ skitterspec spec-env up <name> --docs
207
+ ```
180
208
 
181
- **Warn, don't refuse** — doing this deliberately is legitimate, and the user may
182
- have a reason. If they continue, carry on exactly as normal, and mention that
183
- the trailer for that commit wants `spec-sync ref <new-spec-name>` rather than the
184
- bare form.
209
+ Run the commands it prints, then move this session into the worktree with a
210
+ plain `cd` — the Bash working directory persists between calls, so from here on
211
+ the spec is written on its own branch. Confirm the move landed rather than
212
+ reading silence as success (`.claude/rules/negative-checks.md` rule 1):
213
+ `skitterspec spec-env resolve` with no argument must name this spec. If it does
214
+ not, say so and write the spec where you are standing instead; a spec in the
215
+ wrong tree is worse than a spec with no worktree.
216
+
217
+ **`--docs` is what makes this cheap.** It skips the `setup` commands and the
218
+ Docker stack — everything whose only purpose is making a tree *runnable* — so
219
+ provisioning a worktree to write markdown in is a `git worktree add` and nothing
220
+ else. `/spec-start` re-runs `up` over the same worktree without the flag, and the
221
+ setup runs then, at the first moment the tree is used for code.
222
+
223
+ **Why the base branch is no longer where this happens.** `main` is where work
224
+ **lands**, not where it happens. Authoring on it meant the spec sat uncommitted
225
+ there for as long as Phase C2's page went unanswered — which is unbounded by
226
+ design, because a reader walking away from a diff is the normal case — and a
227
+ release could not be cut through it. The verdict lands the spec instead, so
228
+ `main` gains it as one commit and is never dirty on the way.
229
+
230
+ **A spec written in ANOTHER spec's worktree is still the mistake it always was**,
231
+ and this section does not soften that. It physically lives on that branch: not on
232
+ `main` until that spec lands, invisible to anyone listing `specs/backlog/`
233
+ meanwhile, and cancelled along with its host. Committing it there also mis-stamps
234
+ the ticket trailer, which is resolved from the branch (see
235
+ `.claude/rules/commit-trailers.md`, installed with a ticketing provider). The
236
+ difference is whose worktree: **its own** is now the normal path, and someone
237
+ else's is the accident.
238
+
239
+ So if Phase A ran inside another spec's worktree — most likely because a design
240
+ question came up part-way through implementing it — the provision above is the
241
+ fix rather than something to warn about: it moves the session out of that tree
242
+ and into this spec's own. Where isolation is off and there is no worktree to
243
+ move to, **warn, don't refuse**, and say the trailer for that commit wants
244
+ `spec-sync ref <new-spec-name>` rather than the bare form.
185
245
 
186
246
  - **Every spec is a folder** — never a bare file, even for a one-line change:
187
247
  `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
@@ -339,6 +399,157 @@ open questions, `Draft` when you deliberately left some unresolved. Either way
339
399
  the next step is `/spec-start`. The Report section below is where all of that
340
400
  reaches the user — do not narrate it here as well.
341
401
 
402
+ ## Phase C2 — render the spec, then wait for the verdict
403
+
404
+ **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
405
+ present). Without it there is no page and this phase does not exist — skip it in
406
+ silence rather than explaining an absence.
407
+
408
+ A spec is the one artefact whose whole purpose is to be
409
+ **read before work begins**, and until now it was the only one with no reading
410
+ surface: `/spec`
411
+ finished, the spec sat uncommitted, and `/spec-start` had to point that out and
412
+ commit it as a side effect of provisioning. So this phase ends where every other
413
+ phase of the lifecycle ends — on a page, in a verdict.
414
+
415
+ ```
416
+ skitterspec spec-env review <spec> --docs --buttons authoring
417
+ ```
418
+
419
+ `--docs` reads the spec's own documents from the tree you are standing in, which
420
+ after Phase B is **this spec's own worktree**. It renders
421
+ **this spec's documents and nobody else's**: the `owned` half of
422
+ `spec-env stage` is what supplies the file set, and it stays load-bearing even
423
+ now that the tree holds one spec — a project's `spec.companionPaths` and a
424
+ hand-edited `specs/.core/` both land in the same tree, and only the spec's own
425
+ documents belong under this verdict.
426
+
427
+ **This is free.** The engine reads git and splices text into a template; the
428
+ diff never passes through you.
429
+
430
+ **Never pass `--run-reviewers` here.** A spec is prose, and the reviewers
431
+ `review.reviewers` names read code — spending a rate-limited review on a
432
+ paragraph buys nothing. The engine refuses it on a `--docs` render whatever this
433
+ skill asks for, so this is a note about intent rather than a guard you are
434
+ holding: do not add the flag on the assumption that it was an oversight.
435
+
436
+ **Render nothing when nothing was written.** A `⏸` run — grilling that never
437
+ reached a shared understanding — has no spec to show, and must not ask for a
438
+ verdict on one.
439
+
440
+ **Arm nothing.** There is no `spec-env review arm` in this path, and that is a
441
+ decision rather than an omission: the gate asserts that *a phase which ended*
442
+ owes an answer, and a backlog spec owes no phase. A `/spec` run must leave
443
+ `spec-env review gate --check` exiting 0.
444
+
445
+ **And walking away from this page now costs nobody anything**, which is a
446
+ stronger reason than the one that used to sit here. It read *"the spec is simply
447
+ still uncommitted, which `/spec-start` already handles"* — true, and a
448
+ concession: an uncommitted spec meant a dirty base branch, which is everyone's
449
+ problem, so "arm nothing" was tolerating a mess rather than describing a clean
450
+ state. Since Phase B the unanswered spec sits on its own branch in its own
451
+ worktree, where it is in nothing's way: no release is blocked, no other spec has
452
+ to replay over it, and it is still exactly where it was tomorrow morning.
453
+
454
+ ### The two endings this page offers
455
+
456
+ `--buttons authoring` offers `Commit & Start` and `Commit` in place of the
457
+ committing pair, because "commit and build the next phase" is meaningless for a
458
+ spec with no phase in flight.
459
+
460
+ - **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
461
+ passing the pathspec the render reported on `docs.paths`; **land it** (below);
462
+ then **keep the worktree** and run **`/spec-start <name>`**, and **stop there**.
463
+ It never completes or tears anything down, exactly as `commit-continue` stops
464
+ after `/spec-next`. This is the `commit && /spec-start` that was typed by hand.
465
+ - **`commit`** — the same commit and the same land, then
466
+ **tear the worktree down** and finish. The spec stays `Ready` in `backlog` —
467
+ on the base branch, where anyone can see it — ready for a `/spec-start`
468
+ whenever it is wanted.
469
+
470
+ **Both committing verdicts land, and that is what keeps the backlog findable.**
471
+ `ls specs/backlog/` is how specs are found, and a folder bucket is only the truth
472
+ on the branch you are standing on — so a spec left on its own branch would be
473
+ invisible to everyone, including the next `/spec` run. The commit goes on the
474
+ branch and then the branch goes onto the base:
475
+
476
+ ```
477
+ skitterspec spec-env integrate <name>
478
+ ```
479
+
480
+ It plans a rebase onto the base branch in the worktree, then a
481
+ `merge --ff-only` in the primary checkout — run the commands it prints. It
482
+ refuses on a dirty tree, which is correct here: the commit ran first, so anything
483
+ still uncommitted at this point is not this spec's and the land must not proceed.
484
+
485
+ **If the rebase conflicts, stop and say so.** It is unlikely on a
486
+ documents-only branch and not impossible — two specs authored at once can both
487
+ touch `specs/.core/`. Run `git rebase --abort`, leave the commit sitting on the
488
+ branch, and report `❌` with the conflict: there is a standing worktree to clear,
489
+ which is what separates `❌` from `⏸`. Never resolve someone else's conflict to
490
+ get the land through.
491
+
492
+ **The worktree lifetime follows the verdict, and the asymmetry is deliberate.**
493
+ `commit-start` keeps it because you are carrying straight on, and `/spec-start`
494
+ re-runs `up` over it without `--docs` — which is where the setup commands
495
+ Phase B skipped finally run. Plain `commit` tears it down with
496
+ `skitterspec spec-env down <name>`, because a spec parked in the backlog should
497
+ hold no worktree and no `node_modules`; `/spec-start` provisions from scratch
498
+ whenever it is wanted. Always-keep would leave five backlog specs holding five
499
+ checkouts, and always-teardown would have `commit-start` re-provision seconds
500
+ after destroying the tree it needed.
501
+ - **`changes`** — work the notes into the spec, record a resolution for each one
502
+ so the next render shows it struck through with what changed, then
503
+ **re-render, and wait again**. The reader is still holding a decision, so
504
+ ending the turn and
505
+ making them type `/spec-diff` would reopen the loop this exists to close.
506
+ - **`discuss`** — report and talk. Claim nothing, change nothing.
507
+
508
+ **Take the pathspec from the render, not from the tree.** A checkout is shared,
509
+ so the set of this spec's uncommitted documents can differ between the render and
510
+ the verdict — and the reader's conclusion is about what the page showed them.
511
+
512
+ ### Then wait for it
513
+
514
+ **The wait is a command. Do not write one.**
515
+
516
+ 1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
517
+ the whole scope of what you may claim.
518
+ 2. **Run the engine's wait in the background, and end your turn:**
519
+
520
+ ```
521
+ skitterspec spec-env review wait <spec> --since <the timestamp>
522
+ ```
523
+
524
+ It takes no timeout unless you pass one, and you must not pass one: a reader
525
+ who walks away from a spec is the normal case, and a bounded watch once lost a
526
+ verdict to a lunch break.
527
+ 3. **On waking, let the engine pick:**
528
+
529
+ **A watch that dies is re-armed on the same window**, silently and bounded by
530
+ the age of that window — `.claude/rules/spec-reports.md` carries the contract,
531
+ including when to stop and what the banner says instead. Do not restate it
532
+ here.
533
+
534
+ ```
535
+ skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
536
+ ```
537
+
538
+ It claims the one pass that arrived inside the window, acts on nothing when
539
+ none did, and refuses to choose when two did.
540
+ 4. **Route on the verdict** as above.
541
+
542
+ **Where the page is `file://`** — the engine could not serve — there is no server
543
+ to POST to, so the pass is copied and pasted and the reader's next message is
544
+ what carries it. **Do not start a watch that cannot fire**: a wait on the pending
545
+ store would spin forever while the report underneath it claimed to be holding,
546
+ which is the exact failure `.claude/rules/spec-reports.md` records. The wait is
547
+ the turn ending, and the banner says so.
548
+
549
+ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
550
+ three, in that order — never the bare `page:` path. `.claude/rules/spec-reports.md`
551
+ carries the shape and why every tier is named rather than one being chosen.
552
+
342
553
  ## Phase D — record the isolation stack (only if configured)
343
554
 
344
555
  **Only when `specs/.core/env.config.json` exists** (per-spec isolation is
@@ -461,16 +672,61 @@ the shape; this section carries only what is specific here.
461
672
 
462
673
  - `✅` — a `Ready` spec is written to `specs/backlog/<name>/`.
463
674
  - `⚠️` — written as `Draft`; open questions were deliberately left. Name them.
675
+ - `❌` — the spec was committed and the land failed part-way: the rebase
676
+ conflicted, or the fast-forward was refused. There is a standing worktree and a
677
+ branch to deal with, so say where both are.
464
678
  - `⏸` — grilling did not reach a shared understanding, so nothing was written.
465
679
  That is the skill working: a spec written over an unresolved requirement is
466
680
  the outcome Phase A exists to prevent.
467
681
 
468
- **Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
682
+ **Fields:** `Tracker` · `Spec` · `Built` · `Landed` · `Worktree` · `Follow-ups` ·
683
+ `Next`
469
684
 
470
685
  `Built` is the spec's path and phase count; `Spec` is its status and bucket;
471
- `Next` is `/spec-start <name>`, with the name spelled the way it must be typed.
472
686
  `Tracker` appears only when a provider is installed and linked it.
473
687
 
688
+ `Landed` and `Worktree` belong to the **verdict** half of the run and appear
689
+ only once one has been acted on — a run that is still waiting on the page has
690
+ neither. `Landed` says the base branch fast-forwarded and to what; `Worktree`
691
+ says kept (on `commit-start`) or removed (on `commit`), with the path. Neither
692
+ appears where isolation is off: nothing was provisioned and nothing was landed.
693
+
694
+ **`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
695
+ waiting on a verdict, so the block **omits the `Review` row** and ends on the
696
+ banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
697
+ this page's two exits:
698
+
699
+ ---
700
+
701
+ ## ⏸ Review ready — &lt;N&gt; files, +&lt;a&gt; −&lt;d&gt;
702
+
703
+ - **local** — &lt;the `local:` URL&gt;
704
+ - **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
705
+ - **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
706
+
707
+ I'm holding here until you send a verdict — the wait covers local and network.
708
+
709
+ `Commit & Start` puts it in flight · `Commit` keeps it for later
710
+
711
+ ---
712
+
713
+ There `Next` names the page rather than a command, because the button is what
714
+ carries the work on.
715
+
716
+ **Neither exit leaves the spec anywhere awkward**, and the banner does not
717
+ explain that — the whole point of Phase B is that there is nothing to warn
718
+ about. Both buttons commit and land, so either way the spec reaches the base
719
+ branch as one commit; the only difference is whether the worktree stays.
720
+
721
+ Where no page was rendered — isolation is not configured, or nothing was
722
+ written — `Next` is `/spec-start <name>`, with the name spelled the way it must
723
+ be typed.
724
+
725
+ **A spec written without a page is still uncommitted**, so that `Next` relies on
726
+ `/spec-start` committing the spec when it is all that is uncommitted. Say
727
+ `/commit, then /spec-start <name>` when anything else is uncommitted too, or the
728
+ row sends the reader to a refusal.
729
+
474
730
  **`Follow-ups` is almost always `none` here.** This skill's whole job is to
475
731
  capture work, so anything it surfaced belongs in the spec it just wrote rather
476
732
  than in a follow-up line beneath it.
@@ -104,11 +104,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
104
104
  description (an **update** to the existing issue, plus a sub-issue per phase).
105
105
  Recording a snapshot here would declare the mirror already in sync and strand
106
106
  the issue showing the raw report forever.
107
+ - **Preserve the original, before anything replaces it.** Run this the moment
108
+ the spec file exists and **before the linking push**:
109
+
110
+ ```
111
+ skitterspec spec-sync preserve <spec>
112
+ ```
113
+
114
+ It posts the issue's current description onto the issue as a comment — the one
115
+ surface one-way sync never touches, so no push can clobber it. On the API path
116
+ it reads the description itself; without a key it prints the body and the
117
+ marker, and you post it with the Linear comment tool after checking the
118
+ comments for that marker.
119
+
120
+ **The ordering is the whole correctness condition.** Run before the push, this
121
+ keeps what the reporter filed. Run after it, it would keep the generated spec
122
+ and report success — which is why it is a step of its own here rather than a
123
+ line in the push sequence. The engine warns when it can tell it is late, but it
124
+ cannot always tell.
125
+
126
+ **It never fails the adoption.** A project that set
127
+ `intake.preserveOriginal: false`, an unreachable Linear, an issue with no
128
+ description, a comment Linear refused — every one of them exits 0 and says so.
129
+ Relay what it printed and carry on.
107
130
  - **Say what will happen** in the finish-up message. The linking step runs right
108
131
  after the spec is written, so the issue's description is replaced by the spec
109
- **then** — not on some later manual push. The reporter's words are not lost:
110
- they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
111
- keeps the original in the issue's history.
132
+ **then** — not on some later manual push. Say both halves: the description
133
+ becomes the spec, **and** the original is preserved as a comment on the same
134
+ issue, so the reporter can still read what they wrote.
135
+
136
+ **Do not send anyone to the issue's history for it.** This used to say Linear
137
+ keeps the original there, and that is true and useless: history is a diff
138
+ viewer nobody opens, it is not quotable, and it degrades to "it is in there
139
+ somewhere". The comment is the answer, and the other half is the spec's own
140
+ **Problem** (or **Symptom**) section quoting the reporter.
112
141
 
113
142
  ## 1. Reproduce & isolate (light investigation)
114
143
 
@@ -309,10 +338,14 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
309
338
  events later. Report the Linear issue URL as part of the skill's finish-up
310
339
  message.
311
340
 
312
- **Only when all three hold**: `specs/.core/linear.config.json` exists, its
313
- `sync.fieldOwnership` includes `assignee`, and the spec carries a
341
+ **Only when all three hold**: `specs/.core/linear.config.json` exists, the repo
342
+ **owns** `assignee` in its `sync.fieldOwnership`, and the spec carries a
314
343
  `linear_identifier`. Any one missing → skip this step silently and carry on; a
315
- project that has not opted in must see no trace of assignment.
344
+ project that declined must see no trace of assignment.
345
+
346
+ Ownership is the **value**, not the key: `assignee` is owned by default, and
347
+ `"none"` is how a project declines it. Testing whether the key is *present* would
348
+ read as opted-in everywhere, since the default puts it in every config.
316
349
 
317
350
  **Never blocks, never fails the skill.** Everything below is best-effort: the
318
351
  branch is provisioned and the spec is moving either way, and an unassigned issue
@@ -474,11 +507,18 @@ skitterspec spec-env review arm <spec>
474
507
  ```
475
508
 
476
509
  **Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
477
- than reading a second copy here: note the moment you start waiting, watch the
478
- pending store, end your turn, and let `--claim-since` pick the one pass that
479
- arrived inside the window. The banner it describes is what this skill emits in
480
- place of a `Review` row, and the routing on the verdict is `/spec-diff` §2 and
481
- §4, as it is everywhere.
510
+ than reading a second copy here: note the moment, run
511
+ `skitterspec spec-env review wait <spec> --since <that moment>` in the
512
+ background, end your turn, and let `--claim-since` pick the one pass that
513
+ arrived inside the window. **Do not compose a watcher**, and do not give the
514
+ wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
515
+ The banner it describes is what this skill emits in place of a `Review` row,
516
+ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
517
+
518
+ **A watch that dies is re-armed on the same window**, silently and bounded by
519
+ the age of that window — `.claude/rules/spec-reports.md` carries the contract,
520
+ including when to stop and what the banner says instead. Do not restate it
521
+ here.
482
522
 
483
523
  **Why this skill arms as well as waits.** Waiting is what any offer does;
484
524
  **arming** asserts an obligation that outlives the turn, and belongs only to
@@ -499,30 +539,33 @@ this worktree is refused until a verdict is sent or
499
539
  `skitterspec spec-env review skip "<reason>"` records the decision to move on.
500
540
  The exit is always one command, and one of them is *"I am moving on"*.
501
541
 
502
- Relay the **`open:`** line rather than the bare path: a path is not clickable in
503
- any terminal, and a page nobody can open is a page nobody reads.
542
+ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
543
+ three — rather than the bare `page:` path: a path is not clickable in any
544
+ terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
545
+ line with it where the engine printed one, and nothing where it did not.
546
+ `.claude/rules/spec-reports.md` carries the shape, including why a rigid
547
+ contract took that line.
504
548
 
505
549
  - **Never write the review unasked**, and **never publish**. Publishing leaves
506
550
  something behind that this tooling cannot remove, so it is always an ask. A
507
551
  `file://` link is no use on a phone, and saying so **is** the ask —
508
552
  `/spec-diff` §6 owns how.
509
- **Follow the `reader:` line the engine printed — do not sniff for it.** It
510
- answers where the person reading this is sitting, and the offer changes with it:
511
-
512
- - **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
513
- unknown is the ordinary state of a local machine, and a warning there is an
514
- accusation against a healthy session.
515
- - **`local`** — the `file://` URL.
516
- - **`remote`** — the engine has already stood its local server up and put a URL
517
- the reader can open on `open:`. So there is **nothing special to say**: relay
518
- that line like any other. Any `also:` lines under it are the other addresses
519
- this machine has, offered because the best-guess one can be wrong — pass them
520
- on rather than editing them out.
521
-
522
- **Never read an environment variable to decide this** — not `SSH_CONNECTION`,
523
- not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
524
- and in `--json`, and a second implementation here could not be tested and would
525
- drift.
553
+ **The `reader:` line no longer decides anything here, and that is the point.**
554
+ It is still printed, and it is still the only place that question is answered —
555
+ but the offer does not change with it, because the stack lists every tier
556
+ whatever it says. Three reader states used to mean three different offers, and
557
+ that branching is exactly what produced a `file://` page on a session detected
558
+ `unknown`, a LAN URL for a phone off the network, and an address that changed
559
+ underneath a reader when detection flipped mid-session.
560
+
561
+ So: **relay all three tier lines, every time.** Any `also:` lines sit under
562
+ `network` — the other addresses this machine has, offered because the
563
+ best-guess one can be wrong — so pass them on rather than editing them out.
564
+
565
+ **Never read an environment variable to decide anything about the offer** — not
566
+ `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
567
+ here for a detection to decide, and a second implementation of one could not be
568
+ tested and would drift.
526
569
 
527
570
  **Serving is the engine's to do; publishing is never.** A `remote` reader
528
571
  authorises a local server — one process, ended by one flag, leaving nothing
@@ -76,8 +76,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
76
76
  Do not roll anything back, and do not stop to ask.
77
77
  - **Say what happened** in the skill's report: mirror updated, skipped as
78
78
  unlinked, or failed with the reason.
79
- - **There is no unassign step, and that is not an omission.** With `assignee` in
80
- `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
79
+ - **There is no unassign step, and that is not an omission.** Where the repo owns
80
+ `assignee`, the projection derives it from the spec's lifecycle
81
81
  bucket — so moving the folder to `complete`/`cancelled` is *itself* what
82
82
  releases the issue, and the push above carries it like any other field. The
83
83
  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
@@ -158,6 +158,35 @@ of the work, so an unreclaimed one is worth a line rather than a silence.
158
158
  reclaim the cancelled spec's environment. On confirmation, run the `spec-env` CLI
159
159
  directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
160
160
 
161
+ 0. **Name a pass still waiting for THIS spec — before anything is removed.**
162
+
163
+ ```
164
+ skitterspec spec-env review waiting --json
165
+ ```
166
+
167
+ Filter to the spec being cancelled and say nothing about any other: a run
168
+ reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
169
+ one, give the code, the verdict and the age, then the two exits — claim it
170
+ now with `/spec-reviewed <code>` **while the worktree still stands**, or
171
+ disown it with `skitterspec spec-env review <spec> --drop <code>`.
172
+
173
+ **Why here and not anywhere else.** Nothing is about to become unreachable —
174
+ a pass can be disowned long after its spec is gone. What is about to pass is
175
+ the last moment the verdict can still be **honoured**: before teardown a
176
+ `commit` pass can be claimed and acted on, after it there is no branch left
177
+ to commit to and disowning is all that remains. On a cancelled spec that is
178
+ sharper still — the worktree may hold the only copy of the work, so a pass
179
+ approving it is the one thing that might argue for keeping it.
180
+
181
+ **It reports, and it never blocks.** No refusal, no confirmation of its own,
182
+ no non-zero exit — this step already asks before it reclaims anything, and a
183
+ waiting pass is information rather than a second gate.
184
+ And **it never claims** — reporting a pass is not taking one, and
185
+ `/spec-diff` §0 is untouched by this step.
186
+
187
+ Put what you found in the report's `Notes` row.
188
+ Silent when nothing is waiting, which is the usual case.
189
+
161
190
  1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
162
191
  main` first to free the canonical ports.
163
192
  2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-claim
3
- description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
3
+ description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with the repo owning assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
@@ -16,9 +16,17 @@ and the push that follows tells Linear. This skill is how that record changes
16
16
  after `/spec-start` has set it — a hand-off mid-flight, a spec picked up from
17
17
  someone who moved on, or work a lead is distributing.
18
18
 
19
- **Opt-in.** Needs `specs/.core/linear.config.json` *and* `assignee` in its
20
- `sync.fieldOwnership`. If either is missing, say which one and stop — without the
21
- field the stamp would sit in the file doing nothing.
19
+ **Opt-in.** Needs `specs/.core/linear.config.json` *and* the repo to **own**
20
+ `assignee` in its `sync.fieldOwnership` — which `"none"` declines as surely as
21
+ omitting it does. If either is missing, say which one and stop: without the field
22
+ the stamp would sit in the file doing nothing.
23
+
24
+ **The engine refuses this too, and that is the point.** `spec-sync assign` checks
25
+ the same thing and writes nothing, so the rule holds for a script, a chained
26
+ command, and anyone who reached for the CLI directly. This paragraph was the only
27
+ thing enforcing it for long enough that the engine's own success line —
28
+ `next: push it, so Linear agrees` — was printed over a push that would drop the
29
+ field. Prose in one skill is not a guard; it is a guard's documentation.
22
30
 
23
31
  ## 1. Identify the target spec
24
32
 
@@ -95,8 +95,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
95
95
  Do not roll anything back, and do not stop to ask.
96
96
  - **Say what happened** in the skill's report: mirror updated, skipped as
97
97
  unlinked, or failed with the reason.
98
- - **There is no unassign step, and that is not an omission.** With `assignee` in
99
- `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
98
+ - **There is no unassign step, and that is not an omission.** Where the repo owns
99
+ `assignee`, the projection derives it from the spec's lifecycle
100
100
  bucket — so moving the folder to `complete`/`cancelled` is *itself* what
101
101
  releases the issue, and the push above carries it like any other field. The
102
102
  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
@@ -275,6 +275,31 @@ nothing left to protect.
275
275
  worktree and branch are being kept, and go straight to sub-step 4. Mention
276
276
  `skitterspec spec-env up <name>` re-attaches it later either way.
277
277
 
278
+ 0. **Name a pass still waiting for THIS spec — before anything is removed.**
279
+
280
+ ```
281
+ skitterspec spec-env review waiting --json
282
+ ```
283
+
284
+ Filter to the spec being completed and say nothing about any other: a run
285
+ reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
286
+ one, give the code, the verdict and the age, then the two exits — claim it
287
+ now with `/spec-reviewed <code>` **while the worktree still stands**, or
288
+ disown it with `skitterspec spec-env review <spec> --drop <code>`.
289
+
290
+ **Why here and not anywhere else.** Nothing is about to become unreachable —
291
+ a pass can be disowned long after its spec is gone. What is about to pass is
292
+ the last moment the verdict can still be **honoured**: before teardown a
293
+ `commit` pass can be claimed and acted on, after it there is no branch left
294
+ to commit to and disowning is all that remains.
295
+
296
+ **It reports, and it never blocks.** No refusal, no confirmation of its own,
297
+ no non-zero exit. And **it never claims** — reporting a pass is not taking
298
+ one, and `/spec-diff` §0 is untouched by this step.
299
+
300
+ Put what you found in the report's `Notes` row.
301
+ Silent when nothing is waiting, which is the usual case.
302
+
278
303
  1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
279
304
  names this spec, run `skitterspec spec-env connect main` first so the
280
305
  canonical ports go back to the primary checkout.