@skitterbyte/skitterspec-linear 19.15.0 → 19.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/MIGRATION.md +27 -0
  2. package/README.md +2 -1
  3. package/assets/claude-md-section.md +18 -9
  4. package/assets/commands/allow-main.md +1 -2
  5. package/assets/core/env.config.json.example +0 -1
  6. package/assets/core/env.config.md +28 -26
  7. package/assets/hooks/main-guard.cjs +73 -6
  8. package/assets/hooks/project-guard.cjs +80 -6
  9. package/assets/hooks/review-gate.cjs +73 -6
  10. package/assets/review/page.html +10 -83
  11. package/assets/rules/commit-trailers.md +2 -2
  12. package/assets/rules/spec-planning.md +26 -22
  13. package/assets/rules/spec-reports.md +52 -52
  14. package/assets/skills/no-spec/SKILL.md +2 -2
  15. package/assets/skills/spec/SKILL.md +22 -5
  16. package/assets/skills/spec-bug/SKILL.md +18 -15
  17. package/assets/skills/spec-complete/SKILL.md +23 -1
  18. package/assets/skills/spec-diff/SKILL.md +47 -115
  19. package/assets/skills/spec-hotfix/SKILL.md +18 -15
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +66 -41
  22. package/assets/skills/spec-park/SKILL.md +92 -0
  23. package/assets/skills/spec-resume/SKILL.md +153 -0
  24. package/assets/skills/spec-review/SKILL.md +2 -2
  25. package/assets/skills/spec-reviewed/SKILL.md +1 -8
  26. package/assets/skills/spec-status/SKILL.md +1 -1
  27. package/assets/skills/spec-sync/SKILL.md +12 -12
  28. package/assets/skills/spec-todo/SKILL.md +5 -2
  29. package/package.json +1 -1
  30. package/src/cli.js +361 -208
  31. package/src/env/bootstrap.js +3 -1
  32. package/src/env/checks.js +49 -0
  33. package/src/env/config.js +27 -7
  34. package/src/env/hooks.js +53 -4
  35. package/src/env/live.js +48 -0
  36. package/src/env/provision.js +10 -2
  37. package/src/env/resume.js +234 -0
  38. package/src/env/review.js +71 -173
  39. package/src/env/serve.js +3 -7
  40. package/src/init.js +383 -50
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/linear/cli-sync.js +3 -3
  43. package/src/vendor/provider-kit/src/specs.js +46 -1
  44. package/src/vendor/sync-core/src/summary.js +10 -1
  45. package/assets/commands/spec-remote-review.md +0 -37
package/MIGRATION.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # Migration guide
2
2
 
3
+ ## The tailnet is `remote`; publishing the review is retired (nothing to edit)
4
+
5
+ The review stack's `remote:` line used to be a claude.ai page the review was
6
+ published to. That tier is gone. `remote:` is now the review server's
7
+ **tailnet address**, on its own line, labelled `(tailnet)`. It is the same
8
+ server as `local` and `network`, so one wait covers all three, and a verdict
9
+ pressed there wakes the waiting session like any other.
10
+
11
+ ```
12
+ local: http://127.0.0.1:7760/7e9e…/feat-orders
13
+ network: http://192.168.0.136:7760/7e9e…/feat-orders
14
+ remote: http://100.126.111.34:7760/7e9e…/feat-orders (tailnet)
15
+ ```
16
+
17
+ - **`/spec-remote-review` is removed.** `skitterspec update` retires the command
18
+ file. A copy you edited is kept, with the usual warning, and you can delete
19
+ it.
20
+ - **`review.allowRemote` is ignored.** A config that still sets it loads
21
+ without a warning, and you can delete the key whenever you like.
22
+ `spec-env review allow remote` now refuses and names the tailnet line.
23
+ - **`remote` follows `review.allowNetwork`.** It is off whenever `network` is,
24
+ with the same command to turn it on. On a machine with no tailnet address it
25
+ reads `— (no tailnet address on this machine)`.
26
+ - **`--publish-copy` is gone**, along with the page's published mode and its
27
+ `Allow remote` button. A page published before this change still exists, and
28
+ `spec-env down` still names it at teardown.
29
+
3
30
  ## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
