@skitterbyte/skitterspec-linear 19.3.0 → 19.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 (71) 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/linear.config.json.example +2 -2
  6. package/assets/core/linear.config.md +49 -16
  7. package/assets/hooks/main-guard.cjs +40 -6
  8. package/assets/hooks/review-gate.cjs +42 -7
  9. package/assets/rules/commit-trailers.md +24 -1
  10. package/assets/rules/spec-planning.md +81 -18
  11. package/assets/rules/spec-reports.md +1 -1
  12. package/assets/skills/spec/SKILL.md +55 -2
  13. package/assets/skills/spec-bug/SKILL.md +36 -3
  14. package/assets/skills/spec-cancel/SKILL.md +37 -0
  15. package/assets/skills/spec-claim/SKILL.md +41 -2
  16. package/assets/skills/spec-complete/SKILL.md +115 -0
  17. package/assets/skills/spec-hotfix/SKILL.md +51 -4
  18. package/assets/skills/spec-incident/SKILL.md +22 -0
  19. package/assets/skills/spec-linear-setup/SKILL.md +23 -1
  20. package/assets/skills/spec-next/SKILL.md +12 -5
  21. package/assets/skills/spec-push/SKILL.md +22 -0
  22. package/assets/skills/spec-review/SKILL.md +34 -0
  23. package/assets/skills/spec-start/SKILL.md +50 -3
  24. package/assets/skills/spec-status/SKILL.md +18 -3
  25. package/assets/skills/spec-sync/SKILL.md +1 -0
  26. package/assets/skills/spec-to-main/SKILL.md +47 -1
  27. package/package.json +1 -1
  28. package/src/cli.js +1188 -79
  29. package/src/env/base.js +104 -0
  30. package/src/env/bootstrap.js +22 -3
  31. package/src/env/classify.js +12 -4
  32. package/src/env/config.js +77 -5
  33. package/src/env/disposition.js +62 -0
  34. package/src/env/handoff.js +81 -0
  35. package/src/env/host.js +262 -0
  36. package/src/env/hotfix.js +237 -9
  37. package/src/env/hotfixland.js +105 -10
  38. package/src/env/inflight.js +98 -0
  39. package/src/env/integrate.js +136 -9
  40. package/src/env/live.js +8 -7
  41. package/src/env/mainguard.js +20 -5
  42. package/src/env/phases.js +28 -0
  43. package/src/env/project.js +223 -0
  44. package/src/env/provision.js +30 -8
  45. package/src/env/resolve.js +147 -25
  46. package/src/env/review.js +21 -7
  47. package/src/env/reviewers.js +7 -10
  48. package/src/env/serve.js +27 -11
  49. package/src/env/specstate.js +101 -0
  50. package/src/env/supervise.js +15 -2
  51. package/src/env/teardown.js +46 -3
  52. package/src/init.js +49 -9
  53. package/src/vendor/linear/cli-sanitise.js +8 -3
  54. package/src/vendor/linear/cli-sync.js +64 -10
  55. package/src/vendor/linear/config.js +27 -21
  56. package/src/vendor/linear/doctor.js +2 -0
  57. package/src/vendor/provider-kit/index.js +4 -0
  58. package/src/vendor/provider-kit/src/apply.js +58 -6
  59. package/src/vendor/provider-kit/src/assignment.js +78 -1
  60. package/src/vendor/provider-kit/src/config.js +34 -1
  61. package/src/vendor/provider-kit/src/credentials.js +7 -2
  62. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  63. package/src/vendor/provider-kit/src/released.js +48 -4
  64. package/src/vendor/provider-kit/src/specs.js +18 -7
  65. package/src/vendor/provider-kit/src/splice.js +64 -0
  66. package/src/vendor/provider-kit/src/status.js +137 -0
  67. package/src/vendor/sync-core/index.js +14 -1
  68. package/src/vendor/sync-core/src/compare.js +81 -6
  69. package/src/vendor/sync-core/src/normalize.js +50 -7
  70. package/src/vendor/sync-core/src/push.js +65 -5
  71. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -0,0 +1,104 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `spec-env base` — which branch skitterspec will fork from and land onto, and
