@skitterbyte/skitterspec-linear 7.0.2 → 8.0.1

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

@@ -1,9 +1,11 @@
-# Setting up Linear hybrid-sync
+# Setting up Linear sync (one-way)
 
-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.
+A start-to-finish guide to getting `/spec-status` and `/spec-push` working against
+a real Linear workspace. Sync is **one-way**: the repo is the source of truth and
+the linked Linear project is a **generated mirror** — content is pushed up, never
+read back or merged. 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
@@ -47,7 +49,7 @@ claude mcp list
 ```
 
 > Read-only trial: use `https://mcp.linear.app/mcp/readonly` to exercise
-> `/spec-status` and `/spec-pull` without granting write access. `/spec-push`
+> `/spec-status` (drift report) without granting write access. `/spec-push`
 > needs the full (writable) endpoint.
 
 ## 3. Find your team id
@@ -108,33 +110,30 @@ Two ways to get there:
 
 | 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 |
-
-By default the **entire spec body travels as the project `description`** — phases
-and acceptance criteria included.
-
-**Optional: body round-trip.** Opt in — add `milestones`/`tasks` to
-`sync.keyedFields` (and `sync.fieldOwnership`) — and phases sync as **Milestones**
-and tasks as **Issues**, compared per item: edit an individual phase or task in
-Linear and pull just that back into the right phase file / task line, or push
-local changes up. The link ids live in the phase file frontmatter
-(`linear_milestone_id`) and inline on task lines (`- [ ] do it (SKI-123)`).
-Deletions are report-only (surfaced by `/spec-status`, never auto-applied). Full
-details in the "Body round-trip" section of `linear.config.md`.
+| `/spec-status` | — | Read-only drift report: what would push (create/update), and whether Linear's workflow-state drifted from the spec. Writes nothing. |
+| `/spec-push`   | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (project description/status, milestones, issues), stamping new ids back into the spec. |
+
+Typical loop: edit the spec in-repo → `/spec-status` (what's pending) →
+`/spec-push` (send it up). There is no pull — Linear is a generated mirror.
+
+### What gets pushed
+
+| Field | What |
+|-------|------|
+| `description` | the spec body (problem, solution, acceptance criteria) as the project description |
+| `milestones` | one per phase (name + goal) |
+| `issues` | one per task — first-sentence **title**, full task text as the **description** |
+| `workflowState` → project status | the spec's lifecycle bucket, mapped via `states` |
+
+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.
+
+Phases push as **Milestones** and tasks as **Issues** by default. The link ids
+live in the phase-file frontmatter (`linear_milestone_id`) and inline on task
+lines (`- [ ] do it (SKI-123)`); `/spec-push` stamps them the first time it
+creates each object, so later pushes update instead of recreate.
 
 Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog**,
 **Open questions**) are stripped from the pushed description — they never leave
@@ -142,24 +141,20 @@ 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`.
+- **Commit** `specs/.core/linear-base/` — the last-pushed snapshots (content
+  hashes per spec, so `/spec-push` knows what changed without reading Linear
+  back). Each worktree carries its own, so it must travel with the branch.
 
 ## 8. Smoke test (verify your setup)
 
-With a linked spec, confirm the round-trip end-to-end:
+With a linked spec, confirm push 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**.
+1. `/spec-status` → shows what would push (`pending — N to create, M to update`).
+2. `/spec-push` → creates the project's milestones/issues and sets the
+   description/status; ids are stamped back into the spec.
+3. `/spec-status` again → **up to date** (nothing changed since the last push).
+4. Edit a task locally, `/spec-push` → the matching issue updates;
+   `/spec-status` returns to **up to date**.
 
 ## Troubleshooting
 
@@ -167,9 +162,9 @@ With a linked spec, confirm the round-trip end-to-end:
   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).
+- **A configured status name silently does nothing** — Linear ignores an unknown
+  project status. Run `/spec-status` (it validates the `states` names against the
+  workspace) and fix `linear.config.json` to the real project-status names
+  (`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.

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

