@skitterbyte/skitterspec 0.1.0 → 1.0.0

package/src/init.js

@@ -25,6 +25,11 @@ const SKILLS = [
   'spec-complete',
   'spec-cancel',
   'spec-init',
+  'spec-env',
+  'spec-env-down',
+  'spec-status',
+  'spec-pull',
+  'spec-push',
   'commit',
 ]
 
@@ -32,25 +37,26 @@ const RULES = ['spec-planning.md', 'commit-messages.md']
 
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
 
-const BACKLOG_INDEX = `<!-- Maintained by the spec skills — do not hand-edit. -->
-<!-- Live view of the backlog. /spec prepends a row; /spec-ready updates status; -->
-<!-- /spec-go and /spec-cancel remove the row when the spec leaves the backlog. -->
-
-| Added | Spec | Type | Status |
-|-------|------|------|--------|
-`
-
-const COMPLETE_INDEX = `<!-- Maintained by the spec skills — do not hand-edit. -->
-<!-- Append-only completion log, newest first. /spec-complete prepends a row. -->
-
-| Completed | Spec | Type |
-|-----------|------|------|
-`
+// Opt-in per-spec isolation config, scaffolded into specs/.core/ as templates
+// the consumer copies (env.config.json.example → env.config.json to adopt).
+const CORE_FILES = [
+  path.join('core', 'env.config.json.example'),
+  path.join('core', 'env.config.md'),
+  path.join('core', 'linear.config.json.example'),
+  path.join('core', 'linear.config.md'),
+]
 
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], removed: [], warnings: [] }
+
+// Folder index files scaffolded by earlier versions, now retired. `init`/`update`
+// deletes any left behind so upgrading projects don't keep stale caches.
+const RETIRED_FILES = [
+  path.join('specs', 'backlog', '00-index.md'),
+  path.join('specs', 'complete', '00-index.md'),
+]
 
 function rel(dir, p) {
   return path.relative(dir, p) || '.'
@@ -107,17 +113,14 @@ function installRule(dir, opts) {
   }
 }
 
