@skitterbyte/skitterspec-linear 7.0.1 → 8.0.0

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"

package/assets/core/linear.config.md

@@ -1,10 +1,12 @@
-# `linear.config.json` — Linear hybrid-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.
+# `linear.config.json` — Linear one-way sync config
+
+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

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)
 
@@ -190,3 +192,7 @@ queried directly.)
 - Never delete historical notes.
 - The spec file is the single source of truth for implementation progress.
 - Move specs between buckets with `git mv` to preserve history.
+- Never let inline emphasis or a link cross a hard line break — keep a whole
+  `**bold**`, `*italic*`, or `[text](url)` on one line (let it overflow the wrap
+  column rather than splitting it). Many round-tripping editors mangle a
+  `**`/`*`/link span that straddles a newline, so clean source avoids the churn.

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

@@ -137,19 +137,18 @@ change to the flow below. Follow the provider's pull 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
 

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

@@ -1,14 +1,14 @@
 ---
 name: spec-push
-description: Push a spec's local content up to its linked Linear project (repo → Linear), three-way aware and ownership-respecting. Never pushes pull-owned fields or local-only sections; aborts if Linear moved since the last sync unless --force (which backs up the remote side first). Runs `skitterspec spec-sync push` then applies the blessed writes over MCP. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "sync my spec up to Linear", or "update the Linear project from this spec".
+description: Push a spec up to its linked Linear project (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (project description/status, milestones, issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear project from this spec".
 ---
 
-# /spec-push — send spec content up to Linear
+# /spec-push — send a spec up to Linear (one-way)
 
-Repo → Linear. Sends the fields the repo owns/co-authors (description, phases,
-tasks per config) up to the linked project. It **never** writes `pull`-owned
-fields (status/priority/labels) or `localOnlySections`, and it **aborts** if
-Linear moved since the last sync (pull first) unless you `--force`.
+Repo → Linear. The repo is the **source of truth**; Linear is a **generated
+mirror**. This skill computes what changed since the last push and applies it —
+it never reads Linear content back or merges. A person editing the mirror in
+Linear will see it overwritten on the next push.
 
 **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
 tell the user how to enable Linear sync and stop.
@@ -17,58 +17,64 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Fetch the Linear project
+## 2. Get the plan from the engine
 
-- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, stop
-  (link via `/spec` first).
-- Discover the Linear MCP tools at runtime (project read **and** update). If
-  Linear isn't connected — or the update tool is missing — relay the fix and stop,
-  **writing nothing**.
-- Call the read tool and write the project JSON to a temp file.
+```
+skitterspec spec-sync push <spec> --json
+```
 
-## 3. Run the engine (the guard)
+The engine prints a JSON **plan** (no network, no remote read):
 
+```json
+{
+  "project": { "description": "…", "status": "in-progress", "priority": 2, "labels": ["…"] },
+  "milestones": { "create": [{ "ref": "01-outbox", "name": "…", "goal": "…" }], "update": [{ "id": "…", "name": "…", "goal": "…" }] },
+  "issues": { "create": [{ "ref": "<task text>", "title": "…", "description": "…", "done": false, "milestoneRef": "01-outbox" }], "update": [{ "id": "SKI-1", "title": "…", "description": "…", "done": true }] }
+}
 ```
-skitterspec spec-sync push <spec> --remote <tempfile> --out <mergedfile> [--force]
-```
 
-- **Refused** (`remote-moved` / `concurrent-write` / conflict) — relay the message
-  and **stop**. Do not write to Linear. Suggest `/spec-pull` first.
-- **OK** — the engine has confirmed it's safe, rewritten the base, and stamped
-  `last_synced_at`. Its summary lists the `written` fields (and any `skipped`
-  because they're not pushable).
-- **`--force`** — only when the user explicitly asks. Local wins after the engine
-  backs up the remote side under `sync.backupDir`. Relay the backup path.
+An empty plan (no project, no create/update) means the mirror is up to date —
+say so and stop.
+
+## 3. Discover the Linear MCP tools
 
-## 4. Apply the blessed writes to Linear
+Discover project + milestone + issue **create/update** tools at runtime. If
+Linear isn't connected or a needed tool is missing, relay the fix and stop,
+**writing nothing**.
 
-Only when step 3 returned OK: for each `written` field, call the Linear update
-tool with that field's local value (e.g. `description` → the project description).
-The engine has already vetted the change and moved the base — so if a Linear
-write fails, re-run `/spec-pull` to reconcile rather than retrying blindly.
+**Validate the project states first.** Fetch the workspace's project-status
+names and run `skitterspec spec-sync status <spec> --workspace-states <file>`; if
+it errors (a configured `states` name isn't in the workspace), stop and fix the
+config — Linear silently ignores an unknown project status.
 
-**Milestones (`milestonesPush` in the result).** When milestones are keyed, the
-engine can't write them itself — apply the plan over MCP:
+## 4. Apply the plan (order matters)
 
-- `update`: for each `{ id, name, goal }`, call the milestone-save tool with that
-  `id` (name → milestone name, goal → its description).
-- `create`: for each `{ name, goal }`, call the milestone-save tool with no id to
-  create it under the project, then **stamp the returned milestone id** into the
-  matching phase file's frontmatter (`linear_milestone_id`) so it links on the
-  next sync. Match the phase file by its title.
+1. **Milestones create** → create each in Linear; for each, stamp the returned id
+   into its phase file: the `ref` is the phase-file basename.
+2. **Issues create** → create each (link to its milestone by `milestoneRef`,
+   resolving a `create` ref to the id just minted); stamp the returned identifier
+   back onto the matching task line (`ref` is the task's text).
+3. **Milestones/issues update** → save by `id`.
+4. **Project** → set description + status (map `status` — the local bucket — to
+   the Linear project-status name via `config.states`). Priority, labels, cycles
+   and comments are Linear-native triage — do **not** push them; they're the PM's.
 
-Progress is Linear-derived — never push it.
+Map the local status bucket to Linear's project status through `config.states`
+(e.g. `complete → Completed`).
 
-**Issues (`issuesPush` in the result).** When tasks are keyed:
+## 5. Record the snapshot
+
+After everything applied and the ids are stamped into the files:
+
+```
+skitterspec spec-sync record <spec>
+```
 
-- `update`: for each `{ id, text, done }`, call the issue-save tool with that `id`
-  (text → title; `done` → a completed state, else a non-completed state — leave an
-  already-non-completed issue's exact state untouched).
-- `create`: for each `{ text, done }`, create an issue under the project (attach it
-  to the milestone of the phase the task lives in when known), then **stamp the new
-  issue identifier inline** on that task line (`… (SKI-123)`), matching by text.
+This writes the last-pushed snapshot from the now-stamped files, so the next
+`/spec-push` produces an empty plan. Commit the stamped spec + snapshot into the
+branch so the mirror-link rides in the PR.
 
-## 5. Report
+## 6. Report
 
-Relay the git-like summary (written / skipped / backup / base) plus which Linear
-fields you updated.
+Summarise what was created/updated in Linear and confirm the snapshot was
+recorded. There is no pull — Linear is a generated mirror.

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

@@ -1,46 +1,51 @@
 ---
 name: spec-status
-description: Show a spec's sync status against its linked Linear project — a read-only, git-status-style per-field divergence (local-only / remote-only / conflict / in-sync). Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what's diverged from Linear", or "show spec sync status".
+description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's workflow-state differs from the spec's. Fetches the Linear project over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
 ---
 
-# /spec-status — show a spec's divergence from Linear
+# /spec-status — one-way sync drift report
 
-Read-only. Prints, per field, whether the spec and its linked Linear project have
-diverged since the last sync — the `git status` of the hybrid sync. Writes
-nothing to either side.
+Read-only. Reports two things and writes nothing:
 
-This skill is **opt-in**: it only runs when `specs/.core/linear.config.json`
-exists. If it's absent, tell the user to copy `linear.config.json.example` →
-`linear.config.json` to enable Linear sync, and stop.
+1. **Pending push** — has the spec changed since the last push (are there
+   milestones/issues/description to create or update)?
+2. **State drift** — does Linear's project workflow-state differ from the spec's
+   status? (The repo wins on the next push; this is just a heads-up, e.g. a card
+   moved in Linear.)
+
+The repo is the source of truth; Linear is a generated mirror, so there is no
+per-field "conflict" — only "what would the next push send" and "did the mirror
+drift".
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
 
 ## 1. Identify the target spec
 
-Use the spec named as an argument, else the spec **currently in context**. If
-neither is clear, ask which spec.
+Use the argument, else the spec in context; ask if unclear.
+
+## 2. Fetch the Linear project (optional, for drift)
 
-## 2. Fetch the Linear project (read-only)
+If the spec has a `linear_project_id`, discover the Linear MCP read tool and write
+the project JSON to a temp file — this lets the report compare workflow-state. If
+Linear isn't connected, skip the drift line (still report pending-push).
 
-- Read the spec's `linear_project_id` from `00-overview.md` frontmatter. If it's
-  missing, the spec isn't linked yet — say so and stop (link it via `/spec`).
-- Discover the connected Linear MCP tools at runtime (the project-read tool). If
-  Linear isn't connected, relay "connect the `linear` MCP server" and stop — do
-  nothing else.
-- Call the project-read tool for that id and write the returned JSON to a temp
-  file (e.g. under the OS temp dir).
+Optionally fetch the workspace project-status names to a file to validate the
+configured `states` at the same time.
 
 ## 3. Run the engine
 
 ```
-skitterspec spec-sync status <spec> --remote <tempfile>
+skitterspec spec-sync status <spec> [--remote <projectfile>] [--workspace-states <statesfile>]
 ```
 
-The engine does the three-way compare (local vs Linear vs the committed base) and
-prints each diverged field with its classification and sync direction. Without
-`--remote` it falls back to a local-vs-base comparison (still read-only).
+- Reports `push: pending — N to create, M to update` or `up to date`.
+- With `--remote`, adds a `drift:` line comparing Linear's workflow-state to the
+  spec's status.
+- With `--workspace-states`, fails loudly if a configured state name isn't in the
+  workspace (Linear would silently no-op it).
 
 ## 4. Report
 
-Relay the engine's summary verbatim, then offer the natural next step:
-`/spec-pull` for remote-only changes, `/spec-push` for local-only, and — for a
-`conflict` — resolve locally or use `--force` (which backs up the losing side).
-Never write anything from this skill.
+Relay the engine's output verbatim. Suggest `/spec-push` if a push is pending.
+Never write to either side.

package/bin/skitterspec-linear.js

@@ -10,6 +10,7 @@
 
 const { run } = require('../src/cli.js')
 const { specSync } = require('../src/vendor/linear/cli-sync.js')
+const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')
 
 async function main(argv) {
   const [cmd, ...rest] = argv
@@ -17,6 +18,10 @@ async function main(argv) {
     await specSync(rest)
     return
   }
+  if (cmd === 'spec-sanitise') {
+    process.exitCode = await specSanitise(rest)
+    return
+  }
   await run(argv)
 }
 

package/package.json

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