@skitterbyte/skitterspec-jira 2.1.0 → 2.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 +42 -0
- package/assets/core/jira.config.md +2 -0
- package/assets/rules/spec-planning.md +41 -13
- package/assets/skills/spec/SKILL.md +33 -17
- package/assets/skills/spec-bug/SKILL.md +4 -0
- package/assets/skills/spec-complete/SKILL.md +39 -0
- package/assets/skills/spec-hotfix/SKILL.md +4 -0
- package/assets/skills/spec-incident/SKILL.md +142 -0
- package/assets/skills/spec-init/SKILL.md +2 -1
- package/package.json +1 -1
- package/src/cli.js +1 -1
- package/src/env/resolve.js +5 -4
- package/src/vendor/jira/api.js +58 -2
- package/src/vendor/jira/cli-sync.js +176 -13
- package/src/vendor/jira/config.js +6 -3
- package/src/vendor/provider-kit/src/config.js +44 -0
- package/src/vendor/sync-core/index.js +4 -1
- package/src/vendor/sync-core/src/normalize.js +111 -18
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
|
|
@@ -13,6 +13,8 @@ NAMES — never a credential. Credentials live in the user-level store
|
|
|
13
13
|
| `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
|
|
14
14
|
| `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
|
|
15
15
|
| `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
|
|
16
|
+
| `statesByType.<issue type>.<bucket>` | Per-TYPE override laid over `states` — statuses belong to the type's workflow, so `{ "Service Request": { "complete": "Closed" } }` completes that type differently. A bucket set to `null` sends no status; validation checks each type against its own workflow. | `{}` |
|
|
17
|
+
| `jira.severityField` | The field id the `Severity:` header is written to (e.g. `customfield_10900`). Empty, the header stays repo-only. A fix spec's `Incident:` header adds a `Relates` issue link to its incident, once. | `""` |
|
|
16
18
|
| `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
|
|
17
19
|
| `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
|
|
18
20
|
| `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
|
|
@@ -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
|
|
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`,
|
|
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
|
|
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,
|
|
602
|
-
refactors.
|
|
603
|
-
|
|
604
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
191
|
+
### Propose the kind — feature, chore or issue
|
|
192
192
|
|
|
193
|
-
This skill writes
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
|
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
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
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
|
|
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
|
|
292
|
-
> **Name:** <feat- or
|
|
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 **
|
|
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-jira",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.2.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
|
|
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
|
}
|
package/src/env/resolve.js
CHANGED
|
@@ -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.
|
|
299
|
-
// defaults to `feat` and the whole folder name is the
|
|
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
|
}
|
package/src/vendor/jira/api.js
CHANGED
|
@@ -152,6 +152,13 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
|
|
|
152
152
|
if (input.assigneeId !== undefined) {
|
|
153
153
|
fields.assignee = input.assigneeId == null ? null : { accountId: input.assigneeId }
|
|
154
154
|
}
|
|
155
|
+
// Extra raw fields, keyed by field id — how `jira.severityField` writes a
|
|
156
|
+
// site's own Severity field without this adapter knowing its id.
|
|
157
|
+
if (input.extraFields) {
|
|
158
|
+
for (const [id, value] of Object.entries(input.extraFields)) {
|
|
159
|
+
if (value !== undefined) fields[id] = value
|
|
160
|
+
}
|
|
161
|
+
}
|
|
155
162
|
return fields
|
|
156
163
|
}
|
|
157
164
|
|
|
@@ -164,14 +171,42 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
|
|
|
164
171
|
return normalizeIssue(raw)
|
|
165
172
|
},
|
|
166
173
|
|
|
167
|
-
async createIssue({ title, description, assigneeId, projectKey, issueTypeName }) {
|
|
174
|
+
async createIssue({ title, description, assigneeId, projectKey, issueTypeName, extraFields }) {
|
|
168
175
|
const created = await request('POST', '/issue', {
|
|
169
|
-
body: { fields: issueFields({ title, description, assigneeId }, { forCreate: true, projectKey, issueTypeName }) },
|
|
176
|
+
body: { fields: issueFields({ title, description, assigneeId, extraFields }, { forCreate: true, projectKey, issueTypeName }) },
|
|
170
177
|
})
|
|
171
178
|
if (!created || !created.key) throw new Error('Jira returned no issue for the create')
|
|
172
179
|
return { id: String(created.id), identifier: created.key, url: urlOf(created.key) }
|
|
173
180
|
},
|
|
174
181
|
|
|
182
|
+
/**
|
|
183
|
+
* The "Relates" links an issue already carries, as the other end's key —
|
|
184
|
+
* what lets a re-push skip a link that is already there instead of
|
|
185
|
+
* stacking a duplicate on every push.
|
|
186
|
+
*/
|
|
187
|
+
async listRelatedLinks(keyOrId) {
|
|
188
|
+
const raw = await request('GET', `/issue/${encodeURIComponent(keyOrId)}`, {
|
|
189
|
+
query: { fields: 'issuelinks' },
|
|
190
|
+
allow404: true,
|
|
191
|
+
})
|
|
192
|
+
const links = (raw && raw.fields && raw.fields.issuelinks) || []
|
|
193
|
+
return links
|
|
194
|
+
.map((l) => (l.inwardIssue && l.inwardIssue.key) || (l.outwardIssue && l.outwardIssue.key))
|
|
195
|
+
.filter(Boolean)
|
|
196
|
+
},
|
|
197
|
+
|
|
198
|
+
/** Add a "Relates" issue link between two issues. */
|
|
199
|
+
async createRelatedLink(keyOrId, targetKeyOrId) {
|
|
200
|
+
await request('POST', '/issueLink', {
|
|
201
|
+
body: {
|
|
202
|
+
type: { name: 'Relates' },
|
|
203
|
+
inwardIssue: { key: String(keyOrId) },
|
|
204
|
+
outwardIssue: { key: String(targetKeyOrId) },
|
|
205
|
+
},
|
|
206
|
+
})
|
|
207
|
+
return { added: true }
|
|
208
|
+
},
|
|
209
|
+
|
|
175
210
|
async createSubIssue(parentId, { title, description, projectKey, subtaskTypeName }) {
|
|
176
211
|
const fields = issueFields({ title, description }, { forCreate: true, projectKey, issueTypeName: subtaskTypeName })
|
|
177
212
|
fields.parent = { id: String(parentId) }
|
|
@@ -267,6 +302,27 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
|
|
|
267
302
|
return [...names.values()]
|
|
268
303
|
},
|
|
269
304
|
|
|
305
|
+
/**
|
|
306
|
+
* The same statuses KEYED BY ISSUE TYPE — Jira binds a workflow to the
|
|
307
|
+
* type, so a status one type lacks is exactly what per-type validation
|
|
308
|
+
* exists to catch, and the deduped list above hides it.
|
|
309
|
+
*/
|
|
310
|
+
async listIssueStatesByType(projectKey) {
|
|
311
|
+
const raw = await request('GET', `/project/${encodeURIComponent(projectKey)}/statuses`)
|
|
312
|
+
const byType = {}
|
|
313
|
+
for (const type of raw || []) {
|
|
314
|
+
if (!type || !type.name) continue
|
|
315
|
+
byType[type.name] = (type.statuses || [])
|
|
316
|
+
.filter((status) => status && status.name)
|
|
317
|
+
.map((status) => ({
|
|
318
|
+
id: String(status.id),
|
|
319
|
+
name: status.name,
|
|
320
|
+
category: (status.statusCategory && status.statusCategory.name) || null,
|
|
321
|
+
}))
|
|
322
|
+
}
|
|
323
|
+
return byType
|
|
324
|
+
},
|
|
325
|
+
|
|
270
326
|
async readViewer() {
|
|
271
327
|
const raw = await request('GET', '/myself')
|
|
272
328
|
if (!raw || !raw.accountId) return null
|
|
@@ -26,6 +26,9 @@ const {
|
|
|
26
26
|
isEmptyPlan,
|
|
27
27
|
validateStates,
|
|
28
28
|
stateSuggestions,
|
|
29
|
+
effectiveStates,
|
|
30
|
+
specHeaders,
|
|
31
|
+
linkedIncident,
|
|
29
32
|
remoteDescriptionEdited,
|
|
30
33
|
writeFrontmatter,
|
|
31
34
|
stampSubIssueId,
|
|
@@ -72,6 +75,41 @@ function stateCheckFailure(config, flags) {
|
|
|
72
75
|
} catch (error) {
|
|
73
76
|
return [`${PROGRAM} plan: refusing — --workspace-states is not valid JSON: ${error.message}`]
|
|
74
77
|
}
|
|
78
|
+
// The keyed shape (`{ "<issue type>": [names] }`, what `states --json`
|
|
79
|
+
// prints) is checked PER TYPE: each configured type's effective statuses —
|
|
80
|
+
// statesByType over states, nulls skipped — against that type's own
|
|
81
|
+
// workflow, so a status one type's workflow lacks refuses before the first
|
|
82
|
+
// write even when another type can reach it.
|
|
83
|
+
if (names && typeof names === 'object' && !Array.isArray(names)) {
|
|
84
|
+
const lc = (s) => String(s).toLowerCase().trim()
|
|
85
|
+
const types = [
|
|
86
|
+
...new Set(
|
|
87
|
+
[config.jira.issueType, config.jira.subtaskType, ...Object.values(config.jira.issueTypeByKind || {})].filter(Boolean),
|
|
88
|
+
),
|
|
89
|
+
]
|
|
90
|
+
const problems = []
|
|
91
|
+
for (const type of types) {
|
|
92
|
+
const have = names[type]
|
|
93
|
+
// A TYPE THE FILE LACKS IS A CANNOT-TELL, not a refusal: an absence
|
|
94
|
+
// here is an older file or a type the fetch could not read, and neither
|
|
95
|
+
// is evidence the config is wrong (negative-checks.md rule 4).
|
|
96
|
+
if (!Array.isArray(have)) continue
|
|
97
|
+
const haveSet = new Set(have.map(lc))
|
|
98
|
+
const effective = effectiveStates(config, config.statesByType, type)
|
|
99
|
+
for (const [bucket, name] of Object.entries(effective)) {
|
|
100
|
+
if (typeof name !== 'string') continue // null = send no status
|
|
101
|
+
if (!haveSet.has(lc(name))) problems.push({ type, bucket, name, available: have })
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
if (!problems.length) return null
|
|
105
|
+
const lines = [`${PROGRAM} plan: refusing — configured status name(s) missing from the type that would receive them`, '']
|
|
106
|
+
for (const p of problems) {
|
|
107
|
+
lines.push(` ${p.type}: "${p.name}" (states.${p.bucket}) is not a status this type's workflow has`)
|
|
108
|
+
lines.push(` ${p.type} has: ${p.available.join(', ') || '(none reported)'}`)
|
|
109
|
+
}
|
|
110
|
+
lines.push('', ` Fix ${CONFIG_FILE} -> states / statesByType.`)
|
|
111
|
+
return lines
|
|
112
|
+
}
|
|
75
113
|
const list = Array.isArray(names) ? names : []
|
|
76
114
|
const missing = validateStates(config, list)
|
|
77
115
|
if (missing.length) {
|
|
@@ -97,27 +135,61 @@ function specKindOf(snapshotDir) {
|
|
|
97
135
|
if (name.startsWith('bug-')) return 'bug'
|
|
98
136
|
if (name.startsWith('hotfix-')) return 'hotfix'
|
|
99
137
|
if (name.startsWith('chore-')) return 'chore'
|
|
138
|
+
if (name.startsWith('issue-')) return 'issue'
|
|
139
|
+
if (name.startsWith('incident-')) return 'incident'
|
|
100
140
|
return 'feature'
|
|
101
141
|
}
|
|
102
142
|
|
|
103
|
-
function applyOps({ adapter, config, kind = 'feature' }) {
|
|
143
|
+
function applyOps({ adapter, config, kind = 'feature', snapshotDir = null, out = null }) {
|
|
104
144
|
// The mint type for THIS spec's kind (jira.issueTypeByKind), falling back to
|
|
105
145
|
// the one configured type — unmapped kinds mint exactly as before.
|
|
106
146
|
const mintType = (config.jira.issueTypeByKind && config.jira.issueTypeByKind[kind]) || config.jira.issueType
|
|
107
|
-
|
|
108
|
-
|
|
147
|
+
// Push-time extras off the spec's own headers: `Severity:` lands in the
|
|
148
|
+
// site's own field (`jira.severityField`, opt-in — unset, the header stays
|
|
149
|
+
// repo-only), `Incident:` as a "Relates" issue link. Neither is a synced
|
|
150
|
+
// field, so neither touches the stored-base hashes.
|
|
151
|
+
const severity = snapshotDir ? specHeaders(snapshotDir, config).severity : null
|
|
152
|
+
const severityFields =
|
|
153
|
+
severity != null && config.jira.severityField ? { [config.jira.severityField]: severity } : undefined
|
|
154
|
+
const incident = snapshotDir ? linkedIncident(snapshotDir, config) : null
|
|
155
|
+
const relateToIncident = async (keyOrId) => {
|
|
156
|
+
if (!incident) return
|
|
157
|
+
if (!incident.identifier) {
|
|
158
|
+
if (out) out.write(` !! related incident ${incident.name} is not linked yet — link skipped\n`)
|
|
159
|
+
return
|
|
160
|
+
}
|
|
161
|
+
if (typeof adapter.createRelatedLink !== 'function') return
|
|
162
|
+
// Jira stacks duplicate links, and a push runs per phase — so an existing
|
|
163
|
+
// link to the incident is the skip condition, not an error to swallow.
|
|
164
|
+
if (typeof adapter.listRelatedLinks === 'function') {
|
|
165
|
+
const linked = await adapter.listRelatedLinks(keyOrId)
|
|
166
|
+
if (linked.includes(incident.identifier)) return
|
|
167
|
+
}
|
|
168
|
+
await adapter.createRelatedLink(keyOrId, incident.identifier)
|
|
169
|
+
if (out) out.write(` related link added: ${incident.identifier}\n`)
|
|
170
|
+
}
|
|
171
|
+
// Per-type resolution: statesByType[issue type] overlays states, and null
|
|
172
|
+
// means "send no status for this bucket" — a deliberate skip, not a gap.
|
|
173
|
+
const statusFor = (bucket, type) => {
|
|
174
|
+
const name = effectiveStates(config, config.statesByType, type)[bucket]
|
|
175
|
+
if (name === null) return null
|
|
109
176
|
if (!name) {
|
|
110
177
|
throw new Error(`no status configured for the "${bucket}" bucket — fix ${CONFIG_FILE} -> states`)
|
|
111
178
|
}
|
|
112
179
|
return name
|
|
113
180
|
}
|
|
114
|
-
const settle = async (keyOrId, bucket) => {
|
|
181
|
+
const settle = async (keyOrId, bucket, type) => {
|
|
115
182
|
if (!bucket) return
|
|
116
|
-
|
|
183
|
+
const name = statusFor(bucket, type)
|
|
184
|
+
if (name === null) return
|
|
185
|
+
await adapter.transitionTo(keyOrId, name)
|
|
117
186
|
}
|
|
118
187
|
return {
|
|
119
188
|
prevalidateStates: (buckets) => {
|
|
120
|
-
for (const bucket of buckets)
|
|
189
|
+
for (const bucket of buckets) {
|
|
190
|
+
statusFor(bucket, mintType)
|
|
191
|
+
statusFor(bucket, config.jira.subtaskType)
|
|
192
|
+
}
|
|
121
193
|
},
|
|
122
194
|
searchTwin: (title) => adapter.searchIssues({ query: title, projectKey: config.jira.projectKey }),
|
|
123
195
|
twinAdvice: (twin, wanted, specName) =>
|
|
@@ -134,8 +206,10 @@ function applyOps({ adapter, config, kind = 'feature' }) {
|
|
|
134
206
|
assigneeId: issue && issue.assignee ? issue.assignee : undefined,
|
|
135
207
|
projectKey: config.jira.projectKey,
|
|
136
208
|
issueTypeName: mintType,
|
|
209
|
+
extraFields: severityFields,
|
|
137
210
|
})
|
|
138
|
-
await settle(created.identifier, issue && issue.state)
|
|
211
|
+
await settle(created.identifier, issue && issue.state, mintType)
|
|
212
|
+
await relateToIncident(created.identifier)
|
|
139
213
|
return created
|
|
140
214
|
},
|
|
141
215
|
updateIssue: async (existing, issue) => {
|
|
@@ -144,8 +218,10 @@ function applyOps({ adapter, config, kind = 'feature' }) {
|
|
|
144
218
|
// Null is meaningful here — it is how Jira unassigns — so the key is
|
|
145
219
|
// forwarded whenever the plan carries it, never truthiness-tested.
|
|
146
220
|
if ('assignee' in issue) updates.assigneeId = issue.assignee ?? null
|
|
221
|
+
if (severityFields) updates.extraFields = severityFields
|
|
147
222
|
if (Object.keys(updates).length) await adapter.updateIssue(existing.identifier, updates)
|
|
148
|
-
await settle(existing.identifier, issue.state)
|
|
223
|
+
await settle(existing.identifier, issue.state, mintType)
|
|
224
|
+
await relateToIncident(existing.identifier)
|
|
149
225
|
},
|
|
150
226
|
mintSubIssue: async (parentId, sub) => {
|
|
151
227
|
const created = await adapter.createSubIssue(parentId, {
|
|
@@ -154,7 +230,7 @@ function applyOps({ adapter, config, kind = 'feature' }) {
|
|
|
154
230
|
projectKey: config.jira.projectKey,
|
|
155
231
|
subtaskTypeName: config.jira.subtaskType,
|
|
156
232
|
})
|
|
157
|
-
await settle(created.identifier, sub.state)
|
|
233
|
+
await settle(created.identifier, sub.state, config.jira.subtaskType)
|
|
158
234
|
return created
|
|
159
235
|
},
|
|
160
236
|
updateSubIssue: async (sub) => {
|
|
@@ -162,7 +238,7 @@ function applyOps({ adapter, config, kind = 'feature' }) {
|
|
|
162
238
|
if (sub.name != null) updates.title = sub.name
|
|
163
239
|
if (sub.goal != null) updates.description = sub.goal
|
|
164
240
|
if (Object.keys(updates).length) await adapter.updateIssue(sub.id, updates)
|
|
165
|
-
await settle(sub.id, sub.state)
|
|
241
|
+
await settle(sub.id, sub.state, config.jira.subtaskType)
|
|
166
242
|
},
|
|
167
243
|
}
|
|
168
244
|
}
|
|
@@ -254,7 +330,7 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
|
|
|
254
330
|
snapshotDir,
|
|
255
331
|
plan,
|
|
256
332
|
adapter: cred.adapter,
|
|
257
|
-
ops: applyOps({ adapter: cred.adapter, config, kind: specKindOf(snapshotDir) }),
|
|
333
|
+
ops: applyOps({ adapter: cred.adapter, config, kind: specKindOf(snapshotDir), snapshotDir, out }),
|
|
258
334
|
forceNew: !!flags.forceNew,
|
|
259
335
|
program: PROGRAM,
|
|
260
336
|
})
|
|
@@ -504,15 +580,31 @@ async function specSyncStates(dir, config, flags, out) {
|
|
|
504
580
|
return 1
|
|
505
581
|
}
|
|
506
582
|
let states
|
|
583
|
+
let byType = null
|
|
507
584
|
try {
|
|
508
|
-
|
|
585
|
+
if (typeof cred.adapter.listIssueStatesByType === 'function') {
|
|
586
|
+
byType = await cred.adapter.listIssueStatesByType(config.jira.projectKey)
|
|
587
|
+
const byName = new Map()
|
|
588
|
+
for (const list of Object.values(byType)) for (const s of list) if (!byName.has(s.name)) byName.set(s.name, s)
|
|
589
|
+
states = [...byName.values()]
|
|
590
|
+
} else {
|
|
591
|
+
states = await cred.adapter.listIssueStates(config.jira.projectKey)
|
|
592
|
+
}
|
|
509
593
|
} catch (error) {
|
|
510
594
|
out.write(`${PROGRAM} states: ${error.message}\n`)
|
|
511
595
|
return 1
|
|
512
596
|
}
|
|
513
597
|
const names = states.map((s) => s.name)
|
|
514
598
|
if (flags.json) {
|
|
515
|
-
|
|
599
|
+
if (byType) {
|
|
600
|
+
// The keyed shape --workspace-states consumes: `{ "<type>": [names] }`,
|
|
601
|
+
// so the pre-write check can validate each type against its own
|
|
602
|
+
// workflow. (A bare array from an older engine is still accepted there.)
|
|
603
|
+
const keyed = {}
|
|
604
|
+
for (const [type, list] of Object.entries(byType)) keyed[type] = list.map((s) => s.name)
|
|
605
|
+
out.write(JSON.stringify(keyed, null, 2) + '\n')
|
|
606
|
+
return 0
|
|
607
|
+
}
|
|
516
608
|
out.write(JSON.stringify(names, null, 2) + '\n')
|
|
517
609
|
return 0
|
|
518
610
|
}
|
|
@@ -539,6 +631,29 @@ async function specSyncStates(dir, config, flags, out) {
|
|
|
539
631
|
lines.push(` ${bucket.padEnd(bw)} -> ${String(name).padEnd(nw)} ${tail}`)
|
|
540
632
|
}
|
|
541
633
|
if (missing.length) lines.push(` remap: ${PROGRAM} init-config --force --state <bucket>="<status>"`)
|
|
634
|
+
// Per-type overrides, each checked against ITS issue type's own workflow —
|
|
635
|
+
// the union above cannot see a status one type lacks. Absent entirely when
|
|
636
|
+
// no statesByType is configured; "not checked" when the adapter could not
|
|
637
|
+
// list statuses per type.
|
|
638
|
+
const overrideTypes = Object.keys(config.statesByType || {})
|
|
639
|
+
if (overrideTypes.length) {
|
|
640
|
+
lines.push('', ' statesByType overrides, checked per issue type:')
|
|
641
|
+
const lc = (s) => String(s).toLowerCase().trim()
|
|
642
|
+
for (const type of overrideTypes) {
|
|
643
|
+
const have = byType && type in byType ? new Set(byType[type].map((s) => lc(s.name))) : null
|
|
644
|
+
for (const [bucket, name] of Object.entries(config.statesByType[type])) {
|
|
645
|
+
const tail =
|
|
646
|
+
name === null
|
|
647
|
+
? 'sends no status'
|
|
648
|
+
: have === null
|
|
649
|
+
? 'not checked — statuses not listed per type'
|
|
650
|
+
: have.has(lc(name))
|
|
651
|
+
? 'ok'
|
|
652
|
+
: "MISSING from this type's workflow"
|
|
653
|
+
lines.push(` ${type}.${bucket} -> ${name === null ? '(none)' : name} ${tail}`)
|
|
654
|
+
}
|
|
655
|
+
}
|
|
656
|
+
}
|
|
542
657
|
out.write(lines.join('\n') + '\n')
|
|
543
658
|
return 0
|
|
544
659
|
}
|
|
@@ -698,6 +813,50 @@ function specSyncReleased(dir, config, rangeArg, flags, out) {
|
|
|
698
813
|
}
|
|
699
814
|
|
|
700
815
|
// ---------------------------------------------------------------------------
|
|
816
|
+
|
|
817
|
+
// `comment <spec> --file <f>` — post a file's markdown onto the spec's issue
|
|
818
|
+
// as a comment: the one surface one-way sync never touches, so no later push
|
|
819
|
+
// can clobber it. `/spec-complete` posts an incident's log through this.
|
|
820
|
+
// Misuse (no readable file) exits 1; every cannot-tell exits 0 and says so.
|
|
821
|
+
async function specSyncComment(dir, config, specArg, flags, out) {
|
|
822
|
+
const snapshotDir = resolveOrExit(specArg, dir, out)
|
|
823
|
+
if (!snapshotDir) return 1
|
|
824
|
+
const done = (msg) => {
|
|
825
|
+
out.write(`${PROGRAM} comment: ${msg}\n`)
|
|
826
|
+
return 0
|
|
827
|
+
}
|
|
828
|
+
if (!flags.file) {
|
|
829
|
+
out.write(`${PROGRAM} comment: pass --file <markdown file to post>\n`)
|
|
830
|
+
return 1
|
|
831
|
+
}
|
|
832
|
+
let body
|
|
833
|
+
try {
|
|
834
|
+
body = fs.readFileSync(flags.file, 'utf-8')
|
|
835
|
+
} catch (error) {
|
|
836
|
+
out.write(`${PROGRAM} comment: cannot read --file: ${error.message}\n`)
|
|
837
|
+
return 1
|
|
838
|
+
}
|
|
839
|
+
if (!body.trim()) {
|
|
840
|
+
out.write(`${PROGRAM} comment: --file is empty — nothing to post\n`)
|
|
841
|
+
return 1
|
|
842
|
+
}
|
|
843
|
+
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
844
|
+
const identifier = specHelpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
|
|
845
|
+
if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing posted`)
|
|
846
|
+
const cred = apiAdapterFor(config, flags)
|
|
847
|
+
const transport = kit.resolveTransport(flags, config, cred.ok)
|
|
848
|
+
if (transport === 'mcp') {
|
|
849
|
+
return done(`transport = mcp — post the file's contents onto ${identifier} with the Atlassian comment tool yourself`)
|
|
850
|
+
}
|
|
851
|
+
if (!cred.ok) return done(`no credentials — ${cred.error.split('\n')[0]}; nothing posted`)
|
|
852
|
+
try {
|
|
853
|
+
await cred.adapter.createComment(identifier, body)
|
|
854
|
+
return done(`${identifier} — comment posted (${body.length} characters)`)
|
|
855
|
+
} catch (error) {
|
|
856
|
+
return done(`could not reach Jira (${String(error.message).split('\n')[0]}); nothing posted`)
|
|
857
|
+
}
|
|
858
|
+
}
|
|
859
|
+
|
|
701
860
|
// `preserve <spec>` — post the issue's current description back onto the issue
|
|
702
861
|
// as a comment BEFORE the linking push replaces it. Every cannot-tell exits 0:
|
|
703
862
|
// a missing link, an unreachable Jira, an issue with no description, and an
|
|
@@ -1113,6 +1272,7 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
|
|
|
1113
1272
|
ref [<spec>] the Refs: trailer value for this branch
|
|
1114
1273
|
released [<range>] tickets a commit range contains
|
|
1115
1274
|
preserve <spec> [--text <f>] keep an adopted issue's original report
|
|
1275
|
+
comment <spec> --file <f> post a file onto the issue as a comment
|
|
1116
1276
|
credentials <status|set|unset> the email + API-token pair (user-level)
|
|
1117
1277
|
init-config --site-url … --project-key … write the config
|
|
1118
1278
|
doctor [--check-remote] [--json] readiness report
|
|
@@ -1191,6 +1351,8 @@ async function specSync(rest, io = {}) {
|
|
|
1191
1351
|
return specSyncReleased(dir, config, positional[0], flags, out)
|
|
1192
1352
|
case 'preserve':
|
|
1193
1353
|
return specSyncPreserve(dir, config, positional[0], flags, out)
|
|
1354
|
+
case 'comment':
|
|
1355
|
+
return specSyncComment(dir, config, positional[0], flags, out)
|
|
1194
1356
|
case 'credentials':
|
|
1195
1357
|
return specSyncCredentials(dir, config, positional[0], flags, out)
|
|
1196
1358
|
default:
|
|
@@ -1219,6 +1381,7 @@ function parseArgs(args, sub) {
|
|
|
1219
1381
|
'--stored': { kind: 'path' },
|
|
1220
1382
|
'--remote': { kind: 'path' },
|
|
1221
1383
|
'--text': { kind: 'path' },
|
|
1384
|
+
'--file': { kind: 'path' },
|
|
1222
1385
|
'--workspace-states': { kind: 'path', name: 'workspaceStates' },
|
|
1223
1386
|
'--skip-state-check': { kind: 'boolean', name: 'skipStateCheck' },
|
|
1224
1387
|
'--via': { kind: 'string' },
|
|
@@ -39,7 +39,7 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
39
39
|
// (`feature`/`bug`/`hotfix`/`chore`, from the spec folder's prefix), falling
|
|
40
40
|
// back to `issueType` — `{ "bug": "Bug" }` files bug specs as Jira Bugs.
|
|
41
41
|
// Empty means one type for everything, as before.
|
|
42
|
-
jira: Object.freeze({ siteUrl: '', projectKey: '', issueType: 'Task', subtaskType: 'Subtask', issueTypeByKind: Object.freeze({}) }),
|
|
42
|
+
jira: Object.freeze({ siteUrl: '', projectKey: '', issueType: 'Task', subtaskType: 'Subtask', issueTypeByKind: Object.freeze({}), severityField: '' }),
|
|
43
43
|
// A spec is a Jira ISSUE; each phase a SUBTASK of it. `tasks` selects how the
|
|
44
44
|
// phase's checkboxes reach that subtask's description (as an ADF task list —
|
|
45
45
|
// live checkboxes, still a read-only mirror).
|
|
@@ -106,6 +106,7 @@ function defaults() {
|
|
|
106
106
|
jira: { ...DEFAULT_CONFIG.jira, issueTypeByKind: { ...DEFAULT_CONFIG.jira.issueTypeByKind } },
|
|
107
107
|
mapping: { ...DEFAULT_CONFIG.mapping },
|
|
108
108
|
states: { ...DEFAULT_CONFIG.states },
|
|
109
|
+
statesByType: {},
|
|
109
110
|
stateAliases: {},
|
|
110
111
|
snapshot: { ...DEFAULT_CONFIG.snapshot },
|
|
111
112
|
fields: { ...DEFAULT_CONFIG.fields },
|
|
@@ -126,7 +127,7 @@ function defaults() {
|
|
|
126
127
|
}
|
|
127
128
|
|
|
128
129
|
const { isObject, stringList, assign } = kitConfig
|
|
129
|
-
const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
130
|
+
const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
130
131
|
kitConfig.makeMergeHelpers({
|
|
131
132
|
configFile: CONFIG_FILE,
|
|
132
133
|
ownership: OWNERSHIP,
|
|
@@ -146,11 +147,12 @@ function mergeConfig(base, parsed) {
|
|
|
146
147
|
assign(base.jira, parsed.jira, 'projectKey', 'string?')
|
|
147
148
|
assign(base.jira, parsed.jira, 'issueType', 'string')
|
|
148
149
|
assign(base.jira, parsed.jira, 'subtaskType', 'string')
|
|
150
|
+
assign(base.jira, parsed.jira, 'severityField', 'string?')
|
|
149
151
|
if (isObject(parsed.jira.issueTypeByKind)) {
|
|
150
152
|
// Only the kinds a spec folder can actually be — an unknown key is
|
|
151
153
|
// dropped, matching the other providers' by-kind validation.
|
|
152
154
|
const byKind = {}
|
|
153
|
-
for (const kind of ['feature', 'bug', 'hotfix', 'chore']) {
|
|
155
|
+
for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident']) {
|
|
154
156
|
const value = parsed.jira.issueTypeByKind[kind]
|
|
155
157
|
if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
|
|
156
158
|
}
|
|
@@ -173,6 +175,7 @@ function mergeConfig(base, parsed) {
|
|
|
173
175
|
}
|
|
174
176
|
|
|
175
177
|
mergeStates(base, parsed)
|
|
178
|
+
mergeStateOverrides(base, parsed, 'statesByType')
|
|
176
179
|
|
|
177
180
|
if (isObject(parsed.snapshot)) {
|
|
178
181
|
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:
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
}
|