@skitterbyte/skitterspec-linear 18.0.0 → 18.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 (51) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +33 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/no-spec/SKILL.md +3 -2
  7. package/assets/skills/spec-complete/SKILL.md +67 -25
  8. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  9. package/assets/skills/spec-sync/SKILL.md +10 -1
  10. package/package.json +1 -1
  11. package/src/cli.js +295 -37
  12. package/src/env/config.js +14 -2
  13. package/src/env/hotfix.js +261 -15
  14. package/src/env/hotfixland.js +302 -0
  15. package/src/env/resolve.js +22 -8
  16. package/src/init.js +36 -4
  17. package/src/vendor/linear/api.js +43 -56
  18. package/src/vendor/linear/cli-sanitise.js +2 -2
  19. package/src/vendor/linear/cli-sync.js +87 -390
  20. package/src/vendor/linear/config.js +46 -171
  21. package/src/vendor/linear/credentials.js +40 -370
  22. package/src/vendor/linear/dialect.js +177 -0
  23. package/src/vendor/linear/doctor.js +7 -15
  24. package/src/vendor/linear/identity.js +20 -70
  25. package/src/vendor/linear/released.js +4 -222
  26. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  27. package/src/vendor/provider-kit/index.js +41 -0
  28. package/src/vendor/provider-kit/src/adapter.js +23 -0
  29. package/src/vendor/provider-kit/src/apply.js +197 -0
  30. package/src/vendor/provider-kit/src/args.js +68 -0
  31. package/src/vendor/provider-kit/src/config.js +198 -0
  32. package/src/vendor/provider-kit/src/credentials.js +404 -0
  33. package/src/vendor/provider-kit/src/doctor.js +35 -0
  34. package/src/vendor/provider-kit/src/http.js +44 -0
  35. package/src/vendor/provider-kit/src/identity.js +93 -0
  36. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  37. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  38. package/src/vendor/provider-kit/src/prompt.js +50 -0
  39. package/src/vendor/provider-kit/src/released.js +226 -0
  40. package/src/vendor/provider-kit/src/specs.js +166 -0
  41. package/src/vendor/provider-kit/src/transport.js +22 -0
  42. package/src/vendor/sync-core/index.js +22 -5
  43. package/src/vendor/sync-core/src/compare.js +14 -12
  44. package/src/vendor/sync-core/src/dialect.js +51 -0
  45. package/src/vendor/sync-core/src/fields.js +36 -0
  46. package/src/vendor/sync-core/src/legacy.js +19 -9
  47. package/src/vendor/sync-core/src/normalize.js +30 -158
  48. package/src/vendor/sync-core/src/push.js +1 -1
  49. package/src/vendor/sync-core/src/retarget.js +21 -17
  50. package/src/vendor/sync-core/src/verify.js +24 -45
  51. package/src/vendor/sync-core/src/write.js +7 -5
