@skitterbyte/skitterspec-linear 19.13.0 → 19.15.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.
@@ -325,8 +325,11 @@ through to a documented conservative default; see the field notes below.
325
325
  // - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
326
326
  // rc/a/b. Spell each segment ("20??/Q?").
327
327
  // - No match REFUSES, naming `spec-env base` — it never falls back to
328
- // origin/HEAD, because zero matches usually means "not fetched", and
329
- // the default branch is exactly where a rolling base must not land.
328
+ // origin/HEAD UNASKED, because zero matches usually means "not
329
+ // fetched", and the default branch is exactly where a rolling base must
330
+ // not land by accident. Between rcs (one merged, the next not cut) the
331
+ // refusal OFFERS `baseBranchFallback` below; accepting it pins that
332
+ // branch locally until a match appears, for every command at once.
330
333
  // - Newest-by-date is only right when one rc is live at a time (the next
331
334
  // is cut after the last merges). If your rcs overlap, pin `baseBranch`.
332
335
  // - A spec that outlived a roll lands on the new rc; the integrate plan
@@ -336,6 +339,17 @@ through to a documented conservative default; see the field notes below.
336
339
  // `spec-env base` lists the matches, the base, and specs on an older one.
337
340
  "baseBranchPattern": "",
338
341
 
342
+ // The branch OFFERED as the base while `baseBranchPattern` matches nothing —
343
+ // the gap between one rc merging and the next being cut. Empty = the
344
+ // remote's default branch (`<land.remote>/HEAD`). It is never used unasked:
345
+ // the refusal offers it, and accepting (`spec-env base --use-fallback`)
346
+ // writes a local, gitignored pin in `.spec-env/base-pin.json` that clears
347
+ // itself the moment a branch matches again. Name a branch here when you
348
+ // release from something other than the default (a test branch). A value
349
+ // that names no branch, or neither resolving, means no offer — a plain
350
+ // refusal, because a guessed base is worse. Ignored without a pattern.
351
+ "baseBranchFallback": "",
352
+
339
353
  // How a finished branch reaches the base branch.
340
354
  // strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
341
355
  // exactly as always; nothing below applies.
@@ -526,7 +540,8 @@ through to a documented conservative default; see the field notes below.
526
540
  // SKITTERSPEC_READER=local|remote in the environment outranks this key: a
527
541
  // wrapper that runs the engine on another machine (a VM's `prlctl exec`)
528
542
  // speaks for that machine alone. A reader on another machine — this key or
529
- // that variable set to "remote", or ssh — gets no `local` tier while
543
+ // that variable set to "remote", ssh, or a Windows session with no desktop
544
+ // (no SESSIONNAME: `prlctl exec`, sshd, a scheduled task) — gets no `local` tier while
530
545
  // `network` has a URL, since 127.0.0.1 is the engine's machine.
531
546
  // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
532
547
  // you are reading, and no signal outranks being told. Detection is only the
@@ -3373,7 +3373,8 @@ a.ticket:hover { border-color: var(--accent); }
3373
3373
  part(data.branch)
3374
3374
  sep()
3375
3375
  part(data.mode === 'branch'
3376
- ? 'everything since ' + data.base + (data.fellBack ? ' (working tree clean)' : '')
3376
+ ? 'everything since ' + data.base + (data.fellBack ? ' (working tree clean)' : '') +
3377
+ (data.baseGap ? ' — ' + data.baseGap : '')
3377
3378
  : data.mode === 'docs'
3378
3379
  ? "the spec's own documents"
3379
3380
  : 'uncommitted work')
@@ -55,6 +55,28 @@ offer's `label`, and Cancel.
55
55
  something easier-sounding, never pre-select it, and never add a third option. A
56
56
  bypass that arrives pre-selected is a bypass by default wearing a question mark.
57
57
 
58
+ ### A worked `satisfy`: the gap between release branches
59
+
60
+ Under `baseBranchPattern`, a base nobody can resolve refuses — and where the
61
+ last release branch has merged and the next is not yet cut, that refusal is the
62
+ normal state of the repo for a while, not a mistake. So the engine declares:
63
+
64
+ ```json
65
+ {
66
+ "blocked": true,
67
+ "reason": "no branch matches 20??/Q? — run spec-env base to fetch",
68
+ "offer": { "kind": "satisfy", "label": "Use master as the base for now", "command": "skitterspec spec-env base --use-fallback" }
69
+ }
70
+ ```
71
+
72
+ Text output carries the same thing as an `offer:` line under the refusal. On
73
+ the pick, run the command and retry the command that refused. It is `satisfy`
74
+ because it gives the guard what it asked for — a base — and the pick is kept as
75
+ a local pin that every command then honours, so it is asked once per gap rather
76
+ than once per command. The pin clears itself when a branch matches again, so
77
+ nothing about it needs recording. No fallback resolvable means no `offer`, and
78
+ the refusal stands alone.
79
+
58
80
  ## A bypass is offered once per obligation
59
81
 
60
82
  The engine enforces this; a skill does not count anything. Spend the offer by
@@ -171,13 +171,22 @@ engine runs on one machine and the reader is on another — a wrapper running it
171
171
  inside a VM, or an ssh session — `127.0.0.1` is the engine's machine, not the
172
172
  reader's. That door never opens, whatever anyone asks. It was also first in the
173
173
  stack, the link habit reaches for, and it cost a timeout on every review. So the
174
- engine hides it, on a signal someone set on purpose: `SKITTERSPEC_READER=remote`
175
- (`local` outranks ssh), the committed `review.reader`, or ssh. It hides it only
174
+ engine hides it, on `SKITTERSPEC_READER=remote` (`local` outranks everything
175
+ below it), the committed `review.reader`, ssh, or a Windows session with no
176
+ desktop (no `SESSIONNAME`, which is what `prlctl exec`, the OpenSSH server and a
177
+ scheduled task all look like). It hides it only
176
178
  when `network` has a URL to take its place; otherwise the line stays and says
177
- it is unreachable. Detection decides nothing here, and nor does the skill. A
178
- tier marked `hidden` in `--json` is absent from the printed stack, so copying
179
- the stack still produces the right banner. The holding line names the engine's
180
- `covers` — *the wait covers network* — never a door the stack did not show.
179
+ it is unreachable.
180
+
181
+ **That last signal is detection, allowed here for what a wrong guess costs.** The network URL is the same server, so it opens from
182
+ the engine's own machine too. A reader wrongly judged to be elsewhere gets the
183
+ second-best link, never a page that will not open. Detection has done harm
184
+ before when it decided whether to *serve*, because a wrong guess there removed
185
+ the verdict loop. Nothing like that is at stake here. The skill still decides
186
+ nothing. A tier marked `hidden` in `--json` is absent from the printed stack, so
187
+ copying the stack still produces the right banner. The holding line names the
188
+ engine's `covers` — *the wait covers network* — never a door the stack did not
189
+ show.
181
190
 
