@skitterbyte/skitterspec-linear 19.16.0 → 19.18.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.
@@ -689,10 +689,9 @@ line with it where the engine printed one, and nothing where it did not.
689
689
  `.claude/rules/spec-reports.md` carries the shape, including why a rigid
690
690
  contract took that line.
691
691
 
692
- - **Never write the review unasked**, and **never publish**. Publishing leaves
693
- something behind that this tooling cannot remove, so it is always an ask. A
694
- `file://` link is no use on a phone, and saying so **is** the ask —
695
- `/spec-diff` §6 owns how.
692
+ - **Never write the review unasked**, and **never publish** — there is no
693
+ publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
694
+ stack says why nothing was served.
696
695
  **The `reader:` line no longer decides anything here, and that is the point.**
697
696
  It is still printed, and it is still the only place that question is answered —
698
697
  but the offer does not change with it, because the stack lists every tier
@@ -702,22 +701,20 @@ that branching is exactly what produced a `file://` page on a session detected
702
701
  underneath a reader when detection flipped mid-session.
703
702
 
704
703
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
705
- `network` — the other addresses this machine has, offered because the
706
- best-guess one can be wrong — so pass them on rather than editing them out: in
707
- the banner they are indented sub-bullets under **network**, labels
708
- (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
704
+ their tier — the other addresses this machine has of that kind — so pass them
705
+ on rather than editing them out: in the banner they are indented sub-bullets
706
+ under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
707
+ shows.
709
708
 
710
709
  **Never read an environment variable to decide anything about the offer** — not
711
710
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
712
711
  here for a detection to decide, and a second implementation of one could not be
713
712
  tested and would drift.
714
713
 
715
- **Serving is the engine's to do; publishing is never.** A `remote` reader
714
+ **Serving is the engine's to do, and there is nothing else.** A `remote` reader
716
715
  authorises a local server — one process, ended by one flag, leaving nothing
717
- behind — and authorises nothing else. Publishing leaves a page this tooling
718
- cannot remove, so it stays an ask in every case, always. If the engine could not
719
- serve (a busy port, a machine with no network address) it falls back to the
720
- `file://` URL with its marker, and that is when publishing is worth naming.
716
+ behind. If the engine could not serve (a busy port, a machine with no network
717
+ address) it falls back to the `file://` URL with its marker.
721
718
 
722
719
  - **Never fatal.** A failed render — no worktree, a git error — is one line, and
723
720
  the fix is still done. The page is a convenience; the repo is the record.
@@ -50,8 +50,10 @@ evidence.
50
50
  Otherwise resolve **in this order**, and stop at the first that answers:
51
51
 
52
52
  1. **The live spec of this checkout** — run
53
- `skitterspec spec-env live status` and read its `live:` line. `live: yes`
54
- names the spec whose branch is checked out here; that is the one to build.
53
+ `skitterspec spec-env live status` and read its `in-flight:` line. A spec
54
+ name there is the spec whose branch is checked out here; that is the one to
55
+ build. `none` and `unknown` answer nothing — carry on down the list. (The
56
+ bare report's first line is a bare `spec-env live:` header, not an answer.)
55
57
  2. **The worktree you are standing in** — if this session's cwd is inside a
56
58
  spec's worktree, that spec is in flight *for this session*. This is the
57
59
  manual-parallel path: several specs may be provisioned, and a terminal tab
@@ -62,10 +64,17 @@ Otherwise resolve **in this order**, and stop at the first that answers:
62
64
  named, from wherever you happen to be standing:
63
65
 
64
66
  ```
65
- skitterspec spec-env resolve
67
+ skitterspec spec-env resolve --json
66
68
  ```
67
69
 
68
- Take its `spec:` line **only when it names exactly one spec**.
70
+ Take its `spec` **only when it names exactly one spec** (`ok: true`); `via`
71
+ says which rung answered.
72
+
73
+ From the primary checkout that includes the spec `/spec-live main` last
74
+ released here (`via: "last-live"`): releasing leaves the session standing
75
+ in the primary checkout, which says nothing on its own, so the engine
76
+ remembers the spec it handed back — for as long as that spec's worktree
77
+ exists — ahead of counting worktrees.
69
78
 
70
79
  This is the **durable** rung, and that is the whole reason it exists. Rungs 1
71
80
  to 3 all read *session* state, and session state does not survive a `/clear`,
@@ -81,13 +90,14 @@ Otherwise resolve **in this order**, and stop at the first that answers:
81
90
  `.claude/rules/spec-planning.md` states has none left.
82
91
 
83
92
  **Say which spec you resolved and how**, before writing a line of it:
84
- *"not standing in a worktree — `<spec>` is the only spec provisioned"*. Rungs
93
+ *"not standing in a worktree — `<spec>` is the only spec provisioned"*, or
94
+ *"`<spec>` was last live on this checkout"*. Rungs
85
95
  1 to 3 are self-evident to whoever typed the command; this one is not, and
86
96
  the operator cannot see from where they sit what you picked.
87
97
 
88
- **Several worktrees stay a refusal.** The engine names them and resolves
89
- nothing — exactly the ambiguity the refusal below exists for. Relay its list
90
- unchanged and stop; never pick from it.
98
+ **Several worktrees stay a refusal.** The engine answers `ok: false` with
99
+ `reason: "ambiguous"` and lists the `candidates`, each with its `worktree`,
100
+ and resolves nothing. Relay that list unchanged and stop; never pick from it.
91
101
 
92
102
  WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is still
93
103
  a worktree, so a finished spec can go on counting as provisioned. That widens
@@ -96,10 +106,18 @@ Otherwise resolve **in this order**, and stop at the first that answers:
96
106
  manufacture an *absence*, which is why the absence below is still worth
97
107
  refusing on.
98
108
 
99
- **If none answers, refuse and stop:**
100
- `no spec in flight — run /spec-start <name> to start one`.
109
+ **If none answers, refuse and stop — and say which absence it is.** Rung 4's
110
+ `reason` tells them apart, and they send the reader to different places:
111
+
112
+ - **`reason: "none"`** — no spec has a worktree anywhere:
113
+ `no spec in flight — run /spec-start <name> to start one`.
114
+ - **`reason: "ambiguous"`** — several specs are in flight and this session is
115
+ standing in none of them: `several specs are in flight and this session is
116
+ not in one of them`, then the candidates as the engine listed them (spec and
117
+ worktree), and `/spec-next --worktree <path>` as the way to name one.
118
+ `/spec-start` is wrong here: every one of them is already started.
101
119
 
102
- That now answers a real absence — no worktree anywhere, the engine included —
120
+ The first answers a real absence — no worktree anywhere, the engine included —
103
121
  rather than a session that merely lost track of where it was standing.
104
122
 
105
123
  **Never fall back to the spec "in context".** A spec discussed in conversation
@@ -340,6 +358,13 @@ plain markdown list in the conversation — never fenced, and
340
358
  out of the terminal to find out what to do, which is the failure this exists to
341
359
  fix; the steps themselves are what they act on.
342
360
 
361
+ **Steps you had to write are saved first.** When the phase file holds only a
362
+ vague manual task — "check it on the running host" — and you wrote the steps
363
+ yourself, add them under that task as numbered sub-checkboxes **before** you
364
+ ask. The conversation does not survive a `/clear`, and a later run that makes
365
+ up its own set lists different steps from the ones the reader was shown. A
366
+ phase whose manual steps are already tasks is left as it is.
367
+
343
368
  Then ask one question, with three answers:
344
369
 
345
370
  - **All done** — tick those steps and carry on to the end of the phase.
@@ -358,6 +383,8 @@ needs no new shape in the report.
358
383
  tasks after an unconfirmed step are not built past it, and the phase did not
359
384
  end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
360
385
  End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
386
+ Its `Next` lists the open steps a row each, copied from the phase file —
387
+ `.claude/rules/spec-reports.md`, *Open manual steps are rows*.
361
388
 
362
389
  ## 4. Record progress
363
390
 
@@ -493,11 +520,11 @@ so one subject lives in one place:
493
520
 
494
521
  - **local** — <the `local:` URL>
495
522
  - **network** — <the `network:` URL, or off with the command that turns it on>
496
- - **remote** — <the `remote:` URL, or off with the command that turns it on>
523
+ - **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
497
524
 
498
525
  <the `live:` line, exactly as the engine printed it — omitted when it printed none>
499
526
 
500
- I'm holding here until you send a verdict — the wait covers local and network.
527
+ I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
501
528
 
502
529
  `/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
503
530
 
@@ -518,22 +545,14 @@ reviewer sees the heading they have always seen.
518
545
  printed one line per tier, in that order, and `--json` carries the same thing as
519
546
  `tiers`. Relay all three whatever they say, including the ones that are off with
520
547
  the command that turns them on: a reader who has left the house cannot ask for a
521
- remote page they were never shown.
548
+ remote door they were never shown.
522
549
 
523
550
  **Do not pick one for them.** The engine used to, and the guess failed three
524
551
  separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
525
552
  why the *one link, never two* rule now reads
526
- **one link per reachable store, each labelled** —
527
- local and network are two doors into one room, so the wait
528
- covers both. `remote` is a second store, so its own line carries its own caveat:
529
- *a verdict here needs `/spec-reviewed`*, because nothing pushes from
530
- the artifact store into this conversation. Never let the holding line promise a
531
- wait over that tier.
532
-
533
- **Publishing is still never yours to do.** `remote` reading `off` is the normal
534
- state, and the fix for it is the command on that line — typed by the operator,
535
- or pressed on the page, because a published page is one this tooling cannot
536
- remove and permitting it is not publishing it.
553
+ **one link per door, each labelled, all into one store** —
554
+ local, network and remote are three doors into one room, so the wait
555
+ covers every one the stack shows.
537
556
 
538
557
  **The `live:` line goes with the stack**, and it is the engine's line too —
539
558
  copied as printed, and **absent when the engine printed none**. The page can act
@@ -548,7 +567,7 @@ verdict.
548
567
  **Where you are not waiting, it stays the `Review` row** — the counts and the
549
568
  page link, and **no question**:
550
569
 
551
- | **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
570
+ | **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** <URL> (tailnet) |
552
571
 
553
572
  At the end of a phase you are always waiting, so this shape belongs to the
554
573
  renders that are not this step: a mid-phase `/spec-diff`, a page produced
@@ -662,10 +681,9 @@ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines
662
681
  never the bare `page:` path: a path is not clickable in any terminal, and a page
663
682
  nobody can open is a page nobody reads.
664
683
 
665
- - **Never write the review unasked**, and **never publish**. Publishing leaves
666
- something behind that this tooling cannot remove, so it is always something
667
- someone asks for. A `file://` link is no use on a phone, and saying so **is**
668
- the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
684
+ - **Never write the review unasked**, and **never publish** — there is no
685
+ publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
686
+ stack says why nothing was served.
669
687
  **The `reader:` line no longer decides anything here, and that is the point.**
670
688
  It is still printed, and it is still the only place that question is answered —
671
689
  but the offer does not change with it, because the stack lists every tier
@@ -675,23 +693,20 @@ that branching is exactly what produced a `file://` page on a session detected
675
693
  underneath a reader when detection flipped mid-session.
676
694
 
677
695
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
678
- `network` — the other addresses this machine has, offered because the
679
- best-guess one can be wrong — so pass them on rather than editing them out: in
680
- the banner they are indented sub-bullets under **network**, labels
681
- (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
696
+ their tier — the other addresses this machine has of that kind — so pass them
697
+ on rather than editing them out: in the banner they are indented sub-bullets
698
+ under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
699
+ shows.
682
700
 
683
701
  **Never read an environment variable to decide anything about the offer** — not
684
702
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
685
703
  here for a detection to decide, and a second implementation of one could not be
686
704
  tested and would drift.
687
705
 
688
- **Serving is the engine's to do; publishing is never.** The server is one
706
+ **Serving is the engine's to do, and there is nothing else.** The server is one
689
707
  process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
690
- decides whether it binds wide — no detection involved. A reader the server CAN
691
- reach is not a reason to publish as well: the tiers they can already open are on
692
- the stack. Publishing leaves a page this tooling cannot remove, so it stays an
693
- ask in every case, always — which is why `remote` shows the command rather than
694
- a URL until someone types it.
708
+ decides whether it binds wide — on the LAN and the tailnet alike — with no
709
+ detection involved.
695
710
 
696
711
  - **Never fatal.** A failed render — no worktree, a git error — is one line and
697
712
  the phase is still done. The page is a convenience; the repo is the record.
@@ -711,9 +726,11 @@ the shape; this section carries only what is specific here.
711
726
  - `⚠️` — built and green, with something worth knowing (a mirror that did not
712
727
  refresh, a deviation from the plan) — or stopped at manual steps answered
713
728
  **Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
714
- are open, and `Next` is `/commit, then /spec-next` to pick them up.
729
+ are open, and `Next` is `/commit`, then a row per open step, then
730
+ `/spec-next` to pick them up.
715
731
  - `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
716
- - `⏸` — no spec in flight, or the name given does not match the one that is.
732
+ - `⏸` — no spec in flight, several in flight with this session in none of
733
+ them, or the name given does not match the one that is.
717
734
 
718
735
  **Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Notes` · `Review` ·
719
736
  `Follow-ups` · `Next`
@@ -290,9 +290,9 @@ reader:
290
290
 
291
291
  - **local** — &lt;the `local:` URL&gt;
292
292
  - **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
293
- - **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
293
+ - **remote** — &lt;the `remote:` tailnet URL, or what that line says when there is none&gt;
294
294
 
295
- I'm holding here until you send a verdict — the wait covers local and network.
295
+ I'm holding here until you send a verdict — the wait covers &lt;the tiers the engine's `covers` names&gt;.
296
296
 
297
297
  `Commit` commits the refresh · `Request changes` works them now
298
298
 
@@ -176,14 +176,7 @@ everything a decision needs, so there is nothing to go looking for, and going
176
176
  looking is the bypass step 0 forbids. The file is right there and readable; that
177
177
  is precisely why the rule is written down rather than assumed.
178
178
 
179
- **Check the store before concluding nothing is waiting.** Only when this spec
180
- has a published page (`--json` reports a `url`): a reader off the LAN sent their
181
- pass to the artifact's own `passes` collection rather than to the engine, so an
182
- empty holding area is not an empty answer yet. Read it with the Artifact tool's
183
- `read_db`, merge the `blob` through `--notes`, and **delete the document** —
184
- `/spec-diff` §6 owns the whole sequence, including that a claim consumes.
185
-
186
- **Nothing waiting in either is an ordinary answer.** Say so and stop. Do not hunt
179
+ **Nothing waiting is an ordinary answer.** Say so and stop. Do not hunt
187
180
  through other specs, and do not treat an empty holding area as a problem — a
188
181
  `file://` page copies to the clipboard instead of sending, so mention that the
189
182
  pass may be on their clipboard waiting to be pasted, and finish.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.16.0",
3
+ "version": "19.18.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",