@skitterbyte/skitterspec-jira 2.7.0 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/assets/claude-md-section.md +6 -0
  2. package/assets/core/env.config.json.example +5 -0
  3. package/assets/core/env.config.md +26 -5
  4. package/assets/review/page.html +9 -0
  5. package/assets/rules/spec-planning.md +65 -12
  6. package/assets/rules/spec-reports.md +8 -1
  7. package/assets/skills/spec/SKILL.md +31 -14
  8. package/assets/skills/spec-cancel/SKILL.md +7 -0
  9. package/assets/skills/spec-complete/SKILL.md +6 -0
  10. package/assets/skills/spec-epic-next/SKILL.md +83 -0
  11. package/assets/skills/spec-init/SKILL.md +35 -3
  12. package/assets/skills/spec-next/SKILL.md +38 -1
  13. package/assets/skills/spec-start/SKILL.md +2 -2
  14. package/assets/skills/spec-tada/SKILL.md +153 -0
  15. package/bin/skitterspec-jira.js +5 -0
  16. package/package.json +1 -1
  17. package/src/cli.js +473 -25
  18. package/src/env/config.js +57 -6
  19. package/src/env/epic.js +69 -19
  20. package/src/env/epicpage.js +87 -39
  21. package/src/env/epicread.js +41 -3
  22. package/src/env/integrate.js +48 -1
  23. package/src/env/nextaction.js +78 -1
  24. package/src/env/project.js +54 -3
  25. package/src/env/projectedit.js +148 -0
  26. package/src/env/resolve.js +1 -0
  27. package/src/env/review.js +21 -3
  28. package/src/env/serve.js +44 -8
  29. package/src/env/specbranches.js +120 -0
  30. package/src/env/teardown.js +18 -3
  31. package/src/gating.js +16 -4
  32. package/src/init.js +11 -3
  33. package/src/tada/commits.js +145 -0
  34. package/src/tada/digest.js +260 -0
  35. package/src/tada/format.js +37 -0
  36. package/src/tada/page.js +213 -0
  37. package/src/tada/repo.js +102 -0
  38. package/src/tada/serve.js +127 -0
  39. package/src/tada/specs.js +146 -0
  40. package/src/tada/transcripts.js +258 -0
  41. package/src/tada/window.js +156 -0
  42. package/src/vendor/provider-kit/src/apply.js +25 -1
  43. package/src/vendor/sync-core/src/compare.js +10 -2
  44. package/src/vendor/sync-core/src/push.js +14 -3
  45. /package/assets/commands/{epic.md → spec-epic.md} +0 -0
package/src/env/config.js CHANGED
@@ -60,7 +60,7 @@
60
60
  */
61
61
 
62
62
  const { createHash } = require('node:crypto')
63
- const { readFileSync, realpathSync } = require('node:fs')
63
+ const { existsSync, readFileSync, realpathSync } = require('node:fs')
64
64
  const { join, resolve, sep } = require('node:path')
65
65
 
