@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
@@ -16,7 +16,7 @@ diff as a self-contained HTML page you open locally — or publish, and read on
16
16
  phone. The diff never passes through the model, so the page costs no context
17
17
  tokens however large it is; the optional written review is the part that costs,
18
18
  and it is offered rather than assumed. `/spec-next` writes the page at the end of
19
- every phase.
19
+ every phase. **`skitterspec status`** lists what is in flight across worktrees.
20
20
 
21
21
  **Handing the review back.** The page takes marks: tick `✓ accept` per file as
22
22
  you read, note anything against a line or a whole file, answer the questions a
@@ -34,6 +34,25 @@ An accept remembers the file's content, so it lapses by itself when that file
34
34
  changes again. The marks are information — nothing gates on them; the verdict is
35
35
  the one thing you choose, once.
36
36
 
37
+ **The phase waits for that press.** `/spec-next` ends a phase by rendering the
38
+ page and then watching for your verdict, so the button is what carries the work
39
+ on — no command to remember. What makes that safe is not that the page is
40
+ unreachable (it is reachable, deliberately): it is the **serve token** in the
41
+ URL, 48 random bits deciding who can POST at all, plus the **window** — only a
42
+ pass that arrives *while the session is waiting* is claimed for you, and two
43
+ arrivals refuse rather than pick. Outside that window nothing is claimed
44
+ unasked: type `/spec-reviewed`, or `/spec-reviewed 324199` to name one exactly,
45
+ which matters only when two are waiting. A `file://` page has no server to talk
46
+ to, so it copies and you paste, as before.
47
+
48
+ **And a phase that ended owes you an answer.** The gate is armed when the page
49
+ is rendered at the end of a phase, and cleared by a committing verdict or by
50
+ `skitterspec spec-env review skip "<reason>"` — while it is armed, `/spec-next`
51
+ refuses to build the next phase. Mid-phase renders arm nothing, every
52
+ cannot-tell exits 0 and says nothing, and `review.required: false` turns it off
53
+ for a project. The exit is always one command; one of them is *"I am moving
54
+ on"*, and that reason goes on the record.
55
+
37
56
  **A second opinion, when you want one** (`review.reviewers`, empty by default).
38
57
  Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
39
58
  a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
@@ -36,6 +36,7 @@
36
36
  ]
37
37
  },
38
38
  "baseBranch": "",
39
+ "baseBranchPattern": "",
39
40
  "guards": {
40
41
  "refuseTeardownIfDirty": true,
41
42
  "refuseTeardownIfUnpushed": true
@@ -5,7 +5,7 @@ stack + host dev servers + a front-door proxy per in-progress spec).
5
5
  Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
6
6
  `/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
7
7
  is `/spec-diff`; the `skitterspec spec-env
8
- <up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
8
+ <up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
9
9
  the engine beneath them.
10
10
 
11
11
  **Once this file is present, isolation is the default policy:** `/spec-start` gives
@@ -284,9 +284,65 @@ through to a documented conservative default; see the field notes below.
284
284
  // Integration base branch — the branch specs fork from and land back onto
285
285
  // (used by the teardown "merged?" guard and, later, the integrate step).
286
286
  // Empty = auto-detect: origin/HEAD → main → master. Set it when your default
287
- // branch isn't discoverable (e.g. no remote) or differs (trunk, develop).
287
+ // branch isn't discoverable (e.g. no remote) or differs (trunk, develop, a
288
+ // release-candidate branch). An explicit value always wins — it is the pin.
288
289
  "baseBranch": "",
289
290
 
