@skitterbyte/skitterspec-linear 19.5.1 → 19.7.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,109 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The disk half of an epic's answer, shared by the CLI (`skitterspec epic
5
+ * status`) and the review server's epic page (spec feat-epic-next, Decision 5),
6
+ * so a page and a terminal opened side by side cannot read the same epic two
7
+ * ways.
8
+ *
9
+ * Waits are read off the BASE BRANCH by git, never off whatever the primary
10
+ * checkout has checked out; each member's progress and review state off its
11
+ * OWN worktree, where they are true (`env/epic.js`).
12
+ */
13
+
14
+ const fs = require('node:fs')
15
+ const path = require('node:path')
16
+
17
+ const { isEpic } = require('./resolve.js')
18
+ const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
19
+ const { epicRows, readNextInputs } = require('./nextaction.js')
20
+ const { reviewOutPath } = require('./review.js')
21
+
22
+ /**
23
+ * The base branch's spec tree: `{ index, readFile, candidates }`, or null when
24
+ * the branch cannot be read — cannot-tell, never an empty plan.
25
+ */
26
+ function epicTree(git, base) {
27
+ const listing = git(['ls-tree', '-r', '--name-only', base, '--', 'specs'])
28
+ if (listing === null) return null
29
+ // `git grep` exits 1 on no match, which the reader returns as null. The tree
30
+ // above was readable, so here null is "no spec names an epic".
31
+ const grep = git(['grep', '-l', '-E', '^>[[:space:]]*\\*\\*Epic:\\*\\*', base, '--', 'specs'])
32
+ const candidates = (grep || '')
33
+ .split('\n')
34
+ .filter(Boolean)
35
+ .map((l) => l.slice(base.length + 1))
36
+ return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
37
+ }
38
+
39
+ // A provisioned spec's own overview and bucket, read in its worktree — the
40
+ // copy where an in-flight spec's bucket and headers are true. null when the
41
+ // worktree holds no readable copy.
42
+ function worktreeOverview(root, folder) {
43
+ for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
44
+ const dir = path.join(root, 'specs', bucket, folder)
45
+ let overview
46
+ try {
47
+ overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
48
+ } catch {
49
+ continue
50
+ }
51
+ const phases = fs
52
+ .readdirSync(dir)
53
+ .filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
54
+ .map((f) => {
55
+ let text = null
56
+ try {
57
+ text = fs.readFileSync(path.join(dir, f), 'utf8')
58
+ } catch {
59
+ // unreadable: a phase with nothing to say
60
+ }
61
+ return { n: Number(f.slice(0, 2)), text }
62
+ })
63
+ return { folder, bucket, overview, phases, root }
64
+ }
65
+ return null
66
+ }
67
+
68
+ // Epics with a member, or themselves, in flight on this machine — what a bare
69
+ // `epic status` offers when it cannot tell which one was meant, and what the
70
+ // review server's index lists.
71
+ function epicsInFlight(worktrees) {
72
+ const open = worktrees.filter((w) => w.bucket !== 'complete' && w.bucket !== 'cancelled')
73
+ const names = open.map((w) => (isEpic(w.folder) ? w.folder : epicHeaders(w.overview).epic)).filter(Boolean)
74
+ return [...new Set(names)].sort()
75
+ }
76
+
77
+ /**
78
+ * The callbacks `epicRows` reads each member through: its own worktree, the
79
+ * review sidecars beside its page in the primary checkout, and a link to that
80
+ * page from `linkFor` — absolute for a terminal, relative for the served page.
81
+ */
82
+ function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
83
+ const own = new Map(worktrees.map((w) => [w.folder, w]))
84
+ return {
85
+ inputsFor: (spec) => {
86
+ const w = own.get(spec)
87
+ if (!w) return null
88
+ return readNextInputs({
89
+ folder: spec,
90
+ bucket: w.bucket,
91
+ worktree: w.root,
92
+ outPath: reviewOutPath(dir, spec),
93
+ required: config ? config.review.required : true,
94
+ git: git(w.root),
95
+ })
96
+ },
97
+ tabFor: (spec) => (own.has(spec) ? path.relative(path.dirname(dir), own.get(spec).root) : null),
98
+ linkFor,
99
+ }
100
+ }
101
+
102
+ /** The whole answer for one epic: `epicStatus` plus a row per member. */
103
+ function epicAnswer(epic, inputs, readers) {
104
+ const status = epicStatus({ epic, ...inputs })
105
+ const { rows, next } = epicRows(status, readers)
106
+ return { ...status, rows, next }
107
+ }
108
+
109
+ module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
@@ -18,6 +18,7 @@ const path = require('node:path')
18
18
 
19
19
  const { readSpecState } = require('./specstate.js')
20
20
  const { progressText } = require('./phases.js')
21
+ const { actionText } = require('./nextaction.js')
21
22
 
22
23
  /**
23
24
  * @param {object} a
@@ -81,9 +82,18 @@ function formatInFlight(rows, { dir }) {
81
82
  const width = Math.max(...rows.map((r) => r.spec.length))
82
83
  const live = rows.filter(isInFlight).length
83
84
  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}`)