@@ -0,0 +1,166 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Spec resolution and listing for a provider CLI — how a spec argument becomes
5
+ * a snapshot directory, how a spec names its snapshot sidecar, and which specs
6
+ * a repo holds with which tracker links.
7
+ *
8
+ * The frontmatter key that links a spec is the provider's
9
+ * (`config.fields.identifier` — sync-core `src/fields.js`); everything else
10
+ * here is filesystem shape shared by every provider. `program` prefixes the
11
+ * user-facing refusals (`spec-sync: spec not found: …`).
12
+ */
13
+
14
+ const fs = require('node:fs')
15
+ const path = require('node:path')
16
+
17
+ const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
18
+ const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
19
+
20
+ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
21
+ // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder
22
+ // found under specs/** (preferred) or a literal path to a snapshot directory.
23
+ function resolveSnapshotDir(specArg, dir) {
24
+ const found = findSpecFolder(specArg, dir)
25
+ if (found) return found.path
26
+ const literal = path.resolve(dir, specArg)
27
+ if (fs.existsSync(literal) && fs.statSync(literal).isDirectory()) return literal
28
+ return null
29
+ }
30
+
31
+ // The identifier keying the snapshot sidecar: the spec's stamped identifier
32
+ // if set, else its folder name (so the engine is usable before a spec is
33
+ // linked).
34
+ function specIdentifier(snapshotDir, config) {
35
+ const field = fieldsOf(config).identifier
36
+ try {
37
+ const { frontmatter } = readSnapshot(snapshotDir, config)
38
+ if (frontmatter[field]) return String(frontmatter[field])
39
+ } catch {
40
+ /* fall through to folder name */
41
+ }
42
+ return path.basename(snapshotDir)
43
+ }
44
+
45
+ // Read a spec's stamped identifier without throwing: an unlinked spec, an
46
+ // unreadable file and a spec with no frontmatter all read as `null`.
47
+ function linkedIdentifier(overviewPath, config) {
48
+ const field = fieldsOf(config).identifier
49
+ let raw
50
+ try {
51
+ raw = fs.readFileSync(overviewPath, 'utf-8')
52
+ } catch {
53
+ return null
54
+ }
55
+ const { data } = parseFrontmatter(raw)
56
+ return data[field] ? String(data[field]) : null
57
+ }
58
+
59
+ // Every spec under specs/<bucket>/, paired with the tracker issue it is
60
+ // linked to (`null` when it has never been pushed). Folder specs read
61
+ // `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
62
+ // itself. Sorted for stable output.
63
+ function listSpecs(dir, config) {
64
+ const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
65
+ const specs = []
66
+ for (const bucket of BUCKETS) {
67
+ const root = path.join(dir, 'specs', bucket)
68
+ let entries
69
+ try {
70
+ entries = fs.readdirSync(root, { withFileTypes: true })
71
+ } catch {
72
+ continue
73
+ }
74
+ for (const entry of entries) {
75
+ let name
76
+ let overviewPath
77
+ if (entry.isDirectory()) {
78
+ name = entry.name
79
+ overviewPath = path.join(root, name, overviewFile)
80
+ } else if (entry.isFile() && entry.name.endsWith('.md')) {
81
+ name = entry.name.slice(0, -3)
82
+ overviewPath = path.join(root, entry.name)
83
+ } else {
84
+ continue
85
+ }
86
+ specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
87
+ }
88
+ }
89
+ return specs.sort((a, b) => a.spec.localeCompare(b.spec))
90
+ }
91
+
92
+ // Resolve a spec argument to its folder, or null with a message on stdout.
93
+ // EVERY failure path here must print and EVERY caller must return a non-zero
94
+ // code: a push skill checks $? before it applies a plan, so a resolve failure
95
+ // that exits 0 reads as "nothing to do" rather than "I could not find the
96
+ // spec".
97
+ function resolveOrExit(specArg, dir, out) {
98
+ if (!specArg) {
99
+ out.write(`${program}: no spec given\n`)
100
+ return null
101
+ }
102
+ const snapshotDir = resolveSnapshotDir(specArg, dir)
103
+ if (!snapshotDir) {
104
+ out.write(`${program}: spec not found: ${specArg}\n`)
105
+ return null
106
+ }
107
+ return snapshotDir
108
+ }
109
+
110
+ // Phase-status warnings for a spec, one formatted line each. A spec states
111
+ // each phase's status three times and only the h1 emoji is read — get it
112
+ // wrong and the phase projects as `backlog`, pushes cleanly, and is recorded
113
+ // as intended: invisible. Reported by every subcommand that reads a
114
+ // projection, fatal in none — a legacy spec must still push.
115
+ function warningLines(snapshotDir, config) {
116
+ return lintPhases(snapshotDir, config).map((w) => ` warning ${w.file}: ${w.message}`)
117
+ }
118
+
119
+ // Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
120
+ function warnToErr(snapshotDir, config, err) {
121
+ const lines = warningLines(snapshotDir, config)
122
+ if (lines.length) err.write(lines.join('\n') + '\n')
123
+ }
124
+
125
+ // Render the read-back comparison — the same check `verify` and `apply`
126
+ // both report through, so the two cannot disagree about what "intact" means.
127
+ function verifyLines(snapshotDir, config, stored, identifier) {
128
+ const projection = projectionOf(snapshotDir, config)
129
+ const checks = []
130
+ if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
131
+ for (const [ref, text] of Object.entries(stored.subIssues || {})) {
132
+ const sub = projection.subIssues.find((s) => s.ref === ref)
133
+ if (!sub) {
134
+ checks.push([`sub-issue ${ref}`, null, text])
135
+ continue
136
+ }
137
+ checks.push([`sub-issue ${ref}`, sub.goal, text])
138
+ }
139
+
140
+ const lines = [`${program} verify: ${identifier}`]
141
+ let bad = 0
142
+ for (const [label, sent, got] of checks) {
143
+ if (sent == null) {
144
+ lines.push(` ?? ${label}: read back, but the projection has no such phase — stale ref?`)
145
+ bad++
146
+ continue
147
+ }
148
+ const r = compareStored(sent, got, config)
149
+ if (r.ok) continue
150
+ bad++
151
+ lines.push(
152
+ ` !! ${label}: the tracker stored different text — ${Math.abs(r.lost)} character(s) ` +
153
+ `${r.lost > 0 ? 'lost' : 'added'}, first difference at ${r.at}`,
154
+ ` sent: …${r.sentContext}…`,
155
+ ` stored: …${r.storedContext}…`,
156
+ )
157
+ }
158
+ if (!bad) lines.push(` ${checks.length} description(s) round-tripped intact`)
159
+ else lines.push(' the repo is unchanged and still correct; re-push to overwrite the mirror')
160
+ return lines
161
+ }
162
+
163
+ return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
164
+ }
165
+
166
+ module.exports = { makeSpecHelpers }
@@ -0,0 +1,22 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Which transport a command runs over: `--via` wins, else the config's
5
+ * declared default, else "api when a credential resolved, mcp when it didn't".
6
+ *
7
+ * This expression was repeated verbatim nine times in the first provider —
8
+ * hoisted so the precedence is decided once. Per-command DEGRADATION stays with
9
+ * the command: which operations are impossible over mcp (exit 1, say so) and
10
+ * which hand the skill instructions (exit 0) is a per-command judgment, not a
11
+ * transport fact.
12
+ */
13
+
14
+ function resolveTransport(flags, config, credentialOk) {
15
+ return (
16
+ (flags && flags.via) ||
17
+ (config && config.apply && config.apply.transport) ||
18
+ (credentialOk ? 'api' : 'mcp')
19
+ )
20
+ }
21
+
22
+ module.exports = { resolveTransport }
@@ -13,15 +13,16 @@
13
13
  * stored matches what was sent — it merges nothing (see `src/verify.js`).
