@skitterbyte/skitterspec-jira 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/SETUP.md +5 -0
  3. package/assets/core/env.config.json.example +1 -0
  4. package/assets/core/env.config.md +143 -8
  5. package/assets/core/jira.config.md +4 -2
  6. package/assets/hooks/main-guard.cjs +40 -6
  7. package/assets/hooks/review-gate.cjs +42 -7
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +81 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +55 -2
  12. package/assets/skills/spec-bug/SKILL.md +25 -1
  13. package/assets/skills/spec-cancel/SKILL.md +35 -0
  14. package/assets/skills/spec-complete/SKILL.md +113 -0
  15. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  16. package/assets/skills/spec-incident/SKILL.md +22 -0
  17. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  18. package/assets/skills/spec-next/SKILL.md +9 -4
  19. package/assets/skills/spec-push/SKILL.md +22 -0
  20. package/assets/skills/spec-review/SKILL.md +32 -0
  21. package/assets/skills/spec-start/SKILL.md +39 -1
  22. package/assets/skills/spec-status/SKILL.md +18 -3
  23. package/assets/skills/spec-sync/SKILL.md +1 -0
  24. package/assets/skills/spec-to-main/SKILL.md +47 -1
  25. package/package.json +1 -1
  26. package/src/cli.js +1188 -79
  27. package/src/env/base.js +104 -0
  28. package/src/env/bootstrap.js +22 -3
  29. package/src/env/classify.js +12 -4
  30. package/src/env/config.js +77 -5
  31. package/src/env/disposition.js +62 -0
  32. package/src/env/handoff.js +81 -0
  33. package/src/env/host.js +262 -0
  34. package/src/env/hotfix.js +237 -9
  35. package/src/env/hotfixland.js +105 -10
  36. package/src/env/inflight.js +98 -0
  37. package/src/env/integrate.js +136 -9
  38. package/src/env/live.js +8 -7
  39. package/src/env/mainguard.js +20 -5
  40. package/src/env/phases.js +28 -0
  41. package/src/env/project.js +223 -0
  42. package/src/env/provision.js +30 -8
  43. package/src/env/resolve.js +147 -25
  44. package/src/env/review.js +21 -7
  45. package/src/env/reviewers.js +7 -10
  46. package/src/env/serve.js +27 -11
  47. package/src/env/specstate.js +101 -0
  48. package/src/env/supervise.js +15 -2
  49. package/src/env/teardown.js +46 -3
  50. package/src/init.js +49 -9
  51. package/src/vendor/jira/cli-sync.js +48 -4
  52. package/src/vendor/jira/config.js +17 -5
  53. package/src/vendor/provider-kit/index.js +4 -0
  54. package/src/vendor/provider-kit/src/apply.js +58 -6
  55. package/src/vendor/provider-kit/src/assignment.js +78 -1
  56. package/src/vendor/provider-kit/src/config.js +34 -1
  57. package/src/vendor/provider-kit/src/credentials.js +7 -2
  58. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  59. package/src/vendor/provider-kit/src/released.js +48 -4
  60. package/src/vendor/provider-kit/src/specs.js +18 -7
  61. package/src/vendor/provider-kit/src/splice.js +64 -0
  62. package/src/vendor/provider-kit/src/status.js +137 -0
  63. package/src/vendor/sync-core/index.js +14 -1
  64. package/src/vendor/sync-core/src/compare.js +81 -6
  65. package/src/vendor/sync-core/src/normalize.js +50 -7
  66. package/src/vendor/sync-core/src/push.js +65 -5
  67. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -21,6 +21,7 @@
21
21
  */
22
22
 
23
23
  const { spawnSync } = require('node:child_process')
24
+ const { shellPath } = require('./project.js')
24
25
 
25
26
  // The fields skittership's `release-hotfix.cjs --json` prints, and their types.
26
27
  // `versionCommit` is null only on its `--dry-run`, which skitterspec never