-// backlog + complete are kept in git by their 00-index.md file, so they need no .gitkeep
-const FOLDERS_WITH_INDEX = new Set(['backlog', 'complete'])
-
 function installFolders(dir) {
   for (const folder of SPEC_FOLDERS) {
     const abs = path.join(dir, 'specs', folder)
     if (!fs.existsSync(abs)) {
       ensureDir(abs)
       report.created.push(rel(dir, abs) + '/')
-      // keep otherwise-empty folders in git (those without an 00-index.md)
-      if (!FOLDERS_WITH_INDEX.has(folder) && !fs.readdirSync(abs).length) {
+      // keep otherwise-empty folders in git
+      if (!fs.readdirSync(abs).length) {
         fs.writeFileSync(path.join(abs, '.gitkeep'), '')
       }
     } else {
@@ -126,9 +129,48 @@ function installFolders(dir) {
   }
 }
 
-function installIndexes(dir, opts) {
-  writeFile(dir, path.join(dir, 'specs', 'backlog', '00-index.md'), BACKLOG_INDEX, opts)
-  writeFile(dir, path.join(dir, 'specs', 'complete', '00-index.md'), COMPLETE_INDEX, opts)
+// Delete retired folder index files left by earlier versions. If removing one
+// empties its bucket, drop a `.gitkeep` so the folder stays tracked in git.
+function removeRetiredFiles(dir) {
+  for (const relPath of RETIRED_FILES) {
+    const target = path.join(dir, relPath)
+    if (!fs.existsSync(target)) continue
+    fs.unlinkSync(target)
+    report.removed.push(rel(dir, target))
+    const folder = path.dirname(target)
+    if (fs.existsSync(folder) && !fs.readdirSync(folder).length) {
+      fs.writeFileSync(path.join(folder, '.gitkeep'), '')
+    }
+  }
+}
+
+// Scaffold the opt-in isolation templates into specs/.core/ (the example config
+// + its field docs). Copied, not activated: the feature stays off until the
+// consumer copies env.config.json.example → env.config.json.
+function installCore(dir, opts) {
+  for (const asset of CORE_FILES) {
+    copyAsset(
+      dir,
+      asset,
+      path.join(dir, 'specs', '.core', path.basename(asset)),
+      opts,
+    )
+  }
+}
+
+// Activate opt-in per-spec isolation: write specs/.core/env.config.json from the
+// example asset so /spec-go provisions a worktree for every in-progress spec.
+// Only called when the operator opts in, and never on `update` (adopting isolation
+// is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
+// never clobbers an existing env.config.json without --force.
+function installIsolation(dir, { enabled }, opts) {
+  if (!enabled) return
+  copyAsset(
+    dir,
+    path.join('core', 'env.config.json.example'),
+    path.join(dir, 'specs', '.core', 'env.config.json'),
+    opts,
+  )
 }
 
 function installClaudeMd(dir, { mode }) {
@@ -303,30 +345,43 @@ function printReport(dir, mode) {
   process.stdout.write(`\nskitterspec ${mode} → ${dir}\n`)
   line('created', report.created)
   line('updated', report.updated)
+  line('removed', report.removed)
   line('unchanged', report.skipped)
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
   }
+  const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
+  const isolationNote = isolationOn
+    ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +
+      ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
+    : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
+      ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   process.stdout.write(
     '\nDone. Skills resolve as /spec, /spec-ready, /spec-go, /spec-complete,' +
-      ' /spec-cancel, /spec-bug, /spec-init, /commit.\n' +
+      ' /spec-cancel, /spec-bug, /spec-init, /spec-env, /spec-env-down,' +
+      ' /spec-status, /spec-pull, /spec-push, /commit.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
-      " project's stack, then run /spec.\n",
+      " project's stack, then run /spec.\n" +
+      isolationNote,
   )
 }
 
-async function init({ dir, force, claudeMd, mode, release }) {
+async function init({ dir, force, claudeMd, mode, release, isolation }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   report.created.length = 0
   report.updated.length = 0
   report.skipped.length = 0
+  report.removed.length = 0
   report.warnings.length = 0
 
   installSkills(dir, { force })
   installRule(dir, { force })
   installFolders(dir)
-  installIndexes(dir, { force })
+  removeRetiredFiles(dir)
+  installCore(dir, { force })
+  // Adopting isolation writes the live env.config.json — init only, never update.
+  if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
   // Release tooling. The CLI resolves `release` from flags/prompts; when called

package/src/prompts.js

@@ -7,10 +7,11 @@
  * test suite never imports the interactive UI.
  *
  * `seed` is the resolved release config (existing file merged with any flags),
- * used to pre-fill every answer. Returns a release config of the same shape.
+ * used to pre-fill every answer. `isolationSeed` pre-fills the per-spec isolation
+ * question. Returns `{ release, isolation }`.
  */
 
-async function promptSetup({ seed, pkgExists }) {
+async function promptSetup({ seed, pkgExists, isolationSeed = false }) {
   const prompts = require('prompts')
 
   let cancelled = false
@@ -61,21 +62,31 @@ async function promptSetup({ seed, pkgExists }) {
     })
   }
 
+  questions.push({
+    type: 'confirm',
+    name: 'isolation',
+    message: 'Enable per-spec isolation — a git worktree per spec?',
+    initial: isolationSeed,
+  })
+
   const ans = await prompts(questions, { onCancel })
   if (cancelled) throw new Error('Setup cancelled')
 
   return {
-    changelog: {
-      enabled: ans.changelogEnabled,
-      file: ans.changelogFile || seed.changelog.file,
-    },
-    releases: {
-      enabled: ans.releasesEnabled,
-      file: ans.releasesFile || seed.releases.file,
-      productName: ans.productName || seed.releases.productName,
-      scopeAreas: seed.releases.scopeAreas,
+    release: {
+      changelog: {
+        enabled: ans.changelogEnabled,
+        file: ans.changelogFile || seed.changelog.file,
+      },
+      releases: {
+        enabled: ans.releasesEnabled,
+        file: ans.releasesFile || seed.releases.file,
+        productName: ans.productName || seed.releases.productName,
+        scopeAreas: seed.releases.scopeAreas,
+      },
+      versionHook: pkgExists ? Boolean(ans.versionHook) : seed.versionHook,
     },
-    versionHook: pkgExists ? Boolean(ans.versionHook) : seed.versionHook,
+    isolation: Boolean(ans.isolation),
   }
 }
 

package/src/sync/apply.js

@@ -0,0 +1,66 @@
+'use strict'
+
+/**
+ * Translate normalized field values into a local frontmatter patch (pull side).
+ *
+ * Only the `pull`-owned, frontmatter-backed fields have a local home in Phase 2:
+ *   workflowState → spec_status (Linear state name mapped back to the bucket),
+ *   priority      → priority,
+ *   labels        → labels.
+ * Any other field handed in (a body field like `description`/`milestones`) has no
+ * frontmatter mapping yet, so it's returned in `deferred` — the caller must NOT
+ * advance its base, keeping the remote edit pending instead of falsely synced.
+ */
+
+// field name → frontmatter key.
+const FRONTMATTER_FIELD = {
+  workflowState: 'spec_status',
+  priority: 'priority',
+  labels: 'labels',
+}
+
+// Invert config.states ({ bucket: "Linear Name" }) → { "linear name": bucket }.
+function invertStates(config) {
+  const out = {}
+  const states = (config && config.states) || {}
+  for (const [bucket, name] of Object.entries(states)) {
+    if (typeof name === 'string') out[name.toLowerCase()] = bucket
+  }
+  return out
+}
+
+// Map a remote workflowState (a Linear state name) back to a local bucket. Falls
+// back to the raw value when it isn't one of the configured states.
+function localWorkflowState(value, config) {
+  if (value == null) return null
+  const bucket = invertStates(config)[String(value).toLowerCase()]
+  return bucket || String(value)
+}
+
+/**
+ * Build the frontmatter patch for a set of applied field values.
+ * @param {object} fieldValues  { fieldName: value } to write locally
+ * @returns {{ patch:object, applied:string[], deferred:string[] }}
+ */
+function frontmatterPatchFor(fieldValues, config) {
+  const patch = {}
+  const applied = []
+  const deferred = []
+  for (const [field, value] of Object.entries(fieldValues)) {
+    const key = FRONTMATTER_FIELD[field]
+    if (!key) {
+      deferred.push(field)
+      continue
+    }
+    patch[key] = field === 'workflowState' ? localWorkflowState(value, config) : value
+    applied.push(field)
+  }
+  return { patch, applied, deferred }
+}
+
+module.exports = {
+  frontmatterPatchFor,
+  localWorkflowState,
+  invertStates,
+  FRONTMATTER_FIELD,
+}

package/src/sync/base.js

@@ -0,0 +1,83 @@
+'use strict'
+
+/**
+ * The committed base sidecar + the backup-before-force reflog.
+ *
+ * The base is the last-synced snapshot per spec, stored at
+ * `{sync.baseDir}/{identifier}.base.json` and committed so each worktree carries
+ * its own base and the three-way divergence check stays accurate. After any
+ * successful pull/push/force the engine rewrites it (`writeBase`).
+ *
+ * `backup(side, …)` lands the about-to-be-clobbered side under `{sync.backupDir}`
+ * BEFORE a `--force` overwrites it — force never destroys without first writing a
+ * copy. The filename carries a caller-supplied timestamp (the engine takes no
+ * Date.now(), for reproducible tests) and is made collision-safe with a counter.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function baseFile(dir, identifier, config) {
+  return path.join(dir, config.sync.baseDir, `${identifier}.base.json`)
+}
+
+/**
+ * Read a spec's committed base. Returns the parsed object, or `null` when no base
+ * exists yet (never synced) — the compare treats null as "no prior state".
+ */
+function readBase(dir, identifier, config) {
+  const file = baseFile(dir, identifier, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid base ${path.relative(dir, file)}: ${error.message}`)
+  }
+}
+
+/**
+ * Rewrite a spec's committed base with the freshly-synced field set. Creates
+ * `{sync.baseDir}` if needed. Returns the absolute path written.
+ */
+function writeBase(dir, identifier, config, data) {
+  const file = baseFile(dir, identifier, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+  return file
+}
+
+/**
+ * Back up the about-to-be-clobbered `side` ('local' | 'remote') into
+ * `{sync.backupDir}` before a --force. `timestamp` is caller-supplied (the engine
+ * never reads the clock); the name is made collision-safe with a `-N` counter.
+ * Returns the absolute path written, or null when `data` is nullish (nothing to
+ * back up — e.g. forcing a pull with no prior remote).
+ */
+function backup(side, dir, identifier, config, { timestamp, data }) {
+  if (data == null) return null
+  const backupRoot = path.join(dir, config.sync.backupDir)
+  fs.mkdirSync(backupRoot, { recursive: true })
+
+  const stem = `${identifier}.${side}.${timestamp}`
+  let file = path.join(backupRoot, `${stem}.json`)
+  let n = 1
+  while (fs.existsSync(file)) {
+    file = path.join(backupRoot, `${stem}-${n}.json`)
+    n += 1
+  }
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+  return file
+}
+
+module.exports = {
+  readBase,
+  writeBase,
+  backup,
+  baseFile,
+}

package/src/sync/compare.js

@@ -0,0 +1,99 @@
+'use strict'
+
+/**
+ * The three-way compare at the heart of the hybrid sync.
+ *
+ * `classify(local, remote, base, config)` compares each configured field across
+ * the local snapshot, the remote (Linear) projection, and the committed base
+ * (the last-synced state). Per field it returns a raw three-way `status`
+ * (unchanged / local-only / remote-only / conflict), then collapses it through
+ * the field's ownership (`both|pull|push`) into effective `pushable` / `pullable`
+ * flags. Ownership is what makes most "both sides differ" cases *not* a real
+ * conflict:
+ *   - a `pull` field never pushes (Linear wins) → conflict collapses to remote-only
+ *   - a `push` field never pulls (repo wins)    → conflict collapses to local-only
+ *   - only a `both` field where both sides moved off base is a true `conflict`.
+ *
+ * Pure and deterministic: field identity is a stable content hash (sorted-key
+ * JSON → SHA-1), so `null`, `undefined`, and a missing base all compare equal,
+ * and object key order never causes a false diff. No Date.now()/Math.random().
+ */
+
+const { createHash } = require('node:crypto')
+
+// Deterministic JSON: object keys sorted recursively; array order preserved
+// (order is meaningful for milestones/tasks). undefined normalises to null.
+function stableStringify(value) {
+  if (value === undefined || value === null) return 'null'
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']'
+  }
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value)
+}
+
+// Stable content hash of a single field value.
+function hashField(value) {
+  return createHash('sha1').update(stableStringify(value)).digest('hex')
+}
+
+// Raw three-way status from the three hashes.
+function rawStatus(localH, remoteH, baseH) {
+  const localChanged = localH !== baseH
+  const remoteChanged = remoteH !== baseH
+  if (!localChanged && !remoteChanged) return 'unchanged'
+  if (localChanged && !remoteChanged) return 'local-only'
+  if (!localChanged && remoteChanged) return 'remote-only'
+  // both moved off base — but they may have converged on the same value.
+  if (localH === remoteH) return 'unchanged'
+  return 'conflict'
+}
+
+// Collapse the raw status through ownership into an effective status + flags.
+function collapse(raw, ownership) {
+  const canPush = ownership === 'both' || ownership === 'push'
+  const canPull = ownership === 'both' || ownership === 'pull'
+
+  if (raw === 'unchanged') return { status: 'unchanged', pushable: false, pullable: false }
+  if (raw === 'local-only') return { status: 'local-only', pushable: canPush, pullable: false }
+  if (raw === 'remote-only') return { status: 'remote-only', pushable: false, pullable: canPull }
+
+  // conflict: both sides diverged off base.
+  if (ownership === 'push') return { status: 'local-only', pushable: true, pullable: false }
+  if (ownership === 'pull') return { status: 'remote-only', pushable: false, pullable: true }
+  return { status: 'conflict', pushable: true, pullable: true }
+}
+
+/**
+ * Classify every field in `config.sync.fieldOwnership`.
+ *
+ * @param {object} local  normalized local snapshot (normalizeLocal output)
+ * @param {object} remote normalized remote projection (normalizeRemote output)
+ * @param {object|null} base the committed base (same shape) or null (never synced)
+ * @returns {Array<{field, ownership, raw, status, pushable, pullable}>}
+ *   one entry per configured field, in config order.
+ */
+function classify(local, remote, base, config) {
+  const ownership = config.sync.fieldOwnership
+  const baseObj = base || {}
+  return Object.keys(ownership).map((field) => {
+    const own = ownership[field]
+    const localH = hashField(local ? local[field] : null)
+    const remoteH = hashField(remote ? remote[field] : null)
+    const baseH = hashField(field in baseObj ? baseObj[field] : null)
+    const raw = rawStatus(localH, remoteH, baseH)
+    const { status, pushable, pullable } = collapse(raw, own)
+    return { field, ownership: own, raw, status, pushable, pullable }
+  })
+}
+
+module.exports = {
+  classify,
+  hashField,
+  stableStringify,
+  rawStatus,
+  collapse,
+}

package/src/sync/config.js

@@ -0,0 +1,198 @@
+'use strict'
+
+/**
+ * Config loader for the Linear hybrid-sync feature (`/spec-status`, `/spec-pull`,
+ * `/spec-push` and the Linear-aware paths of `/spec` and `/spec-go`).
+ *
+ * Reads `specs/.core/linear.config.json` from the project root and normalises it
+ * over frozen defaults. The feature is strictly opt-in: when the file is absent
+ * the loader never throws — it returns the defaults with `present:false`, which
+ * every caller treats as "Linear sync unused".
+ *
+ * Mirrors the shape/idiom of `src/env/config.js` (frozen defaults, merge known
+ * keys only, forward-compatible on unknown keys). Zero-dependency. The one place
+ * it is stricter: a `sync.fieldOwnership` value outside `both|pull|push` is a
+ * hard error — the engine's whole safety model rests on those enums.
+ *
+ * Shape (see assets/core/linear.config.md for field docs):
+ *   {
+ *     linear:   { teamKey, teamId, initiativeId },
+ *     mapping:  { specFolder, phases, tasks },
+ *     states:   { backlog, "in-progress", complete, cancelled },
+ *     snapshot: { overviewFile },
+ *     branch:   { pattern },
+ *     sync: {
+ *       baseDir, backupDir,
+ *       fieldOwnership: { <field>: "both" | "pull" | "push" },
+ *       localOnlySections: string[]
+ *     }
+ *   }
+ */
+
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
+
+const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
+
+const DEFAULT_CONFIG = Object.freeze({
+  linear: Object.freeze({ teamKey: '', teamId: '', initiativeId: '' }),
+  mapping: Object.freeze({ specFolder: 'project', phases: 'milestone', tasks: 'issue' }),
+  states: Object.freeze({
+    backlog: 'Backlog',
+    'in-progress': 'In Progress',
+    complete: 'Done',
+    cancelled: 'Cancelled',
+  }),
+  snapshot: Object.freeze({ overviewFile: '00-overview.md' }),
+  branch: Object.freeze({ pattern: '{type}/{slug}' }),
+  sync: Object.freeze({
+    baseDir: 'specs/.core/linear-base',
+    backupDir: 'specs/.core/linear-backups',
+    fieldOwnership: Object.freeze({
+      description: 'both',
+      milestones: 'both',
+      phaseBodies: 'both',
+      acceptanceCriteria: 'both',
+      taskBreakdown: 'both',
+      workflowState: 'pull',
+      priority: 'pull',
+      labels: 'pull',
+    }),
+    localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
+  }),
+})
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// A fresh, deeply-mutable copy of the defaults to merge onto.
+function defaults() {
+  return {
+    linear: { ...DEFAULT_CONFIG.linear },
+    mapping: { ...DEFAULT_CONFIG.mapping },
+    states: { ...DEFAULT_CONFIG.states },
+    snapshot: { ...DEFAULT_CONFIG.snapshot },
+    branch: { ...DEFAULT_CONFIG.branch },
+    sync: {
+      baseDir: DEFAULT_CONFIG.sync.baseDir,
+      backupDir: DEFAULT_CONFIG.sync.backupDir,
+      fieldOwnership: { ...DEFAULT_CONFIG.sync.fieldOwnership },
+      localOnlySections: [...DEFAULT_CONFIG.sync.localOnlySections],
+    },
+  }
+}
+
+// Copy a typed field from parsed[key] onto base[key] when it matches `type`.
+// Strings are trimmed and must be non-empty to override; `string?` may be empty.
+function assign(base, parsed, key, type) {
+  const v = parsed[key]
+  if (type === 'string') {
+    if (typeof v === 'string' && v.trim()) base[key] = v.trim()
+  } else if (type === 'string?') {
+    if (typeof v === 'string') base[key] = v
+  } else if (type === 'boolean') {
+    if (typeof v === 'boolean') base[key] = v
+  }
+}
+
+// Merge (and validate) sync.fieldOwnership. Any key the caller lists joins the
+// compared field set; the value MUST be one of both|pull|push.
+function mergeFieldOwnership(base, parsed) {
+  if (!isObject(parsed)) return
+  for (const [field, dir] of Object.entries(parsed)) {
+    if (!OWNERSHIP.includes(dir)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: sync.fieldOwnership.${field} = ${JSON.stringify(dir)} ` +
+          `(expected one of ${OWNERSHIP.join('|')})`,
+      )
+    }
+    base[field] = dir
+  }
+}
+
+/**
+ * Merge a parsed config over the defaults. Only known keys are copied (unknown
+ * keys ignored for forward-compat). Nested objects are merged field-by-field.
+ */
+function mergeConfig(base, parsed) {
+  if (!isObject(parsed)) return base
+
+  if (isObject(parsed.linear)) {
+    assign(base.linear, parsed.linear, 'teamKey', 'string?')
+    assign(base.linear, parsed.linear, 'teamId', 'string?')
+    assign(base.linear, parsed.linear, 'initiativeId', 'string?')
+  }
+
+  if (isObject(parsed.mapping)) {
+    assign(base.mapping, parsed.mapping, 'specFolder', 'string')
+    assign(base.mapping, parsed.mapping, 'phases', 'string')
+    assign(base.mapping, parsed.mapping, 'tasks', 'string')
+  }
+
+  if (isObject(parsed.states)) {
+    for (const key of Object.keys(base.states)) {
+      assign(base.states, parsed.states, key, 'string')
+    }
+  }
+
+  if (isObject(parsed.snapshot)) {
+    assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
+  }
+
+  if (isObject(parsed.branch)) {
+    assign(base.branch, parsed.branch, 'pattern', 'string')
+  }
+
+  if (isObject(parsed.sync)) {
+    assign(base.sync, parsed.sync, 'baseDir', 'string')
+    assign(base.sync, parsed.sync, 'backupDir', 'string')
+    mergeFieldOwnership(base.sync.fieldOwnership, parsed.sync.fieldOwnership)
+    if (Array.isArray(parsed.sync.localOnlySections)) {
+      base.sync.localOnlySections = parsed.sync.localOnlySections
+        .filter((s) => typeof s === 'string' && s.trim())
+        .map((s) => s.trim())
+    }
+  }
+
+  return base
+}
+
+/**
+ * Load and normalise `specs/.core/linear.config.json` from `dir` (default cwd).
+ * Returns `{ config, present }`:
+ *   - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
+ *   - present      → `{ config: merged,   present: true }`
+ * Malformed JSON or a bad `fieldOwnership` enum → throws a clear Error.
+ */
+function loadLinearConfig(dir = process.cwd()) {
+  const base = defaults()
+  const file = join(dir, CONFIG_FILE)
+
+  let raw
+  try {
+    raw = readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { config: base, present: false }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+
+  return { config: mergeConfig(base, parsed), present: true }
+}
+
+module.exports = {
+  loadLinearConfig,
+  mergeConfig,
+  DEFAULT_CONFIG,
+  CONFIG_FILE,
+  OWNERSHIP,
+}