@skitterbyte/skitterspec-linear 19.2.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 +131 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +95 -6
  12. package/assets/skills/spec-bug/SKILL.md +68 -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 +72 -4
  17. package/assets/skills/spec-incident/SKILL.md +44 -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
@@ -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`) —
@@ -177,6 +187,27 @@ Hotfixes are concrete — confirm, don't over-grill. Establish:
177
187
  - **Root cause:** read the code **at the base tag** and trace it to `file:line`.
178
188
  The fix belongs on the tag's line, so reason about that code, not `main`'s.
179
189
 
190
+ ### Watch for the other doors — incident, bug, or not a defect
191
+
192
+ This is the most specific defect door, so most mis-entries route *down*
193
+ (`.claude/rules/spec-planning.md` carries the full routing matrix):
194
+
195
+ - **Live outage** — the released version is not just wrong but down or
196
+ degraded **right now** → propose **`/spec-incident`**; the record comes
197
+ first, and the fix returns here as a linked hotfix spec.
198
+ - **Not on a released version** — §1 cannot name a deployed tag the defect is
199
+ on (it exists only on `main`, or prod runs something newer that is fine) →
200
+ propose **`/spec-bug`**; a hotfix branch for something `main` can carry is
201
+ waste, not safety.
202
+ - **Not a defect** — the ask is new or changed behaviour, not restoring
203
+ intended behaviour → propose **`/spec`**.
204
+
205
+ **Always confirm; never silently switch** — name the signal in the user's own
206
+ words with a one-line reason; a decline carries this skill on where it was.
207
+ **On a confirmed switch, hand off in-session and carry the context**
208
+ established so far — the symptom, the repro, any version discussion — so the
209
+ destination grills only what it still needs.
210
+
180
211
  ## 3. Provision the worktree from the tag, then write in it
181
212
 
182
213
  **Provision before you write, not after.** §1 settled the tag and the name and
@@ -244,6 +275,10 @@ installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
244
275
  and a step whose documented opening the repo will not perform is not a step. The
245
276
  spec is written in the worktree at §5, on the branch it belongs to.
246
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
+
247
282
  **§5 records the same tag you passed to `--from`**, on the spec's
248
283
  `> **Base version:**` header. That is not bookkeeping: `/spec-complete` cuts the
249
284
  release and carries the fix off the header, so a worktree forked from one ref and
@@ -282,6 +317,28 @@ you there, so create the folder and write it here. A hotfix
282
317
  is usually a single-pass fix, so the `## Fix` block can live directly in
283
318
  `00-overview.md`. Keep it lean:
284
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
+
285
342
  ```markdown
286
343
  # Hotfix: <short title>
287
344
 
@@ -290,7 +347,7 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
290
347
  > **Status:** In Progress — fixing (red test added)
291
348
  > **Author:** <git user.name — who reported/captured it>
292
349
  > **Developer:** <git user.name — you, since you're fixing it now>
293
- > **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>
294
351
  > **Raised:** <YYYY-MM-DD (today)>
295
352
  > **Area:** <files/modules>
296
353
  > **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
@@ -369,7 +426,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
369
426
  behaves exactly as above. When present, link the spec you just wrote so status
370
427
  and discussion live in Linear while the repo stays the source of truth. A spec is
371
428
  a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
372
- 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.
373
432
 
374
433
  **Linking is just the first push**, so it runs the same engine path `/spec-push`
375
434
  does — you never create the issue by hand:
@@ -450,6 +509,12 @@ is a cosmetic gap that `/spec-claim` closes later.
450
509
  skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
451
510
  ```
452
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
+
453
518
  4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
454
519
  seam already set it, and this seam must not overwrite it with the tracker's
455
520
  display name.
@@ -471,12 +536,15 @@ is a cosmetic gap that `/spec-claim` closes later.
471
536
 
472
537
  **Nothing is pushed here.** `assign` writes the repo only, and the refresh these
473
538
  skills already run sends it. Assignment is an ordinary field of the projection,
474
- 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.
475
541
 
476
542
  **There is no unassign step anywhere.** The projection derives the assignee from
477
543
  the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
478
544
  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.
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.
480
548
 
481
549
  ### Picking the Linear Project
482
550
 
@@ -37,6 +37,28 @@ Ask for exactly these, batched, with nothing speculative:
37
37
  A root cause is **not** grilled: nobody has it yet, and the Timeline is where
