@skitterbyte/skitterspec-linear 19.6.0 → 19.8.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/src/cli.js CHANGED
@@ -79,6 +79,7 @@ const {
79
79
  const {
80
80
  primaryAnchor,
81
81
  attachProject,
82
+ projectName,
82
83
  repoRootOf,
83
84
  prefixOf,
84
85
  toRepoPath,
@@ -183,7 +184,8 @@ const {
183
184
  mainGuardStatus,
184
185
  } = require('./env/mainguard.js')
185
186
  const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
186
- const { planIntegrate, planIntegrateCheckout, planIntegratePr } = require('./env/integrate.js')
187
+ const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
188
+ const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
187
189
  const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
188
190
  const { collectDisposition } = require('./env/disposition.js')
189
191
  const { planHandoff } = require('./env/handoff.js')
@@ -198,6 +200,8 @@ const {
198
200
  appendChangelog,
199
201
  waitsMetByRebase,
200
202
  } = require('./env/epic.js')
203
+ const { nextAction, readNextInputs } = require('./env/nextaction.js')
204
+ const { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
201
205
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
202
206
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
203
207
  const { planDev } = require('./env/dev.js')
@@ -278,7 +282,8 @@ Usage:
278
282
  dev down <spec> stop the spec's host dev servers
279
283
  connect <spec> expose a spec on the canonical ports (main = off)
280
284
  integrate <spec> plan the land: rebase + fast-forward, or in PR
281
- mode push + PR (--push, --draft, --strategy)
285
+ mode push + PR (--push, --draft, --strategy);
286
+ --docs: under specDocs "branch", publish only
282
287
  disposition <spec>
283
288
  list unticked tasks, open phases and surfaced
284
289
  follow-ups to dispose before a PR goes ready
@@ -565,7 +570,26 @@ function inFlightStatus(argv) {
565
570
  const dir = anchor.dir
566
571
  const { config, present } = loadEnvConfig(dir)
567
572
  attachProject(config, anchor)
568
- const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
573
+ const rows = (present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []).map((r) =>
574
+ // Only a spec whose own copy was read, and which is still in flight, gets
575
+ // a next action — a finished or unreadable one has nothing true to offer.
576
+ isInFlight(r) && r.found
577
+ ? {
578
+ ...r,
579
+ next: nextAction({
580
+ spec: r.spec,
581
+ ...readNextInputs({
582
+ folder: r.spec,
583
+ bucket: r.bucket,
584
+ worktree: r.worktree,
585
+ outPath: reviewOutPath(dir, r.spec),
586
+ required: config.review.required,
587
+ git: gitReader(r.worktree),
588
+ }),
589
+ }),
590
+ }
591
+ : r,
592
+ )
569
593
  if (json) {
570
594
  const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
571
595
  process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
@@ -586,15 +610,105 @@ function inFlightStatus(argv) {
586
610
  */
587
611
  function epicStatusCommand(argv) {
588
612
  const json = argv.includes('--json')
589
- const epic = epicPositional(argv)
613
+ const named = epicPositional(argv)
614
+ const based = epicInputs(argv, json, named || null)
615
+ if (!based) return
616
+ const here = argv.includes('--here') ? hereTree(based) : null
617
+ if (argv.includes('--here') && !here) {
618
+ process.stdout.write(json ? JSON.stringify({ epic: named || null, cannotTell: 'not in a git checkout' }, null, 2) + '\n' : 'epic: cannot tell — --here needs a git checkout to read\n')
619
+ return
620
+ }
621
+ // --here: members and headers from this tree, uncommitted edits included;
622
+ // a wait is still met only on the base branch.
623
+ const inputs = here
624
+ ? { ...based, ...here.tree, waitIndex: based.index, waitRead: based.readFile }
625
+ : based
626
+ const epic = named || epicFromHere(inputs)
590
627
  if (!epic) {
591
- process.stdout.write('Usage: skitterspec epic status <epic> [--json] [--dir <path>]\n')
628
+ const flying = epicsInFlight(inputs.worktrees)
629
+ const line = flying.length
630
+ ? `name an epic — in flight here: ${flying.join(', ')}`
631
+ : 'name an epic — none has a member in flight here'
632
+ process.stdout.write(
633
+ json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--here] [--json] [--dir <path>]\n${line}\n`,
634
+ )
635
+ return
636
+ }
637
+ const up = inputs.config ? readRunningReviewServer(inputs.dir, inputs.config) : null
638
+ const readers = memberReaders({
639
+ ...inputs,
640
+ git: gitReader,
641
+ // A link only where a server is already serving: this reads the server and
642
+ // never starts one, so a status asked from a phone never restarts the
643
+ // server whose link that phone has open.
644
+ //
645
+ // The NETWORK address where the server is bound wide, so a row read on a
646
+ // phone opens there too; loopback where it is not, or where this machine
647
+ // has no address to offer. A tailnet reader has the epic page, whose member
648
+ // links are relative.
649
+ linkFor: (spec) => memberPageLink(up, offerableLanAddresses(), spec),
650
+ })
651
+ const answer = { ...epicAnswer(epic, inputs, readers), ...(here ? { here: here.label } : {}) }
652
+ const page = epicPageTiers(inputs, up, epic)
653
+ if (json) {
654
+ process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
592
655
  return
593
656
  }
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))
657
+ // No such epic is a plain answer; a page link for it would be a link to nothing.
658
+ const found = answer.found || answer.members.length
659
+ process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
660
+ }
661
+
662
+ // A member's review page as `epic status` prints it: the network URL where the
663
+ // server is bound wide, else loopback; null with nothing serving.
664
+ function memberPageLink(up, addrs, spec) {
665
+ if (!up) return null
666
+ const served = reviewServedUrls(up, addrs, spec)
667
+ return served.url || served.loopbackUrl
668
+ }
669
+
670
+ /**
671
+ * Where the epic page can be read: the same tiers a review render prints, for
672
+ * the epic's own route — or, with no server running, the one command that
673
+ * starts it. Never null where isolation is configured, because the page is the
674
+ * thing a phone reader comes back to (Decision 8).
675
+ */
676
+ function epicPageTiers(inputs, up, epic) {
677
+ if (!inputs.config) return null
678
+ if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
679
+ const served = reviewServedUrls(up, offerableLanAddresses(), epic)
680
+ return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config }) }
681
+ }
682
+
683
+ function epicPageLines(page) {
684
+ if (!page) return ''
685
+ if (page.off) return `epic page: no review server running — start it with: ${page.start}\n`
686
+ return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
687
+ }
688
+
689
+ // The working tree `--here` reads: the project folder of the checkout this
690
+ // command runs in. null when there is no checkout to read.
691
+ function hereTree(inputs) {
692
+ const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
693
+ if (!top) return null
694
+ const root = path.join(path.resolve(top), (inputs.config && prefixOf(inputs.config)) || '')
695
+ return { tree: workingTree(root), label: path.relative(path.dirname(inputs.dir), root) || root }
696
+ }
697
+
698
+ /**
699
+ * The epic a bare `epic status` means: the one whose worktree this command runs
700
+ * in, or the epic named by the member whose worktree it runs in. A positive
701
+ * signal or nothing — standing anywhere else names no epic, and the caller says
702
+ * so rather than picking one.
703
+ */
704
+ function epicFromHere(inputs) {
705
+ const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
706
+ if (!top) return null
707
+ const here = path.resolve(top)
708
+ const own = inputs.worktrees.find((w) => here === path.resolve(w.root) || here.startsWith(path.resolve(w.root) + path.sep))
709
+ if (!own) return null
710
+ if (isEpic(own.folder)) return own.folder
711
+ return epicHeaders(own.overview).epic
598
712
  }
599
713
 
600
714
  /**
@@ -744,52 +858,15 @@ function epicInputs(argv, json, subject) {
744
858
  } catch (err) {
745
859
  return say(err.message)
746
860
  }
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}`])
861
+ const tree = epicTree(git, base)
862
+ if (!tree) return say(`the base branch ${base} could not be read`)
757
863
  const worktrees = present
758
864
  ? provisionedSpecs(dir, config)
759
865
  .filter((p) => !p.specless)
760
866
  .map((p) => worktreeOverview(p.project, p.folder))
761
867
  .filter(Boolean)
762
868
  : []
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
869
+ return { dir, config: present ? config : null, base, ...tree, worktrees, branches: specBranchDocs(git, config, base) }
793
870
  }
794
871
 
795
872
  // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -902,14 +979,28 @@ function untouchedLines(plan) {
902
979
  * yet is not broken, and a check that stopped someone's work over a missing
903
980
  * header would be a worse failure than the omission it names.
904
981
  */
982
+ // Specs that live only on their own branch, for the checks that read the
983
+ // backlog. Every cannot-tell — no git, an unresolvable base — is an empty list,
984
+ // which leaves the disk scan exactly as it was.
985
+ function branchSpecDocs(dir) {
986
+ try {
987
+ const { config } = loadEnvConfig(dir)
988
+ const git = gitReader(dir)
989
+ return specBranchDocs(git, config, resolveBaseBranch(config, git))
990
+ } catch {
991
+ return []
992
+ }
993
+ }
994
+
905
995
  function gatingCheck(dir, argv) {
906
996
  const { opts, positional } = parse(argv)
907
- const { checkGating, activeSpecs } = require('./gating.js')
997
+ const { checkGating, activeSpecs, ACTIVE_BUCKETS } = require('./gating.js')
998
+ const branches = branchSpecDocs(dir).filter((b) => ACTIVE_BUCKETS.includes(b.bucket))
908
999
 
909
1000
  let specs = null
910
1001
  if (positional.length && !opts.all) {
911
1002
  const name = path.basename(positional[0])
912
- const found = activeSpecs(dir).filter((s) => s.folder === name)
1003
+ const found = preferBranches(activeSpecs(dir), branches).filter((s) => s.folder === name)
913
1004
  if (!found.length) {
914
1005
  // Not an accusation: a name that matches no ACTIVE spec is usually a
915
1006
  // finished one, which gating never covers anyway.
@@ -919,7 +1010,7 @@ function gatingCheck(dir, argv) {
919
1010
  specs = found
920
1011
  }
921
1012
 
922
- const result = checkGating(dir, specs)
1013
+ const result = checkGating(dir, specs, { branches })
923
1014
 
924
1015
  if (opts.json) {
925
1016
  process.stdout.write(JSON.stringify(result, null, 2) + '\n')
@@ -939,8 +1030,8 @@ function gatingCheck(dir, argv) {
939
1030
  for (const f of result.findings) {
940
1031
  lines.push(
941
1032
  f.kind === 'missing'
942
- ? ` ${f.folder} (${f.bucket}): no Gating: header`
943
- : ` ${f.folder} (${f.bucket}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
1033
+ ? ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): no Gating: header`
1034
+ : ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
944
1035
  )
945
1036
  }
946
1037
  lines.push('')
@@ -2054,6 +2145,16 @@ function specEnvDown(dir, config, specArg, flags) {
2054
2145
  prAbandon = prAbandonCommand(info, { branch: spec.branch, id: pr.id })
2055
2146
  }
2056
2147
  }
2148
+ // Under the docs lane, a branch whose whole range is this spec's own
2149
+ // documents (its folder, its companions) is a never-started spec: the
2150
+ // planner may offer its remote delete. Asked only in that lane, and an
2151
+ // unreadable or empty range is not docs-only — it stays false.
2152
+ if (config.land && config.land.specDocs === 'branch' && !worktreeState.merged) {
2153
+ const range = landRange(gitReader(dir), base, spec.branch)
2154
+ if (Array.isArray(range) && range.length) {
2155
+ worktreeState = { ...worktreeState, docsOnly: classifyDirtyTree(spec, range, config).foreign.length === 0 }
2156
+ }
2157
+ }
2057
2158
  const plan = planDown(spec, config, flags, {
2058
2159
  worktreeState,
2059
2160
  prAbandonCommand: prAbandon,
@@ -2426,6 +2527,15 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2426
2527
  // entirely on its branch may not exist in the primary checkout's specs/** —
2427
2528
  // resolveSpecWithWorktree offers its worktree as a fallback search location.
2428
2529
  const spec = resolveSpecWithWorktree(dir, config, specArg)
2530
+ // `--docs` is /spec's authoring land. Under the "branch" lane the document
2531
+ // rides its own branch, so there is nothing to land — only a branch to
2532
+ // publish. Under "trunk" it falls through to the ordinary land unchanged.
2533
+ // Keyed on the FLAG, never on `specDocs` alone: /spec-complete lands CODE
2534
+ // through this same verb, and that land must not turn into a push.
2535
+ if (flags.docs === true && config.land && config.land.specDocs === 'branch') {
2536
+ specEnvIntegrateDocs(dir, config, spec, flags)
2537
+ return
2538
+ }
2429
2539
  // Fetch before resolving under a rolling base, so a spec that outlived a
2430
2540
  // release roll lands on the rc that exists now rather than the one the last
2431
2541
  // fetch saw. No pattern → no fetch, and the plan below is unchanged.
@@ -2811,6 +2921,55 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
2811
2921
  process.stdout.write(out.join('\n') + '\n')
2812
2922
  }
2813
2923
 
2924
+ // The authoring land under `land.specDocs: "branch"`: publish the spec's branch,
2925
+ // consent-gated, and touch nothing else. /spec runs what is printed.
2926
+ function specEnvIntegrateDocs(dir, config, spec, flags) {
2927
+ const checkout = config.mode === 'checkout'
2928
+ const treePath = checkout ? dir : spec.worktreePath
2929
+ if (!checkout && !fs.existsSync(spec.worktreePath)) {
2930
+ process.stdout.write(`spec-env integrate: ${spec.folder} has no worktree — nothing to publish.\n`)
2931
+ return
2932
+ }
2933
+ const remote = (config.land && config.land.remote) || 'origin'
2934
+ const git = gitReader(treePath)
2935
+ const status = git(['status', '--porcelain'])
2936
+ const remoteConfigured = git(['remote', 'get-url', remote]) !== null
2937
+ const headSha = git(['rev-parse', 'HEAD'])
2938
+ const lsRemote = remoteConfigured ? git(['ls-remote', remote, `refs/heads/${spec.branch}`]) : null
2939
+ const plan = planIntegrateDocs(spec, config, {
2940
+ worktreeState: { dirty: status !== null && status.length > 0 },
2941
+ remote,
2942
+ treePath,
2943
+ remoteConfigured,
2944
+ pushedAtHead: Boolean(headSha && lsRemote && lsRemote.split(/\s/)[0] === headSha),
2945
+ push: flags.push === true,
2946
+ })
2947
+
2948
+ if (plan.blocked) {
2949
+ process.stdout.write(`spec-env integrate: blocked — ${plan.reason}.\n`)
2950
+ return
2951
+ }
2952
+ const out = [`spec-env integrate: ${spec.folder} (spec docs ride the branch)`, '']
2953
+ out.push(' lane: branch — land.specDocs; the base branch is not touched')
2954
+ out.push(` branch: ${plan.branch}`)
2955
+ out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
2956
+ if (plan.noRemote) {
2957
+ out.push(` remote: no "${remote}" configured — the branch stays local`)
2958
+ } else if (plan.push.via === 'remote') {
2959
+ out.push(` pushed: already on ${remote} at HEAD — nothing to run`)
2960
+ } else if (plan.push.via === 'push') {
2961
+ out.push('')
2962
+ out.push(' run these:')
2963
+ for (const cmd of plan.commands) out.push(` ${cmd}`)
2964
+ } else {
2965
+ out.push('')
2966
+ out.push(' then, to publish the branch — with your consent')
2967
+ out.push(' (or re-run with --push to plan it as one list):')
2968
+ for (const cmd of plan.holdCommands) out.push(` ${cmd}`)
2969
+ }
2970
+ process.stdout.write(out.join('\n') + '\n')
2971
+ }
2972
+
2814
2973
  // `spec-env disposition [<spec>] [--json]` — enumerate the loose ends a
2815
2974
  // completion must dispose before a PR goes ready: unticked tasks, phase-index
2816
2975
  // rows not ✅, surfaced follow-ups. Information only — it never refuses and
@@ -5362,6 +5521,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5362
5521
  notes,
5363
5522
  gate,
5364
5523
  buttons,
5524
+ project: projectName(config),
5365
5525
  ...surfaceArgs,
5366
5526
  ...(docs ? { only: docs.owned, treePath: docs.tree } : {}),
5367
5527
  })
@@ -5404,6 +5564,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5404
5564
  notes,
5405
5565
  gate,
5406
5566
  buttons,
5567
+ project: projectName(config),
5407
5568
  ...surfaceArgs,
5408
5569
  fellBack: true,
5409
5570
  })
@@ -5753,9 +5914,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5753
5914
  // The reason there is no served URL, when there is none. A `file://` link
5754
5915
  // with nothing said about it reads as the ordinary outcome, and it is not.
5755
5916
  (!served && noServeBecause ? ` not served: ${noServeBecause}\n` : '') +
5756
- (served && served.loopback && config.review.allowNetwork
5757
- ? ` network permitted but the running server is loopback-bound — ${served.widen}\n`
5758
- : '') +
5759
5917
  (served && served.started && !served.loopback
5760
5918
  ? ' serving: every provisioned spec, to anyone with a URL on your network.\n' +
5761
5919
  ' stop: skitterspec spec-env review serve --stop\n'
@@ -7473,5 +7631,6 @@ module.exports = {
7473
7631
  serverScriptOk,
7474
7632
  daemonScript,
7475
7633
  reviewServedUrls,
7634
+ memberPageLink,
7476
7635
  restartHost,
7477
7636
  }
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')
@@ -230,9 +230,11 @@ const DEFAULT_CONFIG = Object.freeze({
230
230
  // follows the merge. `remote` names where the branch is pushed. `draft`
231
231
  // opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
232
232
  // 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.
233
+ // DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
234
+ // docs under "pr"), "branch" has the spec ride its feature branch and land
235
+ // with the work. The "trunk" here is only the base's default — with a
236
+ // ticketing provider configured and the key unset, `applyProviderSpecDocs`
237
+ // makes it "branch", whatever the strategy.
236
238
  land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
237
239
  // `mainIsLandingZone` defaults ON wherever isolation is configured, matching
238
240
  // the review gate's precedent: the push toward not working on the base branch
@@ -307,6 +309,10 @@ const DEFAULT_CONFIG = Object.freeze({
307
309
  allowRemote: false,
308
310
  commitWith: '/commit',
309
311
  required: true,
312
+ // The name every generated page carries in its tab and above its heading.
313
+ // Empty means "the project folder's name" (`projectName` in project.js) —
314
+ // the override exists for a checkout named `app` or `repo`.
315
+ projectName: '',
310
316
  // External code reviewers whose findings render as CHECKS on the page.
311
317
  // Empty by default and never written by `init`: configuring one sends the
312
318
  // worktree's diff to whatever the command talks to, which is a decision
@@ -772,6 +778,8 @@ function mergeConfig(base, parsed) {
772
778
  // here. There is nothing it could mean instead: the hand-off has no off
773
779
  // switch, so a blank value is a typo rather than an instruction.
774
780
  assign(base.review, parsed.review, 'commitWith', 'string')
781
+ // A blank name falls back to the folder's, like `commitWith` above.
782
+ assign(base.review, parsed.review, 'projectName', 'string')
775
783
  // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
776
784
  // leaves the gate ON. Turning off a check that refuses must be something
777
785
  // someone WROTE, never something a typo achieved on their behalf.
@@ -873,6 +881,33 @@ function applyProviderEnvDefaults(config, parsed) {
873
881
  return config
874
882
  }
875
883
 
884
+ // The provider's own config file, relative to the project root — set once per
885
+ // process by a provider superset's bin, like the defaults above. A registered
886
+ // file that EXISTS is the positive signal that a ticketing provider is attached
887
+ // to this project, and only then does `land.specDocs` default to "branch": the
888
+ // tracker is the backlog, so landing a spec document on the base branch just to
889
+ // make it findable buys nothing (feat-tracker-spec-branches).
890
+ //
891
+ // WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
892
+ // has no config file, and reads as no provider — which is the safe reading,
893
+ // since "trunk" is today's behaviour. An unregistered base distribution never
894
+ // asks at all.
895
+ let providerConfigFile = null
896
+ function setProviderConfigFile(rel) {
897
+ providerConfigFile = rel || null
898
+ }
899
+
900
+ // An explicit `specDocs` in the file — any value, even one the merge rejected —
901
+ // is the project's decision; a rejected typo stays on the conservative "trunk"
902
+ // rather than being promoted to the provider default.
903
+ function applyProviderSpecDocs(config, parsed, dir) {
904
+ if (!providerConfigFile) return config
905
+ const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
906
+ if (pLand && 'specDocs' in pLand) return config
907
+ if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
908
+ return config
909
+ }
910
+
876
911
  function loadEnvConfig(dir = process.cwd()) {
877
912
  const base = defaults()
878
913
  const file = join(dir, CONFIG_FILE)
@@ -882,7 +917,12 @@ function loadEnvConfig(dir = process.cwd()) {
882
917
  raw = readFileSync(file, 'utf-8')
883
918
  } catch (error) {
884
919
  if (error.code === 'ENOENT') {
885
- return { config: applyProviderEnvDefaults(base, null), present: false, unknown: [], badReviewers: [] }
920
+ return {
921
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
922
+ present: false,
923
+ unknown: [],
924
+ badReviewers: [],
925
+ }
886
926
  }
887
927
  throw error
888
928
  }
@@ -895,7 +935,7 @@ function loadEnvConfig(dir = process.cwd()) {
895
935
  }
896
936
 
897
937
  return {
898
- config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
938
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
899
939
  present: true,
900
940
  unknown: collectUnknownKeys(parsed),
901
941
  badReviewers: collectBadReviewers(parsed),
@@ -905,6 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
905
945
  module.exports = {
906
946
  loadEnvConfig,
907
947
  setProviderEnvDefaults,
948
+ setProviderConfigFile,
908
949
  resolveServePort,
909
950
  derivedServePort,
910
951
  servePortRoot,
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
 
@@ -291,12 +292,21 @@ function layer(members) {
291
292
  * - `index` `indexSpecTree` of the base branch
292
293
  * - `readFile` base-branch path → text, or null
293
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
294
298
  * - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
295
299
  * each provisioned spec's own copy, which is where an
296
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.
297
306
  */
298
- function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
307
+ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
299
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]))
300
310
  const members = new Map()
301
311
 
302
312
  for (const file of candidates) {
@@ -311,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
311
321
  members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
312
322
  }
313
323
  // A member authored on its own branch and not landed yet is invisible on the
314
- // base branch; its worktree copy is what knows it belongs here.
315
- for (const w of worktrees) {
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]) {
316
328
  const h = epicHeaders(w.overview)
317
329
  // The worktree's copy is the newer word on a spec being built: it may have
318
330
  // joined, changed its waits, or moved to another epic.
@@ -326,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
326
338
  const base = index.get(m.spec)
327
339
  // In flight is the positive signal of a worktree whose own copy has not
328
340
  // finished; otherwise the base branch's bucket.
329
- m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : base ? base.bucket : wt ? wt.bucket : null
330
- m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, index, readFile) }))
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) }))
331
344
  // A phase's own `Waits on:` holds that phase, not the spec's start: the
332
345
  // sync point the field example turned on (#154 phase 2 on #159 phase 1).
333
346
  // A phase already done has nothing left to wait for.
334
347
  m.phaseWaits = m.phases
335
348
  .filter((p) => p.text !== null && !phaseIsDone(p.text))
336
349
  .flatMap((p) =>
337
- 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) } })),
338
351
  )
