@skitterbyte/skitterspec-jira 2.14.0 → 2.16.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 (43) hide show
  1. package/assets/claude-md-section.md +12 -0
  2. package/assets/core/SETUP.md +12 -12
  3. package/assets/core/env.config.md +25 -3
  4. package/assets/hooks/main-guard.cjs +73 -6
  5. package/assets/hooks/project-guard.cjs +80 -6
  6. package/assets/hooks/review-gate.cjs +73 -6
  7. package/assets/review/page.html +2 -1
  8. package/assets/rules/commit-trailers.md +2 -2
  9. package/assets/rules/offered-unblocks.md +22 -0
  10. package/assets/rules/spec-planning.md +12 -1
  11. package/assets/skills/no-spec/SKILL.md +5 -0
  12. package/assets/skills/spec/SKILL.md +20 -3
  13. package/assets/skills/spec-bug/SKILL.md +8 -2
  14. package/assets/skills/spec-complete/SKILL.md +28 -2
  15. package/assets/skills/spec-diff/SKILL.md +5 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +8 -2
  17. package/assets/skills/spec-idea/SKILL.md +5 -0
  18. package/assets/skills/spec-init/SKILL.md +4 -2
  19. package/assets/skills/spec-next/SKILL.md +18 -0
  20. package/assets/skills/spec-park/SKILL.md +92 -0
  21. package/assets/skills/spec-resume/SKILL.md +153 -0
  22. package/assets/skills/spec-start/SKILL.md +6 -2
  23. package/assets/skills/spec-sync/SKILL.md +10 -10
  24. package/assets/skills/spec-to-main/SKILL.md +5 -1
  25. package/assets/skills/spec-todo/SKILL.md +5 -2
  26. package/package.json +1 -1
  27. package/src/cli.js +311 -15
  28. package/src/env/base.js +21 -5
  29. package/src/env/basepin.js +62 -0
  30. package/src/env/bootstrap.js +3 -1
  31. package/src/env/checks.js +49 -0
  32. package/src/env/config.js +48 -1
  33. package/src/env/hooks.js +53 -4
  34. package/src/env/provision.js +10 -2
  35. package/src/env/resolve.js +66 -13
  36. package/src/env/resume.js +234 -0
  37. package/src/env/review.js +4 -1
  38. package/src/env/serve.js +3 -0
  39. package/src/ideacmd.js +11 -1
  40. package/src/init.js +287 -49
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/provider-kit/src/specs.js +46 -1
  43. package/src/vendor/sync-core/src/summary.js +10 -1
