@skitterbyte/skitterspec-jira 2.14.0 → 2.16.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 (43) hide show
  1. package/assets/claude-md-section.md +12 -0
  2. package/assets/core/SETUP.md +12 -12
  3. package/assets/core/env.config.md +25 -3
  4. package/assets/hooks/main-guard.cjs +73 -6
  5. package/assets/hooks/project-guard.cjs +80 -6
  6. package/assets/hooks/review-gate.cjs +73 -6
  7. package/assets/review/page.html +2 -1
  8. package/assets/rules/commit-trailers.md +2 -2
  9. package/assets/rules/offered-unblocks.md +22 -0
  10. package/assets/rules/spec-planning.md +12 -1
  11. package/assets/skills/no-spec/SKILL.md +5 -0
  12. package/assets/skills/spec/SKILL.md +20 -3
  13. package/assets/skills/spec-bug/SKILL.md +8 -2
  14. package/assets/skills/spec-complete/SKILL.md +28 -2
  15. package/assets/skills/spec-diff/SKILL.md +5 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +8 -2
  17. package/assets/skills/spec-idea/SKILL.md +5 -0
  18. package/assets/skills/spec-init/SKILL.md +4 -2
  19. package/assets/skills/spec-next/SKILL.md +18 -0
  20. package/assets/skills/spec-park/SKILL.md +92 -0
  21. package/assets/skills/spec-resume/SKILL.md +153 -0
  22. package/assets/skills/spec-start/SKILL.md +6 -2
  23. package/assets/skills/spec-sync/SKILL.md +10 -10
  24. package/assets/skills/spec-to-main/SKILL.md +5 -1
  25. package/assets/skills/spec-todo/SKILL.md +5 -2
  26. package/package.json +1 -1
  27. package/src/cli.js +311 -15
  28. package/src/env/base.js +21 -5
  29. package/src/env/basepin.js +62 -0
  30. package/src/env/bootstrap.js +3 -1
  31. package/src/env/checks.js +49 -0
  32. package/src/env/config.js +48 -1
  33. package/src/env/hooks.js +53 -4
  34. package/src/env/provision.js +10 -2
  35. package/src/env/resolve.js +66 -13
  36. package/src/env/resume.js +234 -0
  37. package/src/env/review.js +4 -1
  38. package/src/env/serve.js +3 -0
  39. package/src/ideacmd.js +11 -1
  40. package/src/init.js +287 -49
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/provider-kit/src/specs.js +46 -1
  43. package/src/vendor/sync-core/src/summary.js +10 -1
@@ -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
@@ -50,7 +50,7 @@ Store the pair in the user-level credentials store (outside every repo,
50
50
  `0600`), **in your own terminal — not through an assistant**:
51
51
 
52
52
  ```sh
53
- pnpm exec skitterspec-jira spec-sync credentials set --site-url https://<site>.atlassian.net
53
+ {{exec}} skitterspec-jira spec-sync credentials set --site-url https://<site>.atlassian.net
54
54
  # Jira account email for https://<site>.atlassian.net: you@example.com
55
55
  # Jira API token for you@example.com (hidden): ●●●●●●●●
56
56
  ```
@@ -81,7 +81,7 @@ statuses (`spec-sync states`) — then writes `specs/.core/jira.config.json`
81
81
  via `spec-sync init-config`. By hand instead:
82
82
 
83
83
  ```sh
84
- pnpm exec skitterspec-jira spec-sync init-config \
84
+ {{exec}} skitterspec-jira spec-sync init-config \
85
85
  --site-url https://your-site.atlassian.net \
86
86
  --project-key PROJ \
87
87
  --state complete=Done
@@ -106,7 +106,7 @@ anything was released. A workflow that encodes a pipeline has standard outs
106
106
  ## 4. Check — `spec-sync doctor`
107
107
 
108
108
  ```sh
109
- pnpm exec skitterspec-jira spec-sync doctor --check-remote
109
+ {{exec}} skitterspec-jira spec-sync doctor --check-remote
110
110
  ```
111
111
 
112
112
  Every row reports `ok`, or names the exact command that fixes it. `missing`
@@ -133,20 +133,20 @@ apply path. `states.json` below is the project's status names.
133
133
  1. **Doctor** — every row ok:
134
134
 
135
135
  ```sh
136
- pnpm exec skitterspec-jira spec-sync doctor --check-remote
136
+ {{exec}} skitterspec-jira spec-sync doctor --check-remote
137
137
  ```
138
138
 
139
139
  2. **States** — the project's statuses list:
140
140
 
141
141
  ```sh
