@skitterbyte/skitterspec-jira 2.14.0 → 2.16.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 (43) hide show
  1. package/assets/claude-md-section.md +12 -0
  2. package/assets/core/SETUP.md +12 -12
  3. package/assets/core/env.config.md +25 -3
  4. package/assets/hooks/main-guard.cjs +73 -6
  5. package/assets/hooks/project-guard.cjs +80 -6
  6. package/assets/hooks/review-gate.cjs +73 -6
  7. package/assets/review/page.html +2 -1
  8. package/assets/rules/commit-trailers.md +2 -2
  9. package/assets/rules/offered-unblocks.md +22 -0
  10. package/assets/rules/spec-planning.md +12 -1
  11. package/assets/skills/no-spec/SKILL.md +5 -0
  12. package/assets/skills/spec/SKILL.md +20 -3
  13. package/assets/skills/spec-bug/SKILL.md +8 -2
  14. package/assets/skills/spec-complete/SKILL.md +28 -2
  15. package/assets/skills/spec-diff/SKILL.md +5 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +8 -2
  17. package/assets/skills/spec-idea/SKILL.md +5 -0
  18. package/assets/skills/spec-init/SKILL.md +4 -2
  19. package/assets/skills/spec-next/SKILL.md +18 -0
  20. package/assets/skills/spec-park/SKILL.md +92 -0
  21. package/assets/skills/spec-resume/SKILL.md +153 -0
  22. package/assets/skills/spec-start/SKILL.md +6 -2
  23. package/assets/skills/spec-sync/SKILL.md +10 -10
  24. package/assets/skills/spec-to-main/SKILL.md +5 -1
  25. package/assets/skills/spec-todo/SKILL.md +5 -2
  26. package/package.json +1 -1
  27. package/src/cli.js +311 -15
  28. package/src/env/base.js +21 -5
  29. package/src/env/basepin.js +62 -0
  30. package/src/env/bootstrap.js +3 -1
  31. package/src/env/checks.js +49 -0
  32. package/src/env/config.js +48 -1
  33. package/src/env/hooks.js +53 -4
  34. package/src/env/provision.js +10 -2
  35. package/src/env/resolve.js +66 -13
  36. package/src/env/resume.js +234 -0
  37. package/src/env/review.js +4 -1
  38. package/src/env/serve.js +3 -0
  39. package/src/ideacmd.js +11 -1
  40. package/src/init.js +287 -49
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/provider-kit/src/specs.js +46 -1
  43. package/src/vendor/sync-core/src/summary.js +10 -1
package/src/cli.js CHANGED
@@ -5,7 +5,7 @@ const path = require('path')
5
5
  const os = require('os')
6
6
  const { pathToFileURL } = require('url')
7
7
  const { execFileSync } = require('child_process')
