@skitterbyte/skitterspec-linear 3.1.0 → 3.4.0

package/README.md

@@ -32,16 +32,22 @@ and `/spec-go` pulls first so you build against the current shared state.
 ## Opt-in
 
 Linear sync is inert until `specs/.core/linear.config.json` exists — copy the
-scaffolded `linear.config.json.example` and fill in your team / initiative IDs
-(every field is documented in `specs/.core/linear.config.md`). Without it, this
+scaffolded `linear.config.json.example` and fill in your team id. Without it, this
 behaves exactly like the base.
 
-**Mapping** (config-driven): spec folder → Linear **Project**; each phase → a
-**Milestone**; tasks → **Issues**; an optional **Initiative** groups specs.
-**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. **Base sidecars** (`specs/.core/linear-base/`) are
-committed; **backups** (`specs/.core/linear-backups/`) are gitignored.
+**Start here:** `specs/.core/SETUP.md` (scaffolded by `init`) is the full
+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 today:** 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. A per-**Milestone** /
+per-**Issue** round-trip (phases and tasks as first-class Linear objects) is a
+planned extension — see `linear.config.md`. **Base sidecars**
+(`specs/.core/linear-base/`) are committed; **backups**
+(`specs/.core/linear-backups/`) are gitignored.
 
 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