291
+ // A base that ROLLS: a glob over the remote's branch names (e.g. "20??/Q?")
292
+ // for teams that work off a release candidate versioned per release. The
293
+ // base is the NEWEST match by commit date, so cutting the next rc is all it
294
+ // takes to move every spec onto it — no config edit per release, no message
295
+ // to the team. Precedence: baseBranch (pin) → this pattern → origin/HEAD →
296
+ // main → master.
297
+ // - Matched against `refs/remotes/<land.remote>/*`, never the network:
298
+ // `spec-env up`, `integrate` and `spec-env base` fetch first; everything
299
+ // else reads what the last fetch saw.
300
+ // - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
301
+ // rc/a/b. Spell each segment ("20??/Q?").
302
+ // - No match REFUSES, naming `spec-env base` — it never falls back to
303
+ // origin/HEAD, because zero matches usually means "not fetched", and
304
+ // the default branch is exactly where a rolling base must not land.
305
+ // - Newest-by-date is only right when one rc is live at a time (the next
306
+ // is cut after the last merges). If your rcs overlap, pin `baseBranch`.
307
+ // - A spec that outlived a roll lands on the new rc; the integrate plan
308
+ // says `retarget: forked from <old> · landing onto <new>`, and switches
309
+ // a primary checkout still on the old rc before the fast-forward.
310
+ // A pattern holding whitespace or ".." is dropped (treated as unset).
311
+ // `spec-env base` lists the matches, the base, and specs on an older one.
312
+ "baseBranchPattern": "",
313
+
314
+ // How a finished branch reaches the base branch.
315
+ // strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
316
+ // exactly as always; nothing below applies.
317
+ // "pr" — the branch is pushed and a pull request carries it; the
318
+ // base branch moves only when the host merges. `spec-env
319
+ // integrate` then plans a rebase onto <remote>/<base> and a
320
+ // consent-gated push (`--push` consents; already-pushed-at-HEAD
321
+ // counts as consent; otherwise the plan holds), and a landed
322
+ // branch prints the finish — base catch-up plus the deferred
323
+ // `afterLand`. `--strategy ff|pr` on integrate overrides this per
324
+ // invocation; an unrecognised config value falls back to "ff".
325
+ // remote: where the branch is pushed. Default "origin".
326
+ // draft: mid-spec PRs open as drafts (a draft cannot be merged, so
327
+ // nothing downstream can close a ticket early); /spec-complete is
328
+ // what flips the PR to ready. Default true.
329
+ // specDocs: where a SPEC DOCUMENT lands under "pr". "trunk" (default) keeps
330
+ // today's authoring land — needs direct push for docs. "branch"
331
+ // has the spec ride the feature branch and land with the work's
332
+ // PR; the backlog is then found via the tracker listing, and the
333
+ // authoring worktree stays (it is the document's only copy).
334
+ // The merged-check and PR commands need the host's CLI — `gh` on github.com,
335
+ // `az` on dev.azure.com — detected from the remote URL, never configured. An
336
+ // unknown host (Enterprise/Server domains included) degrades to the ancestry
337
+ // test plus generic printed commands, and every failed lookup is a
338
+ // cannot-tell: teardown then HOLDS the worktree rather than guessing.
339
+ "land": {
340
+ "strategy": "ff",
341
+ "remote": "origin",
342
+ "draft": true,
343
+ "specDocs": "trunk"
344
+ },
345
+
290
346
  // Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
291
347
  // blocks when the commits are ALSO unmerged into the base branch — a branch
292
348
  // already landed on base tears down (and its branch is deleted) without
@@ -297,9 +353,12 @@ through to a documented conservative default; see the field notes below.
297
353
  },
298
354
 
299
355
  // What teardown cleans up beyond this machine. Nothing publishes a spec
300
- // branch for you, so a remote copy exists only because you pushed it by hand —
301
- // and without this a completed spec leaves that merged branch on the remote
302
- // forever. `deleteRemoteBranch`:
356
+ // branch unasked — a remote copy exists because you pushed it by hand, or
357
+ // because a PR-mode land pushed it behind the consent gate — and without this
358
+ // a completed spec leaves that merged branch on the remote forever. (Hosts
359
+ // that auto-delete the branch on merge make the planned delete an
360
+ // already-gone no-op, reported as such, never as a failure.)
361
+ // `deleteRemoteBranch`:
303
362
  // "prompt" (default) — plan `git push <remote> --delete <branch>` in its own
304
363
  // "confirm with the user first" section; /spec-complete and
305
364
  // /spec-cancel ask before running it.
@@ -358,11 +417,36 @@ through to a documented conservative default; see the field notes below.
358
417
  // `hotfix land --push`; without it the land holds before the carry. The
359
418
  // worktree stays until `spec-env hotfix finish`. Default: built-in patch tag,
360
419
  // carry to main, no targets.
