@skitterbyte/skitterspec-linear 19.6.0 → 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.
package/README.md CHANGED
@@ -93,6 +93,7 @@ them. Your `specs/` content and live `.core` config are never touched.
93
93
  | `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
94
94
  | `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
95
95
  | `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
96
+ | `/epic` | What every member of an epic needs next, in which tab, and the epic page |
96
97
  | `/spec-push` | Repo → Linear, one-way |
97
98
  | `/spec-status` | Read-only report: what would push, and any edited description |
98
99
  | `/spec-list` | What the tracker holds, with each spec's folder name |
@@ -0,0 +1,21 @@
1
+ ---
2
+ description: What every member of an epic needs next, in which tab, and the epic page — bare uses the epic or member worktree you are in
3
+ argument-hint: "[<epic>]"
4
+ allowed-tools: Bash({{exec}} skitterspec epic status:*)
5
+ disable-model-invocation: true
6
+ ---
7
+ !`{{exec}} skitterspec epic status $ARGUMENTS`
8
+
9
+ Relay the engine output above verbatim. Add nothing and run nothing else.
10
+
11
+ **It is for coming back to the epic's tab.** Each member is built in a tab of
12
+ its own; this one is where you return to see what each needs. On a phone the
13
+ in-app browser closes to switch tabs, so the epic page's link is what you came
14
+ back for — it is the last thing printed.
15
+
16
+ **It reads, and nothing more.** It starts no server, claims no pass and runs no
17
+ member's next command: those are typed in that member's own tab. A waiting pass
18
+ it names is picked up there with `/spec-reviewed`.
19
+
20
+ **Only you can run it**, for `/spec-connect`'s reason: there is no judgement to
21
+ apply, so no model turn is spent finding one.
@@ -124,6 +124,14 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
124
124
  is worse: `/commit` belongs to skittership, which is why the gate is enforced
125
125
  by a hook rather than by editing that skill.
126
126
 
127
+ **`/epic` is the sixth command**, and it is user-only for the mild reason: it
128
+ pre-executes `skitterspec epic status` and relays it, so there is no judgement
129
+ to apply. It exists for the tab an epic is run from — each member is built in
130
+ a tab of its own, and on a phone the in-app browser has to close to switch
131
+ tabs, so the epic page's link has to be one command away rather than scrolled
132
+ past. Bare, it means the epic of the worktree it runs in. It reads and nothing
133
+ more: the next action it names for a member is typed in that member's tab.
134
+
127
135
  **A refusal may OFFER its own exit, and that is a different thing again.**
128
136
  Where the engine declares one, a skill relays the refusal and **then** offers it
129
137
  — once per obligation, with the choice recorded, and answered by the operator
@@ -518,8 +518,31 @@ invoke it yourself.
518
518
 
519
519
  **An epic has no phase 1.** `spec-env up` gives it a documents-only tree (no
520
520
  `setup`, no Docker) whether or not `--docs` was passed, because its work is its
521
- members'. Skip this step and step 5, end with the block, and name
522
- `skitterspec epic status <name>` in `Next`.
521
+ members'. Skip this step and step 5, and end with the block — but first ask
522
+ what the epic needs started:
523
+
524
+ ```
525
+ skitterspec epic status <name> --json
526
+ ```
527
+
528
+ Its `rows` carry each member's next action, and its `page` the epic page's
529
+ tiers. Two things go in the block, both copied from it rather than composed:
530
+
531
+ - **`Next`** names the first members to start — one `/spec-start <member>`
532
+ for each row whose `next.verb` is `start`, **in a new tab each**, and only as
533
+ many as there are free lanes (`freeLanes`; all of them when it is null). A
534
+ start qualified `no free lane` or `clashes with …` is not offered here. None
535
+ ready is a true answer: say what the first wave waits on.
536
+ - **`Review`** carries the epic page's stack — `local`, `network`, `remote`,
537
+ as `page.tiers` gives them — or, where `page.off`, the command that starts
538
+ the server. It is a page to come back to, not one to answer: nothing waits
539
+ on it, so it is the row and never the banner.
540
+
541
+ **This tab is the epic's from here.** The members are built in tabs of their
542
+ own; this one is where the operator comes back to see what each needs. On a
543
+ phone the in-app browser has to close to switch tabs, so the page link must be
544
+ one command away rather than scrolled past: **`/epic`** re-shows the table and
545
+ the page, and the block names it.
523
546
 
524
547
  **`checkout` mode — carry straight on into `/spec-next`** in this session: it
525
548
  marks phase 1 started, refreshes the mirror again, builds it with tests and
@@ -585,11 +608,15 @@ the shape; this section carries only what is specific here.
585
608
  is **not** on this list in `worktree` mode — it is an `Untouched` row on a
586
609
  `✅`.
587
610
 
588
- **Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Follow-ups` · `Next`
611
+ **Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Review` · `Follow-ups` · `Next`
589
612
 
590
613
  `Worktree` carries the path, because the session is now standing in it and the
591
614
  operator's next command depends on knowing that. `Next` is `/spec-next`.
592
615
 
616
+ **An epic is the one exception, both ways.** `Review` appears only for an epic,
617
+ carrying its page's stack, and its `Next` is the members to start in new tabs
618
+ — with `/epic` to bring the table and the page back (step 6).
619
+
593
620
  `Untouched` appears only when `spec-env up` reported uncommitted work that was
594
621
  not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing
595
622
  went wrong: a worktree carries nothing, so that work was never in play.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.6.0",
3
+ "version": "19.7.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -198,6 +198,8 @@ const {
198
198
  appendChangelog,
199
199
  waitsMetByRebase,
200
200
  } = require('./env/epic.js')
201
+ const { nextAction, readNextInputs } = require('./env/nextaction.js')
202
+ const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
201
203
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
202
204
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
203
205
  const { planDev } = require('./env/dev.js')
@@ -565,7 +567,26 @@ function inFlightStatus(argv) {
565
567
  const dir = anchor.dir
566
568
  const { config, present } = loadEnvConfig(dir)
567
569
  attachProject(config, anchor)
568
- const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
570
+ const rows = (present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []).map((r) =>
571
+ // Only a spec whose own copy was read, and which is still in flight, gets
572
+ // a next action — a finished or unreadable one has nothing true to offer.
573
+ isInFlight(r) && r.found
574
+ ? {
575
+ ...r,
576
+ next: nextAction({
577
+ spec: r.spec,
578
+ ...readNextInputs({
579
+ folder: r.spec,
580
+ bucket: r.bucket,
581
+ worktree: r.worktree,
582
+ outPath: reviewOutPath(dir, r.spec),
583
+ required: config.review.required,
584
+ git: gitReader(r.worktree),
585
+ }),
586
+ }),
587
+ }
588
+ : r,
589
+ )
569
590
  if (json) {
570
591
  const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
571
592
  process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
@@ -586,15 +607,73 @@ function inFlightStatus(argv) {
586
607
  */
587
608
  function epicStatusCommand(argv) {
588
609
  const json = argv.includes('--json')
589
- const epic = epicPositional(argv)
610
+ const named = epicPositional(argv)
611
+ const inputs = epicInputs(argv, json, named || null)
612
+ if (!inputs) return
613
+ const epic = named || epicFromHere(inputs)
590
614
  if (!epic) {
591
- process.stdout.write('Usage: skitterspec epic status <epic> [--json] [--dir <path>]\n')
615
+ const flying = epicsInFlight(inputs.worktrees)
616
+ const line = flying.length
617
+ ? `name an epic — in flight here: ${flying.join(', ')}`
618
+ : 'name an epic — none has a member in flight here'
619
+ process.stdout.write(
620
+ json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--json] [--dir <path>]\n${line}\n`,
621
+ )
592
622
  return
