@skitterbyte/skitterspec-jira 2.5.1 → 2.6.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
@@ -72,6 +72,7 @@ const {
72
72
  repoInfo,
73
73
  expandTokens,
74
74
  splitPrefix,
75
+ isEpic,
75
76
  parseBaseVersion,
76
77
  BUCKETS,
77
78
  } = require('./env/resolve.js')
@@ -187,6 +188,16 @@ const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase }
187
188
  const { collectDisposition } = require('./env/disposition.js')
188
189
  const { planHandoff } = require('./env/handoff.js')
189
190
  const { collectInFlight, detailOf, formatInFlight, isInFlight } = require('./env/inflight.js')
191
+ const {
192
+ epicStatus,
193
+ formatEpicStatus,
194
+ indexSpecTree,
195
+ epicHeaders,
196
+ memberCheck,
197
+ bypassLine,
198
+ appendChangelog,
199
+ waitsMetByRebase,
200
+ } = require('./env/epic.js')
190
201
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
191
202
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
192
203
  const { planDev } = require('./env/dev.js')
@@ -296,6 +307,20 @@ Usage:
296
307
  skitterspec status What is in flight here: every spec with a worktree,
297
308
  its bucket and phase progress read from that
298
309
  worktree (--json). Offline; always exits 0.
310
+ skitterspec epic status <epic>
311
+ An epic's members, from their Epic: and Waits on:
312
+ headers: ready now, blocked and on what, cannot
313
+ tell, waves, sync points, never-together pairs
314
+ and free lanes (--json). Waits are met only on
315
+ the base branch. Always exits 0.
316
+ skitterspec epic check <spec> [--phase N]
317
+ What starting a member (or building phase N)
318
+ should hear: unmet waits, with a bypass offer the
319
+ first time, and members on the same files in
320
+ flight. Silent when nothing; never refuses.
321
+ skitterspec epic bypass <spec> [--phase N]
322
+ Build past an unmet wait, recorded as a dated
323
+ line in the member's Changelog.
299
324
  skitterspec gating <cmd> Release-gating check (opt-in; needs
300
325
  specs/.core/gating.config.json). Subcommands:
301
326
  check [spec] report specs with no recorded gating
@@ -553,6 +578,220 @@ function inFlightStatus(argv) {
553
578
  process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
554
579
  }
555
580
 
