@skitterbyte/skitterspec-linear 10.0.0 → 10.1.0

package/MIGRATION.md

@@ -1,5 +1,68 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec-linear` v9 → v10 (`push` validates your issue states)
+
+**`spec-sync push` now refuses to run until the configured `states` names have
+been checked against your Linear workspace.** The check itself is not new — it
+already existed on `spec-sync status --workspace-states` — but it was advisory,
+and skipping it sent a state name Linear **silently ignores**: the description
+lands, the issue never moves, and nothing errors. The base
+`@skitterbyte/skitterspec` is unaffected.
+
+### Breaking change
+
+| | v9 | v10 |
+|---|-----|-----|
+| `spec-sync push <spec>` | runs | **exits 1** unless `--workspace-states <file>` or `--skip-state-check` is passed |
+| A configured state absent from the workspace | pushed, silently no-op | **exits 1**, naming the workspace's real states |
+
+`/spec-push` handles this for you — it fetches the workspace's issue
+workflow-state names over MCP and passes them on. **Nothing changes if you drive
+sync through the skill.** Only a direct CLI caller needs updating.
+
+### What to do
+
+1. **Using `/spec-push`?** Nothing. Run `update` and carry on.
+2. **Calling `spec-sync push` from CI or a script?** Supply the workspace's issue
+   workflow-state names as a JSON array and pass the file:
+
+   ```sh
+   # names come from your Linear workspace, e.g. via the MCP server or the API
+   echo '["Backlog","Todo","In Progress","Done","Canceled"]' > states.json
+   skitterspec spec-sync push my-spec --workspace-states states.json --json
+   ```
+
+   Or opt out deliberately with `--skip-state-check`. Don't reach for it to get
+   past a *failing* check — that check is the only thing standing between you and
+   a push that moves nothing.
+3. **If the check refuses,** it tells you what your workspace actually has and,
+   where the lifecycle bucket makes it unambiguous, which name to use:
+
+   ```
+   spec-sync push: refusing — configured state name(s) not in the workspace
+
+     states.complete: "Done" is not an issue state in this workspace
+       use "Completed" instead
+
+     available: Backlog, Todo, In Progress, Completed, Canceled
+   ```
+
+   Fix `specs/.core/linear.config.json` → `states`. `/spec-push` will offer to
+   apply the fix for you.
+
+### Also in v10 (not breaking)
+
+- **A pre-9.0 mirror is detected before it can be orphaned.** A spec still
+  carrying `linear_project_id` / `linear_milestone_id` reads as unlinked to v9+,
+  so `push` would emit an all-creates plan and abandon the live mirror. The plan
+  now carries a `legacy` field naming how many objects that would strand, and
+  `/spec-push` stops. **If you skipped the v8 → v9 migration below, read it now** —
+  this is the guard that catches you, not a substitute for it.
+- **`update` says what it skipped** — each `customized (kept)` file now reports
+  `+added −removed`, with `--diff` to see the upstream changes you declined.
+- **This guide now ships inside the package** (it wasn't in the published tarball
+  before v10 — `files` listed only `bin`/`src`/`assets`).
+
 ## `@skitterbyte/skitterspec-linear` v8 → v9 (a spec is an Issue, phases are sub-issues)
 
 **v9 remaps the Linear mirror.** A spec is now a Linear **issue** (not a Project),
@@ -48,6 +111,79 @@ phase**. The base `@skitterbyte/skitterspec` is unaffected (still v15).
 5. **Task-level issues** created under v8 are no longer managed by the sync —
    close or repurpose them in Linear by hand.
 
+## `@skitterbyte/skitterspec-linear` v7 → v8 (sync goes one-way; `/spec-pull` removed)
+
+**v8 made sync one-way.** The repo became the sole source of truth and Linear a
+**generated mirror**: content is pushed up, never read back or merged. The
+three-way merge engine and everything that fed it were retired.
+
+### Breaking changes
+
+| Area | v7 | v8 |
+|------|-----|-----|
+| Skills | `/spec-status`, `/spec-push`, **`/spec-pull`** | `/spec-status`, `/spec-push` |
+| `spec-sync` subcommands | `normalize`, `push`, `status`, **`pull`** | `normalize`, `push`, `status`, **`record`** |
+| Sidecar | a three-way merge base | the **last-pushed snapshot** (`record` writes it) |
+| `sync.fieldOwnership` | `pull` / `both` values were load-bearing | still parsed; nothing is pulled |
+
+### What to do
+
+1. **Drop `/spec-pull` from any workflow that calls it.** There is no
+   replacement: editing the mirror in Linear is no longer an input. A person
+   editing the issue will see it overwritten by the next push.
+2. **Replace `spec-sync pull` in scripts with `spec-sync record`** — it writes the
+   snapshot from the current repo files after a push is applied.
+3. **Delete stale merge-base sidecars** under `sync.baseDir`; the first push after
+   upgrading writes the new snapshot format.
+
+## `@skitterbyte/skitterspec-linear` v1 → v7 (no breaking changes)
+
+Every major in this range was a **routine version bump**, not a breaking
+contract. The skills (`/spec-status`, `/spec-push`, `/spec-pull`) and the
+`spec-sync` subcommands (`normalize`, `push`, `pull`, `status`) were identical at
+v1 and at v7. Upgrading anywhere inside this range needs **no action** beyond
+re-running `update`.
+
+One thing did change quietly, at **v4**: `sync.fieldOwnership` lost its
+`milestones`, `phaseBodies`, `acceptanceCriteria` and `taskBreakdown` entries when
+that detail moved inside `description`. A config still listing them does not
+error — unknown keys merge in and *join the compared set* — so remove them if
+you have them, or they will be compared against fields that no longer exist.
+
+## `@skitterbyte/skitterspec` v3 → v16 (no breaking changes)
+
+**Nothing in this range requires action.** Thirteen majors sounds like thirteen
+migrations; it was one habit. Every release in this period was cut as a major
+bump regardless of size (see `RELEASING.md`), and the base package's contract
+never broke: **no skill was ever removed and no CLI flag was ever removed** — the
+surface only grew. The spec folder layout
+(`.core`/`backlog`/`in-progress`/`complete`/`cancelled`) is unchanged throughout.
+
+The `feat(sync)!` commits that appear in this window changed
+`@skitterbyte/skitterspec-linear`, which ships separately; the base was bumped
+alongside it in lockstep. If you are on the **superset**, read the provider
+entries above — those are the ones with work in them.
+
+What each major actually added, so you can see what you gain by upgrading:
+
+| Major | What landed |
+|-------|-------------|
+| v4 | `setup` commands bootstrap a fresh worktree's dependencies |
+| v5, v6 | version bumps only |
+| v7 | release docs refreshed; stale scripts dropped |
+| v8 | version bump only |
+| v9 | released alongside the provider's Linear body round-trip |
+| v10, v11 | version bumps only |
+| v12 | install manifest + `update --resync` / `--reset`; **`/spec-live`** overlay |
+| v13 | **`/spec-hotfix`**, **`/spec-to-main`**, `spec-env prune` for orphaned test DBs |
+| v14 | **Impact map** in the spec templates; live-aware `/spec-go`; the docs site |
+| v15 | released alongside the provider's one-way sync switch |
+| v16 | spec `Name:` handle; `/spec-complete` · `/spec-cancel` commit their own edits |
+
+**Spec files written under an older version still read.** The template grew
+(the Impact map at v14, the `Name:` header at v16) but the lifecycle skills treat
+both as optional — `/spec-review` adds them if you want them.
+
 ## `@skitterbyte/skitterspec` v2 → v3 (slimmer surface + local traffic diversion)
 
 **v3 shrinks the everyday command surface to five verbs — `spec → go → connect →

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/SETUP.md

