@skitterbyte/skitterspec-linear 9.2.0 → 10.0.0

package/MIGRATION.md

@@ -0,0 +1,156 @@
+# Migration guide
+
+## `@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),
+each phase a **sub-issue** (not a Milestone), and **tasks are no longer synced**
+(they stay in the repo phase files). This collapses a large spec from ~1 project +
+N milestones + dozens of task-issues down to **one issue + one sub-issue per
+phase**. The base `@skitterbyte/skitterspec` is unaffected (still v15).
+
+### Breaking changes
+
+| Area | v8 | v9 |
+|------|-----|-----|
+| `linear.config.json` → `mapping` | `{specFolder:"project", phases:"milestone", tasks:"issue"}` | `{specFolder:"issue", phases:"subissue", tasks:"none"}` |
+| `linear.config.json` → `linear` | `initiativeId` | `projectId` (the project picker's default) |
+| `linear.config.json` → `states` | Linear **Project** statuses (e.g. `Completed`) | Linear **issue** workflow states (e.g. `Done`) |
+| `linear.config.json` → `sync.fieldOwnership` | `{description, milestones, tasks, workflowState}` | `{description, subIssues, workflowState}` |
+| Phase frontmatter | `linear_milestone_id` | `linear_issue_id` (the sub-issue id) |
+| Overview frontmatter | `linear_project_id` + `linear_identifier` | `linear_identifier` (the spec issue) |
+| Last-pushed snapshot | `{project, milestones, issues}` | `{issue, subIssues}` |
+
+### What to do
+
+1. **Upgrade and re-run `update`:** `npx @skitterbyte/skitterspec-linear update`.
+   It refreshes the skills, the `linear.config.md` / `SETUP.md` docs, and the
+   config example.
+2. **Edit `specs/.core/linear.config.json`** to the new keys above (or delete it
+   and re-copy `linear.config.json.example`). Point `states` at your workspace's
+   **issue** states; set `linear.projectId` if most specs belong to one Project —
+   it pre-selects the picker's default rather than fixing every spec there.
+3. **Optionally add `intake`** to start specs from issues someone else filed:
+
+   ```jsonc
+   "intake": {
+     "label": "web-app",      // the inbox `/spec --from-issue` browses
+     "bugLabels": ["bug"]     // issues with these route to /spec-bug
+   }
+   ```
+
+   Without it, `/spec SKI-123` still adopts an issue by id; only the browsable
+   inbox and the bug routing need the labels.
+4. **Existing pushed specs:** the snapshot format changed, so the first
+   `/spec-push` after upgrading **re-creates** the mirror (a fresh issue +
+   sub-issues). Delete any stale `specs/.core/linear-base/*.base.json` and the old
+   `linear_project_id` / `linear_milestone_id` frontmatter first. If you were
+   pre-first-push, there's nothing to reconcile.
+5. **Task-level issues** created under v8 are no longer managed by the sync —
+   close or repurpose them in Linear by hand.
+
+## `@skitterbyte/skitterspec` v2 → v3 (slimmer surface + local traffic diversion)
+
+**v3 shrinks the everyday command surface to five verbs — `spec → go → connect →
+commit → complete` — by folding provisioning, teardown, and grooming into the
+lifecycle skills, and adds `/spec-connect` for testing a worktree at your normal
+`localhost` URL.** (`@skitterbyte/skitterspec-linear` moves to v2.0.0 in lockstep.)
+
+### Removed skills (breaking) → where they went
+
+| Removed skill | Replaced by |
+|---------------|-------------|
+| `/spec-env` | **Automatic in `/spec-go`** — it provisions the worktree and (with your OK) starts the spec's dev servers. Escalate Docker later with the CLI: `skitterspec spec-env up <name>`. |
+| `/spec-env-down` | **Folded into `/spec-complete` and `/spec-cancel`** — they tear the environment down (dev servers, worktree, stack, slot) as part of finishing/abandoning a spec. |
+| `/spec-ready` | **Folded into `/spec`** — grilling now writes a `Ready` spec directly (or `Draft` if you deliberately leave open questions). Go straight to `/spec-go`. |
+
+The **`skitterspec spec-env` CLI engine stays** (`up`, `down`, `dev`, `connect`,
+`integrate`, `status`, `resolve`) — only the three *skills* were removed. Anything
+that scripted those CLI verbs keeps working.
+
+### New — `/spec-connect` and two config blocks
+
+- **`/spec-connect <name>`** points your canonical `localhost` ports at a spec's
+  running dev servers (so you can test a worktree's UI/API at the normal URL);
+  `/spec-connect main` hands the ports back. It's a small bundled Node reverse
+  proxy — no external install. Exclusive: one spec exposed at a time.
+- **`env.config.json` gains `dev` and `proxy` blocks.** `dev` lists the host dev
+  servers `/spec-go` starts (`{ name, command, portVar, health?, frontPort? }`);
+  `proxy` configures the front-door proxy (`{ enabled, host }`). Both default to
+  off/empty, so existing projects are unaffected until you fill `dev` in.
+
+### What to do
+
+1. **Upgrade and re-run `init`** (or `update`): `npx @skitterbyte/skitterspec
+   update`. It stops installing the three removed skills, installs `/spec-connect`,
+   and refreshes the CLAUDE.md section + `spec-planning` rule. Your specs and
+   `env.config.json` are untouched.
+2. **Remove muscle memory for the old commands** — use `/spec-go` to bring a spec
+   up, `/spec-complete`/`/spec-cancel` to tear it down, and `/spec` (no separate
+   `/spec-ready`) to reach a Ready spec.
+3. **To test UI/API worktrees:** add a `dev` block to `env.config.json` (see
+   `specs/.core/env.config.md`), then `/spec-go` → `/spec-connect <name>`.
+
+## `@skitterbyte/skitterspec` v1 → v2 (tracker-free base)
+
+**v2 of the base package is tracker-free.** The Linear sync feature — the
+`/spec-status`, `/spec-push` skills, the `spec-sync` CLI, the
+Linear-aware steps of `/spec` and `/spec-go`, and the `linear.config.*`
+templates — moved out of `@skitterbyte/skitterspec` into a separate **superset**
+distribution, `@skitterbyte/skitterspec-linear`. You now install exactly one:
+
+| If you… | Install |
+|---------|---------|
+| don't sync specs to a tracker | `@skitterbyte/skitterspec` (v2) |
+| use (or want) Linear sync | `@skitterbyte/skitterspec-linear` |
+
+Everything else — the spec lifecycle and per-spec isolation — is unchanged and
+present in **both**.
+
+### If you did NOT use Linear sync
+
+Nothing to do. Upgrade to v2 and re-run `init` (or `update`) as usual. The base
+never installed the Linear skills for you, so there's nothing to remove.
+
+### If you DID use Linear sync
+
+Switching is one install plus a re-`init`:
+
+1. **Install the superset** (in place of the base):
+
+   ```sh
+   npm rm @skitterbyte/skitterspec        # if it was a dependency
+   npx @skitterbyte/skitterspec-linear init
+   ```
+
+2. **Re-run `init`.** It re-installs the shared skills (now composed with the
+   Linear steps) and the three sync skills, and re-scaffolds the config
+   templates. Your existing files are preserved — `init` never overwrites without
+   `--force`.
+
+3. **Your config is unchanged.** The live config path is still
+   `specs/.core/linear.config.json`, and the committed base sidecars under
+   `specs/.core/linear-base/` are read as-is. No re-linking, no re-sync.
+
+That's it — `/spec-status`, `/spec-push`, and `skitterspec-linear
+spec-sync …` work exactly as before.
+
+### One config note — branch naming
+
+Embedding the Linear identifier in a worktree branch name is now configured in the
+**isolation** config, not the Linear config. In `specs/.core/env.config.json` set:
+
+```jsonc
+"branch": { "pattern": "{identifier}-{slug}", "identifierField": "linear_identifier" }
+```
+
+If you don't need the id in branch names, leave the default `{type}/{slug}` — the
+old implicit Linear-branch behaviour is off unless you opt in this way. (This is
+the only behavioural change beyond the package split.)
+
+## Why the split
+
+The base couldn't ship without a specific tracker's fingerprints baked into shared
+skills and a `src/sync/` engine. Extracting the provider makes the base a clean,
+tracker-free workflow and lets a new provider (e.g. Jira) ship as another superset
+over the same base — without re-patching the base. See
+`specs/complete/feat-extract-ticketing-provider/` for the full rationale.

package/README.md

@@ -51,6 +51,25 @@ fuller guide):
    `/spec-status` reports what would push. Sync is **one-way**: the repo is the
    source of truth and Linear is a generated mirror.
 
+## Upgrading
+
+```sh
+npx @skitterbyte/skitterspec-linear update
+```
+
+`update` refreshes the files it manages (skills, rules, `specs/.core` docs) and
+**keeps anything you edited**. A file it kept is listed under
+`customized (kept)` with the change it declined summarised as `+added −removed`:
+
+```
+customized (kept):
+  .claude/rules/spec-planning.md  +34 −13
+```
+
+Add `--diff` to see those changes as a unified diff before deciding whether to
+re-apply your edits on top, or `--force` to take the package version and lose
+them. Your `specs/` content and live `.core` config are never touched.
+
 ## What the superset adds
 
 On top of the base skills (`/spec`, `/spec-go`, isolation, …):

package/assets/core/SETUP.md

@@ -14,6 +14,17 @@ 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.
+
 ## 1. Install the package
 
 Install the Linear superset (or, if you already run the base, switch to it — it
@@ -173,10 +184,15 @@ With a linked spec, confirm push end-to-end:
   this session. Re-run step 2; remember a fresh add needs a Claude Code restart.
 - **"missing required tools: issueCreate"** — you're on the read-only endpoint
   (or a restricted API key). Use `https://mcp.linear.app/mcp` for push.
-- **A configured state name silently does nothing** — Linear ignores an unknown
-  issue state. Run `/spec-status` (it validates the `states` names against the
-  workspace) and fix `linear.config.json` to the real issue-state names
-  (`Backlog / Todo / In Progress / Done / Canceled`).
+- **"refusing — the configured issue states have not been validated"** — `push`
+  requires the workspace's issue-state names (`--workspace-states <file>`), which
+  `/spec-push` fetches for you. Run the skill rather than the CLI directly, or
+  pass the file yourself.
+- **"refusing — configured state name(s) not in the workspace"** — Linear ignores
+  an unknown issue state, so this is caught before the push rather than after.
+  Fix `linear.config.json` to the real issue-state names
+  (`Backlog / Todo / In Progress / Done / Canceled`). Upgrading from 8.x, the
+  value inverts: project status `Completed` → issue state `Done`.
 - **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
   workspace. Remove and re-add the server to authenticate against another.
 - **Bold around an inline code span renders oddly in Linear** — Linear moves the

package/assets/core/linear.config.md

@@ -54,7 +54,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 
   // Map the spec's lifecycle bucket → the Linear ISSUE workflow-state name. Used
   // for the spec issue's state (from its folder) AND each sub-issue's state (from
-  // the phase emoji). Names must match the workspace's issue states exactly.
+  // the phase emoji). Names must match the workspace's issue states exactly —
+  // Linear silently IGNORES an unknown state, so a typo pushes clean and the
+  // issue never moves. `/spec-push` fetches the workspace's names and `push`
+  // refuses to run without them, so a wrong name here fails loudly rather than
+  // quietly. (Upgrading from 8.x? The right value inverts: the project status
+  // `Completed` becomes the issue state `Done`.)
   "states": {
     "backlog": "Backlog",
     "in-progress": "In Progress",

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

@@ -20,10 +20,36 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Get the plan from the engine
+## 2. Connect, and validate the issue states
+
+Discover the issue **read + create/update** tools at runtime (`get_issue`,
+`save_issue` — a single upsert covers create and update), plus the **project
+list** tool if this push will mint the spec issue (see the picker below — it is
+optional; without it the picker is skipped, not failed). If Linear isn't
+connected or a needed tool is missing, relay the fix and stop, **writing
+nothing**.
+
+Then fetch the workspace's issue workflow-state **names** and write them to a
+file as a JSON array (e.g. `["Backlog","In Progress","Done","Canceled"]`). Step 3
+requires that file: `push` **refuses to run** without it, because Linear silently
+ignores an unknown issue state — the description lands, the issue never moves,
+and nothing errors. If the check reports a name that isn't in the workspace, stop
+and fix `specs/.core/linear.config.json`.
+
+**If the check refuses, offer to fix it.** The refusal lists every configured
+name the workspace lacks, the workspace's real state names, and — where the
+bucket makes it unambiguous — which one to use instead. Relay that, then offer to
+apply it to `specs/.core/linear.config.json` → `states`, and do so on the user's
+confirmation. Never edit their config without asking, and never guess a bucket
+the refusal made no suggestion for — ask which state they want.
+
+`--skip-state-check` exists for the deliberate exception; do not reach for it to
+get past a failing check.
+
+## 3. Get the plan from the engine
 
 ```
-skitterspec spec-sync push <spec> --json
+skitterspec spec-sync push <spec> --workspace-states <file> --json
 ```
 
 The engine prints a JSON **plan** (no network, no remote read):
@@ -43,19 +69,15 @@ date — say so and stop. `state` values are local buckets
 (`backlog`/`in-progress`/`complete`/`cancelled`); map each to the Linear
 issue-state NAME via `config.states` at apply time.
 
-## 3. Discover the Linear MCP tools
-
-Discover the issue **read + create/update** tools at runtime (`get_issue`,
-`save_issue` — a single upsert covers create and update), plus the **project
-list** tool if this push will mint the spec issue (see the picker below — it is
-optional; without it the picker is skipped, not failed). If Linear isn't
-connected or a needed tool is missing, relay the fix and stop, **writing
-nothing**.
+### Stop if the plan reports a pre-9.0 mirror
 
-**Validate the issue states first.** Fetch the workspace's issue workflow-state
-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 issue state.
+If the plan carries a **`legacy`** field, this spec was linked under the pre-9.0
+model (`linear_project_id` / `linear_milestone_id`). v9 reads the new keys, finds
+none, and the plan above is therefore **all-creates** — applying it mints a fresh
+mirror and **abandons** the existing one. **Stop.** Relay `legacy.keys`,
+`legacy.files` and `legacy.orphanCount` ("this would orphan N live objects"),
+point at `MIGRATION.md` → "v8 → v9", and apply nothing until the user has
+migrated or explicitly confirms they want a new mirror.
 
 ## 4. Apply the plan (order matters)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "9.2.0",
+  "version": "10.0.0",
   "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",
@@ -21,7 +21,8 @@
   "files": [
     "bin",
     "src",
-    "assets"
+    "assets",
+    "MIGRATION.md"
   ],
   "engines": {
     "node": ">=18"

package/src/cli.js

@@ -79,6 +79,8 @@ Options (init / update):
   --reset                  (init) Start again: reset managed scaffolding fresh
                            (needs --yes; never touches your specs or config)
   --force                  Overwrite skill/rule/script files that already exist
+  --diff                   (update) Show the upstream changes each customized
+                           file declined, as a unified diff
   --dir <path>             Target project dir (default: positional arg or cwd)
   --no-claude-md           Skip creating/patching CLAUDE.md
   --yes, -y                Accept defaults; skip the interactive setup prompts
@@ -104,6 +106,7 @@ function parse(argv) {
     removeReleaseTooling: false,
     resync: false,
     reset: false,
+    diff: false,
   }
   const positional = []
   for (let i = 0; i < argv.length; i++) {
@@ -116,6 +119,7 @@ function parse(argv) {
     else if (a === '--remove-release-tooling') opts.removeReleaseTooling = true
     else if (a === '--resync') opts.resync = true
     else if (a === '--reset') opts.reset = true
+    else if (a === '--diff') opts.diff = true
     else if (a === '--dir') opts.dir = argv[++i]
     else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
     else positional.push(a)
@@ -1346,7 +1350,7 @@ async function run(argv) {
           break
         }
         if (action === 'resync') {
-          resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
+          resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
           break
         }
         // action === 'create-missing' → fall through to a normal (skip-existing) init.
@@ -1365,7 +1369,7 @@ async function run(argv) {
     case 'update':
       // `update` is a resync — refresh managed files, keep customized ones
       // (--force to overwrite). Leaves specs/ and live .core config alone.
-      resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
+      resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
       await cleanupReleaseTooling(dir, opts)
       break
     default:

package/src/init.js

@@ -53,7 +53,7 @@ const CORE_FILES = listCoreTemplates()
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], customized: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], removed: [], customized: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -82,6 +82,8 @@ function ensureDir(p) {
 // old version we own" (safe to update) from "a file the user edited" (keep). It
 // lists only managed FILES (skills, rules, .core templates) — never user content.
 
+const { linesDiff } = require('./lines-diff.js')
+
 const MANIFEST_FILE = path.join('specs', '.core', '.skitterspec-manifest.json')
 const MANIFEST_VERSION = 1
 
@@ -132,13 +134,24 @@ function writeManifest(dir, files) {
 
 // Classify a managed file against the manifest baseline.
 //   missing    — not on disk
-//   pristine   — on disk and matches the hash we recorded (ours to update)
-//   customized — on disk but differs (or unknown) — a user edit; keep it
-function managedState(dir, relPath, manifest) {
+//   pristine   — ours to update: it matches the package asset, or the hash we recorded
+//   customized — on disk but differs from both — a user edit; keep it
+//
+// `bundled` (the current package asset) is optional but decisive: a file whose
+// CONTENT equals what we ship is not customized, whatever the manifest says.
+// Without that check a stale hash pinned the file out of updates permanently —
+// anything that changed it out-of-band (an errant tool, a partial restore, a
+// manifest lost and re-seeded at the wrong version) froze it for good, silently.
+// Comparing content first makes the tool self-healing after any restore.
+// `pruneRetiredManaged` passes no `bundled` on purpose: the package no longer
+// ships that file, so there is nothing to compare it against.
+function managedState(dir, relPath, manifest, bundled) {
   const abs = path.join(dir, relPath)
   if (!fs.existsSync(abs)) return 'missing'
+  const onDisk = fs.readFileSync(abs, 'utf8')
+  if (bundled !== undefined && onDisk === bundled) return 'pristine'
   const known = manifest.files[relPath]
-  return known && sha1(fs.readFileSync(abs, 'utf8')) === known ? 'pristine' : 'customized'
+  return known && sha1(onDisk) === known ? 'pristine' : 'customized'
 }
 
 // Reconcile and persist the manifest after an install/resync run: keep prior
@@ -405,7 +418,7 @@ function isExistingSetup(dir) {
 // update; customized (edited) → keep + report, unless `force`.
 function resyncManagedFile(dir, target, manifest, force) {
   const { relPath, abs, bundled } = target
-  const state = managedState(dir, relPath, manifest)
+  const state = managedState(dir, relPath, manifest, bundled)
   const write = (bucket) => {
     ensureDir(path.dirname(abs))
     fs.writeFileSync(abs, bundled)
@@ -416,17 +429,25 @@ function resyncManagedFile(dir, target, manifest, force) {
   if (state === 'customized') {
     if (force) return write('updated')
     writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
-    return report.customized.push(relPath)
+    // Carry the change the user just DECLINED. A bare filename tells them a
+    // decision was made on their behalf but not what it was, which leaves
+    // "clobber and re-apply my edits by hand" as the only safe way to upgrade.
+    const { added, removed, hunks } = linesDiff(fs.readFileSync(abs, 'utf8'), bundled)
+    return report.customized.push({ relPath, added, removed, hunks })
   }
   // pristine — update only if the bundled content actually changed
   if (fs.readFileSync(abs, 'utf8') === bundled) {
+    // The file is ours and current, but the manifest disagreed — record the
+    // repair rather than healing in silence: a file that quietly starts
+    // updating again is as opaque as one that quietly stopped.
+    if (manifest.files[relPath] !== sha1(bundled)) report.healed.push(relPath)
     writtenHashes[relPath] = sha1(bundled)
     return report.skipped.push(relPath)
   }
   write('updated')
 }
 
-function resync(dir, { force = false, claudeMd = true } = {}) {
+function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
   const manifest = readManifest(dir)
@@ -436,7 +457,7 @@ function resync(dir, { force = false, claudeMd = true } = {}) {
   pruneRetiredManaged(dir, manifest)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
-  printReport(dir, 'resync')
+  printReport(dir, 'resync', { diff })
 }
 
 // The never-touch set: START AGAIN may only delete a known managed file, and may
@@ -502,7 +523,7 @@ function reset(dir, { claudeMd = true } = {}) {
   printReport(dir, 'reset')
 }
 
-function printReport(dir, mode) {
+function printReport(dir, mode, { diff = false } = {}) {
   const line = (label, items) => {
     if (!items.length) return
     process.stdout.write(`\n${label}:\n`)
@@ -512,12 +533,25 @@ function printReport(dir, mode) {
   line('created', report.created)
   line('updated', report.updated)
   line('removed', report.removed)
-  line('customized (kept)', report.customized)
+  line(
+    'customized (kept)',
+    report.customized.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
+  line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
   }
+  if (diff) {
+    for (const c of report.customized) {
+      if (!c.hunks.length) continue
+      process.stdout.write(`\n--- ${c.relPath} (kept — this is what you declined)\n`)
+      for (const h of c.hunks) process.stdout.write(`${h}\n`)
+    }
+  } else if (report.customized.length) {
+    process.stdout.write('\nRe-run with --diff to see the changes those files declined.\n')
+  }
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
   const isolationNote = isolationOn
     ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +

package/src/lines-diff.js

@@ -0,0 +1,114 @@
+'use strict'
+
+/**
+ * A minimal line diff — just enough for `update` to say what it skipped.
+ *
+ * `update` reports a file it kept as `customized (kept)` and nothing else, so
+ * there is no way to learn WHICH upstream changes you declined without diffing
+ * against `node_modules` by hand. That is how a real behavioural change (the
+ * lifecycle skills learning to commit their own edits) went unnoticed through an
+ * upgrade in the field.
+ *
+ * Zero dependencies on purpose: this package ships with none, and `diff(1)` is
+ * not a portable guarantee. An LCS over lines is a few dozen lines of code and
+ * the inputs are markdown files of a few hundred lines.
+ */
+
+// Longest-common-subsequence walk over two line arrays, as a flat op list.
+// `t` is ' ' (context), '-' (only in `a`) or '+' (only in `b`).
+function diffOps(a, b) {
+  const n = a.length
+  const m = b.length
+  // dp[i][j] = LCS length of a[i..] and b[j..], flattened.
+  const dp = new Int32Array((n + 1) * (m + 1))
+  const at = (i, j) => i * (m + 1) + j
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[at(i, j)] = a[i] === b[j] ? dp[at(i + 1, j + 1)] + 1 : Math.max(dp[at(i + 1, j)], dp[at(i, j + 1)])
+    }
+  }
+
+  const ops = []
+  let i = 0
+  let j = 0
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ t: ' ', line: a[i], a: i, b: j })
+      i++
+      j++
+    } else if (dp[at(i + 1, j)] >= dp[at(i, j + 1)]) {
+      ops.push({ t: '-', line: a[i], a: i, b: j })
+      i++
+    } else {
+      ops.push({ t: '+', line: b[j], a: i, b: j })
+      j++
+    }
+  }
+  while (i < n) {
+    ops.push({ t: '-', line: a[i], a: i, b: j })
+    i++
+  }
+  while (j < m) {
+    ops.push({ t: '+', line: b[j], a: i, b: j })
+    j++
+  }
+  return ops
+}
+
+// Group the ops into unified-diff hunks, each carrying `context` unchanged lines
+// either side of a run of changes. Runs closer together than 2×context merge, as
+// `diff -u` does, so a cluster of edits reads as one hunk.
+function toHunks(ops, context) {
+  const changed = ops.map((o) => o.t !== ' ')
+  const hunks = []
+  let k = 0
+  while (k < ops.length) {
+    if (!changed[k]) {
+      k++
+      continue
+    }
+    let start = Math.max(0, k - context)
+    let end = k
+    // Extend while the next change is near enough to keep in the same hunk.
+    for (let p = k; p < ops.length; p++) {
+      if (changed[p]) end = p
+      else if (p - end > context * 2) break
+    }
+    end = Math.min(ops.length - 1, end + context)
+
+    const body = ops.slice(start, end + 1)
+    const aStart = body[0].a + 1
+    const bStart = body[0].b + 1
+    const aLen = body.filter((o) => o.t !== '+').length
+    const bLen = body.filter((o) => o.t !== '-').length
+    hunks.push(
+      [`@@ -${aStart},${aLen} +${bStart},${bLen} @@`, ...body.map((o) => `${o.t}${o.line}`)].join('\n'),
+    )
+    k = end + 1
+  }
+  return hunks
+}
+
+/**
+ * Diff `a` (what is on disk) against `b` (what the package ships).
+ *
+ * `added`/`removed` count the lines an update WOULD add and remove — the summary
+ * printed beside a kept file. `hunks` are unified-diff blocks for `--diff`.
+ *
+ * @param {string|string[]} a
+ * @param {string|string[]} b
+ * @param {{context?:number}} [opts]
+ * @returns {{added:number, removed:number, hunks:string[]}}
+ */
+function linesDiff(a, b, { context = 3 } = {}) {
+  const A = Array.isArray(a) ? a : String(a).split('\n')
+  const B = Array.isArray(b) ? b : String(b).split('\n')
+  const ops = diffOps(A, B)
+  return {
+    added: ops.filter((o) => o.t === '+').length,
+    removed: ops.filter((o) => o.t === '-').length,
+    hunks: toHunks(ops, context),
+  }
+}
+
+module.exports = { linesDiff }

package/src/vendor/linear/cli-sync.js

@@ -10,6 +10,7 @@
  *
  *   spec-sync normalize <spec>   print the local projection (JSON)
  *   spec-sync push <spec>        print the create/update PLAN the skill applies
+ *                                (requires --workspace-states; see stateCheckFailure)
  *   spec-sync stamp <spec>       write returned ids back into the spec files
  *   spec-sync record <spec>      write the last-pushed snapshot (after apply)
  *   spec-sync status <spec>      read-only drift report (never writes)
@@ -35,6 +36,7 @@ const {
   isEmptyPlan,
   remoteWorkflowState,
   validateStates,
+  stateSuggestions,
   lintPhases,
   writeFrontmatter,
   stampSubIssueId,
@@ -178,16 +180,22 @@ function specSyncNormalize(dir, config, specArg, out, err) {
 // applies it over MCP then calls `record`.
 function specSyncPush(dir, config, specArg, flags, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
+  const failure = stateCheckFailure(config, flags)
+  if (failure) {
+    out.write(failure.join('\n') + '\n')
+    return 1
+  }
   const identifier = specIdentifier(snapshotDir, config)
   const r = push({ dir, snapshotDir, identifier, config })
   if (flags.json || !out.isTTY) {
     warnToErr(snapshotDir, config, err)
     out.write(JSON.stringify(r.plan, null, 2) + '\n')
-    return
+    return 0
   }
   const p = r.plan
   const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
+  if (p.legacy) lines.push(...legacyLines(p.legacy))
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
     if (p.issue) lines.push('  issue: description/state')
@@ -196,6 +204,84 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
     lines.push('  (run with --json for the full plan the skill applies)')
   }
   out.write(lines.join('\n') + '\n')
+  return 0
+}
+
+// The pre-9.0 mirror block. Loud on purpose: the plan below it looks entirely
+// ordinary — an all-creates plan for a spec that reads as unlinked — and
+// applying it mints a second mirror and abandons the first.
+function legacyLines(legacy) {
+  const found = legacy.keys.length ? legacy.keys.join(', ') : 'a pre-9.0 last-pushed snapshot'
+  const where = legacy.files.length ? ` in ${legacy.files.join(', ')}` : ''
+  const out = [
+    '  !! PRE-9.0 MIRROR — do not apply this plan as-is',
+    `     found ${found}${where}`,
+  ]
+  if (legacy.orphans) {
+    const o = legacy.orphans
+    out.push(
+      `     applying it would orphan ${o.total} live object(s): ` +
+        `${o.projects} project(s), ${o.milestones} milestone(s), ${o.issues} task issue(s)`,
+    )
+  }
+  out.push('     migrate first — see MIGRATION.md ("v8 → v9")')
+  return out
+}
+
+/**
+ * Validate the configured `states` names against the workspace, for a command
+ * that REFUSES without them.
+ *
+ * The engine is offline — `mcp.js` is the skill's adapter, not ours — so the
+ * names have to be fetched over MCP and handed in via `--workspace-states`. That
+ * handoff used to be advisory: `/spec-push` told the agent to run it against
+ * `status`, and skipping it sent a state name Linear **silently ignores** (the
+ * description lands, the issue never moves, nothing errors). Requiring the file
+ * turns the one check that catches it from a convention into a precondition.
+ *
+ * Returns null when the caller may proceed, or the lines to print before exiting
+ * non-zero.
+ */
+function stateCheckFailure(config, flags) {
+  if (flags.skipStateCheck) return null
+  if (!flags.workspaceStates) {
+    return [
+      'spec-sync push: refusing — the configured issue states have not been validated',
+      '  pass --workspace-states <file> (a JSON array of the workspace\'s issue',
+      '  workflow-state names, which /spec-push fetches over MCP), or',
+      '  --skip-state-check to push anyway.',
+      '  Linear silently ignores an unknown issue state: the push would look',
+      '  clean and the issue would never move.',
+    ]
+  }
+  if (!fs.existsSync(flags.workspaceStates)) {
+    return [`spec-sync push: refusing — no such --workspace-states file: ${flags.workspaceStates}`]
+  }
+  let names
+  try {
+    names = JSON.parse(fs.readFileSync(flags.workspaceStates, 'utf-8'))
+  } catch (error) {
+    return [`spec-sync push: refusing — --workspace-states is not valid JSON: ${error.message}`]
+  }
+  const list = Array.isArray(names) ? names : []
+  const missing = validateStates(config, list)
+  if (missing.length) {
+    // Say what IS available, and what to use instead. "Done is not a state" sends
+    // you to the Linear UI to go and look; naming the replacement does not.
+    const lines = ['spec-sync push: refusing — configured state name(s) not in the workspace', '']
+    for (const { bucket, configured, suggestion } of stateSuggestions(config, list)) {
+      lines.push(`  states.${bucket}: "${configured}" is not an issue state in this workspace`)
+      if (suggestion) lines.push(`    use "${suggestion}" instead`)
+    }
+    lines.push(
+      '',
+      `  available: ${list.join(', ') || '(the workspace reported none)'}`,
+      '  Fix specs/.core/linear.config.json → states. Linear silently ignores an',
+      '  unknown issue state, so this would have pushed clean and moved nothing.',
+    )
+    return lines
+  }
+  return null
 }
 
 // A tracker id as it appears in a spec: `SKI-42`. Deliberately strict — the
@@ -347,12 +433,13 @@ async function specSync(rest, io = {}) {
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null, issue: null, url: null, subs: [] }
+  const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [] }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
+    else if (args[i] === '--skip-state-check') flags.skipStateCheck = true
     else if (args[i] === '--issue') flags.issue = args[++i]
     else if (args[i] === '--url') flags.url = args[++i]
     else if (args[i] === '--sub') flags.subs.push(args[++i])
@@ -374,8 +461,7 @@ async function specSync(rest, io = {}) {
       specSyncNormalize(dir, config, positional[0], out, err)
       return 0
     case 'push':
-      specSyncPush(dir, config, positional[0], flags, out, err)
-      return 0
+      return specSyncPush(dir, config, positional[0], flags, out, err) || 0
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
@@ -387,7 +473,8 @@ async function specSync(rest, io = {}) {
       specSyncLinked(dir, config, flags, out)
       return 0
     default:
-      out.write('Usage: skitterspec spec-sync <normalize|push|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+      out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync push <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
         '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
         '       skitterspec spec-sync linked [--json]\n')
       return 0

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

@@ -10,12 +10,13 @@
  * over its API. No remote content is read or merged.
  */
 
-const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates } = require('./src/normalize.js')
+const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions } = require('./src/normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
 const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
+const { detectLegacyMirror } = require('./src/legacy.js')
 
 module.exports = {
   normalizeLocal,
@@ -31,6 +32,7 @@ module.exports = {
   remoteWorkflowState,
   titleFromText,
   validateStates,
+  stateSuggestions,
   hashField,
   stableStringify,
   readBase,
@@ -41,4 +43,5 @@ module.exports = {
   findPhaseFileByTitle,
   listPhaseFiles,
   sanitizeSpecMarkdown,
+  detectLegacyMirror,
 }

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

@@ -0,0 +1,90 @@
+'use strict'
+
+/**
+ * Detect a spec whose mirror was created under the **pre-9.0 model**.
+ *
+ * v9 remapped the mirror: a spec is an issue (was a Project), a phase is a
+ * sub-issue (was a Milestone), and tasks are no longer objects at all. The
+ * frontmatter keys moved with it — `linear_project_id` → `linear_identifier`,
+ * `linear_milestone_id` → `linear_issue_id`.
+ *
+ * The failure this guards is silent and destructive: v9 looks for the new keys,
+ * finds nothing, and produces a perfectly ordinary **all-creates** plan. Applying
+ * it mints a fresh mirror and abandons the old one — in the field that would have
+ * been 17 new objects against 2 projects, 15 milestones and 145 task issues left
+ * orphaned, with nothing on screen suggesting a prior mirror existed. It was
+ * caught only because an all-creates plan looked wrong for specs synced an hour
+ * earlier.
+ *
+ * Pure reads; returns `null` for anything that is not demonstrably pre-9.0, so a
+ * never-pushed spec is never mistaken for a stranded one.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { parseFrontmatter } = require('./normalize.js')
+const { readBase } = require('./base.js')
+const { listPhaseFiles } = require('./write.js')
+
+// Frontmatter keys only the pre-9.0 model ever wrote.
+const LEGACY_OVERVIEW_KEY = 'linear_project_id'
+const LEGACY_PHASE_KEY = 'linear_milestone_id'
+
+function frontmatterOf(file) {
+  try {
+    return parseFrontmatter(fs.readFileSync(file, 'utf-8')).data || {}
+  } catch {
+    return {}
+  }
+}
+
+// A pre-9.0 snapshot recorded `{project, milestones, issues}`; v9 records
+// `{issue, subIssues}`. Counting what it holds turns the warning from "this
+// looks old" into "this many live objects would be abandoned".
+function countOrphans(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null
+  const size = (v) => (Array.isArray(v) ? v.length : v && typeof v === 'object' ? Object.keys(v).length : 0)
+  const projects = snapshot.project ? 1 : 0
+  const milestones = size(snapshot.milestones)
+  const issues = size(snapshot.issues)
+  if (!projects && !milestones && !issues) return null
+  return { projects, milestones, issues, total: projects + milestones + issues }
+}
+
+/**
+ * @returns {null|{keys:string[], files:string[], orphans:object|null, orphanCount:number}}
+ */
+function detectLegacyMirror({ dir, snapshotDir, identifier, config }) {
+  const keys = []
+  const files = []
+
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
+  if (overview[LEGACY_OVERVIEW_KEY] != null) {
+    keys.push(LEGACY_OVERVIEW_KEY)
+    files.push(overviewFile)
+  }
+
+  for (const file of listPhaseFiles(snapshotDir)) {
+    if (frontmatterOf(path.join(snapshotDir, file))[LEGACY_PHASE_KEY] != null) {
+      if (!keys.includes(LEGACY_PHASE_KEY)) keys.push(LEGACY_PHASE_KEY)
+      files.push(file)
+    }
+  }
+
+  let orphans = null
+  try {
+    orphans = countOrphans(readBase(dir, identifier, config))
+  } catch {
+    /* an unreadable snapshot is not evidence either way */
+  }
+
+  // A legacy snapshot alone is enough: the spec may have had its frontmatter
+  // hand-cleaned while the mirror it names is still live.
+  if (!keys.length && !orphans) return null
+
+  return { keys, files, orphans, orphanCount: orphans ? orphans.total : 0 }
+}
+
+module.exports = { detectLegacyMirror }

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

@@ -343,13 +343,18 @@ function readPhaseFiles(snapshotDir) {
       // both sides keeps a wrapped goal from diffing forever.
       const goal = collapseHyphenAware((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
       // Rendered as markdown checklist lines, ready to drop into a sub-issue
-      // description: indentation kept so nesting survives, the bullet marker
-      // normalised to `-`, and any inline `(KEY-123)` stamped on a legacy task
+      // description: indentation kept so nesting survives, each bullet keeping
+      // 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 parsed = parseTaskLine(`[${b.mark}] ${b.text}`)
-        return `${b.indent}- [${b.mark}] ${parsed ? parsed.text : b.text}`
+        // `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
+        // exist in the repo.
+        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}`
       })
       return {
         phase: file.replace(/\.md$/, ''),
@@ -663,7 +668,43 @@ function validateStates(config, workspaceStates) {
   return configured.filter((name) => !have.has(name.toLowerCase().trim()))
 }
 
+// Words that identify a workspace state as belonging to a lifecycle bucket.
+// Used only to SUGGEST a replacement for a configured name the workspace does
+// not have — never to pick one silently. The 8→9 case this exists for is
+// `complete`, where the correct value inverts: the project status `Completed`
+// became the issue state `Done`, and no string-distance measure gets you from
+// one to the other.
+const BUCKET_WORDS = {
+  backlog: ['backlog', 'triage', 'todo', 'to do'],
+  'in-progress': ['in progress', 'in-progress', 'doing', 'started', 'in review'],
+  complete: ['done', 'complete', 'completed', 'shipped', 'merged', 'released'],
+  cancelled: ['canceled', 'cancelled', 'abandoned', "won't do", 'wont do', 'duplicate'],
+}
+
+/**
+ * For each configured state name the workspace lacks, what to use instead.
+ *
+ * `validateStates` says a name is wrong; this says what is right, which is the
+ * difference between an error you can act on and one you have to go look up.
+ *
+ * @returns {Array<{bucket:string, configured:string, suggestion:string|null}>}
+ */
+function stateSuggestions(config, workspaceStates) {
+  const names = (workspaceStates || []).map((s) => String(s)).filter(Boolean)
+  const have = new Set(names.map((n) => n.toLowerCase().trim()))
+  const out = []
+  for (const [bucket, configured] of Object.entries((config && config.states) || {})) {
+    if (typeof configured !== 'string') continue
+    if (have.has(configured.toLowerCase().trim())) continue
+    const words = BUCKET_WORDS[bucket] || []
+    const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
+    out.push({ bucket, configured, suggestion })
+  }
+  return out
+}
+
 module.exports = {
+  stateSuggestions,
   normalizeLocal,
   lintPhases,
   readSnapshot,

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

@@ -18,6 +18,7 @@
 const { normalizeLocal } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
+const { detectLegacyMirror } = require('./legacy.js')
 
 // Build the one-way projection from a local snapshot: the spec issue's prose +
 // status, and its phase sub-issues. `status` is the local lifecycle bucket; the
@@ -36,6 +37,12 @@ function push({ dir, snapshotDir, identifier, config }) {
   const projection = projectionOf(snapshotDir, config)
   const snapshot = readBase(dir, identifier, config)
   const plan = planChanges(projection, snapshot)
+  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
+  // plan above is all-creates and would abandon a live mirror. Carry the finding
+  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
+  // skill that applies this plan is exactly the consumer that would miss them.
+  const legacy = detectLegacyMirror({ dir, snapshotDir, identifier, config })
+  if (legacy) plan.legacy = legacy
   return { ok: true, empty: isEmptyPlan(plan), plan, projection }
 }
 

package/src/vendor/sync-core/src/task-block.js

@@ -25,6 +25,43 @@ const LIST_MARKER_RE = /^[ \t]*(?:[-*+]|\d+\.)\s/
 // A checkbox bullet — unambiguously a task, so it always starts its own block,
 // at any indent. (A bare list marker is ambiguous; a checkbox never is.)
 const CHECKBOX_RE = /^[ \t]*[-*+]\s*\[[ xX]\]/
+// A bare list bullet — no checkbox — captured with its marker so a sub-bullet
+// is re-rendered as the `-`/`*`/`1.` its author wrote.
+const BULLET_RE = /^([ \t]*)([-*+]|\d+\.)\s+(.*)$/
+
+function indentWidth(line) {
+  return line.length - line.trimStart().length
+}
+
+// Collect the wrapped continuation lines following the bullet opening at
+// `start`, seeded with the opener's own text. Shared by task bullets and plain
+// sub-bullets — both wrap the same way, and both stop at the first line that
+// belongs to something else.
+function collectContinuation(lines, start, hang, inFence, parts) {
+  let j = start + 1
+  for (; j < lines.length; j++) {
+    const l = lines[j]
+    if (!l.trim()) break
+    if (inFence[j]) break // a fence opening ends the bullet, never continues it
+    if (!CONTINUATION_RE.test(l)) break
+    if (BLOCK_BREAK_RE.test(l)) {
+      // Indent alone can't tell a nested child from a wrapped continuation —
+      // both sit at the hanging indent. The *marker* is the reliable signal:
+      //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
+      //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
+      //     sits exactly at the hang; shallower or deeper it's a real sub/
+      //     sibling list → break, and the caller's scan claims it as a block of
+      //     its own. (Keeping the at-hang continuation preserves the task's
+      //     stamped id, so the next push updates instead of creating a
+      //     duplicate issue.)
+      //   - headings, quotes, tables and fences always break.
+      if (CHECKBOX_RE.test(l)) break
+      if (!LIST_MARKER_RE.test(l) || indentWidth(l) !== hang) break
+    }
+    parts.push(l.trim())
+  }
+  return { end: j, parts }
+}
 
 // Mark every line that lies inside a fenced code block — the opening fence, its
 // content, and the closing fence all count as `true`. Line scanners that hunt
@@ -107,51 +144,68 @@ function spanMask(body) {
 }
 
 /**
- * Find every task bullet in `lines` as a logical block.
- * @returns {Array<{start:number, end:number, indent:string, mark:string, text:string}>}
+ * Find every task bullet in `lines` as a logical block, plus the non-checkbox
+ * bullets that live inside a task's list subtree.
+ * @returns {Array<{start:number, end:number, indent:string, marker:string,
+ *   checkbox:boolean, mark:string|null, text:string}>}
  *   `end` is exclusive. `text` is the collapsed single-line form, id included.
+ *   `checkbox` is false for a plain sub-bullet; its `mark` is then null and its
+ *   `marker` is the bullet it was written with (`-`, `*`, `1.` …).
  */
 function findTaskBlocks(lines) {
   const blocks = []
   const inFence = fenceMask(lines)
+  // The marker indents of the task bullets whose list subtree is still open,
+  // outermost first. Without this the scan had no model of nesting at all: a
+  // bare bullet that dedented out of a nested checkbox belonged to nothing and
+  // was silently dropped, taking its wrapped continuations with it.
+  const open = []
+
   for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // A blank line alone doesn't close a subtree — a loose list is still a list.
+    // What closes it is a later line at or shallower than the task's own indent.
+    if (!line.trim()) continue
+    const indent = indentWidth(line)
+    while (open.length && indent <= open[open.length - 1]) open.pop()
     if (inFence[i]) continue // an example bullet inside a ``` block is not a task
-    const m = TASK_START_RE.exec(lines[i])
-    if (!m) continue
-    const parts = [m[3]]
-    // The hanging indent: where the bullet's text starts (marker width). A
-    // wrapped continuation aligns exactly AT this column.
-    const hang = lines[i].length - m[3].length
-    let j = i + 1
-    for (; j < lines.length; j++) {
-      const l = lines[j]
-      if (!l.trim()) break
-      if (inFence[j]) break // a fence opening ends the bullet, never continues it
-      if (!CONTINUATION_RE.test(l)) break
-      if (BLOCK_BREAK_RE.test(l)) {
-        // Indent alone can't tell a nested child from a wrapped continuation —
-        // both sit at the hanging indent. The *marker* is the reliable signal:
-        //   - a checkbox (- [ ] / - [x]) is unambiguously a task → always break;
-        //   - a bare marker (-/*/+/N.) is wrapped continuation prose ONLY when it
-        //     sits exactly at the hang; shallower or deeper it's a real sub/
-        //     sibling list → break. (Keeping the at-hang continuation preserves
-        //     the task's stamped id, so the next push updates instead of
-        //     creating a duplicate issue.)
-        //   - headings, quotes, tables and fences always break.
-        if (CHECKBOX_RE.test(l)) break
-        const indent = l.length - l.trimStart().length
-        if (!LIST_MARKER_RE.test(l) || indent !== hang) break
-      }
-      parts.push(l.trim())
+
+    const t = TASK_START_RE.exec(line)
+    if (t) {
+      // The hanging indent: where the bullet's text starts (marker width). A
+      // wrapped continuation aligns exactly AT this column.
+      const { end, parts } = collectContinuation(lines, i, line.length - t[3].length, inFence, [t[3]])
+      blocks.push({
+        start: i,
+        end,
+        indent: t[1],
+        marker: '-',
+        checkbox: true,
+        mark: t[2].toLowerCase() === 'x' ? 'x' : ' ',
+        text: collapseHyphenAware(parts.join('\n')),
+      })
+      open.push(indent)
+      i = end - 1
+      continue
     }
+
+    // A bare bullet is claimed ONLY inside an open task's subtree. Outside one
+    // it is ordinary prose in the phase file: the projection is the task list,
+    // not the whole body, and widening it here would mirror a Notes section.
+    if (!open.length) continue
+    const b = BULLET_RE.exec(line)
+    if (!b) continue
+    const { end, parts } = collectContinuation(lines, i, line.length - b[3].length, inFence, [b[3]])
     blocks.push({
       start: i,
-      end: j,
-      indent: m[1],
-      mark: m[2].toLowerCase() === 'x' ? 'x' : ' ',
+      end,
+      indent: b[1],
+      marker: b[2],
+      checkbox: false,
+      mark: null,
       text: collapseHyphenAware(parts.join('\n')),
     })
-    i = j - 1
+    i = end - 1
   }
   return blocks
 }

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

@@ -128,6 +128,7 @@ function stampIssueId(snapshotDir, text, id) {
     const lines = fs.readFileSync(p, 'utf-8').split('\n')
     const width = inferWidth(lines)
     for (const b of findTaskBlocks(lines)) {
+      if (!b.checkbox) continue // a plain sub-bullet is not a task — never stamp one
       if (INLINE_ID_RE.test(b.text)) continue
       if (b.text !== want) continue
       const rendered = renderTaskBlock({ indent: b.indent, done: b.mark === 'x', text: want, id }, width)