@skitterbyte/skitterspec-linear 19.14.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 +2 -0
- package/assets/claude-md-section.md +12 -0
- package/assets/core/env.config.md +25 -3
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +2 -1
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/offered-unblocks.md +22 -0
- package/assets/rules/spec-planning.md +12 -1
- package/assets/skills/no-spec/SKILL.md +5 -0
- package/assets/skills/spec/SKILL.md +20 -3
- package/assets/skills/spec-bug/SKILL.md +8 -2
- package/assets/skills/spec-complete/SKILL.md +28 -2
- package/assets/skills/spec-diff/SKILL.md +5 -0
- package/assets/skills/spec-hotfix/SKILL.md +8 -2
- package/assets/skills/spec-idea/SKILL.md +5 -0
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +18 -0
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-start/SKILL.md +6 -2
- package/assets/skills/spec-status/SKILL.md +1 -1
- package/assets/skills/spec-sync/SKILL.md +12 -12
- package/assets/skills/spec-to-main/SKILL.md +5 -1
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +311 -15
- package/src/env/base.js +21 -5
- package/src/env/basepin.js +62 -0
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +48 -1
- package/src/env/hooks.js +53 -4
- package/src/env/provision.js +10 -2
- package/src/env/resolve.js +66 -13
- package/src/env/resume.js +234 -0
- package/src/env/review.js +4 -1
- package/src/env/serve.js +3 -0
- package/src/ideacmd.js +11 -1
- package/src/init.js +287 -49
- package/src/tada/todo.js +19 -4
- package/src/vendor/linear/cli-sync.js +3 -3
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
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.
|
|
@@ -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
|
|
329
|
-
// the default branch is exactly where a rolling base must
|
|
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
|
-
|
|
88
|
-
|
|
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
|
|
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 =
|
|
113
|
-
|
|
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
|
-
|
|
67
|
-
|
|
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
|
|
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 =
|
|
85
|
-
|
|
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
|
-
|
|
85
|
-
|
|
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
|
|
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 =
|
|
110
|
-
|
|
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 }
|
package/assets/review/page.html
CHANGED
|
@@ -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: SKS-29
|
|
|
23
23
|
Get the value from the engine rather than reading it off a spec by hand:
|
|
24
24
|
|
|
25
25
|
```
|
|
26
|
-
|
|
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
|
-
|
|
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
|
|
@@ -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,
|
|
40
|
-
|
|
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. **
|
|
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,
|
|
39
|
-
|
|
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
|
|
@@ -439,7 +461,11 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
|
|
|
439
461
|
relay it verbatim in the `Landed` row so the reader sees where the work went.
|
|
440
462
|
|
|
441
463
|
A refusal naming `no branch matches <pattern>` means no release candidate is
|
|
442
|
-
visible
|
|
464
|
+
visible. Where it carries an `offer:` line it is the gap between release
|
|
465
|
+
branches: relay it, then offer it as `.claude/rules/offered-unblocks.md`
|
|
466
|
+
describes — its label and Cancel — and on the pick run
|
|
467
|
+
`skitterspec spec-env base --use-fallback` and retry the land. With no offer
|
|
468
|
+
it is usually not fetched: relay it, stop with `⏸`, and name
|
|
443
469
|
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
444
470
|
3. **Run the after-land commands.** Where the plan ends with a
|
|
445
471
|
`then, in the primary checkout (<path>), run:` section — the project's
|