@skitterbyte/skitterspec-linear 7.0.1 → 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.1",
+  "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

@@ -83,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()
 }
@@ -378,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

@@ -26,6 +26,40 @@ 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}>}
@@ -62,16 +96,34 @@ function findTaskBlocks(lines) {
  * style: `- [x] ` opener, continuations aligned under the text.
  * @returns {string[]}
  */
-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})` : '')
+// 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 = opener
+  let line = firstPrefix
   let first = true
-  for (const word of body.split(' ')) {
-    if (!first && line.length + 1 + word.length > width) {
+  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 {
@@ -83,13 +135,42 @@ function renderTaskBlock({ indent = '', done, text, id }, width = DEFAULT_WIDTH)
   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. Falls back to the default when there's nothing to learn from.
+// 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) {
-  const widths = lines.filter((l) => l.trim()).map((l) => l.length)
+  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, collapse, inferWidth, DEFAULT_WIDTH }
+module.exports = {
+  findTaskBlocks,
+  renderTaskBlock,
+  wrapEmphasisAware,
+  spanMask,
+  collapse,
+  inferWidth,
+  DEFAULT_WIDTH,
+}