38
38
  the investigation lands as it happens.
39
39
 
40
+ ### No live outage to record — route to the right door
41
+
42
+ This is the costliest door to enter wrongly — no backlog stop, no review page,
43
+ straight into `specs/in-progress/` — so the grill's own answers are also its
44
+ exit. When items 1 and 2 establish there is **no outage to record** — nothing
45
+ is down or degraded, it never was live, or it is a risk rather than an event —
46
+ propose the right door instead of writing an incident
47
+ (`.claude/rules/spec-planning.md` carries the full routing matrix):
48
+
49
+ - a **defect** → **`/spec-bug`**, or **`/spec-hotfix`** when it is on a
50
+ released version;
51
+ - anything else → **`/spec`**, whose kind proposal picks feature, chore or
52
+ issue from there.
53
+
54
+ **A past outage someone wants a record of stays an incident**: "it is over" is
55
+ not "it never happened" — the signal is *no outage to record*, not *no outage
56
+ now*. This check is the grill's existing questions read honestly, never an
57
+ extra round trip, and the hand-off contract is the same as everywhere else:
58
+ confirm first, naming the signal in the user's own words; a decline carries
59
+ this skill on; on a confirmed switch invoke the destination skill in-session,
60
+ seeded with everything already established.
61
+
40
62
  ## 2. Write it, in flight
41
63
 
42
64
  Pick a short kebab name prefixed `incident-` (e.g. `incident-api-outage`).
@@ -50,6 +72,28 @@ this spec. Without isolation, write where you stand.
50
72
  The spec is a folder in **`specs/in-progress/`** — never backlog — with
51
73
  `00-overview.md` and one phase file:
52
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
+
53
97
  ```markdown
54
98
  # Incident: <short title>
55
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
@@ -193,10 +193,15 @@ once it is over. Without a provider this is a no-op and nothing below changes.
193
193
  **Only when `specs/.core/linear.config.json` exists** and the spec carries a
194
194
  `linear_identifier`. Otherwise skip this step — no config means zero change.
195
195
 
196
- - **No pull.** Linear is a generated mirror in one-way sync, so there is nothing
197
- to bring down before building — the repo is already the source of truth. (A
198
- workflow-state a teammate moved in Linear is advisory only; `/spec-status`
199
- surfaces it. It is overwritten on the next push.)
196
+ - **No pull — one look at the board, before building.** Nothing is brought
197
+ down. Run `skitterspec spec-sync board <spec>`: it reads Linear and writes nothing to
198
+ the spec, and it is **silent** unless the issue says Done or Cancelled while
199
+ this spec is still in flight. When it prints a line, relay it once as a
200
+ warning — this session holds the branch, so the cleanup it names is the
201
+ operator's to choose — and **carry on with the build**. Never run that
202
+ cleanup and never refuse on it. A status someone moved anywhere else is the
203
+ board doing its job, and the next push sends a state only when the spec
204
+ itself changes bucket.
200
205
  - **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
201
206
  moved to `in-progress` and its phase to `🔄` — both real state changes, and the
202
207
  tracker is a generated mirror of them. This holds under **both**
@@ -212,7 +217,9 @@ once it is over. Without a provider this is a no-op and nothing below changes.
212
217
  `assignee` (it does by default; `"none"` declines it). If the spec records nobody and
213
218
  `skitterspec spec-sync whoami --json` answers, stamp it with
214
219
  `skitterspec spec-sync assign <spec> --to <id> --name "<name>"` and let the
215
- push above carry it. If identity is unknown, skip it in silence.
220
+ push above carry it. If identity is unknown, skip it in silence. Where
221
+ `spec-sync ownership` reports `assignee: pull`, add `--if-unassigned`: the
222
+ ticket is the record there, so it is assigned only when nobody holds it.
216
223
  **Do not prompt**: an assignment question in the middle of a build is an
217
224
  interruption with no deadline, and `/spec-claim` answers it whenever the
218
225
  operator likes.
@@ -20,6 +20,13 @@ own (the sub-issue's title and state). This skill computes what changed since
20
20
  the last push and applies it — it never reads Linear content back or merges. A
21
21
  person editing the mirror in Linear will see it overwritten on the next push.
22
22
 
23
+ **That is `mapping.description: "spec"`.** Under `"summary"` (what a new
24
+ config is written with) the issue and each sub-issue carry a delimited
25
+ **block** instead — summary, acceptance criteria, surfaces, gating and
26
+ progress for the spec; goal and task count for a phase — spliced in beside
27
+ whatever the team wrote in Linear, which is never overwritten. Only the block
28
+ is the repo's, so only an edit inside it is reported.
29
+
23
30
  **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
24
31
  tell the user how to enable Linear sync and stop.
25
32
 
@@ -155,6 +162,21 @@ the chosen project through as `--project <id>`.
155
162
 
156
163
  ## 4a. Apply it yourself — the MCP path (order matters)
157
164
 
165
+ **In summary mode, every body you write is the engine's splice — never the plan's text on its own.**
166
+ Only when the plan's `descriptionMode` is
167
+ `summary` (it is always present; `spec` needs none of this). There
168
+ the plan's `description` and each sub-issue's `goal` are a **block**, and the
169
+ issue's body is the block *plus the team's text around it*. Writing the block
170
+ alone deletes that text. So, for each object you are about to write:
171
+
172
+ 1. Save the body Linear holds now to a file — an empty file for one you are
173
+ creating.
174
+ 2. `skitterspec spec-sync splice <spec> --live <file>` for the spec issue, or
175
+ `… --phase <ref>` for a phase's sub-issue.
176
+ 3. Write **exactly what it prints**. A non-zero exit printed nothing and means
177
+ a delimiter was edited by hand: skip that object's body, write its other
178
+ fields, and name it in the report. Never compose the splice yourself.
179
+
158
180
  **First, check whether you are about to overwrite someone.** On the API path
159
181
  `apply` does this for itself, off the read-back it already makes. On the MCP
160
182
  path nothing has read the issue yet, so ask before you write:
@@ -43,6 +43,11 @@ trust the spec's own wording — verify:
43
43
  - **Decisions still valid.** Re-check each `## Decisions` entry against the