420
+ //
421
+ // `releaseBranch` makes hotfixes BRANCH-BASED, for a team whose release line
422
+ // is a branch rather than a tag. Worked example — an rc flow:
423
+ // master takes only rc merges and hotfixes; prod is whatever it holds
424
+ // 2026/Q4 the current release candidate (`baseBranchPattern: "20??/Q?"`)
425
+ // Test/Demo/Live env branches that take merges from master — OUT OF SCOPE:
426
+ // merging master into them stays your pipeline's job
427
+ // With `"releaseBranch": "master"`, `spec-env up hotfix-<name> --docs` fetches
428
+ // and forks from origin/master's head and prints the header to record —
429
+ // `> **Base version:** master@<sha>`. `hotfix land` then rebases onto
430
+ // origin/master and lands ON it by `land.strategy` (`--strategy` overrides):
431
+ // "ff" pushes the hotfix onto master; "pr" opens a READY pull request and
432
+ // holds until the host merges it. The fix is then carried to the resolved base
433
+ // (the newest rc) — directly under "ff", through a `carry/<slug>` branch and
434
+ // its own ready PR under "pr". `hotfix finish` tears down once both are
435
+ // confirmed. Empty (the default) = the tag flow above, unchanged; a hotfix
436
+ // keeps landing the way its own `Base version` says it was cut.
437
+ //
438
+ // `tag` (default true) keeps the release tag on a branch-based hotfix, bumped
439
+ // from the newest tag the release branch has; false is for a team whose deploy
440
+ // is driven by the env-branch merge rather than a tag. Under "pr",
441
+ // `releaseWith` refuses — a squash or rebase merge leaves its tag on a commit
442
+ // the release branch never has — so use the built-in tag there.
361
443
  "hotfix": {
362
444
  "releaseWith": "",
363
445
  "bump": "patch",
364
446
  "cherryPickMain": true,
365
- "targets": []
447
+ "targets": [],
448
+ "releaseBranch": "",
449
+ "tag": true
366
450
  },
367
451
 
368
452
  // Reading a spec's diff (`spec-env review`, `/spec-diff`).
@@ -42,8 +42,8 @@
42
42
  "fieldOwnership": {
43
43
  "description": "push",
44
44
  "subIssues": "push",
45
- "workflowState": "push",
46
- "assignee": "push"
45
+ "workflowState": "pull",
46
+ "assignee": "pull"
47
47
  },
48
48
  "localOnlySections": ["State log", "Changelog", "Open questions"],
49
49
  "keyedFields": {}
@@ -7,8 +7,9 @@ a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
7
7
  that sub-issue's description as a read-only checklist. Content is
8
8
  pushed up and never read back or merged — `/spec-push` diffs the spec against a
9
9
  committed **last-pushed snapshot** and applies only what changed; `/spec-status`
10
- is a read-only report of what would push. The `sync.fieldOwnership` map now just selects the
11
- projection field set (every field is repo-owned and pushed).
10
+ is a read-only report of what would push. The `sync.fieldOwnership` map says who
11
+ owns each field: the repo pushes the content (`description`, `subIssues`), and
12
+ Linear owns status and assignee (`workflowState`, `assignee` ship as `pull`).
12
13
 
13
14
  **Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
14
15
  is absent the feature is simply unused — `/spec`, `/spec-start`, and the CLI's
@@ -125,17 +126,19 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
125
126
  // carries its own, and push knows what changed without reading Linear back.
126
127
  "baseDir": "specs/.core/linear-base",
127
128
 
128
- // The pushed projection field set (repo → Linear, one-way). The `push` marker
129
- // is retained for shape; there is no pull. The default set is the spec
130
- // issue's `description`, its `subIssues` (one per phase — name + goal +
131
- // state), and the lifecycle `workflowState`. Tasks, priority, labels, cycles
132
- // and comments are NOT here, so a PM's triage is never touched. Any key you
133
- // add joins the pushed projection.
129
+ // Who owns each field. `push`: the repo, sent one way (repo → Linear) — the
130
+ // spec issue's `description` and its `subIssues` (one per phase — name +
131
+ // goal + state). `pull`: Linear — the `workflowState` is sent only as a
132
+ // transition the repo made (a bucket move), and the `assignee` is never
133
+ // projected; `spec-sync assign` writes it directly. `"push"` on either
134
+ // restores the repo-owned behaviour; `"none"` declines a field. Tasks,
135
+ // priority, labels, cycles and comments are NOT here, so a PM's triage is
136
+ // never touched.
134
137
  "fieldOwnership": {
135
138
  "description": "push",
136
139
  "subIssues": "push",
137
- "workflowState": "push",
138
- "assignee": "push"
140
+ "workflowState": "pull",
141
+ "assignee": "pull"
139
142
  },
140
143
 
141
144
  // Markdown sections of 00-overview.md that are local-only scaffolding and