339
352
  }
340
353
 
@@ -379,9 +392,6 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
379
392
  }
380
393
  }
381
394
 
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
395
  // `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
386
396
  function syncLine({ spec, phase, wait }) {
387
397
  const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
@@ -389,28 +399,47 @@ function syncLine({ spec, phase, wait }) {
389
399
  return `${who} after ${wait.raw} (${mark} — ${wait.why})`
390
400
  }
391
401
 
402
+ // Columns padded to their widest cell. Plain text, never a markdown table: the
403
+ // answer is read raw under `watch` as often as it is rendered (spec
404
+ // feat-epic-next, Decision 3), and a pipe table read raw is noise.
405
+ function aligned(lines, indent = ' ') {
406
+ const widths = lines[0].map((_, i) => Math.max(...lines.map((l) => l[i].length)))
407
+ return lines.map((l) => (indent + l.map((c, i) => (i === l.length - 1 ? c : c.padEnd(widths[i]))).join(' ')).trimEnd())
408
+ }
409
+
392
410
  /**
393
- * The human answer, in the report-block shape: one sentence, then a table of
394
- * only the rows that have something in them.
411
+ * The human answer: a headline, one row per member saying what to run and in
412
+ * which tab, then the plan's shape — waves, sync points, clashes — wherever
413
+ * there is something to say. `s.rows` comes from `epicRows`; a status without
414
+ * them is rendered with nothing read off disk, so an in-flight member says it
415
+ * cannot tell rather than guessing.
395
416
  */
396
417
  function formatEpicStatus(s) {
397
- if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
418
+ if (!s.found && !s.members.length) {
419
+ return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
420
+ }
398
421
  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(' · ')],
422
+ const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
423
+ const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${where}`
424
+ const out = [head, '']
425
+ if (!s.members.length) {
426
+ out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
427
+ } else {
428
+ const { rows, next } = s.rows ? { rows: s.rows, next: s.next } : epicRows(s)
429
+ const state = (r) => (r.bucket === 'in-progress' ? r.next.state : r.next.state || r.bucket || 'unknown')
430
+ out.push(
431
+ ...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
432
+ )
433
+ if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
434
+ }
435
+ const shape = [
436
+ ['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
437
+ ['sync points', s.syncPoints.map(syncLine).join(' · ')],
438
+ ['never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
439
+ ['cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
411
440
  ].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`
441
+ if (shape.length) out.push('', ...aligned(shape))
442
+ return out.join('\n') + '\n'
414
443
  }
415
444
 
416
445
  /**