@skitterbyte/skitterspec-linear 19.15.0 → 19.17.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 (45) hide show
  1. package/MIGRATION.md +27 -0
  2. package/README.md +2 -1
  3. package/assets/claude-md-section.md +18 -9
  4. package/assets/commands/allow-main.md +1 -2
  5. package/assets/core/env.config.json.example +0 -1
  6. package/assets/core/env.config.md +28 -26
  7. package/assets/hooks/main-guard.cjs +73 -6
  8. package/assets/hooks/project-guard.cjs +80 -6
  9. package/assets/hooks/review-gate.cjs +73 -6
  10. package/assets/review/page.html +10 -83
  11. package/assets/rules/commit-trailers.md +2 -2
  12. package/assets/rules/spec-planning.md +26 -22
  13. package/assets/rules/spec-reports.md +52 -52
  14. package/assets/skills/no-spec/SKILL.md +2 -2
  15. package/assets/skills/spec/SKILL.md +22 -5
  16. package/assets/skills/spec-bug/SKILL.md +18 -15
  17. package/assets/skills/spec-complete/SKILL.md +23 -1
  18. package/assets/skills/spec-diff/SKILL.md +47 -115
  19. package/assets/skills/spec-hotfix/SKILL.md +18 -15
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +66 -41
  22. package/assets/skills/spec-park/SKILL.md +92 -0
  23. package/assets/skills/spec-resume/SKILL.md +153 -0
  24. package/assets/skills/spec-review/SKILL.md +2 -2
  25. package/assets/skills/spec-reviewed/SKILL.md +1 -8
  26. package/assets/skills/spec-status/SKILL.md +1 -1
  27. package/assets/skills/spec-sync/SKILL.md +12 -12
  28. package/assets/skills/spec-todo/SKILL.md +5 -2
  29. package/package.json +1 -1
  30. package/src/cli.js +361 -208
  31. package/src/env/bootstrap.js +3 -1
  32. package/src/env/checks.js +49 -0
  33. package/src/env/config.js +27 -7
  34. package/src/env/hooks.js +53 -4
  35. package/src/env/live.js +48 -0
  36. package/src/env/provision.js +10 -2
  37. package/src/env/resume.js +234 -0
  38. package/src/env/review.js +71 -173
  39. package/src/env/serve.js +3 -7
  40. package/src/init.js +383 -50
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/linear/cli-sync.js +3 -3
  43. package/src/vendor/provider-kit/src/specs.js +46 -1
  44. package/src/vendor/sync-core/src/summary.js +10 -1
  45. package/assets/commands/spec-remote-review.md +0 -37
@@ -2039,8 +2039,8 @@ a.ticket:hover { border-color: var(--accent); }
2039
2039
  * SAID a session claimed the pass, which is the only ending with provably
2040
2040
  * nothing left on the page to read: no code to quote, no command to run, no
2041
2041
  * blob to paste. Every other one — still asking, established-nobody-did, a
2042
- * poll that failed, a `file://` page whose pass is on the clipboard, a
2043
- * published page whose verdict needs `/spec-reviewed` — keeps the tab,
2042
+ * poll that failed, a `file://` page whose pass is on the clipboard — keeps
2043
+ * the tab,
2044
2044
  * because each leaves something the reader still needs.
2045
2045
  *
2046
2046
  * BEST-EFFORT BY CONSTRUCTION, not by caution. Browsers refuse
@@ -2770,10 +2770,9 @@ a.ticket:hover { border-color: var(--accent); }
2770
2770
  * would be worse than asking for the paste. Clear it again and they return.
2771
2771
  * ======================================================================== */
2772
2772
 
2773
- // Only a `file://` page. A served page posts; a published one writes to its
2774
- // store. Both can deliver, so both keep their buttons — decided from what the
2775
- // page IS, exactly as `send` decides.
2776
- var NO_TRANSPORT = location.protocol === 'file:' && !isArtifact()
2773
+ // Only a `file://` page. A served page posts, so it keeps its buttons —
2774
+ // decided from what the page IS, exactly as `send` decides.
2775
+ var NO_TRANSPORT = location.protocol === 'file:'
2777
2776
  var cmdList = document.getElementById('cmd-list')
2778
2777
  var cmdLead = document.getElementById('cmd-lead')
2779
2778
  var cmdRows = {}
@@ -2916,85 +2915,15 @@ a.ticket:hover { border-color: var(--accent); }
2916
2915
  ask()
2917
2916
  }
2918
2917
 
