@skitterbyte/skitterspec-linear 10.0.1 → 10.1.0

package/README.md

@@ -114,6 +114,22 @@ never clobbered. A workflow-state a teammate moves in Linear is surfaced by
 (`specs/.core/linear-base/`, content hashes) are committed so push sends only what
 changed.
 
+**Fidelity safeguards.** Linear's markdown parser silently drops characters from
+tables nested inside list items, so a nested table is reshaped before sending —
+2-column tables become a bullet list, others a code block — and column-0 tables
+are left alone. Your spec files are never modified. After a push, each stored
+description is read back and compared against what was sent, ignoring Linear's
+own reformatting and reporting anything genuinely lost. Both are automatic.
+
+**Adopting on a long backlog.** By default a spec costs one `save_issue` call
+plus one per phase, so mirroring a backlog that already runs to dozens of specs
+front-loads hundreds of calls for work nobody has started. Set
+`mapping.phases: "deferred"` and a spec sitting in `specs/backlog/` mirrors as
+**the issue alone**, keeping its phase list in the description; its sub-issues are
+created by the push that follows `/spec-go`, when the work actually starts. Phases
+that are already linked keep syncing either way, so switching an existing project
+over never strands a live sub-issue. See `linear.config.md` for the details.
+
 **Which Project a spec lands in** is asked once, when the issue is first created
 — a filterable list of your team's projects, defaulting to `linear.projectId` and
 always offering *None*. It's passed on the create call only and never stored, so

package/assets/core/linear.config.md

@@ -47,6 +47,10 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // "none" leaves the description as the phase's Goal line alone. Either way no
   // issue is created per task. These are the defaults.
   //
+  // `phases` selects WHEN a phase becomes a sub-issue: "subissue" from the
+  // spec's first push (default), or "deferred" only once the work starts — see
+  // "Deferring sub-issues until a spec starts" below.
+  //
   // Under "checklist" the mirror keeps the phase file's OWN section headings: a
   // phase with `## Tasks` and `## Acceptance` arrives as two headed sections, in
   // source order, each heading reproduced as written. Checkboxes written before
@@ -145,6 +149,70 @@ Unlinked local items (a spec with no `linear_identifier`, a phase with no
 `linear_issue_id`) are created in Linear on the next `/spec-push`, which stamps
 the new id back so they link from then on.
 
