@skitterbyte/skitterspec-linear 19.1.0 → 19.2.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,47 @@
1
1
  # Migration guide
2
2
 
3
+ ## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
4
+
5
+ Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
6
+ manual steps) and **incidents** (`incident-` prefix, captured live by the new
7
+ `/spec-incident` skill; `/spec-complete` ends one by writing `incident-log.md`
8
+ and posting it onto the tracker item as a comment, via the new
9
+ `spec-sync comment <spec> --file <f>` verb). A lifecycle bucket can map to a
10
+ different state per work item type (`statesByType` on Azure Boards and Jira)
11
+ or per spec kind (`statesByKind` on GitHub and Linear), both top-level beside
12
+ `states`, with `null` meaning "send no state" — and the pre-write check now
13
+ validates each type's effective states against **that type's own** list, so a
14
+ state only one type lacks refuses before anything is written. On Azure and
15
+ Jira, `spec-sync states --json` now prints a per-type map
16
+ (`{ "<type>": [names] }`); a flat array from an older file is still accepted
17
+ and checked as the union. A fix spec can carry
18
+ `> **Incident:** incident-<name>` (linked as related on push) and
19
+ `> **Severity:**` (`1 - Critical` … `4 - Low`). Configs without any of the new
20
+ keys behave exactly as before, and `skitterspec update` ships the new skill
21
+ and rules.
22
+
23
+ Consumer config, by provider:
24
+
25
+ - **Azure Boards** —
26
+ `azure.workItemTypeByKind: { "issue": "Issue", "incident": "Incident" }`,
27
+ plus
28
+ `statesByType: { "Issue": { "complete": "Closed" }, "Incident": { "backlog": null, "complete": "Closed" } }`.
29
+ Severity writes the built-in `Microsoft.VSTS.Common.Severity` — nothing to
30
+ configure; a type without the field skips it with a note. The incident link
31
+ is `System.LinkTypes.Related`.
32
+ - **GitHub** — `github.labelsByKind` accepts the new kinds;
33
+ `statesByKind: { "issue": { "complete": "Done" } }` routes a kind's board
34
+ Status (`null` sends none); `github.severityLabels: { "2": "sev-high" }`
35
+ maps the header's leading digit to a label. The incident rides in the
36
+ generated body as a `Related incident: #N` line.
37
+ - **Jira** — `jira.issueTypeByKind` accepts the new kinds; `statesByType`
38
+ keys by issue type; `jira.severityField` names the field to write (e.g.
39
+ `customfield_10900`). The incident link is a `Relates` issue link, added
40
+ once.
41
+ - **Linear** — `linear.labelsByKind` accepts the new kinds; `statesByKind`
42
+ keys by spec kind; `linear.severityLabels` maps digits to team labels. The
43
+ incident link is a related-issue relation.
44
+
3
45
  ## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
4
46
 
5
47
  Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
package/README.md CHANGED
@@ -77,6 +77,7 @@ them. Your `specs/` content and live `.core` config are never touched.
77
77
  | `/spec` | Grill to a shared understanding, then write a groomed spec |
78
78
  | `/spec-bug` | Reproduce with a failing test, then drive it red→green |
79
79
  | `/spec-hotfix` | Fix the released version: fork from a tag, land by tag + cherry-pick |
80
+ | `/spec-incident` | Capture a live outage as a record written during it, fixes linked |
80
81
  | `/no-spec` | Work that genuinely has no spec — on its own branch all the same |
81
82
  | `/spec-review` | Re-validate a spec against the code; refresh what drifted |
82
83
  | `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 |
@@ -35,11 +35,16 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
35
35
  // see "Renaming a team" below (optional)
36
36
  "teamId": "", // Linear team UUID (the issue's team)
37
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
+ "labelsByKind": {}, // one label per spec kind (feature/bug/hotfix/chore/
39
+ // issue/incident, from the folder prefix), applied
40
+ // at mint — e.g. { "chore": "Chore" }. The label
41
+ // must already exist on the team; a missing one is
42
+ // a one-line note, never a failed push
43
+ "severityLabels": {} // one label per Severity: header digit
44
+ // ("2 - High" → "2") — e.g. { "2": "Sev High" },
45
+ // applied at mint. Unset, the header stays
46
+ // repo-only. A fix spec's Incident: header adds a
47
+ // related-issue relation to its incident
43
48
  },
44
49
 
45
50
  // Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
@@ -90,6 +95,11 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
90
95
  "cancelled": "Canceled"
91
96
  },
92
97
 
98
+ // Per-KIND override laid over `states` (Linear has no work item types, so
99
+ // the spec's kind keys it) — e.g. { "issue": { "complete": "Done" } }. A
100
+ // bucket set to null sends no state; a bucket an entry lacks falls through.
101
+ "statesByKind": {},
102
+
93
103
  // The spec's entry-point file the local snapshot + frontmatter live in.
94
104
  "snapshot": {
95
105
  "overviewFile": "00-overview.md"
@@ -7,9 +7,10 @@ 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) 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) |
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
+ | `/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/` |
13
14
  | `/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) |
14
15
  | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
15
16
  | `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
@@ -587,26 +588,34 @@ none of them describes.
587
588
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
588
589
  (architecture, code style, testing, database, etc.) rather than restating them.
589
590
 
590
- ## Spec types — Feature, Chore, Bug, Hotfix
591
+ ## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident
591
592
 
592
- Every spec is one of four types, recorded **both** in the header and the filename:
593
+ Every spec is one of six types, recorded **both** in the header and the filename:
593
594
 
594
595
  - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
595
- `> **Type:** Bug`, or `> **Type:** Hotfix` (authoritative, greppable:
596
+ `> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`, or
597
+ `> **Type:** Incident` (authoritative, greppable:
596
598
  `grep -rl 'Type:.*Hotfix' specs/`).
597
599
  - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
598
- `bug-<name>` for bugs, `hotfix-<name>` for hotfixes (visible in listings;
600
+ `issue-<name>` for issues, `bug-<name>` for bugs, `hotfix-<name>` for
601
+ hotfixes, `incident-<name>` for incidents (visible in listings;
599
602
  glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
600
603
 
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
604
+ A **Chore** is code work no end user sees — tooling, CI, dependency bumps,
605
+ internal refactors. An **Issue** is work with **no code change at all** —
606
+ in-app configuration, a data fix, a support task — written as a spec of manual
607
+ steps so there is a record and a history; everything user-facing that changes
608
+ code is a feature. There is no
609
+ separate entry skill for either — `/spec` **proposes** feature, chore or issue
610
+ from what the
605
611
  grilling defined, with a one-line reason, and the user confirms. A chore
606
612
  defaults its `Gating:` to `none: not user-facing` (where gating is configured),
607
613
  and its commits default to `chore`/`refactor`/`ci` types with **no**
608
614
  `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`.
615
+ no release note to write. An issue defaults its `Gating:` to `none: no code`
616
+ and its commits to `docs` with no `Release-Note:`, and it closes when the spec
617
+ completes — nothing is released. Feature specs keep `feat`; bug specs keep
618
+ `fix`.
610
619
  Where a ticketing provider maps kinds to tracker types (e.g. Azure's
611
620
  `workItemTypeByKind`), the chore mapping is what keeps tooling work off the
612
621
  customer-facing release ladder.
@@ -616,14 +625,25 @@ carries an extra `> **Base version:** <tag>` header, forks its worktree from tha
616
625
  tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
617
626
  fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
618
627
 
619
- All four types share the same lifecycle folders below — type is orthogonal to
628
+ An **Incident** is an outage or degradation of a live service, captured by
629
+ **`/spec-incident`** during the outage, so it starts straight in
630
+ `specs/in-progress/`. It is a record, not delivery work: its fixes are
631
+ separate hotfix, bug, chore or issue specs, each carrying
632
+ `> **Incident:** incident-<name>` so the push links them, and they are never
633
+ its phases. It carries `> **Severity:**` (Azure's literal values,
634
+ `1 - Critical` … `4 - Low`) and a `## Timeline` appended to as the incident
635
+ unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
636
+ onto the tracker item as a comment.
637
+
638
+ All six types share the same lifecycle folders below — type is orthogonal to
620
639
  status.
