@skitterbyte/skitterspec-linear 19.2.0 → 19.4.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 (60) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/env.config.json.example +1 -0
  3. package/assets/core/env.config.md +90 -6
  4. package/assets/core/linear.config.json.example +2 -2
  5. package/assets/core/linear.config.md +49 -16
  6. package/assets/hooks/main-guard.cjs +18 -2
  7. package/assets/hooks/review-gate.cjs +19 -2
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +131 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +95 -6
  12. package/assets/skills/spec-bug/SKILL.md +68 -3
  13. package/assets/skills/spec-cancel/SKILL.md +37 -0
  14. package/assets/skills/spec-claim/SKILL.md +41 -2
  15. package/assets/skills/spec-complete/SKILL.md +115 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +72 -4
  17. package/assets/skills/spec-incident/SKILL.md +44 -0
  18. package/assets/skills/spec-linear-setup/SKILL.md +23 -1
  19. package/assets/skills/spec-next/SKILL.md +12 -5
  20. package/assets/skills/spec-push/SKILL.md +22 -0
  21. package/assets/skills/spec-review/SKILL.md +34 -0
  22. package/assets/skills/spec-start/SKILL.md +50 -3
  23. package/assets/skills/spec-status/SKILL.md +18 -3
  24. package/assets/skills/spec-sync/SKILL.md +1 -0
  25. package/assets/skills/spec-to-main/SKILL.md +47 -1
  26. package/package.json +1 -1
  27. package/src/cli.js +1091 -39
  28. package/src/env/base.js +104 -0
  29. package/src/env/config.js +75 -3
  30. package/src/env/disposition.js +62 -0
  31. package/src/env/handoff.js +80 -0
  32. package/src/env/host.js +262 -0
  33. package/src/env/hotfix.js +225 -0
  34. package/src/env/hotfixland.js +103 -9
  35. package/src/env/inflight.js +95 -0
  36. package/src/env/integrate.js +130 -4
  37. package/src/env/mainguard.js +6 -0
  38. package/src/env/phases.js +28 -0
  39. package/src/env/provision.js +18 -6
  40. package/src/env/resolve.js +108 -9
  41. package/src/env/serve.js +6 -1
  42. package/src/env/specstate.js +101 -0
  43. package/src/env/teardown.js +42 -0
  44. package/src/vendor/linear/cli-sync.js +55 -6
  45. package/src/vendor/linear/config.js +27 -21
  46. package/src/vendor/linear/doctor.js +2 -0
  47. package/src/vendor/provider-kit/index.js +4 -0
  48. package/src/vendor/provider-kit/src/apply.js +49 -4
  49. package/src/vendor/provider-kit/src/assignment.js +78 -1
  50. package/src/vendor/provider-kit/src/config.js +34 -1
  51. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  52. package/src/vendor/provider-kit/src/released.js +14 -1
  53. package/src/vendor/provider-kit/src/specs.js +4 -2
  54. package/src/vendor/provider-kit/src/splice.js +64 -0
  55. package/src/vendor/provider-kit/src/status.js +137 -0
  56. package/src/vendor/sync-core/index.js +14 -1
  57. package/src/vendor/sync-core/src/compare.js +17 -5
  58. package/src/vendor/sync-core/src/normalize.js +50 -7
  59. package/src/vendor/sync-core/src/push.js +26 -2
  60. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -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
@@ -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 }
@@ -351,12 +351,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
351
351
  // A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
352
352
  // `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
353
353
  // line prod runs. Attaching an existing branch ignores baseRef (already forked).
354
- const forkPoint = !attached && spec.baseRef ? ` ${spec.baseRef}` : ''
355
- commands.push(
356
- attached
357
- ? `git worktree add ${spec.worktreePath} ${spec.branch}`
358
- : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
359
- )
354
+ // A rolling base sets `spec.forkFrom` when the primary checkout is not on it.
355
+ // A branch already published (`spec.resumeFrom` — a handed-over spec) is
356
+ // fetched and built from instead: the work is there, and a fresh fork would
357
+ // strand it. It outranks every fork point, a hotfix's tag included, because
358
+ // the branch already forked from wherever it was meant to.
359
+ const forkFrom = spec.baseRef || spec.forkFrom
360
+ const forkPoint = !attached && forkFrom ? ` ${forkFrom}` : ''
361
+ const resume = !attached && spec.resumeFrom ? spec.resumeFrom : null
362
+ if (resume) {
363
+ commands.push(`git fetch ${resume.remote} ${spec.branch}`)
364
+ commands.push(`git worktree add ${spec.worktreePath} -b ${spec.branch} --track ${resume.remote}/${spec.branch}`)
365
+ } else {
366
+ commands.push(
367
+ attached
368
+ ? `git worktree add ${spec.worktreePath} ${spec.branch}`
369
+ : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
370
+ )
371
+ }
360
372
  // The tree gate. A worktree forks from the base branch's tree, so an