@@ -0,0 +1,169 @@
+# Setting up Linear hybrid-sync
+
+A start-to-finish guide to getting `/spec-status`, `/spec-pull`, and `/spec-push`
+working against a real Linear workspace. Covers the **Linear side** (connecting
+the MCP server, finding your team) that the config reference
+(`linear.config.md`) assumes you already have.
+
+> The whole feature is **opt-in**: until `specs/.core/linear.config.json` exists,
+> everything below is inert and the package behaves exactly like the base
+> `@skitterbyte/skitterspec`.
+
+---
+
+## 1. Install the package
+
+Install the Linear superset (or, if you already run the base, switch to it — it
+contains the entire base, so install one **or** the other, never both):
+
+```sh
+npx @skitterbyte/skitterspec-linear init
+```
+
+## 2. Connect the Linear MCP server
+
+The sync skills talk to Linear over MCP. Add Linear's official remote server and
+authenticate — this is a one-time, per-machine step.
+
+```sh
+claude mcp add --transport http linear https://mcp.linear.app/mcp
+```
+
+Then, **inside Claude Code**, authenticate (a browser window opens for OAuth —
+pick the workspace you want to sync into):
+
+```
+/mcp        →  select "linear"  →  Authenticate
+```
+
+A newly added server only appears in `/mcp` **after Claude Code restarts** — if
+you don't see `linear`, relaunch with `claude --continue` and try again.
+
+Verify it's connected:
+
+```sh
+claude mcp list
+# linear: https://mcp.linear.app/mcp (HTTP) - ✓ authenticated
+```
+
+> Read-only trial: use `https://mcp.linear.app/mcp/readonly` to exercise
+> `/spec-status` and `/spec-pull` without granting write access. `/spec-push`
+> needs the full (writable) endpoint.
+
+## 3. Find your team id
+
+`linear.config.json` needs your Linear **team UUID**. The easiest way is to just
+ask Claude once the MCP server is connected:
+
+> "List my Linear teams with their ids."
+
+It calls the Linear `list_teams` tool and returns rows like:
+
+```
+Skitterspec — e07c2b54-dcf6-4b6e-81bd-175a9bc79868  (key: SKI)
+```
+
+Copy the `id` (the UUID). The `key` (e.g. `SKI`) is the short human handle. If you
+want an **Initiative** to group your specs, ask "list my Linear initiatives" and
+copy that id too (optional).
+
+## 4. Scaffold the config
+
+`init` dropped a `specs/.core/linear.config.json.example`. Copy it and fill in the
+ids from step 3 — the team id is the only required field:
+
+```jsonc
+// specs/.core/linear.config.json
+{
+  "linear": {
+    "teamKey": "SKI",
+    "teamId": "e07c2b54-dcf6-4b6e-81bd-175a9bc79868",
+    "initiativeId": ""            // optional
+  }
+}
+```
+
+Everything else (state names, field ownership) has sensible defaults — see
+`linear.config.md` to customise. The moment this file exists, the Linear steps in
+`/spec` and `/spec-go` and the three sync skills switch on.
+
+## 5. Link a spec to a Linear project
+
+A spec syncs once its `00-overview.md` frontmatter carries a `linear_project_id`.
+Two ways to get there:
+
+- **New spec:** run `/spec` — with Linear configured it offers to create a linked
+  Linear **Project** (one Milestone per phase) and stamps the id for you.
+- **Existing spec / existing Linear project:** add the id by hand. Ask Claude to
+  "create a Linear project for this spec" (or find an existing one's id via
+  `list_projects`), then set the frontmatter:
+
+  ```yaml
+  ---
+  linear_project_id: "640bcb1a-28cd-46b5-b2f8-ff47ce494ed1"
+  ---
+  ```
+
+## 6. Everyday sync
+
+| Command | Direction | What it does |
+|---------|-----------|--------------|
+| `/spec-status` | — | Read-only. Per-field divergence: `local-only` / `remote-only` / `conflict` / `in sync`. |
+| `/spec-pull`   | Linear → repo | Applies remote-owned fields (status/priority/labels). Refuses a real conflict unless `--force`. |
+| `/spec-push`   | repo → Linear | Sends the co-authored `description` up. Refuses if a co-authored field moved on Linear since your last sync (pull first) unless `--force`. |
+
+Typical loop: `/spec-status` → `/spec-pull` (take Linear's status) → edit the spec
+in-repo → `/spec-push` (send content up).
+
+### What actually syncs
+
+| Field | Owner | Direction |
+|-------|-------|-----------|
+| `description` (the whole spec body: problem, solution, **phases**, acceptance criteria) | co-authored | push **and** pull |
+| `workflowState` → `spec_status` | Linear | pull only |
+| `priority` | Linear | pull only |
+| `labels` | Linear | pull only |
+
+The **entire spec body travels as the project `description`** — phases and
+acceptance criteria included. A separate per-milestone / per-issue round-trip
+(editing an individual phase in Linear and pulling just that back) is **not yet
+implemented**; opt in later by adding `milestones`/`phaseBodies`/`taskBreakdown`
+to `sync.fieldOwnership` once that write path exists.
+
+Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog**,
+**Open questions**) are stripped from the pushed description — they never leave
+the repo.
+
+## 7. What to commit
+
+- **Commit** `specs/.core/linear-base/` — the three-way merge's base sidecars
+  (last-synced snapshot per spec). Each worktree carries its own, so it must
+  travel with the branch.
+- **Gitignore** `specs/.core/linear-backups/` — `--force` recovery copies, local
+  and per-machine. Add `specs/.core/linear-backups/` to `.gitignore`.
+
+## 8. Smoke test (verify your setup)
+
+With a linked spec, confirm the round-trip end-to-end:
+
+1. `/spec-status` → note the current divergence.
+2. `/spec-pull` → Linear's status/priority/labels land in the spec's frontmatter
+   (`spec_status`, `priority`, `labels`).
+3. `/spec-status` again → **in sync**. (This also proves description idempotency:
+   Linear rewrites markdown bullets on save, and the sync canonicalizes both
+   sides so that never shows as a spurious change.)
+4. Edit the spec body locally, `/spec-push` → the change lands on the Linear
+   project's description; `/spec-status` returns to **in sync**.
+
+## Troubleshooting
+
+- **"connect the `linear` MCP server"** — the server isn't connected/authed for
+  this session. Re-run step 2; remember a fresh add needs a Claude Code restart.
+- **"missing required tools: projectUpdate"** — you're on the read-only endpoint
+  (or a restricted API key). Use `https://mcp.linear.app/mcp` for push.
+- **A field won't stop showing as diverged** — that field genuinely differs on
+  the two sides. `pull`-owned fields (status/priority/labels) resolve to Linear;
+  `/spec-pull` reconciles them. For a co-authored `conflict`, resolve locally or
+  `--force` (which backs up the losing side under `sync.backupDir` first).
+- **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
+  workspace. Remove and re-add the server to authenticate against another.

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

