@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.
Files changed (50) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +36 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/spec-complete/SKILL.md +67 -25
  7. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  8. package/assets/skills/spec-sync/SKILL.md +10 -1
  9. package/package.json +1 -1
  10. package/src/cli.js +289 -34
  11. package/src/env/config.js +14 -2
  12. package/src/env/hotfix.js +288 -16
  13. package/src/env/hotfixland.js +302 -0
  14. package/src/env/resolve.js +22 -8
  15. package/src/init.js +36 -4
  16. package/src/vendor/linear/api.js +43 -56
  17. package/src/vendor/linear/cli-sanitise.js +2 -2
  18. package/src/vendor/linear/cli-sync.js +87 -390
  19. package/src/vendor/linear/config.js +46 -171
  20. package/src/vendor/linear/credentials.js +40 -370
  21. package/src/vendor/linear/dialect.js +177 -0
  22. package/src/vendor/linear/doctor.js +7 -15
  23. package/src/vendor/linear/identity.js +20 -70
  24. package/src/vendor/linear/released.js +4 -222
  25. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  26. package/src/vendor/provider-kit/index.js +41 -0
  27. package/src/vendor/provider-kit/src/adapter.js +23 -0
  28. package/src/vendor/provider-kit/src/apply.js +197 -0
  29. package/src/vendor/provider-kit/src/args.js +68 -0
  30. package/src/vendor/provider-kit/src/config.js +198 -0
  31. package/src/vendor/provider-kit/src/credentials.js +404 -0
  32. package/src/vendor/provider-kit/src/doctor.js +35 -0
  33. package/src/vendor/provider-kit/src/http.js +44 -0
  34. package/src/vendor/provider-kit/src/identity.js +93 -0
  35. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  36. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  37. package/src/vendor/provider-kit/src/prompt.js +50 -0
  38. package/src/vendor/provider-kit/src/released.js +226 -0
  39. package/src/vendor/provider-kit/src/specs.js +166 -0
  40. package/src/vendor/provider-kit/src/transport.js +22 -0
  41. package/src/vendor/sync-core/index.js +22 -5
  42. package/src/vendor/sync-core/src/compare.js +14 -12
  43. package/src/vendor/sync-core/src/dialect.js +51 -0
  44. package/src/vendor/sync-core/src/fields.js +36 -0
  45. package/src/vendor/sync-core/src/legacy.js +19 -9
  46. package/src/vendor/sync-core/src/normalize.js +30 -158
  47. package/src/vendor/sync-core/src/push.js +1 -1
  48. package/src/vendor/sync-core/src/retarget.js +21 -17
  49. package/src/vendor/sync-core/src/verify.js +24 -45
  50. 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 the cherry-pick onto the base branch, and not at all when
157
- // `hotfix.cherryPickMain` is false, since the base gained nothing.
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 tag + cherry-pick, not
280
- // fast-forward. `bump` is the version-bump strategy for the new deploy tag (only
281
- // "patch" today: v33.16.4 -> v33.16.5). `cherryPickMain` also cherry-picks the
282
- // fix onto the base branch for the next release (default true). `targets` is an
283
- // optional default list of extra base tags to also patch (test/demo lines);
284
- // `--also <tag>` adds more at run time. Nothing is ever pushed — you push the
285
- // deploy tag to trigger CI/CD. Default: patch, main, none.
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` (tag + cherry-pick),
194
- not a fast-forward. Isolation is **orthogonal to lifecycle status** and inactive
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 deploy tag and the `main` cherry-pick — and
184
- a deploy tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
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` — tag + cherry-pick (not fast-forward)
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
- Use the hotfix landing instead of the integrate steps below:
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
- 2. **Plan + execute.** Run `skitterspec spec-env hotfix land <name>` — add
208
- `--also <tag>` for each extra release line to patch (test/demo on their own
209
- versions). Run the printed commands **in order**. It:
210
- - tags the hotfix branch with the **patch-bumped base tag** (the deploy tag) —
211
- **created locally; you push it** (`git push origin <tag>`) to trigger CI/CD;
212
- - for each `--also` target, cherry-picks the fix onto a throwaway worktree at
213
- that tag and re-tags it;
214
- - cherry-picks the fix onto `main` for the next release.
215
- On a **cherry-pick conflict** (non-zero exit), run `git -C <checkout>
216
- cherry-pick --abort` there, relay the conflict, and **stop** — don't offer
217
- teardown.
218
- On a **no-op** ("nothing to land"), say so and continue.
219
- 3. **Run the after-land commands** when the plan ends with a
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 it
222
- cherry-picks onto `main`, so a prod-only land or a no-op has none.
223
- 4. **Re-test on `main`** after the cherry-pick — it must be **green**.
224
- 5. **Report** the deploy tag(s) and the `main` cherry-pick. It **never pushes** —
225
- remind the user to `git push origin <deploy-tag>` to deploy. Then teardown
226
- (step 7) applies: a tagged hotfix branch tears down with **no `--force`**.
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**, captured by the deploy tag for a **hotfix** —
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 tagging a new patch for CI/CD and cherry-picking 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.
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, tag it, cherry-pick back to main
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` tags the
246
- new patch and cherry-picks off the header, so a worktree forked from one ref and
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
- - [ ] Deploy tag (patch bump of the base version) created at `/spec-complete`
340
- and pushed **by you** to trigger CI/CD.
341
- - [ ] Fix cherry-picked onto `main` (and any `--also` release lines).
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: it patch-bumps the base tag,
653
- tags the hotfix branch **locally** (you push it to deploy), and cherry-picks the
654
- fix onto `main`. Add `--also <tag>` at completion to also patch other release
655
- lines (test/demo on their own versions).
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
- **Fields:** `Tracker` · `Follow-ups` · `Next`
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.0.1",
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",