4
31
 
5
32
  Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
package/README.md CHANGED
@@ -85,6 +85,8 @@ them. Your `specs/` content and live `.core` config are never touched.
85
85
  | `/spec-diff` | Read what a phase changed, on a page you can mark up |
86
86
  | `/spec-reviewed` | Pick up a verdict pressed when nothing was waiting for it |
87
87
  | `/spec-epic-next` | Name the epic member that can start now, to start in a new tab |
88
+ | `/spec-resume` | Go back into a spec in flight, by name or ticket, and act on a message |
89
+ | `/spec-park` | Record what a spec in flight is waiting on: a deploy, a release, a soak |
88
90
  | `/spec-to-main` | Land the branch mid-spec, without finishing it |
89
91
  | `/spec-complete` | Verify, land, tear down |
90
92
  | `/spec-cancel` | Record why, stamp the header, tear down |
@@ -94,7 +96,6 @@ them. Your `specs/` content and live `.core` config are never touched.
94
96
  | `/spec-init` | Bootstrap or repair the workflow in a project |
95
97
  | `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
96
98
  | `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
97
- | `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
98
99
  | `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
99
100
  | `/allow-project` | Let this session work on another skitterspec project — yours to run, never Claude's |
100
101
  | `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
@@ -12,8 +12,8 @@ skill that wants one will tell you to type it.
12
12
 
13
13
  **Seeing the work.** A phase is built in its own worktree, so `git diff` in your
14
14
  terminal answers about the base branch. **`/spec-diff`** renders that worktree's
15
- diff as a self-contained HTML page you open locally — or publish, and read on a
16
- phone. The diff never passes through the model, so the page costs no context
15
+ diff as a self-contained HTML page you open locally — or on a phone, over your
16
+ LAN or tailnet. 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
19
  every phase. **`skitterspec status`** lists what is in flight across worktrees.
@@ -30,6 +30,18 @@ neither acts on one: a session works on the project it was started in, and a
30
30
  hook refuses its writes and lifecycle commands anywhere else until you type
31
31
  `/allow-project <name>`.
32
32
 
33
+ **Coming back to a spec** that waited on a deploy, another project or a soak
34
+ is **`/spec-resume <name|#N> [message]`**. It finds the spec even if it exists
35
+ only on its branch, rebuilds its worktree if this machine has none, moves the
36
+ session there and shows what it was blocked on. Then it acts on the message:
37
+ feedback on the shipped work becomes tasks, "the deploy is out" clears the
38
+ blocker, and a question gets an answer from the spec. It never starts
39
+ anything. `/spec #N` on a ticket that already has a spec offers it instead.
40
+ **`/spec-park "<reason>"`** records the wait in the first place, as a
41
+ `Blocked on:` line. `/spec` writes the planned ones ("phase 4 waits until
42
+ phase 3 has run in prod a week"), and `/spec-next` stops before building
43
+ past either kind.
44
+
33
45
  **Handing the review back.** The page takes marks: tick `✓ accept` per file as
34
46
  you read, note anything against a line or a whole file, answer the questions a
35
47
  written review asked — then **end it in a decision**. At the end of a phase the
@@ -86,13 +98,10 @@ running and concluded nothing, so the phase still owes an answer.
86
98
 
87
99
  **Every render lists where the page can be read**, labelled, in a fixed order —
88
100
  `local`, `network`, `remote` — each either a URL or the one command that turns it
89
- on, plus a `live:` line saying whether the change is also running. `local` and
90
- `network` are two doors into one room: the same server and the same waiting
91
- verdict, so one wait covers both. `remote` is a published page, a second store —
92
- a verdict there needs `/spec-reviewed`, and it stays off until someone types
93
- **`/spec-remote-review`**, which toggles it. Publishing is permitted by that
94
- command, never performed by it: a published page is one this tooling cannot
95
- remove.
101
+ on, plus a `live:` line saying whether the change is also running. They are
102
+ labelled by address: `local` is this machine, `network` your LAN, `remote` your
103
+ tailnet. All three are doors into one room — the same server and the same
104
+ waiting verdict — so one wait covers every one the stack shows.
96
105
 
97
106
  **One ending.** Every spec skill finishes with the same block — a verdict
98
107
  (`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
@@ -26,8 +26,7 @@ id it degrades to a repo-wide allow that outlives the session and is cleared onl
26
26
  by `/allow-main off`; the engine says which kind you got, so do not read a bare
27
27
  "allowed" as temporary.
28
28
 
29
- **It is machine-local and gitignored.** Unlike `/spec-remote-review`, this writes
30
- nothing anyone else pulls: it is your decision about your checkout, not the
29
+ **It is machine-local and gitignored.** It writes nothing anyone else pulls: it is your decision about your checkout, not the
31
30
  project's policy. The project-wide switch is `guards.mainIsLandingZone` in
32
31
  `specs/.core/env.config.json`, and turning that off is a different, committed
33
32
  decision.
@@ -50,7 +50,6 @@
50
50
  "servePort": "auto",
51
51
  "serve": "always",
52
52
  "allowNetwork": true,
53
- "allowRemote": false,
54
53
  "commitWith": "/commit",
55
54
  "required": true,
56
55
  "projectName": "",
@@ -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|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
8
+ <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|checks|status|resolve|resume|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
@@ -229,6 +229,14 @@ through to a documented conservative default; see the field notes below.
229
229
  // relies on {slug}-style tokens is a poor one to reuse.
230
230
  "afterLand": [],
231
231
 
232
+ // The project's own end-of-spec checks. `/spec-complete` runs them with
233
+ // `spec-env checks <spec>` in the spec's worktree once the suite is green,
234
+ // before it lands, and relays each one's output in its report. Shell strings,
235
+ // run as written. ADVISORY: a non-zero exit is reported as `failed` and makes
236
+ // the run ⚠️ — it never stops the land. A non-string entry is dropped.
237
+ // "complete": { "checks": ["node scripts/docs-freshness.js impact"] }
238
+ "complete": { "checks": [] },
239
+
232
240
  // Host dev servers `spec-env dev up <spec>` starts on the spec's port block
233
241
  // (for apps that run via `pnpm dev` on the host, not inside the Docker stack).
234
242
  // An array so UI + API (or more) are supervised independently; [] = none.
@@ -593,14 +601,13 @@ through to a documented conservative default; see the field notes below.
593
601
  // It replaced `serveOnRemote`, which gated serving on the reader — and so
594
602
  // handed a local machine a page it could read and not answer. A legacy
595
603
  // `serveOnRemote: false` is still read as `serve: "never"`.
596
- // Either way NOTHING IS PUBLISHED on a detection: a server is one process
597
- // ended by one flag, while a published page is one this tooling cannot
598
- // remove, so that half stays an explicit ask. Teardown names a server that
604
+ // Either way NOTHING IS PUBLISHED: a server is one process ended by one flag,
605
+ // and nothing in this workflow publishes the page. Teardown names a server that
599
606
  // served the last spec, and `spec-env prune` reaps a pidfile whose process is
600
607
  // gone. Default: true.
601
608
  //
602
- // `allowNetwork` and `allowRemote` decide WHICH TIERS a render offers, and
603
- // they replaced the engine guessing where the reader was sitting. It guessed
609
+ // `allowNetwork` decides WHICH TIERS a render offers beyond `local`, and it
610
+ // replaced the engine guessing where the reader was sitting. It guessed
604
611
  // for a while and got it wrong three separate ways in one day: a file:// page
605
612
  // on a session detected `unknown`, a LAN URL for a phone that had left the
606
613
  // network, and an address that changed underneath a reader mid-session. So
@@ -608,26 +615,21 @@ through to a documented conservative default; see the field notes below.
608
615
  // turns it on — and you pick the one that reaches you.
609
616
  //
610
617
  // `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
611
- // page opens on your phone, or loopback only. THIS IS WHAT
612
- // CHOOSES THE BIND; `reader` no longer does. Default: true,
613
- // which matches what the engine already did.
614
- // `allowRemote` — whether PUBLISHING is permitted for EVERY spec. It
615
- // permits it; it publishes nothing. Default: FALSE,
616
- // because a published page is one skitterspec cannot
617
- // delete, so it must never happen unasked. This is the
618
- // PROJECT DEFAULT: `/spec-remote-review` permits one spec
619
- // at a time, in a gitignored sidecar beside its page, and
620
- // never edits this file — `review allow remote --project`
621
- // is what does.
622
- //
623
- // `local` and `network` are two doors into ONE ROOM — the page POSTs to
624
- // `location.pathname`, so both reach the same server and the same waiting
625
- // verdict, and one wait covers both. `remote` is a second store: a verdict
626
- // pressed on a published page needs `/spec-reviewed`, because nothing pushes
627
- // from an artifact's store into a conversation.
628
- //
629
- // Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
630
- // empty value toggles — which is what `/spec-remote-review` runs. It writes
618
+ // page opens on your phone (`network`, the LAN URL) and
619
+ // over your tailnet (`remote`), or loopback only. THIS IS
620
+ // WHAT CHOOSES THE BIND; `reader` no longer does.
621
+ // Default: true, which matches what the engine already did.
622
+ // `allowRemote` — RETIRED, and ignored if present. It permitted publishing
623
+ // the page as a claude.ai artifact; that tier is gone, and
624
+ // `remote` now names the tailnet address on
625
+ // `allowNetwork`'s switch (feat-tailnet-remote-tier).
626
+ //
627
+ // `local`, `network` and `remote` are three doors into ONE ROOM — the page
628
+ // POSTs to `location.pathname`, so each reaches the same server and the same
629
+ // waiting verdict, and one wait covers them all.
630
+ //
631
+ // It is toggled by `spec-env review allow network --set [on|off]`, where an
632
+ // empty value toggles. It writes
631
633
  // THIS FILE in the primary checkout, so it changes for everyone who pulls and
632
634
  // leaves that tree dirty; the engine says so when it does.
633
635
  //
@@ -84,8 +84,62 @@ function readPayload() {
84
84
  const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
85
85
 
86
86
  function findEngine(projectDir, platform = process.platform) {
87
- if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
88
- let at = projectDir
87
+ return locateEngine(projectDir, platform).engine
88
+ }
89
+
90
+ /**
91
+ * `findEngine`, plus the directories it walked up from — which is what a hook
92
+ * names when nothing answered.
93
+ *
94
+ * A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
95
+ * (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
96
+ * primary's `node_modules`. A `--docs` worktree has none of its own, so the
97
+ * primary checkout is asked for second — found through git, never guessed from
98
+ * the folder layout.
99
+ */
100
+ function locateEngine(projectDir, platform = process.platform) {
101
+ if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
102
+ const tried = [projectDir]
103
+ const local = walkUp(projectDir, platform)
104
+ if (local) return { engine: local, tried }
105
+ const primary = primaryCheckoutDir(projectDir)
106
+ if (primary) {
107
+ tried.push(primary)
108
+ const found = walkUp(primary, platform)
109
+ if (found) return { engine: found, tried }
110
+ }
111
+ return { engine: 'skitterspec', tried }
112
+ }
113
+
114
+ /**
115
+ * Where `projectDir` sits in the checkout its worktree was added from, or null
116
+ * when it is not in a linked worktree.
117
+ *
118
+ * WHAT WOULD FOOL THIS: a git directory kept somewhere else
119
+ * (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
120
+ * holds no `node_modules`, so the lookup finds nothing and falls through to
121
+ * PATH exactly as it did before — a wasted look, never a wrong engine.
122
+ */
123
+ function primaryCheckoutDir(projectDir) {
124
+ const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
125
+ cwd: projectDir,
126
+ encoding: 'utf8',
127
+ timeout: 2000,
128
+ })
129
+ if (r.error || r.status !== 0) return null
130
+ const [top, common] = (r.stdout || '').split(/\r?\n/)
131
+ if (!top || !common) return null
132
+ const primary = path.dirname(path.resolve(projectDir, common))
133
+ if (path.resolve(primary) === path.resolve(top)) return null
134
+ // A project in a subfolder of its repo has the same subfolder in the primary.
135
+ // A path that will not map (a symlinked spelling of the same tree) is asked
136
+ // about at the primary's root instead.
137
+ const rel = path.relative(top, projectDir)
138
+ return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
139
+ }
140
+
141
+ function walkUp(start, platform) {
142
+ let at = start
89
143
  for (let i = 0; i < 6 && at; i++) {
90
144
  for (const name of ENGINES) {
91
145
  // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
@@ -103,14 +157,26 @@ function findEngine(projectDir, platform = process.platform) {
103
157
  if (up === at) break
104
158
  at = up
105
159
  }
106
- return 'skitterspec'
160
+ return null
107
161
  }
108
162
 
109
163
  // How to run what `findEngine` found: a `.js` engine through this node, since
110
164
  // Windows cannot execute one directly — anything else as itself, as before.
111
165
  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: [] }
166
+ const { engine, tried } = locateEngine(projectDir, platform)
167
+ const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
168
+ return Object.defineProperty(command, 'tried', { value: tried })
169
+ }
170
+
171
+ // Still open, but not silently: an engine nobody can reach turns this guard off
172
+ // for as long as it stays unreachable, and the operator is owed one line saying
173
+ // so. Stderr with exit 0 is information, never a decision.
174
+ function unreachable(hook, engine, result) {
175
+ if (!result.error || result.error.code !== 'ENOENT') return
176
+ const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
177
+ process.stderr.write(
178
+ `${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
179
+ )
114
180
  }
115
181
 
116
182
  // The tools that write a file. A matcher is configured too, but a hook that is
@@ -169,6 +235,7 @@ function main() {
169
235
 
170
236
  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
171
237
  // process never ran or was killed, and neither is a refusal.
238
+ unreachable('main-guard', engine, result)
172
239
  if (result.error || result.status === null) allow()
173
240
  if (result.status !== 1) allow()
174
241
 
@@ -193,4 +260,4 @@ if (require.main === module) {
193
260
  }
194
261
  }
195
262
 
196
- module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
263
+ module.exports = { findEngine, locateEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
@@ -63,10 +63,69 @@ function readPayload() {
63
63
  const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
64
64
 
65
65
  function findEngine(projectDir, platform = process.platform) {
66
- if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
67
- let at = projectDir
66
+ return locateEngine(projectDir, platform).engine
67
+ }
68
+
69
+ /**
70
+ * `findEngine`, plus the directories it walked up from — which is what a hook
71
+ * names when nothing answered.
72
+ *
73
+ * A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
74
+ * (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
75
+ * primary's `node_modules`. A `--docs` worktree has none of its own, so the
76
+ * primary checkout is asked for second — found through git, never guessed from
77
+ * the folder layout.
78
+ */
79
+ function locateEngine(projectDir, platform = process.platform) {
80
+ if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
81
+ const tried = [projectDir]
82
+ const local = walkUp(projectDir, platform)
83
+ if (local) return { engine: local, tried }
84
+ const primary = primaryCheckoutDir(projectDir)
85
+ if (primary) {
86
+ tried.push(primary)
87
+ const found = walkUp(primary, platform)
88
+ if (found) return { engine: found, tried }
89
+ }
90
+ return { engine: 'skitterspec', tried }
91
+ }
92
+
93
+ /**
94
+ * Where `projectDir` sits in the checkout its worktree was added from, or null
95
+ * when it is not in a linked worktree.
96
+ *
97
+ * WHAT WOULD FOOL THIS: a git directory kept somewhere else
98
+ * (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
99
+ * holds no `node_modules`, so the lookup finds nothing and falls through to
100
+ * PATH exactly as it did before — a wasted look, never a wrong engine.
101
+ */
102
+ function primaryCheckoutDir(projectDir) {
103
+ const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
104
+ cwd: projectDir,
105
+ encoding: 'utf8',
106
+ timeout: 2000,
107
+ })
108
+ if (r.error || r.status !== 0) return null
109
+ const [top, common] = (r.stdout || '').split(/\r?\n/)
110
+ if (!top || !common) return null
111
+ const primary = path.dirname(path.resolve(projectDir, common))
112
+ if (path.resolve(primary) === path.resolve(top)) return null
113
+ // A project in a subfolder of its repo has the same subfolder in the primary.
114
+ // A path that will not map (a symlinked spelling of the same tree) is asked
115
+ // about at the primary's root instead.
116
+ const rel = path.relative(top, projectDir)
117
+ return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
118
+ }
119
+
120
+ function walkUp(start, platform) {
121
+ let at = start
68
122
  for (let i = 0; i < 6 && at; i++) {
69
123
  for (const name of ENGINES) {
124
+ // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
125
+ // shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
126
+ // `.cmd` beside it needs a shell — which a hook handing a tool's command
127
+ // line over as an argument must never use. Unreachable, the hook failed
128
+ // open, and every guard was silently off on Windows (chore-windows-ci).
70
129
  const candidate =
71
130
  platform === 'win32'
72
131
  ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
@@ -77,12 +136,26 @@ function findEngine(projectDir, platform = process.platform) {
77
136
  if (up === at) break
78
137
  at = up
79
138
  }
80
- return 'skitterspec'
139
+ return null
81
140
  }
82
141
 
142
+ // How to run what `findEngine` found: a `.js` engine through this node, since
143
+ // Windows cannot execute one directly — anything else as itself, as before.
83
144
  function engineCommand(projectDir, platform = process.platform) {
84
- const engine = findEngine(projectDir, platform)
85
- return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
145
+ const { engine, tried } = locateEngine(projectDir, platform)
146
+ const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
147
+ return Object.defineProperty(command, 'tried', { value: tried })
148
+ }
149
+
150
+ // Still open, but not silently: an engine nobody can reach turns this guard off
151
+ // for as long as it stays unreachable, and the operator is owed one line saying
152
+ // so. Stderr with exit 0 is information, never a decision.
153
+ function unreachable(hook, engine, result) {
154
+ if (!result.error || result.error.code !== 'ENOENT') return
155
+ const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
156
+ process.stderr.write(
157
+ `${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
158
+ )
86
159
  }
87
160
 
88
161
  const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
@@ -143,6 +216,7 @@ function main() {
143
216
 
144
217
  const engine = engineCommand(home)
145
218
  const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd: home, encoding: 'utf8', timeout: 8000 })
219
+ unreachable('project-guard', engine, result)
146
220
  if (result.error || result.status !== 1) allow()
147
221
  // Exit 1 alone is a crash as often as a refusal; the printed line decides.
148
222
  const said = (result.stdout || '').trim()
@@ -158,4 +232,4 @@ if (require.main === module) {
158
232
  }
159
233
  }
