@skitterbyte/skitterspec-linear 19.3.0 → 19.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/env.config.json.example +1 -0
  3. package/assets/core/env.config.md +90 -6
  4. package/assets/core/linear.config.json.example +2 -2
  5. package/assets/core/linear.config.md +49 -16
  6. package/assets/hooks/main-guard.cjs +18 -2
  7. package/assets/hooks/review-gate.cjs +19 -2
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +81 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +55 -2
  12. package/assets/skills/spec-bug/SKILL.md +36 -3
  13. package/assets/skills/spec-cancel/SKILL.md +37 -0
  14. package/assets/skills/spec-claim/SKILL.md +41 -2
  15. package/assets/skills/spec-complete/SKILL.md +115 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +51 -4
  17. package/assets/skills/spec-incident/SKILL.md +22 -0
  18. package/assets/skills/spec-linear-setup/SKILL.md +23 -1
  19. package/assets/skills/spec-next/SKILL.md +12 -5
  20. package/assets/skills/spec-push/SKILL.md +22 -0
  21. package/assets/skills/spec-review/SKILL.md +34 -0
  22. package/assets/skills/spec-start/SKILL.md +50 -3
  23. package/assets/skills/spec-status/SKILL.md +18 -3
  24. package/assets/skills/spec-sync/SKILL.md +1 -0
  25. package/assets/skills/spec-to-main/SKILL.md +47 -1
  26. package/package.json +1 -1
  27. package/src/cli.js +1091 -39
  28. package/src/env/base.js +104 -0
  29. package/src/env/config.js +75 -3
  30. package/src/env/disposition.js +62 -0
  31. package/src/env/handoff.js +80 -0
  32. package/src/env/host.js +262 -0
  33. package/src/env/hotfix.js +225 -0
  34. package/src/env/hotfixland.js +103 -9
  35. package/src/env/inflight.js +95 -0
  36. package/src/env/integrate.js +130 -4
  37. package/src/env/mainguard.js +6 -0
  38. package/src/env/phases.js +28 -0
  39. package/src/env/provision.js +18 -6
  40. package/src/env/resolve.js +108 -9
  41. package/src/env/serve.js +6 -1
  42. package/src/env/specstate.js +101 -0
  43. package/src/env/teardown.js +42 -0
  44. package/src/vendor/linear/cli-sync.js +55 -6
  45. package/src/vendor/linear/config.js +27 -21
  46. package/src/vendor/linear/doctor.js +2 -0
  47. package/src/vendor/provider-kit/index.js +4 -0
  48. package/src/vendor/provider-kit/src/apply.js +49 -4
  49. package/src/vendor/provider-kit/src/assignment.js +78 -1
  50. package/src/vendor/provider-kit/src/config.js +34 -1
  51. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  52. package/src/vendor/provider-kit/src/released.js +14 -1
  53. package/src/vendor/provider-kit/src/specs.js +4 -2
  54. package/src/vendor/provider-kit/src/splice.js +64 -0
  55. package/src/vendor/provider-kit/src/status.js +137 -0
  56. package/src/vendor/sync-core/index.js +14 -1
  57. package/src/vendor/sync-core/src/compare.js +17 -5
  58. package/src/vendor/sync-core/src/normalize.js +50 -7
  59. package/src/vendor/sync-core/src/push.js +26 -2
  60. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -157,7 +157,9 @@ not write the spec until this is resolved.
157
157
  asking. Verify endpoints/models/files actually exist before relying on them.
158
158
  - Cover, at minimum, the areas that apply:
159
159
  1. **Problem & why** — what's broken/missing, who feels it, why now.
160
- 2. **Scope & non-goals** — explicit out-of-scope items.
160
+ 2. **Scope & non-goals** — explicit out-of-scope items, and the
161
+ **acceptance criteria**: what someone checks, without reading the code,
162
+ to call the work done (they become `## Acceptance criteria`).
161
163
  3. **Affected areas** — concrete files/modules/packages this touches.
162
164
  4. **Proposed solution shape** — the chosen approach and the alternatives
163
165
  rejected, with the reason (this becomes "Decisions").
@@ -330,6 +332,28 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
330
332
  a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
331
333
  uses `bug-`, the incident one `incident-`).
332
334
 