@@ -26,10 +26,6 @@
     "backupDir": "specs/.core/linear-backups",
     "fieldOwnership": {
       "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
       "workflowState": "pull",
       "priority": "pull",
       "labels": "pull"

package/assets/core/linear.config.md

@@ -77,13 +77,14 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     //   "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.
+    // 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).
     "fieldOwnership": {
       "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
       "workflowState": "pull",
       "priority": "pull",
       "labels": "pull"

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

@@ -1,6 +1,6 @@
 ---
 name: spec-bug
-description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
+description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. When per-spec isolation is enabled it provisions a worktree first, so the failing test and fix land on the bug's own branch, never on main. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
 ---
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
@@ -24,7 +24,49 @@ Bugs are concrete — confirm, don't over-grill. Establish:
   against the broken one (the bug usually lives in the differential). Do NOT
   patch a symptom before you understand the cause.
 
-## 2. Write the failing test FIRST (RED) — mandatory
+## 2. Isolate the fix in a worktree — when isolation is enabled
+
+**Only when per-spec isolation is enabled** (`specs/.core/env.config.json`
+exists). Skip this whole section otherwise — the fix happens in place, on the
+current branch.
+
+**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
+place), skip this whole section and fix on the current branch — same as when
+isolation is off. Warn that the fix will land wherever you currently are (usually
+`main`); reserve it for a trivial one-liner or an explicit request.
+
+A bug fix changes real source, so — exactly like `/spec-go` — it belongs on the
+bug's **own branch**, never directly on `main`. Provision the worktree **now**,
+before the failing test, so the test, the fix, and the spec all land together and
+arrive as one reviewable PR.
+
+The engine resolves a spec by its folder, so seed a **minimal stub** for it to
+provision from — you'll flesh it out in §4:
+
+- From the base branch (`main`), create
+  `specs/in-progress/bug-<name>/00-overview.md` with just the header block and the
+  `## Symptom` you established above.
+- Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
+  the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
+  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
+- Run the printed `git worktree add`. **The worktree forks from `main`'s last
+  commit, so your uncommitted stub doesn't travel with it** — move it across so
+  `main` is left pristine:
+  `mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/`.
+- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  none of the repo's gitignored files (`.env`, local overrides). Run the printed
+  `in the worktree, run:` steps (file seeding, then `setup`) in order, before
+  anything else.
+- **Trust the worktree for this session.** The engine wrote the printed
+  `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
+  — run `/add-dir <trusted root>` before editing into the worktree, or the first
+  edits will prompt.
+- **Do everything below in the worktree**, on the branch — the red test, the fix,
+  and the rest of the spec. Act on the worktree with absolute paths /
+  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
+  opener). `main` changes only when the branch merges (at `/spec-complete`).
+
+## 3. Write the failing test FIRST (RED) — mandatory
 
 Encode the **correct** (expected) behaviour as a test, then run it and confirm it
 **fails for the right reason**:
@@ -36,10 +78,13 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
   passes before the fix proves nothing — keep refining the assertion until it
   genuinely captures the bug.
 
-## 3. Write the Bug spec
+## 4. Write the Bug spec
 
-Create the spec **folder** `specs/in-progress/bug-<kebab-name>/` with its entry
-point `00-overview.md` (every spec is a folder — never a bare file). A bug is
+Fill in the spec's entry point `00-overview.md`. **When isolated**, you already
+seeded this stub in §2 and moved it into the worktree — flesh it out there.
+**When not isolated**, create the spec **folder**
+`specs/in-progress/bug-<kebab-name>/` with its entry point `00-overview.md` now
+(every spec is a folder — never a bare file). A bug is
 usually a single-pass fix, so the `## Fix` block can live directly in
 `00-overview.md`. **If the fix needs phasing** (large/uncertain root cause),
 split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
@@ -90,7 +135,7 @@ The **State log** is the folder/status audit trail; later transitions
 (`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
 fix narrative and decisions — keep them separate.
 
-## 4. Drive to GREEN
+## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
   project rules (see `.claude/rules/`).
@@ -103,8 +148,10 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
-## 5. Report
+## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test
 result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it. Do **not** `git commit` unless the user asks.
+archive it (**when isolated**, the fix lives on the bug's branch, and
+`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
+user asks.

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

@@ -26,6 +26,12 @@ Diverting your browser to the spec is a separate explicit step — `/spec-connec
 the spec doesn't already have a worktree, provision it **first**, so all the
 housekeeping below lands on the spec's branch and never on `main`:
 
+**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
+place), skip the provisioning bullets below and build on the current branch — the
+same "in place otherwise" path used when isolation is off. Warn that the work
+will land wherever you currently are (usually `main`); reserve it for a trivial
+change or an explicit request.
+
 - Run `skitterspec spec-env up <name>` (the `spec-env` CLI engine). It adds a git
   worktree on a branch forked from `main`, and — only when the spec's
   `> **Stack:**` header is `worktree + docker` — also brings up its Docker stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "3.1.0",
+  "version": "3.4.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.",
   "keywords": [
     "claude",

package/src/vendor/linear/config.js

@@ -50,12 +50,14 @@ 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.
     fieldOwnership: Object.freeze({
       description: 'both',
-      milestones: 'both',
-      phaseBodies: 'both',
-      acceptanceCriteria: 'both',
-      taskBreakdown: 'both',
       workflowState: 'pull',
       priority: 'pull',
       labels: 'pull',

package/src/vendor/linear/mcp.js

@@ -16,18 +16,20 @@
  */
 
 // Canonical operations, and the regexes that match a Linear MCP tool name to
-// each. Ordered patterns: first match wins. Verified against the connected
-// Linear MCP server during build (resolves the overview's Open questions).
+// each. Ordered patterns: first match wins. Matched against the real connected
+// Linear MCP server: it exposes a single upsert `save_*` tool per object (create
+// when no id, update when id given) rather than separate create/update verbs, so
+// each write op accepts `save_*` as well as the legacy `create_`/`update_` names.
 const MATCHERS = {
   projectRead: [/get_?project\b/i, /read_?project/i, /project_?get/i],
-  projectUpdate: [/update_?project/i, /project_?update/i],
-  projectCreate: [/create_?project/i, /project_?create/i],
+  projectUpdate: [/save_?project/i, /update_?project/i, /project_?update/i],
+  projectCreate: [/save_?project/i, /create_?project/i, /project_?create/i],
   milestoneList: [/list_?.*milestone/i, /milestones?_?list/i, /get_?.*milestones?/i],
-  milestoneCreate: [/create_?.*milestone/i, /milestone_?create/i],
-  milestoneUpdate: [/update_?.*milestone/i, /milestone_?update/i],
+  milestoneCreate: [/save_?.*milestone/i, /create_?.*milestone/i, /milestone_?create/i],
+  milestoneUpdate: [/save_?.*milestone/i, /update_?.*milestone/i, /milestone_?update/i],
   issueList: [/list_?issues?/i, /issues?_?list/i, /get_?issues?/i],
-  issueCreate: [/create_?issue/i, /issue_?create/i],
-  issueUpdate: [/update_?issue/i, /issue_?update/i],
+  issueCreate: [/save_?issue/i, /create_?issue/i, /issue_?create/i],
+  issueUpdate: [/save_?issue/i, /update_?issue/i, /issue_?update/i],
 }
 
 // The minimum the push/pull engine can't run without. Milestone/issue ops are
@@ -88,17 +90,24 @@ function makeAdapter(callTool, resolved) {
     return name
   }
   return {
+    // Linear's project-read tool keys on `query` (accepts a UUID, key, or slug).
     async readProject(id) {
-      return callTool(need('projectRead'), { id })
+      return callTool(need('projectRead'), { query: id })
+    },
+    // `save_project` upserts: with `id` it updates, without it creates. Create
+    // needs a name and at least one team (`addTeams`).
+    async createProject(project) {
+      return callTool(need('projectCreate'), { ...project })
     },
     async updateProject(id, updates) {
       return callTool(need('projectUpdate'), { id, ...updates })
     },
+    // `save_milestone` requires the owning `project`; upserts on `id`.
     async createMilestone(projectId, milestone) {
-      return callTool(need('milestoneCreate'), { projectId, ...milestone })
+      return callTool(need('milestoneCreate'), { project: projectId, ...milestone })
     },
-    async updateMilestone(id, updates) {
-      return callTool(need('milestoneUpdate'), { id, ...updates })
+    async updateMilestone(projectId, id, updates) {
+      return callTool(need('milestoneUpdate'), { project: projectId, id, ...updates })
     },
   }
 }

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

@@ -82,6 +82,25 @@ function parseSections(body) {
   return { title, sections }
 }
 
+// Canonicalise markdown so semantically-equal content hashes equal across the
+// boundary. Linear reserializes markdown on save (authored `-` bullets come back
+// as `*`, trailing whitespace trimmed, blank runs collapsed), so without this a
+// clean push→pull would report `description` as perpetually changed. Applied to
+// the description on BOTH sides. Conservative: only unifies list markers and
+// whitespace — the transforms actually observed from Linear.
+function canonicalizeMarkdown(text) {
+  if (text == null) return text
+  return String(text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    // Unordered-list marker at line start (`*`/`+`/`-`) → `-`. Requires a space
+    // after the marker so bold/emphasis (`**Goal:**`) is untouched.
+    .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
 // Canonical milestone status from the phase-index emoji.
 const EMOJI_STATUS = { '⬜': 'not-started', '🔄': 'in-progress', '✅': 'done' }
 
@@ -160,7 +179,7 @@ function buildDescription(title, sections, localOnlySections) {
     if (skip.has(heading)) continue
     parts.push(`## ${heading}\n\n${content}`.trim())
   }
-  return parts.join('\n\n').trim() || null
+  return canonicalizeMarkdown(parts.join('\n\n')) || null
 }
 
 /**
@@ -208,6 +227,46 @@ function canonicalRemoteStatus(state) {
   return s
 }
 
+// The real Linear projection carries the project's workflow state in `status`
+// (an object `{ name, type }`); accept a bare string / legacy `state` too.
+function remoteStateName(project) {
+  const st = project.status != null ? project.status : project.state
+  if (st == null) return null
+  if (typeof st === 'object') return st.name != null ? st.name : st.type != null ? st.type : null
+  return st
+}
+
+// Real Linear priority is an object `{ value, name }`; accept a bare number too.
+function remotePriority(priority) {
+  if (priority == null) return null
+  if (typeof priority === 'object') return priority.value != null ? priority.value : null
+  return priority
+}
+
+// Real Linear labels are `[{ id, name }]`; accept bare strings too.
+function remoteLabels(labels) {
+  if (!Array.isArray(labels)) return []
+  return labels
+    .map((l) => (typeof l === 'string' ? l : l && l.name != null ? l.name : null))
+    .filter((n) => n != null)
+}
+
+// A real Linear milestone has no workflow state — only `progress` ("0%".."100%").
+// Fall back to a legacy `status`/`state` when present (fixtures / older shapes).
+function remoteMilestoneStatus(m) {
+  if (m.status != null) return canonicalRemoteStatus(m.status)
+  if (m.state != null) return canonicalRemoteStatus(m.state)
+  if (m.progress != null) {
+    const pct = parseInt(String(m.progress), 10)
+    if (Number.isFinite(pct)) {
+      if (pct >= 100) return 'done'
+      if (pct > 0) return 'in-progress'
+    }
+    return 'not-started'
+  }
+  return 'not-started'
+}
+
 /**
  * Normalize a remote Project projection (from the Phase 2 MCP adapter, or a
  * fixture) into the same field set as `normalizeLocal`.
@@ -215,11 +274,12 @@ function canonicalRemoteStatus(state) {
 function normalizeRemote(project, config) {
   const p = project || {}
   const milestones = Array.isArray(p.milestones) ? p.milestones : []
+  const stateName = remoteStateName(p)
   const extracted = {
-    description: p.description != null ? p.description : null,
+    description: p.description != null ? canonicalizeMarkdown(p.description) : null,
     milestones: milestones.map((m) => ({
       name: m.name,
-      status: canonicalRemoteStatus(m.status != null ? m.status : m.state),
+      status: remoteMilestoneStatus(m),
     })),
     phaseBodies: milestones.map((m) => ({
       phase: m.name,
@@ -230,9 +290,9 @@ function normalizeRemote(project, config) {
       phase: m.name,
       tasks: Array.isArray(m.tasks) ? m.tasks : [],
     })),
-    workflowState: p.state != null ? bucketForState(p.state, config) : null,
-    priority: p.priority != null ? p.priority : null,
-    labels: Array.isArray(p.labels) ? p.labels : [],
+    workflowState: stateName != null ? bucketForState(stateName, config) : null,
+    priority: remotePriority(p.priority),
+    labels: remoteLabels(p.labels),
   }
   return toFieldSet(extracted, config)
 }
@@ -245,5 +305,6 @@ module.exports = {
   parseSections,
   parsePhaseIndex,
   canonicalRemoteStatus,
+  canonicalizeMarkdown,
   bucketForState,
 }

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

@@ -28,16 +28,18 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
   }
   const remote = normalizeRemote(remoteRaw, config)
   const base = readBase(dir, identifier, config)
-  const baseStamp = base && base.__meta ? base.__meta.updatedAt : null
   const fields = classify(local, remote, base, config)
 
-  // Remote moved past base if the classifier sees remote-side divergence OR the
-  // recorded updatedAt no longer matches (a change we can't even see as a field).
+  // Remote moved past base only if a *co-authored* (`both`) field diverged on the
+  // remote side — that's the case the repo can't safely overwrite without a pull.
+  // A `pull`-owned change (status/priority/labels) is Linear's to own and must
+  // NOT block a content push, and a bare `updatedAt` bump (which any Linear edit
+  // produces) is too coarse to gate on — the pre-write re-read below still catches
+  // a racer that lands during the push itself.
   const remoteDivergedFields = fields
-    .filter((f) => f.raw === 'remote-only' || f.raw === 'conflict')
+    .filter((f) => f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
     .map((f) => f.field)
-  const stampMoved = baseStamp != null && remoteRaw.updatedAt !== baseStamp
-  const moved = remoteDivergedFields.length > 0 || stampMoved
+  const moved = remoteDivergedFields.length > 0
 
   if (moved && !force) {
     return {