@@ -12,8 +12,8 @@
   "states": {
     "backlog": "Backlog",
     "in-progress": "In Progress",
-    "complete": "Done",
-    "cancelled": "Cancelled"
+    "complete": "Completed",
+    "cancelled": "Canceled"
   },
   "snapshot": {
     "overviewFile": "00-overview.md"
@@ -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

@@ -1,10 +1,12 @@
-# `linear.config.json` — Linear hybrid-sync config
+# `linear.config.json` — Linear one-way sync config
 
-Opt-in config for the git-like Linear sync (`/spec-status`, `/spec-pull`,
-`/spec-push`, and the Linear-aware paths of `/spec` and `/spec-go`). Linear owns
-**status and discussion**; the repo stays the **co-authoring surface for spec
-content**. Sync is bidirectional but git-like: explicit commands, a committed
-**base sidecar** for three-way merge, and no blind overwrites.
+Opt-in config for the Linear sync (`/spec-status`, `/spec-push`, and the
+Linear-aware paths of `/spec` and `/spec-go`). Sync is **one-way**: the repo is
+the source of truth and the Linear project is a **generated mirror**. Content is
+pushed up and never read back or merged — `/spec-push` diffs the spec against a
+committed **last-pushed snapshot** and applies only what changed; `/spec-status`
+is a read-only drift report. The `sync.fieldOwnership` map now just selects the
+projection field set (every field is repo-owned and pushed).
 
 **Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
 is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
@@ -59,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/rules/spec-planning.md

@@ -68,13 +68,15 @@ Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engin
 tracker-free: it knows nothing about any specific ticketing system. A
 ticketing provider is installed as its own distribution that plugs into two named
 **seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
-skill-name + CLI contract — it ships `/spec-status` (read-only per-field
-divergence), `/spec-pull` (tracker→repo), and `/spec-push` (repo→tracker), backed
-by a `spec-sync` CLI, three-way merged against a committed base sidecar. When a
-provider is present, `/spec` also links the spec to the tracker and `/spec-go`
-pulls first. With no provider installed the seams are empty and every skill
-behaves as a plain filesystem workflow. See the provider package's own docs for
-its config and field reference.
+skill-name + CLI contract. Sync is **one-way**: the repo is the source of truth
+and the tracker is a **generated mirror**. It ships `/spec-push` (repo→tracker;
+computes a create/update plan against a committed last-pushed snapshot and applies
+it) and `/spec-status` (read-only drift report — what would push, and whether the
+tracker's workflow-state drifted), backed by a `spec-sync` CLI. There is no
+content pull — the tracker is never read back or merged. When a provider is
+present, `/spec` also links the spec to the tracker. With no provider installed
+the seams are empty and every skill behaves as a plain filesystem workflow. See
+the provider package's own docs for its config and field reference.
 
 ## Project conventions (fill this in)
 

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,27 +129,25 @@ 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` in its `00-overview.md` frontmatter. Otherwise skip this
-step — no config means zero change to the flow below.
-
-- **Run `/spec-pull` first.** Bring down anything Linear changed since the last
-  sync (status, priority, discussion-driven fields) so you build against the
-  current shared state, not a stale snapshot. On a conflict it refuses — relay
-  that and let the user resolve before continuing; do not `--force` for them.
-- **Commit the refreshed snapshot** into the feature branch (a small
-  `chore(spec): pull latest from Linear`-style commit) so the frozen spec rides
-  in the PR alongside the code it describes.
-- Linear's GitHub branch/PR automation may now drive status transitions off the
-  branch and PR you pushed in step 2 — expect state to move on the Linear side;
-  keep any manual status edits minimal to avoid fighting it.
+`linear_project_id`. Otherwise skip this step — no config means zero change.
+
+- **No pull.** Linear is a generated mirror in one-way sync, so there is nothing
+  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.
+- 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`.
 
 ## 4. Implement the phase