335
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
336
+ Run `skitterspec spec-sync ownership --json` once and read both values:
337
+
338
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
339
+ this skill **writes no `> **Status:**` header and appends no State log row**,
340
+ wherever its steps below say to. A spec this skill creates gets neither: its
341
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
342
+ has stamped the url, and its body has no `## State log` section. Readiness is
343
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
344
+ empty — so nothing is lost with the header.
345
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
346
+ **writes no `> **Developer:**` line** either.
347
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
348
+ — is cannot-tell, and the steps below run exactly as written.
349
+
350
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
351
+ the code, not a planning status), the phase files and index, and the Changelog.
352
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
353
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
354
+ any of these lines keeps them untouched: they are history, and nothing rewrites
355
+ them.
356
+
333
357
  Use this template (keep it **as concise as possible** — no filler, no restating
334
358
  the codebase, link rather than duplicate):
335
359
 
@@ -354,10 +378,20 @@ the codebase, link rather than duplicate):
354
378
  > "none: not user-facing". An empty value or a bare
355
379
  > "none" is not a valid outcome — see Phase A item 10>
356
380
 
381
+ ## Summary
382
+
383
+ <1–3 sentences: what the work delivers, for someone who will never open the
384
+ spec — no phase breakdown, no implementation detail. With a ticketing provider
385
+ in summary mode this is what the ticket leads with.>
386
+
357
387
  ## Problem
358
388
 
359
389
  <2–6 sentences: what's wrong/missing and why it matters. No fluff.>
360
390
 
391
+ ## Acceptance criteria
392
+
393
+ - <an observable check, from Phase A item 2 — one per line>
394
+
361
395
  ## Decisions
362
396
 
363
397
  <Numbered, confirmed decisions from Phase A. Each: the choice + one-line why,
@@ -467,6 +501,11 @@ Rules for the spec body:
467
501
  - **Changelog** is mandatory and lives in the spec. Every later decision or
468
502
  course-correction gets a dated one-line entry. Convert relative dates to
469
503
  absolute.
