@skitterbyte/skitterspec-linear 18.1.0 → 18.1.2

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.
@@ -0,0 +1,380 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The release seam — `spec-sync release create | deployed | complete`.
5
+ *
6
+ * A release today is a git tag and nothing more, while `released` already
7
+ * knows exactly which tickets a tag contains. These verbs write that down where
8
+ * people look: a release object on the tracker holding its tickets, which the
9
+ * host project's CI moves through its deploy stages.
10
+ *
11
+ * SKITTERSPEC DECIDES A RELEASE'S CONTENTS, never the tracker. The ticket set
12
+ * is `ticketsInRange` + `partitionStageMoves` over previous-tag → this-tag:
13
+ * the `Refs:` trailers, bookkeeping commits ignored, foreign refs excluded.
14
+ * That is one definition of "what shipped", shared with `released`.
15
+ *
16
+ * EVERY VERB IS A DRY RUN UNLESS `--apply`. CI passes it; a person reading the
17
+ * plan does not have to.
18
+ *
19
+ * IDEMPOTENT BY LOOKUP, not by memory. `create` finds the release for the tag
20
+ * first and updates it; a retry on the same tag never mints a duplicate. A
21
+ * lookup that FAILED is a cannot-tell, and refuses rather than creating
22
+ * (`.claude/rules/negative-checks.md` rule 4) — creating on "I could not see
23
+ * one" is exactly how duplicates are made.
24
+ *
25
+ * Tracker calls arrive as OPTIONAL adapter ops, feature-detected: a provider
26
+ * without them makes every verb refuse in one line. The ops:
27
+ *
28
+ * - `releaseFind(tag)` → release | null (throws = cannot tell)
29
+ * - `releaseCreate({ tag, name, body, prerelease })` → release
30
+ * - `releaseUpdate(release, { name, body })`
31
+ * - `releaseAttach(release, tickets)` → `{ attached, already }`
32
+ * - `releaseStage(release, optionName, tickets)` → `{ set }`
33
+ * - `releaseComplete(release)`
34
+ * - `releaseTagExists(tag)` OPTIONAL → true | false (throws = cannot tell)
35
+ *
36
+ * A release object carries at least `{ id, url, body }`.
37
+ */
38
+
39
+ const { execFileSync } = require('node:child_process')
40
+
41
+ const { ticketsInRange, partitionStageMoves, stageOrderWarning } = require('./released.js')
42
+
43
+ const REQUIRED_OPS = ['releaseFind', 'releaseCreate', 'releaseUpdate', 'releaseAttach', 'releaseStage', 'releaseComplete']
44
+
45
+ // The line a release body carries so the next verb can read where the release
46
+ // is without asking anything else. An HTML comment: invisible where the body is
47
+ // rendered as markdown, and never confused with prose a person wrote.
48
+ const MARKER_RE = /<!--\s*skitterspec:release\s+v1\s+stage=([A-Za-z0-9_.-]*)\s*-->/
49
+
50
+ function stageOf(body) {
51
+ const m = MARKER_RE.exec(String(body || ''))
52
+ return m ? m[1] || null : null
53
+ }
54
+
55
+ function withStage(body, key) {
56
+ const line = `<!-- skitterspec:release v1 stage=${key || ''} -->`
57
+ const text = String(body || '')
58
+ return MARKER_RE.test(text) ? text.replace(MARKER_RE, line) : `${text.replace(/\s+$/, '')}\n\n${line}\n`
59
+ }
60
+
61
+ function gitReader(dir) {
62
+ return (argv) => {
63
+ try {
64
+ return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }).trim()
65
+ } catch {
66
+ return null
67
+ }
68
+ }
69
+ }
70
+
71
+ /**
72
+ * The series a tag belongs to: the configured `tagPrefix` it starts with,
73
+ * longest first so `skitterspec-github@` is not read as `skitterspec`.
74
+ */
75
+ function seriesFor(series, tag) {
76
+ return (
77
+ [...(series || [])]
78
+ .filter((s) => s && s.tagPrefix)
79
+ .sort((a, b) => b.tagPrefix.length - a.tagPrefix.length)
80
+ .find((s) => String(tag).startsWith(s.tagPrefix)) || null
81
+ )
82
+ }
83
+
84
+ /**
85
+ * Previous tag in the same series → this tag.
86
+ *
87
+ * `git describe --match '<prefix>*' <tag>^` walks back from the commit BEFORE
88
+ * this tag, so a hotfix tag cut from a release tag ranges from that base, and
89
+ * a tag never ranges from itself.
90
+ *
91
+ * WHAT WOULD FOOL THIS: a shallow clone. `describe` there finds no previous tag
92
+ * and the range silently becomes "everything" — every ticket in history landing
93
+ * on one release. So shallowness is asked about first, as a positive signal,
94
+ * and refused with the fix (CI checkout `fetch-depth: 0`).
95
+ */
96
+ function resolveRange(dir, tag, prefix, git = gitReader(dir)) {
97
+ if (git(['rev-parse', '--is-shallow-repository']) === 'true') {
98
+ return {
99
+ ok: false,
100
+ error: 'this clone is shallow, so the previous tag cannot be found — check out with fetch-depth: 0',
101
+ }
102
+ }
103
+ if (!git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`])) {
104
+ return { ok: false, error: `no tag ${tag} in this repo` }
105
+ }
106
+ const previous = git(['describe', '--tags', '--abbrev=0', '--match', `${prefix}*`, `${tag}^`])
107
+ if (previous) return { ok: true, range: `${previous}..${tag}`, previous }
108
+ return { ok: true, range: tag, previous: null, first: true }
109
+ }
110
+
111
+ /**
112
+ * Compose the release body: the notes, then the issues, then the marker. Pure,
113
+ * so a re-run on unchanged inputs produces the same text — which is what lets
114
+ * `create` say "no change" rather than rewrite a release on every CI retry.
115
+ */
116
+ function composeBody({ notes, tickets, links, stage, describe }) {
117
+ const parts = []
118
+ if (notes && String(notes).trim()) parts.push(String(notes).trim())
119
+ if (tickets.length) {
120
+ parts.push(['## Issues', '', ...tickets.map((t) => `- ${describe ? describe(t) : t.ref}`)].join('\n'))
121
+ }
122
+ if (links && links.length) {
123
+ parts.push(['## Links', '', ...links.map((l) => `- [${l.label || l.url}](${l.url})`)].join('\n'))
124
+ }
125
+ return withStage(parts.join('\n\n'), stage)
126
+ }
127
+
128
+ // `--link <url>[=label]`, repeatable. http(s) only: this lands in a body a
129
+ // tracker renders as a link, and a `javascript:` url there is script.
130
+ function parseLinks(raw) {
131
+ const out = []
132
+ const bad = []
133
+ for (const item of raw || []) {
134
+ const s = String(item)
135
+ const eq = s.indexOf('=', s.indexOf('://') + 3)
136
+ const url = eq > 0 ? s.slice(0, eq) : s
137
+ const label = eq > 0 ? s.slice(eq + 1) : null
138
+ if (/^https?:\/\//i.test(url)) out.push({ url, label })
139
+ else bad.push(s)
140
+ }
141
+ return { links: out, bad }
142
+ }
143
+
144
+ /**
145
+ * @param {object} p
146
+ * - `tracker` the tracker's name in messages
147
+ * - `program` 'spec-sync'
148
+ * - `readCommits(dir, range)` → `{ ok, commits | error }` (the provider's `released` reader)
149
+ * - `ticketOptions(config)` → the `ticketsInRange` options (ignorePaths, refPattern, …)
150
+ * - `teamKey(config)` → the foreign-ref key for `partitionStageMoves` ('' for none)
151
+ * - `listSpecs(dir, config)` → `[{ identifier, bucket, spec }]`
152
+ * - `series(config)` → `[{ tagPrefix, envs: { key: optionName } }]`
153
+ * - `adapterFor(config, flags)` → `{ ok, adapter | error }`
154
+ * - `describe(ticket)` OPTIONAL → the issue line in the body
155
+ * - `impossibleOverMcp` OPTIONAL — the transport answer for a provider whose
156
+ * MCP server cannot write releases; `(config, flags) → string | null`
157
+ */
158
+ function makeReleaseCommands(p) {
159
+ const prog = `${p.program || 'spec-sync'} release`
160
+
161
+ function refuse(out, msg) {
162
+ out.write(`${prog}: ${msg}\n`)
163
+ return 1
164
+ }
165
+
166
+ // Everything a verb needs before touching the tracker, refused in one line
167
+ // each so CI logs say exactly what was missing.
168
+ function prepare(dir, config, tagArg, flags, out) {
169
+ if (!tagArg) return { code: refuse(out, 'pass the tag, e.g. skitterspec@1.4.0') }
170
+ const series = p.series(config)
171
+ if (!series.length) return { code: refuse(out, `no releases.series configured — add one to the ${p.tracker} config`) }
172
+ let tag = String(tagArg)
173
+ // A bare version is accepted when exactly one series is configured — the
174
+ // common single-package repo — and refused otherwise rather than guessed.
175
+ if (!seriesFor(series, tag)) {
176
+ if (series.length === 1 && /^v?\d/.test(tag)) tag = `${series[0].tagPrefix}${tag}`
177
+ else return { code: refuse(out, `${tag} matches no releases.series tagPrefix (${series.map((s) => s.tagPrefix).join(', ')})`) }
178
+ }
179
+ const s = seriesFor(series, tag)
180
+ if (p.impossibleOverMcp) {
181
+ const why = p.impossibleOverMcp(config, flags)
182
+ if (why) return { code: refuse(out, why) }
183
+ }
184
+ const got = p.adapterFor(config, flags)
185
+ if (!got.ok) return { code: refuse(out, got.error) }
186
+ const missing = REQUIRED_OPS.filter((op) => typeof got.adapter[op] !== 'function')
187
+ if (missing.length) return { code: refuse(out, `the ${p.tracker} provider has no release support (${missing.join(', ')})`) }
188
+ return { tag, series: s, adapter: got.adapter }
189
+ }
190
+
191
+ // The tickets a tag's range contains, split into what the release holds and
192
+ // what it reports. Recomputed by every verb — stateless, so `deployed` and
193
+ // `complete` act on the same set `create` attached without storing it.
194
+ function ticketsOf(dir, config, tag, s) {
195
+ const range = resolveRange(dir, tag, s.tagPrefix)
196
+ if (!range.ok) return range
197
+ const read = p.readCommits(dir, range.range)
198
+ if (!read.ok) return { ok: false, error: read.error }
199
+ const report = ticketsInRange(read.commits, p.ticketOptions(config))
200
+ const parts = partitionStageMoves({ tickets: report.tickets, teamKey: p.teamKey(config), specs: p.listSpecs(dir, config) })
201
+ // Movable AND unfinished: code that landed via /spec-to-main really is in
202
+ // this release. Attaching never touches workflow state — push owns that.
203
+ const attach = [...parts.movable, ...parts.unfinished]
204
+ return { ok: true, range, report, parts, attach }
205
+ }
206
+
207
+ function planLines(t, tag) {
208
+ const lines = [
209
+ ` range: ${t.range.range}${t.range.first ? ' (no previous release in this series — everything up to the tag)' : ''}`,
210
+ ` attach: ${t.attach.map((x) => x.ref).join(', ') || 'none'}`,
211
+ ]
212
+ if (t.parts.unfinished.length) lines.push(` (in flight: ${t.parts.unfinished.map((x) => x.ref).join(', ')} — attached, state left to push)`)
213
+ if (t.parts.foreign.length) lines.push(` foreign: ${t.parts.foreign.map((x) => x.ref).join(', ')} — not attached`)
214
+ if (t.parts.unlinked.length) lines.push(` unlinked: ${t.parts.unlinked.map((x) => x.ref).join(', ')} — no spec claims them, not attached`)
215
+ lines.push(` ${t.report.unreferenced} commit(s) carry no Refs: trailer${t.report.ignored ? `, ${t.report.ignored} bookkeeping ignored` : ''}`)
216
+ // Without this line a range from before a tracker move reads as mostly
217
+ // missing: those commits are neither unreferenced nor attached.
218
+ if (t.report.historical) lines.push(` ${t.report.historical} commit(s) reference an earlier tracker — not attached`)
219
+ return lines
220
+ }
221
+
222
+ async function find(adapter, tag, out) {
223
+ try {
224
+ return { ok: true, release: await adapter.releaseFind(tag) }
225
+ } catch (error) {
226
+ refuse(out, `could not look up the release for ${tag} (${String(error.message).split('\n')[0]}) — refusing rather than risk a duplicate`)
227
+ return { ok: false }
228
+ }
229
+ }
230
+
231
+ async function create(dir, config, tagArg, flags, out) {
232
+ const prep = prepare(dir, config, tagArg, flags, out)
233
+ if (prep.code != null) return prep.code
234
+ const { tag, series: s, adapter } = prep
235
+ const t = ticketsOf(dir, config, tag, s)
236
+ if (!t.ok) return refuse(out, t.error)
237
+ const { links, bad } = parseLinks(flags.links)
238
+ if (bad.length) return refuse(out, `--link must be http(s): ${bad.join(', ')}`)
239
+ let notes = null
240
+ if (flags.notes) {
241
+ try {
242
+ notes = require('node:fs').readFileSync(flags.notes, 'utf-8')
243
+ } catch (error) {
244
+ return refuse(out, `cannot read --notes: ${error.message}`)
245
+ }
246
+ }
247
+ const envKeys = Object.keys(s.envs || {})
248
+ const stage = flags.stage || envKeys[0] || null
249
+ if (stage && envKeys.length && !envKeys.includes(stage)) {
250
+ return refuse(out, `--stage ${stage} is not an env of ${s.tagPrefix} (${envKeys.join(', ')})`)
251
+ }
252
+
253
+ // A tracker that would CREATE a missing tag from the default branch must
254
+ // not be handed one it has not got — the release would point at the wrong
255
+ // commit. Positive signals only: `false` refuses, a throw is a cannot-tell
256
+ // and the create goes ahead exactly as it would have.
257
+ if (adapter.releaseTagExists) {
258
+ let exists = null
259
+ try {
260
+ exists = await adapter.releaseTagExists(tag)
261
+ } catch {
262
+ exists = null
263
+ }
264
+ if (exists === false) return refuse(out, `${tag} is not on the ${p.tracker} remote yet — push the tag first`)
265
+ }
266
+
267
+ const found = await find(adapter, tag, out)
268
+ if (!found.ok) return 1
269
+ const existing = found.release
270
+ // A release already past its first stage keeps the stage it is at: a CI
271
+ // retry of `create` must not drag a deployed release back.
272
+ const keep = existing ? stageOf(existing.body) : null
273
+ const body = composeBody({ notes, tickets: await describeAll(adapter, t.attach), links, stage: keep || stage, describe: p.describe })
274
+
275
+ const header = [`${prog} create: ${tag}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`, ...planLines(t, tag)]
276
+ if (!flags.apply) {
277
+ header.push(` would ${existing ? (existing.body === body ? 'leave the release unchanged' : 'update the release') : 'create the release'}${existing && existing.url ? ` (${existing.url})` : ''}`)
278
+ return emit(out, flags, header, { tag, range: t.range.range, attach: t.attach.map((x) => x.ref), apply: false, existing: !!existing })
279
+ }
280
+ let release = existing
281
+ if (!release) {
282
+ release = await adapter.releaseCreate({ tag, name: tag, body, prerelease: true })
283
+ header.push(` created: ${release.url || release.id}`)
284
+ } else if (release.body !== body) {
285
+ await adapter.releaseUpdate(release, { name: tag, body })
286
+ header.push(` updated: ${release.url || release.id}`)
287
+ } else {
288
+ header.push(` unchanged: ${release.url || release.id}`)
289
+ }
290
+ const attached = await adapter.releaseAttach(release, t.attach)
291
+ header.push(` issues: ${attached.attached} noted, ${attached.already} already noted`)
292
+ return emit(out, flags, header, { tag, range: t.range.range, attach: t.attach.map((x) => x.ref), apply: true, url: release.url || null })
293
+ }
294
+
295
+ async function deployed(dir, config, tagArg, envKey, flags, out) {
296
+ const prep = prepare(dir, config, tagArg, flags, out)
297
+ if (prep.code != null) return prep.code
298
+ const { tag, series: s, adapter } = prep
299
+ const envs = s.envs || {}
300
+ if (!envKey || !(envKey in envs)) {
301
+ return refuse(out, `pass an env of ${s.tagPrefix}: ${Object.keys(envs).join(', ') || '(none configured)'}`)
302
+ }
303
+ const found = await find(adapter, tag, out)
304
+ if (!found.ok) return 1
305
+ if (!found.release) return refuse(out, `no release for ${tag} yet — run \`release create ${tag}\` first`)
306
+ const t = ticketsOf(dir, config, tag, s)
307
+ if (!t.ok) return refuse(out, t.error)
308
+ const lines = [`${prog} deployed: ${tag} → ${envKey}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`]
309
+ // WARNS, NEVER REFUSES: a rollback and a hotfix straight to prod are both
310
+ // legitimate. The order is the series' own env order.
311
+ const ladder = Object.keys(envs).map((key) => ({ key, state: key }))
312
+ const from = stageOf(found.release.body)
313
+ const warn = from ? stageOrderWarning(ladder, from, envKey) : null
314
+ if (warn) lines.push(` !! ${warn}`)
315
+ lines.push(` issues: ${t.attach.map((x) => x.ref).join(', ') || 'none'} → "${envs[envKey]}"`)
316
+ if (!flags.apply) return emit(out, flags, lines, { tag, env: envKey, apply: false, warn })
317
+ const staged = await adapter.releaseStage(found.release, envs[envKey], t.attach)
318
+ await adapter.releaseUpdate(found.release, { name: tag, body: withStage(found.release.body, envKey) })
319
+ lines.push(` set: ${staged.set} issue(s)`)
320
+ return emit(out, flags, lines, { tag, env: envKey, apply: true, warn, set: staged.set })
321
+ }
322
+
323
+ async function complete(dir, config, tagArg, flags, out) {
324
+ const prep = prepare(dir, config, tagArg, flags, out)
325
+ if (prep.code != null) return prep.code
326
+ const { tag, adapter } = prep
327
+ const found = await find(adapter, tag, out)
328
+ if (!found.ok) return 1
329
+ if (!found.release) return refuse(out, `no release for ${tag} yet — run \`release create ${tag}\` first`)
330
+ const lines = [`${prog} complete: ${tag}${flags.apply ? '' : ' (dry run — pass --apply to write)'}`]
331
+ if (!flags.apply) {
332
+ lines.push(` would mark ${found.release.url || found.release.id} complete`)
333
+ return emit(out, flags, lines, { tag, apply: false })
334
+ }
335
+ await adapter.releaseComplete(found.release)
336
+ lines.push(` completed: ${found.release.url || found.release.id}`)
337
+ return emit(out, flags, lines, { tag, apply: true })
338
+ }
339
+
340
+ // Titles for the body, best-effort: a ticket the tracker cannot read is
341
+ // still listed, by ref. The body is information, not a gate.
342
+ async function describeAll(adapter, tickets) {
343
+ const out = []
344
+ for (const t of tickets) {
345
+ let title = null
346
+ if (adapter.readIssue) {
347
+ try {
348
+ const issue = await adapter.readIssue(t.ref)
349
+ title = issue && issue.title ? issue.title : null
350
+ } catch {
351
+ title = null
352
+ }
353
+ }
354
+ out.push({ ...t, title })
355
+ }
356
+ return out
357
+ }
358
+
359
+ function emit(out, flags, lines, json) {
360
+ out.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
361
+ return 0
362
+ }
363
+
364
+ async function run(dir, config, args, flags, out) {
365
+ const [verb, tag, env] = args
366
+ if (verb === 'create') return create(dir, config, tag, flags, out)
367
+ if (verb === 'deployed') return deployed(dir, config, tag, env, flags, out)
368
+ if (verb === 'complete') return complete(dir, config, tag, flags, out)
369
+ out.write(
370
+ `Usage: ${prog} create <tag> [--notes <f>] [--link <url>[=label]] [--stage <env>] [--apply] [--json]\n` +
371
+ ` ${prog} deployed <tag> <env> [--apply] [--json]\n` +
372
+ ` ${prog} complete <tag> [--apply] [--json]\n`,
373
+ )
374
+ return verb ? 1 : 0
375
+ }
376
+
377
+ return { run, create, deployed, complete }
378
+ }
379
+
380
+ module.exports = { makeReleaseCommands, resolveRange, seriesFor, composeBody, stageOf, withStage, parseLinks, REQUIRED_OPS }
@@ -14,7 +14,7 @@
14
14
  */
