@skitterbyte/skitterspec-jira 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/SETUP.md +5 -0
  3. package/assets/core/env.config.json.example +1 -0
  4. package/assets/core/env.config.md +143 -8
  5. package/assets/core/jira.config.md +4 -2
  6. package/assets/hooks/main-guard.cjs +40 -6
  7. package/assets/hooks/review-gate.cjs +42 -7
  8. package/assets/rules/commit-trailers.md +24 -1
  9. package/assets/rules/spec-planning.md +81 -18
  10. package/assets/rules/spec-reports.md +1 -1
  11. package/assets/skills/spec/SKILL.md +55 -2
  12. package/assets/skills/spec-bug/SKILL.md +25 -1
  13. package/assets/skills/spec-cancel/SKILL.md +35 -0
  14. package/assets/skills/spec-complete/SKILL.md +113 -0
  15. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  16. package/assets/skills/spec-incident/SKILL.md +22 -0
  17. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  18. package/assets/skills/spec-next/SKILL.md +9 -4
  19. package/assets/skills/spec-push/SKILL.md +22 -0
  20. package/assets/skills/spec-review/SKILL.md +32 -0
  21. package/assets/skills/spec-start/SKILL.md +39 -1
  22. package/assets/skills/spec-status/SKILL.md +18 -3
  23. package/assets/skills/spec-sync/SKILL.md +1 -0
  24. package/assets/skills/spec-to-main/SKILL.md +47 -1
  25. package/package.json +1 -1
  26. package/src/cli.js +1188 -79
  27. package/src/env/base.js +104 -0
  28. package/src/env/bootstrap.js +22 -3
  29. package/src/env/classify.js +12 -4
  30. package/src/env/config.js +77 -5
  31. package/src/env/disposition.js +62 -0
  32. package/src/env/handoff.js +81 -0
  33. package/src/env/host.js +262 -0
  34. package/src/env/hotfix.js +237 -9
  35. package/src/env/hotfixland.js +105 -10
  36. package/src/env/inflight.js +98 -0
  37. package/src/env/integrate.js +136 -9
  38. package/src/env/live.js +8 -7
  39. package/src/env/mainguard.js +20 -5
  40. package/src/env/phases.js +28 -0
  41. package/src/env/project.js +223 -0
  42. package/src/env/provision.js +30 -8
  43. package/src/env/resolve.js +147 -25
  44. package/src/env/review.js +21 -7
  45. package/src/env/reviewers.js +7 -10
  46. package/src/env/serve.js +27 -11
  47. package/src/env/specstate.js +101 -0
  48. package/src/env/supervise.js +15 -2
  49. package/src/env/teardown.js +46 -3
  50. package/src/init.js +49 -9
  51. package/src/vendor/jira/cli-sync.js +48 -4
  52. package/src/vendor/jira/config.js +17 -5
  53. package/src/vendor/provider-kit/index.js +4 -0
  54. package/src/vendor/provider-kit/src/apply.js +58 -6
  55. package/src/vendor/provider-kit/src/assignment.js +78 -1
  56. package/src/vendor/provider-kit/src/config.js +34 -1
  57. package/src/vendor/provider-kit/src/credentials.js +7 -2
  58. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  59. package/src/vendor/provider-kit/src/released.js +48 -4
  60. package/src/vendor/provider-kit/src/specs.js +18 -7
  61. package/src/vendor/provider-kit/src/splice.js +64 -0
  62. package/src/vendor/provider-kit/src/status.js +137 -0
  63. package/src/vendor/sync-core/index.js +14 -1
  64. package/src/vendor/sync-core/src/compare.js +81 -6
  65. package/src/vendor/sync-core/src/normalize.js +50 -7
  66. package/src/vendor/sync-core/src/push.js +65 -5
  67. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -32,6 +32,7 @@ const fs = require('node:fs')
32
32
  const path = require('node:path')
33
33
  const crypto = require('node:crypto')
34
34
  const { spawn } = require('node:child_process')