504
+ - **`## Summary` and `## Acceptance criteria` are the ticket-facing pair.**
505
+ Write them for a reader on the board, not the one building it: the summary
506
+ says what the work delivers, each criterion is something a person can check.
507
+ A ticketing provider in summary mode projects exactly these (plus the
508
+ Impact table's surfaces, Gating and progress) and nothing else.
470
509
  - Keep it tight. If a section adds no information, delete it.
471
510
 
472
511
  ## Phase C — finish up
@@ -550,6 +589,18 @@ on the branch you are standing on — so a spec left on its own branch would be
550
589
  invisible to everyone, including the next `/spec` run. The commit goes on the
551
590
  branch and then the branch goes onto the base:
552
591
 
592
+ **Unless the project set `land.specDocs: "branch"`** — the lane for a base
593
+ branch nobody may push, where the spec document rides the feature branch and
594
+ lands with the work's PR. There both verdicts commit on the branch and
595
+ **skip the integrate below entirely**; `commit-start` carries into
596
+ `/spec-start` over the same worktree exactly as ever, and plain `commit` keeps
597
+ the branch AND the worktree, because they are now the only copy of the
598
+ document. Say the trade out loud in the report's `Notes`: the backlog is found
599
+ through the tracker listing (or `git branch`), not `ls specs/backlog/` on base
600
+ — and a later `/spec-cancel` of a never-started branch-mode spec deletes the
601
+ branch and worktree with the spec document dying with them, no PR ever having
602
+ existed. Under the default `"trunk"` everything below applies unchanged.
603
+
553
604
  ```
554
605
  skitterspec spec-env integrate <name>
555
606
  ```
@@ -671,7 +722,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
671
722
  behaves exactly as above. When present, link the spec you just wrote so status
672
723
  and discussion live in Linear while the repo stays the source of truth. A spec is
673
724
  a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
674
- its description as a read-only checklist.
725
+ its description as a read-only checklist. That is the `spec` description mode;
726
+ under `summary` (a new config's default) the issue and each sub-issue carry
727
+ a short block instead, and the phase's tasks stay in git.
675
728
 
676
729
  **Linking is just the first push**, so it runs the same engine path `/spec-push`
677
730
  does — you never create the issue by hand:
@@ -291,6 +291,28 @@ split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
291
291
  `00-overview.md`, exactly like a feature spec. It starts in `in-progress`
292
292
  because work is already underway. Keep it lean:
293
293
 
294
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
295
+ Run `skitterspec spec-sync ownership --json` once and read both values:
296
+
297
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
298
+ this skill **writes no `> **Status:**` header and appends no State log row**,
299
+ wherever its steps below say to. A spec this skill creates gets neither: its
300
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
301
+ has stamped the url, and its body has no `## State log` section. Readiness is
302
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
303
+ empty — so nothing is lost with the header.
304
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
305
+ **writes no `> **Developer:**` line** either.
306
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
307
+ — is cannot-tell, and the steps below run exactly as written.
308
+
309
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
310
+ the code, not a planning status), the phase files and index, and the Changelog.
311
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
312
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
313
+ any of these lines keeps them untouched: they are history, and nothing rewrites
314
+ them.
315
+
294
316
  ```markdown
295
317
  # Bug: <short title>
296
318
 
@@ -369,7 +391,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
369
391
  behaves exactly as above. When present, link the spec you just wrote so status
370
392
  and discussion live in Linear while the repo stays the source of truth. A spec is
371
393
  a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
372
- its description as a read-only checklist.
394
+ its description as a read-only checklist. That is the `spec` description mode;
395
+ under `summary` (a new config's default) the issue and each sub-issue carry
396
+ a short block instead, and the phase's tasks stay in git.
373
397
 
374
398
  **Linking is just the first push**, so it runs the same engine path `/spec-push`
375
399
  does — you never create the issue by hand:
@@ -450,6 +474,12 @@ is a cosmetic gap that `/spec-claim` closes later.
450
474
  skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
451
475
  ```
452
476
 
477
+ **Where `spec-sync ownership` reports `assignee: pull`**, the issue is the
478
+ record and the spec file is not: add `--if-unassigned`. It writes Linear
479
+ directly, claims the issue only when nobody holds it, and stamps nothing —
480
+ so step 4 has no header to leave alone, since under `pull` no `Developer:`
481
+ line was written.
482
+
453
483
  4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
454
484
  seam already set it, and this seam must not overwrite it with the tracker's
455
485
  display name.
@@ -471,12 +501,15 @@ is a cosmetic gap that `/spec-claim` closes later.
471
501
 
472
502
  **Nothing is pushed here.** `assign` writes the repo only, and the refresh these
473
503
  skills already run sends it. Assignment is an ordinary field of the projection,
474
- not a side errand with its own network call.
504
+ not a side errand with its own network call. Under `pull` the
505
+ `assign` call is itself the write, so there is nothing for a push to carry.
475
506
 
476
507
  **There is no unassign step anywhere.** The projection derives the assignee from
477
508
  the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
478
509
  issue through the push they already make. The stamp deliberately stays in the
479
- file: who actioned the work outlives who is currently holding it.
510
+ file: who actioned the work outlives who is currently holding it. Under `pull`
511
+ the projection carries no assignee at all, so finishing a spec leaves it on
512
+ the issue: the board keeps who did the work.
480
513
 
481
514
  ### Picking the Linear Project
482
515
 
@@ -37,6 +37,28 @@ it verbatim/condensed for the header.
37
37
 
38
38
  ## 4. Stamp the spec
39
39
 
40
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
41
+ Run `skitterspec spec-sync ownership --json` once and read both values:
42
+
43
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
44
+ this skill **writes no `> **Status:**` header and appends no State log row**,
45
+ wherever its steps below say to. A spec this skill creates gets neither: its
46
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
47
+ has stamped the url, and its body has no `## State log` section. Readiness is
48
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
49
+ empty — so nothing is lost with the header.
50
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
51
+ **writes no `> **Developer:**` line** either.
52
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
53
+ — is cannot-tell, and the steps below run exactly as written.
54
+
55
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
56
+ the code, not a planning status), the phase files and index, and the Changelog.
57
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
58
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
59
+ any of these lines keeps them untouched: they are history, and nothing rewrites
60
+ them.
61
+
40
62
  Update the **Status** header in the entry point so the reason is visible at the
41
63
  top:
42
64
 
@@ -74,6 +96,10 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
74
96
  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
75
97
  the repo regardless; the mirror is disposable and the next push repairs it.
76
98
  Do not roll anything back, and do not stop to ask.
99
+ - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
100
+ a PR, and a ready PR is not a merged one — so skip it on run 1, even where
101
+ the `branch` lane committed the move to ride the PR, and run it on run 2 once
102
+ the host has merged. The tracker's Done lands when the work does.
77
103
  - **Say what happened** in the skill's report: mirror updated, skipped as
78
104
  unlinked, or failed with the reason.
79
105
  - **There is no unassign step, and that is not an omission.** Where the repo owns
@@ -82,6 +108,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
82
108
  releases the issue, and the push above carries it like any other field. The
83
109
  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
