@skitterbyte/skitterspec-linear 10.0.1 → 10.2.0

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

@@ -16,6 +16,7 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { flattenNestedTables } = require('./tables.js')
 const { fenceMask, findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
 
 // --- markdown / frontmatter parsing -----------------------------------------
@@ -306,7 +307,10 @@ function phaseStateBucket(body) {
 // 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) {
-  const m = /^\[([ xX])\]\s*(.*)$/.exec(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()
@@ -319,44 +323,31 @@ function parseTaskLine(line) {
   return { id, text, done }
 }
 
-/**
- * Split a phase's task blocks into the `##` sections they were written under.
- *
- * The checklist used to be one flat list under a hardcoded `## Tasks`, so a
- * criterion written under `## Acceptance` arrived in the mirror as an ordinary
- * open task. Nothing was lost — it was just unreadable.
- *
- * Grouping is done by MAPPING blocks onto headings, not by re-parsing the body
- * section by section: `findTaskBlocks` tracks open task subtrees across a
- * continuous body, and slicing that body at every heading would change what a
- * block claims at a section boundary. A heading inside a fence is not a heading
- * (`fenceMask`), and the phase file's own `#` H1 is not a section.
- *
- * @returns {Array<{heading:string|null, tasks:string[]}>} in source order;
- *   `heading` is null for blocks that precede every heading, and a heading with
- *   no blocks under it never appears.
- */
-function groupTasksByHeading(lines, blocks, renderTask) {
-  const inFence = fenceMask(lines)
-  const headings = []
-  for (let i = 0; i < lines.length; i++) {
-    if (inFence[i]) continue
-    const m = /^(#{2,6})\s+(.*\S)\s*$/.exec(lines[i])
-    if (m) headings.push({ line: i, heading: `${m[1]} ${m[2]}` })
-  }
+// 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.
 
-  const groups = []
-  for (const b of blocks) {
-    let heading = null
-    for (const h of headings) {
-      if (h.line >= b.start) break
-      heading = h.heading
-    }
-    const last = groups[groups.length - 1]
-    if (last && last.heading === heading) last.tasks.push(renderTask(b))
-    else groups.push({ heading, tasks: [renderTask(b)] })
-  }
-  return groups
+// 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
@@ -381,25 +372,13 @@ function readPhaseFiles(snapshotDir) {
       // 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((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
+      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, and any inline `(KEY-123)` stamped on a legacy task
-      // line stripped — those ids were per-task issues we no longer create, and
-      // they read as noise in the mirror.
+      // the marker its author wrote.
       const lines = body.split('\n')
-      const renderTask = (b) => {
-        // `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.
-        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}`
-      }
       const blocks = findTaskBlocks(lines)
-      const tasks = blocks.map(renderTask)
-      const taskGroups = groupTasksByHeading(lines, blocks, renderTask)
+      const tasks = blocks.map(renderTaskBlockLine)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -414,7 +393,11 @@ function readPhaseFiles(snapshotDir) {
         emoji: headingEmoji(body),
         statusLine: phaseStatusLine(body),
         tasks,
-        taskGroups,
+        // 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,
       }
     })
 }
@@ -527,7 +510,7 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
     if (skip.has(heading)) continue
     parts.push(`## ${heading}\n\n${content}`.trim())
   }
-  return canonicalizeMarkdown(parts.join('\n\n')) || null
+  return flattenNestedTables(canonicalizeMarkdown(parts.join('\n\n'))) || null
 }
 
 // A phase sub-issue's description: its `**Goal:**` line, plus the phase's task
@@ -538,19 +521,127 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
 // 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) {
-  if (tasksMode !== 'checklist' || !phase.tasks.length) return phase.goal
-  const parts = []
-  if (phase.goal) parts.push(phase.goal, '')
-  // One section per source heading, in source order. Checkboxes written before
-  // any heading keep the `## Tasks` default, so a phase file with a single task
-  // section — every one in this repo's corpus but two — projects unchanged.
-  const groups = phase.taskGroups && phase.taskGroups.length ? phase.taskGroups : [{ heading: null, tasks: phase.tasks }]
-  groups.forEach((group, i) => {
-    if (i) parts.push('')
-    parts.push(group.heading || '## Tasks', '', ...group.tasks)
+function subIssueBody(phase, tasksMode, localOnlySections) {
+  if (tasksMode !== 'checklist') return flattenNestedTables(phase.goal)
+  return flattenNestedTables(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) {
+  if (!inlined.length) return description
+  const sections = inlined.map((phase) => {
+    const body = demoteHeadings(subIssueBody(phase, tasksMode, localOnlySections) || '', INLINE_PHASE_LEVEL - 1)
+    const heading = '#'.repeat(INLINE_PHASE_LEVEL) + ` ${phaseHeading(phase)}`
+    return body ? `${heading}\n\n${body}` : heading
   })
-  return parts.join('\n')
+  return [description, ...sections].filter(Boolean).join('\n\n') || null
 }
 
 /**
@@ -564,19 +655,119 @@ function bucketFromPath(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']
+
+// 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 { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
-  // Phases sync as sub-issues whenever `subIssues` is in the pushed projection,
-  // so strip the `## Phases` index from the description to avoid duplicating it
-  // (as prose AND as sub-issues) in the Linear mirror.
-  const phasesProjected = !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership)
   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: buildDescription(
-      title,
-      sections,
+    description: withInlinePhases(
+      buildDescription(
+        title,
+        sections,
+        config.sync.localOnlySections,
+        phasesCarriedBySubIssues ? ['Phases'] : [],
+      ),
+      inlined,
+      tasksMode,
       config.sync.localOnlySections,
-      phasesProjected ? ['Phases'] : [],
     ),
     // 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.
@@ -584,17 +775,32 @@ function normalizeLocal(snapshotDir, config) {
     // 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: phases
-      .filter((p) => p.name)
-      .map((p) => ({ id: p.id, ref: p.phase, name: p.name, goal: subIssueBody(p, tasksMode), state: p.state })),
-    // Status is the spec's lifecycle bucket. The folder is the source of truth;
-    // an explicit `spec_status` frontmatter key overrides it if present.
-    workflowState:
-      frontmatter.spec_status != null ? String(frontmatter.spec_status) : bucketFromPath(snapshotDir),
+    subIssues: projected.map((p) => ({
+      id: p.id,
+      ref: p.phase,
+      name: p.name,
+      goal: subIssueBody(p, tasksMode, config.sync.localOnlySections),
+      state: p.state,
+    })),
+    workflowState,
   }
   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 ------------------------------------------------------
 
 // Map a remote workflow-state name back to the local lifecycle bucket (the
@@ -758,6 +964,9 @@ function stateSuggestions(config, workspaceStates) {
 module.exports = {
   stateSuggestions,
   normalizeLocal,
+  phaseProjection,
+  phaseModeFor,
+  phasesWithheld,
   lintPhases,
   readSnapshot,
   parseFrontmatter,

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

@@ -15,7 +15,7 @@
  * Date.now(). `recordPush` writes the snapshot sidecar.
  */
 
-const { normalizeLocal } = require('./normalize.js')
+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')
@@ -30,6 +30,15 @@ function projectionOf(snapshotDir, config) {
     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),
   }
 }
 
@@ -43,6 +52,14 @@ function push({ dir, snapshotDir, identifier, config }) {
   // 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 }
 }
 

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

@@ -0,0 +1,102 @@
+'use strict'
+
+/**
+ * Flatten markdown tables that sit INSIDE a list item, because Linear corrupts
+ * them.
+ *
+ * Measured on probe SKI-28 (2026-08-28): when Linear renders a table nested in a
+ * list item, every **data** cell loses its first N characters, where N is the
+ * list-content indent Linear renders at — 3 per ordered-list level, 2 per bullet
+ * level — regardless of the indent the source used. Source indents 3, 4 and 6
+ * all lose exactly 3. The header row is never touched, column-0 tables never
+ * corrupt, and the column count is irrelevant. Real damage from the field: the
+ * auth header `X-Extraction-Key` was stored as `Extraction-Key`.
+ *
+ * The engine passes the table through byte-identically — this is Linear's
+ * parser, not ours — but the projection is the only place that can stop the
+ * markdown reaching it in a shape it mangles. So nested tables are re-emitted as
+ * shapes SKI-28 proved survive nesting unchanged:
+ *
+ *   - 2 columns  → a bullet list (`- a — b`), the key/value case, and the shape
+ *                  the reporter hand-repaired in production
+ *   - otherwise  → a fenced code block wrapping the original rows verbatim
+ *
+ * This shapes the PROJECTION only. Repo files are never rewritten: the source
+ * markdown is valid and renders correctly in GitHub and every editor.
+ */
+
+const { fenceMask } = require('./task-block.js')
+
+// A table row: optional indent, then a `|`-delimited line. We only ever act on
+// indented ones — a column-0 table (the `## Phases` index, every Impact map) is
+// rendered correctly by Linear and must project byte-identically.
+const ROW_RE = /^([ \t]+)\|(.*)\|[ \t]*$/
+// The separator under the header — `|---|:--:|`. Its presence is what makes the
+// block a table rather than prose that happens to contain pipes.
+const SEPARATOR_RE = /^[ \t]+\|[\s:|-]+\|[ \t]*$/
+
+// Split a row into cells on pipes that are OUTSIDE an inline-code span, so a
+// documented `` `a | b` `` alternation stays one cell instead of splitting.
+function splitCells(body) {
+  const cells = []
+  let cur = ''
+  let code = false
+  for (const ch of body) {
+    if (ch === '`') code = !code
+    if (ch === '|' && !code) {
+      cells.push(cur.trim())
+      cur = ''
+      continue
+    }
+    cur += ch
+  }
+  cells.push(cur.trim())
+  return cells
+}
+
+/**
+ * Rewrite every indented table in `md`. Returns the text unchanged when there is
+ * nothing nested to flatten.
+ * @param {string} md
+ * @returns {string}
+ */
+function flattenNestedTables(md) {
+  if (md == null) return md
+  const lines = String(md).split('\n')
+  const inFence = fenceMask(lines)
+  const out = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const header = ROW_RE.exec(lines[i])
+    // A table shown as an EXAMPLE inside a ``` block is documentation — often of
+    // this very bug — so it is left exactly as written.
+    if (!header || inFence[i] || !SEPARATOR_RE.test(lines[i + 1] || '')) {
+      out.push(lines[i])
+      continue
+    }
+
+    const indent = header[1]
+    const rows = [splitCells(header[2])]
+    const raw = [lines[i], lines[i + 1]]
+    let j = i + 2
+    for (; j < lines.length && !inFence[j]; j++) {
+      const row = ROW_RE.exec(lines[j])
+      if (!row) break
+      rows.push(splitCells(row[2]))
+      raw.push(lines[j])
+    }
+
+    if (rows[0].length === 2) {
+      // Header first, bolded: dropping it would lose content and inventing a
+      // caption would invent it.
+      out.push(`${indent}- **${rows[0][0]}** — **${rows[0][1]}**`)
+      for (const r of rows.slice(1)) out.push(`${indent}- ${r[0]} — ${r[1]}`)
+    } else {
+      out.push(`${indent}\`\`\``, ...raw, `${indent}\`\`\``)
+    }
+    i = j - 1
+  }
+  return out.join('\n')
+}
+
+module.exports = { flattenNestedTables, splitCells }

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

@@ -16,15 +16,23 @@ 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*(.*)$/
+//
+// 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.)
-const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[ xX]\]/
+// 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+(.*)$/
@@ -181,7 +189,9 @@ function findTaskBlocks(lines) {
         indent: t[1],
         marker: '-',
         checkbox: true,
-        mark: t[2].toLowerCase() === 'x' ? 'x' : ' ',
+        // 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)
@@ -189,9 +199,10 @@ function findTaskBlocks(lines) {
       continue
     }
 
-    // A bare bullet is claimed ONLY inside an open task's subtree. Outside one
-    // it is ordinary prose in the phase file: the projection is the task list,
-    // not the whole body, and widening it here would mirror a Notes section.
+    // 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