581
+ /**
582
+ * `skitterspec epic status <epic>` — the members' own headers turned into an
583
+ * order. Waits are read off the BASE BRANCH by git, never off whatever the
584
+ * primary checkout has checked out, because that is the one place every
585
+ * session agrees on (`env/epic.js`). Advisory: always exits 0.
586
+ */
587
+ function epicStatusCommand(argv) {
588
+ const json = argv.includes('--json')
589
+ const epic = epicPositional(argv)
590
+ if (!epic) {
591
+ process.stdout.write('Usage: skitterspec epic status <epic> [--json] [--dir <path>]\n')
592
+ return
593
+ }
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))
598
+ }
599
+
600
+ /**
601
+ * `skitterspec epic check <spec> [--phase N]` — what starting or building one
602
+ * member should hear about its epic, asked by `/spec-start` (the start) and
603
+ * `/spec-next` (`--phase N`). Prints nothing when there is nothing to say: a
604
+ * spec in no epic, or one with nothing in its way.
605
+ *
606
+ * An unmet wait is `blocked`, with a `bypass` offer the first time it is asked
607
+ * (`.claude/rules/offered-unblocks.md`); `--offered` spends that offer. It
608
+ * never refuses anything itself and always exits 0 — the skill relays it and
609
+ * the operator answers (spec feat-epics, Decision 8).
610
+ */
611
+ function epicCheckCommand(argv) {
612
+ const json = argv.includes('--json')
613
+ const spec = epicPositional(argv)
614
+ const phase = phaseFlag(argv)
615
+ if (!spec || phase === undefined) {
616
+ process.stdout.write('Usage: skitterspec epic check <spec> [--phase N] [--offered] [--json] [--dir <path>]\n')
617
+ return
618
+ }
619
+ const ctx = memberContext(argv, json, spec)
620
+ if (!ctx) return
621
+ const { result, recordFile, record } = ctx.check(phase)
622
+ if (argv.includes('--offered')) {
623
+ const key = phase === null ? 'start' : `phase ${phase}`
624
+ if (result.offer) writeEpicRecord(recordFile, { ...record, offered: [...new Set([...(record.offered || []), key])] })
625
+ process.stdout.write(json ? JSON.stringify({ spec, offered: key }, null, 2) + '\n' : '')
626
+ return
627
+ }
628
+ if (json) {
629
+ process.stdout.write(JSON.stringify(result, null, 2) + '\n')
630
+ return
631
+ }
632
+ for (const w of result.warnings) process.stdout.write(`epic check: ${spec} (${result.epic}) — ${w.message}\n`)
633
+ if (result.blocked) process.stdout.write(`epic check: ${result.reason}\n`)
634
+ }
635
+
636
+ /**
637
+ * `skitterspec epic bypass <spec> [--phase N]` — build past an unmet wait, on
638
+ * the record. Writes a dated line into the member's own Changelog, in its
639
+ * worktree, and remembers the scope so the same wait is not asked again. A
640
+ * wait already met has nothing to bypass and writes nothing.
641
+ */
642
+ function epicBypassCommand(argv) {
643
+ const spec = epicPositional(argv)
644
+ const phase = phaseFlag(argv)
645
+ if (!spec || phase === undefined) {
646
+ process.stdout.write('Usage: skitterspec epic bypass <spec> [--phase N] [--dir <path>]\n')
647
+ return
648
+ }
649
+ const ctx = memberContext(argv, false, spec)
650
+ if (!ctx) return
651
+ const { result, recordFile, record } = ctx.check(phase)
652
+ if (!result.blocked) {
653
+ process.stdout.write(`epic bypass: ${spec} has no unmet wait${phase === null ? '' : ` for phase ${phase}`} — nothing recorded.\n`)
654
+ return
655
+ }
656
+ // Written where the spec is being built — its own worktree — and nowhere
657
+ // else: on the base branch the line would be a change nobody reviews.
658
+ const file = ctx.worktreeFile
659
+ if (!file) {
660
+ process.stdout.write(`epic bypass: ${spec} has no worktree to record it in — /spec-start it first. Nothing recorded.\n`)
661
+ process.exitCode = 1
662
+ return
663
+ }
664
+ const line = bypassLine(result, new Date().toISOString().slice(0, 10))
665
+ fs.writeFileSync(file, appendChangelog(fs.readFileSync(file, 'utf8'), line))
666
+ writeEpicRecord(recordFile, { ...record, bypassed: [...new Set([...(record.bypassed || []), ...result.scopes])] })
667
+ process.stdout.write(`epic bypass: recorded in ${path.relative(process.cwd(), file) || file}\n ${line}\n`)
668
+ }
669
+
670
+ // `--phase N` → N; absent → null (the start); present but not a number →
671
+ // undefined, which the callers refuse as usage.
672
+ function phaseFlag(argv) {
673
+ const at = argv.indexOf('--phase')
674
+ if (at === -1) return null
675
+ const n = Number(argv[at + 1])
676
+ return Number.isInteger(n) && n > 0 ? n : undefined
677
+ }
678
+
679
+ // One member, read for `check` and `bypass`: its epic (off its own copy — the
680
+ // worktree's where it has one, else the base branch's), the record of offers
681
+ // and bypasses, and where its worktree overview lives. null, having said why,
682
+ // when the base branch cannot be read.
683
+ function memberContext(argv, json, spec) {
684
+ const inputs = epicInputs(argv, json, spec)
685
+ if (!inputs) return null
686
+ const own = inputs.worktrees.find((w) => w.folder === spec)
687
+ const entry = inputs.index.get(spec)
688
+ const text = own ? own.overview : entry ? inputs.readFile(`specs/${entry.bucket}/${spec}/00-overview.md`) : null
689
+ const epic = text ? epicHeaders(text).epic : null
690
+ const recordFile = path.join(inputs.dir, '.spec-env', 'epics', `${spec}.json`)
691
+ const record = readEpicRecord(recordFile)
692
+ return {
693
+ worktreeFile: own ? path.join(own.root, 'specs', own.bucket, spec, '00-overview.md') : null,
694
+ check: (phase) => ({
695
+ recordFile,
696
+ record,
697
+ result: epic
698
+ ? memberCheck(epicStatus({ epic, ...inputs }), spec, { phase, record })
699
+ : { spec, epic: null, phase, warnings: [], blocked: false },
700
+ }),
701
+ }
702
+ }
703
+
704
+ // The per-spec record of offers raised and waits bypassed. Machine-local and
705
+ // gitignored, like the review sidecars; the Changelog line is the durable half.
706
+ // An unreadable record is an empty one: the cost is an offer asked again.
707
+ function readEpicRecord(file) {
708
+ try {
709
+ return JSON.parse(fs.readFileSync(file, 'utf8'))
710
+ } catch {
711
+ return {}
712
+ }
713
+ }
714
+
715
+ function writeEpicRecord(file, record) {
716
+ fs.mkdirSync(path.dirname(file), { recursive: true })
717
+ fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n')
718
+ }
719
+
720
+ function epicPositional(argv) {
721
+ return argv.find((a, i) => !a.startsWith('--') && argv[i - 1] !== '--dir')
722
+ }
723
+
724
+ // The base branch's spec tree and the provisioned worktrees' own copies — what
725
+ // both `epic` verbs read. Waits are read off the BASE BRANCH by git, never off
726
+ // whatever the primary checkout has checked out (`env/epic.js`). null, having
727
+ // said why, when the base branch cannot be read.
728
+ function epicInputs(argv, json, subject) {
729
+ const at = argv.indexOf('--dir')
730
+ const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
731
+ const anchor = primaryAnchor(from, gitReader(from))
732
+ const dir = anchor.dir
733
+ const { config, present } = loadEnvConfig(dir)
734
+ attachProject(config, anchor)
735
+ const git = gitReader(dir)
736
+ const say = (line) => {
737
+ process.stdout.write(json ? JSON.stringify({ subject, cannotTell: line }, null, 2) + '\n' : `epic: cannot tell — ${line}\n`)
738
+ return null
739
+ }
740
+
741
+ let base
742
+ try {
743
+ base = resolveBaseBranch(config, git)
744
+ } catch (err) {
745
+ return say(err.message)
746
+ }
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}`])
757
+ const worktrees = present
758
+ ? provisionedSpecs(dir, config)
759
+ .filter((p) => !p.specless)
760
+ .map((p) => worktreeOverview(p.project, p.folder))
761
+ .filter(Boolean)
762
+ : []
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
793
+ }
794
+
556
795
  // Plan a provision: allocate the slot, persist the registry, and print the plan
557
796
  // the /spec-env skill executes (git worktree add, docker compose up, .env).
558
797
  // This creates no worktree and starts no stack — the caller runs the
@@ -981,7 +1220,9 @@ function specEnvNospec(dir, config, name, flags = {}) {
981
1220
  }
982
1221
 
983
1222
  function specEnvUp(dir, config, specArg, flags = {}) {
984
- const docs = flags.docs === true
1223
+ // An epic holds no code — its work is its members' — so its tree is always a
1224
+ // documents-only one, with or without the flag (spec feat-epics).
1225
+ const docs = flags.docs === true || isEpic(String(specArg || ''))
985
1226
 
986
1227
  // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
987
1228
  // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
@@ -999,7 +1240,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
999
1240
  try {
1000
1241
  spec = resolveSpecWithWorktree(dir, config, specArg)
1001
1242
  } catch (err) {
1002
- const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident)-./.test(specArg)
1243
+ const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident|epic)-./.test(specArg)
1003
1244
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
1004
1245
  throw err
1005
1246
  }
@@ -1367,7 +1608,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1367
1608
  * primary checkout already has its dependencies.
1368
1609
  */
1369
1610
  function specEnvBootstrap(dir, config, specArg, flags = {}) {
1370
- const docs = flags.docs === true
1611
+ const docs = flags.docs === true || isEpic(String(specArg || ''))
1371
1612
  const json = flags.json === true
1372
1613
  const say = (line) => process.stdout.write(line + '\n')
1373
1614
  const refuse = (msg) => {
@@ -2243,7 +2484,8 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2243
2484
  }
2244
2485
  const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
2245
2486
  ` base: ${base}`, ` branch: ${cplan.branch}`,
2246
- ...retargetLines(retarget), '',
2487
+ ...retargetLines(retarget),
2488
+ ...reverifyLines(dir, spec, base, dir), '',
2247
2489
  ' run these (abort the rebase on conflict):']
2248
2490
  for (const cmd of cplan.commands) cout.push(` ${cmd}`)
2249
2491
  process.stdout.write(cout.join('\n') + '\n' + afterLandSection(cplan.afterLand))
@@ -2359,12 +2601,51 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2359
2601
  out.push(` worktree: ${spec.worktreePath}`)
2360
2602
  out.push(...retargetLines(retarget))
2361
2603
  if (primarySwitch) out.push(` primary: on ${primarySwitch.from} — switched to ${base} before the land`)
2604
+ out.push(...reverifyLines(dir, spec, baseRef, spec.projectPath || spec.worktreePath))
2362
2605
  out.push('')
2363
2606
  out.push(' run these (abort the rebase on conflict):')
2364
2607
  for (const cmd of plan.commands) out.push(` ${cmd}`)
2365
2608
  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
2366
2609
  }
2367
2610
 
2611
+ // What this land's rebase will bring in that the spec's BUILT phases waited
2612
+ // on (spec feat-epics, Decision 9) — each listed phase was built without its
2613
+ // dependency underneath, so the landing skill runs the tests after the rebase
2614
+ // and before the fast-forward. Read off the fork point and the base by git,
2615
+ // against the spec's own copy in `tree`. Silent when nothing arrives, which is
2616
+ // every spec with no `Waits on:` at all.
2617
+ function reverifyLines(dir, spec, baseRef, tree) {
2618
+ const own = worktreeOverview(tree, spec.folder)
2619
+ if (!own) return []
2620
+ const git = gitReader(dir)
2621
+ const read = (ref) => {
2622
+ const listing = ref ? git(['ls-tree', '-r', '--name-only', ref, '--', 'specs']) : null
2623
+ // An unreadable side reads as nothing at all, so every wait on it is a
2624
+ // cannot-tell — never a "met by this rebase" that nobody could check.
2625
+ return listing === null
2626
+ ? { index: new Map(), readFile: () => null }
2627
+ : { index: indexSpecTree(listing), readFile: (p) => git(['show', `${ref}:${p}`]) }
2628
+ }
2629
+ const fork = git(['merge-base', baseRef, spec.branch])
2630
+ const { met, cannotTell } = waitsMetByRebase({
2631
+ overview: own.overview,
2632
+ phases: own.phases,
2633
+ before: read(fork),
2634
+ after: read(baseRef),
2635
+ })
2636
+ const what = (phase) => (phase === null ? 'start' : `phase ${phase}`)
2637
+ const lines = []
2638
+ if (met.length) {
2639
+ lines.push(' re-verify: this rebase brings in what built phases waited on — run the tests')
2640
+ lines.push(' after the rebase and before the fast-forward:')
2641
+ for (const { phase, wait } of met) lines.push(` ${what(phase)} waited on ${wait.raw} — ${wait.why}`)
2642
+ }
2643
+ for (const { phase, wait } of cannotTell) {
2644
+ lines.push(` re-verify: cannot tell for ${what(phase)} — ${wait.raw}: ${wait.why}`)
2645
+ }
2646
+ return lines
2647
+ }
2648
+
2368
2649
  // The line a plan carries when the rc rolled while the spec was in flight. The
2369
2650
  // rebase onto the newer rc is the land working, not a mistake — but it should
2370
2651
  // never happen without the reader seeing it.
@@ -7091,6 +7372,15 @@ async function run(argv) {
7091
7372
  return
7092
7373
  }
7093
7374
 
7375
+ if (cmd === 'epic') {
7376
+ const [sub, ...eArgs] = rest
7377
+ if (sub === 'status') epicStatusCommand(eArgs)
7378
+ else if (sub === 'check') epicCheckCommand(eArgs)
7379
+ else if (sub === 'bypass') epicBypassCommand(eArgs)
7380
+ else process.stdout.write('Usage: skitterspec epic <status <epic> | check <spec> | bypass <spec>> [--phase N] [--json] [--dir <path>]\n')
7381
+ return
7382
+ }
7383
+
7094
7384
  const { opts, positional } = parse(rest)
7095
7385
  const dir = path.resolve(opts.dir || positional[0] || process.cwd())
7096
7386