@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
@@ -77,7 +77,7 @@ const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
77
77
  // flight and something else entirely for work that finished long ago. A bucket
78
78
  // the map omits gets DEFAULT_PHASE_MODE, so a partial map adds an exception
79
79
  // rather than silently suppressing phases everywhere it is silent.
80
- const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
80
+ const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline', 'none'])
81
81
  const DEFAULT_PHASE_MODE = 'subissue'
82
82
 
83
83
  // How `spec-sync apply` reaches Linear. `api` talks to the GraphQL API directly;
@@ -150,7 +150,12 @@ const DEFAULT_CONFIG = Object.freeze({
150
150
  // synced (they live only in the repo phase files).
151
151
  // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
152
152
  // phase's checkboxes reach that sub-issue's description — see TASK_MAPPINGS.
153
- mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist' }),
153
+ // `description`: what the ticket body carries — `spec` (the whole overview)
154
+ // or `summary` (a delimited block beside the team's own text). `spec` is the
155
+ // default so a config written before the key pushes what it always pushed.
156
+ mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist', description: 'spec' }),
157
+ // The summary block's delimiters (provisional until chore-delimiter-spike-providers measures this tracker).
158
+ summary: Object.freeze({ delimiter: 'heading' }),
154
159
  // Linear ISSUE workflow-state names — the spec issue's state (from the folder
155
160
  // bucket) and each sub-issue's state (from the phase emoji) both map through
156
161
  // this one table. They must match the workspace's issue states exactly;
@@ -190,29 +195,28 @@ const DEFAULT_CONFIG = Object.freeze({
190
195
  sync: Object.freeze({
191
196
  baseDir: 'specs/.core/linear-base',
192
197
  backupDir: 'specs/.core/linear-backups',
193
- // One-way (repo → Linear): the projection field set the repo owns and pushes
194
- // — the issue `description`, its `subIssues` (one per phase, name + goal +
195
- // state), and the lifecycle `workflowState`. There is no pull. Priority,
196
- // labels, cycles and comments are Linear-native triage — deliberately NOT in
197
- // the set, so the PM's triage is never touched. The `push` marker is retained
198
- // for shape; any key you add joins the pushed projection.
198
+ // The repo owns the spec's CONTENT and pushes it one way (repo → Linear) —
199
+ // the issue `description` and its `subIssues` (one per phase, name + goal +
200
+ // state). Priority, labels, cycles and comments are Linear-native triage —
201
+ // deliberately NOT in the set, so the PM's triage is never touched.
199
202
  //
200
- // `assignee` ships ON, and the opt-out is `"assignee": "none"`. It was
201
- // opt-in until v16, and the cost of that was silent in exactly the wrong
202
- // direction: a repo that never added the line looked identical to one that
203
- // did not want the feature, so the only signal was noticing an unassigned
204
- // issue weeks later.
203
+ // Linear owns the spec's STATUS and ASSIGNEE (`pull`). The board is where a
204
+ // team assigns and moves work, so a repo copy is one somebody has to keep in
205
+ // step by hand. Under `pull` the state is sent only as a transition the repo
206
+ // made (a spec changing bucket — see `compare.js` `issueChanges`), the
207
+ // assignee is never projected, and `spec-sync assign` writes Linear directly.
208
+ // Set either back to `"push"` for the repo-owned behaviour, or `"none"` to
209
+ // leave it alone entirely.
205
210
  //
206
- // WHAT MAKES ON-BY-DEFAULT SAFE, and it is not this line: a spec that
207
- // records no assignee sends none (so a PM's triage survives), and a snapshot
208
- // with no assignee key means "never pushed" rather than "was null" (so no
209
- // upgrade emits a clear). Flipping the default widens who gets assigned; it
210
- // cannot widen who gets UNassigned. See `compare.js` `issueChanges`.
211
+ // WHAT MAKES `pull` SAFE ON UPGRADE: a pulled field asserts nothing, so the
212
+ // flip can only make pushes send LESS. A state is never re-sent from an old
213
+ // snapshot (cannot-tell routes to silence), and an assignee hash recorded
214
+ // under `push` is never compared again — so nothing is cleared on the board.
211
215
  fieldOwnership: Object.freeze({
212
216
  description: 'push',
213
217
  subIssues: 'push',
214
- workflowState: 'push',
215
- assignee: 'push',
218
+ workflowState: 'pull',
219
+ assignee: 'pull',
216
220
  }),
217
221
  localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
218
222
  // Fields that are keyed collections (arrays of objects with a stable id),
@@ -283,6 +287,7 @@ function defaults() {
283
287
  preserveOriginal: DEFAULT_CONFIG.intake.preserveOriginal,
284
288
  },
285
289
  mapping: { ...DEFAULT_CONFIG.mapping },
290
+ summary: { ...DEFAULT_CONFIG.summary },
286
291
  states: { ...DEFAULT_CONFIG.states },
287
292
  statesByKind: {},
288
293
  stateAliases: {},
@@ -308,7 +313,7 @@ function defaults() {
308
313
  // vocabularies; `mergeConfig` below is the part that is Linear's — which keys
309
314
  // exist and how they nest.
310
315
  const { isObject, stringList, assign } = kitConfig
311
- const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
316
+ const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields, mergeDescription } =
312
317
  kitConfig.makeMergeHelpers({
313
318
  configFile: CONFIG_FILE,
314
319
  ownership: OWNERSHIP,
@@ -375,6 +380,7 @@ function mergeConfig(base, parsed) {
375
380
  }
376
381
  mergePhaseMapping(base.mapping, parsed.mapping)
377
382
  }
383
+ mergeDescription(base, parsed)
378
384
 
379
385
  mergeStates(base, parsed)
380
386
  mergeStateOverrides(base, parsed, 'statesByKind')
@@ -57,6 +57,8 @@ function runChecks(state = {}) {
57
57
  ]
58
58
  // A retired config key is a stale file, not a broken one (provider-kit
59
59
  // `retiredKeysRow`): present only when the config still carries one.
60
+ // Who owns status and assignee here — a fact, never a fault.
61
+ if (state.ownership) checks.push(state.ownership)
60
62
  if (state.retired) checks.push(state.retired)
61
63
  return combineDoctorChecks(checks)
62
64
  }
@@ -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
  }
@@ -36,6 +36,7 @@
36
36
  * - `updateSubIssue(sub)` apply a sub-issue update
37
37
  * - `remoteEditedLine(identifier)` the someone-else-edited warning
38
38
  * - `twinAdvice(twin, title, specName)` the refusal message for a twin
39
+ * - `afterIssue(issue)` optional; → a report line or null
39
40
  */
40
41
 
41
42
  const path = require('node:path')
@@ -51,6 +52,8 @@ const {
51
52
  remoteDescriptionEdited,
52
53
  remoteSubIssueEdited,
53
54
  listPhaseFiles,
55
+ descriptionMode,
56
+ spliceBlock,
54
57
  } = require('../../sync-core')
55
58
  const { makeSpecHelpers } = require('./specs.js')
56
59
 
@@ -140,11 +143,23 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
140
143
  lines.push(ops.remoteEditedLine(identifier))
141
144
  }
142
145
  if (plan.issue) {
143
- await ops.updateIssue(existing, plan.issue)
146
+ const issue = spliced(plan.issue, 'description', existing, config, identifier, lines)
147
+ await ops.updateIssue(existing, issue)
144
148
  lines.push(` issue updated: ${identifier}`)
145
149
  }
146
150
  }
147
151
 
152
+ // A provider's per-push extra on the spec issue (e.g. progress mirrored into
153
+ // a native field). Never fatal: the repo and the block already carry it.
154
+ if (ops.afterIssue && result.issue) {
155
+ try {
156
+ const line = await ops.afterIssue(result.issue)
157
+ if (line) lines.push(line)
158
+ } catch (error) {
159
+ lines.push(` ?? ${result.issue.identifier}: ${String((error && error.message) || error).split('\n')[0]}`)
160
+ }
161
+ }
162
+
148
163
  // 4. Sub-issue creates — each stamped as it lands, for the same reason.
149
164
  for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
150
165
  const created = await ops.mintSubIssue(parentId, sub)
@@ -167,11 +182,15 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
167
182
  // issue. The read is spent only where the snapshot recorded something to
168
183
  // compare against, so an old snapshot costs no extra calls.
169
184
  const base = readBase(dir, identifier, config)
170
- for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
185
+ const summary = descriptionMode(config) === 'summary'
186
+ for (let sub of (plan.subIssues && plan.subIssues.update) || []) {
171
187
  const streams = base && base.subIssueStreams
172
- if (sub.goal != null && streams && streams[String(sub.id)]) {
188
+ const compare = sub.goal != null && streams && streams[String(sub.id)]
189
+ // Summary mode always reads the live body: the block is spliced into it.
190
+ if (compare || (summary && sub.goal != null)) {
173
191
  const before = await adapter.readIssue(sub.id)
174
- if (remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
192
+ if (compare && remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
193
+ sub = spliced(sub, 'goal', before, config, sub.id, lines)
175
194
  }
176
195
  await ops.updateSubIssue(sub)
177
196
  result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
@@ -198,6 +217,32 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
198
217
  return { result, lines, lost }
199
218
  }
200
219
 
220
+ /**
221
+ * Under `mapping.description: "summary"` the planned body is the block alone,
222
+ * and the write must be the block SPLICED into what the tracker holds, so the
223
+ * team's text around it survives. `spec` mode returns the payload untouched.
224
+ *
225
+ * A damaged block (a delimiter someone edited) is cannot-tell: the body is
226
+ * left out of the write entirely and the run says so. Guessing the edges would
227
+ * eat the team's text, and prepending would leave two blocks.
228
+ */
229
+ function spliced(payload, key, live, config, label, lines) {
230
+ if (descriptionMode(config) !== 'summary' || payload[key] == null) return payload
231
+ const hook = config && config.remote && config.remote.description
232
+ const current = live && typeof hook === 'function' ? hook(live) : live ? live.description : undefined
233
+ // Nothing read back is not an empty body: write nothing rather than guess.
234
+ if (typeof current !== 'string') {
235
+ lines.push(` ?? ${label}: could not read its body — summary block not written`)
236
+ return { ...payload, [key]: undefined }
237
+ }
238
+ const next = spliceBlock(current, payload[key], config)
239
+ if (next == null) {
240
+ lines.push(` !! ${label}: its summary block's delimiters were edited — block not written; repair them and re-push`)
241
+ return { ...payload, [key]: undefined }
242
+ }
243
+ return { ...payload, [key]: next }
244
+ }
245
+
201
246
  // The phase file a sub-issue ref names — the ref is the phase-file basename.
202
247
  function resolvePhaseFileIn(snapshotDir, ref) {
203
248
  const want = String(ref).replace(/\.md$/, '')
@@ -13,6 +13,12 @@
13
13
  * the operator is in the tracker, which is the fact assignment rests on.
14
14
  * - `users [<query>]` finds a person to hand a spec to.
15
15
  *
16
+ * Under `sync.fieldOwnership.assignee: "pull"` the TRACKER owns the field, so
17
+ * `assign` writes the ticket directly and stamps nothing into the repo — there
18
+ * is no projection to carry it, and a stamp would be a copy someone has to
19
+ * keep in step. `--if-unassigned` is how `/spec-start` claims a ticket nobody
20
+ * holds without ever taking one from someone who does.
21
+ *
16
22
  * Everything tracker-shaped arrives as a hook (`makeAssignmentCommands`): the
17
23
  * tracker's name for messages, the frontmatter fields, the store scope, how a
18
24
  * credential resolves and how an adapter is made. The behaviour is the Linear
@@ -21,9 +27,10 @@
21
27
 
22
28
  const path = require('node:path')
23
29
 
24
- const { ownsField, writeFrontmatter, deleteFrontmatter, fieldsOf } = require('../../sync-core')
30
+ const { ownsField, ownershipOf, writeFrontmatter, deleteFrontmatter, fieldsOf, readSnapshot } = require('../../sync-core')
25
31
  const { resolveTransport } = require('./transport.js')
26
32
  const { makeSpecHelpers } = require('./specs.js')
33
+ const { readStatus } = require('./status.js')
27
34
 
28
35
  /**
29
36
  * @param {object} p
@@ -58,6 +65,7 @@ function makeAssignmentCommands(p) {
58
65
 
59
66
  const problems = []
60
67
  if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
68
+ if (flags.release && flags.ifUnassigned) problems.push('--if-unassigned guards an assignment — it has nothing to say about --release')
61
69
  if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
62
70
  // An unlinked spec has no issue to assign. Refusing beats stamping a field
63
71
  // that would sit in the file doing nothing until someone noticed.
@@ -86,6 +94,19 @@ function makeAssignmentCommands(p) {
86
94
  return 1
87
95
  }
88
96
 
97
+ if (ownershipOf(config, 'assignee') === 'pull') return assignOnTracker(config, identifier, flags, out)
98
+
99
+ // Under `push` the repo's stamp IS the record, so that is what the guard asks.
100
+ if (flags.ifUnassigned) {
101
+ const { frontmatter } = readSnapshot(snapshotDir, config)
102
+ const recorded = frontmatter[fields.assigneeId]
103
+ if (recorded) {
104
+ const shown = (fields.assigneeName && frontmatter[fields.assigneeName]) || recorded
105
+ out.write(`spec-sync assign: ${rel} is already assigned to ${shown} — left alone\n`)
106
+ return 0
107
+ }
108
+ }
109
+
89
110
  if (flags.release) {
90
111
  const removed = deleteFrontmatter(snapshotDir, config, [fields.assigneeId, fields.assigneeName].filter(Boolean))
91
112
  if (flags.json) {
@@ -116,6 +137,62 @@ function makeAssignmentCommands(p) {
116
137
  return 0
117
138
  }
118
139
 
140
+ /**
141
+ * The `pull` half of `assign`: write the ticket, stamp nothing.
142
+ *
143
+ * `--if-unassigned` reads the ticket first and acts only on a POSITIVE
144
+ * "nobody holds it". A read that could not run is cannot-tell, and the
145
+ * harmless branch is to assign nobody: taking a ticket from a colleague is
146
+ * the one mistake here that costs someone else their afternoon.
147
+ *
148
+ * Exits 0 on every cannot-tell (MCP transport, no credential, an unreadable
149
+ * ticket) and 1 only when the tracker refused a write it was asked to make.
150
+ */
151
+ async function assignOnTracker(config, identifier, flags, out) {
152
+ const say = (line) => {
153
+ out.write(`spec-sync assign: ${line}\n`)
154
+ return 0
155
+ }
156
+ const report = (result) => {
157
+ if (flags.json) {
158
+ out.write(JSON.stringify({ issue: identifier, owner: 'tracker', ...result }, null, 2) + '\n')
159
+ return 0
160
+ }
161
+ return say(result.line)
162
+ }
163
+ const cred = flags.adapter ? { ok: true } : p.resolveCredential(config, flags.env || process.env)
164
+ const transport = resolveTransport(flags, config, cred.ok)
165
+ if (transport === 'mcp' || !cred.ok) {
166
+ const what = flags.release ? 'unassign it' : `assign it to ${flags.to}`
167
+ return report({
168
+ written: false,
169
+ line: `${p.tracker} owns the assignee here, and there is no API transport — ${what} on ${identifier} with the tracker's own tool; nothing was written`,
170
+ })
171
+ }
172
+ const adapter = flags.adapter || p.makeAdapter(config, cred, flags)
173
+
174
+ if (flags.ifUnassigned) {
175
+ const now = await readStatus({ adapter, ref: identifier, config })
176
+ if (!now.ok) {
177
+ return report({ written: false, line: `could not read ${identifier} (${now.reason}) — assigned nobody` })
178
+ }
179
+ if (now.assignee) {
180
+ const who = now.assignee.name || now.assignee.id
181
+ return report({ written: false, assignee: now.assignee, line: `${identifier} is already assigned to ${who} — left alone` })
182
+ }
183
+ }
184
+
185
+ try {
186
+ await adapter.updateIssue(identifier, { assigneeId: flags.release ? null : flags.to })
187
+ } catch (error) {
188
+ out.write(`spec-sync assign: ${p.tracker} refused — ${String(error.message).split('\n')[0]}\n`)
189
+ return 1
190
+ }
191
+ if (flags.release) return report({ written: true, released: true, line: `${identifier} unassigned on ${p.tracker}` })
192
+ const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
193
+ return report({ written: true, id: flags.to, name: flags.name || null, line: `${identifier} assigned to ${who} on ${p.tracker}` })
194
+ }
195
+
119
196
  /**
120
197
  * Exit 0 even when the answer is "unknown": this answers a question, and
121
198
  * "nobody is identified here" is a valid answer — a shared key, an offline
@@ -236,6 +236,33 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
236
236
  base[key] = table
237
237
  }
238
238
 
239
+ // Merge (and validate) what a ticket's description carries —
240
+ // `mapping.description` (`spec` · `summary`) and the block's delimiter style
241
+ // (`summary.delimiter`: `comment` · `heading`). Loud on a bad value: a typo
242
+ // must not read as a choice to keep pushing the whole spec.
243
+ function mergeDescription(base, parsed) {
244
+ if (isObject(parsed.mapping) && parsed.mapping.description !== undefined) {
245
+ const mode = parsed.mapping.description
246
+ if (!DESCRIPTION_MODES.includes(mode)) {
247
+ throw new Error(
248
+ `Invalid ${configFile}: mapping.description = ${JSON.stringify(mode)} ` +
249
+ `(expected one of ${DESCRIPTION_MODES.join('|')})`,
250
+ )
251
+ }
252
+ base.mapping.description = mode
253
+ }
254
+ if (isObject(parsed.summary) && parsed.summary.delimiter !== undefined) {
255
+ const style = parsed.summary.delimiter
256
+ if (!DELIMITER_STYLES.includes(style)) {
257
+ throw new Error(
258
+ `Invalid ${configFile}: summary.delimiter = ${JSON.stringify(style)} ` +
259
+ `(expected one of ${DELIMITER_STYLES.join('|')})`,
260
+ )
261
+ }
262
+ base.summary = { ...(base.summary || {}), delimiter: style }
263
+ }
264
+ }
265
+
239
266
  return {
240
267
  mergeStates,
241
268
  mergeStateOverrides,
@@ -243,9 +270,15 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
243
270
  mergePhaseMapping,
244
271
  mergeReleaseIgnorePaths,
245
272
  mergeKeyedFields,
273
+ mergeDescription,
246
274
  }
247
275
  }
248
276
 
277
+ // What `mapping.description` may be. `spec` is the default and what a config
278
+ // that predates the key gets, so an upgrade rewrites no ticket.
279
+ const DESCRIPTION_MODES = Object.freeze(['spec', 'summary'])
280
+ const DELIMITER_STYLES = Object.freeze(['comment', 'heading'])
281
+
249
282
  // Keys no provider reads any more. The merge already ignores them, as it does
250
283
  // every unknown key — so a config still carrying one is a stale file, not a
251
284
  // broken one, and `doctor` says so as a `warn` without touching the exit code.
@@ -292,4 +325,4 @@ function retiredKeysRow(file, configFile, row) {
292
325
  )
293
326
  }
294
327
 
295
- module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS }
328
+ module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS, DESCRIPTION_MODES, DELIMITER_STYLES }
@@ -14,22 +14,46 @@ function expandStateArgs(args, config) {
14
14
  return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
15
15
  }
16
16
 
17
- // The spec's status beside the board's, and whether they disagree. A board
18
- // state that maps to no bucket never disagrees: it is somewhere push does not
19
- // manage, which is not a claim about the spec. Nor does a row whose spec is not
20
- // on this machine — there is nothing to disagree WITH.
17
+ // A spec's bucket is a CODE FACT — whether `/spec-start`, `/spec-complete` or
18
+ // `/spec-cancel` has run — and the board holds the planning status. So almost
19
+ // every difference between the two is the board doing its job: a backlog spec
20
+ // the board calls Ready or Blocked, an in-flight one it calls In Review. Neither
21
+ // is a claim about the repo, and flagging them would teach a reader to ignore
22
+ // the column.
23
+ //
24
+ // One difference IS worth a reader's time: the board says the work is finished
25
+ // (Done or Cancelled) and the repo has not done the matching cleanup. Only that
26
+ // pairing disagrees, and it carries the command that would close it.
27
+ const LIVE_BUCKETS = ['backlog', 'in-progress']
28
+ const FINISHED_BUCKETS = ['complete', 'cancelled']
29
+
30
+ // `{ board, cleanup }` when the board has finished what the repo has not, else
31
+ // null. Done against a spec in flight is `/spec-complete`; every other pairing
32
+ // (Cancelled, or Done on a spec that never started) is `/spec-cancel`, because
33
+ // there is no work here to complete.
34
+ function boardDisagreement(specBucket, boardBucket) {
35
+ if (!LIVE_BUCKETS.includes(specBucket) || !FINISHED_BUCKETS.includes(boardBucket)) return null
36
+ const cleanup = specBucket === 'in-progress' && boardBucket === 'complete' ? '/spec-complete' : '/spec-cancel'
37
+ return { board: boardBucket, cleanup }
38
+ }
39
+
40
+ // The spec's status beside the board's, and whether they disagree in the one
41
+ // way above. A board state that maps to no bucket never disagrees: it is
42
+ // somewhere push does not manage, which is not a claim about the spec. Nor does
43
+ // a row whose spec is not on this machine — there is nothing to disagree WITH.
21
44
  function specColumn(stateName, spec, config) {
22
45
  const specStatus = spec ? spec.bucket : null
23
46
  const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
24
- const disagrees = Boolean(specStatus && seen && seen.mapped && seen.bucket !== specStatus)
25
- return { specStatus, disagrees }
47
+ const found = specStatus && seen && seen.mapped ? boardDisagreement(specStatus, seen.bucket) : null
48
+ return found ? { specStatus, disagrees: true, cleanup: found.cleanup } : { specStatus, disagrees: false }
26
49
  }
27
50
 
28
- // The cell itself: `in-progress`, `≠ backlog` when it disagrees, `—` when the
29
- // spec is not here.
30
- function specCell({ specStatus, disagrees }) {
51
+ // The cell itself: `in-progress`, `≠ in-progress → /spec-cancel` when the board
52
+ // finished it, `—` when the spec is not here.
53
+ function specCell({ specStatus, disagrees, cleanup }) {
31
54
  if (!specStatus) return '—'
32
- return disagrees ? `≠ ${specStatus}` : specStatus
55
+ if (!disagrees) return specStatus
56
+ return cleanup ? `≠ ${specStatus} → ${cleanup}` : `≠ ${specStatus}`
33
57
  }
34
58
 
35
- module.exports = { expandStateArgs, specColumn, specCell }
59
+ module.exports = { expandStateArgs, specColumn, specCell, boardDisagreement }
@@ -146,7 +146,10 @@ function ticketsInRange(commits, options = {}) {
146
146
  let unreferenced = 0
147
147
  let ignored = 0
148
148
  let historical = 0
149
+ let merges = 0
150
+ let sawMergeFlag = false
149
151
  for (const commit of commits || []) {
152
+ if (commit && commit.isMerge !== undefined) sawMergeFlag = true
150
153
  if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
151
154
  // Not counted as unreferenced either: that number exists to surface a
152
155
  // MISSED trailer, and a paperwork commit is not a gap someone should hunt.
@@ -157,8 +160,15 @@ function ticketsInRange(commits, options = {}) {
157
160
  if (!refs.length) {
158
161
  // A POSITIVE signal, never an absence: only a trailer that actually
159
162
  // carries an older tracker's ref makes a commit historical. A commit with
160
- // no trailer at all is still the gap `unreferenced` is there to name.
163
+ // no trailer at all is still the gap `unreferenced` is there to name —
164
+ // unless it is a MERGE commit, which is transport: under PR landing the
165
+ // host writes one per merged PR, and counting each as a missed trailer
166
+ // buries the real gaps. A merge that CARRIES a trailer still counted
167
+ // above, deliberately — a hand merge is where a ticket's only trailer
168
+ // sometimes lives, which is why these are read rather than skipped
169
+ // (`--no-merges` was tried and dropped for exactly that loss).
161
170
  if (foreign.some((p) => refsInBody(commit && commit.body, p).length)) historical++
171
+ else if (commit && commit.isMerge) merges++
162
172
  else unreferenced++
163
173
  continue
164
174
  }
@@ -171,6 +181,9 @@ function ticketsInRange(commits, options = {}) {
171
181
  total: (commits || []).length,
172
182
  }
173
183
  if (foreign.length) report.historical = historical
184
+ // Present only when a caller supplied the flag at all, so a provider that
185
+ // passes no parent info sees exactly the report shape it always did.
186
+ if (sawMergeFlag) report.merges = merges
174
187
  return report
175
188
  }
176
189
 
@@ -24,7 +24,7 @@ const {
24
24
  resolvePrimaryCheckout,
25
25
  } = require('../../../env/resolve.js')
26
26
  const { loadEnvConfig } = require('../../../env/config.js')
27
- const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
27
+ const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored, comparableDescription } = require('../../sync-core')
28
28
 
29
29
  function makeSpecHelpers({ program = 'spec-sync' } = {}) {
30
30
  // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder
@@ -227,7 +227,9 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
227
227
  bad++
228
228
  continue
229
229
  }
230
- const r = compareStored(sent, got, config)
230
+ // Summary mode compares the block alone: the text around it is the
231
+ // team's. Right after a write a missing block IS a loss, so it reads as ''.
232
+ const r = compareStored(sent, comparableDescription(got, config) ?? '', config)
231
233
  if (r.ok) continue
232
234
  bad++
233
235
  lines.push(
@@ -0,0 +1,64 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `spec-sync splice <spec> --live <file> [--phase <ref>]` — the body to write,
5
+ * for an apply the ENGINE is not doing (the skills' MCP path).
6
+ *
7
+ * Under `mapping.description: "summary"` a plan carries the block alone, and
8
+ * writing that over the whole description would delete the team's text around
9
+ * it. So the skill reads the live body, hands it here, and writes back exactly
10
+ * what this prints — the splice is the engine's, never composed in a skill.
11
+ * In `spec` mode it prints the projection as it is: the whole body is the
12
+ * repo's there.
13
+ *
14
+ * Exit codes: 0 with the body on stdout; 1 when nothing must be written — a
15
+ * damaged block (a delimiter someone edited), an unknown phase ref, or a live
16
+ * file that could not be read. Nothing is printed to stdout then, so a caller
17
+ * that pipes stdout into a write can never write a partial or empty body.
18
+ */
19
+
20
+ const fs = require('node:fs')
21
+
22
+ const { projectionOf, descriptionMode, spliceBlock } = require('../../sync-core')
23
+
24
+ function spliceBody(snapshotDir, config, live, phaseRef) {
25
+ const projection = projectionOf(snapshotDir, config)
26
+ let planned = projection.description
27
+ if (phaseRef) {
28
+ const want = String(phaseRef).replace(/\.md$/, '')
29
+ const sub = (projection.subIssues || []).find((s) => s.ref === want)
30
+ if (!sub) return { ok: false, reason: `no phase ${want} in the projection` }
31
+ planned = sub.goal
32
+ }
33
+ if (planned == null) return { ok: false, reason: 'the projection has no body for that object' }
34
+ if (descriptionMode(config) !== 'summary') return { ok: true, text: planned }
35
+ const text = spliceBlock(live, planned, config)
36
+ if (text == null) {
37
+ return { ok: false, reason: "its summary block's delimiters were edited — write nothing; repair them and re-run" }
38
+ }
39
+ return { ok: true, text }
40
+ }
41
+
42
+ function specSyncSplice({ snapshotDir, config, flags, out, err, program = 'spec-sync' }) {
43
+ const say = (msg) => (err || out).write(`${program} splice: ${msg}\n`)
44
+ if (!flags.live) {
45
+ say('pass --live <file> holding the description the tracker has now (an empty file for a new issue)')
46
+ return 1
47
+ }
48
+ let live
49
+ try {
50
+ live = fs.readFileSync(flags.live, 'utf-8')
51
+ } catch (error) {
52
+ say(`cannot read --live: ${error.message}`)
53
+ return 1
54
+ }
55
+ const r = spliceBody(snapshotDir, config, live, flags.phase)
56
+ if (!r.ok) {
57
+ say(r.reason)
58
+ return 1
59
+ }
60
+ out.write(r.text)
61
+ return 0
62
+ }
63
+
64
+ module.exports = { spliceBody, specSyncSplice }