@skitterbyte/skitterspec-jira 2.3.0 → 2.5.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 (67) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/SETUP.md +5 -0
  3. package/assets/core/env.config.json.example +1 -0
  4. package/assets/core/env.config.md +143 -8
  5. package/assets/core/jira.config.md +4 -2
  6. package/assets/hooks/main-guard.cjs +40 -6
  7. package/assets/hooks/review-gate.cjs +42 -7
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +81 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +55 -2
  12. package/assets/skills/spec-bug/SKILL.md +25 -1
  13. package/assets/skills/spec-cancel/SKILL.md +35 -0
  14. package/assets/skills/spec-complete/SKILL.md +113 -0
  15. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  16. package/assets/skills/spec-incident/SKILL.md +22 -0
  17. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  18. package/assets/skills/spec-next/SKILL.md +9 -4
  19. package/assets/skills/spec-push/SKILL.md +22 -0
  20. package/assets/skills/spec-review/SKILL.md +32 -0
  21. package/assets/skills/spec-start/SKILL.md +39 -1
  22. package/assets/skills/spec-status/SKILL.md +18 -3
  23. package/assets/skills/spec-sync/SKILL.md +1 -0
  24. package/assets/skills/spec-to-main/SKILL.md +47 -1
  25. package/package.json +1 -1
  26. package/src/cli.js +1188 -79
  27. package/src/env/base.js +104 -0
  28. package/src/env/bootstrap.js +22 -3
  29. package/src/env/classify.js +12 -4
  30. package/src/env/config.js +77 -5
  31. package/src/env/disposition.js +62 -0
  32. package/src/env/handoff.js +81 -0
  33. package/src/env/host.js +262 -0
  34. package/src/env/hotfix.js +237 -9
  35. package/src/env/hotfixland.js +105 -10
  36. package/src/env/inflight.js +98 -0
  37. package/src/env/integrate.js +136 -9
  38. package/src/env/live.js +8 -7
  39. package/src/env/mainguard.js +20 -5
  40. package/src/env/phases.js +28 -0
  41. package/src/env/project.js +223 -0
  42. package/src/env/provision.js +30 -8
  43. package/src/env/resolve.js +147 -25
  44. package/src/env/review.js +21 -7
  45. package/src/env/reviewers.js +7 -10
  46. package/src/env/serve.js +27 -11
  47. package/src/env/specstate.js +101 -0
  48. package/src/env/supervise.js +15 -2
  49. package/src/env/teardown.js +46 -3
  50. package/src/init.js +49 -9
  51. package/src/vendor/jira/cli-sync.js +48 -4
  52. package/src/vendor/jira/config.js +17 -5
  53. package/src/vendor/provider-kit/index.js +4 -0
  54. package/src/vendor/provider-kit/src/apply.js +58 -6
  55. package/src/vendor/provider-kit/src/assignment.js +78 -1
  56. package/src/vendor/provider-kit/src/config.js +34 -1
  57. package/src/vendor/provider-kit/src/credentials.js +7 -2
  58. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  59. package/src/vendor/provider-kit/src/released.js +48 -4
  60. package/src/vendor/provider-kit/src/specs.js +18 -7
  61. package/src/vendor/provider-kit/src/splice.js +64 -0
  62. package/src/vendor/provider-kit/src/status.js +137 -0
  63. package/src/vendor/sync-core/index.js +14 -1
  64. package/src/vendor/sync-core/src/compare.js +81 -6
  65. package/src/vendor/sync-core/src/normalize.js +50 -7
  66. package/src/vendor/sync-core/src/push.js +65 -5
  67. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -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:
@@ -37,6 +37,28 @@ it verbatim/condensed for the header.
37
37
 
38
38
  ## 4. Stamp the spec
39
39
 
