@skitterbyte/skitterspec-jira 2.16.0 → 2.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.
- package/MIGRATION.md +78 -0
- package/assets/claude-md-section.md +6 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +24 -27
- package/assets/review/page.html +10 -83
- package/assets/rules/spec-planning.md +14 -21
- package/assets/rules/spec-reports.md +112 -54
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +2 -2
- package/assets/skills/spec-bug/SKILL.md +10 -13
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +10 -13
- package/assets/skills/spec-next/SKILL.md +59 -42
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/package.json +1 -1
- package/src/cli.js +251 -204
- package/src/env/config.js +16 -7
- package/src/env/hooks.js +6 -3
- package/src/env/live.js +48 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +509 -13
- package/assets/commands/spec-remote-review.md +0 -37
|
@@ -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/…)
|
|
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
|
-
|
|
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
|
|
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
|
|
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` |
|
|
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
|
|
164
|
-
|
|
165
|
-
|
|
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
|
-
**
|
|
192
|
-
|
|
193
|
-
tailnet one
|
|
194
|
-
labelled; `--json` carries
|
|
195
|
-
way. Copy them as indented sub-bullets under
|
|
196
|
-
labels included
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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.
|
|
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
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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
|
|
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
|
|
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;
|
|
362
|
-
published page
|
|
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
|
-
|
|
367
|
-
|
|
368
|
-
opened at `
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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.
|
|
@@ -460,6 +460,47 @@ work on. A row that cannot be run spends the trust the position was designed to
|
|
|
460
460
|
earn — and the two skills that got it wrong got it wrong independently, which is
|
|
461
461
|
what makes it a missing constraint rather than two slips.
|
|
462
462
|
|
|
463
|
+
### Open manual steps are rows
|
|
464
|
+
|
|
465
|
+
When the next action includes steps only a person can do — a manual test pass,
|
|
466
|
+
a check in the running app — and any are still open, `Next`
|
|
467
|
+
**lists every one of them, one per row**. The label sits on the first row
|
|
468
|
+
only, each step gets a row of its own with the label cell blank, and a closing
|
|
469
|
+
row names what comes after:
|
|
470
|
+
|
|
471
|
+
| | |
|
|
472
|
+
|---|---|
|
|
473
|
+
| **Follow-ups** | none |
|
|
474
|
+
| **Next** | `/spec-live`, then: |
|
|
475
|
+
| | 1. Open Settings → Business Unit Setup |
|
|
476
|
+
| | 2. Pick a business unit with gaps; each process shows ✗ with its gaps |
|
|
477
|
+
| | 3. Set one process up, press **Check again**; its card turns ✓ |
|
|
478
|
+
| | then `/spec-next` to finish phase 5 |
|
|
479
|
+
|
|
480
|
+
**A count is not a list.** `run the seven manual steps` names steps the reader
|
|
481
|
+
cannot see: the list it means is several messages up, or gone after a `/clear`.
|
|
482
|
+
Neither is the phase file's path — that sends the reader out of the terminal to
|
|
483
|
+
find out what to do, which is the failure `/spec-next`'s *Manual steps* exists
|
|
484
|
+
to fix.
|
|
485
|
+
|
|
486
|
+
**Copy them from the phase file, never from an earlier message.** The open
|
|
487
|
+
manual tasks there — and the numbered sub-tasks `/spec-next` writes under a
|
|
488
|
+
vague one — are the record. A run that did not list them (`/commit`,
|
|
489
|
+
`/spec-resume`) reads them there; one that did copies the same text. A
|
|
490
|
+
conversation is not durable, and steps re-made from memory drift from the ones
|
|
491
|
+
the reader was shown.
|
|
492
|
+
|
|
493
|
+
**It applies to every skill's block**, not only `/spec-next`'s. The report this
|
|
494
|
+
was written from came from `/commit`, after `/spec-next` had listed the steps
|
|
495
|
+
and been answered **Not yet**.
|
|
496
|
+
|
|
497
|
+
**It is an amendment, and it is argued from this section's own rule.** It adds
|
|
498
|
+
no row type and nothing after the block — `Next` stays last, and is the same
|
|
499
|
+
single next action, written out. A `Next` that counts steps out of sight is not
|
|
500
|
+
runnable from the state the run leaves behind; one row per step is what makes it
|
|
501
|
+
so, and seven steps in one cell are a paragraph nobody follows. A report with no
|
|
502
|
+
open manual steps keeps its one-row `Next`.
|
|
503
|
+
|
|
463
504
|
## Field vocabulary, in this order
|
|
464
505
|
|
|
465
506
|
A skill emits only the fields it declares, in this order, skipping the rest.
|
|
@@ -482,9 +523,9 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
482
523
|
| `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
524
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
484
525
|
| `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
|
|
526
|
+
| `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
527
|
| `Follow-ups` | **Always.** `none`, or one line each. |
|
|
487
|
-
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
|
|
528
|
+
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. Open manual steps take a row each (*Open manual steps are rows*). |
|
|
488
529
|
|
|
489
530
|
The order runs identity → context → what happened → where it went → what to do.
|
|
490
531
|
**`Tracker` is first** because the id is what addresses this work outside the
|
|
@@ -533,7 +574,8 @@ silence.
|
|
|
533
574
|
|
|
534
575
|
## Where the block may grow
|
|
535
576
|
|
|
536
|
-
|
|
577
|
+
Two places. `Next` takes a row per open manual step (*Open manual steps are
|
|
578
|
+
rows*, above). And a non-`✅` verdict adds a `Why` row, and quotes the output that
|
|
537
579
|
justifies it — the failing assertion, the conflict, the engine's refusal — in a
|
|
538
580
|
fenced block **above** the table, where a fence means what a fence should mean:
|
|
539
581
|
|
|
@@ -601,6 +643,22 @@ the reasoning.
|
|
|
601
643
|
| **Follow-ups** | Session expiry is read from two places; phase 4 leans on one |
|
|
602
644
|
| **Next** | `/spec-next` → phase 4 (Docs) |
|
|
603
645
|
|
|
646
|
+
**`⚠️` — stopped at manual steps answered Not yet.**
|
|
647
|
+
|
|
648
|
+
⚠️ **Phase 2 code built; manual check open** — `feat-orders`, 2 of 4
|
|
649
|
+
|
|
650
|
+
| | |
|
|
651
|
+
|---|---|
|
|
652
|
+
| **Branch** | `spec/feat-orders` · 3 commits, dirty |
|
|
653
|
+
| **Built** | Order form, POST /orders handler |
|
|
654
|
+
| **Tests** | 131 passed · npm test |
|
|
655
|
+
| **Notes** | Manual check answered **Not yet** — the phase stays `🔄` |
|
|
656
|
+
| **Follow-ups** | none |
|
|
657
|
+
| **Next** | `/commit`, then `/spec-live`, then: |
|
|
658
|
+
| | 1. Place an order with two lines; the confirmation lists both |
|
|
659
|
+
| | 2. Place one with a negative quantity; the form refuses it |
|
|
660
|
+
| | then `/spec-next` to finish phase 2 |
|
|
661
|
+
|
|
604
662
|
**`⏸` — refused, nothing changed.**
|
|
605
663
|
|
|
606
664
|
⏸ **`/spec-next` refused — no spec in flight**
|
|
@@ -237,9 +237,9 @@ banner, which carries the counts, the stack and the two exits:
|
|
|
237
237
|
|
|
238
238
|
- **local** — <the `local:` URL>
|
|
239
239
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
240
|
-
- **remote** — <the `remote:` URL, or
|
|
240
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
241
241
|
|
|
242
|
-
I'm holding here until you send a verdict — the wait covers
|
|
242
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
243
243
|
|
|
244
244
|
`Commit & Land` finishes it · `Commit` keeps the branch
|
|
245
245
|
|
|
@@ -907,9 +907,9 @@ this page's two exits:
|
|
|
907
907
|
|
|
908
908
|
- **local** — <the `local:` URL>
|
|
909
909
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
910
|
-
- **remote** — <the `remote:` URL, or
|
|
910
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
911
911
|
|
|
912
|
-
I'm holding here until you send a verdict — the wait covers
|
|
912
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
913
913
|
|
|
914
914
|
`Commit & Start` puts it in flight · `Commit` keeps it for later
|
|
915
915
|
|
|
@@ -579,10 +579,9 @@ line with it where the engine printed one, and nothing where it did not.
|
|
|
579
579
|
`.claude/rules/spec-reports.md` carries the shape, including why a rigid
|
|
580
580
|
contract took that line.
|
|
581
581
|
|
|
582
|
-
- **Never write the review unasked**, and **never publish
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
`/spec-diff` §6 owns how.
|
|
582
|
+
- **Never write the review unasked**, and **never publish** — there is no
|
|
583
|
+
publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
|
|
584
|
+
stack says why nothing was served.
|
|
586
585
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
587
586
|
It is still printed, and it is still the only place that question is answered —
|
|
588
587
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -592,22 +591,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
592
591
|
underneath a reader when detection flipped mid-session.
|
|
593
592
|
|
|
594
593
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
594
|
+
their tier — the other addresses this machine has of that kind — so pass them
|
|
595
|
+
on rather than editing them out: in the banner they are indented sub-bullets
|
|
596
|
+
under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
|
|
597
|
+
shows.
|
|
599
598
|
|
|
600
599
|
**Never read an environment variable to decide anything about the offer** — not
|
|
601
600
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
602
601
|
here for a detection to decide, and a second implementation of one could not be
|
|
603
602
|
tested and would drift.
|
|
604
603
|
|
|
605
|
-
**Serving is the engine's to do
|
|
604
|
+
**Serving is the engine's to do, and there is nothing else.** A `remote` reader
|
|
606
605
|
authorises a local server — one process, ended by one flag, leaving nothing
|
|
607
|
-
behind
|
|
608
|
-
|
|
609
|
-
serve (a busy port, a machine with no network address) it falls back to the
|
|
610
|
-
`file://` URL with its marker, and that is when publishing is worth naming.
|
|
606
|
+
behind. If the engine could not serve (a busy port, a machine with no network
|
|
607
|
+
address) it falls back to the `file://` URL with its marker.
|
|
611
608
|
|
|
612
609
|
- **Never fatal.** A failed render — no worktree, a git error — is one line, and
|
|
613
610
|
the fix is still done. The page is a convenience; the repo is the record.
|
|
@@ -14,11 +14,11 @@ A phase is built in its own worktree, and the terminal is somewhere else — so
|
|
|
14
14
|
`git diff` answers about the wrong branch and a 350-line diff read as terminal
|
|
15
15
|
text is scrolling, not review. This renders the diff as a page instead: the
|
|
16
16
|
engine collects it with `git -C`, writes a self-contained HTML file, and you open
|
|
17
|
-
it locally or
|
|
17
|
+
it locally, or on a phone over your LAN or tailnet.
|
|
18
18
|
|
|
19
19
|
**The diff never passes through the model.** git writes the patches and the
|
|
20
20
|
engine splices them into the page. A 266KB patch costs **zero** context tokens,
|
|
21
|
-
and a 289KB page costs the same to
|
|
21
|
+
and a 289KB page costs the same to serve as a 5KB one. Do not "simplify" this
|
|
22
22
|
by reading the diff and emitting HTML — that is the one change that would undo
|
|
23
23
|
the whole design.
|
|
24
24
|
|
|
@@ -354,8 +354,8 @@ spend it.
|
|
|
354
354
|
|
|
355
355
|
## 2b. An action changes something, then hands the page back
|
|
356
356
|
|
|
357
|
-
Only on a pass carrying an **action**.
|
|
358
|
-
**
|
|
357
|
+
Only on a pass carrying an **action**. Two of them, and
|
|
358
|
+
**both end the same way**:
|
|
359
359
|
do the thing, re-render (§4), and wait again (§4b) — because the reader
|
|
360
360
|
still has a decision in front of them and has not made it.
|
|
361
361
|
|
|
@@ -363,7 +363,11 @@ still has a decision in front of them and has not made it.
|
|
|
363
363
|
|--------|----|------|
|
|
364
364
|
| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
|
|
365
365
|
| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
|
|
366
|
-
|
|
366
|
+
|
|
367
|
+
**There is no `allow-remote` either.** It permitted publishing the page as a
|
|
368
|
+
claude.ai artifact, and that tier was retired (feat-tailnet-remote-tier):
|
|
369
|
+
`remote` is the tailnet address now, on `network`'s switch, so `allow-network`
|
|
370
|
+
turns both on.
|
|
367
371
|
|
|
368
372
|
**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
|
|
369
373
|
live is about the diff on screen; handing the whole instance back to `main` is a
|
|
@@ -371,7 +375,7 @@ workspace decision with nothing to do with this review. The `live:` line names
|
|
|
371
375
|
`/spec-live main` for it — a command the operator types, which is also why no
|
|
372
376
|
skill runs it.
|
|
373
377
|
|
|
374
|
-
**AN ACTION IS NOT A VERDICT, and the gate is untouched by
|
|
378
|
+
**AN ACTION IS NOT A VERDICT, and the gate is untouched by both.** A phase
|
|
375
379
|
that ended armed the gate, and it is discharged by a committing verdict or a
|
|
376
380
|
recorded skip and by nothing else — so after any of these the phase still owes
|
|
377
381
|
an answer, and that is exactly why the run waits again rather than finishing.
|
|
@@ -425,17 +429,9 @@ edits `specs/.core/env.config.json` in the **primary checkout**, so it changes
|
|
|
425
429
|
behaviour for everyone who pulls and leaves that tree dirty — one server binds
|
|
426
430
|
for every spec, so the bind cannot be narrower. The engine prints the absolute
|
|
427
431
|
path; relay that rather than letting a shared setting change land silently.
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
over the network kills the page doing the turning.
|
|
432
|
-
|
|
433
|
-
**`allow remote` permits publishing. It does not publish by itself.**
|
|
434
|
-
Publishing stays an explicit ask (§6), because the page it leaves behind is one
|
|
435
|
-
this tooling cannot remove. A reader who presses `Allow remote` on the page, or
|
|
436
|
-
types `/spec-remote-review` beside a waiting review, **has** asked: the engine
|
|
437
|
-
names the page on its `review:`/`publish:` lines, and that page is published
|
|
438
|
-
and the stack re-shown. Nothing it does not name is published.
|
|
432
|
+
And it is **enable-only**: there is no action that turns a tier off, because
|
|
433
|
+
turning `network` off from a page reached over the network kills the page doing
|
|
434
|
+
the turning.
|
|
439
435
|
|
|
440
436
|
## 3. Gate it on nothing
|
|
441
437
|
|
|
@@ -493,7 +489,7 @@ could not run is that strip's business rather than yours.
|
|
|
493
489
|
|
|
494
490
|
**There is no switch left to handle.** The engine serves and prints a **stack** —
|
|
495
491
|
one line per tier, `local`, `network`, `remote`, each either a URL or the one
|
|
496
|
-
command that turns it on. All of it is free and
|
|
492
|
+
command that turns it on. All of it is free, and all of it is one server.
|
|
497
493
|
You are not choosing between them; you are relaying every line it printed.
|
|
498
494
|
`.claude/rules/spec-reports.md` carries the shape and why.
|
|
499
495
|
|
|
@@ -564,7 +560,7 @@ says:
|
|
|
564
560
|
|------|---------|
|
|
565
561
|
| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
|
|
566
562
|
| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
|
|
567
|
-
| `remote` | the
|
|
563
|
+
| `remote` | the tailnet URL, labelled `(tailnet)` — or `off` with `network`'s command, or `no tailnet address on this machine` |
|
|
568
564
|
|
|
569
565
|
**The `reader:` line decides nothing here any more.** It is still printed and
|
|
570
566
|
still the only place that question is answered, but the offer no longer branches
|
|
@@ -581,23 +577,20 @@ tested and would drift. The ranking and the traps
|
|
|
581
577
|
a tty under Claude Code) live in `review.js` beside the code, which is where they
|
|
582
578
|
belong.
|
|
583
579
|
|
|
584
|
-
**It authorises serving,
|
|
585
|
-
local server — one process, ended by one flag, leaving nothing
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
`specs/complete/bug-remote-reader-gets-a-dead-link/`.
|
|
580
|
+
**It authorises serving, and serving is all there is.** A `remote` reader
|
|
581
|
+
authorises a local server — one process, ended by one flag, leaving nothing
|
|
582
|
+
behind. Publishing the page was once a second answer and was retired with the
|
|
583
|
+
published tier (feat-tailnet-remote-tier): the tailnet reaches a reader off the
|
|
584
|
+
wifi without a page this tooling could never remove.
|
|
590
585
|
|
|
591
586
|
When serving fails — a busy port, or a machine with no network address — the
|
|
592
|
-
engine falls back to the `file://` URL with its marker and nothing breaks.
|
|
593
|
-
is the one case where naming publishing is worth doing, because it is the only
|
|
594
|
-
answer left.
|
|
587
|
+
engine falls back to the `file://` URL with its marker and nothing breaks.
|
|
595
588
|
|
|
596
589
|
`review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
|
|
597
590
|
operator settle where they are reading, and an explicit value is believed without
|
|
598
591
|
sniffing. What the engine may *do* is settled by the tier settings instead —
|
|
599
|
-
`review.serve` (`always` · `never`)
|
|
600
|
-
|
|
592
|
+
`review.serve` (`always` · `never`) and `review.allowNetwork` — not by the
|
|
593
|
+
reader.
|
|
601
594
|
|
|
602
595
|
## 4b. Wait for the verdict — because asking for one means waiting for it
|
|
603
596
|
|
|
@@ -623,9 +616,6 @@ transport only decides what carries the answer back:
|
|
|
623
616
|
- **A `file://` page** has nothing to post to, so the reader pastes the pass and
|
|
624
617
|
their next message carries it. Say you are holding and **end the turn** — that
|
|
625
618
|
is the same wait, carried by the conversation. It is not a lesser one.
|
|
626
|
-
- **A published page** writes to the artifact's own store, which nothing reaches
|
|
627
|
-
from here. That is the one case where the honest sentence is *press a verdict,
|
|
628
|
-
then type `/spec-reviewed`* — see the published-page paragraph below.
|
|
629
619
|
|
|
630
620
|
**Do not ask, and therefore do not wait, on a render nobody is waiting behind** —
|
|
631
621
|
a bare `--page-only`, a page produced alongside other work, a pass that has
|
|
@@ -673,18 +663,15 @@ the stranger's pass the old rule was written about, and two arrivals refuse
|
|
|
673
663
|
rather than pick. What is left of the old rule is unchanged and still absolute —
|
|
674
664
|
outside this window, a pass is claimed because a person named it.
|
|
675
665
|
|
|
676
|
-
**The wait covers
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
notice, and it was made three times in a row while three verdicts sat unread.
|
|
682
|
-
Where the page is published, say plainly that `/spec-reviewed` is what picks it
|
|
683
|
-
up.
|
|
666
|
+
**The wait covers every served door.** It watches the engine's local store,
|
|
667
|
+
which is where a served page POSTs — from `local`, `network` or `remote` alike,
|
|
668
|
+
since all three are the same server. A published page once wrote to a store no
|
|
669
|
+
watch reached, and three verdicts sat unread under a line claiming the run was
|
|
670
|
+
waiting; that is why the published tier was retired rather than caveated.
|
|
684
671
|
|
|
685
672
|
**`/spec-reviewed` is not replaced by this.** It stays the way in for a pass
|
|
686
|
-
that arrived when nobody was waiting, for the two-passes case
|
|
687
|
-
|
|
673
|
+
that arrived when nobody was waiting, and for the two-passes case. It is
|
|
674
|
+
user-only, and that is still the
|
|
688
675
|
enforcement that makes a named claim a person's decision.
|
|
689
676
|
|
|
690
677
|
**A harness with no file-watch is no longer on that list**, and that is the
|
|
@@ -743,78 +730,23 @@ Then re-render with it spliced in — the engine renders it, you never emit HTML
|
|
|
743
730
|
skitterspec spec-env review <spec> --review <file>
|
|
744
731
|
```
|
|
745
732
|
|
|
746
|
-
## 6.
|
|
747
|
-
|
|
748
|
-
**
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
decision is being made, so it is the moment worth saying it — `spec-env down`
|
|
764
|
-
repeats it at teardown, by which point the page has outlived the spec.
|
|
765
|
-
- **Degrade in one line.** If the harness cannot publish — no capability, an
|
|
766
|
-
error — say so, report the local file path, and carry on. That is a working
|
|
767
|
-
outcome, not a failure.
|
|
768
|
-
- **Reach for `--publish-copy`, never a hand transform.** The engine writes the
|
|
769
|
-
page as a complete HTML document and an artifact host wraps page *content*, so
|
|
770
|
-
publishing the page as-written nests two documents. `spec-env review <spec>
|
|
771
|
-
--publish-copy` emits the body-only copy and names its path on a `publish:`
|
|
772
|
-
line. Do not split the document yourself: a rendered page contains the diff,
|
|
773
|
-
and a diff of this project contains `<!doctype html>` as ordinary patch text.
|
|
774
|
-
|
|
775
|
-
The engine knows nothing about publishing and cannot do it. It writes a file and
|
|
776
|
-
reads a URL back as an opaque string; everything about what that string means
|
|
777
|
-
lives here.
|
|
778
|
-
|
|
779
|
-
### Publish it so the buttons still work
|
|
780
|
-
|
|
781
|
-
A published page is the answer for a reader **no local server can reach** — a
|
|
782
|
-
phone on mobile data, anyone away from the LAN the engine serves on. It is also
|
|
783
|
-
the one surface where the verdict buttons have nowhere to POST: the page's own
|
|
784
|
-
URL is on claude.ai, so a POST fails and the reader gets "could not reach the
|
|
785
|
-
server" after pressing a verdict they meant.
|
|
786
|
-
|
|
787
|
-
So **publish it with a store**, and the page uses it:
|
|
788
|
-
|
|
789
|
-
- Declare `capabilities: {db: {}}`. The page checks for `window.claude.use` and
|
|
790
|
-
writes the pass into the artifact's own `passes` collection instead of
|
|
791
|
-
POSTing. Nothing else about it changes — same marks, same verdicts, same
|
|
792
|
-
refusal to commit over an open comment.
|
|
793
|
-
- **Do not declare `user`.** The pass is not per-viewer private state, a shared
|
|
794
|
-
collection is what it wants, and a declaration nothing uses is a grant asked
|
|
795
|
-
for nothing.
|
|
796
|
-
- **Same file path every time**, so a redeploy reuses the URL. That is what
|
|
797
|
-
answers the clear-down worry: one page per spec, replaced at each render,
|
|
798
|
-
rather than an artifact per phase accumulating in the gallery.
|
|
799
|
-
- **Send a push notification with the URL** when you publish. The reader is by
|
|
800
|
-
definition somewhere else — that is why it was published.
|
|
801
|
-
|
|
802
|
-
### Taking a stored pass back
|
|
803
|
-
|
|
804
|
-
A pass in the store is claimed the same way in spirit and a different way in
|
|
805
|
-
mechanism, because the engine cannot see it:
|
|
806
|
-
|
|
807
|
-
1. Read the `passes` collection with the Artifact tool's `read_db`.
|
|
808
|
-
2. **Apply step 0 unchanged.** One waiting pass, offered by what it says and
|
|
809
|
-
when it was sent; two is a refusal to guess. Nothing here is automatic —
|
|
810
|
-
there is no wait window on this transport, because nothing pushes from the
|
|
811
|
-
store to this conversation.
|
|
812
|
-
3. Write the pass's `blob` to a scratch file **verbatim** and merge it with
|
|
813
|
-
`spec-env review <spec> --notes <file>`. It rejoins the ordinary path at §2
|
|
814
|
-
step 1, so the verdict is judged and routed exactly as any other.
|
|
815
|
-
4. **Delete the document** with `write_db` once it is merged. A claim consumes:
|
|
816
|
-
a pass left in the store is claimable twice, which is the one property the
|
|
817
|
-
six-digit code has always had and this transport must not lose.
|
|
733
|
+
## 6. There is no publishing
|
|
734
|
+
|
|
735
|
+
**This skill does not publish the page, and nothing in this workflow does.**
|
|
736
|
+
Publishing it as a claude.ai artifact was retired with the published tier
|
|
737
|
+
(feat-tailnet-remote-tier). It wrote to a store no wait could watch, and left a
|
|
738
|
+
page this tooling could never remove. A reader off the wifi opens the `remote`
|
|
739
|
+
line — the review server's tailnet address — and sends the verdict into the
|
|
740
|
+
same store as every other door.
|
|
741
|
+
|
|
742
|
+
**Where no door reaches the reader** — no network, no tailnet, a server that
|
|
743
|
+
could not start — say so plainly with the stack the engine printed, and stop.
|
|
744
|
+
Do not reach for the Artifact tool as a fallback: that is the second store this
|
|
745
|
+
design removed.
|
|
746
|
+
|
|
747
|
+
A page published before this change still exists, and teardown still names it
|
|
748
|
+
(`spec-env down` reads the `.url` sidecar it left). Nothing writes that sidecar
|
|
749
|
+
any more.
|
|
818
750
|
|
|
819
751
|
## 7. Report
|
|
820
752
|
|