@skitterbyte/skitterspec-linear 10.0.0 → 10.0.1

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/assets/core/SETUP.md

@@ -14,16 +14,25 @@ team) that the config reference (`linear.config.md`) assumes you already have.
 
 ---
 
-## Upgrading from 8.x
-
-**v9 remapped the mirror.** A spec is now an **issue** (was a Project), a phase a
-**sub-issue** (was a Milestone), and tasks are no longer objects. The frontmatter
-keys moved with it, so a spec linked under 8.x reads as **unlinked** to v9 — the
-next `/spec-push` would mint a fresh mirror and abandon the old one.
-
-`spec-sync push` detects this and refuses to let the plan be applied blind, but
-read **`MIGRATION.md`** ("v8 → v9", shipped with the package) before upgrading a
-repo with a live mirror. Fresh installs can skip this section.
+## Upgrading an existing install
+
+Fresh installs can skip this section. **`MIGRATION.md` ships with the package** —
+read the entry for the version you are coming from before upgrading a repo with a
+live mirror.
+
+**From 9.x — `push` now validates your issue states.** `spec-sync push` refuses
+to run until the configured `states` names have been checked against the
+workspace. `/spec-push` does that for you, so nothing changes if you drive sync
+through the skill; a script calling the CLI directly must pass
+`--workspace-states <file>` (or `--skip-state-check`). See `MIGRATION.md`
+→ "v9 → v10".
+
+**From 8.x — the mirror was remapped.** A spec is now an **issue** (was a
+Project), a phase a **sub-issue** (was a Milestone), and tasks are no longer
+objects. The frontmatter keys moved with it, so a spec linked under 8.x reads as
+**unlinked** — the next `/spec-push` would mint a fresh mirror and abandon the old
+one. `push` detects this and refuses to let the plan be applied blind, but read
+`MIGRATION.md` → "v8 → v9" first.
 
 ## 1. Install the package
 

package/assets/core/linear.config.md

@@ -46,6 +46,13 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // that sub-issue: "checklist" mirrors them into its description (default),
   // "none" leaves the description as the phase's Goal line alone. Either way no
   // issue is created per task. These are the defaults.
+  //
+  // Under "checklist" the mirror keeps the phase file's OWN section headings: a
+  // phase with `## Tasks` and `## Acceptance` arrives as two headed sections, in
+  // source order, each heading reproduced as written. Checkboxes written before
+  // any heading appear under `## Tasks`. A heading with no checkboxes under it
+  // is not mirrored. Nesting, sub-bullets and inline formatting are preserved;
+  // a legacy inline `(KEY-123)` on a task line is stripped.
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.0.0",
+  "version": "10.0.1",
   "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",

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

@@ -319,6 +319,46 @@ function parseTaskLine(line) {
   return { id, text, done }
 }
 
+/**
+ * Split a phase's task blocks into the `##` sections they were written under.
+ *
+ * The checklist used to be one flat list under a hardcoded `## Tasks`, so a
+ * criterion written under `## Acceptance` arrived in the mirror as an ordinary
+ * open task. Nothing was lost — it was just unreadable.
+ *
+ * Grouping is done by MAPPING blocks onto headings, not by re-parsing the body
+ * section by section: `findTaskBlocks` tracks open task subtrees across a
+ * continuous body, and slicing that body at every heading would change what a
+ * block claims at a section boundary. A heading inside a fence is not a heading
+ * (`fenceMask`), and the phase file's own `#` H1 is not a section.
+ *
+ * @returns {Array<{heading:string|null, tasks:string[]}>} in source order;
+ *   `heading` is null for blocks that precede every heading, and a heading with
+ *   no blocks under it never appears.
+ */
+function groupTasksByHeading(lines, blocks, renderTask) {
+  const inFence = fenceMask(lines)
+  const headings = []
+  for (let i = 0; i < lines.length; i++) {
+    if (inFence[i]) continue
+    const m = /^(#{2,6})\s+(.*\S)\s*$/.exec(lines[i])
+    if (m) headings.push({ line: i, heading: `${m[1]} ${m[2]}` })
+  }
+
+  const groups = []
+  for (const b of blocks) {
+    let heading = null
+    for (const h of headings) {
+      if (h.line >= b.start) break
+      heading = h.heading
+    }
+    const last = groups[groups.length - 1]
+    if (last && last.heading === heading) last.tasks.push(renderTask(b))
+    else groups.push({ heading, tasks: [renderTask(b)] })
+  }
+  return groups
+}
+
 // Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
 // linked milestone id (from optional frontmatter), title, goal and tasks.
 function readPhaseFiles(snapshotDir) {
@@ -347,7 +387,8 @@ function readPhaseFiles(snapshotDir) {
       // the marker its author wrote, and any inline `(KEY-123)` stamped on a legacy task
       // line stripped — those ids were per-task issues we no longer create, and
       // they read as noise in the mirror.
-      const tasks = findTaskBlocks(body.split('\n')).map((b) => {
+      const lines = body.split('\n')
+      const renderTask = (b) => {
         // `findTaskBlocks` also returns the plain sub-bullets written underneath
         // a task. They carry no checkbox, so they render as the bullet their
         // author used — emitting `- [ ]` here would invent a task that does not
@@ -355,7 +396,10 @@ function readPhaseFiles(snapshotDir) {
         const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
         const text = parsed ? parsed.text : b.text
         return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
-      })
+      }
+      const blocks = findTaskBlocks(lines)
+      const tasks = blocks.map(renderTask)
+      const taskGroups = groupTasksByHeading(lines, blocks, renderTask)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -370,6 +414,7 @@ function readPhaseFiles(snapshotDir) {
         emoji: headingEmoji(body),
         statusLine: phaseStatusLine(body),
         tasks,
+        taskGroups,
       }
     })
 }
@@ -497,7 +542,14 @@ function subIssueBody(phase, tasksMode) {
   if (tasksMode !== 'checklist' || !phase.tasks.length) return phase.goal
   const parts = []
   if (phase.goal) parts.push(phase.goal, '')
-  parts.push('## Tasks', '', ...phase.tasks)
+  // One section per source heading, in source order. Checkboxes written before
+  // any heading keep the `## Tasks` default, so a phase file with a single task
+  // section — every one in this repo's corpus but two — projects unchanged.
+  const groups = phase.taskGroups && phase.taskGroups.length ? phase.taskGroups : [{ heading: null, tasks: phase.tasks }]
+  groups.forEach((group, i) => {
+    if (i) parts.push('')
+    parts.push(group.heading || '## Tasks', '', ...group.tasks)
+  })
   return parts.join('\n')
 }