@skitterbyte/skitterspec-linear 18.3.1 → 19.1.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 (36) hide show
  1. package/MIGRATION.md +170 -1
  2. package/README.md +9 -7
  3. package/assets/core/SETUP.md +4 -4
  4. package/assets/core/env.config.md +1 -1
  5. package/assets/core/linear.config.json.example +2 -1
  6. package/assets/core/linear.config.md +59 -48
  7. package/assets/rules/spec-planning.md +35 -12
  8. package/assets/rules/spec-reports.md +47 -6
  9. package/assets/skills/no-spec/SKILL.md +2 -2
  10. package/assets/skills/spec/SKILL.md +32 -9
  11. package/assets/skills/spec-bug/SKILL.md +6 -4
  12. package/assets/skills/spec-hotfix/SKILL.md +4 -2
  13. package/assets/skills/spec-linear-setup/SKILL.md +9 -35
  14. package/assets/skills/spec-list/SKILL.md +13 -1
  15. package/assets/skills/spec-next/SKILL.md +5 -3
  16. package/assets/skills/spec-push/SKILL.md +1 -1
  17. package/assets/skills/spec-status/SKILL.md +30 -26
  18. package/assets/skills/spec-sync/SKILL.md +6 -5
  19. package/package.json +1 -1
  20. package/src/cli.js +114 -28
  21. package/src/env/resolve.js +11 -4
  22. package/src/env/review.js +126 -2
  23. package/src/vendor/linear/api.js +30 -1
  24. package/src/vendor/linear/cli-sync.js +64 -269
  25. package/src/vendor/linear/config.js +30 -49
  26. package/src/vendor/linear/doctor.js +4 -66
  27. package/src/vendor/provider-kit/src/config.js +101 -48
  28. package/src/vendor/provider-kit/src/list-assignee.js +71 -0
  29. package/src/vendor/provider-kit/src/list-rows.js +35 -0
  30. package/src/vendor/provider-kit/src/released.js +27 -77
  31. package/src/vendor/provider-kit/src/specs.js +89 -7
  32. package/src/vendor/sync-core/index.js +3 -4
  33. package/src/vendor/sync-core/src/compare.js +6 -6
  34. package/src/vendor/sync-core/src/normalize.js +60 -59
  35. package/assets/core/ci-stages.md +0 -110
  36. package/src/vendor/provider-kit/src/releases.js +0 -380
@@ -14,7 +14,16 @@
14
14
  const fs = require('node:fs')
15
15
  const path = require('node:path')
16
16
 
17
- const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
17
+ const { execFileSync } = require('node:child_process')
18
+
19
+ const {
20
+ BUCKETS,
21
+ findSpecFolder,
22
+ resolveSpec,
23
+ liveWorktreePaths,
24
+ resolvePrimaryCheckout,
25
+ } = require('../../../env/resolve.js')
26
+ const { loadEnvConfig } = require('../../../env/config.js')
18
27
  const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
19
28
 
20
29
  function makeSpecHelpers({ program = 'spec-sync' } = {}) {
@@ -45,22 +54,32 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
45
54
  // Read a spec's stamped identifier without throwing: an unlinked spec, an
46
55
  // unreadable file and a spec with no frontmatter all read as `null`.
47
56
  function linkedIdentifier(overviewPath, config) {
48
- const field = fieldsOf(config).identifier
57
+ return linkedFields(overviewPath, config).identifier
58
+ }
59
+
60
+ // The stamped identifier AND url, each `null` when absent. The url is only
61
+ // ever what a push stamped — never built from the identifier, because a url
62
+ // constructed here would be a guess about a tracker's address scheme.
63
+ function linkedFields(overviewPath, config) {
64
+ const fields = fieldsOf(config)
49
65
  let raw
50
66
  try {
51
67
  raw = fs.readFileSync(overviewPath, 'utf-8')
52
68
  } catch {
53
- return null
69
+ return { identifier: null, url: null }
54
70
  }
55
71
  const { data } = parseFrontmatter(raw)
56
- return data[field] ? String(data[field]) : null
72
+ return {
73
+ identifier: data[fields.identifier] ? String(data[fields.identifier]) : null,
74
+ url: fields.url && data[fields.url] ? String(data[fields.url]) : null,
75
+ }
57
76
  }
58
77
 
59
78
  // Every spec under specs/<bucket>/, paired with the tracker issue it is
60
79
  // linked to (`null` when it has never been pushed). Folder specs read
61
80
  // `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
62
81
  // itself. Sorted for stable output.
63
- function listSpecs(dir, config) {
82
+ function listSpecs(dir, config, options = {}) {
64
83
  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
65
84
  const specs = []
66
85
  for (const bucket of BUCKETS) {
@@ -83,12 +102,75 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
83
102
  } else {
84
103
  continue
85
104
  }
86
- specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
105
+ const linked = linkedFields(overviewPath, config)
106
+ const row = { spec: name, bucket, identifier: linked.identifier }
107
+ // Opt-in, so every listing that never asked for a url keeps its shape.
108
+ if (options.urls) row.url = linked.url
109
+ specs.push(row)
87
110
  }
88
111
  }
89
112
  return specs.sort((a, b) => a.spec.localeCompare(b.spec))
90
113
  }