84
110
  they record who actioned the work, which outlives who is holding it.
111
+ Under `assignee: pull` the projection carries no assignee at all, so the
112
+ issue keeps it: the board records who did the work.
85
113
 
86
114
  ### Why it sits here
87
115
 
@@ -254,6 +282,15 @@ only ordering that survives.
254
282
  copy of abandoned work. Seeing no such section here is the expected case, not
255
283
  a fault — and if the user wants the remote branch gone anyway, that is their
256
284
  call to make explicitly, not something to tidy away on their behalf.
285
+
286
+ **In PR mode the same confirm-first section may carry the PR abandon**
287
+ (`gh pr close` / `az repos pr update --status abandoned`): a cancelled spec
288
+ must not leave a live PR behind — it is noise with a merge button on it.
289
+ The teardown of an open-PR spec is refused unforced (the PR is named), so
290
+ this line appears on the forced run the refusal led to; ask before running
291
+ it like the delete above, and run the abandon **before** any remote branch
292
+ delete — closing the PR first is what stops the host complaining about a
293
+ deleted source branch.
257
294
  4. `skitterspec spec-env prune` — reap orphaned test-DB volumes that belong to no
258
295
  live spec (leftovers from declined/aborted teardowns or manual worktree
259
296
  removal). Show the orphan list and, **only on the user's confirmation**, run
@@ -28,6 +28,27 @@ thing enforcing it for long enough that the engine's own success line —
28
28
  `next: push it, so Linear agrees` — was printed over a push that would drop the
29
29
  field. Prose in one skill is not a guard; it is a guard's documentation.
30
30
 
31
+ ## Under `pull`, the issue is the record
32
+
33
+ Ask once: `skitterspec spec-sync ownership --json`. Where `assignee` is
34
+ **`pull`**, Linear owns who is building the spec, and the repo keeps no copy — so
35
+ the steps below change in four places, and only these:
36
+
37
+ - **`assign` writes Linear directly and stamps nothing.** There is no repo record
38
+ to change and no push to follow: §4 does not run, because the `assign` call
39
+ *was* the write.
40
+ - **Take checks Linear, not the file.** Run `assign <spec> --to <id> --if-unassigned`
41
+ first. If it reports the issue is already assigned to someone else, that is
42
+ step 2's colleague: name them, confirm, then run it again without the flag.
43
+ - **No `> **Developer:**` line is written**, by any mode. The tracker names the
44
+ person; a header would be the copy `pull` exists to remove.
45
+ - **§3 is skipped.** The issue's own history records the move, and a
46
+ Changelog line saying who holds it would be that copy again.
47
+
48
+ Everything else stands: the opt-in check, resolving a person through a search
49
+ before a hand-over, and the report. Under `push` (or with ownership unknown)
50
+ nothing in this section applies.
51
+
31
52
  ## 1. Identify the target spec
32
53
 
33
54
  The argument, else the spec in flight for this session, else ask. Unlike
@@ -78,8 +99,26 @@ now".
78
99
  stranger and nothing downstream would notice.
79
100
  2. On several matches, show them and let the user pick. On none, say so and
80
101
  stop — do not fall back to the raw argument as an id.
81
- 3. Stamp it with the resolved id and display name.
82
- 4. Set `> **Developer:**` to that person's **Linear display name**.
102
+ 3. **Make the work reachable before you hand it over.** Run
103
+ `skitterspec spec-env handoff <spec> --json`. A spec's branch lives in a
104
+ local worktree, so without this the issue would name a new owner for code
105
+ only you can see.
106
+ - **`blocked`** — relay the reason. Where it carries an `offer` (uncommitted
107
+ work: `/commit`), offer it once as `offered-unblocks.md` says, run it on a
108
+ yes, then run `handoff` again. With no offer, stop here: nothing is assigned.
109
+ - **`commands`** non-empty — the branch is not published at HEAD. Ask once,
110
+ naming the target: *"push `<branch>` to `<remote>` so <name> can pick it
111
+ up?"* Run it on a yes. On a no, stop: a hand-over the new owner cannot
112
+ reach is not a hand-over, so nothing is assigned.
113
+ - Then post the note it wrote onto the issue:
114
+ `skitterspec spec-sync comment <spec> --file <notePath>`. It names the
115
+ branch, the sha and the phases done, and a comment is the surface no later
116
+ push replaces. A failed post is said and does not stop the hand-over.
117
+
118
+ The new owner's `/spec-start <spec>` resumes from that branch rather than
119
+ forking a fresh one (`spec-env up` sees it on the remote).
120
+ 4. Stamp it with the resolved id and display name.
121
+ 5. Set `> **Developer:**` to that person's **Linear display name**.
83
122
 