5
+ * which in-flight specs forked from an older one.
6
+ *
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).
11
+ */
12
+
13
+ const HOW = Object.freeze({
14
+ pin: 'pinned by baseBranch',
15
+ pattern: 'newest match',
16
+ 'origin-head': 'origin/HEAD',
17
+ local: 'local branch',
18
+ fallback: 'nothing detected — default',
19
+ })
20
+
21
+ /**
22
+ * Which match a spec branch forked from: the one whose merge-base with the
23
+ * branch is newest. `matches` is newest-first; `mergeBase(name)` returns a sha
24
+ * or null; `isAncestor(a, b)` is true when `a` is an ancestor of (or equal to) `b`.
25
+ *
26
+ * WHAT WOULD FOOL THIS: a release candidate cut from a base that already holds
27
+ * the old rc's tip. Both merge-bases are then the same commit and nothing in
28
+ * the history says which one the spec was forked from — so a tie goes to the
29
+ * NEWER match, and the spec is not reported as behind. Being wrong that way
30
+ * costs a row that should have printed; the rebase onto the newer match is a
31
+ * no-op for exactly the commits the two share, so nothing lands wrong.
32
+ */
33
+ function forkMatch(matches, mergeBase, isAncestor) {
34
+ let best = null
35
+ for (const name of matches) {
36
+ const sha = mergeBase(name)
37
+ if (!sha) continue
38
+ // Strictly newer only: an equal merge-base keeps the newer match already held.
39
+ if (!best || (sha !== best.sha && isAncestor(best.sha, sha))) best = { name, sha }
40
+ }
41
+ return best ? best.name : null
42
+ }
43
+
44
+ /**
45
+ * Build the report. `facts`:
46
+ * { pattern, remote, base, how, fetch: { ok, reason } | null,
47
+ * matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }] }
48
+ * Returns `{ json, lines }`; the CLI prints one of them and always exits 0.
49
+ */
50
+ function planBaseReport(facts) {
51
+ const { pattern, remote, base, how } = facts
52
+ const matches = facts.matches || []
53
+ const fetch = facts.fetch || null
54
+ // Behind = forked from a match that is not the base. Only meaningful when the
55
+ // pattern chose the base: a pin is a deliberate choice of base, and the
56
+ // matches beside it are not competing for the role.
57
+ const stale =
58
+ how === 'pattern' && base
59
+ ? (facts.forks || []).filter((f) => f.forkedFrom && f.forkedFrom !== base)
60
+ : []
61
+
62
+ const json = {
63
+ base: base || null,
64
+ how,
65
+ pattern: pattern || null,
66
+ remote,
67
+ fetch,
68
+ matches: matches.map((m) => ({ ...m, base: m.name === base })),
69
+ stale,
70
+ }
71
+
72
+ const lines = []
73
+ if (!pattern) {
74
+ lines.push(`spec-env base: ${base} (${HOW[how]})`)
75
+ return { json, lines }
76
+ }
77
+
78
+ if (base) lines.push(`spec-env base: ${base} (${HOW[how]}${how === 'pin' ? ` — ${pattern} not used` : ` for ${pattern}`})`)
79
+ else lines.push(`spec-env base: none — no branch on ${remote} matches ${pattern}`)
80
+
81
+ if (fetch) {
82
+ lines.push(
83
+ fetch.ok
84
+ ? ` fetched ${remote}`
85
+ : ` fetch from ${remote} failed${fetch.reason ? ` (${fetch.reason})` : ''} — listing the refs already here`,
86
+ )
87
+ }
88
+
89
+ if (matches.length) {
90
+ const width = Math.max(...matches.map((m) => m.name.length))
91
+ for (const m of matches) {
92
+ const mark = m.name === base ? (how === 'pin' ? ' ← base (pin)' : ' ← base') : ''
93
+ lines.push(` ${m.name.padEnd(width)} ${m.date || ''}${mark}`.trimEnd())
94
+ }
95
+ }
96
+
97
+ if (stale.length) {
98
+ lines.push(' forked from an older match:')
99
+ for (const s of stale) lines.push(` ${s.spec} · forked from ${s.forkedFrom}`)
100
+ }
101
+ return { json, lines }
102
+ }
103
+
104
+ module.exports = { forkMatch, planBaseReport }
@@ -61,7 +61,7 @@ function lstatOrNull(fs, p) {
61
61
  * The target is tested with `lstat`, which does not: an existing link, even a
62
62
  * dangling one, is somebody's deliberate state and is left alone.
63
63
  */
64
- function runSeed(step, { cwd, mainRoot, fs }) {
64
+ function runSeed(step, { cwd, mainRoot, fs, platform = process.platform }) {
65
65
  const src = path.join(mainRoot, step.file)
66
66
  const dst = path.join(cwd, step.file)
67
67
  if (!fs.existsSync(src)) {
@@ -71,8 +71,26 @@ function runSeed(step, { cwd, mainRoot, fs }) {
71
71
  return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
72
72
  }
73
73
  fs.mkdirSync(path.dirname(dst), { recursive: true })
74
- if (step.mode === 'copy') fs.copyFileSync(src, dst)
75
- else fs.symlinkSync(src, dst)
74
+ if (step.mode === 'copy') {
75
+ fs.copyFileSync(src, dst)
76
+ return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
77
+ }
78
+ // WINDOWS WITHOUT DEVELOPER MODE CANNOT CREATE A SYMLINK (EPERM), and a
79
+ // seed is what makes a fresh worktree runnable at all (chore-windows-ci). A
80
+ // directory takes a junction there, which needs no privilege; a file that
81
+ // still cannot be linked is copied — said, because a copy does not follow
82
+ // later edits to the primary checkout's file the way a link would.
83
+ const dir = fs.statSync(src).isDirectory()
84
+ try {
85
+ fs.symlinkSync(src, dst, dir && platform === 'win32' ? 'junction' : undefined)
86
+ } catch (err) {
87
+ if (dir || !(err && (err.code === 'EPERM' || err.code === 'EACCES'))) throw err
88
+ fs.copyFileSync(src, dst)
89
+ return {
90
+ outcome: 'seeded',
91
+ line: `seeded ${step.file} → ${src} (copied — this machine cannot create symlinks)`,
92
+ }
93
+ }
76
94
  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
77
95
  }
78
96
 
@@ -157,6 +175,7 @@ function runBootstrap(steps, io) {
157
175
  cwd: io.cwd,
158
176
  mainRoot: io.mainRoot,
159
177
  fs: io.fs || realFs,
178
+ platform: io.platform || process.platform,
160
179
  spawn: io.spawn || spawnSync,
161
180
  childStdout: io.childStdout || 'inherit',
162
181
  }
@@ -17,6 +17,7 @@
17
17
 
18
18
  const path = require('node:path')
19
19
  const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
20
+ const { fromRepoPath, prefixOf } = require('./project.js')
20
21
 
21
22
  // git reports repo-relative, forward-slashed paths; an untracked directory comes
22
23
  // back with a trailing slash. Normalise both away so comparisons are exact.
@@ -66,7 +67,9 @@ function expandCompanion(pattern, spec, config) {
66
67
  /**
67
68
  * Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
68
69
  * not. Repo-relative paths in, repo-relative paths out; nothing is read from git
69
- * and nothing is written.
70
+ * and nothing is written. The spec's folders and companion paths are
71
+ * PROJECT-relative, so each path is converted with the config's prefix before it
72
+ * is compared — a path outside a subfolder project is never the spec's.
70
73
  *
71
74
  * Owned:
72
75
  * - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
@@ -89,11 +92,13 @@ function classifyDirtyTree(spec, dirtyPaths, config) {
89
92
  if (expanded) companions.add(expanded)
90
93
  }
91
94
 
95
+ const prefix = prefixOf(config)
92
96
  for (const raw of dirtyPaths || []) {
93
97
  const p = normalize(raw)
94
98
  if (!p) continue
95
- const inFolder = folders.some((f) => p === f || p.startsWith(`${f}/`))
96
- if (inFolder || companions.has(p)) owned.push(p)
99
+ const rel = fromRepoPath(p, prefix)
100
+ const inFolder = rel !== null && folders.some((f) => rel === f || rel.startsWith(`${f}/`))
101
+ if (inFolder || (rel !== null && companions.has(rel))) owned.push(p)
97
102
  else foreign.push(p)
98
103
  }
99
104
  return { owned, foreign }
@@ -129,7 +134,10 @@ function unquotePath(p) {
129
134
  function dirtyPaths(git) {
130
135
  const lists = [
131
136
  git(['diff', '--name-only', 'HEAD']),
132
- git(['ls-files', '--others', '--exclude-standard']),
137
+ // `--full-name`: `ls-files` answers relative to its cwd, `diff` from the repo
138
+ // root. Read from a subfolder project they disagreed, and every untracked
139
+ // spec document was classified as somebody else's.
140
+ git(['ls-files', '--others', '--exclude-standard', '--full-name']),
133
141
  ]
134
142
  if (lists.every((l) => l === null)) return null
135
143
  const out = []
package/src/env/config.js CHANGED
@@ -41,19 +41,27 @@
41
41
  * // spec alongside its own folder (provider-neutral; {slug} and
42
42
  * // {identifier} expand); empty = the spec folder only
43
43
  * baseBranch: "", // "" = auto-detect (origin/HEAD → main → master)
44
+ * baseBranchPattern: "", // glob over remote branch names; newest match
45
+ * // by commit date is the base (rolling release-candidate)
46
+ * land: { strategy, remote, draft, specDocs }, // how a branch lands:
47
+ * // "ff" (default, trunk-based local fast-forward) or "pr"
48
+ * // (push + pull request; base moves when the host merges)
44
49
  * guards: { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
45
50
  * teardown: { deleteRemoteBranch },
46
51
  * live: { migrations: [ "glob", ... ] } // migration globs → `live take`
47
52
  * // refuses a branch that changes them (code-only v1)
48
- * hotfix: { bump, cherryPickMain, targets } // `hotfix land`: patch-bump the
49
- * // deploy tag, also cherry-pick onto the base branch (main), and
50
- * // onto any extra base tags in `targets` (test/demo lines)
53
+ * hotfix: { bump, cherryPickMain, targets, releaseWith, releaseBranch, tag }
54
+ * // `hotfix land`: patch-bump the deploy tag, also cherry-pick
55
+ * // onto the base branch (main), and onto any extra base tags in
56
+ * // `targets` (test/demo lines). `releaseBranch` makes the hotfix
57
+ * // branch-based: it forks from <remote>/<releaseBranch> instead
58
+ * // of a tag; `tag` keeps (true) or drops the release-tag cut
51
59
  * }
52
60
  */
53
61
 
54
62
  const { createHash } = require('node:crypto')
55
63
  const { readFileSync, realpathSync } = require('node:fs')
56
- const { join, resolve } = require('node:path')
64
+ const { join, resolve, sep } = require('node:path')
57
65
 
58
66
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
59
67
 
@@ -206,6 +214,26 @@ const DEFAULT_CONFIG = Object.freeze({
206
214
  spec: Object.freeze({ companionPaths: Object.freeze([]) }),
207
215
  // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
208
216
  baseBranch: '',
217
+ // A glob over the remote's branch names (`"20??/Q?"`) for a base that rolls:
218
+ // the newest match by commit date is the base, so cutting the next release
219
+ // candidate is all it takes to move every spec onto it. An explicit
220
+ // `baseBranch` still wins. Empty = off, and resolution is exactly as before.
221
+ baseBranchPattern: '',
222
+ // How a finished branch reaches the base branch. `strategy: "ff"` (the
223
+ // default) is trunk-based landing exactly as it has always been: rebase, then
224
+ // a local `merge --ff-only` — nothing changes for an installed repo on
225
+ // upgrade. `"pr"` lands by pushing the branch and opening a pull request on
226
+ // the host: the base branch moves only when the host merges, so integrate's
227
+ // plan ends in a consent-gated push (the hotfix pattern: already-pushed is
228
+ // honoured, `--push` is the recorded yes, otherwise the plan holds) and the
229
+ // project's `afterLand` commands are deferred to the completion run that
230
+ // follows the merge. `remote` names where the branch is pushed. `draft`
231
+ // opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
232
+ // downstream can close a ticket early). `specDocs` decides where a spec
233
+ // DOCUMENT lands under "pr": "trunk" keeps today's authoring land (needs
234
+ // direct push for docs), "branch" has the spec ride the feature branch and
235
+ // land with the work's PR.
236
+ land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
209
237
  // `mainIsLandingZone` defaults ON wherever isolation is configured, matching
210
238
  // the review gate's precedent: the push toward not working on the base branch
211
239
  // is the normal path, and stepping off it is the deliberate act. That does
@@ -301,11 +329,19 @@ const DEFAULT_CONFIG = Object.freeze({
301
329
  // `releaseWith` is a project's own release command, run in the hotfix
302
330
  // worktree in place of the built-in tagger — e.g. skittership's
303
331
  // `node scripts/release-hotfix.cjs --json`. Empty (the default) = built-in.
332
+ // `releaseBranch` names a release LINE that is a branch rather than a tag
333
+ // (e.g. "master", where prod is whatever master holds): the hotfix forks from
334
+ // the remote's head of it and records `Base version: <branch>@<sha>`. Empty
335
+ // (the default) = today's tag-based hotfix, unchanged. `tag` (default true)
336
+ // keeps the release-tag cut; false is for a team whose deploy is driven by a
337
+ // branch merge rather than a tag.
304
338
  hotfix: Object.freeze({
305
339
  bump: 'patch',
306
340
  cherryPickMain: true,
307
341
  targets: Object.freeze([]),
308
342
  releaseWith: '',
343
+ releaseBranch: '',
344
+ tag: true,
309
345
  }),
310
346
  })
311
347
 
@@ -370,6 +406,8 @@ function defaults() {
370
406
  branch: { ...DEFAULT_CONFIG.branch },
371
407
  spec: { companionPaths: [] },
372
408
  baseBranch: DEFAULT_CONFIG.baseBranch,
409
+ baseBranchPattern: DEFAULT_CONFIG.baseBranchPattern,
410
+ land: { ...DEFAULT_CONFIG.land },
373
411
  guards: { ...DEFAULT_CONFIG.guards },
374
412
  teardown: { ...DEFAULT_CONFIG.teardown },
375
413
  review: { ...DEFAULT_CONFIG.review, reviewers: [] },
@@ -637,6 +675,15 @@ function mergeConfig(base, parsed) {
637
675
  assign(base, parsed, 'registry', 'string')
638
676
  assign(base, parsed, 'baseBranch', 'string')
639
677
 
678
+ // Dropped rather than thrown on, like every field here — and dropping is the
679
+ // safe direction: an unusable pattern resolves the base exactly as an unset
680
+ // one does. Whitespace and `..` can never name a branch, so a pattern holding
681
+ // either is a typo, not a glob.
682
+ if (typeof parsed.baseBranchPattern === 'string') {
683
+ const pattern = parsed.baseBranchPattern.trim()
684
+ if (pattern && !/\s/.test(pattern) && !pattern.includes('..')) base.baseBranchPattern = pattern
685
+ }
686
+
640
687
  // Same treatment as `teardown.deleteRemoteBranch` below, for the same reason:
641
688
  // an unrecognised value falls through to the default rather than erroring or
642
689
  // being taken literally. The fallback direction matters — "worktree" is the
@@ -646,6 +693,23 @@ function mergeConfig(base, parsed) {
646
693
  base.mode = parsed.mode
647
694
  }
648
695
 
696
+ // The enums fall through to their defaults on an unrecognised value, like
697
+ // `mode` above — and the fallback direction matters the same way: "ff" is the
698
+ // conservative strategy (nothing leaves the machine), so a typo ("PR",
699
+ // "pull-request") costs a local land that was meant to be a push, never a
700
+ // push that was meant to stay local. Same for `specDocs`: "trunk" is today's
701
+ // behaviour.
702
+ if (isObject(parsed.land)) {
703
+ if (parsed.land.strategy === 'ff' || parsed.land.strategy === 'pr') {
704
+ base.land.strategy = parsed.land.strategy
705
+ }
706
+ assign(base.land, parsed.land, 'remote', 'string')
707
+ assign(base.land, parsed.land, 'draft', 'boolean')
708
+ if (parsed.land.specDocs === 'trunk' || parsed.land.specDocs === 'branch') {
709
+ base.land.specDocs = parsed.land.specDocs
710
+ }
711
+ }
712
+
649
713
  if (isObject(parsed.guards)) {
650
714
  assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
651
715
  assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
@@ -739,6 +803,14 @@ function mergeConfig(base, parsed) {
739
803
  assign(base.hotfix, parsed.hotfix, 'bump', 'string')
740
804
  assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
741
805
  assign(base.hotfix, parsed.hotfix, 'releaseWith', 'string')
806
+ assign(base.hotfix, parsed.hotfix, 'tag', 'boolean')
807
+ // Trimmed, and dropped when it could never name a branch — the same
808
+ // direction as `baseBranchPattern`: unusable means unset, which is the
809
+ // tag-based flow every hotfix had before this key existed.
810
+ if (typeof parsed.hotfix.releaseBranch === 'string') {
811
+ const name = parsed.hotfix.releaseBranch.trim()
812
+ if (name && !/[\s@~^:?*[\\]/.test(name) && !name.includes('..')) base.hotfix.releaseBranch = name
813
+ }
742
814
  if (Array.isArray(parsed.hotfix.targets)) {
743
815
  base.hotfix.targets = normalizeFileList(parsed.hotfix.targets)
744
816
  }
@@ -819,7 +891,7 @@ function loadEnvConfig(dir = process.cwd()) {
819
891
  try {
820
892
  parsed = JSON.parse(raw)
821
893
  } catch (error) {
822
- throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
894
+ throw new Error(`Invalid ${CONFIG_FILE.split(sep).join('/')}: ${error.message}`)
823
895
  }
824
896
 
825
897
  return {
@@ -0,0 +1,62 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Disposition enumeration for `spec-env disposition` — the input to
5
+ * /spec-complete's PR-mode guard.
6
+ *
7
+ * Once a PR is ready, anyone can merge from the host's UI and the tracker
8
+ * closes the ticket, so readying it is the last moment skitterspec is
9
+ * guaranteed to be standing there. Before that happens, every loose end is
10
+ * ENUMERATED here and DISPOSED by the operator in the skill (tick with
11
+ * evidence · spin off as a linked ticket · drop with a recorded reason).
12
+ * Enumeration is automatic; deciding is human — the same split the review
13
+ * marks use, and like them this is information: nothing here refuses, counts
14
+ * toward a gate, or exits non-zero.
15
+ *
16
+ * Pure: the caller reads the files and hands them over, so every shape is
17
+ * unit-testable with no filesystem.
18
+ *
19
+ * @param {object} input { overview, phases: [{ file, content }] }
20
+ * @returns {object} { tasks, phases, followUps, clean }
21
+ * tasks — unticked `- [ ]` items, per phase file, with line numbers
22
+ * phases — phase-index rows whose status is not ✅
23
+ * followUps — Changelog `Follow-up surfaced:` lines (all of them: whether a
24
+ * spec was later written for one is not knowable from this file,
25
+ * so the operator reads the list rather than trusting a guess)
26
+ * clean — nothing enumerated; the guard has nothing to ask about
27
+ */
28
+ function collectDisposition(input) {
29
+ const overview = (input && input.overview) || ''
30
+ const phaseFiles = (input && Array.isArray(input.phases)) ? input.phases : []
31
+
32
+ const tasks = []
33
+ for (const { file, content } of phaseFiles) {
34
+ const lines = String(content || '').split('\n')
35
+ lines.forEach((line, i) => {
36
+ const m = line.match(/^\s*- \[ \] (.+)$/)
37
+ if (m) tasks.push({ file, line: i + 1, text: m[1].trim() })
38
+ })
39
+ }
40
+
41
+ // Phase-index rows: | <n> | <title> | <status> | [<file>](<file>) | — only
42
+ // rows whose status cell is not ✅. The index is the overview's summary of
43
+ // the phase files, so a row here and no unticked tasks usually means the
44
+ // index lagged; both are listed and the operator reconciles.
45
+ const phases = []
46
+ for (const line of overview.split('\n')) {
47
+ const m = line.match(/^\|\s*(\d+)\s*\|\s*(.+?)\s*\|\s*([^|]+?)\s*\|\s*\[([^\]]+)\]/)
48
+ if (m && !m[3].includes('✅')) {
49
+ phases.push({ n: Number(m[1]), title: m[2], status: m[3].trim(), file: m[4] })
50
+ }
51
+ }
52
+
53
+ const followUps = []
54
+ for (const line of overview.split('\n')) {
55
+ const m = line.match(/Follow-up surfaced:\s*(.+)$/)
56
+ if (m) followUps.push({ text: m[1].trim() })
57
+ }
58
+
59
+ return { tasks, phases, followUps, clean: !tasks.length && !phases.length && !followUps.length }
60
+ }
61
+
62
+ module.exports = { collectDisposition }
@@ -0,0 +1,81 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `spec-env handoff <spec>` — make a spec's work reachable by its next owner.
5
+ *
6
+ * A spec branch lives in a local worktree, and nothing requires it ever to
7
+ * reach a remote — so a ticket handed to someone else points at code only its
8
+ * old owner can see. This plans the two things that close that: the branch
9
+ * published (a push the operator consents to, since it is outward-facing), and
10
+ * a note for the ticket naming where the work is. `/spec-start` on the new
11
+ * owner's machine then resumes from the published branch rather than forking.
12
+ *
13
+ * Pure: every fact arrives as an argument, so each answer is testable without a
14
+ * repo. The CLI reads git and writes the note.
15
+ */
16
+
17
+ const { phaseProgress, progressText } = require('./phases.js')
18
+ const { shellPath } = require('./project.js')
19
+
20
+ // Uncommitted work cannot travel with a push, so a hand-over would silently
21
+ // leave it behind in the old worktree. The engine declares the way out rather
22
+ // than leaving the skill to infer one (`offered-unblocks.md`): committing is
23
+ // what the guard asks for, so it is a `satisfy`, and nothing is weakened.
24
+ const COMMIT_FIRST = Object.freeze({ kind: 'satisfy', label: 'Commit first, then hand it over', command: '/commit' })
25
+
26
+ /**
27
+ * @param {object} f
28
+ * - `spec` `{ folder, branch, worktreePath }`
29
+ * - `worktree` true when the worktree exists on this machine
30
+ * - `dirtyPaths` uncommitted paths in that worktree ([] when clean)
31
+ * - `remote` the remote name, and `remoteConfigured` whether it exists
32
+ * - `headSha` the worktree's HEAD
33
+ * - `remoteSha` the branch's sha on the remote, '' when unpublished,
34
+ * null when the remote could not be asked
35
+ * - `phases` `[{ file, content }]`
36
+ */
37
+ function planHandoff(f) {
38
+ const { spec } = f
39
+ const refuse = (reason, offer) => ({ blocked: true, reason, ...(offer ? { offer } : {}) })
40
+
41
+ if (!f.worktree) {
42
+ return refuse(`${spec.folder} has no worktree on this machine — hand it over from wherever it is being built`)
43
+ }
44
+ if (f.dirtyPaths && f.dirtyPaths.length) {
45
+ return refuse(
46
+ `${spec.folder}'s worktree has ${f.dirtyPaths.length} uncommitted path(s) — a push carries commits, so they would stay behind`,
47
+ COMMIT_FIRST,
48
+ )
49
+ }
50
+ if (!f.remoteConfigured) {
51
+ return refuse(`no remote named ${f.remote} — publish ${spec.branch} somewhere the new owner can reach first`)
52
+ }
53
+
54
+ const progress = phaseProgress(f.phases)
55
+ // Published AT HEAD is the positive signal the push is already done; an
56
+ // unpublished branch and a stale one both need it, and a remote that could
57
+ // not be asked is planned as if it does (a redundant push is harmless).
58
+ const published = Boolean(f.headSha && f.remoteSha && f.remoteSha === f.headSha)
59
+ const commands = published ? [] : [`git -C ${shellPath(spec.worktreePath)} push -u ${f.remote} ${spec.branch}`]
60
+ const sha = (f.headSha || '').slice(0, 12)
61
+ const note = [
62
+ `**Handed over** — the work is on \`${spec.branch}\` at \`${sha}\` (${f.remote}), ${progressText(progress)}.`,
63
+ '',
64
+ `\`/spec-start ${spec.folder}\` resumes from that branch rather than forking a new one.`,
65
+ '',
66
+ ].join('\n')
67
+
68
+ return {
69
+ blocked: false,
70
+ branch: spec.branch,
71
+ sha,
72
+ remote: f.remote,
73
+ published,
74
+ remoteUnknown: f.remoteSha === null,
75
+ progress,
76
+ commands,
77
+ note,
78
+ }
79
+ }
80
+
81
+ module.exports = { planHandoff, phaseProgress, progressText, COMMIT_FIRST }