85
+ const row = (r, indent) => {
86
+ out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
87
+ out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
88
+ if (r.next) out.push(`${indent} next: ${actionText(r.next)}`)
89
+ }
90
+ // Members are listed under their epic, read off each spec's own copy; a spec
91
+ // in no epic — the common case — prints exactly as it always has.
92
+ for (const r of rows.filter((x) => !x.epic)) row(r, ' ')
93
+ const epics = [...new Set(rows.map((r) => r.epic).filter(Boolean))].sort()
94
+ for (const epic of epics) {
95
+ out.push(` ${epic}`)
96
+ for (const r of rows.filter((x) => x.epic === epic)) row(r, ' ')
87
97
  }
88
98
  // SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
89
99
  // this checkout, the line would explain a discrepancy that is not there.
@@ -0,0 +1,262 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The one thing to do next for a spec, and where — the cell behind the `next`
5
+ * column of `skitterspec epic status` and `skitterspec status` (spec
6
+ * feat-epic-next, Decision 1).
7
+ *
8
+ * `nextAction` is pure: every input arrives already read, with `null` meaning
9
+ * the reader could not tell. `readNextInputs` is the half that touches disk —
10
+ * the gate, the pending store, the worktree's tree and its phase files — and
11
+ * its io is injectable so the command layer is testable without a worktree.
12
+ *
13
+ * Positive signals only (`.claude/rules/negative-checks.md`). A verb is a
14
+ * claim about the spec, so every input that is unreadable routes to
15
+ * `cannot-tell` and never to a verb: telling someone to `/spec-complete` a spec
16
+ * whose phase files could not be read is the accusation this exists to avoid.
17
+ */
18
+
19
+ const fs = require('node:fs')
20
+ const path = require('node:path')
21
+
22
+ const { phaseIsDone } = require('./resolve.js')
23
+ const { readGate, readPending, gateState } = require('./review.js')
24
+ const { dirtyPaths } = require('./classify.js')
25
+
26
+ const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
27
+
28
+ const tell = (state, why) => ({ verb: 'cannot-tell', state, command: null, link: null, why })
29
+
30
+ function backlogAction(spec, { waits = [], freeLanes = null, clashWith = [] }) {
31
+ const unmet = waits.filter((w) => w.state === 'unmet')
32
+ if (unmet.length) {
33
+ return { verb: 'blocked', state: 'backlog', command: null, link: null, why: `waits on ${unmet.map((w) => w.raw).join(', ')}` }
34
+ }
35
+ const unknown = waits.filter((w) => w.state !== 'met')
36
+ if (unknown.length) return tell('backlog', `cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed`)
37
+ // Both qualifiers advise and never withhold the command: `Lanes:` is a cap
38
+ // the operator chose and `Area:` is declared rather than measured, so the
39
+ // operator may know better (spec feat-epics, Decision 4).
40
+ const held = []
41
+ if (freeLanes === 0) held.push('no free lane')
42
+ if (clashWith.length) held.push(`clashes with ${clashWith.join(', ')}`)
43
+ return {
44
+ verb: 'start',
45
+ state: 'backlog · ready',
46
+ command: `/spec-start ${spec}`,
47
+ link: null,
48
+ why: held.length ? held.join(' · ') : null,
49
+ }
50
+ }
51
+
52
+ /**
53
+ * @param {object} a
54
+ * - `spec` the spec's folder name
55
+ * - `bucket` where its own copy sits, or null when it could not be read
56
+ * - `phases` `[{ n, done }]` from its own copy, or null when unreadable
57
+ * - `gate` `armed` · `clear` · `off` (the project opted out) ·
58
+ * `unreadable`
59
+ * - `passes` codes of the passes waiting unclaimed, or null when the
60
+ * pending store could not be read
61
+ * - `dirty` uncommitted paths in its worktree, or null when git could
62
+ * not answer
63
+ * - `syncWaits` `[{ phase, state, raw }]` — this spec's phase-level waits
64
+ * - `waits` its start waits, resolved — a backlog member's only
65
+ * - `freeLanes` the epic's free lanes, or null with no cap
66
+ * - `clashWith` in-flight members whose `Area:` meets this one's
67
+ * @returns {{ verb, state, command, link, why }}
68
+ */
69
+ function nextAction(a) {
70
+ const { spec, bucket } = a
71
+ if (bucket === 'complete') return { verb: 'done', state: 'complete', command: null, link: null, why: null }
72
+ if (bucket === 'cancelled') return { verb: 'done', state: 'cancelled', command: null, link: null, why: null }
73
+ if (bucket === 'backlog') return backlogAction(spec, a)
74
+ if (bucket !== 'in-progress') return tell('unknown', `${spec}'s own copy could not be read`)
75
+
76
+ const phases = a.phases
77
+ if (phases === null || phases === undefined) return tell('in-progress', 'its phase files could not be read')
78
+ const done = phases.filter((p) => p.done).length
79
+ const progress = `phase ${Math.min(done + 1, phases.length)} of ${phases.length}`
80
+
81
+ // A pass first: someone already answered, and only a person in that tab can
82
+ // pick it up (`/spec-reviewed` is user-only by harness enforcement).
83
+ if (a.passes === null || a.passes === undefined) return tell(progress, 'the pending store is not readable')
84
+ if (a.passes.length === 1) {
85
+ return { verb: 'claim', state: `${progress} · pass waiting`, command: `/spec-reviewed ${a.passes[0]}`, link: null, why: null }
86
+ }
87
+ if (a.passes.length > 1) {
88
+ return {
89
+ verb: 'claim',
90
+ state: `${progress} · ${a.passes.length} passes waiting`,
91
+ command: '/spec-reviewed <code>',
92
+ link: null,
93
+ why: `name one: ${a.passes.join(', ')}`,
94
+ }
95
+ }
96
+
97
+ // `off` is a project that set `review.required: false` — silence, not a
98
+ // finding, so it falls through to the rest of the precedence.
99
+ if (a.gate === 'unreadable') return tell(progress, 'the review gate is not readable')
100
+ if (a.gate === 'armed') {
101
+ return { verb: 'verdict', state: `${progress} · page waits`, command: null, link: null, why: 'press a verdict on its page' }
102
+ }
103
+
104
+ // DIRTY WITH NO PHASE ENDED IS NOT "COMMIT". The engine cannot tell an agent
105
+ // mid-build from work left sitting, and `/commit` said to a tab that is
106
+ // building is the wrong advice — so it is a state with no verb (Decision 2).
107
+ if (a.dirty === null || a.dirty === undefined) return tell(progress, 'git could not read its worktree')
108
+ if (a.dirty > 0) {
109
+ return { verb: 'building', state: `${progress} · ${plural(a.dirty, 'file')} uncommitted`, command: null, link: null, why: 'building — nothing to run yet' }
110
+ }
111
+
112
+ // A spec with no phase files yet has nothing for `/spec-next` to build;
113
+ // naming the command would send the operator to a refusal.
114
+ if (!phases.length) return { verb: 'idle', state: 'no phase files', command: null, link: null, why: null }
115
+ if (done === phases.length) {
116
+ return { verb: 'complete', state: `${done} of ${phases.length} ✅ · clean`, command: '/spec-complete', link: null, why: null }
117
+ }
118
+
119
+ const next = phases.find((p) => !p.done).n
120
+ const held = (a.syncWaits || []).filter((w) => w.phase === next)
121
+ const unmet = held.filter((w) => w.state === 'unmet')
122
+ if (unmet.length) {
123
+ return { verb: 'held', state: progress, command: null, link: null, why: `phase ${next} waits on ${unmet.map((w) => w.raw).join(', ')}` }
124
+ }
125
+ const unknown = held.filter((w) => w.state !== 'met')
126
+ return {
127
+ verb: 'next',
128
+ state: progress,
129
+ command: '/spec-next',
130
+ link: null,
131
+ why: unknown.length ? `phase ${next} · cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed` : `phase ${next}`,
132
+ }
133
+ }
134
+
135
+ /**
136
+ * The epic's own row: `/spec-complete <epic>` once no member is open, and
137
+ * nothing before — an epic completes after its members (feat-epics, Decision
138
+ * 7). An epic with no members has nothing to complete after, so it says
139
+ * nothing rather than inviting a completion of an empty plan.
140
+ */
141
+ function epicNext(epic, members) {
142
+ if (!members.length) return null
143
+ if (members.some((m) => m.bucket !== 'complete' && m.bucket !== 'cancelled')) return null
144
+ return { verb: 'complete', state: 'every member finished', command: `/spec-complete ${epic}`, link: null, why: null }
145
+ }
146
+
147
+ const defaultIo = {
148
+ readdir: (dir) => fs.readdirSync(dir),
149
+ readFile: (file) => fs.readFileSync(file, 'utf8'),
150
+ }
151
+
152
+ function tryRead(fn) {
153
+ try {
154
+ return fn()
155
+ } catch {
156
+ return null
157
+ }
158
+ }
159
+
160
+ /**
161
+ * A spec's phases as its own copy has them, `[{ n, done }]`, or null when the
162
+ * folder could not be read. Read in the worktree because that is the copy that
163
+ * is true for a spec being built; the base branch still files it in backlog.
164
+ */
165
+ function readPhases(root, bucket, folder, io = defaultIo) {
166
+ const dir = path.join(root, 'specs', bucket, folder)
167
+ const files = tryRead(() => io.readdir(dir))
168
+ if (!files) return null
169
+ const out = []
170
+ for (const f of files.filter((x) => /^(?!00-)\d{2}-.*\.md$/.test(x)).sort()) {
171
+ const text = tryRead(() => io.readFile(path.join(dir, f)))
172
+ // One unreadable phase makes the count a guess, and a guess here is what
173
+ // would print `/spec-complete` for a spec with a phase left to build.
174
+ if (text === null) return null
175
+ out.push({ n: Number(f.slice(0, 2)), done: phaseIsDone(text) })
176
+ }
177
+ return out
178
+ }
179
+
180
+ /**
181
+ * The disk half: everything `nextAction` needs about one in-flight spec that is
182
+ * not the epic's to say.
183
+ *
184
+ * @param {object} a
185
+ * - `folder` the spec
186
+ * - `bucket` its bucket in its own copy
187
+ * - `worktree` its worktree root
188
+ * - `outPath` its review page path in the primary checkout, where the gate
189
+ * and the pending store sit beside it
190
+ * - `required` `review.required` from the project config
191
+ * - `git` a reader for the worktree, `argv → stdout | null`
192
+ */
193
+ function readNextInputs({ folder, bucket, worktree, outPath, required, git, io = defaultIo }) {
194
+ const gateRead = readGate(outPath, folder)
195
+ const g = gateState({ ...gateRead, required })
196
+ // `unknown` covers three readings and only one is a fault: the project
197
+ // opting out is silence, a corrupt or newer sidecar is cannot-tell.
198
+ const gate = g.state === 'armed' ? 'armed' : g.state === 'clear' ? 'clear' : required === false ? 'off' : 'unreadable'
199
+ const pending = readPending(outPath, folder)
200
+ const passes = pending.corrupt ? null : pending.pending.passes.filter((p) => p && p.code).map((p) => p.code)
201
+ const dirty = dirtyPaths(git)
202
+ return {
203
+ bucket,
204
+ phases: bucket ? readPhases(worktree, bucket, folder, io) : null,
205
+ gate,
206
+ passes,
207
+ dirty: dirty === null ? null : dirty.length,
208
+ }
209
+ }
210
+
211
+ /**
212
+ * The `next` cell as words — one string shared by every rendering, so the
213
+ * terminal, `status` and the page cannot word the same action differently.
214
+ */
215
+ function actionText(a) {
216
+ if (!a) return '—'
217
+ if (a.verb === 'verdict') return a.link ? `verdict → ${a.link}` : 'verdict — /spec-diff in its tab'
218
+ if (a.verb === 'cannot-tell') return `cannot tell — ${a.why}`
219
+ if (a.command) return a.why ? `${a.command} — ${a.why}` : a.command
220
+ return a.why || '—'
221
+ }
222
+
223
+ /**
224
+ * One row per member, in `epicStatus` order: `{ spec, bucket, tab, next }`,
225
+ * plus the epic's own action. Pure — the disk arrives through three callbacks,
226
+ * each answering for one spec:
227
+ *
228
+ * - `inputsFor(spec)` → `readNextInputs`' answer, or null when the spec has
229
+ * no worktree on this machine
230
+ * - `tabFor(spec)` → where its tab stands, or null
231
+ * - `linkFor(spec)` → its served page, or null when nothing is serving
232
+ *
233
+ * An in-flight member with no worktree HERE is cannot-tell rather than
234
+ * guessed: it may be in flight on a colleague's machine, and its gate and its
235
+ * tree are there, not here.
236
+ */
237
+ function epicRows(status, { inputsFor = () => null, tabFor = () => null, linkFor = () => null } = {}) {
238
+ const flying = new Set(status.inFlight.map((m) => m.spec))
239
+ const rows = status.members.map((m) => {
240
+ const clashWith = status.clashes
241
+ .filter((c) => c.specs.includes(m.spec))
242
+ .map((c) => c.specs.find((x) => x !== m.spec))
243
+ .filter((x) => flying.has(x))
244
+ const syncWaits = status.syncPoints
245
+ .filter((p) => p.spec === m.spec && p.phase !== null)
246
+ .map((p) => ({ phase: p.phase, state: p.wait.state, raw: p.wait.raw }))
247
+ let next
248
+ if (m.bucket === 'in-progress') {
249
+ const inputs = inputsFor(m.spec)
250
+ next = inputs
251
+ ? nextAction({ spec: m.spec, ...inputs, bucket: 'in-progress', syncWaits })
252
+ : tell('in-progress', 'no worktree for it on this machine')
253
+ } else {
254
+ next = nextAction({ spec: m.spec, bucket: m.bucket, waits: m.waits, freeLanes: status.freeLanes, clashWith })
255
+ }
256
+ if (next.verb === 'verdict') next = { ...next, link: linkFor(m.spec) }
257
+ return { spec: m.spec, bucket: m.bucket, tab: m.bucket === 'in-progress' ? tabFor(m.spec) : null, next }
258
+ })
259
+ return { rows, next: epicNext(status.epic, status.members) }
260
+ }
261
+
262
+ module.exports = { nextAction, epicNext, epicRows, actionText, readNextInputs, readPhases }
@@ -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,
package/src/env/serve.js CHANGED
@@ -35,7 +35,10 @@ const {
35
35
  allSpecs,
36
36
  resolveSpec,
37
37
  resolveBaseBranch,
38
+ isEpic,
38
39
  } = require('./resolve.js')