142
- pnpm exec skitterspec-jira spec-sync states --json > states.json
142
+ {{exec}} skitterspec-jira spec-sync states --json > states.json
143
143
  ```
144
144
 
145
145
  3. **Mint** — on a test spec with at least one phase and a task checklist:
146
146
 
147
147
  ```sh
148
- pnpm exec skitterspec-jira spec-sync plan <spec> --workspace-states states.json --json > plan.json
149
- pnpm exec skitterspec-jira spec-sync apply <spec> --plan plan.json
148
+ {{exec}} skitterspec-jira spec-sync plan <spec> --workspace-states states.json --json > plan.json
149
+ {{exec}} skitterspec-jira spec-sync apply <spec> --plan plan.json
150
150
  ```
151
151
 
152
152
  In Jira: the issue and its subtasks exist, statuses match the buckets, and
@@ -161,8 +161,8 @@ apply path. `states.json` below is the project's status names.
161
161
  onto a spec, and preserve before the linking push:
162
162
 
163
163
  ```sh
164
- pnpm exec skitterspec-jira spec-sync stamp <spec> --issue PROJ-123
165
- pnpm exec skitterspec-jira spec-sync preserve <spec>
164
+ {{exec}} skitterspec-jira spec-sync stamp <spec> --issue PROJ-123
165
+ {{exec}} skitterspec-jira spec-sync preserve <spec>
166
166
  ```
167
167
 
168
168
  The original description appears as a comment headed **Original report**;
@@ -174,7 +174,7 @@ apply path. `states.json` below is the project's status names.
174
174
  every sub-issue as a stale ref) and:
175
175
 
176
176
  ```sh
177
- pnpm exec skitterspec-jira spec-sync verify <spec> --stored readback.json
177
+ {{exec}} skitterspec-jira spec-sync verify <spec> --stored readback.json
178
178
  ```
179
179
 
180
180
  "round-tripped intact", exit 0.
@@ -182,7 +182,7 @@ apply path. `states.json` below is the project's status names.
182
182
  7. **Released** — over a range with `Refs:` trailers:
183
183
 
184
184
  ```sh
185
- pnpm exec skitterspec-jira spec-sync released <tag>..HEAD
185
+ {{exec}} skitterspec-jira spec-sync released <tag>..HEAD
186
186
  ```
187
187
 
188
188
  Tickets counted, unreferenced commits reported, bookkeeping ignored.
@@ -191,7 +191,7 @@ apply path. `states.json` below is the project's status names.
191
191
  and:
192
192
 
193
193
  ```sh
194
- pnpm exec skitterspec-jira spec-sync status <spec> --remote issue.json
194
+ {{exec}} skitterspec-jira spec-sync status <spec> --remote issue.json
195
195
  ```
196
196
 
197
197
  The edit is reported; the next apply replaces it and says so loudly.
@@ -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.
@@ -325,8 +333,11 @@ through to a documented conservative default; see the field notes below.
325
333
  // - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
326
334
  // rc/a/b. Spell each segment ("20??/Q?").
327
335
  // - No match REFUSES, naming `spec-env base` — it never falls back to
328
- // origin/HEAD, because zero matches usually means "not fetched", and
329
- // the default branch is exactly where a rolling base must not land.
336
+ // origin/HEAD UNASKED, because zero matches usually means "not
337
+ // fetched", and the default branch is exactly where a rolling base must
338
+ // not land by accident. Between rcs (one merged, the next not cut) the
339
+ // refusal OFFERS `baseBranchFallback` below; accepting it pins that
340
+ // branch locally until a match appears, for every command at once.
330
341
  // - Newest-by-date is only right when one rc is live at a time (the next
331
342
  // is cut after the last merges). If your rcs overlap, pin `baseBranch`.
332
343
  // - A spec that outlived a roll lands on the new rc; the integrate plan
@@ -336,6 +347,17 @@ through to a documented conservative default; see the field notes below.
336
347
  // `spec-env base` lists the matches, the base, and specs on an older one.
337
348
  "baseBranchPattern": "",
338
349
 
350
+ // The branch OFFERED as the base while `baseBranchPattern` matches nothing —
351
+ // the gap between one rc merging and the next being cut. Empty = the
352
+ // remote's default branch (`<land.remote>/HEAD`). It is never used unasked:
353
+ // the refusal offers it, and accepting (`spec-env base --use-fallback`)
354
+ // writes a local, gitignored pin in `.spec-env/base-pin.json` that clears
355
+ // itself the moment a branch matches again. Name a branch here when you
356
+ // release from something other than the default (a test branch). A value
357
+ // that names no branch, or neither resolving, means no offer — a plain
358
+ // refusal, because a guessed base is worse. Ignored without a pattern.
359
+ "baseBranchFallback": "",
360
+
339
361
  // How a finished branch reaches the base branch.
340
362
  // strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
341
363
  // exactly as always; nothing below applies.
@@ -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 }
@@ -3373,7 +3373,8 @@ a.ticket:hover { border-color: var(--accent); }
3373
3373
  part(data.branch)
3374
3374
  sep()
3375
3375
  part(data.mode === 'branch'
3376
- ? 'everything since ' + data.base + (data.fellBack ? ' (working tree clean)' : '')
3376
+ ? 'everything since ' + data.base + (data.fellBack ? ' (working tree clean)' : '') +
3377
+ (data.baseGap ? ' — ' + data.baseGap : '')
3377
3378
  : data.mode === 'docs'
3378
3379
  ? "the spec's own documents"
3379
3380
  : 'uncommitted work')
@@ -23,7 +23,7 @@ Refs: PROJ-29
23
23
  Get the value from the engine rather than reading it off a spec by hand:
24
24
 
25
25
  ```
