@skitterbyte/skitterspec-linear 18.0.1 → 18.1.1
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/MIGRATION.md +81 -0
- package/assets/core/env.config.md +36 -9
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-planning.md +4 -2
- package/assets/skills/spec-complete/SKILL.md +67 -25
- package/assets/skills/spec-hotfix/SKILL.md +21 -11
- package/assets/skills/spec-sync/SKILL.md +10 -1
- package/package.json +1 -1
- package/src/cli.js +289 -34
- package/src/env/config.js +14 -2
- package/src/env/hotfix.js +288 -16
- package/src/env/hotfixland.js +302 -0
- package/src/env/resolve.js +22 -8
- package/src/init.js +36 -4
- package/src/vendor/linear/api.js +43 -56
- package/src/vendor/linear/cli-sanitise.js +2 -2
- package/src/vendor/linear/cli-sync.js +87 -390
- package/src/vendor/linear/config.js +46 -171
- package/src/vendor/linear/credentials.js +40 -370
- package/src/vendor/linear/dialect.js +177 -0
- package/src/vendor/linear/doctor.js +7 -15
- package/src/vendor/linear/identity.js +20 -70
- package/src/vendor/linear/released.js +4 -222
- package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
- package/src/vendor/provider-kit/index.js +41 -0
- package/src/vendor/provider-kit/src/adapter.js +23 -0
- package/src/vendor/provider-kit/src/apply.js +197 -0
- package/src/vendor/provider-kit/src/args.js +68 -0
- package/src/vendor/provider-kit/src/config.js +198 -0
- package/src/vendor/provider-kit/src/credentials.js +404 -0
- package/src/vendor/provider-kit/src/doctor.js +35 -0
- package/src/vendor/provider-kit/src/http.js +44 -0
- package/src/vendor/provider-kit/src/identity.js +93 -0
- package/src/vendor/provider-kit/src/md-compare.js +39 -0
- package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
- package/src/vendor/provider-kit/src/prompt.js +50 -0
- package/src/vendor/provider-kit/src/released.js +226 -0
- package/src/vendor/provider-kit/src/specs.js +166 -0
- package/src/vendor/provider-kit/src/transport.js +22 -0
- package/src/vendor/sync-core/index.js +22 -5
- package/src/vendor/sync-core/src/compare.js +14 -12
- package/src/vendor/sync-core/src/dialect.js +51 -0
- package/src/vendor/sync-core/src/fields.js +36 -0
- package/src/vendor/sync-core/src/legacy.js +19 -9
- package/src/vendor/sync-core/src/normalize.js +30 -158
- package/src/vendor/sync-core/src/push.js +1 -1
- package/src/vendor/sync-core/src/retarget.js +21 -17
- package/src/vendor/sync-core/src/verify.js +24 -45
- package/src/vendor/sync-core/src/write.js +7 -5
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,69 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
|
|
4
|
+
|
|
5
|
+
### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
|
|
6
|
+
|
|
7
|
+
`hotfix land` used to print a plan: a `git tag` for the patch-bumped base tag,
|
|
8
|
+
the `--also` cherry-picks, and a `git cherry-pick <base>..<branch>` onto main.
|
|
9
|
+
The skill ran it by hand, and you pushed the tag yourself.
|
|
10
|
+
**It now runs the land itself**, stopping at the first step that fails:
|
|
11
|
+
|
|
12
|
+
1. **release** — `hotfix.releaseWith` when it is set (see below), otherwise the
|
|
13
|
+
built-in tagger. The release is recorded in `.spec-env/hotfix/<spec>.json`,
|
|
14
|
+
so a re-run reuses it rather than cutting a second one.
|
|
15
|
+
2. **push** — the branch, then the tag, to `origin`, **only with `--push`**.
|
|
16
|
+
Without it the run **holds** here: exit 0, both push commands printed, and
|
|
17
|
+
nothing carried. A re-run after you push by hand finds the tag on the remote
|
|
18
|
+
and carries on.
|
|
19
|
+
3. **carry** — the branch's commits onto main, **minus the version commit** and
|
|
20
|
+
anything main already has, so the spec's completion commits arrive and main's
|
|
21
|
+
version line does not move. It runs in place when main is checked out and
|
|
22
|
+
clean, through a throwaway worktree when it isn't checked out, and is
|
|
23
|
+
**refused** with the command to run later when main is checked out and dirty.
|
|
24
|
+
A conflict is aborted and names the commit.
|
|
25
|
+
|
|
26
|
+
`--plan` describes the steps and runs nothing; `--json` reports each step's
|
|
27
|
+
outcome. Refusals and failures now exit 1.
|
|
28
|
+
|
|
29
|
+
**What to change.** Run `skitterspec update` to take the new `/spec-complete`
|
|
30
|
+
and `/spec-hotfix`. `/spec-complete` asks before passing `--push`. Anything of
|
|
31
|
+
your own that ran `hotfix land`'s printed commands should run the verb itself,
|
|
32
|
+
with `--push` once you have decided to deploy.
|
|
33
|
+
|
|
34
|
+
### Breaking change 2 — a hotfix's worktree waits for `spec-env hotfix finish`
|
|
35
|
+
|
|
36
|
+
`/spec-complete` used to tear a hotfix down as soon as it had tagged. The branch
|
|
37
|
+
is now kept until the deploy is confirmed, because a failed deploy cuts the next
|
|
38
|
+
release from the same branch. Run `/spec-complete` again on the landed hotfix,
|
|
39
|
+
or `skitterspec spec-env hotfix finish <spec>` directly. It removes the worktree
|
|
40
|
+
and deletes the branch only when the tree is clean, a release tag is at HEAD,
|
|
41
|
+
and `origin/<branch>` is at HEAD. It names every check that fails, and has no
|
|
42
|
+
`--force`.
|
|
43
|
+
|
|
44
|
+
### New — `hotfix.releaseWith` and a real `hotfix.bump`
|
|
45
|
+
|
|
46
|
+
- **`hotfix.releaseWith`** is a command run in the hotfix worktree. It cuts the
|
|
47
|
+
release (a version commit and a tag) and prints one JSON line:
|
|
48
|
+
`{"tag","version","baseTag","branch","versionCommit","pushed"}`. skittership
|
|
49
|
+
2.1+ ships one:
|
|
50
|
+
|
|
51
|
+
```jsonc
|
|
52
|
+
"hotfix": { "releaseWith": "node scripts/release-hotfix.cjs --json" }
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Call node directly, not `pnpm run`, so no run banner reaches stdout. Anything
|
|
56
|
+
but the JSON line is a refusal. Add `--allow-postversion` yourself if your
|
|
57
|
+
package.json has a `postversion` script. `init` and `update` suggest this when
|
|
58
|
+
the script is present, and never write it.
|
|
59
|
+
- **`hotfix.bump`** was parsed and ignored; it is now read. `"patch"` (the
|
|
60
|
+
default) is the old behaviour. `"hotfix-suffix"` cuts `X.Y.Z-hotfix.N`,
|
|
61
|
+
continues a base that is already a hotfix tag, and is not blocked by a later
|
|
62
|
+
`X.Y.(Z+1)`. Any other value is refused when `hotfix land` runs.
|
|
63
|
+
|
|
64
|
+
Extra targets (`hotfix.targets` / `--also`) stay tag-only: they never go through
|
|
65
|
+
`releaseWith` and are not pushed.
|
|
66
|
+
|
|
3
67
|
## `@skitterbyte/skitterspec` v22 → v23 (the engine runs the worktree bootstrap)
|
|
4
68
|
|
|
5
69
|
### Breaking change — `spec-env up` no longer prints the worktree steps
|
|
@@ -36,6 +100,17 @@ Nothing in `env.config.json` changes.
|
|
|
36
100
|
**If you added a secrets-hook exception for the printed seed commands**, you
|
|
37
101
|
can remove it now. Nothing shipped prints them any more.
|
|
38
102
|
|
|
103
|
+
## `@skitterbyte/skitterspec-jira` v0 → v1 (first release)
|
|
104
|
+
|
|
105
|
+
Nothing to migrate: this is the distribution's first release. It is a superset
|
|
106
|
+
of `@skitterbyte/skitterspec` — install exactly one of the base, the Linear
|
|
107
|
+
superset, or this one. Coming from the base, run `npx
|
|
108
|
+
@skitterbyte/skitterspec-jira update` and then `skitterspec-jira spec-sync
|
|
109
|
+
init-config --site-url … --project-key …` (or the `/spec-jira-setup` skill) to
|
|
110
|
+
opt into Jira sync. Coming from `@skitterbyte/skitterspec-linear`: the two
|
|
111
|
+
supersets share one credentials store and one base workflow, but a repo syncs
|
|
112
|
+
to one tracker — swap distributions only if the repo is moving trackers.
|
|
113
|
+
|
|
39
114
|
## `@skitterbyte/skitterspec` v21 → v22 (a review port per repo, and every render serves)
|
|
40
115
|
|
|
41
116
|
### Breaking change 1 — `review.serveOnRemote` is now `review.serve`
|
|
@@ -163,6 +238,12 @@ can run it.
|
|
|
163
238
|
committed file, so it changes for everyone who pulls and leaves that tree dirty.
|
|
164
239
|
The engine says so when it does.
|
|
165
240
|
|
|
241
|
+
## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
|
|
242
|
+
|
|
243
|
+
The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
|
|
244
|
+
distribution composes the same engine. Read that entry; nothing here is
|
|
245
|
+
Linear-specific.
|
|
246
|
+
|
|
166
247
|
## `@skitterbyte/skitterspec-linear` v17 → v18 (the engine runs the worktree bootstrap)
|
|
167
248
|
|
|
168
249
|
The same change as `@skitterbyte/skitterspec` v22 → v23 above — this
|
|
@@ -153,8 +153,8 @@ through to a documented conservative default; see the field notes below.
|
|
|
153
153
|
// `spec-env integrate` prints them after the fast-forward (worktree and
|
|
154
154
|
// checkout mode), and also after "already landed" — a land on another
|
|
155
155
|
// machine leaves them pending here. `spec-env hotfix land` prints them
|
|
156
|
-
// after
|
|
157
|
-
// `hotfix.cherryPickMain`
|
|
156
|
+
// after a carry that moved the base branch, and not at all when it moved
|
|
157
|
+
// nothing (held, already carried, or `hotfix.cherryPickMain` false).
|
|
158
158
|
// The engine only plans: /spec-complete, /spec-to-main and /no-spec run
|
|
159
159
|
// them (a /spec documents-only land does not). They stop at the first
|
|
160
160
|
// failure, report it as a caveat, and never undo the land or block
|
|
@@ -276,14 +276,41 @@ through to a documented conservative default; see the field notes below.
|
|
|
276
276
|
},
|
|
277
277
|
|
|
278
278
|
// Hotfix landing (`spec-env hotfix land` / `/spec-complete` on a Type: Hotfix
|
|
279
|
-
// spec). A hotfix forks from a release tag and lands by
|
|
280
|
-
// fast-forward
|
|
281
|
-
//
|
|
282
|
-
//
|
|
283
|
-
//
|
|
284
|
-
//
|
|
285
|
-
//
|
|
279
|
+
// spec). A hotfix forks from a release tag and lands by release + push + carry,
|
|
280
|
+
// not fast-forward; `hotfix land` runs those steps itself, in that order.
|
|
281
|
+
//
|
|
282
|
+
// `releaseWith` is a command run IN THE HOTFIX WORKTREE that cuts the release —
|
|
283
|
+
// its version commit and its tag — and prints ONE JSON line on stdout:
|
|
284
|
+
// {"tag","version","baseTag","branch","versionCommit","pushed"}. skittership
|
|
285
|
+
// 2.1+ ships one: "node scripts/release-hotfix.cjs --json" (call node directly
|
|
286
|
+
// rather than through `pnpm run`, so no run banner reaches stdout; anything but
|
|
287
|
+
// the JSON line is a refusal). skitterspec never passes it `--push`, since it
|
|
288
|
+
// owns the push. skittership refuses a branch outside its `hotfix.branchPrefix`
|
|
289
|
+
// (default `hotfix/`) — the default `branch.pattern` already gives
|
|
290
|
+
// `hotfix/<slug>` — and refuses a package.json with a `postversion` script
|
|
291
|
+
// unless the command says `--allow-postversion`; add that yourself if you have
|
|
292
|
+
// one. Empty (the default) = the built-in tagger.
|
|
293
|
+
//
|
|
294
|
+
// `bump` is the built-in tagger's strategy: "patch" (v33.16.4 -> v33.16.5) or
|
|
295
|
+
// "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...). Under
|
|
296
|
+
// either, a base that is already a hotfix tag continues its line
|
|
297
|
+
// (v36.2.3-hotfix.4 -> v36.2.3-hotfix.5), so "patch" never takes a number the
|
|
298
|
+
// mainline owns. When the patch tag already exists, the refusal names the
|
|
299
|
+
// free hotfix tag that "hotfix-suffix" would cut. Any other value is refused
|
|
300
|
+
// when `hotfix land` runs. Tags order X.Y.Z-rc.N < X.Y.Z < X.Y.Z-hotfix.N <
|
|
301
|
+
// X.Y.(Z+1), the same as skittership.
|
|
302
|
+
//
|
|
303
|
+
// `cherryPickMain` carries the fix onto the base branch for the next release
|
|
304
|
+
// (default true) — its commits minus the version commit and minus anything the
|
|
305
|
+
// base already has. `targets` is an optional default list of extra base tags to
|
|
306
|
+
// also patch (test/demo lines); `--also <tag>` adds more at run time. Targets
|
|
307
|
+
// are TAG-ONLY: they get the built-in tagger, never `releaseWith`, and are not
|
|
308
|
+
// pushed. The prod release is pushed (branch, then tag, to origin) only on
|
|
309
|
+
// `hotfix land --push`; without it the land holds before the carry. The
|
|
310
|
+
// worktree stays until `spec-env hotfix finish`. Default: built-in patch tag,
|
|
311
|
+
// carry to main, no targets.
|
|
286
312
|
"hotfix": {
|
|
313
|
+
"releaseWith": "",
|
|
287
314
|
"bump": "patch",
|
|
288
315
|
"cherryPickMain": true,
|
|
289
316
|
"targets": []
|
|
@@ -85,7 +85,7 @@ function findEngine(projectDir) {
|
|
|
85
85
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
86
86
|
let at = projectDir
|
|
87
87
|
for (let i = 0; i < 6 && at; i++) {
|
|
88
|
-
for (const name of ['skitterspec', 'skitterspec-linear']) {
|
|
88
|
+
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
|
|
89
89
|
const candidate = path.join(at, 'node_modules', '.bin', name)
|
|
90
90
|
if (fs.existsSync(candidate)) return candidate
|
|
91
91
|
}
|
|
@@ -82,7 +82,7 @@ function findEngine(projectDir) {
|
|
|
82
82
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
83
83
|
let at = projectDir
|
|
84
84
|
for (let i = 0; i < 6 && at; i++) {
|
|
85
|
-
for (const name of ['skitterspec', 'skitterspec-linear']) {
|
|
85
|
+
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
|
|
86
86
|
const candidate = path.join(at, 'node_modules', '.bin', name)
|
|
87
87
|
if (fs.existsSync(candidate)) return candidate
|
|
88
88
|
}
|
|
@@ -190,8 +190,10 @@ the finished spec's own test-DB volume; `spec-env prune` additionally reaps
|
|
|
190
190
|
**orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
|
|
191
191
|
`/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one
|
|
192
192
|
exception to "fork from `main`": `/spec-hotfix` forks the worktree from a release
|
|
193
|
-
tag and `/spec-complete` lands it via `spec-env hotfix land` (
|
|
194
|
-
|
|
193
|
+
tag and `/spec-complete` lands it via `spec-env hotfix land` (release, push on
|
|
194
|
+
consent, carry to `main` without the version commit), not a fast-forward; its
|
|
195
|
+
worktree stays until the deploy is out and a second `/spec-complete` runs
|
|
196
|
+
`spec-env hotfix finish`. Isolation is **orthogonal to lifecycle status** and inactive
|
|
195
197
|
when `env.config.json` is absent — every skill then behaves as it does today.
|
|
196
198
|
|
|
197
199
|
**Live overlay (`/spec-live`, a command) — the light way to test a spec.** `/spec-connect`
|
|
@@ -17,6 +17,9 @@ description: Finish a spec — verify all phases are genuinely done, update prog
|
|
|
17
17
|
- Locate the spec folder under `specs/` (usually `specs/in-progress/`). Entry
|
|
18
18
|
point is its `00-overview.md`; phases are separate files (`01-<slug>.md`, `02-…`)
|
|
19
19
|
listed in its phase index (legacy specs may be a bare `<name>.md`).
|
|
20
|
+
- **A hotfix already in `specs/complete/` whose worktree still stands** is a
|
|
21
|
+
hotfix waiting on its deploy. That run is the teardown only: go straight to
|
|
22
|
+
step 7's hotfix paragraph, and do not re-verify, re-move or re-land it.
|
|
20
23
|
|
|
21
24
|
## 2. Double-check progress — don't rubber-stamp
|
|
22
25
|
|
|
@@ -180,8 +183,8 @@ about another spec followed from it. `Next` is one action for this spec, and
|
|
|
180
183
|
`/spec-list` is where the wider picture lives if they want it.
|
|
181
184
|
|
|
182
185
|
`Landed` says how, because the two ways differ: a fast-forward names the base
|
|
183
|
-
and the commit, a hotfix names the
|
|
184
|
-
a
|
|
186
|
+
and the commit, a hotfix names the release tag, whether it was pushed, and the
|
|
187
|
+
`main` carry — and a release tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
|
|
185
188
|
what was reclaimed, including any orphaned volumes swept, or that teardown was
|
|
186
189
|
declined and the worktree still stands.
|
|
187
190
|
|
|
@@ -196,34 +199,57 @@ commands you run differ but these steps do not)
|
|
|
196
199
|
before. When it applies, offer to land the finished branch so the work reaches its
|
|
197
200
|
destination in one flow. **How it lands depends on the spec type:**
|
|
198
201
|
|
|
199
|
-
### 6-hotfix. `Type: Hotfix` —
|
|
202
|
+
### 6-hotfix. `Type: Hotfix` — release, push, carry (not fast-forward)
|
|
200
203
|
|
|
201
204
|
A hotfix is built on an old release **tag**, so it can't fast-forward onto `main`.
|
|
202
|
-
|
|
205
|
+
The engine runs its landing itself — `hotfix land` releases, pushes and carries,
|
|
206
|
+
in that order, and stops at the first step that fails:
|
|
203
207
|
|
|
204
208
|
1. **Require a clean worktree.** Step 4 already committed the completion edits, so
|
|
205
209
|
this should pass. If the tree is *still* dirty, that's unrelated work — offer
|
|
206
|
-
`/commit` and **stop**.
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
On a
|
|
219
|
-
|
|
210
|
+
`/commit` and **stop**. The order matters beyond tidiness: a project's
|
|
211
|
+
`hotfix.releaseWith` (skittership's `release-hotfix.cjs`) refuses a dirty tree
|
|
212
|
+
and an already-tagged HEAD, so the release has to run **after** the §4 commit.
|
|
213
|
+
2. **Ask before pushing.** Pushing the tag is what starts the prod deploy, so it is
|
|
214
|
+
the operator's to say yes to — ask once, plainly, naming the tag-to-be and the
|
|
215
|
+
remote (`skitterspec spec-env hotfix land <name> --plan` says what will run).
|
|
216
|
+
3. **Land it.** On a yes:
|
|
217
|
+
|
|
218
|
+
```
|
|
219
|
+
skitterspec spec-env hotfix land <name> --push
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
On a no, run it **without** `--push`. Add `--also <tag>` for each extra release
|
|
223
|
+
line to patch (test/demo lines — tag-only, never through `releaseWith`).
|
|
224
|
+
It:
|
|
225
|
+
- **releases** the branch head — through `hotfix.releaseWith` when the project
|
|
226
|
+
set one (its version commit and tag; its one JSON line names the tag), else
|
|
227
|
+
the built-in tagger (`hotfix.bump`: `patch`, or `hotfix-suffix` for
|
|
228
|
+
`X.Y.Z-hotfix.N`). The release is recorded, so a re-run never cuts a second;
|
|
229
|
+
- **pushes** the branch, then the tag, to `origin` — only with `--push`. Without
|
|
230
|
+
it the run **holds** here, exit 0, printing both push commands; a re-run after
|
|
231
|
+
the operator pushes by hand finds the tag on the remote and carries on;
|
|
232
|
+
- **carries** the fix onto `main`: the branch's commits minus the version commit
|
|
233
|
+
and minus anything `main` already has, so the spec's completion commits arrive
|
|
234
|
+
and `main`'s version line does not move. In place when `main` is checked out
|
|
235
|
+
and clean, through a throwaway worktree when it is not checked out, and
|
|
236
|
+
**refused** — with the command to run later — when it is checked out and
|
|
237
|
+
dirty.
|
|
238
|
+
|
|
239
|
+
Relay its step lines. A **non-zero exit** is a refusal or a failure at a named
|
|
240
|
+
step — a refused release, a failed push, a conflicted carry (already aborted,
|
|
241
|
+
naming the commit). Relay it and **stop**; whatever was cut is recorded, so the
|
|
242
|
+
fix is to clear the cause and re-run the same command. On a **no-op** ("nothing
|
|
243
|
+
to land"), say so and continue.
|
|
244
|
+
4. **Run the after-land commands** when the run ends with a
|
|
220
245
|
`then, in the primary checkout (<path>), run:` section — exactly as step 3
|
|
221
|
-
of 6-feature/bug below says. `hotfix land` prints it only when
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
(step 7)
|
|
246
|
+
of 6-feature/bug below says. `hotfix land` prints it only when the carry moved
|
|
247
|
+
`main`, so a held, prod-only or already-carried land has none.
|
|
248
|
+
5. **Re-test on `main`** after the carry — it must be **green**.
|
|
249
|
+
6. **Report** — `Landed` names the release tag and whether it was **pushed**, and
|
|
250
|
+
what the carry did. A tag cut but not pushed is a `⚠️`, not a `✅`.
|
|
251
|
+
**Then stop: the worktree is kept** (step 7). The branch is what the next
|
|
252
|
+
`-hotfix.N` is cut from if this deploy fails, so it waits for the deploy.
|
|
227
253
|
|
|
228
254
|
### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
|
|
229
255
|
|
|
@@ -278,6 +304,21 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
|
|
|
278
304
|
|
|
279
305
|
## 7. Tear down the environment (opt-in, only if configured)
|
|
280
306
|
|
|
307
|
+
**A hotfix is torn down later, by `hotfix finish`.**
|
|
308
|
+
It is never torn down here on the run that landed it. Skip sub-steps 0–3 for a `Type: Hotfix` spec that step 6 just landed,
|
|
309
|
+
and say the worktree is kept until the deploy is confirmed. When the operator runs
|
|
310
|
+
`/spec-complete` **again** on that hotfix — it is already in `specs/complete/` and
|
|
311
|
+
already landed — this step is the whole run: `cd` to the primary checkout, then
|
|
312
|
+
|
|
313
|
+
```
|
|
314
|
+
skitterspec spec-env hotfix finish <name>
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
It tears down only when the tree is clean, a release tag is at HEAD and the branch
|
|
318
|
+
is on `origin` at HEAD, naming every check that fails; there is no `--force`.
|
|
319
|
+
Relay a refusal and stop. Report what it removed in `Worktree`.
|
|
320
|
+
|
|
321
|
+
|
|
281
322
|
**Only when `specs/.core/env.config.json` exists.** Reclaiming the environment is
|
|
282
323
|
what completing a spec *is*, so sub-steps 1–3 run **automatically — do not ask**.
|
|
283
324
|
Run the `spec-env` CLI directly (the old `/spec-env-down` skill is gone —
|
|
@@ -355,7 +396,8 @@ only ordering that survives.
|
|
|
355
396
|
|
|
356
397
|
3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
|
|
357
398
|
and execute the commands it prints, in order. After a landing — merged into
|
|
358
|
-
base for a **feature/bug
|
|
399
|
+
base for a **feature/bug** (a hotfix never reaches this sub-step; see the top
|
|
400
|
+
of step 7) —
|
|
359
401
|
teardown needs **no `--force`** and drops the branch with `git branch -D`,
|
|
360
402
|
which is safe precisely because the commits are already somewhere else. It
|
|
361
403
|
still respects the guards (won't destroy a dirty, or unpushed-and-unlanded,
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-hotfix
|
|
3
|
-
description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green, then land it by
|
|
3
|
+
description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green, then land it by cutting the release, pushing it on consent, and carrying the fix onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# /spec-hotfix — fix a released version,
|
|
6
|
+
# /spec-hotfix — fix a released version, release it, carry it back to main
|
|
7
7
|
|
|
8
8
|
> Stay silent while this runs — speak only to ask something you cannot answer
|
|
9
9
|
> yourself, or to report a failure at the moment it happens. Read
|
|
@@ -162,6 +162,9 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
|
|
|
162
162
|
usually names
|
|
163
163
|
the version they *saw* the bug on, which is not necessarily what is deployed,
|
|
164
164
|
and a hotfix forked from the wrong tag fails late.
|
|
165
|
+
**A hotfix tag is a valid base**: prod may be running `v36.4.0-hotfix.2`, and a
|
|
166
|
+
hotfix on it continues that line (`-hotfix.3` under `hotfix.bump:
|
|
167
|
+
"hotfix-suffix"` or skittership's release).
|
|
165
168
|
- **Verify the tag exists** before anything else:
|
|
166
169
|
`git rev-parse --verify <tag>^{commit}`. If it doesn't resolve, stop and ask.
|
|
167
170
|
|
|
@@ -242,8 +245,8 @@ and a step whose documented opening the repo will not perform is not a step. The
|
|
|
242
245
|
spec is written in the worktree at §5, on the branch it belongs to.
|
|
243
246
|
|
|
244
247
|
**§5 records the same tag you passed to `--from`**, on the spec's
|
|
245
|
-
`> **Base version:**` header. That is not bookkeeping: `/spec-complete`
|
|
246
|
-
|
|
248
|
+
`> **Base version:**` header. That is not bookkeeping: `/spec-complete` cuts the
|
|
249
|
+
release and carries the fix off the header, so a worktree forked from one ref and
|
|
247
250
|
a header naming another is this whole bug again with the halves swapped.
|
|
248
251
|
|
|
249
252
|
- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
|
|
@@ -336,9 +339,12 @@ place of the table when the spec touches no external surface.>
|
|
|
336
339
|
|
|
337
340
|
## Landing
|
|
338
341
|
|
|
339
|
-
- [ ]
|
|
340
|
-
and pushed
|
|
341
|
-
|
|
342
|
+
- [ ] Release cut at `/spec-complete` (`hotfix.releaseWith`, else the
|
|
343
|
+
`hotfix.bump` tag) and pushed — branch, then tag — on your say-so, which
|
|
344
|
+
triggers CI/CD.
|
|
345
|
+
- [ ] Fix carried onto `main` without the version commit (and tagged onto any
|
|
346
|
+
`--also` release lines).
|
|
347
|
+
- [ ] Deploy confirmed, then `/spec-complete` again to run `hotfix finish`.
|
|
342
348
|
|
|
343
349
|
## State log
|
|
344
350
|
|
|
@@ -649,10 +655,14 @@ prod is theirs to trigger. The spec stays in `in-progress`.
|
|
|
649
655
|
- **`/spec-live` is refused for a hotfix** — its branch is built on an old tag, so
|
|
650
656
|
hot-reloading it onto the running dev server could break the shared instance.
|
|
651
657
|
To test it, the user runs `/spec-connect` (its own isolated stack).
|
|
652
|
-
- `Next` points at **`/spec-complete`** to land it
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
658
|
+
- `Next` points at **`/spec-complete`** to land it. That cuts the configured
|
|
659
|
+
release — `hotfix.releaseWith` (e.g. skittership's
|
|
660
|
+
`node scripts/release-hotfix.cjs --json`) or the built-in tagger's `hotfix.bump`
|
|
661
|
+
tag — asks before pushing the branch and then the tag, and carries the fix onto
|
|
662
|
+
`main` without the version commit. The worktree stays until the deploy is
|
|
663
|
+
confirmed; a second `/spec-complete` then runs `spec-env hotfix finish`. Add
|
|
664
|
+
`--also <tag>` at completion to also tag other release lines (test/demo,
|
|
665
|
+
tag-only).
|
|
656
666
|
|
|
657
667
|
End with the block defined in `.claude/rules/spec-reports.md`. That file carries
|
|
658
668
|
the shape; this section carries only what is specific here.
|
|
@@ -230,7 +230,16 @@ the shape; this section carries only what is specific here.
|
|
|
230
230
|
- `⏸` — it refused: no config, an unvalidated state list, a bad argument.
|
|
231
231
|
Nothing was written.
|
|
232
232
|
|
|
233
|
-
**
|
|
233
|
+
**A branch-local bucket is the normal case, never the caveat.** `linked`
|
|
234
|
+
reads the checkout it runs in, and an in-flight spec's move to
|
|
235
|
+
`in-progress` lives on its own unlanded branch — so from the primary
|
|
236
|
+
checkout the spec still reads `backlog` while the tracker (pushed from
|
|
237
|
+
the worktree) is ahead. That is worktree mode working as designed:
|
|
238
|
+
report it `✅` with the fact in `Notes`. Spending `⚠️` on the normal
|
|
239
|
+
case is how the verdict stops meaning anything — the same argument
|
|
240
|
+
`spec-reports.md` makes for `Untouched`.
|
|
241
|
+
|
|
242
|
+
**Fields:** `Tracker` · `Notes` · `Follow-ups` · `Next`
|
|
234
243
|
|
|
235
244
|
`Tracker` says what changed in Linear **and that the repo is unchanged** — it is
|
|
236
245
|
the source of truth either way, and a report that omits the second half reads as
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "18.
|
|
3
|
+
"version": "18.1.1",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|