@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,85 @@
+'use strict'
+
+/**
+ * `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
+ * generated mirror. We never read remote content: `push` builds the local
+ * projection, diffs it against the committed **last-pushed snapshot**, and
+ * returns a **create/update plan** the provider skill applies over MCP.
+ *
+ * The skill: applies the plan → stamps each newly-created id back into the phase
+ * frontmatter / task line → calls `recordPush`, which re-reads the (now
+ * id-stamped) projection and writes the snapshot. That closes the loop: the next
+ * `push` sees an unchanged snapshot and produces an empty plan.
+ *
+ * Pure aside from reading the snapshot; no adapter, no remote read, no
+ * Date.now(). `recordPush` writes the snapshot sidecar.
+ */
+
+const { normalizeLocal, phasesWithheld, phaseModeFor } = require('./normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
+const { readBase, writeBase } = require('./base.js')
+const { detectLegacyMirror } = require('./legacy.js')
+
+// Build the one-way projection from a local snapshot: the spec issue's prose +
+// status, and its phase sub-issues. `status` is the local lifecycle bucket; the
+// skill maps it (and each sub-issue's `state`) to the Linear issue-state NAME via
+// config.states at apply time.
+function projectionOf(snapshotDir, config) {
+  const local = normalizeLocal(snapshotDir, config)
+  const projection = {
+    description: local.description ?? null,
+    status: local.workflowState ?? null,
+    subIssues: Array.isArray(local.subIssues) ? local.subIssues : [],
+    // How many phases `mapping.phases: 'deferred'` is holding back. Reporting
+    // only — `snapshotOf`/`specIssueHash` read named fields, so this never
+    // reaches a hash and cannot make an unchanged spec look edited.
+    phasesWithheld: phasesWithheld(snapshotDir, config),
+    // The phase mode that resolved for THIS spec's bucket. Reporting only, on
+    // the same terms: a spec with no sub-issues has to read as deliberate rather
+    // than as phase files that failed to parse, and with `mapping.phases` now a
+    // per-bucket map, which mode applied is no longer readable off the config.
+    phaseMode: phaseModeFor(local.workflowState, config),
+  }
+  // ASSIGNEE IS SET ONLY WHEN THE FIELD IS IN PLAY, and the distinction between
+  // `undefined` and `null` is load-bearing all the way down: `undefined` means
+  // the repo never opted in, so no hash is recorded and no op is ever emitted;
+  // `null` means opted in with nobody assigned, which CAN legitimately clear a
+  // previously-pushed assignee. Defaulting the key to null here would collapse
+  // the two and make an un-opted-in repo start clearing assignees on its next
+  // push. `normalizeLocal` omits the key entirely when `sync.fieldOwnership`
+  // does not list it.
+  if ('assignee' in local) projection.assignee = local.assignee ?? null
+  return projection
+}
+
+function push({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  const snapshot = readBase(dir, identifier, config)
+  const plan = planChanges(projection, snapshot)
+  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
+  // plan above is all-creates and would abandon a live mirror. Carry the finding
+  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
+  // skill that applies this plan is exactly the consumer that would miss them.
+  const legacy = detectLegacyMirror({ dir, snapshotDir, identifier, config })
+  if (legacy) plan.legacy = legacy
+  // Same reasoning as `legacy`: carried ON THE PLAN, not as a stderr warning,
+  // because `--json` routes warnings to stderr and the skill applying the plan
+  // is the consumer that most needs to know the missing sub-issues are deliberate.
+  if (projection.phasesWithheld) plan.phasesDeferred = projection.phasesWithheld
+  // Always set, unlike the two above: the skill relaying this should not have to
+  // know that an absent field means `subissue`. `isEmptyPlan` and `snapshotOf`
+  // both read named fields, so an extra key cannot make a spec look edited.
+  plan.phaseMode = projection.phaseMode
+  return { ok: true, empty: isEmptyPlan(plan), plan, projection }
+}
+
+/**
+ * Record the last-pushed snapshot from the CURRENT files — call after the skill
+ * has applied the plan and stamped new ids. Returns the snapshot path.
+ */
+function recordPush({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  return writeBase(dir, identifier, config, snapshotOf(projection, config))
+}
+
+module.exports = { push, recordPush, projectionOf }

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

@@ -0,0 +1,278 @@
+'use strict'
+
+/**
+ * Retarget a mirror after the tracker's team key is renamed.
+ *
+ * Renaming a Linear team rewrites the key in every issue identifier
+ * (`SKI-7` → `SKS-7`). The repo stamps those identifiers in three places — spec
+ * frontmatter, the sync-base snapshot filenames, and the `subIssues` keys
+ * inside those snapshots — and nothing moves them, so afterwards every stamped
+ * spec is stale and `/spec-push` fails with `no issue found for SKI-7`.
+ *
+ * This module is the PURE half: it plans and applies a prefix move over the
+ * repo's machine-read fields. It is provider-neutral by design (decision 8) —
+ * "old prefix → new prefix over stamps and snapshots" involves no tracker at
+ * all, so it belongs here beside `legacy.js`. Detecting the rename and
+ * spot-checking an identifier are the only steps that touch a tracker, and they
+ * live in the provider's CLI.
+ *
+ * **Frontmatter only — never prose.** A naive repo-wide `SKI-` → `SKS-`
+ * substitution passes a casual eyeball and quietly rewrites the historical
+ * record ("Probe SKI-28 falsified the reported hypothesis").
+ * `.claude/rules/spec-planning.md` says never delete historical notes, so prose
+ * mentions, doc placeholders and test fixtures are out of scope entirely.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+
+const { parseFrontmatter, LIFECYCLE_BUCKETS: BUCKETS } = require('./normalize.js')
+const { fieldsOf } = require('./fields.js')
+
+// An issue identifier: team key, dash, number. Matched CASE-INSENSITIVELY
+// because the stamped url field carries the identifier lowercased in its path
+// (`…/issue/reu-188/retire-…`). Matching only uppercase left 29 of 33 real URLs
+// in a live repo pointing at the old key — the same ones the hand-repair
+// missed. A rewrite only happens when the key matches `oldKey`, so an unrelated
+// token like `utf-8` is never in scope.
+const IDENTIFIER_RE = /\b([A-Za-z][A-Za-z0-9]*)-(\d+)\b/g
+
+// The stamped identifier fields, from the provider's vocabulary.
+const stampFields = (config) => {
+  const f = fieldsOf(config)
+  return [f.identifier, f.issueId]
+}
+const SNAPSHOT_SUFFIX = '.base.json'
+
+// Every `.md` under each spec folder — overview and phase files alike, plus the
+// legacy bare `<name>.md` shape.
+function specMarkdownFiles(dir) {
+  const files = []
+  for (const bucket of BUCKETS) {
+    const root = path.join(dir, 'specs', bucket)
+    let entries
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const p = path.join(root, entry.name)
+      if (entry.isDirectory()) {
+        for (const f of fs.readdirSync(p)) if (f.endsWith('.md')) files.push(path.join(p, f))
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(p)
+      }
+    }
+  }
+  return files.sort()
+}
+
+const snapshotDirOf = (dir, config) => path.resolve(dir, config.sync.baseDir)
+
+function snapshotFiles(dir, config) {
+  try {
+    return fs.readdirSync(snapshotDirOf(dir, config)).filter((f) => f.endsWith(SNAPSHOT_SUFFIX)).sort()
+  } catch {
+    return []
+  }
+}
+
+// Rewrite `<oldKey>-<n>` → `<newKey>-<n>` in `text`, leaving every other
+// identifier alone. The number is preserved: a team rename does not renumber.
+function movePrefix(text, oldKey, newKey) {
+  const want = String(oldKey).toLowerCase()
+  return String(text).replace(IDENTIFIER_RE, (whole, key, n) => {
+    if (key.toLowerCase() !== want) return whole
+    // Preserve the case it was written in: a URL path segment stays lowercase,
+    // a frontmatter stamp stays uppercase.
+    const next = key === key.toLowerCase() ? newKey.toLowerCase() : newKey
+    return `${next}-${n}`
+  })
+}
+
+/**
+ * The recorded key this repo believes it is stamped with.
+ *
+ * `config.provider.teamKey` is authoritative when set — but it defaults to `""`
+ * and is written by `init-config` and never read, which is exactly why a stale
+ * key never failed loudly. So fall back to the prefix actually observed in the
+ * stamps. Disagreeing stamps are reported, never guessed at and never thrown:
+ * the caller phrases its own refusal.
+ *
+ * @returns {{key: string|null, source: 'config'|'stamps'|null, keys?: string[], reason?: string}}
+ */
+function deriveRecordedKey(dir, config) {
+  const configured = (config.provider && config.provider.teamKey) || ''
+  if (configured) return { key: configured, source: 'config' }
+
+  const keys = new Set()
+  for (const file of specMarkdownFiles(dir)) {
+    let raw
+    try {
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    const { data } = parseFrontmatter(raw)
+    for (const field of stampFields(config)) {
+      if (!data[field]) continue
+      const m = /^([A-Z][A-Z0-9]*)-\d+$/.exec(String(data[field]).trim())
+      if (m) keys.add(m[1])
+    }
+  }
+  for (const name of snapshotFiles(dir, config)) {
+    const m = /^([A-Z][A-Z0-9]*)-\d+$/.exec(name.slice(0, -SNAPSHOT_SUFFIX.length))
+    if (m) keys.add(m[1])
+  }
+
+  // BLIND SPOT: the scan sees `.md` frontmatter under the four lifecycle buckets
+  // and the snapshot filenames — nothing else. A stamp anywhere else (a spec
+  // parked outside a bucket, a non-markdown file) is invisible, so `no stamped
+  // identifiers` means "none where we looked". That is why it refuses instead of
+  // concluding the repo is unstamped: the caller stops, and a human looks.
+  const found = [...keys].sort()
+  if (found.length === 1) return { key: found[0], source: 'stamps' }
+  if (!found.length) return { key: null, source: null, keys: [], reason: 'no stamped identifiers found under specs/' }
+  return {
+    key: null,
+    source: null,
+    keys: found,
+    reason: `stamps disagree — found ${found.join(', ')}; set the provider config's team key to the recorded one`,
+  }
+}
+
+/**
+ * Plan the prefix move. Pure: reads the repo, writes nothing.
+ *
+ * @returns {{stamps: Array<{file, from, to}>, snapshots: Array<{file, from, to, keys}>, configKey: {from,to}|null}}
+ *   `stamps[].from`/`to` are whole file contents; the caller writes them as-is.
+ */
+function planRetarget({ dir, oldKey, newKey, config }) {
+  const stamps = []
+  for (const file of specMarkdownFiles(dir)) {
+    let raw
+    try {
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    // Scoped to the leading `---` block. Everything after it is prose and is
+    // returned byte-identical.
+    const m = /^(---\n[\s\S]*?\n---)([\s\S]*)$/.exec(raw)
+    if (!m) continue
+    const head = movePrefix(m[1], oldKey, newKey)
+    if (head === m[1]) continue
+    stamps.push({ file: path.relative(dir, file), from: raw, to: head + m[2] })
+  }
+
+  const snapshots = []
+  const prefix = `${oldKey}-`
+  for (const name of snapshotFiles(dir, config)) {
+    const ident = name.slice(0, -SNAPSHOT_SUFFIX.length)
+    let body
+    try {
+      body = JSON.parse(fs.readFileSync(path.join(snapshotDirOf(dir, config), name), 'utf-8'))
+    } catch {
+      continue
+    }
+    // The `subIssues` map is keyed BY IDENTIFIER, so a rename strands every key
+    // inside the file as well as the filename. The hashes are content-derived
+    // and stay valid — only the keys move.
+    const keys = {}
+    let rekeyed = false
+    for (const [k, hash] of Object.entries(body.subIssues || {})) {
+      const next = k.startsWith(prefix) ? `${newKey}-${k.slice(prefix.length)}` : k
+      if (next !== k) rekeyed = true
+      keys[next] = hash
+    }
+    const renamed = ident.startsWith(prefix) ? `${newKey}-${ident.slice(prefix.length)}${SNAPSHOT_SUFFIX}` : name
+    if (renamed === name && !rekeyed) continue
+    snapshots.push({ file: name, from: name, to: renamed, keys, body })
+  }
+
+  const recorded = (config.provider && config.provider.teamKey) || ''
+  const configKey = recorded && recorded !== newKey ? { from: recorded, to: newKey } : null
+
+  return { stamps, snapshots, configKey }
+}
+
+// True when a plan would change nothing.
+const isEmptyRetarget = (plan) => !plan.stamps.length && !plan.snapshots.length && !plan.configKey
+
+// `git status --porcelain` over `dir`: [] clean, the lines when dirty, null when
+// this is not a git repo.
+function dirtyPaths(dir) {
+  let out
+  try {
+    out = execFileSync('git', ['-C', dir, 'status', '--porcelain'], { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim()
+  } catch {
+    return null
+  }
+  return out ? out.split('\n') : []
+}
+
+// Move a file, preferring `git mv` so history follows it. Falls back to a plain
+// rename when the file is untracked (git mv refuses those) or git is absent.
+function moveFile(dir, from, to) {
+  try {
+    execFileSync('git', ['-C', dir, 'mv', from, to], { stdio: ['ignore', 'ignore', 'ignore'] })
+    return 'git mv'
+  } catch {
+    fs.renameSync(path.join(dir, from), path.join(dir, to))
+    return 'rename'
+  }
+}
+
+/**
+ * Apply a plan. Everything moves together — stamps, snapshot names, the keys
+ * inside them, and the config key — because a half-retargeted repo is harder to
+ * reason about than an un-retargeted one.
+ */
+function applyRetarget(plan, { dir, config }) {
+  const changed = { files: [], snapshots: [], configKey: false }
+
+  for (const s of plan.stamps) {
+    fs.writeFileSync(path.join(dir, s.file), s.to, 'utf-8')
+    changed.files.push(s.file)
+  }
+
+  const baseRel = config.sync.baseDir
+  for (const snap of plan.snapshots) {
+    // Re-key BEFORE the rename, so the path being written is the one the plan
+    // recorded.
+    const src = path.join(dir, baseRel, snap.from)
+    fs.writeFileSync(src, JSON.stringify({ ...snap.body, subIssues: snap.keys }, null, 2) + '\n', 'utf-8')
+    if (snap.to !== snap.from) {
+      const how = moveFile(dir, path.join(baseRel, snap.from), path.join(baseRel, snap.to))
+      changed.snapshots.push({ ...snap, how })
+    }
+  }
+
+  if (plan.configKey && config.provider && config.provider.configFile) {
+    // Textual, not parse-and-restringify: the config is hand-edited and carries
+    // ordering (and possibly comments) a JSON round-trip would discard. The
+    // file and the JSON key both come from the provider (`config.provider`).
+    const file = path.join(dir, config.provider.configFile)
+    const keyField = config.provider.teamKeyJsonField || 'teamKey'
+    const raw = fs.readFileSync(file, 'utf-8')
+    const re = new RegExp('("' + keyField + '"\\s*:\\s*")([^"]*)(")')
+    fs.writeFileSync(file, raw.replace(re, `$1${plan.configKey.to}$3`), 'utf-8')
+    changed.configKey = true
+  }
+
+  return changed
+}
+
+module.exports = {
+  planRetarget,
+  applyRetarget,
+  deriveRecordedKey,
+  isEmptyRetarget,
+  dirtyPaths,
+  movePrefix,
+  specMarkdownFiles,
+}

package/src/vendor/sync-core/src/task-block.js

@@ -0,0 +1,308 @@
+'use strict'
+
+// Task bullets in a phase file are hand-wrapped prose, not single lines:
+//
+//   - [x] Add the retry column to the outbox table, modelled on the existing
+//         queue: status, attempts, `nextAttemptAt`, …
+//
+// A Linear issue title is single-line, so the two representations differ by
+// wrapping alone. This module is the one place that converts between them:
+// `findTaskBlocks` reads wrapped bullets into logical tasks, `renderTaskBlock`
+// writes a logical task back out re-wrapped in the file's own style.
+//
+// Everything here is line-index based so callers can splice whole blocks.
+
+const DEFAULT_WIDTH = 80
+
+// Start of a task bullet. The continuation lines that follow are any indented,
+// non-empty lines that are not themselves a bullet or heading.
+//
+// The mark is ANY single character, not just ` `/`x`. Projects use `[~]` for
+// in-progress, `[>]` for deferred, `[-]` for dropped, and a parser that only
+// knew ` xX` matched none of them — so the whole bullet was claimed by no block
+// and vanished from the mirror (bug-phase-content-dropped). What the mark MEANS
+// is nobody's business here; it is carried through verbatim and re-emitted as
+// written. Only `x`/`X` counts as done (see `parseTaskLine`).
+const TASK_START_RE = /^([ \t]*)-\s*\[([^\]])\]\s*(.*)$/
+const CONTINUATION_RE = /^[ \t]+\S/
+const BLOCK_BREAK_RE = /^[ \t]*(?:[-*+]\s|\d+\.\s|#{1,6}\s|>|\||```)/
+// A list-marker line (unordered or ordered). Distinguished from other block
+// breaks because a wrapped continuation can legitimately begin with one.
+const LIST_MARKER_RE = /^[ \t]*(?:[-*+]|\d+\.)\s/
+// A checkbox bullet — unambiguously a task, so it always starts its own block,
+// at any indent. (A bare list marker is ambiguous; a checkbox never is.) Any
+// mark, matching TASK_START_RE.
+const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[^\]]\]/
+// A bare list bullet — no checkbox — captured with its marker so a sub-bullet
+// is re-rendered as the `-`/`*`/`1.` its author wrote.
+const BULLET_RE = /^([ \t]*)([-*+]|\d+\.)\s+(.*)$/
+
+function indentWidth(line) {
+  return line.length - line.trimStart().length
+}
+
+// Collect the wrapped continuation lines following the bullet opening at
+// `start`, seeded with the opener's own text. Shared by task bullets and plain
+// sub-bullets — both wrap the same way, and both stop at the first line that
+// belongs to something else.
+function collectContinuation(lines, start, hang, inFence, parts) {
+  let j = start + 1
+  for (; j < lines.length; j++) {
+    const l = lines[j]
+    if (!l.trim()) break
+    if (inFence[j]) break // a fence opening ends the bullet, never continues it
+    if (!CONTINUATION_RE.test(l)) break
+    if (BLOCK_BREAK_RE.test(l)) {
+      // Indent alone can't tell a nested child from a wrapped continuation —
+      // both sit at the hanging indent. The *marker* is the reliable signal:
+      //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
+      //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
+      //     sits exactly at the hang; shallower or deeper it's a real sub/
+      //     sibling list → break, and the caller's scan claims it as a block of
+      //     its own. (Keeping the at-hang continuation preserves the task's
+      //     stamped id, so the next push updates instead of creating a
+      //     duplicate issue.)
+      //   - headings, quotes, tables and fences always break.
+      if (CHECKBOX_RE.test(l)) break
+      if (!LIST_MARKER_RE.test(l) || indentWidth(l) !== hang) break
+    }
+    parts.push(l.trim())
+  }
+  return { end: j, parts }
+}
+
+// Mark every line that lies inside a fenced code block — the opening fence, its
+// content, and the closing fence all count as `true`. Line scanners that hunt
+// for markdown structure (task bullets, section headings) use this to ignore an
+// EXAMPLE of that structure shown inside a fence: a spec that documents a
+// checklist format in a ``` block must not have those example bullets harvested
+// as real tasks (and pushed as real tracker issues). Supports ``` and ~~~ fences
+// of any length ≥ 3; a closing fence is a bare marker (no info string) of the
+// same character and at least the opening length.
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false)
+  let open = null // the opening marker string (``` or ~~~ …), or null
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    if (open) {
+      mask[i] = true
+      if (/^(`{3,}|~{3,})$/.test(trimmed) && trimmed[0] === open[0] && trimmed.length >= open.length) {
+        open = null
+      }
+      continue
+    }
+    const m = /^[ \t]*(`{3,}|~{3,})/.exec(lines[i])
+    if (m) {
+      open = m[1]
+      mask[i] = true
+    }
+  }
+  return mask
+}
+
+// Collapse a wrapped bullet's lines into the single logical line the rest of the
+// sync engine (and Linear) works in.
+function collapse(text) {
+  return String(text).replace(/\s+/g, ' ').trim()
+}
+
+// Like `collapse`, but a word wrapped at a hyphen (`state-entry-with-`⏎
+// `assignment`) rejoins TIGHT — one compound — instead of gaining a space. Every
+// other break collapses to a single space. Use this wherever hand-wrapped prose
+// is flattened to one logical line, so a hard wrap at a hyphen isn't data loss.
+function collapseHyphenAware(text) {
+  return String(text)
+    .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+// Mark every character of `body` that lies inside an inline emphasis or link
+// span — `**bold**`, `*italic*`, `[text](url)` — so wrapping can avoid breaking
+// one across a line (Linear mangles a straddling `**`/`*`/link on save). Code
+// spans are exempt (Linear only rejoins them, harmlessly) but their contents are
+// neutralised first so a `*` inside code can't spoof an italic marker.
+function spanMask(body) {
+  const mask = new Array(body.length).fill(false)
+  // Neutralise code-span contents to same-length filler (indices stay aligned).
+  const chars = body.split('')
+  let m
+  const codeRe = /`[^`]*`/g
+  while ((m = codeRe.exec(body)) !== null) {
+    for (let i = m.index; i < m.index + m[0].length; i++) chars[i] = 'x'
+  }
+  let masked = chars.join('')
+  const cover = (re) => {
+    re.lastIndex = 0
+    let mm
+    while ((mm = re.exec(masked)) !== null) {
+      for (let i = mm.index; i < mm.index + mm[0].length; i++) mask[i] = true
+      if (mm[0].length === 0) re.lastIndex++
+    }
+  }
+  cover(/\*\*.+?\*\*/g) // bold
+  cover(/\[[^\]]*\]\([^)]*\)/g) // link
+  // Neutralise the bold/link spans already found, so their asterisks aren't
+  // reused when scanning for single-`*` italics.
+  const m2 = masked.split('')
+  for (let i = 0; i < mask.length; i++) if (mask[i]) m2[i] = 'x'
+  masked = m2.join('')
+  cover(/\*[^*]+?\*/g) // italic
+  return mask
+}
+
+/**
+ * Find every task bullet in `lines` as a logical block, plus the non-checkbox
+ * bullets that live inside a task's list subtree.
+ * @returns {Array<{start:number, end:number, indent:string, marker:string,
+ *   checkbox:boolean, mark:string|null, text:string}>}
+ *   `end` is exclusive. `text` is the collapsed single-line form, id included.
+ *   `checkbox` is false for a plain sub-bullet; its `mark` is then null and its
+ *   `marker` is the bullet it was written with (`-`, `*`, `1.` …).
+ */
+function findTaskBlocks(lines) {
+  const blocks = []
+  const inFence = fenceMask(lines)
+  // The marker indents of the task bullets whose list subtree is still open,
+  // outermost first. Without this the scan had no model of nesting at all: a
+  // bare bullet that dedented out of a nested checkbox belonged to nothing and
+  // was silently dropped, taking its wrapped continuations with it.
+  const open = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // A blank line alone doesn't close a subtree — a loose list is still a list.
+    // What closes it is a later line at or shallower than the task's own indent.
+    if (!line.trim()) continue
+    const indent = indentWidth(line)
+    while (open.length && indent <= open[open.length - 1]) open.pop()
+    if (inFence[i]) continue // an example bullet inside a ``` block is not a task
+
+    const t = TASK_START_RE.exec(line)
+    if (t) {
+      // The hanging indent: where the bullet's text starts (marker width). A
+      // wrapped continuation aligns exactly AT this column.
+      const { end, parts } = collectContinuation(lines, i, line.length - t[3].length, inFence, [t[3]])
+      blocks.push({
+        start: i,
+        end,
+        indent: t[1],
+        marker: '-',
+        checkbox: true,
+        // Case-folded for `x` (the one mark whose meaning we act on), otherwise
+        // verbatim — a project's `~`/`>`/`-` must round-trip as written.
+        mark: t[2].toLowerCase() === 'x' ? 'x' : t[2],
+        text: collapseHyphenAware(parts.join('\n')),
+      })
+      open.push(indent)
+      i = end - 1
+      continue
+    }
+
+    // A bare bullet is claimed ONLY inside an open task's subtree — there it is
+    // part of the task and must be re-rendered with it. Outside one it is
+    // ordinary prose, which the projection now passes through verbatim, so
+    // claiming it here would only re-wrap a list nobody asked us to touch.
+    if (!open.length) continue
+    const b = BULLET_RE.exec(line)
+    if (!b) continue
+    const { end, parts } = collectContinuation(lines, i, line.length - b[3].length, inFence, [b[3]])
+    blocks.push({
+      start: i,
+      end,
+      indent: b[1],
+      marker: b[2],
+      checkbox: false,
+      mark: null,
+      text: collapseHyphenAware(parts.join('\n')),
+    })
+    i = end - 1
+  }
+  return blocks
+}
+
+/**
+ * Render a logical task back into wrapped file lines, matching the surrounding
+ * style: `- [x] ` opener, continuations aligned under the text.
+ * @returns {string[]}
+ */
+// Wrap `body` (a single logical line) into file lines, emphasis-aware: a break is
+// only taken at a word gap that lies OUTSIDE every `**`/`*`/link span, so an
+// emphasis run never straddles a line (Linear mangles one that does). The first
+// line is prefixed with `firstPrefix`, continuations with `hang`. An over-width
+// single span overflows rather than being split.
+function wrapEmphasisAware(body, { firstPrefix = '', hang = '', width = DEFAULT_WIDTH } = {}) {
+  const mask = spanMask(body)
+  const words = body.split(' ')
+  // The index in `body` of the space that precedes each word.
+  const spaceBefore = []
+  let pos = 0
+  for (let k = 0; k < words.length; k++) {
+    if (k > 0) {
+      spaceBefore[k] = pos
+      pos += 1
+    }
+    pos += words[k].length
+  }
+
+  const out = []
+  let line = firstPrefix
+  let first = true
+  for (let k = 0; k < words.length; k++) {
+    const word = words[k]
+    // Break only at a safe gap; a gap inside a span overflows instead of
+    // splitting it (so an over-width single span stays whole on one line).
+    const canBreak = k > 0 && !mask[spaceBefore[k]]
+    if (!first && canBreak && line.length + 1 + word.length > width) {
+      out.push(line)
+      line = hang + word
+    } else {
+      line += (first ? '' : ' ') + word
+      first = false
+    }
+  }
+  out.push(line)
+  return out
+}
+
+function renderTaskBlock({ indent = '', done, text, id }, width = DEFAULT_WIDTH) {
+  const opener = `${indent}- [${done ? 'x' : ' '}] `
+  const hang = ' '.repeat(opener.length)
+  const body = collapse(text) + (id ? ` (${id})` : '')
+  return wrapEmphasisAware(body, { firstPrefix: opener, hang, width })
+}
+
+// Infer the wrap width a file already uses, so a rewrite doesn't reflow it to a
+// different column. Only *prose* lines count — a single wide table row or a long
+// line of fenced code would otherwise pull the whole file's prose to a wider
+// column than the author wrapped at. Falls back to the default when there's
+// nothing prose-like to learn from.
+function inferWidth(lines, fallback = DEFAULT_WIDTH) {
+  let inFence = false
+  const widths = []
+  for (const l of lines) {
+    if (/^[ \t]*```/.test(l)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    if (!l.trim()) continue
+    if (l.includes('|')) continue // table row
+    widths.push(l.length)
+  }
+  if (!widths.length) return fallback
+  const max = Math.max(...widths)
+  return max > 40 && max <= 120 ? Math.max(max, 60) : fallback
+}
+
+module.exports = {
+  fenceMask,
+  findTaskBlocks,
+  renderTaskBlock,
+  wrapEmphasisAware,
+  spanMask,
+  collapse,
+  collapseHyphenAware,
+  inferWidth,
+  DEFAULT_WIDTH,
+}