@skitterbyte/skitterspec-linear 19.16.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.
- package/MIGRATION.md +27 -0
- package/README.md +0 -1
- 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 +19 -25
- package/assets/review/page.html +10 -83
- package/assets/rules/spec-planning.md +14 -21
- package/assets/rules/spec-reports.md +52 -52
- 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 +48 -41
- 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 +192 -202
- package/src/env/config.js +16 -7
- 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 +98 -3
- package/assets/commands/spec-remote-review.md +0 -37
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## The tailnet is `remote`; publishing the review is retired (nothing to edit)
|
|
4
|
+
|
|
5
|
+
The review stack's `remote:` line used to be a claude.ai page the review was
|
|
6
|
+
published to. That tier is gone. `remote:` is now the review server's
|
|
7
|
+
**tailnet address**, on its own line, labelled `(tailnet)`. It is the same
|
|
8
|
+
server as `local` and `network`, so one wait covers all three, and a verdict
|
|
9
|
+
pressed there wakes the waiting session like any other.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
local: http://127.0.0.1:7760/7e9e…/feat-orders
|
|
13
|
+
network: http://192.168.0.136:7760/7e9e…/feat-orders
|
|
14
|
+
remote: http://100.126.111.34:7760/7e9e…/feat-orders (tailnet)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
- **`/spec-remote-review` is removed.** `skitterspec update` retires the command
|
|
18
|
+
file. A copy you edited is kept, with the usual warning, and you can delete
|
|
19
|
+
it.
|
|
20
|
+
- **`review.allowRemote` is ignored.** A config that still sets it loads
|
|
21
|
+
without a warning, and you can delete the key whenever you like.
|
|
22
|
+
`spec-env review allow remote` now refuses and names the tailnet line.
|
|
23
|
+
- **`remote` follows `review.allowNetwork`.** It is off whenever `network` is,
|
|
24
|
+
with the same command to turn it on. On a machine with no tailnet address it
|
|
25
|
+
reads `— (no tailnet address on this machine)`.
|
|
26
|
+
- **`--publish-copy` is gone**, along with the page's published mode and its
|
|
27
|
+
`Allow remote` button. A page published before this change still exists, and
|
|
28
|
+
`spec-env down` still names it at teardown.
|
|
29
|
+
|
|
3
30
|
## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
|
|
4
31
|
|
|
5
32
|
Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
|
package/README.md
CHANGED
|
@@ -96,7 +96,6 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
96
96
|
| `/spec-init` | Bootstrap or repair the workflow in a project |
|
|
97
97
|
| `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
|
|
98
98
|
| `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
|
|
99
|
-
| `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
|
|
100
99
|
| `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
|
|
101
100
|
| `/allow-project` | Let this session work on another skitterspec project — yours to run, never Claude's |
|
|
102
101
|
| `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
|
|
@@ -12,8 +12,8 @@ skill that wants one will tell you to type it.
|
|
|
12
12
|
|
|
13
13
|
**Seeing the work.** A phase is built in its own worktree, so `git diff` in your
|
|
14
14
|
terminal answers about the base branch. **`/spec-diff`** renders that worktree's
|
|
15
|
-
diff as a self-contained HTML page you open locally — or
|
|
16
|
-
|
|
15
|
+
diff as a self-contained HTML page you open locally — or on a phone, over your
|
|
16
|
+
LAN or tailnet. The diff never passes through the model, so the page costs no context
|
|
17
17
|
tokens however large it is; the optional written review is the part that costs,
|
|
18
18
|
and it is offered rather than assumed. `/spec-next` writes the page at the end of
|
|
19
19
|
every phase. **`skitterspec status`** lists what is in flight across worktrees.
|
|
@@ -98,13 +98,10 @@ running and concluded nothing, so the phase still owes an answer.
|
|
|
98
98
|
|
|
99
99
|
**Every render lists where the page can be read**, labelled, in a fixed order —
|
|
100
100
|
`local`, `network`, `remote` — each either a URL or the one command that turns it
|
|
101
|
-
on, plus a `live:` line saying whether the change is also running.
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
|
|
106
|
-
command, never performed by it: a published page is one this tooling cannot
|
|
107
|
-
remove.
|
|
101
|
+
on, plus a `live:` line saying whether the change is also running. They are
|
|
102
|
+
labelled by address: `local` is this machine, `network` your LAN, `remote` your
|
|
103
|
+
tailnet. All three are doors into one room — the same server and the same
|
|
104
|
+
waiting verdict — so one wait covers every one the stack shows.
|
|
108
105
|
|
|
109
106
|
**One ending.** Every spec skill finishes with the same block — a verdict
|
|
110
107
|
(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
|
|
@@ -26,8 +26,7 @@ id it degrades to a repo-wide allow that outlives the session and is cleared onl
|
|
|
26
26
|
by `/allow-main off`; the engine says which kind you got, so do not read a bare
|
|
27
27
|
"allowed" as temporary.
|
|
28
28
|
|
|
29
|
-
**It is machine-local and gitignored.**
|
|
30
|
-
nothing anyone else pulls: it is your decision about your checkout, not the
|
|
29
|
+
**It is machine-local and gitignored.** It writes nothing anyone else pulls: it is your decision about your checkout, not the
|
|
31
30
|
project's policy. The project-wide switch is `guards.mainIsLandingZone` in
|
|
32
31
|
`specs/.core/env.config.json`, and turning that off is a different, committed
|
|
33
32
|
decision.
|
|
@@ -601,14 +601,13 @@ through to a documented conservative default; see the field notes below.
|
|
|
601
601
|
// It replaced `serveOnRemote`, which gated serving on the reader — and so
|
|
602
602
|
// handed a local machine a page it could read and not answer. A legacy
|
|
603
603
|
// `serveOnRemote: false` is still read as `serve: "never"`.
|
|
604
|
-
// Either way NOTHING IS PUBLISHED
|
|
605
|
-
//
|
|
606
|
-
// remove, so that half stays an explicit ask. Teardown names a server that
|
|
604
|
+
// Either way NOTHING IS PUBLISHED: a server is one process ended by one flag,
|
|
605
|
+
// and nothing in this workflow publishes the page. Teardown names a server that
|
|
607
606
|
// served the last spec, and `spec-env prune` reaps a pidfile whose process is
|
|
608
607
|
// gone. Default: true.
|
|
609
608
|
//
|
|
610
|
-
// `allowNetwork`
|
|
611
|
-
//
|
|
609
|
+
// `allowNetwork` decides WHICH TIERS a render offers beyond `local`, and it
|
|
610
|
+
// replaced the engine guessing where the reader was sitting. It guessed
|
|
612
611
|
// for a while and got it wrong three separate ways in one day: a file:// page
|
|
613
612
|
// on a session detected `unknown`, a LAN URL for a phone that had left the
|
|
614
613
|
// network, and an address that changed underneath a reader mid-session. So
|
|
@@ -616,26 +615,21 @@ through to a documented conservative default; see the field notes below.
|
|
|
616
615
|
// turns it on — and you pick the one that reaches you.
|
|
617
616
|
//
|
|
618
617
|
// `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
|
|
619
|
-
// page opens on your phone
|
|
620
|
-
//
|
|
621
|
-
//
|
|
622
|
-
//
|
|
623
|
-
//
|
|
624
|
-
//
|
|
625
|
-
//
|
|
626
|
-
//
|
|
627
|
-
//
|
|
628
|
-
//
|
|
629
|
-
//
|
|
630
|
-
//
|
|
631
|
-
//
|
|
632
|
-
//
|
|
633
|
-
//
|
|
634
|
-
// pressed on a published page needs `/spec-reviewed`, because nothing pushes
|
|
635
|
-
// from an artifact's store into a conversation.
|
|
636
|
-
//
|
|
637
|
-
// Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
|
|
638
|
-
// empty value toggles — which is what `/spec-remote-review` runs. It writes
|
|
618
|
+
// page opens on your phone (`network`, the LAN URL) and
|
|
619
|
+
// over your tailnet (`remote`), or loopback only. THIS IS
|
|
620
|
+
// WHAT CHOOSES THE BIND; `reader` no longer does.
|
|
621
|
+
// Default: true, which matches what the engine already did.
|
|
622
|
+
// `allowRemote` — RETIRED, and ignored if present. It permitted publishing
|
|
623
|
+
// the page as a claude.ai artifact; that tier is gone, and
|
|
624
|
+
// `remote` now names the tailnet address on
|
|
625
|
+
// `allowNetwork`'s switch (feat-tailnet-remote-tier).
|
|
626
|
+
//
|
|
627
|
+
// `local`, `network` and `remote` are three doors into ONE ROOM — the page
|
|
628
|
+
// POSTs to `location.pathname`, so each reaches the same server and the same
|
|
629
|
+
// waiting verdict, and one wait covers them all.
|
|
630
|
+
//
|
|
631
|
+
// It is toggled by `spec-env review allow network --set [on|off]`, where an
|
|
632
|
+
// empty value toggles. It writes
|
|
639
633
|
// THIS FILE in the primary checkout, so it changes for everyone who pulls and
|
|
640
634
|
// leaves that tree dirty; the engine says so when it does.
|
|
641
635
|
//
|
package/assets/review/page.html
CHANGED
|
@@ -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
|
|
2043
|
-
*
|
|
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
|
|
2774
|
-
//
|
|
2775
|
-
|
|
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
|
|
2985
|
-
//
|
|
2986
|
-
//
|
|
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.
|
|
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'
|
|
2974
|
+
var SURFACE_LABEL = { live: 'live', network: 'network' }
|
|
3048
2975
|
|
|
3049
2976
|
function surfaceStateText(row) {
|
|
3050
2977
|
if (row.kind === 'live') {
|
|
@@ -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
|
|
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
|
|
|
@@ -28,7 +28,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
|
|
|
28
28
|
| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
|
|
29
29
|
|
|
30
30
|
**Skills vs commands.** The table above lists **skills** — Claude reads them and
|
|
31
|
-
exercises judgment. `/spec-connect
|
|
31
|
+
exercises judgment. `/spec-connect` and `/spec-live` are
|
|
32
32
|
instead **slash commands**
|
|
33
33
|
(`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
|
|
34
34
|
relays its output, so there is no judgment to apply and no model turn spent
|
|
@@ -36,19 +36,12 @@ finding one. They are marked `disable-model-invocation`, meaning
|
|
|
36
36
|
**only you can run them** — a skill that wants one will tell you to type it
|
|
37
37
|
rather than invoking it.
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
It exists because a render's `remote:` line has to name something a person can
|
|
46
|
-
act on, and `skitterspec spec-env review allow remote` is not what anyone
|
|
47
|
-
reconstructs from a page they are reading on a phone. Making the line
|
|
48
|
-
*clickable* was considered and rejected — the only clickable thing markdown has
|
|
49
|
-
is a URL, and a URL that acts when it is **fetched** is one a link previewer or
|
|
50
|
-
a prefetcher fires with nobody involved. It **permits** publishing; it publishes
|
|
51
|
-
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.
|
|
52
45
|
|
|
53
46
|
`/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
|
|
54
47
|
convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
|
|
@@ -121,8 +114,8 @@ already use, so one category is not spelled two ways. `/spec-init` asks for
|
|
|
121
114
|
both — on an existing config through a `/no-spec` branch, since the base
|
|
122
115
|
branch is a landing zone.
|
|
123
116
|
|
|
124
|
-
**`/allow-main` is the
|
|
125
|
-
from the other
|
|
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`
|
|
126
119
|
are marked that way because there is no judgment to apply. This one is marked that
|
|
127
120
|
way because **Claude must not be able to lift a guard aimed at Claude.**
|
|
128
121
|
|
|
@@ -172,7 +165,7 @@ it fails open on every cannot-tell. `/allow-project <name>` lifts it for one
|
|
|
172
165
|
session, and it is user-only for `/allow-main`'s reason: Claude must not be
|
|
173
166
|
able to lift a guard aimed at Claude.
|
|
174
167
|
|
|
175
|
-
**`/spec-skip` is the
|
|
168
|
+
**`/spec-skip` is the fourth command**, and it is user-only for `/allow-main`'s
|
|
176
169
|
reason rather than the mild one: it lifts the review gate, which is a guard
|
|
177
170
|
aimed at Claude. It pre-executes `skitterspec spec-env review skip "<reason>"`
|
|
178
171
|
and relays it — the same exit that always existed, at an address a person will
|
|
@@ -189,7 +182,7 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
|
|
|
189
182
|
is worse: `/commit` belongs to skittership, which is why the gate is enforced
|
|
190
183
|
by a hook rather than by editing that skill.
|
|
191
184
|
|
|
192
|
-
**`/spec-epic` is the
|
|
185
|
+
**`/spec-epic` is the fifth command**, and it is user-only for the mild reason: it
|
|
193
186
|
pre-executes `skitterspec epic status` and relays it, so there is no judgement
|
|
194
187
|
to apply. It exists for the tab an epic is run from — each member is built in
|
|
195
188
|
a tab of its own, and on a phone the in-app browser has to close to switch
|
|
@@ -380,7 +373,7 @@ the base branch — and a 350-line diff read as terminal text is scrolling, not
|
|
|
380
373
|
review. The engine collects the worktree's changes with `git -C` and writes a
|
|
381
374
|
self-contained HTML page (`.spec-env/reviews/<spec>.html`, gitignored) with
|
|
382
375
|
whole-file context that folds away, a file tree, and new files included. You open
|
|
383
|
-
it locally, or
|
|
376
|
+
it locally, or on a phone over your LAN or tailnet.
|
|
384
377
|
**The diff never passes through the model**, so the page is free to produce
|
|
385
378
|
however large it is; the *written*
|
|
386
379
|
review — a short read plus `flag`/`confirm`/`good` notes — is the part that costs
|
|
@@ -559,7 +552,7 @@ its verdicts and its fields.
|
|
|
559
552
|
| **Branch** | `spec/feat-orders` · 3 commits, clean |
|
|
560
553
|
| **Built** | POST /orders handler, orders schema |
|
|
561
554
|
| **Tests** | 128 passed · dotnet test |
|
|
562
|
-
| **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**
|
|
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) |
|
|
563
556
|
| **Follow-ups** | none |
|
|
564
557
|
| **Next** | `/spec-next` → phase 3 (Auth) |
|
|
565
558
|
|
|
@@ -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.
|
|
@@ -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
|
|
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** — <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
|
|
|
@@ -935,9 +935,9 @@ this page's two exits:
|
|
|
935
935
|
|
|
936
936
|
- **local** — <the `local:` URL>
|
|
937
937
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
938
|
-
- **remote** — <the `remote:` URL, or
|
|
938
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
939
939
|
|
|
940
|
-
I'm holding here until you send a verdict — the wait covers
|
|
940
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
941
941
|
|
|
942
942
|
`Commit & Start` puts it in flight · `Commit` keeps it for later
|
|
943
943
|
|