@skitterbyte/skitterspec-linear 19.15.0 → 19.17.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 (45) hide show
  1. package/MIGRATION.md +27 -0
  2. package/README.md +2 -1
  3. package/assets/claude-md-section.md +18 -9
  4. package/assets/commands/allow-main.md +1 -2
  5. package/assets/core/env.config.json.example +0 -1
  6. package/assets/core/env.config.md +28 -26
  7. package/assets/hooks/main-guard.cjs +73 -6
  8. package/assets/hooks/project-guard.cjs +80 -6
  9. package/assets/hooks/review-gate.cjs +73 -6
  10. package/assets/review/page.html +10 -83
  11. package/assets/rules/commit-trailers.md +2 -2
  12. package/assets/rules/spec-planning.md +26 -22
  13. package/assets/rules/spec-reports.md +52 -52
  14. package/assets/skills/no-spec/SKILL.md +2 -2
  15. package/assets/skills/spec/SKILL.md +22 -5
  16. package/assets/skills/spec-bug/SKILL.md +18 -15
  17. package/assets/skills/spec-complete/SKILL.md +23 -1
  18. package/assets/skills/spec-diff/SKILL.md +47 -115
  19. package/assets/skills/spec-hotfix/SKILL.md +18 -15
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +66 -41
  22. package/assets/skills/spec-park/SKILL.md +92 -0
  23. package/assets/skills/spec-resume/SKILL.md +153 -0
  24. package/assets/skills/spec-review/SKILL.md +2 -2
  25. package/assets/skills/spec-reviewed/SKILL.md +1 -8
  26. package/assets/skills/spec-status/SKILL.md +1 -1
  27. package/assets/skills/spec-sync/SKILL.md +12 -12
  28. package/assets/skills/spec-todo/SKILL.md +5 -2
  29. package/package.json +1 -1
  30. package/src/cli.js +361 -208
  31. package/src/env/bootstrap.js +3 -1
  32. package/src/env/checks.js +49 -0
  33. package/src/env/config.js +27 -7
  34. package/src/env/hooks.js +53 -4
  35. package/src/env/live.js +48 -0
  36. package/src/env/provision.js +10 -2
  37. package/src/env/resume.js +234 -0
  38. package/src/env/review.js +71 -173
  39. package/src/env/serve.js +3 -7
  40. package/src/init.js +383 -50
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/linear/cli-sync.js +3 -3
  43. package/src/vendor/provider-kit/src/specs.js +46 -1
  44. package/src/vendor/sync-core/src/summary.js +10 -1
  45. package/assets/commands/spec-remote-review.md +0 -37