26
- pnpm exec skitterspec-jira spec-sync ref
26
+ {{exec}} skitterspec-jira spec-sync ref
27
27
  ```
28
28
 
29
29
  Bare, that answers **from the branch** — correct whenever you are committing
@@ -48,7 +48,7 @@ the bare command answers with the old spec's ticket.
48
48
  Name the spec instead — still the engine, never a hand-written id:
49
49
 
50
50
  ```
51
- pnpm exec skitterspec-jira spec-sync ref feat-distance-prescriptions
51
+ {{exec}} skitterspec-jira spec-sync ref feat-distance-prescriptions
52
52
  ```
53
53
 
54
54
  The branch is not consulted, so this works from `main` too. An unknown spec name
@@ -55,6 +55,28 @@ offer's `label`, and Cancel.
55
55
  something easier-sounding, never pre-select it, and never add a third option. A
56
56
  bypass that arrives pre-selected is a bypass by default wearing a question mark.
57
57
 
58
+ ### A worked `satisfy`: the gap between release branches
59
+
60
+ Under `baseBranchPattern`, a base nobody can resolve refuses — and where the
61
+ last release branch has merged and the next is not yet cut, that refusal is the
62
+ normal state of the repo for a while, not a mistake. So the engine declares:
63
+
64
+ ```json
65
+ {
66
+ "blocked": true,
67
+ "reason": "no branch matches 20??/Q? — run spec-env base to fetch",
68
+ "offer": { "kind": "satisfy", "label": "Use master as the base for now", "command": "skitterspec spec-env base --use-fallback" }
69
+ }
70
+ ```
71
+
72
+ Text output carries the same thing as an `offer:` line under the refusal. On
73
+ the pick, run the command and retry the command that refused. It is `satisfy`
74
+ because it gives the guard what it asked for — a base — and the pick is kept as
75
+ a local pin that every command then honours, so it is asked once per gap rather
76
+ than once per command. The pin clears itself when a branch matches again, so
77
+ nothing about it needs recording. No fallback resolvable means no `offer`, and
78
+ the refusal stands alone.
79
+
58
80
  ## A bypass is offered once per obligation
59
81
 
60
82
  The engine enforces this; a skill does not count anything. Spend the offer by
@@ -18,6 +18,8 @@ and lifecycle stay consistent. Each sets a status on the spec header
18
18
  | `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
19
19
  | `/spec-reviewed` | Pick up a review approved on the page — offered by its code, claimed on your word | (unchanged) | (unchanged) |
20
20
  | `/spec-epic-next` | Name the epic member that can start now, as the `/spec-start` to type in a new tab — a picker when several can; reads only | (unchanged) | (unchanged) |
21
+ | `/spec-resume` | Go back into a spec already in flight, by name or `#N`. It rebuilds the worktree when this machine has none, shows what it is blocked on, and acts on the message given with it. It starts nothing | (unchanged) | (unchanged) |
22
+ | `/spec-park` | Park a spec in flight on something outside the repo: a `Blocked on:` line on the spec or a phase, committed on its branch. The worktree stays | (unchanged) | (unchanged) |
21
23
  | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
22
24
  | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
23
25
  | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
@@ -253,7 +255,7 @@ your canonical `localhost` ports so you can test it at the normal URL
253
255
  move, header edits, the code) happens on the spec's branch in the worktree; `main`
254
256
  changes only when it merges. Teardown is folded into `/spec-complete` ·