66
66
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
@@ -162,6 +162,11 @@ const DEFAULT_CONFIG = Object.freeze({
162
162
  // dev servers may still want parallel specs, and absence of configuration is
163
163
  // not evidence of intent (see .claude/rules/negative-checks.md).
164
164
  mode: 'worktree',
165
+ // What this project is called and which group it belongs to — facts about
166
+ // the project, not about any one feature. `name` heads every generated page
167
+ // (empty: the folder's name); `category` is a free label (`work`, a client's
168
+ // name) that `skitterspec tada` scopes a report by.
169
+ project: Object.freeze({ name: '', category: '' }),
165
170
  worktree: Object.freeze({ root: '../{repo}-wt', folderPattern: '{slug}' }),
166
171
  docker: Object.freeze({
167
172
  enabled: true,
@@ -230,9 +235,11 @@ const DEFAULT_CONFIG = Object.freeze({
230
235
  // follows the merge. `remote` names where the branch is pushed. `draft`
231
236
  // opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
232
237
  // downstream can close a ticket early). `specDocs` decides where a spec
233
- // DOCUMENT lands under "pr": "trunk" keeps today's authoring land (needs
234
- // direct push for docs), "branch" has the spec ride the feature branch and
235
- // land with the work's PR.
238
+ // DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
239
+ // docs under "pr"), "branch" has the spec ride its feature branch and land
240
+ // with the work. The "trunk" here is only the base's default — with a
241
+ // ticketing provider configured and the key unset, `applyProviderSpecDocs`
242
+ // makes it "branch", whatever the strategy.
236
243
  land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
237
244
  // `mainIsLandingZone` defaults ON wherever isolation is configured, matching
238
245
  // the review gate's precedent: the push toward not working on the base branch
@@ -307,6 +314,9 @@ const DEFAULT_CONFIG = Object.freeze({
307
314
  allowRemote: false,
308
315
  commitWith: '/commit',
309
316
  required: true,
317
+ // SUPERSEDED by `project.name`, and still read beneath it so a config that
318
+ // set it keeps its name. The name was never the review page's alone.
319
+ projectName: '',
310
320
  // External code reviewers whose findings render as CHECKS on the page.
311
321
  // Empty by default and never written by `init`: configuring one sends the
312
322
  // worktree's diff to whatever the command talks to, which is a decision
@@ -394,6 +404,7 @@ function collectUnknownKeys(parsed, known = DEFAULT_CONFIG, prefix = '') {
394
404
  function defaults() {
395
405
  return {
396
406
  mode: DEFAULT_CONFIG.mode,
407
+ project: { ...DEFAULT_CONFIG.project },
397
408
  worktree: { ...DEFAULT_CONFIG.worktree },
398
409
  docker: { ...DEFAULT_CONFIG.docker },
399
410
  seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
@@ -627,6 +638,11 @@ function normalizeAfterLand(parsed, setupTriggers) {
627
638
  function mergeConfig(base, parsed) {
628
639
  if (!isObject(parsed)) return base
629
640
 
641
+ if (isObject(parsed.project)) {
642
+ assign(base.project, parsed.project, 'name', 'string')
643
+ assign(base.project, parsed.project, 'category', 'string')
644
+ }
645
+
630
646
  if (isObject(parsed.worktree)) {
631
647
  assign(base.worktree, parsed.worktree, 'root', 'string')
632
648
  assign(base.worktree, parsed.worktree, 'folderPattern', 'string')
@@ -772,6 +788,8 @@ function mergeConfig(base, parsed) {
772
788
  // here. There is nothing it could mean instead: the hand-off has no off
773
789
  // switch, so a blank value is a typo rather than an instruction.
774
790
  assign(base.review, parsed.review, 'commitWith', 'string')
791
+ // A blank name falls back to the folder's, like `commitWith` above.
792
+ assign(base.review, parsed.review, 'projectName', 'string')
775
793
  // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
776
794
  // leaves the gate ON. Turning off a check that refuses must be something
777
795
  // someone WROTE, never something a typo achieved on their behalf.
@@ -873,6 +891,33 @@ function applyProviderEnvDefaults(config, parsed) {
873
891
  return config
874
892
  }
875
893
 
894
+ // The provider's own config file, relative to the project root — set once per
895
+ // process by a provider superset's bin, like the defaults above. A registered
896
+ // file that EXISTS is the positive signal that a ticketing provider is attached
897
+ // to this project, and only then does `land.specDocs` default to "branch": the
898
+ // tracker is the backlog, so landing a spec document on the base branch just to
899
+ // make it findable buys nothing (feat-tracker-spec-branches).
900
+ //
901
+ // WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
902
+ // has no config file, and reads as no provider — which is the safe reading,
903
+ // since "trunk" is today's behaviour. An unregistered base distribution never
904
+ // asks at all.
905
+ let providerConfigFile = null
906
+ function setProviderConfigFile(rel) {
907
+ providerConfigFile = rel || null
908
+ }
909
+
910
+ // An explicit `specDocs` in the file — any value, even one the merge rejected —
911
+ // is the project's decision; a rejected typo stays on the conservative "trunk"
912
+ // rather than being promoted to the provider default.
913
+ function applyProviderSpecDocs(config, parsed, dir) {
914
+ if (!providerConfigFile) return config
915
+ const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
916
+ if (pLand && 'specDocs' in pLand) return config
917
+ if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
918
+ return config
919
+ }
920
+
876
921
  function loadEnvConfig(dir = process.cwd()) {
877
922
  const base = defaults()
878
923
  const file = join(dir, CONFIG_FILE)
@@ -882,7 +927,12 @@ function loadEnvConfig(dir = process.cwd()) {
882
927
  raw = readFileSync(file, 'utf-8')
883
928
  } catch (error) {
884
929
  if (error.code === 'ENOENT') {
885
- return { config: applyProviderEnvDefaults(base, null), present: false, unknown: [], badReviewers: [] }
930
+ return {
931
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
932
+ present: false,
933
+ unknown: [],
934
+ badReviewers: [],
935
+ }
886
936
  }
887
937
  throw error
888
938
  }
@@ -895,7 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
895
945
  }
896
946
 
897
947
  return {
898
- config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
948
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
899
949
  present: true,
900
950
  unknown: collectUnknownKeys(parsed),
901
951
  badReviewers: collectBadReviewers(parsed),
@@ -905,6 +955,7 @@ function loadEnvConfig(dir = process.cwd()) {
905
955
  module.exports = {
906
956
  loadEnvConfig,
907
957
  setProviderEnvDefaults,
958
+ setProviderConfigFile,
908
959
  resolveServePort,
909
960
  derivedServePort,
910
961
  servePortRoot,
package/src/env/epic.js CHANGED
@@ -27,7 +27,7 @@
27
27
  */
28
28
 
29
29
  const { phaseIsDone } = require('./resolve.js')
30
- const { epicRows, actionText } = require('./nextaction.js')
30
+ const { epicRows, epicPlan, actionText } = require('./nextaction.js')
31
31
 
32
32
  const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
33
33
 
@@ -292,12 +292,21 @@ function layer(members) {
292
292
  * - `index` `indexSpecTree` of the base branch
293
293
  * - `readFile` base-branch path → text, or null
294
294
  * - `candidates` base-branch overview paths that may carry an `Epic:` header
295
+ * - `waitIndex`/`waitRead` where a wait is resolved, when that is not where
296
+ * members are read — `epic status --here` reads members off a
297
+ * working tree and still meets a wait only on the base branch
295
298
  * - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
296
299
  * each provisioned spec's own copy, which is where an
297
300
  * in-flight spec's bucket and phase progress are true
301
+ * - `branches` the same shape, read off spec branches this machine has no
302
+ * worktree for (`env/specbranches.js`) — how a member that
303
+ * rides its own branch is seen at all. It can make a member
304
+ * VISIBLE and give it a bucket; it never meets a wait, which
305
+ * is still read only off the base branch.
298
306
  */
299
- function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
307
+ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
300
308
  const own = new Map(worktrees.map((w) => [w.folder, w]))
309
+ const onBranch = new Map(branches.filter((b) => !own.has(b.folder)).map((b) => [b.folder, b]))
301
310
  const members = new Map()
302
311
 
303
312
  for (const file of candidates) {
@@ -312,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
312
321
  members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
313
322
  }
314
323
  // A member authored on its own branch and not landed yet is invisible on the
315
- // base branch; its worktree copy is what knows it belongs here.
316
- for (const w of worktrees) {
324
+ // base branch; its worktree copy is what knows it belongs here — or, with no
325
+ // worktree on this machine, its branch's copy. The worktree is read last, so
326
+ // it wins.
327
+ for (const w of [...onBranch.values(), ...worktrees]) {
317
328
  const h = epicHeaders(w.overview)
318
329
  // The worktree's copy is the newer word on a spec being built: it may have
319
330
  // joined, changed its waits, or moved to another epic.
@@ -327,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
327
338
  const base = index.get(m.spec)
328
339
  // In flight is the positive signal of a worktree whose own copy has not
329
340
  // finished; otherwise the base branch's bucket.
330
- m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : base ? base.bucket : wt ? wt.bucket : null
331
- m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, index, readFile) }))
341
+ const br = onBranch.get(m.spec)
342
+ m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : br ? br.bucket : base ? base.bucket : wt ? wt.bucket : null
343
+ m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, waitIndex, waitRead) }))
332
344
  // A phase's own `Waits on:` holds that phase, not the spec's start: the
333
345
  // sync point the field example turned on (#154 phase 2 on #159 phase 1).
334
346
  // A phase already done has nothing left to wait for.
335
347
  m.phaseWaits = m.phases
336
348
  .filter((p) => p.text !== null && !phaseIsDone(p.text))
337
349
  .flatMap((p) =>
338
- epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, index, readFile) } })),
350
+ epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, waitIndex, waitRead) } })),
339
351
  )
340
352
  }
341
353
 
@@ -396,26 +408,42 @@ function aligned(lines, indent = ' ') {
396
408
  }
397
409
 
398
410
  /**
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.
411
+ * The human answer, in the order a reader needs it (spec
412
+ * feat-spec-epic-commands, Decisions 9–10): how far along, every member in its
413
+ * group, then the numbered next steps, then the plan's shape — waves, sync
414
+ * points, clashes — which explains the order the steps act on. `s.rows` comes
415
+ * from `epicRows`; a status without them is rendered with nothing read off
416
+ * disk, so an in-flight member says it cannot tell rather than guessing.
404
417
  */
405
418
  function formatEpicStatus(s) {
406
- if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
419
+ if (!s.found && !s.members.length) {
420
+ return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
421
+ }
407
422
  const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
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, '']
423
+ const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
424
+ const out = []
410
425
  if (!s.members.length) {
411
- out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
426
+ out.push(`${s.epic} — 0 members · ${lanes}${where}`, '', ` no members — no spec carries \`> **Epic:** ${s.epic}\``)
412
427
  } else {
413
428
  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')
429
+ const plan = s.steps ? s : epicPlan(s, { rows, next })
430
+ const { progress, groups, steps } = plan
431
+ const byName = new Map(rows.map((r) => [r.spec, r]))
415
432
  out.push(
416
- ...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
433
+ `${s.epic} — ${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${lanes}${where}`,
434
+ ` ${progressBar(progress)}`,
417
435
  )
418
- if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
436
+ const group = (title, names, cells) => {
437
+ if (!names.length) return
438
+ out.push('', ` ${title}`, ...aligned(names.map((n) => cells(byName.get(n))), ' '))
439
+ }
440
+ group('in flight', groups.inFlight, (r) => [r.spec, r.next.state || 'in-progress', r.tab || '—'])
441
+ group('ready to start', groups.ready, (r) => [r.spec, r.next.why || 'ready'])
442
+ group('waiting', groups.waiting, (r) => [r.spec, r.next.why || actionText(r.next)])
443
+ if (groups.done.length) out.push('', ` done (${groups.done.length})`, ` ${groups.done.join(', ')}`)
444
+ out.push('', ' next steps')
445
+ if (steps.length) out.push(...steps.flatMap((st, i) => stepLines(st, i + 1, s.freeLanes)))
446
+ else out.push(' nothing to type — every open member is building, held or waiting')
419
447
  }
420
448
  const shape = [
421
449
  ['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
@@ -427,6 +455,28 @@ function formatEpicStatus(s) {
427
455
  return out.join('\n') + '\n'
428
456
  }
429
457
 
458
+ // `[█████░░░░]` — one cell per member, so it reads as a count, not a percent.
459
+ function progressBar({ done, total }) {
460
+ return `[${'█'.repeat(done)}${'░'.repeat(Math.max(0, total - done))}]`
461
+ }
462
+
463
+ // One numbered step: where, then what to type, then what it unblocks and any
464
+ // caution, each on its own line so a phone-width terminal does not wrap them
465
+ // into one another.
466
+ function stepLines(st, n, freeLanes) {
467
+ const where =
468
+ st.where === 'epic'
469
+ ? "in the epic's tab"
470
+ : st.where === 'new-tab'
471
+ ? `in a new tab${freeLanes === null || freeLanes === undefined ? '' : ` (${freeLanes} lane${freeLanes === 1 ? '' : 's'} free)`}`
472
+ : `in ${st.tab || `${st.spec}'s tab`}`
473
+ const what = st.verb === 'verdict' ? (st.link ? `press a verdict → ${st.link}` : 'press a verdict on its page') : st.command
474
+ const lines = [` ${n}. ${where}: ${what}`]
475
+ if (st.unblocks.length) lines.push(` → unblocks ${st.unblocks.join(', ')}`)
476
+ if (st.caution) lines.push(` ⚠ ${st.caution}`)
477
+ return lines
478
+ }
479
+
430
480
  /**
431
481
  * What starting or building one member should hear about — the half of
432
482
  * `epic check` that is about other members in flight. Each warning names the
@@ -18,7 +18,7 @@
18
18
  * no cell ever has to list tiers.
19
19
  */
20
20
 
21
- const { actionText } = require('./nextaction.js')
21
+ const { actionText, epicRows, epicPlan } = require('./nextaction.js')
22
22
 
23
23
  const REFRESH_SECONDS = 30
24
24
 
@@ -28,18 +28,6 @@ function escapeHtml(s) {
28
28
 
29
29
  const href = (spec) => escapeHtml(encodeURIComponent(spec))
30
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
31
  function memberCell(row) {
44
32
  // An in-flight member with a tab has a page of its own on this server.
45
33
  return row.tab ? `<a href="${href(row.spec)}">${escapeHtml(row.spec)}</a>` : escapeHtml(row.spec)
@@ -51,22 +39,66 @@ function syncLine({ spec, phase, wait }) {
51
39
  return `${who} after ${wait.raw} (${mark})`
52
40
  }
53
41
 
54
- function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
42
+ // One numbered step. A pass is named by what to type and never its code, like
43
+ // the `next` cell; a verdict links to the member's page.
44
+ function stepItem(st, freeLanes) {
45
+ const where =
46
+ st.where === 'epic'
47
+ ? "In the epic's tab"
48
+ : st.where === 'new-tab'
49
+ ? `In a new tab${freeLanes === null || freeLanes === undefined ? '' : ` (${freeLanes} lane${freeLanes === 1 ? '' : 's'} free)`}`
50
+ : `In <code>${escapeHtml(st.tab || `${st.spec}'s tab`)}</code>`
51
+ const what =
52
+ st.verb === 'claim'
53
+ ? 'verdict waiting — <code>/spec-reviewed</code>'
54
+ : st.verb === 'verdict'
55
+ ? `<a href="${href(st.spec)}">press a verdict on ${escapeHtml(st.spec)}'s page →</a>`
56
+ : `<code>${escapeHtml(st.command)}</code>`
57
+ const notes = [
58
+ st.unblocks.length ? `<div class="un">→ unblocks ${escapeHtml(st.unblocks.join(', '))}</div>` : '',
59
+ st.caution ? `<div class="warn">⚠ ${escapeHtml(st.caution)}</div>` : '',
60
+ ].join('')
61
+ return `<li><div class="where">${where}</div><div class="what">${what}</div>${notes}</li>`
62
+ }
63
+
64
+ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
55
65
  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>`
66
+ const { rows, next } = answer.rows ? { rows: answer.rows, next: answer.next } : epicRows(answer)
67
+ const { progress, groups, steps } = answer.steps ? answer : epicPlan(answer, { rows, next })
68
+ const byName = new Map(rows.map((r) => [r.spec, r]))
69
+
70
+ const section = (title, cls, names, cell) =>
71
+ names.length
72
+ ? `<section class="${cls}"><h2>${title} <span class="n">${names.length}</span></h2>\n<table><tbody>\n${names
73
+ .map((n) => {
74
+ const r = byName.get(n)
75
+ return `<tr class="v-${escapeHtml(r.next.verb)}"><td class="m">${memberCell(r)}</td>${cell(r)}</tr>`
76
+ })
77
+ .join('\n')}\n</tbody></table></section>`
78
+ : ''
79
+ const groupsHtml = answer.members.length
80
+ ? [
81
+ section('In flight', 'g-flight', groups.inFlight, (r) =>
82
+ `<td class="s">${escapeHtml(r.next.state || 'in-progress')}</td><td class="t">${r.tab ? `<code>${escapeHtml(r.tab)}</code>` : '—'}</td>`),
83
+ section('Ready to start', 'g-ready', groups.ready, (r) =>
84
+ `<td class="s">${r.next.why ? `<span class="warn">⚠ ${escapeHtml(r.next.why)}</span>` : 'ready'}</td>`),
85
+ section('Waiting', 'g-wait', groups.waiting, (r) => `<td class="s">${escapeHtml(r.next.why || actionText(r.next))}</td>`),
86
+ groups.done.length
87
+ ? `<details class="g-done"><summary><h2>Done <span class="n">${groups.done.length}</span></h2></summary><p class="dim">${escapeHtml(groups.done.join(' · '))}</p></details>`
88
+ : '',
89
+ ]
90
+ .filter(Boolean)
91
+ .join('\n')
68
92
  : `<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>` : ''
93
+
94
+ const stepsHtml = answer.members.length
95
+ ? `<section class="steps"><h2>Next steps</h2>\n${
96
+ steps.length
97
+ ? `<ol>\n${steps.map((st) => stepItem(st, answer.freeLanes)).join('\n')}\n</ol>`
98
+ : '<p class="dim">Nothing to type — every open member is building, held or waiting.</p>'
99
+ }</section>`
100
+ : ''
101
+ const pct = progress.total ? Math.round((progress.done / progress.total) * 100) : 0
70
102
  const shape = [
71
103
  ['waves', answer.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
72
104
  ['sync points', answer.syncPoints.map(syncLine).join(' · ')],
@@ -83,17 +115,18 @@ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
83
115
  <meta charset="utf-8">
84
116
  <meta name="viewport" content="width=device-width, initial-scale=1">
85
117
  <meta http-equiv="refresh" content="${Number(refreshSeconds)}">
86
- <title>${escapeHtml(answer.epic)}</title>
118
+ <title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
87
119
  <style>
88
- :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
120
+ :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00; --ok:#1f7a3a }
89
121
  @media (prefers-color-scheme: dark) {
90
- :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a }
122
+ :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a; --ok:#5fc27e }
91
123
  }
92
124
  * { box-sizing:border-box }
93
125
  body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
94
126
  font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
95
127
  main { max-width:60rem; margin:0 auto }
96
128
  h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
129
+ .eyebrow { color:var(--dim); font-size:.8rem; margin:0 0 .1rem }
97
130
  .sub { color:var(--dim); margin:0 0 1.25rem }
98
131
  .wrap { overflow-x:auto }
99
132
  table { border-collapse:collapse; width:100% }
@@ -102,10 +135,24 @@ th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertic
102
135
  a { color:var(--link); text-decoration:none; font-weight:600 }
103
136
  a:hover { text-decoration:underline }
104
137
  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 }
138
+ .why, .s, .t, .dim { color:var(--dim) }
139
+ .bar { height:.5rem; background:var(--line); border-radius:.25rem; overflow:hidden; margin:0 0 1.5rem }
140
+ .bar > span { display:block; height:100%; background:var(--ok) }
141
+ h2 { font-size:.8rem; text-transform:uppercase; letter-spacing:.06em; color:var(--dim); font-weight:600; margin:1.5rem 0 .4rem; display:inline-block }
142
+ h2 .n { font-weight:400 }
143
+ section table td.m { width:40% }
144
+ .warn { color:var(--hot) }
145
+ .v-verdict .s, .v-claim .s { color:var(--hot) }
146
+ details summary { cursor:pointer; list-style:none }
147
+ details summary::-webkit-details-marker { display:none }
148
+ details summary h2::after { content:' ▸' } details[open] summary h2::after { content:' ▾' }
149
+ .steps { border-top:2px solid var(--line); margin-top:1.75rem }
150
+ .steps ol { margin:.25rem 0 0; padding-left:1.5rem }
151
+ .steps li { margin:0 0 .9rem }
152
+ .steps .where { color:var(--dim); font-size:.9em }
153
+ .steps .what { margin:.1rem 0 }
154
+ .steps .un { color:var(--ok) }
155
+ dl { margin:.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
109
156
  dt { color:var(--dim) } dd { margin:0 }
110
157
  .empty, .foot { color:var(--dim) }
111
158
  .foot { margin-top:1.5rem; font-size:.85em }
@@ -113,11 +160,12 @@ dt { color:var(--dim) } dd { margin:0 }
113
160
  </head>
114
161
  <body>
115
162
  <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>` : ''}
163
+ ${project ? `<p class="eyebrow">${escapeHtml(project)}</p>\n` : ''}<h1>${escapeHtml(answer.epic)}</h1>
164
+ <p class="sub">${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${escapeHtml(lanes)}</p>
165
+ <div class="bar" role="img" aria-label="${progress.done} of ${progress.total} done"><span style="width:${pct}%"></span></div>
166
+ <div class="wrap">${groupsHtml}</div>
167
+ ${stepsHtml}
168
+ ${shape ? `<details class="shape"><summary><h2>Waves · never together</h2></summary>\n<dl>\n${shape}\n</dl></details>` : ''}
121
169
  <p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
122
170
  </main>
123
171
  </body>
@@ -16,7 +16,7 @@ const path = require('node:path')
16
16
 
17
17
  const { isEpic } = require('./resolve.js')
18
18
  const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
19
- const { epicRows, readNextInputs } = require('./nextaction.js')
19
+ const { epicRows, epicPlan, readNextInputs } = require('./nextaction.js')
20
20
  const { reviewOutPath } = require('./review.js')
21
21
 
22
22
  /**
@@ -36,6 +36,44 @@ function epicTree(git, base) {
36
36
  return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
37
37
  }
38
38
 
39
+ /**
40
+ * The same shape as `epicTree`, read off a WORKING TREE on disk — uncommitted
41
+ * edits included. It is what `epic status --here` reads members and headers
42
+ * from, so a conversion can be checked in the worktree it is made in before it
43
+ * lands. Waits are still met only on the base branch: that is the caller's
44
+ * `waitIndex`, never this.
45
+ *
46
+ * WHAT WOULD FOOL THIS: a file git would ignore is read like any other. Under
47
+ * `specs/` there is nothing ignored by design, so the cost is a stray editor
48
+ * backup named `*.md`, read as one more phase file.
49
+ */
50
+ function workingTree(root) {
51
+ const files = []
52
+ const walk = (rel) => {
53
+ let entries
54
+ try {
55
+ entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true })
56
+ } catch {
57
+ return
58
+ }
59
+ for (const e of entries) {
60
+ const p = `${rel}/${e.name}`
61
+ if (e.isDirectory()) walk(p)
62
+ else if (e.isFile()) files.push(p)
63
+ }
64
+ }
65
+ walk('specs')
66
+ const readFile = (p) => {
67
+ try {
68
+ return fs.readFileSync(path.join(root, p), 'utf8')
69
+ } catch {
70
+ return null
71
+ }
72
+ }
73
+ const candidates = files.filter((p) => p.endsWith('/00-overview.md') && /^>\s*\*\*Epic:\*\*/m.test(readFile(p) || ''))
74
+ return { index: indexSpecTree(files.join('\n')), readFile, candidates }
75
+ }
76
+
39
77
  // A provisioned spec's own overview and bucket, read in its worktree — the
40
78
  // copy where an in-flight spec's bucket and headers are true. null when the
41
79
  // worktree holds no readable copy.
@@ -103,7 +141,7 @@ function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
103
141
  function epicAnswer(epic, inputs, readers) {
104
142
  const status = epicStatus({ epic, ...inputs })
105
143
  const { rows, next } = epicRows(status, readers)
106
- return { ...status, rows, next }
144
+ return { ...status, rows, next, ...epicPlan(status, { rows, next }) }
107
145
  }
108
146
 
109
- module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
147
+ module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
@@ -243,6 +243,53 @@ function planIntegratePr(spec, config, ctx) {
243
243
  }
244
244
  }
245
245
 
246
+ /**
247
+ * Pure planner for the AUTHORING land of a spec document under
248
+ * `land.specDocs: "branch"` (`spec-env integrate --docs`).
249
+ *
250
+ * The document rides its own branch rather than landing on base, so the plan
251
+ * touches no base at all — no rebase, no fast-forward, no PR. What it does is
252
+ * publish the branch, because a spec on an unpushed branch is on one machine
253
+ * and nowhere else (the ticket's summary block cannot rebuild it). The push is
254
+ * consent-gated with `planIntegratePr`'s shape: already on the remote at HEAD
255
+ * is honoured (`via: "remote"`), `--push` is the recorded yes (`via: "push"`),
256
+ * otherwise it HOLDS (`via: "hold"`) with the push in `holdCommands`.
257
+ *
258
+ * NO REMOTE IS A HOLD, NEVER AN ERROR. A clone with no remote of that name
259
+ * cannot publish, and refusing would accuse a healthy local-only repo; the
260
+ * plan says so (`noRemote`) and the spec stays on its local branch.
261
+ *
262
+ * ctx: { worktreeState: { dirty }, remote, treePath, remoteConfigured,
263
+ * pushedAtHead, push }
264
+ */
265
+ function planIntegrateDocs(spec, config, ctx) {
266
+ const { worktreeState = {}, treePath, remoteConfigured } = ctx || {}
267
+ const remote = (ctx && ctx.remote) || 'origin'
268
+ const branch = spec.branch
269
+ const result = {
270
+ blocked: false, noop: false, reason: null, commands: [],
271
+ push: null, holdCommands: [], noRemote: false,
272
+ afterLand: noAfterLand(), branch, remote,
273
+ }
274
+
275
+ // The verdict's commit ran first, so anything still uncommitted is not this
276
+ // spec's — and a push would publish a branch missing it.
277
+ if (worktreeState.dirty) {
278
+ return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the spec first' }
279
+ }
280
+ if (!remoteConfigured) {
281
+ return { ...result, noRemote: true, push: { kind: 'push', via: 'hold', remote, branch } }
282
+ }
283
+ if (ctx.pushedAtHead) {
284
+ return { ...result, noop: true, push: { kind: 'push', via: 'remote', remote, branch } }
285
+ }
286
+ const pushCommand = `git -C ${shellPath(treePath)} push -u ${remote} ${branch}`
287
+ if (ctx.push) {
288
+ return { ...result, commands: [pushCommand], push: { kind: 'push', via: 'push', remote, branch } }
289
+ }
290
+ return { ...result, push: { kind: 'push', via: 'hold', remote, branch }, holdCommands: [pushCommand] }
291
+ }
292
+
246
293
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
247
294
  // primary checkout, standing on base) once the land commands have succeeded.
248
295
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
@@ -291,4 +338,4 @@ function noAfterLand() {
291
338
  return { cwd: null, commands: [], entries: [], range: null }
292
339
  }
293
340
 
294
- module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }
341
+ module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs, afterLandFor, rangeOf }