8
- const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
8
+ const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
9
9
  const {
10
10
  detectReleaseTooling,
11
11
  removeReleaseTooling,
@@ -43,14 +43,17 @@ const SPEC_ENV_VERBS = Object.freeze([
43
43
  'live',
44
44
  'review',
45
45
  'stage',
46
+ 'checks',
46
47
  'status',
47
48
  'resolve',
49
+ 'resume',
48
50
  'base',
49
51
  'nospec',
50
52
  'main',
51
53
  'project',
52
54
  ])
53
55
  const { forkMatch, planBaseReport } = require('./env/base.js')
56
+ const { readBasePin, writeBasePin, clearBasePin } = require('./env/basepin.js')
54
57
  const {
55
58
  readRegistry,
56
59
  writeRegistry,
@@ -66,6 +69,8 @@ const {
66
69
  resolveSpecless,
67
70
  resolveBaseBranch,
68
71
  describeBaseBranch,
72
+ BaseUnresolvedError,
73
+ gapNote,
69
74
  baseRemote,
70
75
  liveWorktreePaths,
71
76
  collectSpecFolders,
@@ -195,6 +200,7 @@ const {
195
200
  const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
196
201
  const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
197
202
  const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
203
+ const { findTarget, planResume, resumeLines, blockingNext } = require('./env/resume.js')
198
204
  const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
199
205
  const { collectDisposition } = require('./env/disposition.js')
200
206
  const { planHandoff } = require('./env/handoff.js')
@@ -333,11 +339,18 @@ Usage:
333
339
  --run-reviewers runs review.reviewers)
334
340
  stage [spec] split the uncommitted tree into this spec's
335
341
  documents and everything else
342
+ checks [spec] run complete.checks in the spec's worktree
343
+ (advisory — always exits 0)
336
344
  status list provisioned specs + port blocks
337
345
  resolve <spec> print resolved slug/type/branch/paths
346
+ resume [spec|#N] an in-flight spec: its blockers, and the plan
347
+ to rebuild its worktree from its branch
348
+ (prints commands; creates nothing)
338
349
  base fetch, list baseBranchPattern matches
339
350
  newest-first, mark the base, and name
340
351
  specs forked from an older match
352
+ (--use-fallback pins the fallback
353
+ while nothing matches; --unpin)
341
354
  skitterspec status What is in flight here: every spec with a worktree,
342
355
  its bucket and phase progress read from that
343
356
  worktree (--json). Offline; always exits 0.
@@ -404,8 +417,12 @@ Options (init / update):
404
417
  --dir <path> Target project dir (default: positional arg or cwd)
405
418
  --gating (init) Adopt release gating: each spec records whether
406
419
  it ships behind a feature flag
420
+ --local (init) Keep the install on this machine: managed
421
+ files excluded from git, hooks in
422
+ settings.local.json, the block in CLAUDE.local.md.
423
+ For one developer on a shared repo — never a team
407
424
  --no-claude-md Skip creating/patching CLAUDE.md
408
- --yes, -y Accept defaults; skip the interactive setup prompts
425
+ --yes, -y Accept defaults; skip the interactive setup prompts
409
426
  --isolation / --no-isolation Enable/skip per-spec isolation (a git
410
427
  worktree per spec; writes env.config.json)
411
428
  --name <name> / --category <c> (init --isolation) Write project.name /
@@ -439,6 +456,7 @@ function parse(argv) {
439
456
  if (a === '--force') opts.force = true
440
457
  else if (a === '--no-claude-md') opts.claudeMd = false
441
458
  else if (a === '--yes' || a === '-y') opts.yes = true
459
+ else if (a === '--local') opts.local = true
442
460
  else if (a === '--isolation') opts.isolation = true
443
461
  else if (a === '--no-isolation') opts.isolation = false
444
462
  else if (a === '--gating') opts.gating = true
@@ -590,6 +608,10 @@ function provisionedSpecs(dir, config) {
590
608
 
591
609
  function specEnvStatus(dir, config) {
592
610
  const provisioned = provisionedSpecs(dir, config)
611
+ // A base held on the fallback is worth one line wherever work is listed: it
612
+ // is the state every fork and land is in until the next release branch.
613
+ const gap = gapNote(config, gitReader(dir))
614
+ if (gap) process.stdout.write(`spec-env: base ${config.gapPin.base} — ${gap}\n`)
593
615
 
594
616
  // REACHED EITHER WAY. This used to return here, so a repo with nothing in
595
617
  // flight could say nothing about a waiting pass — and a repo with nothing in
@@ -911,7 +933,20 @@ function repoBlockers(repo, specs) {
911
933
  } catch {
912
934
  return []
913
935
  }
914
- return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required)
936
+ // Each spec's own copy — its worktree where it has one, since base reads
937
+ // `backlog` for the life of a spec and holds none of its Blocked on: edits.
938
+ // A spec that cannot be resolved or read is not parked, it is unknown.
939
+ const parked = {}
940
+ for (const spec of specs) {
941
+ try {
942
+ const copy = readSpecCopy(resolveSpecWithWorktree(repo, config, spec).path)
943
+ const b = copy && blockingNext(copy)
944
+ if (b) parked[spec] = b
945
+ } catch {
946
+ // cannot tell — say nothing
947
+ }
948
+ }
949
+ return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required, parked)
915
950
  }
916
951
 
917
952
  /**
@@ -2281,7 +2316,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
2281
2316
  // `setup` exactly as a spec does, since a `setup` that reads a seeded `.env`
2282
2317
  // fails without it; what it never has is a stack, so no slot is consulted.
2283
2318
  if (spec.specless && !spec.unwritten) {
2284
- steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false })
2319
+ steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false, localSeeds: localSeedFiles(dir) })
2285
2320
  } else {
2286
2321
  const compose = composeFilePresent(dir, config)
2287
2322
  const { wantsDocker } = resolveStack(spec, config, { docs, composeFilePresent: compose })
@@ -2301,6 +2336,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
2301
2336
  docs,
2302
2337
  wantsDocker,
2303
2338
  composeFilePresent: compose,
2339
+ localSeeds: localSeedFiles(dir),
2304
2340
  })
2305
2341
  }
2306
2342
 
@@ -3135,7 +3171,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
3135
3171
  }
3136
3172
  const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
3137
3173
  ` base: ${base}`, ` branch: ${cplan.branch}`,
3138
- ...retargetLines(retarget),
3174
+ ...retargetLines(retarget), ...gapLines(config, gitReader(dir)),
3139
3175
  ...reverifyLines(dir, spec, base, dir), '',
3140
3176
  ' run these (abort the rebase on conflict):']
3141
3177
  for (const cmd of cplan.commands) cout.push(` ${cmd}`)
@@ -3250,7 +3286,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
3250
3286
  out.push(` base: ${plan.base}`)
3251
3287
  out.push(` branch: ${plan.branch}`)
3252
3288
  out.push(` worktree: ${spec.worktreePath}`)
3253
- out.push(...retargetLines(retarget))
3289
+ out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
3254
3290
  if (primarySwitch) out.push(` primary: on ${primarySwitch.from} — switched to ${base} before the land`)
3255
3291
  out.push(...reverifyLines(dir, spec, baseRef, spec.projectPath || spec.worktreePath))
3256
3292
  out.push('')
@@ -3304,6 +3340,13 @@ function retargetLines(retarget) {
3304
3340
  return retarget ? [` retarget: forked from ${retarget.from} · landing onto ${retarget.to}`] : []
3305
3341
  }
3306
3342
 
3343
+ // Said under `base:` when a gap pin chose it, so a land onto the fallback is
3344
+ // never mistaken for a land onto a release branch. Nothing otherwise.
3345
+ function gapLines(config, git) {
3346
+ const note = gapNote(config, git)
3347
+ return note ? [` gap: ${note}`] : []
3348
+ }
3349
+
3307
3350
  // Is the primary checkout sitting on an older rolling-base match? Positive
3308
3351
  // signal only: the branch it has out must itself match `baseBranchPattern`
3309
3352
  // (locally or on the remote). Anything else — a live spec, a detached HEAD, no
@@ -3438,7 +3481,7 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
3438
3481
  out.push(` base: ${remote}/${base}`)
3439
3482
  out.push(` branch: ${plan.branch}`)
3440
3483
  out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
3441
- out.push(...retargetLines(retarget))
3484
+ out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
3442
3485
  // Silent on cannot-tell: a line about a lookup that failed accuses nothing
3443
3486
  // and helps nobody — the placeholder in the commands already degrades.
3444
3487
  if (pr.state === 'none') out.push(' pr: none yet')
@@ -4470,18 +4513,141 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
4470
4513
  }
4471
4514
 
4472
4515
  /**
4473
- * `skitterspec spec-env base [--json]`
4516
+ * `skitterspec spec-env resume <name|#N> [--json]` (feat-spec-resume)
4517
+ *
4518
+ * Which in-flight spec the argument means, what it is blocked on, and — where
4519
+ * this machine has no worktree for it — the commands that rebuild one from its
4520
+ * branch. Plans and prints; creates nothing, moves nothing, asks no tracker.
4521
+ * A refusal exits 1.
4522
+ *
4523
+ * Every copy of the spec this clone can see is read — the checkout it runs
4524
+ * from, each live worktree, and each spec branch (local, then remote-tracking,
4525
+ * never fetched) — because under `land.specDocs: "branch"` an in-flight spec
4526
+ * may exist nowhere else than its branch, and on the base branch its bucket
4527
+ * reads `backlog` whatever it really is. `env/resume.js` picks which copy
4528
+ * speaks.
4529
+ */
4530
+ function specEnvResume(dir, config, arg, flags = {}) {
4531
+ const git = gitReader(dir)
4532
+ const prefix = prefixOf(config)
4533
+ const ownTree = (folder) => resolveSpecless(folder, dir, config, { spec: true }).worktreePath
4534
+ const copies = []
4535
+ const roots = [dir, ...[...liveWorktreePaths(git)].filter((p) => !sameDir(p, dir))]
4536
+ for (const root of roots) {
4537
+ const project = sameDir(root, dir) ? dir : projectIn(root, prefix)
4538
+ for (const bucket of BUCKETS) {
4539
+ let folders
4540
+ try {
4541
+ folders = fs.readdirSync(path.join(project, 'specs', bucket), { withFileTypes: true })
4542
+ } catch {
4543
+ continue
4544
+ }
4545
+ for (const entry of folders) {
4546
+ if (!entry.isDirectory()) continue
4547
+ const folder = entry.name
4548
+ // Another spec's worktree carries every base spec too; only a spec's
4549
+ // OWN tree speaks for it, and the checkout this ran from speaks last.
4550
+ const own = sameDir(ownTree(folder), root)
4551
+ if (!own && !sameDir(root, dir)) continue
4552
+ const copy = readSpecCopy(path.join(project, 'specs', bucket, folder))
4553
+ if (copy) copies.push({ folder, bucket, origin: own ? 'worktree' : 'here', ...copy })
4554
+ }
4555
+ }
4556
+ }
4557
+ let base = null
4558
+ try {
4559
+ base = resolveBaseBranch(config, git)
4560
+ } catch {
4561
+ // An unresolvable base hides branch-only specs; the disk copies still answer.
4562
+ }
4563
+ for (const b of specBranchDocs(git, config, base)) {
4564
+ copies.push({ folder: b.folder, bucket: b.bucket, origin: 'branch', local: b.local, ref: b.ref, overview: b.overview, phases: b.phases })
4565
+ }
4566
+
4567
+ // Bare means what every bare spec-env verb means: the worktree you are
4568
+ // standing in, else the sole provisioned spec. Neither answering leaves the
4569
+ // argument empty, and findTarget refuses that rather than guessing.
4570
+ if (!arg) {
4571
+ try {
4572
+ arg = resolveSpecWithWorktree(dir, config).folder
4573
+ } catch {
4574
+ arg = ''
4575
+ }
4576
+ }
4577
+ const identifierField = config.branch && config.branch.identifierField
4578
+ const found = findTarget(arg, copies, identifierField)
4579
+ if (found.refused) {
4580
+ process.exitCode = 1
4581
+ const r = { ok: false, refused: found.refused, refusedOnly: true }
4582
+ process.stdout.write(flags.json ? JSON.stringify({ ok: false, refused: found.refused }, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
4583
+ return
4584
+ }
4585
+ const target = found.target
4586
+ const remote = baseRemote(config)
4587
+ let branch
4588
+ if (target.origin === 'branch') {
4589
+ branch = target.ref.replace(/^refs\/heads\//, '').replace(new RegExp(`^refs/remotes/${remote}/`), '')
4590
+ } else {
4591
+ try {
4592
+ branch = resolveSpecWithWorktree(dir, config, target.folder).branch
4593
+ } catch {
4594
+ branch = resolveSpecless(target.folder, dir, config, { spec: true }).branch
4595
+ }
4596
+ }
4597
+ const worktreePath = ownTree(target.folder)
4598
+ const r = planResume(target, {
4599
+ branch,
4600
+ worktreePath,
4601
+ worktreeExists: fs.existsSync(worktreePath),
4602
+ localBranch: git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]) !== null,
4603
+ remoteBranch: git(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null,
4604
+ remote,
4605
+ identifierField,
4606
+ })
4607
+ if (!r.ok) process.exitCode = 1
4608
+ process.stdout.write(flags.json ? JSON.stringify(r, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
4609
+ }
4610
+
4611
+ // A spec folder's overview and phase files, or null when it has no overview.
4612
+ function readSpecCopy(specDir) {
4613
+ let overview
4614
+ try {
4615
+ overview = fs.readFileSync(path.join(specDir, '00-overview.md'), 'utf8')
4616
+ } catch {
4617
+ return null
4618
+ }
4619
+ const phases = []
4620
+ for (const f of fs.readdirSync(specDir).filter((n) => /^(?!00-)\d{2}-.*\.md$/.test(n)).sort()) {
4621
+ try {
4622
+ phases.push({ n: Number(f.slice(0, 2)), text: fs.readFileSync(path.join(specDir, f), 'utf8') })
4623
+ } catch {
4624
+ // An unreadable phase file is left out, never counted as done or blocked.
4625
+ }
4626
+ }
4627
+ return { overview, phases }
4628
+ }
4629
+
4630
+ /**
4631
+ * `skitterspec spec-env base [--json] [--use-fallback | --unpin]`
4474
4632
  *
4475
4633
  * Which branch is the base, how it was found, and — under `baseBranchPattern` —
4476
4634
  * every match newest-first plus the provisioned specs that forked from an older
4477
4635
  * one. It fetches first, because the resolver itself never does: a release
4478
4636
  * candidate cut since the last fetch is invisible to it.
4479
4637
  *
4480
- * Lists only and always exits 0. A failed fetch is reported and the listing
4481
- * carries on from the refs already here; nothing is edited, and pinning stays a
4482
- * hand edit of `baseBranch`.
4638
+ * Bare, it lists only and always exits 0; the one thing it writes is deleting a
4639
+ * gap pin a match has retired. A failed fetch is reported and the listing
4640
+ * carries on from the refs already here.
4641
+ *
4642
+ * `--use-fallback` is the offer's command: it writes the gap pin
4643
+ * (`env/basepin.js`) when the pattern matches nothing and a fallback resolves.
4644
+ * `--unpin` removes it. Both exit 1 on a refusal, since a caller retries on 0.
4645
+ * A permanent pin stays a hand edit of `baseBranch`.
4483
4646
  */
4484
4647
  function specEnvBase(dir, config, flags = {}) {
4648
+ if (flags.useFallback) return baseUseFallback(dir, config, flags)
4649
+ if (flags.unpin) return baseUnpin(dir, config, flags)
4650
+
4485
4651
  const pattern = (config.baseBranchPattern || '').trim()
4486
4652
  const remote = baseRemote(config)
4487
4653
  const git = gitReader(dir)
@@ -4489,7 +4655,9 @@ function specEnvBase(dir, config, flags = {}) {
4489
4655
  // No pattern: the base is today's chain, and there is nothing to fetch for —
4490
4656
  // origin/HEAD is not updated by a fetch.
4491
4657
  const fetch = fetchForPattern(dir, config)
4492
- const { base, how } = describeBaseBranch(config, git)
4658
+ const pin = pattern ? readBasePin(dir, config) : null
4659
+ const { base, how, stalePin, refused } = describeBaseBranch(config, git, pin)
4660
+ const pinCleared = Boolean(flags.pinRetired) || (Boolean(stalePin) && clearBasePin(dir, config))
4493
4661
 
4494
4662
  let matches = []
4495
4663
  let forks = []
@@ -4502,10 +4670,74 @@ function specEnvBase(dir, config, flags = {}) {
4502
4670
  }))
4503
4671
  }
4504
4672
 
4505
- const { json, lines } = planBaseReport({ pattern, remote, base, how, fetch, matches, forks })
4673
+ const { json, lines } = planBaseReport({
4674
+ pattern,
4675
+ remote,
4676
+ base,
4677
+ how,
4678
+ fetch,
4679
+ matches,
4680
+ forks,
4681
+ pin,
4682
+ pinCleared,
4683
+ offer: refused ? refused.offer : null,
4684
+ })
4506
4685
  process.stdout.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
4507
4686
  }
4508
4687
 
4688
+ // One answer for both pin verbs: a line of text, or `{ ok, ... }` as JSON.
4689
+ function basePinAnswer(flags, ok, line, extra = {}) {
4690
+ if (!ok) process.exitCode = 1
4691
+ process.stdout.write(flags.json ? JSON.stringify({ ok, ...extra, message: line }, null, 2) + '\n' : line + '\n')
4692
+ }
4693
+
4694
+ // WHAT WOULD FOOL THIS: an unfetched remote looks exactly like the gap — no
4695
+ // branch matches in either case. So it fetches first and will not pin on a
4696
+ // failed fetch: a pin made then could hold the base on the fallback while the
4697
+ // next release branch already exists on the remote.
4698
+ function baseUseFallback(dir, config, flags) {
4699
+ const pattern = (config.baseBranchPattern || '').trim()
4700
+ if (!pattern) {
4701
+ return basePinAnswer(flags, false, 'spec-env base: no baseBranchPattern is set — there is no gap to pin.')
4702
+ }
4703
+ const fetch = fetchForPattern(dir, config)
4704
+ if (fetch && !fetch.ok) {
4705
+ return basePinAnswer(
4706
+ flags,
4707
+ false,
4708
+ `spec-env base: fetch from ${baseRemote(config)} failed${fetch.reason ? ` (${fetch.reason})` : ''} — ` +
4709
+ `cannot tell whether a ${pattern} branch exists, so nothing was pinned.`,
4710
+ )
4711
+ }
4712
+ // null, not the attached pin: the question is whether the PATTERN matches.
4713
+ const { base, refused } = describeBaseBranch(config, gitReader(dir), null)
4714
+ if (base) {
4715
+ clearBasePin(dir, config)
4716
+ return basePinAnswer(flags, false, `spec-env base: ${base} matches ${pattern} — no gap to pin; it is the base.`, { base })
4717
+ }
4718
+ if (!refused || !refused.fallback) {
4719
+ return basePinAnswer(
4720
+ flags,
4721
+ false,
4722
+ `spec-env base: no branch matches ${pattern}, and no fallback resolves — set baseBranchFallback, ` +
4723
+ `or run git remote set-head ${baseRemote(config)} --auto.`,
4724
+ )
4725
+ }
4726
+ const pin = writeBasePin(dir, config, { base: refused.fallback, pattern })
4727
+ basePinAnswer(
4728
+ flags,
4729
+ true,
4730
+ `spec-env base: pinned ${pin.base} for the gap — no ${pattern} branch on ${baseRemote(config)}. ` +
4731
+ `It clears itself when one appears.`,
4732
+ { base: pin.base, pin },
4733
+ )
4734
+ }
4735
+
4736
+ function baseUnpin(dir, config, flags) {
4737
+ const removed = clearBasePin(dir, config)
4738
+ basePinAnswer(flags, true, removed ? 'spec-env base: gap pin removed.' : 'spec-env base: no gap pin to remove.', { removed })
4739
+ }
4740
+
4509
4741
  // Fetch the base's remote, but only where `baseBranchPattern` decides the base:
4510
4742
  // the resolver reads remote-tracking refs and never the network, so a release
4511
4743
  // candidate cut since the last fetch is invisible until something fetches. With
@@ -4623,6 +4855,20 @@ function provisionedBranches(dir, config) {
4623
4855
  * Re-anchoring would silently answer about the wrong checkout, so the tree read
4624
4856
  * is printed rather than assumed.
4625
4857
  */
4858
+ // `spec-env checks [spec]` — run the project's `complete.checks` in the spec's
4859
+ // worktree, for `/spec-complete` to relay before it lands. Always exits 0: the
4860
+ // checks inform the completion and never stop it (`env/checks.js`).
4861
+ function specEnvChecks(dir, config, specArg, flags = {}) {
4862
+ const spec = resolveSpecWithWorktree(dir, config, specArg)
4863
+ const { runChecks, formatChecks } = require('./env/checks.js')
4864
+ const results = runChecks(config.complete.checks, { cwd: spec.projectPath || spec.worktreePath })
4865
+ if (flags.json) {
4866
+ process.stdout.write(JSON.stringify({ spec: spec.folder, checks: results }, null, 2) + '\n')
4867
+ return
4868
+ }
4869
+ process.stdout.write(formatChecks(spec.folder, results) + '\n')
4870
+ }
4871
+
4626
4872
  function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
4627
4873
  const spec = resolveSpecWithWorktree(dir, config, specArg)
4628
4874
 
@@ -6053,12 +6299,16 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6053
6299
  // spec with no branch to put live (decision 6), so it carries neither key and
6054
6300
  // renders exactly as it did before this existed.
6055
6301
  const surfaceArgs = docs ? {} : { live, tiers: pageTiers(config) }
6302
+ // The words beside the base when a gap pin chose it; asked only where a base
6303
+ // is shown, which is the branch range.
6304
+ const baseGap = () => gapNote(config, trimmed)
6056
6305
  let data = collectReview({
6057
6306
  spec,
6058
6307
  git,
6059
6308
  mode,
6060
6309
  ref,
6061
6310
  base,
6311
+ baseGap: base ? baseGap() : null,
6062
6312
  now,
6063
6313
  notes,
6064
6314
  gate,
@@ -6102,6 +6352,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6102
6352
  mode: 'branch',
6103
6353
  ref: mergeBase,
6104
6354
  base: fallbackBase,
6355
+ baseGap: baseGap(),
6105
6356
  now,
6106
6357
  notes,
6107
6358
  gate,
@@ -6300,6 +6551,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6300
6551
  mode,
6301
6552
  base,
6302
6553
  fellBack,
6554
+ baseGap: data.baseGap,
6303
6555
  // The paths a committing verdict on this page must commit, so the
6304
6556
  // skill that routes on it never recomputes the set the reader saw.
6305
6557
  // Absent for every other mode, which keeps their output identical.
@@ -6376,6 +6628,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6376
6628
  `spec-env review: ${spec.folder} (${
6377
6629
  fellBack ? `working tree clean — since ${base}` : mode === 'branch' ? `since ${base}` : 'uncommitted'
6378
6630
  })\n` +
6631
+ (data.baseGap ? ` base: ${base} — ${data.baseGap}\n` : '') +
6379
6632
  ` ${t.files} file${t.files === 1 ? '' : 's'}, +${t.additions} -${t.deletions}\n` +
6380
6633
  (merged
6381
6634
  ? ` merged: ${merged.accepted} accept${merged.accepted === 1 ? '' : 's'}, ` +
@@ -7916,6 +8169,8 @@ async function specEnv(rest) {
7916
8169
  else if (args[i] === '--cwd') flags.cwd = args[++i]
7917
8170
  else if (args[i] === '--command') flags.command = args[++i] ?? ''
7918
8171
  else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
8172
+ else if (args[i] === '--use-fallback') flags.useFallback = true
8173
+ else if (args[i] === '--unpin') flags.unpin = true
7919
8174
  else positional.push(args[i])
7920
8175
  }
7921
8176
  dir = path.resolve(dir)
@@ -7987,6 +8242,40 @@ async function specEnv(rest) {
7987
8242
  }
7988
8243
  }
7989
8244
 
8245
+ // A gap pin a match has retired is deleted here, the one point every
8246
+ // subcommand passes, so it cannot outlive the gap even when nobody runs
8247
+ // `spec-env base`. Only asked when a pin exists, so the common path pays
8248
+ // nothing. The resolver already ignores it; this just tidies the file.
8249
+ if (config.gapPin && describeBaseBranch(config, gitReader(dir)).stalePin) {
8250
+ clearBasePin(dir, config)
8251
+ flags.pinRetired = true
8252
+ }
8253
+
8254
+ try {
8255
+ await specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom)
8256
+ } catch (error) {
8257
+ if (!(error instanceof BaseUnresolvedError)) throw error
8258
+ baseRefusal(sub, error, flags)
8259
+ }
8260
+ }
8261
+
8262
+ // A base that will not resolve, said with the way out where the engine has one
8263
+ // (`.claude/rules/offered-unblocks.md`): the refusal first, then the offer.
8264
+ // stdout and exit 1, so a skill reads it whether or not it asked for --json.
8265
+ function baseRefusal(sub, error, flags) {
8266
+ process.exitCode = 1
8267
+ if (flags.json) {
8268
+ const out = { blocked: true, reason: error.refused }
8269
+ if (error.offer) out.offer = error.offer
8270
+ process.stdout.write(JSON.stringify(out, null, 2) + '\n')
8271
+ return
8272
+ }
8273
+ const lines = [`spec-env ${sub}: ${error.refused}`]
8274
+ if (error.offer) lines.push(` offer: ${error.offer.label} — ${error.offer.command}`)
8275
+ process.stdout.write(lines.join('\n') + '\n')
8276
+ }
8277
+
8278
+ async function specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom) {
7990
8279
  switch (sub) {
7991
8280
  case 'up':
7992
8281
  specEnvUp(dir, config, positional[0], flags)
@@ -8033,12 +8322,18 @@ async function specEnv(rest) {
8033
8322
  case 'resolve':
8034
8323
  specEnvResolve(dir, config, positional[0], flags)
8035
8324
  break
8325
+ case 'resume':
8326
+ specEnvResume(dir, config, positional[0], flags)
8327
+ break
8036
8328
  case 'base':
8037
8329
  specEnvBase(dir, config, flags)
8038
8330
  break
8039
8331
  case 'stage':
8040
8332
  specEnvStage(dir, config, positional[0], flags, invokedFrom)
8041
8333
  break
8334
+ case 'checks':
8335
+ specEnvChecks(dir, config, positional[0], flags)
8336
+ break
8042
8337
  case 'review':
8043
8338
  // `serve` is the one review sub-action rather than a verb of its own: it
8044
8339
  // answers the same question ("show me this diff") from the same engine,
@@ -8203,7 +8498,7 @@ async function run(argv) {
8203
8498
  break
8204
8499
  }
8205
8500
  if (action === 'resync') {
8206
- resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
8501
+ resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
8207
8502
  break
8208
8503
  }
8209
8504
  // action === 'create-missing' → fall through to a normal (skip-existing) init.
@@ -8230,6 +8525,7 @@ async function run(argv) {
8230
8525
  workspaceMode,
8231
8526
  gating,
8232
8527
  project: opts.project,
8528
+ local: opts.local,
8233
8529
  })
8234
8530
  break
8235
8531
  }
@@ -8241,7 +8537,7 @@ async function run(argv) {
8241
8537
  checkSync(dir, { claudeMd: opts.claudeMd })
8242
8538
  break
8243
8539
  }
8244
- resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
8540
+ resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
8245
8541
  await cleanupReleaseTooling(dir, opts)
8246
8542
  break
8247
8543
  default:
package/src/env/base.js CHANGED
@@ -5,14 +5,16 @@
5
5
  * which in-flight specs forked from an older one.
6
6
  *
7
7
  * Pure: the CLI fetches, reads refs and computes merge-bases, and hands the
8
- * facts in. Nothing here touches git, and nothing here edits config — pinning
9
- * is a hand edit of `baseBranch`, deliberately without a verb (the pin is the
10
- * exception, so it does not get one).
8
+ * facts in. Nothing here touches git, and nothing here edits config — a
9
+ * permanent pin is a hand edit of `baseBranch`, deliberately without a verb.
10
+ * The gap pin is different (`env/basepin.js`): local, temporary, and retired by
11
+ * the next match, so `--use-fallback` and `--unpin` are its verbs.
11
12
  */
12
13
 
13
14
  const HOW = Object.freeze({
14
15
  pin: 'pinned by baseBranch',
15
16
  pattern: 'newest match',
17
+ 'gap-pin': 'pinned for the gap',
16
18
  'origin-head': 'origin/HEAD',
17
19
  local: 'local branch',
18
20
  fallback: 'nothing detected — default',
@@ -44,7 +46,10 @@ function forkMatch(matches, mergeBase, isAncestor) {
44
46
  /**
45
47
  * Build the report. `facts`:
46
48
  * { pattern, remote, base, how, fetch: { ok, reason } | null,
47
- * matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }] }
49
+ * matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }],
50
+ * pin: { base, pattern, pinnedAt } | null — the gap pin in force,
51
+ * pinCleared: bool — a match retired a pin on this run,
52
+ * offer: { kind, label, command } | null — no match and no pin }
48
53
  * Returns `{ json, lines }`; the CLI prints one of them and always exits 0.
49
54
  */
50
55
  function planBaseReport(facts) {
@@ -67,6 +72,9 @@ function planBaseReport(facts) {
67
72
  fetch,
68
73
  matches: matches.map((m) => ({ ...m, base: m.name === base })),
69
74
  stale,
75
+ pin: how === 'gap-pin' ? facts.pin || null : null,
76
+ pinCleared: Boolean(facts.pinCleared),
77
+ offer: facts.offer || null,
70
78
  }
71
79
 
72
80
  const lines = []
@@ -75,7 +83,8 @@ function planBaseReport(facts) {
75
83
  return { json, lines }
76
84
  }
77
85
 
78
- if (base) lines.push(`spec-env base: ${base} (${HOW[how]}${how === 'pin' ? ` — ${pattern} not used` : ` for ${pattern}`})`)
86
+ if (how === 'gap-pin') lines.push(`spec-env base: ${base} — no ${pattern} branch on ${remote} (${HOW[how]})`)
87
+ else if (base) lines.push(`spec-env base: ${base} (${HOW[how]}${how === 'pin' ? ` — ${pattern} not used` : ` for ${pattern}`})`)
79
88
  else lines.push(`spec-env base: none — no branch on ${remote} matches ${pattern}`)
80
89
 
81
90
  if (fetch) {
@@ -94,6 +103,13 @@ function planBaseReport(facts) {
94
103
  }
95
104
  }
96
105
 
106
+ if (how === 'gap-pin') {
107
+ const since = facts.pin && facts.pin.pinnedAt ? ` since ${facts.pin.pinnedAt.slice(0, 10)}` : ''
108
+ lines.push(` pinned${since} · clears itself when a ${pattern} branch appears · --unpin removes it now`)
109
+ }
110
+ if (facts.pinCleared) lines.push(` gap pin cleared — ${base} matches ${pattern}`)
111
+ if (!base && facts.offer) lines.push(` offer: ${facts.offer.label} — ${facts.offer.command}`)
112
+
97
113
  if (stale.length) {
98
114
  lines.push(' forked from an older match:')
99
115
  for (const s of stale) lines.push(` ${s.spec} · forked from ${s.forkedFrom}`)