40
+ const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
41
+ const { renderEpicPage } = require('./epicpage.js')
39
42
  const { readRegistry } = require('./registry.js')
40
43
  const { loadEnvConfig } = require('./config.js')
41
44
  const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
@@ -124,8 +127,16 @@ function escapeHtml(s) {
124
127
  * palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
125
128
  * do not disagree when opened side by side.
126
129
  */
127
- function renderIndex(entries, { token = null } = {}) {
130
+ function renderIndex(entries, { token = null, epics = [] } = {}) {
128
131
  const prefix = token ? `/${token}` : ''
132
+ // Epics with a member in flight, each a doorway to its epic page. Listed
133
+ // above the diffs because an epic page is where a reader running several
134
+ // members starts; absent entirely on a repo with no epic in flight.
135
+ const epicList = epics.length
136
+ ? `<h2>epics</h2>\n<ul>\n${epics
137
+ .map((e) => `<li><a href="${prefix}/${encodeURIComponent(e)}">${escapeHtml(e)}</a><span class="b">what to run next, per member</span></li>`)
138
+ .join('\n')}\n</ul>\n<h2>diffs</h2>`
139
+ : ''
129
140
  const rows = entries
130
141
  .map((e) => {
131
142
  const t = e.totals || { files: 0, additions: 0, deletions: 0 }
@@ -161,6 +172,7 @@ body { margin:0; padding:2rem 1.25rem; background:var(--bg); color:var(--fg);
161
172
  font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
162
173
  main { max-width:52rem; margin:0 auto }
163
174
  h1 { font-size:1.1rem; margin:0 0 1.25rem; font-weight:600 }
175
+ h2 { font-size:.9rem; margin:1.25rem 0 .25rem; font-weight:600; color:var(--dim) }
164
176
  ul { list-style:none; margin:0; padding:0 }
165
177
  li { display:flex; flex-wrap:wrap; gap:.75rem; align-items:baseline;
166
178
  padding:.7rem 0; border-top:1px solid var(--line) }
@@ -177,6 +189,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
177
189
  <body>
178
190
  <main>
179
191
  <h1>spec diffs</h1>
192
+ ${epicList}
180
193
  ${body}
181
194
  </main>
182
195
  </body>
@@ -792,7 +805,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
792
805
  })
793
806
  }
794
807
 
795
- function createReviewServer({ resolveEntries, render, receive = null, passState = null, token = null }) {
808
+ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
796
809
  return http.createServer((req, res) => {
797
810
  const send = (code, body, type = 'text/html; charset=utf-8') => {
798
811
  res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
@@ -846,7 +859,7 @@ function createReviewServer({ resolveEntries, render, receive = null, passState
846
859
  }
847
860
 
848
861
  try {
849
- if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token }))
862
+ if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
850
863
  const out = render(route.spec, { branch: route.branch })
851
864
  if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
852
865
  if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
@@ -995,9 +1008,53 @@ function serverHooks(dir, config) {
995
1008
  }
996
1009
  })
997
1010
 
1011
+ // Every provisioned spec's own copy — what an epic's members are read off.
1012
+ const worktrees = () =>
1013
+ allSpecs(dir, config, liveWorktreePaths(trimmedGit), specless())
1014
+ .filter((s) => !s.specless && s.worktreePath && s.worktreePath !== dir && fs.existsSync(s.worktreePath))
1015
+ .map((s) => worktreeOverview(s.projectPath || s.worktreePath, s.folder))
1016
+ .filter(Boolean)
1017
+
1018
+ // The epic page, read per request like every other page. null — a 404 — when
1019
+ // no such epic exists and no spec names it; an unreadable base branch is a
1020
+ // 409 saying so, never an empty plan.
1021
+ const epicPage = (folder) => {
1022
+ let base
1023
+ try {
1024
+ base = resolveBaseBranch(config, trimmedGit)
1025
+ } catch (err) {
1026
+ return { error: `cannot tell — ${err.message}` }
1027
+ }
1028
+ const tree = epicTree(trimmedGit, base)
1029
+ if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
1030
+ const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
1031
+ const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
1032
+ if (!answer.found && !answer.members.length) return null
1033
+ return { html: renderEpicPage(answer) }
1034
+ }
1035
+
998
1036
  return {
999
1037
  resolveEntries,
1000
- render: (folder, opts) => renderSpecPage(dir, config, resolveOne(folder), opts),
1038
+ resolveEpics: () => {
1039
+ try {
1040
+ return epicsInFlight(worktrees())
1041
+ } catch {
1042
+ // The index is a doorway; an unreadable worktree costs a link, never the page.
1043
+ return []
1044
+ }
1045
+ },
1046
+ render: (folder, opts) => {
1047
+ // AN EPIC BEING WRITTEN KEEPS ITS AUTHORING PAGE. `/spec` renders a new
1048
+ // epic's own documents at this same address, with verdict buttons, and
1049
+ // that page must still be the one a reader gets while the documents are
1050
+ // uncommitted. Every other epic address is the epic page.
1051
+ if (isEpic(folder)) {
1052
+ const one = resolveOne(folder)
1053
+ const view = one ? viewFor(dir, config, one, trimmedGit) : null
1054
+ if (!view || view.kind !== 'docs') return epicPage(folder)
1055
+ }
1056
+ return renderSpecPage(dir, config, resolveOne(folder), opts)
1057
+ },
1001
1058
  receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
1002
1059
  // A spec this daemon cannot resolve is not a pass that was claimed — it is
1003
1060
  // a lookup that could not see, so it says nothing rather than reporting the
@@ -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
 
@@ -314,6 +314,26 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
314
314
  throw error
315
315
  }
316
316
  },
317
+ /**
318
+ * Make `ref` a child of `parentRef` — an epic member under its epic (spec
319
+ * feat-epics). Both are read by identifier or uuid. Idempotent: an issue
320
+ * already under that parent is left alone; one under another is moved,
321
+ * since Linear has one parent per issue. Read back, and refused when Linear
322
+ * holds anything else, so a link that did not land is never reported set.
323
+ */
324
+ async setParent(ref, parentRef) {
325
+ const issue = await this.readIssue(ref)
326
+ if (!issue) throw new Error(`no Linear issue ${ref} to put under ${parentRef}`)
327
+ const parent = await this.readIssue(parentRef)
328
+ if (!parent) throw new Error(`no Linear issue ${parentRef} to put ${issue.identifier} under`)
329
+ if (issue.parent && issue.parent.id === parent.id) return { changed: false }
330
+ await this.updateIssue(issue.id, { parentId: parent.id })
331
+ const back = await this.readIssue(issue.id)
332
+ if (!back || !back.parent || back.parent.id !== parent.id) {
333
+ throw new Error(`${issue.identifier} was put under ${parent.identifier} but Linear reads it back elsewhere`)
334
+ }
335
+ return { changed: true, moved: !!issue.parent }
336
+ },
317
337
  // A phase sub-issue is an ordinary issue carrying `parentId`. Same mutation,
318
338
  // so there is no separate sub-issue surface to keep in step.
319
339
  async createSubIssue(parentId, subIssue) {