593
623
  }
594
- const inputs = epicInputs(argv, json, epic)
595
- if (!inputs) return
596
- const status = epicStatus({ epic, ...inputs })
597
- process.stdout.write(json ? JSON.stringify({ base: inputs.base, ...status }, null, 2) + '\n' : formatEpicStatus(status))
624
+ const up = inputs.config ? readRunningReviewServer(inputs.dir, inputs.config) : null
625
+ const readers = memberReaders({
626
+ ...inputs,
627
+ git: gitReader,
628
+ // A link only where a server is already serving: this reads the server and
629
+ // never starts one, so a status asked from a phone never restarts the
630
+ // server whose link that phone has open.
631
+ linkFor: (spec) => (up ? `${serveUrl('127.0.0.1', up)}${encodeURIComponent(spec)}` : null),
632
+ })
633
+ const answer = epicAnswer(epic, inputs, readers)
634
+ const page = epicPageTiers(inputs, up, epic)
635
+ if (json) {
636
+ process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
637
+ return
638
+ }
639
+ // No such epic is a plain answer; a page link for it would be a link to nothing.
640
+ const found = answer.found || answer.members.length
641
+ process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
642
+ }
643
+
644
+ /**
645
+ * Where the epic page can be read: the same tiers a review render prints, for
646
+ * the epic's own route — or, with no server running, the one command that
647
+ * starts it. Never null where isolation is configured, because the page is the
648
+ * thing a phone reader comes back to (Decision 8).
649
+ */
650
+ function epicPageTiers(inputs, up, epic) {
651
+ if (!inputs.config) return null
652
+ if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
653
+ const served = reviewServedUrls(up, offerableLanAddresses(), epic)
654
+ return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config }) }
655
+ }
656
+
657
+ function epicPageLines(page) {
658
+ if (!page) return ''
659
+ if (page.off) return `epic page: no review server running — start it with: ${page.start}\n`
660
+ return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
661
+ }
662
+
663
+ /**
664
+ * The epic a bare `epic status` means: the one whose worktree this command runs
665
+ * in, or the epic named by the member whose worktree it runs in. A positive
666
+ * signal or nothing — standing anywhere else names no epic, and the caller says
667
+ * so rather than picking one.
668
+ */
669
+ function epicFromHere(inputs) {
670
+ const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
671
+ if (!top) return null
672
+ const here = path.resolve(top)
673
+ const own = inputs.worktrees.find((w) => here === path.resolve(w.root) || here.startsWith(path.resolve(w.root) + path.sep))
674
+ if (!own) return null
675
+ if (isEpic(own.folder)) return own.folder
676
+ return epicHeaders(own.overview).epic
598
677
  }
