@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.
Files changed (71) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/SETUP.md +5 -0
  3. package/assets/core/env.config.json.example +1 -0
  4. package/assets/core/env.config.md +143 -8
  5. package/assets/core/linear.config.json.example +2 -2
  6. package/assets/core/linear.config.md +49 -16
  7. package/assets/hooks/main-guard.cjs +40 -6
  8. package/assets/hooks/review-gate.cjs +42 -7
  9. package/assets/rules/commit-trailers.md +24 -1
  10. package/assets/rules/spec-planning.md +81 -18
  11. package/assets/rules/spec-reports.md +1 -1
  12. package/assets/skills/spec/SKILL.md +55 -2
  13. package/assets/skills/spec-bug/SKILL.md +36 -3
  14. package/assets/skills/spec-cancel/SKILL.md +37 -0
  15. package/assets/skills/spec-claim/SKILL.md +41 -2
  16. package/assets/skills/spec-complete/SKILL.md +115 -0
  17. package/assets/skills/spec-hotfix/SKILL.md +51 -4
  18. package/assets/skills/spec-incident/SKILL.md +22 -0
  19. package/assets/skills/spec-linear-setup/SKILL.md +23 -1
  20. package/assets/skills/spec-next/SKILL.md +12 -5
  21. package/assets/skills/spec-push/SKILL.md +22 -0
  22. package/assets/skills/spec-review/SKILL.md +34 -0
  23. package/assets/skills/spec-start/SKILL.md +50 -3
  24. package/assets/skills/spec-status/SKILL.md +18 -3
  25. package/assets/skills/spec-sync/SKILL.md +1 -0
  26. package/assets/skills/spec-to-main/SKILL.md +47 -1
  27. package/package.json +1 -1
  28. package/src/cli.js +1188 -79
  29. package/src/env/base.js +104 -0
  30. package/src/env/bootstrap.js +22 -3
  31. package/src/env/classify.js +12 -4
  32. package/src/env/config.js +77 -5
  33. package/src/env/disposition.js +62 -0
  34. package/src/env/handoff.js +81 -0
  35. package/src/env/host.js +262 -0
  36. package/src/env/hotfix.js +237 -9
  37. package/src/env/hotfixland.js +105 -10
  38. package/src/env/inflight.js +98 -0
  39. package/src/env/integrate.js +136 -9
  40. package/src/env/live.js +8 -7
  41. package/src/env/mainguard.js +20 -5
  42. package/src/env/phases.js +28 -0
  43. package/src/env/project.js +223 -0
  44. package/src/env/provision.js +30 -8
  45. package/src/env/resolve.js +147 -25
  46. package/src/env/review.js +21 -7
  47. package/src/env/reviewers.js +7 -10
  48. package/src/env/serve.js +27 -11
  49. package/src/env/specstate.js +101 -0
  50. package/src/env/supervise.js +15 -2
  51. package/src/env/teardown.js +46 -3
  52. package/src/init.js +49 -9
  53. package/src/vendor/linear/cli-sanitise.js +8 -3
  54. package/src/vendor/linear/cli-sync.js +64 -10
  55. package/src/vendor/linear/config.js +27 -21
  56. package/src/vendor/linear/doctor.js +2 -0
  57. package/src/vendor/provider-kit/index.js +4 -0
  58. package/src/vendor/provider-kit/src/apply.js +58 -6
  59. package/src/vendor/provider-kit/src/assignment.js +78 -1
  60. package/src/vendor/provider-kit/src/config.js +34 -1
  61. package/src/vendor/provider-kit/src/credentials.js +7 -2
  62. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  63. package/src/vendor/provider-kit/src/released.js +48 -4
  64. package/src/vendor/provider-kit/src/specs.js +18 -7
  65. package/src/vendor/provider-kit/src/splice.js +64 -0
  66. package/src/vendor/provider-kit/src/status.js +137 -0
  67. package/src/vendor/sync-core/index.js +14 -1
  68. package/src/vendor/sync-core/src/compare.js +81 -6
  69. package/src/vendor/sync-core/src/normalize.js +50 -7
  70. package/src/vendor/sync-core/src/push.js +65 -5
  71. 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
@@ -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
@@ -36,6 +36,7 @@
36
36
  ]
37
37
  },
38
38
  "baseBranch": "",
39
+ "baseBranchPattern": "",
39
40
  "guards": {
40
41
  "refuseTeardownIfDirty": true,
41
42
  "refuseTeardownIfUnpushed": true
@@ -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, so {worktreePath} is usually
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 for you, so a remote copy exists only because you pushed it by hand —
301
- // and without this a completed spec leaves that merged branch on the remote
302
- // forever. `deleteRemoteBranch`:
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}` — primary checkout dir basename (e.g. `skitterspec`).
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": "push",
46
- "assignee": "push"
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 now just selects the
11
- projection field set (every field is repo-owned and pushed).
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
- // The pushed projection field set (repo → Linear, one-way). The `push` marker
129
- // is retained for shape; there is no pull. The default set is the spec
130
- // issue's `description`, its `subIssues` (one per phase — name + goal +
131
- // state), and the lifecycle `workflowState`. Tasks, priority, labels, cycles
132
- // and comments are NOT here, so a PM's triage is never touched. Any key you
133
- // add joins the pushed projection.
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": "push",
138
- "assignee": "push"
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
- **On by default since v16.** The spec issue is assigned to whoever is building
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; there is no pull. `/spec-push` diffs the
683
- current spec against the committed **last-pushed snapshot** and sends only what
684
- changed — creates for unlinked items, updates for changed ones. A workflow-state a
685
- teammate moves in Linear is **not skitterspec's business**: it is never read
686
- back or reported, and push resends State only when the spec itself moves. A
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
- function findEngine(projectDir) {
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 ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
89
- const candidate = path.join(at, 'node_modules', '.bin', name)
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 result = spawnSync(findEngine(cwd), argv, { cwd, encoding: 'utf8', timeout: 8000 })
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
- deny((result.stdout || '').trim())
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
- function findEngine(projectDir) {
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 ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
86
- const candidate = path.join(at, 'node_modules', '.bin', name)
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
- findEngine(cwd),
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
- (result.stdout || '').trim() +
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
- The repo lands specs with `merge --ff-only`, so history is linear and branch
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.