2919
- /**
2920
- * Is this page running as a published Artifact?
2921
- *
2922
- * A CAPABILITY CHECK, not a hostname one. `window.claude.use` is the whole
2923
- * contract for reaching anything the viewer grants, and it exists only where
2924
- * a viewer is there to grant it — so its presence is what distinguishes the
2925
- * published page from the two the engine serves, without this file knowing
2926
- * anything about where it was published.
2927
- */
2928
- function isArtifact() {
2929
- return Boolean(window.claude && typeof window.claude.use === 'function')
2930
- }
2931
-
2932
- /**
2933
- * Hand the pass to the artifact's own store.
2934
- *
2935
- * THE THIRD TRANSPORT, for the reader no local server can reach: a phone on
2936
- * mobile data, or anyone away from the LAN the engine serves on. The pass
2937
- * lands in a document Claude reads back and deletes, so it is consumed
2938
- * exactly like a claimed one.
2939
- *
2940
- * `use` is asked only once the reader has pressed something. Asking at load
2941
- * would spend a consent prompt on every render, including the ones nobody
2942
- * ends in a verdict.
2943
- */
2944
- function sendToStore(json, verdict) {
2945
- copyHint.hidden = false
2946
- copyHint.textContent = 'Sending…'
2947
- var landed = false
2948
- window.claude.use('db').then(function (db) {
2949
- // `null` means this view cannot run db — not granted, not served, failed
2950
- // to load, all indistinguishable by design. The clipboard is still there,
2951
- // so the pass is recoverable rather than lost.
2952
- if (!db) {
2953
- showFallback(json, 'Could not reach the store. Copy this, then paste it to Claude.')
2954
- return
2955
- }
2956
- return db
2957
- .collection('passes')
2958
- .add({ spec: data.spec, at: new Date().toISOString(), render: data.generatedAt, blob: JSON.parse(json) })
2959
- .then(function () {
2960
- landed = true
2961
- // NO CODE HERE, and none invented. Six digits are the engine's, minted
2962
- // by the holding area this pass never went through — so the page says
2963
- // the one thing that is true and actionable.
2964
- copyHint.textContent = 'Sent. Run this where Claude is:'
2965
- showCommand('/spec-reviewed')
2966
- // A PUBLISHED PAGE CANNOT ASK. The pass went into the artifact's own
2967
- // store, which the engine only reads when someone tells it to, so
2968
- // nothing here could ever come back `true` — and the command is the
2969
- // whole ending rather than a fallback within it.
2970
- markDecided(verdict, '/spec-reviewed', null)
2971
- })
2972
- }).then(null, function (err) {
2973
- if (landed) return
2974
- showFallback(
2975
- json,
2976
- 'Could not store the pass' + (err && err.code ? ' (' + err.code + ')' : '') +
2977
- '. Copy this, then paste it to Claude.',
2978
- )
2979
- })
2980
- }
2981
-
2982
2918
  function send(verdict) {
2983
2919
  var json = JSON.stringify(buildBlob(verdict), null, 2)
2984
- // DECIDED FROM WHAT THE PAGE IS, not from what it can guess. A published
2985
- // page has a store and no server; a page opened over http was served by the
2986
- // engine and can hand the pass straight back; a `file://` page has no server
2987
- // to talk to and never will.
2920
+ // DECIDED FROM WHAT THE PAGE IS, not from what it can guess. A page opened
2921
+ // over http was served by the engine and can hand the pass straight back;
2922
+ // a `file://` page has no server to talk to and never will.
2988
2923
  //
2989
2924
  // NOT "try the POST and fall back on failure": a failed POST and an absent
2990
2925
  // one look identical to the reader, so the fallback would hide a server
2991
- // that is refusing passes behind a message about copying. The published page
2992
- // is exactly that trap — its POST would go to claude.ai and fail — which is
2993
- // why it is answered first, by what the page IS rather than by what failed.
2994
- if (isArtifact()) {
2995
- sendToStore(json, verdict)
2996
- return
2997
- }
2926
+ // that is refusing passes behind a message about copying.
2998
2927
  if (location.protocol !== 'file:') {
2999
2928
  post(json, verdict)
3000
2929
  return
@@ -3037,14 +2966,12 @@ a.ticket:hover { border-color: var(--accent); }
3037
2966
  // precondition of the thing they asked for, not a verdict on the diff.
3038
2967
  'live-on': '▶ Commit & put it live',
3039
2968
  'allow-network': '▶ Allow network',
3040
- 'allow-remote': '▶ Allow remote',
3041
2969
  }
3042
2970
  var ACTION_CMD = {
3043
2971
  'live-on': '/spec-live',
3044
2972
  'allow-network': 'skitterspec spec-env review allow network',
3045
- 'allow-remote': '/spec-remote-review',
3046
2973
  }
3047
- var SURFACE_LABEL = { live: 'live', network: 'network', remote: 'remote' }
2974
+ var SURFACE_LABEL = { live: 'live', network: 'network' }
3048
2975
 
3049
2976
  function surfaceStateText(row) {
3050
2977
  if (row.kind === 'live') {
@@ -23,7 +23,7 @@ Refs: SKS-29
23
23
  Get the value from the engine rather than reading it off a spec by hand:
24
24
 
25
25
  ```
26
- pnpm exec skitterspec-linear spec-sync ref
26
+ {{exec}} skitterspec-linear spec-sync ref
27
27
  ```
28
28
 
29
29
  Bare, that answers **from the branch** — correct whenever you are committing
@@ -48,7 +48,7 @@ the bare command answers with the old spec's ticket.
48
48
  Name the spec instead — still the engine, never a hand-written id:
49
49
 
50
50
  ```
51
- pnpm exec skitterspec-linear spec-sync ref feat-distance-prescriptions
51
+ {{exec}} skitterspec-linear spec-sync ref feat-distance-prescriptions
52
52
  ```
53
53
 
54
54
  The branch is not consulted, so this works from `main` too. An unknown spec name
@@ -1,7 +1,7 @@
1
1
  # Spec Planning
2
2
 
3
3
  Spec-driven development is driven by ten lifecycle skills (plus the
4
- `/spec-connect`, `/spec-live` and `/spec-remote-review` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
4
+ `/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
5
5
  and lifecycle stay consistent. Each sets a status on the spec header
6
6
  (`> **Status:** …`):
7
7
 
@@ -18,6 +18,8 @@ and lifecycle stay consistent. Each sets a status on the spec header
18
18
  | `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
19
19
  | `/spec-reviewed` | Pick up a review approved on the page — offered by its code, claimed on your word | (unchanged) | (unchanged) |
20
20
  | `/spec-epic-next` | Name the epic member that can start now, as the `/spec-start` to type in a new tab — a picker when several can; reads only | (unchanged) | (unchanged) |
21
+ | `/spec-resume` | Go back into a spec already in flight, by name or `#N`. It rebuilds the worktree when this machine has none, shows what it is blocked on, and acts on the message given with it. It starts nothing | (unchanged) | (unchanged) |
22
+ | `/spec-park` | Park a spec in flight on something outside the repo: a `Blocked on:` line on the spec or a phase, committed on its branch. The worktree stays | (unchanged) | (unchanged) |
21
23
  | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
22
24
  | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
23
25
  | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
@@ -26,7 +28,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
26
28
  | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
27
29
 
28
30
  **Skills vs commands.** The table above lists **skills** — Claude reads them and
29
- exercises judgment. `/spec-connect`, `/spec-live` and `/spec-remote-review` are
31
+ exercises judgment. `/spec-connect` and `/spec-live` are
30
32
  instead **slash commands**
31
33
  (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
32
34
  relays its output, so there is no judgment to apply and no model turn spent
@@ -34,19 +36,12 @@ finding one. They are marked `disable-model-invocation`, meaning
34
36
  **only you can run them** — a skill that wants one will tell you to type it
35
37
  rather than invoking it.
36
38
 
37
- **`/spec-remote-review`** is the newest and the smallest: it toggles whether
38
- **this spec** may publish, and takes `on`/`off` when you would rather say which.
39
- The permission is per worktree, kept in the gitignored review store, so the base
40
- branch is never dirtied and no other spec gains it; `review.allowRemote` in the
41
- committed config is the project default beneath it. Turned on beside a page
42
- that already exists, it is the ask to publish that page and re-show the stack.
43
- It exists because a render's `remote:` line has to name something a person can
44
- act on, and `skitterspec spec-env review allow remote` is not what anyone
45
- reconstructs from a page they are reading on a phone. Making the line
46
- *clickable* was considered and rejected — the only clickable thing markdown has
47
- is a URL, and a URL that acts when it is **fetched** is one a link previewer or
48
- a prefetcher fires with nobody involved. It **permits** publishing; it publishes
49
- nothing.
39
+ **The `spec-remote-review` command was retired** with the published review tier
40
+ (feat-tailnet-remote-tier). It toggled whether a spec might publish its review
41
+ as a claude.ai page — a second store no wait could watch, and a page this
42
+ tooling could never delete. The `remote:` line now names the review server's
43
+ tailnet address, on the same switch as `network`, so there is nothing left for
44
+ a command to toggle.
50
45
 
51
46
  `/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
52
47
  convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
@@ -119,8 +114,8 @@ already use, so one category is not spelled two ways. `/spec-init` asks for
119
114
  both — on an existing config through a `/no-spec` branch, since the base
120
115
  branch is a landing zone.
121
116
 
122
- **`/allow-main` is the fourth command.** It is user-only for a different reason
123
- from the other three: `/spec-connect`, `/spec-live` and `/spec-remote-review`
117
+ **`/allow-main` is the third command.** It is user-only for a different reason
118
+ from the other two: `/spec-connect` and `/spec-live`
124
119
  are marked that way because there is no judgment to apply. This one is marked that
125
120
  way because **Claude must not be able to lift a guard aimed at Claude.**
126
121
 
@@ -170,7 +165,7 @@ it fails open on every cannot-tell. `/allow-project <name>` lifts it for one
170
165
  session, and it is user-only for `/allow-main`'s reason: Claude must not be
171
166
  able to lift a guard aimed at Claude.
172
167
 
173
- **`/spec-skip` is the fifth command**, and it is user-only for `/allow-main`'s
168
+ **`/spec-skip` is the fourth command**, and it is user-only for `/allow-main`'s
174
169
  reason rather than the mild one: it lifts the review gate, which is a guard
175
170
  aimed at Claude. It pre-executes `skitterspec spec-env review skip "<reason>"`
176
171
  and relays it — the same exit that always existed, at an address a person will
@@ -187,7 +182,7 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
187
182
  is worse: `/commit` belongs to skittership, which is why the gate is enforced
188
183
  by a hook rather than by editing that skill.
189
184
 
190
- **`/spec-epic` is the sixth command**, and it is user-only for the mild reason: it
185
+ **`/spec-epic` is the fifth command**, and it is user-only for the mild reason: it
191
186
  pre-executes `skitterspec epic status` and relays it, so there is no judgement
192
187
  to apply. It exists for the tab an epic is run from — each member is built in
193
188
  a tab of its own, and on a phone the in-app browser has to close to switch
@@ -253,7 +248,7 @@ your canonical `localhost` ports so you can test it at the normal URL
253
248
  move, header edits, the code) happens on the spec's branch in the worktree; `main`
254
249
  changes only when it merges. Teardown is folded into `/spec-complete` ·
255
250
  `/spec-cancel`. Beneath the skills, `skitterspec spec-env
256
- <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
251
+ <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|checks|status|resolve|resume|base>` is the CLI
257
252
  engine. `up` plans the fork;
258
253
  **`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
259
254
  the command a skill runs names no file, and a secrets hook that refuses any
@@ -378,7 +373,7 @@ the base branch — and a 350-line diff read as terminal text is scrolling, not
378
373
  review. The engine collects the worktree's changes with `git -C` and writes a
379
374
  self-contained HTML page (`.spec-env/reviews/<spec>.html`, gitignored) with
380
375
  whole-file context that folds away, a file tree, and new files included. You open
381
- it locally, or publish it and read it on a phone.
376
+ it locally, or on a phone over your LAN or tailnet.
382
377
  **The diff never passes through the model**, so the page is free to produce
383
378
  however large it is; the *written*
384
379
  review — a short read plus `flag`/`confirm`/`good` notes — is the part that costs
@@ -557,7 +552,7 @@ its verdicts and its fields.
557
552
  | **Branch** | `spec/feat-orders` · 3 commits, clean |
558
553
  | **Built** | POST /orders handler, orders schema |
559
554
  | **Tests** | 128 passed · dotnet test |
560
- | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
555
+ | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) |
561
556
  | **Follow-ups** | none |
562
557
  | **Next** | `/spec-next` → phase 3 (Auth) |
563
558
 
@@ -906,6 +901,15 @@ Every spec header carries:
906
901
  only that phase.
907
902
  - `> **Lanes:**` — on an epic, optional: how many members may be in flight at
908
903
  once.
904
+ - `> **Blocked on:**`: on a spec, or on one phase file. It records that the
905
+ spec, or that phase, waits on something outside the repo: a deploy, another
906
+ project's release, a soak. The value is free text, with an optional
907
+ `(until YYYY-MM-DD)` that `/spec-todo` reads. `/spec` writes the planned
908
+ ones, `/spec-park` writes the ad-hoc ones, and `/spec-resume` clears them on
909
+ the record. `/spec-next` stops before building past one, and
910
+ `/spec-complete` reports one still standing. **Not `Waits on:`.** That one
911
+ is an epic wait the engine can observe on the base branch. This one is a
912
+ condition only a person can judge, so nothing ever counts it as met.
909
913
 
910
914
  **Under a provider's default `pull`, these three are the tracker's** —
911
915
  `Status:`, `Developer:` and the State log — and new specs carry
@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
36
36
  | **Branch** | `spec/feat-foo` · 3 commits, clean |
37
37
  | **Built** | POST /orders handler, orders schema |
38
38
  | **Tests** | 128 passed · dotnet test |
39
- | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) also [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) · **remote** off |
39
+ | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) |
40
40
  | **Follow-ups** | none |
41
41
  | **Next** | `/spec-next` → phase 3 (Auth) |
42
42
 
@@ -89,12 +89,11 @@ the options may be offered after the table.
89
89
 
90
90
  - **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
91
91
  - **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
92
- - also — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
93
- - **remote** — off · `/spec-remote-review` turns it on
92
+ - **remote** — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
94
93
 
95
94
  live: off — /spec-live to put it live
96
95
 
97
- I'm holding here until you send a verdict — the wait covers local and network.
96
+ I'm holding here until you send a verdict — the wait covers local, network and remote.
98
97
 
99
98
  `/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
100
99
 
@@ -115,7 +114,7 @@ middle of a review.
115
114
  capability. `live: off — the page can put it live` told the reader that a page
116
115
  somewhere could do it and left them to find the verb — and the verb is what they
117
116
  need when they are in a terminal rather than on the page. So the lines say
118
- `/spec-live`, `/spec-live main`, `/spec-remote-review`. Making them *clickable*
117
+ `/spec-live` and `/spec-live main`. Making them *clickable*
119
118
  was considered and rejected: the only clickable thing markdown has is a URL, and
120
119
  a URL that acts when it is **fetched** is one a link previewer or a prefetcher
121
120
  fires with nobody involved.
@@ -157,12 +156,18 @@ and the reader on a phone was left with nothing they could open.
157
156
  |------|----|----------|
158
157
  | `local` | the loopback URL — the machine the run is on | never. With nothing served it is the `file://` page, and says it cannot send a verdict |
159
158
  | `network` | the LAN URL — a phone on the same wifi | `review.allowNetwork` is false, or this machine has no network address |
160
- | `remote` | a published page, for a reader off the network | `review.allowRemote` is false, or nothing has been published |
159
+ | `remote` | the tailnet URL, labelled `(tailnet)` — a reader off the wifi | whenever `network` is, with the same command; or this machine has no tailnet address |
160
+
161
+ **Labelled by address, never by where the reader sits.** `local` is loopback,
162
+ `network` the LAN, `remote` the tailnet, wherever the reader is. Relabelling
163
+ the LAN `local` whenever loopback is hidden would give one URL two names, and
164
+ a label that moves is one nobody learns.
161
165
 
162
166
  A tier that is off **keeps its line** and names the one command that turns it
163
- on. Dropping the line is what left a reader who had walked out of the house with
164
- nothing on screen to tell them a remote page was even possible — they could not
165
- ask for what they could not see.
167
+ on — or, where nothing of ours can, says why (`no tailnet address on this
168
+ machine`). Dropping the line is what left a reader who had walked out of the
169
+ house with nothing on screen to tell them a remote door was even possible —
170
+ they could not ask for what they could not see.
166
171
 
167
172
  **One exception: a reader on another machine sees no `local` line.** This is
168
173
  the third amendment, and it argues from the rule's own reason. The rule keeps a
@@ -188,20 +193,27 @@ copying the stack still produces the right banner. The holding line names the
188
193
  engine's `covers` — *the wait covers network* — never a door the stack did not
189
194
  show.
190
195
 
191
- **The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
192
- The engine offers the other addresses this machine has (a
193
- tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
194
- labelled; `--json` carries them as that tier's `alternates`, labelled the same
195
- way. Copy them as indented sub-bullets under the network bullet, verbatim,
196
- labels included. This is not an amendment to the tier rule: the stack is the
197
- engine's, copied rather than composed, and the engine was already printing
198
- these — a contract that made the skill edit them out was the composing this
199
- section forbids. A machine with no alternates renders the banner exactly as
200
- above, minus the sub-bullet.
196
+ **A tier may carry alternates, and they are part of it — not a fourth tier.**
197
+ Where this machine has a second address of the same kind — another LAN
198
+ interface, a second tailnet one — the engine prints it as an `also:` line under
199
+ its tier, labelled; `--json` carries it as that tier's `alternates`, labelled
200
+ the same way. Copy them as indented sub-bullets under that tier's bullet,
201
+ verbatim, labels included: the stack is the engine's, copied rather than
202
+ composed. A machine with no alternates — the usual case — renders the banner
203
+ exactly as above.
204
+
205
+ **The fourth amendment, and the first to remove rules rather than add them.**
206
+ `remote` was a published claude.ai page: a second store no wait could watch, a
207
+ page this tooling could never delete, and a toggle command of its own. Once the
208
+ review server answered on the tailnet, a reader off the wifi already had a door
209
+ into the same room — printed as an `also:` sub-line, the hardest link in the
210
+ stack to find. So the published tier was retired and the tailnet took its name
211
+ (feat-tailnet-remote-tier). It deletes a tier, its caveat and a transport, and
212
+ adds no kind of line; that is the argument the bar above asked for.
201
213
 
202
214
  **Only promise a wait the transport can deliver.** The wait itself is real in
203
215
  every case; what varies is what carries it back, not whether the run is
204
- stopped. Three transports, three true sentences:
216
+ stopped. Two transports, two true sentences:
205
217
 
206
218
  - **A page the engine SERVES** hands its pass to the local store, and
207
219
  `spec-env review wait` returns when it lands. The run is woken by the press:
@@ -225,18 +237,12 @@ stopped. Three transports, three true sentences:
225
237
  *"I'm holding here — paste the pass when you have it."*
226
238
  This is the same wait, carried by the conversation instead of a watch. It is
227
239
  not a lesser one, and it is not an excuse to ask without waiting.
228
- - **A PUBLISHED page** writes to the artifact's own store, and nothing pushes
229
- from there into the conversation. That is the one case where a verdict is
230
- genuinely invisible until someone asks for it, so its line in the stack says
231
- that rather than letting the holding line speak for it:
232
-
233
- - **remote** — [https://…](https://…) · a verdict here needs `/spec-reviewed`
234
240
 
235
- Where `remote` is the only tier a reader can reach, the holding line says so
236
- too: *press a verdict, then type `/spec-reviewed` — I cannot see it until you
237
- do.* Where a served tier is reachable as well, the holding line keeps naming
238
- the tiers the wait covers, and `remote`'s own caveat sits on `remote`'s line
239
- where it belongs.
241
+ A third transport — a published page writing to a store nothing here watched —
242
+ was retired with the published tier. A verdict that arrives when no wait is
243
+ running is the one left that nothing pushes into the conversation, and its
244
+ sentence is *press a verdict, then type `/spec-reviewed` — I cannot see it until
245
+ you do.*
240
246
 
241
247
  **A harness with no file-watch does not get an exemption.** It once read
242
248
  "change nothing" — keep the row, keep the question, do not wait — and that
@@ -313,7 +319,7 @@ the session every half hour all night for a review nobody is returning to
313
319
  before morning.
314
320
 
315
321
  **Past the bound the banner degrades**, to the sentence this file already
316
- defines for a transport that cannot push into the conversation:
322
+ defines for a verdict nothing pushes into the conversation:
317
323
 
318
324
  *press a verdict, then type `/spec-reviewed` — I cannot see it until you do.*
319
325
 
@@ -350,7 +356,7 @@ block. *Waiting* is what any offer does, and it is what this section governs.
350
356
  that is finished. A mid-run render waits without arming — walking away from it
351
357
  costs nothing, which is exactly why `Continue` is safe to offer there.
352
358
 
353
- **One link per reachable store, each labelled.** This amends
359
+ **One link per door, each labelled, all into one store.** This amends
354
360
  *"exactly one link, never two"*, and the evidence that rule was written on is
355
361
  the reason it still reads the way it does. Two links were handed over, the wait
356
362
  stood behind only one of them, and a verdict was pressed on the published page
@@ -358,20 +364,19 @@ three times while each one sat unread under a line claiming the run was waiting.
358
364
  Two links was not a convenience with a caveat; the caveat existing was the bug.
359
365
 
360
366
  **What that evidence is about is the store, not the count.** A served page hands
361
- its pass to the local pending store, which `spec-env review wait` watches; a
362
- published page writes to the artifact's own store, which nothing here can see.
367
+ its pass to the local pending store, which `spec-env review wait` watches; the
368
+ published page wrote to an artifact's own store, which nothing here could see.
363
369
  Two links into two stores asks the reader to know which door the run is standing
364
- behind, and they cannot.
365
-
366
- **Local and network are two doors into one room.** The page POSTs with
367
- `fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
368
- opened at `192.168.0.136:7760/…` reach the same server process and the same
369
- pending store. One wait covers both, and a verdict pressed on either wakes the
370
- same run. A `network` alternate — the `also:` tailnet address — is one more
371
- door into the same room: the same server answers on it, so the wait-coverage
372
- line stays true with nothing added to it. Between all of those the objection
373
- does not apply — which is why they are offered, and why offering them gives
374
- nothing up.
370
+ behind, and they cannot — which is why the second store was retired rather
371
+ than caveated.
372
+
373
+ **Local, network and remote are three doors into one room.** The page POSTs with
374
+ `fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…`, at
375
+ `192.168.0.136:7760/…` or at `100.126.111.34:7760/…` reaches the same server
376
+ process and the same pending store. One wait covers all three, and a verdict
377
+ pressed on any of them wakes the same run. An `also:` alternate is one more door
378
+ into the same room. Between all of those the objection does not apply — which is
379
+ why they are offered, and why offering them gives nothing up.
375
380
 
376
381
  **So two things are required, and the second is what the old rule lacked.**
377
382
  Every link is **labelled** with its tier, and one line says
@@ -379,11 +384,6 @@ Every link is **labelled** with its tier, and one line says
379
384
  Two *unlabelled* links stay forbidden exactly as before, because
380
385
  the reader still cannot tell them apart.
381
386
 
382
- **`remote` keeps the caveat it always had.** It is listed so a reader off the
383
- network knows the surface exists and what turns it on — never as a door the wait
384
- is claimed to cover. Where it is on and published, its line says what is true of
385
- it: *a verdict here needs `/spec-reviewed`*.
386
-
387
387
  **Still forbidden**, in the words of the rule this amends: offering two links
388
388
  into **different** stores without saying which one the wait is watching. That is
389
389
  the failure that cost three unread verdicts, and nothing here touches it.
@@ -482,7 +482,7 @@ behind it — say nothing rather than reporting that there was nothing to report
482
482
  | `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure) · `not pushed · <command> publishes it` (a push suggested rather than asked, as `/spec`'s branch lane does). |
483
483
  | `Worktree` | A worktree provisioned, entered, or torn down. |
484
484
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
485
- | `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
485
+ | `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any alternates inline after their tier's URL (`also <url>`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
486
486
  | `Follow-ups` | **Always.** `none`, or one line each. |
487
487
  | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
488
488
 
@@ -237,9 +237,9 @@ banner, which carries the counts, the stack and the two exits:
237
237
 
238
238
  - **local** — &lt;the `local:` URL&gt;
239
239
  - **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
240
- - **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
240
+ - **remote** — &lt;the `remote:` tailnet URL, or what that line says when there is none&gt;
241
241
 
242
- I'm holding here until you send a verdict — the wait covers local and network.
242
+ I'm holding here until you send a verdict — the wait covers &lt;the tiers the engine's `covers` names&gt;.
243
243
 
244
244
  `Commit & Land` finishes it · `Commit` keeps the branch
245
245
 
@@ -36,8 +36,14 @@ Then:
36
36
 
37
37
  1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
38
38
  and drop any issue whose identifier is already stamped on a spec. If the user
39
- named such an issue directly, **stop** and point them at that spec — one issue
40
- never becomes two specs.
39
+ named such an issue directly, it already has a spec, and one issue never
40
+ becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
41
+ of what they wrote as its message: feedback on shipped work, or "the deploy
42
+ is out", belongs to the spec that is already in flight. Confirm it, as kind
43
+ routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
44
+ a yes. On a no, stop and name the spec. That spec may exist only on its
45
+ branch, which `linked` reads too, so a missing `specs/` folder here is not
46
+ evidence that the issue is free.
41
47
  2. **Read the issue** with the discovered issue-read tool: title, description,
42
48
  labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
43
49
  without it — a spec written from the user's own description is still a spec.
@@ -215,7 +221,15 @@ not write the spec until this is resolved.
215
221
  answer **either way**: a flag name, or `none: <one-line reason>`. "No" is a
216
222
  decision and belongs in the header; silence is not. Skip entirely when the
217
223
  config is absent — that project does not use flags.
218
- 11. **Open questions** — anything still undecided.
224
+ 11. **Waits outside the repo**: does any phase only make sense once
225
+ something happens elsewhere? For example, an earlier phase deployed and
226
+ running for logs, another project's release, or a soak of N days. Each
227
+ becomes that phase file's `> **Blocked on:**` line (template below),
228
+ with `(until YYYY-MM-DD)` only when a date was given. `/spec-next` stops
229
+ before building that phase, and `/spec-resume` is how it goes on. This
230
+ is free text, a condition only a person can judge, which is what sets it
231
+ apart from an epic member's `Waits on:`. With no such wait, write none.
232
+ 12. **Open questions** — anything still undecided.
219
233
 
220
234
  Stop grilling when there are no unresolved branches that would change the spec.
221
235
  Briefly play back the agreed understanding before writing.
@@ -500,6 +514,9 @@ order). Each phase file uses this template:
500
514
  # Phase 1 — <goal> ⬜
501
515
 
502
516
  > Spec: [00-overview.md](00-overview.md) · **Status:** Not started
517
+ > **Blocked on:** <only when this phase waits on something outside the repo
518
+ > (Phase A item 11) — the condition, plus "(until YYYY-MM-DD)" if dated.
519
+ > Omit the line entirely otherwise>
503
520
 
504
521
  **Goal:** <one line — what this phase delivers and how it's proven>.
505
522
 
@@ -918,9 +935,9 @@ this page's two exits:
918
935
 
919
936
  - **local** — &lt;the `local:` URL&gt;
920
937
  - **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
921
- - **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
938
+ - **remote** — &lt;the `remote:` tailnet URL, or what that line says when there is none&gt;
922
939
 
923
- I'm holding here until you send a verdict — the wait covers local and network.
940
+ I'm holding here until you send a verdict — the wait covers &lt;the tiers the engine's `covers` names&gt;.
924
941
 
925
942
  `Commit & Start` puts it in flight · `Commit` keeps it for later
926
943
 
@@ -35,8 +35,14 @@ Then:
35
35
 
36
36
  1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
37
37
  and drop any issue whose identifier is already stamped on a spec. If the user
38
- named such an issue directly, **stop** and point them at that spec — one issue
39
- never becomes two specs.
38
+ named such an issue directly, it already has a spec, and one issue never
39
+ becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
40
+ of what they wrote as its message: feedback on shipped work, or "the deploy
41
+ is out", belongs to the spec that is already in flight. Confirm it, as kind
42
+ routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
43
+ a yes. On a no, stop and name the spec. That spec may exist only on its
44
+ branch, which `linked` reads too, so a missing `specs/` folder here is not
45
+ evidence that the issue is free.
40
46
  2. **Read the issue** with the discovered issue-read tool: title, description,
41
47
  labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
42
48
  without it — a spec written from the user's own description is still a spec.
@@ -669,10 +675,9 @@ line with it where the engine printed one, and nothing where it did not.
669
675
  `.claude/rules/spec-reports.md` carries the shape, including why a rigid
670
676
  contract took that line.
671
677
 
672
- - **Never write the review unasked**, and **never publish**. Publishing leaves
673
- something behind that this tooling cannot remove, so it is always an ask. A
674
- `file://` link is no use on a phone, and saying so **is** the ask —
675
- `/spec-diff` §6 owns how.
678
+ - **Never write the review unasked**, and **never publish** — there is no
679
+ publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
680
+ stack says why nothing was served.
676
681
  **The `reader:` line no longer decides anything here, and that is the point.**
677
682
  It is still printed, and it is still the only place that question is answered —
678
683
  but the offer does not change with it, because the stack lists every tier
@@ -682,22 +687,20 @@ that branching is exactly what produced a `file://` page on a session detected
682
687
  underneath a reader when detection flipped mid-session.
683
688
 
684
689
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
685
- `network` — the other addresses this machine has, offered because the
686
- best-guess one can be wrong — so pass them on rather than editing them out: in
687
- the banner they are indented sub-bullets under **network**, labels
688
- (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
690
+ their tier — the other addresses this machine has of that kind — so pass them
691
+ on rather than editing them out: in the banner they are indented sub-bullets
692
+ under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
693
+ shows.
689
694
 
690
695
  **Never read an environment variable to decide anything about the offer** — not
691
696
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
692
697
  here for a detection to decide, and a second implementation of one could not be
693
698
  tested and would drift.
694
699
 
695
- **Serving is the engine's to do; publishing is never.** A `remote` reader
700
+ **Serving is the engine's to do, and there is nothing else.** A `remote` reader
696
701
  authorises a local server — one process, ended by one flag, leaving nothing
697
- behind — and authorises nothing else. Publishing leaves a page this tooling
698
- cannot remove, so it stays an ask in every case, always. If the engine could not
699
- serve (a busy port, a machine with no network address) it falls back to the
700
- `file://` URL with its marker, and that is when publishing is worth naming.
702
+ behind. If the engine could not serve (a busy port, a machine with no network
703
+ address) it falls back to the `file://` URL with its marker.
701
704
 
702
705
  - **Never fatal.** A failed render — no worktree, a git error — is one line, and
703
706
  the fix is still done. The page is a convenience; the repo is the record.