+## What is reshaped before sending, and what is checked afterwards
+
+Two safeguards sit either side of the push. Neither is configurable — both exist
+because Linear's markdown parser does not always store what it is given.
+
+**Nested tables are reshaped.** A markdown table written *inside* a list item is
+corrupted by Linear: every data cell loses its first N characters, N being the
+list-content indent Linear renders at (3 per ordered level, 2 per bullet),
+whatever indent the source used. The header row survives, which makes it easy to
+miss. Measured, not inferred — a table at source indent 3, 4 or 6 inside a
+numbered list loses exactly 3 characters per cell. So before sending, a nested
+table is re-emitted as a **bullet list** (2 columns) or a **fenced code block**
+(any other count), both of which round-trip byte-identically. Column-0 tables —
+the `## Phases` index, every Impact map — are never touched, and neither are
+tables inside a fenced example. **Your spec files are not modified**: the source
+markdown is valid and renders correctly in GitHub and every editor, so this
+shapes only the projection.
+
+**The round-trip is verified.** After `/spec-push` applies a plan it reads each
+description back and runs `spec-sync verify`, which compares word characters and
+ignores the reformatting Linear legitimately applies (renumbered ordered lists,
+`-`→`*`, collapsed table separators, checkbox case, whitespace). Anything lost or
+altered is reported with both sides of the first difference. It warns rather than
+fails — the repo is unaffected and re-pushing overwrites the mirror. This is not
+a pull: nothing read back is merged, stamped or written anywhere.
+
+## Deferring sub-issues until a spec starts
+
+`mapping.phases` decides *when* a phase becomes a sub-issue:
+
+- `"subissue"` (default) — from the spec's first push. A spec costs `1 + N`
+  `save_issue` calls to mirror, N being its phase count.
+- `"deferred"` — only once the work starts. A spec sitting in `specs/backlog/`
+  mirrors as **the issue alone**; its sub-issues are created by the push that
+  follows `/spec-go`.
+
+Deferral is worth setting when you adopt sync on a project that already has a
+long backlog, where the default means mirroring every phase of every spec nobody
+has started yet — in this repo, 130 calls where 35 would do.
+
+What defers and what does not:
+
+- **Unlinked phases defer; linked ones never do.** A phase already carrying a
+  `linear_issue_id` keeps projecting whatever the mode. One-way sync has no
+  delete, so withholding a live sub-issue would not remove it from Linear — it
+  would freeze it there, never updated again. That makes switching an existing
+  project to `"deferred"` safe: it only changes what has yet to be minted.
+- **The trigger is the spec's projected state**, not its folder alone — so a
+  `spec_status` frontmatter override moves the issue's state and its sub-issues
+  together. Phases defer while that state is `backlog` or `cancelled`; a spec
+  cancelled without ever starting never mints phases it never worked, while one
+  cancelled mid-flight has ids already and keeps them.
+- **A deferred spec keeps its `## Phases` index in the description.** That
+  section is normally stripped because the sub-issues carry it; while they are
+  withheld it is the only place the phase breakdown appears. It drops out of the
+  description in the same push that creates the sub-issues.
+- **`/spec-push` and `/spec-status` say so**, printing `N phase(s) deferred`, and
+  the JSON plan carries a `phasesDeferred` count — a spec with no sub-issues
+  reads as deliberate rather than as phase files that failed to parse.
+
+There is no snapshot state behind this and nothing to migrate: the last-pushed
+snapshot only ever recorded sub-issues that have an id, so a deferred phase is
+simply absent from it and arrives as an ordinary `create` when it projects.
+
 ## Which Project a spec issue belongs to
 
 `linear.projectId` is the **default**, not a mandate. When a spec issue is first

package/assets/skills/spec-go/SKILL.md

@@ -152,9 +152,16 @@ below. Follow the provider's steps below (nothing to do here without one).
   to bring down before building — the repo is already the source of truth. (A
   workflow-state a teammate moved in Linear is advisory only; `/spec-status`
   surfaces it. It is overwritten on the next push.)
-- **Optional: refresh the mirror.** If you want Linear to reflect the now
-  in-progress spec, run `/spec-push` to send it up. This is optional at
-  `/spec-go` time — the mirror can equally be refreshed later.
+- **Refresh the mirror.** Run `/spec-push` to send the now in-progress spec up.
+  Whether that is optional depends on `mapping.phases`:
+  - `"subissue"` (the default) — **optional**. The phase sub-issues already
+    exist; this push only moves their states. Refresh now or later.
+  - `"deferred"` — **do it now, without asking.** Under deferral a spec sitting
+    in the backlog is mirrored as the issue alone, and this push is what mints
+    its phase sub-issues. Skip it and a started spec stays mirrored as a
+    phase-less issue until someone happens to run `/spec-push` by hand. Run it
+    straight after the step-2 commit, so the sub-issues land with the same
+    branch push that fires the tracker's automation.
 - Linear's GitHub branch/PR automation may drive status transitions off the
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.

package/assets/skills/spec-push/SKILL.md

@@ -69,6 +69,12 @@ date — say so and stop. `state` values are local buckets
 (`backlog`/`in-progress`/`complete`/`cancelled`); map each to the Linear
 issue-state NAME via `config.states` at apply time.
 
+A **`phasesDeferred`** field means `mapping.phases` is `"deferred"` and this spec
+has not started, so its phases are deliberately absent from the plan — the issue
+pushes alone and the sub-issues are minted by the push that follows `/spec-go`.
+Relay the count; it is not a sign the phase files failed to parse. Nothing else
+about applying the plan changes.
+
 ### Stop if the plan reports a pre-9.0 mirror
 
 If the plan carries a **`legacy`** field, this spec was linked under the pre-9.0
