@skitterbyte/skitterspec-linear 7.0.0 → 7.0.2

package/assets/rules/spec-planning.md

@@ -190,3 +190,7 @@ queried directly.)
 - Never delete historical notes.
 - The spec file is the single source of truth for implementation progress.
 - Move specs between buckets with `git mv` to preserve history.
+- Never let inline emphasis or a link cross a hard line break — keep a whole
+  `**bold**`, `*italic*`, or `[text](url)` on one line (let it overflow the wrap
+  column rather than splitting it). Many round-tripping editors mangle a
+  `**`/`*`/link span that straddles a newline, so clean source avoids the churn.

package/bin/skitterspec-linear.js

@@ -10,6 +10,7 @@
 
 const { run } = require('../src/cli.js')
 const { specSync } = require('../src/vendor/linear/cli-sync.js')
+const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')
 
 async function main(argv) {
   const [cmd, ...rest] = argv
@@ -17,6 +18,10 @@ async function main(argv) {
     await specSync(rest)
     return
   }
+  if (cmd === 'spec-sanitise') {
+    process.exitCode = await specSanitise(rest)
+    return
+  }
   await run(argv)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/vendor/linear/cli-sanitise.js

@@ -0,0 +1,101 @@
+'use strict'
+
+/**
+ * `spec-sanitise` — a one-time maintenance pass over spec markdown.
+ *
+ * Rewrites files so no inline emphasis (`**bold**`, `*italic*`) or link text
+ * straddles a hard line break, and repairs any Linear-mangled `****` artifacts
+ * already committed. Hand-wrapped specs acquire straddles over time; Linear
+ * corrupts them on save, so this brings the corpus "inline" to round-trip cleanly.
+ *
+ * Dry-run by default (reports the files it WOULD change); pass `--write` to apply.
+ * Minimal-diff and idempotent — only paragraphs/items that actually straddle are
+ * reflowed (see sync-core `sanitizeSpecMarkdown`).
+ *
+ *   skitterspec-linear spec-sanitise [paths...] [--write] [--width N]
+ *
+ * Defaults to scanning `specs/`. Exit code 1 in dry-run when changes are pending
+ * (so it's CI-friendly), 0 once everything is clean.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { sanitizeSpecMarkdown } = require('../sync-core')
+
+// Recursively collect *.md files under a path (a file path is returned as-is).
+function collectMarkdown(target) {
+  const out = []
+  const walk = (p) => {
+    let st
+    try {
+      st = fs.statSync(p)
+    } catch {
+      return
+    }
+    if (st.isDirectory()) {
+      if (/(^|\/)(node_modules|\.git)$/.test(p)) return
+      for (const name of fs.readdirSync(p).sort()) walk(path.join(p, name))
+    } else if (st.isFile() && p.endsWith('.md')) {
+      out.push(p)
+    }
+  }
+  walk(target)
+  return out
+}
+
+function parseArgs(argv) {
+  const paths = []
+  let write = false
+  let width = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--write') write = true
+    else if (a === '--width') width = parseInt(argv[++i], 10)
+    else if (a === '--help' || a === '-h') return { help: true }
+    else paths.push(a)
+  }
+  if (!paths.length) paths.push('specs')
+  return { paths, write, width: Number.isFinite(width) ? width : null }
+}
+
+async function specSanitise(argv, { cwd = process.cwd(), out = process.stdout } = {}) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    out.write('Usage: skitterspec-linear spec-sanitise [paths...] [--write] [--width N]\n')
+    return 0
+  }
+
+  const files = new Set()
+  for (const p of opts.paths) for (const f of collectMarkdown(path.resolve(cwd, p))) files.add(f)
+
+  let changedFiles = 0
+  let totalFixes = 0
+  for (const file of [...files].sort()) {
+    const src = fs.readFileSync(file, 'utf-8')
+    const res = sanitizeSpecMarkdown(src, opts.width ? { width: opts.width } : {})
+    if (!res.changed) continue
+    changedFiles++
+    totalFixes += res.fixes
+    const rel = path.relative(cwd, file)
+    if (opts.write) {
+      fs.writeFileSync(file, res.text, 'utf-8')
+      out.write(`fixed  ${rel} (${res.fixes} span${res.fixes === 1 ? '' : 's'})\n`)
+    } else {
+      out.write(`would fix  ${rel} (${res.fixes} span${res.fixes === 1 ? '' : 's'})\n`)
+    }
+  }
+
+  if (!changedFiles) {
+    out.write(`spec-sanitise: clean — no straddling spans in ${files.size} file(s).\n`)
+    return 0
+  }
+  const verb = opts.write ? 'Fixed' : 'Would fix'
+  out.write(`\n${verb} ${totalFixes} span(s) across ${changedFiles} file(s).\n`)
+  if (!opts.write) {
+    out.write('Re-run with --write to apply. Review the diff before committing.\n')
+    return 1
+  }
+  return 0
+}
+
+module.exports = { specSanitise, collectMarkdown, parseArgs }

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

@@ -16,6 +16,7 @@ const { pull } = require('./src/pull.js')
 const { push } = require('./src/push.js')
 const { writeFrontmatter } = require('./src/write.js')
 const { frontmatterPatchFor, localWorkflowState } = require('./src/apply.js')
+const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 
 module.exports = {
   normalizeLocal,
@@ -32,4 +33,5 @@ module.exports = {
   writeFrontmatter,
   frontmatterPatchFor,
   localWorkflowState,
+  sanitizeSpecMarkdown,
 }

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

@@ -16,6 +16,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { findTaskBlocks, collapse } = require('./task-block.js')
 
 // --- markdown / frontmatter parsing -----------------------------------------
 
@@ -82,21 +83,123 @@ function parseSections(body) {
   return { title, sections }
 }
 
+// Linear mangles inline emphasis whose markers straddle a hard line break: it
+// terminates the run at end-of-line and restarts it at the next, so `**a\nb**`
+// comes back as `**a****\n****b**`, `*a\nb*` as `*a**\n**b*`, and a link splits
+// into two. Canonicalise BOTH representations — the clean straddle we author and
+// the mangled form Linear returns — to the same single-line span, so an
+// already-mangled remote stops reading as a spurious `remote-only` diff and the
+// payload we push carries no straddle for Linear to mangle again. Idempotent: a
+// joined span has no interior newline, so nothing re-fires. Repo files are never
+// rewritten — this only shapes the normalized projection the compare/push see.
+function joinEmphasisAcrossBreaks(text) {
+  let s = String(text)
+  // (1) Repair Linear's mangle artifacts first — an emphasis run terminated at
+  // end-of-line and restarted at the next. These are very specific asterisk runs
+  // flanking a break, so a targeted regex is safe:
+  //   bold:   `**X****\n****Y**` → the `****\n****` empty-bold artifact → a space.
+  s = s.replace(/\*{4}[ \t]*\n[ \t]*\*{4}/g, ' ')
+  //   italic: `*X**\n**Y*` — the `**\n**` artifact sits INSIDE a single-`*` span;
+  //   gate on the enclosing single `*` so a genuine pair of adjacent bolds at a
+  //   line boundary (`a**\n**b`) is left alone.
+  s = s.replace(/(^|[^*\n])\*([^*\n]+)\*\*[ \t]*\n[ \t]*\*\*([^*\n]+)\*(?![*])/g, '$1*$2 $3*')
+  //   link split across a break onto the same url → one link.
+  s = s.replace(/\[([^\]]+)\]\(([^)]+)\)[ \t]*\n[ \t]*\[([^\]]+)\]\(\2\)/g, '[$1 $3]($2)')
+  // (2) Join the clean straddle we author — a newline that falls while an
+  // emphasis/link span is OPEN. A scanner (not a regex) so an opening `**` is
+  // never mis-paired with an unrelated closing `**` on the next line, and markers
+  // inside a `code span` are ignored (Linear only rejoins those, harmlessly).
+  return joinOpenSpans(s)
+}
+
+// Walk the text tracking whether we're inside a `**bold**`, `*italic*`, `[link
+// text]`/`(url)`, or `` `code` `` span. A newline encountered while a
+// non-code span is open joins the two lines with a single space (dropping the
+// next line's indentation); every other newline is preserved.
+function joinOpenSpans(text) {
+  const out = []
+  let bold = false
+  let italic = false
+  let code = false
+  let link = 0 // 0 none · 1 in link text · 2 in url
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (c === '\n') {
+      if (!code && (bold || italic || link)) {
+        out.push(' ')
+        while (i + 1 < text.length && (text[i + 1] === ' ' || text[i + 1] === '\t')) i++
+      } else {
+        out.push('\n')
+      }
+      continue
+    }
+    if (c === '`') {
+      code = !code
+      out.push(c)
+      continue
+    }
+    if (code) {
+      out.push(c)
+      continue
+    }
+    if (c === '*' && text[i + 1] === '*') {
+      bold = !bold
+      out.push('**')
+      i++
+      continue
+    }
+    if (c === '*') {
+      // Basic flanking so a stray `*` (e.g. `2 * 3`) doesn't open a phantom span:
+      // an opener needs a non-space to its right, a closer a non-space to its left.
+      const ok = italic ? !/\s/.test(text[i - 1] || '') : !/\s/.test(text[i + 1] || '')
+      if (ok) italic = !italic
+      out.push(c)
+      continue
+    }
+    if (c === '[' && link === 0) {
+      link = 1
+      out.push(c)
+      continue
+    }
+    if (c === ']' && link === 1) {
+      if (text[i + 1] === '(') {
+        link = 2
+        out.push('](')
+        i++
+      } else {
+        link = 0
+        out.push(c)
+      }
+      continue
+    }
+    if (c === ')' && link === 2) {
+      link = 0
+      out.push(c)
+      continue
+    }
+    out.push(c)
+  }
+  return out.join('')
+}
+
 // Canonicalise markdown so semantically-equal content hashes equal across the
 // boundary. Linear reserializes markdown on save (authored `-` bullets come back
-// as `*`, trailing whitespace trimmed, blank runs collapsed), so without this a
-// clean push→pull would report `description` as perpetually changed. Applied to
-// the description on BOTH sides. Conservative: only unifies list markers and
-// whitespace — the transforms actually observed from Linear.
+// as `*`, trailing whitespace trimmed, blank runs collapsed, emphasis spanning a
+// line break mangled), so without this a clean push→pull would report
+// `description` as perpetually changed. Applied to the description on BOTH sides.
+// Conservative: only unifies list markers, whitespace, and emphasis-across-a-break
+// — the transforms actually observed from Linear.
 function canonicalizeMarkdown(text) {
   if (text == null) return text
-  return String(text)
+  const marked = String(text)
     .replace(/\r\n/g, '\n')
     .split('\n')
     // Unordered-list marker at line start (`*`/`+`/`-`) → `-`. Requires a space
-    // after the marker so bold/emphasis (`**Goal:**`) is untouched.
+    // after the marker so bold/emphasis (`**Goal:**`) is untouched. Done BEFORE
+    // the emphasis join so a `*` list bullet can't spoof an italic delimiter.
     .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
     .join('\n')
+  return joinEmphasisAcrossBreaks(marked)
     .replace(/\n{3,}/g, '\n\n')
     .trim()
 }
@@ -165,10 +268,15 @@ function readPhaseFiles(snapshotDir) {
     .map((file) => {
       const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
       const { data, body } = parseFrontmatter(raw)
-      const goal = (/^\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/m.exec(body) || [])[1] || ''
-      const tasks = (body.match(/^-\s*\[[ x]\]\s*.*$/gm) || []).map((t) =>
-        t.replace(/^-\s*/, '').trim(),
-      )
+      // 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 = collapse((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
+      const tasks = findTaskBlocks(body.split('\n')).map((b) => `[${b.mark}] ${b.text}`)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -372,5 +480,6 @@ module.exports = {
   parseTaskLine,
   canonicalRemoteStatus,
   canonicalizeMarkdown,
+  joinEmphasisAcrossBreaks,
   bucketForState,
 }

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

