@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/cli.js CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  const fs = require('fs')
4
4
  const path = require('path')
5
+ const os = require('os')
6
+ const { pathToFileURL } = require('url')
5
7
  const { execFileSync } = require('child_process')
6
8
  const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
7
9
  const {
@@ -79,6 +81,9 @@ const {
79
81
  const {
80
82
  primaryAnchor,
81
83
  attachProject,
84
+ projectName,
85
+ projectCategory,
86
+ describeProject,
82
87
  repoRootOf,
83
88
  prefixOf,
84
89
  toRepoPath,
@@ -183,7 +188,8 @@ const {
183
188
  mainGuardStatus,
184
189
  } = require('./env/mainguard.js')
185
190
  const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
186
- const { planIntegrate, planIntegrateCheckout, planIntegratePr } = require('./env/integrate.js')
191
+ const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
192
+ const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
187
193
  const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
188
194
  const { collectDisposition } = require('./env/disposition.js')
189
195
  const { planHandoff } = require('./env/handoff.js')
@@ -198,11 +204,19 @@ const {
198
204
  appendChangelog,
199
205
  waitsMetByRebase,
200
206
  } = require('./env/epic.js')
201
- const { nextAction, readNextInputs } = require('./env/nextaction.js')
202
- const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
207
+ const { nextAction, readNextInputs, actionText } = require('./env/nextaction.js')
208
+ const { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
203
209
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
204
210
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
205
211
  const { planDev } = require('./env/dev.js')
212
+ const { windowFor, windowLabel, humanLabel, localDay } = require('./tada/window.js')
213
+ const { ROUTE: TADA_ROUTE, tadaQuery, recapKey: tadaRecapKey, recapPath: tadaRecapPath } = require('./tada/serve.js')
214
+ const { defaultRoot, knownDirs } = require('./tada/transcripts.js')
215
+ const { setProjectKeys } = require('./env/projectedit.js')
216
+ const { buildDigest, gitRepoOf } = require('./tada/digest.js')
217
+ const { readRepoFacts } = require('./tada/repo.js')
218
+ const { formatTada } = require('./tada/format.js')
219
+ const { renderTadaPage } = require('./tada/page.js')
206
220
  const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
207
221
  const {
208
222
  renderRoutes,
@@ -280,7 +294,8 @@ Usage:
280
294
  dev down <spec> stop the spec's host dev servers
281
295
  connect <spec> expose a spec on the canonical ports (main = off)
282
296
  integrate <spec> plan the land: rebase + fast-forward, or in PR
283
- mode push + PR (--push, --draft, --strategy)
297
+ mode push + PR (--push, --draft, --strategy);
298
+ --docs: under specDocs "branch", publish only
284
299
  disposition <spec>
285
300
  list unticked tasks, open phases and surfaced
286
301
  follow-ups to dispose before a PR goes ready
@@ -323,6 +338,24 @@ Usage:
323
338
  skitterspec epic bypass <spec> [--phase N]
324
339
  Build past an unmet wait, recorded as a dated
325
340
  line in the member's Changelog.
341
+ skitterspec project This project's name and category, and where each
342
+ comes from. --name <n> / --category <c> set them
343
+ in specs/.core/env.config.json ("" clears),
344
+ editing only those keys; --categories lists the
345
+ categories your other projects use (--json).
346
+ skitterspec tada What you did in Claude Code: the window's sessions,
347
+ commits and spec moves across every project,
348
+ folded into each repo and grouped by spec.
349
+ --since <when> (to now) or --on <when> (that day):
350
+ today, yesterday, last friday, 3 days ago, 2w,
351
+ 2026-11-06 or 6 Nov. Scoped to projects sharing
352
+ this one's project.category (--all-projects for
353
+ every project). Prompts on branches with no spec
354
+ are left out unless they led to one (--chat keeps
355
+ them). --here for this repo only,
356
+ --json, --page [--summary <recap.md>] for an HTML
357
+ page. Reads ~/.claude/projects; exits 0 unless the
358
+ window cannot be read.
326
359
  skitterspec gating <cmd> Release-gating check (opt-in; needs
327
360
  specs/.core/gating.config.json). Subcommands:
328
361
  check [spec] report specs with no recorded gating
@@ -345,6 +378,8 @@ Options (init / update):
345
378
  --yes, -y Accept defaults; skip the interactive setup prompts
346
379
  --isolation / --no-isolation Enable/skip per-spec isolation (a git
347
380
  worktree per spec; writes env.config.json)
381
+ --name <name> / --category <c> (init --isolation) Write project.name /
382
+ project.category into env.config.json
348
383
  --remove-release-tooling (update) Remove leftover release tooling
349
384
  non-interactively (moved to skittership)
350
385
 
@@ -386,7 +421,11 @@ function parse(argv) {
386
421
  else if (a === '--diff') opts.diff = true
387
422
  else if (a === '--check') opts.check = true
388
423
  else if (a === '--dir') opts.dir = argv[++i]
389
- else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
424
+ else if (a === '--name' || a === '--category') {
425
+ const v = argv[++i]
426
+ if (v === undefined) throw new Error(`${a} needs a value`)
427
+ opts.project = { ...opts.project, [a.slice(2)]: v }
428
+ } else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
390
429
  else positional.push(a)
391
430
  }
392
431
  return { opts, positional }
@@ -563,6 +602,25 @@ function inFlightStatus(argv) {
563
602
  const json = argv.includes('--json')
564
603
  const at = argv.indexOf('--dir')
565
604
  const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
605
+ const { anchor, present, rows } = inFlightRows(from)
606
+ if (json) {
607
+ const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
608
+ process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
609
+ return
610
+ }
611
+ if (!present) {
612
+ process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
613
+ return
614
+ }
615
+ process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir: anchor.dir }))
616
+ }
617
+
618
+ /**
619
+ * The rows behind `skitterspec status`, read from `from`'s repo — shared with
620
+ * `skitterspec tada`, whose open items are exactly these, so the two can never
621
+ * disagree about what is in flight.
622
+ */
623
+ function inFlightRows(from) {
566
624
  const anchor = primaryAnchor(from, gitReader(from))
567
625
  const dir = anchor.dir
568
626
  const { config, present } = loadEnvConfig(dir)
@@ -587,18 +645,283 @@ function inFlightStatus(argv) {
587
645
  }
588
646
  : r,
589
647
  )
648
+ return { anchor, present, rows }
649
+ }
650
+
651
+ /**
652
+ * `skitterspec project` — what this project is called and which category it is
653
+ * in, and the one way to set them. It writes the checkout it runs in (in a
654
+ * worktree, that is the branch), and leaves committing to the caller.
655
+ *
656
+ * NO env.config.json, NO WRITE. That file's presence is what turns isolation
657
+ * on, so creating it to hold a category would change how every skill behaves
658
+ * as a side effect of naming a project.
659
+ */
660
+ function projectCommand(argv) {
661
+ const json = argv.includes('--json')
662
+ if (argv.includes('--categories')) return projectCategories(json)
663
+
664
+ const cwd = process.cwd()
665
+ const anchor = primaryAnchor(cwd, gitReader(cwd))
666
+ const top = gitReader(cwd)(['rev-parse', '--show-toplevel'])
667
+ // THE TREE YOU ARE STANDING IN, never the primary checkout: a worktree's
668
+ // config is the branch's, and that is where the change is meant to land.
669
+ const dir = top ? projectIn(path.resolve(top), anchor.prefix) : cwd
670
+ const file = path.join(dir, 'specs', '.core', 'env.config.json')
671
+ const refuse = (why) => {
672
+ process.stderr.write(`skitterspec project: ${why}\n`)
673
+ process.exitCode = 1
674
+ }
675
+
676
+ const changes = {}
677
+ for (const k of ['name', 'category']) {
678
+ const at = argv.indexOf(`--${k}`)
679
+ if (at === -1) continue
680
+ const v = argv[at + 1]
681
+ if (v === undefined || (v.startsWith('--') && v !== '')) return refuse(`--${k} needs a value ("" clears it)`)
682
+ changes[k] = v.trim()
683
+ }
684
+
685
+ if (!fs.existsSync(file)) {
686
+ if (Object.keys(changes).length) {
687
+ return refuse(
688
+ `no specs/.core/env.config.json here — it is what turns isolation on, so it is not created just to hold a ` +
689
+ `${Object.keys(changes).join(' and ')}. Adopt isolation first: skitterspec init --isolation`,
690
+ )
691
+ }
692
+ } else if (Object.keys(changes).length) {
693
+ let edited
694
+ try {
695
+ edited = setProjectKeys(fs.readFileSync(file, 'utf8'), changes)
696
+ } catch (e) {
697
+ return refuse(`${path.relative(cwd, file) || file}: ${e.message}`)
698
+ }
699
+ fs.writeFileSync(file, edited)
700
+ }
701
+
702
+ let config = {}
703
+ try {
704
+ config = loadEnvConfig(dir).config
705
+ } catch (e) {
706
+ return refuse(e.message)
707
+ }
708
+ attachProject(config, anchor)
709
+ const d = describeProject(config)
710
+ const wrote = Object.keys(changes)
590
711
  if (json) {
591
- const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
592
- process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
712
+ process.stdout.write(JSON.stringify({ dir, file: fs.existsSync(file) ? file : null, ...d, wrote }, null, 2) + '\n')
593
713
  return
594
714
  }
595
- if (!present) {
596
- process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
715
+ const line = (label, x) => ` ${label.padEnd(9)} ${x.value === null ? '—' : x.value} (${x.source})`
716
+ const out = [`project: ${dir}`, line('name:', d.name), line('category:', d.category)]
717
+ if (wrote.length) out.push('', `set ${wrote.join(' and ')} in specs/.core/env.config.json — commit it to keep it`)
718
+ else if (!fs.existsSync(file)) out.push('', 'no specs/.core/env.config.json — these are the defaults')
719
+ process.stdout.write(out.join('\n') + '\n')
720
+ }
721
+
722
+ // The categories the projects you work in already carry — so a new one picks
723
+ // `work` rather than inventing `Work stuff` and splitting a report in two.
724
+ // Projects are the repos your Claude Code sessions ran in; each is asked for
725
+ // its own config.
726
+ function projectCategories(json) {
727
+ const repos = new Set()
728
+ for (const d of knownDirs(defaultRoot())) {
729
+ const r = gitRepoOf(d)
730
+ if (r.repo) repos.add(r.repo)
731
+ }
732
+ const byCategory = new Map()
733
+ const none = []
734
+ for (const repo of [...repos].sort()) {
735
+ let category = null
736
+ let name = path.basename(repo)
737
+ try {
738
+ const { config } = loadEnvConfig(repo)
739
+ category = projectCategory(config)
740
+ name = (config.project && config.project.name && config.project.name.trim()) || name
741
+ } catch {
742
+ // An unreadable config is that repo's to fix; it simply has no answer.
743
+ }
744
+ if (!category) {
745
+ none.push(name)
746
+ continue
747
+ }
748
+ const key = category.toLowerCase()
749
+ if (!byCategory.has(key)) byCategory.set(key, { spellings: new Map(), projects: [] })
750
+ const row = byCategory.get(key)
751
+ row.spellings.set(category, (row.spellings.get(category) || 0) + 1)
752
+ row.projects.push(name)
753
+ }
754
+ // One category, however it was capitalised — shown as most projects spell
755
+ // it, the tie broken alphabetically so the answer does not depend on which
756
+ // repo happened to be read first.
757
+ const rows = [...byCategory.values()]
758
+ .map(({ spellings, projects }) => ({
759
+ category: [...spellings].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0][0],
760
+ projects,
761
+ }))
762
+ .sort((a, b) => b.projects.length - a.projects.length || a.category.localeCompare(b.category))
763
+ if (json) {
764
+ process.stdout.write(JSON.stringify({ categories: rows, uncategorised: none }, null, 2) + '\n')
597
765
  return
598
766
  }
599
- process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
767
+ const width = Math.max(8, ...rows.map((r) => r.category.length))
768
+ const out = rows.length ? ['categories in use:', ...rows.map((r) => ` ${r.category.padEnd(width)} ${r.projects.length} ${r.projects.join(', ')}`)] : ['no project has a category yet']
769
+ if (none.length) out.push(`uncategorised: ${none.join(', ')}`)
770
+ process.stdout.write(out.join('\n') + '\n')
600
771
  }
