@skitterbyte/skitterspec-linear 19.2.0 → 19.4.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/assets/claude-md-section.md +20 -1
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +90 -6
- package/assets/core/linear.config.json.example +2 -2
- package/assets/core/linear.config.md +49 -16
- package/assets/hooks/main-guard.cjs +18 -2
- package/assets/hooks/review-gate.cjs +19 -2
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +131 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +95 -6
- package/assets/skills/spec-bug/SKILL.md +68 -3
- package/assets/skills/spec-cancel/SKILL.md +37 -0
- package/assets/skills/spec-claim/SKILL.md +41 -2
- package/assets/skills/spec-complete/SKILL.md +115 -0
- package/assets/skills/spec-hotfix/SKILL.md +72 -4
- package/assets/skills/spec-incident/SKILL.md +44 -0
- package/assets/skills/spec-linear-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +12 -5
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +34 -0
- package/assets/skills/spec-start/SKILL.md +50 -3
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1091 -39
- package/src/env/base.js +104 -0
- package/src/env/config.js +75 -3
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +80 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +225 -0
- package/src/env/hotfixland.js +103 -9
- package/src/env/inflight.js +95 -0
- package/src/env/integrate.js +130 -4
- package/src/env/mainguard.js +6 -0
- package/src/env/phases.js +28 -0
- package/src/env/provision.js +18 -6
- package/src/env/resolve.js +108 -9
- package/src/env/serve.js +6 -1
- package/src/env/specstate.js +101 -0
- package/src/env/teardown.js +42 -0
- package/src/vendor/linear/cli-sync.js +55 -6
- package/src/vendor/linear/config.js +27 -21
- package/src/vendor/linear/doctor.js +2 -0
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +49 -4
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +14 -1
- package/src/vendor/provider-kit/src/specs.js +4 -2
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +17 -5
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +26 -2
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -16,7 +16,7 @@ diff as a self-contained HTML page you open locally — or publish, and read on
|
|
|
16
16
|
phone. 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
|
-
every phase.
|
|
19
|
+
every phase. **`skitterspec status`** lists what is in flight across worktrees.
|
|
20
20
|
|
|
21
21
|
**Handing the review back.** The page takes marks: tick `✓ accept` per file as
|
|
22
22
|
you read, note anything against a line or a whole file, answer the questions a
|
|
@@ -34,6 +34,25 @@ An accept remembers the file's content, so it lapses by itself when that file
|
|
|
34
34
|
changes again. The marks are information — nothing gates on them; the verdict is
|
|
35
35
|
the one thing you choose, once.
|
|
36
36
|
|
|
37
|
+
**The phase waits for that press.** `/spec-next` ends a phase by rendering the
|
|
38
|
+
page and then watching for your verdict, so the button is what carries the work
|
|
39
|
+
on — no command to remember. What makes that safe is not that the page is
|
|
40
|
+
unreachable (it is reachable, deliberately): it is the **serve token** in the
|
|
41
|
+
URL, 48 random bits deciding who can POST at all, plus the **window** — only a
|
|
42
|
+
pass that arrives *while the session is waiting* is claimed for you, and two
|
|
43
|
+
arrivals refuse rather than pick. Outside that window nothing is claimed
|
|
44
|
+
unasked: type `/spec-reviewed`, or `/spec-reviewed 324199` to name one exactly,
|
|
45
|
+
which matters only when two are waiting. A `file://` page has no server to talk
|
|
46
|
+
to, so it copies and you paste, as before.
|
|
47
|
+
|
|
48
|
+
**And a phase that ended owes you an answer.** The gate is armed when the page
|
|
49
|
+
is rendered at the end of a phase, and cleared by a committing verdict or by
|
|
50
|
+
`skitterspec spec-env review skip "<reason>"` — while it is armed, `/spec-next`
|
|
51
|
+
refuses to build the next phase. Mid-phase renders arm nothing, every
|
|
52
|
+
cannot-tell exits 0 and says nothing, and `review.required: false` turns it off
|
|
53
|
+
for a project. The exit is always one command; one of them is *"I am moving
|
|
54
|
+
on"*, and that reason goes on the record.
|
|
55
|
+
|
|
37
56
|
**A second opinion, when you want one** (`review.reviewers`, empty by default).
|
|
38
57
|
Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
|
|
39
58
|
a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
|
|
@@ -5,7 +5,7 @@ stack + host dev servers + a front-door proxy per in-progress spec).
|
|
|
5
5
|
Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
|
|
6
6
|
`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
|
|
7
7
|
is `/spec-diff`; the `skitterspec spec-env
|
|
8
|
-
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
|
|
8
|
+
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
|
|
9
9
|
the engine beneath them.
|
|
10
10
|
|
|
11
11
|
**Once this file is present, isolation is the default policy:** `/spec-start` gives
|
|
@@ -284,9 +284,65 @@ through to a documented conservative default; see the field notes below.
|
|
|
284
284
|
// Integration base branch — the branch specs fork from and land back onto
|
|
285
285
|
// (used by the teardown "merged?" guard and, later, the integrate step).
|
|
286
286
|
// Empty = auto-detect: origin/HEAD → main → master. Set it when your default
|
|
287
|
-
// branch isn't discoverable (e.g. no remote) or differs (trunk, develop
|
|
287
|
+
// branch isn't discoverable (e.g. no remote) or differs (trunk, develop, a
|
|
288
|
+
// release-candidate branch). An explicit value always wins — it is the pin.
|
|
288
289
|
"baseBranch": "",
|
|
289
290
|
|
|
291
|
+
// A base that ROLLS: a glob over the remote's branch names (e.g. "20??/Q?")
|
|
292
|
+
// for teams that work off a release candidate versioned per release. The
|
|
293
|
+
// base is the NEWEST match by commit date, so cutting the next rc is all it
|
|
294
|
+
// takes to move every spec onto it — no config edit per release, no message
|
|
295
|
+
// to the team. Precedence: baseBranch (pin) → this pattern → origin/HEAD →
|
|
296
|
+
// main → master.
|
|
297
|
+
// - Matched against `refs/remotes/<land.remote>/*`, never the network:
|
|
298
|
+
// `spec-env up`, `integrate` and `spec-env base` fetch first; everything
|
|
299
|
+
// else reads what the last fetch saw.
|
|
300
|
+
// - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
|
|
301
|
+
// rc/a/b. Spell each segment ("20??/Q?").
|
|
302
|
+
// - No match REFUSES, naming `spec-env base` — it never falls back to
|
|
303
|
+
// origin/HEAD, because zero matches usually means "not fetched", and
|
|
304
|
+
// the default branch is exactly where a rolling base must not land.
|
|
305
|
+
// - Newest-by-date is only right when one rc is live at a time (the next
|
|
306
|
+
// is cut after the last merges). If your rcs overlap, pin `baseBranch`.
|
|
307
|
+
// - A spec that outlived a roll lands on the new rc; the integrate plan
|
|
308
|
+
// says `retarget: forked from <old> · landing onto <new>`, and switches
|
|
309
|
+
// a primary checkout still on the old rc before the fast-forward.
|
|
310
|
+
// A pattern holding whitespace or ".." is dropped (treated as unset).
|
|
311
|
+
// `spec-env base` lists the matches, the base, and specs on an older one.
|
|
312
|
+
"baseBranchPattern": "",
|
|
313
|
+
|
|
314
|
+
// How a finished branch reaches the base branch.
|
|
315
|
+
// strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
|
|
316
|
+
// exactly as always; nothing below applies.
|
|
317
|
+
// "pr" — the branch is pushed and a pull request carries it; the
|
|
318
|
+
// base branch moves only when the host merges. `spec-env
|
|
319
|
+
// integrate` then plans a rebase onto <remote>/<base> and a
|
|
320
|
+
// consent-gated push (`--push` consents; already-pushed-at-HEAD
|
|
321
|
+
// counts as consent; otherwise the plan holds), and a landed
|
|
322
|
+
// branch prints the finish — base catch-up plus the deferred
|
|
323
|
+
// `afterLand`. `--strategy ff|pr` on integrate overrides this per
|
|
324
|
+
// invocation; an unrecognised config value falls back to "ff".
|
|
325
|
+
// remote: where the branch is pushed. Default "origin".
|
|
326
|
+
// draft: mid-spec PRs open as drafts (a draft cannot be merged, so
|
|
327
|
+
// nothing downstream can close a ticket early); /spec-complete is
|
|
328
|
+
// what flips the PR to ready. Default true.
|
|
329
|
+
// specDocs: where a SPEC DOCUMENT lands under "pr". "trunk" (default) keeps
|
|
330
|
+
// today's authoring land — needs direct push for docs. "branch"
|
|
331
|
+
// has the spec ride the feature branch and land with the work's
|
|
332
|
+
// PR; the backlog is then found via the tracker listing, and the
|
|
333
|
+
// authoring worktree stays (it is the document's only copy).
|
|
334
|
+
// The merged-check and PR commands need the host's CLI — `gh` on github.com,
|
|
335
|
+
// `az` on dev.azure.com — detected from the remote URL, never configured. An
|
|
336
|
+
// unknown host (Enterprise/Server domains included) degrades to the ancestry
|
|
337
|
+
// test plus generic printed commands, and every failed lookup is a
|
|
338
|
+
// cannot-tell: teardown then HOLDS the worktree rather than guessing.
|
|
339
|
+
"land": {
|
|
340
|
+
"strategy": "ff",
|
|
341
|
+
"remote": "origin",
|
|
342
|
+
"draft": true,
|
|
343
|
+
"specDocs": "trunk"
|
|
344
|
+
},
|
|
345
|
+
|
|
290
346
|
// Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
|
|
291
347
|
// blocks when the commits are ALSO unmerged into the base branch — a branch
|
|
292
348
|
// already landed on base tears down (and its branch is deleted) without
|
|
@@ -297,9 +353,12 @@ through to a documented conservative default; see the field notes below.
|
|
|
297
353
|
},
|
|
298
354
|
|
|
299
355
|
// What teardown cleans up beyond this machine. Nothing publishes a spec
|
|
300
|
-
// branch
|
|
301
|
-
//
|
|
302
|
-
// forever.
|
|
356
|
+
// branch unasked — a remote copy exists because you pushed it by hand, or
|
|
357
|
+
// because a PR-mode land pushed it behind the consent gate — and without this
|
|
358
|
+
// a completed spec leaves that merged branch on the remote forever. (Hosts
|
|
359
|
+
// that auto-delete the branch on merge make the planned delete an
|
|
360
|
+
// already-gone no-op, reported as such, never as a failure.)
|
|
361
|
+
// `deleteRemoteBranch`:
|
|
303
362
|
// "prompt" (default) — plan `git push <remote> --delete <branch>` in its own
|
|
304
363
|
// "confirm with the user first" section; /spec-complete and
|
|
305
364
|
// /spec-cancel ask before running it.
|
|
@@ -358,11 +417,36 @@ through to a documented conservative default; see the field notes below.
|
|
|
358
417
|
// `hotfix land --push`; without it the land holds before the carry. The
|
|
359
418
|
// worktree stays until `spec-env hotfix finish`. Default: built-in patch tag,
|
|
360
419
|
// carry to main, no targets.
|
|
420
|
+
//
|
|
421
|
+
// `releaseBranch` makes hotfixes BRANCH-BASED, for a team whose release line
|
|
422
|
+
// is a branch rather than a tag. Worked example — an rc flow:
|
|
423
|
+
// master takes only rc merges and hotfixes; prod is whatever it holds
|
|
424
|
+
// 2026/Q4 the current release candidate (`baseBranchPattern: "20??/Q?"`)
|
|
425
|
+
// Test/Demo/Live env branches that take merges from master — OUT OF SCOPE:
|
|
426
|
+
// merging master into them stays your pipeline's job
|
|
427
|
+
// With `"releaseBranch": "master"`, `spec-env up hotfix-<name> --docs` fetches
|
|
428
|
+
// and forks from origin/master's head and prints the header to record —
|
|
429
|
+
// `> **Base version:** master@<sha>`. `hotfix land` then rebases onto
|
|
430
|
+
// origin/master and lands ON it by `land.strategy` (`--strategy` overrides):
|
|
431
|
+
// "ff" pushes the hotfix onto master; "pr" opens a READY pull request and
|
|
432
|
+
// holds until the host merges it. The fix is then carried to the resolved base
|
|
433
|
+
// (the newest rc) — directly under "ff", through a `carry/<slug>` branch and
|
|
434
|
+
// its own ready PR under "pr". `hotfix finish` tears down once both are
|
|
435
|
+
// confirmed. Empty (the default) = the tag flow above, unchanged; a hotfix
|
|
436
|
+
// keeps landing the way its own `Base version` says it was cut.
|
|
437
|
+
//
|
|
438
|
+
// `tag` (default true) keeps the release tag on a branch-based hotfix, bumped
|
|
439
|
+
// from the newest tag the release branch has; false is for a team whose deploy
|
|
440
|
+
// is driven by the env-branch merge rather than a tag. Under "pr",
|
|
441
|
+
// `releaseWith` refuses — a squash or rebase merge leaves its tag on a commit
|
|
442
|
+
// the release branch never has — so use the built-in tag there.
|
|
361
443
|
"hotfix": {
|
|
362
444
|
"releaseWith": "",
|
|
363
445
|
"bump": "patch",
|
|
364
446
|
"cherryPickMain": true,
|
|
365
|
-
"targets": []
|
|
447
|
+
"targets": [],
|
|
448
|
+
"releaseBranch": "",
|
|
449
|
+
"tag": true
|
|
366
450
|
},
|
|
367
451
|
|
|
368
452
|
// Reading a spec's diff (`spec-env review`, `/spec-diff`).
|
|
@@ -42,8 +42,8 @@
|
|
|
42
42
|
"fieldOwnership": {
|
|
43
43
|
"description": "push",
|
|
44
44
|
"subIssues": "push",
|
|
45
|
-
"workflowState": "
|
|
46
|
-
"assignee": "
|
|
45
|
+
"workflowState": "pull",
|
|
46
|
+
"assignee": "pull"
|
|
47
47
|
},
|
|
48
48
|
"localOnlySections": ["State log", "Changelog", "Open questions"],
|
|
49
49
|
"keyedFields": {}
|
|
@@ -7,8 +7,9 @@ a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
|
|
|
7
7
|
that sub-issue's description as a read-only checklist. Content is
|
|
8
8
|
pushed up and never read back or merged — `/spec-push` diffs the spec against a
|
|
9
9
|
committed **last-pushed snapshot** and applies only what changed; `/spec-status`
|
|
10
|
-
is a read-only report of what would push. The `sync.fieldOwnership` map
|
|
11
|
-
|
|
10
|
+
is a read-only report of what would push. The `sync.fieldOwnership` map says who
|
|
11
|
+
owns each field: the repo pushes the content (`description`, `subIssues`), and
|
|
12
|
+
Linear owns status and assignee (`workflowState`, `assignee` ship as `pull`).
|
|
12
13
|
|
|
13
14
|
**Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
|
|
14
15
|
is absent the feature is simply unused — `/spec`, `/spec-start`, and the CLI's
|
|
@@ -125,17 +126,19 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
125
126
|
// carries its own, and push knows what changed without reading Linear back.
|
|
126
127
|
"baseDir": "specs/.core/linear-base",
|
|
127
128
|
|
|
128
|
-
//
|
|
129
|
-
//
|
|
130
|
-
//
|
|
131
|
-
//
|
|
132
|
-
//
|
|
133
|
-
//
|
|
129
|
+
// Who owns each field. `push`: the repo, sent one way (repo → Linear) — the
|
|
130
|
+
// spec issue's `description` and its `subIssues` (one per phase — name +
|
|
131
|
+
// goal + state). `pull`: Linear — the `workflowState` is sent only as a
|
|
132
|
+
// transition the repo made (a bucket move), and the `assignee` is never
|
|
133
|
+
// projected; `spec-sync assign` writes it directly. `"push"` on either
|
|
134
|
+
// restores the repo-owned behaviour; `"none"` declines a field. Tasks,
|
|
135
|
+
// priority, labels, cycles and comments are NOT here, so a PM's triage is
|
|
136
|
+
// never touched.
|
|
134
137
|
"fieldOwnership": {
|
|
135
138
|
"description": "push",
|
|
136
139
|
"subIssues": "push",
|
|
137
|
-
"workflowState": "
|
|
138
|
-
"assignee": "
|
|
140
|
+
"workflowState": "pull",
|
|
141
|
+
"assignee": "pull"
|
|
139
142
|
},
|
|
140
143
|
|
|
141
144
|
// Markdown sections of 00-overview.md that are local-only scaffolding and
|
|
@@ -177,7 +180,17 @@ Sprint", "Released". A bucket's value may be an **array** instead of a string:
|
|
|
177
180
|
|
|
178
181
|
## Assignment (`sync.fieldOwnership.assignee`)
|
|
179
182
|
|
|
180
|
-
**
|
|
183
|
+
**Linear owns it by default (`pull`).** The board is where a team assigns work,
|
|
184
|
+
so the issue's assignee is the record and the spec keeps no copy: `/spec-start`
|
|
185
|
+
runs `spec-sync assign --if-unassigned`, which assigns you only when nobody holds
|
|
186
|
+
the issue and never reassigns anyone; `/spec-claim` writes Linear directly; and
|
|
187
|
+
finishing a spec leaves the assignee in place — the board keeps who did the work.
|
|
188
|
+
No `linear_assignee_id` stamp and no `> **Developer:**` line is written. Set
|
|
189
|
+
`"assignee": "push"` for the repo-owned behaviour described below.
|
|
190
|
+
|
|
191
|
+
### Under `push`
|
|
192
|
+
|
|
193
|
+
**On by default from v16 until `pull` replaced it.** The spec issue is assigned to whoever is building
|
|
181
194
|
it: `/spec-start` records them, and the issue is released when the spec
|
|
182
195
|
completes. To decline it, say so:
|
|
183
196
|
|
|
@@ -457,6 +470,24 @@ default for anyone who never sets one.
|
|
|
457
470
|
**section of the spec issue's own description**, with its full task list, and
|
|
458
471
|
the `## Phases` index stays as the table of contents. One issue per spec,
|
|
459
472
|
however many phases it has.
|
|
473
|
+
- `"none"` — no phase objects at all: the issue is one ticket. A phase that
|
|
474
|
+
already carries a `linear_issue_id` keeps its sub-issue (see below).
|
|
475
|
+
|
|
476
|
+
## What the issue body carries — `mapping.description`
|
|
477
|
+
|
|
478
|
+
- `"spec"` (the default, and what a config without the key gets) — the whole
|
|
479
|
+
overview, replacing the description on every push.
|
|
480
|
+
- `"summary"` — a delimited **block** (summary, acceptance criteria, surfaces
|
|
481
|
+
touched, gating, spec path) spliced into the description beside whatever the
|
|
482
|
+
team wrote there, which no push touches. Phase sub-issues get a block with
|
|
483
|
+
their goal. Drift is reported only for an edit *inside* the block.
|
|
484
|
+
|
|
485
|
+
`summary.delimiter` marks the block: `"heading"` (the default here — a
|
|
486
|
+
`## Skitterspec summary` heading and an end line) or `"comment"` (HTML
|
|
487
|
+
comments). Linear's default is **provisional** until
|
|
488
|
+
`chore-delimiter-spike-providers` measures which survives Linear's editor. A
|
|
489
|
+
delimiter someone edited is reported and the block left unwritten, never
|
|
490
|
+
guessed at.
|
|
460
491
|
|
|
461
492
|
### One mode, or one per bucket
|
|
462
493
|
|
|
@@ -679,11 +710,13 @@ most specific destination. Leave a list empty and nothing routes through it.
|
|
|
679
710
|
|
|
680
711
|
## One direction — nothing to reconcile
|
|
681
712
|
|
|
682
|
-
The repo owns the spec and pushes it;
|
|
683
|
-
current spec against the committed
|
|
684
|
-
changed — creates for unlinked items, updates for
|
|
685
|
-
teammate moves in Linear is **
|
|
686
|
-
|
|
713
|
+
The repo owns the spec's content and pushes it; nothing is merged back.
|
|
714
|
+
`/spec-push` diffs the current spec against the committed
|
|
715
|
+
**last-pushed snapshot** and sends only what changed — creates for unlinked items, updates for
|
|
716
|
+
changed ones. A workflow-state a teammate moves in Linear is **Linear's**: push
|
|
717
|
+
sends a state only when the spec itself changes bucket, and the one difference
|
|
718
|
+
reported is the issue being Done or Cancelled while the spec is still in flight
|
|
719
|
+
(`spec-sync board`, which names the cleanup and runs nothing). A
|
|
687
720
|
**description** someone edited there is reported by `/spec-status`, because
|
|
688
721
|
the next push replaces it. Priority, labels, cycles and comments are
|
|
689
722
|
Linear-native triage and are never touched. No base merge, no conflicts, no
|
|
@@ -117,6 +117,15 @@ function writeTarget(input) {
|
|
|
117
117
|
return null
|
|
118
118
|
}
|
|
119
119
|
|
|
120
|
+
// The engine's own refusal line, from `spec-env main check`. Pure.
|
|
121
|
+
//
|
|
122
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
123
|
+
// refusal is the last thing `check` writes, so a crash before it prints nothing
|
|
124
|
+
// — and one after it has already decided.
|
|
125
|
+
function isRefusal(stdout) {
|
|
126
|
+
return /^spec-env main: /m.test(stdout || '')
|
|
127
|
+
}
|
|
128
|
+
|
|
120
129
|
function main() {
|
|
121
130
|
const payload = readPayload()
|
|
122
131
|
if (!payload) allow()
|
|
@@ -145,7 +154,14 @@ function main() {
|
|
|
145
154
|
if (result.error || result.status === null) allow()
|
|
146
155
|
if (result.status !== 1) allow()
|
|
147
156
|
|
|
148
|
-
|
|
157
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
158
|
+
// engine that cannot even load looks exactly like one refusing — and read
|
|
159
|
+
// that way it denied every Edit and Write in the session. The positive signal
|
|
160
|
+
// is the refusal the engine PRINTS; a crash prints nothing on stdout.
|
|
161
|
+
const said = (result.stdout || '').trim()
|
|
162
|
+
if (!isRefusal(said)) allow()
|
|
163
|
+
|
|
164
|
+
deny(said)
|
|
149
165
|
}
|
|
150
166
|
|
|
151
167
|
// Guarded so the pieces above can be required and tested without the script
|
|
@@ -159,4 +175,4 @@ if (require.main === module) {
|
|
|
159
175
|
}
|
|
160
176
|
}
|
|
161
177
|
|
|
162
|
-
module.exports = { findEngine, WRITE_TOOLS, writeTarget }
|
|
178
|
+
module.exports = { findEngine, WRITE_TOOLS, writeTarget, isRefusal }
|
|
@@ -93,6 +93,15 @@ function findEngine(projectDir) {
|
|
|
93
93
|
return 'skitterspec'
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
+
// The engine's own refusal line, from `spec-env review gate --check`. Pure.
|
|
97
|
+
//
|
|
98
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
99
|
+
// refusal is written last, after every read has succeeded, so a crash before
|
|
100
|
+
// it prints nothing — and one after it has already decided.
|
|
101
|
+
function isRefusal(stdout) {
|
|
102
|
+
return /^spec-env review gate: /m.test(stdout || '')
|
|
103
|
+
}
|
|
104
|
+
|
|
96
105
|
function main() {
|
|
97
106
|
const payload = readPayload()
|
|
98
107
|
if (!payload) allow()
|
|
@@ -119,8 +128,16 @@ function main() {
|
|
|
119
128
|
if (result.error || result.status === null) allow()
|
|
120
129
|
if (result.status !== 1) allow()
|
|
121
130
|
|
|
131
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
132
|
+
// engine that cannot even load looks exactly like one saying "armed" — and
|
|
133
|
+
// once read that way it denied every Bash call in the session, the operator's
|
|
134
|
+
// own `!` commands included. The positive signal is the refusal the engine
|
|
135
|
+
// PRINTS; a crash prints nothing on stdout, so it allows.
|
|
136
|
+
const said = (result.stdout || '').trim()
|
|
137
|
+
if (!isRefusal(said)) allow()
|
|
138
|
+
|
|
122
139
|
deny(
|
|
123
|
-
|
|
140
|
+
said +
|
|
124
141
|
'\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
|
|
125
142
|
'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
|
|
126
143
|
'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
|
|
@@ -143,4 +160,4 @@ if (require.main === module) {
|
|
|
143
160
|
}
|
|
144
161
|
}
|
|
145
162
|
|
|
146
|
-
module.exports = { findEngine }
|
|
163
|
+
module.exports = { findEngine, isRefusal }
|
|
@@ -85,10 +85,33 @@ and it is cancelled along with it.
|
|
|
85
85
|
|
|
86
86
|
## Why it exists
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
In trunk mode the repo lands specs with `merge --ff-only`, so history is linear and branch
|
|
89
89
|
names never reach it. The commit message is the only artefact that survives into
|
|
90
90
|
the range a release scans, which is what lets
|
|
91
91
|
`spec-sync released <range>` report the tickets a release contains. A ref that
|
|
92
92
|
names the wrong ticket does not merely lose information — it moves a commit onto
|
|
93
93
|
another ticket's release report, which is worse than the gap it was meant to
|
|
94
94
|
close.
|
|
95
|
+
|
|
96
|
+
## Merge styles, and which range still holds the trailers
|
|
97
|
+
|
|
98
|
+
Trunk mode keeps this simple: `merge --ff-only` means linear history and every
|
|
99
|
+
trailer survives. PR mode (`land.strategy: "pr"`) hands the merge to the host,
|
|
100
|
+
and no merge style is required — teams pick their own — so the scan copes
|
|
101
|
+
per style instead:
|
|
102
|
+
|
|
103
|
+
- **Merge commits** — every branch commit survives, trailers intact. A
|
|
104
|
+
trailer-less merge commit counts as transport, never as an unreferenced gap —
|
|
105
|
+
while a merge that CARRIES a trailer still counts, because a hand merge is
|
|
106
|
+
where a ticket's only trailer sometimes lives.
|
|
107
|
+
- **Squashed feature PRs** — the branch's commits collapse into one. The
|
|
108
|
+
trailers survive when the squash message keeps the commit bodies (GitHub:
|
|
109
|
+
the "Default commit message" squash setting; Azure DevOps: keep the commit
|
|
110
|
+
descriptions in the squash message) — `released` counts every `Refs:` line
|
|
111
|
+
in the one body, so a squashed PR carrying three commits still reports three
|
|
112
|
+
tickets.
|
|
113
|
+
- **A squashed integration-to-release merge** — one commit for a whole cycle,
|
|
114
|
+
and attribution on the release branch is gone by construction. No setting
|
|
115
|
+
fixes that: point `released <range>` at the integration branch's range
|
|
116
|
+
instead, where the commits still exist. The range argument has always been
|
|
117
|
+
arbitrary, and this is what it is for.
|
|
@@ -7,7 +7,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
|
|
|
7
7
|
|
|
8
8
|
| Skill | Purpose | Status | Folder |
|
|
9
9
|
|-------|---------|--------|--------|
|
|
10
|
-
| `/spec` | (Feature/Chore/Issue) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch
|
|
10
|
+
| `/spec` | (Feature/Chore/Issue) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch by a fast-forward — or riding the feature branch under `land.specDocs: "branch"`) |
|
|
11
11
|
| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
|
|
12
12
|
| `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
|
|
13
13
|
| `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
|
|
@@ -157,6 +157,9 @@ build phase 1 now? Say yes and it carries on into a bare `/spec-next`; say no an
|
|
|
157
157
|
you are already standing in the worktree, so `/spec-next` typed later does the
|
|
158
158
|
same thing. The primary checkout stays on the base branch throughout — the
|
|
159
159
|
session followed the spec, nothing was checked out anywhere.
|
|
160
|
+
That is also why the base branch reads `backlog` for a spec being built: the
|
|
161
|
+
move happened on its branch. **`skitterspec status`** reads each worktree's own
|
|
162
|
+
copy and lists what is in flight and how far along it is.
|
|
160
163
|
**`checkout`** builds the branch in the primary checkout instead: one spec at a
|
|
161
164
|
time, nowhere else to stand, and the build always carries straight on.
|
|
162
165
|
The difference is how many specs can be in flight at once.
|
|
@@ -179,7 +182,7 @@ your canonical `localhost` ports so you can test it at the normal URL
|
|
|
179
182
|
move, header edits, the code) happens on the spec's branch in the worktree; `main`
|
|
180
183
|
changes only when it merges. Teardown is folded into `/spec-complete` ·
|
|
181
184
|
`/spec-cancel`. Beneath the skills, `skitterspec spec-env
|
|
182
|
-
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
|
|
185
|
+
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
|
|
183
186
|
engine. `up` plans the fork;
|
|
184
187
|
**`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
|
|
185
188
|
the command a skill runs names no file, and a secrets hook that refuses any
|
|
@@ -234,6 +237,16 @@ worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
|
|
|
234
237
|
`commit` tears it down, because a spec parked in the backlog should hold no
|
|
235
238
|
checkout.
|
|
236
239
|
|
|
240
|
+
**`land.specDocs: "branch"` is the exception, taken deliberately.** Where the
|
|
241
|
+
base branch accepts no direct push even for documents, the spec rides its
|
|
242
|
+
feature branch and lands with the work's PR: both verdicts commit and skip the
|
|
243
|
+
integrate, plain `commit` keeps branch and worktree (they are the document's
|
|
244
|
+
only copy), and the backlog is found through the tracker listing rather than
|
|
245
|
+
`ls specs/backlog/` on base — the known branch-relative-bucket cost, accepted
|
|
246
|
+
because the alternative is a spec that cannot be written at all. The worktree
|
|
247
|
+
fork-point check is exempt in this mode for the hotfix's reason: the spec is
|
|
248
|
+
*supposed* to be absent from the fork point.
|
|
249
|
+
|
|
237
250
|
**What this bought is the reason it changed.** The page waits for a verdict
|
|
238
251
|
without a timeout — deliberately, because a reader walking away from a diff is
|
|
239
252
|
the normal case — and while the spec was authored in the primary checkout that
|
|
@@ -497,15 +510,60 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
|
|
|
497
510
|
backed by a `spec-sync` CLI. There is no content pull — the tracker is never
|
|
498
511
|
read back or merged.
|
|
499
512
|
|
|
500
|
-
**
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
with
|
|
508
|
-
|
|
513
|
+
**What a ticket carries is the project's choice (`mapping.description`).**
|
|
514
|
+
Under `"spec"` the issue body is the whole overview and each phase sub-issue
|
|
515
|
+
its phase file, replaced on every push — what every config written before the
|
|
516
|
+
setting existed gets. Under `"summary"`, what a new config is written with, the
|
|
517
|
+
spec stays in git and the ticket gets what a ticket is for: a delimited
|
|
518
|
+
**block** holding the spec's `## Summary`, its `## Acceptance criteria`, the
|
|
519
|
+
Impact table's surfaces, its gating and its progress (`62% · phase 3 of 4`),
|
|
520
|
+
with each sub-issue's block holding its goal and task count. Push **splices**
|
|
521
|
+
the block into whatever the description holds, so a team's own text around it
|
|
522
|
+
survives every push, and only an edit *inside* the block is drift. That is a
|
|
523
|
+
splice, not a pull: nothing outside the block is parsed, merged or written
|
|
524
|
+
back. A delimiter edited by hand is cannot-tell — the push names it and writes
|
|
525
|
+
nothing there rather than guess. `mapping.phases: "none"` drops the phase
|
|
526
|
+
objects entirely; `subissue` stays the default because assignable phases are
|
|
527
|
+
what let them run in parallel.
|
|
528
|
+
|
|
529
|
+
**The tracker owns status; the repo owns the spec.** With a provider attached,
|
|
530
|
+
a team runs its work from the board — assignment, Ready, Blocked, Cancelled and
|
|
531
|
+
Done all happen there — so a status kept in the repo as well is a copy somebody
|
|
532
|
+
has to keep in step by hand, and on the base branch it was already wrong (an
|
|
533
|
+
in-flight spec still reads `backlog` there). The split follows what each side
|
|
534
|
+
can actually know:
|
|
535
|
+
|
|
536
|
+
1. **The repo owns the content** — Problem, Decisions, phases, checkboxes,
|
|
537
|
+
Changelog. Content follows branches, lands in the same commit as its code,
|
|
538
|
+
and is read offline by the agent building it. That is why specs did not move
|
|
539
|
+
into the tracker wholesale: a ticket has no branches.
|
|
540
|
+
2. **The tracker owns status and assignee** — `sync.fieldOwnership`
|
|
541
|
+
`workflowState` and `assignee` ship as **`pull`**. Under `pull` the skills
|
|
542
|
+
write no `Status:` header, no `Developer:` line and no State log row (the
|
|
543
|
+
`spec-status-owner` seam asks `spec-sync ownership` first), `assign` writes
|
|
544
|
+
the ticket directly, and the repo stores nothing it reads.
|
|
545
|
+
3. **Buckets are code facts**, not planning status: `backlog` (not started),
|
|
546
|
+
`in-progress` (`/spec-start` ran), `complete` (landed — merged on the host
|
|
547
|
+
under PR landing), `cancelled` (torn down). Only skills that act on code move
|
|
548
|
+
them.
|
|
549
|
+
4. **The repo writes status only when it acts on code** — creation, start,
|
|
550
|
+
complete, cancel — detected as a bucket move, never on a push that merely
|
|
551
|
+
cannot tell. Under PR landing the complete transition waits for run 2: a
|
|
552
|
+
ready PR is not a merged one.
|
|
553
|
+
5. **A board that finished first is reported, never obeyed.** `spec-sync board`
|
|
554
|
+
says one line when the ticket is Done or Cancelled while the spec is still in
|
|
555
|
+
flight, naming the cleanup; `/spec-start` and `/spec-next` warn and carry on,
|
|
556
|
+
`/spec-status` reports. Nobody is obliged to sync, because nothing reads the
|
|
557
|
+
bucket as planning truth any more.
|
|
558
|
+
|
|
559
|
+
`"push"` on either field restores the repo-owned behaviour; `"none"` leaves it
|
|
560
|
+
alone entirely. Without a provider none of this applies: the header, the State
|
|
561
|
+
log and the buckets keep their meaning, because there is nowhere else for status
|
|
562
|
+
to live. Releases and deployments are the host project's to record. The one
|
|
563
|
+
release question skitterspec answers is which tickets a commit range contains
|
|
564
|
+
(`spec-sync released <range> --json`, each row with its spec and url), because
|
|
565
|
+
only the `Refs:` trailers know. What the project's CI does with that list is its
|
|
566
|
+
own business.
|
|
509
567
|
|
|
510
568
|
**One-way means the repo wins, and it now wins *loudly*.** Those are different
|
|
511
569
|
claims and only the first was ever in doubt. A ticket's description is generated
|
|
@@ -538,13 +596,14 @@ disk at all. The tracker knows both, and each row carries the spec's folder name
|
|
|
538
596
|
so `/spec-start <name>` is a copy-paste away. See the provider's own docs for
|
|
539
597
|
what it calls the command.
|
|
540
598
|
|
|
541
|
-
A provider
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
599
|
+
A provider also knows **who is building a spec**, and under the default `pull`
|
|
600
|
+
the ticket's assignee is the record: `/spec-start` assigns the operator only when
|
|
601
|
+
nobody holds the ticket (`assign --if-unassigned`), never reassigns anyone, and
|
|
602
|
+
leaves the assignee in place when the spec finishes — the board keeps who did
|
|
603
|
+
the work. `/spec-claim` moves ownership mid-flight — take it, hand it back, or
|
|
604
|
+
hand it to a teammate — by writing the ticket directly. Under `push` the spec
|
|
605
|
+
file is the record and the ticket the mirror, as before. See the provider's own
|
|
606
|
+
docs for both.
|
|
548
607
|
|
|
549
608
|
**Every skill that moves a spec through the lifecycle carries a seam**, so the
|
|
550
609
|
mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
|
|
@@ -635,6 +694,56 @@ its phases. It carries `> **Severity:**` (Azure's literal values,
|
|
|
635
694
|
unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
|
|
636
695
|
onto the tracker item as a comment.
|
|
637
696
|
|
|
697
|
+
### Kind routing — any door, the right spec
|
|
698
|
+
|
|
699
|
+
`/spec` is the default door, so the kind of work someone describes does not
|
|
700
|
+
always match the skill they typed — especially for someone new, for whom
|
|
701
|
+
"spec it" is the reflex. Every entry skill therefore
|
|
702
|
+
**watches its grill for the signals that mark the other kinds**, and proposes a
|
|
703
|
+
hand-off the moment one appears — never at the end of a grill already shaping
|
|
704
|
+
the wrong spec:
|
|
705
|
+
|
|
706
|
+
| In | Watches for | Hands to |
|
|
707
|
+
|----|-------------|----------|
|
|
708
|
+
| `/spec` | defect · defect on a released version · live outage | `/spec-bug` · `/spec-hotfix` · `/spec-incident` |
|
|
709
|
+
| `/spec-bug` | on a released version · live outage · not a defect | `/spec-hotfix` · `/spec-incident` · `/spec` |
|
|
710
|
+
| `/spec-hotfix` | live outage · not on a released version · not a defect | `/spec-incident` · `/spec-bug` · `/spec` |
|
|
711
|
+
| `/spec-incident` | no live outage to record | defect → `/spec-bug` (on a released version → `/spec-hotfix`), else `/spec` |
|
|
712
|
+
|
|
713
|
+
Feature, chore and issue all route to `/spec` — one door for the three kinds it
|
|
714
|
+
writes, where its kind proposal picks between them. Example signals, weighed in
|
|
715
|
+
context rather than matched as keywords: a **defect** is behaviour differing
|
|
716
|
+
from intended — "it's broken", a failing flow, a stack trace of a failure;
|
|
717
|
+
**on a released version** is that defect where what is deployed is named — "in
|
|
718
|
+
prod", "since v2.1"; a **live outage** is a service down or degraded
|
|
719
|
+
**right now**, users affected as we speak; **not a defect** is an ask for new or
|
|
720
|
+
changed behaviour rather than for restoring intended behaviour.
|
|
721
|
+
|
|
722
|
+
Three rules, the same in every skill:
|
|
723
|
+
|
|
724
|
+
- **Always confirm; never silently switch.** Name the signal in the user's own
|
|
725
|
+
words and propose the destination with a one-line reason; the user confirms
|
|
726
|
+
or declines. A decline ends the matter — the grill carries on where it was,
|
|
727
|
+
and the same signal is not raised again. A signal is a question, never a
|
|
728
|
+
verdict: a pasted stack trace in "handle this error nicely" is a feature
|
|
729
|
+
request, not a bug report.
|
|
730
|
+
- **Precedence: incident > hotfix > bug.** One description can carry several
|
|
731
|
+
signals; propose the most specific destination — the same reasoning the
|
|
732
|
+
intake label routing documents for hotfix-over-bug.
|
|
733
|
+
- **Hand off in-session, carrying the context.** On a confirmed switch the
|
|
734
|
+
current skill invokes the destination skill directly and seeds it with
|
|
735
|
+
everything the grilling has already established — symptom, version, impact,
|
|
736
|
+
repro material, decisions so far — so the destination grills only what it
|
|
737
|
+
still needs ("seed, don't skip, the grill", the principle issue adoption
|
|
738
|
+
already uses). Stop-and-retype is the **label** routing's shape, and right
|
|
739
|
+
there because it fires before any grilling; mid-grill it would throw away
|
|
740
|
+
the answers already given.
|
|
741
|
+
|
|
742
|
+
This is judgment, not configuration: the signals are examples, there is no
|
|
743
|
+
list to maintain, and nothing here reads a label. A ticketing provider's
|
|
744
|
+
intake label routing (`intake.bugLabels` / `intake.hotfixLabels`) is a
|
|
745
|
+
separate, earlier check and is unchanged by this.
|
|
746
|
+
|
|
638
747
|
All six types share the same lifecycle folders below — type is orthogonal to
|
|
639
748
|
status.
|
|
640
749
|
|
|
@@ -663,6 +772,10 @@ Every spec header carries:
|
|
|
663
772
|
(one-way; the repo owns the link), and `/spec-complete` on the incident
|
|
664
773
|
counts the spec among its fixes. Absent on everything else.
|
|
665
774
|
|
|
775
|
+
**Under a provider's default `pull`, these three are the tracker's** —
|
|
776
|
+
`Status:`, `Developer:` and the State log — and new specs carry
|
|
777
|
+
`> **Tracker:** <url>` instead; see the ticketing section above. A spec that already has them keeps them as history.
|
|
778
|
+
|
|
666
779
|
Every spec also has a **State log** table — the audit trail of folder/status
|
|
667
780
|
transitions. Each lifecycle skill appends exactly one row when it changes state:
|
|
668
781
|
|
|
@@ -448,7 +448,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
448
448
|
| `Built` | What the run produced — the code, the edits, the spec written. |
|
|
449
449
|
| `Tests` | The result and the command that produced it. |
|
|
450
450
|
| `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
|
|
451
|
-
| `Landed` | A fast-forward, a tag, a cherry-pick. |
|
|
451
|
+
| `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). |
|
|
452
452
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
453
453
|
| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
|
|
454
454
|
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|