@skitterbyte/skitterspec-linear 8.0.0 → 8.0.2

package/README.md

@@ -1,10 +1,10 @@
 # @skitterbyte/skitterspec-linear
 
 Spec-driven development for [Claude Code](https://claude.com/claude-code), **with
-Linear hybrid-sync**. A strict **superset** of
+one-way Linear sync**. A strict **superset** of
 [`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
-everything in the base filesystem workflow, plus git-like sync between a spec and
-its linked Linear project.
+everything in the base filesystem workflow, plus one-way sync from a spec up to
+its linked Linear project — the repo is canonical, Linear is a generated mirror.
 
 ```sh
 npx @skitterbyte/skitterspec-linear init
@@ -46,27 +46,26 @@ fuller guide):
    That file is the opt-in gate — until it exists, everything below is inert and
    the package behaves exactly like the base.
 
-4. **Link and sync** — `/spec` now creates a linked Linear Project (a Milestone
-   per phase) and stamps the id; then `/spec-status`, `/spec-pull`, `/spec-push`
-   keep the spec and its project in step. Optionally turn on the per-Milestone /
-   per-Issue **body round-trip** (see below).
+4. **Link and push** — `/spec` creates a linked Linear Project (a Milestone per
+   phase) and stamps the id; then `/spec-push` publishes the spec up and
+   `/spec-status` reports what would push. Sync is **one-way**: the repo is the
+   source of truth and Linear is a generated mirror.
 
 ## What the superset adds
 
 On top of the base skills (`/spec`, `/spec-go`, isolation, …):
 
-- **`/spec-status`** — read-only, per-field divergence (local-only / remote-only /
-  conflict / in-sync). Changes nothing.
-- **`/spec-pull [--force]`** — Linear → repo. Applies remote-only fields; refuses
-  to clobber a conflicting local edit unless `--force`.
-- **`/spec-push [--force]`** — repo → Linear. Ownership-respecting,
-  concurrency-checked; refuses if Linear moved since base unless `--force`.
+- **`/spec-status`** — read-only drift report: what the next push would create /
+  update, plus any workflow-state drift. Changes nothing.
+- **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
+  last-pushed snapshot and applies only what changed (project description +
+  status, milestones, issues), stamping the returned ids back into the spec.
 - **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
   engine behind the skills, for CI / local runs.
 
 The shared `/spec` and `/spec-go` skills come composed with the Linear steps
-filled in: `/spec` links a new spec to a Linear Project (a Milestone per phase),
-and `/spec-go` pulls first so you build against the current shared state.
+filled in: `/spec` links a new spec to a Linear Project (a Milestone per phase).
+There is no pull — the repo is already canonical, so `/spec-go` just builds.
 
 ## Opt-in
 
@@ -78,16 +77,15 @@ behaves exactly like the base.
 setup guide — connecting the `linear` MCP server, finding your team id, linking a
 spec, and a smoke test. Per-field docs live in `specs/.core/linear.config.md`.
 
-**What syncs:** by default the whole spec body travels as the Linear Project
-**`description`** (co-authored, push + pull); **status / priority / labels** are
-Linear-owned (pull only). **Field ownership** (`both` / `pull` / `push`) collapses
-conflicts — only a `both` field that moved on both sides is a real conflict, and
-`--force` backs up the losing side before winning. **Opt into a per-Milestone /
-per-Issue body round-trip** — phases ↔ Linear Milestones and tasks ↔ Issues,
-compared per item — by adding `milestones`/`tasks` to `sync.keyedFields` (see the
-"Body round-trip" section of `linear.config.md`); deletions there are report-only.
-**Base sidecars** (`specs/.core/linear-base/`) are committed; **backups**
-(`specs/.core/linear-backups/`) are gitignored.
+**What pushes:** the spec body travels as the Linear Project **`description`**,
+phases as **Milestones**, tasks as **Issues** (a short first-sentence title, the
+full task text as the description), and the lifecycle bucket sets the project's
+**workflow state**. Priority, labels, cycles and comments are **Linear-native
+triage** — the PM's to set in Linear; one-way sync neither pushes nor reads them,
+so they're never clobbered. A workflow-state a teammate moves in Linear is
+surfaced by `/spec-status` as drift and overwritten on the next push. **Last-pushed
+snapshots** (`specs/.core/linear-base/`, content hashes) are committed so push
+sends only what changed.
 
 Branch naming that embeds the Linear id lives in the isolation config
 (`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:

package/assets/core/SETUP.md

@@ -168,3 +168,9 @@ With a linked spec, confirm push end-to-end:
   (`Backlog / Planned / In Progress / Completed / Canceled`).
 - **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
   workspace. Remove and re-add the server to authenticate against another.
+- **Bold around an inline code span renders oddly in Linear** — Linear moves the
+  closing `**` before an inline code span on save (`**no unresolved `` `X` ``**`
+  → `**no unresolved** `` `X` ``). This is a Linear rendering quirk in the mirror
+  only; it never touches your repo (one-way sync never reads content back), so
+  it's cosmetic. Avoid wrapping a whole phrase that ends in code in bold if the
+  mirror's rendering matters to you.

package/assets/core/linear.config.json.example

@@ -23,12 +23,11 @@
   },
   "sync": {
     "baseDir": "specs/.core/linear-base",
-    "backupDir": "specs/.core/linear-backups",
     "fieldOwnership": {
-      "description": "both",
-      "workflowState": "pull",
-      "priority": "pull",
-      "labels": "pull"
+      "description": "push",
+      "milestones": "push",
+      "tasks": "push",
+      "workflowState": "push"
     },
     "localOnlySections": ["State log", "Changelog", "Open questions"],
     "keyedFields": {}

package/assets/core/linear.config.md

@@ -61,101 +61,69 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     "pattern": "{type}/{slug}"
   },
 
