@skitterbyte/skitterspec 16.2.0 → 16.3.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

@@ -22,6 +22,25 @@ This installs the skills + rules into `.claude/`, scaffolds `specs/`, and patche
 `CLAUDE.md`. See `.claude/rules/spec-planning.md` after install to set your
 project's typecheck/test/lint commands.
 
+## Upgrading
+
+```sh
+npx @skitterbyte/skitterspec 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.
+
 ## Pick one distribution
 
 Ticketing sync is a **separate superset you install instead of this one**:

package/package.json

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