84
123
  This is the **one** place the tracker's name reaches the header, and the
85
124
  exception is the whole reason it exists: there is no `git config user.name`
@@ -102,6 +102,29 @@ feature was designed not to disturb.
102
102
 
103
103
  - Tick all completed tasks in the phase files; flip every finished phase-file
104
104
  heading **and** every row in the `00-overview.md` phase index to `✅`.
105
+
106
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
107
+ Run `skitterspec spec-sync ownership --json` once and read both values:
108
+
109
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
110
+ this skill **writes no `> **Status:**` header and appends no State log row**,
111
+ wherever its steps below say to. A spec this skill creates gets neither: its
112
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
113
+ has stamped the url, and its body has no `## State log` section. Readiness is
114
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
115
+ empty — so nothing is lost with the header.
116
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
117
+ **writes no `> **Developer:**` line** either.
118
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
119
+ — is cannot-tell, and the steps below run exactly as written.
120
+
121
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
122
+ the code, not a planning status), the phase files and index, and the Changelog.
123
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
124
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
125
+ any of these lines keeps them untouched: they are history, and nothing rewrites
126
+ them.
127
+
105
128
  - Set the **Status** header in the entry point:
106
129
  `> **Status:** Complete (<YYYY-MM-DD>)`.
107
130
  - Append a **State log** row:
@@ -135,6 +158,10 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
135
158
  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
136
159
  the repo regardless; the mirror is disposable and the next push repairs it.
137
160
  Do not roll anything back, and do not stop to ask.
161
+ - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
162
+ a PR, and a ready PR is not a merged one — so skip it on run 1, even where
163
+ the `branch` lane committed the move to ride the PR, and run it on run 2 once
164
+ the host has merged. The tracker's Done lands when the work does.
138
165
  - **Say what happened** in the skill's report: mirror updated, skipped as
139
166
  unlinked, or failed with the reason.
140
167
  - **There is no unassign step, and that is not an omission.** Where the repo owns
@@ -143,6 +170,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
143
170
  releases the issue, and the push above carries it like any other field. The
144
171
  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
145
172
  they record who actioned the work, which outlives who is holding it.
173
+ Under `assignee: pull` the projection carries no assignee at all, so the
174
+ issue keeps it: the board records who did the work.
146
175
 
147
176
  ### Why it sits here
148
177
 
@@ -290,6 +319,27 @@ in that order, and stops at the first step that fails:
290
319
  **Then stop: the worktree is kept** (step 7). The branch is what the next
291
320
  `-hotfix.N` is cut from if this deploy fails, so it waits for the deploy.
292
321
 
322
+ **A branch-based hotfix** (`> **Base version:** <branch>@<sha>`, from
323
+ `hotfix.releaseBranch`) runs the same command and the same consent ask — the
324
+ engine picks the path from the header. What differs is what it does:
325
+
326
+ - it **rebases** onto `<remote>/<branch>` and **lands on the release branch** by
327
+ `land.strategy`: under `ff` the push of the hotfix onto that branch *is* the
328
+ land (so the consent ask names the release branch, not only a tag); under `pr`
329
+ it pushes the hotfix branch and opens a **ready** PR, then holds with
330
+ `the PR into <branch> is open` — re-run the same command once it merges;
331
+ - the **tag** is optional (`hotfix.tag`): cut and pushed after the land, or not
332
+ at all;
333
+ - the **carry** goes to the resolved base — the current rc under
334
+ `baseBranchPattern` — directly under `ff`, through a `carry/<slug>` branch and
335
+ its own ready PR under `pr`.
336
+
337
+ `Landed` then names the release branch, how it landed (fast-forward, or the PR
338
+ and whether it merged), the tag if one was cut, and the carry. A PR still
339
+ waiting on its merge is a `⚠️` — the land is not done until the host says so.
340
+ `spec-env hotfix finish` tears it down once both the land and the carry are
341
+ confirmed, naming every check that is not.
342
+
293
343
  ### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
294
344
 
