@skitterbyte/skitterspec-linear 19.14.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.
- package/assets/core/env.config.md +16 -2
- package/assets/review/page.html +2 -1
- package/assets/rules/offered-unblocks.md +22 -0
- package/assets/skills/no-spec/SKILL.md +5 -0
- package/assets/skills/spec-complete/SKILL.md +5 -1
- package/assets/skills/spec-diff/SKILL.md +5 -0
- package/assets/skills/spec-idea/SKILL.md +5 -0
- package/assets/skills/spec-start/SKILL.md +6 -2
- package/assets/skills/spec-to-main/SKILL.md +5 -1
- package/package.json +1 -1
- package/src/cli.js +142 -9
- package/src/env/base.js +21 -5
- package/src/env/basepin.js +62 -0
- package/src/env/config.js +37 -1
- package/src/env/resolve.js +66 -13
- package/src/env/review.js +4 -1
- package/src/env/serve.js +3 -0
- package/src/ideacmd.js +11 -1
|
@@ -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
|
|
329
|
-
// the default branch is exactly where a rolling base must
|
|
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.
|
package/assets/review/page.html
CHANGED
|
@@ -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
|
|
@@ -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
|
|
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
|
-
|
|
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
|
|
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.
|
|
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
|
|
@@ -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
|
-
*
|
|
4481
|
-
*
|
|
4482
|
-
*
|
|
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
|
|
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({
|
|
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
|
|
@@ -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,
|
|
@@ -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 —
|
|
9
|
-
* is a hand edit of `baseBranch`, deliberately without a verb
|
|
10
|
-
*
|
|
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 (
|
|
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),
|
package/src/env/resolve.js
CHANGED
|
@@ -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`
|
|
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
|
|
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`
|
|
483
|
-
*
|
|
484
|
-
*
|
|
485
|
-
*
|
|
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
|
-
|
|
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)
|
|
497
|
-
|
|
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
|
@@ -316,7 +316,7 @@ function readerOffMachine(reader) {
|
|
|
316
316
|
* `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
|
|
317
317
|
* caller's declaration about the work, not a reading of the gate.
|
|
318
318
|
*/
|
|
319
|
-
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 }) {
|
|
320
320
|
// WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
|
|
321
321
|
// reads the spec's worktree, and for those the two are the same path — so
|
|
322
322
|
// `treePath` left null keeps the existing behaviour exactly. The `docs` mode
|
|
@@ -424,6 +424,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
424
424
|
// "everything since main, because there was nothing uncommitted" are
|
|
425
425
|
// different answers to "what am I looking at".
|
|
426
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,
|
|
427
430
|
generatedAt: now,
|
|
428
431
|
// Is there a phase left for `/spec-next` to build? The page needs it to
|
|
429
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)
|
|
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') {
|