599
678
 
600
679
  /**
@@ -744,52 +823,15 @@ function epicInputs(argv, json, subject) {
744
823
  } catch (err) {
745
824
  return say(err.message)
746
825
  }
747
- const listing = git(['ls-tree', '-r', '--name-only', base, '--', 'specs'])
748
- if (listing === null) return say(`the base branch ${base} could not be read`)
749
- // `git grep` exits 1 on no match, which the reader returns as null. The tree
750
- // above was readable, so here null is "no spec names an epic".
751
- const grep = git(['grep', '-l', '-E', '^>[[:space:]]*\\*\\*Epic:\\*\\*', base, '--', 'specs'])
752
- const candidates = (grep || '')
753
- .split('\n')
754
- .filter(Boolean)
755
- .map((l) => l.slice(base.length + 1))
756
- const readFile = (p) => git(['show', `${base}:${p}`])
826
+ const tree = epicTree(git, base)
827
+ if (!tree) return say(`the base branch ${base} could not be read`)
757
828
  const worktrees = present
758
829
  ? provisionedSpecs(dir, config)
759
830
  .filter((p) => !p.specless)
760
831
  .map((p) => worktreeOverview(p.project, p.folder))
761
832
  .filter(Boolean)
762
833
  : []
763
- return { dir, base, index: indexSpecTree(listing), readFile, candidates, worktrees }
764
- }
765
-
766
- // A provisioned spec's own overview and bucket, read in its worktree — the
767
- // copy where an in-flight spec's bucket and headers are true. null when the
768
- // worktree holds no readable copy.
769
- function worktreeOverview(root, folder) {
770
- for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
771
- const dir = path.join(root, 'specs', bucket, folder)
772
- let overview
773
- try {
774
- overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
775
- } catch {
776
- continue
777
- }
778
- const phases = fs
779
- .readdirSync(dir)
780
- .filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
781
- .map((f) => {
782
- let text = null
783
- try {
784
- text = fs.readFileSync(path.join(dir, f), 'utf8')
785
- } catch {
786
- // unreadable: a phase with nothing to say
787
- }
788
- return { n: Number(f.slice(0, 2)), text }
789
- })
790
- return { folder, bucket, overview, phases, root }
791
- }
792
- return null
834
+ return { dir, config: present ? config : null, base, ...tree, worktrees }
793
835
  }
794
836
 
795
837
  // Plan a provision: allocate the slot, persist the registry, and print the plan
package/src/env/epic.js CHANGED
@@ -27,6 +27,7 @@
27
27
  */
28
28
 
29
29
  const { phaseIsDone } = require('./resolve.js')
30
+ const { epicRows, actionText } = require('./nextaction.js')
30
31
 
31
32
  const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
32
33
 
@@ -379,9 +380,6 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
379
380
  }
380
381
  }
381
382
 
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
383
  // `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