15
15
 
16
16
  const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
17
- const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
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')
20
20
  const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
@@ -66,6 +66,7 @@ module.exports = {
66
66
  // Did someone else edit the tracker's description since the last push?
67
67
  // Three-valued; `null` is cannot-tell and must never be reported as drift.
68
68
  remoteDescriptionEdited,
69
+ remoteSubIssueEdited,
69
70
  // Provider seams: the frontmatter field vocabulary and the markdown dialect
70
71
  // a provider's config supplies (`config.fields` / `config.dialect`).
71
72
  fieldsOf,
@@ -137,6 +137,30 @@ function remoteDescriptionEdited(snapshot, remote, config) {
137
137
 
138
138
  return hashField(stream(text, config)) !== recorded
139
139
  }
140
+
141
+ /**
142
+ * The same question for one phase SUB-ISSUE: has its body been edited on the
143
+ * tracker since the last push? It matters most where the tracker renders a
144
+ * phase's task list as clickable boxes — GitHub does — because ticking one
145
+ * there is an edit the next push replaces.
146
+ *
147
+ * The same three answers and the same cannot-tells as above, plus one of its
148
+ * own: no `subIssueStreams` in the snapshot, or none for this id. Every
149
+ * snapshot written before this existed lacks it, and a phase whose body was
150
+ * never sent (no goal) has nothing recorded.
151
+ *
152
+ * @param {object|null} snapshot the committed last-pushed snapshot
153
+ * @param {string} id the sub-issue's id as the snapshot keys it
154
+ * @param {object|null} remote what the tracker currently holds for it
155
+ * @returns {boolean|null}
156
+ */
157
+ function remoteSubIssueEdited(snapshot, id, remote, config) {
158
+ const streams = snapshot && snapshot.subIssueStreams
159
+ if (!streams || typeof streams !== 'object' || Array.isArray(streams)) return null
160
+ const recorded = streams[String(id)]
161
+ if (typeof recorded !== 'string' || !recorded) return null
162
+ return remoteDescriptionEdited({ issueFields: { descriptionStream: recorded } }, remote, config)
163
+ }
140
164
  // A phase SUB-ISSUE: its name, goal and state (all repo-owned).
141
165
  const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
142
166
 
@@ -160,6 +184,13 @@ function snapshotOf(projection, config) {
160
184
  issue: specIssueHash(p),
161
185
  issueFields: specIssueFieldHashes(p, config),
162
186
  subIssues: byId(p.subIssues, subIssueHash),
187
+ // Recorded and never planned on, like `descriptionStream`: `planChanges`
188
+ // reads `subIssues` by name, so this key cannot make a push pending. Only a
189
+ // phase whose body is actually sent (a string goal) gets one.
190
+ subIssueStreams: byId(
191
+ (p.subIssues || []).filter((s) => s && typeof s.goal === 'string'),
192
+ (s) => hashField(stream(s.goal, config)),
193
+ ),
163
194
  }
164
195
  }
