@skitterbyte/skitterspec-jira 2.3.0 → 2.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 (57) 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/jira.config.md +4 -2
  5. package/assets/hooks/main-guard.cjs +18 -2
  6. package/assets/hooks/review-gate.cjs +19 -2
  7. package/assets/rules/commit-trailers.md +24 -1
  8. package/assets/rules/spec-planning.md +81 -18
  9. package/assets/rules/spec-reports.md +1 -1
  10. package/assets/skills/spec/SKILL.md +55 -2
  11. package/assets/skills/spec-bug/SKILL.md +25 -1
  12. package/assets/skills/spec-cancel/SKILL.md +35 -0
  13. package/assets/skills/spec-complete/SKILL.md +113 -0
  14. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  15. package/assets/skills/spec-incident/SKILL.md +22 -0
  16. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  17. package/assets/skills/spec-next/SKILL.md +9 -4
  18. package/assets/skills/spec-push/SKILL.md +22 -0
  19. package/assets/skills/spec-review/SKILL.md +32 -0
  20. package/assets/skills/spec-start/SKILL.md +39 -1
  21. package/assets/skills/spec-status/SKILL.md +18 -3
  22. package/assets/skills/spec-sync/SKILL.md +1 -0
  23. package/assets/skills/spec-to-main/SKILL.md +47 -1
  24. package/package.json +1 -1
  25. package/src/cli.js +1091 -39
  26. package/src/env/base.js +104 -0
  27. package/src/env/config.js +75 -3
  28. package/src/env/disposition.js +62 -0
  29. package/src/env/handoff.js +80 -0
  30. package/src/env/host.js +262 -0
  31. package/src/env/hotfix.js +225 -0
  32. package/src/env/hotfixland.js +103 -9
  33. package/src/env/inflight.js +95 -0
  34. package/src/env/integrate.js +130 -4
  35. package/src/env/mainguard.js +6 -0
  36. package/src/env/phases.js +28 -0
  37. package/src/env/provision.js +18 -6
  38. package/src/env/resolve.js +108 -9
  39. package/src/env/serve.js +6 -1
  40. package/src/env/specstate.js +101 -0
  41. package/src/env/teardown.js +42 -0
  42. package/src/vendor/jira/cli-sync.js +45 -3
  43. package/src/vendor/jira/config.js +17 -5
  44. package/src/vendor/provider-kit/index.js +4 -0
  45. package/src/vendor/provider-kit/src/apply.js +49 -4
  46. package/src/vendor/provider-kit/src/assignment.js +78 -1
  47. package/src/vendor/provider-kit/src/config.js +34 -1
  48. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  49. package/src/vendor/provider-kit/src/released.js +14 -1
  50. package/src/vendor/provider-kit/src/specs.js +4 -2
  51. package/src/vendor/provider-kit/src/splice.js +64 -0
  52. package/src/vendor/provider-kit/src/status.js +137 -0
  53. package/src/vendor/sync-core/index.js +14 -1
  54. package/src/vendor/sync-core/src/compare.js +17 -5
  55. package/src/vendor/sync-core/src/normalize.js +50 -7
  56. package/src/vendor/sync-core/src/push.js +26 -2
  57. 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`).
@@ -11,14 +11,16 @@ NAMES — never a credential. Credentials live in the user-level store
11
11
  | `jira.issueType` | The issue type a spec mints as. | `"Task"` |
12
12
  | `jira.issueTypeByKind` | The mint type per spec kind (`feature`/`bug`/`hotfix`/`chore`, from the folder prefix), falling back to `jira.issueType` — `{ "bug": "Bug" }` files bug specs as Jira Bugs. The type must exist in the project before mapping it. | `{}` |
13
13
  | `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