@@ -70,17 +71,35 @@ function describeStep(step) {
70
71
  case 'release':
71
72
  if (step.via === 'command') return `release: ${step.command}`
72
73
  if (step.via === 'recorded') return `release: ${step.tag} (cut earlier — not re-run)`
73
- return `release: git tag ${step.tag}`
74
- case 'push':
75
- if (step.via === 'remote') return `push: ${step.tag || 'the tag'} is already on ${step.remote}`
74
+ return `release: git tag ${step.tag}${step.at ? ` ${step.at}` : ''}`
75
+ case 'push': {
76
+ if (step.via === 'remote') {
77
+ return step.refs ? `push: already on ${step.remote}` : `push: ${step.tag || 'the tag'} is already on ${step.remote}`
78
+ }
76
79
  if (step.via === 'hold') return `push: held — no consent to push to ${step.remote}`
77
- return `push: ${step.branch}, then ${step.tag || 'the tag'}, to ${step.remote}`
80
+ const what = [...pushRefs(step), ...(pushesTag(step) ? [step.tag || 'the tag'] : [])]
81
+ return `push: ${what.join(', then ')}, to ${step.remote}`
82
+ }
83
+ case 'rebase':
84
+ return `rebase: onto ${step.onto}`
85
+ case 'pr':
86
+ if (!step.command) return `pr: cannot tell the PR's state — open one into ${step.base} on the host`
87
+ if (step.command.startsWith('#')) return `pr: ${step.command.slice(1).trim()}`
88
+ return `pr: ${step.command}`
89
+ case 'wait':
90
+ return `wait: the PR into ${step.base} is not merged yet — re-run once the host merges it`
78
91
  case 'target':
79
92
  return `target: ${step.base} -> ${step.tag} (cherry-pick, tag)`
80
93
  case 'carry': {
81
94
  const n = Array.isArray(step.commits) ? step.commits.length : 0
82
95
  const what = n === 1 ? '1 commit' : `${n} commits`
83
96
  if (step.strategy === 'worktree') return `carry: cherry-pick ${what} onto ${step.base} (throwaway worktree)`
97
+ if (step.strategy === 'pr') {
98
+ if (step.prState === 'open' || step.prState === 'draft') return `carry: the PR from ${step.carryBranch} into ${step.base} is open — merge it to finish`
99
+ if (step.prState === 'merged') return `carry: the PR from ${step.carryBranch} into ${step.base} is merged`
100
+ if (!step.push) return `carry: held — no consent to push ${step.carryBranch} to ${step.remote}`
101
+ return `carry: cherry-pick ${what} onto ${step.carryBranch}, push it, open a PR into ${step.base}`
102
+ }
84
103
  return `carry: cherry-pick ${what} onto ${step.base}`
85
104
  }
86
105
  default:
@@ -88,6 +107,16 @@ function describeStep(step) {
88
107
  }
89
108
  }
90
109
 
110
+ // What a push step sends besides the tag. A tag-based land pushes its branch;
111
+ // a branch-based one names its refs — `<hotfix>:<release>` for an ff land, the
112
+ // hotfix branch for a PR, or none at all when only the tag is left to publish.
113
+ function pushRefs(step) {
114
+ return Array.isArray(step.refs) ? step.refs : [step.branch]
115
+ }
116
+ function pushesTag(step) {
117
+ return step.withTag !== false
118
+ }
119
+
91
120
  // The last non-blank line a command wrote to stderr — skittership's refusals
92
121
  // are one `✖ release-hotfix: <reason>` line there, and that is what to relay.