621
640
 
622
641
  ## Header fields & State log (audit trail)
623
642
 
624
643
  Every spec header carries:
625
644
 
626
- - `> **Name:**` — the spec's folder name (`feat-`/`bug-`/`hotfix-<kebab-name>`).
645
+ - `> **Name:**` — the spec's folder name
646
+ (`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-<kebab-name>`).
627
647
  It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
628
648
  in the header so it's copy-pasteable without digging for the folder name.
629
649
  - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
@@ -634,6 +654,14 @@ Every spec header carries:
634
654
  **only when `specs/.core/gating.config.json` exists**: a flag name, or
635
655
  `none: <one-line reason>`. Absent entirely in a project that has not adopted
636
656
  gating.
657
+ - `> **Severity:**` — on bug, hotfix and incident specs, optional except where
658
+ `/spec-incident` grills it: Azure's literal values
659
+ (`1 - Critical` … `4 - Low`). The push writes it where the provider has a
660
+ home for it; absent, nothing is sent.
661
+ - `> **Incident:**` — on a spec that is a **fix** for an open incident:
662
+ `incident-<name>`. The push links the two as related on the tracker
663
+ (one-way; the repo owns the link), and `/spec-complete` on the incident
664
+ counts the spec among its fixes. Absent on everything else.
637
665
 
638
666
  Every spec also has a **State log** table — the audit trail of folder/status
639
667
  transitions. Each lifecycle skill appends exactly one row when it changes state:
@@ -668,7 +696,7 @@ When asked for a plan, implementation strategy, or feature breakdown:
668
696
 
669
697
  ```
670
698
  specs/backlog/ Ready (or Draft) specs (/spec)
671
- specs/in-progress/ under active implementation (/spec-start, /spec-bug)
699
+ specs/in-progress/ under active implementation (/spec-start, /spec-bug, /spec-incident)
672
700
  specs/complete/ finished (/spec-complete)
673
701
  specs/cancelled/ abandoned, with a reason on the header (/spec-cancel)
674
702
  specs/.core/ project rules — ALWAYS APPLY, never moved
@@ -188,31 +188,42 @@ 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
191
+ ### Propose the kind — feature, chore or issue
192
192
 
193
- This skill writes two kinds of spec, and
193
+ This skill writes three kinds of spec, and
194
194
  **you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
195
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"*.
196
+ lines that decide it: a **chore** is code work no end user sees — tooling, CI,
197
+ dependency bumps, internal refactors. An **issue** is work with
198
+ **no code change at all** — in-app configuration, a data fix, a support task —
199
+ written as a spec of manual steps so there is a record and a history.
200
+ Everything user-facing that changes code is a **feature**. So the proposal
201
+ reads like *"no user-visible surface → chore"*, *"no code change, manual
202
+ steps → issue"* or *"adds an endpoint users call → feature"*.
200
203
 
201
204
  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
205
+ (`feat-` / `chore-` / `issue-`) and the `> **Type:**` header
206
+ (`Feature` / `Chore` / `Issue`). A chore
203
207
  also defaults its `Gating:` to `none: not user-facing` (only when gating is
204
208
  configured — offer the default, let the user override it like any other
205
209
  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.
210
+ `Release-Note:` (see `.claude/rules/spec-planning.md`). An issue defaults its
211
+ `Gating:` to `none: no code`, and its commits to `docs` with no
212
+ `Release-Note:` — its phases are manual steps, not code, though `/spec-start`
213
+ still gives it a worktree, because the document needs one and the history is
214
+ the point.
215
+
216
+ There is no `/spec-chore` or `/spec-issue` and none should be added: one entry
217
+ point, one grill, and the kind is an output of understanding the work rather
218
+ than a door the user must pick before describing it. The one kind with its own
219
+ door is the **incident** — an outage or degradation of a live service, which
220
+ needs a different grill and starts mid-flight — so when the grilling uncovers
221
+ one, hand off to **`/spec-incident`** rather than writing it here.
211
222
 
212
223
  ## Phase B — write the spec
213
224
 
214
- This skill is for **features and chores**. For bugs, use `/spec-bug`
215
- (test-first, red→green).
225
+ This skill is for **features, chores and issues**. For bugs, use `/spec-bug`
226
+ (test-first, red→green); for a live outage, `/spec-incident`.
216
227
 
217
228
  ### Write it in its own worktree
218
229
 
@@ -280,7 +291,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
280
291
  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
281
292
  into `00-overview.md`. This keeps each phase easy to dive into on its own.
282
293
  - 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-`).
294
+ a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
295
+ uses `bug-`, the incident one `incident-`).
284
296
 
285
297
  Use this template (keep it **as concise as possible** — no filler, no restating
286
298
  the codebase, link rather than duplicate):
@@ -288,8 +300,8 @@ the codebase, link rather than duplicate):
288
300
  ```markdown
289
301
  # <Feature title>
290
302
 
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`)
303
+ > **Type:** <Feature, Chore or Issue — the kind proposed after Phase A>
304
+ > **Name:** <feat-, chore- or issue-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
293
305
  > **Status:** Ready — not started
294
306
  > **Author:** <git user.name — `git config user.name`>
295
307
  > **Developer:** —
@@ -297,6 +309,10 @@ the codebase, link rather than duplicate):
297
309
  > **Area:** <comma-separated files/modules this touches>
298
310
  > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
299
311
  > services; only acted on when isolation is enabled — see Phase A item 9>
312
+ > **Incident:** <incident-<name> — only when this spec is a fix for an open
313
+ > incident spec; the next push links the two as related on the tracker, and
314
+ > `/spec-complete` on the incident counts this spec among its fixes. Omit the
315
+ > line entirely otherwise>
300
316
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
301
317
  > is configured; omit the line entirely otherwise. A chore defaults to
302
318
  > "none: not user-facing". An empty value or a bare
@@ -269,6 +269,10 @@ because work is already underway. Keep it lean:
269
269
  > **Developer:** <git user.name — you, since you're fixing it now>
270
270
  > **Raised:** <YYYY-MM-DD (today)>
271
271
  > **Area:** <files/modules>
272
+ > **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
273
+ > the push writes it where the provider has a home for it. Omit otherwise>
274
+ > **Incident:** <incident-<name> — only when this bug is a fix for an open
275
+ > incident spec; the next push links the two as related. Omit otherwise>
272
276
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
273
277
  > is configured; omit the line entirely otherwise>
274
278
 
@@ -42,6 +42,45 @@ Before marking complete, confirm the work is actually finished:
42
42
  is its own, and step 4 commits that.
43
43
 
44
44
 
45
+ ### An incident spec — the log, and the open-fix check
46
+
47
+ **Only for `Type: Incident` specs** (folder prefix `incident-`); every other
48
+ kind skips this in silence.
49
+
50
+ 1. **Check for open linked fixes.** Grep `specs/backlog/` and
51
+ `specs/in-progress/` for specs carrying `> **Incident:** <this spec's name>`.
52
+ Any hit is a fix still open: **refuse**, naming each one, and offer to
53
+ complete anyway with it listed as outstanding in the log — the operator
54
+ answers; record the choice in the spec's Changelog either way.
55
+ BLIND SPOT, named: a fix spec authored but not yet landed on the base branch
56
+ is invisible to this grep — acceptable, because `/spec`'s committing
57
+ verdicts land authored specs on the base
58
+ (`.claude/rules/negative-checks.md`).
59
+ 2. **Write `incident-log.md`** into the spec folder — the stakeholder- and
60
+ support-facing record, built from the spec and its linked fixes:
61
+ summary · severity · timeline (started, detected, mitigated, resolved) ·
62
+ impact (who, what, for how long) · root cause · the fixes (each linked
63
+ spec, its ticket, and the release it shipped in — `spec-sync released`
64
+ answers that where a provider is installed; a fix completed but not yet
65
+ released is listed as such) · what went well and what didn't · follow-ups,
66
+ each offered as a `/spec` on the spot.
67
+ 3. **Push the log onto the incident item as a comment** (only when a provider
68
+ is installed and the spec is linked):
69
+
70
+ ```
71
+ skitterspec spec-sync comment <spec> --file specs/in-progress/<spec>/incident-log.md
72
+ ```
73
+
74
+ A comment, deliberately: the item's description is generated from the spec,
75
+ so a log written there would be clobbered by the next push — comments are
76
+ the one surface one-way sync never touches. The command exits 0 on every
77
+ cannot-tell (unlinked, offline, no credentials) and says so; relay the line
78
+ and finish either way — the log in the repo is the record.
79
+
80
+ Completion then proceeds as normal: the per-type state map decides what the
81
+ tracker is sent (an Incident completes to whatever `statesByType` names for
82
+ it), and steps 3–7 below are unchanged.
83
+
45
84
  ### Release gating (only when configured)
46
85
 
47
86
  **Only when `specs/.core/gating.config.json` exists.** Run
@@ -293,6 +293,10 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
293
293
  > **Base version:** <tag prod is running, e.g. v33.16.4>
294
294
  > **Raised:** <YYYY-MM-DD (today)>
295
295
  > **Area:** <files/modules>
296
+ > **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
297
+ > the push writes it where the provider has a home for it. Omit otherwise>
298
+ > **Incident:** <incident-<name> — only when this hotfix is a fix for an open
299
+ > incident spec; the next push links the two as related. Omit otherwise>
296
300
  > **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
297
301
  > when release gating is configured, and overridable — see below>
298
302
 
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: spec-incident
3
+ description: Capture a live incident — an outage or degradation of a running service — as an Incident-type spec written during the outage. Grills for what is down, since when, who is affected, severity and what was tried, then writes the spec straight into specs/in-progress/ with a Timeline appended to as it unfolds. Fixes are separate linked specs, never phases. Use when the user says "/spec-incident", "we have an outage", "prod is down and I need an incident record", or asks to track an incident.
4
+ ---
5
+
6
+ # /spec-incident — capture a live incident
7
+
8
+ > Stay silent while this runs — speak only to ask something you cannot answer
9
+ > yourself, or to report a failure at the moment it happens. Read
10
+ > `.claude/rules/spec-reports.md` before reporting; it defines the block this
11
+ > skill ends with.
12
+
13
+ An **incident** is an outage or degradation of a live service. It is not
14
+ delivery work: the fixes are separate hotfix, bug, chore or issue specs, each
15
+ linked back to it, and this spec is the **record** — what happened, when, to
16
+ whom, and what was done. It is written **during** the outage, so it starts in
17
+ `specs/in-progress/`, there is no backlog stop and no review page to wait on:
18
+ speed matters, and the record is reviewed at completion, when
19
+ `/spec-complete` writes the incident log from it.
20
+
21
+ **This skill is not the response.** Mitigating comes first, and nothing here
22
+ blocks it — the grill is short, the spec is small, and everything else is
23
+ appended as it happens.
24
+
25
+ ## 1. Grill — short, and only what the record needs
26
+
27
+ Ask for exactly these, batched, with nothing speculative:
28
+
29
+ 1. **What is down or degraded** — the service, and how it is failing.
30
+ 2. **Since when** — first report, and detection time where they differ.
31
+ 3. **Who is affected** — which users or systems, and how badly.
32
+ 4. **Severity** — Azure's literal values: `1 - Critical`, `2 - High`,
33
+ `3 - Medium`, `4 - Low`. Propose one from the impact described; the user
34
+ confirms.
35
+ 5. **What has been tried** — anything already attempted, and its effect.
36
+
37
+ A root cause is **not** grilled: nobody has it yet, and the Timeline is where
38
+ the investigation lands as it happens.
39
+
40
+ ## 2. Write it, in flight
41
+
42
+ Pick a short kebab name prefixed `incident-` (e.g. `incident-api-outage`).
43
+
44
+ **With per-spec isolation** (`specs/.core/env.config.json` present), provision
45
+ before writing, exactly as `/spec` Phase B does: run
46
+ `skitterspec spec-env up <name> --docs`, run the commands it prints, `cd` into
47
+ the worktree, and confirm with a bare `skitterspec spec-env resolve` naming
48
+ this spec. Without isolation, write where you stand.
49
+
50
+ The spec is a folder in **`specs/in-progress/`** — never backlog — with
51
+ `00-overview.md` and one phase file:
52
+
53
+ ```markdown
54
+ # Incident: <short title>
55
+
56
+ > **Type:** Incident
57
+ > **Name:** incident-<kebab-name>
58
+ > **Status:** In Progress — live (started <YYYY-MM-DD>)
59
+ > **Author:** <git user.name>
60
+ > **Developer:** <git user.name — whoever is running the incident>
61
+ > **Raised:** <YYYY-MM-DD (today)>
62
+ > **Severity:** <1 - Critical … 4 - Low>
63
+ > **Gating:** <pre-filled "none: incident record, no code"; only when release
64
+ > gating is configured, omit otherwise>
65
+
66
+ ## Impact
67
+
68
+ <who is affected, what is failing, since when — from the grill>
69
+
70
+ ## Timeline
71
+
72
+ - <YYYY-MM-DD HH:MM> — <first report / detected / what was tried / what changed>
73
+
74
+ ## Fixes
75
+
76
+ <one line per fix spec as they are opened — see step 4. "None yet" until then.>
77
+
78
+ ## State log
79
+
80
+ | Date | Status | Folder | By |
81
+ |------|--------|--------|----|
82
+ | <YYYY-MM-DD> | In Progress | in-progress | <author> |
83
+
84
+ ## Changelog
85
+
86
+ - <YYYY-MM-DD> — Incident captured.
87
+ ```
88
+
89
+ The phase file `01-response.md` holds the response as tasks — mitigate,
90
+ diagnose, open fix specs, verify recovery — manual steps, not code. Commits in
91
+ this spec default to `docs` with no `Release-Note:`.
92
+
93
+ ## 3. Link to the tracker (only if a provider is installed)
94
+
95
+ Run the provider's linking push exactly as `/spec` Phase E describes — the
96
+ spec is already in `in-progress`, so the mint lands in the incident's
97
+ in-flight state (with Azure's `statesByType`, an Incident is created Active
98
+ and never sent New; the `Severity:` header is written where the provider has a
99
+ home for it). No provider, or an unreachable tracker, is one line and the
100
+ record stands in the repo.
101
+
102
+ ## 4. Run the incident from the spec
103
+
104
+ - **Append to the Timeline** as things happen — dated lines, cheap and often.
105
+ - **Fixes are separate specs**: a prod-version fix is `/spec-hotfix`, a
106
+ mainline defect `/spec-bug`, tooling `/spec` (chore), manual remediation
107
+ `/spec` (issue). Each fix spec carries `> **Incident:** incident-<name>` in
108
+ its header, which the next push turns into a related link on the tracker.
109
+ They are never phases of this spec.
110
+ - **Mid-incident board states stay manual**: skitterspec writes states at
111
+ lifecycle moves only, so moving the ticket to a Mitigated-style state during
112
+ the outage is done on the board, and the next push leaves it until the spec
113
+ itself moves.
114
+
115
+ ## 5. End of the outage is not the end of the spec
116
+
117
+ When the service is recovered, say so in the Timeline and keep the spec in
118
+ flight until the record is complete — root cause written, fixes linked.
119
+ `/spec-complete` is the ending: it writes `incident-log.md` from this spec and
120
+ its linked fixes, refuses while a linked fix is still open (and offers to
121
+ complete anyway with it listed as outstanding), and pushes the log onto the
122
+ incident item as a comment.
123
+
124
+ ## Report
125
+
126
+ End with the block defined in `.claude/rules/spec-reports.md`. That file
127
+ carries the shape; this section carries only what is specific here.
128
+
129
+ **Verdicts**
130
+
131
+ - `✅` — the incident spec is written, in flight, and (where a provider is
132
+ installed) linked.
133
+ - `⚠️` — written and in flight, with something worth knowing (a mint that
134
+ failed, a worktree that could not be provisioned so it was written in
135
+ place).
136
+ - `⏸` — the grill could not establish what is down, so nothing was written.
137
+
138
+ **Fields:** `Tracker` · `Branch` · `Spec` · `Built` · `Worktree` ·
139
+ `Follow-ups` · `Next`
140
+
141
+ `Next` is the response itself — the first task of `01-response.md` — never a
142
+ review page: nothing here waits on a verdict while a service is down.
@@ -27,8 +27,9 @@ clobber customised content. Finish with a summary of created vs already-present.
27
27
  > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
28
28
  > `--reset` (reset needs `--yes`) drive the stronger actions.
29
29
 
30
- The system is **thirteen skills**: `spec` (feature), `spec-bug` (bug),
30
+ The system is **fourteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
31
31
  `spec-hotfix` (a bug fixed on a released tag),
32
+ `spec-incident` (a live outage, recorded as it happens),
32
33
  `no-spec` (work that genuinely has none — off the base branch all the same),
33
34
  `spec-review`, `spec-start`,
34
35
  `spec-next`, `spec-diff` (read a spec's diff as a page),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.1.0",
3
+ "version": "19.2.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
@@ -906,7 +906,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
906
906
  try {
907
907
  spec = resolveSpecWithWorktree(dir, config, specArg)
908
908
  } catch (err) {
909
- const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore)-./.test(specArg)
909
+ const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident)-./.test(specArg)
910
910
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
911
911
  throw err
912
912
  }
@@ -4,7 +4,7 @@
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-`/`hotfix-`/`chore-` prefix into
7
+ * `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix into
8
8
  * `{ type, slug }`, derives the
9
9
  * git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
10
10
  * is filled from a tracker id when one is configured, else it falls back to
@@ -295,10 +295,11 @@ function phaseIsDone(text) {
295
295
  return /^#\s.*✅\s*$/m.test(text)
296
296
  }
297
297
 
298
- // Split a `feat-`/`bug-`/`hotfix-`/`chore-` prefix. Unknown prefix → type
299
- // defaults to `feat` and the whole folder name is the slug.
298
+ // Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix.
299
+ // Unknown prefix → type defaults to `feat` and the whole folder name is the
300
+ // slug.
300
301
  function splitPrefix(folder) {
301
- const m = /^(feat|bug|hotfix|chore)-(.+)$/.exec(folder)
302
+ const m = /^(feat|bug|hotfix|chore|issue|incident)-(.+)$/.exec(folder)
302
303
  if (m) return { type: m[1], slug: m[2] }
303
304
  return { type: 'feat', slug: folder }
304
305
  }
@@ -294,6 +294,26 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
294
294
  )
295
295
  return unwrap(data, 'issueUpdate')
296
296
  },
297
+ /**
298
+ * Add a "related" relation between two issues (by uuid). Idempotent at
299
+ * this level: Linear refuses a relation that already exists, and that
300
+ * refusal comes back as `{ added: false, already: true }` — a re-push per
301
+ * phase is the normal case, not a failure.
302
+ */
303
+ async createIssueRelation(issueId, relatedIssueId) {
304
+ try {
305
+ const data = await call(
306
+ 'mutation($input: IssueRelationCreateInput!) { issueRelationCreate(input: $input) { success } }',
307
+ { input: { issueId, relatedIssueId, type: 'related' } },
308
+ )
309
+ return { added: !!(data && data.issueRelationCreate && data.issueRelationCreate.success) }
310
+ } catch (error) {
311
+ if (/already exists|duplicate/i.test(String(error && error.message))) {
312
+ return { added: false, already: true }
313
+ }
314
+ throw error
315
+ }
316
+ },
297
317
  // A phase sub-issue is an ordinary issue carrying `parentId`. Same mutation,
298
318
  // so there is no separate sub-issue surface to keep in step.
299
319
  async createSubIssue(parentId, subIssue) {
@@ -531,8 +551,13 @@ async function fetchWorkspaceStates(adapter, teamId) {
531
551
  * from the workspace, so a `config.states` value the workspace lacks fails here
532
552
  * with the same vocabulary the state check already uses.
533
553
  */
534
- function stateIdFor(bucket, config, states) {
535
- const name = config && config.states && config.states[bucket]
554
+ function stateIdFor(bucket, config, states, kind) {
555
+ // Per-kind resolution: Linear has no work item types, so statesByKind keys
556
+ // the override by the SPEC's kind. An entry of null means "send no state
557
+ // for this bucket", which lands on the same `return null` an unmapped
558
+ // bucket always took — the caller already treats null as "no transition".
559
+ const over = config && config.statesByKind && kind ? config.statesByKind[kind] : null
560
+ const name = over && bucket in over ? over[bucket] : config && config.states && config.states[bucket]
536
561
  if (!name) return null
537
562
  const hit = states.find((s) => s && s.name === name)
538
563
  if (!hit) {
@@ -56,6 +56,8 @@ const {
56
56
  phaseModeFor,
57
57
  ownsField,
58
58
  remoteDescriptionEdited,
59
+ specHeaders,
60
+ linkedIncident,
59
61
  } = require('../sync-core')
60
62
 
61
63
  const {
@@ -2233,24 +2235,59 @@ function specKindOf(snapshotDir) {
2233
2235
  if (name.startsWith('bug-')) return 'bug'
2234
2236
  if (name.startsWith('hotfix-')) return 'hotfix'
2235
2237
  if (name.startsWith('chore-')) return 'chore'
2238
+ if (name.startsWith('issue-')) return 'issue'
2239
+ if (name.startsWith('incident-')) return 'incident'
2236
2240
  return 'feature'
2237
2241
  }
2238
2242
 
2239
2243
  async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false, out = null }) {
2240
- const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states) : null)
2244
+ const kind = specKindOf(snapshotDir)
2245
+ // Per-kind state resolution: statesByKind[kind] overlays states inside
2246
+ // stateIdFor, and a bucket overridden to null resolves to no transition.
2247
+ const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states, kind) : null)
2241
2248
  // THIS spec's kind label (linear.labelsByKind), resolved name → id once per
2242
2249
  // apply. A label Linear does not have is a one-line note and an unlabelled
2243
2250
  // mint, never a failed push — and with nothing configured, no label call is
2244
2251
  // made at all.
2245
- const kindLabelName = (config.linear && config.linear.labelsByKind && config.linear.labelsByKind[specKindOf(snapshotDir)]) || ''
2252
+ const kindLabelName = (config.linear && config.linear.labelsByKind && config.linear.labelsByKind[kind]) || ''
2253
+ // The `Severity:` header's label (linear.severityLabels, keyed by the
2254
+ // leading digit — "2 - High" → "2"). Opt-in: unset, the header stays
2255
+ // repo-only and no extra label call is made.
2256
+ const severity = specHeaders(snapshotDir, config).severity
2257
+ const severityDigit = severity ? (/^([1-4])/.exec(severity) || [])[1] : null
2258
+ const severityLabelName =
2259
+ (severityDigit && config.linear && config.linear.severityLabels && config.linear.severityLabels[severityDigit]) || ''
2260
+ const wantedLabels = [kindLabelName, severityLabelName].filter(Boolean)
2246
2261
  let kindLabelIds = null
2247
- if (kindLabelName && teamId && typeof adapter.listLabels === 'function') {
2262
+ if (wantedLabels.length && teamId && typeof adapter.listLabels === 'function') {
2248
2263
  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`)
2264
+ const ids = []
2265
+ for (const name of wantedLabels) {
2266
+ const hit = labels.find((l) => l && String(l.name).toLowerCase() === name.toLowerCase())
2267
+ if (hit) ids.push(hit.id)
2268
+ else if (out) out.write(` !! label "${name}" is not on the team — minted without it\n`)
2269
+ }
2270
+ if (ids.length) kindLabelIds = ids
2271
+ } else if (wantedLabels.length && out && typeof adapter.listLabels !== 'function') {
2272
+ out.write(` !! label "${wantedLabels.join('", "')}" skipped — this transport cannot list labels\n`)
2273
+ }
2274
+ // The `Incident:` header's related link, added after the mint/update. The
2275
+ // repo owns the link; an incident not linked yet is a line, never a failure.
2276
+ const incident = linkedIncident(snapshotDir, config)
2277
+ const relateToIncident = async (issueId) => {
2278
+ if (!incident) return
2279
+ if (!incident.identifier) {
2280
+ if (out) out.write(` !! related incident ${incident.name} is not linked yet — link skipped\n`)
2281
+ return
2282
+ }
2283
+ if (typeof adapter.createIssueRelation !== 'function' || typeof adapter.readIssue !== 'function') return
2284
+ const target = await adapter.readIssue(incident.identifier)
2285
+ if (!target || !target.id) {
2286
+ if (out) out.write(` !! related incident ${incident.identifier} not found on Linear — link skipped\n`)
2287
+ return
2288
+ }
2289
+ const r = await adapter.createIssueRelation(issueId, target.id)
2290
+ if (out && r && r.added) out.write(` related link added: ${incident.identifier}\n`)
2254
2291
  }
2255
2292
  const ops = {
2256
2293
  prevalidateStates: (buckets) => {
@@ -2278,6 +2315,7 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2278
2315
  labelIds: kindLabelIds,
2279
2316
  }))
2280
2317
  if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
2318
+ await relateToIncident(created.id)
2281
2319
  return created
2282
2320
  },
2283
2321
  updateIssue: async (existing, issue) => {
@@ -2292,6 +2330,7 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2292
2330
  // is something to say, so `in` is the test, not truthiness.
2293
2331
  if ('assignee' in issue) updates.assigneeId = issue.assignee ?? null
2294
2332
  await adapter.updateIssue(existing.id, updates)
2333
+ await relateToIncident(existing.id)
2295
2334
  },
2296
2335
  mintSubIssue: async (parentId, sub) => {
2297
2336
  const created = await adapter.createSubIssue(parentId, withoutNull({
@@ -3000,6 +3039,53 @@ function originalPreserved(comments) {
3000
3039
  })
3001
3040
  }
3002
3041
 
3042
+
3043
+ // `comment <spec> --file <f>` — post a file's markdown onto the spec's issue
3044
+ // as a comment: the one surface one-way sync never touches, so no later push
3045
+ // can clobber it. `/spec-complete` posts an incident's log through this.
3046
+ // Misuse (no readable file) exits 1; every cannot-tell exits 0 and says so.
3047
+ async function specSyncComment(dir, config, specArg, flags, out) {
3048
+ const snapshotDir = resolveOrExit(specArg, dir, out)
3049
+ if (!snapshotDir) return 1
3050
+ const done = (msg) => {
3051
+ out.write(`spec-sync comment: ${msg}\n`)
3052
+ return 0
3053
+ }
3054
+ if (!flags.file) {
3055
+ out.write('spec-sync comment: pass --file <markdown file to post>\n')
3056
+ return 1
3057
+ }
3058
+ let body
3059
+ try {
3060
+ body = fs.readFileSync(flags.file, 'utf-8')
3061
+ } catch (error) {
3062
+ out.write(`spec-sync comment: cannot read --file: ${error.message}\n`)
3063
+ return 1
3064
+ }
3065
+ if (!body.trim()) {
3066
+ out.write('spec-sync comment: --file is empty — nothing to post\n')
3067
+ return 1
3068
+ }
3069
+ const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
3070
+ const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
3071
+ if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing posted`)
3072
+ const key = resolveApiKey(config, flags.env || process.env)
3073
+ const transport = resolveTransport(flags, config, key.ok)
3074
+ if (transport === 'mcp') {
3075
+ return done(`transport = mcp — post the file's contents onto ${identifier} with the Linear comment tool yourself`)
3076
+ }
3077
+ if (!key.ok) return done(`no API key — ${key.error.split('\n')[0]}; nothing posted`)
3078
+ const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
3079
+ try {
3080
+ const issue = await adapter.readIssue(identifier)
3081
+ if (!issue || !issue.id) return done(`${identifier} not found on Linear — nothing posted`)
3082
+ await adapter.createComment(issue.id, body)
3083
+ return done(`${identifier} — comment posted (${body.length} characters)`)
3084
+ } catch (error) {
3085
+ return done(`could not reach Linear (${String(error.message).split('\n')[0]}); nothing posted`)
3086
+ }
3087
+ }
3088
+
3003
3089
  /**
3004
3090
  * `spec-sync preserve <spec> [--text <file>] [--json]` — post the issue's
3005
3091
  * current description as a comment, before a push replaces it with the spec.
@@ -3234,6 +3320,7 @@ async function specSync(rest, io = {}) {
3234
3320
  // `preserve --text <file>`: the description to keep, when the caller read it
3235
3321
  // over MCP and the engine cannot.
3236
3322
  else if (args[i] === '--text') flags.text = path.resolve(args[++i])
3323
+ else if (args[i] === '--file') flags.file = path.resolve(args[++i])
3237
3324
  else if (args[i] === '--mcp') flags.mcp = path.resolve(args[++i])
3238
3325
  else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
3239
3326
  else if (args[i] === '--via') flags.via = args[++i]
@@ -3407,6 +3494,8 @@ async function specSync(rest, io = {}) {
3407
3494
  return specSyncVerify(dir, config, positional[0], flags, out) || 0
3408
3495
  case 'preserve':
3409
3496
  return (await specSyncPreserve(dir, config, positional[0], flags, out)) || 0
3497
+ case 'comment':
3498
+ return (await specSyncComment(dir, config, positional[0], flags, out)) || 0
3410
3499
  case 'linked':
3411
3500
  specSyncLinked(dir, config, flags, out)
3412
3501
  return 0
@@ -3426,6 +3515,7 @@ async function specSync(rest, io = {}) {
3426
3515
  ' skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
3427
3516
  ' skitterspec spec-sync verify <spec> --stored <file>\n' +
3428
3517
  ' skitterspec spec-sync preserve <spec> [--text <file>] [--via api|mcp] [--json]\n' +
3518
+ ' skitterspec spec-sync comment <spec> --file <file> [--via api|mcp]\n' +
3429
3519
  ' skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
3430
3520
  ' skitterspec spec-sync linked [--json]\n' +
3431
3521
  ' skitterspec spec-sync ref [<spec>] [--json]\n' +
@@ -123,6 +123,7 @@ const DEFAULT_CONFIG = Object.freeze({
123
123
  // already exist on the team; a missing one is a one-line note, never a
124
124
  // failed push. Empty means no kind label, as before.
125
125
  labelsByKind: Object.freeze({}),
126
+ severityLabels: Object.freeze({}),
126
127
  }),
127
128
  // Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
128
129
  // inbox filter — issues carrying it are what the web app files; `bugLabels`
@@ -274,7 +275,7 @@ const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
274
275
  // A fresh, deeply-mutable copy of the defaults to merge onto.
275
276
  function defaults() {
276
277
  return {
277
- linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind } },
278
+ linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind }, severityLabels: { ...DEFAULT_CONFIG.linear.severityLabels } },
278
279
  intake: {
279
280
  label: DEFAULT_CONFIG.intake.label,
280
281
  bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
@@ -283,6 +284,7 @@ function defaults() {
283
284
  },
284
285
  mapping: { ...DEFAULT_CONFIG.mapping },
285
286
  states: { ...DEFAULT_CONFIG.states },
287
+ statesByKind: {},
286
288
  stateAliases: {},
287
289
  snapshot: { ...DEFAULT_CONFIG.snapshot },
288
290
  fields: { ...DEFAULT_CONFIG.fields },
@@ -306,7 +308,7 @@ function defaults() {
306
308
  // vocabularies; `mergeConfig` below is the part that is Linear's — which keys
307
309
  // exist and how they nest.
308
310
  const { isObject, stringList, assign } = kitConfig
309
- const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
311
+ const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
310
312
  kitConfig.makeMergeHelpers({
311
313
  configFile: CONFIG_FILE,
312
314
  ownership: OWNERSHIP,
@@ -329,12 +331,21 @@ function mergeConfig(base, parsed) {
329
331
  // Only the kinds a spec folder can actually be — an unknown key is
330
332
  // dropped, matching the other providers' by-kind validation.
331
333
  const byKind = {}
332
- for (const kind of ['feature', 'bug', 'hotfix', 'chore']) {
334
+ for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident']) {
333
335
  const value = parsed.linear.labelsByKind[kind]
334
336
  if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
335
337
  }
336
338
  base.linear.labelsByKind = byKind
337
339
  }
340
+ if (isObject(parsed.linear.severityLabels)) {
341
+ // Keyed by the Severity header's leading digit ("2 - High" → "2").
342
+ const bySeverity = {}
343
+ for (const digit of ['1', '2', '3', '4']) {
344
+ const value = parsed.linear.severityLabels[digit]
345
+ if (typeof value === 'string' && value.trim()) bySeverity[digit] = value.trim()
346
+ }
347
+ base.linear.severityLabels = bySeverity
348
+ }
338
349
  }
339
350
 
340
351
  if (isObject(parsed.intake)) {
@@ -366,6 +377,7 @@ function mergeConfig(base, parsed) {
366
377
  }
367
378
 
368
379
  mergeStates(base, parsed)
380
+ mergeStateOverrides(base, parsed, 'statesByKind')
369
381
 
370
382
  if (isObject(parsed.snapshot)) {
371
383
  assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
@@ -193,8 +193,52 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
193
193
  base.stateAliases = aliases
194
194
  }
195
195
 
196
+ // Merge (and validate) a per-type/kind state override table — `statesByType`
197
+ // keyed by work item / issue type (Azure, Jira), `statesByKind` keyed by spec
198
+ // kind (GitHub, Linear). Each entry is a PARTIAL bucket map laid over
199
+ // `states` for that type/kind: a bucket set to null means "send no state for
200
+ // this bucket", and a bucket the entry lacks falls through to `states`.
201
+ // An unknown bucket is refused — a typo'd bucket would silently change
202
+ // nothing at push time. Call after mergeStates, so buckets are final.
203
+ function mergeStateOverrides(base, parsed, key) {
204
+ const value = parsed[key]
205
+ if (!isObject(value)) return
206
+ const table = {}
207
+ for (const [name, entry] of Object.entries(value)) {
208
+ if (!isObject(entry)) {
209
+ throw new Error(
210
+ `Invalid ${configFile}: ${key}.${JSON.stringify(name)} = ${JSON.stringify(entry)} ` +
211
+ '(expected an object mapping lifecycle buckets to a state name, or null to send no state)',
212
+ )
213
+ }
214
+ const row = {}
215
+ for (const [bucket, state] of Object.entries(entry)) {
216
+ if (!(bucket in base.states)) {
217
+ throw new Error(
218
+ `Invalid ${configFile}: ${key}.${JSON.stringify(name)}.${bucket} — not a lifecycle bucket ` +
219
+ `(${Object.keys(base.states).join(', ')})`,
220
+ )
221
+ }
222
+ if (state === null) {
223
+ row[bucket] = null
224
+ continue
225
+ }
226
+ if (typeof state !== 'string' || !state.trim()) {
227
+ throw new Error(
228
+ `Invalid ${configFile}: ${key}.${JSON.stringify(name)}.${bucket} = ${JSON.stringify(state)} ` +
229
+ '(expected a state name, or null to send no state)',
230
+ )
231
+ }
232
+ row[bucket] = state.trim()
233
+ }
234
+ if (Object.keys(row).length) table[name] = row
235
+ }
236
+ base[key] = table
237
+ }
238
+
196
239
  return {
197
240
  mergeStates,
241
+ mergeStateOverrides,
198
242
  mergeFieldOwnership,
199
243
  mergePhaseMapping,
200
244
  mergeReleaseIgnorePaths,
@@ -13,7 +13,7 @@
13
13
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
14
14
  */
15
15
 
16
- const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
16
+ const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, linkedIncident, phaseModeFor } = require('./src/normalize.js')
17
17
  const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
