@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

package/src/vendor/sync-core/src/normalize.js

@@ -0,0 +1,989 @@
+'use strict'
+
+/**
+ * Normalize a remote Project projection and a local spec snapshot into the SAME
+ * field set, so the three-way compare (compare.js) can diff them field by field.
+ *
+ * Both `normalizeLocal(snapshotDir, config)` and `normalizeRemote(project, config)`
+ * return an object whose keys are exactly `config.sync.fieldOwnership`'s keys —
+ * identical field sets by construction. A field a given side can't supply is
+ * `null` (scalars) or `[]` (collections), never absent, so the sets stay equal.
+ *
+ * Pure: `normalizeLocal` reads files under `snapshotDir` but makes no other side
+ * effects and no Date.now()/Math.random(). `localOnlySections` are stripped from
+ * the local `description` so they're never pushed to remote.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { dialectOf } = require('./dialect.js')
+const { fieldsOf } = require('./fields.js')
+const { fenceMask, findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
+
+// --- markdown / frontmatter parsing -----------------------------------------
+
+// Split `---\n…\n---` frontmatter off the top. Returns { data, body }.
+function parseFrontmatter(raw) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw)
+  if (!m) return { data: {}, body: raw }
+  const data = {}
+  for (const line of m[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (!kv) continue
+    data[kv[1]] = parseScalar(kv[2].trim())
+  }
+  return { data, body: raw.slice(m[0].length) }
+}
+
+// Parse a frontmatter scalar: quoted string, JSON array, number, or bare string.
+function parseScalar(v) {
+  if (v === '') return null
+  const unq = /^["'](.*)["']$/.exec(v)
+  if (unq) return unq[1]
+  if (v.startsWith('[')) {
+    try {
+      return JSON.parse(v)
+    } catch {
+      return v
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean)
+    }
+  }
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+  return v
+}
+
+// Split a markdown body into { title, sections } where sections maps a `## `
+// heading text → its content (until the next `## `). The H1 `# ` is the title.
+function parseSections(body) {
+  const lines = body.split('\n')
+  const inFence = fenceMask(lines)
+  let title = null
+  const sections = {}
+  let current = null
+  let buf = []
+  const flush = () => {
+    if (current !== null) sections[current] = buf.join('\n').trim()
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // A `#`/`##` inside a fenced code block is example text, not a real heading —
+    // treat it as body content so it can't start a phantom section.
+    const h1 = inFence[i] ? null : /^#\s+(.*)$/.exec(line)
+    const h2 = inFence[i] ? null : /^##\s+(.*)$/.exec(line)
+    if (h1 && title === null) {
+      title = h1[1].trim()
+      continue
+    }
+    if (h2) {
+      flush()
+      current = h2[1].trim()
+      buf = []
+      continue
+    }
+    if (current !== null) buf.push(line)
+  }
+  flush()
+  return { title, sections }
+}
+
+// Canonical milestone status from the phase-index emoji.
+const EMOJI_STATUS = { '⬜': 'not-started', '🔄': 'in-progress', '✅': 'done' }
+
+// Parse the "## Phases" index table into [{ name, status }] rows.
+function parsePhaseIndex(phasesSection) {
+  if (!phasesSection) return []
+  const rows = []
+  for (const line of phasesSection.split('\n')) {
+    // | 1 | Phase name | ✅ | [01-…](01-…) |
+    const cells = line.split('|').map((c) => c.trim())
+    if (cells.length < 5) continue
+    const n = cells[1]
+    if (!/^\d+$/.test(n)) continue // skip header + separator rows
+    const name = cells[2]
+    const emoji = (cells[3].match(/[⬜🔄✅]/u) || [])[0]
+    // `stated` separates "the row says not-started" from "the row said nothing
+    // we recognise". A cell holding the word `Done`, an em dash, or a legacy
+    // spec's freeform text expresses no status in this vocabulary, and reading
+    // its absence as `not-started` let lintPhases quote the overview as saying
+    // something it never said.
+    rows.push({ name, status: EMOJI_STATUS[emoji] || 'not-started', stated: Boolean(emoji) })
+  }
+  return rows
+}
+
+// The phase's descriptive title: the h1 with the "Phase N — " prefix and any
+// trailing status emoji stripped (so it matches its Linear Milestone name).
+function phaseTitle(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  if (!h1) return null
+  const t = h1[1]
+    .replace(/\s*[⬜🔄✅]\s*$/u, '')
+    .replace(/^Phase\s+\d+\s*[—–-]\s*/i, '')
+    .trim()
+  return t || null
+}
+
+// The raw ⬜/🔄/✅ on a phase file's h1, or undefined when it carries none.
+// Kept separate from `phaseStateBucket` because the LINT has to tell "absent"
+// apart from "not-started" — the projection deliberately cannot (see below).
+function headingEmoji(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  return h1 ? (h1[1].match(/[⬜🔄✅]/u) || [])[0] : undefined
+}
+
+// The `> **Status:** …` line's value, or null when the file has none. This is
+// the human mirror of the heading emoji, not a source of truth — `lintPhases`
+// cross-checks it, and nothing else reads it.
+function phaseStatusLine(body) {
+  const m = /^>.*\*\*Status:\*\*\s*(.+?)\s*$/m.exec(body)
+  return m ? m[1] : null
+}
+
+// Read a `> **Status:**` value leniently into the canonical vocabulary: an emoji
+// if it carries one, else a word we recognise. Returns null for anything else —
+// the line is free prose, and warning on an unrecognised phrasing would train
+// the warning away.
+// `pending` is deliberately NOT here: "pending review" matches as not-started
+// but means roughly the opposite, and a false positive is worse than a missed
+// check — it teaches the reader to ignore the warning.
+const STATUS_WORDS = [
+  [/\b(not[\s-]?started|todo|to[\s-]do|planned)\b/i, 'not-started'],
+  [/\b(in[\s-]?progress|started|doing|wip)\b/i, 'in-progress'],
+  [/\b(done|complete[d]?|finished|shipped)\b/i, 'done'],
+]
+function statusLineValue(line) {
+  if (!line) return null
+  const emoji = (line.match(/[⬜🔄✅]/u) || [])[0]
+  if (emoji) return EMOJI_STATUS[emoji]
+  for (const [re, status] of STATUS_WORDS) if (re.test(line)) return status
+  return null
+}
+
+// A phase's status (from its heading emoji ⬜/🔄/✅) mapped to a state bucket the
+// `states` table understands, so a sub-issue lands in the matching Linear issue
+// state. Unknown/absent → backlog.
+//
+// That fallback conflates "author marked it not-started" with "author used a
+// format we don't parse", which is silent corruption: the wrong state pushes
+// cleanly and `record` then commits it as the INTENDED value. The fix is not
+// leniency here — one convention beats two — it is `lintPhases`, which warns.
+const PHASE_STATE_BUCKET = { 'not-started': 'backlog', 'in-progress': 'in-progress', done: 'complete' }
+function phaseStateBucket(body) {
+  return PHASE_STATE_BUCKET[EMOJI_STATUS[headingEmoji(body)]] || 'backlog'
+}
+
+// Parse a task line (already stripped of its leading "- ") into a keyed item:
+// its checkbox state, its text, and the inline Linear issue identifier if present
+// (`… (SKI-123)`). Returns null for a non-task line.
+function parseTaskLine(line) {
+  // Any single-character mark, matching the parser (`TASK_START_RE`). Only
+  // `x`/`X` is done — every other mark (`~`, `>`, `-` …) is a project's own
+  // vocabulary, carried through verbatim rather than coerced to unchecked.
+  const m = /^\[([^\]])\]\s*(.*)$/.exec(line)
+  if (!m) return null
+  const done = m[1].toLowerCase() === 'x'
+  let text = m[2].trim()
+  let id = null
+  const idm = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/.exec(text)
+  if (idm) {
+    id = idm[1]
+    text = text.slice(0, idm.index).trim()
+  }
+  return { id, text, done }
+}
+
+// Tasks used to be grouped onto their source headings here, because the body was
+// rebuilt from harvested task lines and the headings had to be put back. The
+// projection now emits the phase file itself, so the headings never leave in the
+// first place (bug-phase-content-dropped) and the grouping is gone with them.
+
+// The phase's stated purpose, in either shape people actually write it: an
+// inline `**Goal:** …` paragraph, or a `## Goal` section. Only the inline form
+// was recognised — so the phase files written the other way (4 of the 96 in this
+// repo, all of them recent) projected an empty goal.
+function phaseGoal(body) {
+  const inline = /\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body)
+  if (inline) return inline[1]
+  return parseSections(body).sections.Goal || ''
+}
+
+// One task block back to a single markdown line. `findTaskBlocks` also returns
+// the plain sub-bullets written underneath a task; they carry no checkbox, so
+// they render as the bullet their author used — emitting `- [ ]` here would
+// invent a task that does not exist in the repo. Any inline `(KEY-123)` stamped
+// on a legacy task line is stripped: those ids were per-task issues we no longer
+// create, and they read as noise in the mirror.
+function renderTaskBlockLine(b) {
+  const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
+  const text = parsed ? parsed.text : b.text
+  return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
+}
+
+// Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
+// linked milestone id (from optional frontmatter), title, goal and tasks.
+function readPhaseFiles(snapshotDir, config) {
+  let entries
+  try {
+    entries = fs.readdirSync(snapshotDir)
+  } catch {
+    return []
+  }
+  return entries
+    .filter((f) => /^\d\d-.*\.md$/.test(f) && !f.startsWith('00-'))
+    .sort()
+    .map((file) => {
+      const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+      const { data, body } = parseFrontmatter(raw)
+      // No /m on either: under /m, `$` matches end-of-LINE, so a non-greedy
+      // scan stops at the first newline and a hand-wrapped bullet or goal loses
+      // every continuation line. Tasks come from findTaskBlocks, which reads a
+      // wrapped bullet as one logical task.
+      // Collapsed, not just captured: the goal becomes a milestone description,
+      // and Linear may canonicalize a soft line break away on save. Collapsing
+      // both sides keeps a wrapped goal from diffing forever.
+      const goal = collapseHyphenAware(phaseGoal(body))
+      // Rendered as markdown checklist lines, ready to drop into a sub-issue
+      // description: indentation kept so nesting survives, each bullet keeping
+      // the marker its author wrote.
+      const lines = body.split('\n')
+      const blocks = findTaskBlocks(lines)
+      const tasks = blocks.map(renderTaskBlockLine)
+      return {
+        phase: file.replace(/\.md$/, ''),
+        file,
+        // The sub-issue id, stamped back into the phase file on first push.
+        id: data[fieldsOf(config).issueId] != null ? String(data[fieldsOf(config).issueId]) : null,
+        name: phaseTitle(body),
+        goal: goal.trim(),
+        state: phaseStateBucket(body),
+        // Lint-only signals. `emoji` is undefined when the heading carries none
+        // — the distinction `state` throws away; `statusLine` is the raw
+        // `> **Status:**` value. Neither affects the projection.
+        emoji: headingEmoji(body),
+        statusLine: phaseStatusLine(body),
+        tasks,
+        // The raw body and the parsed blocks, so `subIssueBody` can project the
+        // file rather than rebuild it from fragments. Not part of the pushed
+        // field set — `toFieldSet` picks the projection's keys explicitly.
+        lines,
+        blocks,
+      }
+    })
+}
+
+// --- phase-status lint ------------------------------------------------------
+
+/**
+ * Warn where a phase's status signals are absent or disagree.
+ *
+ * A spec carries the same status in three places — the phase file's h1 emoji,
+ * its `> **Status:**` line, and the `00-overview.md` phase-index row — and only
+ * the h1 is load-bearing. Writing the other two correctly while leaving the h1
+ * bare projects a finished phase as `backlog`, pushes cleanly, and records the
+ * wrong value as intended. Nothing looks wrong anywhere.
+ *
+ * Returns `[{ file, code, message }]`, `code` being `missing-status-emoji` or
+ * `status-disagreement`. Pure aside from reads; callers decide how loud to be
+ * (today: printed, never fatal).
+ */
+function lintPhases(snapshotDir, config) {
+  const phases = readPhaseFiles(snapshotDir, config)
+  // BLIND SPOT: `readPhaseFiles` only sees `NN-*.md`, so a legacy bare
+  // `<name>.md` spec yields no phases at all. Silence is the right answer —
+  // there is no phase file to carry an emoji — but it is silence from having
+  // looked nowhere, not from having looked and found everything in order.
+  if (!phases.length) return []
+
+  // The overview may be absent (a legacy bare `<name>.md` spec) — that is not
+  // itself a lint failure, it just removes one of the three cross-checks.
+  let indexRows = []
+  try {
+    const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+    const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
+    const { sections } = parseSections(parseFrontmatter(raw).body)
+    indexRows = parsePhaseIndex(sections.Phases)
+  } catch {
+    indexRows = []
+  }
+
+  const warnings = []
+  phases.forEach((phase, i) => {
+    if (!phase.emoji) {
+      warnings.push({
+        file: phase.file,
+        code: 'missing-status-emoji',
+        message: `no ⬜/🔄/✅ in the heading — projecting as not-started`,
+      })
+      // Without a heading emoji there is nothing to disagree WITH: the other two
+      // signals can't be checked against a value that was never expressed.
+      return
+    }
+
+    const heading = EMOJI_STATUS[phase.emoji]
+
+    const fromLine = statusLineValue(phase.statusLine)
+    if (fromLine && fromLine !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but its Status line says ${fromLine}`,
+      })
+    }
+
+    // Match the index row by phase title, falling back to position — a renamed
+    // phase shouldn't silently drop the check.
+    //
+    // BLIND SPOT: the index is only evidence where it used the emoji vocabulary.
+    // A row whose Status cell holds prose (or nothing) parses as `not-started`,
+    // which is a default, not a statement — cross-checking against it accused a
+    // healthy spec of a disagreement with a value nobody wrote. `stated` is the
+    // positive signal: compare only against a status the row actually expressed.
+    const row = indexRows.find((r) => r.name === phase.name) || indexRows[i]
+    if (row && row.stated && row.status !== heading) {
+      warnings.push({
+        file: phase.file,
+        code: 'status-disagreement',
+        message: `heading says ${heading} but the overview phase-index row says ${row.status}`,
+      })
+    }
+  })
+  return warnings
+}
+
+// --- ownership-driven field set ---------------------------------------------
+
+/**
+ * Does this repo own `field` — i.e. does the projection carry it at all?
+ *
+ * THE VALUE DECIDES, NEVER THE KEY'S PRESENCE. A field configured `none` is
+ * declared not-ours, and it must be indistinguishable from one the config never
+ * listed: both produce a projection with no such key, which is the single
+ * vocabulary every downstream reader already speaks for "not in play"
+ * (`compare.js` hashes it only when defined; the status report prints an
+ * assignee line only when defined).
+ *
+ * Asked in one place so the two cannot drift. Testing `field in fieldOwnership`
+ * at a call site reads correct and is not: once a field is owned by DEFAULT the
+ * key is always present, and the test silently becomes "always true".
+ */
+function ownsField(config, field) {
+  const owned = config && config.sync && config.sync.fieldOwnership
+  return !!owned && field in owned && owned[field] !== 'none'
+}
+
+// Reduce an `extracted` map to exactly the configured field keys, defaulting a
+// missing field to `null` so local and remote always share an identical set.
+//
+// A declined field is OMITTED, not set null. The two are not interchangeable
+// here: `null` is a value this projection asserts — it is how a finished spec
+// hands its issue back — so writing it for a field the repo does not own would
+// clear in Linear exactly what declining ownership promised not to touch.
+function toFieldSet(extracted, config) {
+  const out = {}
+  for (const field of Object.keys(config.sync.fieldOwnership)) {
+    if (!ownsField(config, field)) continue
+    out[field] = field in extracted ? extracted[field] : null
+  }
+  return out
+}
+
+// --- local snapshot ---------------------------------------------------------
+
+/**
+ * Read a spec snapshot (its 00-overview.md + phase files) into the raw pieces the
+ * extractors and callers need. Pure aside from reads under `snapshotDir`.
+ */
+function readSnapshot(snapshotDir, config) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
+  const { data, body } = parseFrontmatter(raw)
+  const { title, sections } = parseSections(body)
+  const phases = readPhaseFiles(snapshotDir, config)
+  return { frontmatter: data, title, sections, phases, body }
+}
+
+// Build the pushed description: the overview prose with local-only sections
+// removed. Keeps the title line for context. `extraSkip` drops additional
+// sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
+// the phase list isn't duplicated in the description — Decision 5).
+function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
+  const skip = new Set([...(localOnlySections || []), ...extraSkip])
+  const parts = []
+  if (title) parts.push(`# ${title}`)
+  for (const [heading, content] of Object.entries(sections)) {
+    if (skip.has(heading)) continue
+    parts.push(`## ${heading}\n\n${content}`.trim())
+  }
+  return dialect.flattenTables(dialect.canonicalize(parts.join('\n\n'))) || null
+}
+
+// A phase sub-issue's description: its `**Goal:**` line, plus the phase's task
+// list as a markdown checklist when `mapping.tasks` is `checklist`.
+//
+// The checklist is a READ-ONLY mirror like everything else here — the repo is
+// the source of truth, so a box ticked in the tracker is overwritten on the next
+// push. Without it a sub-issue is a title and one sentence, which is too thin to
+// act on; with it the phase is legible to someone working in the tracker without
+// tasks becoming individually-synced objects again.
+function subIssueBody(phase, tasksMode, localOnlySections, dialect) {
+  if (tasksMode !== 'checklist') return dialect.flattenTables(phase.goal)
+  return dialect.flattenTables(projectPhaseBody(phase, localOnlySections))
+}
+
+/**
+ * Project a phase file into its sub-issue body: the file as written, with each
+ * task bullet replaced by its rendered single-line form.
+ *
+ * This used to REBUILD the body from two harvested fragments — the `**Goal:**`
+ * paragraph and the task lines `findTaskBlocks` claimed — and silently dropped
+ * everything neither covered: prose, whole `##` sections, and any table or
+ * fenced block nested under a task. `buildDescription` never had that problem
+ * because it projects the overview section by section, so the fix is to make the
+ * phase body work the same way — lossless by construction rather than by
+ * enumerating the shapes we remembered.
+ *
+ * Only two things are deliberately left out, and both are pushed as their own
+ * field, so keeping them would duplicate:
+ *
+ *   - the `#` h1, projected as the sub-issue's `name`;
+ *   - the `> **Status:**` line, projected as its `state`.
+ *
+ * Local-only sections are stripped exactly as they are from the description.
+ */
+function projectPhaseBody(phase, localOnlySections) {
+  const skip = new Set(localOnlySections || [])
+  const lines = phase.lines || []
+  const inFence = fenceMask(lines)
+  // Where each task block starts, so the walk can emit its rendered form and
+  // jump the lines it claims. Line-indexed splicing is what `task-block.js` is
+  // built for; everything it does NOT claim is content, and passes through.
+  const blockAt = new Map()
+  for (const b of phase.blocks || []) blockAt.set(b.start, b)
+
+  const out = []
+  let dropping = false // inside a local-only section
+  let seenTitle = false
+  for (let i = 0; i < lines.length; i++) {
+    const block = blockAt.get(i)
+    if (block) {
+      if (!dropping) out.push(renderTaskBlockLine(block))
+      i = block.end - 1
+      continue
+    }
+    const line = lines[i]
+    if (!inFence[i]) {
+      const h2 = /^##\s+(.*\S)\s*$/.exec(line)
+      if (h2) dropping = skip.has(h2[1].trim())
+      if (!seenTitle && /^#\s+/.test(line)) {
+        seenTitle = true
+        continue
+      }
+      if (/^>\s*\*\*Status:\*\*/.test(line)) continue
+    }
+    if (!dropping) out.push(line)
+  }
+  // Collapse the blank runs the removals leave behind, and trim the ends.
+  return out
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+// Phases inline as `###`, hanging under the `## Phases` index that lists them.
+// The body they carry is a whole document in its own right and starts at `##`,
+// so it demotes to sit under that heading rather than break out of it.
+const INLINE_PHASE_LEVEL = 3
+const MAX_HEADING_LEVEL = 6
+
+/**
+ * Shift every heading in a projected phase body `by` levels, so an inlined phase
+ * nests under the `###` that introduces it.
+ *
+ * Projected for a sub-issue the body is the whole description and its `## Tasks`
+ * is correctly top-level. Inlined it is a subsection, and an undemoted `## Tasks`
+ * would read as a sibling of `## Problem` — pulling every following phase under
+ * it in the outline. Only the `#` run length changes; the content is the same
+ * bytes either way, which is the point of sharing one composer.
+ */
+function demoteHeadings(body, by) {
+  const lines = body.split('\n')
+  const inFence = fenceMask(lines)
+  return lines
+    .map((line, i) => {
+      if (inFence[i]) return line
+      const h = /^(#{1,6})(\s)/.exec(line)
+      if (!h) return line
+      return '#'.repeat(Math.min(h[1].length + by, MAX_HEADING_LEVEL)) + line.slice(h[1].length)
+    })
+    .join('\n')
+}
+
+// The phase file's h1 exactly as written — `Phase 2 — The inline projection 🔄`.
+// `projectPhaseBody` drops it because a sub-issue projects the title as `name`
+// and the emoji as `state`; inlined there are no such fields, so this heading is
+// the only place either can live, and the raw line is where both still are.
+function phaseHeading(phase) {
+  for (const line of phase.lines || []) {
+    const h1 = /^#\s+(.*\S)\s*$/.exec(line)
+    if (h1) return h1[1]
+  }
+  return phase.name
+}
+
+/**
+ * Append the inlined phases to the spec issue's description as `###` sections.
+ *
+ * The body is `subIssueBody`'s — the SAME composer the sub-issue form uses, so
+ * `inline` inherits its fidelity guarantee instead of growing a second extractor
+ * that drops content, which is exactly what the reporting project had to
+ * hand-roll before this existed.
+ */
+function withInlinePhases(description, inlined, tasksMode, localOnlySections, dialect) {
+  if (!inlined.length) return description
+  const sections = inlined.map((phase) => {
+    const body = demoteHeadings(subIssueBody(phase, tasksMode, localOnlySections, dialect) || '', INLINE_PHASE_LEVEL - 1)
+    const heading = '#'.repeat(INLINE_PHASE_LEVEL) + ` ${phaseHeading(phase)}`
+    return body ? `${heading}\n\n${body}` : heading
+  })
+  return [description, ...sections].filter(Boolean).join('\n\n') || null
+}
+
+/**
+ * Normalize a local spec snapshot into the configured field set.
+ */
+// The spec's lifecycle bucket from its folder — the source of truth for status
+// (specs live in specs/<bucket>/<name>/). Maps directly to a `states` key.
+const LIFECYCLE_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
+function bucketFromPath(snapshotDir) {
+  const parent = path.basename(path.dirname(snapshotDir))
+  return LIFECYCLE_BUCKETS.includes(parent) ? parent : null
+}
+
+// Lifecycle buckets in which a spec's work has not begun: never started, or
+// abandoned without ever starting. Under `mapping.phases: 'deferred'` these are
+// the states in which phases are not yet worth minting as sub-issues.
+const UNSTARTED_BUCKETS = ['backlog', 'cancelled']
+
+// Buckets where a spec is FINISHED, and so has nobody working on it.
+const TERMINAL_BUCKETS = ['complete', 'cancelled']
+
+/**
+ * The Linear user this spec is assigned to, AS PROJECTED — which is not simply
+ * what the frontmatter records.
+ *
+ * The BUCKET decides, not the stamp's presence. A spec that is live (`backlog`,
+ * `in-progress`) projects whoever the repo recorded; a finished one projects
+ * `null`, so completing a spec hands the issue back with no unassign step for
+ * anyone to remember. The stamp itself is deliberately left in the spec file:
+ * `> **Developer:**` and the frontmatter are the durable record of who actioned
+ * the work, and that outlives the assignment.
+ *
+ * `null` here does NOT mean "clear it in Linear" on its own — see
+ * `issueChanges`, where an assignee that was never pushed is left alone rather
+ * than retracted. That is what stops this wiping a PM's triage.
+ */
+function assigneeFor(workflowState, frontmatter, config) {
+  if (TERMINAL_BUCKETS.includes(String(workflowState))) return null
+  const id = frontmatter && frontmatter[fieldsOf(config).assigneeId]
+  return typeof id === 'string' && id.trim() ? id.trim() : null
+}
+
+// The mode a bucket gets when a per-bucket `mapping.phases` map omits it. Adding
+// a bucket to the map is therefore an EXCEPTION for that bucket, not a switch
+// that silently suppresses phases everywhere the map is silent. Matches the
+// scalar default in the provider's config so both forms start from one place.
+const DEFAULT_PHASE_MODE = 'subissue'
+
+/**
+ * The phase mode configured for one lifecycle bucket.
+ *
+ * `mapping.phases` is EITHER a scalar — one mode for the whole repo, which is
+ * what every config was before per-bucket mapping — or a map keyed by lifecycle
+ * bucket (`{ backlog: 'subissue', complete: 'inline' }`), because a repo can
+ * legitimately want assignable sub-issues for work in flight and none at all for
+ * 250 finished specs. A scalar resolves to itself for every bucket, so existing
+ * configs are unchanged.
+ *
+ * The SINGLE place a mode is decided: the projection and the description's
+ * `## Phases` index both read it, so they cannot disagree about one spec.
+ */
+function phaseModeFor(bucket, config) {
+  const configured = config && config.mapping && config.mapping.phases
+  if (typeof configured === 'string') return configured
+  if (configured && typeof configured === 'object' && !Array.isArray(configured)) {
+    const mode = configured[bucket]
+    return typeof mode === 'string' ? mode : DEFAULT_PHASE_MODE
+  }
+  return DEFAULT_PHASE_MODE
+}
+
+/**
+ * Which phases the projection sends, and how many the `deferred` mapping is
+ * holding back. Pure — split out so both the projection and the CLI's "N phases
+ * deferred" line read the SAME predicate rather than two copies of it.
+ *
+ * Only UNLINKED phases are withheld. A phase that already carries an id keeps
+ * projecting whatever the mode: one-way sync has no delete op, so withholding a
+ * live sub-issue would not remove it from the tracker — it would freeze it there,
+ * never updated again. That makes switching a project to `deferred` safe.
+ */
+// The spec's lifecycle status as projected: its folder bucket, unless the
+// overview frontmatter pins `spec_status`. Shared by the projection and by
+// `phasesWithheld` so the two can never disagree about whether work has started.
+function specStatus(snapshotDir, frontmatter) {
+  return frontmatter && frontmatter.spec_status != null
+    ? String(frontmatter.spec_status)
+    : bucketFromPath(snapshotDir)
+}
+
+function phaseProjection(phases, workflowState, config) {
+  const named = phases.filter((p) => p.name)
+  const mode = phaseModeFor(workflowState, config)
+  // `deferred` and `inline` both send only phases that ALREADY carry an id, and
+  // for the same reason: one-way sync has no delete op, so withholding a live
+  // sub-issue would freeze it in the tracker rather than remove it (Decision 4).
+  // They differ only in where an unlinked phase goes — nowhere yet, or into the
+  // spec issue's own description.
+  const deferring = mode === 'deferred' && UNSTARTED_BUCKETS.includes(workflowState)
+  const projected = deferring || mode === 'inline' ? named.filter((p) => p.id != null) : named
+  const unlinked = named.filter((p) => p.id == null)
+  return {
+    projected,
+    // Held back until the work starts. Nothing carries them meanwhile, which is
+    // why the `## Phases` index stays and the CLI says how many.
+    withheld: deferring ? unlinked.length : 0,
+    // Rendered into the description instead. Deliberately NOT counted as
+    // withheld: nothing is missing from the mirror, so a report that said "N
+    // phases deferred" would be describing the opposite of what happened.
+    inlined: mode === 'inline' ? unlinked : [],
+  }
+}
+
+function normalizeLocal(snapshotDir, config) {
+  const dialect = dialectOf(config)
+  const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
+  const tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
+  // Status is the spec's lifecycle bucket. The folder is the source of truth; an
+  // explicit `spec_status` frontmatter key overrides it if present. Resolved
+  // BEFORE the sub-issue projection because deferral withholds phases by this
+  // status — so the issue's state and its sub-issues always agree on whether the
+  // work has started, however that status was arrived at.
+  const workflowState = specStatus(snapshotDir, frontmatter)
+  const { projected, withheld, inlined } = phaseProjection(phases, workflowState, config)
+
+  // Strip the `## Phases` index only when the SUB-ISSUES replace it: they carry
+  // every phase, so keeping the index would duplicate the list as prose AND as
+  // objects. It stays whenever they do not — while deferral holds a phase back
+  // the index is the only place that phase appears, and under `inline` there are
+  // no new sub-issues at all, so it is the issue's only table of contents
+  // (Decision 3).
+  //
+  // Keyed on the resolved MODE rather than on `subIssues` being an owned field:
+  // ownership says WHICH fields sync, which is a different question from how
+  // phases are shaped, and `inline` answers the second one per spec (Decision 5).
+  // Ownership still gets a say — an unowned `subIssues` pushes no sub-issues at
+  // all, so the index has to stay there too.
+  const syncsSubIssues = !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership)
+  const phasesCarriedBySubIssues =
+    syncsSubIssues && phaseModeFor(workflowState, config) !== 'inline' && withheld === 0
+  const extracted = {
+    description: withInlinePhases(
+      buildDescription(
+        title,
+        sections,
+        config.sync.localOnlySections,
+        phasesCarriedBySubIssues ? ['Phases'] : [],
+        dialect,
+      ),
+      inlined,
+      tasksMode,
+      config.sync.localOnlySections,
+      dialect,
+    ),
+    // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
+    // local handle the push skill stamps a newly-created sub-issue id back into.
+    // `state` is the phase's status bucket (from its heading emoji), mapped to a
+    // Linear issue state via `config.states` at push time. Tasks ride along in
+    // the description as a read-only checklist (`mapping.tasks`), never as
+    // individually-synced objects.
+    subIssues: projected.map((p) => ({
+      id: p.id,
+      ref: p.phase,
+      name: p.name,
+      goal: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
+      state: p.state,
+    })),
+    workflowState,
+    // Who is building this. `toFieldSet` drops it unless the repo listed
+    // `assignee` in `sync.fieldOwnership`, so the opt-in costs no extra check
+    // here — an un-opted-in repo simply has no such key on its projection, and
+    // every downstream reader treats that as "the field is not in play".
+    assignee: assigneeFor(workflowState, frontmatter, config),
+  }
+  return toFieldSet(extracted, config)
+}
+
+/**
+ * How many phases `mapping.phases: 'deferred'` is currently holding back for
+ * this spec — 0 in every other mode.
+ *
+ * Deliberately NOT a key on `normalizeLocal`'s return: that is the configured
+ * field set and nothing else, so a reporting-only value cannot drift into the
+ * synced shape (or a hash). Callers that want to SAY "N phases deferred" ask for
+ * it, at the cost of a second read of a handful of small files.
+ */
+function phasesWithheld(snapshotDir, config) {
+  const { frontmatter, phases } = readSnapshot(snapshotDir, config)
+  return phaseProjection(phases, specStatus(snapshotDir, frontmatter), config).withheld
+}
+
+// --- remote projection ------------------------------------------------------
+
+// The lifecycle bucket a deployment ladder descends FROM. A spec is handed over
+// to the deploy pipeline once it is finished, so every rung sits downstream of
+// `complete` — a ticket on "On Test" is a completed spec that has been deployed,
+// not a spec that moved somewhere else.
+const LADDER_ORIGIN_BUCKET = 'complete'
+
+// The declared ladder rung with this state name, or null.
+function stageForState(state, config) {
+  if (state == null) return null
+  const want = String(state).toLowerCase().trim()
+  const stages = (config && config.release && config.release.stages) || []
+  if (!Array.isArray(stages)) return null
+  return stages.find((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want) || null
+}
+
+// Map a remote workflow-state name back to the local lifecycle bucket (the
+// vocabulary `spec_status` uses) via config.states, so local and remote
+// workflowState hash equal when semantically equal. Falls back to a lowercased
+// raw value when the state isn't one of the configured names.
+//
+// A DECLARED DEPLOYMENT STAGE reads as `complete`, deliberately. Without this
+// the fallback lowercases it — "On Test" becomes "on test", which equals no
+// bucket — and every deployed spec reports as drifted forever, for the whole
+// time it sits in the pipeline. The project told us these states are downstream
+// of a finished spec, so they are not a disagreement about where the spec is.
+function bucketForState(state, config) {
+  if (state == null) return null
+  const states = (config && config.states) || {}
+  const want = String(state).toLowerCase().trim()
+  for (const [bucket, name] of Object.entries(states)) {
+    if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
+  }
+  if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
+  return want
+}
+
+// Canonicalise a remote workflow-state name into the same vocabulary the local
+// milestone emojis use, so equal states hash equal.
+function canonicalRemoteStatus(state) {
+  const s = String(state || '').toLowerCase().trim()
+  if (!s) return 'not-started'
+  if (/(done|complete|completed|merged)/.test(s)) return 'done'
+  if (/(progress|started|doing|review)/.test(s)) return 'in-progress'
+  if (/(backlog|todo|planned|triage)/.test(s)) return 'not-started'
+  return s
+}
+
+// A tracker issue usually carries its workflow state in `state` (an object
+// `{ name, type }`); accept `status` / a bare string too for robustness. A
+// provider whose remote shape differs supplies `config.remote.stateName`.
+function remoteStateName(issue, config) {
+  const hook = config && config.remote && config.remote.stateName
+  if (typeof hook === 'function') return hook(issue)
+  const st = issue.state != null ? issue.state : issue.status
+  if (st == null) return null
+  if (typeof st === 'object') return st.name != null ? st.name : st.type != null ? st.type : null
+  return st
+}
+
+// The ONE thing one-way sync reads back: the mirror issue's current workflow
+// state, mapped to the local lifecycle bucket, so `/spec-status` can report a
+// drift ("the tracker says Done, your spec says In Progress"). Read-only — never writes.
+function remoteWorkflowState(issue, config) {
+  const name = remoteStateName(issue || {}, config)
+  return name != null ? bucketForState(name, config) : null
+}
+
+// The declared ladder rung a remote issue is currently sitting on, or null.
+// Pairs with `remoteWorkflowState`: that says which bucket the issue maps to,
+// this says whether it got there by being deployed. Read-only.
+function remoteStage(issue, config) {
+  return stageForState(remoteStateName(issue || {}, config), config)
+}
+
+// A Linear issue title is plain text, so markdown emphasis is noise there — and
+// worse, an emphasis run cut mid-title (or a bold LABEL like `**1. Foo**`) can
+// leave a dangling `**`. Strip `*` emphasis markers and unwrap `[text](url)` to
+// `text`. Backticks and `_` are KEPT: task labels lean on inline code
+// (`` `DbFoo` ``) and identifiers use snake_case, and neither breaks a title.
+function stripTitleMarkup(t) {
+  return t
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // [text](url) -> text
+    .replace(/\*/g, '') // bold/italic markers (incl. a dangling ** from a cut)
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+// Trim a trailing parenthetical whose opener has no matching close — so a cut
+// title never ends on a dangling `(`/`[`.
+function dropUnclosedBracket(t) {
+  for (const [open, close] of [
+    ['(', ')'],
+    ['[', ']'],
+  ]) {
+    const o = t.lastIndexOf(open)
+    if (o !== -1 && t.indexOf(close, o) === -1) t = t.slice(0, o)
+  }
+  return t
+}
+
+// Derive a short Linear issue title from a task's full text: the first sentence,
+// falling back to the first `max` chars at a word boundary. A paragraph-length
+// task keeps its full text as the issue *description* (see the projection); this
+// is only the title, so it must read as a one-liner. Guards decimals/versions
+// (`7.0.2`) and common abbreviations (`e.g.`, `i.e.`, `etc.`) so it doesn't cut
+// mid-number or mid-abbreviation.
+function titleFromText(text, max = 100) {
+  const s = collapse(text)
+  if (!s) return s
+  let title = s
+  const re = /[.!?]/g
+  let m
+  while ((m = re.exec(s)) !== null) {
+    const i = m.index
+    const after = s[i + 1]
+    if (after !== undefined && !/\s/.test(after)) continue // not a sentence end
+    if (/\d/.test(s[i - 1] || '') && /\d/.test(after || '')) continue // 7.0.2, 3.14
+    if (/(?:^|[^\w])\d+$/.test(s.slice(0, i))) continue // list ordinal "1." "2."
+    if (/(^|\s)(e\.g|i\.e|etc|vs|no|fig|cf)$/i.test(s.slice(0, i))) continue // abbrev
+    title = s.slice(0, i) // drop the terminator
+    break
+  }
+  title = title.trim()
+  if (title.length > max) {
+    const cut = title.slice(0, max)
+    // Prefer the last clause boundary before the limit — a terminator/separator
+    // to cut AFTER (`.`/`;`/`:`…) or a dash to cut BEFORE — over a bare word break.
+    const minCut = Math.floor(max * 0.4)
+    let boundary = -1
+    let mm
+    const after = /[.!?;:](?=\s|$)/g
+    while ((mm = after.exec(cut)) !== null) boundary = Math.max(boundary, mm.index + 1)
+    const before = /\s[—–]/g
+    while ((mm = before.exec(cut)) !== null) boundary = Math.max(boundary, mm.index)
+    let t
+    if (boundary > minCut) {
+      t = cut.slice(0, boundary)
+    } else {
+      const sp = cut.lastIndexOf(' ')
+      t = sp > 40 ? cut.slice(0, sp) : cut
+    }
+    title = dropUnclosedBracket(t).replace(/[\s.,:;—–([]+$/, '').trim()
+  }
+  return stripTitleMarkup(title)
+}
+
+// Every state NAME the config points at: the lifecycle bucket map, plus the
+// project's deployment ladder when it declares one. Both reach Linear the same
+// way and fail the same way, so both are checked by the same lookup.
+function configuredStateNames(config) {
+  const names = Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
+  const stages = (config && config.release && config.release.stages) || []
+  for (const stage of Array.isArray(stages) ? stages : []) {
+    if (stage && typeof stage.state === 'string') names.push(stage.state)
+  }
+  return names
+}
+
+// Which configured state NAMES are absent from the live workspace. The skill
+// fetches the workspace's project-status names over MCP and passes them here;
+// a non-empty result means a typo/rename that Linear would silently no-op.
+//
+// A project with no `release.stages` contributes nothing here, so the ladder
+// cannot make this accuse a config that was fine before it existed.
+function validateStates(config, workspaceStates) {
+  const configured = configuredStateNames(config)
+  const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
+  return configured.filter((name) => !have.has(name.toLowerCase().trim()))
+}
+
+// Words that identify a workspace state as belonging to a lifecycle bucket.
+// Used only to SUGGEST a replacement for a configured name the workspace does
+// not have — never to pick one silently. The 8→9 case this exists for is
+// `complete`, where the correct value inverts: the project status `Completed`
+// became the issue state `Done`, and no string-distance measure gets you from
+// one to the other.
+const BUCKET_WORDS = {
+  backlog: ['backlog', 'triage', 'todo', 'to do'],
+  'in-progress': ['in progress', 'in-progress', 'doing', 'started', 'in review'],
+  complete: ['done', 'complete', 'completed', 'shipped', 'merged', 'released'],
+  cancelled: ['canceled', 'cancelled', 'abandoned', "won't do", 'wont do', 'duplicate'],
+}
+
+/**
+ * For each configured state name the workspace lacks, what to use instead.
+ *
+ * `validateStates` says a name is wrong; this says what is right, which is the
+ * difference between an error you can act on and one you have to go look up.
+ *
+ * @returns {Array<{bucket:string, configured:string, suggestion:string|null}>}
+ */
+function stateSuggestions(config, workspaceStates) {
+  const names = (workspaceStates || []).map((s) => String(s)).filter(Boolean)
+  const have = new Set(names.map((n) => n.toLowerCase().trim()))
+  const out = []
+  for (const [bucket, configured] of Object.entries((config && config.states) || {})) {
+    if (typeof configured !== 'string') continue
+    if (have.has(configured.toLowerCase().trim())) continue
+    const words = BUCKET_WORDS[bucket] || []
+    const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
+    out.push({ bucket, configured, suggestion, label: `states.${bucket}` })
+  }
+  // Deployment-ladder rungs, reported the same way. No suggestion is offered:
+  // BUCKET_WORDS describes lifecycle vocabulary, and a stage name is the
+  // project's own — guessing "On Test" meant "In Progress" would be worse than
+  // saying nothing.
+  const stages = (config && config.release && config.release.stages) || []
+  for (const stage of Array.isArray(stages) ? stages : []) {
+    if (!stage || typeof stage.state !== 'string') continue
+    if (have.has(stage.state.toLowerCase().trim())) continue
+    out.push({
+      bucket: null,
+      configured: stage.state,
+      suggestion: null,
+      label: `release.stages[${stage.key}]`,
+    })
+  }
+  return out
+}
+
+module.exports = {
+  ownsField,
+  stateSuggestions,
+  configuredStateNames,
+  normalizeLocal,
+  assigneeFor,
+  phaseProjection,
+  phaseModeFor,
+  phasesWithheld,
+  lintPhases,
+  readSnapshot,
+  parseFrontmatter,
+  parseSections,
+  parsePhaseIndex,
+  parseTaskLine,
+  titleFromText,
+  validateStates,
+  canonicalRemoteStatus,
+  bucketForState,
+  LIFECYCLE_BUCKETS,
+  stageForState,
+  remoteStage,
+  remoteWorkflowState,
+  LADDER_ORIGIN_BUCKET,
+}