package/src/tada/todo.js CHANGED
@@ -96,7 +96,7 @@ function lastPrompt(g) {
96
96
  * - `gates` `{ [spec]: gateState(...) }`; a missing or `unknown` state is
97
97
  * cannot-tell, and says nothing
98
98
  */
99
- function blockersFrom({ specs, passes = [], gates = {} }) {
99
+ function blockersFrom({ specs, passes = [], gates = {}, parked = {} }) {
100
100
  const want = new Set(specs)
101
101
  const out = []
102
102
  for (const p of passes) {
@@ -106,6 +106,13 @@ function blockersFrom({ specs, passes = [], gates = {} }) {
106
106
  const g = gates[spec]
107
107
  if (g && g.state === 'armed') out.push({ spec, kind: 'gate', phase: g.gate ? g.gate.phase : null })
108
108
  }
109
+ // A spec parked on something outside the repo (feat-spec-resume): the line
110
+ // that holds its next build, from `spec-env resume`'s `blockingNext`. A wait
111
+ // planned for a later phase holds nothing yet and is not listed.
112
+ for (const spec of specs) {
113
+ const b = parked[spec]
114
+ if (b) out.push({ spec, kind: 'parked', where: b.where, text: b.text, until: b.until })
115
+ }
109
116
  return out
110
117
  }
111
118
 
@@ -118,11 +125,11 @@ function blockersFrom({ specs, passes = [], gates = {} }) {
118
125
  * @param {string[]} specs its in-flight spec names
119
126
  * @param {boolean} [required] `review.required`; false opts the gates out
120
127
  */
121
- function readBlockers(reviews, specs, required) {
122
- if (!fs.existsSync(reviews)) return []
128
+ function readBlockers(reviews, specs, required, parked = {}) {
129
+ if (!fs.existsSync(reviews)) return blockersFrom({ specs, parked })
123
130
  const gates = {}
124
131
  for (const spec of specs) gates[spec] = gateState({ ...readGate(path.join(reviews, `${spec}.html`), spec), required })
125
- return blockersFrom({ specs, passes: waitingPasses(reviews).passes, gates })
132
+ return blockersFrom({ specs, passes: waitingPasses(reviews).passes, gates, parked })
126
133
  }
127
134
 
128
135
  /**
@@ -211,6 +218,14 @@ const ageText = (at, now) => {
211
218
  }
212
219
 
213
220
  function blockedText(b, now) {
221
+ if (b.kind === 'parked') {
222
+ const where = b.where === 'spec' ? '' : ` (phase ${b.where})`
223
+ // Compared as local calendar days: a wait "until" a date has run out once
224
+ // that day has begun, not at UTC midnight.
225
+ const due = b.until && b.until <= localDay(now)
226
+ const until = b.until ? (due ? ` · until ${b.until}, now passed — ready to resume` : ` · until ${b.until}`) : ''
227
+ return `${b.spec} — parked${where}: ${b.text}${until} · /spec-resume ${b.spec}`
228
+ }
214
229
  if (b.kind === 'gate') return `${b.spec} — gate armed${b.phase ? `, phase ${b.phase}` : ''}: a verdict is owed`
215
230
  return `${b.spec} — ${b.verdict || 'a'} verdict waiting (${b.code}${b.at ? ageText(b.at, now) : ''})`
216
231
  }
@@ -144,7 +144,7 @@ const { applySpecPlan, heldFlags, heldOverMcp } = require('../provider-kit/src/a
144
144
  // (`src/specs.js`), keyed by this provider's `config.fields`. `linkedIdentifier`
145
145
  // keeps a config-free arity below for its many local callers.
146
146
  const specHelpers = require('../provider-kit/src/specs.js').makeSpecHelpers({ program: 'spec-sync' })
147
- const { resolveSnapshotDir, specIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr } = specHelpers
147
+ const { resolveSnapshotDir, specIdentifier, listSpecs, listSpecsLive, listSpecsWithBranches, resolveOrExit, warningLines, warnToErr } = specHelpers
148
148
  const { expandStateArgs, specColumn, specCell } = require('../provider-kit/src/list-rows.js')
149
149
 
150
150
  // The stamp key is fixed for this provider, so the config-free arity survives
@@ -160,7 +160,7 @@ const linkedIdentifier = (overviewPath) =>
160
160
  * issue twice, without reading Linear back.
161
161
  */
162
162
  function specSyncLinked(dir, config, flags, out) {
163
- const specs = listSpecs(dir, config)
163
+ const specs = listSpecsWithBranches(dir, config)
164
164
  if (flags.json) {
165
165
  out.write(JSON.stringify(specs, null, 2) + '\n')
166
166
  return
@@ -171,7 +171,7 @@ function specSyncLinked(dir, config, flags, out) {
171
171
  }
172
172
  const lines = ['spec-sync linked:']
173
173
  for (const s of specs) {
174
- lines.push(` ${s.identifier || '—'}\t${s.spec} (${s.bucket})`)
174
+ lines.push(` ${s.identifier || '—'}\t${s.spec} (${s.bucket}${s.source === 'branch' ? `, on ${s.ref}` : ''})`)
175
175
  }
176
176
  const n = specs.filter((s) => s.identifier).length
177
177
  lines.push(` ${n}/${specs.length} linked`)
@@ -21,7 +21,10 @@ const {
21
21
  findSpecFolder,
22
22
  resolveSpec,
23
23
  liveWorktreePaths,
24
+ resolveBaseBranch,
24
25
  } = require('../../../env/resolve.js')
26
+ const { specBranchDocs } = require('../../../env/specbranches.js')
27
+ const { frontmatterField } = require('../../../env/resume.js')
25
28
  const { loadEnvConfig } = require('../../../env/config.js')
26
29
  const { primaryAnchor, attachProject, projectIn } = require('../../../env/project.js')
27
30
  const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored, comparableDescription } = require('../../sync-core')
@@ -180,6 +183,48 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
180
183
  return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
181
184
  }
182
185
 
186
+ // `listSpecs`, plus the specs that exist ONLY on their own branch
187
+ // (`source: 'branch'`, with the `ref` they were read from). Under
188
+ // `land.specDocs: "branch"` an in-flight spec has no copy on base and, on a
189
+ // machine that never provisioned it, no worktree either — so a ticket that
190
+ // already has a spec read as unadopted, and `/spec #N` began a second one.
191
+ // Read off local then remote-tracking spec branches, never fetched.
192
+ //
193
+ // WHAT WOULD FOOL THIS: a remote that was never fetched (its specs are absent
194
+ // — the old answer, never a wrong one), and a spec branch renamed away from
195
+ // `branch.pattern` (not found). Anything unreadable adds nothing.
196
+ function listSpecsWithBranches(dir, config) {
197
+ const live = listSpecs(dir, config)
198
+ const git = (args) => {
199
+ try {
200
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
201
+ } catch {
202
+ return null
203
+ }
204
+ }
205
+ let docs
206
+ try {
207
+ const anchor = primaryAnchor(dir, git)
208
+ const env = loadEnvConfig(anchor.dir || dir)
209
+ if (!env.present) return live
210
+ docs = specBranchDocs(git, env.config, resolveBaseBranch(env.config, git))
211
+ } catch {
212
+ return live
213
+ }
214
+ const field = fieldsOf(config).identifier
215
+ const seen = new Set(live.map((s) => s.spec))
216
+ const extra = docs
217
+ .filter((d) => !seen.has(d.folder))
218
+ .map((d) => ({
219
+ spec: d.folder,
220
+ bucket: d.bucket,
221
+ identifier: frontmatterField(d.overview, field),
222
+ source: 'branch',
223
+ ref: d.ref.replace(/^refs\/(heads|remotes)\//, ''),
224
+ }))
225
+ return [...live, ...extra].sort((a, b) => a.spec.localeCompare(b.spec))
226
+ }
227
+
183
228
  // Resolve a spec argument to its folder, or null with a message on stdout.
184
229
  // EVERY failure path here must print and EVERY caller must return a non-zero
185
230
  // code: a push skill checks $? before it applies a plan, so a resolve failure
@@ -253,7 +298,7 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
253
298
  return lines
254
299
  }
255
300
 
256
- return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
301
+ return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, listSpecsWithBranches, resolveOrExit, warningLines, warnToErr, verifyLines }
257
302
  }
258
303
 
259
304
  module.exports = { makeSpecHelpers }
@@ -188,6 +188,11 @@ function specBlockInner({ snapshotDir, sections, body, phases }) {
188
188
  if (t) parts.push(`**Touches** ${t}`)
189
189
  const gating = headerValue(body, 'Gating')
190
190
  if (gating) parts.push(`**Gating** ${gating}`)
191
+ // A spec parked on something outside the repo (feat-spec-resume). It says
192
+ // why the ticket is not moving, and never sets its Status: the tracker owns
193
+ // status. Absent, nothing is written, so an unparked block is unchanged.
194
+ const blocked = headerValue(body, 'Blocked on')
195
+ if (blocked && blocked !== '—') parts.push(`**Blocked on** ${blocked}`)
191
196
  const progress = progressLine(phases)
192
197
  if (progress) parts.push(progress)
193
198
  parts.push(`**Spec** \`${specPath(snapshotDir)}\``)
@@ -239,7 +244,11 @@ function progressLine(phases) {
239
244
  function phaseBlockInner(phase) {
240
245
  const goal = String((phase && phase.goal) || '').trim() || String((phase && phase.name) || '').trim()
241
246
  const { ticked, total } = taskCounts(phase)
242
- return total ? `${goal}\n\n**Progress** ${ticked} of ${total} tasks` : goal
247
+ const blocked = headerValue(((phase && phase.lines) || []).join('\n'), 'Blocked on')
248
+ const parts = [goal]
249
+ if (blocked && blocked !== '—') parts.push(`**Blocked on** ${blocked}`)
250
+ if (total) parts.push(`**Progress** ${ticked} of ${total} tasks`)
251
+ return parts.join('\n\n')
243
252
  }
244
253
 
245
254
  module.exports = {
@@ -1,37 +0,0 @@
1
- ---
2
- description: Permit or forbid publishing this spec's review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
3
- argument-hint: "[on | off]"
4
- allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
5
- disable-model-invocation: true
6
- ---
7
- !`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
8
-
9
- Relay the engine output above verbatim. Add nothing to it.
10
-
11
- **Then one thing, and only when the engine asked for it.** Where the output
12
- carries a `review:` and a `publish:` line, typing this command **is** the ask
13
- to publish that page: the banner named this command beside a review the reader
14
- could not reach, so the link is what they are waiting for. Publish it exactly
15
- as `/spec-diff` §6 describes (run the `publish:` command, publish the copy it
16
- names with a store, write the URL file), then re-emit the review banner with
17
- all three tiers, `remote` now carrying the URL. A wait already running keeps
18
- running; do not restart it or the server. If the harness refuses the publish,
19
- say so in one line and keep the banner as it was, because local and network
20
- still work.
21
-
22
- With no `publish:` line, run nothing else. Nothing has a page to publish, or
23
- the tier was turned off.
24
-
25
- **Bare toggles.** That is the common case: you are looking at a render whose
26
- `remote:` line says which way it currently is, and what you want is the other
27
- one. `on` and `off` are there for when you are not looking at it.
28
-
29
- **It is per spec.** The engine resolves the spec from the worktree you are
30
- standing in and records the permission in the gitignored review store, so
31
- the base branch is untouched and no other spec may publish because of it.
32
- `skitterspec spec-env review allow remote --project` is the committed,
33
- every-spec form, for a team that wants it.
34
-
35
- **A published page is one skitterspec cannot delete**, and a verdict pressed
36
- on one needs `/spec-reviewed`, because nothing pushes from an artifact's store
37
- into a conversation.