@skitterbyte/skitterspec-linear 19.0.0 → 19.1.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.
package/MIGRATION.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # Migration guide
2
2
 
3
+ ## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
4
+
5
+ Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
6
+ provider can map spec kinds to its own idiom. Configs without a mapping keep
7
+ working unchanged: an unmapped kind mints the provider's default type exactly
8
+ as before, and `System.Description` stays Azure's body field unless a type is
9
+ mapped away from it. `skitterspec update` ships the new skills and rules.
10
+
11
+ **Create tracker types and states before mapping them.** A mapping names
12
+ something the tracker must already have:
13
+
14
+ - **Azure Boards** — create the custom inherited type (e.g. `Chore`) and its
15
+ states in your process, then set
16
+ `azure.workItemTypeByKind: { "chore": "Chore" }`. To fill a Bug form's Repro
17
+ Steps instead of the hidden Description, set
18
+ `azure.bodyFieldByType: { "Bug": "Microsoft.VSTS.TCM.ReproSteps" }` — it
19
+ applies symmetrically to create, update, read-back and the edited-hash
20
+ compare, so `/spec-status` stays quiet after a push. Bugs minted before the
21
+ mapping keep reading their Description until the next push rewrites them.
22
+ `spec-sync doctor --check-remote` verifies every mapped type exists and
23
+ carries its body field.
24
+ - **GitHub** — `github.labelsByKind: { "chore": "chore" }` adds the kind's
25
+ label beside the spec marker.
26
+ - **Jira** — `jira.issueTypeByKind: { "bug": "Bug", "chore": "Task" }` picks
27
+ the mint type per kind; the type must exist in the project.
28
+ - **Linear** — `linear.labelsByKind: { "chore": "Chore" }` labels the mint;
29
+ the label must already exist on the team (a missing one is a one-line note,
30
+ never a failed push).
31
+
3
32
  ## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
4
33
 
5
34
  Skitterspec now tells GitHub about **its own** transitions and nothing
@@ -580,7 +580,7 @@ through to a documented conservative default; see the field notes below.
580
580
  - `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
581
581
  - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
582
582
  (safe for a `COMPOSE_PROJECT_NAME`).
583
- - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
583
+ - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
584
584
 
585
585
  ## Pruning orphaned test-DB volumes
586
586
 
@@ -2,7 +2,8 @@
2
2
  "linear": {
3
3
  "teamKey": "",
4
4
  "teamId": "",
5
- "projectId": ""
5
+ "projectId": "",
6
+ "labelsByKind": {}
6
7
  },
7
8
  "intake": {
8
9
  "label": "",
@@ -34,7 +34,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
34
34
  "teamKey": "", // human-facing key, e.g. "ENG" — the RECORDED key;
35
35
  // see "Renaming a team" below (optional)
36
36
  "teamId": "", // Linear team UUID (the issue's team)
37
- "projectId": "" // DEFAULT for the project picker (see below)
37
+ "projectId": "", // DEFAULT for the project picker (see below)
38
+ "labelsByKind": {} // one label per spec kind (feature/bug/hotfix/chore,
39
+ // from the folder prefix), applied at mint —
40
+ // e.g. { "chore": "Chore" }. The label must already
41
+ // exist on the team; a missing one is a one-line
42
+ // note, never a failed push
38
43
  },
39
44
 
40
45
  // Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
@@ -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) Grill to a clear shared understanding, 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) 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) |
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
  | `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
@@ -587,23 +587,36 @@ none of them describes.
587
587
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
588
588
  (architecture, code style, testing, database, etc.) rather than restating them.
589
589
 
590
- ## Spec types — Feature, Bug, Hotfix
590
+ ## Spec types — Feature, Chore, Bug, Hotfix
591
591
 
592
- Every spec is one of three types, recorded **both** in the header and the filename:
592
+ Every spec is one of four types, recorded **both** in the header and the filename:
593
593
 