40
+ **Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
41
+ Run `skitterspec spec-sync ownership --json` once and read both values:
42
+
43
+ - **`workflowState: "pull"`** — Jira is the record of this spec's status, so
44
+ this skill **writes no `> **Status:**` header and appends no State log row**,
45
+ wherever its steps below say to. A spec this skill creates gets neither: its
46
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
47
+ has stamped the url, and its body has no `## State log` section. Readiness is
48
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
49
+ empty — so nothing is lost with the header.
50
+ - **`assignee: "pull"`** — Jira holds who is building it, so this skill
51
+ **writes no `> **Developer:**` line** either.
52
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
53
+ — is cannot-tell, and the steps below run exactly as written.
54
+
55
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
56
+ the code, not a planning status), the phase files and index, and the Changelog.
57
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
58
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
59
+ any of these lines keeps them untouched: they are history, and nothing rewrites
60
+ them.
61
+
40
62
  Update the **Status** header in the entry point so the reason is visible at the
41
63
  top:
42
64
 
@@ -75,6 +97,10 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
75
97
  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
76
98
  and the next push repairs it. Do not roll anything back, and do not stop to
77
99
  ask.
100
+ - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
101
+ a PR, and a ready PR is not a merged one — so skip it on run 1, even where
102
+ the `branch` lane committed the move to ride the PR, and run it on run 2 once
103
+ the host has merged. The tracker's Done lands when the work does.
78
104
  - **Say what happened** in the skill's report: mirror updated, skipped as
79
105
  unlinked, or failed with the reason.
80
106
  - **There is no assignment to release here.** Assignment sync is not yet
@@ -252,6 +278,15 @@ only ordering that survives.
252
278
  copy of abandoned work. Seeing no such section here is the expected case, not
253
279
  a fault — and if the user wants the remote branch gone anyway, that is their
254
280
  call to make explicitly, not something to tidy away on their behalf.
281
+
282
+ **In PR mode the same confirm-first section may carry the PR abandon**
283
+ (`gh pr close` / `az repos pr update --status abandoned`): a cancelled spec
284
+ must not leave a live PR behind — it is noise with a merge button on it.
285
+ The teardown of an open-PR spec is refused unforced (the PR is named), so
286
+ this line appears on the forced run the refusal led to; ask before running
287
+ it like the delete above, and run the abandon **before** any remote branch
288
+ delete — closing the PR first is what stops the host complaining about a
289
+ deleted source branch.
255
290
  4. `skitterspec spec-env prune` — reap orphaned test-DB volumes that belong to no
256
291
  live spec (leftovers from declined/aborted teardowns or manual worktree
257
292
  removal). Show the orphan list and, **only on the user's confirmation**, run
@@ -102,6 +102,29 @@ feature was designed not to disturb.
102
102
 
103
103
  - Tick all completed tasks in the phase files; flip every finished phase-file
104
104
  heading **and** every row in the `00-overview.md` phase index to `✅`.
105
+
106
+ **Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
107
+ Run `skitterspec spec-sync ownership --json` once and read both values:
108
+
109
+ - **`workflowState: "pull"`** — Jira is the record of this spec's status, so
110
+ this skill **writes no `> **Status:**` header and appends no State log row**,
111
+ wherever its steps below say to. A spec this skill creates gets neither: its
112
+ header carries `> **Tracker:** <issue url>` instead, filled in once linking
113
+ has stamped the url, and its body has no `## State log` section. Readiness is
114
+ the spec's own content — a `Draft` is a spec whose **Open questions** is not
115
+ empty — so nothing is lost with the header.
116
+ - **`assignee: "pull"`** — Jira holds who is building it, so this skill
117
+ **writes no `> **Developer:**` line** either.
118
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
119
+ — is cannot-tell, and the steps below run exactly as written.
120
+
121
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
122
+ the code, not a planning status), the phase files and index, and the Changelog.
123
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
124
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
125
+ any of these lines keeps them untouched: they are history, and nothing rewrites
126
+ them.
127
+
105
128
  - Set the **Status** header in the entry point:
106
129
  `> **Status:** Complete (<YYYY-MM-DD>)`.
107
130
  - Append a **State log** row:
@@ -136,6 +159,10 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
136
159
  complete/cancelled/reviewed in the repo regardless; the mirror is disposable
137
160
  and the next push repairs it. Do not roll anything back, and do not stop to
138
161
  ask.