18
18
  const { readBase, writeBase } = require('./src/base.js')
19
19
  const { push, recordPush, projectionOf } = require('./src/push.js')
@@ -46,6 +46,9 @@ module.exports = {
46
46
  titleFromText,
47
47
  validateStates,
48
48
  stateSuggestions,
49
+ effectiveStates,
50
+ specHeaders,
51
+ linkedIncident,
49
52
  hashField,
50
53
  stableStringify,
51
54
  readBase,
@@ -405,6 +405,60 @@ function readSnapshot(snapshotDir, config) {
405
405
  return { frontmatter: data, title, sections, phases, body }
406
406
  }
407
407
 
408
+ // The spec's own `> **Severity:**` and `> **Incident:**` headers, off the
409
+ // overview's blockquote block. They are PUSH-TIME EXTRAS, deliberately not
410
+ // keys on `normalizeLocal`'s field set: severity lands in a provider-specific
411
+ // home (a field, a label) and the incident link as a typed relation, so
412
+ // neither belongs in the synced-field hashes a stored base compares.
413
+ function specHeaders(snapshotDir, config) {
414
+ const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
415
+ let raw
416
+ try {
417
+ raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
418
+ } catch {
419
+ return { severity: null, incident: null }
420
+ }
421
+ const read = (name) => {
422
+ const m = new RegExp(`^>\\s*\\*\\*${name}:\\*\\*\\s*(.+)$`, 'm').exec(raw)
423
+ return m ? m[1].trim() : null
424
+ }
425
+ return { severity: read('Severity'), incident: read('Incident') }
426
+ }
427
+
428
+ // Resolve a fix spec's `> **Incident:**` header to the incident spec it names:
429
+ // its folder in any lifecycle bucket, and the tracker identifier stamped on it
430
+ // (via the provider's own `fields.identifier`). `identifier: null` means the
431
+ // incident exists but is not linked yet — report and carry on, never fail the
432
+ // push over it. No header at all returns null.
433
+ function linkedIncident(snapshotDir, config) {
434
+ const { incident } = specHeaders(snapshotDir, config)
435
+ if (!incident) return null
436
+ const root = path.resolve(snapshotDir, '..', '..', '..')
437
+ const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
438
+ for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
439
+ const file = path.join(root, 'specs', bucket, incident, overviewFile)
440
+ if (!fs.existsSync(file)) continue
441
+ const { data } = parseFrontmatter(fs.readFileSync(file, 'utf-8'))
442
+ const idField = config && config.fields && config.fields.identifier
443
+ const identifier = idField && data[idField] != null ? String(data[idField]) : null
444
+ return { name: incident, identifier, found: true }
445
+ }
446
+ // A FOLDER NOT ON DISK IS NOT PROOF THE INCIDENT DOES NOT EXIST — buckets
447
+ // are branch-local truth, so an incident on its own unlanded branch is
448
+ // invisible here. The caller reports "not linked yet" and carries on.
449
+ return { name: incident, identifier: null, found: false }
450
+ }
451
+
452
+ // The one-line cross-reference a fix spec's body carries to its incident. Part
453
+ // of the PROJECTION (not appended at send time), so the stored base, the plan
454
+ // and what the tracker holds all hash the same bytes — and on GitHub the
455
+ // `#N` identifier backlinks on the incident's own timeline.
456
+ function relatedIncidentLine(snapshotDir, config) {
457
+ const incident = linkedIncident(snapshotDir, config)
458
+ if (!incident) return ''
459
+ return `\n\nRelated incident: ${incident.identifier || incident.name}`
460
+ }
461
+
408
462
  // The headings a bug-shaped spec's ticket leads with, in this order, when the