@@ -0,0 +1,147 @@
+'use strict'
+
+/**
+ * One-time sanitiser: rewrite spec markdown so no inline emphasis or link span
+ * straddles a hard line break, and repair any Linear-mangled `****` artifacts
+ * already committed. This brings hand-wrapped spec files "inline" so they round-
+ * trip through Linear cleanly (Linear mangles a straddling `**`/`*`/link on save).
+ *
+ * Deliberately minimal-diff: only a block that actually contains a straddle or a
+ * mangle is reflowed — every other paragraph, table, code fence, and heading is
+ * left byte-for-byte untouched. A reflowed block is re-wrapped emphasis-aware to
+ * the file's own inferred width, so spans stay whole. Idempotent: a second run is
+ * a no-op.
+ *
+ * Pure string→string (`sanitizeSpecMarkdown`); the CLI wraps it with fs walking.
+ */
+
+const {
+  wrapEmphasisAware,
+  collapse,
+  inferWidth,
+  DEFAULT_WIDTH,
+} = require('./task-block.js')
+const { joinEmphasisAcrossBreaks } = require('./normalize.js')
+
+// A run of non-blank lines contains an emphasis straddle / mangle iff joining
+// spans across breaks changes it.
+function hasStraddle(text) {
+  return joinEmphasisAcrossBreaks(text) !== text
+}
+
+// Turn a multi-line region into its clean single logical line: repair mangles and
+// join straddles first (needs the newlines), then collapse whitespace.
+function cleanLogicalLine(text) {
+  return collapse(joinEmphasisAcrossBreaks(text))
+}
+
+// A bullet line: indent, marker (`- `, `* `, `+ `, `1. `, optionally a `[ ]`/`[x]`
+// checkbox), then the text.
+const BULLET_RE = /^(\s*)((?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?)(.*)$/
+// Structural blocks we never reflow.
+const PASSTHROUGH_RE = /^\s*(#{1,6}\s|>|\||[-*_]{3,}\s*$|<)/
+// A GFM table separator row (only pipes/colons/dashes/spaces, with a pipe AND a
+// dash). Detecting a table by this — not by any stray `|` — so a pipe inside an
+// inline `code|span` doesn't make us treat a whole list as an untouchable table.
+const TABLE_SEP_RE = /^[\s|:-]*\|[\s|:-]*-[\s|:-]*$|^[\s|:-]*-[\s|:-]*\|[\s|:-]*$/
+
+// Split a block (consecutive non-blank lines) into items when it's a list; each
+// item is its bullet line plus more-indented continuation lines.
+function splitListItems(block) {
+  const items = []
+  let cur = null
+  for (const line of block) {
+    if (BULLET_RE.test(line)) {
+      cur = [line]
+      items.push(cur)
+    } else if (cur) {
+      cur.push(line) // continuation of the current bullet
+    } else {
+      return null // leading non-bullet line — not a clean list block
+    }
+  }
+  return items
+}
+
+// Reflow one bullet item (raw lines) to width, emphasis-aware. Returns the item's
+// lines unchanged when it carries no straddle.
+function sanitizeItem(itemLines, width) {
+  const raw = itemLines.join('\n')
+  if (!hasStraddle(raw)) return { lines: itemLines, fixed: false }
+  const m = BULLET_RE.exec(itemLines[0])
+  const indent = m[1]
+  const marker = m[2]
+  const firstPrefix = indent + marker
+  const hang = ' '.repeat(firstPrefix.length)
+  // Body = the item's text (first line after the marker + continuations).
+  const bodyRaw = [m[3], ...itemLines.slice(1)].join('\n')
+  const body = cleanLogicalLine(bodyRaw)
+  return { lines: wrapEmphasisAware(body, { firstPrefix, hang, width }), fixed: true }
+}
+
+// Reflow a plain prose paragraph (raw lines) to width, preserving its leading
+// indent. Unchanged when it carries no straddle.
+function sanitizeProse(block, width) {
+  const raw = block.join('\n')
+  if (!hasStraddle(raw)) return { lines: block, fixed: false }
+  const indent = (/^(\s*)/.exec(block[0]) || ['', ''])[1]
+  const body = cleanLogicalLine(raw)
+  return { lines: wrapEmphasisAware(body, { firstPrefix: indent, hang: indent, width }), fixed: true }
+}
+
+/**
+ * Sanitise one markdown document.
+ * @returns {{ text:string, changed:boolean, fixes:number }} fixes = blocks/items reflowed.
+ */
+function sanitizeSpecMarkdown(text, { width } = {}) {
+  const src = String(text)
+  const lines = src.split('\n')
+  const w = width || inferWidth(lines) || DEFAULT_WIDTH
+  const out = []
+  let i = 0
+  let fixes = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    // Fenced code — copy verbatim through the closing fence.
+    if (/^[ \t]*```/.test(line)) {
+      out.push(line)
+      i++
+      while (i < lines.length && !/^[ \t]*```/.test(lines[i])) out.push(lines[i++])
+      if (i < lines.length) out.push(lines[i++])
+      continue
+    }
+    if (!line.trim()) {
+      out.push(line)
+      i++
+      continue
+    }
+    // Gather a block of consecutive non-blank, non-fence lines.
+    let j = i
+    while (j < lines.length && lines[j].trim() && !/^[ \t]*```/.test(lines[j])) j++
+    const block = lines.slice(i, j)
+    i = j
+
+    // Never reflow structural blocks (headings, tables, quotes, rules, HTML).
+    if (PASSTHROUGH_RE.test(block[0]) || block.some((l) => TABLE_SEP_RE.test(l))) {
+      out.push(...block)
+      continue
+    }
+
+    const items = BULLET_RE.test(block[0]) ? splitListItems(block) : null
+    if (items) {
+      for (const it of items) {
+        const r = sanitizeItem(it, w)
+        out.push(...r.lines)
+        if (r.fixed) fixes++
+      }
+    } else {
+      const r = sanitizeProse(block, w)
+      out.push(...r.lines)
+      if (r.fixed) fixes++
+    }
+  }
+  const result = out.join('\n')
+  return { text: result, changed: result !== src, fixes }
+}
+
+module.exports = { sanitizeSpecMarkdown, hasStraddle }

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

@@ -0,0 +1,176 @@
+'use strict'
+
+// Task bullets in a phase file are hand-wrapped prose, not single lines:
+//
+//   - [x] Add `DbProcessEventOutbox` to `prisma/schema.prisma`, modelled on
+//         `DbNotificationOutbox`: 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.
+const TASK_START_RE = /^([ \t]*)-\s*\[([ xX])\]\s*(.*)$/
+const CONTINUATION_RE = /^[ \t]+\S/
+const BLOCK_BREAK_RE = /^[ \t]*(?:[-*+]\s|\d+\.\s|#{1,6}\s|>|\||```)/
+
+// 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()
+}
+
+// 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.
+ * @returns {Array<{start:number, end:number, indent:string, mark:string, text:string}>}
+ *   `end` is exclusive. `text` is the collapsed single-line form, id included.
+ */
+function findTaskBlocks(lines) {
+  const blocks = []
+  for (let i = 0; i < lines.length; i++) {
+    const m = TASK_START_RE.exec(lines[i])
+    if (!m) continue
+    const parts = [m[3]]
+    let j = i + 1
+    for (; j < lines.length; j++) {
+      const l = lines[j]
+      if (!l.trim()) break
+      if (!CONTINUATION_RE.test(l)) break
+      if (BLOCK_BREAK_RE.test(l)) break
+      parts.push(l.trim())
+    }
+    blocks.push({
+      start: i,
+      end: j,
+      indent: m[1],
+      mark: m[2].toLowerCase() === 'x' ? 'x' : ' ',
+      text: collapse(parts.join(' ')),
+    })
+    i = j - 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 = {
+  findTaskBlocks,
+  renderTaskBlock,
+  wrapEmphasisAware,
+  spanMask,
+  collapse,
+  inferWidth,
+  DEFAULT_WIDTH,
+}

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

@@ -18,6 +18,12 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const {
+  findTaskBlocks,
+  renderTaskBlock,
+  collapse,
+  inferWidth,
+} = require('./task-block.js')
 
 // Serialize a JS value as a YAML-ish frontmatter scalar. null/undefined → the
 // key is dropped (caller shouldn't pass those).
@@ -222,33 +228,31 @@ function applyMilestonesPull(snapshotDir, items) {
 
 // --- task-line denormalizer (keyed issue pull) -----------------------------
 //
-// Tasks live as checkbox lines inside phase files. A pulled issue edit rewrites
-// the matching line (by its inline id) in place; a Linear-only issue appends a
-// new task line; a created issue's id is stamped inline. Removals report-only.
+// Tasks live as (hand-wrapped) checkbox bullets inside phase files. A pulled
+// issue edit rewrites the matching bullet — whole block, re-wrapped — by its
+// inline id; a Linear-only issue appends a new bullet; a created issue's id is
+// stamped inline. Removals report-only. See task-block.js for the wrapping.
 
-const TASK_RE = /^(\s*)-\s*\[([ xX])\]\s*(.*)$/
 const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
 
-// Render a task line from an item.
-function taskLine(indent, { id, text, done }) {
-  return `${indent}- [${done ? 'x' : ' '}] ${text}${id ? ` (${id})` : ''}`
-}
-
-// Update the task line carrying inline id `id` (text + checkbox), in place.
+// Update the task carrying inline id `id` (text + checkbox), in place.
+//
+// Block-aware: a task bullet is hand-wrapped across several lines, so the whole
+// block is replaced and the new text re-wrapped in the file's own style. Editing
+// only the first line would strand its continuation lines as orphaned prose.
 function updateTaskLine(snapshotDir, id, { text, done }) {
   const want = String(id)
   for (const file of listPhaseFiles(snapshotDir)) {
     const p = path.join(snapshotDir, file)
     const lines = fs.readFileSync(p, 'utf-8').split('\n')
-    for (let i = 0; i < lines.length; i++) {
-      const m = TASK_RE.exec(lines[i])
-      if (!m) continue
-      const idm = INLINE_ID_RE.exec(m[3])
-      if (idm && idm[1] === want) {
-        lines[i] = taskLine(m[1], { id: want, text, done })
-        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
-        return true
-      }
+    const width = inferWidth(lines)
+    for (const b of findTaskBlocks(lines)) {
+      const idm = INLINE_ID_RE.exec(b.text)
+      if (!idm || idm[1] !== want) continue
+      const rendered = renderTaskBlock({ indent: b.indent, done, text, id: want }, width)
+      lines.splice(b.start, b.end - b.start, ...rendered)
+      fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+      return true
     }
   }
   return false
@@ -262,11 +266,10 @@ function addTaskLine(snapshotDir, item) {
   if (!file) return null
   const p = path.join(snapshotDir, file)
   const lines = fs.readFileSync(p, 'utf-8').split('\n')
-  let lastTask = -1
-  for (let i = 0; i < lines.length; i++) if (TASK_RE.test(lines[i])) lastTask = i
-  const line = taskLine('', item)
-  if (lastTask >= 0) lines.splice(lastTask + 1, 0, line)
-  else lines.push(line)
+  const blocks = findTaskBlocks(lines)
+  const rendered = renderTaskBlock({ indent: '', ...item }, inferWidth(lines))
+  if (blocks.length) lines.splice(blocks[blocks.length - 1].end, 0, ...rendered)
+  else lines.push(...rendered)
   fs.writeFileSync(p, lines.join('\n'), 'utf-8')
   return file
 }
@@ -274,18 +277,21 @@ function addTaskLine(snapshotDir, item) {
 // Stamp an inline id onto the (idless) task line whose text matches — used after
 // the skill creates an issue for a new local task.
 function stampIssueId(snapshotDir, text, id) {
-  const want = String(text).trim()
+  const want = collapse(text)
   for (const file of listPhaseFiles(snapshotDir)) {
     const p = path.join(snapshotDir, file)
     const lines = fs.readFileSync(p, 'utf-8').split('\n')
-    for (let i = 0; i < lines.length; i++) {
-      const m = TASK_RE.exec(lines[i])
-      if (!m || INLINE_ID_RE.test(m[3])) continue
-      if (m[3].trim() === want) {
-        lines[i] = `${m[1]}- [${m[2].toLowerCase() === 'x' ? 'x' : ' '}] ${want} (${id})`
-        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
-        return file
-      }
+    const width = inferWidth(lines)
+    for (const b of findTaskBlocks(lines)) {
+      if (INLINE_ID_RE.test(b.text)) continue
+      if (b.text !== want) continue
+      const rendered = renderTaskBlock(
+        { indent: b.indent, done: b.mark === 'x', text: want, id },
+        width,
+      )
+      lines.splice(b.start, b.end - b.start, ...rendered)
+      fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+      return file
     }
   }
   return null