361
373
  // uncommitted spec would produce a branch missing the spec it is for — this is
362
374
  // where that gets committed, or refused. Worktree mode had NO clean gate before
@@ -384,6 +384,27 @@ function readBaseVersionField(specPath) {
384
384
  return m[1].trim().replace(/^["'`]|["'`]$/g, '') || null
385
385
  }
386
386
 
387
+ /**
388
+ * Parse a `Base version` value. Two forms:
389
+ * - a release tag, `v33.16.4` → `{ kind: 'tag', tag, ref }`
390
+ * - a release BRANCH at a commit, `master@1a2b3c4d5e6f` → `{ kind: 'branch',
391
+ * branch, sha, ref }`, written by a branch-based hotfix (`hotfix.releaseBranch`)
392
+ * `ref` is what a worktree forks from: the tag, or the sha — never the branch
393
+ * name, which has moved on since the hotfix was cut.
394
+ *
395
+ * WHAT WOULD FOOL THIS: a tag literally shaped `<name>@<7–40 hex chars>`. Version
396
+ * tags carry dots (`skitterspec@1.4.0`), so they never match; a tag that did
397
+ * would be read as a branch form and fork from that sha, which is the commit
398
+ * the tag points at only if someone named it that way on purpose.
399
+ */
400
+ function parseBaseVersion(value) {
401
+ if (typeof value !== 'string' || !value.trim()) return null
402
+ const v = value.trim()
403
+ const m = /^([^@\s]+)@([0-9a-f]{7,40})$/i.exec(v)
404
+ if (m) return { kind: 'branch', branch: m[1], sha: m[2], ref: m[2] }
405
+ return { kind: 'tag', tag: v, ref: v }
406
+ }
407
+
387
408
  /**
388
409
  * Derive the git branch for a spec from the provider-neutral `branch.pattern`
389
410
  * (`{type}`, `{slug}`, and optionally `{identifier}`). When the pattern uses
@@ -404,31 +425,102 @@ function branchFor(spec, config) {
404
425
  return expandTokens(branch, tokens)
405
426
  }
406
427
 
428
+ /**
429
+ * Thrown when `baseBranchPattern` is set and no remote branch matches it. A
430
+ * refusal, never a fall-through: the default branch is exactly where a rolling
431
+ * base must not land. `refused` carries the one-line reason; `pattern` the glob.
432
+ */
433
+ class BaseUnresolvedError extends Error {
434
+ constructor(pattern) {
435
+ const refused = `no branch matches ${pattern} — run spec-env base to fetch`
436
+ super(refused)
437
+ this.name = 'BaseUnresolvedError'
438
+ this.refused = refused
439
+ this.pattern = pattern
440
+ }
441
+ }
442
+
407
443
  /**
408
444
  * Resolve the integration base branch (the branch specs fork from and land back
409
445
  * onto). Precedence:
410
446
  * 1. `config.baseBranch` — explicit override
411
- * 2. `origin/HEAD` — the remote's default branch
412
- * 3. `main` if it exists locally
413
- * 4. `master` if it exists locally
414
- * 5. `main` — last-resort default
447
+ * 2. `config.baseBranchPattern` — the newest remote branch matching it, by
448
+ * committer date; no match throws `BaseUnresolvedError`
449
+ * 3. `origin/HEAD` — the remote's default branch
450
+ * 4. `main` if it exists locally
451
+ * 5. `master` if it exists locally
452
+ * 6. `main` — last-resort default
415
453
  *
416
454
  * `git(args)` runs a read-only git command and returns trimmed stdout, or `null`
417
455
  * on a non-zero exit / failure. It's injected so this stays pure and unit-testable
418
456
  * with no live git; the CLI supplies a real reader. (Note: `show-ref --quiet`
419
457
  * emits no stdout on success, so a non-null `''` still means "exists".)
458
+ *
459
+ * Step 2 reads remote-tracking refs and never the network, so it stays
460
+ * synchronous for every caller, the main-guard hook included. Fetching is left
461
+ * to the commands that already talk to the remote.
420
462
  */
421
463
  function resolveBaseBranch(config, git) {
464
+ const { base, refused } = describeBaseBranch(config, git)
465
+ if (refused) throw refused
466
+ return base
467
+ }
468
+
469
+ /**
470
+ * The same resolution as `resolveBaseBranch`, returned as data with HOW it was
471
+ * found — `pin` · `pattern` · `origin-head` · `local` · `fallback` — for the
472
+ * one surface that reports it (`spec-env base`). A pattern with no match comes
473
+ * back as `{ base: null, how: 'pattern', refused }` rather than thrown, so a
474
+ * listing can still say what it saw.
475
+ */
476
+ function describeBaseBranch(config, git) {
422
477
  const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
423
- if (explicit) return explicit
478
+ if (explicit) return { base: explicit, how: 'pin' }
479
+
480
+ const pattern = config && typeof config.baseBranchPattern === 'string' && config.baseBranchPattern.trim()
481
+ if (pattern) {
482
+ try {
483
+ return { base: newestMatch(config, git, pattern), how: 'pattern' }
484
+ } catch (error) {
485
+ if (error instanceof BaseUnresolvedError) return { base: null, how: 'pattern', refused: error }
486
+ throw error
487
+ }
488
+ }
424
489
 
425
490
  const originHead = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
426
- if (originHead) return originHead.replace(/^origin\//, '')
491
+ if (originHead) return { base: originHead.replace(/^origin\//, ''), how: 'origin-head' }
427
492
 
428
493
  for (const name of ['main', 'master']) {
429
- if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return name
494
+ if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return { base: name, how: 'local' }
430
495
  }
431
- return 'main'
496
+ return { base: 'main', how: 'fallback' }
497
+ }
498
+
499
+ // The newest remote-tracking branch matching `pattern`, prefix stripped.
500
+ //
501
+ // WHAT WOULD FOOL THIS: an unfetched remote. A release candidate cut since the
502
+ // last fetch is invisible here, and no rc at all looks identical to "never
503
+ // fetched" — so an empty answer refuses rather than concluding anything, and
504
+ // names the verb that fetches. A stale-but-present answer is the older rc;
505
+ // `up` and `integrate` fetch before resolving so they never act on one.
506
+ function baseRemote(config) {
507
+ return (config && config.land && typeof config.land.remote === 'string' && config.land.remote.trim()) || 'origin'
508
+ }
509
+
510
+ function newestMatch(config, git, pattern) {
511
+ const remote = baseRemote(config)
512
+ const prefix = `refs/remotes/${remote}/`
513
+ const out = git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)', `${prefix}${pattern}`])
514
+ const names = (out || '')
515
+ .split('\n')
516
+ .map((line) => line.trim())
517
+ .filter((ref) => ref.startsWith(prefix))
518
+ .map((ref) => ref.slice(prefix.length))
519
+ // `origin/HEAD` is a symref to the default branch, and a broad pattern
520
+ // (`*`) would otherwise match it.
521
+ .filter((name) => name && name !== 'HEAD')
522
+ if (names.length === 0) throw new BaseUnresolvedError(pattern)
523
+ return names[0]
432
524
  }
433
525
 
434
526
  /**
@@ -528,6 +620,7 @@ function resolveSpecless(name, dir, config, entry = {}) {
528
620
  slug,
529
621
  stack: 'worktree',
530
622
  baseRef: null,
623
+ baseVersion: null,
531
624
  specless: true,
532
625
  unwritten: authored,
533
626
  }
@@ -580,7 +673,8 @@ function resolveSpec(specArg, dir, config, opts = {}) {
580
673
  const stack = readStackField(found.path, config)
581
674
  // A hotfix forks its worktree from a release tag (its `Base version`) instead
582
675
  // of base HEAD; every other type resolves to baseRef:null (fork from HEAD).
583
- const baseRef = type === 'hotfix' ? readBaseVersionField(found.path) : null
676
+ const baseVersion = type === 'hotfix' ? parseBaseVersion(readBaseVersionField(found.path)) : null
677
+ const baseRef = baseVersion ? baseVersion.ref : null
584
678
  // `specless: false` is written out rather than left off, so every consumer
585
679
  // reads the same field on every resolution instead of treating `undefined` as
586
680
  // an answer.
@@ -592,6 +686,7 @@ function resolveSpec(specArg, dir, config, opts = {}) {
592
686
  slug,
593
687
  stack,
594
688
  baseRef,
689
+ baseVersion,
595
690
  specless: false,
596
691
  }
597
692
  const branch = branchFor(spec, config)
@@ -705,6 +800,9 @@ module.exports = {
705
800
  collectSpecFolders,
706
801
  allSpecs,
707
802
  resolveBaseBranch,
803
+ describeBaseBranch,
804
+ baseRemote,
805
+ BaseUnresolvedError,
708
806
  resolvePrimaryCheckout,
709
807
  currentBranch,
710
808
  assertPrimaryOnMain,
@@ -721,4 +819,5 @@ module.exports = {
721
819
  readFrontmatterField,
722
820
  readStackField,
723
821
  readBaseVersionField,
822
+ parseBaseVersion,
724
823
  }
package/src/env/serve.js CHANGED
@@ -40,6 +40,7 @@ const { readRegistry } = require('./registry.js')
40
40
  const { loadEnvConfig } = require('./config.js')
41
41
  const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
42
42
  const { liveStateFor } = require('./live.js')
43
+ const { preferRemoteBase } = require('./host.js')
43
44
  const {
44
45
  rawGitReader,
45
46
  collectReview,
@@ -557,7 +558,11 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
557
558
  const out = git(argv)
558
559
  return out == null ? null : String(out).trim() || null
559
560
  }
560
- const base = () => spec.baseRef || resolveBaseBranch(config, trimmed)
561
+ // PR mode measures the diff against the REMOTE image of base — local base is
562
+ // allowed to go stale there. `preferRemoteBase` never fetches and falls back
563
+ // to the local name, so the render stays offline-safe.
564
+ const base = () =>
565
+ spec.baseRef || preferRemoteBase(config, resolveBaseBranch(config, trimmed), trimmed)
561
566
 
562
567
  const now = new Date().toISOString()
563
568
  let mode = 'working'
@@ -0,0 +1,101 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * What a spec's own copy says about it — the reader behind `skitterspec status`.
5
+ *
6
+ * Point it at a worktree (or any checkout) and a spec folder name, and it reports
7
+ * the bucket the spec sits in THERE, its phase progress, and any `Status:` /
8
+ * `Developer:` header it still carries. Pure but for the injected `io`, so the
9
+ * command layer is testable without a worktree and this without a CLI.
10
+ *
11
+ * THE BUCKET IS READ FROM THE ROOT IT IS GIVEN. On the base branch an in-flight
12
+ * spec still sits in `backlog/`, which is the very lie this exists to correct, so
13
+ * the caller hands it the worktree's root, never the checkout it is standing in.
14
+ *
15
+ * A MISSING `Status:` HEADER IS NOT UNKNOWN. Under `sync.fieldOwnership`
16
+ * `workflowState: "pull"` new specs carry no `Status:` or `Developer:` line —
17
+ * the board owns both — so `status: null` is the expected shape, and the bucket
18
+ * and progress still answer. Only a spec that cannot be found or read is
19
+ * `found: false`, and the caller renders that as `status unknown` rather than
20
+ * dropping it (Decision 5).
21
+ */
22
+
23
+ const fs = require('node:fs')
24
+ const path = require('node:path')
25
+
26
+ const { phaseProgress } = require('./phases.js')
27
+
28
+ // Most live first: a spec that exists in two buckets mid-`git mv` is reported
29
+ // where it is going, not where it was.
30
+ const SEARCH = ['in-progress', 'backlog', 'complete', 'cancelled']
31
+
32
+ const defaultIo = {
33
+ readdir: (dir) => fs.readdirSync(dir),
34
+ readFile: (file) => fs.readFileSync(file, 'utf8'),
35
+ }
36
+
37
+ // A header line's value, or null when the line is absent, empty, or the `—`
38
+ // placeholder the templates write before anyone is named.
39
+ function header(text, field) {
40
+ const m = new RegExp(`^>\\s*\\*\\*${field}:\\*\\*[ \\t]*(.*)$`, 'm').exec(text)
41
+ if (!m) return null
42
+ const value = m[1].trim()
43
+ return value && value !== '—' && value !== '-' ? value : null
44
+ }
45
+
46
+ // Inline phases, for the legacy overview with no phase files: `## Phase N …`
47
+ // headings carrying the same emoji the phase files do. Nothing countable is
48
+ // null, never zero — "no phases" and "could not see the phases" differ.
49
+ function inlineProgress(text) {
50
+ const headings = text.split('\n').filter((l) => /^#{2,3}\s+Phase\s+\d+\b/.test(l))
51
+ if (!headings.length) return null
52
+ return phaseProgress(headings.map((h) => ({ content: h.replace(/^#+/, '#') })))
53
+ }
54
+
55
+ function tryRead(io, fn) {
56
+ try {
57
+ return fn()
58
+ } catch {
59
+ return null
60
+ }
61
+ }
62
+
63
+ /**
64
+ * @param {string} root the checkout to read — a spec's worktree, normally
65
+ * @param {string} folder the spec's folder name (`feat-x`)
66
+ * @param {object} [io] `{ readdir, readFile }`, each throwing on failure
67
+ * @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer }
68
+ * | { found: false, reason }}
69
+ */
70
+ function readSpecState(root, folder, io = defaultIo) {
71
+ for (const bucket of SEARCH) {
72
+ const dir = path.join(root, 'specs', bucket, folder)
73
+ const files = tryRead(io, () => io.readdir(dir))
74
+ if (files) {
75
+ const overview = tryRead(io, () => io.readFile(path.join(dir, '00-overview.md')))
76
+ if (overview === null) return { found: false, reason: `${bucket}/${folder} has no readable 00-overview.md` }
77
+ const phaseFiles = files.filter((f) => /^(?!00-)\d{2}-.*\.md$/.test(f)).sort()
78
+ const phases = phaseFiles.map((f) => ({ file: f, content: tryRead(io, () => io.readFile(path.join(dir, f))) }))
79
+ const progress = phases.length ? phaseProgress(phases) : inlineProgress(overview)
80
+ return state(bucket, false, overview, progress)
81
+ }
82
+ const bare = tryRead(io, () => io.readFile(path.join(root, 'specs', bucket, `${folder}.md`)))
83
+ if (bare !== null) return state(bucket, true, bare, inlineProgress(bare))
84
+ }
85
+ return { found: false, reason: `no spec named ${folder} under specs/` }
86
+ }
87
+
88
+ function state(bucket, legacy, text, progress) {
89
+ return {
90
+ found: true,
91
+ bucket,
92
+ legacy,
93
+ phasesDone: progress ? progress.done : null,
94
+ phasesTotal: progress ? progress.total : null,
95
+ currentPhase: progress ? progress.current : null,
96
+ status: header(text, 'Status'),
97
+ developer: header(text, 'Developer'),
98
+ }
99
+ }
100
+
101
+ module.exports = { readSpecState, SEARCH }
@@ -59,6 +59,28 @@ function planDown(spec, config, flags, ctx) {
59
59
  if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed && !landed) {
60
60
  return blocked('worktree has unpushed commits not yet merged into the base branch')
61
61
  }
62
+ // PR mode: `merged` already includes the host's answer (the CLI folds a
63
+ // merged PR in before planning), so an UNLANDED branch here really is one
64
+ // the host has not merged — or one whose lookup failed, and deleting a
65
+ // worktree on a lookup that failed is the destructive reading of an absence
66
+ // (`.claude/rules/negative-checks.md` rule 4). Refused at plan time rather
67
+ // than left to `git branch -d`'s error, because this message can name the
68
+ // PR and the exit where git's cannot. `--force` bypasses, and still plans
69
+ // `-d` below, so a genuinely unlanded branch fails loudly rather than
70
+ // being -D'd.
71
+ if (config.land && config.land.strategy === 'pr' && !landed) {
72
+ const prState = worktreeState.prState
73
+ const at = worktreeState.prUrl ? ` — see ${worktreeState.prUrl}` : ''
74
+ if (prState === 'open' || prState === 'draft') {
75
+ return blocked(
76
+ `the PR for ${spec.branch} is still ${prState}${at}; it lands when the host merges`,
77
+ )
78
+ }
79
+ if (prState === 'none') {
80
+ return blocked(`${spec.branch} has no PR and is not merged into the base branch`)
81
+ }
82
+ return blocked(`cannot confirm the PR for ${spec.branch} merged${at}`)
83
+ }
62
84
  }
63
85
 
64
86
  // Docker teardown only applies to a Docker-escalated spec. A worktree-only spec
@@ -160,6 +182,11 @@ function planDown(spec, config, flags, ctx) {
160
182
  // may well be on a remote this clone cannot see (pushed from another machine),
161
183
  // and the honest answer to "is there a remote branch?" is then "cannot tell",
162
184
  // which routes to doing nothing.
185
+ //
186
+ // A host that auto-deletes the branch on merge (common PR-mode hygiene) makes
187
+ // this delete a no-op: `git push --delete` errors with "remote ref does not
188
+ // exist", which is loud and destroys nothing. The skills report that as
189
+ // already-gone, never as a failed teardown.
163
190
  const remoteCommands = []
164
191
  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
165
192
  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
@@ -184,6 +211,21 @@ function planDown(spec, config, flags, ctx) {
184
211
  }
185
212
  }
186
213
 
214
+ // A live PR left behind by a cancelled spec is noise with a merge button on
215
+ // it, so a FORCED teardown past an open/draft PR also plans the abandon —
216
+ // composed by the caller (the host adapter's business), quarantined with the
217
+ // remote delete because closing a shared PR reaches outside this machine.
218
+ // Unforced never gets here with an open PR (the guard above refused), and a
219
+ // missing command (unknown host, no id) plans nothing: the refusal/report
220
+ // already named the PR, and a person closes it.
221
+ if (
222
+ config.land && config.land.strategy === 'pr' &&
223
+ (worktreeState.prState === 'open' || worktreeState.prState === 'draft') &&
224
+ ctx && ctx.prAbandonCommand
225
+ ) {
226
+ remoteCommands.push(ctx.prAbandonCommand)
227
+ }
228
+
187
229
  return {
188
230
  blocked: false,
189
231
  reason: null,
@@ -84,7 +84,9 @@ const {
84
84
  } = require('./credentials.js')
85
85
  const { resolveIdentity, displayNameOf } = require('./identity.js')
86
86
  const { makeAssignmentCommands } = require('../provider-kit/src/assignment.js')
87
+ const { specSyncOwnership, specSyncBoard: kitBoard, ownershipDoctorRow } = require('../provider-kit/src/status.js')
87
88
  const { resolveTransport } = require('../provider-kit/src/transport.js')
89
+ const { specSyncSplice } = require('../provider-kit/src/splice.js')
88
90
 
89
91
  // `assign`, `whoami` and `users` are the kit's (`provider-kit/src/assignment.js`),
90
92
  // hoisted when the GitHub provider became their second consumer. What is
@@ -115,6 +117,24 @@ const assignment = makeAssignmentCommands({
115
117
  usersOverMcp: 'search the workspace over MCP with the user-list tool',
116
118
  })
117
119
  const specSyncAssign = (dir, config, specArg, flags, out) => assignment.assign(dir, config, specArg, flags, out)
120
+
121
+ // `board <spec>` — has Linear finished what this repo has not? The kit's
122
+ // (`provider-kit/src/status.js`): one line on a disagreement, silent otherwise.
123
+ async function specSyncBoard(dir, config, specArg, flags, out) {
124
+ const snapshotDir = resolveOrExit(specArg, dir, out)
125
+ if (!snapshotDir) return 1
126
+ const key = resolveApiKey(config, flags.env || process.env)
127
+ const transport = resolveTransport(flags, config, key.ok || !!flags.adapter)
128
+ const credential =
129
+ transport === 'mcp'
130
+ ? { ok: false, error: 'transport = mcp — no API read' }
131
+ : flags.adapter
132
+ ? { ok: true, adapter: flags.adapter }
133
+ : key.ok
134
+ ? { ok: true, adapter: makeApiAdapter({ apiKey: key.key, fetch: flags.fetch }) }
135
+ : { ok: false, error: key.error }
136
+ return kitBoard({ snapshotDir, config, credential, flags, out, tracker: 'Linear', program: 'spec-sync' })
137
+ }
118
138
  const specSyncWhoami = (dir, config, flags, out) => assignment.whoami(dir, config, flags, out)
119
139
  const specSyncUsers = (dir, config, query, flags, out) => assignment.users(dir, config, query, flags, out)
120
140
  const { readAllStdin, promptHidden } = require('../provider-kit/src/prompt.js')
@@ -883,6 +903,7 @@ function gatherState(dir, flags) {
883
903
  }
884
904
 
885
905
  state._config = config
906
+ if (config) state.ownership = ownershipDoctorRow(config)
886
907
  state.retired = retiredKeysRow(path.join(dir, CONFIG_FILE), CONFIG_FILE, doctorRow)
887
908
  return state
888
909
  }
@@ -1027,7 +1048,10 @@ function readCommitRange(dir, rangeArg, verb) {
1027
1048
 
1028
1049
  // NUL-delimited so a subject or body containing the separator cannot split a
1029
1050
  // record; RS between commits for the same reason.
1030
- const raw = git(['log', '--format=%H%x00%s%x00%b%x1e', range])
1051
+ // %P rides with the sha so a merge commit can be told apart: its trailers
1052
+ // are READ (a hand merge is where a ticket's only trailer sometimes lives),
1053
+ // but a trailer-less merge counts as transport rather than a gap.
1054
+ const raw = git(['log', '--format=%H %P%x00%s%x00%b%x1e', range])
1031
1055
  if (raw === null) {
1032
1056
  return { error: [`spec-sync ${verb}: git could not resolve the range "${range}".`] }
1033
1057
  }
@@ -1037,8 +1061,9 @@ function readCommitRange(dir, rangeArg, verb) {
1037
1061
  .map((r) => r.replace(/^\n/, ''))
1038
1062
  .filter((r) => r.trim())
1039
1063
  .map((record) => {
1040
- const [sha, subject, ...rest] = record.split('\x00')
1041
- return { sha, subject, body: rest.join('\x00') }
1064
+ const [idLine, subject, ...rest] = record.split('\x00')
1065
+ const [sha, ...parents] = String(idLine).trim().split(/\s+/).filter(Boolean)
1066
+ return { sha, isMerge: parents.length > 1, subject, body: rest.join('\x00') }
1042
1067
  })
1043
1068
 
1044
1069
  // What each commit CHANGED, so bookkeeping can be told from shipped work. A
@@ -1104,6 +1129,7 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
1104
1129
  // MISSED trailer looks identical, so silence here would read as "everything is
1105
1130
  // accounted for".
1106
1131
  lines.push(` ${report.unreferenced} commit(s) carry no ref`)
1132
+ if (report.merges) lines.push(` ${report.merges} merge commit(s) — transport, not counted as gaps`)
1107
1133
  // A filter that removes commits without saying so reads as "there was nothing
1108
1134
  // there". Named only when it actually fired — on a project with no paperwork
1109
1135
  // in the range there is nothing to disclose.
@@ -1994,6 +2020,7 @@ async function specSyncList(dir, config, flags, out) {
1994
2020
 
1995
2021
  const rows = ordered.map((issue) => {
1996
2022
  const local = byIdentifier.get(issue.identifier) || null
2023
+ const column = specColumn((issue.state && issue.state.name) || null, local, config)
1997
2024
  return {
1998
2025
  identifier: issue.identifier || '',
1999
2026
  title: issue.title || '',
@@ -2004,7 +2031,9 @@ async function specSyncList(dir, config, flags, out) {
2004
2031
  // close, so hiding it would defeat the command.
2005
2032
  spec: local ? local.spec : null,
2006
2033
  bucket: local ? local.bucket : null,
2007
- disagrees: specColumn((issue.state && issue.state.name) || null, local, config).disagrees,
2034
+ disagrees: column.disagrees,
2035
+ // The command that closes it — present only on a disagreeing row.
2036
+ ...(column.cleanup ? { cleanup: column.cleanup } : {}),
2008
2037
  assignee: (issue.assignee && issue.assignee.name) || null,
2009
2038
  // Filled in below for in-progress rows only; `null` on every row that was
2010
2039
  // never looked up, so the shape does not vary by state.
@@ -2140,7 +2169,7 @@ async function specSyncList(dir, config, flags, out) {
2140
2169
  } else {
2141
2170
  const idW = Math.max(...shown.map((r) => r.identifier.length))
2142
2171
  const stW = Math.max(...shown.map((r) => r.state.length))
2143
- const cell = (r) => specCell({ specStatus: r.bucket, disagrees: r.disagrees })
2172
+ const cell = (r) => specCell({ specStatus: r.bucket, disagrees: r.disagrees, cleanup: r.cleanup })
2144
2173
  const bkW = Math.max(...shown.map((r) => cell(r).length))
2145
2174
  const pad = ' '.repeat(idW + stW + bkW + 6)
2146
2175
  const specW = Math.max(...shown.map((r) => (r.spec || UNLINKED).length))
@@ -2656,6 +2685,10 @@ function specSyncInitConfig(dir, flags, out) {
2656
2685
  if (flags.teamKey) linear.teamKey = flags.teamKey
2657
2686
  if (flags.projectId) linear.projectId = flags.projectId
2658
2687
  draft.linear = linear
2688
+ // A NEW config carries a summary, not the spec: written explicitly, so the
2689
+ // file says what the ticket gets. A config that predates the key keeps
2690
+ // pushing the spec (the loader's default), so an upgrade rewrites nothing.
2691
+ draft.mapping = { description: flags.description || 'summary' }
2659
2692
  const intake = {}
2660
2693
  if (flags.intakeLabel) intake.label = flags.intakeLabel
2661
2694
  if (flags.bugLabels.length) intake.bugLabels = flags.bugLabels
@@ -3317,6 +3350,9 @@ async function specSync(rest, io = {}) {
3317
3350
  else if (args[i] === '--apply') flags.apply = true
3318
3351
  else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
3319
3352
  else if (args[i] === '--stored') flags.stored = path.resolve(args[++i])
3353
+ else if (args[i] === '--live') flags.live = path.resolve(args[++i])
3354
+ else if (args[i] === '--description') flags.description = args[++i]
3355
+ else if (args[i] === '--phase') flags.phase = args[++i]
3320
3356
  // `preserve --text <file>`: the description to keep, when the caller read it
3321
3357
  // over MCP and the engine cannot.
3322
3358
  else if (args[i] === '--text') flags.text = path.resolve(args[++i])
@@ -3355,6 +3391,7 @@ async function specSync(rest, io = {}) {
3355
3391
  else if (args[i] === '--unset') flags.unset = true
3356
3392
  else if (args[i] === '--to') flags.to = String(args[++i] || '').trim()
3357
3393
  else if (args[i] === '--release') flags.release = true
3394
+ else if (args[i] === '--if-unassigned') flags.ifUnassigned = true
3358
3395
  else if (args[i] === '--no-assign') flags.noAssign = true
3359
3396
  else if (args[i] === '--limit') flags.limit = Number(args[++i]) || 0
3360
3397
  else if (args[i] === '--cursor') flags.cursor = String(args[++i] || '').trim()
@@ -3490,6 +3527,11 @@ async function specSync(rest, io = {}) {
3490
3527
  return (await specSyncRetarget(dir, config, flags, out)) || 0
3491
3528
  case 'apply':
3492
3529
  return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
3530
+ case 'splice': {
3531
+ const snapshotDir = resolveOrExit(positional[0], dir, err)
3532
+ if (!snapshotDir) return 1
3533
+ return specSyncSplice({ snapshotDir, config, flags, out, err, program: 'spec-sync' })
3534
+ }
3493
3535
  case 'verify':
3494
3536
  return specSyncVerify(dir, config, positional[0], flags, out) || 0
3495
3537
  case 'preserve':
@@ -3499,6 +3541,10 @@ async function specSync(rest, io = {}) {
3499
3541
  case 'linked':
3500
3542
  specSyncLinked(dir, config, flags, out)
3501
3543
  return 0
3544
+ case 'ownership':
3545
+ return specSyncOwnership(config, flags, out, 'spec-sync')
3546
+ case 'board':
3547
+ return specSyncBoard(dir, config, positional[0], flags, out)
3502
3548
  case 'credentials':
3503
3549
  return await specSyncCredentials(dir, config, positional[0], flags, out)
3504
3550
  default:
@@ -3510,14 +3556,17 @@ async function specSync(rest, io = {}) {
3510
3556
  ' skitterspec spec-sync projects [--via api|mcp] [--json]\n' +
3511
3557
  ' skitterspec spec-sync whoami [--set <id> [--name N]] [--unset] [--json]\n' +
3512
3558
  ' skitterspec spec-sync users [<name-or-email>] [--limit N] [--cursor C] [--json]\n' +
3513
- ' skitterspec spec-sync assign <spec> --to <id> [--name N] | --release [--json]\n' +
3559
+ ' skitterspec spec-sync assign <spec> --to <id> [--name N] [--if-unassigned] | --release [--json]\n' +
3514
3560
  ' skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
3515
3561
  ' skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
3516
3562
  ' skitterspec spec-sync verify <spec> --stored <file>\n' +
3563
+ ' skitterspec spec-sync splice <spec> --live <file> [--phase <ref>]\n' +
3517
3564
  ' skitterspec spec-sync preserve <spec> [--text <file>] [--via api|mcp] [--json]\n' +
3518
3565
  ' skitterspec spec-sync comment <spec> --file <file> [--via api|mcp]\n' +
3519
3566
  ' skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
3520
3567
  ' skitterspec spec-sync linked [--json]\n' +
3568
+ ' skitterspec spec-sync ownership [--json]\n' +
3569
+ ' skitterspec spec-sync board <spec> [--json]\n' +
3521
3570
  ' skitterspec spec-sync ref [<spec>] [--json]\n' +
3522
3571
  ' skitterspec spec-sync released [<range>] [--json]\n' +
3523
3572
  ' skitterspec spec-sync reattach <spec> [--to <ISSUE-REF>] [--json]\n' +