182
191
  **The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
183
192
  The engine offers the other addresses this machine has (a
@@ -45,6 +45,11 @@ things answering to one name is how a teardown removes the wrong tree.
45
45
  skitterspec spec-env nospec <name>
46
46
  ```
47
47
 
48
+ A refusal naming `no branch matches <pattern>` that carries an `offer:` line
49
+ is the gap between release branches: relay it, then offer it as
50
+ `.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
51
+ the pick run `skitterspec spec-env base --use-fallback` and retry.
52
+
48
53
  It records the name as a **specless branch** and prints the plan. Run the
49
54
  `git worktree add` it prints, then move this session into the worktree with a
50
55
  plain `cd` and run the `then, run:` line where there is one:
@@ -439,7 +439,11 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
439
439
  relay it verbatim in the `Landed` row so the reader sees where the work went.
440
440
 
441
441
  A refusal naming `no branch matches <pattern>` means no release candidate is
442
- visible — usually not fetched. Relay it, stop with `⏸`, and name
442
+ visible. Where it carries an `offer:` line it is the gap between release
443
+ branches: relay it, then offer it as `.claude/rules/offered-unblocks.md`
444
+ describes — its label and Cancel — and on the pick run
445
+ `skitterspec spec-env base --use-fallback` and retry the land. With no offer
446
+ it is usually not fetched: relay it, stop with `⏸`, and name
443
447
  `skitterspec spec-env base` (it fetches and lists) as the next step.
444
448
  3. **Run the after-land commands.** Where the plan ends with a
445
449
  `then, in the primary checkout (<path>), run:` section — the project's
@@ -470,6 +470,11 @@ skitterspec spec-env review <spec> --run-reviewers # …and run review.reviewe
470
470
  skitterspec spec-env review serve # every spec, on localhost
471
471
  ```
472
472
 
473
+ A refusal naming `no branch matches <pattern>` that carries an `offer:` line
474
+ is the gap between release branches: relay it, then offer it as
475
+ `.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
476
+ the pick run `skitterspec spec-env base --use-fallback` and render again.
477
+
473
478
  **`--run-reviewers` is opt-in here, and a BARE `/spec-diff` MUST NOT PASS IT.**
474
479
  `/spec-next` runs the project's configured reviewers once per phase, where the
475
480
  cost is paid against work that is finished. This skill answers at any point,
@@ -62,6 +62,11 @@ branch and that is always the operator's call.
62
62
  **A refused capture loses nothing.** The engine prints the text back. Put it in
63
63
  the `Why` row verbatim so the user can copy it.
64
64
 
65
+ A refusal naming `no branch matches <pattern>` that carries an `offer:` line
66
+ is the gap between release branches: relay it, then offer it as
67
+ `.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
68
+ the pick run `skitterspec spec-env base --use-fallback` and retry.
69
+
65
70
  ## 3. List
66
71
 
67
72
  ```
@@ -156,8 +156,12 @@ render says so. On **`--plan`** this step does not run at all.
156
156
  the primary checkout is not on the newest release candidate the plan says
157
157
  `fork: <base> (the base — the primary checkout is on <old>)` and forks from
158
158
  it. Relay that line in the `Branch` row. A refusal naming
159
- `no branch matches <pattern>` means no release candidate is visible —
160
- usually not fetched: relay it, stop with `⏸`, and name
159
+ `no branch matches <pattern>` means no release candidate is visible. Where
160
+ it carries an `offer:` line it is the gap between release branches: relay
161
+ it, then offer it as `.claude/rules/offered-unblocks.md` describes — its
162
+ label and Cancel — and on the pick run
163
+ `skitterspec spec-env base --use-fallback` and re-run `up`. With no offer it
164
+ is usually not fetched: relay it, stop with `⏸`, and name
161
165
  `skitterspec spec-env base` (it fetches and lists) as the next step.
162
166
 
163
167
  2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
@@ -112,7 +112,11 @@ can carry two more things, and both are the engine's to say:
112
112
  relay it verbatim in the `Landed` row so the reader sees where the work went.
113
113
 
114
114
  A refusal naming `no branch matches <pattern>` means no release candidate is
115
- visible — usually not fetched. Relay it, stop with `⏸`, and name
115
+ visible. Where it carries an `offer:` line it is the gap between release
116
+ branches: relay it, then offer it as `.claude/rules/offered-unblocks.md`
117
+ describes — its label and Cancel — and on the pick run
118
+ `skitterspec spec-env base --use-fallback` and retry the land. With no offer it
119
+ is usually not fetched: relay it, stop with `⏸`, and name
116
120
  `skitterspec spec-env base` (it fetches and lists) as the next step.
117
121
 
118
122
  **Then run the after-land commands.** Where the plan ends with a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.13.0",
3
+ "version": "19.15.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -51,6 +51,7 @@ const SPEC_ENV_VERBS = Object.freeze([
51
51
  'project',
52
52
  ])
53
53
  const { forkMatch, planBaseReport } = require('./env/base.js')