594
- - **Header field:** `> **Type:** Feature`, `> **Type:** Bug`, or
595
- `> **Type:** Hotfix` (authoritative, greppable:
594
+ - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
595
+ `> **Type:** Bug`, or `> **Type:** Hotfix` (authoritative, greppable:
596
596
  `grep -rl 'Type:.*Hotfix' specs/`).
597
- - **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs,
598
- `hotfix-<name>` for hotfixes (visible in listings; glob-safe — never use
599
- `[BUG]`/`[FEATURE]` brackets).
597
+ - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
598
+ `bug-<name>` for bugs, `hotfix-<name>` for hotfixes (visible in listings;
599
+ glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
600
+
601
+ A **Chore** is work no end user sees — tooling, CI, dependency bumps, internal
602
+ refactors. The line: anything that is not work end users see or functions they
603
+ use within the app is a chore; everything user-facing is a feature. There is no
604
+ separate entry skill — `/spec` **proposes** feature or chore from what the
605
+ grilling defined, with a one-line reason, and the user confirms. A chore
606
+ defaults its `Gating:` to `none: not user-facing` (where gating is configured),
607
+ and its commits default to `chore`/`refactor`/`ci` types with **no**
608
+ `Release-Note:` footer — a chore is by definition not user-visible, so it has
609
+ no release note to write. Feature specs keep `feat`; bug specs keep `fix`.
610
+ Where a ticketing provider maps kinds to tracker types (e.g. Azure's
611
+ `workItemTypeByKind`), the chore mapping is what keeps tooling work off the
612
+ customer-facing release ladder.
600
613
 
601
614
  A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
602
615
  carries an extra `> **Base version:** <tag>` header, forks its worktree from that
603
616
  tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
604
617
  fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
605
618
 
606
- All three types share the same lifecycle folders below — type is orthogonal to
619
+ All four types share the same lifecycle folders below — type is orthogonal to
607
620
  status.
608
621
 
609
622
  ## Header fields & State log (audit trail)
@@ -231,8 +231,34 @@ again on the **same** `--since`. Not a fresh one — a pass that arrived during
231
231
  the gap is still inside the original window, and re-arming on a new timestamp
232
232
  would strand exactly that pass.
233
233
 
234
- **Say nothing when you do it.** Nothing happened and the window is unchanged; a
235
- line on every death turns a working loop into a stream of non-events.
234
+ **Say as little as the harness allows when you do it.** Nothing happened and
235
+ the window is unchanged; a line on every death turns a working loop into a
236
+ stream of non-events. Where the harness lets a turn end on the tool call, the
237
+ tool call is the whole turn. Where it insists on visible text — Claude Code
238
+ does, after a monitor event — that text is one fixed line,
239
+ `Still waiting for the verdict.`, and nothing else: not the spec, not the age,
240
+ not the links. The wait's own start line arriving as an event is answered the
241
+ same way.
242
+
243
+ **Every fifth re-arm, show the banner again.** Even one line per re-arm adds
244
+ up: over a long idle they push the verdict line and the banner's links out of
245
+ sight, and a reader who comes back has to scroll for the URL that lets them
246
+ answer. So `review wait` counts the starts on each window, and on every fifth
247
+ re-arm its start line is followed by `re-show: banner (re-arm N)` and the stack.
248
+ Relay that as the run's **verdict line** — copied from the block when it is
249
+ still in context, dropped rather than reconstructed when it is not — and then
250
+ **the banner** in its current state, with its stack copied from the `re-show:`
251
+ lines. Not the table: that would be a second block.
252
+
253
+ **A count here, not an age**, and the bound below is unaffected. What buries
254
+ the banner is how many re-arms have scrolled past it, and a death every five
255
+ minutes and one every forty-five push it up the same distance each. The age of
256
+ the window still decides when to stop.
257
+
258
+ **And it is not a third control after the block.** It is the banner this file
259
+ already defines, repeated in whatever state it is in — past the bound, that is
260
+ the degraded sentence below. No block is repeated, so nothing follows a second
261
+ one, and nothing about the banner's shape changes.
236
262
 
237
263
  **An operator who stopped it is not a death** — re-arming over a deliberate
238
264
  stop makes the wait unstoppable, which is worse than a wait that stops. But a
@@ -142,8 +142,8 @@ because writing it means reading the diff, and that spend is the user's call.
142
142
 
143
143
  **A watch that dies is re-armed on the same window**, silently and bounded by
144
144
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
145
- including when to stop and what the banner says instead. Do not restate it
146
- here.
145
+ including when to stop, what the banner says instead, and when the
146
+ engine's `re-show:` brings the banner back. Do not restate it here.
147
147
 
148
148
  ```
149
149
  skitterspec spec-env review <name> --claim-since <the timestamp> --json
@@ -188,9 +188,31 @@ not write the spec until this is resolved.
188
188
  Stop grilling when there are no unresolved branches that would change the spec.
189
189
  Briefly play back the agreed understanding before writing.
190
190
 
191
+ ### Propose the kind — feature or chore
192
+
193
+ This skill writes two kinds of spec, and
194
+ **you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
195
+ The
196
+ line that decides it: a **chore** is anything that is not work end users see or
197
+ functions they use within the app — tooling, CI, dependency bumps, internal
198
+ refactors. Everything user-facing is a **feature**. So the proposal reads like
199
+ *"no user-visible surface → chore"* or *"adds an endpoint users call → feature"*.
200
+
201
+ The kind is recorded twice, and both follow from the answer: the folder prefix
202
+ (`feat-` / `chore-`) and the `> **Type:**` header (`Feature` / `Chore`). A chore
203
+ also defaults its `Gating:` to `none: not user-facing` (only when gating is
204
+ configured — offer the default, let the user override it like any other
205
+ answer), and its commits default to `chore`/`refactor`/`ci` types with no
206
+ `Release-Note:` (see `.claude/rules/spec-planning.md`).
207
+
208
+ There is no `/spec-chore` and none should be added: one entry point, one grill,
209
+ and the kind is an output of understanding the work rather than a door the user
210
+ must pick before describing it.
211
+
191
212
  ## Phase B — write the spec
192
213
 
193
- This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
214
+ This skill is for **features and chores**. For bugs, use `/spec-bug`
215
+ (test-first, red→green).
194
216
 
195
217
  ### Write it in its own worktree
196
218
 
@@ -257,8 +279,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
257
279
  that phase's goal, its task checkboxes (tests included), and any phase-specific
258
280
  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
259
281
  into `00-overview.md`. This keeps each phase easy to dive into on its own.
260
- - Choose a short kebab-case name and **prefix it `feat-`** (the bug counterpart
261
- uses `bug-`).
282
+ - Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
283
+ a feature, `chore-` for a chore (the bug counterpart uses `bug-`).
262
284
 
263
285
  Use this template (keep it **as concise as possible** — no filler, no restating
264
286
  the codebase, link rather than duplicate):
@@ -266,8 +288,8 @@ the codebase, link rather than duplicate):
266
288
  ```markdown
267
289
  # <Feature title>
268
290
 
269
- > **Type:** Feature
270
- > **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
291
+ > **Type:** <Feature or Chore — the kind proposed after Phase A>
292
+ > **Name:** <feat- or chore-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
271
293
  > **Status:** Ready — not started
272
294
  > **Author:** <git user.name — `git config user.name`>
273
295
  > **Developer:** —
@@ -276,7 +298,8 @@ the codebase, link rather than duplicate):
276
298
  > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
277
299
  > services; only acted on when isolation is enabled — see Phase A item 9>
278
300
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
279
- > is configured; omit the line entirely otherwise. An empty value or a bare
301
+ > is configured; omit the line entirely otherwise. A chore defaults to
302
+ > "none: not user-facing". An empty value or a bare
280
303
  > "none" is not a valid outcome — see Phase A item 10>
281
304
 
282
305
  ## Problem
@@ -538,8 +561,8 @@ the verdict — and the reader's conclusion is about what the page showed them.
538
561
 
539
562
  **A watch that dies is re-armed on the same window**, silently and bounded by
540
563
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
541
- including when to stop and what the banner says instead. Do not restate it
542
- here.
564
+ including when to stop, what the banner says instead, and when the
565
+ engine's `re-show:` brings the banner back. Do not restate it here.
543
566
 
544
567
  ```
545
568
  skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
@@ -571,8 +571,8 @@ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
571
571
 
572
572
  **A watch that dies is re-armed on the same window**, silently and bounded by
573
573
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
574
- including when to stop and what the banner says instead. Do not restate it
575
- here.
574
+ including when to stop, what the banner says instead, and when the
575
+ engine's `re-show:` brings the banner back. Do not restate it here.
576
576
 
577
577
  **Why this skill arms as well as waits.** Waiting is what any offer does;
578
578
  **arming** asserts an obligation that outlives the turn, and belongs only to
@@ -506,8 +506,8 @@ reading — and that is the gap the whole gate exists to close.
506
506
 
507
507
  **A watch that dies is re-armed on the same window**, silently and bounded by
508
508
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
509
- including when to stop and what the banner says instead. Do not restate it
510
- here.
509
+ including when to stop, what the banner says instead, and when the
510
+ engine's `re-show:` brings the banner back. Do not restate it here.
511
511
 
512
512
  Then **end your turn**. Do not poll it and do not hold the turn open: the
513
513
  point is that the reader has the terminal back while they read.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.0.0",
3
+ "version": "19.1.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -119,6 +119,9 @@ const {
119
119
  passesSince,
120
120
  waitForPass,
121
121
  WAIT_HEARTBEAT_MS,
122
+ WAIT_RESHOW_EVERY,
123
+ recordWaitStart,
124
+ reshowDue,
122
125
  waitingPasses,
123
126
  describePending,
124
127
  pendingAge,
@@ -903,7 +906,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
903
906
  try {
904
907
  spec = resolveSpecWithWorktree(dir, config, specArg)
905
908
  } catch (err) {
906
- const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
909
+ const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore)-./.test(specArg)
907
910
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
908
911
  throw err
909
912
  }
@@ -2761,6 +2764,74 @@ function resolveHeartbeatMs(flags) {
2761
2764
  return seconds * 1000
2762
2765
  }
2763
2766
 
2767
+ /**
2768
+ * Every this-many re-arms the stack is printed again. Default 5, `0` disables.
2769
+ * A value that is not a whole number takes the DEFAULT rather than disabling
2770
+ * (`.claude/rules/negative-checks.md` rule 4), the same as `--heartbeat`.
2771
+ */
2772
+ function resolveReshowEvery(flags) {
2773
+ if (flags.reshowEvery === undefined || flags.reshowEvery === null) return WAIT_RESHOW_EVERY
2774
+ const n = Number(flags.reshowEvery)
2775
+ if (!Number.isInteger(n) || n < 0) return WAIT_RESHOW_EVERY
2776
+ return n
2777
+ }
2778
+
2779
+ /**
2780
+ * The review server that is running, read and never touched — or null.
2781
+ *
2782
+ * NOT `ensureReviewServer`. That one adopts, and where a server is stale it
2783
+ * replaces it, and a re-show that restarted the server would kill the link
2784
+ * open on the reader's phone in order to remind them of it. This reads the
2785
+ * pidfile and the settings and stops there.
2786
+ *
2787
+ * WHAT WOULD FOOL THIS: a pidfile left by a crash names a pid the OS may have
2788
+ * reused for something else. `isAlive` cannot tell those apart, so the URL it
2789
+ * offers could point at nothing — the same blind spot every adopt has, and the
2790
+ * cost is a dead link in a reminder, never a lost pass.
2791
+ */
2792
+ function readRunningReviewServer(dir, config) {
2793
+ const abs = (rel) => path.resolve(dir, rel)
2794
+ const settingsFile = `${stateDirLabel(config)}/review-serve.json`
2795
+ const proc = serveProcFor(config, abs(settingsFile), { root: dir })
2796
+ const pid = readPid(abs(proc.pidFile))
2797
+ if (!pid || !isAlive(pid)) return null
2798
+ let settings = null
2799
+ try {
2800
+ settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
2801
+ } catch {
2802
+ return null
2803
+ }
2804
+ if (!settings || !settings.port) return null
2805
+ return {
2806
+ port: settings.port,
2807
+ token: settings.token || null,
2808
+ loopback: settings.host === '127.0.0.1' || settings.host === 'localhost',
2809
+ }
2810
+ }
2811
+
2812
+ /**
2813
+ * The stack a re-show prints: the same tiers and `live` a render reports, from
2814
+ * the same functions, with nothing rendered and nothing started.
2815
+ */
2816
+ function reshowStack(dir, config, spec, out) {
2817
+ const cfg = withSpecRemote(config, out)
2818
+ const up = readRunningReviewServer(dir, cfg)
2819
+ const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
2820
+ const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg })
2821
+ let live = null
2822
+ try {
2823
+ const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
2824
+ live = liveStateFor(
2825
+ spec,
2826
+ liveContext(dir, cfg, spec, { onBase: primaryState.onBase, primaryBranch: primaryState.branch }),
2827
+ )
2828
+ } catch {
2829
+ // Cannot tell whether it is live — print no line rather than a wrong one.
2830
+ live = null
2831
+ }
2832
+ return { tiers, live }
2833
+ }
2834
+
2764
2835
  async function specEnvReviewWait(dir, config, specArg, flags) {
2765
2836
  let spec
2766
2837
  try {
@@ -2794,10 +2865,28 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
2794
2865
  // SAID BEFORE THE FIRST POLL, not after it. The whole point is that a caller
2795
2866
  // knows the wait is running; a line printed on the way out would arrive only
2796
2867
  // for the waits that already worked.
2868
+ //
2869
+ // WHICH START THIS IS, counted per window. A wait that dies is re-armed on the
2870
+ // same `--since`, and every re-arm leaves a trace in the conversation, so
2871
+ // after enough of them the banner and its links have scrolled out of sight.
2872
+ // Every `reshowEvery`th re-arm prints the stack again, read-only, for the
2873
+ // skill to relay as the banner.
2874
+ const reshowEvery = resolveReshowEvery(flags)
2875
+ const started = recordWaitStart(out, spec.folder, flags.since)
2876
+ const rearm = started ? started.rearm : null
2877
+ const reshow = reshowDue(rearm, reshowEvery)
2878
+ const stack = reshow ? reshowStack(dir, config, spec, out) : null
2879
+
2797
2880
  if (!flags.json) {
2798
2881
  process.stdout.write(
2799
2882
  `spec-env review wait: ${spec.folder} — waiting for a verdict sent since ${flags.since}` +
2800
- `${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}\n`,
2883
+ `${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}` +
2884
+ `${rearm ? ` (re-arm ${rearm})` : ''}\n` +
2885
+ (stack
2886
+ ? ` re-show: banner (re-arm ${rearm})\n` +
2887
+ stack.tiers.map((t) => reviewTierLine(t) + '\n').join('') +
2888
+ (liveStateLine(stack.live) ? `${liveStateLine(stack.live)}\n` : '')
2889
+ : ''),
2801
2890
  )
2802
2891
  }
2803
2892
 
@@ -2827,7 +2916,20 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
2827
2916
  })
2828
2917
 
2829
2918
  if (flags.json) {
2830
- process.stdout.write(`${JSON.stringify({ spec: spec.folder, since: flags.since, ...result }, null, 2)}\n`)
2919
+ process.stdout.write(
2920
+ `${JSON.stringify(
2921
+ {
2922
+ spec: spec.folder,
2923
+ since: flags.since,
2924
+ rearm,
2925
+ reshow,
2926
+ ...(stack ? { tiers: stack.tiers, live: stack.live } : {}),
2927
+ ...result,
2928
+ },
2929
+ null,
2930
+ 2,
2931
+ )}\n`,
2932
+ )
2831
2933
  }
2832
2934
 
2833
2935
  if (result.state === 'arrived') {
@@ -5617,6 +5719,7 @@ async function specEnv(rest) {
5617
5719
  claim: null,
5618
5720
  offered: false,
5619
5721
  heartbeat: null,
5722
+ reshowEvery: null,
5620
5723
  drop: null,
5621
5724
  buttons: null,
5622
5725
  json: false,
@@ -5652,6 +5755,7 @@ async function specEnv(rest) {
5652
5755
  else if (args[i] === '--claim') flags.claim = args[++i]
5653
5756
  else if (args[i] === '--claim-since') flags.claimSince = args[++i]
5654
5757
  else if (args[i] === '--heartbeat') flags.heartbeat = args[++i]
5758
+ else if (args[i] === '--reshow-every') flags.reshowEvery = args[++i]
5655
5759
  else if (args[i] === '--since') flags.since = args[++i]
5656
5760
  else if (args[i] === '--timeout') flags.timeout = args[++i]
5657
5761
  else if (args[i] === '--drop') flags.drop = args[++i]
@@ -5831,6 +5935,7 @@ async function specEnv(rest) {
5831
5935
  ' review skip [spec] "<reason>" move on without one, on the record\n' +
5832
5936
  ' review gate [spec] --offered record that the bypass was offered (spends it)\n' +
5833
5937
  ' review wait [spec] --heartbeat <secs> proof-of-life cadence on stderr; 0 disables\n' +
5938
+ ' review wait [spec] --reshow-every <n> print the stack again every nth re-arm (5); 0 disables\n' +
5834
5939
  ' review wait [spec] --since <iso> block until a verdict arrives ([--timeout <s>])\n' +
5835
5940
  ' review waiting [--json] every pass waiting, across every spec\n' +
5836
5941
  ' review [spec] --claim-since <iso> claim the one pass that arrived since <iso>\n' +
@@ -4,7 +4,8 @@
4
4
  * Pure spec/branch resolution for per-spec isolation.
5
5
  *
6
6
  * Given a spec argument (a folder name or path) it locates the spec folder under
7
- * `specs/**`, splits the `feat-`/`bug-` prefix into `{ type, slug }`, derives the
7
+ * `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-` prefix into
8
+ * `{ type, slug }`, derives the
8
9
  * git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
9
10
  * is filled from a tracker id when one is configured, else it falls back to
10
11
  * `{type}/{slug}`), and expands the config's path/name tokens (`{repo}`,
@@ -294,10 +295,10 @@ function phaseIsDone(text) {
294
295
  return /^#\s.*✅\s*$/m.test(text)
295
296
  }
296
297
 
297
- // Split a `feat-`/`bug-`/`hotfix-` prefix. Unknown prefix → type defaults to
298
- // `feat` and the whole folder name is the slug.
298
+ // Split a `feat-`/`bug-`/`hotfix-`/`chore-` prefix. Unknown prefix → type
299
+ // defaults to `feat` and the whole folder name is the slug.
299
300
  function splitPrefix(folder) {
300
- const m = /^(feat|bug|hotfix)-(.+)$/.exec(folder)
301
+ const m = /^(feat|bug|hotfix|chore)-(.+)$/.exec(folder)
301
302
  if (m) return { type: m[1], slug: m[2] }
302
303
  return { type: 'feat', slug: folder }
303
304
  }
@@ -498,6 +499,12 @@ function assertPrimaryOnMain(config, git) {
498
499
  * was actually created against, and re-deriving it would go wrong the moment a
499
500
  * project changed its pattern under a standing branch.
500
501
  *
502
+ * A `chore-foo` SPEC derives the same `chore/foo` branch as `/no-spec foo`
503
+ * does, deliberately left colliding: both cannot exist at once, and git
504
+ * refuses the second `worktree add -b` loudly rather than either lane
505
+ * silently adopting the other's branch (spec feat-chore-kind-bug-bodies,
506
+ * decision 9).
507
+ *
501
508
  * Pure but for `repoInfo`, like `resolveSpec`.
502
509
  */
503
510
  function resolveSpecless(name, dir, config, entry = {}) {
package/src/env/review.js CHANGED
@@ -1282,6 +1282,81 @@ const WAIT_POLL_MS = 400
1282
1282
  // whatever is supervising the process.
1283
1283
  const WAIT_HEARTBEAT_MS = 5 * 60 * 1000
1284
1284
 
1285
+ // Every this-many re-arms on one window, the wait prints the stack again. A
1286
+ // COUNT, not an interval, and deliberately: what buries the banner is how many
1287
+ // re-arms have scrolled past it, and a death every five minutes and one every
1288
+ // forty-five push it up the same distance each. This is not the count
1289
+ // `spec-reports.md` rejects — that one bounded how long to keep waiting, and
1290
+ // the 12-hour age bound below still does.
1291
+ const WAIT_RESHOW_EVERY = 5
1292
+
1293
+ // How old a window may be before its start count is pruned. The same 12 hours
1294
+ // the skills stop re-arming at: past it nobody is counting, so nothing is kept.
1295
+ const WAIT_WINDOW_MAX_MS = 12 * 60 * 60 * 1000
1296
+
1297
+ // Beside the pending store, under gitignored `.spec-env/`.
1298
+ const WAITS_SUFFIX = '.waits.json'
1299
+
1300
+ function reviewWaitsPath(outPath) {
1301
+ return outPath.replace(/\.html$/, '') + WAITS_SUFFIX
1302
+ }
1303
+
1304
+ /**
1305
+ * Record that a wait started on `since`, and say which start this is.
1306
+ * Returns `{ starts, rearm }` — `rearm` is 0 for the first wait on a window —
1307
+ * or `null` when it cannot tell.
1308
+ *
1309
+ * CANNOT-TELL IS NULL, and null means no re-show (`.claude/rules/negative-checks.md`
1310
+ * rule 4). A store that will not parse, a window that is not a timestamp, a
1311
+ * write that failed: each costs the reader one reminder, never a verdict, so
1312
+ * none of them is worth more than silence. An unreadable store is also never
1313
+ * written over — it may be someone's history.
1314
+ *
1315
+ * WHAT WOULD FOOL THIS: it counts STARTS, so anything that runs `review wait`
1316
+ * on the same window counts too — a second session waiting on one spec, or a
1317
+ * person running it by hand. That over-counts, and the cost is a banner shown
1318
+ * a little early, which is the harmless direction.
1319
+ */
1320
+ function recordWaitStart(outPath, specFolder, since, { now = Date.now() } = {}) {
1321
+ if (!Number.isFinite(Date.parse(since))) return null
1322
+ const file = reviewWaitsPath(outPath)
1323
+ let store = { version: 1, spec: specFolder, windows: {} }
1324
+ let raw = null
1325
+ try {
1326
+ raw = fs.readFileSync(file, 'utf8')
1327
+ } catch {}
1328
+ if (raw !== null) {
1329
+ try {
1330
+ const parsed = JSON.parse(raw)
1331
+ if (!parsed || typeof parsed.windows !== 'object' || parsed.windows === null) return null
1332
+ store = { version: parsed.version || 1, spec: parsed.spec || specFolder, windows: parsed.windows }
1333
+ } catch {
1334
+ return null
1335
+ }
1336
+ }
1337
+ const windows = {}
1338
+ for (const [key, count] of Object.entries(store.windows)) {
1339
+ const at = Date.parse(key)
1340
+ if (Number.isFinite(at) && now - at <= WAIT_WINDOW_MAX_MS) windows[key] = count
1341
+ }
1342
+ const prior = Number.isInteger(windows[since]) && windows[since] > 0 ? windows[since] : 0
1343
+ const starts = prior + 1
1344
+ windows[since] = starts
1345
+ try {
1346
+ fs.mkdirSync(path.dirname(file), { recursive: true })
1347
+ fs.writeFileSync(file, JSON.stringify({ ...store, windows }, null, 2) + '\n')
1348
+ } catch {
1349
+ return null
1350
+ }
1351
+ return { starts, rearm: starts - 1 }
1352
+ }
1353
+
1354
+ // Is this re-arm one that re-shows the stack? Pure. The first wait never does —
1355
+ // the banner is right above it — and `every` of 0 turns it off.
1356
+ function reshowDue(rearm, every = WAIT_RESHOW_EVERY) {
1357
+ return Number.isInteger(every) && every > 0 && Number.isInteger(rearm) && rearm > 0 && rearm % every === 0
1358
+ }
1359
+
1285
1360
  /**
1286
1361
  * Block until exactly one pass arrives inside a window. Impure only in that it
1287
1362
  * reads the store and sleeps; it writes nothing and claims nothing.
@@ -2555,6 +2630,10 @@ module.exports = {
2555
2630
  waitingPasses,
2556
2631
  waitForPass,
2557
2632
  WAIT_HEARTBEAT_MS,
2633
+ WAIT_RESHOW_EVERY,
2634
+ recordWaitStart,
2635
+ reshowDue,
2636
+ reviewWaitsPath,
2558
2637
  WAIT_POLL_MS,
2559
2638
  passState,
2560
2639
  describePending,
@@ -330,6 +330,16 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
330
330
  )
331
331
  return (data && data.issues && data.issues.nodes) || []
332
332
  },
333
+ // A team's issue labels, for resolving a configured label NAME
334
+ // (linear.labelsByKind) to the id a create wants. Team-scoped labels and
335
+ // the workspace ones the team inherits both answer here.
336
+ async listLabels(teamId) {
337
+ const data = await call(
338
+ `query($id: String!) { team(id: $id) { labels { nodes { id name } } } }`,
339
+ { id: teamId },
340
+ )
341
+ return (data && data.team && data.team.labels && data.team.labels.nodes) || []
342
+ },
333
343
  async listProjects(teamId) {
334
344
  const data = teamId
335
345
  ? await call(`query($id: String!) { team(id: $id) { projects { nodes { id name } } } }`, { id: teamId })
@@ -2226,8 +2226,32 @@ function describeRefusal(error) {
2226
2226
  * stripped (`withoutNull`) except the assignee clear, and the refusal texts
2227
2227
  * name Linear and its commands.
2228
2228
  */
2229
- async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false }) {
2229
+ // A spec's KIND, read off its folder prefix — the same convention the
2230
+ // lifecycle skills stamp into `> **Type:**`, but greppable with no file read.
2231
+ function specKindOf(snapshotDir) {
2232
+ const name = path.basename(String(snapshotDir || ''))
2233
+ if (name.startsWith('bug-')) return 'bug'
2234
+ if (name.startsWith('hotfix-')) return 'hotfix'
2235
+ if (name.startsWith('chore-')) return 'chore'
2236
+ return 'feature'
2237
+ }
2238
+
2239
+ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false, out = null }) {
2230
2240
  const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states) : null)
