@skitterbyte/skitterspec-jira 2.3.0 → 2.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 (57) 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/jira.config.md +4 -2
  5. package/assets/hooks/main-guard.cjs +18 -2
  6. package/assets/hooks/review-gate.cjs +19 -2
  7. package/assets/rules/commit-trailers.md +24 -1
  8. package/assets/rules/spec-planning.md +81 -18
  9. package/assets/rules/spec-reports.md +1 -1
  10. package/assets/skills/spec/SKILL.md +55 -2
  11. package/assets/skills/spec-bug/SKILL.md +25 -1
  12. package/assets/skills/spec-cancel/SKILL.md +35 -0
  13. package/assets/skills/spec-complete/SKILL.md +113 -0
  14. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  15. package/assets/skills/spec-incident/SKILL.md +22 -0
  16. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  17. package/assets/skills/spec-next/SKILL.md +9 -4
  18. package/assets/skills/spec-push/SKILL.md +22 -0
  19. package/assets/skills/spec-review/SKILL.md +32 -0
  20. package/assets/skills/spec-start/SKILL.md +39 -1
  21. package/assets/skills/spec-status/SKILL.md +18 -3
  22. package/assets/skills/spec-sync/SKILL.md +1 -0
  23. package/assets/skills/spec-to-main/SKILL.md +47 -1
  24. package/package.json +1 -1
  25. package/src/cli.js +1091 -39
  26. package/src/env/base.js +104 -0
  27. package/src/env/config.js +75 -3
  28. package/src/env/disposition.js +62 -0
  29. package/src/env/handoff.js +80 -0
  30. package/src/env/host.js +262 -0
  31. package/src/env/hotfix.js +225 -0
  32. package/src/env/hotfixland.js +103 -9
  33. package/src/env/inflight.js +95 -0
  34. package/src/env/integrate.js +130 -4
  35. package/src/env/mainguard.js +6 -0
  36. package/src/env/phases.js +28 -0
  37. package/src/env/provision.js +18 -6
  38. package/src/env/resolve.js +108 -9
  39. package/src/env/serve.js +6 -1
  40. package/src/env/specstate.js +101 -0
  41. package/src/env/teardown.js +42 -0
  42. package/src/vendor/jira/cli-sync.js +45 -3
  43. package/src/vendor/jira/config.js +17 -5
  44. package/src/vendor/provider-kit/index.js +4 -0
  45. package/src/vendor/provider-kit/src/apply.js +49 -4
  46. package/src/vendor/provider-kit/src/assignment.js +78 -1
  47. package/src/vendor/provider-kit/src/config.js +34 -1
  48. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  49. package/src/vendor/provider-kit/src/released.js +14 -1
  50. package/src/vendor/provider-kit/src/specs.js +4 -2
  51. package/src/vendor/provider-kit/src/splice.js +64 -0
  52. package/src/vendor/provider-kit/src/status.js +137 -0
  53. package/src/vendor/sync-core/index.js +14 -1
  54. package/src/vendor/sync-core/src/compare.js +17 -5
  55. package/src/vendor/sync-core/src/normalize.js +50 -7
  56. package/src/vendor/sync-core/src/push.js +26 -2
  57. 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,
@@ -34,6 +34,7 @@ const {
34
34
  stampSubIssueId,
35
35
  listPhaseFiles,
36
36
  normalizeLocal,
37
+ descriptionMode,
37
38
  } = require('../sync-core')
38
39
  const kit = require('../provider-kit')
39
40
  const { BUCKETS, findSpecFolder, currentBranch } = require('../../env/resolve.js')
@@ -258,6 +259,16 @@ function apiAdapterFor(config, flags) {
258
259
  }
259
260
  }
260
261
 
262
+ // `board <spec>` — has Jira finished what this repo has not? The kit's
263
+ // (`provider-kit/src/status.js`): one line on a disagreement, silent otherwise.
264
+ async function specSyncBoard(dir, config, specArg, flags, out) {
265
+ const snapshotDir = resolveOrExit(specArg, dir, out)
266
+ if (!snapshotDir) return 1
267
+ const cred = apiAdapterFor(config, flags)
268
+ const credential = kit.resolveTransport(flags, config, cred.ok) === 'mcp' ? { ok: false, error: 'transport = mcp — no API read' } : cred
269
+ return kit.specSyncBoard({ snapshotDir, config, credential, flags, out, tracker: 'Jira', program: PROGRAM })
270
+ }
271
+
261
272
  // ---------------------------------------------------------------------------