162
+ - **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
163
+ a PR, and a ready PR is not a merged one — so skip it on run 1, even where
164
+ the `branch` lane committed the move to ride the PR, and run it on run 2 once
165
+ the host has merged. The tracker's Done lands when the work does.
139
166
  - **Say what happened** in the skill's report: mirror updated, skipped as
140
167
  unlinked, or failed with the reason.
141
168
  - **There is no assignment to release here.** Assignment sync is not yet
@@ -288,6 +315,27 @@ in that order, and stops at the first step that fails:
288
315
  **Then stop: the worktree is kept** (step 7). The branch is what the next
289
316
  `-hotfix.N` is cut from if this deploy fails, so it waits for the deploy.
290
317
 
318
+ **A branch-based hotfix** (`> **Base version:** <branch>@<sha>`, from
319
+ `hotfix.releaseBranch`) runs the same command and the same consent ask — the
320
+ engine picks the path from the header. What differs is what it does:
321
+
322
+ - it **rebases** onto `<remote>/<branch>` and **lands on the release branch** by
323
+ `land.strategy`: under `ff` the push of the hotfix onto that branch *is* the
324
+ land (so the consent ask names the release branch, not only a tag); under `pr`
325
+ it pushes the hotfix branch and opens a **ready** PR, then holds with
326
+ `the PR into <branch> is open` — re-run the same command once it merges;
327
+ - the **tag** is optional (`hotfix.tag`): cut and pushed after the land, or not
328
+ at all;
329
+ - the **carry** goes to the resolved base — the current rc under
330
+ `baseBranchPattern` — directly under `ff`, through a `carry/<slug>` branch and
331
+ its own ready PR under `pr`.
332
+
333
+ `Landed` then names the release branch, how it landed (fast-forward, or the PR
334
+ and whether it merged), the tag if one was cut, and the carry. A PR still
335
+ waiting on its merge is a `⚠️` — the land is not done until the host says so.
336
+ `spec-env hotfix finish` tears it down once both the land and the carry are
337
+ confirmed, naming every check that is not.
338
+
291
339
  ### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
292
340
 