2241
+ // THIS spec's kind label (linear.labelsByKind), resolved name → id once per
2242
+ // apply. A label Linear does not have is a one-line note and an unlabelled
2243
+ // mint, never a failed push — and with nothing configured, no label call is
2244
+ // made at all.
2245
+ const kindLabelName = (config.linear && config.linear.labelsByKind && config.linear.labelsByKind[specKindOf(snapshotDir)]) || ''
2246
+ let kindLabelIds = null
2247
+ if (kindLabelName && teamId && typeof adapter.listLabels === 'function') {
2248
+ const labels = await adapter.listLabels(teamId)
2249
+ const hit = labels.find((l) => l && String(l.name).toLowerCase() === kindLabelName.toLowerCase())
2250
+ if (hit) kindLabelIds = [hit.id]
2251
+ else if (out) out.write(` !! label "${kindLabelName}" is not on the team — minted without it\n`)
2252
+ } else if (kindLabelName && out && typeof adapter.listLabels !== 'function') {
2253
+ out.write(` !! label "${kindLabelName}" skipped — this transport cannot list labels\n`)
2254
+ }
2231
2255
  const ops = {
2232
2256
  prevalidateStates: (buckets) => {
2233
2257
  for (const bucket of buckets) stateId(bucket)
@@ -2250,6 +2274,8 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2250
2274
  // Assert only. An issue being minted has no assignee to retract, so
2251
2275
  // `withoutNull` dropping a null here is exactly right.
2252
2276
  assigneeId: (issue && issue.assignee) || null,
2277
+ // The kind's label, when configured and resolved above; null drops out.
2278
+ labelIds: kindLabelIds,
2253
2279
  }))