295
345
  Land the finished branch on the base branch so the work reaches `main` (or your
@@ -325,6 +375,19 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
325
375
  `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
326
376
  to the user; do not tear anything down.
327
377
  On a **no-op** ("already landed"), just say so and continue.
378
+
379
+ **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
380
+ can carry two more things, and both are the engine's to say:
381
+ - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
382
+ when the primary checkout still has an older release candidate out — run it
383
+ in order with the rest;
384
+ - a `retarget: forked from <old> · landing onto <new>` line, when the rc
385
+ rolled while this spec was in flight. It is the land working, not a fault:
386
+ relay it verbatim in the `Landed` row so the reader sees where the work went.
387
+
388
+ A refusal naming `no branch matches <pattern>` means no release candidate is
389
+ visible — usually not fetched. Relay it, stop with `⏸`, and name
390
+ `skitterspec spec-env base` (it fetches and lists) as the next step.
328
391
  3. **Run the after-land commands.** Where the plan ends with a
329
392
  `then, in the primary checkout (<path>), run:` section — the project's
330
393
  `afterLand`, such as a data migration — run those commands in that
@@ -344,6 +407,58 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
344
407
  5. **Report** the landing (base branch, fast-forward result). It **never pushes** —
345
408
  mention the user can `git push` the base branch themselves.
346
409
 
410
+ ### 6-pr. PR mode (`land.strategy: "pr"`) — dispose, push, ready; finish after the merge
411
+
412
+ Completion is **two runs** here, the `hotfix land`/`finish` shape: the merge is
413
+ the host's act and may be days away, so the run that readies the PR cannot also
414
+ finalise. Which run this is, the engine says: `spec-env integrate <name>`
415
+ printing a `(pr)` plan is run 1; printing
416
+ `already landed … — finish what the merge deferred` is run 2.
417
+
418
+ **Run 1 — the last control point.** Once the PR is ready, anyone can merge from
419
+ the host UI and the tracker's automations act — so everything that needs a
420
+ person happens before the ready, in this order:
421
+
422
+ 1. **Disposition pass — mandatory, before anything is pushed.** Run
423
+ `skitterspec spec-env disposition <name> --json`. For every unticked task,
424
+ non-✅ phase and surfaced follow-up it lists, the user disposes it:
425
+ **tick** (it was done — tick it, naming the evidence) · **spin off** (a
426
+ follow-on ticket minted now, linked to this one — offer `/spec` or the
427
+ provider's mint) · **drop** (a dated Changelog line with the reason, the
428
+ `none: <reason>` grammar). Batch the asking; never decide for them, and
429
+ never auto-create. **Refuse to ready the PR while anything is undisposed**
430
+ — you asked the enumeration, so it cannot also be fine. `clean` proceeds
431
+ with nothing asked.
432
+ 2. **Consent, naming the target.** Ask once, plainly:
433
+ *"push `<branch>` and open the PR into `<base>` on `<remote>`, ready for
434
+ merge?"* — the base branch is named so a spec that outlived a release roll
435
+ is caught by the person reading a stale rc name. On a no, stop with the
436
+ held commands relayed.
437
+ 3. **Run the plan.** `skitterspec spec-env integrate <name> --push` and run
438
+ what it prints: fetch, rebase onto `<remote>/<base>`, the push, and the PR
439
+ create — or, where a draft already exists, the flip-to-ready. A rebase
440
+ conflict aborts and stops exactly as 6-feature/bug step 2.
441
+ 4. **Defer the finalise.** §4's bucket move follows the spec documents'
442
+ `land.specDocs` lane: under `trunk` leave the spec in `specs/in-progress/`
443
+ — run 2 moves it on base after the merge; under `branch` commit the move on
444
+ the branch *before* step 3 so it rides the PR. Either way
445
+ **the tracker's Done waits for run 2**: a ready PR is not a merged one.
446
+ 5. **Stop, keeping the worktree.** Report
447
+ `Landed: PR #N opened — finish after merge` (or `ready`), spec
448
+ `In Progress`, worktree standing. No afterLand runs — the plan deferred it
449
+ — and no teardown. The merge is what un-blocks run 2; nothing here waits on
450
+ it.
451
+
452
+ **Run 2 — after the host merges.** `integrate` recognises the landed branch
453
+ (ancestry or the host's answer) and prints the finish: catch local base up and
454
+ the deferred `afterLand` with the land's own range. Run those, then do what run
455
+ 1 deferred — the §4 move (trunk lane) with its State log row and commit, the
456
+ §5 report — then **§7 teardown runs as normal**:
457
+ a host-merged branch counts as landed (squash and rebase
458
+ merges included), and a host that auto-deleted the branch makes the remote
459
+ delete an already-gone no-op, never a failure. Re-test on base before calling
460
+ it done, exactly as 6-feature/bug step 4.
461
+
347
462
  ## 7. Tear down the environment (opt-in, only if configured)
348
463
 
349
464
  **A hotfix is torn down later, by `hotfix finish`.**
@@ -148,6 +148,16 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
148
148
 
149
149
  ## 1. Establish the base version (the tag)
150
150
 
151
+ **A release BRANCH instead of a tag.** Where `env.config.json` sets
152
+ `hotfix.releaseBranch` (e.g. `"master"` — a team whose prod is whatever that
153
+ branch holds), there is **no tag to ask for**: skip the questions below and run
154
+ §3's `up` **without `--from`**. The engine fetches, forks from the remote's head
155
+ of that branch, and prints two lines — `fork:` naming the commit, and
156
+ `record: > **Base version:** <branch>@<sha>` — and §5 copies that `record:`
157
+ value into the header **verbatim**. Say which commit it forked from in one line;
158
+ that is the version the fix is built on. The rest of this section is the tag
159
+ flow, unchanged.
160
+
151
161
  - **Read the arguments.** `/spec-hotfix <tag> <name>` (e.g.
152
162
  `/spec-hotfix v33.16.4 login-crash`). An argument shaped like an issue
153
163
  reference — letters, a hyphen, digits (`SKI-123`) —
@@ -265,6 +275,10 @@ installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
265
275
  and a step whose documented opening the repo will not perform is not a step. The
266
276
  spec is written in the worktree at §5, on the branch it belongs to.
267
277
 
278
+ **Branch-based (`hotfix.releaseBranch`):** run the same command **without**
279
+ `--from` — the engine picks the release branch's head and prints the
280
+ `record:` line §5 copies. An explicit `--from` still wins over it.
281
+
268
282
  **§5 records the same tag you passed to `--from`**, on the spec's
269
283
  `> **Base version:**` header. That is not bookkeeping: `/spec-complete` cuts the
270
284
  release and carries the fix off the header, so a worktree forked from one ref and
@@ -303,6 +317,28 @@ you there, so create the folder and write it here. A hotfix
303
317
  is usually a single-pass fix, so the `## Fix` block can live directly in
304
318
  `00-overview.md`. Keep it lean:
305
319
 
320
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
321
+ Run `skitterspec spec-sync ownership --json` once and read both values:
322
+
323
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
324
+ this skill **writes no `> **Status:**` header and appends no State log row**,
325
+ wherever its steps below say to. A spec this skill creates gets neither: its
326
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
327
+ has stamped the url, and its body has no `## State log` section. Readiness is
328
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
329
+ empty — so nothing is lost with the header.
330
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
331
+ **writes no `> **Developer:**` line** either.
332
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
333
+ — is cannot-tell, and the steps below run exactly as written.
334
+
335
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
336
+ the code, not a planning status), the phase files and index, and the Changelog.
337
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
338
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
339
+ any of these lines keeps them untouched: they are history, and nothing rewrites
340
+ them.
341
+
306
342
  ```markdown
307
343
  # Hotfix: <short title>
308
344
 
@@ -311,7 +347,7 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
311
347
  > **Status:** In Progress — fixing (red test added)
312
348
  > **Author:** <git user.name — who reported/captured it>
313
349
  > **Developer:** <git user.name — you, since you're fixing it now>
314
- > **Base version:** <tag prod is running, e.g. v33.16.4>
350
+ > **Base version:** <tag prod is running, e.g. v33.16.4 — or, branch-based, the `record:` value `up` printed, e.g. master@1a2b3c4d5e6f>
315
351
  > **Raised:** <YYYY-MM-DD (today)>
316
352
  > **Area:** <files/modules>
317
353
  > **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
@@ -390,7 +426,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
390
426
  behaves exactly as above. When present, link the spec you just wrote so status
391
427
  and discussion live in Linear while the repo stays the source of truth. A spec is
392
428
  a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
393
- its description as a read-only checklist.
429
+ its description as a read-only checklist. That is the `spec` description mode;
430
+ under `summary` (a new config's default) the issue and each sub-issue carry
431
+ a short block instead, and the phase's tasks stay in git.
394
432
 
395
433
  **Linking is just the first push**, so it runs the same engine path `/spec-push`
396
434
  does — you never create the issue by hand:
@@ -471,6 +509,12 @@ is a cosmetic gap that `/spec-claim` closes later.
471
509
  skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
472
510
  ```
473
511
 
512
+ **Where `spec-sync ownership` reports `assignee: pull`**, the issue is the
513
+ record and the spec file is not: add `--if-unassigned`. It writes Linear
514
+ directly, claims the issue only when nobody holds it, and stamps nothing —
515
+ so step 4 has no header to leave alone, since under `pull` no `Developer:`
516
+ line was written.
517
+
474
518
  4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
475
519
  seam already set it, and this seam must not overwrite it with the tracker's
476
520
  display name.
@@ -492,12 +536,15 @@ is a cosmetic gap that `/spec-claim` closes later.
492
536
 
493
537
  **Nothing is pushed here.** `assign` writes the repo only, and the refresh these
494
538
  skills already run sends it. Assignment is an ordinary field of the projection,
495
- not a side errand with its own network call.
539
+ not a side errand with its own network call. Under `pull` the
540
+ `assign` call is itself the write, so there is nothing for a push to carry.
496
541
 
497
542
  **There is no unassign step anywhere.** The projection derives the assignee from
498
543
  the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
499
544
  issue through the push they already make. The stamp deliberately stays in the
500
- file: who actioned the work outlives who is currently holding it.
545
+ file: who actioned the work outlives who is currently holding it. Under `pull`
546
+ the projection carries no assignee at all, so finishing a spec leaves it on
547
+ the issue: the board keeps who did the work.
501
548
 
502
549
  ### Picking the Linear Project
503
550
 
@@ -72,6 +72,28 @@ this spec. Without isolation, write where you stand.
72
72
  The spec is a folder in **`specs/in-progress/`** — never backlog — with
73
73
  `00-overview.md` and one phase file:
74
74
 
75
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
76
+ Run `skitterspec spec-sync ownership --json` once and read both values:
77
+
78
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
79
+ this skill **writes no `> **Status:**` header and appends no State log row**,
80
+ wherever its steps below say to. A spec this skill creates gets neither: its
81
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
82
+ has stamped the url, and its body has no `## State log` section. Readiness is
83
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
84
+ empty — so nothing is lost with the header.
85
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
86
+ **writes no `> **Developer:**` line** either.
87
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
88
+ — is cannot-tell, and the steps below run exactly as written.
89
+
90
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
91
+ the code, not a planning status), the phase files and index, and the Changelog.
92
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
93
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
94
+ any of these lines keeps them untouched: they are history, and nothing rewrites
95
+ them.
96
+
75
97
  ```markdown
76
98
  # Incident: <short title>
77
99
 
@@ -190,6 +190,27 @@ their id the same way. **Never write a user id into `linear.config.json`**: that
190
190
  file is committed, so it would assign every teammate's specs to whoever ran
191
191
  setup.
192
192
 
193
+ ## 7c. What does a ticket carry?
194
+
195
+ Ask once, with the recommendation first — this decides what the team sees on
196
+ every ticket, so it is theirs to choose rather than a default to inherit:
197
+
198
+ - **`summary`** *(recommended — what `init-config` writes)* — the ticket holds a
199
+ short delimited block: the spec's summary, its acceptance criteria, the
200
+ surfaces it touches, its gating and its progress. Push splices that block in
201
+ beside whatever the team writes, which no push ever touches. The spec itself
202
+ stays in git.
203
+ - **`spec`** — the whole overview is the ticket body, replaced on every push.
204
+ Pass `--description spec` to `init-config`.
205
+
206
+ Linear's block is marked with a heading for now (`summary.delimiter`), provisional
207
+ until a measured run settles which delimiter Linear's editor keeps.
208
+
209
+ Then name the phase mode, without asking unless they raise it:
210
+ `mapping.phases` stays `subissue` — one assignable sub-issue per phase, which
211
+ is what lets phases run in parallel. `deferred` (minted at `/spec-start`),
212
+ `inline` and `none` (no sub-issues at all) are one edit to the file away.
213
+
193
214
  ## 8. Write it
194
215
 
195
216
  ```
@@ -197,7 +218,8 @@ skitterspec spec-sync init-config \
197
218
  --team-id <uuid> [--team-key KEY] [--project-id <uuid>] \
198
219
  [--intake-label <name>] [--bug-labels a,b] [--hotfix-labels a,b] \
199
220
  [--state <bucket>=<name> …] [--no-assign] \
200
- --states <statesfile> [--force] [--json]
221
+ --states <statesfile> [--force] [--json] \
222
+ [--description summary|spec]
201
223
  ```
202
224
 
203
225
  The engine writes **only the keys that differ from the defaults**, so the file