160
234
 
161
- module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, mayConcern, insideHome, isRefusal }
235
+ module.exports = { findEngine, locateEngine, engineCommand, WRITE_TOOLS, writeTarget, mayConcern, insideHome, isRefusal }
@@ -81,8 +81,62 @@ function readPayload() {
81
81
  const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
82
82
 
83
83
  function findEngine(projectDir, platform = process.platform) {
84
- if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
85
- let at = projectDir
84
+ return locateEngine(projectDir, platform).engine
85
+ }
86
+
87
+ /**
88
+ * `findEngine`, plus the directories it walked up from — which is what a hook
89
+ * names when nothing answered.
90
+ *
91
+ * A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
92
+ * (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
93
+ * primary's `node_modules`. A `--docs` worktree has none of its own, so the
94
+ * primary checkout is asked for second — found through git, never guessed from
95
+ * the folder layout.
96
+ */
97
+ function locateEngine(projectDir, platform = process.platform) {
98
+ if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
99
+ const tried = [projectDir]
100
+ const local = walkUp(projectDir, platform)
101
+ if (local) return { engine: local, tried }
102
+ const primary = primaryCheckoutDir(projectDir)
103
+ if (primary) {
104
+ tried.push(primary)
105
+ const found = walkUp(primary, platform)
106
+ if (found) return { engine: found, tried }
107
+ }
108
+ return { engine: 'skitterspec', tried }
109
+ }
110
+
111
+ /**
112
+ * Where `projectDir` sits in the checkout its worktree was added from, or null
113
+ * when it is not in a linked worktree.
114
+ *
115
+ * WHAT WOULD FOOL THIS: a git directory kept somewhere else
116
+ * (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
117
+ * holds no `node_modules`, so the lookup finds nothing and falls through to
118
+ * PATH exactly as it did before — a wasted look, never a wrong engine.
119
+ */
120
+ function primaryCheckoutDir(projectDir) {
121
+ const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
122
+ cwd: projectDir,
123
+ encoding: 'utf8',
124
+ timeout: 2000,
125
+ })
126
+ if (r.error || r.status !== 0) return null
127
+ const [top, common] = (r.stdout || '').split(/\r?\n/)
128
+ if (!top || !common) return null
129
+ const primary = path.dirname(path.resolve(projectDir, common))
130
+ if (path.resolve(primary) === path.resolve(top)) return null
131
+ // A project in a subfolder of its repo has the same subfolder in the primary.
132
+ // A path that will not map (a symlinked spelling of the same tree) is asked
133
+ // about at the primary's root instead.
134
+ const rel = path.relative(top, projectDir)
135
+ return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
136
+ }
137
+
138
+ function walkUp(start, platform) {
139
+ let at = start
86
140
  for (let i = 0; i < 6 && at; i++) {
87
141
  for (const name of ENGINES) {
88
142
  // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
@@ -100,14 +154,26 @@ function findEngine(projectDir, platform = process.platform) {
100
154
  if (up === at) break
101
155
  at = up
102
156
  }
103
- return 'skitterspec'
157
+ return null
104
158
  }
105
159
 
106
160
  // How to run what `findEngine` found: a `.js` engine through this node, since
107
161
  // Windows cannot execute one directly — anything else as itself, as before.
108
162
  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: [] }
163
+ const { engine, tried } = locateEngine(projectDir, platform)
164
+ const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
165
+ return Object.defineProperty(command, 'tried', { value: tried })
166
+ }
167
+
168
+ // Still open, but not silently: an engine nobody can reach turns this guard off
169
+ // for as long as it stays unreachable, and the operator is owed one line saying
170
+ // so. Stderr with exit 0 is information, never a decision.
171
+ function unreachable(hook, engine, result) {
172
+ if (!result.error || result.error.code !== 'ENOENT') return
173
+ const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
174
+ process.stderr.write(
175
+ `${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
176
+ )
111
177
  }
112
178
 
113
179
  // The engine's own refusal line, from `spec-env review gate --check`. Pure.
@@ -143,6 +209,7 @@ function main() {
143
209
 
144
210
  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
145
211
  // process never ran or was killed, and neither is a refusal.
212
+ unreachable('review-gate', engine, result)
146
213
  if (result.error || result.status === null) allow()
147
214
  if (result.status !== 1) allow()
148
215
 
@@ -178,4 +245,4 @@ if (require.main === module) {
178
245
  }
179
246
  }
180
247
 
181
- module.exports = { findEngine, engineCommand, isRefusal }
248
+ module.exports = { findEngine, locateEngine, engineCommand, isRefusal }