2254
2280
  if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
2255
2281
  return created
@@ -2404,7 +2430,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2404
2430
  out.write(`spec-sync apply: ${error.message}\n`)
2405
2431
  return 1
2406
2432
  }
2407
- const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew }
2433
+ const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew, out }
2408
2434
 
2409
2435
  if (!bulk) {
2410
2436
  const lines = ['spec-sync apply: transport = api']
@@ -113,7 +113,17 @@ const DEFAULT_CONFIG = Object.freeze({
113
113
  // call only and never stored in the spec or the snapshot, so a PM re-homing the
114
114
  // issue in Linear is invisible to sync. (The old `initiativeId` grouped
115
115
  // Projects, which no longer exist.)
116
- linear: Object.freeze({ teamKey: '', teamId: '', projectId: '' }),
116
+ linear: Object.freeze({
117
+ teamKey: '',
118
+ teamId: '',
119
+ projectId: '',
120
+ // One label per SPEC KIND (`feature`/`bug`/`hotfix`/`chore`, from the spec
121
+ // folder's prefix), applied at mint when set — `{ "chore": "Chore" }`
122
+ // keeps tooling work filterable out of release views. The label must
123
+ // already exist on the team; a missing one is a one-line note, never a
124
+ // failed push. Empty means no kind label, as before.
125
+ labelsByKind: Object.freeze({}),
126
+ }),
117
127
  // Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
118
128
  // inbox filter — issues carrying it are what the web app files; `bugLabels`
119
129
  // route an issue to `/spec-bug` instead of `/spec`, and `hotfixLabels` route it
@@ -264,7 +274,7 @@ const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
264
274
  // A fresh, deeply-mutable copy of the defaults to merge onto.
265
275
  function defaults() {
266
276
  return {
267
- linear: { ...DEFAULT_CONFIG.linear },
277
+ linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind } },
268
278
  intake: {
269
279
  label: DEFAULT_CONFIG.intake.label,
270
280
  bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
@@ -315,6 +325,16 @@ function mergeConfig(base, parsed) {
315
325
  assign(base.linear, parsed.linear, 'teamKey', 'string?')
316
326
  assign(base.linear, parsed.linear, 'teamId', 'string?')
317
327
  assign(base.linear, parsed.linear, 'projectId', 'string?')
328
+ if (isObject(parsed.linear.labelsByKind)) {
329
+ // Only the kinds a spec folder can actually be — an unknown key is
330
+ // dropped, matching the other providers' by-kind validation.
331
+ const byKind = {}
332
+ for (const kind of ['feature', 'bug', 'hotfix', 'chore']) {
333
+ const value = parsed.linear.labelsByKind[kind]
334
+ if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
335
+ }
336
+ base.linear.labelsByKind = byKind
337
+ }
318
338
  }
319
339
 
320
340
  if (isObject(parsed.intake)) {
@@ -405,15 +405,39 @@ function readSnapshot(snapshotDir, config) {
405
405
  return { frontmatter: data, title, sections, phases, body }
406
406
  }
407
407
 
408
+ // The headings a bug-shaped spec's ticket leads with, in this order, when the
409
+ // spec has them. A Bug ticket is read for its repro before anything else, and
410
+ // the feature overview order buries it. Sections a spec does not have are
411
+ // skipped, never invented — a legacy bug spec with feature-shaped sections
412
+ // renders exactly as it always did.
413
+ const BUG_LEAD_SECTIONS = ['Symptom', 'Repro', 'Expected', 'Actual', 'Root cause', 'Failing test (red)', 'Fix']
414
+
415
+ // A spec's kind off its folder prefix — the same convention the providers'
416
+ // `specKindOf` reads, kept local because sync-core depends on no other package.
417
+ function bugShaped(snapshotDir) {
418
+ const name = path.basename(String(snapshotDir || ''))
419
+ return name.startsWith('bug-') || name.startsWith('hotfix-')
420
+ }
421
+
408
422
  // Build the pushed description: the overview prose with local-only sections
409
423
  // removed. Keeps the title line for context. `extraSkip` drops additional
410
424
  // sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
411
425
  // the phase list isn't duplicated in the description — Decision 5).
412
- function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
426
+ // `leadSections` names headings to emit FIRST, in its order, matched
427
+ // case-insensitively; the rest follow in document order. Empty means document
428
+ // order throughout — byte-identical to before the parameter existed.
429
+ function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect, leadSections = []) {
413
430
  const skip = new Set([...(localOnlySections || []), ...extraSkip])
414
431
  const parts = []
415
432
  if (title) parts.push(`# ${title}`)
416
- for (const [heading, content] of Object.entries(sections)) {
433
+ const entries = Object.entries(sections)
434
+ const lead = []
435
+ for (const want of leadSections) {
436
+ const hit = entries.find(([heading]) => heading.toLowerCase() === want.toLowerCase())
437
+ if (hit) lead.push(hit)
438
+ }
439
+ const ordered = [...lead, ...entries.filter((e) => !lead.includes(e))]
440
+ for (const [heading, content] of ordered) {
417
441
  if (skip.has(heading)) continue
418
442
  parts.push(`## ${heading}\n\n${content}`.trim())
419
443
  }
@@ -706,6 +730,10 @@ function normalizeLocal(snapshotDir, config) {
706
730
  config.sync.localOnlySections,
707
731
  phasesCarriedBySubIssues ? ['Phases'] : [],
708
732
  dialect,
733
+ // A bug or hotfix spec's ticket leads with the bug sections — a
734
+ // different render of the same overview, so the Bug form opens on the
735
+ // repro rather than the feature-shaped prose.
736
+ bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
709
737
  ),
710
738
  inlined,
711
739
  tasksMode,