@skitterbyte/skitterspec-jira 2.3.0 → 2.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 (67) 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/jira.config.md +4 -2
  6. package/assets/hooks/main-guard.cjs +40 -6
  7. package/assets/hooks/review-gate.cjs +42 -7
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +81 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +55 -2
  12. package/assets/skills/spec-bug/SKILL.md +25 -1
  13. package/assets/skills/spec-cancel/SKILL.md +35 -0
  14. package/assets/skills/spec-complete/SKILL.md +113 -0
  15. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  16. package/assets/skills/spec-incident/SKILL.md +22 -0
  17. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  18. package/assets/skills/spec-next/SKILL.md +9 -4
  19. package/assets/skills/spec-push/SKILL.md +22 -0
  20. package/assets/skills/spec-review/SKILL.md +32 -0
  21. package/assets/skills/spec-start/SKILL.md +39 -1
  22. package/assets/skills/spec-status/SKILL.md +18 -3
  23. package/assets/skills/spec-sync/SKILL.md +1 -0
  24. package/assets/skills/spec-to-main/SKILL.md +47 -1
  25. package/package.json +1 -1
  26. package/src/cli.js +1188 -79
  27. package/src/env/base.js +104 -0
  28. package/src/env/bootstrap.js +22 -3
  29. package/src/env/classify.js +12 -4
  30. package/src/env/config.js +77 -5
  31. package/src/env/disposition.js +62 -0
  32. package/src/env/handoff.js +81 -0
  33. package/src/env/host.js +262 -0
  34. package/src/env/hotfix.js +237 -9
  35. package/src/env/hotfixland.js +105 -10
  36. package/src/env/inflight.js +98 -0
  37. package/src/env/integrate.js +136 -9
  38. package/src/env/live.js +8 -7
  39. package/src/env/mainguard.js +20 -5
  40. package/src/env/phases.js +28 -0
  41. package/src/env/project.js +223 -0
  42. package/src/env/provision.js +30 -8
  43. package/src/env/resolve.js +147 -25
  44. package/src/env/review.js +21 -7
  45. package/src/env/reviewers.js +7 -10
  46. package/src/env/serve.js +27 -11
  47. package/src/env/specstate.js +101 -0
  48. package/src/env/supervise.js +15 -2
  49. package/src/env/teardown.js +46 -3
  50. package/src/init.js +49 -9
  51. package/src/vendor/jira/cli-sync.js +48 -4
  52. package/src/vendor/jira/config.js +17 -5
  53. package/src/vendor/provider-kit/index.js +4 -0
  54. package/src/vendor/provider-kit/src/apply.js +58 -6
  55. package/src/vendor/provider-kit/src/assignment.js +78 -1
  56. package/src/vendor/provider-kit/src/config.js +34 -1
  57. package/src/vendor/provider-kit/src/credentials.js +7 -2
  58. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  59. package/src/vendor/provider-kit/src/released.js +48 -4
  60. package/src/vendor/provider-kit/src/specs.js +18 -7
  61. package/src/vendor/provider-kit/src/splice.js +64 -0
  62. package/src/vendor/provider-kit/src/status.js +137 -0
  63. package/src/vendor/sync-core/index.js +14 -1
  64. package/src/vendor/sync-core/src/compare.js +81 -6
  65. package/src/vendor/sync-core/src/normalize.js +50 -7
  66. package/src/vendor/sync-core/src/push.js +65 -5
  67. 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
@@ -35,6 +35,11 @@ exactly one):
35
35
  npx @skitterbyte/skitterspec-jira init
36
36
  ```
37
37
 
38
+ **A project in a subfolder of its repo** (a solution folder beside `Sql/`,
39
+ say) installs and runs exactly the same way, from that folder: install the
40
+ package there or above it, and run `spec-sync` from it. `specs/.core/env.config.md`
41
+ → *A project in a subfolder of its repo* has the details.
42
+
38
43
  ## 2. Credentials — an email + API-token pair
39
44
 
40
45
  Jira Cloud authenticates REST calls with basic auth: your Atlassian account
@@ -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).
@@ -11,14 +11,16 @@ NAMES — never a credential. Credentials live in the user-level store
11
11
  | `jira.issueType` | The issue type a spec mints as. | `"Task"` |
12
12
  | `jira.issueTypeByKind` | The mint type per spec kind (`feature`/`bug`/`hotfix`/`chore`, from the folder prefix), falling back to `jira.issueType` — `{ "bug": "Bug" }` files bug specs as Jira Bugs. The type must exist in the project before mapping it. | `{}` |
13
13
  | `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