@@ -177,7 +180,17 @@ Sprint", "Released". A bucket's value may be an **array** instead of a string:
177
180
 
178
181
  ## Assignment (`sync.fieldOwnership.assignee`)
179
182
 
180
- **On by default since v16.** The spec issue is assigned to whoever is building
183
+ **Linear owns it by default (`pull`).** The board is where a team assigns work,
184
+ so the issue's assignee is the record and the spec keeps no copy: `/spec-start`
185
+ runs `spec-sync assign --if-unassigned`, which assigns you only when nobody holds
186
+ the issue and never reassigns anyone; `/spec-claim` writes Linear directly; and
187
+ finishing a spec leaves the assignee in place — the board keeps who did the work.
188
+ No `linear_assignee_id` stamp and no `> **Developer:**` line is written. Set
189
+ `"assignee": "push"` for the repo-owned behaviour described below.
190
+
191
+ ### Under `push`
192
+
193
+ **On by default from v16 until `pull` replaced it.** The spec issue is assigned to whoever is building
181
194
  it: `/spec-start` records them, and the issue is released when the spec
182
195
  completes. To decline it, say so:
183
196
 
@@ -457,6 +470,24 @@ default for anyone who never sets one.
457
470
  **section of the spec issue's own description**, with its full task list, and
458
471
  the `## Phases` index stays as the table of contents. One issue per spec,
459
472
  however many phases it has.
473
+ - `"none"` — no phase objects at all: the issue is one ticket. A phase that
474
+ already carries a `linear_issue_id` keeps its sub-issue (see below).
475
+
476
+ ## What the issue body carries — `mapping.description`
477
+
478
+ - `"spec"` (the default, and what a config without the key gets) — the whole
479
+ overview, replacing the description on every push.
480
+ - `"summary"` — a delimited **block** (summary, acceptance criteria, surfaces
481
+ touched, gating, spec path) spliced into the description beside whatever the
482
+ team wrote there, which no push touches. Phase sub-issues get a block with
483
+ their goal. Drift is reported only for an edit *inside* the block.
484
+
485
+ `summary.delimiter` marks the block: `"heading"` (the default here — a
486
+ `## Skitterspec summary` heading and an end line) or `"comment"` (HTML
487
+ comments). Linear's default is **provisional** until
488
+ `chore-delimiter-spike-providers` measures which survives Linear's editor. A
489
+ delimiter someone edited is reported and the block left unwritten, never
490
+ guessed at.
460
491
 
461
492
  ### One mode, or one per bucket
462
493
 
@@ -679,11 +710,13 @@ most specific destination. Leave a list empty and nothing routes through it.
679
710
 
680
711
  ## One direction — nothing to reconcile
681
712
 
682
- The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
683
- current spec against the committed **last-pushed snapshot** and sends only what
684
- changed — creates for unlinked items, updates for changed ones. A workflow-state a
685
- teammate moves in Linear is **not skitterspec's business**: it is never read
686
- back or reported, and push resends State only when the spec itself moves. A
713
+ The repo owns the spec's content and pushes it; nothing is merged back.
714
+ `/spec-push` diffs the current spec against the committed
715
+ **last-pushed snapshot** and sends only what changed — creates for unlinked items, updates for
716
+ changed ones. A workflow-state a teammate moves in Linear is **Linear's**: push
717
+ sends a state only when the spec itself changes bucket, and the one difference
718
+ reported is the issue being Done or Cancelled while the spec is still in flight
719
+ (`spec-sync board`, which names the cleanup and runs nothing). A
687
720
  **description** someone edited there is reported by `/spec-status`, because
688
721
  the next push replaces it. Priority, labels, cycles and comments are
689
722
  Linear-native triage and are never touched. No base merge, no conflicts, no
@@ -117,6 +117,15 @@ function writeTarget(input) {
117
117
  return null
118
118
  }
119
119
 