@@ -97,6 +103,36 @@ migrated or explicitly confirms they want a new mirror.
 Priority, labels, cycles and comments are Linear-native triage — do **not** push
 them; they're the PM's.
 
+## 4b. Verify what Linear actually stored
+
+Linear reserialises markdown on save, and it does not always preserve what you
+sent — a table nested in a list item comes back with characters missing from
+every data cell, silently. Check before you record the push as good.
+
+For each issue you created or updated in step 4, read its `description` back
+(`get_issue`) and write what you got to a JSON file:
+
+```json
+{ "issue": "<stored description>", "subIssues": { "01-outbox": "<stored>" } }
+```
+
+Then:
+
+```
+skitterspec spec-sync verify <spec> --stored <file>
+```
+
+It compares against what the engine sent, ignoring the reformatting Linear
+legitimately applies (renumbered ordered lists, `-`→`*`, collapsed table
+separators, checkbox case, whitespace) and reporting only lost or altered **word
+characters**. Relay any divergence — it prints both sides around the first
+difference. It exits 0 either way: the repo is unaffected and still correct, so
+this is a warning, not a failure.
+
+This is **not a pull**. Nothing read here is merged, stamped, or written
+anywhere; the repo remains the only source of truth. Do it before step 5 so a
+corrupted push is visible before the snapshot records it as good.
+
 ## 5. Stamp the ids, then record the snapshot
 
 Write every id you collected back into the spec in **one** call — the engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.0.1",
+  "version": "10.1.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

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

@@ -41,6 +41,7 @@ const {
   writeFrontmatter,
   stampSubIssueId,
   listPhaseFiles,
+  compareStored,
 } = require('../sync-core')
 
 const { loadLinearConfig } = require('./config.js')
@@ -196,6 +197,7 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
   const p = r.plan
   const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
   if (p.legacy) lines.push(...legacyLines(p.legacy))
+  if (p.phasesDeferred) lines.push(...deferredLines(p.phasesDeferred))
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
     if (p.issue) lines.push('  issue: description/state')
@@ -207,6 +209,16 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
   return 0
 }
 
+// `mapping.phases: 'deferred'` is holding phases back. Said plainly wherever a
+// plan or a status report is printed, because the alternative reading of a spec
+// with no sub-issues is that its phase files failed to parse.
+function deferredLines(n) {
+  return [
+    `  ${n} phase(s) deferred — mapping.phases is "deferred" and this spec has not started`,
+    '     they are created on the push that follows /spec-go',
+  ]
+}
+
 // The pre-9.0 mirror block. Loud on purpose: the plan below it looks entirely
 // ordinary — an all-creates plan for a spec that reads as unlinked — and
 // applying it mints a second mirror and abandons the first.
@@ -404,6 +416,9 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   const projection = projectionOf(snapshotDir, config)
   const snapshot = readBase(dir, identifier, config)
   const plan = planChanges(projection, snapshot)
+  // From the projection, not the plan: `status` builds its plan with
+  // `planChanges` directly rather than going through `push`.
+  if (projection.phasesWithheld) lines.push(...deferredLines(projection.phasesWithheld))
   if (!snapshot) lines.push('  push: never pushed — everything is pending')
   else if (isEmptyPlan(plan)) lines.push('  push: up to date — nothing changed since the last push')
   else {
@@ -427,17 +442,86 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   return 0
 }
 
