@skitterbyte/skitterspec-jira 2.15.0 → 2.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/assets/claude-md-section.md +18 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/SETUP.md +12 -12
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +28 -26
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +10 -83
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/spec-planning.md +26 -22
- package/assets/rules/spec-reports.md +52 -52
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +22 -5
- package/assets/skills/spec-bug/SKILL.md +18 -15
- package/assets/skills/spec-complete/SKILL.md +23 -1
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +18 -15
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +66 -41
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/assets/skills/spec-sync/SKILL.md +10 -10
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +361 -208
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +27 -7
- package/src/env/hooks.js +53 -4
- package/src/env/live.js +48 -0
- package/src/env/provision.js +10 -2
- package/src/env/resume.js +234 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +383 -50
- package/src/tada/todo.js +19 -4
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
- package/assets/commands/spec-remote-review.md +0 -37
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') {
|
|
@@ -23,7 +23,7 @@ Refs: PROJ-29
|
|
|
23
23
|
Get the value from the engine rather than reading it off a spec by hand:
|
|
24
24
|
|
|
25
25
|
```
|
|
26
|
-
|
|
26
|
+
{{exec}} skitterspec-jira 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
|
-
|
|
51
|
+
{{exec}} skitterspec-jira 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
|
|
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
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
|
123
|
-
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`
|
|
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
|
|
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
|
|
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
|
|
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**
|
|
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/…)
|
|
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
|
|
|
@@ -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,
|
|
40
|
-
|
|
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 (`getJiraIssue`):
|
|
42
48
|
title, description, labels, reporter, URL. If Jira isn't connected, say so
|
|
43
49
|
and offer to carry on without it — a spec written from the user's own
|
|
@@ -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. **
|
|
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
|
|
|
@@ -890,9 +907,9 @@ this page's two exits:
|
|
|
890
907
|
|
|
891
908
|
- **local** — <the `local:` URL>
|
|
892
909
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
893
|
-
- **remote** — <the `remote:` URL, or
|
|
910
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
894
911
|
|
|
895
|
-
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>.
|
|
896
913
|
|
|
897
914
|
`Commit & Start` puts it in flight · `Commit` keeps it for later
|
|
898
915
|
|
|
@@ -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,
|
|
39
|
-
|
|
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 (`getJiraIssue`):
|
|
41
47
|
title, description, labels, reporter, URL. If Jira isn't connected, say so
|
|
42
48
|
and offer to carry on without it — a spec written from the user's own
|
|
@@ -573,10 +579,9 @@ line with it where the engine printed one, and nothing where it did not.
|
|
|
573
579
|
`.claude/rules/spec-reports.md` carries the shape, including why a rigid
|
|
574
580
|
contract took that line.
|
|
575
581
|
|
|
576
|
-
- **Never write the review unasked**, and **never publish
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
`/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.
|
|
580
585
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
581
586
|
It is still printed, and it is still the only place that question is answered —
|
|
582
587
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -586,22 +591,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
586
591
|
underneath a reader when detection flipped mid-session.
|
|
587
592
|
|
|
588
593
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
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.
|
|
593
598
|
|
|
594
599
|
**Never read an environment variable to decide anything about the offer** — not
|
|
595
600
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
596
601
|
here for a detection to decide, and a second implementation of one could not be
|
|
597
602
|
tested and would drift.
|
|
598
603
|
|
|
599
|
-
**Serving is the engine's to do
|
|
604
|
+
**Serving is the engine's to do, and there is nothing else.** A `remote` reader
|
|
600
605
|
authorises a local server — one process, ended by one flag, leaving nothing
|
|
601
|
-
behind
|
|
602
|
-
|
|
603
|
-
serve (a busy port, a machine with no network address) it falls back to the
|
|
604
|
-
`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.
|
|
605
608
|
|
|
606
609
|
- **Never fatal.** A failed render — no worktree, a git error — is one line, and
|
|
607
610
|
the fix is still done. The page is a convenience; the repo is the record.
|