54
+ const { readBasePin, writeBasePin, clearBasePin } = require('./env/basepin.js')
54
55
  const {
55
56
  readRegistry,
56
57
  writeRegistry,
@@ -66,6 +67,8 @@ const {
66
67
  resolveSpecless,
67
68
  resolveBaseBranch,
68
69
  describeBaseBranch,
70
+ BaseUnresolvedError,
71
+ gapNote,
69
72
  baseRemote,
70
73
  liveWorktreePaths,
71
74
  collectSpecFolders,
@@ -338,6 +341,8 @@ Usage:
338
341
  base fetch, list baseBranchPattern matches
339
342
  newest-first, mark the base, and name
340
343
  specs forked from an older match
344
+ (--use-fallback pins the fallback
345
+ while nothing matches; --unpin)
341
346
  skitterspec status What is in flight here: every spec with a worktree,
342
347
  its bucket and phase progress read from that
343
348
  worktree (--json). Offline; always exits 0.
@@ -590,6 +595,10 @@ function provisionedSpecs(dir, config) {
590
595
 
591
596
  function specEnvStatus(dir, config) {
592
597
  const provisioned = provisionedSpecs(dir, config)
598
+ // A base held on the fallback is worth one line wherever work is listed: it
599
+ // is the state every fork and land is in until the next release branch.
600
+ const gap = gapNote(config, gitReader(dir))
601
+ if (gap) process.stdout.write(`spec-env: base ${config.gapPin.base} — ${gap}\n`)
593
602
 
594
603
  // REACHED EITHER WAY. This used to return here, so a repo with nothing in
595
604
  // flight could say nothing about a waiting pass — and a repo with nothing in
@@ -1029,7 +1038,7 @@ async function serveTadaPage({ window, flags, recap }) {
1029
1038
  const q = tadaQuery({ ...flags, on: flags.on || (flags.since ? null : localDay(window.since)) })
1030
1039
  const withQ = (u) => (u ? `${u}${q}` : u)
1031
1040
  const page = { ...served, loopbackUrl: withQ(served.loopbackUrl), url: withQ(served.url), alternates: (served.alternates || []).map(withQ) }
1032
- const reader = resolveReader(config, process.env)
1041
+ const reader = resolveReader(config, process.env, process.platform)
1033
1042
  const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config, reader })
1034
1043
  process.stdout.write(`page: ${humanLabel(window)}\n${reviewStackText(tiers)}`)
1035
1044
  return true
@@ -1135,7 +1144,7 @@ function epicPageTiers(inputs, up, epic) {
1135
1144
  if (!inputs.config) return null
1136
1145
  if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
1137
1146
  const served = reviewServedUrls(up, offerableLanAddresses(), epic)
1138
- const reader = resolveReader(inputs.config, process.env)
1147
+ const reader = resolveReader(inputs.config, process.env, process.platform)
1139
1148
  return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config, reader }) }
1140
1149
  }
1141
1150
 
@@ -3135,7 +3144,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
3135
3144
  }
3136
3145
  const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
3137
3146
  ` base: ${base}`, ` branch: ${cplan.branch}`,
3138
- ...retargetLines(retarget),
3147
+ ...retargetLines(retarget), ...gapLines(config, gitReader(dir)),
3139
3148
  ...reverifyLines(dir, spec, base, dir), '',
3140
3149
  ' run these (abort the rebase on conflict):']
3141
3150
  for (const cmd of cplan.commands) cout.push(` ${cmd}`)
@@ -3250,7 +3259,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
3250
3259
  out.push(` base: ${plan.base}`)
3251
3260
  out.push(` branch: ${plan.branch}`)
3252
3261
  out.push(` worktree: ${spec.worktreePath}`)
3253
- out.push(...retargetLines(retarget))
3262
+ out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
3254
3263
  if (primarySwitch) out.push(` primary: on ${primarySwitch.from} — switched to ${base} before the land`)
3255
3264
  out.push(...reverifyLines(dir, spec, baseRef, spec.projectPath || spec.worktreePath))
3256
3265
  out.push('')
@@ -3304,6 +3313,13 @@ function retargetLines(retarget) {
3304
3313
  return retarget ? [` retarget: forked from ${retarget.from} · landing onto ${retarget.to}`] : []
3305
3314
  }
3306
3315
 
3316
+ // Said under `base:` when a gap pin chose it, so a land onto the fallback is
3317
+ // never mistaken for a land onto a release branch. Nothing otherwise.
3318
+ function gapLines(config, git) {
3319
+ const note = gapNote(config, git)
3320
+ return note ? [` gap: ${note}`] : []
3321
+ }
3322
+
3307
3323
  // Is the primary checkout sitting on an older rolling-base match? Positive
3308
3324
  // signal only: the branch it has out must itself match `baseBranchPattern`
3309
3325
  // (locally or on the remote). Anything else — a live spec, a detached HEAD, no
@@ -3438,7 +3454,7 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
3438
3454
  out.push(` base: ${remote}/${base}`)
3439
3455
  out.push(` branch: ${plan.branch}`)
3440
3456
  out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
3441
- out.push(...retargetLines(retarget))
3457
+ out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
3442
3458
  // Silent on cannot-tell: a line about a lookup that failed accuses nothing
3443
3459
  // and helps nobody — the placeholder in the commands already degrades.
3444
3460
  if (pr.state === 'none') out.push(' pr: none yet')
@@ -4470,18 +4486,26 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
4470
4486
  }
4471
4487
 
4472
4488
  /**
4473
- * `skitterspec spec-env base [--json]`
4489
+ * `skitterspec spec-env base [--json] [--use-fallback | --unpin]`
4474
4490
  *
4475
4491
  * Which branch is the base, how it was found, and — under `baseBranchPattern` —
4476
4492
  * every match newest-first plus the provisioned specs that forked from an older
4477
4493
  * one. It fetches first, because the resolver itself never does: a release
4478
4494
  * candidate cut since the last fetch is invisible to it.
4479
4495
  *
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`.
4496
+ * Bare, it lists only and always exits 0; the one thing it writes is deleting a
4497
+ * gap pin a match has retired. A failed fetch is reported and the listing
4498
+ * carries on from the refs already here.
4499
+ *
4500
+ * `--use-fallback` is the offer's command: it writes the gap pin
4501
+ * (`env/basepin.js`) when the pattern matches nothing and a fallback resolves.
4502
+ * `--unpin` removes it. Both exit 1 on a refusal, since a caller retries on 0.
4503
+ * A permanent pin stays a hand edit of `baseBranch`.
4483
4504
  */
4484
4505
  function specEnvBase(dir, config, flags = {}) {
4506
+ if (flags.useFallback) return baseUseFallback(dir, config, flags)
4507
+ if (flags.unpin) return baseUnpin(dir, config, flags)
4508
+
4485
4509
  const pattern = (config.baseBranchPattern || '').trim()
4486
4510
  const remote = baseRemote(config)
4487
4511
  const git = gitReader(dir)
@@ -4489,7 +4513,9 @@ function specEnvBase(dir, config, flags = {}) {
4489
4513
  // No pattern: the base is today's chain, and there is nothing to fetch for —
4490
4514
  // origin/HEAD is not updated by a fetch.
4491
4515
  const fetch = fetchForPattern(dir, config)
4492
- const { base, how } = describeBaseBranch(config, git)
4516
+ const pin = pattern ? readBasePin(dir, config) : null
4517
+ const { base, how, stalePin, refused } = describeBaseBranch(config, git, pin)
4518
+ const pinCleared = Boolean(flags.pinRetired) || (Boolean(stalePin) && clearBasePin(dir, config))
4493
4519
 
4494
4520
  let matches = []
4495
4521
  let forks = []
@@ -4502,10 +4528,74 @@ function specEnvBase(dir, config, flags = {}) {
4502
4528
  }))