409
463
  // spec has them. A Bug ticket is read for its repro before anything else, and
410
464
  // the feature overview order buries it. Sections a spec does not have are
@@ -723,23 +777,24 @@ function normalizeLocal(snapshotDir, config) {
723
777
  const phasesCarriedBySubIssues =
724
778
  syncsSubIssues && phaseModeFor(workflowState, config) !== 'inline' && withheld === 0
725
779
  const extracted = {
726
- description: withInlinePhases(
727
- buildDescription(
728
- title,
729
- sections,
780
+ description:
781
+ withInlinePhases(
782
+ buildDescription(
783
+ title,
784
+ sections,
785
+ config.sync.localOnlySections,
786
+ phasesCarriedBySubIssues ? ['Phases'] : [],
787
+ dialect,
788
+ // A bug or hotfix spec's ticket leads with the bug sections — a
789
+ // different render of the same overview, so the Bug form opens on the
790
+ // repro rather than the feature-shaped prose.
791
+ bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
792
+ ),
793
+ inlined,
794
+ tasksMode,
730
795
  config.sync.localOnlySections,
731
- phasesCarriedBySubIssues ? ['Phases'] : [],
732
796
  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 : [],
737
- ),
738
- inlined,
739
- tasksMode,
740
- config.sync.localOnlySections,
741
- dialect,
742
- ),
797
+ ) + relatedIncidentLine(snapshotDir, config),
743
798
  // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
744
799
  // local handle the push skill stamps a newly-created sub-issue id back into.
745
800
  // `state` is the phase's status bucket (from its heading emoji), mapped to a
@@ -786,7 +841,14 @@ function phasesWithheld(snapshotDir, config) {
786
841
  function stateNamesFor(bucket, config) {
787
842
  const primary = config && config.states && config.states[bucket]
788
843
  const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
789
- return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
844
+ // Override values read as the bucket they override — so a `/spec-status`
845
+ // against a type completed to "Closed" still reads as `complete`.
846
+ const overrides = stateOverrideTables(config).flatMap((table) =>
847
+ Object.values(table).map((entry) => entry && entry[bucket]),
848
+ )
849
+ return [...new Set([primary, ...(Array.isArray(aliases) ? aliases : []), ...overrides])].filter(
850
+ (n) => typeof n === 'string' && n,
851
+ )
790
852
  }
791
853
 
792
854
  // Map a remote workflow-state name back to the local lifecycle bucket (the
@@ -922,11 +984,39 @@ function titleFromText(text, max = 100) {
922
984
  return stripTitleMarkup(title)
923
985
  }
924
986
 
925
- // Every state NAME the config points at: the lifecycle bucket map.
987
+ // Per-type/kind state OVERRIDES: `table` maps a work item type (Azure, Jira)
988
+ // or a spec kind (GitHub, Linear) to a partial bucket map laid over
989
+ // `config.states`. A bucket mapped to null means "send no state for this
990
+ // bucket"; a bucket the entry lacks falls through to the base map. With no
991
+ // table, or no entry for `key`, this is exactly `config.states`.
992
+ function effectiveStates(config, table, key) {
993
+ const out = { ...((config && config.states) || {}) }
994
+ const over = (table && key && table[key]) || null
995
+ if (over) for (const [bucket, value] of Object.entries(over)) out[bucket] = value
996
+ return out
997
+ }
998
+
999
+ // The per-type/kind override tables a provider config may carry. Readers that
1000
+ // scan "every configured state name" scan these too, so an override value is
1001
+ // validated and recognised exactly like a base one.
1002
+ function stateOverrideTables(config) {
1003
+ return [config && config.statesByType, config && config.statesByKind].filter(Boolean)
1004
+ }
1005
+
1006
+ // Every state NAME the config points at: the lifecycle bucket map, plus any
1007
+ // per-type/kind override values (null entries carry no name).
926
1008
  function configuredStateNames(config) {
927
1009
  // The WRITTEN names only. An alias is never written, so one the workspace
928
1010
  // lacks cannot strand a push; `stateSuggestions` still names it in reports.
929
- return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
1011
+ const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
1012
+ for (const table of stateOverrideTables(config)) {
1013
+ for (const entry of Object.values(table)) {
1014
+ for (const value of Object.values(entry || {})) {
1015
+ if (typeof value === 'string') names.push(value)
1016
+ }
1017
+ }
1018
+ }
1019
+ return [...new Set(names)]
930
1020
  }
931
1021
 
932
1022
  // Which configured state NAMES are absent from the live workspace. The skill
@@ -977,6 +1067,7 @@ module.exports = {
977
1067
  ownsField,
978
1068
  stateSuggestions,
979
1069
  configuredStateNames,
1070
+ effectiveStates,
980
1071
  normalizeLocal,
981
1072
  assigneeFor,
982
1073
  phaseProjection,
@@ -996,4 +1087,6 @@ module.exports = {
996
1087
  remoteWorkflowState,
997
1088
  remoteStateReading,
998
1089
  stateNamesFor,
1090
+ specHeaders,
1091
+ linkedIncident,
999
1092
  }