91
114
 
115
+ // `listSpecs`, but each spec's BUCKET read from where that spec actually
116
+ // lives. `/spec-start` moves a spec to `in-progress/` on its own branch, so
117
+ // on the base branch an in-flight spec still reads `backlog` — and a spec
118
+ // authored in its own worktree and not yet landed is not here at all. Each
119
+ // live worktree is read too, and a spec found in ITS OWN worktree (the path
120
+ // `resolveSpec` names for it) wins over every other copy. `source` says
121
+ // which: `here`, `worktree`, or `other-tree` for a spec only some other
122
+ // worktree carries.
123
+ //
124
+ // WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is
125
+ // still live, so a finished spec can read from a stale tree. And with no
126
+ // `env.config.json` there is no worktree layout to resolve, so this is
127
+ // exactly `listSpecs` — the current tree's answer, as before.
128
+ function listSpecsLive(dir, config) {
129
+ const here = listSpecs(dir, config).map((s) => ({ ...s, source: 'here' }))
130
+ const git = (args) => {
131
+ try {
132
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
133
+ } catch {
134
+ return null
135
+ }
136
+ }
137
+ let primary
138
+ let env
139
+ try {
140
+ primary = resolvePrimaryCheckout(dir, git) || dir
141
+ env = loadEnvConfig(primary)
142
+ } catch {
143
+ return here
144
+ }
145
+ if (!env.present) return here
146
+ // Compared as REAL paths: git reports a worktree resolved through
147
+ // symlinks (macOS /var → /private/var) where `resolveSpec` does not.
148
+ const real = (p) => {
149
+ try {
150
+ return fs.realpathSync(p)
151
+ } catch {
152
+ return path.resolve(p)
153
+ }
154
+ }
155
+ const self = real(dir)
156
+ const byName = new Map(here.map((s) => [s.spec, s]))
157
+ for (const listed of liveWorktreePaths(git)) {
158
+ const tree = real(listed)
159
+ if (tree === self) continue
160
+ for (const s of listSpecs(tree, config)) {
161
+ let own = null
162
+ try {
163
+ own = real(resolveSpec(s.spec, primary, env.config, { searchDirs: [tree] }).worktreePath)
164
+ } catch {
165
+ own = null
166
+ }
167
+ if (own === tree) byName.set(s.spec, { ...s, source: 'worktree' })
168
+ else if (!byName.has(s.spec)) byName.set(s.spec, { ...s, source: 'other-tree' })
169
+ }
170
+ }
171
+ return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
172
+ }
173
+
92
174
  // Resolve a spec argument to its folder, or null with a message on stdout.
93
175
  // EVERY failure path here must print and EVERY caller must return a non-zero
94
176
  // code: a push skill checks $? before it applies a plan, so a resolve failure
@@ -160,7 +242,7 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
160
242
  return lines
161
243
  }
162
244
 
163
- return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
245
+ return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
164
246
  }
165
247
 
166
248
  module.exports = { makeSpecHelpers }
@@ -13,7 +13,7 @@
13
13
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
14
14
  */
15
15
 
16
- const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
16
+ const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
17
17
  const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
18
18
  const { readBase, writeBase } = require('./src/base.js')
19
19
  const { push, recordPush, projectionOf } = require('./src/push.js')