44
44
  current architecture and `.claude/rules/*.md`. Flag any that now conflict with
45
45
  how the codebase actually works (a changed convention, a superseded approach).
46
+ - **The ticket-facing pair.** A spec with no `## Summary` or no
47
+ `## Acceptance criteria` is not broken — older specs predate both — but where
48
+ a ticketing provider pushes summaries the ticket falls back to the Problem's
49
+ first paragraph and shows no definition of done. Offer to write the missing
50
+ one(s) in step 3, with a draft; never add them unasked.
46
51
  - **New constraints.** Note rules/patterns introduced since the spec was written
47
52
  that it must now honour (e.g. a new required field, a new error type, a new
48
53
  pattern the rest of the code now follows).
@@ -96,6 +101,29 @@ resolve it by reading the code, do that instead of asking.
96
101
  - Add a dated **Changelog** entry summarising the review (e.g. `- <date> —
97
102
  Reviewed vs codebase: retargeted Phase 2 onto X, dropped Y (removed), ticked Z
98
103
  (already done)`).
104
+
105
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
106
+ Run `skitterspec spec-sync ownership --json` once and read both values:
107
+
108
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
109
+ this skill **writes no `> **Status:**` header and appends no State log row**,
110
+ wherever its steps below say to. A spec this skill creates gets neither: its
111
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
112
+ has stamped the url, and its body has no `## State log` section. Readiness is
113
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
114
+ empty — so nothing is lost with the header.
115
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
116
+ **writes no `> **Developer:**` line** either.
117
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
118
+ — is cannot-tell, and the steps below run exactly as written.
119
+
120
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
121
+ the code, not a planning status), the phase files and index, and the Changelog.
122
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
123
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
124
+ any of these lines keeps them untouched: they are history, and nothing rewrites
125
+ them.
126
+
99
127
  - **Status:** if drift is minor, leave status as-is. If a `Ready` spec needs real
100
128
  re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
101
129
  **State log** row).
@@ -118,6 +146,10 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
118
146
  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
119
147
  the repo regardless; the mirror is disposable and the next push repairs it.
120
148
  Do not roll anything back, and do not stop to ask.
149
+ - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
150
+ a PR, and a ready PR is not a merged one — so skip it on run 1, even where
151
+ the `branch` lane committed the move to ride the PR, and run it on run 2 once
152
+ the host has merged. The tracker's Done lands when the work does.
121
153
  - **Say what happened** in the skill's report: mirror updated, skipped as
