@skitterbyte/skitterspec-linear 19.3.0 → 19.5.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/SETUP.md +5 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +143 -8
- package/assets/core/linear.config.json.example +2 -2
- package/assets/core/linear.config.md +49 -16
- package/assets/hooks/main-guard.cjs +40 -6
- package/assets/hooks/review-gate.cjs +42 -7
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +36 -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 +51 -4
- package/assets/skills/spec-incident/SKILL.md +22 -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 +1188 -79
- package/src/env/base.js +104 -0
- package/src/env/bootstrap.js +22 -3
- package/src/env/classify.js +12 -4
- package/src/env/config.js +77 -5
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +81 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +237 -9
- package/src/env/hotfixland.js +105 -10
- package/src/env/inflight.js +98 -0
- package/src/env/integrate.js +136 -9
- package/src/env/live.js +8 -7
- package/src/env/mainguard.js +20 -5
- package/src/env/phases.js +28 -0
- package/src/env/project.js +223 -0
- package/src/env/provision.js +30 -8
- package/src/env/resolve.js +147 -25
- package/src/env/review.js +21 -7
- package/src/env/reviewers.js +7 -10
- package/src/env/serve.js +27 -11
- package/src/env/specstate.js +101 -0
- package/src/env/supervise.js +15 -2
- package/src/env/teardown.js +46 -3
- package/src/init.js +49 -9
- package/src/vendor/linear/cli-sanitise.js +8 -3
- package/src/vendor/linear/cli-sync.js +64 -10
- 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 +58 -6
- 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/credentials.js +7 -2
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +48 -4
- package/src/vendor/provider-kit/src/specs.js +18 -7
- 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 +81 -6
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +65 -5
- 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
|
package/assets/core/SETUP.md
CHANGED
|
@@ -43,6 +43,11 @@ contains the entire base, so install one **or** the other, never both):
|
|
|
43
43
|
npx @skitterbyte/skitterspec-linear init
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
+
**A project in a subfolder of its repo** (a solution folder beside `Sql/`,
|
|
47
|
+
say) installs and runs exactly the same way, from that folder: install the
|
|
48
|
+
package there or above it, and run `spec-sync` from it. `specs/.core/env.config.md`
|
|
49
|
+
→ *A project in a subfolder of its repo* has the details.
|
|
50
|
+
|
|
46
51
|
## 2. Connect the Linear MCP server
|
|
47
52
|
|
|
48
53
|
The sync skills talk to Linear over MCP. Add Linear's official remote server and
|
|
@@ -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
|
|
@@ -68,6 +68,8 @@ through to a documented conservative default; see the field notes below.
|
|
|
68
68
|
"worktree": {
|
|
69
69
|
"root": "../{repo}-wt", // dir that holds all spec worktrees; sibling of
|
|
70
70
|
// the primary checkout, never nested inside it.
|
|
71
|
+
// Resolved against the REPO root, even for a
|
|
72
|
+
// project in a subfolder of its repo (below).
|
|
71
73
|
"folderPattern": "{slug}" // per-spec worktree dir name.
|
|
72
74
|
},
|
|
73
75
|
|
|
@@ -141,7 +143,8 @@ through to a documented conservative default; see the field notes below.
|
|
|
141
143
|
// typechecks, builds and tests work immediately instead of failing on a
|
|
142
144
|
// missing node_modules. An array, run in order, stopping at the first that
|
|
143
145
|
// exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
|
|
144
|
-
// expand (the cwd is already the worktree
|
|
146
|
+
// expand (the cwd is already the worktree — the project folder inside it, for a
|
|
147
|
+
// project in a subfolder of its repo — so {worktreePath} is usually
|
|
145
148
|
// redundant). Example: ["pnpm install --frozen-lockfile"].
|
|
146
149
|
// An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
|
|
147
150
|
// IGNORED here — a fresh worktree always runs every setup step — and exists
|
|
@@ -284,9 +287,65 @@ through to a documented conservative default; see the field notes below.
|
|
|
284
287
|
// Integration base branch — the branch specs fork from and land back onto
|
|
285
288
|
// (used by the teardown "merged?" guard and, later, the integrate step).
|
|
286
289
|
// 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
|
|
290
|
+
// branch isn't discoverable (e.g. no remote) or differs (trunk, develop, a
|
|
291
|
+
// release-candidate branch). An explicit value always wins — it is the pin.
|
|
288
292
|
"baseBranch": "",
|
|
289
293
|
|
|
294
|
+
// A base that ROLLS: a glob over the remote's branch names (e.g. "20??/Q?")
|
|
295
|
+
// for teams that work off a release candidate versioned per release. The
|
|
296
|
+
// base is the NEWEST match by commit date, so cutting the next rc is all it
|
|
297
|
+
// takes to move every spec onto it — no config edit per release, no message
|
|
298
|
+
// to the team. Precedence: baseBranch (pin) → this pattern → origin/HEAD →
|
|
299
|
+
// main → master.
|
|
300
|
+
// - Matched against `refs/remotes/<land.remote>/*`, never the network:
|
|
301
|
+
// `spec-env up`, `integrate` and `spec-env base` fetch first; everything
|
|
302
|
+
// else reads what the last fetch saw.
|
|
303
|
+
// - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
|
|
304
|
+
// rc/a/b. Spell each segment ("20??/Q?").
|
|
305
|
+
// - No match REFUSES, naming `spec-env base` — it never falls back to
|
|
306
|
+
// origin/HEAD, because zero matches usually means "not fetched", and
|
|
307
|
+
// the default branch is exactly where a rolling base must not land.
|
|
308
|
+
// - Newest-by-date is only right when one rc is live at a time (the next
|
|
309
|
+
// is cut after the last merges). If your rcs overlap, pin `baseBranch`.
|
|
310
|
+
// - A spec that outlived a roll lands on the new rc; the integrate plan
|
|
311
|
+
// says `retarget: forked from <old> · landing onto <new>`, and switches
|
|
312
|
+
// a primary checkout still on the old rc before the fast-forward.
|
|
313
|
+
// A pattern holding whitespace or ".." is dropped (treated as unset).
|
|
314
|
+
// `spec-env base` lists the matches, the base, and specs on an older one.
|
|
315
|
+
"baseBranchPattern": "",
|
|
316
|
+
|
|
317
|
+
// How a finished branch reaches the base branch.
|
|
318
|
+
// strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
|
|
319
|
+
// exactly as always; nothing below applies.
|
|
320
|
+
// "pr" — the branch is pushed and a pull request carries it; the
|
|
321
|
+
// base branch moves only when the host merges. `spec-env
|
|
322
|
+
// integrate` then plans a rebase onto <remote>/<base> and a
|
|
323
|
+
// consent-gated push (`--push` consents; already-pushed-at-HEAD
|
|
324
|
+
// counts as consent; otherwise the plan holds), and a landed
|
|
325
|
+
// branch prints the finish — base catch-up plus the deferred
|
|
326
|
+
// `afterLand`. `--strategy ff|pr` on integrate overrides this per
|
|
327
|
+
// invocation; an unrecognised config value falls back to "ff".
|
|
328
|
+
// remote: where the branch is pushed. Default "origin".
|
|
329
|
+
// draft: mid-spec PRs open as drafts (a draft cannot be merged, so
|
|
330
|
+
// nothing downstream can close a ticket early); /spec-complete is
|
|
331
|
+
// what flips the PR to ready. Default true.
|
|
332
|
+
// specDocs: where a SPEC DOCUMENT lands under "pr". "trunk" (default) keeps
|
|
333
|
+
// today's authoring land — needs direct push for docs. "branch"
|
|
334
|
+
// has the spec ride the feature branch and land with the work's
|
|
335
|
+
// PR; the backlog is then found via the tracker listing, and the
|
|
336
|
+
// authoring worktree stays (it is the document's only copy).
|
|
337
|
+
// The merged-check and PR commands need the host's CLI — `gh` on github.com,
|
|
338
|
+
// `az` on dev.azure.com — detected from the remote URL, never configured. An
|
|
339
|
+
// unknown host (Enterprise/Server domains included) degrades to the ancestry
|
|
340
|
+
// test plus generic printed commands, and every failed lookup is a
|
|
341
|
+
// cannot-tell: teardown then HOLDS the worktree rather than guessing.
|
|
342
|
+
"land": {
|
|
343
|
+
"strategy": "ff",
|
|
344
|
+
"remote": "origin",
|
|
345
|
+
"draft": true,
|
|
346
|
+
"specDocs": "trunk"
|
|
347
|
+
},
|
|
348
|
+
|
|
290
349
|
// Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
|
|
291
350
|
// blocks when the commits are ALSO unmerged into the base branch — a branch
|
|
292
351
|
// already landed on base tears down (and its branch is deleted) without
|
|
@@ -297,9 +356,12 @@ through to a documented conservative default; see the field notes below.
|
|
|
297
356
|
},
|
|
298
357
|
|
|
299
358
|
// What teardown cleans up beyond this machine. Nothing publishes a spec
|
|
300
|
-
// branch
|
|
301
|
-
//
|
|
302
|
-
// forever.
|
|
359
|
+
// branch unasked — a remote copy exists because you pushed it by hand, or
|
|
360
|
+
// because a PR-mode land pushed it behind the consent gate — and without this
|
|
361
|
+
// a completed spec leaves that merged branch on the remote forever. (Hosts
|
|
362
|
+
// that auto-delete the branch on merge make the planned delete an
|
|
363
|
+
// already-gone no-op, reported as such, never as a failure.)
|
|
364
|
+
// `deleteRemoteBranch`:
|
|
303
365
|
// "prompt" (default) — plan `git push <remote> --delete <branch>` in its own
|
|
304
366
|
// "confirm with the user first" section; /spec-complete and
|
|
305
367
|
// /spec-cancel ask before running it.
|
|
@@ -358,11 +420,36 @@ through to a documented conservative default; see the field notes below.
|
|
|
358
420
|
// `hotfix land --push`; without it the land holds before the carry. The
|
|
359
421
|
// worktree stays until `spec-env hotfix finish`. Default: built-in patch tag,
|
|
360
422
|
// carry to main, no targets.
|
|
423
|
+
//
|
|
424
|
+
// `releaseBranch` makes hotfixes BRANCH-BASED, for a team whose release line
|
|
425
|
+
// is a branch rather than a tag. Worked example — an rc flow:
|
|
426
|
+
// master takes only rc merges and hotfixes; prod is whatever it holds
|
|
427
|
+
// 2026/Q4 the current release candidate (`baseBranchPattern: "20??/Q?"`)
|
|
428
|
+
// Test/Demo/Live env branches that take merges from master — OUT OF SCOPE:
|
|
429
|
+
// merging master into them stays your pipeline's job
|
|
430
|
+
// With `"releaseBranch": "master"`, `spec-env up hotfix-<name> --docs` fetches
|
|
431
|
+
// and forks from origin/master's head and prints the header to record —
|
|
432
|
+
// `> **Base version:** master@<sha>`. `hotfix land` then rebases onto
|
|
433
|
+
// origin/master and lands ON it by `land.strategy` (`--strategy` overrides):
|
|
434
|
+
// "ff" pushes the hotfix onto master; "pr" opens a READY pull request and
|
|
435
|
+
// holds until the host merges it. The fix is then carried to the resolved base
|
|
436
|
+
// (the newest rc) — directly under "ff", through a `carry/<slug>` branch and
|
|
437
|
+
// its own ready PR under "pr". `hotfix finish` tears down once both are
|
|
438
|
+
// confirmed. Empty (the default) = the tag flow above, unchanged; a hotfix
|
|
439
|
+
// keeps landing the way its own `Base version` says it was cut.
|
|
440
|
+
//
|
|
441
|
+
// `tag` (default true) keeps the release tag on a branch-based hotfix, bumped
|
|
442
|
+
// from the newest tag the release branch has; false is for a team whose deploy
|
|
443
|
+
// is driven by the env-branch merge rather than a tag. Under "pr",
|
|
444
|
+
// `releaseWith` refuses — a squash or rebase merge leaves its tag on a commit
|
|
445
|
+
// the release branch never has — so use the built-in tag there.
|
|
361
446
|
"hotfix": {
|
|
362
447
|
"releaseWith": "",
|
|
363
448
|
"bump": "patch",
|
|
364
449
|
"cherryPickMain": true,
|
|
365
|
-
"targets": []
|
|
450
|
+
"targets": [],
|
|
451
|
+
"releaseBranch": "",
|
|
452
|
+
"tag": true
|
|
366
453
|
},
|
|
367
454
|
|
|
368
455
|
// Reading a spec's diff (`spec-env review`, `/spec-diff`).
|
|
@@ -575,9 +662,57 @@ through to a documented conservative default; see the field notes below.
|
|
|
575
662
|
}
|
|
576
663
|
```
|
|
577
664
|
|
|
665
|
+
## A project in a subfolder of its repo
|
|
666
|
+
|
|
667
|
+
Most projects ARE their repo: `specs/` and `.claude/` sit at the git root. Some
|
|
668
|
+
cannot — a Visual Studio solution folder beside `Sql/` and a prototype or two,
|
|
669
|
+
where sessions start in the solution folder, so that is where `.claude/` must be
|
|
670
|
+
for its skills and hooks to load, and where `specs/` belongs. That works with no
|
|
671
|
+
configuration:
|
|
672
|
+
|
|
673
|
+
```
|
|
674
|
+
C:\Code\LSC App\ ← git root
|
|
675
|
+
├── FF.CSC.Solution\ ← the project: specs/, .claude/, run Claude here
|
|
676
|
+
├── Sql\
|
|
677
|
+
└── Prototype\
|
|
678
|
+
C:\Code\LSC App-wt\<spec>\ ← each spec's worktree, beside the repo
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
- **The project is found, not configured.** Every `spec-env` verb walks up from
|
|
682
|
+
where it is run to the nearest folder holding `specs/.core/`, stopping at the
|
|
683
|
+
git root. Found at the root, it behaves exactly as it always has; found in a
|
|
684
|
+
subfolder, that subfolder is the project — from inside it or anywhere beneath
|
|
685
|
+
it. `spec-env resolve` and `skitterspec status` print a
|
|
686
|
+
`subfolder: FF.CSC.Solution/ (in repo C:\Code\LSC App)` line when it is not
|
|
687
|
+
the root, and nothing extra when it is. Several projects in one repo are not
|
|
688
|
+
supported: the nearest `specs/.core/` wins.
|
|
689
|
+
- **Repo-level things resolve against the repo root**: `worktree.root`, `{repo}`
|
|
690
|
+
(`LSC App`, not the project folder's name) and therefore the worktree layout.
|
|
691
|
+
A spec's worktree is a checkout of the whole repo, with the project at the same
|
|
692
|
+
place inside it.
|
|
693
|
+
- **Everything in this file is project-relative**: `setup`, `dev`, seed files,
|
|
694
|
+
`docker.composeFile` and `docker.envFile`, `registry`, `spec.companionPaths`,
|
|
695
|
+
and the folder `/spec-start` moves the session into
|
|
696
|
+
(`<worktree>/FF.CSC.Solution`). Git commands run against the worktree.
|
|
697
|
+
- **The review page lists git paths**, so the project's files carry its folder
|
|
698
|
+
(`FF.CSC.Solution/specs/…`) and a change beside it (`Sql/…`) is shown as code.
|
|
699
|
+
- **The main guard covers the whole primary checkout**, not only the project
|
|
700
|
+
folder: a write to `Sql/` on the base branch is unreviewed work too.
|
|
701
|
+
- **Install skitterspec in the project folder or above it.** The hooks find the
|
|
702
|
+
engine by walking UP from the session's folder to a `node_modules/.bin`; an
|
|
703
|
+
install below the project (say an Angular `ClientApp/node_modules`) is not
|
|
704
|
+
found, and the hooks fall back to `skitterspec` on your PATH.
|
|
705
|
+
- **Run `spec-sync` from the project folder.** The tracker providers take the
|
|
706
|
+
project from where they are run (or `--dir`); `release.ignorePaths` are read
|
|
707
|
+
against the project, so `specs/` means the project's.
|
|
708
|
+
- **Windows**: git prints `/` and paths with spaces are quoted in every command
|
|
709
|
+
the engine prints. A deep spec folder inside a worktree can pass 260
|
|
710
|
+
characters — set `git config --global core.longpaths true` once.
|
|
711
|
+
|
|
578
712
|
## Token expansion
|
|
579
713
|
|
|
580
|
-
- `{repo}` —
|
|
714
|
+
- `{repo}` — the repo root's dir basename (e.g. `skitterspec`) — the primary
|
|
715
|
+
checkout's root, which for a project in a subfolder is the folder above it.
|
|
581
716
|
- `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
|
|
582
717
|
(safe for a `COMPOSE_PROJECT_NAME`).
|
|
583
718
|
- `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
|
|
@@ -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
|
|
@@ -81,12 +81,22 @@ function readPayload() {
|
|
|
81
81
|
* the local install is looked for by path first — walking up from the project,
|
|
82
82
|
* because a git worktree's checkout has its own `node_modules`.
|
|
83
83
|
*/
|
|
84
|
-
|
|
84
|
+
const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
85
|
+
|
|
86
|
+
function findEngine(projectDir, platform = process.platform) {
|
|
85
87
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
86
88
|
let at = projectDir
|
|
87
89
|
for (let i = 0; i < 6 && at; i++) {
|
|
88
|
-
for (const name of
|
|
89
|
-
|
|
90
|
+
for (const name of ENGINES) {
|
|
91
|
+
// ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
|
|
92
|
+
// shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
|
|
93
|
+
// `.cmd` beside it needs a shell — which a hook handing a tool's command
|
|
94
|
+
// line over as an argument must never use. Unreachable, the hook failed
|
|
95
|
+
// open, and every guard was silently off on Windows (chore-windows-ci).
|
|
96
|
+
const candidate =
|
|
97
|
+
platform === 'win32'
|
|
98
|
+
? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
|
|
99
|
+
: path.join(at, 'node_modules', '.bin', name)
|
|
90
100
|
if (fs.existsSync(candidate)) return candidate
|
|
91
101
|
}
|
|
92
102
|
const up = path.dirname(at)
|
|
@@ -96,6 +106,13 @@ function findEngine(projectDir) {
|
|
|
96
106
|
return 'skitterspec'
|
|
97
107
|
}
|
|
98
108
|
|
|
109
|
+
// How to run what `findEngine` found: a `.js` engine through this node, since
|
|
110
|
+
// Windows cannot execute one directly — anything else as itself, as before.
|
|
111
|
+
function engineCommand(projectDir, platform = process.platform) {
|
|
112
|
+
const engine = findEngine(projectDir, platform)
|
|
113
|
+
return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
|
|
114
|
+
}
|
|
115
|
+
|
|
99
116
|
// The tools that write a file. A matcher is configured too, but a hook that is
|
|
100
117
|
// reached some other way must still be inert rather than guessing.
|
|
101
118
|
//
|
|
@@ -117,6 +134,15 @@ function writeTarget(input) {
|
|
|
117
134
|
return null
|
|
118
135
|
}
|
|
119
136
|
|
|
137
|
+
// The engine's own refusal line, from `spec-env main check`. Pure.
|
|
138
|
+
//
|
|
139
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
140
|
+
// refusal is the last thing `check` writes, so a crash before it prints nothing
|
|
141
|
+
// — and one after it has already decided.
|
|
142
|
+
function isRefusal(stdout) {
|
|
143
|
+
return /^spec-env main: /m.test(stdout || '')
|
|
144
|
+
}
|
|
145
|
+
|
|
120
146
|
function main() {
|
|
121
147
|
const payload = readPayload()
|
|
122
148
|
if (!payload) allow()
|
|
@@ -138,14 +164,22 @@ function main() {
|
|
|
138
164
|
const target = writeTarget(payload.tool_input)
|
|
139
165
|
if (target) argv.push('--path', target)
|
|
140
166
|
|
|
141
|
-
const
|
|
167
|
+
const engine = engineCommand(cwd)
|
|
168
|
+
const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd, encoding: 'utf8', timeout: 8000 })
|
|
142
169
|
|
|
143
170
|
// No engine, a crash, a timeout — all cannot-tell. `status` is null when the
|
|
144
171
|
// process never ran or was killed, and neither is a refusal.
|
|
145
172
|
if (result.error || result.status === null) allow()
|
|
146
173
|
if (result.status !== 1) allow()
|
|
147
174
|
|
|
148
|
-
|
|
175
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
176
|
+
// engine that cannot even load looks exactly like one refusing — and read
|
|
177
|
+
// that way it denied every Edit and Write in the session. The positive signal
|
|
178
|
+
// is the refusal the engine PRINTS; a crash prints nothing on stdout.
|
|
179
|
+
const said = (result.stdout || '').trim()
|
|
180
|
+
if (!isRefusal(said)) allow()
|
|
181
|
+
|
|
182
|
+
deny(said)
|
|
149
183
|
}
|
|
150
184
|
|
|
151
185
|
// Guarded so the pieces above can be required and tested without the script
|
|
@@ -159,4 +193,4 @@ if (require.main === module) {
|
|
|
159
193
|
}
|
|
160
194
|
}
|
|
161
195
|
|
|
162
|
-
module.exports = { findEngine, WRITE_TOOLS, writeTarget }
|
|
196
|
+
module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
|
|
@@ -78,12 +78,22 @@ function readPayload() {
|
|
|
78
78
|
* is the fallback for a global install, and `SKITTERSPEC_BIN` overrides
|
|
79
79
|
* everything for anyone whose layout is neither.
|
|
80
80
|
*/
|
|
81
|
-
|
|
81
|
+
const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
82
|
+
|
|
83
|
+
function findEngine(projectDir, platform = process.platform) {
|
|
82
84
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
83
85
|
let at = projectDir
|
|
84
86
|
for (let i = 0; i < 6 && at; i++) {
|
|
85
|
-
for (const name of
|
|
86
|
-
|
|
87
|
+
for (const name of ENGINES) {
|
|
88
|
+
// ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
|
|
89
|
+
// shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
|
|
90
|
+
// `.cmd` beside it needs a shell — which a hook handing a tool's command
|
|
91
|
+
// line over as an argument must never use. Unreachable, the hook failed
|
|
92
|
+
// open, and every guard was silently off on Windows (chore-windows-ci).
|
|
93
|
+
const candidate =
|
|
94
|
+
platform === 'win32'
|
|
95
|
+
? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
|
|
96
|
+
: path.join(at, 'node_modules', '.bin', name)
|
|
87
97
|
if (fs.existsSync(candidate)) return candidate
|
|
88
98
|
}
|
|
89
99
|
const up = path.dirname(at)
|
|
@@ -93,6 +103,22 @@ function findEngine(projectDir) {
|
|
|
93
103
|
return 'skitterspec'
|
|
94
104
|
}
|
|
95
105
|
|
|
106
|
+
// How to run what `findEngine` found: a `.js` engine through this node, since
|
|
107
|
+
// Windows cannot execute one directly — anything else as itself, as before.
|
|
108
|
+
function engineCommand(projectDir, platform = process.platform) {
|
|
109
|
+
const engine = findEngine(projectDir, platform)
|
|
110
|
+
return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// The engine's own refusal line, from `spec-env review gate --check`. Pure.
|
|
114
|
+
//
|
|
115
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
116
|
+
// refusal is written last, after every read has succeeded, so a crash before
|
|
117
|
+
// it prints nothing — and one after it has already decided.
|
|
118
|
+
function isRefusal(stdout) {
|
|
119
|
+
return /^spec-env review gate: /m.test(stdout || '')
|
|
120
|
+
}
|
|
121
|
+
|
|
96
122
|
function main() {
|
|
97
123
|
const payload = readPayload()
|
|
98
124
|
if (!payload) allow()
|
|
@@ -108,9 +134,10 @@ function main() {
|
|
|
108
134
|
// its own checkout, and the answer differs per worktree.
|
|
109
135
|
const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
|
|
110
136
|
|
|
137
|
+
const engine = engineCommand(cwd)
|
|
111
138
|
const result = spawnSync(
|
|
112
|
-
|
|
113
|
-
['spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
|
|
139
|
+
engine.file,
|
|
140
|
+
[...engine.args, 'spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
|
|
114
141
|
{ cwd, encoding: 'utf8', timeout: 8000 },
|
|
115
142
|
)
|
|
116
143
|
|
|
@@ -119,8 +146,16 @@ function main() {
|
|
|
119
146
|
if (result.error || result.status === null) allow()
|
|
120
147
|
if (result.status !== 1) allow()
|
|
121
148
|
|
|
149
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
150
|
+
// engine that cannot even load looks exactly like one saying "armed" — and
|
|
151
|
+
// once read that way it denied every Bash call in the session, the operator's
|
|
152
|
+
// own `!` commands included. The positive signal is the refusal the engine
|
|
153
|
+
// PRINTS; a crash prints nothing on stdout, so it allows.
|
|
154
|
+
const said = (result.stdout || '').trim()
|
|
155
|
+
if (!isRefusal(said)) allow()
|
|
156
|
+
|
|
122
157
|
deny(
|
|
123
|
-
|
|
158
|
+
said +
|
|
124
159
|
'\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
|
|
125
160
|
'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
|
|
126
161
|
'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
|
|
@@ -143,4 +178,4 @@ if (require.main === module) {
|
|
|
143
178
|
}
|
|
144
179
|
}
|
|
145
180
|
|
|
146
|
-
module.exports = { findEngine }
|
|
181
|
+
module.exports = { findEngine, engineCommand, 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.
|