601
772
 
773
+ /**
774
+ * `skitterspec tada` — the ta-da list's digest: what was done in the window,
775
+ * across every project, folded into repos and grouped by branch. Advisory and
776
+ * read-only: always exits 0, a quiet day included — an empty answer is not a
777
+ * finding. Only a `--since` it cannot read refuses, because a window guessed
778
+ * from a typo would report the wrong day with total confidence.
779
+ */
780
+ async function tadaCommand(argv) {
781
+ const json = argv.includes('--json')
782
+ let window
783
+ try {
784
+ window = windowFor({ since: tadaFlag(argv, '--since'), on: tadaFlag(argv, '--on') })
785
+ } catch (e) {
786
+ process.stderr.write(`skitterspec tada: ${e.message}\n`)
787
+ process.exitCode = 1
788
+ return
789
+ }
790
+ const flags = {
791
+ on: tadaFlag(argv, '--on') ? localDay(window.since) : null,
792
+ since: tadaFlag(argv, '--since') ? localDay(window.since) : null,
793
+ all: argv.includes('--all-projects'),
794
+ chat: argv.includes('--chat'),
795
+ here: argv.includes('--here'),
796
+ }
797
+ let recap = null
798
+ if (argv.includes('--page')) {
799
+ // The recap is the model's, handed over as a file.
800
+ const from = tadaFlag(argv, '--summary')
801
+ if (from) {
802
+ try {
803
+ recap = fs.readFileSync(path.resolve(from), 'utf8')
804
+ } catch (e) {
805
+ process.stderr.write(`skitterspec tada: --summary ${from}: ${e.code || e.message}\n`)
806
+ process.exitCode = 1
807
+ return
808
+ }
809
+ }
810
+ // Served where the review server can serve it: the page is drawn per
811
+ // request there, so only the recap is kept. It prints the links and
812
+ // nothing else, because the digest it carries was already read once.
813
+ if (await serveTadaPage({ window, flags, recap })) return
814
+ }
815
+ const digest = await buildDigest({
816
+ root: defaultRoot(),
817
+ window,
818
+ here: flags.here ? process.cwd() : null,
819
+ category: flags.all ? null : runningCategory(process.cwd()),
820
+ chat: flags.chat,
821
+ facts: (repo) => {
822
+ let config = {}
823
+ try {
824
+ config = loadEnvConfig(repo).config
825
+ } catch {
826
+ // An unreadable config is the repo's to fix, not this report's — the
827
+ // defaults still read its commits; only a custom branch.pattern is lost.
828
+ }
829
+ return readRepoFacts({ repo, git: gitReader(repo), config, window })
830
+ },
831
+ openFor: (repo) => {
832
+ try {
833
+ return inFlightRows(repo)
834
+ .rows.filter(isInFlight)
835
+ .map((r) => ({ spec: r.spec, detail: detailOf(r), next: r.next ? actionText(r.next) : null }))
836
+ } catch {
837
+ return []
838
+ }
839
+ },
840
+ })
841
+ // The reader's own dates, for the text header and the page; the digest's
842
+ // own `since`/`until` stay UTC instants for a script.
843
+ digest.window.label = humanLabel(window)
844
+ if (argv.includes('--page')) {
845
+ // No server to serve it: the page is a file on this machine, as it was.
846
+ const out = path.join(os.tmpdir(), `skitterspec-tada-${windowLabel(window).replace(' → ', '_')}.html`)
847
+ fs.writeFileSync(out, renderTadaPage(digest, { recap, title: `Ta-da · ${digest.window.label}`, category: digest.category || null }))
848
+ process.stdout.write(`page: ${pathToFileURL(out).href}\n`)
849
+ return
850
+ }
851
+ if (json) {
852
+ process.stdout.write(JSON.stringify(digest, null, 2) + '\n')
853
+ return
854
+ }
855
+ process.stdout.write(formatTada(digest))
856
+ }
857
+
858
+ /**
859
+ * `--page` through the review server: save the recap where the server reads
860
+ * it, make sure the server is up, and print every tier for the window's
861
+ * address — the stack a review render prints, for the `_tada` route.
862
+ *
863
+ * Returns false — fall back to the file — where there is nothing to serve
864
+ * from: no isolation here, `review.serve: "never"`, or a server that could not
865
+ * start. Each of those is the project's or the machine's state, not a failure
866
+ * of the page, so the file is still written and nothing exits non-zero.
867
+ */
868
+ async function serveTadaPage({ window, flags, recap }) {
869
+ const cwd = process.cwd()
870
+ const anchor = primaryAnchor(cwd, gitReader(cwd))
871
+ let loaded
872
+ try {
873
+ loaded = loadEnvConfig(anchor.dir)
874
+ } catch {
875
+ return false
876
+ }
877
+ const { config, present } = loaded
878
+ if (!present || config.review.serve === 'never') return false
879
+ attachProject(config, anchor)
880
+ const dir = anchor.dir
881
+ const ask = { on: flags.on, since: flags.since, window, all: flags.all, chat: flags.chat }
882
+ if (recap !== null) {
883
+ const file = tadaRecapPath(path.join(dir, stateDirLabel(config)), tadaRecapKey(ask))
884
+ fs.mkdirSync(path.dirname(file), { recursive: true })
885
+ fs.writeFileSync(file, recap)
886
+ }
887
+ const up = await ensureReviewServer(dir, config, { host: config.review.allowNetwork ? '0.0.0.0' : '127.0.0.1' })
888
+ if (up.error) return false
889
+ const served = reviewServedUrls(up, offerableLanAddresses(), TADA_ROUTE)
890
+ // The window rides in the query, as absolute days, so the link means the
891
+ // same page tomorrow as it does now.
892
+ const q = tadaQuery({ ...flags, on: flags.on || (flags.since ? null : localDay(window.since)) })
893
+ const withQ = (u) => (u ? `${u}${q}` : u)
894
+ const page = { ...served, loopbackUrl: withQ(served.loopbackUrl), url: withQ(served.url), alternates: (served.alternates || []).map(withQ) }
895
+ const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config })
896
+ process.stdout.write(`page: ${humanLabel(window)}\n${tiers.map(reviewTierLine).join('\n')}\n`)
897
+ return true
898
+ }
899
+
900
+ // The category of the project a report is run from — its scope. Null (report
901
+ // everything) outside a repo, in a repo with no category, or with a config that
902
+ // cannot be read: an unreadable config narrowing the report to nothing would
903
+ // be the confident wrong answer.
904
+ function runningCategory(cwd) {
905
+ const r = gitRepoOf(cwd)
906
+ if (!r.repo) return null
907
+ try {
908
+ return projectCategory(loadEnvConfig(r.repo).config)
909
+ } catch {
910
+ return null
911
+ }
912
+ }
913
+
914
+ // A flag's value, which may be several words — `--since last friday`,
915
+ // `--on 6 Nov` — running to the next flag. Quoting it works too.
916
+ function tadaFlag(argv, name) {
917
+ const at = argv.indexOf(name)
918
+ if (at === -1) return undefined
919
+ const words = []
920
+ for (let i = at + 1; i < argv.length && !argv[i].startsWith('--'); i++) words.push(argv[i])
921
+ return words.length ? words.join(' ') : undefined
922
+ }
923
+
924
+
602
925
  /**
603
926
  * `skitterspec epic status <epic>` — the members' own headers turned into an
604
927
  * order. Waits are read off the BASE BRANCH by git, never off whatever the
@@ -608,8 +931,18 @@ function inFlightStatus(argv) {
608
931
  function epicStatusCommand(argv) {
609
932
  const json = argv.includes('--json')
610
933
  const named = epicPositional(argv)
611
- const inputs = epicInputs(argv, json, named || null)
612
- if (!inputs) return
934
+ const based = epicInputs(argv, json, named || null)
935
+ if (!based) return
936
+ const here = argv.includes('--here') ? hereTree(based) : null
937
+ if (argv.includes('--here') && !here) {
938
+ 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')
939
+ return
940
+ }
941
+ // --here: members and headers from this tree, uncommitted edits included;
942
+ // a wait is still met only on the base branch.
943
+ const inputs = here
944
+ ? { ...based, ...here.tree, waitIndex: based.index, waitRead: based.readFile }
945
+ : based
613
946
  const epic = named || epicFromHere(inputs)
614
947
  if (!epic) {
615
948
  const flying = epicsInFlight(inputs.worktrees)
@@ -617,7 +950,7 @@ function epicStatusCommand(argv) {
617
950
  ? `name an epic — in flight here: ${flying.join(', ')}`
618
951
  : 'name an epic — none has a member in flight here'
619
952
  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`,
953
+ json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--here] [--json] [--dir <path>]\n${line}\n`,
621
954
  )
622
955
  return
623
956
  }
@@ -628,9 +961,14 @@ function epicStatusCommand(argv) {
628
961
  // A link only where a server is already serving: this reads the server and
629
962
  // never starts one, so a status asked from a phone never restarts the
630
963
  // server whose link that phone has open.
631
- linkFor: (spec) => (up ? `${serveUrl('127.0.0.1', up)}${encodeURIComponent(spec)}` : null),
964
+ //
965
+ // The NETWORK address where the server is bound wide, so a row read on a
966
+ // phone opens there too; loopback where it is not, or where this machine
967
+ // has no address to offer. A tailnet reader has the epic page, whose member
968
+ // links are relative.
969
+ linkFor: (spec) => memberPageLink(up, offerableLanAddresses(), spec),
632
970
  })
633
- const answer = epicAnswer(epic, inputs, readers)
971
+ const answer = { ...epicAnswer(epic, inputs, readers), ...(here ? { here: here.label } : {}) }
634
972
  const page = epicPageTiers(inputs, up, epic)
635
973
  if (json) {
636
974
  process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
@@ -641,6 +979,14 @@ function epicStatusCommand(argv) {
641
979
  process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
642
980
  }
643
981
 
982
+ // A member's review page as `epic status` prints it: the network URL where the
983
+ // server is bound wide, else loopback; null with nothing serving.
984
+ function memberPageLink(up, addrs, spec) {
985
+ if (!up) return null
986
+ const served = reviewServedUrls(up, addrs, spec)
987
+ return served.url || served.loopbackUrl
988
+ }
989
+
644
990
  /**
645
991
  * Where the epic page can be read: the same tiers a review render prints, for
646
992
  * the epic's own route — or, with no server running, the one command that
@@ -660,6 +1006,15 @@ function epicPageLines(page) {
660
1006
  return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
661
1007
  }
662
1008
 
1009
+ // The working tree `--here` reads: the project folder of the checkout this
1010
+ // command runs in. null when there is no checkout to read.
1011
+ function hereTree(inputs) {
1012
+ const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
1013
+ if (!top) return null
1014
+ const root = path.join(path.resolve(top), (inputs.config && prefixOf(inputs.config)) || '')
1015
+ return { tree: workingTree(root), label: path.relative(path.dirname(inputs.dir), root) || root }
1016
+ }
1017
+
663
1018
  /**
664
1019
  * The epic a bare `epic status` means: the one whose worktree this command runs
665
1020
  * in, or the epic named by the member whose worktree it runs in. A positive
@@ -831,7 +1186,7 @@ function epicInputs(argv, json, subject) {
831
1186
  .map((p) => worktreeOverview(p.project, p.folder))
832
1187
  .filter(Boolean)
833
1188
  : []
834
- return { dir, config: present ? config : null, base, ...tree, worktrees }
1189
+ return { dir, config: present ? config : null, base, ...tree, worktrees, branches: specBranchDocs(git, config, base) }
835
1190
  }
836
1191
 
837
1192
  // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -944,14 +1299,28 @@ function untouchedLines(plan) {
944
1299
  * yet is not broken, and a check that stopped someone's work over a missing
945
1300
  * header would be a worse failure than the omission it names.
946
1301
  */
