@skitterbyte/skitterspec-linear 19.15.0 → 19.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.
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 |
@@ -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
@@ -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.
@@ -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 }
@@ -23,7 +23,7 @@ Refs: SKS-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-linear spec-sync ref
26
+ {{exec}} skitterspec-linear 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-linear spec-sync ref feat-distance-prescriptions
51
+ {{exec}} skitterspec-linear 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
@@ -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
@@ -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: title, description,
42
48
  labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
43
49
  without it — a spec written from the user's own description is still a spec.
@@ -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
 
@@ -35,8 +35,14 @@ Then:
35
35
 
36
36
  1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
37
37
  and drop any issue whose identifier is already stamped on a spec. If the user
38
- named such an issue directly, **stop** and point them at that spec — one issue
39
- never becomes two specs.
38
+ named such an issue directly, it already has a spec, and one issue never
39
+ becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
40
+ of what they wrote as its message: feedback on shipped work, or "the deploy
41
+ is out", belongs to the spec that is already in flight. Confirm it, as kind
42
+ routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
43
+ a yes. On a no, stop and name the spec. That spec may exist only on its
44
+ branch, which `linked` reads too, so a missing `specs/` folder here is not
45
+ evidence that the issue is free.
40
46
  2. **Read the issue** with the discovered issue-read tool: title, description,
41
47
  labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
42
48
  without it — a spec written from the user's own description is still a spec.
@@ -35,11 +35,32 @@ Before marking complete, confirm the work is actually finished:
35
35
  - If genuinely incomplete work remains, **stop and tell the user** rather than
36
36
  forcing completion. Offer to finish it (`/spec-next`) or to complete with the
37
37
  remaining items explicitly listed as deferred.
38
+ - **Report any blocker still standing; never refuse over one.** Run
39
+ `skitterspec spec-env resume <spec> --json` and read `blockers`. Each
40
+ `> **Blocked on:**` line still in the spec goes in the report's `Notes`,
41
+ quoted with its `until` date where it has one. A spec can finish with a wait
42
+ still written down: the soak may have been dropped, or the deploy may have
43
+ happened without anyone saying so. The line staying in the completed spec is
44
+ the record of that, and nothing is gated on it. With none, say nothing.
38
45
  - **Check for pre-existing uncommitted changes — before you touch anything.**
39
46
  Run `git status`. Anything already uncommitted is the *user's* work (a
40
47
  half-finished phase, a stray fix) and must not be swept into the completion
41
48
  commit: offer `/commit` and **stop**. Everything this skill writes in steps 3–4
42
49
  is its own, and step 4 commits that.
50
+ - **Run the project's completion checks**, once the suite is green:
51
+
52
+ ```
53
+ skitterspec spec-env checks <spec>
54
+ ```
55
+
56
+ It runs each `complete.checks` command from `env.config.json` in the spec's
57
+ worktree — the project's own end-of-spec questions, such as a docs report —
58
+ and always exits 0. Relay what each printed into `Notes`. A check marked
59
+ `failed` makes the run `⚠️`; it **never stops the completion or the land**,
60
+ because a check's output is a reason to look again, not proof of a fault.
61
+ Where a check names a fix you can make now (re-read a page, then record it),
62
+ offer it — the operator answers. `no completion checks configured` is the
63
+ usual answer and says nothing in the report.
43
64
 
44
65
 
45
66
  ### An epic — complete after its members
@@ -278,7 +299,8 @@ the shape; this section carries only what is specific here.
278
299
 
279
300
  `Notes` carries the after-land commands step 6 ran, and where, and any it
280
301
  skipped because the land matched no `when` — or, on a failure, the command that failed and the ones that did not run. A project with
281
- no `afterLand` says nothing about it.
302
+ no `afterLand` says nothing about it. It also carries what each completion
303
+ check reported (§2) — a project with none says nothing about them either.
282
304
 
283
305
  **Report this spec and no other.** A completion is the moment it is most
284
306
  tempting to survey what is left — what else is in flight, what is in the
@@ -42,8 +42,14 @@ Then:
42
42
 
43
43
  1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
44
44
  and drop any issue whose identifier is already stamped on a spec. If the user
45
- named such an issue directly, **stop** and point them at that spec — one issue
46
- never becomes two specs.
45
+ named such an issue directly, it already has a spec, and one issue never
46
+ becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
47
+ of what they wrote as its message: feedback on shipped work, or "the deploy
48
+ is out", belongs to the spec that is already in flight. Confirm it, as kind
49
+ routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
50
+ a yes. On a no, stop and name the spec. That spec may exist only on its
51
+ branch, which `linked` reads too, so a missing `specs/` folder here is not
52
+ evidence that the issue is free.
47
53
  2. **Read the issue** with the discovered issue-read tool: title, description,
48
54
  labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
49
55
  without it — a spec written from the user's own description is still a spec.
@@ -27,14 +27,16 @@ clobber customised content. Finish with a summary of created vs already-present.
27
27
  > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
28
28
  > `--reset` (reset needs `--yes`) drive the stronger actions.
29
29
 
30
- The system is **eighteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
30
+ The system is **twenty skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
31
31
  `spec-hotfix` (a bug fixed on a released tag),
32
32
  `spec-incident` (a live outage, recorded as it happens),
33
33
  `no-spec` (work that genuinely has none — off the base branch all the same),
34
34
  `spec-review`, `spec-start`,
35
35
  `spec-next`, `spec-diff` (read a spec's diff as a page),
36
36
  `spec-reviewed` (pick up a review you approved on that page),
37
- `spec-epic-next` (name the epic member that can start now), `spec-to-main`,
37
+ `spec-epic-next` (name the epic member that can start now),
38
+ `spec-resume` (back into a spec in flight, by name or ticket),
39
+ `spec-park` (record what a spec in flight is waiting on), `spec-to-main`,
38
40
  `spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
39
41
  `spec-todo` (where you left off, and what is ahead), `spec-idea` (an idea
40
42
  parked without a spec),
@@ -215,6 +215,24 @@ once at the start, so each phase is asked as it is built.
215
215
  not matter for this phase, and the bypass is that knowledge on the record. What
216
216
  it rules out is the silent build.
217
217
 
218
+ **Then ask whether the spec is parked.** Run
219
+ `skitterspec spec-env resume <spec> --json` and read `blocking`. It is the
220
+ `> **Blocked on:**` line that holds this build: the spec's own line, or this
221
+ phase's. A line on a later phase is not this build's business, and the engine
222
+ leaves it out.
223
+
224
+ - **`blocking: null`**: carry on in silence. This is the usual case.
225
+ - **Anything else**: stop with the `⏸` block before marking anything started.
226
+ `Why` quotes the blocker, with its `until` date where it has one. `Next` is
227
+ `/spec-resume <spec> <what happened>`, which is the exit. It hears that the
228
+ condition is met, clears the line on the record, and builds.
229
+
230
+ **No bypass is offered here, and none is needed.** Unlike an epic wait, a
231
+ blocker is a condition only a person can judge (a deploy, another project's
232
+ release, a week in prod), so the person who knows it is met says so to
233
+ `/spec-resume`, and that clears it with a Changelog line. A build past one
234
+ without a word would be exactly the silent step this check exists to stop.
235
+
218
236
  Mark it started: set the phase-file heading to `🔄` and its `> **Status:**` to
219
237
  `In progress`, and flip the matching row in the overview phase index to `🔄`.
220
238