-  // The three-way merge engine's on-disk state.
+  // One-way push engine state.
   "sync": {
-    // Committed base sidecar dir: the last-synced snapshot per spec, as
-    // {baseDir}/{identifier}.base.json. Committed so each worktree carries its
-    // own base and the divergence check stays accurate.
+    // Committed last-pushed snapshot dir: content hashes of the last push per
+    // spec, as {baseDir}/{identifier}.base.json. Committed so each worktree
+    // carries its own, and push knows what changed without reading Linear back.
     "baseDir": "specs/.core/linear-base",
 
-    // Backup-before-force lands the about-to-be-clobbered side here (the
-    // reflog). --force never destroys without first writing a copy.
-    "backupDir": "specs/.core/linear-backups",
-
-    // Per-field sync direction — collapses which fields can ever conflict:
-    //   "both" — co-authored: push + pull, may conflict (both moved off base).
-    //   "pull" — Linear→local only (e.g. status/priority); a local edit never
-    //            pushes and a conflict resolves to remote-wins.
-    //   "push" — local→Linear only; a remote edit never pulls and a conflict
-    //            resolves to local-wins.
-    // Any field key you add here joins the compared field set; a value outside
-    // both|pull|push is rejected at load time. The default set is scoped to the
-    // fields that round-trip through the live skill today: the whole spec body
-    // travels as `description`; status/priority/labels are Linear-owned (pull).
-    // A phase/milestone or per-issue round-trip is a future extension — opt in by
-    // adding `milestones`/`phaseBodies`/`taskBreakdown` here once that write path
-    // exists (see the deferred body write-back note in the package README).
+    // The pushed projection field set (repo → Linear, one-way). The `push` marker
+    // is retained for shape; there is no pull. The default set is the project
+    // `description`, `milestones` (one per phase), `tasks` (one issue each), and
+    // the lifecycle `workflowState`. Priority, labels, cycles and comments are
+    // Linear-native triage — deliberately NOT here, so a PM's triage is never
+    // touched. Any key you add joins the pushed projection.
     "fieldOwnership": {
-      "description": "both",
-      "workflowState": "pull",
-      "priority": "pull",
-      "labels": "pull"
+      "description": "push",
+      "milestones": "push",
+      "tasks": "push",
+      "workflowState": "push"
     },
 
     // Markdown sections of 00-overview.md that are local-only scaffolding and
     // are stripped from the pushed `description` (never sent to Linear).
     "localOnlySections": ["State log", "Changelog", "Open questions"],
 
-    // OPT-IN body round-trip. Map a keyed collection field → its item id key to
-    // sync it per item (each phase ↔ a Milestone, each task ↔ an Issue) instead of
-    // as one description blob. Empty by default. See "Body round-trip" below.
+    // Reserved. Milestones and tasks are always projected per item (each phase →
+    // a Milestone, each task → an Issue), so this no longer needs setting; it is
+    // validated but unused. Leave it `{}`.
     "keyedFields": {}
   }
 }
 ```
 
-## Body round-trip (milestones & tasks) — opt-in
+## Phases → Milestones, tasks → Issues
 
-By default the whole spec body travels as the project **`description`**. Opt a
-workspace into a finer-grained, bidirectional sync by adding the keyed fields:
+Push maps the spec's structure to Linear's, keyed by id so it updates rather than
+recreates:
 
-```jsonc
-"sync": {
-  "fieldOwnership": { "milestones": "both", "tasks": "both" },
-  "keyedFields": { "milestones": "id", "tasks": "id" }
-}
-```
-
-With this on:
-
-- **Phases ↔ Milestones.** Each phase file maps to a Linear Milestone. The link id
-  lives in the phase file's frontmatter (`linear_milestone_id`); its title ← the
+- **Phases → Milestones.** Each phase file maps to a Linear Milestone. The link id
+  lives in the phase file's frontmatter (`linear_milestone_id`); its name ← the
   phase h1, its description ← the phase `**Goal:**` line. The `Phases` index is
-  then stripped from the pushed `description` (no duplication).
-- **Tasks ↔ Issues.** Each `- [ ]` task line maps to a Linear Issue. The link id
-  is carried **inline** on the line — `- [ ] do the thing (SKI-123)`. Text ↔ the
-  issue title; `[x]`/`[ ]` ↔ a completed / non-completed issue state.
-- **Per-item merge.** Items are compared by id, so editing milestone A locally and
-  milestone B in Linear both apply; only the *same* item moving on both sides is a
-  conflict.
-- **Deletions are report-only.** A phase/milestone or task/issue removed on either
-  side is surfaced by `/spec-status` (and the pull/push summaries) for you to
-  resolve by hand — it is never auto-deleted.
+  stripped from the pushed `description` (no duplication).
+- **Tasks → Issues.** Each `- [ ]` task line maps to a Linear Issue. The link id
+  is carried **inline** on the line — `- [ ] do the thing (SKI-123)`. The issue
+  **title** is the task's first sentence; the **description** is the full task
+  text; `[x]`/`[ ]` ↔ a completed / non-completed issue state.
 
 Unlinked local items (a new phase with no `linear_milestone_id`, a task with no
 inline id) are created in Linear on the next `/spec-push`, which stamps the new id
 back so they link from then on.
 
-## Field ownership & conflicts
-
-The spec is a set of structured fields, most written by only one side. Marking a
-field's owner collapses which fields can genuinely conflict:
-
-- A `pull` field (Linear owns it) never reports as **pushable** — a stray local
-  edit is informational and gets reverted on the next pull.
-- A `push` field (the repo owns it) never reports as **pullable**.
-- Only a `both` field where **both** sides moved off the committed base is a real
-  `conflict` — `/spec-push` / `/spec-pull` refuse it unless `--force` (which
-  backs up the losing side into `sync.backupDir` first).
+## One direction — nothing to reconcile
 
-After any successful pull/push/force the engine **rewrites the base** so the next
-three-way compare starts clean.
+The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
+current spec against the committed **last-pushed snapshot** and sends only what
+changed — creates for unlinked items, updates for changed ones. A workflow-state a
+teammate moves in Linear is surfaced by `/spec-status` as **drift** (advisory) and
+overwritten on the next push. Priority, labels, cycles and comments are
+Linear-native triage and are never touched. No base merge, no conflicts, no
+`--force`.
 
 ## What to commit
 
-- **`sync.baseDir`** (default `specs/.core/linear-base/`) — **commit it.** The base
-  sidecar is the last-synced snapshot the three-way merge compares against; each
-  worktree carries its own base, so it must travel with the branch.
-- **`sync.backupDir`** (default `specs/.core/linear-backups/`) — **gitignore it.**
-  These are `--force` recovery copies (a local reflog), per-machine and not shared.
-  Add `specs/.core/linear-backups/` to your `.gitignore`.
+- **`sync.baseDir`** (default `specs/.core/linear-base/`) — **commit it.** The
+  last-pushed snapshot is content hashes of the last push, so `/spec-push` knows
+  what changed without reading Linear back; each worktree carries its own, so it
+  must travel with the branch.

package/assets/skills/spec/SKILL.md

@@ -217,11 +217,11 @@ finish as above.
 ## Phase E — link to a ticketing provider (only if one is installed)
 
 **Only when a ticketing provider is installed and configured** (it ships the
-`/spec-push` · `/spec-pull` · `/spec-status` skills and a provider config under
+`/spec-push` · `/spec-status` skills and a provider config under
 `specs/.core/`). If none is present, skip this phase entirely — the spec stays
 local-only and `/spec` behaves exactly as above. When a provider is present, link
 the spec to the tracker after writing it, so status and discussion live there
-while the repo stays the co-authoring surface — follow the provider's link steps
+while the repo stays the source of truth — follow the provider's link steps
 below (nothing to do here without one).
 
 **Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).

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

@@ -129,12 +129,11 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
-## 3b. Pull from the tracker first (only if a provider is installed)
+## 3b. Sync with the tracker (only if a provider is installed)
 
-**Only when a ticketing provider with a `/spec-pull` skill is installed** and the
-spec is linked to the tracker. Otherwise skip this step — no provider means zero
-change to the flow below. Follow the provider's pull steps below (nothing to do
-here without one).
+**Only when a ticketing provider is installed** and the spec is linked to the
+tracker. Otherwise skip this step — no provider means zero change to the flow
+below. Follow the provider's steps below (nothing to do here without one).
 
 **Only when `specs/.core/linear.config.json` exists** and the spec carries a
 `linear_project_id`. Otherwise skip this step — no config means zero change.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "8.0.0",
-  "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
+  "version": "8.0.2",
+  "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",
     "claude-code",

package/src/init.js

@@ -259,6 +259,30 @@ function removeRetiredFiles(dir) {
   }
 }
 
+// Prune a file the manifest records as managed but the current package no longer
+// ships — a retired skill (e.g. `spec-pull` after the one-way switch), rule, or
+// template. Without this, upgrading leaves a live, model-visible skill on disk
+// whose instructions invoke a command that no longer exists. Delete it only when
+// PRISTINE (still matches the hash we last wrote) so a user edit is never lost; a
+// customized retired file is kept with a warning. An emptied skill folder is
+// removed. Takes the pre-flush manifest (which still holds the retired entries).
+function pruneRetiredManaged(dir, manifest) {
+  const managedRel = new Set(managedTargets(dir).map((t) => t.relPath))
+  for (const relPath of Object.keys(manifest.files || {})) {
+    if (managedRel.has(relPath)) continue // still shipped by this version
+    const abs = path.join(dir, relPath)
+    if (!fs.existsSync(abs)) continue // already gone
+    if (managedState(dir, relPath, manifest) === 'customized') {
+      report.warnings.push(`retired but kept (you edited it): ${relPath} — delete manually if unused`)
+      continue
+    }
+    fs.unlinkSync(abs)
+    report.removed.push(rel(dir, abs))
+    const folder = path.dirname(abs)
+    if (fs.existsSync(folder) && !fs.readdirSync(folder).length) fs.rmdirSync(folder)
+  }
+}
+
 // Scaffold the opt-in isolation templates into specs/.core/ (the example config
 // + its field docs). Copied, not activated: the feature stays off until the
 // consumer copies env.config.json.example → env.config.json.
@@ -409,6 +433,7 @@ function resync(dir, { force = false, claudeMd = true } = {}) {
   for (const t of managedTargets(dir)) resyncManagedFile(dir, t, manifest, force)
   installFolders(dir)
   removeRetiredFiles(dir)
+  pruneRetiredManaged(dir, manifest)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
   printReport(dir, 'resync')

package/src/vendor/linear/config.js

@@ -1,8 +1,8 @@
 'use strict'
 
 /**
- * Config loader for the Linear hybrid-sync feature (`/spec-status`, `/spec-pull`,
- * `/spec-push` and the Linear-aware paths of `/spec` and `/spec-go`).
+ * Config loader for the one-way Linear sync feature (`/spec-status`, `/spec-push`
+ * and the Linear-aware paths of `/spec` and `/spec-go`).
  *
  * Reads `specs/.core/linear.config.json` from the project root and normalises it
  * over frozen defaults. The feature is strictly opt-in: when the file is absent
@@ -54,21 +54,17 @@ const DEFAULT_CONFIG = Object.freeze({
   sync: Object.freeze({
     baseDir: 'specs/.core/linear-base',
     backupDir: 'specs/.core/linear-backups',
-    // The synced field set. Kept to the fields that genuinely round-trip through
-    // the live skill today: the project `description` (co-authored) plus the
-    // Linear-owned status/priority/labels (pull-only). A spec's phase/milestone,
-    // acceptance-criteria and task detail still travel *inside* `description` — a
-    // separate milestone/issue round-trip is a future extension (add the fields
-    // here to opt a workspace in). Any key you add joins the compared set.
-    // One-way (repo → Linear): every field is repo-owned and pushed. The
-    // `push` marker is kept for the projection field-set; there is no pull.
+    // One-way (repo → Linear): the projection field set the repo owns and pushes
+    // — the project `description`, `milestones` (one per phase), `tasks` (one
+    // issue each), and the lifecycle `workflowState`. There is no pull. Priority,
+    // labels, cycles and comments are Linear-native triage — deliberately NOT in
+    // the set, so the PM's triage is never touched. The `push` marker is retained
+    // for shape; any key you add joins the pushed projection.
     fieldOwnership: Object.freeze({
       description: 'push',
       milestones: 'push',
       tasks: 'push',
       workflowState: 'push',
-      priority: 'push',
-      labels: 'push',
     }),
     localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
     // Fields that are keyed collections (arrays of objects with a stable id),

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

@@ -346,13 +346,16 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
  */
 function normalizeLocal(snapshotDir, config) {
   const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
-  const milestonesKeyed = !!(config.sync.keyedFields && config.sync.keyedFields.milestones)
+  // Phases sync as first-class Milestones whenever `milestones` is in the pushed
+  // projection, so strip the `## Phases` index from the description to avoid
+  // duplicating it (as prose AND as milestones) in the Linear mirror.
+  const milestonesProjected = !!(config.sync.fieldOwnership && 'milestones' in config.sync.fieldOwnership)
   const extracted = {
     description: buildDescription(
       title,
       sections,
       config.sync.localOnlySections,
-      milestonesKeyed ? ['Phases'] : [],
+      milestonesProjected ? ['Phases'] : [],
     ),
     // Milestone projection items. `ref` is the phase-file basename — the local
     // handle the push skill stamps a newly-created milestone id back into.
@@ -430,6 +433,19 @@ function remoteWorkflowState(project, config) {
   return name != null ? bucketForState(name, config) : null
 }
 
+// Trim a trailing parenthetical whose opener has no matching close — so a cut
+// title never ends on a dangling `(`/`[`.
+function dropUnclosedBracket(t) {
+  for (const [open, close] of [
+    ['(', ')'],
+    ['[', ']'],
+  ]) {
+    const o = t.lastIndexOf(open)
+    if (o !== -1 && t.indexOf(close, o) === -1) t = t.slice(0, o)
+  }
+  return t
+}
+
 // Derive a short Linear issue title from a task's full text: the first sentence,
 // falling back to the first `max` chars at a word boundary. A paragraph-length
 // task keeps its full text as the issue *description* (see the projection); this
@@ -454,8 +470,23 @@ function titleFromText(text, max = 100) {
   title = title.trim()
   if (title.length > max) {
     const cut = title.slice(0, max)
-    const sp = cut.lastIndexOf(' ')
-    title = (sp > 40 ? cut.slice(0, sp) : cut).trim()
+    // Prefer the last clause boundary before the limit — a terminator/separator
+    // to cut AFTER (`.`/`;`/`:`…) or a dash to cut BEFORE — over a bare word break.
+    const minCut = Math.floor(max * 0.4)
+    let boundary = -1
+    let mm
+    const after = /[.!?;:](?=\s|$)/g
+    while ((mm = after.exec(cut)) !== null) boundary = Math.max(boundary, mm.index + 1)
+    const before = /\s[—–]/g
+    while ((mm = before.exec(cut)) !== null) boundary = Math.max(boundary, mm.index)
+    let t
+    if (boundary > minCut) {
+      t = cut.slice(0, boundary)
+    } else {
+      const sp = cut.lastIndexOf(' ')
+      t = sp > 40 ? cut.slice(0, sp) : cut
+    }
+    title = dropUnclosedBracket(t).replace(/[\s.,:;—–([]+$/, '').trim()
   }
   return title
 }

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

@@ -36,6 +36,29 @@ function cleanLogicalLine(text) {
 const BULLET_RE = /^(\s*)((?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?)(.*)$/
 // Structural blocks we never reflow.
 const PASSTHROUGH_RE = /^\s*(#{1,6}\s|>|\||[-*_]{3,}\s*$|<)/
+// A line that is its own structural block — a blockquote (`>`) or a table/pipe
+// row (`|`). A hard boundary a join must never reach across (else the markers get
+// absorbed into the preceding paragraph as literal text); copied verbatim.
+const STRUCT_LINE_RE = /^[ \t]*[>|]/
+// A fenced-code delimiter.
+const FENCE_RE = /^[ \t]*```/
+
+// A structural fingerprint of a document: the count of block-marker lines that a
+// safe reflow must leave untouched. Used as a self-check — if sanitising changes
+// any of these, the reflow corrupted structure (a blockquote absorbed, a fence
+// eaten, a bullet collapsed) and the write is refused. Cheap insurance against the
+// next corruption class, not just the ones we special-case.
+function structuralSignature(text) {
+  let struct = 0 // blockquote or pipe-row lines
+  let fence = 0
+  let bullets = 0
+  for (const l of String(text).split('\n')) {
+    if (STRUCT_LINE_RE.test(l)) struct++
+    if (FENCE_RE.test(l)) fence++
+    if (BULLET_RE.test(l)) bullets++
+  }
+  return `${struct}|${fence}|${bullets}`
+}
 // A GFM table separator row (only pipes/colons/dashes/spaces, with a pipe AND a
 // dash). Detecting a table by this — not by any stray `|` — so a pipe inside an
 // inline `code|span` doesn't make us treat a whole list as an untouchable table.
@@ -99,21 +122,28 @@ function sanitizeSpecMarkdown(text, { width } = {}) {
   while (i < lines.length) {
     const line = lines[i]
     // Fenced code — copy verbatim through the closing fence.
-    if (/^[ \t]*```/.test(line)) {
+    if (FENCE_RE.test(line)) {
       out.push(line)
       i++
-      while (i < lines.length && !/^[ \t]*```/.test(lines[i])) out.push(lines[i++])
+      while (i < lines.length && !FENCE_RE.test(lines[i])) out.push(lines[i++])
       if (i < lines.length) out.push(lines[i++])
       continue
     }
+    // Blockquote / table row — copy the whole run verbatim. A hard boundary: a
+    // join must never reach across it, so it also terminates any preceding block.
+    if (STRUCT_LINE_RE.test(line)) {
+      while (i < lines.length && STRUCT_LINE_RE.test(lines[i])) out.push(lines[i++])
+      continue
+    }
     if (!line.trim()) {
       out.push(line)
       i++
       continue
     }
-    // Gather a block of consecutive non-blank, non-fence lines.
+    // Gather a block of consecutive non-blank lines, stopping at any structural
+    // boundary (fence, blockquote, table row) so a reflow can't absorb one.
     let j = i
-    while (j < lines.length && lines[j].trim() && !/^[ \t]*```/.test(lines[j])) j++
+    while (j < lines.length && lines[j].trim() && !FENCE_RE.test(lines[j]) && !STRUCT_LINE_RE.test(lines[j])) j++
     const block = lines.slice(i, j)
     i = j
 
@@ -137,7 +167,13 @@ function sanitizeSpecMarkdown(text, { width } = {}) {
     }
   }
   const result = out.join('\n')
+  // Self-check: a safe reflow never changes the count of structural markers. If it
+  // did, we corrupted something (a blockquote, fence, or bullet) — refuse the write
+  // and hand back the original untouched, flagged for the caller to report.
+  if (result !== src && structuralSignature(result) !== structuralSignature(src)) {
+    return { text: src, changed: false, fixes: 0, refused: true }
+  }
   return { text: result, changed: result !== src, fixes }
 }
 
-module.exports = { sanitizeSpecMarkdown, hasStraddle }
+module.exports = { sanitizeSpecMarkdown, hasStraddle, structuralSignature }