122
154
  unlinked, or failed with the reason.
123
155
  - **There is no unassign step, and that is not an omission.** Where the repo owns
@@ -126,6 +158,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
126
158
  releases the issue, and the push above carries it like any other field. The
127
159
  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
128
160
  they record who actioned the work, which outlives who is holding it.
161
+ Under `assignee: pull` the projection carries no assignee at all, so the
162
+ issue keeps it: the board records who did the work.
129
163
 
130
164
  ### Why it sits here
131
165
 
@@ -152,6 +152,14 @@ render says so. On **`--plan`** this step does not run at all.
152
152
  1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
153
153
  `to provision, run:` commands it prints and confirm they succeeded.
154
154
 
155
+ **Under a rolling base** (`baseBranchPattern`) `up` fetches first, and where
156
+ the primary checkout is not on the newest release candidate the plan says
157
+ `fork: <base> (the base — the primary checkout is on <old>)` and forks from
158
+ it. Relay that line in the `Branch` row. A refusal naming
159
+ `no branch matches <pattern>` means no release candidate is visible —
160
+ usually not fetched: relay it, stop with `⏸`, and name
161
+ `skitterspec spec-env base` (it fetches and lists) as the next step.
162
+
155
163
  2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
156
164
  `.claude/settings.local.json`, but that file does not hot-reload in this
157
165
  session — run **`/add-dir <trusted root>`** before editing into the worktree,
@@ -255,6 +263,29 @@ branch is already here.
255
263
 
256
264
  - `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
257
265
  already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
266
+
267
+ **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
268
+ Run `skitterspec spec-sync ownership --json` once and read both values:
269
+
270
+ - **`workflowState: "pull"`** — Linear is the record of this spec's status, so
271
+ this skill **writes no `> **Status:**` header and appends no State log row**,
272
+ wherever its steps below say to. A spec this skill creates gets neither: its
273
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
274
+ has stamped the url, and its body has no `## State log` section. Readiness is
275
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
276
+ empty — so nothing is lost with the header.
277
+ - **`assignee: "pull"`** — Linear holds who is building it, so this skill
278
+ **writes no `> **Developer:**` line** either.
279
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
280
+ — is cannot-tell, and the steps below run exactly as written.
281
+
282
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
283
+ the code, not a planning status), the phase files and index, and the Changelog.
284
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
285
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
286
+ any of these lines keeps them untouched: they are history, and nothing rewrites
287
+ them.
288
+
258
289
  - Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
259
290
  - Set **Developer** if it is still `—` (`git config user.name`).
260
291
 
@@ -294,6 +325,12 @@ is a cosmetic gap that `/spec-claim` closes later.
294
325
  skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
295
326
  ```
296
327
 
328
+ **Where `spec-sync ownership` reports `assignee: pull`**, the issue is the
329
+ record and the spec file is not: add `--if-unassigned`. It writes Linear
330
+ directly, claims the issue only when nobody holds it, and stamps nothing —
331
+ so step 4 has no header to leave alone, since under `pull` no `Developer:`
332
+ line was written.
333
+
297
334
  4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
298
335
  seam already set it, and this seam must not overwrite it with the tracker's
299
336
  display name.
@@ -315,12 +352,15 @@ is a cosmetic gap that `/spec-claim` closes later.
315
352
 
316
353
  **Nothing is pushed here.** `assign` writes the repo only, and the refresh these
317
354
  skills already run sends it. Assignment is an ordinary field of the projection,
318
- not a side errand with its own network call.
355
+ not a side errand with its own network call. Under `pull` the
356
+ `assign` call is itself the write, so there is nothing for a push to carry.
319
357
 
320
358
  **There is no unassign step anywhere.** The projection derives the assignee from
321
359
  the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
322
360
  issue through the push they already make. The stamp deliberately stays in the
323
- file: who actioned the work outlives who is currently holding it.
361
+ file: who actioned the work outlives who is currently holding it. Under `pull`
362
+ the projection carries no assignee at all, so finishing a spec leaves it on
363
+ the issue: the board keeps who did the work.
324
364
 
325
365
  - Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
326
366
 
@@ -329,6 +369,12 @@ carries a `linear_identifier`. Either missing → **skip**, in one line
329
369
  (`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
330
370
  this step changes.