4503
4529
  }
4504
4530
 
4505
- const { json, lines } = planBaseReport({ pattern, remote, base, how, fetch, matches, forks })
4531
+ const { json, lines } = planBaseReport({
4532
+ pattern,
4533
+ remote,
4534
+ base,
4535
+ how,
4536
+ fetch,
4537
+ matches,
4538
+ forks,
4539
+ pin,
4540
+ pinCleared,
4541
+ offer: refused ? refused.offer : null,
4542
+ })
4506
4543
  process.stdout.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
4507
4544
  }
4508
4545
 
4546
+ // One answer for both pin verbs: a line of text, or `{ ok, ... }` as JSON.
4547
+ function basePinAnswer(flags, ok, line, extra = {}) {
4548
+ if (!ok) process.exitCode = 1
4549
+ process.stdout.write(flags.json ? JSON.stringify({ ok, ...extra, message: line }, null, 2) + '\n' : line + '\n')
4550
+ }
4551
+
4552
+ // WHAT WOULD FOOL THIS: an unfetched remote looks exactly like the gap — no
4553
+ // branch matches in either case. So it fetches first and will not pin on a
4554
+ // failed fetch: a pin made then could hold the base on the fallback while the
4555
+ // next release branch already exists on the remote.
4556
+ function baseUseFallback(dir, config, flags) {
4557
+ const pattern = (config.baseBranchPattern || '').trim()
4558
+ if (!pattern) {
4559
+ return basePinAnswer(flags, false, 'spec-env base: no baseBranchPattern is set — there is no gap to pin.')
4560
+ }
4561
+ const fetch = fetchForPattern(dir, config)
4562
+ if (fetch && !fetch.ok) {
4563
+ return basePinAnswer(
4564
+ flags,
4565
+ false,
4566
+ `spec-env base: fetch from ${baseRemote(config)} failed${fetch.reason ? ` (${fetch.reason})` : ''} — ` +
4567
+ `cannot tell whether a ${pattern} branch exists, so nothing was pinned.`,
4568
+ )
4569
+ }
4570
+ // null, not the attached pin: the question is whether the PATTERN matches.
4571
+ const { base, refused } = describeBaseBranch(config, gitReader(dir), null)
4572
+ if (base) {
4573
+ clearBasePin(dir, config)
4574
+ return basePinAnswer(flags, false, `spec-env base: ${base} matches ${pattern} — no gap to pin; it is the base.`, { base })
4575
+ }
4576
+ if (!refused || !refused.fallback) {
4577
+ return basePinAnswer(
4578
+ flags,
4579
+ false,
4580
+ `spec-env base: no branch matches ${pattern}, and no fallback resolves — set baseBranchFallback, ` +
4581
+ `or run git remote set-head ${baseRemote(config)} --auto.`,
4582
+ )
4583
+ }
4584
+ const pin = writeBasePin(dir, config, { base: refused.fallback, pattern })
4585
+ basePinAnswer(
4586
+ flags,
4587
+ true,
4588
+ `spec-env base: pinned ${pin.base} for the gap — no ${pattern} branch on ${baseRemote(config)}. ` +
4589
+ `It clears itself when one appears.`,
4590
+ { base: pin.base, pin },
4591
+ )
4592
+ }
4593
+
4594
+ function baseUnpin(dir, config, flags) {
4595
+ const removed = clearBasePin(dir, config)
4596
+ basePinAnswer(flags, true, removed ? 'spec-env base: gap pin removed.' : 'spec-env base: no gap pin to remove.', { removed })
4597
+ }
4598
+
4509
4599
  // Fetch the base's remote, but only where `baseBranchPattern` decides the base:
4510
4600
  // the resolver reads remote-tracking refs and never the network, so a release
4511
4601
  // candidate cut since the last fetch is invisible until something fetches. With
@@ -4878,7 +4968,7 @@ function reshowStack(dir, config, spec, out) {
4878
4968
  const cfg = withSpecRemote(config, out)
4879
4969
  const up = readRunningReviewServer(dir, cfg)
4880
4970
  const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
4881
- const reader = resolveReader(cfg, process.env)
4971
+ const reader = resolveReader(cfg, process.env, process.platform)
4882
4972
  const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg, reader })
4883
4973
  let live = null