14
- | `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
14
+ | `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline` \| `none`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
15
+ | `mapping.description` | What a ticket body carries. `"summary"`: a delimited block (summary, acceptance criteria, surfaces touched, gating, spec path) spliced in beside the team's own text, which no push touches; phase sub-issues get a block with their goal. `"spec"`: the whole overview, replacing the body (the behaviour before this key). A config without the key is `spec`, so an upgrade rewrites no ticket. | `spec` |
16
+ | `summary.delimiter` | How the block is marked: `"comment"` (HTML comments, hidden on the rendered ticket) or `"heading"` (a `## Skitterspec summary` heading and an end line). Provisional for this tracker until `chore-delimiter-spike-providers` measures which survives its editor. A delimiter someone edited is reported and the block is left unwritten, never guessed at. | `heading` |
15
17
  | `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
16
18
  | `statesByType.<issue type>.<bucket>` | Per-TYPE override laid over `states` — statuses belong to the type's workflow, so `{ "Service Request": { "complete": "Closed" } }` completes that type differently. A bucket set to `null` sends no status; validation checks each type against its own workflow. | `{}` |
17
19
  | `jira.severityField` | The field id the `Severity:` header is written to (e.g. `customfield_10900`). Empty, the header stays repo-only. A fix spec's `Incident:` header adds a `Relates` issue link to its incident, once. | `""` |
18
20
  | `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
19
21
  | `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
20
22
  | `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
21
- | `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
23
+ | `sync.fieldOwnership` | Who owns each field. The repo pushes `description` and `subIssues`; Jira owns `workflowState` and `assignee` (`pull`: the state is sent only on a bucket move, the assignee never projected). `"push"` restores the repo-owned behaviour; `"none"` declines a field. | content `push`, status and assignee `pull` |
22
24
  | `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
23
25
 
24
26
  Descriptions are stored as ADF (Atlassian Document Format): the adapter
@@ -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 }
@@ -87,10 +87,33 @@ and it is cancelled along with it.
87
87
 
88
88
  ## Why it exists
89
89
 
90
- The repo lands specs with `merge --ff-only`, so history is linear and branch
90
+ In trunk mode the repo lands specs with `merge --ff-only`, so history is linear and branch
91
91
  names never reach it. The commit message is the only artefact that survives into
92
92
  the range a release scans, which is what lets
93
93
  `spec-sync released <range>` report the tickets a release contains. A ref that
94
94
  names the wrong ticket does not merely lose information — it moves a commit onto
95
95
  another ticket's release report, which is worse than the gap it was meant to
96
96
  close.
97
+
98
+ ## Merge styles, and which range still holds the trailers
99
+
100
+ Trunk mode keeps this simple: `merge --ff-only` means linear history and every
101
+ trailer survives. PR mode (`land.strategy: "pr"`) hands the merge to the host,
102
+ and no merge style is required — teams pick their own — so the scan copes
103
+ per style instead:
104
+
105
+ - **Merge commits** — every branch commit survives, trailers intact. A
106
+ trailer-less merge commit counts as transport, never as an unreferenced gap —
107
+ while a merge that CARRIES a trailer still counts, because a hand merge is
108
+ where a ticket's only trailer sometimes lives.
109
+ - **Squashed feature PRs** — the branch's commits collapse into one. The
110
+ trailers survive when the squash message keeps the commit bodies (GitHub:
111
+ the "Default commit message" squash setting; Azure DevOps: keep the commit
112
+ descriptions in the squash message) — `released` counts every `Refs:` line
113
+ in the one body, so a squashed PR carrying three commits still reports three
114
+ tickets.
115
+ - **A squashed integration-to-release merge** — one commit for a whole cycle,
116
+ and attribution on the release branch is gone by construction. No setting
117
+ fixes that: point `released <range>` at the integration branch's range
118
+ instead, where the commits still exist. The range argument has always been
119
+ 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
@@ -713,6 +772,10 @@ Every spec header carries:
713
772
  (one-way; the repo owns the link), and `/spec-complete` on the incident
714
773
  counts the spec among its fixes. Absent on everything else.
715
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
+
716
779
  Every spec also has a **State log** table — the audit trail of folder/status
717
780
  transitions. Each lifecycle skill appends exactly one row when it changes state:
718
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. |
@@ -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/jira.config.json` exists.
336
+ Run `skitterspec spec-sync ownership --json` once and read both values:
337
+
338
+ - **`workflowState: "pull"`** — Jira 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"`** — Jira 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 Jira while the repo stays the source of truth. A spec is
673
724
  a Jira **issue**; each phase is a **subtask**, 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/jira.config.json` exists.
295
+ Run `skitterspec spec-sync ownership --json` once and read both values:
296
+
297
+ - **`workflowState: "pull"`** — Jira 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"`** — Jira 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 Jira while the repo stays the source of truth. A spec is
371
393
  a Jira **issue**; each phase is a **subtask**, 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: