@skitterbyte/skitterspec 16.3.0 → 16.3.2

package/MIGRATION.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "16.3.0",
+  "version": "16.3.2",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",