@skitterbyte/skitterspec-jira 2.5.0 → 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')
@@ -250,6 +261,8 @@ Usage:
250
261
  Docker stack (prints commands; creates nothing)
251
262
  --docs: a tree to write documents in — no
252
263
  setup commands, no Docker
264
+ --plan: write nothing, not even the trust
265
+ entry or the registry record
253
266
  bootstrap [spec] run the worktree's seeds, env file, setup
254
267
  and stack itself, in the worktree — after
255
268
  \`up\`'s worktree add (--docs: seeds only;
@@ -294,6 +307,20 @@ Usage:
294
307
  skitterspec status What is in flight here: every spec with a worktree,
295
308
  its bucket and phase progress read from that
296
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.
297
324
  skitterspec gating <cmd> Release-gating check (opt-in; needs
298
325
  specs/.core/gating.config.json). Subcommands:
299
326
  check [spec] report specs with no recorded gating
@@ -551,6 +578,220 @@ function inFlightStatus(argv) {
551
578
  process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
552
579
  }
553
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
+
554
795
  // Plan a provision: allocate the slot, persist the registry, and print the plan
555
796
  // the /spec-env skill executes (git worktree add, docker compose up, .env).
556
797
  // This creates no worktree and starts no stack — the caller runs the
@@ -979,7 +1220,9 @@ function specEnvNospec(dir, config, name, flags = {}) {
979
1220
  }
980
1221
 
981
1222
  function specEnvUp(dir, config, specArg, flags = {}) {
982
- 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 || ''))
983
1226
 
984
1227
  // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
985
1228
  // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
@@ -997,7 +1240,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
997
1240
  try {
998
1241
  spec = resolveSpecWithWorktree(dir, config, specArg)
999
1242
  } catch (err) {
1000
- 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)
1001
1244
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
1002
1245
  throw err
1003
1246
  }
@@ -1038,11 +1281,13 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1038
1281
  }
1039
1282
  const beforeAuth = readRegistry(dir, config)
1040
1283
  const resolved = resolveSpecless(specArg, dir, config, { spec: true })
1041
- writeRegistry(
1042
- dir,
1043
- config,
1044
- recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
1045
- )
1284
+ if (!flags.plan) {
1285
+ writeRegistry(
1286
+ dir,
1287
+ config,
1288
+ recordSpecless(beforeAuth, specArg, { branch: resolved.branch, spec: true }),
1289
+ )
1290
+ }
1046
1291
  spec = resolved
1047
1292
  const fork = fromVersion || releaseFork
1048
1293
  if (fork) {
@@ -1172,8 +1417,12 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1172
1417
  // Trust the shared worktree root so edits into the freshly-provisioned worktree
1173
1418
  // don't prompt. One absolute entry (the root) covers every spec; self-heals on
1174
1419
  // every provision for teammates who only cloned and ran /spec-start.
1420
+ //
1421
+ // `--plan` is the dry run: every write below is asked and not made, and the
1422
+ // report says "would". It was parsed and ignored once, so a plan headed
1423
+ // "nothing created yet" still wrote this entry into the operator's settings.
1175
1424
  const worktreeRootAbs = path.dirname(spec.worktreePath)
1176
- const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
1425
+ const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs, { dryRun: !!flags.plan })
1177
1426
 
1178
1427
  // Documents mode brings no stack up, so a Docker spec provisioned this way is
1179
1428
  // a worktree-only run. Asked through `resolveStack`, which `planUp` also
@@ -1204,7 +1453,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1204
1453
  Object.prototype.hasOwnProperty.call(before.slots, spec.folder) || worktreeOnDisk
1205
1454
  const alloc = allocateSlot(before, spec.folder)
1206
1455
  slot = alloc.slot
1207
- writeRegistry(dir, config, alloc.registry) // the engine's only write (Docker path)
1456
+ if (!flags.plan) writeRegistry(dir, config, alloc.registry) // the engine's only write (Docker path)
1208
1457
  } else {
1209
1458
  attached = worktreeOnDisk
1210
1459
  }
@@ -1291,7 +1540,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1291
1540
  // the lane working rather than something the engine failed to find.
1292
1541
  if (authoring) {
1293
1542
  out.push(' authoring: no spec document yet — the skill writes it in the worktree')
1294
- out.push(` recorded: added to ${config.registry} until the spec is written`)
1543
+ out.push(` recorded: ${flags.plan ? 'would add to' : 'added to'} ${config.registry} until the spec is written`)
1295
1544
  }
1296
1545
  // Only where one was NAMED. The fork point is otherwise base HEAD, which is
1297
1546
  // the unremarkable case, and a line asserting it on every provision would
@@ -1323,10 +1572,8 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1323
1572
  `\n add ${worktreeRootAbs} to permissions.additionalDirectories yourself`,
1324
1573
  )
1325
1574
  } else {
1326
- out.push(
1327
- ` trusted: ${worktreeRootAbs} ` +
1328
- `(${trust.changed ? 'added to' : 'already in'} .claude/settings.local.json)`,
1329
- )
1575
+ const verb = !trust.changed ? 'already in' : flags.plan ? 'would add to' : 'added to'
1576
+ out.push(` trusted: ${worktreeRootAbs} (${verb} .claude/settings.local.json)`)
1330
1577
  }
1331
1578
  out.push(...specCommitLines(plan, spec.folder))
1332
1579
  out.push(...untouchedLines(plan))
@@ -1361,7 +1608,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1361
1608
  * primary checkout already has its dependencies.
1362
1609
  */
1363
1610
  function specEnvBootstrap(dir, config, specArg, flags = {}) {
1364
- const docs = flags.docs === true
1611
+ const docs = flags.docs === true || isEpic(String(specArg || ''))
1365
1612
  const json = flags.json === true
1366
1613
  const say = (line) => process.stdout.write(line + '\n')
1367
1614
  const refuse = (msg) => {
@@ -2237,7 +2484,8 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2237
2484
  }
2238
2485
  const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
2239
2486
  ` base: ${base}`, ` branch: ${cplan.branch}`,
2240
- ...retargetLines(retarget), '',
2487
+ ...retargetLines(retarget),
2488
+ ...reverifyLines(dir, spec, base, dir), '',
2241
2489
  ' run these (abort the rebase on conflict):']
2242
2490
  for (const cmd of cplan.commands) cout.push(` ${cmd}`)
2243
2491
  process.stdout.write(cout.join('\n') + '\n' + afterLandSection(cplan.afterLand))
@@ -2353,12 +2601,51 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2353
2601
  out.push(` worktree: ${spec.worktreePath}`)
2354
2602
  out.push(...retargetLines(retarget))
2355
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))
2356
2605
  out.push('')
2357
2606
  out.push(' run these (abort the rebase on conflict):')
2358
2607
  for (const cmd of plan.commands) out.push(` ${cmd}`)
2359
2608
  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
2360
2609
  }
2361
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
+
2362
2649
  // The line a plan carries when the rc rolled while the spec was in flight. The
2363
2650
  // rebase onto the newer rc is the land working, not a mistake — but it should
2364
2651
  // never happen without the reader seeing it.
@@ -7085,6 +7372,15 @@ async function run(argv) {
7085
7372
  return
7086
7373
  }
7087
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
+
7088
7384
  const { opts, positional } = parse(rest)
7089
7385
  const dir = path.resolve(opts.dir || positional[0] || process.cwd())
7090
7386