331
371
 
372
+ **Ask the board first.** Run `skitterspec spec-sync board <spec>`. It is silent
373
+ unless Linear already says Done or Cancelled for this issue; when it prints a
374
+ line, relay it once as a warning and **carry on** — you are the one about to hold
375
+ this branch, so the cleanup it names is yours to choose, and nothing here runs it
376
+ or refuses on it.
377
+
332
378
  **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
333
379
  moved to `in-progress/` and been stamped with a developer — two real state
334
380
  changes, and the tracker is a generated mirror of them. It costs one engine call
@@ -398,7 +444,8 @@ destroyed: that skill relays the refusal and offers both ways out. Nothing to do
398
444
  here beyond knowing it is no longer dead code.
399
445
 
400
446
  A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
401
- it is well-formed first.
447
+ it is well-formed first. Where the spec keeps no `Status:` header (the tracker
448
+ owns its status), a non-empty **Open questions** section is what marks a Draft.
402
449
 
403
450
  - **Report anything left waiting, and claim none of it.** Ask the engine once:
404
451
 
@@ -19,9 +19,12 @@ Read-only. Reports two things and writes nothing:
19
19
  since the last push? The next push replaces it, so this is worth reading
20
20
  first.
21
21
 
22
- **Status is not compared, deliberately.** Skitterspec tells Linear about its
23
- own transitions and never reads a status back: a card someone moved by hand is
24
- theirs to have moved, and push resends State only when the spec itself moves.
22
+ **Status is not compared — with one exception.** Skitterspec tells Linear about
23
+ its own transitions and does not mirror a status back: a card someone moved by
24
+ hand is theirs to have moved, and push resends State only when the spec itself
25
+ changes bucket. The exception is the one difference the repo can act on — the
26
+ issue says Done or Cancelled while the spec is still in flight — which §3c
27
+ asks about, and reports without acting.
25
28
 
26
29
  The repo is the source of truth; Linear is a generated mirror, so there is no
27
30
  per-field "conflict" — only "what would the next push send" and "did someone
@@ -84,6 +87,18 @@ Read-only until `--yes`. Do not attempt the rewrite by hand — the identifiers
84
87
  live in frontmatter, snapshot filenames and the keys inside those snapshots, and
85
88
  a hand edit misses some (it has, twice).
86
89
 
90
+ ## 3c. Has the board finished it?
91
+
92
+ ```
93
+ skitterspec spec-sync board <spec>
94
+ ```
95
+
96
+ Silent unless Linear says Done or Cancelled while this spec is in `backlog` or
97
+ `in-progress`; then one line naming the cleanup (`/spec-complete` or
98
+ `/spec-cancel`). Relay that line as it is.
99
+ **Report it; never offer or run the cleanup** — this skill is read-only, and
100
+ the branch may be someone else's to close. Silence, an unlinked spec and an unreadable issue all say nothing.
101
+
87
102
  ## 4. Report
88
103
 
89
104
  Relay the engine's output **verbatim, above the block** — it is the answer, and
@@ -51,6 +51,7 @@ In a project that installs the Linear superset the binary is
51
51
  | "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
52
52
  | "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
53
53
  | "who's on this team?", "find Jane's user id" | `users <name-or-email>` |
54
+ | "did someone close this on the board?", "is Linear ahead of the repo?" | `board <spec>` — silent unless Linear says Done/Cancelled where the spec is not; relay its cleanup, never run it |
54
55
  | push one spec, or "what would push?" | **defer** — see below |
55
56
 
56
57
  **With no argument, run `linked`.** It is the repo-wide overview, it is
@@ -28,6 +28,11 @@ fast-forward leaves `base == branch`, the operation is
28
28
  **idempotent and repeatable**: new commits put the branch ahead of base again,
29
29
  and you can run `/spec-to-main` as many times as you like.
30
30
 
31
+ **In PR mode** (`land.strategy: "pr"` in `env.config.json`) the destination is
32
+ the host, not the local base: this skill becomes *push the branch and open or
33
+ update the DRAFT pull request* — same intent (get the work into CI / the shared
34
+ env), new transport. §4b replaces §4 there; everything else holds unchanged.
35
+
31
36
  ## 0. Preconditions — when this applies
32
37
 
33
38
  - **Isolation must be on** (`specs/.core/env.config.json` exists **and** the spec
@@ -87,6 +92,19 @@ nothing else.
87
92
  On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
88
93
  and continue — the branch has no commits base doesn't already have.
89
94
 
95
+ **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
96
+ can carry two more things, and both are the engine's to say:
97
+ - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
98
+ when the primary checkout still has an older release candidate out — run it
99
+ in order with the rest;
100
+ - a `retarget: forked from <old> · landing onto <new>` line, when the rc
101
+ rolled while this spec was in flight. It is the land working, not a fault:
102
+ relay it verbatim in the `Landed` row so the reader sees where the work went.
103
+
104
+ A refusal naming `no branch matches <pattern>` means no release candidate is
105
+ visible — usually not fetched. Relay it, stop with `⏸`, and name
106
+ `skitterspec spec-env base` (it fetches and lists) as the next step.
107
+
90
108
  **Then run the after-land commands.** Where the plan ends with a
91
109
  `then, in the primary checkout (<path>), run:` section — the project's
92
110
  `afterLand`, such as a data migration — run those commands in that directory,
@@ -99,6 +117,28 @@ land made elsewhere leaves them pending here.
99
117
  that failed and the ones that did not run, and it **never undoes the land**.
100
118
  No section, nothing to run, and nothing to say about it.
101
119
 
120
+ ## 4b. PR mode — push the branch, keep the PR a draft
121
+
122
+ When the plan's heading reads `(pr)`, run
123
+ `skitterspec spec-env integrate <name> --draft` instead and run what it prints:
124
+ a fetch, a rebase onto `<remote>/<base>`, and — this is the consent gate — the
125
+ push and PR-create under its own `with your consent` section.
126
+ **Ask before pushing**: ask once, plainly, naming the remote and that the PR
127
+ opens as a draft. On a yes, re-run with `--push` added and run the single printed list; on
128
+ a no, relay the held commands and stop — the work is rebased and ready, and the
129
+ user can push it themselves.
130
+
131
+ - **The draft is the point.** A draft cannot be merged and the tracker's
132
+ automations read it as in-progress, so nothing downstream can close the
133
+ ticket early. `/spec-complete` is what flips it to ready.
134
+ - A `pr:` line saying the PR is already open means the push updates it —
135
+ nothing more to create, and that is the repeatable case.
136
+ - **No after-land commands run here.** The plan defers them ("after-land
137
+ commands are deferred: base moves when the host merges") — the completion run
138
+ that follows the merge owns them. §5's re-test on base does not apply either:
139
+ base has not moved; CI on the PR is the check this land exists for.
140
+ - A **rebase conflict** aborts and stops exactly as §4.
141
+
102
142
  ## 5. Re-test on base, then report
103
143
 
104
144
  - Run the project's test command **from the primary checkout** — base must be
@@ -111,7 +151,9 @@ No section, nothing to run, and nothing to say about it.
111
151
  to Complete, `git mv` the spec, or tear down the worktree/stack.
112
152
  **The spec stays `In Progress` and the worktree stays put.**
113
153
  - It **never pushes** — say the user can `git push` the base branch themselves to
114
- trigger CI / the shared env.
154
+ trigger CI / the shared env. (PR mode is not an exception to the stance but to
155
+ the mechanics: there the push *is* the land, and it runs only behind §4b's
156
+ explicit consent — never silently.)
115
157
  - `Next` points the way forward: `/spec-next` to continue the remaining phases
116
158
  (you'll keep committing on the same branch and can `/spec-to-main` again), and
117
159
  `/spec-complete` when every phase is genuinely done — it will land the final
@@ -135,6 +177,10 @@ the shape; this section carries only what is specific here.
135
177
  skipped because the land matched no `when` — or the one that failed and the ones that did not run. Nothing about it when none are
136
178
  configured.
137
179
 
180
+ `Landed` in PR mode names the host, not the base: `PR #14 (draft) opened` or
181
+ `PR #14 (draft) updated` — and `held — not pushed` when §4b's consent was
182
+ declined, because an unpushed rebase is a true outcome, not a failure.
183
+
138
184
  **No `Spec` field, deliberately.** This skill changes no status and moves no
139
185
  folder, and a `Spec` line here would read as though it had. The spec stays
140
186
  `In Progress` and the worktree stays standing — if that needs saying, the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.2.0",
3
+ "version": "19.4.0",
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",