@skitterbyte/skitterspec-linear 3.4.0 → 5.0.0

package/src/env/live.js

@@ -0,0 +1,348 @@
+'use strict'
+
+/**
+ * Live-overlay receipt — the advisory record of which spec currently holds the
+ * primary checkout for live testing.
+ *
+ * The *authority* on "who's live" is the branch checked out in the primary
+ * checkout (see `assertPrimaryOnMain` in resolve.js): on the base branch → free;
+ * on a feature branch → that spec is in control. This receipt is only metadata —
+ * it powers `live status` and crash recovery (`live abort` reads `baseMainCommit`
+ * from here to restore the primary checkout). It lives beside the slot registry
+ * at the primary checkout root (`.spec-env/live.json`, gitignored).
+ *
+ * `receiptPath`/`renderReceipt`/`summarizeReceipt` are pure; `read`/`write`/`clear`
+ * are the thin IO seam the CLI drives, mirroring env/registry.js. No `Date.now()`
+ * — the caller passes `heldSince`.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
+
+// Absolute path to the receipt — a sibling of the configured registry file, so it
+// follows wherever `.spec-env` is configured (default `.spec-env/live.json`).
+function receiptPath(rootDir, config) {
+  return path.resolve(rootDir, path.dirname(config.registry), 'live.json')
+}
+
+// Normalize receipt fields into the persisted shape. Pure; throws on a missing
+// field so a half-formed receipt is never written.
+function renderReceipt(fields) {
+  for (const key of REQUIRED) {
+    if (!fields || !fields[key]) throw new Error(`live receipt: missing ${key}`)
+  }
+  const receipt = {}
+  for (const key of REQUIRED) receipt[key] = String(fields[key])
+  return receipt
+}
+
+// Read the receipt. Missing file → null (no one is live). Malformed JSON → Error.
+function readReceipt(rootDir, config) {
+  const file = receiptPath(rootDir, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(
+      `Invalid live receipt ${path.dirname(config.registry)}/live.json: ${error.message}`,
+    )
+  }
+}
+
+// Persist the receipt, creating its parent dir as needed. Returns the written shape.
+function writeReceipt(rootDir, config, fields) {
+  const receipt = renderReceipt(fields)
+  const file = receiptPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + '\n')
+  return receipt
+}
+
+// Remove the receipt. Idempotent: clearing an absent receipt is a clean no-op.
+function clearReceipt(rootDir, config) {
+  const file = receiptPath(rootDir, config)
+  try {
+    fs.unlinkSync(file)
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+}
+
+// A one-line human summary of a receipt (or the "free" state when null). Pure.
+function summarizeReceipt(receipt) {
+  if (!receipt) return 'free — no spec is live'
+  return (
+    `${receipt.spec} (branch ${receipt.branch}) — ` +
+    `held by ${receipt.holder} since ${receipt.heldSince}`
+  )
+}
+
+// --- stateful detection (glob matching) -----------------------------------
+
+// Translate a restricted glob into an anchored RegExp: `**` matches across path
+// separators (with an optional trailing `/`), `*` matches within a segment, `?`
+// a single non-separator char. Enough for migration-path globs, no dependency.
+function globToRegExp(glob) {
+  let re = ''
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i]
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*'
+        i++
+        if (glob[i + 1] === '/') i++ // consume the `/` in `**/`
+      } else {
+        re += '[^/]*'
+      }
+    } else if (ch === '?') {
+      re += '[^/]'
+    } else if ('.+^${}()|[]\\/'.includes(ch)) {
+      re += '\\' + ch
+    } else {
+      re += ch
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+// True when any file path matches any of the migration globs. Empty patterns or
+// no files → false (nothing configured / nothing changed).
+function migrationsHit(files, patterns) {
+  if (!Array.isArray(files) || !files.length) return false
+  if (!Array.isArray(patterns) || !patterns.length) return false
+  const res = patterns.map(globToRegExp)
+  return files.some((f) => res.some((r) => r.test(f)))
+}
+
+// --- take planner ---------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live take`. Validates the preconditions for putting
+ * a spec live on the running instance by branch-switch, and returns either a
+ * structured refusal or the ordered git steps + the receipt to write. All git /
+ * port state is probed by the CLI and passed in `ctx`, keeping this deterministic
+ * and unit-testable with no live git.
+ *
+ * ctx:
+ *   primary        { onBase, branch, baseBranch } — the guard result for the primary checkout
+ *   primaryPath    absolute path of the primary checkout (the checkout target)
+ *   clean          boolean — primary checkout working tree is clean
+ *   worktreeExists boolean — the spec's worktree is on disk
+ *   base           resolved base branch name (rebase target)
+ *   baseMainCommit primary HEAD before the switch (receipt / crash recovery)
+ *   serverUp       true | false | null — null = no canonical ports declared → no gate
+ *   canonicalPorts number[] — declared canonical (frontPort) ports, for messages
+ *   migrationsHit  boolean — the branch diff touches configured migration globs
+ *   depsChanged    boolean — the branch diff touches a lockfile/manifest (→ warn)
+ *   holder,heldSince receipt provenance (injected by the CLI; no Date.now here)
+ *
+ * @returns {object} { blocked, reason, commands, warnings, receipt, base, branch, worktreePath }
+ */
+function planTake(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const base = c.base
+  const result = {
+    blocked: false,
+    reason: null,
+    commands: [],
+    warnings: [],
+    receipt: null,
+    base,
+    branch,
+    worktreePath: spec.worktreePath,
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // 1. The lock: the primary checkout must be on base (free). Off-base → a spec
+  //    (or you) already holds the live instance.
+  if (!c.primary || !c.primary.onBase) {
+    const on = c.primary && c.primary.branch ? c.primary.branch : '(detached)'
+    return block(
+      `primary checkout is on ${on}, not ${base} — a spec already holds the live ` +
+        'instance; release it with `/spec-live main` first',
+    )
+  }
+  // 2. Never switch a dirty tree — the checkout is reset back to base on release.
+  if (!c.clean) {
+    return block('primary checkout has uncommitted changes — commit or stash them first')
+  }
+  // 3. Need a worktree holding the branch to detach and hand over.
+  if (!c.worktreeExists) {
+    return block(`${spec.folder} has no worktree — run \`/spec-go ${spec.folder}\` first`)
+  }
+  // 4. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
+  if (spec.stack === 'docker') {
+    return block(
+      `${spec.folder} is stateful (Stack: worktree + docker) — live overlay is ` +
+        'code-only; use `/spec-connect` for a Docker-backed spec',
+    )
+  }
+  // 5. …and refuse a branch that changes migrations (would mutate the shared DB).
+  if (c.migrationsHit) {
+    return block(
+      `${spec.folder}'s branch changes migrations — live overlay is code-only; ` +
+        'use `/spec-connect`',
+    )
+  }
+  // 6. Verify-only: a dev server must be listening to hot-reload the switch.
+  if (c.serverUp === false) {
+    return block(
+      `no dev server listening on canonical port(s) ${(c.canonicalPorts || []).join(', ')} — ` +
+        'start your dev server (or `skitterspec spec-env dev up`) first',
+    )
+  }
+
+  const warnings = []
+  if (c.depsChanged) {
+    warnings.push('dependencies changed on this branch — restart your dev server after the switch')
+  }
+  if (c.serverUp === null) {
+    warnings.push('no canonical dev ports configured — nothing to hot-reload; switching anyway')
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${spec.worktreePath} rebase ${base}`,
+      `git -C ${spec.worktreePath} switch --detach`,
+      `git -C ${c.primaryPath} checkout ${branch}`,
+    ],
+    warnings,
+    receipt: {
+      spec: spec.folder,
+      branch,
+      holder: c.holder,
+      heldSince: c.heldSince,
+      baseMainCommit: c.baseMainCommit,
+    },
+  }
+}
+
+// --- release planner ------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live release` — hand the running instance back to
+ * base and re-isolate the spec's branch into its worktree (the graceful exit of
+ * an unfinished session). All git state is probed by the CLI and passed in.
+ *
+ * In the branch-switch model `take` never moves the base ref, so release is just
+ * `checkout base` (frees the branch) then re-attach it to the worktree — no reset.
+ *
+ * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists }
+ * @returns {object} { blocked, noop, reason, commands, clears, base, branch, worktreePath }
+ */
+function planRelease(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const base = c.base
+  const result = {
+    blocked: false,
+    noop: false,
+    reason: null,
+    commands: [],
+    clears: false,
+    base,
+    branch,
+    worktreePath: spec.worktreePath,
+  }
+
+  // Nothing live — the primary checkout is already on base.
+  if (c.primary && c.primary.onBase) {
+    return { ...result, noop: true, reason: `nothing is live — the primary checkout is on ${base}` }
+  }
+  // A different spec holds the instance.
+  if (c.primary && c.primary.branch !== branch) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `the live spec is ${c.primary.branch}, not ${branch} — release that one`,
+    }
+  }
+  // Fixes made while live must be committed to the branch first (never discarded).
+  if (!c.clean) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `primary checkout has uncommitted changes — commit your fixes to ${branch} first`,
+    }
+  }
+
+  const commands = [`git -C ${c.primaryPath} checkout ${base}`]
+  if (c.worktreeExists) commands.push(`git -C ${spec.worktreePath} switch ${branch}`)
+  return { ...result, commands, clears: true }
+}
+
+// --- abort planner --------------------------------------------------------
+
+/**
+ * Pure planner for `spec-env live abort` — crash recovery. Works from the receipt
+ * (not a resolved spec), so it recovers even when the spec folder can't be found.
+ * Conservative: it refuses to discard uncommitted work, and won't force anything
+ * without a receipt to tell it what "live" was.
+ *
+ * Like release, recovery is `checkout base` + re-isolate — no `reset --hard`:
+ * branch-switch never moved base, and resetting to the receipt's recorded commit
+ * would discard any legitimate advance of base. `baseMainCommit` stays a record.
+ *
+ * ctx: { receipt, primary:{onBase,branch}, primaryPath, base, clean, worktreeExists, worktreePath }
+ * @returns {object} { blocked, noop, reason, commands, clears, base, branch }
+ */
+function planAbort(config, ctx) {
+  const c = ctx || {}
+  const base = c.base
+  const result = { blocked: false, noop: false, reason: null, commands: [], clears: false, base, branch: null }
+
+  if (!c.receipt) {
+    if (c.primary && c.primary.onBase) {
+      return { ...result, noop: true, reason: `nothing is live — the primary checkout is on ${base}` }
+    }
+    const on = c.primary && c.primary.branch ? c.primary.branch : '(detached)'
+    return {
+      ...result,
+      blocked: true,
+      reason:
+        `no live receipt, but the primary checkout is on ${on} — no recorded base ` +
+        `to restore; check out ${base} manually once you're sure it's safe`,
+    }
+  }
+
+  // Receipt present. Never discard uncommitted work — surface it instead.
+  if (!c.clean) {
+    return {
+      ...result,
+      blocked: true,
+      reason:
+        'the primary checkout has uncommitted changes that abort would discard — ' +
+        'commit or stash them (or resolve manually) first',
+    }
+  }
+
+  const branch = c.receipt.branch
+  const commands = []
+  if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${c.primaryPath} checkout ${base}`)
+  if (c.worktreeExists) commands.push(`git -C ${c.worktreePath} switch ${branch}`)
+  return { ...result, commands, clears: true, branch }
+}
+
+module.exports = {
+  receiptPath,
+  renderReceipt,
+  readReceipt,
+  writeReceipt,
+  clearReceipt,
+  summarizeReceipt,
+  globToRegExp,
+  migrationsHit,
+  planTake,
+  planRelease,
+  planAbort,
+}

package/src/env/resolve.js

@@ -165,6 +165,29 @@ function resolvePrimaryCheckout(dir, git) {
   return common ? path.dirname(path.resolve(dir, common)) : dir
 }
 
+/**
+ * The current branch of a checkout, or `null` when detached (or not a repo).
+ * `git` is a reader bound to the target checkout — for the live-overlay guard the
+ * CLI binds it to the primary checkout. (`symbolic-ref --short HEAD` exits
+ * non-zero on a detached HEAD, which the reader maps to `null`.)
+ */
+function currentBranch(git) {
+  return git(['symbolic-ref', '--short', 'HEAD'])
+}
+
+/**
+ * The live-overlay guard: is the primary checkout on the integration base branch
+ * (free) or on a feature branch (a spec is in control)? Returns
+ * `{ onBase, branch, baseBranch }` — a structured result, never a throw, so each
+ * caller phrases its own refusal. `git` must be bound to the primary checkout.
+ * `onBase` is false on a detached HEAD (`branch === null`), which is not the base.
+ */
+function assertPrimaryOnMain(config, git) {
+  const baseBranch = resolveBaseBranch(config, git)
+  const branch = currentBranch(git)
+  return { onBase: branch === baseBranch, branch, baseBranch }
+}
+
 /**
  * Resolve a spec argument to its identity + isolation coordinates.
  * Throws a clear Error when the spec folder can't be found.
@@ -208,6 +231,8 @@ module.exports = {
   resolveSpec,
   resolveBaseBranch,
   resolvePrimaryCheckout,
+  currentBranch,
+  assertPrimaryOnMain,
   branchFor,
   splitPrefix,
   repoInfo,

package/src/init.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
@@ -52,7 +53,12 @@ const CORE_FILES = listCoreTemplates()
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], removed: [], customized: [], warnings: [] }
+
+function resetReport() {
+  for (const k of Object.keys(report)) report[k].length = 0
+  for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
+}
 
 // Folder index files scaffolded by earlier versions, now retired. `init`/`update`
 // deletes any left behind so upgrading projects don't keep stale caches.
@@ -69,7 +75,109 @@ function ensureDir(p) {
   if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true })
 }
 
+// --- install manifest (safe re-run baseline) --------------------------------
+//
+// specs/.core/.skitterspec-manifest.json records, per managed file, the sha1 of
+// the content we last wrote. It's the baseline that lets a later resync tell "an
+// 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 MANIFEST_FILE = path.join('specs', '.core', '.skitterspec-manifest.json')
+const MANIFEST_VERSION = 1
+
+// Hashes of files actually written in the current run (populated by writeFile),
+// reset each init() alongside `report`.
+const writtenHashes = {}
+
+function sha1(content) {
+  return crypto.createHash('sha1').update(content).digest('hex')
+}
+
+// The full managed set for a target dir: repo-relative path, absolute path, and
+// the bundled content that ships in this distribution's assets.
+function managedTargets(dir) {
+  const out = []
+  const add = (assetRel, targetAbs) =>
+    out.push({
+      relPath: rel(dir, targetAbs),
+      abs: targetAbs,
+      bundled: fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'),
+    })
+  for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
+  for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
+  return out
+}
+
+// Read the manifest (tolerant: missing/malformed → an empty baseline).
+function readManifest(dir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8'))
+    if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
+      return { version: parsed.version || MANIFEST_VERSION, files: parsed.files }
+    }
+  } catch {
+    /* missing or malformed → empty baseline */
+  }
+  return { version: MANIFEST_VERSION, files: {} }
+}
+
+function writeManifest(dir, files) {
+  const target = path.join(dir, MANIFEST_FILE)
+  ensureDir(path.dirname(target))
+  const sorted = {}
+  for (const k of Object.keys(files).sort()) sorted[k] = files[k]
+  fs.writeFileSync(target, JSON.stringify({ version: MANIFEST_VERSION, files: sorted }, null, 2) + '\n')
+}
+
+// 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) {
+  const abs = path.join(dir, relPath)
+  if (!fs.existsSync(abs)) return 'missing'
+  const known = manifest.files[relPath]
+  return known && sha1(fs.readFileSync(abs, 'utf8')) === known ? 'pristine' : 'customized'
+}
+
+// Reconcile and persist the manifest after an install/resync run: keep prior
+// entries, apply files written this run, seed any pre-existing managed file that
+// has no entry yet from its bundled hash (migration for repos predating the
+// manifest), and prune entries whose file is gone.
+function flushManifest(dir) {
+  // Only managed files belong in the manifest — never live user config (e.g. an
+  // env.config.json that installIsolation happens to write through writeFile).
+  const managed = managedTargets(dir)
+  const managedRel = new Set(managed.map((t) => t.relPath))
+  const merged = { ...readManifest(dir).files, ...writtenHashes }
+  const next = {}
+  for (const [relPath, hash] of Object.entries(merged)) {
+    if (managedRel.has(relPath)) next[relPath] = hash
+  }
+  for (const { relPath, abs, bundled } of managed) {
+    if (!next[relPath] && fs.existsSync(abs)) next[relPath] = sha1(bundled) // migration seed
+  }
+  for (const relPath of Object.keys(next)) {
+    if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
+  }
+  writeManifest(dir, next)
+}
+
 function writeFile(dir, target, content, { force }) {
+  // A dangling symlink (its target no longer exists) is invisible to existsSync,
+  // which follows the link — but the link itself is still on disk, so a plain
+  // writeFileSync would follow it into a missing directory and throw ENOENT.
+  // Drop the broken link and write a real file in its place.
+  let link = null
+  try {
+    link = fs.lstatSync(target)
+  } catch {
+    /* no such path — nothing to clean up */
+  }
+  if (link && link.isSymbolicLink() && !fs.existsSync(target)) {
+    fs.unlinkSync(target)
+  }
   if (fs.existsSync(target)) {
     if (!force) {
       report.skipped.push(rel(dir, target))
@@ -77,15 +185,19 @@ function writeFile(dir, target, content, { force }) {
     }
     const existing = fs.readFileSync(target, 'utf8')
     if (existing === content) {
+      // Already the content we'd write — record it as ours (pristine).
+      writtenHashes[rel(dir, target)] = sha1(content)
       report.skipped.push(rel(dir, target))
       return
     }
     fs.writeFileSync(target, content)
+    writtenHashes[rel(dir, target)] = sha1(content)
     report.updated.push(rel(dir, target))
     return
   }
   ensureDir(path.dirname(target))
   fs.writeFileSync(target, content)
+  writtenHashes[rel(dir, target)] = sha1(content)
   report.created.push(rel(dir, target))
 }
 
@@ -253,6 +365,118 @@ function installClaudeMd(dir, { mode }) {
   report.updated.push('CLAUDE.md (appended spec workflow section)')
 }
 
+// --- detection, resync, reset (safe re-run) ---------------------------------
+
+// True when the repo looks already set up: any managed file present, any spec
+// lifecycle folder, or the CLAUDE.md spec marker (Decision 1 — detect eagerly).
+function isExistingSetup(dir) {
+  if (managedTargets(dir).some((t) => fs.existsSync(t.abs))) return true
+  if (SPEC_FOLDERS.some((f) => fs.existsSync(path.join(dir, 'specs', f)))) return true
+  const claude = path.join(dir, 'CLAUDE.md')
+  return fs.existsSync(claude) && fs.readFileSync(claude, 'utf8').includes(SPEC_MARKER_START)
+}
+
+// RESYNC: bring managed files to the latest bundled version WITHOUT clobbering
+// user edits. Per file: missing → create; pristine (matches the manifest) →
+// 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 write = (bucket) => {
+    ensureDir(path.dirname(abs))
+    fs.writeFileSync(abs, bundled)
+    writtenHashes[relPath] = sha1(bundled)
+    report[bucket].push(relPath)
+  }
+  if (state === 'missing') return write('created')
+  if (state === 'customized') {
+    if (force) return write('updated')
+    writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
+    return report.customized.push(relPath)
+  }
+  // pristine — update only if the bundled content actually changed
+  if (fs.readFileSync(abs, 'utf8') === bundled) {
+    writtenHashes[relPath] = sha1(bundled)
+    return report.skipped.push(relPath)
+  }
+  write('updated')
+}
+
+function resync(dir, { force = false, claudeMd = true } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  resetReport()
+  const manifest = readManifest(dir)
+  for (const t of managedTargets(dir)) resyncManagedFile(dir, t, manifest, force)
+  installFolders(dir)
+  removeRetiredFiles(dir)
+  if (claudeMd) installClaudeMd(dir, { mode: 'update' })
+  flushManifest(dir)
+  printReport(dir, 'resync')
+}
+
+// The never-touch set: START AGAIN may only delete a known managed file, and may
+// never delete spec content or active config (defense-in-depth — the manifest
+// never lists these, but a tampered/foreign entry must still be refused).
+const PROTECTED_SPEC_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
+const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json']
+const PROTECTED_DIRS = ['linear-base', 'linear-backups']
+
+function assertSafeToDelete(relPath, managedSet) {
+  const norm = relPath.split(path.sep).join('/')
+  for (const b of PROTECTED_SPEC_BUCKETS) {
+    if (norm.startsWith(`specs/${b}/`)) throw new Error(`refusing to delete spec content: ${relPath}`)
+  }
+  if (PROTECTED_CONFIG.includes(path.posix.basename(norm))) {
+    throw new Error(`refusing to delete active config: ${relPath}`)
+  }
+  for (const d of PROTECTED_DIRS) {
+    if (norm.includes(`/${d}/`)) throw new Error(`refusing to delete sync state: ${relPath}`)
+  }
+  if (!managedSet.has(norm)) throw new Error(`refusing to delete a non-managed path: ${relPath}`)
+}
+
+// Remove the marked spec-workflow block from CLAUDE.md (leaves the rest intact).
+function stripClaudeMdSection(dir) {
+  const target = path.join(dir, 'CLAUDE.md')
+  if (!fs.existsSync(target)) return
+  const existing = fs.readFileSync(target, 'utf8')
+  const next = existing.replace(
+    new RegExp(`\\n?${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`),
+    '\n',
+  )
+  if (next !== existing) {
+    fs.writeFileSync(target, next)
+    report.removed.push('CLAUDE.md (spec workflow section)')
+  }
+}
+
+// START AGAIN: delete exactly the manifest-listed managed files (each guarded),
+// strip the CLAUDE.md marked section, then reinstall fresh. Never touches a
+// non-manifest path. Destructive by design for managed files (that's the point).
+function reset(dir, { claudeMd = true } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  resetReport()
+  const manifest = readManifest(dir)
+  const managedSet = new Set(managedTargets(dir).map((t) => t.relPath.split(path.sep).join('/')))
+  for (const relPath of Object.keys(manifest.files)) {
+    assertSafeToDelete(relPath, managedSet)
+    const abs = path.join(dir, relPath)
+    if (fs.existsSync(abs)) {
+      fs.unlinkSync(abs)
+      report.removed.push(relPath)
+    }
+  }
+  if (claudeMd) stripClaudeMdSection(dir)
+  installSkills(dir, { force: true })
+  installRule(dir, { force: true })
+  installFolders(dir)
+  removeRetiredFiles(dir)
+  installCore(dir, { force: true })
+  if (claudeMd) installClaudeMd(dir, { mode: 'init' })
+  flushManifest(dir)
+  printReport(dir, 'reset')
+}
+
 function printReport(dir, mode) {
   const line = (label, items) => {
     if (!items.length) return
@@ -263,6 +487,7 @@ function printReport(dir, mode) {
   line('created', report.created)
   line('updated', report.updated)
   line('removed', report.removed)
+  line('customized (kept)', report.customized)
   line('unchanged', report.skipped)
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
@@ -285,11 +510,7 @@ function printReport(dir, mode) {
 
 async function init({ dir, force, claudeMd, mode, isolation }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
-  report.created.length = 0
-  report.updated.length = 0
-  report.skipped.length = 0
-  report.removed.length = 0
-  report.warnings.length = 0
+  resetReport()
 
   installSkills(dir, { force })
   installRule(dir, { force })
@@ -300,6 +521,10 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
+  // Record what we wrote (and migrate a pre-manifest repo) so a later resync can
+  // tell our files from the user's.
+  flushManifest(dir)
+
   printReport(dir, mode)
 }
 
@@ -308,4 +533,14 @@ module.exports = {
   SKILLS,
   RULES,
   SPEC_FOLDERS,
+  MANIFEST_FILE,
+  sha1,
+  readManifest,
+  writeManifest,
+  managedTargets,
+  managedState,
+  isExistingSetup,
+  resync,
+  reset,
+  assertSafeToDelete,
 }