386
384
  function syncLine({ spec, phase, wait }) {
387
385
  const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
@@ -389,28 +387,44 @@ function syncLine({ spec, phase, wait }) {
389
387
  return `${who} after ${wait.raw} (${mark} — ${wait.why})`
390
388
  }
391
389
 
390
+ // Columns padded to their widest cell. Plain text, never a markdown table: the
391
+ // answer is read raw under `watch` as often as it is rendered (spec
392
+ // feat-epic-next, Decision 3), and a pipe table read raw is noise.
393
+ function aligned(lines, indent = ' ') {
394
+ const widths = lines[0].map((_, i) => Math.max(...lines.map((l) => l[i].length)))
395
+ return lines.map((l) => (indent + l.map((c, i) => (i === l.length - 1 ? c : c.padEnd(widths[i]))).join(' ')).trimEnd())
396
+ }
397
+
392
398
  /**
393
- * The human answer, in the report-block shape: one sentence, then a table of
394
- * only the rows that have something in them.
399
+ * The human answer: a headline, one row per member saying what to run and in
400
+ * which tab, then the plan's shape — waves, sync points, clashes — wherever
401
+ * there is something to say. `s.rows` comes from `epicRows`; a status without
402
+ * them is rendered with nothing read off disk, so an in-flight member says it
403
+ * cannot tell rather than guessing.
395
404
  */
396
405
  function formatEpicStatus(s) {
397
406
  if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
398
407
  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(' · ')],
408
+ const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${s.found ? '' : ' · epic not on the base branch'}`
409
+ const out = [head, '']
410
+ if (!s.members.length) {
411
+ out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
412
+ } else {
413
+ const { rows, next } = s.rows ? { rows: s.rows, next: s.next } : epicRows(s)
414
+ const state = (r) => (r.bucket === 'in-progress' ? r.next.state : r.next.state || r.bucket || 'unknown')
415
+ out.push(
416
+ ...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
417
+ )
418
+ if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
419
+ }
420
+ const shape = [
421
+ ['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
422
+ ['sync points', s.syncPoints.map(syncLine).join(' · ')],
423
+ ['never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
424
+ ['cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
411
425
  ].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`
426
+ if (shape.length) out.push('', ...aligned(shape))
427
+ return out.join('\n') + '\n'
414
428
  }
415
429
 