@@ -14,16 +14,25 @@ team) that the config reference (`linear.config.md`) assumes you already have.
 
 ---
 
-## Upgrading from 8.x
-
-**v9 remapped the mirror.** A spec is now an **issue** (was a Project), a phase a
-**sub-issue** (was a Milestone), and tasks are no longer objects. The frontmatter
-keys moved with it, so a spec linked under 8.x reads as **unlinked** to v9 — the
-next `/spec-push` would mint a fresh mirror and abandon the old one.
-
-`spec-sync push` detects this and refuses to let the plan be applied blind, but
-read **`MIGRATION.md`** ("v8 → v9", shipped with the package) before upgrading a
-repo with a live mirror. Fresh installs can skip this section.
+## Upgrading an existing install
+
+Fresh installs can skip this section. **`MIGRATION.md` ships with the package** —
+read the entry for the version you are coming from before upgrading a repo with a
+live mirror.
+
+**From 9.x — `push` now validates your issue states.** `spec-sync push` refuses
+to run until the configured `states` names have been checked against the
+workspace. `/spec-push` does that for you, so nothing changes if you drive sync
+through the skill; a script calling the CLI directly must pass
+`--workspace-states <file>` (or `--skip-state-check`). See `MIGRATION.md`
+→ "v9 → v10".
+
+**From 8.x — the mirror was remapped.** A spec is now an **issue** (was a
+Project), a phase a **sub-issue** (was a Milestone), and tasks are no longer
+objects. The frontmatter keys moved with it, so a spec linked under 8.x reads as
+**unlinked** — the next `/spec-push` would mint a fresh mirror and abandon the old
+one. `push` detects this and refuses to let the plan be applied blind, but read
+`MIGRATION.md` → "v8 → v9" first.
 
 ## 1. Install the package
 

package/assets/core/linear.config.md

@@ -46,6 +46,17 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // that sub-issue: "checklist" mirrors them into its description (default),
   // "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
+  // any heading appear under `## Tasks`. A heading with no checkboxes under it
+  // is not mirrored. Nesting, sub-bullets and inline formatting are preserved;
+  // a legacy inline `(KEY-123)` on a task line is stripped.
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",
@@ -138,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.0",
+  "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 -----------------------------------------
@@ -319,6 +320,46 @@ 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]}` })
+  }
+
+  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
+}
+
 // Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
 // linked milestone id (from optional frontmatter), title, goal and tasks.
 function readPhaseFiles(snapshotDir) {
@@ -347,7 +388,8 @@ function readPhaseFiles(snapshotDir) {
       // 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.
-      const tasks = findTaskBlocks(body.split('\n')).map((b) => {
+      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
@@ -355,7 +397,10 @@ function readPhaseFiles(snapshotDir) {
         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)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -370,6 +415,7 @@ function readPhaseFiles(snapshotDir) {
         emoji: headingEmoji(body),
         statusLine: phaseStatusLine(body),
         tasks,
+        taskGroups,
       }
     })
 }
@@ -482,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
@@ -494,11 +540,18 @@ 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, '')
-  parts.push('## Tasks', '', ...phase.tasks)
-  return parts.join('\n')
+  // 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)
+  })
+  return flattenNestedTables(parts.join('\n'))
 }
 
 /**
@@ -512,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,
@@ -532,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
@@ -706,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 }