@@ -0,0 +1,234 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Going back into a spec that is already in flight (feat-spec-resume) — the
5
+ * engine behind `skitterspec spec-env resume <name|#N>`.
6
+ *
7
+ * A spec that waits on something outside the repo — a deploy, another
8
+ * project's release, a soak period — is left and come back to. Coming back is
9
+ * not starting: nothing here moves a bucket, assigns anyone or touches a
10
+ * tracker. It answers three things, and the skill acts on them:
11
+ *
12
+ * - which spec the argument means (a folder name, or a tracker ref read off
13
+ * each copy's frontmatter through `branch.identifierField`),
14
+ * - whether it can be resumed (only `in-progress` — read from the spec's OWN
15
+ * copy, since the base branch goes on reading `backlog` for the life of a
16
+ * spec), and how to rebuild its worktree when this machine has none,
17
+ * - what it is blocked on (`> **Blocked on:**`, on the overview or a phase).
18
+ *
19
+ * Pure: callers hand in the copies they could read and whether the worktree
20
+ * and branches exist. `cli.js` does the reading.
21
+ */
22
+
23
+ const { phaseProgress } = require('./phases.js')
24
+ const { shellPath } = require('./project.js')
25
+
26
+ // Same grammar as `specstate.js`'s header(): a blockquote `**Field:**` line.
27
+ function headerValue(text, field) {
28
+ const m = new RegExp(`^>\\s*\\*\\*${field}:\\*\\*[ \\t]*(.*)$`, 'm').exec(String(text || ''))
29
+ if (!m) return null
30
+ const value = m[1].trim()
31
+ return value && value !== '—' && value !== '-' ? value : null
32
+ }
33
+
34
+ // A real calendar date, or null. `2026-02-31` is not one, and a malformed
35
+ // `until` must stay text rather than become a date someone acts on.
36
+ function calendarDate(s) {
37
+ if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return null
38
+ const d = new Date(`${s}T00:00:00Z`)
39
+ return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s ? s : null
40
+ }
41
+
42
+ /**
43
+ * One `Blocked on:` value → `{ text, until }`. A trailing `(until YYYY-MM-DD)`
44
+ * is the only part read as data; anything else — including an `until` that is
45
+ * not a real date — stays in `text`, so a typo is shown rather than obeyed.
46
+ */
47
+ function parseBlockedOn(value) {
48
+ if (!value) return null
49
+ const m = /^(.*?)\s*\(until\s+([^)]*)\)\s*$/.exec(value)
50
+ const until = m ? calendarDate(m[2].trim()) : null
51
+ return until ? { text: m[1].trim() || value, until } : { text: value, until: null }
52
+ }
53
+
54
+ /**
55
+ * Every blocker a spec records: the overview's (`where: 'spec'`), then each
56
+ * phase file's (`where: <phase number>`), in phase order.
57
+ *
58
+ * @param {{ overview: string, phases?: Array<{ n: number, text: string }> }} copy
59
+ * @returns {Array<{ where: 'spec'|number, text: string, until: string|null }>}
60
+ */
61
+ function blockers(copy) {
62
+ const out = []
63
+ const spec = parseBlockedOn(headerValue(copy && copy.overview, 'Blocked on'))
64
+ if (spec) out.push({ where: 'spec', ...spec })
65
+ const phases = ((copy && copy.phases) || []).filter((p) => p && typeof p.text === 'string')
66
+ for (const p of [...phases].sort((a, b) => a.n - b.n)) {
67
+ const b = parseBlockedOn(headerValue(p.text, 'Blocked on'))
68
+ if (b) out.push({ where: p.n, ...b })
69
+ }
70
+ return out
71
+ }
72
+
73
+ /**
74
+ * The blocker that stands in front of the NEXT build, or null.
75
+ *
76
+ * The next build is the first phase not `✅` — the one `/spec-next` would
77
+ * pick. A spec-level blocker holds every phase; a phase's own holds only that
78
+ * phase. A blocker on a LATER phase is not this build's business and says
79
+ * nothing: a spec planned to wait at phase 4 builds phases 1–3 unhindered.
80
+ * Nothing left to build means nothing to block.
81
+ */
82
+ function blockingNext(copy) {
83
+ const all = blockers(copy)
84
+ const phases = ((copy && copy.phases) || []).filter((p) => p && typeof p.text === 'string')
85
+ const heading = (t) => (t.split('\n').find((l) => /^#\s/.test(l)) || '').trim()
86
+ const next = [...phases].sort((a, b) => a.n - b.n).find((p) => !heading(p.text).endsWith('✅'))
87
+ if (!next) return null
88
+ return all.find((b) => b.where === 'spec') || all.find((b) => b.where === next.n) || null
89
+ }
90
+
91
+ // A frontmatter field off an overview's text — the in-memory twin of
92
+ // resolve.js `readFrontmatterField`, for copies read off a branch.
93
+ function frontmatterField(text, field) {
94
+ if (!field) return null
95
+ const fm = /^---\n([\s\S]*?)\n---/.exec(String(text || ''))
96
+ if (!fm) return null
97
+ const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(fm[1])
98
+ return m ? m[1].trim().replace(/^["']|["']$/g, '') || null : null
99
+ }
100
+
101
+ // `#241`, `241` and `"#241"` are one ticket; `ABC-88` only ever matches itself.
102
+ function sameRef(a, b) {
103
+ const norm = (s) => String(s).trim().replace(/^#/, '').toLowerCase()
104
+ return Boolean(a) && Boolean(b) && norm(a) === norm(b)
105
+ }
106
+
107
+ // Which copy speaks for a spec: its own worktree, then a branch (local before
108
+ // remote-tracking), then the checkout the command was run from.
109
+ const RANK = { worktree: 0, branch: 1, here: 2 }
110
+ function rank(c) {
111
+ return RANK[c.origin] * 2 + (c.origin === 'branch' && !c.local ? 1 : 0)
112
+ }
113
+
114
+ /**
115
+ * The copy an argument means, or a refusal.
116
+ *
117
+ * A FOLDER NAME WINS OVER A REF. Folder names carry a kind prefix
118
+ * (`feat-`, `bug-`…) and tracker refs do not, so the two cannot collide in
119
+ * practice — but if one ever did, the name someone typed for a folder is the
120
+ * more specific claim.
121
+ *
122
+ * A REF THAT MATCHES NOTHING NAMES NOTHING. It never falls back to the nearest
123
+ * spec or the only one provisioned: resuming the wrong spec writes into a
124
+ * branch nobody asked about. Without `branch.identifierField` a ref cannot be
125
+ * read at all, and the refusal says that rather than "not found".
126
+ *
127
+ * @param {string} arg
128
+ * @param {Array<{ folder, bucket, origin: 'worktree'|'branch'|'here', local?, ref?, overview, phases }>} copies
129
+ * @param {string} [identifierField]
130
+ */
131
+ function findTarget(arg, copies, identifierField) {
132
+ const wanted = String(arg || '').trim()
133
+ if (!wanted) return { refused: 'no spec given — /spec-resume <name> or /spec-resume #<ticket>' }
134
+ const best = (list) => [...list].sort((a, b) => rank(a) - rank(b))[0]
135
+ const byName = copies.filter((c) => c.folder === wanted)
136
+ if (byName.length) return { target: best(byName), by: 'name' }
137
+
138
+ if (!identifierField) {
139
+ return {
140
+ refused:
141
+ `no spec named ${wanted}` +
142
+ (/^#?[\w-]*\d+$/.test(wanted)
143
+ ? ', and a ticket ref cannot be looked up: branch.identifierField is not set in env.config.json'
144
+ : ''),
145
+ }
146
+ }
147
+ const byRef = copies.filter((c) => sameRef(frontmatterField(c.overview, identifierField), wanted))
148
+ const folders = [...new Set(byRef.map((c) => c.folder))]
149
+ if (!folders.length) return { refused: `no spec named or linked to ${wanted}` }
150
+ if (folders.length > 1) {
151
+ return { refused: `${wanted} is linked from more than one spec (${folders.join(', ')}) — name the one you mean` }
152
+ }
153
+ return { target: best(byRef), by: 'ref' }
154
+ }
155
+
156
+ /**
157
+ * The full answer for a found copy.
158
+ *
159
+ * @param {object} target the copy `findTarget` chose
160
+ * @param {object} env what the caller could see:
161
+ * `{ branch, worktreePath, worktreeExists, localBranch, remoteBranch, remote, identifierField }`
162
+ */
163
+ function planResume(target, env) {
164
+ const progress = phaseProgress((target.phases || []).map((p) => ({ content: p.text })))
165
+ const base = {
166
+ spec: target.folder,
167
+ bucket: target.bucket,
168
+ source: target.origin,
169
+ branch: env.branch,
170
+ identifier: frontmatterField(target.overview, env.identifierField),
171
+ progress: { done: progress.done, total: progress.total, current: progress.current },
172
+ blockers: blockers(target),
173
+ blocking: blockingNext(target),
174
+ worktree: { path: env.worktreePath, present: Boolean(env.worktreeExists) },
175
+ }
176
+ if (target.bucket !== 'in-progress') {
177
+ const how =
178
+ target.bucket === 'backlog'
179
+ ? ' — it was never started; /spec-start puts it in flight'
180
+ : ' — there is nothing left to resume'
181
+ return { ok: false, ...base, refused: `${target.folder} is in ${target.bucket}${how}` }
182
+ }
183
+ if (env.worktreeExists) return { ok: true, ...base, commands: [], then: [] }
184
+
185
+ // NEVER `-b` WITHOUT A BRANCH TO ATTACH. A fresh fork from base would hand
186
+ // back an empty tree with the spec's work out of reach — that is a start,
187
+ // and starting is /spec-start's. So: the local branch, else the remote's,
188
+ // else a refusal.
189
+ let commands
190
+ if (env.localBranch) {
191
+ commands = [`git worktree add ${shellPath(env.worktreePath)} ${env.branch}`]
192
+ } else if (env.remoteBranch) {
193
+ commands = [
194
+ `git fetch ${env.remote} ${env.branch}`,
195
+ `git worktree add ${shellPath(env.worktreePath)} -b ${env.branch} --track ${env.remote}/${env.branch}`,
196
+ ]
197
+ } else {
198
+ return {
199
+ ok: false,
200
+ ...base,
201
+ refused: `${target.folder} has no worktree and no ${env.branch} branch here or on ${env.remote} — nothing to resume from`,
202
+ }
203
+ }
204
+ return { ok: true, ...base, commands, then: [`skitterspec spec-env bootstrap ${target.folder}`] }
205
+ }
206
+
207
+ function blockerLine(b) {
208
+ const where = b.where === 'spec' ? 'spec' : `phase ${b.where}`
209
+ return `${where} — ${b.text}${b.until ? ` (until ${b.until})` : ''}`
210
+ }
211
+
212
+ /** The text report — what `spec-env resume` prints without `--json`. */
213
+ function resumeLines(r) {
214
+ if (r.refusedOnly) return [`spec-env resume: refused — ${r.refused}`]
215
+ const lines = [`spec-env resume: ${r.spec} (${r.bucket}, on ${r.branch})`]
216
+ if (r.identifier) lines.push(` ticket: ${r.identifier}`)
217
+ const { done, total, current } = r.progress
218
+ lines.push(
219
+ ` phases: ${total ? `${done} of ${total} done${current ? `, phase ${current} in progress` : ''}` : 'no phase files'}`,
220
+ )
221
+ for (const b of r.blockers) lines.push(` blocked: ${blockerLine(b)}${r.blocking && b.where === r.blocking.where ? ' ← holds the next build' : ''}`)
222
+ if (!r.ok) {
223
+ lines.push(` refused: ${r.refused}`)
224
+ return lines
225
+ }
226
+ lines.push(` worktree: ${r.worktree.path}${r.worktree.present ? '' : ' (missing — provision below)'}`)
227
+ if (r.commands.length) {
228
+ lines.push('', ' to provision, run:', ...r.commands.map((c) => ` ${c}`))
229
+ lines.push('', ' then, run:', ...r.then.map((c) => ` ${c}`))
230
+ }
231
+ return lines
232
+ }
233
+
234
+ module.exports = { blockers, blockingNext, parseBlockedOn, findTarget, planResume, resumeLines, blockerLine, frontmatterField, sameRef }
package/src/env/review.js CHANGED
@@ -316,7 +316,7 @@ function readerOffMachine(reader) {
316
316
  * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
317
317
  * caller's declaration about the work, not a reading of the gate.
318
318
  */
319
- function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
319
+ function collectReview({ spec, git, mode = 'working', ref, base = null, baseGap = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
320
320
  // WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
321
321
  // reads the spec's worktree, and for those the two are the same path — so
322
322
  // `treePath` left null keeps the existing behaviour exactly. The `docs` mode
@@ -424,6 +424,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
424
424
  // "everything since main, because there was nothing uncommitted" are
425
425
  // different answers to "what am I looking at".
426
426
  fellBack,
427
+ // Set when a gap pin chose `base` (`gapNote`): the page says so beside it,
428
+ // because "since master" reads as a decision nobody made otherwise.
429
+ baseGap: base ? baseGap : null,
427
430
  generatedAt: now,
428
431
  // Is there a phase left for `/spec-next` to build? The page needs it to
429
432
  // know whether offering `Commit & Continue` means anything — and it is read
package/src/env/serve.js CHANGED
@@ -35,6 +35,7 @@ const {
35
35
  allSpecs,
36
36
  resolveSpec,
37
37
  resolveBaseBranch,
38
+ gapNote,
38
39
  isEpic,
39
40
  } = require('./resolve.js')
40
41
  const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
@@ -641,6 +642,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
641
642
  mode,
642
643
  ref,
643
644
  base: baseName,
645
+ baseGap: baseName ? gapNote(config, trimmed) : null,
644
646
  now,
645
647
  notes,
646
648
  gate,
@@ -664,6 +666,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
664
666
  mode: 'branch',
665
667
  ref: mergeBase,
666
668
  base: fallbackBase,
669
+ baseGap: gapNote(config, trimmed),
667
670
  now,
668
671
  notes,
669
672
  gate,
package/src/ideacmd.js CHANGED
@@ -154,7 +154,17 @@ function refuse(out, flags, reason, extra = {}) {
154
154
 
155
155
  async function fileStore(sub, positional, flags, { cwd, now, out }) {
156
156
  const ctx = fileContext(cwd)
157
- if (!ctx.base) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
157
+ if (!ctx.base) {
158
+ // A rolling base in its gap carries the engine's offer
159
+ // (`.claude/rules/offered-unblocks.md`): the refusal, then the way out.
160
+ const offer = ctx.refused && ctx.refused.offer
161
+ if (!offer) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
162
+ write(out, flags, { ok: false, refused: ctx.refused.message, offer }, [
163
+ `idea: ${ctx.refused.message}`,
164
+ ` offer: ${offer.label} — ${offer.command}`,
165
+ ])
166
+ return 1
167
+ }
158
168
  const { tip, text } = readOnBase(ctx)
159
169
 
160
170
  if (sub === 'list') {