35
+ const { signalGroup } = require('./supervise.js')
35
36
 
36
37
  const BUNDLED_ADAPTERS = { coderabbit: require('./reviewers/coderabbit.js') }
37
38
 
@@ -287,7 +288,9 @@ function runReviewer(entry, ctx) {
287
288
  // Through a shell, deliberately: the config holds a command LINE, with
288
289
  // pipes and quoting the project chose. It is read from a committed config
289
290
  // in the project's own repo — the same trust level as a package script.
290
- child = spawnFn('/bin/sh', ['-c', rendered], {
291
+ // `sh` from PATH on Windows — Git for Windows' — where `/bin/sh` does not
292
+ // exist and no reviewer could run at all (chore-windows-ci).
293
+ child = spawnFn(process.platform === 'win32' ? 'sh' : '/bin/sh', ['-c', rendered], {
291
294
  cwd: worktree,
292
295
  stdio: ['ignore', 'pipe', 'pipe'],
293
296
  // THE CHILD LEADS ITS OWN PROCESS GROUP, and the timeout below depends
@@ -314,15 +317,9 @@ function runReviewer(entry, ctx) {
314
317
  timedOut = true
315
318
  // The group, not the shell: `/bin/sh -c "cr review"` killed on its own
316
319
  // leaves the reviewer running and holding the port/rate-limit slot.
317
- try {
318
- process.kill(-child.pid, 'SIGKILL')
319
- } catch {
320
- try {
321
- child.kill('SIGKILL')
322
- } catch {
323
- /* already gone */
324
- }
325
- }
320
+ // `signalGroup` is the group on POSIX and the process tree on Windows,
321
+ // which has no groups (env/supervise.js).
322
+ signalGroup(child.pid, 'SIGKILL')
326
323
  }, entry.timeout * 1000)
327
324
 
328
325
  const settle = (spawnError) => {
package/src/env/serve.js CHANGED
@@ -38,8 +38,10 @@ const {
38
38
  } = require('./resolve.js')
39
39
  const { readRegistry } = require('./registry.js')
40
40
  const { loadEnvConfig } = require('./config.js')
41
+ const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
41
42
  const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
42
43
  const { liveStateFor } = require('./live.js')
44
+ const { preferRemoteBase } = require('./host.js')
43
45
  const {
44
46
  rawGitReader,
45
47
  collectReview,
@@ -218,8 +220,11 @@ ${body}
218
220
  * file in the tree IS evidence that the tree is being used for something else,
219
221
  * and that answer must stay unchanged — see the stays-silent test.
220
222
  */
221
- function isProjectBookkeeping(p) {
222
- return String(p).startsWith('specs/.core/')
223
+ //
224
+ // `p` is a repo path; the project's `specs/.core/` is under its prefix.
225
+ function isProjectBookkeeping(p, prefix = '') {
226
+ const rel = fromRepoPath(String(p), prefix)
227
+ return rel !== null && rel.startsWith('specs/.core/')
223
228
  }
224
229
 
225
230
  function docsWorktree(wt, spec, config) {
@@ -245,18 +250,22 @@ function docsWorktree(wt, spec, config) {
245
250
  // which is what `--docs` showed from the CLI — a served page that listed a
246
251
  // file the run's own report did not would be a different page from the one
247
252
  // the reader was told about.
248
- const intruders = foreign.filter((p) => !isProjectBookkeeping(p))
253
+ const intruders = foreign.filter((p) => !isProjectBookkeeping(p, prefixOf(config)))
249
254
  if (!owned.length || intruders.length) return null
250
255
  return { owned }
251
256
  }
252
257
 
253
258
  function viewFor(dir, config, spec, git, { fallback = false } = {}) {
254
259
  if (!spec) return null
260
+ // Every tree a view names is a git ROOT, so the reader bound to it prints
261
+ // root-relative paths and takes root-relative pathspecs. `dir` is the project
262
+ // folder, which is the root unless the project sits in a subfolder.
263
+ const root = repoRootOf(dir, config)
255
264
  // LIVE COMES FIRST, because while a spec is live its worktree still exists —
256
265
  // detached — and would win the check below while holding none of the work.
257
266
  // `live take` checks the branch out HERE, and a fix made while live is made
258
267
  // here too, so this checkout is the tree that answers.
259
- if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: dir }
268
+ if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: root }
260
269
  const wt = spec.worktreePath
261
270
  if (wt && wt !== dir && fs.existsSync(wt)) {
262
271
  // A DOCS WORKTREE IS NOT A CODE WORKTREE, and this used to be unreachable.
@@ -286,7 +295,7 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
286
295
  if (docs) return { kind: 'docs', tree: wt, owned: docs.owned }
287
296
  return { kind: 'worktree', tree: wt }
288
297
  }
289
- const found = specDocsIn(dir, spec, config, trimmedGitReader(dir))
298
+ const found = specDocsIn(root, spec, config, trimmedGitReader(root))
290
299
  // `error` is cannot-tell — not a page, and not an error page either (rule 4:
291
300
  // the harmless branch).
292
301
  if (found.error) return null
@@ -309,9 +318,9 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
309
318
  // omits them in the first place. A direct request is someone opening an
310
319
  // address they were given, and that has to keep resolving.
311
320
  if (!fallback) return null
312
- const committed = committedDocsFor(dir, config, spec)
321
+ const committed = committedDocsFor(root, config, spec)
313
322
  if (!committed) return null
314
- return { kind: 'docs-committed', tree: dir, owned: committed }
323
+ return { kind: 'docs-committed', tree: root, owned: committed }
315
324
  }
316
325
 
317
326
  /**
@@ -321,9 +330,9 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
321
330
  * that is no spec at all must stay a 404 rather than render an empty page with
322
331
  * a commit button on it.
323
332
  */
324
- function committedDocsFor(dir, config, spec) {
325
- const git = trimmedGitReader(dir)
326
- const out = git(['ls-files', '--', `specs/*/${spec.folder}/*`])
333
+ function committedDocsFor(root, config, spec) {
334
+ const git = trimmedGitReader(root)
335
+ const out = git(['ls-files', '--', toRepoPath(`specs/*/${spec.folder}/*`, prefixOf(config))])
327
336
  if (out == null) return null
328
337
  const paths = String(out)
329
338
  .split('\n')
@@ -557,7 +566,11 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
557
566
  const out = git(argv)
558
567
  return out == null ? null : String(out).trim() || null
559
568
  }
560
- const base = () => spec.baseRef || resolveBaseBranch(config, trimmed)
569
+ // PR mode measures the diff against the REMOTE image of base — local base is
570
+ // allowed to go stale there. `preferRemoteBase` never fetches and falls back
571
+ // to the local name, so the render stays offline-safe.
572
+ const base = () =>
573
+ spec.baseRef || preferRemoteBase(config, resolveBaseBranch(config, trimmed), trimmed)
561
574
 
562
575
  const now = new Date().toISOString()
563
576
  let mode = 'working'
@@ -1030,6 +1043,9 @@ if (require.main === module) {
1030
1043
  }
1031
1044
  const { dir, port, host, token } = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'))
1032
1045
  const { config } = loadEnvConfig(dir)
1046
+ // `dir` is the project folder the CLI anchored on; re-derive where it sits in
1047
+ // its repo so worktree paths resolve beside the repo, as the CLI's do.
1048
+ attachProject(config, primaryAnchor(dir, trimmedGitReader(dir)))
1033
1049
  const server = createReviewServer({ ...serverHooks(dir, config), token })
1034
1050
  startReviewServer(server, { port, host }).then(
1035
1051
  () => {},
@@ -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 }
@@ -12,7 +12,7 @@
12
12
 
13
13
  const fs = require('node:fs')
14
14
  const path = require('node:path')
15
- const { spawn } = require('node:child_process')
15
+ const { spawn, spawnSync } = require('node:child_process')
16
16
 
17
17
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
18
18
 
@@ -34,7 +34,18 @@ function isAlive(pid) {
34
34
  // Signal a detached process's whole group (its leader pid is `pid`, so the group
35
35
  // id is `-pid`) — reaches children like vite/tsc that a bare `pnpm dev` spawns.
36
36
  // Falls back to signalling just the leader if the group send fails.
37
- function signalGroup(pid, sig) {
37
+ //
38
+ // WINDOWS HAS NO PROCESS GROUPS: `-pid` throws, the fallback kills only the
39
+ // `sh` wrapper, and the server it started survives — holding its port and its
40
+ // worktree, which then cannot be removed (chore-windows-ci). `taskkill /T` walks
41
+ // the tree instead; `/F` for both signals, because a console process ignores
42
+ // the polite close a bare `taskkill` sends. Run with an argument list, never a
43
+ // shell. `opts` is injectable for tests.
44
+ function signalGroup(pid, sig, { platform = process.platform, run = spawnSync } = {}) {
45
+ if (platform === 'win32') {
46
+ run('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
47
+ return
48
+ }
38
49
  try {
39
50
  process.kill(-pid, sig)
40
51
  } catch {
@@ -81,6 +92,8 @@ function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
81
92
  cwd,
82
93
  env: { ...process.env, ...proc.env },
83
94
  detached: true,
95
+ // No console window per dev server on Windows; nothing anywhere else.
96
+ windowsHide: true,
84
97
  stdio: ['ignore', out, out],
85
98
  })
86
99
  child.unref()
@@ -23,6 +23,7 @@
23
23
 
24
24
  const { expandTokens } = require('./resolve.js')
25
25
  const { composeFileArg } = require('./provision.js')
26
+ const { shellPath } = require('./project.js')
26
27
 
27
28
  /**
28
29
  * @param {object} spec resolved spec: { slug, branch, worktreePath, projectName, ... }
@@ -59,6 +60,28 @@ function planDown(spec, config, flags, ctx) {
59
60
  if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed && !landed) {
60
61
  return blocked('worktree has unpushed commits not yet merged into the base branch')
61
62
  }
63
+ // PR mode: `merged` already includes the host's answer (the CLI folds a
64
+ // merged PR in before planning), so an UNLANDED branch here really is one
65
+ // the host has not merged — or one whose lookup failed, and deleting a
66
+ // worktree on a lookup that failed is the destructive reading of an absence
67
+ // (`.claude/rules/negative-checks.md` rule 4). Refused at plan time rather
68
+ // than left to `git branch -d`'s error, because this message can name the
69
+ // PR and the exit where git's cannot. `--force` bypasses, and still plans
70
+ // `-d` below, so a genuinely unlanded branch fails loudly rather than
71
+ // being -D'd.
72
+ if (config.land && config.land.strategy === 'pr' && !landed) {
73
+ const prState = worktreeState.prState
74
+ const at = worktreeState.prUrl ? ` — see ${worktreeState.prUrl}` : ''
75
+ if (prState === 'open' || prState === 'draft') {
76
+ return blocked(
77
+ `the PR for ${spec.branch} is still ${prState}${at}; it lands when the host merges`,
78
+ )
79
+ }
80
+ if (prState === 'none') {
81
+ return blocked(`${spec.branch} has no PR and is not merged into the base branch`)
82
+ }
83
+ return blocked(`cannot confirm the PR for ${spec.branch} merged${at}`)
84
+ }
62
85
  }
63
86
 
64
87
  // Docker teardown only applies to a Docker-escalated spec. A worktree-only spec
@@ -109,7 +132,7 @@ function planDown(spec, config, flags, ctx) {
109
132
  commands.push(
110
133
  force
111
134
  ? `git worktree remove --force ${spec.worktreePath}`
112
- : `git worktree remove ${spec.worktreePath}`,
135
+ : `git worktree remove ${shellPath(spec.worktreePath)}`,
113
136
  )
114
137
 
115
138
  // --- delete the branch ---
@@ -160,6 +183,11 @@ function planDown(spec, config, flags, ctx) {
160
183
  // may well be on a remote this clone cannot see (pushed from another machine),
161
184
  // and the honest answer to "is there a remote branch?" is then "cannot tell",
162
185
  // which routes to doing nothing.
186
+ //
187
+ // A host that auto-deletes the branch on merge (common PR-mode hygiene) makes
188
+ // this delete a no-op: `git push --delete` errors with "remote ref does not
189
+ // exist", which is loud and destroys nothing. The skills report that as
190
+ // already-gone, never as a failed teardown.
163
191
  const remoteCommands = []
164
192
  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
165
193
  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
@@ -184,6 +212,21 @@ function planDown(spec, config, flags, ctx) {
184
212
  }
185
213
  }
186
214
 
215
+ // A live PR left behind by a cancelled spec is noise with a merge button on
216
+ // it, so a FORCED teardown past an open/draft PR also plans the abandon —
217
+ // composed by the caller (the host adapter's business), quarantined with the
218
+ // remote delete because closing a shared PR reaches outside this machine.
219
+ // Unforced never gets here with an open PR (the guard above refused), and a
220
+ // missing command (unknown host, no id) plans nothing: the refusal/report
221
+ // already named the PR, and a person closes it.
222
+ if (
223
+ config.land && config.land.strategy === 'pr' &&
224
+ (worktreeState.prState === 'open' || worktreeState.prState === 'draft') &&
225
+ ctx && ctx.prAbandonCommand
226
+ ) {
227
+ remoteCommands.push(ctx.prAbandonCommand)
228
+ }
229
+
187
230
  return {
188
231
  blocked: false,
189
232
  reason: null,
@@ -240,8 +283,8 @@ function planDownCheckout(spec, config, flags, ctx) {
240
283
  }
241
284
 
242
285
  const commands = []
243
- if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
244
- commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
286
+ if (onBranch !== false) commands.push(`git -C ${shellPath(checkoutPath)} switch ${base}`)
287
+ commands.push(`git -C ${shellPath(checkoutPath)} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
245
288
  return { ...result, commands }
246
289
  }
247
290
 
package/src/init.js CHANGED
@@ -3,10 +3,12 @@
3
3
  const fs = require('fs')
4
4
  const path = require('path')
5
5
  const crypto = require('crypto')
6
+ const { execFileSync } = require('child_process')
6
7
 
7
8
  const { ensureWorktreeDirTrusted } = require('./env/trust.js')
8
9
  const { ensureHooks } = require('./env/hooks.js')
9
10
  const { repoInfo, expandTokens } = require('./env/resolve.js')
11
+ const { primaryAnchor } = require('./env/project.js')
10
12
 
11
13
  const ASSETS = path.join(__dirname, '..', 'assets')
12
14
 
@@ -286,8 +288,11 @@ const RETIRED_FILES = [
286
288
  path.join('specs', 'complete', '00-index.md'),
287
289
  ]
288
290
 
291
+ // `/`-separated on every platform: these are the manifest's keys and the
292
+ // report's lines, and a Windows install recording `specs\\.core\\…` would read
293
+ // as a different file to every other machine (chore-windows-ci).
289
294
  function rel(dir, p) {
290
- return path.relative(dir, p) || '.'
295
+ return path.relative(dir, p).split(path.sep).join('/') || '.'
291
296
  }
292
297
 
293
298
  function ensureDir(p) {
@@ -310,8 +315,22 @@ const MANIFEST_VERSION = 1
310
315
  // reset each init() alongside `report`.
311
316
  const writtenHashes = {}
312
317
 
318
+ // Every judgement about a managed file compares content with its line endings
319
+ // normalised. On Windows with `core.autocrlf=true` a checkout rewrites LF to
320
+ // CRLF, and an exact compare read that conversion as the user's edit: every
321
+ // skill, command and rule became "your edit — kept" and stopped updating.
322
+ // Assets ship LF, so hashes of LF files — every manifest already written — are
323
+ // unchanged by this.
324
+ function normalizeEol(content) {
325
+ return content.replace(/\r\n/g, '\n')
326
+ }
327
+
328
+ function sameContent(a, b) {
329
+ return normalizeEol(a) === normalizeEol(b)
330
+ }
331
+
313
332
  function sha1(content) {
314
- return crypto.createHash('sha1').update(content).digest('hex')
333
+ return crypto.createHash('sha1').update(normalizeEol(content)).digest('hex')
315
334
  }
316
335
 
317
336
  // The full managed set for a target dir: repo-relative path, absolute path, and
@@ -349,10 +368,18 @@ function readManifest(dir) {
349
368
  try {
350
369
  const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8'))
351
370
  if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
371
+ // KEYS ARE `/`-SEPARATED ON READ, whoever wrote them. A Windows install
372
+ // before chore-windows-ci recorded `.claude\\skills\\…`; looked up by the
373
+ // `/` paths every caller now uses, its records went missing — and a
374
+ // missing record is what turns a user's edited retired file into one
375
+ // that gets deleted. No managed path contains a backslash, so this
376
+ // cannot merge two genuine entries.
377
+ const files = {}
378
+ for (const [key, hash] of Object.entries(parsed.files)) files[key.replace(/\\/g, '/')] = hash
352
379
  return {
353
380
  version: parsed.version || MANIFEST_VERSION,
354
- files: parsed.files,
355
- baselined: Object.keys(parsed.files).length > 0,
381
+ files,
382
+ baselined: Object.keys(files).length > 0,
356
383
  }
357
384
  }
358
385
  } catch {
@@ -406,10 +433,13 @@ function writeManifest(dir, files) {
406
433
  // `pruneRetiredManaged` passes no `bundled` on purpose: the package no longer
407
434
  // ships that file, so there is nothing to compare it against.
408
435
  function managedState(dir, relPath, manifest, bundled) {
436
+ // Manifest keys are `/`-separated; a caller holding an OS path still finds
437
+ // its file's record (chore-windows-ci).
438
+ relPath = String(relPath).split(path.sep).join('/')
409
439
  const abs = path.join(dir, relPath)
410
440
  if (!fs.existsSync(abs)) return 'missing'
411
441
  const onDisk = fs.readFileSync(abs, 'utf8')
412
- if (bundled !== undefined && onDisk === bundled) return 'pristine'
442
+ if (bundled !== undefined && sameContent(onDisk, bundled)) return 'pristine'
413
443
  const known = manifest.files[relPath]
414
444
  if (known) return sha1(onDisk) === known ? 'pristine' : 'customized'
415
445
  return manifest.baselined ? 'adopted' : 'customized'
@@ -715,8 +745,18 @@ function trustWorktreeRoot(dir) {
715
745
  report.warnings.push('could not read worktree.root — skipped trusting the worktree dir')
716
746
  return
717
747
  }
718
- const { repo, repoSlug } = repoInfo(dir)
719
- const rootAbs = path.resolve(dir, expandTokens(root, { repo, repoSlug }))
748
+ // Resolved against the REPO's root, and named for it, exactly as `spec-env`
749
+ // resolves it — `dir` is the project folder, which is a subfolder of the repo
750
+ // for some projects (feat-subfolder-project). Not a repo → `dir`, as before.
751
+ const anchor = primaryAnchor(dir, (args) => {
752
+ try {
753
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
754
+ } catch {
755
+ return null
756
+ }
757
+ })
758
+ const { repo, repoSlug } = repoInfo(anchor.root)
759
+ const rootAbs = path.resolve(anchor.root, expandTokens(root, { repo, repoSlug }))
720
760
  const res = ensureWorktreeDirTrusted(dir, rootAbs)
721
761
  const label = '.claude/settings.local.json (trusted worktree root)'
722
762
  if (res.reason === 'malformed') {
@@ -777,7 +817,7 @@ function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
777
817
  else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
778
818
  else if (state === 'adopted')
779
819
  rows.push([relPath, 'adopted upstream — yours kept, theirs not installed (--force takes theirs)'])
780
- else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
820
+ else if (!sameContent(fs.readFileSync(abs, 'utf8'), bundled)) rows.push([relPath, 'out of date — would be updated'])
781
821
  }
782
822
  const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
783
823
  // A healthy area says NOTHING. A report that lists what is already fine is a
@@ -876,7 +916,7 @@ function resyncManagedFile(dir, target, manifest, force) {
876
916
  return report[state].push({ relPath, added, removed, hunks })
877
917
  }
878
918
  // pristine — update only if the bundled content actually changed
879
- if (fs.readFileSync(abs, 'utf8') === bundled) {
919
+ if (sameContent(fs.readFileSync(abs, 'utf8'), bundled)) {
880
920
  // The file is ours and current, but the manifest disagreed — record the
881
921
  // repair rather than healing in silence: a file that quietly starts
882
922
  // updating again is as opaque as one that quietly stopped.
@@ -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.
@@ -462,7 +473,7 @@ function specSyncRecord(dir, config, specArg, out) {
462
473
  const snapshotDir = resolveOrExit(specArg, dir, out)
463
474
  if (!snapshotDir) return 1
464
475
  const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config })
465
- out.write(`${PROGRAM} record: snapshot written — ${path.relative(dir, file)}\n`)
476
+ out.write(`${PROGRAM} record: snapshot written — ${path.relative(dir, file).split(path.sep).join('/')}\n`)
466
477
  return 0
467
478
  }
468
479
 
@@ -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
  }
@@ -797,6 +813,8 @@ function specSyncReleased(dir, config, rangeArg, flags, out) {
797
813
  }
798
814
  const report = kit.ticketsInRange(read.commits, {
799
815
  ignorePaths: (config.release && config.release.ignorePaths) || [],
816
+ // A nested project's commits carry its folder in every path (feat-subfolder-project).
817
+ prefix: kit.projectPrefixOf(dir),
800
818
  })
801
819
  report.tickets = kit.nameTickets(report.tickets, listSpecs(dir, config, { urls: true }))
802
820
  if (flags.json) {
@@ -807,6 +825,7 @@ function specSyncReleased(dir, config, rangeArg, flags, out) {
807
825
  for (const t of report.tickets) lines.push(` ${t.ref} (${t.commits} commit(s))${t.spec ? ` ${t.spec}` : ''}`)
808
826
  if (!report.tickets.length) lines.push(' no referenced tickets')
809
827
  if (report.unreferenced) lines.push(` ${report.unreferenced} commit(s) carry no Refs: trailer`)
828
+ if (report.merges) lines.push(` ${report.merges} merge commit(s) — transport, not counted as gaps`)
810
829
  if (report.ignored) lines.push(` ${report.ignored} bookkeeping commit(s) ignored`)
811
830
  out.write(lines.join('\n') + '\n')
812
831
  return 0
@@ -874,6 +893,11 @@ async function specSyncPreserve(dir, config, specArg, flags, out) {
874
893
  return 0
875
894
  }
876
895
  if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing to preserve`)
896
+ // Summary mode splices a block in beside the reporter's text rather than
897
+ // replacing it, so the original is still in the description itself.
898
+ if (descriptionMode(config) === 'summary') {
899
+ return done(`${identifier} — summary mode keeps the original description in place; nothing to preserve`)
900
+ }
877
901
 
878
902
  let original = null
879
903
  if (flags.text) {
@@ -1070,6 +1094,10 @@ async function specSyncInitConfig(dir, flags, out) {
1070
1094
  const parsed = { jira: { siteUrl: flags.siteUrl, projectKey: flags.projectKey } }
1071
1095
  if (flags.issueType) parsed.jira.issueType = flags.issueType
1072
1096
  if (flags.subtaskType) parsed.jira.subtaskType = flags.subtaskType
1097
+ // A NEW config carries a summary, not the spec: written explicitly, so the
1098
+ // file says what the ticket gets. A config that predates the key keeps
1099
+ // pushing the spec (the loader's default), so an upgrade rewrites nothing.
1100
+ parsed.mapping = { description: flags.description || 'summary' }
1073
1101
  if (flags.stateNames && Object.keys(flags.stateNames).length) {
1074
1102
  for (const bucket of Object.keys(flags.stateNames)) {
1075
1103
  if (!LIFECYCLE_BUCKETS.includes(bucket)) {
@@ -1170,6 +1198,7 @@ async function specSyncDoctor(dir, flags, out) {
1170
1198
  checks.push(row('tracker', 'Jira config', 'broken', 'siteUrl or projectKey is empty', `fix ${CONFIG_FILE}`))
1171
1199
  } else {
1172
1200
  checks.push(row('tracker', 'Jira config', 'ok', `${loaded.config.jira.projectKey} @ ${loaded.config.jira.siteUrl}`))
1201
+ checks.push(kit.ownershipDoctorRow(loaded.config))
1173
1202
  // A worktree forks from a COMMIT, so a config that exists only in the
1174
1203
  // working tree is invisible in every spec worktree — where the sync
1175
1204
  // skills actually run — and sync there reports itself off with no clue
@@ -1266,9 +1295,12 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
1266
1295
  record <spec> write the last-pushed snapshot
1267
1296
  status <spec> [--remote <f>] read-only drift report
1268
1297
  verify <spec> --stored <f> compare a read-back against the repo
1298
+ splice <spec> --live <f> [--phase <ref>] the body to write over MCP (summary mode)
1269
1299
  states [--json] the project's status names
1270
1300
  list [--all | --state NAME] tracker listing for the project
1271
1301
  linked [--json] specs and their linked issues (offline)
1302
+ ownership [--json] who owns status and assignee (offline)
1303
+ board <spec> [--json] is the issue finished where the spec is not?
1272
1304
  ref [<spec>] the Refs: trailer value for this branch
1273
1305
  released [<range>] tickets a commit range contains
1274
1306
  preserve <spec> [--text <f>] keep an adopted issue's original report
@@ -1337,10 +1369,19 @@ async function specSync(rest, io = {}) {
1337
1369
  return specSyncRecord(dir, config, positional[0], out)
1338
1370
  case 'status':
1339
1371
  return specSyncStatus(dir, config, positional[0], flags, out, err)
1372
+ case 'splice': {
1373
+ const snapshotDir = resolveOrExit(positional[0], dir, err)
1374
+ if (!snapshotDir) return 1
1375
+ return kit.specSyncSplice({ snapshotDir, config, flags, out, err, program: PROGRAM })
1376
+ }
1340
1377
  case 'verify':
1341
1378
  return specSyncVerify(dir, config, positional[0], flags, out)
1342
1379
  case 'linked':
1343
1380
  return specSyncLinked(dir, config, flags, out)
1381
+ case 'ownership':
1382
+ return kit.specSyncOwnership(config, flags, out, PROGRAM)
1383
+ case 'board':
1384
+ return specSyncBoard(dir, config, positional[0], flags, out)
1344
1385
  case 'states':
1345
1386
  return specSyncStates(dir, config, flags, out)
1346
1387
  case 'list':
@@ -1379,6 +1420,9 @@ function parseArgs(args, sub) {
1379
1420
  '--dir': { kind: 'path', name: 'dirOverride' },
1380
1421
  '--plan': { kind: 'path' },
1381
1422
  '--stored': { kind: 'path' },
1423
+ '--live': { kind: 'path' },
1424
+ '--description': { kind: 'string' },
1425
+ '--phase': { kind: 'string' },
1382
1426
  '--remote': { kind: 'path' },
1383
1427
  '--text': { kind: 'path' },
1384
1428
  '--file': { kind: 'path' },