165
196
 
@@ -295,6 +326,7 @@ function isEmptyPlan(plan) {
295
326
  module.exports = {
296
327
  planChanges,
297
328
  remoteDescriptionEdited,
329
+ remoteSubIssueEdited,
298
330
  issueChanges,
299
331
  specIssueFieldHashes,
300
332
  snapshotOf,
@@ -570,6 +570,15 @@ const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
570
570
  // Buckets where a spec is FINISHED, and so has nobody working on it.
571
571
  const TERMINAL_BUCKETS = ['complete', 'cancelled']
572
572
 
573
+ // A phase's state once its SPEC's bucket has a say. Cancelling a spec abandons
574
+ // every phase not already done — left alone, those sub-issues stay open in
575
+ // Backlog under a closed parent, which reads as work still owed. A phase that
576
+ // was finished keeps `complete`: it shipped before the spec was dropped.
577
+ function phaseStateUnder(workflowState, phaseState) {
578
+ if (workflowState === 'cancelled' && phaseState !== 'complete') return 'cancelled'
579
+ return phaseState
580
+ }
581
+
573
582
  /**
574
583
  * The Linear user this spec is assigned to, AS PROJECTED — which is not simply
575
584
  * what the frontmatter records.
@@ -714,7 +723,7 @@ function normalizeLocal(snapshotDir, config) {
714
723
  ref: p.phase,
715
724
  name: p.name,
716
725
  goal: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
717
- state: p.state,
726
+ state: phaseStateUnder(workflowState, p.state),
718
727
  })),
719
728
  workflowState,
720
729
  // Who is building this. `toFieldSet` drops it unless the repo listed