@@ -41,12 +41,11 @@ module.exports = {
41
41
  push,
42
42
  recordPush,
43
43
  remoteWorkflowState,
44
+ remoteStateReading,
45
+ stateNamesFor,
44
46
  titleFromText,
45
47
  validateStates,
46
48
  stateSuggestions,
47
- stageForState,
48
- remoteStage,
49
- LADDER_ORIGIN_BUCKET,
50
49
  hashField,
51
50
  stableStringify,
52
51
  readBase,
@@ -58,12 +58,12 @@ function specIssueHash(p) {
58
58
 
59
59
  // Per-field hashes of the same two values.
60
60
  //
61
- // They are hashed SEPARATELY because they have different owners once a spec is
62
- // finished. The repo owns the description forever, but the workflow state is
63
- // handed off: a deploy pipeline (see `release.stages`) moves the issue past
64
- // `complete`, and welding the two meant any prose edit re-emitted the state and
65
- // dragged the issue back. Diffing them apart is what lets a push touch the
66
- // description without re-asserting a state someone else now owns.
61
+ // They are hashed SEPARATELY because skitterspec tells the tracker about its
62
+ // own transitions and nothing else. The description is resent whenever it
63
+ // changes; the state only when the spec itself moves. Welding the two meant any
64
+ // prose edit re-emitted the state and dragged back an issue someone had moved
65
+ // on the tracker — which is theirs to do. Diffing them apart is what lets a
66
+ // push touch the description without re-asserting a state.
67
67
  function specIssueFieldHashes(p, config) {
68
68
  const hashes = {
69
69
  description: hashField(p.description ?? null),
@@ -405,15 +405,39 @@ function readSnapshot(snapshotDir, config) {
405
405
  return { frontmatter: data, title, sections, phases, body }
406
406
  }
407
407
 
408
+ // The headings a bug-shaped spec's ticket leads with, in this order, when the
409
+ // spec has them. A Bug ticket is read for its repro before anything else, and
410
+ // the feature overview order buries it. Sections a spec does not have are
411
+ // skipped, never invented — a legacy bug spec with feature-shaped sections
412
+ // renders exactly as it always did.
413
+ const BUG_LEAD_SECTIONS = ['Symptom', 'Repro', 'Expected', 'Actual', 'Root cause', 'Failing test (red)', 'Fix']
414
+
415
+ // A spec's kind off its folder prefix — the same convention the providers'
416
+ // `specKindOf` reads, kept local because sync-core depends on no other package.
417
+ function bugShaped(snapshotDir) {
418
+ const name = path.basename(String(snapshotDir || ''))
419
+ return name.startsWith('bug-') || name.startsWith('hotfix-')
420
+ }
421
+
408
422
  // Build the pushed description: the overview prose with local-only sections
409
423
  // removed. Keeps the title line for context. `extraSkip` drops additional
410
424
  // sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
411
425
  // the phase list isn't duplicated in the description — Decision 5).
412
- function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
426
+ // `leadSections` names headings to emit FIRST, in its order, matched
427
+ // case-insensitively; the rest follow in document order. Empty means document
428
+ // order throughout — byte-identical to before the parameter existed.
429
+ function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect, leadSections = []) {
413
430
  const skip = new Set([...(localOnlySections || []), ...extraSkip])
414
431
  const parts = []
415
432
  if (title) parts.push(`# ${title}`)
416
- for (const [heading, content] of Object.entries(sections)) {
433
+ const entries = Object.entries(sections)
434
+ const lead = []
435
+ for (const want of leadSections) {
436
+ const hit = entries.find(([heading]) => heading.toLowerCase() === want.toLowerCase())
437
+ if (hit) lead.push(hit)
438
+ }
439
+ const ordered = [...lead, ...entries.filter((e) => !lead.includes(e))]
440
+ for (const [heading, content] of ordered) {
417
441
  if (skip.has(heading)) continue
418
442
  parts.push(`## ${heading}\n\n${content}`.trim())
419
443
  }
@@ -706,6 +730,10 @@ function normalizeLocal(snapshotDir, config) {
706
730
  config.sync.localOnlySections,
707
731
  phasesCarriedBySubIssues ? ['Phases'] : [],
708
732
  dialect,
733
+ // A bug or hotfix spec's ticket leads with the bug sections — a
734
+ // different render of the same overview, so the Bug form opens on the
735
+ // repro rather than the feature-shaped prose.
736
+ bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
709
737
  ),
710
738
  inlined,
711
739
  tasksMode,
@@ -751,39 +779,27 @@ function phasesWithheld(snapshotDir, config) {
751
779
 
752
780
  // --- remote projection ------------------------------------------------------
753
781
 
754
- // The lifecycle bucket a deployment ladder descends FROM. A spec is handed over
755
- // to the deploy pipeline once it is finished, so every rung sits downstream of
756
- // `complete` — a ticket on "On Test" is a completed spec that has been deployed,
757
- // not a spec that moved somewhere else.
758
- const LADDER_ORIGIN_BUCKET = 'complete'
759
-
760
- // The declared ladder rung with this state name, or null.
761
- function stageForState(state, config) {
762
- if (state == null) return null
763
- const want = String(state).toLowerCase().trim()
764
- const stages = (config && config.release && config.release.stages) || []
765
- if (!Array.isArray(stages)) return null
766
- return stages.find((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want) || null
782
+ // Every tracker state NAME that means this bucket: the one push writes
783
+ // (`states[bucket]`) first, then its read-only aliases (`stateAliases[bucket]`,
784
+ // from the array form of `states`). Readers use the whole list; writers only
785
+ // ever use `states[bucket]`, so an alias can never be written.
786
+ function stateNamesFor(bucket, config) {
787
+ const primary = config && config.states && config.states[bucket]
788
+ const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
789
+ return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
767
790
  }
768
791
 
769
792
  // Map a remote workflow-state name back to the local lifecycle bucket (the
770
793
  // vocabulary `spec_status` uses) via config.states, so local and remote
771
794
  // workflowState hash equal when semantically equal. Falls back to a lowercased
772
795
  // raw value when the state isn't one of the configured names.
773
- //
774
- // A DECLARED DEPLOYMENT STAGE reads as `complete`, deliberately. Without this
775
- // the fallback lowercases it — "On Test" becomes "on test", which equals no
776
- // bucket — and every deployed spec reports as drifted forever, for the whole
777
- // time it sits in the pipeline. The project told us these states are downstream
778
- // of a finished spec, so they are not a disagreement about where the spec is.
779
796
  function bucketForState(state, config) {
780
797
  if (state == null) return null
781
798
  const states = (config && config.states) || {}
782
799
  const want = String(state).toLowerCase().trim()
783
- for (const [bucket, name] of Object.entries(states)) {
784
- if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
800
+ for (const bucket of Object.keys(states)) {
801
+ if (stateNamesFor(bucket, config).some((name) => name.toLowerCase().trim() === want)) return bucket
785
802
  }
786
- if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
787
803
  return want
788
804
  }
789
805
 
@@ -818,11 +834,20 @@ function remoteWorkflowState(issue, config) {
818
834
  return name != null ? bucketForState(name, config) : null
819
835
  }
820
836
 
821
- // The declared ladder rung a remote issue is currently sitting on, or null.
822
- // Pairs with `remoteWorkflowState`: that says which bucket the issue maps to,
823
- // this says whether it got there by being deployed. Read-only.
824
- function remoteStage(issue, config) {
825
- return stageForState(remoteStateName(issue || {}, config), config)
837
+ // What the drift report needs to know about a remote issue's state: its name,
838
+ // the bucket it maps to, and whether it maps to one at all. Null when the
839
+ // payload carried no state — a cannot-tell, never an answer.
840
+ //
841
+ // AN UNMAPPED STATE IS NOT A DISAGREEMENT. A tracker grows states skitterspec
842
+ // never names ("Blocked", "Next Sprint"), and a ticket a person moved into one
843
+ // is not wrong about the spec — it is somewhere push does not manage, and push
844
+ // will not move it until the spec itself moves. `mapped` is what lets a report
845
+ // say that rather than accuse it.
846
+ function remoteStateReading(issue, config) {
847
+ const name = remoteStateName(issue || {}, config)
848
+ if (name == null) return null
849
+ const bucket = bucketForState(name, config)
850
+ return { name: String(name), bucket, mapped: LIFECYCLE_BUCKETS.includes(bucket) }
826
851
  }
827
852
 
828
853
  // A Linear issue title is plain text, so markdown emphasis is noise there — and
@@ -897,24 +922,16 @@ function titleFromText(text, max = 100) {
897
922
  return stripTitleMarkup(title)
898
923
  }
899
924
 
900
- // Every state NAME the config points at: the lifecycle bucket map, plus the
901
- // project's deployment ladder when it declares one. Both reach Linear the same
902
- // way and fail the same way, so both are checked by the same lookup.
925
+ // Every state NAME the config points at: the lifecycle bucket map.
903
926
  function configuredStateNames(config) {
904
- const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
905
- const stages = (config && config.release && config.release.stages) || []
906
- for (const stage of Array.isArray(stages) ? stages : []) {
907
- if (stage && typeof stage.state === 'string') names.push(stage.state)
908
- }
909
- return names
927
+ // The WRITTEN names only. An alias is never written, so one the workspace
928
+ // lacks cannot strand a push; `stateSuggestions` still names it in reports.
929
+ return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
910
930
  }
911
931
 
912
932
  // Which configured state NAMES are absent from the live workspace. The skill
913
933
  // fetches the workspace's project-status names over MCP and passes them here;
914
934
  // a non-empty result means a typo/rename that Linear would silently no-op.
915
- //
916
- // A project with no `release.stages` contributes nothing here, so the ladder
917
- // cannot make this accuse a config that was fine before it existed.
918
935
  function validateStates(config, workspaceStates) {
919
936
  const configured = configuredStateNames(config)
920
937
  const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
@@ -953,21 +970,6 @@ function stateSuggestions(config, workspaceStates) {
953
970
  const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
954
971
  out.push({ bucket, configured, suggestion, label: `states.${bucket}` })
955
972
  }
956
- // Deployment-ladder rungs, reported the same way. No suggestion is offered:
957
- // BUCKET_WORDS describes lifecycle vocabulary, and a stage name is the
958
- // project's own — guessing "On Test" meant "In Progress" would be worse than
959
- // saying nothing.
960
- const stages = (config && config.release && config.release.stages) || []
961
- for (const stage of Array.isArray(stages) ? stages : []) {
962
- if (!stage || typeof stage.state !== 'string') continue
963
- if (have.has(stage.state.toLowerCase().trim())) continue
964
- out.push({
965
- bucket: null,
966
- configured: stage.state,
967
- suggestion: null,
968
- label: `release.stages[${stage.key}]`,
969
- })
970
- }
971
973
  return out
972
974
  }
973
975
 
@@ -991,8 +993,7 @@ module.exports = {
991
993
  canonicalRemoteStatus,
992
994
  bucketForState,
993
995
  LIFECYCLE_BUCKETS,
994
- stageForState,
995
- remoteStage,
996
996
  remoteWorkflowState,
997
- LADDER_ORIGIN_BUCKET,
997
+ remoteStateReading,
998
+ stateNamesFor,
998
999
  }
@@ -1,110 +0,0 @@
1
- # Wiring a deploy pipeline to Linear
2
-
3
- How a CI/CD pipeline moves a release's tickets along the ladder declared in
4
- `linear.config.json` → `release.stages`. Read `linear.config.md` → "The
5
- deployment ladder" first for the config itself; this page is the pipeline half.
6
-
7
- Nothing here applies until a ladder is declared. Without one, `spec-sync stage`
8
- refuses and every other command behaves as it always has.
9
-
10
- ## The model
11
-
12
- A spec's lifecycle ends at `complete`. Everything after that is a fact about an
13
- **environment**, which no folder under `specs/` can derive — so the repo hands
14
- off. The handoff point is one-way and automatic:
15
-
16
- ```
17
- /spec-complete → states.complete (the repo's last word on state)
18
- CI: spec-sync stage test → release.stages test (the pipeline's, from here on)
19
- CI: spec-sync stage prod → release.stages prod
20
- ```
21
-
22
- Once a spec is complete, pushes stop re-asserting its workflow state, so the
23
- pipeline is the only writer. Editing a finished spec's prose still updates the
24
- mirror's description; it will not drag the ticket back out of the pipeline.
25
-
26
- ## What a stage step runs
27
-
28
- ```sh
29
- skitterspec spec-sync stage <key> <previous-tag>..<this-tag> --apply
30
- ```
31
-
32
- - **Pass the range explicitly.** With no range it defaults to
33
- `git describe --tags --abbrev=0`..HEAD, which is a developer convenience — a
34
- pipeline knows exactly which tag it is deploying, and should say so. The
35
- resolved range is printed on every run either way.
36
- - **Drop `--apply` to dry-run.** Same output, no writes. Worth running in a
37
- pre-deploy job.
38
- - **`--json`** for a machine-readable result: the moves, the skips by category,
39
- and the commit counts.
40
- - **Exit code is 0 unless a write failed**, so a failed move fails the stage.
41
- A range with nothing to move is a success, not a failure.
42
-
43
- The tickets come from `Refs:` trailers on the commits in the range (see the
44
- `commit-trailers` rule). A commit with no trailer is counted and reported, never
45
- guessed at.
46
-
47
- ## Setup
48
-
49
- 1. **A ladder in `linear.config.json`** — via `/spec-linear-setup`, or
50
- `spec-sync init-config --stage test="On Test" --stage prod="Done"`.
51
- 2. **An API key as a pipeline secret**, exposed as the env var named by
52
- `auth.keyEnv` (default `LINEAR_API_KEY`). The config names the *variable*,
53
- never the key. `--apply` needs the API transport and refuses over MCP.
54
- 3. **Full history for the range** (CI: `fetch-depth: 0`). Fetching tags is not
55
- enough on its own: it makes the tag *resolve* without deepening the history,
56
- so `git log <tag>..HEAD` would return only the commits the clone happens to
57
- hold. `stage` and `released` check this and **refuse** rather than report a
58
- partial range, so a shallow checkout fails the step loudly instead of
59
- deploying a release that quietly leaves tickets behind.
60
- 4. **Run `spec-sync doctor --check-remote` once** after setup. It reports the
61
- ladder's rungs against the workspace and warns if the last rung never closes
62
- an issue.
63
-
64
- ### Azure Pipelines
65
-
66
- ```yaml
67
- - task: Bash@3
68
- displayName: Mark tickets as deployed to test
69
- env:
70
- LINEAR_API_KEY: $(LinearApiKey) # a secret variable, not inline
71
- inputs:
72
- targetType: inline
73
- script: |
74
- set -euo pipefail
75
- npx skitterspec spec-sync stage test "$(PreviousTag)..$(Build.SourceBranchName)" --apply
76
- ```
77
-
78
- Repeat per environment with a different `<key>`: a post-deploy step on the test
79
- stage runs `stage test`, the demo approval gate runs `stage demo`, the production
80
- deploy runs `stage prod`.
81
-
82
- ## Why not call the API directly
83
-
84
- A hand-rolled `curl` to Linear's GraphQL endpoint loses three things this command
85
- has, and the loss is silent in all three cases:
86
-
87
- - **State-name validation.** Linear **silently ignores** an unknown workflow
88
- state: the mutation succeeds, and the issue never moves. `stage` resolves the
89
- target state before its first write and refuses if the workspace lacks it.
90
- - **The skip rules.** A range carries refs that must not be moved — another
91
- team's, ones no spec claims, and specs that have not finished. A blanket loop
92
- over every ref in the log moves all of them.
93
- - **Retries and error classification.** The adapter retries transient failures;
94
- a bare `curl` reports a 500 as success if you forget to check.
95
-
96
- ## What it will not move, and why
97
-
98
- Every skipped ref is named in the output with its reason — a silent exclusion and
99
- a successful move look identical in a pipeline log.
100
-
101
- | Skipped | Reason |
102
- |---|---|
103
- | another team's ref | not `linear.teamKey`; writing to an unconfigured team is the worst failure available here |
104
- | no spec claims it | tracker-only work, or a typo in a trailer — nothing here can tell which |
105
- | spec not complete | it landed via `/spec-to-main`; push still owns its state and would bounce it back |
106
- | unreadable | Linear did not return the issue; dropped rather than guessed at |
107
-
108
- A move that runs against the declared order — backwards, or skipping a rung —
109
- **warns and proceeds**. A rollback from test and a hotfix going straight to prod
110
- are both legitimate, and refusing either would be wrong on healthy input.