@skitterbyte/skitterspec-linear 9.2.0 → 10.0.1

package/MIGRATION.md

@@ -0,0 +1,292 @@
+# 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),
+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-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 →
+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,26 @@ team) that the config reference (`linear.config.md`) assumes you already have.
 
 ---
 
+## 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
 
 Install the Linear superset (or, if you already run the base, switch to it — it
@@ -173,10 +193,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

@@ -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",
@@ -54,7 +61,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.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",
@@ -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' +