14
- | `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
14
+ | `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline` \| `none`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
15
+ | `mapping.description` | What a ticket body carries. `"summary"`: a delimited block (summary, acceptance criteria, surfaces touched, gating, spec path) spliced in beside the team's own text, which no push touches; phase sub-issues get a block with their goal. `"spec"`: the whole overview, replacing the body (the behaviour before this key). A config without the key is `spec`, so an upgrade rewrites no ticket. | `spec` |
16
+ | `summary.delimiter` | How the block is marked: `"comment"` (HTML comments, hidden on the rendered ticket) or `"heading"` (a `## Skitterspec summary` heading and an end line). Provisional for this tracker until `chore-delimiter-spike-providers` measures which survives its editor. A delimiter someone edited is reported and the block is left unwritten, never guessed at. | `heading` |
15
17
  | `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
16
18
  | `statesByType.<issue type>.<bucket>` | Per-TYPE override laid over `states` — statuses belong to the type's workflow, so `{ "Service Request": { "complete": "Closed" } }` completes that type differently. A bucket set to `null` sends no status; validation checks each type against its own workflow. | `{}` |
17
19
  | `jira.severityField` | The field id the `Severity:` header is written to (e.g. `customfield_10900`). Empty, the header stays repo-only. A fix spec's `Incident:` header adds a `Relates` issue link to its incident, once. | `""` |
18
20
  | `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
19
21
  | `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
20
22
  | `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
21
- | `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
23
+ | `sync.fieldOwnership` | Who owns each field. The repo pushes `description` and `subIssues`; Jira owns `workflowState` and `assignee` (`pull`: the state is sent only on a bucket move, the assignee never projected). `"push"` restores the repo-owned behaviour; `"none"` declines a field. | content `push`, status and assignee `pull` |
22
24
  | `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
23
25
 
24
26
  Descriptions are stored as ADF (Atlassian Document Format): the adapter
@@ -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 }
@@ -87,10 +87,33 @@ and it is cancelled along with it.
87
87
 
88
88
  ## Why it exists
89
89
 
90
- The repo lands specs with `merge --ff-only`, so history is linear and branch
90
+ In trunk mode the repo lands specs with `merge --ff-only`, so history is linear and branch
91
91
  names never reach it. The commit message is the only artefact that survives into
92
92
  the range a release scans, which is what lets
93
93
  `spec-sync released <range>` report the tickets a release contains. A ref that
94
94
  names the wrong ticket does not merely lose information — it moves a commit onto
95
95
  another ticket's release report, which is worse than the gap it was meant to
96
96
  close.
97
+
98
+ ## Merge styles, and which range still holds the trailers
99
+
100
+ Trunk mode keeps this simple: `merge --ff-only` means linear history and every
101
+ trailer survives. PR mode (`land.strategy: "pr"`) hands the merge to the host,
102
+ and no merge style is required — teams pick their own — so the scan copes
103
+ per style instead:
104
+
105
+ - **Merge commits** — every branch commit survives, trailers intact. A
106
+ trailer-less merge commit counts as transport, never as an unreferenced gap —
107
+ while a merge that CARRIES a trailer still counts, because a hand merge is
108
+ where a ticket's only trailer sometimes lives.
109
+ - **Squashed feature PRs** — the branch's commits collapse into one. The
110
+ trailers survive when the squash message keeps the commit bodies (GitHub:
111
+ the "Default commit message" squash setting; Azure DevOps: keep the commit
112
+ descriptions in the squash message) — `released` counts every `Refs:` line
113
+ in the one body, so a squashed PR carrying three commits still reports three
114
+ tickets.
115
+ - **A squashed integration-to-release merge** — one commit for a whole cycle,
116
+ and attribution on the release branch is gone by construction. No setting
117
+ fixes that: point `released <range>` at the integration branch's range
118
+ instead, where the commits still exist. The range argument has always been
119
+ arbitrary, and this is what it is for.