416
430
  /**
@@ -0,0 +1,128 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The epic page the review server serves at `/<token>/epic-<name>` — the same
5
+ * answer `skitterspec epic status` prints, as a page that refreshes itself
6
+ * (spec feat-epic-next, Decisions 5–7). PURE: it takes the answer `epicAnswer`
7
+ * built and returns HTML.
8
+ *
9
+ * READ-ONLY. It carries no verdict buttons and no form; a member whose page is
10
+ * waiting is a link to that page, where the buttons already are.
11
+ *
12
+ * NO PASS CODE, EVER. The server keeps every route from listing what is
13
+ * waiting — the six digits are an address only the reader's own page shows —
14
+ * so a waiting pass is named here by what to type, never by its code.
15
+ *
16
+ * LINKS ARE RELATIVE. The page is opened through whichever door the reader
17
+ * has — loopback, LAN, tailnet — and `feat-a` resolves against that door, so
18
+ * no cell ever has to list tiers.
19
+ */
20
+
21
+ const { actionText } = require('./nextaction.js')
22
+
23
+ const REFRESH_SECONDS = 30
24
+
25
+ function escapeHtml(s) {
26
+ return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
27
+ }
28
+
29
+ const href = (spec) => escapeHtml(encodeURIComponent(spec))
30
+
31
+ // The `next` cell. Each verb that names a code or a page is handled here; the
32
+ // rest are `actionText`, the same words the terminal prints.
33
+ function nextCell(row) {
34
+ const a = row.next
35
+ if (a.verb === 'claim') return 'verdict waiting — <code>/spec-reviewed</code> in its tab'
36
+ if (a.verb === 'verdict') return `<a href="${href(row.spec)}">press a verdict on its page →</a>`
37
+ if (a.command) {
38
+ return `<code>${escapeHtml(a.command)}</code>${a.why ? ` <span class="why">${escapeHtml(a.why)}</span>` : ''}`
39
+ }
40
+ return escapeHtml(actionText(a))
41
+ }
42
+
43
+ function memberCell(row) {
44
+ // An in-flight member with a tab has a page of its own on this server.
45
+ return row.tab ? `<a href="${href(row.spec)}">${escapeHtml(row.spec)}</a>` : escapeHtml(row.spec)
46
+ }
47
+
48
+ function syncLine({ spec, phase, wait }) {
49
+ const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
50
+ const mark = { met: 'met', unmet: 'not yet', 'cannot-tell': 'cannot tell' }[wait.state]
51
+ return `${who} after ${wait.raw} (${mark})`
52
+ }
53
+
54
+ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
55
+ const lanes = answer.lanes === null ? 'no lane cap' : `${answer.lanes} lanes, ${answer.freeLanes} free`
56
+ const count = `${answer.members.length} member${answer.members.length === 1 ? '' : 's'}`
57
+ const rows = (answer.rows || [])
58
+ .map(
59
+ (r) =>
60
+ `<tr class="v-${escapeHtml(r.next.verb)}"><td class="m">${memberCell(r)}</td>` +
61
+ `<td class="s">${escapeHtml(r.next.state || r.bucket || '')}</td>` +
62
+ `<td class="x">${nextCell(r)}</td>` +
63
+ `<td class="t">${r.tab ? `<code>${escapeHtml(r.tab)}</code>` : '—'}</td></tr>`,
64
+ )
65
+ .join('\n')
66
+ const table = answer.members.length
67
+ ? `<table>\n<thead><tr><th>member</th><th>state</th><th>next</th><th>tab</th></tr></thead>\n<tbody>\n${rows}\n</tbody>\n</table>`
68
+ : `<p class="empty">No member yet — no spec carries <code>&gt; **Epic:** ${escapeHtml(answer.epic)}</code>.</p>`
69
+ const own = answer.next ? `<p class="own"><code>${escapeHtml(answer.next.command)}</code> — every member is finished</p>` : ''
70
+ const shape = [
71
+ ['waves', answer.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
72
+ ['sync points', answer.syncPoints.map(syncLine).join(' · ')],
73
+ ['never together', answer.clashes.map((c) => `${c.specs.join(' ‖ ')}`).join(' · ')],
74
+ ['cycle', answer.cycles.map((c) => c.join(' → ')).join(' · ')],
75
+ ]
76
+ .filter(([, v]) => v)
77
+ .map(([k, v]) => `<dt>${k}</dt><dd>${escapeHtml(v)}</dd>`)
78
+ .join('\n')
79
+
80
+ return `<!doctype html>
81
+ <html lang="en">
82
+ <head>
83
+ <meta charset="utf-8">
84
+ <meta name="viewport" content="width=device-width, initial-scale=1">
85
+ <meta http-equiv="refresh" content="${Number(refreshSeconds)}">
86
+ <title>${escapeHtml(answer.epic)}</title>
87
+ <style>
88
+ :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
89
+ @media (prefers-color-scheme: dark) {
90
+ :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a }
91
+ }
92
+ * { box-sizing:border-box }
93
+ body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
94
+ font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
95
+ main { max-width:60rem; margin:0 auto }
96
+ h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
97
+ .sub { color:var(--dim); margin:0 0 1.25rem }
98
+ .wrap { overflow-x:auto }
99
+ table { border-collapse:collapse; width:100% }
100
+ th { text-align:left; color:var(--dim); font-weight:500; font-size:.85em }
101
+ th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertical-align:top }
102
+ a { color:var(--link); text-decoration:none; font-weight:600 }
103
+ a:hover { text-decoration:underline }
104
+ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.9em }
105
+ .why, .s, .t { color:var(--dim) }
106
+ .v-verdict .x, .v-claim .x { color:var(--hot) }
107
+ .own { margin:1rem 0 0 }
108
+ dl { margin:1.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
109
+ dt { color:var(--dim) } dd { margin:0 }
110
+ .empty, .foot { color:var(--dim) }
111
+ .foot { margin-top:1.5rem; font-size:.85em }
112
+ </style>
113
+ </head>
114
+ <body>
115
+ <main>
116
+ <h1>${escapeHtml(answer.epic)}</h1>
117
+ <p class="sub">${count} · ${escapeHtml(lanes)}</p>
118
+ <div class="wrap">${table}</div>
119
+ ${own}
120
+ ${shape ? `<dl>\n${shape}\n</dl>` : ''}
121
+ <p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
122
+ </main>
123
+ </body>
124
+ </html>
125
+ `
126
+ }
127
+
128
+ module.exports = { renderEpicPage, REFRESH_SECONDS }
@@ -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
@@ -84,6 +85,7 @@ function formatInFlight(rows, { dir }) {
84
85
  const row = (r, indent) => {
85
86
  out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
86
87
  out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
88
+ if (r.next) out.push(`${indent} next: ${actionText(r.next)}`)
87
89
  }
88
90
  // Members are listed under their epic, read off each spec's own copy; a spec
89
91
  // in no epic — the common case — prints exactly as it always has.
@@ -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 }
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