120
+ // The engine's own refusal line, from `spec-env main check`. Pure.
121
+ //
122
+ // WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
123
+ // refusal is the last thing `check` writes, so a crash before it prints nothing
124
+ // — and one after it has already decided.
125
+ function isRefusal(stdout) {
126
+ return /^spec-env main: /m.test(stdout || '')
127
+ }
128
+
120
129
  function main() {
121
130
  const payload = readPayload()
122
131
  if (!payload) allow()
@@ -145,7 +154,14 @@ function main() {
145
154
  if (result.error || result.status === null) allow()
146
155
  if (result.status !== 1) allow()
147
156
 
148
- deny((result.stdout || '').trim())
157
+ // EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
158
+ // engine that cannot even load looks exactly like one refusing — and read
159
+ // that way it denied every Edit and Write in the session. The positive signal
160
+ // is the refusal the engine PRINTS; a crash prints nothing on stdout.
161
+ const said = (result.stdout || '').trim()
162
+ if (!isRefusal(said)) allow()
163
+
164
+ deny(said)
149
165
  }
150
166
 
151
167
  // Guarded so the pieces above can be required and tested without the script
@@ -159,4 +175,4 @@ if (require.main === module) {
159
175
  }
160
176
  }
161
177
 
162
- module.exports = { findEngine, WRITE_TOOLS, writeTarget }
178
+ module.exports = { findEngine, WRITE_TOOLS, writeTarget, isRefusal }
@@ -93,6 +93,15 @@ function findEngine(projectDir) {
93
93
  return 'skitterspec'
94
94
  }
95
95
 