255
257
  `/spec-cancel`. Beneath the skills, `skitterspec spec-env
256
- <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
258
+ <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|checks|status|resolve|resume|base>` is the CLI
257
259
  engine. `up` plans the fork;
258
260
  **`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
259
261
  the command a skill runs names no file, and a secrets hook that refuses any
@@ -906,6 +908,15 @@ Every spec header carries:
906
908
  only that phase.
907
909
  - `> **Lanes:**` — on an epic, optional: how many members may be in flight at
908
910
  once.
911
+ - `> **Blocked on:**`: on a spec, or on one phase file. It records that the
912
+ spec, or that phase, waits on something outside the repo: a deploy, another
913
+ project's release, a soak. The value is free text, with an optional
914
+ `(until YYYY-MM-DD)` that `/spec-todo` reads. `/spec` writes the planned
915
+ ones, `/spec-park` writes the ad-hoc ones, and `/spec-resume` clears them on
916
+ the record. `/spec-next` stops before building past one, and
917
+ `/spec-complete` reports one still standing. **Not `Waits on:`.** That one
918
+ is an epic wait the engine can observe on the base branch. This one is a
919
+ condition only a person can judge, so nothing ever counts it as met.
909
920
 
910
921
  **Under a provider's default `pull`, these three are the tracker's** —
911
922
  `Status:`, `Developer:` and the State log — and new specs carry
@@ -45,6 +45,11 @@ things answering to one name is how a teardown removes the wrong tree.
45
45
  skitterspec spec-env nospec <name>
46
46
  ```
47
47
 
48
+ A refusal naming `no branch matches <pattern>` that carries an `offer:` line
49
+ is the gap between release branches: relay it, then offer it as
50
+ `.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
51
+ the pick run `skitterspec spec-env base --use-fallback` and retry.
52
+
48
53
  It records the name as a **specless branch** and prints the plan. Run the
49
54
  `git worktree add` it prints, then move this session into the worktree with a
50
55
  plain `cd` and run the `then, run:` line where there is one:
@@ -36,8 +36,14 @@ Then:
36
36
 
37
37
  1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
38
38
  and drop any issue whose identifier is already stamped on a spec. If the user
39
- named such an issue directly, **stop** and point them at that spec — one issue
40
- never becomes two specs.
39
+ named such an issue directly, it already has a spec, and one issue never
40
+ becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
41
+ of what they wrote as its message: feedback on shipped work, or "the deploy
42
+ is out", belongs to the spec that is already in flight. Confirm it, as kind
43
+ routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
44
+ a yes. On a no, stop and name the spec. That spec may exist only on its
45
+ branch, which `linked` reads too, so a missing `specs/` folder here is not
46
+ evidence that the issue is free.
41
47
  2. **Read the issue** with the discovered issue-read tool (`getJiraIssue`):
42
48
  title, description, labels, reporter, URL. If Jira isn't connected, say so
43
49
  and offer to carry on without it — a spec written from the user's own
@@ -215,7 +221,15 @@ not write the spec until this is resolved.
215
221
  answer **either way**: a flag name, or `none: <one-line reason>`. "No" is a
216
222
  decision and belongs in the header; silence is not. Skip entirely when the
217
223
  config is absent — that project does not use flags.
218
- 11. **Open questions** — anything still undecided.
224
+ 11. **Waits outside the repo**: does any phase only make sense once
225
+ something happens elsewhere? For example, an earlier phase deployed and
226
+ running for logs, another project's release, or a soak of N days. Each
227
+ becomes that phase file's `> **Blocked on:**` line (template below),
228
+ with `(until YYYY-MM-DD)` only when a date was given. `/spec-next` stops
229
+ before building that phase, and `/spec-resume` is how it goes on. This
230
+ is free text, a condition only a person can judge, which is what sets it
231
+ apart from an epic member's `Waits on:`. With no such wait, write none.
232
+ 12. **Open questions** — anything still undecided.
219
233
 
220
234
  Stop grilling when there are no unresolved branches that would change the spec.
221
235
  Briefly play back the agreed understanding before writing.
@@ -500,6 +514,9 @@ order). Each phase file uses this template:
500
514
  # Phase 1 — <goal> ⬜
501
515
 
502
516
  > Spec: [00-overview.md](00-overview.md) · **Status:** Not started
517
+ > **Blocked on:** <only when this phase waits on something outside the repo
518
+ > (Phase A item 11) — the condition, plus "(until YYYY-MM-DD)" if dated.
519
+ > Omit the line entirely otherwise>
503
520
 
504
521
  **Goal:** <one line — what this phase delivers and how it's proven>.
505
522