@skitterbyte/skitterspec-linear 19.5.0 → 19.6.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.
@@ -0,0 +1,541 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `skitterspec epic status <epic>` — what an epic's members say about its order.
5
+ *
6
+ * An epic declares neither its members nor their order (spec feat-epics,
7
+ * Decision 2): each member carries `> **Epic:**` and `> **Waits on:**`, and
8
+ * this turns those headers into what can start now, what is blocked and on
9
+ * what, and the waves the members fall into.
10
+ *
11
+ * WAITS ARE MET ONLY ON A POSITIVE SIGNAL, read off the BASE BRANCH
12
+ * (`.claude/rules/negative-checks.md` rule 1): the named spec sitting in
13
+ * `complete/` there, or its phase file reading done there. Everything else is
14
+ * one of two different answers, and they are never merged:
15
+ *
16
+ * - unmet — the spec is on the base branch and has not got there yet
17
+ * - cannot tell — the spec is not on the base branch at all, the phase file
18
+ * is not there, or the entry did not parse
19
+ *
20
+ * WHAT WOULD FOOL THIS: a spec on its own unlanded branch is invisible on the
21
+ * base branch, so a wait on it can only ever read cannot-tell — never met, and
22
+ * never blocked-forever. Buckets are branch-local truth; the base branch is the
23
+ * one place every session agrees on, which is why waits are read there and
24
+ * nowhere else.
25
+ *
26
+ * Pure but for the injected reads, so it is testable without a repository.
27
+ */
28
+
29
+ const { phaseIsDone } = require('./resolve.js')
30
+
31
+ const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
32
+
33
+ // A header value off an overview's blockquote block, or null when absent.
34
+ function header(text, name) {
35
+ const m = new RegExp(`^>\\s*\\*\\*${name}:\\*\\*[ \\t]*(.*)$`, 'm').exec(text || '')
36
+ if (!m) return null
37
+ const value = m[1].trim()
38
+ return value && value !== '—' && value !== '-' ? value : null
39
+ }
40
+
41
+ const unquote = (value) => (value == null ? value : value.replace(/^`(.*)`$/, '$1').trim())
42
+
43
+ // `<spec>[ phase N], …` → `[{ spec, phase, raw }]`. The twin of sync-core's
44
+ // `parseWaitsOn` — the base depends on no provider package, so it keeps its
45
+ // own copy, and `env-epic-status.test.js` holds the two to one answer.
46
+ //
47
+ // A MALFORMED ENTRY IS KEPT as `{ spec: null }`, never dropped: dropped, a wait
48
+ // nobody can read would look like no wait, and the member would read as ready.
49
+ function parseWaitsOn(value) {
50
+ if (!value) return []
51
+ const trimmed = value.trim()
52
+ if (/^(none|—|-)$/i.test(trimmed)) return []
53
+ return trimmed
54
+ .split(',')
55
+ .map((part) => part.trim())
56
+ .filter(Boolean)
57
+ .map((part) => {
58
+ const m = /^`?([a-z0-9][a-z0-9._-]*)`?(?:\s+phase\s+(\d+))?$/i.exec(part)
59
+ if (!m) return { spec: null, phase: null, raw: part }
60
+ return { spec: m[1], phase: m[2] ? Number(m[2]) : null, raw: part }
61
+ })
62
+ }
63
+
64
+ function parseLanes(value) {
65
+ const m = /^(\d+)$/.exec((value || '').trim())
66
+ const n = m ? Number(m[1]) : 0
67
+ return n > 0 ? n : null
68
+ }
69
+
70
+ /** The headers an epic or a member carries. */
71
+ function epicHeaders(text) {
72
+ return {
73
+ epic: unquote(header(text, 'Epic')) || null,
74
+ waitsOn: parseWaitsOn(header(text, 'Waits on')),
75
+ lanes: parseLanes(header(text, 'Lanes')),
76
+ area: parseArea(header(text, 'Area')),
77
+ }
78
+ }
79
+
80
+ // Split on commas outside `{…}` and `(…)` — `a/{b,c}.ts, d (x, y)` is two parts.
81
+ function splitTopLevel(value) {
82
+ const parts = []
83
+ let depth = 0
84
+ let cur = ''
85
+ for (const ch of value) {
86
+ if (ch === '{' || ch === '(') depth++
87
+ else if ((ch === '}' || ch === ')') && depth > 0) depth--
88
+ if (ch === ',' && depth === 0) {
89
+ parts.push(cur)
90
+ cur = ''
91
+ } else cur += ch
92
+ }
93
+ parts.push(cur)
94
+ return parts.map((p) => p.trim()).filter(Boolean)
95
+ }
96
+
97
+ // `a/{b,c}/{d,e}.ts` → every combination. One level of nesting per group,
98
+ // which is how the headers write it.
99
+ function expandBraces(pattern) {
100
+ const m = /\{([^{}]*)\}/.exec(pattern)
101
+ if (!m) return [pattern]
102
+ const head = pattern.slice(0, m.index)
103
+ const tail = pattern.slice(m.index + m[0].length)
104
+ return m[1].split(',').flatMap((alt) => expandBraces(`${head}${alt.trim()}${tail}`))
105
+ }
106
+
107
+ /**
108
+ * `> **Area:**` → the path patterns it names, brace-expanded. A trailing
109
+ * annotation — `(new)`, `(deep link)`, `` (`bareLive`) `` — is dropped, and so
110
+ * is any entry that does not read as a path (`skills (spec, spec-start)`):
111
+ * prose names no file, so it can clash with nothing. That is a cannot-tell,
112
+ * and a cannot-tell claims no clash — `Area:` is declared, not measured.
113
+ */
114
+ function parseArea(value) {
115
+ if (!value) return []
116
+ const paths = splitTopLevel(value)
117
+ .map((part) => part.replace(/\s*\([^()]*\)\s*$/, '').replace(/`/g, '').trim())
118
+ .filter((part) => /^[\w.@+\-/*{},[\]]+$/.test(part) && /[/.]/.test(part))
119
+ .flatMap(expandBraces)
120
+ .map((p) => p.replace(/^\.\//, ''))
121
+ return [...new Set(paths)]
122
+ }
123
+
124
+ // One path segment against another, either of which may hold a `*`.
125
+ function segmentsMeet(a, b) {
126
+ if (a === b || a === '**' || b === '**') return true
127
+ const re = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`)
128
+ if (a.includes('*') && re(a).test(b.replace(/\*/g, ''))) return true
129
+ if (b.includes('*') && re(b).test(a.replace(/\*/g, ''))) return true
130
+ return false
131
+ }
132
+
133
+ /**
134
+ * Could one file be named by both patterns? A pattern that ends first is read
135
+ * as a directory holding the other — `packages/api/` and `packages/api` both
136
+ * name everything under it, since a header rarely says which it means. A bare
137
+ * filename (no `/`) is matched against the other's last segment.
138
+ *
139
+ * WHAT WOULD FOOL THIS: a directory and a file of the same name read as a
140
+ * clash, and a glob against a glob is matched loosely. Both err towards
141
+ * naming a clash, which only ever warns.
142
+ */
143
+ function patternsMeet(a, b) {
144
+ const split = (p) => p.replace(/\/+$/, '').split('/').filter(Boolean)
145
+ const sa = split(a)
146
+ const sb = split(b)
147
+ if (sa.length === 1 || sb.length === 1) {
148
+ const [bare, other] = sa.length === 1 ? [sa, sb] : [sb, sa]
149
+ return segmentsMeet(bare[0], other[other.length - 1])
150
+ }
151
+ for (let i = 0; i < Math.min(sa.length, sb.length); i++) {
152
+ if (sa[i] === '**' || sb[i] === '**') return true
153
+ if (!segmentsMeet(sa[i], sb[i])) return false
154
+ }
155
+ return true
156
+ }
157
+
158
+ /**
159
+ * Every pair of open members whose `Area:` patterns meet, with the patterns
160
+ * they share — the "never together" sets. A member with no readable `Area:`
161
+ * claims nothing (stays silent), and finished members are left out: a pair
162
+ * matters only while both may still be built.
163
+ */
164
+ function clashes(members) {
165
+ const open = members.filter((m) => m.area.length && !['complete', 'cancelled'].includes(m.bucket))
166
+ const out = []
167
+ for (let i = 0; i < open.length; i++) {
168
+ for (let j = i + 1; j < open.length; j++) {
169
+ const shared = new Set()
170
+ for (const a of open[i].area) {
171
+ for (const b of open[j].area) if (patternsMeet(a, b)) shared.add(a.length >= b.length ? a : b)
172
+ }
173
+ if (shared.size) out.push({ specs: [open[i].spec, open[j].spec], paths: [...shared].sort() })
174
+ }
175
+ }
176
+ return out
177
+ }
178
+
179
+ /**
180
+ * Index the base branch's `specs/` from a `git ls-tree -r --name-only` listing:
181
+ * folder → `{ bucket, phases: Map<n, path> }`. A folder in two buckets (a
182
+ * `git mv` landed half-way) is filed where it is going, the later bucket.
183
+ */
184
+ function indexSpecTree(listing) {
185
+ const index = new Map()
186
+ for (const line of String(listing || '').split('\n')) {
187
+ const m = /^specs\/([^/]+)\/([^/]+)\/([^/]+)$/.exec(line.trim())
188
+ if (!m || !BUCKETS.includes(m[1])) continue
189
+ const [, bucket, folder, file] = m
190
+ let entry = index.get(folder)
191
+ if (!entry || BUCKETS.indexOf(bucket) > BUCKETS.indexOf(entry.bucket)) {
192
+ entry = { bucket, phases: new Map() }
193
+ index.set(folder, entry)
194
+ }
195
+ if (entry.bucket !== bucket) continue
196
+ const phase = /^(\d\d)-.+\.md$/.exec(file)
197
+ if (phase && file !== '00-overview.md') entry.phases.set(Number(phase[1]), `specs/${bucket}/${folder}/${file}`)
198
+ }
199
+ return index
200
+ }
201
+
202
+ /**
203
+ * Resolve one wait against the base branch.
204
+ * @returns {{ state: 'met' | 'unmet' | 'cannot-tell', why: string }}
205
+ */
206
+ function resolveWait(wait, index, readFile) {
207
+ if (!wait.spec) return { state: 'cannot-tell', why: `"${wait.raw}" does not read as <spec>[ phase N]` }
208
+ const target = index.get(wait.spec)
209
+ if (!target) return { state: 'cannot-tell', why: `${wait.spec} is not on the base branch` }
210
+ if (target.bucket === 'complete') return { state: 'met', why: `${wait.spec} is complete` }
211
+ if (target.bucket === 'cancelled') return { state: 'unmet', why: `${wait.spec} was cancelled` }
212
+ if (wait.phase === null) return { state: 'unmet', why: `${wait.spec} is ${target.bucket}` }
213
+ const file = target.phases.get(wait.phase)
214
+ if (!file) return { state: 'cannot-tell', why: `${wait.spec} has no phase ${wait.phase} on the base branch` }
215
+ const text = readFile(file)
216
+ if (text === null) return { state: 'cannot-tell', why: `${file} could not be read` }
217
+ return phaseIsDone(text)
218
+ ? { state: 'met', why: `${wait.spec} phase ${wait.phase} is done` }
219
+ : { state: 'unmet', why: `${wait.spec} phase ${wait.phase} is not done` }
220
+ }
221
+
222
+ /**
223
+ * Layer members into waves, off their START waits only. A whole-spec wait on
224
+ * another member puts this one in a LATER wave; a wait on one of its phases
225
+ * lets it share the wave — it starts once that phase lands, beside the rest of
226
+ * that spec. A phase file's own wait never moves a wave: it holds that phase,
227
+ * not the spec's start, and is reported as a sync point instead. Waits on specs
228
+ * outside the epic order nothing here.
229
+ *
230
+ * A cycle is found and named, never guessed through: its members and anything
231
+ * waiting on them are left out of the waves.
232
+ */
233
+ function layer(members) {
234
+ const byName = new Map(members.map((m) => [m.spec, m]))
235
+ const edges = new Map(
236
+ members.map((m) => [m.spec, m.waits.filter((w) => w.spec && byName.has(w.spec) && w.spec !== m.spec)]),
237
+ )
238
+
239
+ const cycles = []
240
+ const state = new Map()
241
+ const stack = []
242
+ const visit = (name) => {
243
+ state.set(name, 'open')
244
+ stack.push(name)
245
+ for (const w of edges.get(name)) {
246
+ if (state.get(w.spec) === 'open') {
247
+ const loop = stack.slice(stack.indexOf(w.spec))
248
+ cycles.push([...loop, w.spec])
249
+ } else if (!state.has(w.spec)) visit(w.spec)
250
+ }
251
+ stack.pop()
252
+ state.set(name, 'done')
253
+ }
254
+ for (const m of members) if (!state.has(m.spec)) visit(m.spec)
255
+ const inCycle = new Set(cycles.flat())
256
+
257
+ const wave = new Map()
258
+ const waveOf = (name, seen = new Set()) => {
259
+ if (wave.has(name)) return wave.get(name)
260
+ if (inCycle.has(name) || seen.has(name)) return null
261
+ seen.add(name)
262
+ let n = 1
263
+ for (const w of edges.get(name)) {
264
+ const dep = waveOf(w.spec, seen)
265
+ if (dep === null) {
266
+ wave.set(name, null)
267
+ return null
268
+ }
269
+ n = Math.max(n, w.phase === null ? dep + 1 : dep)
270
+ }
271
+ wave.set(name, n)
272
+ return n
273
+ }
274
+ for (const m of members) waveOf(m.spec)
275
+
276
+ const waves = []
277
+ for (const m of members) {
278
+ const n = wave.get(m.spec)
279
+ if (n == null) continue
280
+ while (waves.length < n) waves.push([])
281
+ waves[n - 1].push(m.spec)
282
+ }
283
+ return { waves, cycles, unlayered: members.filter((m) => wave.get(m.spec) == null).map((m) => m.spec) }
284
+ }
285
+
286
+ /**
287
+ * The whole answer.
288
+ *
289
+ * @param {object} a
290
+ * - `epic` the epic's folder name
291
+ * - `index` `indexSpecTree` of the base branch
292
+ * - `readFile` base-branch path → text, or null
293
+ * - `candidates` base-branch overview paths that may carry an `Epic:` header
294
+ * - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
295
+ * each provisioned spec's own copy, which is where an
296
+ * in-flight spec's bucket and phase progress are true
297
+ */
298
+ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
299
+ const own = new Map(worktrees.map((w) => [w.folder, w]))
300
+ const members = new Map()
301
+
302
+ for (const file of candidates) {
303
+ const m = /^specs\/([^/]+)\/([^/]+)\/00-overview\.md$/.exec(file)
304
+ if (!m || m[2] === epic) continue
305
+ const text = readFile(file)
306
+ if (text === null) continue
307
+ const h = epicHeaders(text)
308
+ if (h.epic !== epic) continue
309
+ const entry = index.get(m[2])
310
+ const phases = entry ? [...entry.phases].map(([n, p]) => ({ n, text: readFile(p) })) : []
311
+ members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
312
+ }
313
+ // A member authored on its own branch and not landed yet is invisible on the
314
+ // base branch; its worktree copy is what knows it belongs here.
315
+ for (const w of worktrees) {
316
+ const h = epicHeaders(w.overview)
317
+ // The worktree's copy is the newer word on a spec being built: it may have
318
+ // joined, changed its waits, or moved to another epic.
319
+ if (h.epic === epic) members.set(w.folder, { spec: w.folder, waits: h.waitsOn, area: h.area, phases: w.phases || [] })
320
+ else if (h.epic !== null) members.delete(w.folder)
321
+ }
322
+
323
+ const list = [...members.values()].sort((a, b) => a.spec.localeCompare(b.spec))
324
+ for (const m of list) {
325
+ const wt = own.get(m.spec)
326
+ const base = index.get(m.spec)
327
+ // In flight is the positive signal of a worktree whose own copy has not
328
+ // finished; otherwise the base branch's bucket.
329
+ m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : base ? base.bucket : wt ? wt.bucket : null
330
+ m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, index, readFile) }))
331
+ // A phase's own `Waits on:` holds that phase, not the spec's start: the
332
+ // sync point the field example turned on (#154 phase 2 on #159 phase 1).
333
+ // A phase already done has nothing left to wait for.
334
+ m.phaseWaits = m.phases
335
+ .filter((p) => p.text !== null && !phaseIsDone(p.text))
336
+ .flatMap((p) =>
337
+ epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, index, readFile) } })),
338
+ )
339
+ }
340
+
341
+ const epicEntry = index.get(epic)
342
+ const epicOverview = epicEntry ? readFile(`specs/${epicEntry.bucket}/${epic}/00-overview.md`) : null
343
+ const lanes = epicHeaders(epicOverview || (own.get(epic) || {}).overview || '').lanes
344
+
345
+ const of = (bucket) => list.filter((m) => m.bucket === bucket)
346
+ const waiting = of('backlog')
347
+ const ready = waiting.filter((m) => m.resolved.every((w) => w.state === 'met'))
348
+ const blocked = waiting.filter((m) => m.resolved.some((w) => w.state === 'unmet'))
349
+ const cannotTell = waiting.filter((m) => !ready.includes(m) && !blocked.includes(m))
350
+ const inFlight = of('in-progress')
351
+ const { waves, cycles, unlayered } = layer(list.filter((m) => m.bucket !== 'cancelled'))
352
+ // Every edge finer than "this spec waits for that one": a start held on
353
+ // another spec's phase, and a phase of this spec held on anything. `phase`
354
+ // is the member's own phase — null for its start.
355
+ const open = list.filter((m) => m.bucket !== 'cancelled' && m.bucket !== 'complete')
356
+ const syncPoints = [
357
+ ...open.flatMap((m) => m.resolved.filter((w) => w.phase !== null).map((wait) => ({ spec: m.spec, phase: null, wait }))),
358
+ ...open.flatMap((m) => m.phaseWaits.map(({ at, wait }) => ({ spec: m.spec, phase: at, wait }))),
359
+ ]
360
+
361
+ const brief = (m) => ({ spec: m.spec, waits: m.resolved })
362
+ return {
363
+ epic,
364
+ found: Boolean(epicEntry || own.has(epic)),
365
+ lanes,
366
+ freeLanes: lanes === null ? null : Math.max(0, lanes - inFlight.length),
367
+ members: list.map((m) => ({ spec: m.spec, bucket: m.bucket, waits: m.resolved })),
368
+ ready: ready.map(brief),
369
+ blocked: blocked.map((m) => ({ spec: m.spec, by: m.resolved.filter((w) => w.state === 'unmet') })),
370
+ cannotTell: cannotTell.map((m) => ({ spec: m.spec, by: m.resolved.filter((w) => w.state === 'cannot-tell') })),
371
+ inFlight: inFlight.map(brief),
372
+ complete: of('complete').map((m) => m.spec),
373
+ cancelled: of('cancelled').map((m) => m.spec),
374
+ waves,
375
+ syncPoints,
376
+ clashes: clashes(list),
377
+ cycles,
378
+ unlayered,
379
+ }
380
+ }
381
+
382
+ const names = (xs) => xs.map((x) => (typeof x === 'string' ? x : x.spec)).join(', ')
383
+ const reasons = (xs) => xs.map((x) => `${x.spec} (${x.by.map((w) => w.why).join('; ')})`).join(', ')
384
+
385
+ // `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
386
+ function syncLine({ spec, phase, wait }) {
387
+ const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
388
+ const mark = { met: 'met', unmet: 'not yet', 'cannot-tell': 'cannot tell' }[wait.state]
389
+ return `${who} after ${wait.raw} (${mark} — ${wait.why})`
390
+ }
391
+
392
+ /**
393
+ * The human answer, in the report-block shape: one sentence, then a table of
394
+ * only the rows that have something in them.
395
+ */
396
+ function formatEpicStatus(s) {
397
+ if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
398
+ const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
399
+ const head = `**${s.epic}** — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${s.found ? '' : ' · epic not on the base branch'}`
400
+ const rows = [
401
+ ['Ready now', names(s.ready)],
402
+ ['In flight', names(s.inFlight)],
403
+ ['Blocked', reasons(s.blocked)],
404
+ ['Cannot tell', reasons(s.cannotTell)],
405
+ ['Done', names(s.complete)],
406
+ ['Cancelled', names(s.cancelled)],
407
+ ['Waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
408
+ ['Sync points', s.syncPoints.map(syncLine).join(' · ')],
409
+ ['Never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
410
+ ['Cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
411
+ ].filter(([, v]) => v)
412
+ if (!s.members.length) rows.push(['Members', `none — no spec carries \`> **Epic:** ${s.epic}\``])
413
+ return `${head}\n\n| | |\n|---|---|\n${rows.map(([k, v]) => `| **${k}** | ${v} |`).join('\n')}\n`
414
+ }
415
+
416
+ /**
417
+ * What starting or building one member should hear about — the half of
418
+ * `epic check` that is about other members in flight. Each warning names the
419
+ * in-flight member and the paths the two share. Never a refusal: `Area:` is
420
+ * declared, not measured (Decision 4). A spec that is no member of anything
421
+ * hears nothing.
422
+ */
423
+ function memberCheck(status, spec, { phase = null, record = {} } = {}) {
424
+ const flying = new Set(status.inFlight.map((m) => m.spec))
425
+ const warnings = status.clashes
426
+ .filter((c) => c.specs.includes(spec))
427
+ .map((c) => ({ with: c.specs.find((x) => x !== spec), paths: c.paths }))
428
+ .filter((c) => flying.has(c.with))
429
+ .map((c) => ({ kind: 'clash', ...c, message: `${c.with} is in flight and edits ${c.paths.join(', ')} too` }))
430
+
431
+ // THE WAITS this build stands behind: the spec's start, always — a start
432
+ // bypassed at `/spec-start` is not asked again — and, with `phase`, that
433
+ // phase's own. Read where the work happens, which is the whole point
434
+ // (Decision 8): the field example's phase 2 was built because the place it
435
+ // was built never read the plan.
436
+ const member = status.members.find((m) => m.spec === spec)
437
+ const bypassed = new Set(record.bypassed || [])
438
+ const scoped = []
439
+ if (member && !bypassed.has('start')) scoped.push(...member.waits.map((w) => ({ scope: 'start', wait: w })))
440
+ if (phase !== null && !bypassed.has(`phase ${phase}`)) {
441
+ for (const p of status.syncPoints) {
442
+ if (p.spec === spec && p.phase === phase) scoped.push({ scope: `phase ${phase}`, wait: p.wait })
443
+ }
444
+ }
445
+ const unmet = scoped.filter((s) => s.wait.state === 'unmet')
446
+ for (const s of scoped.filter((x) => x.wait.state === 'cannot-tell')) {
447
+ warnings.push({ kind: 'cannot-tell', message: `cannot tell whether ${s.wait.raw} has landed — ${s.wait.why}` })
448
+ }
449
+
450
+ const result = { spec, epic: status.epic, phase, warnings, blocked: unmet.length > 0 }
451
+ if (!unmet.length) return result
452
+ const what = phase === null ? `${spec}'s start` : `${spec} phase ${phase}`
453
+ result.scopes = [...new Set(unmet.map((s) => s.scope))]
454
+ result.reason =
455
+ `${what} waits on ${unmet.map((s) => `${s.wait.raw} (${s.wait.why})`).join(', ')} — ` +
456
+ `land that first, or build anyway with: skitterspec epic bypass ${spec}${phase === null ? '' : ` --phase ${phase}`}`
457
+ // Offered ONCE per obligation (`.claude/rules/offered-unblocks.md`): spent by
458
+ // being raised, recorded by `--offered`, so a re-run is a plain refusal.
459
+ const key = phase === null ? 'start' : `phase ${phase}`
460
+ if (!(record.offered || []).includes(key)) {
461
+ result.offer = {
462
+ kind: 'bypass',
463
+ label: 'Build it anyway — the wait is recorded as passed over',
464
+ command: `skitterspec epic bypass ${spec}${phase === null ? '' : ` --phase ${phase}`}`,
465
+ }
466
+ }
467
+ return result
468
+ }
469
+
470
+ /**
471
+ * The dated Changelog line a bypass leaves on the member spec — where the next
472
+ * reader of that spec, and phase 7's re-verify, will find it.
473
+ */
474
+ function bypassLine(check, date) {
475
+ const what = check.phase === null ? 'Started' : `Built phase ${check.phase}`
476
+ return `- ${date} — ${what} past an unmet wait (epic check bypass, ${check.epic}): ${check.reason.split(' — land that first')[0]}.`
477
+ }
478
+
479
+ // Append `line` to the overview's `## Changelog`, which ends the file in every
480
+ // spec the skills write; a spec without one gains the section.
481
+ function appendChangelog(text, line) {
482
+ const body = text.replace(/\s*$/, '')
483
+ return /^## Changelog\s*$/m.test(body) ? `${body}\n${line}\n` : `${body}\n\n## Changelog\n\n${line}\n`
484
+ }
485
+
486
+ /**
487
+ * Waits a landing's rebase will MEET — the field case behind Decision 9: a
488
+ * phase built before the phase it waited on had landed, then rebased over it,
489
+ * lands in the right order without ever having run with the dependency
490
+ * underneath. A rebase satisfies the order, not the intent.
491
+ *
492
+ * Asked of two readings of the base branch — `before` at the spec's fork
493
+ * point, `after` at the base it is about to land on — and of the spec's own
494
+ * DONE phases (a phase not yet built will be built on top anyway). A wait is
495
+ * listed only on a positive signal from BOTH reads: unmet before, met after.
496
+ * Cannot-tell on either side is reported as such and never claimed — the cost
497
+ * of a wrong "met by this rebase" is a re-run nobody needed, but the cost of
498
+ * inventing one is a re-run claim nobody can check.
499
+ *
500
+ * @param {object} a
501
+ * - `overview` the spec's own overview text (its start waits)
502
+ * - `phases` `[{ n, text }]`, the spec's own phase files
503
+ * - `before` `{ index, readFile }` at the fork point
504
+ * - `after` `{ index, readFile }` at the base being landed on
505
+ * @returns {{ met: [{ phase, wait }], cannotTell: [{ phase, wait }] }}
506
+ * `phase` is the spec's phase number, or null for its start's waits.
507
+ */
508
+ function waitsMetByRebase({ overview, phases = [], before, after }) {
509
+ const built = phases.filter((p) => p.text !== null && phaseIsDone(p.text))
510
+ const scoped = [
511
+ ...(built.length ? epicHeaders(overview || '').waitsOn.map((w) => ({ phase: null, w })) : []),
512
+ ...built.flatMap((p) => epicHeaders(p.text).waitsOn.map((w) => ({ phase: p.n, w }))),
513
+ ]
514
+ const met = []
515
+ const cannotTell = []
516
+ for (const { phase, w } of scoped) {
517
+ const was = resolveWait(w, before.index, before.readFile)
518
+ const now = resolveWait(w, after.index, after.readFile)
519
+ if (now.state !== 'met' || was.state === 'met') continue
520
+ const wait = { ...w, why: now.why }
521
+ if (was.state === 'unmet') met.push({ phase, wait })
522
+ else cannotTell.push({ phase, wait: { ...wait, why: `${was.why} at the fork point` } })
523
+ }
524
+ return { met, cannotTell }
525
+ }
526
+
527
+ module.exports = {
528
+ waitsMetByRebase,
529
+ epicStatus,
530
+ formatEpicStatus,
531
+ epicHeaders,
532
+ parseWaitsOn,
533
+ parseArea,
534
+ patternsMeet,
535
+ indexSpecTree,
536
+ resolveWait,
537
+ layer,
538
+ memberCheck,
539
+ bypassLine,
540
+ appendChangelog,
541
+ }
@@ -81,9 +81,17 @@ function formatInFlight(rows, { dir }) {
81
81
  const width = Math.max(...rows.map((r) => r.spec.length))
82
82
  const live = rows.filter(isInFlight).length
83
83
  const out = [live ? `${live} spec${live === 1 ? '' : 's'} in flight` : 'no specs in flight']
84
- for (const r of rows) {
85
- out.push(` ${r.spec.padEnd(width)} ${detailOf(r)}`)
86
- out.push(` ${path.relative(dir, r.worktree) || r.worktree}`)
84
+ const row = (r, indent) => {
85
+ out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
86
+ out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
87
+ }
88
+ // Members are listed under their epic, read off each spec's own copy; a spec
89
+ // in no epic — the common case — prints exactly as it always has.
90
+ for (const r of rows.filter((x) => !x.epic)) row(r, ' ')
91
+ const epics = [...new Set(rows.map((r) => r.epic).filter(Boolean))].sort()
92
+ for (const epic of epics) {
93
+ out.push(` ${epic}`)
94
+ for (const r of rows.filter((x) => x.epic === epic)) row(r, ' ')
87
95
  }
88
96
  // SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
89
97
  // this checkout, the line would explain a discrepancy that is not there.
@@ -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-`/`issue-`/`incident-` prefix into
7
+ * `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-` 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
@@ -77,8 +77,10 @@ function readPhases(specDir, { overviewFile = '00-overview.md' } = {}) {
77
77
  .map((e) => e.name)
78
78
  .sort()
79
79
  // No phase files is not "no phases" — it is a legacy layout whose phases live
80
- // inline in the overview, and this reader cannot see them.
81
- if (!files.length) return null
80
+ // inline in the overview, and this reader cannot see them. The one exception
81
+ // is an epic, whose prefix says positively that it has none: there is no
82
+ // phase for `/spec-next` to build, and that is an answer, not a cannot-tell.
83
+ if (!files.length) return isEpic(specDir) ? { total: 0, done: 0, hasNextPhase: false, live: null } : null
82
84
 
83
85
  let done = 0
84
86
  for (const name of files) {
@@ -296,15 +298,23 @@ function phaseIsDone(text) {
296
298
  return /^#\s.*✅\s*$/m.test(text)
297
299
  }
298
300
 
299
- // Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix.
300
- // Unknown prefix → type defaults to `feat` and the whole folder name is the
301
- // slug.
301
+ // Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-`
302
+ // prefix. Unknown prefix → type defaults to `feat` and the whole folder name is
303
+ // the slug.
302
304
  function splitPrefix(folder) {
303
- const m = /^(feat|bug|hotfix|chore|issue|incident)-(.+)$/.exec(folder)
305
+ const m = /^(feat|bug|hotfix|chore|issue|incident|epic)-(.+)$/.exec(folder)
304
306
  if (m) return { type: m[1], slug: m[2] }
305
307
  return { type: 'feat', slug: folder }
306
308
  }
307
309
 
310
+ // An epic is a spec of specs: a folder with an overview and no phase files of
311
+ // its own, its progress being its members'. Decided off the folder prefix — the
312
+ // positive signal every other kind uses — never off the absence of phase files,
313
+ // which is also what a legacy inline-phase spec looks like.
314
+ function isEpic(folder) {
315
+ return splitPrefix(path.basename(String(folder || ''))).type === 'epic'
316
+ }
317
+
308
318
  // Repo identity used for token expansion.
309
319
  function repoInfo(dir) {
310
320
  const repo = path.basename(dir)
@@ -831,6 +841,7 @@ module.exports = {
831
841
  assertPrimaryOnMain,
832
842
  branchFor,
833
843
  splitPrefix,
844
+ isEpic,
834
845
  repoInfo,
835
846
  expandTokens,
836
847
  findSpecFolder,
@@ -24,6 +24,7 @@ const fs = require('node:fs')
24
24
  const path = require('node:path')
25
25
 
26
26
  const { phaseProgress } = require('./phases.js')
27
+ const { isEpic } = require('./resolve.js')
27
28
 
28
29
  // Most live first: a spec that exists in two buckets mid-`git mv` is reported
29
30
  // where it is going, not where it was.
@@ -64,7 +65,7 @@ function tryRead(io, fn) {
64
65
  * @param {string} root the checkout to read — a spec's worktree, normally
65
66
  * @param {string} folder the spec's folder name (`feat-x`)
66
67
  * @param {object} [io] `{ readdir, readFile }`, each throwing on failure
67
- * @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer }
68
+ * @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer, epic }
68
69
  * | { found: false, reason }}
69
70
  */
70
71
  function readSpecState(root, folder, io = defaultIo) {
@@ -76,7 +77,10 @@ function readSpecState(root, folder, io = defaultIo) {
76
77
  if (overview === null) return { found: false, reason: `${bucket}/${folder} has no readable 00-overview.md` }
77
78
  const phaseFiles = files.filter((f) => /^(?!00-)\d{2}-.*\.md$/.test(f)).sort()
78
79
  const phases = phaseFiles.map((f) => ({ file: f, content: tryRead(io, () => io.readFile(path.join(dir, f))) }))
79
- const progress = phases.length ? phaseProgress(phases) : inlineProgress(overview)
80
+ // An epic has no phases by construction (its prefix says so), so zero is
81
+ // an answer for it — where any other folder without phase files is a
82
+ // legacy overview to read inline.
83
+ const progress = phases.length || isEpic(folder) ? phaseProgress(phases) : inlineProgress(overview)
80
84
  return state(bucket, false, overview, progress)
81
85
  }
82
86
  const bare = tryRead(io, () => io.readFile(path.join(root, 'specs', bucket, `${folder}.md`)))
@@ -95,6 +99,7 @@ function state(bucket, legacy, text, progress) {
95
99
  currentPhase: progress ? progress.current : null,
96
100
  status: header(text, 'Status'),
97
101
  developer: header(text, 'Developer'),
102
+ epic: (header(text, 'Epic') || '').replace(/^`(.*)`$/, '$1') || null,
98
103
  }
99
104
  }
100
105