96
+ // The engine's own refusal line, from `spec-env review gate --check`. Pure.
97
+ //
98
+ // WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
99
+ // refusal is written last, after every read has succeeded, so a crash before
100
+ // it prints nothing — and one after it has already decided.
101
+ function isRefusal(stdout) {
102
+ return /^spec-env review gate: /m.test(stdout || '')
103
+ }
104
+
96
105
  function main() {
97
106
  const payload = readPayload()
98
107
  if (!payload) allow()
@@ -119,8 +128,16 @@ function main() {
119
128
  if (result.error || result.status === null) allow()
120
129
  if (result.status !== 1) allow()
121
130
 
131
+ // EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
132
+ // engine that cannot even load looks exactly like one saying "armed" — and
133
+ // once read that way it denied every Bash call in the session, the operator's
134
+ // own `!` commands included. The positive signal is the refusal the engine
135
+ // PRINTS; a crash prints nothing on stdout, so it allows.
136
+ const said = (result.stdout || '').trim()
137
+ if (!isRefusal(said)) allow()
138
+
122
139
  deny(
123
- (result.stdout || '').trim() +
140
+ said +
124
141
  '\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
125
142
  'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
126
143
  'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
@@ -143,4 +160,4 @@ if (require.main === module) {
143
160
  }
144
161
  }
145
162
 
146
- module.exports = { findEngine }
163
+ module.exports = { findEngine, isRefusal }
@@ -85,10 +85,33 @@ and it is cancelled along with it.
85
85
 
86
86
  ## Why it exists
87
87
 
88
- The repo lands specs with `merge --ff-only`, so history is linear and branch
88
+ In trunk mode the repo lands specs with `merge --ff-only`, so history is linear and branch
89
89
  names never reach it. The commit message is the only artefact that survives into
90
90
  the range a release scans, which is what lets
91
91
  `spec-sync released <range>` report the tickets a release contains. A ref that
92
92
  names the wrong ticket does not merely lose information — it moves a commit onto
93
93
  another ticket's release report, which is worse than the gap it was meant to
94
94
  close.
95
+
96
+ ## Merge styles, and which range still holds the trailers
97
+
98
+ Trunk mode keeps this simple: `merge --ff-only` means linear history and every
99
+ trailer survives. PR mode (`land.strategy: "pr"`) hands the merge to the host,
100
+ and no merge style is required — teams pick their own — so the scan copes
101
+ per style instead:
102
+
103
+ - **Merge commits** — every branch commit survives, trailers intact. A
104
+ trailer-less merge commit counts as transport, never as an unreferenced gap —
105
+ while a merge that CARRIES a trailer still counts, because a hand merge is
106
+ where a ticket's only trailer sometimes lives.
107
+ - **Squashed feature PRs** — the branch's commits collapse into one. The
108
+ trailers survive when the squash message keeps the commit bodies (GitHub:
109
+ the "Default commit message" squash setting; Azure DevOps: keep the commit
110
+ descriptions in the squash message) — `released` counts every `Refs:` line
111
+ in the one body, so a squashed PR carrying three commits still reports three
112
+ tickets.
113
+ - **A squashed integration-to-release merge** — one commit for a whole cycle,
114
+ and attribution on the release branch is gone by construction. No setting
115
+ fixes that: point `released <range>` at the integration branch's range
116
+ instead, where the commits still exist. The range argument has always been
117
+ arbitrary, and this is what it is for.
@@ -7,7 +7,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
7
7
 
8
8
  | Skill | Purpose | Status | Folder |
9
9
  |-------|---------|--------|--------|
10
- | `/spec` | (Feature/Chore/Issue) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
10
+ | `/spec` | (Feature/Chore/Issue) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch by a fast-forward — or riding the feature branch under `land.specDocs: "branch"`) |
11
11
  | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
12
12
  | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
13
13
  | `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
@@ -157,6 +157,9 @@ build phase 1 now? Say yes and it carries on into a bare `/spec-next`; say no an
157
157
  you are already standing in the worktree, so `/spec-next` typed later does the
158
158
  same thing. The primary checkout stays on the base branch throughout — the
159
159
  session followed the spec, nothing was checked out anywhere.
160
+ That is also why the base branch reads `backlog` for a spec being built: the
161
+ move happened on its branch. **`skitterspec status`** reads each worktree's own
162
+ copy and lists what is in flight and how far along it is.
160
163
  **`checkout`** builds the branch in the primary checkout instead: one spec at a
161
164
  time, nowhere else to stand, and the build always carries straight on.
162
165
  The difference is how many specs can be in flight at once.
@@ -179,7 +182,7 @@ your canonical `localhost` ports so you can test it at the normal URL
179
182
  move, header edits, the code) happens on the spec's branch in the worktree; `main`
180
183
  changes only when it merges. Teardown is folded into `/spec-complete` ·
181
184
  `/spec-cancel`. Beneath the skills, `skitterspec spec-env
182
- <up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
185
+ <up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
183
186
  engine. `up` plans the fork;
184
187
  **`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
185
188
  the command a skill runs names no file, and a secrets hook that refuses any
@@ -234,6 +237,16 @@ worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
234
237
  `commit` tears it down, because a spec parked in the backlog should hold no
235
238
  checkout.
236
239
 
240
+ **`land.specDocs: "branch"` is the exception, taken deliberately.** Where the
241
+ base branch accepts no direct push even for documents, the spec rides its
242
+ feature branch and lands with the work's PR: both verdicts commit and skip the
243
+ integrate, plain `commit` keeps branch and worktree (they are the document's
244
+ only copy), and the backlog is found through the tracker listing rather than
245
+ `ls specs/backlog/` on base — the known branch-relative-bucket cost, accepted
246
+ because the alternative is a spec that cannot be written at all. The worktree
247
+ fork-point check is exempt in this mode for the hotfix's reason: the spec is
248
+ *supposed* to be absent from the fork point.
249
+
237
250
  **What this bought is the reason it changed.** The page waits for a verdict
238
251
  without a timeout — deliberately, because a reader walking away from a diff is
239
252
  the normal case — and while the spec was authored in the primary checkout that
@@ -497,15 +510,60 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
497
510
  backed by a `spec-sync` CLI. There is no content pull — the tracker is never
498
511
  read back or merged.
499
512
 
500
- **It tells, it doesn't track.** Skitterspec sends the tracker its own
501
- transitions — a spec starting, a phase finishing, a spec completing or being
502
- cancelled — and nothing else. A status someone changes on the tracker is
503
- theirs to have changed: it is never read back, never reported, and only
504
- overwritten when the spec itself next moves. Releases and deployments are the
505
- host project's to record. The one release question skitterspec answers is which
506
- tickets a commit range contains (`spec-sync released <range> --json`, each row
507
- with its spec and url), because only the `Refs:` trailers know. What the
508
- project's CI does with that list is its own business.
513
+ **What a ticket carries is the project's choice (`mapping.description`).**
514
+ Under `"spec"` the issue body is the whole overview and each phase sub-issue
515
+ its phase file, replaced on every push — what every config written before the
516
+ setting existed gets. Under `"summary"`, what a new config is written with, the
517
+ spec stays in git and the ticket gets what a ticket is for: a delimited
518
+ **block** holding the spec's `## Summary`, its `## Acceptance criteria`, the
519
+ Impact table's surfaces, its gating and its progress (`62% · phase 3 of 4`),
520
+ with each sub-issue's block holding its goal and task count. Push **splices**
521
+ the block into whatever the description holds, so a team's own text around it
522
+ survives every push, and only an edit *inside* the block is drift. That is a
523
+ splice, not a pull: nothing outside the block is parsed, merged or written
524
+ back. A delimiter edited by hand is cannot-tell — the push names it and writes
525
+ nothing there rather than guess. `mapping.phases: "none"` drops the phase
526
+ objects entirely; `subissue` stays the default because assignable phases are
527
+ what let them run in parallel.
528
+
529
+ **The tracker owns status; the repo owns the spec.** With a provider attached,
530
+ a team runs its work from the board — assignment, Ready, Blocked, Cancelled and
531
+ Done all happen there — so a status kept in the repo as well is a copy somebody
532
+ has to keep in step by hand, and on the base branch it was already wrong (an
533
+ in-flight spec still reads `backlog` there). The split follows what each side
534
+ can actually know:
535
+
536
+ 1. **The repo owns the content** — Problem, Decisions, phases, checkboxes,
537
+ Changelog. Content follows branches, lands in the same commit as its code,
538
+ and is read offline by the agent building it. That is why specs did not move
539
+ into the tracker wholesale: a ticket has no branches.
540
+ 2. **The tracker owns status and assignee** — `sync.fieldOwnership`
541
+ `workflowState` and `assignee` ship as **`pull`**. Under `pull` the skills
542
+ write no `Status:` header, no `Developer:` line and no State log row (the
543
+ `spec-status-owner` seam asks `spec-sync ownership` first), `assign` writes
544
+ the ticket directly, and the repo stores nothing it reads.
545
+ 3. **Buckets are code facts**, not planning status: `backlog` (not started),
546
+ `in-progress` (`/spec-start` ran), `complete` (landed — merged on the host
547
+ under PR landing), `cancelled` (torn down). Only skills that act on code move
548
+ them.
549
+ 4. **The repo writes status only when it acts on code** — creation, start,
550
+ complete, cancel — detected as a bucket move, never on a push that merely
551
+ cannot tell. Under PR landing the complete transition waits for run 2: a
552
+ ready PR is not a merged one.
553
+ 5. **A board that finished first is reported, never obeyed.** `spec-sync board`
554
+ says one line when the ticket is Done or Cancelled while the spec is still in
555
+ flight, naming the cleanup; `/spec-start` and `/spec-next` warn and carry on,
556
+ `/spec-status` reports. Nobody is obliged to sync, because nothing reads the
557
+ bucket as planning truth any more.
558
+
559
+ `"push"` on either field restores the repo-owned behaviour; `"none"` leaves it
560
+ alone entirely. Without a provider none of this applies: the header, the State
561
+ log and the buckets keep their meaning, because there is nowhere else for status
562
+ to live. Releases and deployments are the host project's to record. The one
563
+ release question skitterspec answers is which tickets a commit range contains
564
+ (`spec-sync released <range> --json`, each row with its spec and url), because
565
+ only the `Refs:` trailers know. What the project's CI does with that list is its
566
+ own business.
509
567
 
510
568
  **One-way means the repo wins, and it now wins *loudly*.** Those are different
511
569
  claims and only the first was ever in doubt. A ticket's description is generated
@@ -538,13 +596,14 @@ disk at all. The tracker knows both, and each row carries the spec's folder name
538
596
  so `/spec-start <name>` is a copy-paste away. See the provider's own docs for
539
597
  what it calls the command.
540
598
 
541
- A provider may also mirror **who is building a spec**, as one more field the repo
542
- owns. Where it does, `/spec-start` records the developer and the tracker's ticket
543
- is assigned to them, the assignment is released when the spec completes, and
544
- `/spec-claim` moves ownership mid-flight — take it, hand it back, or hand it to a
545
- teammate. Like everything else here it is opt-in and one-way: the spec file is
546
- the record, and the ticket is the mirror. See the provider's own docs for how to
547
- turn it on.
599
+ A provider also knows **who is building a spec**, and under the default `pull`
600
+ the ticket's assignee is the record: `/spec-start` assigns the operator only when
601
+ nobody holds the ticket (`assign --if-unassigned`), never reassigns anyone, and
602
+ leaves the assignee in place when the spec finishes — the board keeps who did
603
+ the work. `/spec-claim` moves ownership mid-flight — take it, hand it back, or
604
+ hand it to a teammate — by writing the ticket directly. Under `push` the spec
605
+ file is the record and the ticket the mirror, as before. See the provider's own
606
+ docs for both.
548
607
 
549
608
  **Every skill that moves a spec through the lifecycle carries a seam**, so the
550
609
  mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
@@ -635,6 +694,56 @@ its phases. It carries `> **Severity:**` (Azure's literal values,
635
694
  unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
636
695
  onto the tracker item as a comment.
637
696
 
697
+ ### Kind routing — any door, the right spec
698
+
699
+ `/spec` is the default door, so the kind of work someone describes does not
700
+ always match the skill they typed — especially for someone new, for whom
701
+ "spec it" is the reflex. Every entry skill therefore
702
+ **watches its grill for the signals that mark the other kinds**, and proposes a
703
+ hand-off the moment one appears — never at the end of a grill already shaping
704
+ the wrong spec:
705
+
706
+ | In | Watches for | Hands to |
707
+ |----|-------------|----------|
708
+ | `/spec` | defect · defect on a released version · live outage | `/spec-bug` · `/spec-hotfix` · `/spec-incident` |
709
+ | `/spec-bug` | on a released version · live outage · not a defect | `/spec-hotfix` · `/spec-incident` · `/spec` |
710
+ | `/spec-hotfix` | live outage · not on a released version · not a defect | `/spec-incident` · `/spec-bug` · `/spec` |
711
+ | `/spec-incident` | no live outage to record | defect → `/spec-bug` (on a released version → `/spec-hotfix`), else `/spec` |
712
+
713
+ Feature, chore and issue all route to `/spec` — one door for the three kinds it
714
+ writes, where its kind proposal picks between them. Example signals, weighed in
715
+ context rather than matched as keywords: a **defect** is behaviour differing
716
+ from intended — "it's broken", a failing flow, a stack trace of a failure;
717
+ **on a released version** is that defect where what is deployed is named — "in
718
+ prod", "since v2.1"; a **live outage** is a service down or degraded
719
+ **right now**, users affected as we speak; **not a defect** is an ask for new or
720
+ changed behaviour rather than for restoring intended behaviour.
721
+
722
+ Three rules, the same in every skill:
723
+
724
+ - **Always confirm; never silently switch.** Name the signal in the user's own
725
+ words and propose the destination with a one-line reason; the user confirms
726
+ or declines. A decline ends the matter — the grill carries on where it was,
727
+ and the same signal is not raised again. A signal is a question, never a
728
+ verdict: a pasted stack trace in "handle this error nicely" is a feature
729
+ request, not a bug report.
730
+ - **Precedence: incident > hotfix > bug.** One description can carry several
731
+ signals; propose the most specific destination — the same reasoning the
732
+ intake label routing documents for hotfix-over-bug.
733
+ - **Hand off in-session, carrying the context.** On a confirmed switch the
734
+ current skill invokes the destination skill directly and seeds it with
735
+ everything the grilling has already established — symptom, version, impact,
736
+ repro material, decisions so far — so the destination grills only what it
737
+ still needs ("seed, don't skip, the grill", the principle issue adoption
738
+ already uses). Stop-and-retype is the **label** routing's shape, and right
739
+ there because it fires before any grilling; mid-grill it would throw away
740
+ the answers already given.
741
+
742
+ This is judgment, not configuration: the signals are examples, there is no
743
+ list to maintain, and nothing here reads a label. A ticketing provider's
744
+ intake label routing (`intake.bugLabels` / `intake.hotfixLabels`) is a
745
+ separate, earlier check and is unchanged by this.
746
+
638
747
  All six types share the same lifecycle folders below — type is orthogonal to
639
748
  status.
640
749
 
@@ -663,6 +772,10 @@ Every spec header carries:
663
772
  (one-way; the repo owns the link), and `/spec-complete` on the incident
664
773
  counts the spec among its fixes. Absent on everything else.
665
774
 
775
+ **Under a provider's default `pull`, these three are the tracker's** —
776
+ `Status:`, `Developer:` and the State log — and new specs carry
777
+ `> **Tracker:** <url>` instead; see the ticketing section above. A spec that already has them keeps them as history.
778
+
666
779
  Every spec also has a **State log** table — the audit trail of folder/status
667
780
  transitions. Each lifecycle skill appends exactly one row when it changes state:
668
781
 
@@ -448,7 +448,7 @@ behind it — say nothing rather than reporting that there was nothing to report
448
448
  | `Built` | What the run produced — the code, the edits, the spec written. |
449
449
  | `Tests` | The result and the command that produced it. |
450
450
  | `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
451
- | `Landed` | A fast-forward, a tag, a cherry-pick. |
451
+ | `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure). |
452
452
  | `Worktree` | A worktree provisioned, entered, or torn down. |
453
453
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
454
454
  | `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |