@skitterbyte/skitterspec-jira 2.7.0 → 2.9.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.
Files changed (45) hide show
  1. package/assets/claude-md-section.md +6 -0
  2. package/assets/core/env.config.json.example +5 -0
  3. package/assets/core/env.config.md +26 -5
  4. package/assets/review/page.html +9 -0
  5. package/assets/rules/spec-planning.md +65 -12
  6. package/assets/rules/spec-reports.md +8 -1
  7. package/assets/skills/spec/SKILL.md +31 -14
  8. package/assets/skills/spec-cancel/SKILL.md +7 -0
  9. package/assets/skills/spec-complete/SKILL.md +6 -0
  10. package/assets/skills/spec-epic-next/SKILL.md +83 -0
  11. package/assets/skills/spec-init/SKILL.md +35 -3
  12. package/assets/skills/spec-next/SKILL.md +38 -1
  13. package/assets/skills/spec-start/SKILL.md +2 -2
  14. package/assets/skills/spec-tada/SKILL.md +153 -0
  15. package/bin/skitterspec-jira.js +5 -0
  16. package/package.json +1 -1
  17. package/src/cli.js +473 -25
  18. package/src/env/config.js +57 -6
  19. package/src/env/epic.js +69 -19
  20. package/src/env/epicpage.js +87 -39
  21. package/src/env/epicread.js +41 -3
  22. package/src/env/integrate.js +48 -1
  23. package/src/env/nextaction.js +78 -1
  24. package/src/env/project.js +54 -3
  25. package/src/env/projectedit.js +148 -0
  26. package/src/env/resolve.js +1 -0
  27. package/src/env/review.js +21 -3
  28. package/src/env/serve.js +44 -8
  29. package/src/env/specbranches.js +120 -0
  30. package/src/env/teardown.js +18 -3
  31. package/src/gating.js +16 -4
  32. package/src/init.js +11 -3
  33. package/src/tada/commits.js +145 -0
  34. package/src/tada/digest.js +260 -0
  35. package/src/tada/format.js +37 -0
  36. package/src/tada/page.js +213 -0
  37. package/src/tada/repo.js +102 -0
  38. package/src/tada/serve.js +127 -0
  39. package/src/tada/specs.js +146 -0
  40. package/src/tada/transcripts.js +258 -0
  41. package/src/tada/window.js +156 -0
  42. package/src/vendor/provider-kit/src/apply.js +25 -1
  43. package/src/vendor/sync-core/src/compare.js +10 -2
  44. package/src/vendor/sync-core/src/push.js +14 -3
  45. /package/assets/commands/{epic.md → spec-epic.md} +0 -0
@@ -0,0 +1,258 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Claude Code's session transcripts, read down to what a ta-da list needs:
5
+ * which prompts a person typed, where they were standing (cwd + git branch),
6
+ * and when. Everything else — tool calls, tool results, reminders, caveats —
7
+ * is dropped here, so the model is handed a digest and never a transcript.
8
+ *
9
+ * WHAT WOULD FOOL THIS: the transcript format is Claude Code's, not ours, and
10
+ * nothing promises it stays put. A renamed field would read as a day with no
11
+ * activity — an absence that proves nothing. So a file touched inside the
12
+ * window that yields no readable entry is reported as `cannot tell`, never
13
+ * silently as an idle day (`.claude/rules/negative-checks.md`).
14
+ */
15
+
16
+ const fs = require('node:fs')
17
+ const os = require('node:os')
18
+ const path = require('node:path')
19
+ const readline = require('node:readline')
20
+
21
+ // Enough to recognise a prompt, short enough that a long day stays a digest.
22
+ const PROMPT_CHARS = 200
23
+ // Per session and place: the first few say what it set out to do, the last
24
+ // few where it ended up. The middle is counted, not shown.
25
+ const KEEP_HEAD = 3
26
+ const KEEP_TAIL = 3
27
+
28
+ // Built-in commands that move the session around rather than do work. Kept out
29
+ // so a recap is not half `/clear`; a skill's command is work and stays.
30
+ const HOUSEKEEPING = new Set([
31
+ 'add-dir', 'clear', 'compact', 'config', 'context', 'cost', 'doctor', 'exit', 'fast',
32
+ 'help', 'login', 'logout', 'memory', 'model', 'permissions', 'quit', 'resume', 'status',
33
+ ])
34
+
35
+ /** Where Claude Code keeps transcripts — `CLAUDE_CONFIG_DIR` moves it. */
36
+ function defaultRoot(env = process.env) {
37
+ const base = env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')
38
+ return path.join(base, 'projects')
39
+ }
40
+
41
+ /**
42
+ * Every `<root>/<project>/<session>.jsonl` modified at or after `since`. A file
43
+ * last written before the window opened cannot hold an entry inside it, so
44
+ * this is a skip and not a guess. Subagent transcripts live a level deeper and
45
+ * are deliberately not read: their prompts were written by Claude, not typed.
46
+ */
47
+ function listTranscripts(root, since) {
48
+ let projects
49
+ try {
50
+ projects = fs.readdirSync(root, { withFileTypes: true })
51
+ } catch {
52
+ return []
53
+ }
54
+ const out = []
55
+ for (const p of projects) {
56
+ if (!p.isDirectory()) continue
57
+ const dir = path.join(root, p.name)
58
+ let files
59
+ try {
60
+ files = fs.readdirSync(dir)
61
+ } catch {
62
+ continue
63
+ }
64
+ for (const f of files) {
65
+ if (!f.endsWith('.jsonl')) continue
66
+ const file = path.join(dir, f)
67
+ let stat
68
+ try {
69
+ stat = fs.statSync(file)
70
+ } catch {
71
+ continue
72
+ }
73
+ if (stat.isFile() && stat.mtime >= since) out.push(file)
74
+ }
75
+ }
76
+ return out.sort()
77
+ }
78
+
79
+ /**
80
+ * What a user entry says, reduced to one of:
81
+ * { text } a prompt someone typed
82
+ * { command, text } a slash command, kept as an event (`/spec-next`)
83
+ * null noise — dropped
84
+ */
85
+ function readPrompt(content) {
86
+ if (typeof content !== 'string') return null // tool results, images
87
+ const s = content.trim()
88
+ if (!s) return null
89
+ const name = /<command-name>\s*([^<\s]+)\s*<\/command-name>/.exec(s)
90
+ if (name) {
91
+ const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(s)
92
+ const command = name[1].startsWith('/') ? name[1] : `/${name[1]}`
93
+ if (HOUSEKEEPING.has(command.slice(1))) return null
94
+ return { command, text: cap(args ? args[1].trim() : '') }
95
+ }
96
+ // Caveats, command output, reminders, task notifications, a bare paste:
97
+ // all arrive as a tagged block, and none of them is something typed.
98
+ if (s.startsWith('<')) return null
99
+ // "[Request interrupted by user]" and its kind.
100
+ if (s.startsWith('[') && s.endsWith(']')) return null
101
+ return { text: cap(s) }
102
+ }
103
+
104
+ function cap(s) {
105
+ const one = s.replace(/\s+/g, ' ').trim()
106
+ return one.length > PROMPT_CHARS ? `${one.slice(0, PROMPT_CHARS - 1)}…` : one
107
+ }
108
+
109
+ /**
110
+ * One transcript, read inside the window. Prompts are attributed to where the
111
+ * session stood when they were typed — a session that `cd`s into a worktree
112
+ * half-way through contributes to two places, which is the point.
113
+ *
114
+ * @returns {Promise<{ id, stamped: number, places: Array<{ cwd, branch,
115
+ * start, end, prompts: Array<{ at, text, command? }> }> }>}
116
+ */
117
+ async function readSession(file, { since, until }) {
118
+ const id = path.basename(file, '.jsonl')
119
+ const places = new Map()
120
+ let cwd = null
121
+ let branch = null
122
+ // Entries carrying a timestamp we could parse, inside the window or not —
123
+ // the positive signal that this is still a format we can read.
124
+ let stamped = 0
125
+
126
+ const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity })
127
+ for await (const line of rl) {
128
+ if (!line) continue
129
+ let e
130
+ try {
131
+ e = JSON.parse(line)
132
+ } catch {
133
+ continue // a half-written last line, or not ours to read
134
+ }
135
+ // Where the session stands is tracked from every entry, so a `cd` made by
136
+ // a tool call moves the prompts that follow it.
137
+ if (typeof e.cwd === 'string') cwd = e.cwd
138
+ if (typeof e.gitBranch === 'string' && e.gitBranch) branch = e.gitBranch
139
+ const at = Date.parse(e.timestamp)
140
+ if (Number.isNaN(at)) continue
141
+ stamped++
142
+ if (at < since.getTime() || at > until.getTime()) continue
143
+ // A compaction summary arrives as a user entry, written by Claude.
144
+ if (e.type !== 'user' || e.isMeta || e.isSidechain || e.isCompactSummary) continue
145
+ const p = readPrompt(e.message && e.message.content)
146
+ if (!p || !cwd) continue
147
+ const key = `${cwd}\0${branch || ''}`
148
+ if (!places.has(key)) places.set(key, { cwd, branch, start: e.timestamp, end: e.timestamp, prompts: [] })
149
+ const place = places.get(key)
150
+ place.end = e.timestamp
151
+ place.prompts.push({ at: e.timestamp, ...p })
152
+ }
153
+ return { id, stamped, launch: launchDir(path.basename(path.dirname(file))), places: [...places.values()] }
154
+ }
155
+
156
+ /**
157
+ * The directory a session was launched from, read back off its transcript
158
+ * folder's name — Claude Code writes `/Users/me/code/app` as
159
+ * `-Users-me-code-app`, flattening `/` and `.` alike to `-`.
160
+ *
161
+ * That flattening is lossy (`my-app` and `my/app` encode the same), so this
162
+ * decodes only by asking the disk: each `-` is tried as a separator and as a
163
+ * literal, keeping the spellings that exist. More than one survivor, or none,
164
+ * is cannot-tell and returns null — a guessed directory would fold a session
165
+ * into the wrong repo with nothing to show for it.
166
+ */
167
+ function launchDir(name, existsOnDisk = fs.existsSync) {
168
+ if (!name.startsWith('-')) return null
169
+ const parts = name.slice(1).split('-')
170
+ // Each `-` has three readings, so the search is exponential in their count;
171
+ // past this many it is cannot-tell rather than a stall.
172
+ if (parts.length > 16) return null
173
+ const seen = new Map()
174
+ const exists = (p) => {
175
+ if (!seen.has(p)) seen.set(p, existsOnDisk(p))
176
+ return seen.get(p)
177
+ }
178
+ const found = []
179
+ const walk = (i, at, seg) => {
180
+ if (found.length > 1) return
181
+ if (i === parts.length) {
182
+ const full = path.join(at, seg)
183
+ if (exists(full)) found.push(full)
184
+ return
185
+ }
186
+ const next = parts[i]
187
+ // Close the segment here, if what it names exists so far.
188
+ if (seg && exists(path.join(at, seg))) walk(i + 1, path.join(at, seg), next)
189
+ // Or keep it open, through a literal `-` or a `.` (a dotfile, `app.web`).
190
+ if (seg !== '') {
191
+ walk(i + 1, at, `${seg}-${next}`)
192
+ walk(i + 1, at, `${seg}.${next}`)
193
+ } else {
194
+ walk(i + 1, at, `.${next}`)
195
+ }
196
+ }
197
+ walk(1, path.sep, parts[0])
198
+ return found.length === 1 ? found[0] : null
199
+ }
200
+
201
+ /** First and last few prompts, with the middle counted rather than shown. */
202
+ function trimPrompts(prompts) {
203
+ if (prompts.length <= KEEP_HEAD + KEEP_TAIL) return { prompts, omitted: 0 }
204
+ return {
205
+ prompts: [...prompts.slice(0, KEEP_HEAD), ...prompts.slice(-KEEP_TAIL)],
206
+ omitted: prompts.length - KEEP_HEAD - KEEP_TAIL,
207
+ }
208
+ }
209
+
210
+ // Enough of a transcript to see where its session ran. A session's first
211
+ // entries carry its cwd; reading the whole file to learn that is how listing
212
+ // every project would cost a minute.
213
+ const HEAD_BYTES = 64 * 1024
214
+
215
+ /**
216
+ * Every directory any session ran in — read from the head of each transcript,
217
+ * plus the folder each session was launched from. All time, not a window: this
218
+ * answers "which projects do you work in", for `skitterspec project
219
+ * --categories`. Resolving them to repos is the caller's.
220
+ */
221
+ function knownDirs(root) {
222
+ const dirs = new Set()
223
+ for (const file of listTranscripts(root, new Date(0))) {
224
+ const launch = launchDir(path.basename(path.dirname(file)))
225
+ if (launch) dirs.add(launch)
226
+ let head = ''
227
+ try {
228
+ const fd = fs.openSync(file, 'r')
229
+ const buf = Buffer.alloc(HEAD_BYTES)
230
+ const n = fs.readSync(fd, buf, 0, HEAD_BYTES, 0)
231
+ fs.closeSync(fd)
232
+ head = buf.subarray(0, n).toString('utf8')
233
+ } catch {
234
+ continue
235
+ }
236
+ for (const m of head.matchAll(/"cwd":"((?:[^"\\]|\\.)*)"/g)) {
237
+ try {
238
+ dirs.add(JSON.parse(`"${m[1]}"`))
239
+ } catch {
240
+ // a cwd cut off at the head's edge — the next line will carry it
241
+ }
242
+ }
243
+ }
244
+ return [...dirs]
245
+ }
246
+
247
+ module.exports = {
248
+ defaultRoot,
249
+ knownDirs,
250
+ launchDir,
251
+ listTranscripts,
252
+ readPrompt,
253
+ readSession,
254
+ trimPrompts,
255
+ PROMPT_CHARS,
256
+ KEEP_HEAD,
257
+ KEEP_TAIL,
258
+ }
@@ -0,0 +1,156 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The window a ta-da list covers — local time, because "today" is the
5
+ * reader's day and not UTC's. `--since <when>` runs from that day to now;
6
+ * `--on <when>` is that one day. Both read the same `<when>`:
7
+ *
8
+ * named today · yesterday · friday · last friday · last week
9
+ * relative 3 days ago · 3d · 2 weeks ago · 2w
10
+ * a date 2026-11-06 · 6 Nov · Nov 6 · 6 November 2026
11
+ *
12
+ * Pure: `now` is injected, so every shape is pinned without a clock.
13
+ */
14
+
15
+ const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']
16
+ const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december']
17
+
18
+ const GRAMMAR = 'today, yesterday, a weekday (last friday), N days/weeks ago (3d, 2w), or a date (2026-11-06, 6 Nov)'
19
+
20
+ function daysBefore(d, n) {
21
+ return new Date(d.getFullYear(), d.getMonth(), d.getDate() - n)
22
+ }
23
+
24
+ // A name or its first three letters; `sept` is accepted for September.
25
+ function lookup(names, word) {
26
+ const w = word.toLowerCase()
27
+ const i = names.findIndex((n) => n === w || n.slice(0, 3) === w)
28
+ if (i !== -1) return i
29
+ return w === 'sept' && names === MONTHS ? 8 : -1
30
+ }
31
+
32
+ function exactDate(year, month, day, value) {
33
+ const d = new Date(year, month, day)
34
+ // `new Date` rolls 31 Feb over into March rather than refusing it.
35
+ if (d.getMonth() !== month || d.getDate() !== day) throw new Error(`no such date: ${value}`)
36
+ return d
37
+ }
38
+
39
+ /**
40
+ * @param {string|undefined} value
41
+ * @param {Date} now
42
+ * @returns {Date} the local midnight the day begins at
43
+ * @throws on a value it cannot read — a window guessed from a typo would
44
+ * report the wrong day with total confidence
45
+ */
46
+ function parseWhen(value, now = new Date()) {
47
+ const raw = (value || 'today').trim()
48
+ const v = raw.toLowerCase().replace(/\s+/g, ' ')
49
+ const today = daysBefore(now, 0)
50
+ let d = null
51
+
52
+ if (v === 'today') d = today
53
+ else if (v === 'yesterday') d = daysBefore(now, 1)
54
+ else if (v === 'last week' || v === 'a week ago') d = daysBefore(now, 7)
55
+
56
+ // A weekday is the most recent PAST one, so it is never more than a week
57
+ // back: `friday` on a Monday is three days back, and `monday` on a Monday is
58
+ // seven — on the day itself, "since monday" meaning today would be `today`
59
+ // spelled oddly. `last friday` says the same thing in more words.
60
+ if (!d) {
61
+ const m = /^(?:last )?([a-z]+)$/.exec(v)
62
+ const day = m ? lookup(WEEKDAYS, m[1]) : -1
63
+ if (day !== -1) d = daysBefore(now, (now.getDay() - day + 7) % 7 || 7)
64
+ }
65
+
66
+ if (!d) {
67
+ const m = /^(\d+|an?) ?(d|days?|w|weeks?)(?: ago)?$/.exec(v) || /^-(\d+)(d|w)$/.exec(v)
68
+ if (m) {
69
+ const n = /^\d+$/.test(m[1]) ? Number(m[1]) : 1
70
+ d = daysBefore(now, m[2].startsWith('w') ? n * 7 : n)
71
+ }
72
+ }
73
+
74
+ if (!d) {
75
+ const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(v)
76
+ if (iso) d = exactDate(Number(iso[1]), Number(iso[2]) - 1, Number(iso[3]), raw)
77
+ }
78
+
79
+ if (!d) {
80
+ // `6 Nov`, `Nov 6`, either with a year. Without one it is the most recent
81
+ // such date — `20 Dec` read in January means last December.
82
+ const dm = /^(\d{1,2})(?:st|nd|rd|th)? ([a-z]+),? ?(\d{4})?$/.exec(v)
83
+ const md = /^([a-z]+) (\d{1,2})(?:st|nd|rd|th)?,? ?(\d{4})?$/.exec(v)
84
+ const parts = dm ? { day: dm[1], month: dm[2], year: dm[3] } : md ? { day: md[2], month: md[1], year: md[3] } : null
85
+ const month = parts ? lookup(MONTHS, parts.month) : -1
86
+ if (month !== -1) {
87
+ if (parts.year) d = exactDate(Number(parts.year), month, Number(parts.day), raw)
88
+ else {
89
+ d = exactDate(now.getFullYear(), month, Number(parts.day), raw)
90
+ if (d > today) d = exactDate(now.getFullYear() - 1, month, Number(parts.day), raw)
91
+ }
92
+ }
93
+ }
94
+
95
+ if (!d && /^\d{1,2}[/.]\d{1,2}(?:[/.]\d{2,4})?$/.test(v)) {
96
+ // 11/12 is the 11th of December in London and the 12th of November in New
97
+ // York. Picking one is the confident wrong answer this refuses to give.
98
+ throw new Error(`${raw} reads two ways (day/month or month/day) — write 2026-11-12 or 12 Nov`)
99
+ }
100
+ if (!d) throw new Error(`expected ${GRAMMAR} — got: ${raw}`)
101
+ if (d > today) throw new Error(`${raw} is in the future`)
102
+ return d
103
+ }
104
+
105
+ /**
106
+ * @param {{ since?: string, on?: string }} when
107
+ * @returns {{ since: Date, until: Date }}
108
+ */
109
+ function windowFor({ since, on } = {}, now = new Date()) {
110
+ if (since && on) throw new Error('--since and --on together name two windows — pick one')
111
+ if (on) {
112
+ const start = parseWhen(on, now)
113
+ const end = daysBefore(start, -1)
114
+ return { since: start, until: end < now ? end : now }
115
+ }
116
+ return { since: parseWhen(since, now), until: now }
117
+ }
118
+
119
+ const localDay = (d) =>
120
+ `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
121
+
122
+ /**
123
+ * The window as the reader's own dates — one day, or `first → last`. The
124
+ * digest's timestamps are UTC instants; a label is not, or `--on 10 Nov` read
125
+ * east of Greenwich would be named the 9th.
126
+ */
127
+ function windowLabel({ since, until }) {
128
+ const last = new Date(until.getTime() - 1) // an `--on` window ends at the next midnight, exclusive
129
+ const a = localDay(since)
130
+ const b = localDay(last < since ? since : last)
131
+ return a === b ? a : `${a} → ${b}`
132
+ }
133
+
134
+ const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
135
+ const MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
136
+
137
+ /**
138
+ * The window as a person writes dates: `Thursday 12 November 2026` for one
139
+ * day, `Fri 6 – Thu 12 Nov 2026` for a span — the month and year said once
140
+ * when the two ends share them, and both times when they do not.
141
+ */
142
+ function humanLabel({ since, until }) {
143
+ const last = new Date(until.getTime() - 1)
144
+ const end = last < since ? since : last
145
+ if (localDay(since) === localDay(end)) {
146
+ return `${DAY_NAMES[since.getDay()]} ${since.getDate()} ${MONTH_NAMES[since.getMonth()]} ${since.getFullYear()}`
147
+ }
148
+ const short = (d) => `${DAY_NAMES[d.getDay()].slice(0, 3)} ${d.getDate()}`
149
+ const month = (d) => MONTH_NAMES[d.getMonth()].slice(0, 3)
150
+ const sameYear = since.getFullYear() === end.getFullYear()
151
+ const sameMonth = sameYear && since.getMonth() === end.getMonth()
152
+ const from = sameMonth ? short(since) : `${short(since)} ${month(since)}${sameYear ? '' : ` ${since.getFullYear()}`}`
153
+ return `${from} – ${short(end)} ${month(end)} ${end.getFullYear()}`
154
+ }
155
+
156
+ module.exports = { parseWhen, windowFor, windowLabel, humanLabel, localDay, GRAMMAR }
@@ -37,6 +37,10 @@
37
37
  * - `remoteEditedLine(identifier)` the someone-else-edited warning
38
38
  * - `twinAdvice(twin, title, specName)` the refusal message for a twin
39
39
  * - `afterIssue(issue)` optional; → a report line or null
40
+ * - `retireSubIssue(id)` optional; close a leftover phase
41
+ * sub-issue as not planned and
42
+ * unlink it. Absent means this tracker
43
+ * cannot, and the push names the ids.
40
44
  * - `setParent(issue, parentIdentifier)` optional; make the spec issue a
41
45
  * child of its epic's → `{ changed }`.
42
46
  * Absent means this tracker cannot
@@ -226,6 +230,26 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
226
230
  lines.push(` sub-issue updated: ${sub.id}`)
227
231
  }
228
232
 
233
+ // 5b. Retire an epic's leftover phase sub-issues (spec feat-epic-migration,
234
+ // Decision 2). Never fatal: a tracker without the seam names the ids once and
235
+ // they are forgotten — the line is the record; a retire that FAILS keeps its
236
+ // id in the snapshot, so the next push tries again.
237
+ const keepSubIssues = []
238
+ const retire = (plan.subIssues && plan.subIssues.retire) || []
239
+ if (retire.length && typeof ops.retireSubIssue !== 'function') {
240
+ lines.push(` this tracker cannot retire sub-issues here — close by hand: ${retire.join(', ')}`)
241
+ } else {
242
+ for (const id of retire) {
243
+ try {
244
+ await ops.retireSubIssue(id)
245
+ lines.push(` sub-issue retired: ${id} (no phase claims it on an epic)`)
246
+ } catch (error) {
247
+ keepSubIssues.push(id)
248
+ lines.push(` ?? retire ${id}: ${String((error && error.message) || error).split('\n')[0]}`)
249
+ }
250
+ }
251
+ }
252
+
229
253
  // 6. Read back what the tracker stored and run the SAME check verify runs.
230
254
  const stored = { issue: undefined, subIssues: {} }
231
255
  if (result.issue) {
@@ -241,7 +265,7 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
241
265
  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
242
266
 
243
267
  // 7. Record the snapshot from the now-stamped files, so the next push is empty.
244
- const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent })
268
+ const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
245
269
  // A repo path, `/`-separated on every platform — the form every other
246
270
  // spec path in this output takes.
247
271
  lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
@@ -252,7 +252,7 @@ function remapped(recorded, current) {
252
252
  * `plan.issue` (when present) is the spec issue's description + state; the push
253
253
  * skill applies its provider's project/grouping choice on top of it.
254
254
  */
255
- function planChanges(projection, snapshot, { linked = false } = {}) {
255
+ function planChanges(projection, snapshot, { linked = false, epic = false } = {}) {
256
256
  const p = projection || {}
257
257
  const snap = snapshot || {}
258
258
  const snapS = snap.subIssues || {}
@@ -297,6 +297,13 @@ function planChanges(projection, snapshot, { linked = false } = {}) {
297
297
  }
298
298
  }
299
299
 
300
+ // AN EPIC'S UNCLAIMED IDS ARE LEFTOVERS, NOT LOST STAMPS. An epic has no
301
+ // phases by construction (spec feat-epics, Decision 1), so every sub-issue the
302
+ // snapshot remembers belongs to the plan spec it was converted from — a
303
+ // positive signal. On any other kind an unclaimed id stays the ambiguity it
304
+ // is above, and nothing is retired (spec feat-epic-migration, Decision 2).
305
+ if (epic && unclaimed.length) subIssues.retire = unclaimed.slice()
306
+
300
307
  const plan = { subIssues }
301
308
  if (unstamped.length) plan.unstamped = unstamped
302
309
  const issue = issueChanges(p, snap, { linked })
@@ -394,7 +401,8 @@ function issueChanges(projection, snapshot, { linked = false } = {}) {
394
401
 
395
402
  // True when a plan would push nothing.
396
403
  function isEmptyPlan(plan) {
397
- return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length
404
+ const retire = plan.subIssues.retire || []
405
+ return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length && !retire.length
398
406
  }
399
407
 
400
408
  module.exports = {
@@ -1,5 +1,7 @@
1
1
  'use strict'
2
2
 
3
+ const path = require('node:path')
4
+
3
5
  /**
4
6
  * `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