4884
4974
  try {
@@ -6053,12 +6143,16 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6053
6143
  // spec with no branch to put live (decision 6), so it carries neither key and
6054
6144
  // renders exactly as it did before this existed.
6055
6145
  const surfaceArgs = docs ? {} : { live, tiers: pageTiers(config) }
6146
+ // The words beside the base when a gap pin chose it; asked only where a base
6147
+ // is shown, which is the branch range.
6148
+ const baseGap = () => gapNote(config, trimmed)
6056
6149
  let data = collectReview({
6057
6150
  spec,
6058
6151
  git,
6059
6152
  mode,
6060
6153
  ref,
6061
6154
  base,
6155
+ baseGap: base ? baseGap() : null,
6062
6156
  now,
6063
6157
  notes,
6064
6158
  gate,
@@ -6102,6 +6196,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6102
6196
  mode: 'branch',
6103
6197
  ref: mergeBase,
6104
6198
  base: fallbackBase,
6199
+ baseGap: baseGap(),
6105
6200
  now,
6106
6201
  notes,
6107
6202
  gate,
@@ -6217,7 +6312,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6217
6312
  const url = readReviewUrl(out)
6218
6313
 
6219
6314
  // Resolved before the --json early return, so both outputs agree.
6220
- const reader = resolveReader(config, process.env)
6315
+ const reader = resolveReader(config, process.env, process.platform)
6221
6316
 
6222
6317
  // A remote reader cannot open a path on this machine — that is the whole of
6223
6318
  // what detection established. Serving is how the engine answers it: a local
@@ -6300,6 +6395,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6300
6395
  mode,
6301
6396
  base,
6302
6397
  fellBack,
6398
+ baseGap: data.baseGap,
6303
6399
  // The paths a committing verdict on this page must commit, so the
6304
6400
  // skill that routes on it never recomputes the set the reader saw.
6305
6401
  // Absent for every other mode, which keeps their output identical.
@@ -6376,6 +6472,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6376
6472
  `spec-env review: ${spec.folder} (${
6377
6473
  fellBack ? `working tree clean — since ${base}` : mode === 'branch' ? `since ${base}` : 'uncommitted'
6378
6474
  })\n` +
6475
+ (data.baseGap ? ` base: ${base} — ${data.baseGap}\n` : '') +
6379
6476
  ` ${t.files} file${t.files === 1 ? '' : 's'}, +${t.additions} -${t.deletions}\n` +
6380
6477
  (merged
6381
6478
  ? ` merged: ${merged.accepted} accept${merged.accepted === 1 ? '' : 's'}, ` +
@@ -7916,6 +8013,8 @@ async function specEnv(rest) {
7916
8013
  else if (args[i] === '--cwd') flags.cwd = args[++i]
7917
8014
  else if (args[i] === '--command') flags.command = args[++i] ?? ''
7918
8015
  else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
8016
+ else if (args[i] === '--use-fallback') flags.useFallback = true
8017
+ else if (args[i] === '--unpin') flags.unpin = true
7919
8018
  else positional.push(args[i])
7920
8019
  }
7921
8020
  dir = path.resolve(dir)
@@ -7987,6 +8086,40 @@ async function specEnv(rest) {
7987
8086
  }
7988
8087
  }
7989
8088
 
8089
+ // A gap pin a match has retired is deleted here, the one point every
8090
+ // subcommand passes, so it cannot outlive the gap even when nobody runs
8091
+ // `spec-env base`. Only asked when a pin exists, so the common path pays
8092
+ // nothing. The resolver already ignores it; this just tidies the file.
8093
+ if (config.gapPin && describeBaseBranch(config, gitReader(dir)).stalePin) {
8094
+ clearBasePin(dir, config)
8095
+ flags.pinRetired = true
8096
+ }
8097
+
8098
+ try {
8099
+ await specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom)
8100
+ } catch (error) {
8101
+ if (!(error instanceof BaseUnresolvedError)) throw error
8102
+ baseRefusal(sub, error, flags)
8103
+ }
8104
+ }
8105
+
8106
+ // A base that will not resolve, said with the way out where the engine has one
8107
+ // (`.claude/rules/offered-unblocks.md`): the refusal first, then the offer.
8108
+ // stdout and exit 1, so a skill reads it whether or not it asked for --json.
8109
+ function baseRefusal(sub, error, flags) {
8110
+ process.exitCode = 1
8111
+ if (flags.json) {
8112
+ const out = { blocked: true, reason: error.refused }
8113
+ if (error.offer) out.offer = error.offer
8114
+ process.stdout.write(JSON.stringify(out, null, 2) + '\n')
8115
+ return
8116
+ }
8117
+ const lines = [`spec-env ${sub}: ${error.refused}`]
8118
+ if (error.offer) lines.push(` offer: ${error.offer.label} — ${error.offer.command}`)
8119
+ process.stdout.write(lines.join('\n') + '\n')
8120
+ }
8121
+
8122
+ async function specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom) {
7990
8123
  switch (sub) {
7991
8124
  case 'up':
7992
8125
  specEnvUp(dir, config, positional[0], flags)
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}`)
@@ -0,0 +1,62 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The gap pin: a local record that someone accepted "use <fallback> as the base
5
+ * for now" while `baseBranchPattern` matched nothing — the gap between one
6
+ * release branch merging and the next being cut.
7
+ *
8
+ * It lives in `.spec-env/base-pin.json` in the primary checkout, gitignored, so
9
+ * accepting the offer changes nobody else's config. It records the pattern it
10
+ * was made under, and the resolver honours it only while that pattern has no
11
+ * match (`describeBaseBranch`), so cutting the next release branch is all it
12
+ * takes to retire it. Callers that see a match override it delete the file.
13
+ *
14
+ * Pure file I/O, no git: the resolver decides what a pin means.
15
+ */
16
+
17
+ const fs = require('node:fs')
18
+ const path = require('node:path')
19
+
20
+ // The state dir sits beside the registry file, e.g. `.spec-env` — the same
21
+ // convention `building.js` and `dev.js` use.
22
+ function pinPath(dir, config) {
23
+ const stateDir = path.posix.dirname((config && config.registry) || '.spec-env/registry.json') || '.spec-env'
24
+ return path.join(dir, stateDir, 'base-pin.json')
25
+ }
26
+
27
+ /**
28
+ * The pin as `{ base, pattern, pinnedAt }`, or null. An unreadable or malformed
29
+ * file is no pin: the resolver then refuses and offers again, which is the
30
+ * harmless direction — a pin read wrongly would decide a base nobody chose.
31
+ */
32
+ function readBasePin(dir, config) {
33
+ let parsed
34
+ try {
35
+ parsed = JSON.parse(fs.readFileSync(pinPath(dir, config), 'utf8'))
36
+ } catch {
37
+ return null
38
+ }
39
+ if (!parsed || typeof parsed.base !== 'string' || typeof parsed.pattern !== 'string') return null
40
+ if (!parsed.base.trim() || !parsed.pattern.trim()) return null
41
+ return { base: parsed.base, pattern: parsed.pattern, pinnedAt: typeof parsed.pinnedAt === 'string' ? parsed.pinnedAt : null }
42
+ }
43
+
44
+ function writeBasePin(dir, config, { base, pattern, pinnedAt = new Date().toISOString() }) {
45
+ const file = pinPath(dir, config)
46
+ fs.mkdirSync(path.dirname(file), { recursive: true })
47
+ const pin = { base, pattern, pinnedAt }
48
+ fs.writeFileSync(file, JSON.stringify(pin, null, 2) + '\n')
49
+ return pin
50
+ }
51
+
52
+ /** Remove the pin. True when there was one to remove. */
53
+ function clearBasePin(dir, config) {
54
+ try {
55
+ fs.unlinkSync(pinPath(dir, config))
56
+ return true
57
+ } catch {
58
+ return false
59
+ }
60
+ }
61
+
62
+ module.exports = { pinPath, readBasePin, writeBasePin, clearBasePin }
package/src/env/config.js CHANGED
@@ -44,6 +44,8 @@
44
44
  * baseBranch: "", // "" = auto-detect (origin/HEAD → main → master)
45
45
  * baseBranchPattern: "", // glob over remote branch names; newest match
46
46
  * // by commit date is the base (rolling release-candidate)
47
+ * baseBranchFallback: "", // offered as the base while the pattern matches
48
+ * // nothing; "" = the remote's default branch
47
49
  * land: { strategy, remote, draft, specDocs }, // how a branch lands:
48
50
  * // "ff" (default, trunk-based local fast-forward) or "pr"
49
51
  * // (push + pull request; base moves when the host merges)
@@ -65,6 +67,7 @@
65
67
  const { createHash } = require('node:crypto')
66
68
  const { existsSync, readFileSync, realpathSync } = require('node:fs')
67
69
  const { join, resolve, sep } = require('node:path')
70
+ const { readBasePin } = require('./basepin.js')
68
71
 
69
72
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
70
73
 
@@ -227,6 +230,12 @@ const DEFAULT_CONFIG = Object.freeze({
227
230
  // candidate is all it takes to move every spec onto it. An explicit
228
231
  // `baseBranch` still wins. Empty = off, and resolution is exactly as before.
229
232
  baseBranchPattern: '',
233
+ // The base to offer while `baseBranchPattern` matches nothing — the gap
234
+ // between one release branch merging and the next being cut. Empty = the
235
+ // remote's default branch. Only ever used once someone accepts the offer,
236
+ // which writes a local pin (`env/basepin.js`); never consulted without a
237
+ // pattern.
238
+ baseBranchFallback: '',
230
239
  // How a finished branch reaches the base branch. `strategy: "ff"` (the
231
240
  // default) is trunk-based landing exactly as it has always been: rebase, then
232
241
  // a local `merge --ff-only` — nothing changes for an installed repo on
@@ -428,6 +437,7 @@ function defaults() {
428
437
  spec: { companionPaths: [] },
429
438
  baseBranch: DEFAULT_CONFIG.baseBranch,
430
439
  baseBranchPattern: DEFAULT_CONFIG.baseBranchPattern,
440
+ baseBranchFallback: DEFAULT_CONFIG.baseBranchFallback,
431
441
  land: { ...DEFAULT_CONFIG.land },
432
442
  guards: { ...DEFAULT_CONFIG.guards },
433
443
  teardown: { ...DEFAULT_CONFIG.teardown },
@@ -712,6 +722,11 @@ function mergeConfig(base, parsed) {
712
722
  const pattern = parsed.baseBranchPattern.trim()
713
723
  if (pattern && !/\s/.test(pattern) && !pattern.includes('..')) base.baseBranchPattern = pattern
714
724
  }
725
+ // A branch name, so the same two characters can never be in it.
726
+ if (typeof parsed.baseBranchFallback === 'string') {
727
+ const fallback = parsed.baseBranchFallback.trim()
728
+ if (fallback && !/\s/.test(fallback) && !fallback.includes('..')) base.baseBranchFallback = fallback
729
+ }
715
730
 
716
731
  // Same treatment as `teardown.deleteRemoteBranch` below, for the same reason:
717
732
  // an unrecognised value falls through to the default rather than erroring or
@@ -944,6 +959,27 @@ function applyProviderSpecDocs(config, parsed, dir) {
944
959
  return config
945
960
  }
946
961
 
962
+ /**
963
+ * Attach the gap pin (`env/basepin.js`) to a loaded config as `gapPin`, so every
964
+ * caller that resolves the base from this config honours it with nothing passed
965
+ * — the main guard, the served pages and the dashboard included. Without a
966
+ * pattern there is no gap and nothing is read.
967
+ *
968
+ * Non-enumerable, because it is local state rather than configuration: it must
969
+ * not appear in a config dump, a deep-equal, or anything written back to disk.
970
+ * `dir` is the folder the config was read from — the primary checkout for
971
+ * every caller that anchors there first. One that does not finds no pin, which
972
+ * is the harmless direction: it refuses and offers again.
973
+ */
974
+ function withGapPin(config, dir) {
975
+ if (config.baseBranchPattern) {
976
+ // A getter, read on every resolve: the review server loads its config once
977
+ // and lives for days, and a pin taken after it started must still count.
978
+ Object.defineProperty(config, 'gapPin', { get: () => readBasePin(dir, config), enumerable: false })
979
+ }
980
+ return config
981
+ }
982
+
947
983
  function loadEnvConfig(dir = process.cwd()) {
948
984
  const base = defaults()
949
985
  const file = join(dir, CONFIG_FILE)
@@ -971,7 +1007,7 @@ function loadEnvConfig(dir = process.cwd()) {
971
1007
  }
972
1008
 
973
1009
  return {
974
- config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
1010
+ config: withGapPin(applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir), dir),
975
1011
  present: true,
976
1012
  unknown: collectUnknownKeys(parsed),
977
1013
  badReviewers: collectBadReviewers(parsed),
@@ -439,15 +439,22 @@ function branchFor(spec, config) {
439
439
  /**
440
440
  * Thrown when `baseBranchPattern` is set and no remote branch matches it. A
441
441
  * refusal, never a fall-through: the default branch is exactly where a rolling
442
- * base must not land. `refused` carries the one-line reason; `pattern` the glob.
442
+ * base must not land unasked. `refused` carries the one-line reason; `pattern`
443
+ * the glob. `offer` is the way out the engine declares
444
+ * (`.claude/rules/offered-unblocks.md`) — pin the fallback for the gap — and is
445
+ * null when no fallback resolves, because guessing a base is worse than asking.
443
446
  */
444
447
  class BaseUnresolvedError extends Error {
445
- constructor(pattern) {
448
+ constructor(pattern, fallback = null) {
446
449
  const refused = `no branch matches ${pattern} — run spec-env base to fetch`
447
450
  super(refused)
448
451
  this.name = 'BaseUnresolvedError'
449
452
  this.refused = refused
450
453
  this.pattern = pattern
454
+ this.fallback = fallback
455
+ this.offer = fallback
456
+ ? { kind: 'satisfy', label: `Use ${fallback} as the base for now`, command: 'skitterspec spec-env base --use-fallback' }
457
+ : null
451
458
  }
452
459
  }
453
460
 
@@ -456,7 +463,8 @@ class BaseUnresolvedError extends Error {
456
463
  * onto). Precedence:
457
464
  * 1. `config.baseBranch` — explicit override
458
465
  * 2. `config.baseBranchPattern` — the newest remote branch matching it, by
459
- * committer date; no match throws `BaseUnresolvedError`
466
+ * committer date; no match takes a gap pin made under that same pattern
467
+ * (`env/basepin.js`), else throws `BaseUnresolvedError`
460
468
  * 3. `origin/HEAD` — the remote's default branch
461
469
  * 4. `main` if it exists locally
462
470
  * 5. `master` if it exists locally
@@ -471,30 +479,40 @@ class BaseUnresolvedError extends Error {
471
479
  * synchronous for every caller, the main-guard hook included. Fetching is left
472
480
  * to the commands that already talk to the remote.
473
481
  */
474
- function resolveBaseBranch(config, git) {
475
- const { base, refused } = describeBaseBranch(config, git)
482
+ function resolveBaseBranch(config, git, pin = (config && config.gapPin) || null) {
483
+ const { base, refused } = describeBaseBranch(config, git, pin)
476
484
  if (refused) throw refused
477
485
  return base
478
486
  }
479
487
 
480
488
  /**
481
489
  * The same resolution as `resolveBaseBranch`, returned as data with HOW it was
482
- * found — `pin` · `pattern` · `origin-head` · `local` · `fallback` — for the
483
- * one surface that reports it (`spec-env base`). A pattern with no match comes
484
- * back as `{ base: null, how: 'pattern', refused }` rather than thrown, so a
485
- * listing can still say what it saw.
490
+ * found — `pin` · `pattern` · `gap-pin` · `origin-head` · `local` · `fallback`
491
+ * — for the surfaces that report it. A pattern with no match comes back as
492
+ * `{ base: null, how: 'pattern', refused }` rather than thrown, so a listing
493
+ * can still say what it saw.
494
+ *
495
+ * `pin` is the gap pin as `readBasePin` returns it, or null. It defaults to
496
+ * the one `loadEnvConfig` attached as `config.gapPin`, so callers need not
497
+ * pass it; it is never read from disk here, so this stays pure. It is honoured only while the
498
+ * pattern has NO match and only when it was made under this same pattern: a
499
+ * match always wins, which is what makes the pin clear itself the moment the
500
+ * next release branch is cut. `stalePin` says a pin was passed and a match
501
+ * overrode it, so the caller can delete the file.
486
502
  */
487
- function describeBaseBranch(config, git) {
503
+ function describeBaseBranch(config, git, pin = (config && config.gapPin) || null) {
488
504
  const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
489
505
  if (explicit) return { base: explicit, how: 'pin' }
490
506
 
491
507
  const pattern = config && typeof config.baseBranchPattern === 'string' && config.baseBranchPattern.trim()
492
508
  if (pattern) {
493
509
  try {
494
- return { base: newestMatch(config, git, pattern), how: 'pattern' }
510
+ const base = newestMatch(config, git, pattern)
511
+ return pin ? { base, how: 'pattern', stalePin: true } : { base, how: 'pattern' }
495
512
  } catch (error) {
496
- if (error instanceof BaseUnresolvedError) return { base: null, how: 'pattern', refused: error }
497
- throw error
513
+ if (!(error instanceof BaseUnresolvedError)) throw error
514
+ if (pin && pin.pattern === pattern && pin.base) return { base: pin.base, how: 'gap-pin', pin }
515
+ return { base: null, how: 'pattern', refused: new BaseUnresolvedError(pattern, gapFallback(config, git)) }
498
516
  }
499
517
  }
500
518
 
@@ -518,6 +536,39 @@ function baseRemote(config) {
518
536
  return (config && config.land && typeof config.land.remote === 'string' && config.land.remote.trim()) || 'origin'
519
537
  }
520
538
 
539
+ /**
540
+ * The words that go beside the base wherever one is shown, when a gap pin
541
+ * chose it — `no 20??/Q? branch on origin — pinned for the gap` — else null.
542
+ * One function so the page, the review text and the plans cannot disagree.
543
+ */
544
+ function gapNote(config, git) {
545
+ const { how } = describeBaseBranch(config, git)
546
+ if (how !== 'gap-pin') return null
547
+ return `no ${config.baseBranchPattern.trim()} branch on ${baseRemote(config)} — pinned for the gap`
548
+ }
549
+
550
+ // The branch a gap pin would name: `baseBranchFallback`, else the remote's
551
+ // default branch. Null when neither can be read — and then no offer is made,
552
+ // because a guessed base is worse than a refusal.
553
+ //
554
+ // WHAT WOULD FOOL THIS: an unset `<remote>/HEAD`. A clone made with
555
+ // `git clone` has one, but a repo that added its remote by hand does not until
556
+ // `git remote set-head` runs, so a healthy repo can land here with no offer.
557
+ // That costs a plain refusal, never a wrong base.
558
+ function gapFallback(config, git) {
559
+ const remote = baseRemote(config)
560
+ const named = config && typeof config.baseBranchFallback === 'string' && config.baseBranchFallback.trim()
561
+ if (named) {
562
+ const exists =
563
+ git(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${named}`]) !== null ||
564
+ git(['show-ref', '--verify', '--quiet', `refs/heads/${named}`]) !== null
565
+ return exists ? named : null
566
+ }
567
+ const head = git(['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`])
568
+ if (!head) return null
569
+ return head.startsWith(`${remote}/`) ? head.slice(remote.length + 1) : head
570
+ }
571
+
521
572
  function newestMatch(config, git, pattern) {
522
573
  const remote = baseRemote(config)
523
574
  const prefix = `refs/remotes/${remote}/`
@@ -834,6 +885,8 @@ module.exports = {
834
885
  allSpecs,
835
886
  resolveBaseBranch,
836
887
  describeBaseBranch,
888
+ gapFallback,
889
+ gapNote,
837
890
  baseRemote,
838
891
  BaseUnresolvedError,
839
892
  resolvePrimaryCheckout,
package/src/env/review.js CHANGED
@@ -222,8 +222,13 @@ function numstatFor(git, ref, file, untracked) {
222
222
  * WHAT WOULD FOOL THIS: the bridge variable is an undocumented harness internal
223
223
  * and may be renamed or dropped, so its ABSENCE proves nothing — which is the
224
224
  * whole reason `unknown` exists and the default is not `local`.
225
+ *
226
+ * `platform` is passed in for the same reason as `env`, and defaults to NONE
227
+ * rather than `process.platform`: a caller that names no platform, and every
228
+ * test that states only an environment, gets the platform-free answer on any
229
+ * machine the suite runs on.
225
230
  */
226
- function detectReader(env = {}) {
231
+ function detectReader(env = {}, platform = null) {
227
232
  // SSH first: a standard convention, and the strongest available signal. If the
228
233
  // shell arrived over the network, the page's path is on a machine the reader
229
234
  // is not looking at.
@@ -233,6 +238,20 @@ function detectReader(env = {}) {
233
238
  // produced the original dead link, read on a phone.
234
239
  if (env.CLAUDE_CODE_BRIDGE_SESSION_ID) return { reader: 'remote', why: 'bridge session' }
235
240
 
241
+ // A WINDOWS SESSION WITH NO DESKTOP. Windows sets SESSIONNAME for every
242
+ // interactive logon — `Console` at the desktop, `RDP-Tcp#N` over Remote
243
+ // Desktop — and whatever starts from that desktop inherits it. A process
244
+ // outside any desktop has none: `prlctl exec`'s background logon (a Mac
245
+ // driving the VM), the OpenSSH server, a scheduled task, a service. Nobody is
246
+ // at this machine's browser in any of those.
247
+ //
248
+ // WHAT WOULD FOOL THIS: a scheduled task or service run while someone sits at
249
+ // the desk. That is affordable only because of what it decides — `local` is
250
+ // hidden only while `network` has a URL, and that URL is the same server, so
251
+ // a wrong guess costs the second-best link, never a page that will not open.
252
+ // Elsewhere SESSIONNAME means nothing, so its absence is not evidence.
253
+ if (platform === 'win32' && !env.SESSIONNAME) return { reader: 'remote', why: 'no interactive session' }
254
+
236
255
  // CLAUDE_CODE_ENTRYPOINT IS DELIBERATELY NOT CONSULTED. It describes the
237
256
  // PROCESS, not the reader, and reports `cli` for a bridged session — it said
238
257
  // exactly that for the session this was written from, where the reader was on
@@ -248,7 +267,7 @@ function detectReader(env = {}) {
248
267
  * sniffing: the operator knows where they are reading, and no signal outranks
249
268
  * being told.
250
269
  */
251
- function resolveReader(config, env = {}) {
270
+ function resolveReader(config, env = {}, platform = null) {
252
271
  // THE WRAPPER FIRST, because it is the one thing that knows this machine. A
253
272
  // committed `review.reader` speaks for every checkout of the repo; a wrapper
254
273
  // that runs the engine inside a VM (`prlctl exec`) speaks for this one, and
@@ -257,7 +276,7 @@ function resolveReader(config, env = {}) {
257
276
  if (told === 'local' || told === 'remote') return { reader: told, why: 'SKITTERSPEC_READER' }
258
277
  const setting = (config && config.review && config.review.reader) || 'detect'
259
278
  if (setting === 'local' || setting === 'remote') return { reader: setting, why: 'configured' }
260
- return detectReader(env)
279
+ return detectReader(env, platform)
261
280
  }
262
281
 
263
282
  /**
@@ -269,7 +288,10 @@ function resolveReader(config, env = {}) {
269
288
  * same machine, where loopback opens fine; and its variable is an undocumented
270
289
  * harness internal. Hiding a working link on that guess is the load-bearing
271
290
  * detection `detectReader` warns against, so only the signals someone set on
272
- * purpose count: the wrapper's variable, the committed setting, and SSH.
291
+ * purpose count: the wrapper's variable, the committed setting, and SSH — plus
292
+ * one detection, a Windows session with no desktop, admitted because hiding
293
+ * `local` only ever happens beside a working `network` URL, so being wrong
294
+ * costs the second-best link rather than the loop.
273
295
  *
274
296
  * WHAT WOULD FOOL THIS: SSH with a `-L` port forward makes the reader's loopback
275
297
  * reach this server, so `ssh` is a strong hint rather than proof —
@@ -294,7 +316,7 @@ function readerOffMachine(reader) {
294
316
  * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
295
317
  * caller's declaration about the work, not a reading of the gate.
296
318
  */
297
- function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
319
+ function collectReview({ spec, git, mode = 'working', ref, base = null, baseGap = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
298
320
  // WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
299
321
  // reads the spec's worktree, and for those the two are the same path — so
300
322
  // `treePath` left null keeps the existing behaviour exactly. The `docs` mode
@@ -402,6 +424,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
402
424
  // "everything since main, because there was nothing uncommitted" are
403
425
  // different answers to "what am I looking at".
404
426
  fellBack,
427
+ // Set when a gap pin chose `base` (`gapNote`): the page says so beside it,
428
+ // because "since master" reads as a decision nobody made otherwise.
429
+ baseGap: base ? baseGap : null,
405
430
  generatedAt: now,
406
431
  // Is there a phase left for `/spec-next` to build? The page needs it to
407
432
  // know whether offering `Commit & Continue` means anything — and it is read
package/src/env/serve.js CHANGED
@@ -35,6 +35,7 @@ const {
35
35
  allSpecs,
36
36
  resolveSpec,
37
37
  resolveBaseBranch,
38
+ gapNote,
38
39
  isEpic,
39
40
  } = require('./resolve.js')
40
41
  const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
@@ -641,6 +642,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
641
642
  mode,
642
643
  ref,
643
644
  base: baseName,
645
+ baseGap: baseName ? gapNote(config, trimmed) : null,
644
646
  now,
645
647
  notes,
646
648
  gate,
@@ -664,6 +666,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
664
666
  mode: 'branch',
665
667
  ref: mergeBase,
666
668
  base: fallbackBase,
669
+ baseGap: gapNote(config, trimmed),
667
670
  now,
668
671
  notes,
669
672
  gate,
package/src/ideacmd.js CHANGED
@@ -154,7 +154,17 @@ function refuse(out, flags, reason, extra = {}) {
154
154
 
155
155
  async function fileStore(sub, positional, flags, { cwd, now, out }) {
156
156
  const ctx = fileContext(cwd)
157
- if (!ctx.base) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
157
+ if (!ctx.base) {
158
+ // A rolling base in its gap carries the engine's offer
159
+ // (`.claude/rules/offered-unblocks.md`): the refusal, then the way out.
160
+ const offer = ctx.refused && ctx.refused.offer
161
+ if (!offer) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
162
+ write(out, flags, { ok: false, refused: ctx.refused.message, offer }, [
163
+ `idea: ${ctx.refused.message}`,
164
+ ` offer: ${offer.label} — ${offer.command}`,
165
+ ])
166
+ return 1
167
+ }
158
168
  const { tip, text } = readOnBase(ctx)
159
169
 
160
170
  if (sub === 'list') {