+/**
+ * `spec-sync verify <spec> --stored <file>` — compare what the tracker STORED
+ * against what we sent, and report any lost text.
+ *
+ * Not a pull: it merges nothing and writes nothing (see sync-core `verify.js`).
+ * The engine is offline, so `/spec-push` does the read over MCP and hands the
+ * result over in a file — the same split `--workspace-states` uses. The file is
+ * `{ "issue": "…", "subIssues": { "<ref>": "…" } }`; any key may be omitted.
+ *
+ * Warns, never fails (exit 0). The mirror is generated and disposable, and a
+ * hard failure after the plan is applied would strand it half-written.
+ */
+function specSyncVerify(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+  if (!flags.stored) {
+    out.write(
+      'spec-sync verify: refusing to run without --stored <file>.\n' +
+        '  The engine is offline: /spec-push reads each description back over MCP\n' +
+        '  and writes {"issue": "…", "subIssues": {"<ref>": "…"}} for this command.\n',
+    )
+    return 1
+  }
+  let stored
+  try {
+    stored = JSON.parse(fs.readFileSync(flags.stored, 'utf-8'))
+  } catch (error) {
+    out.write(`spec-sync verify: cannot read --stored ${flags.stored}: ${error.message}\n`)
+    return 1
+  }
+
+  const identifier = specIdentifier(snapshotDir, config)
+  const projection = projectionOf(snapshotDir, config)
+  const checks = []
+  if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
+  for (const [ref, text] of Object.entries(stored.subIssues || {})) {
+    const sub = projection.subIssues.find((s) => s.ref === ref)
+    if (!sub) {
+      checks.push([`sub-issue ${ref}`, null, text])
+      continue
+    }
+    checks.push([`sub-issue ${ref}`, sub.goal, text])
+  }
+
+  const lines = [`spec-sync verify: ${identifier}`]
+  let bad = 0
+  for (const [label, sent, got] of checks) {
+    if (sent == null) {
+      lines.push(`  ?? ${label}: read back, but the projection has no such phase — stale ref?`)
+      bad++
+      continue
+    }
+    const r = compareStored(sent, got)
+    if (r.ok) continue
+    bad++
+    lines.push(
+      `  !! ${label}: the tracker stored different text — ${Math.abs(r.lost)} character(s) ` +
+        `${r.lost > 0 ? 'lost' : 'added'}, first difference at ${r.at}`,
+      `     sent:   …${r.sentContext}…`,
+      `     stored: …${r.storedContext}…`,
+    )
+  }
+  if (!bad) lines.push(`  ${checks.length} description(s) round-tripped intact`)
+  else lines.push('     the repo is unchanged and still correct; re-push to overwrite the mirror')
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
 async function specSync(rest, io = {}) {
   const out = io.out || process.stdout
   const err = io.err || process.stderr
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [] }
+  const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
+    else if (args[i] === '--stored') flags.stored = path.resolve(args[++i])
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
     else if (args[i] === '--skip-state-check') flags.skipStateCheck = true
     else if (args[i] === '--issue') flags.issue = args[++i]
@@ -469,6 +553,8 @@ async function specSync(rest, io = {}) {
       return 0
     case 'status':
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
+    case 'verify':
+      return specSyncVerify(dir, config, positional[0], flags, out) || 0
     case 'linked':
       specSyncLinked(dir, config, flags, out)
       return 0
@@ -476,6 +562,7 @@ async function specSync(rest, io = {}) {
       out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
         '       skitterspec spec-sync push <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
         '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
+        '       skitterspec spec-sync verify <spec> --stored <file>\n' +
         '       skitterspec spec-sync linked [--json]\n')
       return 0
   }

package/src/vendor/linear/config.js

@@ -44,6 +44,17 @@ const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
 // box ticked in the tracker is overwritten by the next push.
 const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
 
+// When a phase becomes a sub-issue.
+//   subissue — always, from the spec's first push (default)
+//   deferred — only once the work starts: a spec sitting in `backlog` (or
+//              `cancelled` without ever having started) projects the issue
+//              alone, so adopting sync on a long backlog costs one call per
+//              spec instead of one per spec PLUS one per phase. A phase that
+//              already carries an id keeps projecting either way — one-way sync
+//              has no delete, so withholding a LINKED sub-issue would freeze it
+//              in the tracker rather than remove it.
+const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred'])
+
 const DEFAULT_CONFIG = Object.freeze({
   // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
   // first `/spec-push` offer the team's projects and pre-select this one; empty
@@ -201,6 +212,12 @@ function mergeConfig(base, parsed) {
           `(expected one of ${TASK_MAPPINGS.join('|')})`,
       )
     }
+    if (!PHASE_MAPPINGS.includes(base.mapping.phases)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: mapping.phases = ${JSON.stringify(base.mapping.phases)} ` +
+          `(expected one of ${PHASE_MAPPINGS.join('|')})`,
+      )
+    }
   }
 
   if (isObject(parsed.states)) {
@@ -266,4 +283,5 @@ module.exports = {
   CONFIG_FILE,
   OWNERSHIP,
   TASK_MAPPINGS,
+  PHASE_MAPPINGS,
 }

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

@@ -7,7 +7,10 @@
  * about any specific tracker. The repo is the source of truth: the engine builds
  * a local projection, diffs it against a committed last-pushed snapshot
  * (`planChanges`), and returns a create/update plan the provider skill applies
- * over its API. No remote content is read or merged.
+ * over its API. No remote content is read for CONTENT: nothing the tracker holds
+ * ever feeds the projection, the snapshot, or a repo file. `compareStored` is the
+ * one function that looks at a tracker value, and it only checks that what was
+ * stored matches what was sent — it merges nothing (see `src/verify.js`).
  */
 
 const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions } = require('./src/normalize.js')
@@ -17,6 +20,8 @@ const { push, recordPush, projectionOf } = require('./src/push.js')
 const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 const { detectLegacyMirror } = require('./src/legacy.js')
+const { compareStored } = require('./src/verify.js')
+const { flattenNestedTables } = require('./src/tables.js')
 
 module.exports = {
   normalizeLocal,
@@ -44,4 +49,6 @@ module.exports = {
   listPhaseFiles,
   sanitizeSpecMarkdown,
   detectLegacyMirror,
+  compareStored,
+  flattenNestedTables,
 }

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 -----------------------------------------
@@ -527,7 +528,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
@@ -539,7 +540,7 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
 // 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
+  if (tasksMode !== 'checklist' || !phase.tasks.length) return flattenNestedTables(phase.goal)
   const parts = []
   if (phase.goal) parts.push(phase.goal, '')
   // One section per source heading, in source order. Checkboxes written before
@@ -550,7 +551,7 @@ function subIssueBody(phase, tasksMode) {
     if (i) parts.push('')
     parts.push(group.heading || '## Tasks', '', ...group.tasks)
   })
-  return parts.join('\n')
+  return flattenNestedTables(parts.join('\n'))
 }
 
 /**
@@ -564,13 +565,57 @@ 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']
+
+/**
+ * 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 deferring =
+    (config.mapping && config.mapping.phases) === 'deferred' && UNSTARTED_BUCKETS.includes(workflowState)
+  const projected = deferring ? named.filter((p) => p.id != null) : named
+  return { projected, withheld: named.length - projected.length }
+}
+
 function normalizeLocal(snapshotDir, config) {
   const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
+  const tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
+  // Status is the spec's lifecycle bucket. The folder is the source of truth; an
+  // explicit `spec_status` frontmatter key overrides it if present. Resolved
+  // BEFORE the sub-issue projection because deferral withholds phases by this
+  // status — so the issue's state and its sub-issues always agree on whether the
+  // work has started, however that status was arrived at.
+  const workflowState = specStatus(snapshotDir, frontmatter)
+  const { projected, withheld } = phaseProjection(phases, workflowState, 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'
+  // (as prose AND as sub-issues) in the Linear mirror. While deferral is holding
+  // a phase back, that index is the ONLY place the phase appears — stripping it
+  // too would leave a backlog issue with no phase breakdown at all — so it stays
+  // until the sub-issues arrive to replace it.
+  const phasesProjected =
+    !!(config.sync.fieldOwnership && 'subIssues' in config.sync.fieldOwnership) && withheld === 0
   const extracted = {
     description: buildDescription(
       title,
@@ -584,17 +629,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),
+      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 +818,8 @@ function stateSuggestions(config, workspaceStates) {
 module.exports = {
   stateSuggestions,
   normalizeLocal,
+  phaseProjection,
+  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 } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
 const { detectLegacyMirror } = require('./legacy.js')
@@ -30,6 +30,10 @@ 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),
   }
 }
 
@@ -43,6 +47,10 @@ 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
   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/verify.js

@@ -0,0 +1,83 @@
+'use strict'
+
+/**
+ * Compare what Linear STORED against what we sent, and report lost text.
+ *
+ * Why this is not a pull. One-way sync's rule is about **authority**: Linear
+ * must never influence repo content. This reads a description back to *check*
+ * it — it merges nothing, writes nothing, and feeds nothing into the projection
+ * or the snapshot. The repo remains the only source of truth; the only output is
+ * a warning for a human. Without it, a parser that silently eats characters
+ * produces a mirror that looks pushed and is wrong, which is exactly how the
+ * nested-table corruption went unnoticed (see `tables.js`).
+ *
+ * The engine is offline, so the read itself belongs to the `/spec-push` skill —
+ * it fetches over MCP and hands the result here, the same split
+ * `--workspace-states` already uses.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+
+// Linear reserialises markdown on save. These transforms are all observed and
+// all harmless, so they are normalised away BEFORE comparing — otherwise every
+// push would report a false divergence.
+function canonicalForCompare(text) {
+  return String(text == null ? '' : text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) =>
+      line
+        // Ordered-list markers → a placeholder. Linear renumbers lists, and the
+        // digits it rewrites are alphanumeric, so a naive alphanumeric compare
+        // would flag its own benign reformat as data loss. Normalising the
+        // marker keeps digits significant EVERYWHERE ELSE — a port, a version, a
+        // key length still count.
+        .replace(/^(\s*)\d+\.(\s)/, '$1#.$2')
+        // Unordered markers unify (`-`/`+` come back as `*`).
+        .replace(/^(\s*)[*+-](\s)/, '$1-$2')
+        // Checkbox marks case-fold. Targeted rather than lowercasing the whole
+        // text, so a genuine case corruption in prose is still caught.
+        .replace(/^(\s*-\s*\[)[xX](\])/, '$1x$2')
+        // Table separator rows collapse (`|-------|` → `| -- |`).
+        .replace(/^\s*\|[\s:|-]+\|\s*$/, '|--|')
+        .replace(/[ \t]+$/, ''),
+    )
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+// The word-character stream: everything that carries meaning, with every
+// reformatting artefact (whitespace, bullets, asterisk boundaries, pipes,
+// separators) removed. Comparing these catches dropped characters while
+// ignoring every benign transform above.
+function stream(text) {
+  return canonicalForCompare(text).replace(/[^\p{L}\p{N}]/gu, '')
+}
+
+/**
+ * @param {string} sent    what we pushed
+ * @param {string} stored  what the tracker returned
+ * @returns {{ok:boolean, at:number|null, lost:number, sentContext:string, storedContext:string}}
+ *   `ok` false means word characters differ — content was lost or altered.
+ *   `at` is the index in the reduced stream where they first diverge, with ~40
+ *   characters of each side around it so the warning names the damage.
+ */
+function compareStored(sent, stored) {
+  const a = stream(sent)
+  const b = stream(stored)
+  if (a === b) return { ok: true, at: null, lost: 0, sentContext: '', storedContext: '' }
+
+  let at = 0
+  while (at < a.length && at < b.length && a[at] === b[at]) at++
+  const window = (s) => s.slice(Math.max(0, at - 10), at + 30)
+  return {
+    ok: false,
+    at,
+    lost: a.length - b.length,
+    sentContext: window(a),
+    storedContext: window(b),
+  }
+}
+
+module.exports = { compareStored, canonicalForCompare, stream }