5
7
  * generated mirror. We never read remote content: `push` builds the local
@@ -102,7 +104,8 @@ function isLinked(snapshotDir, config) {
102
104
  function push({ dir, snapshotDir, identifier, config }) {
103
105
  const projection = projectionOf(snapshotDir, config)
104
106
  const snapshot = readBase(dir, identifier, config)
105
- const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config) })
107
+ const epic = path.basename(String(snapshotDir || '')).startsWith('epic-')
108
+ const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config), epic })
106
109
  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
107
110
  // plan above is all-creates and would abandon a live mirror. Carry the finding
108
111
  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
@@ -134,10 +137,18 @@ function push({ dir, snapshotDir, identifier, config }) {
134
137
  // that was NOT sent would claim the tracker holds it, and silence the very remap
135
138
  // this record exists to catch. Without `sent` (a hand-applied MCP push) nothing
136
139
  // new is recorded and what was there is kept.
137
- function recordPush({ dir, snapshotDir, identifier, config, sent = null }) {
140
+ // `keepSubIssues` names ids the projection no longer claims but the tracker may
141
+ // still hold — a retire that failed — so the next push plans them again rather
142
+ // than forgetting them.
143
+ function recordPush({ dir, snapshotDir, identifier, config, sent = null, keepSubIssues = [] }) {
138
144
  const projection = projectionOf(snapshotDir, config)
139
145
  const snapshot = snapshotOf(projection, config)
140
- const names = stateNamesRecord(projection, readBase(dir, identifier, config), sent)
146
+ const before = readBase(dir, identifier, config)
147
+ for (const id of keepSubIssues) {
148
+ const hash = before && before.subIssues && before.subIssues[String(id)]
149
+ if (hash !== undefined) snapshot.subIssues[String(id)] = hash
150
+ }
151
+ const names = stateNamesRecord(projection, before, sent)
141
152
  if (names) snapshot.stateNames = names
142
153
  return writeBase(dir, identifier, config, snapshot)
143
154
  }
File without changes