1302
+ // Specs that live only on their own branch, for the checks that read the
1303
+ // backlog. Every cannot-tell — no git, an unresolvable base — is an empty list,
1304
+ // which leaves the disk scan exactly as it was.
1305
+ function branchSpecDocs(dir) {
1306
+ try {
1307
+ const { config } = loadEnvConfig(dir)
1308
+ const git = gitReader(dir)
1309
+ return specBranchDocs(git, config, resolveBaseBranch(config, git))
1310
+ } catch {
1311
+ return []
1312
+ }
1313
+ }
1314
+
947
1315
  function gatingCheck(dir, argv) {
948
1316
  const { opts, positional } = parse(argv)
949
- const { checkGating, activeSpecs } = require('./gating.js')
1317
+ const { checkGating, activeSpecs, ACTIVE_BUCKETS } = require('./gating.js')
1318
+ const branches = branchSpecDocs(dir).filter((b) => ACTIVE_BUCKETS.includes(b.bucket))
950
1319
 
951
1320
  let specs = null
952
1321
  if (positional.length && !opts.all) {
953
1322
  const name = path.basename(positional[0])
954
- const found = activeSpecs(dir).filter((s) => s.folder === name)
1323
+ const found = preferBranches(activeSpecs(dir), branches).filter((s) => s.folder === name)
955
1324
  if (!found.length) {
956
1325
  // Not an accusation: a name that matches no ACTIVE spec is usually a
957
1326
  // finished one, which gating never covers anyway.
@@ -961,7 +1330,7 @@ function gatingCheck(dir, argv) {
961
1330
  specs = found
962
1331
  }
963
1332
 
964
- const result = checkGating(dir, specs)
1333
+ const result = checkGating(dir, specs, { branches })
965
1334
 
966
1335
  if (opts.json) {
967
1336
  process.stdout.write(JSON.stringify(result, null, 2) + '\n')
@@ -981,8 +1350,8 @@ function gatingCheck(dir, argv) {
981
1350
  for (const f of result.findings) {
982
1351
  lines.push(
983
1352
  f.kind === 'missing'
984
- ? ` ${f.folder} (${f.bucket}): no Gating: header`
985
- : ` ${f.folder} (${f.bucket}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
1353
+ ? ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): no Gating: header`
1354
+ : ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
986
1355
  )
987
1356
  }
988
1357
  lines.push('')
@@ -2096,6 +2465,16 @@ function specEnvDown(dir, config, specArg, flags) {
2096
2465
  prAbandon = prAbandonCommand(info, { branch: spec.branch, id: pr.id })
2097
2466
  }
2098
2467
  }
2468
+ // Under the docs lane, a branch whose whole range is this spec's own
2469
+ // documents (its folder, its companions) is a never-started spec: the
2470
+ // planner may offer its remote delete. Asked only in that lane, and an
2471
+ // unreadable or empty range is not docs-only — it stays false.
2472
+ if (config.land && config.land.specDocs === 'branch' && !worktreeState.merged) {
2473
+ const range = landRange(gitReader(dir), base, spec.branch)
2474
+ if (Array.isArray(range) && range.length) {
2475
+ worktreeState = { ...worktreeState, docsOnly: classifyDirtyTree(spec, range, config).foreign.length === 0 }
2476
+ }
2477
+ }
2099
2478
  const plan = planDown(spec, config, flags, {
2100
2479
  worktreeState,
2101
2480
  prAbandonCommand: prAbandon,
@@ -2468,6 +2847,15 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2468
2847
  // entirely on its branch may not exist in the primary checkout's specs/** —
2469
2848
  // resolveSpecWithWorktree offers its worktree as a fallback search location.
2470
2849
  const spec = resolveSpecWithWorktree(dir, config, specArg)
2850
+ // `--docs` is /spec's authoring land. Under the "branch" lane the document
2851
+ // rides its own branch, so there is nothing to land — only a branch to
2852
+ // publish. Under "trunk" it falls through to the ordinary land unchanged.
2853
+ // Keyed on the FLAG, never on `specDocs` alone: /spec-complete lands CODE
2854
+ // through this same verb, and that land must not turn into a push.
2855
+ if (flags.docs === true && config.land && config.land.specDocs === 'branch') {
2856
+ specEnvIntegrateDocs(dir, config, spec, flags)
2857
+ return
2858
+ }
2471
2859
  // Fetch before resolving under a rolling base, so a spec that outlived a
2472
2860
  // release roll lands on the rc that exists now rather than the one the last
2473
2861
  // fetch saw. No pattern → no fetch, and the plan below is unchanged.
@@ -2853,6 +3241,55 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
2853
3241
  process.stdout.write(out.join('\n') + '\n')
2854
3242
  }
2855
3243
 
3244
+ // The authoring land under `land.specDocs: "branch"`: publish the spec's branch,
3245
+ // consent-gated, and touch nothing else. /spec runs what is printed.
3246
+ function specEnvIntegrateDocs(dir, config, spec, flags) {
3247
+ const checkout = config.mode === 'checkout'
3248
+ const treePath = checkout ? dir : spec.worktreePath
3249
+ if (!checkout && !fs.existsSync(spec.worktreePath)) {
3250
+ process.stdout.write(`spec-env integrate: ${spec.folder} has no worktree — nothing to publish.\n`)
3251
+ return
3252
+ }
3253
+ const remote = (config.land && config.land.remote) || 'origin'
3254
+ const git = gitReader(treePath)
3255
+ const status = git(['status', '--porcelain'])
3256
+ const remoteConfigured = git(['remote', 'get-url', remote]) !== null
3257
+ const headSha = git(['rev-parse', 'HEAD'])
3258
+ const lsRemote = remoteConfigured ? git(['ls-remote', remote, `refs/heads/${spec.branch}`]) : null
3259
+ const plan = planIntegrateDocs(spec, config, {
3260
+ worktreeState: { dirty: status !== null && status.length > 0 },
3261
+ remote,
3262
+ treePath,
3263
+ remoteConfigured,
3264
+ pushedAtHead: Boolean(headSha && lsRemote && lsRemote.split(/\s/)[0] === headSha),
3265
+ push: flags.push === true,
3266
+ })
3267
+
3268
+ if (plan.blocked) {
3269
+ process.stdout.write(`spec-env integrate: blocked — ${plan.reason}.\n`)
3270
+ return
3271
+ }
3272
+ const out = [`spec-env integrate: ${spec.folder} (spec docs ride the branch)`, '']
3273
+ out.push(' lane: branch — land.specDocs; the base branch is not touched')
3274
+ out.push(` branch: ${plan.branch}`)
3275
+ out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
3276
+ if (plan.noRemote) {
3277
+ out.push(` remote: no "${remote}" configured — the branch stays local`)
3278
+ } else if (plan.push.via === 'remote') {
3279
+ out.push(` pushed: already on ${remote} at HEAD — nothing to run`)
3280
+ } else if (plan.push.via === 'push') {
3281
+ out.push('')
3282
+ out.push(' run these:')
3283
+ for (const cmd of plan.commands) out.push(` ${cmd}`)
3284
+ } else {
3285
+ out.push('')
3286
+ out.push(' then, to publish the branch — with your consent')
3287
+ out.push(' (or re-run with --push to plan it as one list):')
3288
+ for (const cmd of plan.holdCommands) out.push(` ${cmd}`)
3289
+ }
3290
+ process.stdout.write(out.join('\n') + '\n')
3291
+ }
3292
+
2856
3293
  // `spec-env disposition [<spec>] [--json]` — enumerate the loose ends a
2857
3294
  // completion must dispose before a PR goes ready: unticked tasks, phase-index
2858
3295
  // rows not ✅, surfaced follow-ups. Information only — it never refuses and
@@ -3807,7 +4244,7 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
3807
4244
  `branch: ${r.branch}\n` +
3808
4245
  `worktree: ${r.projectPath}\n` +
3809
4246
  `project: ${r.projectName}\n` +
3810
- projectLine(config.project),
4247
+ projectLine(config.checkout),
3811
4248
  )
3812
4249
  }
3813
4250
 
@@ -5404,6 +5841,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5404
5841
  notes,
5405
5842
  gate,
5406
5843
  buttons,
5844
+ project: projectName(config),
5407
5845
  ...surfaceArgs,
5408
5846
  ...(docs ? { only: docs.owned, treePath: docs.tree } : {}),
5409
5847
  })
@@ -5446,6 +5884,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5446
5884
  notes,
5447
5885
  gate,
5448
5886
  buttons,
5887
+ project: projectName(config),
5449
5888
  ...surfaceArgs,
5450
5889
  fellBack: true,
5451
5890
  })
