@skitterbyte/skitterspec-jira 2.1.0 → 2.3.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.
@@ -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-jira",
3
- "version": "2.1.0",
3
+ "version": "2.3.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
  }
@@ -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
  }
@@ -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
- const statusFor = (bucket) => {
108
- const name = config.states && config.states[bucket]
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
- await adapter.transitionTo(keyOrId, statusFor(bucket))
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) statusFor(bucket)
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
- states = await cred.adapter.listIssueStates(config.jira.projectKey)
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
- // The bare array --workspace-states consumes.
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,