262
273
  // Subcommands. Each returns an exit code and writes only to the streams it is
263
274
  // handed, so every branch is testable offline.
@@ -755,12 +766,16 @@ function specSyncRef(dir, config, specArg, flags, out, err) {
755
766
  // ---------------------------------------------------------------------------
756
767
  // `released [<range>]` — which tickets a commit range contains, off the
757
768
  // `Refs:` trailers (kit `src/released.js` owns the parsing rules).
769
+ // Merge commits are READ, never skipped: a hand merge is where a ticket's only
770
+ // trailer sometimes lives (--no-merges was tried and dropped for exactly that
771
+ // loss). What changes is the counting — a trailer-less merge is transport, not
772
+ // a gap — and %P is what lets ticketsInRange tell the two apart.
758
773
  function readCommitRange(dir, range) {
759
774
  const { execFileSync } = require('node:child_process')
760
775
  const SEP = 'SKITTERSPEC'
761
776
  let raw
762
777
  try {
763
- raw = execFileSync('git', ['-C', dir, 'log', `--format=%x00SKITTERSPEC%x00%H%n%B%x00END%x00`, '--name-only', range], {
778
+ raw = execFileSync('git', ['-C', dir, 'log', `--format=%x00SKITTERSPEC%x00%H %P%n%B%x00END%x00`, '--name-only', range], {
764
779
  encoding: 'utf-8',
765
780
  stdio: ['ignore', 'pipe', 'pipe'],
766
781
  maxBuffer: 64 * 1024 * 1024,
@@ -781,9 +796,10 @@ function readCommitRange(dir, range) {
781
796
  .map((l) => l.trim())
782
797
  .filter(Boolean)
783
798
  const nl = head.indexOf('\n')
784
- const sha = head.slice(0, nl < 0 ? head.length : nl).trim()
799
+ const idLine = head.slice(0, nl < 0 ? head.length : nl).trim()
800
+ const [sha, ...parents] = idLine.split(/\s+/).filter(Boolean)
785
801
  const body = nl < 0 ? '' : head.slice(nl + 1)
786
- commits.push({ sha, subject: body.split('\n')[0] || '', body, paths })
802
+ commits.push({ sha, isMerge: parents.length > 1, subject: body.split('\n')[0] || '', body, paths })
787
803
  }
788
804
  return { ok: true, commits }
789
805
  }
@@ -807,6 +823,7 @@ function specSyncReleased(dir, config, rangeArg, flags, out) {
807
823
  for (const t of report.tickets) lines.push(` ${t.ref} (${t.commits} commit(s))${t.spec ? ` ${t.spec}` : ''}`)
808
824
  if (!report.tickets.length) lines.push(' no referenced tickets')
809
825
  if (report.unreferenced) lines.push(` ${report.unreferenced} commit(s) carry no Refs: trailer`)
826
+ if (report.merges) lines.push(` ${report.merges} merge commit(s) — transport, not counted as gaps`)
810
827
  if (report.ignored) lines.push(` ${report.ignored} bookkeeping commit(s) ignored`)
811
828
  out.write(lines.join('\n') + '\n')
812
829
  return 0
@@ -874,6 +891,11 @@ async function specSyncPreserve(dir, config, specArg, flags, out) {
874
891
  return 0
875
892
  }
876
893
  if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing to preserve`)
894
+ // Summary mode splices a block in beside the reporter's text rather than
895
+ // replacing it, so the original is still in the description itself.
896
+ if (descriptionMode(config) === 'summary') {
897
+ return done(`${identifier} — summary mode keeps the original description in place; nothing to preserve`)
898
+ }
877
899
 
878
900
  let original = null
879
901
  if (flags.text) {
@@ -1070,6 +1092,10 @@ async function specSyncInitConfig(dir, flags, out) {
1070
1092
  const parsed = { jira: { siteUrl: flags.siteUrl, projectKey: flags.projectKey } }
1071
1093
  if (flags.issueType) parsed.jira.issueType = flags.issueType
1072
1094
  if (flags.subtaskType) parsed.jira.subtaskType = flags.subtaskType
1095
+ // A NEW config carries a summary, not the spec: written explicitly, so the
1096
+ // file says what the ticket gets. A config that predates the key keeps
1097
+ // pushing the spec (the loader's default), so an upgrade rewrites nothing.
1098
+ parsed.mapping = { description: flags.description || 'summary' }
1073
1099
  if (flags.stateNames && Object.keys(flags.stateNames).length) {
1074
1100
  for (const bucket of Object.keys(flags.stateNames)) {
1075
1101
  if (!LIFECYCLE_BUCKETS.includes(bucket)) {
@@ -1170,6 +1196,7 @@ async function specSyncDoctor(dir, flags, out) {
1170
1196
  checks.push(row('tracker', 'Jira config', 'broken', 'siteUrl or projectKey is empty', `fix ${CONFIG_FILE}`))
1171
1197
  } else {
1172
1198
  checks.push(row('tracker', 'Jira config', 'ok', `${loaded.config.jira.projectKey} @ ${loaded.config.jira.siteUrl}`))
1199
+ checks.push(kit.ownershipDoctorRow(loaded.config))
1173
1200
  // A worktree forks from a COMMIT, so a config that exists only in the
1174
1201
  // working tree is invisible in every spec worktree — where the sync
1175
1202
  // skills actually run — and sync there reports itself off with no clue
@@ -1266,9 +1293,12 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
1266
1293
  record <spec> write the last-pushed snapshot
1267
1294
  status <spec> [--remote <f>] read-only drift report
1268
1295
  verify <spec> --stored <f> compare a read-back against the repo
1296
+ splice <spec> --live <f> [--phase <ref>] the body to write over MCP (summary mode)
1269
1297
  states [--json] the project's status names
1270
1298
  list [--all | --state NAME] tracker listing for the project
1271
1299
  linked [--json] specs and their linked issues (offline)
1300
+ ownership [--json] who owns status and assignee (offline)
1301
+ board <spec> [--json] is the issue finished where the spec is not?
1272
1302
  ref [<spec>] the Refs: trailer value for this branch
1273
1303
  released [<range>] tickets a commit range contains
1274
1304
  preserve <spec> [--text <f>] keep an adopted issue's original report
@@ -1337,10 +1367,19 @@ async function specSync(rest, io = {}) {
1337
1367
  return specSyncRecord(dir, config, positional[0], out)
1338
1368
  case 'status':
1339
1369
  return specSyncStatus(dir, config, positional[0], flags, out, err)
1370
+ case 'splice': {
1371
+ const snapshotDir = resolveOrExit(positional[0], dir, err)
1372
+ if (!snapshotDir) return 1
1373
+ return kit.specSyncSplice({ snapshotDir, config, flags, out, err, program: PROGRAM })
1374
+ }
1340
1375
  case 'verify':
1341
1376
  return specSyncVerify(dir, config, positional[0], flags, out)
1342
1377
  case 'linked':
1343
1378
  return specSyncLinked(dir, config, flags, out)
1379
+ case 'ownership':
1380
+ return kit.specSyncOwnership(config, flags, out, PROGRAM)
1381
+ case 'board':
1382
+ return specSyncBoard(dir, config, positional[0], flags, out)
1344
1383
  case 'states':
1345
1384
  return specSyncStates(dir, config, flags, out)
1346
1385
  case 'list':
@@ -1379,6 +1418,9 @@ function parseArgs(args, sub) {
1379
1418
  '--dir': { kind: 'path', name: 'dirOverride' },
1380
1419
  '--plan': { kind: 'path' },
1381
1420
  '--stored': { kind: 'path' },
1421
+ '--live': { kind: 'path' },
1422
+ '--description': { kind: 'string' },
1423
+ '--phase': { kind: 'string' },
1382
1424
  '--remote': { kind: 'path' },
1383
1425
  '--text': { kind: 'path' },
1384
1426
  '--file': { kind: 'path' },
@@ -21,7 +21,7 @@ const CONFIG_FILE = 'specs/.core/jira.config.json'
21
21
 
22
22
  const OWNERSHIP = Object.freeze(['both', 'pull', 'push', 'none'])
23
23
  const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
24
- const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
24
+ const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline', 'none'])
25
25
  const TRANSPORTS = Object.freeze(['api', 'mcp'])
26
26
  const DEFAULT_EMAIL_ENV = 'JIRA_EMAIL'
27
27
  const DEFAULT_TOKEN_ENV = 'JIRA_API_TOKEN'
@@ -43,7 +43,12 @@ const DEFAULT_CONFIG = Object.freeze({
43
43
  // A spec is a Jira ISSUE; each phase a SUBTASK of it. `tasks` selects how the
44
44
  // phase's checkboxes reach that subtask's description (as an ADF task list —
45
45
  // live checkboxes, still a read-only mirror).
46
- mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist' }),
46
+ // `description`: what the ticket body carries — `spec` (the whole overview)
47
+ // or `summary` (a delimited block beside the team's own text). `spec` is the
48
+ // default so a config written before the key pushes what it always pushed.
49
+ mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist', description: 'spec' }),
50
+ // The summary block's delimiters (provisional until chore-delimiter-spike-providers measures this tracker).
51
+ summary: Object.freeze({ delimiter: 'heading' }),
47
52
  // Jira STATUS names — the spec issue's status (from the folder bucket) and
48
53
  // each subtask's status (from the phase emoji) both map through this table.
49
54
  // They must match the project's workflow statuses exactly; `validateStates`
@@ -76,11 +81,16 @@ const DEFAULT_CONFIG = Object.freeze({
76
81
  sync: Object.freeze({
77
82
  baseDir: 'specs/.core/jira-base',
78
83
  backupDir: 'specs/.core/jira-backups',
84
+ // The repo owns the spec's CONTENT (`push`); the tracker owns its STATUS and
85
+ // ASSIGNEE (`pull`) — the board is where a team assigns and moves work, so a
86
+ // repo copy is one somebody has to keep in step by hand. Under `pull` the
87
+ // state is sent only as a transition the repo made (a bucket move), and the
88
+ // assignee not at all. Set either back to `"push"` for the repo-owned behaviour.
79
89
  fieldOwnership: Object.freeze({
80
90
  description: 'push',
81
91
  subIssues: 'push',
82
- workflowState: 'push',
83
- assignee: 'push',
92
+ workflowState: 'pull',
93
+ assignee: 'pull',
84
94
  }),
85
95
  localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
86
96
  keyedFields: Object.freeze({}),
@@ -105,6 +115,7 @@ function defaults() {
105
115
  return {
106
116
  jira: { ...DEFAULT_CONFIG.jira, issueTypeByKind: { ...DEFAULT_CONFIG.jira.issueTypeByKind } },
107
117
  mapping: { ...DEFAULT_CONFIG.mapping },
118
+ summary: { ...DEFAULT_CONFIG.summary },
108
119
  states: { ...DEFAULT_CONFIG.states },
109
120
  statesByType: {},
110
121
  stateAliases: {},
@@ -127,7 +138,7 @@ function defaults() {
127
138
  }
128
139
 
129
140
  const { isObject, stringList, assign } = kitConfig
130
- const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
141
+ const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields, mergeDescription } =
131
142
  kitConfig.makeMergeHelpers({
132
143
  configFile: CONFIG_FILE,
133
144
  ownership: OWNERSHIP,
@@ -173,6 +184,7 @@ function mergeConfig(base, parsed) {
173
184
  }
174
185
  mergePhaseMapping(base.mapping, parsed.mapping)
175
186
  }
187
+ mergeDescription(base, parsed)
176
188
 
177
189
  mergeStates(base, parsed)
178
190
  mergeStateOverrides(base, parsed, 'statesByType')
@@ -24,6 +24,8 @@ const prompt = require('./src/prompt.js')
24
24
  const args = require('./src/args.js')
25
25
  const adapter = require('./src/adapter.js')
26
26
  const apply = require('./src/apply.js')
27
+ const status = require('./src/status.js')
28
+ const splice = require('./src/splice.js')
27
29
 
28
30
  module.exports = {
29
31
  ...config,
@@ -38,4 +40,6 @@ module.exports = {
38
40
  ...args,
39
41
  ...adapter,
40
42
  ...apply,
43
+ ...status,
44
+ ...splice,
41
45
  }