@skitterbyte/skitterspec-jira 2.7.0 → 2.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.
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +16 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +40 -11
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +30 -13
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +134 -17
- package/src/env/config.js +47 -6
- package/src/env/epic.js +23 -8
- package/src/env/epicpage.js +4 -3
- package/src/env/epicread.js +39 -1
- package/src/env/integrate.js +48 -1
- package/src/env/project.js +18 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +17 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
package/src/env/teardown.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
}
|