93
122
  function lastLine(text) {
@@ -108,7 +137,7 @@ function runRelease(step, ctx) {
108
137
  return { outcome: 'skipped', line: describeStep(step), release: step.release }
109
138
  }
110
139
  if (step.via === 'tag') {
111
- const res = ctx.spawn('git', ['-C', step.cwd, 'tag', step.tag], {
140
+ const res = ctx.spawn('git', ['-C', step.cwd, 'tag', step.tag, ...(step.at ? [step.at] : [])], {
112
141
  stdio: ['ignore', 'pipe', 'pipe'],
113
142
  encoding: 'utf8',
114
143
  })
@@ -151,15 +180,16 @@ function runPush(step, release, ctx) {
151
180
  const s = { ...step, tag: release ? release.tag : null }
152
181
  if (s.via === 'remote') return { outcome: 'skipped', line: describeStep(s) }
153
182
  if (s.via === 'hold') return { outcome: 'held', line: describeStep(s) }
154
- if (!release) return { outcome: 'failed', line: `${describeStep(s)} — no release to push` }
155
- for (const ref of [s.branch, s.tag]) {
156
- const argv = ['-C', s.cwd, 'push', s.remote, ref]
183
+ if (pushesTag(s) && !release) return { outcome: 'failed', line: `${describeStep(s)} — no release to push` }
184
+ const refs = [...pushRefs(s), ...(pushesTag(s) ? [s.tag] : [])]
185
+ for (const ref of refs) {
186
+ const argv = ['-C', s.cwd, 'push', ...(s.force && ref !== s.tag ? ['--force-with-lease', '-u'] : []), s.remote, ref]
157
187
  const res = ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
158
188
  if (res.error || res.status !== 0) {
159
189
  return { outcome: 'failed', line: `push ${ref} to ${s.remote} — ${lastLine(res.stderr) || why(res)}` }
160
190
  }
161
191
  }
162
- return { outcome: 'pushed', line: `pushed ${s.branch}, then ${s.tag}, to ${s.remote}` }
192
+ return { outcome: 'pushed', line: `pushed ${refs.join(', then ')}, to ${s.remote}` }
163
193
  }
164
194
 
165
195
  /**
@@ -184,12 +214,13 @@ function runCarry(step, release, ctx) {
184
214
  if (!commits.length) {
185
215
  return { outcome: 'skipped', line: `carry: nothing to carry — ${step.base} already has the fix`, carried: 0 }
186
216
  }
217
+ if (step.strategy === 'pr') return runCarryPr(step, commits, ctx)
187
218
  if (step.strategy === 'dirty') {
188
219
  return {
189
220
  outcome: 'refused',
190
221
  line:
191
222
  `carry: ${step.cwd} has uncommitted changes on ${step.base} — commit or stash them, ` +
192
- `then run: git -C ${step.cwd} cherry-pick ${commits.join(' ')}`,
223
+ `then run: git -C ${shellPath(step.cwd)} cherry-pick ${commits.join(' ')}`,
193
224
  }
194
225
  }
195
226
  const git = (argv) =>
@@ -223,6 +254,65 @@ function runCarry(step, release, ctx) {
223
254
  return { outcome: 'ran', line: `carried ${what} onto ${step.base}`, carried: commits.length }
224
255
  }
225
256
 
257
+ // The carry under `land.strategy: "pr"`: the base may be protected, so the fix
258
+ // reaches it the way everything else does — a `carry/<slug>` branch cut from
259
+ // the base, the fix picked onto it in a throwaway worktree, pushed on consent,
260
+ // and a READY PR into the base. A carry PR already open or merged is the host
261
+ // saying this ran before; neither re-runs anything.
262
+ function runCarryPr(step, commits, ctx) {
263
+ if (step.prState === 'open' || step.prState === 'draft' || step.prState === 'merged') {
264
+ return { outcome: 'skipped', line: describeStep(step), carried: 0 }
265
+ }
266
+ if (!step.push) return { outcome: 'held', line: describeStep(step) }
267
+ const git = (argv) =>
268
+ ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
269
+ const fail = (line) => ({ outcome: 'failed', line })
270
+ const add = git(['-C', step.root, 'worktree', 'add', '-B', step.carryBranch, step.tmpPath, step.startRef])
271
+ if (add.error || add.status !== 0) return fail(`carry: worktree add ${step.tmpPath} — ${lastLine(add.stderr) || why(add)}`)
272
+ const cleanup = () => git(['-C', step.root, 'worktree', 'remove', '--force', step.tmpPath])
273
+ for (const sha of commits) {
274
+ const res = git(['-C', step.tmpPath, 'cherry-pick', sha])
275
+ if (res.error || res.status !== 0) {
276
+ git(['-C', step.tmpPath, 'cherry-pick', '--abort'])
277
+ cleanup()
278
+ return fail(`carry: cherry-pick ${sha} onto ${step.carryBranch} conflicted — aborted; ${lastLine(res.stderr) || why(res)}`)
279
+ }
280
+ }
281
+ const push = git(['-C', step.tmpPath, 'push', '--force-with-lease', '-u', step.remote, step.carryBranch])
282
+ cleanup()
283
+ if (push.error || push.status !== 0) return fail(`carry: push ${step.carryBranch} — ${lastLine(push.stderr) || why(push)}`)
284
+ if (!step.prCommand || step.prCommand.startsWith('#')) {
285
+ return { outcome: 'ran', line: `carry: pushed ${step.carryBranch} — open a PR into ${step.base} on the host`, carried: 0 }
286
+ }
287
+ const pr = ctx.spawn(step.prCommand, { cwd: step.root, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
288
+ if (pr.error || pr.status !== 0) return fail(`carry: ${step.prCommand} — ${lastLine(pr.stderr) || why(pr)}`)
289
+ return { outcome: 'ran', line: `carry: opened a PR from ${step.carryBranch} into ${step.base}`, carried: 0 }
290
+ }
291
+
292
+ // Replay the hotfix onto the release branch as it is now. A conflict is
293
+ // aborted, leaving the branch exactly where it was, so a re-run tries again.
294
+ function runRebase(step, ctx) {
295
+ const git = (argv) => ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
296
+ const res = git(['-C', step.cwd, 'rebase', step.onto])
297
+ if (res.error || res.status !== 0) {
298
+ git(['-C', step.cwd, 'rebase', '--abort'])
299
+ return { outcome: 'failed', line: `rebase onto ${step.onto} conflicted — aborted; ${lastLine(res.stderr) || why(res)}` }
300
+ }
301
+ return { outcome: 'ran', line: `rebased onto ${step.onto}` }
302
+ }
303
+
304
+ // Open the PR, through the host's own CLI. A `# …` command is the host saying
305
+ // one already exists (the push updated it); null is a host that could not be
306
+ // asked — neither runs anything.
307
+ function runPr(step, ctx) {
308
+ if (!step.command || step.command.startsWith('#')) return { outcome: 'skipped', line: describeStep(step) }
309
+ const res = ctx.spawn(step.command, { cwd: step.cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
310
+ if (res.error || res.status !== 0) {
311
+ return { outcome: 'failed', line: `pr: ${step.command} — ${lastLine(res.stderr) || why(res)}` }
312
+ }
313
+ return { outcome: 'ran', line: `opened a PR into ${step.base}${res.stdout ? ` — ${lastLine(res.stdout)}` : ''}` }
314
+ }
315
+
226
316
  // A step that is a list of git argvs run in order — a target's worktree,
227
317
  // cherry-pick, tag and cleanup, or the carry's cherry-pick.
228
318
  function runArgvs(step, ctx) {
@@ -267,6 +357,11 @@ function runHotfixLand(steps, io = {}) {
267
357
  if (step.kind === 'release') r = runRelease(step, ctx)
268
358
  else if (step.kind === 'push') r = runPush(step, release, ctx)
269
359
  else if (step.kind === 'carry') r = runCarry(step, release, ctx)
360
+ else if (step.kind === 'rebase') r = runRebase(step, ctx)
361
+ else if (step.kind === 'pr') r = runPr(step, ctx)
362
+ // Not a failure: the land is waiting on the host, and nothing after it
363
+ // (the tag, the carry) may run before the merge.
364
+ else if (step.kind === 'wait') r = { outcome: 'held', line: describeStep(step) }
270
365
  else if (step.kind === 'target') {
271
366
  // A project's release command can cut a tag the built-in tagger also
272
367
  // planned for a target on the same root. Refuse rather than collide.
@@ -0,0 +1,98 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * What is in flight here — the rows behind `skitterspec status`, and the detail
5
+ * `spec-env status` prints beside each provisioned spec.
6
+ *
7
+ * Each spec is read in ITS OWN worktree (`readSpecState`), where the bucket and
8
+ * the phase files are truthful, and again in the checkout the command was run
9
+ * from, so the output can say when the two disagree. Offline by construction:
10
+ * nothing here asks a tracker — the board's view is `spec-sync list` and
11
+ * `spec-sync board` (Decision 7).
12
+ *
13
+ * Pure but for the injected reader, so the command layer is testable without a
14
+ * worktree.
15
+ */
16
+
17
+ const path = require('node:path')
18
+
19
+ const { readSpecState } = require('./specstate.js')
20
+ const { progressText } = require('./phases.js')
21
+
22
+ /**
23
+ * @param {object} a
24
+ * - `dir` the checkout the command was run from
25
+ * - `provisioned` `[{ folder, wt, project, specless }]`, from the worktree
26
+ * list — `project` is the project folder inside `wt`, the
27
+ * same path unless the project sits in a subfolder
28
+ * - `read` `readSpecState`, injectable
29
+ */
30
+ function collectInFlight({ dir, provisioned, read = readSpecState }) {
31
+ return provisioned.map(({ folder, wt, project, specless }) => {
32
+ const at = project || wt
33
+ // A `/no-spec` record has a branch and no document BY DESIGN (Decision 6).
34
+ // It is listed, and never read, so it can never be called unknown.
35
+ if (specless) return { spec: folder, worktree: at, specless: true }
36
+ const there = read(at, folder)
37
+ const here = read(dir, folder)
38
+ return {
39
+ spec: folder,
40
+ worktree: at,
41
+ specless: false,
42
+ ...there,
43
+ // Where this checkout files it: a bucket, or null when it is not on this
44
+ // branch at all (a spec authored and started without landing here).
45
+ here: here.found ? here.bucket : null,
46
+ }
47
+ })
48
+ }
49
+
50
+ // The one-line detail for a row. Every part is optional except the bucket: a
51
+ // `pull`-era spec carries no Status or Developer, and that is the normal shape.
52
+ function detailOf(row) {
53
+ if (row.specless) return '(no spec)'
54
+ if (!row.found) return `status unknown — ${row.reason}`
55
+ const parts = [row.bucket]
56
+ if (row.phasesTotal !== null) {
57
+ parts.push(progressText({ done: row.phasesDone, total: row.phasesTotal, current: row.currentPhase }))
58
+ }
59
+ if (row.status) parts.push(row.status)
60
+ if (row.developer) parts.push(row.developer)
61
+ return parts.join(' · ')
62
+ }
63
+
64
+ // Rows whose bucket here differs from the bucket in their own worktree — the
65
+ // confusion the closing line explains. A positive signal: both reads found the
66
+ // spec and named different buckets, or the worktree found it and this checkout
67
+ // does not have it at all. An unreadable worktree copy is never counted.
68
+ function disagreeing(rows) {
69
+ return rows.filter((r) => !r.specless && r.found && r.here !== r.bucket)
70
+ }
71
+
72
+ // A worktree outlives its spec when a teardown was declined, so a provisioned
73
+ // spec is not necessarily in flight. Finished is the positive signal — the
74
+ // worktree's own copy sits in `complete/` or `cancelled/` — and everything else,
75
+ // an unreadable copy included, is counted as in flight and still listed.
76
+ const FINISHED = new Set(['complete', 'cancelled'])
77
+ const isInFlight = (r) => !r.specless && !(r.found && FINISHED.has(r.bucket))
78
+
79
+ function formatInFlight(rows, { dir }) {
80
+ if (!rows.length) return 'no specs in flight\n'
81
+ const width = Math.max(...rows.map((r) => r.spec.length))
82
+ const live = rows.filter(isInFlight).length
83
+ const out = [live ? `${live} spec${live === 1 ? '' : 's'} in flight` : 'no specs in flight']
84
+ for (const r of rows) {
85
+ out.push(` ${r.spec.padEnd(width)} ${detailOf(r)}`)
86
+ out.push(` ${path.relative(dir, r.worktree) || r.worktree}`)
87
+ }
88
+ // SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
89
+ // this checkout, the line would explain a discrepancy that is not there.
90
+ const off = disagreeing(rows)
91
+ if (off.length) {
92
+ const n = off.length
93
+ out.push('', `On this branch ${n} of these ${n === 1 ? 'reads' : 'read'} differently — a spec's bucket moves on its own branch.`)
94
+ }
95
+ return out.join('\n') + '\n'
96
+ }
97
+
98
+ module.exports = { collectInFlight, detailOf, disagreeing, formatInFlight, isInFlight }
@@ -1,6 +1,7 @@
1
1
  'use strict'
2
2
 
3
3
  const { globToRegExp } = require('./glob.js')
4
+ const { shellPath } = require('./project.js')
4
5
 
5
6
  /**
6
7
  * Pure integrate planner for `spec-env integrate`.
@@ -24,12 +25,15 @@ const { globToRegExp } = require('./glob.js')
24
25
  * returns is identical so callers need no second code path.
25
26
  *
26
27
  * @param {object} ctx { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath,
27
- * changedFiles } — `changedFiles` is what the land brings
28
- * in (`base...branch`), or null when it could not be read
28
+ * changedFiles, primarySwitch } — `changedFiles` is what the
29
+ * land brings in (`base...branch`), or null when it could not
30
+ * be read. `primarySwitch` is set when the primary checkout
31
+ * sits on an older rolling-base match:
32
+ * `{ from, create, remote, dirty }`
29
33
  * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
30
34
  */
31
35
  function planIntegrate(spec, config, ctx) {
32
- const { worktreeState = {}, base, aheadOfBase, mainRepoPath } = ctx || {}
36
+ const { worktreeState = {}, base, aheadOfBase, mainRepoPath, primarySwitch } = ctx || {}
33
37
  const branch = spec.branch
34
38
  const result = {
35
39
  blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
@@ -48,16 +52,39 @@ function planIntegrate(spec, config, ctx) {
48
52
  return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath, null) }
49
53
  }
50
54
 
55
+ // `merge --ff-only` moves whatever the primary checkout has checked out, so a
56
+ // checkout still on the previous release candidate would RECEIVE the land.
57
+ // Switch it first — and refuse while it holds uncommitted work, which a switch
58
+ // would carry onto the new base or refuse halfway through.
59
+ if (primarySwitch && primarySwitch.dirty) {
60
+ return {
61
+ ...result,
62
+ blocked: true,
63
+ reason:
64
+ `the primary checkout is on ${primarySwitch.from}, not ${base}, and has uncommitted ` +
65
+ `changes — commit or stash them there so it can switch to ${base}`,
66
+ }
67
+ }
68
+
51
69
  return {
52
70
  ...result,
53
71
  commands: [
54
- `git -C ${spec.worktreePath} rebase ${base}`,
55
- `git -C ${mainRepoPath} merge --ff-only ${branch}`,
72
+ ...(primarySwitch ? [switchCommand(mainRepoPath, base, primarySwitch)] : []),
73
+ `git -C ${shellPath(spec.worktreePath)} rebase ${base}`,
74
+ `git -C ${shellPath(mainRepoPath)} merge --ff-only ${branch}`,
56
75
  ],
57
76
  afterLand: afterLandFor(config, mainRepoPath, rangeOf(ctx)),
58
77
  }
59
78
  }
60
79
 
80
+ // Put the primary checkout on `base`, creating the local branch from the remote
81
+ // when this clone has never had it (a release candidate cut since).
82
+ function switchCommand(repo, base, { create, remote }) {
83
+ return create
84
+ ? `git -C ${shellPath(repo)} switch -c ${base} --track ${remote || 'origin'}/${base}`
85
+ : `git -C ${shellPath(repo)} switch ${base}`
86
+ }
87
+
61
88
  /**
62
89
  * Pure integrate planner for CHECKOUT mode.
63
90
  *
@@ -108,14 +135,114 @@ function planIntegrateCheckout(spec, config, ctx) {
108
135
  return {
109
136
  ...result,
110
137
  commands: [
111
- `git -C ${checkoutPath} rebase ${base}`,
112
- `git -C ${checkoutPath} switch ${base}`,
113
- `git -C ${checkoutPath} merge --ff-only ${branch}`,
138
+ `git -C ${shellPath(checkoutPath)} rebase ${base}`,
139
+ `git -C ${shellPath(checkoutPath)} switch ${base}`,
140
+ `git -C ${shellPath(checkoutPath)} merge --ff-only ${branch}`,
114
141
  ],
115
142
  afterLand: afterLandFor(config, checkoutPath, rangeOf(ctx)),
116
143
  }
117
144
  }
118
145
 
146
+ /**
147
+ * Pure integrate planner for PR mode (`land.strategy: "pr"`).
148
+ *
149
+ * Landing is not a local fast-forward: the branch is rebased onto the REMOTE
150
+ * image of base, pushed, and a pull request carries it the rest of the way —
151
+ * the base branch moves only when the host merges. So the plan ends in a push,
152
+ * and the push is consent-gated with exactly `planHotfixLand`'s shape: a branch
153
+ * already on the remote at HEAD is honoured as the positive signal (`via:
154
+ * "remote"`), `--push` is the operator's recorded yes (`via: "push"`), and
155
+ * otherwise the plan HOLDS (`via: "hold"`) — the push and PR commands go in
156
+ * `holdCommands` for the skill to print, run by nobody until someone consents.
157
+ *
158
+ * `afterLand` is DEFERRED, never emitted: base has not moved when these
159
+ * commands finish, so the project's after-land steps belong to the completion
160
+ * run that follows the host merge. `afterLandPending: "after-merge"` is how the
161
+ * plan says so.
162
+ *
163
+ * One planner serves both modes: `treePath` is the worktree in worktree mode
164
+ * and the primary checkout in checkout mode, and `onBranch` is asked only where
165
+ * the caller supplies it (checkout mode), exactly as `planIntegrateCheckout`
166
+ * asks it.
167
+ *
168
+ * ctx: { worktreeState: { dirty }, base, remote, treePath, aheadOfRemoteBase,
169
+ * pushedAtHead, push, prCreateCommand, onBranch }
170
+ */
171
+ function planIntegratePr(spec, config, ctx) {
172
+ const { worktreeState = {}, base, treePath, onBranch } = ctx || {}
173
+ const remote = (ctx && ctx.remote) || 'origin'
174
+ const branch = spec.branch
175
+ const result = {
176
+ blocked: false, noop: false, reason: null, commands: [],
177
+ push: null, holdCommands: [], finish: null,
178
+ afterLand: noAfterLand(), afterLandPending: 'after-merge',
179
+ base, branch, remote,
180
+ }
181
+
182
+ // "Already landed" is answered FIRST, as the checkout planner does: a landed
183
+ // spec needs no action wherever the tree happens to be standing, and
184
+ // /spec-complete re-runs integrate on exactly that state. ONLY an explicit
185
+ // false lands here: `aheadOfRemoteBase: null` means `<remote>/<base>` could
186
+ // not be read (never fetched, no network), which is an absence — so it plans
187
+ // rather than claiming landed (`.claude/rules/negative-checks.md` rule 4);
188
+ // the plan's own fetch is what makes the next run answerable.
189
+ //
190
+ // A landed PR-mode branch carries the FINISH half: the host merged, so local
191
+ // base wants catching up and the deferred afterLand comes due here — this is
192
+ // completion run 2, the `hotfix finish` shape. `primaryPath` and
193
+ // `changedFiles` come from the caller like every other git fact; absent a
194
+ // primaryPath (pure tests, checkout mode asking oddly) the finish still
195
+ // names no commands rather than guessing a cwd.
196
+ if (ctx.aheadOfRemoteBase === false) {
197
+ const finish = {
198
+ commands: ctx.primaryPath
199
+ ? [
200
+ `git -C ${shellPath(ctx.primaryPath)} fetch ${remote} ${base}`,
201
+ `git -C ${shellPath(ctx.primaryPath)} merge --ff-only ${remote}/${base}`,
202
+ ]
203
+ : [],
204
+ afterLand: afterLandFor(config, ctx.primaryPath || null, rangeOf(ctx)),
205
+ }
206
+ return { ...result, noop: true, finish }
207
+ }
208
+ if (worktreeState.dirty) {
209
+ return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the completion first' }
210
+ }
211
+ if (onBranch === false) {
212
+ return { ...result, blocked: true, reason: `the checkout is not on ${branch} — switch to it before landing` }
213
+ }
214
+
215
+ const commands = [
216
+ `git -C ${shellPath(treePath)} fetch ${remote} ${base}`,
217
+ `git -C ${shellPath(treePath)} rebase ${remote}/${base}`,
218
+ ]
219
+ // --force-with-lease because the rebase rewrites; -u so the first push sets
220
+ // the upstream the unpushed guard reads.
221
+ const pushCommand = `git -C ${shellPath(treePath)} push --force-with-lease -u ${remote} ${branch}`
222
+ // Composed by the host adapter where one exists; until the caller supplies
223
+ // one, a comment line that cannot be run by accident.
224
+ const prCommand = (ctx && ctx.prCreateCommand)
225
+ || `# open a pull request: ${branch} -> ${base} on ${remote} (gh / az repos)`
226
+
227
+ if (ctx.pushedAtHead || ctx.push) {
228
+ // Consent is satisfied — by the operator having already published the
229
+ // branch (the positive signal), or by `--push`. Pushing after the rebase is
230
+ // safe either way: a no-op push says "Everything up-to-date".
231
+ const via = ctx.pushedAtHead ? 'remote' : 'push'
232
+ return {
233
+ ...result,
234
+ commands: [...commands, pushCommand, prCommand],
235
+ push: { kind: 'push', via, remote, branch },
236
+ }
237
+ }
238
+ return {
239
+ ...result,
240
+ commands,
241
+ push: { kind: 'push', via: 'hold', remote, branch },
242
+ holdCommands: [pushCommand, prCommand],
243
+ }
244
+ }
245
+
119
246
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
120
247
  // primary checkout, standing on base) once the land commands have succeeded.
121
248
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
@@ -164,4 +291,4 @@ function noAfterLand() {
164
291
  return { cwd: null, commands: [], entries: [], range: null }
165
292
  }
166
293
 
167
- module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor, rangeOf }
294
+ module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }
package/src/env/live.js CHANGED
@@ -19,6 +19,7 @@
19
19
  const fs = require('node:fs')
20
20
  const path = require('node:path')
21
21
  const { globToRegExp } = require('./glob.js')
22
+ const { shellPath } = require('./project.js')
22
23
 
23
24
  const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
24
25
 
@@ -341,9 +342,9 @@ function planTake(spec, config, ctx) {
341
342
  return {
342
343
  ...result,
343
344
  commands: [
344
- `git -C ${spec.worktreePath} rebase ${base}`,
345
- `git -C ${spec.worktreePath} switch --detach`,
346
- `git -C ${c.primaryPath} checkout ${branch}`,
345
+ `git -C ${shellPath(spec.worktreePath)} rebase ${base}`,
346
+ `git -C ${shellPath(spec.worktreePath)} switch --detach`,
347
+ `git -C ${shellPath(c.primaryPath)} checkout ${branch}`,
347
348
  ],
348
349
  warnings,
349
350
  receipt: {
@@ -405,8 +406,8 @@ function planRelease(spec, config, ctx) {
405
406
  }
406
407
  }
407
408
 
408
- const commands = [`git -C ${c.primaryPath} checkout ${base}`]
409
- if (c.worktreeExists) commands.push(`git -C ${spec.worktreePath} switch ${branch}`)
409
+ const commands = [`git -C ${shellPath(c.primaryPath)} checkout ${base}`]
410
+ if (c.worktreeExists) commands.push(`git -C ${shellPath(spec.worktreePath)} switch ${branch}`)
410
411
  return { ...result, commands, clears: true }
411
412
  }
412
413
 
@@ -457,8 +458,8 @@ function planAbort(config, ctx) {
457
458
 
458
459
  const branch = c.receipt.branch
459
460
  const commands = []
460
- if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${c.primaryPath} checkout ${base}`)
461
- if (c.worktreeExists) commands.push(`git -C ${c.worktreePath} switch ${branch}`)
461
+ if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${shellPath(c.primaryPath)} checkout ${base}`)
462
+ if (c.worktreeExists) commands.push(`git -C ${shellPath(c.worktreePath)} switch ${branch}`)
462
463
  return { ...result, commands, clears: true, branch }
463
464
  }
464
465
 
@@ -13,6 +13,12 @@
13
13
  * worktree, and `/no-spec` gives mechanical work a branch of its own. So the
14
14
  * guard is a push toward a path that exists rather than a refusal with no exit.
15
15
  *
16
+ * PR MODE CHANGES THE REASON, NOT THE BEHAVIOUR. Under `land.strategy: "pr"`
17
+ * the base branch moves when the host merges, so "where work lands" is the
18
+ * remote — which makes a local write on base MORE wrong, not less: it can
19
+ * never reach the remote base except by a push nobody reviews. The guard fires
20
+ * exactly as before.
21
+ *
16
22
  * THE ACCUSATION IS POSITIVE, AND ALL FOUR PARTS MUST HOLD. It is
17
23
  * `.claude/rules/negative-checks.md` rule 1 applied to a check that stops
18
24
  * someone working: isolation is configured, the guard is not switched off, this
@@ -27,7 +33,8 @@
27
33
  const fs = require('node:fs')
28
34
  const path = require('node:path')
29
35
 
30
- const { assertPrimaryOnMain, resolvePrimaryCheckout } = require('./resolve.js')
36
+ const { assertPrimaryOnMain } = require('./resolve.js')
37
+ const { primaryAnchor } = require('./project.js')
31
38
 
32
39
  // Where the allow lives. Gitignored, machine-local and beside the registry —
33
40
  // this is one person's decision about one session, never the project's policy.
@@ -163,7 +170,7 @@ function checkoutOf(target, gitAt) {
163
170
  // the same directory. Cannot-tell is "not the same", the branch that allows.
164
171
  function sameDir(a, b) {
165
172
  try {
166
- return fs.realpathSync(a) === fs.realpathSync(b)
173
+ return fs.realpathSync.native(a) === fs.realpathSync.native(b)
167
174
  } catch {
168
175
  return false
169
176
  }
@@ -212,12 +219,20 @@ function checkMainWrite(dir, config, git, opts = {}) {
212
219
  // the primary checkout's own, wherever the session is standing.
213
220
  let branchGit = git
214
221
  try {
215
- primary = resolvePrimaryCheckout(dir, git)
222
+ // `primary` is the PROJECT folder in the primary checkout — where the allow
223
+ // file lives. The question "is this write in the primary checkout?" is
224
+ // asked of its ROOT: `--show-toplevel` answers with the root, and a project
225
+ // in a subfolder of its repo compared the two, never matched, and let every
226
+ // write through. The whole primary checkout is guarded, not only the
227
+ // project folder: a write to `Sql/` on the base branch is unreviewed work
228
+ // too (feat-subfolder-project, decision 6).
229
+ const anchor = primaryAnchor(dir, git)
230
+ primary = anchor.dir
216
231
  if (opts.target && typeof opts.gitAt === 'function') {
217
232
  const top = checkoutOf(opts.target, opts.gitAt)
218
- isPrimary = Boolean(top) && Boolean(primary) && sameDir(top, primary)
233
+ isPrimary = Boolean(top) && Boolean(anchor.root) && sameDir(top, anchor.root)
219
234
  if (!isPrimary) return ALLOWS
220
- branchGit = opts.gitAt(primary)
235
+ branchGit = opts.gitAt(anchor.root)
221
236
  } else {
222
237
  isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
223
238
  }
@@ -0,0 +1,28 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Phase progress, read off the phase files' H1 emoji — the same emoji the phase
5
+ * index mirrors, and the one `/spec-review` names as authoritative.
6
+ *
7
+ * Shared by `spec-env handoff` (the ticket note) and the spec-state reader
8
+ * behind `skitterspec status`, so the two can never count one spec differently.
9
+ * Pure: each phase arrives as `{ file, content }`.
10
+ */
11
+
12
+ // How many are ✅, how many there are, and the first 🔄 (where the next owner
13
+ // picks up).
14
+ function phaseProgress(phases) {
15
+ const named = (phases || []).filter((p) => p && typeof p.content === 'string')
16
+ const heading = (p) => (p.content.split('\n').find((l) => /^#\s/.test(l)) || '').trim()
17
+ const done = named.filter((p) => heading(p).endsWith('✅')).length
18
+ const current = named.findIndex((p) => heading(p).endsWith('🔄'))
19
+ return { done, total: named.length, current: current === -1 ? null : current + 1 }
20
+ }
21
+
22
+ function progressText({ done, total, current }) {
23
+ if (!total) return 'no phase files'
24
+ const base = `${done} of ${total} phases done`
25
+ return current ? `${base}, phase ${current} in progress` : base
26
+ }
27
+
28
+ module.exports = { phaseProgress, progressText }