14
14
  */
15
15
 
16
- const { ownsField, normalizeLocal, 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, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
17
17
  const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited } = require('./src/compare.js')
18
18
  const { readBase, writeBase } = require('./src/base.js')
19
19
  const { push, recordPush, projectionOf } = require('./src/push.js')
20
20
  const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
21
- const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
22
21
  const { detectLegacyMirror } = require('./src/legacy.js')
23
22
  const { compareStored, stream } = require('./src/verify.js')
24
- const { flattenNestedTables } = require('./src/tables.js')
23
+ const { identityDialect, dialectOf } = require('./src/dialect.js')
24
+ const { fieldsOf } = require('./src/fields.js')
25
+ const { renderTaskBlock, findTaskBlocks, wrapEmphasisAware, collapseHyphenAware, inferWidth, fenceMask, DEFAULT_WIDTH } = require('./src/task-block.js')
25
26
  const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
26
27
 
27
28
  module.exports = {
@@ -56,7 +57,6 @@ module.exports = {
56
57
  stampIssueId,
57
58
  findPhaseFileByTitle,
58
59
  listPhaseFiles,
59
- sanitizeSpecMarkdown,
60
60
  detectLegacyMirror,
61
61
  compareStored,
62
62
  // The tolerant reduction behind both `compareStored` and the snapshot's
@@ -66,7 +66,24 @@ module.exports = {
66
66
  // Did someone else edit the tracker's description since the last push?
67
67
  // Three-valued; `null` is cannot-tell and must never be reported as drift.
68
68
  remoteDescriptionEdited,
69
- flattenNestedTables,
69
+ // Provider seams: the frontmatter field vocabulary and the markdown dialect
70
+ // a provider's config supplies (`config.fields` / `config.dialect`).
71
+ fieldsOf,
72
+ identityDialect,
73
+ dialectOf,
74
+ // The lifecycle buckets, exported once so providers and tests stop growing
75
+ // private copies (the tracker-free common package keeps its own — it cannot
76
+ // depend on this package).
77
+ LIFECYCLE_BUCKETS,
78
+ // Task-block helpers a provider's own text tooling builds on (the Linear
79
+ // sanitiser reflows emphasis-aware with these).
80
+ renderTaskBlock,
81
+ findTaskBlocks,
82
+ wrapEmphasisAware,
83
+ collapseHyphenAware,
84
+ inferWidth,
85
+ fenceMask,
86
+ DEFAULT_WIDTH,
70
87
  planRetarget,
71
88
  applyRetarget,
72
89
  deriveRecordedKey,
@@ -1,7 +1,7 @@
1
1
  'use strict'
2
2
 
3
3
  /**
4
- * One-sided change detection for one-way sync (repo → Linear).
4
+ * One-sided change detection for one-way sync (repo → tracker).
5
5
  *
6
6
  * The repo is the source of truth; Linear is a generated mirror. We never read
7
7
  * remote content. Instead we record a **last-pushed snapshot** — a content hash
@@ -19,9 +19,10 @@
19
19
  */
20
20
 
21
21
  const { createHash } = require('node:crypto')
22
- // The tolerant reduction `verify.js` already uses to tell Linear's own
22
+ // The tolerant reduction `verify.js` already uses to tell the tracker's own
23
23
  // reserialisation apart from a real edit. Imported rather than reimplemented:
24
24
  // two reductions that disagree would be two different answers to one question.
25
+ // Dialect-parameterised: the provider's `config.dialect` names the transforms.
25
26
  const { stream } = require('./verify.js')
26
27
 
27
28
  // Deterministic JSON: object keys sorted recursively; array order preserved.
@@ -63,7 +64,7 @@ function specIssueHash(p) {
63
64
  // `complete`, and welding the two meant any prose edit re-emitted the state and
64
65
  // dragged the issue back. Diffing them apart is what lets a push touch the
65
66
  // description without re-asserting a state someone else now owns.
66
- function specIssueFieldHashes(p) {
67
+ function specIssueFieldHashes(p, config) {
67
68
  const hashes = {
68
69
  description: hashField(p.description ?? null),
69
70
  state: hashField(p.status ?? null),
@@ -79,7 +80,7 @@ function specIssueFieldHashes(p) {
79
80
  // `description` above decides what to PUSH: it is exact, because any
80
81
  // difference between the repo and what the repo last sent is a difference the
81
82
  // repo should send again. This one decides whether SOMEBODY ELSE has been
82
- // here, and for that exactness is precisely wrong — Linear reserialises
83
+ // here, and for that exactness is precisely wrong — the tracker reserialises
83
84
  // markdown on save (bullets rewritten, ordered lists renumbered, table
84
85
  // separators collapsed), so comparing the exact hash against a read-back would
85
86
  // report a human edit on every intact mirror in the workspace.
@@ -94,7 +95,7 @@ function specIssueFieldHashes(p) {
94
95
  // It is recorded and never planned on. `issueChanges` reads `description`,
95
96
  // `state` and `assignee` by name and never iterates this object, so adding a
96
97
  // key here cannot make a push pending — there is a test for exactly that.
97
- hashes.descriptionStream = hashField(stream(p.description ?? ''))
98
+ hashes.descriptionStream = hashField(stream(p.description ?? '', config))
98
99
  return hashes
99
100
  }
100
101
 
@@ -122,18 +123,19 @@ function specIssueFieldHashes(p) {
122
123
  * @param {object|null} remote what the tracker currently holds for the issue
123
124
  * @returns {boolean|null}
124
125
  */
125
- function remoteDescriptionEdited(snapshot, remote) {
126
+ function remoteDescriptionEdited(snapshot, remote, config) {
126
127
  const fields = snapshot && snapshot.issueFields
127
128
  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return null
128
129
  const recorded = fields.descriptionStream
129
130
  if (typeof recorded !== 'string' || !recorded) return null
130
131
 
131
132
  if (!remote || typeof remote !== 'object') return null
132
- if (!('description' in remote)) return null
133
- const text = remote.description
133
+ // A provider whose remote shape differs supplies `config.remote.description`.
134
+ const hook = config && config.remote && config.remote.description
135
+ const text = typeof hook === 'function' ? hook(remote) : 'description' in remote ? remote.description : undefined
134
136
  if (typeof text !== 'string') return null
135
137
 
136
- return hashField(stream(text)) !== recorded
138
+ return hashField(stream(text, config)) !== recorded
137
139
  }
138
140
  // A phase SUB-ISSUE: its name, goal and state (all repo-owned).
139
141
  const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? null, state: s.state ?? null })
@@ -144,7 +146,7 @@ const subIssueHash = (s) => hashField({ name: s.name ?? null, goal: s.goal ?? nu
144
146
  * aren't recorded until the skill stamps their returned id and the next
145
147
  * projection includes it.
146
148
  */
147
- function snapshotOf(projection) {
149
+ function snapshotOf(projection, config) {
148
150
  const p = projection || {}
149
151
  const byId = (arr, hash) => {
150
152
  const out = {}
@@ -156,7 +158,7 @@ function snapshotOf(projection) {
156
158
  // `issue` keeps a snapshot readable by anything still expecting the combined
157
159
  // hash. Cheap insurance — two SHA-1s of text already in hand.
158
160
  issue: specIssueHash(p),
159
- issueFields: specIssueFieldHashes(p),
161
+ issueFields: specIssueFieldHashes(p, config),
160
162
  subIssues: byId(p.subIssues, subIssueHash),
161
163
  }
162
164
  }
@@ -170,7 +172,7 @@ function snapshotOf(projection) {
170
172
  * — the `ref` because the read-back check matches sub-issues to phases BY ref,
171
173
  * and an update with only an id makes every one of them look unmatched.
172
174
  * `plan.issue` (when present) is the spec issue's description + state; the push
173
- * skill applies `config.linear.projectId` grouping on top of it.
175
+ * skill applies its provider's project/grouping choice on top of it.
174
176
  */
175
177
  function planChanges(projection, snapshot) {
176
178
  const p = projection || {}
@@ -0,0 +1,51 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The tracker's markdown DIALECT — how a provider shapes outbound text and
5
+ * reduces read-backs for comparison. The engine is provider-neutral, but every
6
+ * tracker reserialises text its own way (one rewrites bullets and mangles
7
+ * emphasis, another stores a different format entirely), so the transforms live
8
+ * with the provider and arrive here on `config.dialect`.
9
+ *
10
+ * Three hooks, each `string → string` and pure:
11
+ *
12
+ * - `canonicalize(text)` — canonicalise a projected description so
13
+ * semantically-equal content hashes equal
14
+ * across the boundary.
15
+ * - `flattenTables(text)` — rewrite constructs the tracker's renderer is
16
+ * known to corrupt (applied to every projected
17
+ * body).
18
+ * - `canonicalForCompare(text)`— reduce a read-back so the tracker's own
19
+ * benign reserialisation does not read as data
20
+ * loss (see `verify.js`).
21
+ *
22
+ * The identity dialect is the default: no provider transforms, plus the one
23
+ * reduction that is universal (line endings, trailing whitespace, blank-run
24
+ * collapse) so `canonicalForCompare` is never a bare string equality.
25
+ */
26
+
27
+ function baseCanonicalForCompare(text) {
28
+ return String(text == null ? '' : text)
29
+ .replace(/\r\n/g, '\n')
30
+ .split('\n')
31
+ .map((line) => line.replace(/[ \t]+$/, ''))
32
+ .join('\n')
33
+ .replace(/\n{3,}/g, '\n\n')
34
+ .trim()
35
+ }
36
+
37
+ const identityDialect = Object.freeze({
38
+ canonicalize: (text) => text,
39
+ flattenTables: (text) => text,
40
+ canonicalForCompare: baseCanonicalForCompare,
41
+ })
42
+
43
+ // The dialect in play for a config: the provider's hooks over the identity
44
+ // defaults, so a provider may supply any subset.
45
+ function dialectOf(config) {
46
+ const d = config && config.dialect
47
+ if (!d || typeof d !== 'object') return identityDialect
48
+ return { ...identityDialect, ...d }
49
+ }
50
+
51
+ module.exports = { identityDialect, dialectOf, baseCanonicalForCompare }
@@ -0,0 +1,36 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The frontmatter FIELD VOCABULARY — which keys a provider stamps into spec
5
+ * files. The engine reads and writes stamps by these names and hardcodes none
6
+ * of them: each provider's config loader supplies its own set (the Linear
7
+ * provider defaults to `linear_identifier` / `linear_issue_id` / …), so a
8
+ * second provider stamps its own keys without touching the engine.
9
+ *
10
+ * Required keys: `identifier`, `url`, `issueId`, `assigneeId`.
11
+ * Optional: `assigneeName`, and `legacyIdentifier` / `legacyIssueId` — the keys
12
+ * a pre-9.0 mirror stamped. A provider with no legacy era simply omits them,
13
+ * and legacy detection then reports nothing (`legacy.js`).
14
+ *
15
+ * A missing `config.fields` THROWS rather than defaulting: a silent default
16
+ * would let the engine read stamps under names the provider never wrote, and
17
+ * the failure that produces is an all-creates plan that duplicates a live
18
+ * mirror — far worse than a loud error at the first call.
19
+ */
20
+
21
+ function fieldsOf(config) {
22
+ const f = config && config.fields
23
+ if (!f || typeof f !== 'object' || Array.isArray(f)) {
24
+ throw new Error(
25
+ 'config.fields missing — the provider config must name its frontmatter fields (identifier, url, issueId, assigneeId)',
26
+ )
27
+ }
28
+ for (const key of ['identifier', 'url', 'issueId', 'assigneeId']) {
29
+ if (typeof f[key] !== 'string' || !f[key]) {
30
+ throw new Error(`config.fields.${key} missing — the provider config must name this frontmatter field`)
31
+ }
32
+ }
33
+ return f
34
+ }
35
+
36
+ module.exports = { fieldsOf }
@@ -5,8 +5,9 @@
5
5
  *
6
6
  * v9 remapped the mirror: a spec is an issue (was a Project), a phase is a
7
7
  * sub-issue (was a Milestone), and tasks are no longer objects at all. The
8
- * frontmatter keys moved with it — `linear_project_id` → `linear_identifier`,
9
- * `linear_milestone_id` → `linear_issue_id`.
8
+ * frontmatter keys moved with it (in the Linear provider's vocabulary,
9
+ * `linear_project_id` -> `linear_identifier`, `linear_milestone_id` ->
10
+ * `linear_issue_id` — see `config.fields`).
10
11
  *
11
12
  * The failure this guards is silent and destructive: v9 looks for the new keys,
12
13
  * finds nothing, and produces a perfectly ordinary **all-creates** plan. Applying
@@ -27,9 +28,10 @@ const { parseFrontmatter } = require('./normalize.js')
27
28
  const { readBase } = require('./base.js')
28
29
  const { listPhaseFiles } = require('./write.js')
29
30
 
30
- // Frontmatter keys only the pre-9.0 model ever wrote.
31
- const LEGACY_OVERVIEW_KEY = 'linear_project_id'
32
- const LEGACY_PHASE_KEY = 'linear_milestone_id'
31
+ // The pre-9.0 keys come from the provider's field vocabulary
32
+ // (`config.fields.legacyIdentifier` / `.legacyIssueId`). A provider with no
33
+ // pre-9.0 era omits them, and detection then reports nothing: there is no old
34
+ // model its repos could be stranded on, so an absence is not evidence.
33
35
 
34
36
  function frontmatterOf(file) {
35
37
  try {
@@ -56,19 +58,27 @@ function countOrphans(snapshot) {
56
58
  * @returns {null|{keys:string[], files:string[], orphans:object|null, orphanCount:number}}
57
59
  */
58
60
  function detectLegacyMirror({ dir, snapshotDir, identifier, config }) {
61
+ const fields = (config && config.fields) || {}
62
+ const legacyOverviewKey = fields.legacyIdentifier
63
+ const legacyPhaseKey = fields.legacyIssueId
64
+ // No legacy vocabulary declared -> this provider has no pre-9.0 era, so there
65
+ // is no old model its repos could be stranded on, and an absence of the keys
66
+ // proves nothing (`.claude/rules/negative-checks.md`).
67
+ if (!legacyOverviewKey && !legacyPhaseKey) return null
68
+
59
69
  const keys = []
60
70
  const files = []
61
71
 
62
72
  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
63
73
  const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
64
- if (overview[LEGACY_OVERVIEW_KEY] != null) {
65
- keys.push(LEGACY_OVERVIEW_KEY)
74
+ if (legacyOverviewKey && overview[legacyOverviewKey] != null) {
75
+ keys.push(legacyOverviewKey)
66
76
  files.push(overviewFile)
67
77
  }
68
78
 
69
79
  for (const file of listPhaseFiles(snapshotDir)) {
70
- if (frontmatterOf(path.join(snapshotDir, file))[LEGACY_PHASE_KEY] != null) {
71
- if (!keys.includes(LEGACY_PHASE_KEY)) keys.push(LEGACY_PHASE_KEY)
80
+ if (legacyPhaseKey && frontmatterOf(path.join(snapshotDir, file))[legacyPhaseKey] != null) {
81
+ if (!keys.includes(legacyPhaseKey)) keys.push(legacyPhaseKey)
72
82
  files.push(file)
73
83
  }
74
84
  }