293
341
  Land the finished branch on the base branch so the work reaches `main` (or your
@@ -323,6 +371,19 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
323
371
  `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
324
372
  to the user; do not tear anything down.
325
373
  On a **no-op** ("already landed"), just say so and continue.
374
+
375
+ **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
376
+ can carry two more things, and both are the engine's to say:
377
+ - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
378
+ when the primary checkout still has an older release candidate out — run it
379
+ in order with the rest;
380
+ - a `retarget: forked from <old> · landing onto <new>` line, when the rc
381
+ rolled while this spec was in flight. It is the land working, not a fault:
382
+ relay it verbatim in the `Landed` row so the reader sees where the work went.
383
+
384
+ A refusal naming `no branch matches <pattern>` means no release candidate is
385
+ visible — usually not fetched. Relay it, stop with `⏸`, and name
386
+ `skitterspec spec-env base` (it fetches and lists) as the next step.
326
387
  3. **Run the after-land commands.** Where the plan ends with a
327
388
  `then, in the primary checkout (<path>), run:` section — the project's
328
389
  `afterLand`, such as a data migration — run those commands in that
@@ -342,6 +403,58 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
342
403
  5. **Report** the landing (base branch, fast-forward result). It **never pushes** —
343
404
  mention the user can `git push` the base branch themselves.
344
405
 
406
+ ### 6-pr. PR mode (`land.strategy: "pr"`) — dispose, push, ready; finish after the merge
407
+
408
+ Completion is **two runs** here, the `hotfix land`/`finish` shape: the merge is
409
+ the host's act and may be days away, so the run that readies the PR cannot also
410
+ finalise. Which run this is, the engine says: `spec-env integrate <name>`
411
+ printing a `(pr)` plan is run 1; printing
412
+ `already landed … — finish what the merge deferred` is run 2.
413
+
414
+ **Run 1 — the last control point.** Once the PR is ready, anyone can merge from
415
+ the host UI and the tracker's automations act — so everything that needs a
416
+ person happens before the ready, in this order:
417
+
418
+ 1. **Disposition pass — mandatory, before anything is pushed.** Run
419
+ `skitterspec spec-env disposition <name> --json`. For every unticked task,
420
+ non-✅ phase and surfaced follow-up it lists, the user disposes it:
421
+ **tick** (it was done — tick it, naming the evidence) · **spin off** (a
422
+ follow-on ticket minted now, linked to this one — offer `/spec` or the
423
+ provider's mint) · **drop** (a dated Changelog line with the reason, the
424
+ `none: <reason>` grammar). Batch the asking; never decide for them, and
425
+ never auto-create. **Refuse to ready the PR while anything is undisposed**
426
+ — you asked the enumeration, so it cannot also be fine. `clean` proceeds
427
+ with nothing asked.
428
+ 2. **Consent, naming the target.** Ask once, plainly:
429
+ *"push `<branch>` and open the PR into `<base>` on `<remote>`, ready for
430
+ merge?"* — the base branch is named so a spec that outlived a release roll
431
+ is caught by the person reading a stale rc name. On a no, stop with the
432
+ held commands relayed.
433
+ 3. **Run the plan.** `skitterspec spec-env integrate <name> --push` and run
434
+ what it prints: fetch, rebase onto `<remote>/<base>`, the push, and the PR
435
+ create — or, where a draft already exists, the flip-to-ready. A rebase
436
+ conflict aborts and stops exactly as 6-feature/bug step 2.
437
+ 4. **Defer the finalise.** §4's bucket move follows the spec documents'
438
+ `land.specDocs` lane: under `trunk` leave the spec in `specs/in-progress/`
439
+ — run 2 moves it on base after the merge; under `branch` commit the move on
440
+ the branch *before* step 3 so it rides the PR. Either way
441
+ **the tracker's Done waits for run 2**: a ready PR is not a merged one.
442
+ 5. **Stop, keeping the worktree.** Report
443
+ `Landed: PR #N opened — finish after merge` (or `ready`), spec
444
+ `In Progress`, worktree standing. No afterLand runs — the plan deferred it
445
+ — and no teardown. The merge is what un-blocks run 2; nothing here waits on
446
+ it.
447
+
448
+ **Run 2 — after the host merges.** `integrate` recognises the landed branch
449
+ (ancestry or the host's answer) and prints the finish: catch local base up and
450
+ the deferred `afterLand` with the land's own range. Run those, then do what run
451
+ 1 deferred — the §4 move (trunk lane) with its State log row and commit, the
452
+ §5 report — then **§7 teardown runs as normal**:
453
+ a host-merged branch counts as landed (squash and rebase
454
+ merges included), and a host that auto-deleted the branch makes the remote
455
+ delete an already-gone no-op, never a failure. Re-test on base before calling
456
+ it done, exactly as 6-feature/bug step 4.
457
+
345
458
  ## 7. Tear down the environment (opt-in, only if configured)
346
459
 
347
460
  **A hotfix is torn down later, by `hotfix finish`.**
@@ -148,6 +148,16 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
148
148
 
149
149
  ## 1. Establish the base version (the tag)
150
150
 
151
+ **A release BRANCH instead of a tag.** Where `env.config.json` sets
152
+ `hotfix.releaseBranch` (e.g. `"master"` — a team whose prod is whatever that
153
+ branch holds), there is **no tag to ask for**: skip the questions below and run
154
+ §3's `up` **without `--from`**. The engine fetches, forks from the remote's head
155
+ of that branch, and prints two lines — `fork:` naming the commit, and
156
+ `record: > **Base version:** <branch>@<sha>` — and §5 copies that `record:`
157
+ value into the header **verbatim**. Say which commit it forked from in one line;
158
+ that is the version the fix is built on. The rest of this section is the tag
159
+ flow, unchanged.
160
+
151
161
  - **Read the arguments.** `/spec-hotfix <tag> <name>` (e.g.
152
162
  `/spec-hotfix v33.16.4 login-crash`). An argument shaped like an issue
153
163
  reference — letters, a hyphen, digits (`SKI-123`) —
@@ -265,6 +275,10 @@ installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
265
275
  and a step whose documented opening the repo will not perform is not a step. The
266
276
  spec is written in the worktree at §5, on the branch it belongs to.
267
277
 
278
+ **Branch-based (`hotfix.releaseBranch`):** run the same command **without**
279
+ `--from` — the engine picks the release branch's head and prints the
280
+ `record:` line §5 copies. An explicit `--from` still wins over it.
281
+
268
282
  **§5 records the same tag you passed to `--from`**, on the spec's
269
283
  `> **Base version:**` header. That is not bookkeeping: `/spec-complete` cuts the
270
284
  release and carries the fix off the header, so a worktree forked from one ref and
@@ -303,6 +317,28 @@ you there, so create the folder and write it here. A hotfix
303
317
  is usually a single-pass fix, so the `## Fix` block can live directly in
304
318
  `00-overview.md`. Keep it lean:
305
319
 
320
+ **Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
321
+ Run `skitterspec spec-sync ownership --json` once and read both values:
322
+
323
+ - **`workflowState: "pull"`** — Jira 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"`** — Jira holds who is building it, so this skill
331
+ **writes no `> **Developer:**` line** either.
332
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
333
+ — is cannot-tell, and the steps below run exactly as written.
334
+
335
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
336
+ the code, not a planning status), the phase files and index, and the Changelog.
337
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
338
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
339
+ any of these lines keeps them untouched: they are history, and nothing rewrites
340
+ them.
341
+
306
342
  ```markdown
307
343
  # Hotfix: <short title>
308
344
 
@@ -311,7 +347,7 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
311
347
  > **Status:** In Progress — fixing (red test added)
312
348
  > **Author:** <git user.name — who reported/captured it>
313
349
  > **Developer:** <git user.name — you, since you're fixing it now>
314
- > **Base version:** <tag prod is running, e.g. v33.16.4>
350
+ > **Base version:** <tag prod is running, e.g. v33.16.4 — or, branch-based, the `record:` value `up` printed, e.g. master@1a2b3c4d5e6f>
315
351
  > **Raised:** <YYYY-MM-DD (today)>
316
352
  > **Area:** <files/modules>
317
353
  > **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
@@ -390,7 +426,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
390
426
  behaves exactly as above. When present, link the spec you just wrote so status
391
427
  and discussion live in Jira while the repo stays the source of truth. A spec is
392
428
  a Jira **issue**; each phase is a **subtask**, carrying that phase's tasks in
393
- its description as a read-only checklist.
429
+ its description as a read-only checklist. That is the `spec` description mode;
430
+ under `summary` (a new config's default) the issue and each sub-issue carry
431
+ a short block instead, and the phase's tasks stay in git.
394
432
 
395
433
  **Linking is just the first push**, so it runs the same engine path `/spec-push`
396
434
  does — you never create the issue by hand:
@@ -72,6 +72,28 @@ this spec. Without isolation, write where you stand.
72
72
  The spec is a folder in **`specs/in-progress/`** — never backlog — with
73
73
  `00-overview.md` and one phase file:
74
74
 
75
+ **Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
76
+ Run `skitterspec spec-sync ownership --json` once and read both values:
77
+
78
+ - **`workflowState: "pull"`** — Jira 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"`** — Jira holds who is building it, so this skill
86
+ **writes no `> **Developer:**` line** either.
87
+ - **Anything else** — `push`, `none`, sync reported off, or the command failing
88
+ — is cannot-tell, and the steps below run exactly as written.
89
+
90
+ What `pull` leaves alone: the folder move (a bucket records what the repo did to
91
+ the code, not a planning status), the phase files and index, and the Changelog.
92
+ A reason a `Status:` header would have carried — a cancellation's, a knock-back
93
+ to Draft — goes in a dated Changelog line instead. A spec that already carries
94
+ any of these lines keeps them untouched: they are history, and nothing rewrites
95
+ them.
96
+
75
97
  ```markdown
76
98
  # Incident: <short title>
77
99