@skitterbyte/skitterspec-linear 19.7.0 → 19.8.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.
@@ -47,6 +47,15 @@ function planDown(spec, config, flags, ctx) {
47
47
  // can use `-D` — the same question ("are these commits recoverable?"), so the
48
48
  // two must never answer it differently.
49
49
  const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
50
+ // A spec-documents-only branch under `land.specDocs: "branch"` — authored,
51
+ // perhaps pushed, never started (feat-tracker-spec-branches). It holds no
52
+ // code to lose and was never meant to have a PR, and left on the remote it
53
+ // reads as backlog to every check that scans spec branches. `docsOnly` is a
54
+ // positive signal the caller computes from the branch's own range; anything
55
+ // it cannot read stays false, which keeps every guard below as it was.
56
+ const docsLane = Boolean(
57
+ worktreeState.docsOnly && config.land && config.land.specDocs === 'branch',
58
+ )
50
59
 
51
60
  // --- guards (overridable with --force) ---
52
61
  if (!force) {
@@ -69,7 +78,7 @@ function planDown(spec, config, flags, ctx) {
69
78
  // PR and the exit where git's cannot. `--force` bypasses, and still plans
70
79
  // `-d` below, so a genuinely unlanded branch fails loudly rather than
71
80
  // being -D'd.
72
- if (config.land && config.land.strategy === 'pr' && !landed) {
81
+ if (config.land && config.land.strategy === 'pr' && !landed && !docsLane) {
73
82
  const prState = worktreeState.prState
74
83
  const at = worktreeState.prUrl ? ` — see ${worktreeState.prUrl}` : ''
75
84
  if (prState === 'open' || prState === 'draft') {
@@ -188,9 +197,15 @@ function planDown(spec, config, flags, ctx) {
188
197
  // this delete a no-op: `git push --delete` errors with "remote ref does not
189
198
  // exist", which is loud and destroys nothing. The skills report that as
190
199
  // already-gone, never as a failed teardown.
200
+ //
201
+ // The docs lane is the one unlanded branch that may be offered: its remote
202
+ // copy backs up only the spec document being cancelled, and the ticket keeps
203
+ // the record. It is ALWAYS confirm-first — "always" folds the landed delete
204
+ // into the run-blind list, but deleting the last copy of a document is not
205
+ // what that policy was set for.
191
206
  const remoteCommands = []
192
207
  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
193
- if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
208
+ if (spec.branch && (landed || docsLane) && worktreeState.remoteBranch && policy !== 'never') {
194
209
  // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
195
210
  // itself contains slashes, so the remote is what remains once the exact
196
211
  // "/<branch>" suffix is stripped — not the text before the first slash.
@@ -206,7 +221,7 @@ function planDown(spec, config, flags, ctx) {
206
221
  const cmd = `git push ${remote} --delete ${spec.branch}`
207
222
  // "always" is the project saying it never wants to be asked, so the push
208
223
  // joins the run-blind list. Everything else keeps it quarantined.
209
- if (policy === 'always') commands.push(cmd)
224
+ if (policy === 'always' && landed) commands.push(cmd)
210
225
  else remoteCommands.push(cmd)
211
226
  }
212
227
  }
package/src/gating.js CHANGED
@@ -15,6 +15,7 @@
15
15
 
16
16
  const fs = require('node:fs')
17
17
  const path = require('node:path')
18
+ const { preferBranches, branchLabel } = require('./env/specbranches.js')
18
19
 
19
20
  const CONFIG_FILE = path.join('specs', '.core', 'gating.config.json')
20
21
 
@@ -87,6 +88,12 @@ function readGatingField(specPath) {
87
88
  } catch {
88
89
  return { raw: null, kind: 'missing' }
89
90
  }
91
+ return readGatingText(raw)
92
+ }
93
+
94
+ // The same reading over an overview's text — a spec read off its own branch
95
+ // (`env/specbranches.js`) has text and no path on disk.
96
+ function readGatingText(raw) {
90
97
  const m = /^>\s*\*\*Gating:\*\*\s*(.*)$/m.exec(raw)
91
98
  if (!m) return { raw: null, kind: 'missing' }
92
99
  const value = m[1].trim().replace(/^["'`]|["'`]$/g, '')
@@ -130,15 +137,19 @@ function activeSpecs(dir) {
130
137
  * @returns {{configured: boolean, findings: Array<{folder, bucket, kind, raw}>,
131
138
  * checked: number, guidance: string}}
132
139
  */
133
- function checkGating(dir, specs) {
140
+ function checkGating(dir, specs, { branches = [] } = {}) {
134
141
  const { config, present } = loadGatingConfig(dir)
135
142
  if (!present) return { configured: false, findings: [], checked: 0, guidance: '' }
136
- const targets = specs && specs.length ? specs : activeSpecs(dir)
143
+ // Branch copies (`env/specbranches.js`) win over the disk copy of the same
144
+ // spec and add the ones the base branch cannot see; finished buckets are not
145
+ // gating's business either way.
146
+ const active = branches.filter((b) => ACTIVE_BUCKETS.includes(b.bucket))
147
+ const targets = specs && specs.length ? specs : preferBranches(activeSpecs(dir), active)
137
148
  const findings = []
138
149
  for (const spec of targets) {
139
- const { kind, raw } = readGatingField(spec.path)
150
+ const { kind, raw } = spec.ref ? readGatingText(spec.overview) : readGatingField(spec.path)
140
151
  if (kind === 'missing' || kind === 'invalid') {
141
- findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw })
152
+ findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw, ...(spec.ref ? { from: branchLabel(spec) } : {}) })
142
153
  }
143
154
  }
144
155
  return { configured: true, findings, checked: targets.length, guidance: config.guidance }
@@ -150,6 +161,7 @@ module.exports = {
150
161
  ACTIVE_BUCKETS,
151
162
  loadGatingConfig,
152
163
  readGatingField,
164
+ readGatingText,
153
165
  activeSpecs,
154
166
  checkGating,
155
167
  }
@@ -37,6 +37,10 @@
37
37
  * - `remoteEditedLine(identifier)` the someone-else-edited warning
38
38
  * - `twinAdvice(twin, title, specName)` the refusal message for a twin
39
39
  * - `afterIssue(issue)` optional; → a report line or null
40
+ * - `retireSubIssue(id)` optional; close a leftover phase
41
+ * sub-issue as not planned and
42
+ * unlink it. Absent means this tracker
43
+ * cannot, and the push names the ids.
40
44
  * - `setParent(issue, parentIdentifier)` optional; make the spec issue a
41
45
  * child of its epic's → `{ changed }`.
42
46
  * Absent means this tracker cannot
@@ -226,6 +230,26 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
226
230
  lines.push(` sub-issue updated: ${sub.id}`)
227
231
  }
228
232
 
233
+ // 5b. Retire an epic's leftover phase sub-issues (spec feat-epic-migration,
234
+ // Decision 2). Never fatal: a tracker without the seam names the ids once and
235
+ // they are forgotten — the line is the record; a retire that FAILS keeps its
236
+ // id in the snapshot, so the next push tries again.
237
+ const keepSubIssues = []
238
+ const retire = (plan.subIssues && plan.subIssues.retire) || []
239
+ if (retire.length && typeof ops.retireSubIssue !== 'function') {
240
+ lines.push(` this tracker cannot retire sub-issues here — close by hand: ${retire.join(', ')}`)
241
+ } else {
242
+ for (const id of retire) {
243
+ try {
244
+ await ops.retireSubIssue(id)
245
+ lines.push(` sub-issue retired: ${id} (no phase claims it on an epic)`)
246
+ } catch (error) {
247
+ keepSubIssues.push(id)
248
+ lines.push(` ?? retire ${id}: ${String((error && error.message) || error).split('\n')[0]}`)
249
+ }
250
+ }
251
+ }
252
+
229
253
  // 6. Read back what the tracker stored and run the SAME check verify runs.
230
254
  const stored = { issue: undefined, subIssues: {} }
231
255
  if (result.issue) {
@@ -241,7 +265,7 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
241
265
  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
242
266
 
243
267
  // 7. Record the snapshot from the now-stamped files, so the next push is empty.
244
- const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent })
268
+ const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
245
269
  // A repo path, `/`-separated on every platform — the form every other
246
270
  // spec path in this output takes.
247
271
  lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
@@ -252,7 +252,7 @@ function remapped(recorded, current) {
252
252
  * `plan.issue` (when present) is the spec issue's description + state; the push
253
253
  * skill applies its provider's project/grouping choice on top of it.
254
254
  */
255
- function planChanges(projection, snapshot, { linked = false } = {}) {
255
+ function planChanges(projection, snapshot, { linked = false, epic = false } = {}) {
256
256
  const p = projection || {}
257
257
  const snap = snapshot || {}
258
258
  const snapS = snap.subIssues || {}
@@ -297,6 +297,13 @@ function planChanges(projection, snapshot, { linked = false } = {}) {
297
297
  }
298
298
  }
299
299
 
300
+ // AN EPIC'S UNCLAIMED IDS ARE LEFTOVERS, NOT LOST STAMPS. An epic has no
301
+ // phases by construction (spec feat-epics, Decision 1), so every sub-issue the
302
+ // snapshot remembers belongs to the plan spec it was converted from — a
303
+ // positive signal. On any other kind an unclaimed id stays the ambiguity it
304
+ // is above, and nothing is retired (spec feat-epic-migration, Decision 2).
305
+ if (epic && unclaimed.length) subIssues.retire = unclaimed.slice()
306
+
300
307
  const plan = { subIssues }
301
308
  if (unstamped.length) plan.unstamped = unstamped
302
309
  const issue = issueChanges(p, snap, { linked })
@@ -394,7 +401,8 @@ function issueChanges(projection, snapshot, { linked = false } = {}) {
394
401
 
395
402
  // True when a plan would push nothing.
396
403
  function isEmptyPlan(plan) {
397
- return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length
404
+ const retire = plan.subIssues.retire || []
405
+ return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length && !retire.length
398
406
  }
399
407
 
400
408
  module.exports = {
@@ -1,5 +1,7 @@
1
1
  'use strict'
2
2
 
3
+ const path = require('node:path')
4
+
3
5
  /**
4
6
  * `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
5
7
  * generated mirror. We never read remote content: `push` builds the local
@@ -102,7 +104,8 @@ function isLinked(snapshotDir, config) {
102
104
  function push({ dir, snapshotDir, identifier, config }) {
103
105
  const projection = projectionOf(snapshotDir, config)
104
106
  const snapshot = readBase(dir, identifier, config)
105
- const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config) })
107
+ const epic = path.basename(String(snapshotDir || '')).startsWith('epic-')
108
+ const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config), epic })
106
109
  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
107
110
  // plan above is all-creates and would abandon a live mirror. Carry the finding
108
111
  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
@@ -134,10 +137,18 @@ function push({ dir, snapshotDir, identifier, config }) {
134
137
  // that was NOT sent would claim the tracker holds it, and silence the very remap
135
138
  // this record exists to catch. Without `sent` (a hand-applied MCP push) nothing
136
139
  // new is recorded and what was there is kept.
137
- function recordPush({ dir, snapshotDir, identifier, config, sent = null }) {
140
+ // `keepSubIssues` names ids the projection no longer claims but the tracker may
141
+ // still hold — a retire that failed — so the next push plans them again rather
142
+ // than forgetting them.
143
+ function recordPush({ dir, snapshotDir, identifier, config, sent = null, keepSubIssues = [] }) {
138
144
  const projection = projectionOf(snapshotDir, config)
139
145
  const snapshot = snapshotOf(projection, config)
140
- const names = stateNamesRecord(projection, readBase(dir, identifier, config), sent)
146
+ const before = readBase(dir, identifier, config)
147
+ for (const id of keepSubIssues) {
148
+ const hash = before && before.subIssues && before.subIssues[String(id)]
149
+ if (hash !== undefined) snapshot.subIssues[String(id)] = hash
150
+ }
151
+ const names = stateNamesRecord(projection, before, sent)
141
152
  if (names) snapshot.stateNames = names
142
153
  return writeBase(dir, identifier, config, snapshot)
143
154
  }