@@ -5795,9 +6234,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5795
6234
  // The reason there is no served URL, when there is none. A `file://` link
5796
6235
  // with nothing said about it reads as the ordinary outcome, and it is not.
5797
6236
  (!served && noServeBecause ? ` not served: ${noServeBecause}\n` : '') +
5798
- (served && served.loopback && config.review.allowNetwork
5799
- ? ` network permitted but the running server is loopback-bound — ${served.widen}\n`
5800
- : '') +
5801
6237
  (served && served.started && !served.loopback
5802
6238
  ? ' serving: every provisioned spec, to anyone with a URL on your network.\n' +
5803
6239
  ' stop: skitterspec spec-env review serve --stop\n'
@@ -7414,6 +7850,16 @@ async function run(argv) {
7414
7850
  return
7415
7851
  }
7416
7852
 
7853
+ if (cmd === 'project') {
7854
+ projectCommand(rest)
7855
+ return
7856
+ }
7857
+
7858
+ if (cmd === 'tada') {
7859
+ await tadaCommand(rest)
7860
+ return
7861
+ }
7862
+
7417
7863
  if (cmd === 'epic') {
7418
7864
  const [sub, ...eArgs] = rest
7419
7865
  if (sub === 'status') epicStatusCommand(eArgs)
@@ -7482,6 +7928,7 @@ async function run(argv) {
7482
7928
  isolation,
7483
7929
  workspaceMode,
7484
7930
  gating,
7931
+ project: opts.project,
7485
7932
  })
7486
7933
  break
7487
7934
  }
@@ -7515,5 +7962,6 @@ module.exports = {
7515
7962
  serverScriptOk,
7516
7963
  daemonScript,
7517
7964
  reviewServedUrls,
7965
+ memberPageLink,
7518
7966
  restartHost,
7519
7967
  }