@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/init.js

@@ -0,0 +1,1150 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+
+const { ensureWorktreeDirTrusted } = require('./env/trust.js')
+const { ensureHooks } = require('./env/hooks.js')
+const { repoInfo, expandTokens } = require('./env/resolve.js')
+
+const ASSETS = path.join(__dirname, '..', 'assets')
+
+// Skills, rules, and specs/.core templates are discovered from the bundled assets
+// tree rather than hardcoded, so each distribution installs exactly what it ships:
+// the tracker-free base carries the neutral skill set + env.config templates; a
+// provider superset (built by composing its fragments in) additionally carries its
+// sync skills and provider config templates, and they install with no code change.
+function listSkills() {
+  const dir = path.join(ASSETS, 'skills')
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort()
+}
+
+// Slash commands shipped as `assets/commands/*.md`, installed to
+// `.claude/commands/`. Discovered from the bundled tree exactly like skills, so
+// each distribution installs precisely what it ships.
+function listCommands() {
+  const dir = path.join(ASSETS, 'commands')
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no commands
+  }
+}
+
+// Hook scripts shipped as `assets/hooks/*.cjs` (or `*.mjs`), installed to
+// `.claude/hooks/`. Discovered from the bundled tree like everything else, so a
+// distribution installs precisely what it ships and a hook can be retired by
+// deleting it.
+//
+// A BARE `.js` IS DELIBERATELY NOT DISCOVERED. These files are copied into the
+// TARGET project, where that project's `package.json` — the one file skitterspec
+// does not control — decides how node parses a `.js`. Shipping CommonJS as `.js`
+// crashed the review-gate hook in every `"type": "module"` project, on every
+// Bash tool call. The extension is the only thing that settles it at the file,
+// so both accepted forms pin it; `env-review-hook.test.js` asserts the rule over
+// the whole directory rather than over this filter.
+function listHooks() {
+  try {
+    return fs
+      .readdirSync(path.join(ASSETS, 'hooks'))
+      .filter((f) => f.endsWith('.cjs') || f.endsWith('.mjs'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no hooks
+  }
+}
+
+function listRules() {
+  return fs
+    .readdirSync(path.join(ASSETS, 'rules'))
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+}
+
+// Templates scaffolded into specs/.core/ (the *.example configs + their *.md docs).
+// A consumer copies an example → live config to adopt the matching feature.
+function listCoreTemplates() {
+  return fs
+    .readdirSync(path.join(ASSETS, 'core'))
+    .filter((f) => f.endsWith('.example') || f.endsWith('.md'))
+    .sort()
+    .map((f) => path.join('core', f))
+}
+
+const SKILLS = listSkills()
+
+const COMMANDS = listCommands()
+
+const RULES = listRules()
+
+const HOOKS = listHooks()
+
+const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
+
+// Opt-in config templates, scaffolded into specs/.core/ (the base ships the
+// env.config isolation templates; a provider superset also ships its own).
+const CORE_FILES = listCoreTemplates()
+
+// A command file pre-executes the CLI, so it must carry a literal invocation
+// that actually resolves in THIS project. Three installs are possible — local
+// dependency, global, or none — and the runner differs for each.
+//
+// A LOCKFILE DOES NOT ANSWER THIS QUESTION. It says which runner would be used
+// *if* the CLI were installed here, which is a different thing, and reading it
+// as evidence of an install is inferring from an absence
+// (`.claude/rules/negative-checks.md` rule 1). It cost the non-Node case
+// outright: a project with no lockfile got `npx skitterspec` baked into every
+// command file, and the unscoped name `skitterspec` does not exist on npm, so
+// all four 404'd.
+//
+// So the lockfile keeps the job it is good at — picking the runner once a local
+// install is established — and a ladder decides whether there is one.
+const PACKAGE_MANAGERS = [
+  ['pnpm-lock.yaml', 'pnpm exec'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npx'],
+  ['bun.lockb', 'bunx'],
+]
+
+// Which runner would reach a LOCAL install here? Rung 1's answer only — it says
+// nothing about whether the CLI is present, which is `detectRunner`'s job.
+function detectPackageManager(dir) {
+  for (const [lockfile, exec] of PACKAGE_MANAGERS) {
+    if (fs.existsSync(path.join(dir, lockfile))) return exec
+  }
+  return 'npx'
+}
+
+// The bin names a distribution may expose. A provider superset ships its own
+// name alongside `skitterspec`, and either proves the engine is reachable.
+const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
+
+function binNames() {
+  return process.platform === 'win32'
+    ? ENGINE_BINS.flatMap((n) => [n, `${n}.cmd`, `${n}.exe`])
+    : ENGINE_BINS
+}
+
+// Rung 1 — a local install, found by walking up. Bounded at 6 levels, matching
+// the hooks' own `findEngine`: a git worktree's checkout has its own
+// `node_modules`, and a monorepo package hoists to the root.
+function hasLocalInstall(dir) {
+  let at = path.resolve(dir)
+  for (let i = 0; i < 6; i++) {
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(at, 'node_modules', '.bin', name))) return true
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return false
+}
+
+// An npx cache bin directory. Matched on the path SEGMENT, so a project that
+// happens to live under a directory called `_npxtools` is not mistaken for one.
+const NPX_CACHE_RE = /[\\/]_npx[\\/]/
+
+// Rung 2 — a global install, found on PATH.
+//
+// WHAT WOULD FOOL THIS, and why the filter is not optional: `npx` PREPENDS its
+// own cache bin directory to PATH for the processes it spawns. Verified, not
+// assumed. So running `npx @skitterbyte/skitterspec init` puts a `skitterspec`
+// on PATH that exists only for the duration of that one command — and probing
+// for it here would bake a bare `skitterspec …` into four COMMITTED files that
+// stop working the moment init exits. Excluding `_npx` entries is what makes
+// this rung evidence of an install rather than evidence of the install running.
+function hasPathInstall(env = process.env) {
+  const raw = env.PATH || env.Path || ''
+  if (!raw) return false
+  for (const entry of raw.split(path.delimiter)) {
+    if (!entry || NPX_CACHE_RE.test(entry)) continue
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(entry, name))) return true
+    }
+  }
+  return false
+}
+
+/**
+ * How should a command file invoke the CLI here?
+ *
+ * A positive-signal ladder: each rung asserts something that must be PRESENT,
+ * and only the last is a fallback.
+ *
+ *   local — a local install; the lockfile picks the runner
+ *   path  — a global install; no runner at all, the bin is invoked bare
+ *   none  — neither could be found. `npx` is written as before, and the caller
+ *           warns, because this is the cannot-tell case rather than a third
+ *           kind of install (rule 4: the unknown routes to the harmless branch,
+ *           which here is "write what we always wrote and say so").
+ *
+ * PROJECT-VISIBLE SIGNALS OUTRANK MACHINE-VISIBLE ONES, which is why `local` is
+ * checked first. `.claude/commands/*.md` is committed and `renderCommand` feeds
+ * `managedTargets`, so a render that varies by machine makes the file flip
+ * between pristine and updatable as different people run `update`. A lockfile
+ * is committed and answers the same everywhere; PATH is one machine's business.
+ */
+function detectRunner(dir, env = process.env) {
+  if (hasLocalInstall(dir)) return { runner: detectPackageManager(dir), rung: 'local' }
+  if (hasPathInstall(env)) return { runner: '', rung: 'path' }
+  return { runner: 'npx', rung: 'none' }
+}
+
+// Fill a command file's `{{exec}}` placeholders. Kept a pure function of
+// (content, dir) so `managedTargets` can compare against exactly what
+// `installCommands` would write — otherwise every install would hash as
+// customized on the next run.
+//
+// The token is consumed WITH its trailing space, so an empty runner leaves
+// `Bash(skitterspec …)` rather than `Bash( skitterspec …)`. The second pass
+// catches a bare `{{exec}}` in case a template ever lands without one.
+function renderCommand(content, dir) {
+  const { runner } = detectRunner(dir)
+  return content
+    .split('{{exec}} ')
+    .join(runner ? `${runner} ` : '')
+    .split('{{exec}}')
+    .join(runner)
+}
+
+// --- composed-assets guard -------------------------------------------------
+//
+// A source package's `assets/` is PRE-composition: `<!-- seam:NAME -->` is still
+// literal text that scripts/build-dist.js replaces — with a provider's fragment
+// for the provider distribution, with nothing for the base. Only a built
+// distribution's assets are installable.
+//
+// This is a POSITIVE signal, not an absence: a seam marker must be **present**
+// for the guard to fire, so it cannot misfire on a tree it simply failed to read.
+// And it refuses rather than repairing — installing the wrong thing is the
+// expensive mistake here. In a dev-linked checkout the installed skills are
+// symlinks to the composed distribution, so a `--force` install would write
+// these markers straight through the link and into the built assets.
+const SEAM_RE = /<!--\s*seam:[A-Za-z0-9_-]+\s*-->/
+
+function assetFiles(dir) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return // a distribution need not ship every asset kind
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(dir)
+  return out
+}
+
+// Throws when this package's assets are uncomposed. Called from the **bins** —
+// the outermost boundary, and the only way a real install happens — never from
+// init()/resync()/run(), which the unit tests legitimately drive against this
+// source tree. Guarding any deeper would make the library untestable while
+// protecting nothing extra.
+function assertComposedAssets() {
+  const offenders = assetFiles(ASSETS)
+    .filter((f) => SEAM_RE.test(fs.readFileSync(f, 'utf8')))
+    .map((f) => path.relative(ASSETS, f))
+  if (!offenders.length) return
+  throw new Error(
+    `refusing to install: this package's assets are uncomposed (${offenders.length} ` +
+      `file(s) still carry a <!-- seam:… --> marker, e.g. ${offenders[0]}).\n` +
+      '  These are a workspace source package\'s assets, not a distribution\'s. ' +
+      'Run "npm run build" in the skitterspec repo, then run the command again ' +
+      'from the built distribution.',
+  )
+}
+
+const SPEC_MARKER_START = '<!-- skitterspec:start -->'
+const SPEC_MARKER_END = '<!-- skitterspec:end -->'
+
+const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], adopted: [], healed: [], warnings: [], suggestions: [] }
+
+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.
+const RETIRED_FILES = [
+  path.join('specs', 'backlog', '00-index.md'),
+  path.join('specs', 'complete', '00-index.md'),
+]
+
+function rel(dir, p) {
+  return path.relative(dir, p) || '.'
+}
+
+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 { linesDiff } = require('./lines-diff.js')
+
+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, render = (c) => c) =>
+    out.push({
+      relPath: rel(dir, targetAbs),
+      abs: targetAbs,
+      bundled: render(fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'), dir),
+    })
+  for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of COMMANDS)
+    add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
+  for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
+  for (const name of HOOKS) add(path.join('hooks', name), path.join(dir, '.claude', 'hooks', 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).
+// `baselined` answers a question `files` cannot: could this manifest have SEEN
+// a path? It is true only when the file parsed into the expected shape AND
+// records at least one entry — a POSITIVE signal, not an absence, which is what
+// lets `managedState` read a path's absence from it as evidence of anything
+// (`.claude/rules/negative-checks.md` rule 1).
+//
+// WHAT WOULD FOOL IT: nothing silently. A missing manifest and a malformed one
+// both fall into the same empty baseline below — correct for reading hashes,
+// and useless for reasoning about absence, since on a repo with no manifest yet
+// EVERY path is absent. Both answer `baselined: false`, so the one conclusion
+// that depends on it is simply not drawn.
+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,
+        baselined: Object.keys(parsed.files).length > 0,
+      }
+    }
+  } catch {
+    /* missing or malformed → empty baseline */
+  }
+  return { version: MANIFEST_VERSION, files: {}, baselined: false }
+}
+
+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   — 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
+//   adopted    — a path this version has NEWLY CLAIMED, where the project
+//                already had a file: it differs from what we ship, and the
+//                manifest that could have named it does not. Keep it too — the
+//                two states differ only in what the report CLAIMS about it.
+//
+// The split exists because `customized` made a false statement about the second
+// case. "Your edit — kept" describes our file at a path upstream had not
+// claimed, and the reader acts on it: v21 renamed the commit hook to
+// `review-gate.cjs`, which is the same name anyone would have picked to work
+// around v20's ESM crash — so their shim was kept, the real hook was never
+// installed, and `review-gate.js` was pruned out from under it. The shim fails
+// open, so the gate went silently absent under a report that said success.
+//
+// WHAT WOULD FOOL THIS, and why neither does:
+//   - A repo with no manifest (or an unreadable one) has EVERY path absent.
+//     `baselined` is the positive signal that gates the conclusion, so those
+//     fall back to `customized` — which keeps the file either way
+//     (`.claude/rules/negative-checks.md` rules 1 and 4).
+//   - The signal is ONE-SHOT. `flushManifest`'s migration seed gives any
+//     present managed file an entry on the very next run, so an adopted path
+//     reads `customized` from then on. Anyone who already upgraded has spent
+//     it — which is why the `.cjs` trap is also written into MIGRATION.md,
+//     where that reader is actually looking.
+//
+// `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]
+  if (known) return sha1(onDisk) === known ? 'pristine' : 'customized'
+  return manifest.baselined ? 'adopted' : '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)
+  }
+  // A LIVE symlink is the opposite case, and `--force` is what makes it
+  // dangerous: `writeFileSync` follows the link, so forcing would write composed
+  // content — seam markers resolved, provider text spliced in — straight through
+  // it and into whatever it points at. In a checkout that dogfoods its own
+  // assets that is `packages/*/assets`, i.e. the SOURCE the link exists to keep
+  // live. Refuse: the staleness `--force` was reached for is a smaller problem
+  // than corrupting the file it would overwrite.
+  //
+  // WHAT WOULD MAKE THIS LIE: a HARD link. It has no distinguishing lstat — it
+  // simply is the file — so it takes the same corrupting path and nothing here
+  // can see it. Out of scope deliberately, and said out loud rather than left to
+  // be discovered; nothing in this project's install creates one.
+  //
+  // It cannot fire in an ordinary consumer install, because nothing there is
+  // linked — `skitterspec update` writes copies by design.
+  if (force && link && link.isSymbolicLink() && fs.existsSync(target)) {
+    report.refused.push(rel(dir, target))
+    return
+  }
+  if (fs.existsSync(target)) {
+    if (!force) {
+      report.skipped.push(rel(dir, target))
+      return
+    }
+    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))
+}
+
+function copyAsset(dir, assetRelPath, targetAbs, opts) {
+  const content = fs.readFileSync(path.join(ASSETS, assetRelPath), 'utf8')
+  writeFile(dir, targetAbs, content, opts)
+}
+
+function installSkills(dir, opts) {
+  for (const name of SKILLS) {
+    copyAsset(
+      dir,
+      path.join('skills', name, 'SKILL.md'),
+      path.join(dir, '.claude', 'skills', name, 'SKILL.md'),
+      opts,
+    )
+  }
+}
+
+function installCommands(dir, opts) {
+  for (const name of COMMANDS) {
+    const content = renderCommand(
+      fs.readFileSync(path.join(ASSETS, 'commands', name), 'utf8'),
+      dir,
+    )
+    writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
+  }
+
+  // ONLY on the cannot-tell rung, and it warns rather than refusing: `init` has
+  // real work to do either way — skills, rules, folders — and none of it needs
+  // the CLI reachable later. Silence here is what let a project install cleanly
+  // and hand back four commands that 404 on first use.
+  if (COMMANDS.length && detectRunner(dir).rung === 'none') {
+    report.warnings.push(
+      `the skitterspec CLI could not be found here, so the ${COMMANDS.length} slash ` +
+        'command(s) were written to call `npx skitterspec`, which will fail — ' +
+        'install it (npm i -g @skitterbyte/skitterspec, or add it as a dev ' +
+        'dependency) and re-run `skitterspec update` to rewrite them',
+    )
+  }
+}
+
+function installRule(dir, opts) {
+  for (const name of RULES) {
+    copyAsset(
+      dir,
+      path.join('rules', name),
+      path.join(dir, '.claude', 'rules', name),
+      opts,
+    )
+  }
+}
+
+// Register the review-gate hook in the project's committed settings, so a
+// phase that owes a verdict is enforced one level below the skills. Best-effort
+// in exactly the way `trustWorktreeRoot` is: a settings file we cannot parse is
+// reported and left alone, never rewritten, and never fatal — the hook is an
+// extra layer, and the engine and `/spec-next` hold the gate without it.
+function registerReviewGateHook(dir) {
+  // "hooks", plural, because two ship now — the review gate and the main guard.
+  // The label names the file and the subject rather than one script, so adding a
+  // third does not leave a report that undercounts what it wrote.
+  const label = '.claude/settings.json (skitterspec hooks)'
+  let res
+  try {
+    res = ensureHooks(dir)
+  } catch {
+    report.warnings.push('could not write .claude/settings.json — skitterspec hooks not registered')
+    return
+  }
+  if (res.reason === 'malformed') {
+    report.warnings.push(
+      '.claude/settings.json is not valid JSON — did not register the skitterspec hooks',
+    )
+  } else if (res.reason === 'created') {
+    report.created.push(label)
+  } else if (res.reason === 'added') {
+    report.updated.push(label)
+  } else if (res.reason === 'migrated') {
+    // A WRITE, so it may not fall through to `skipped`. It was doing exactly
+    // that: rewriting the registered path and then reporting "already
+    // registered" — a run that acts and says it did not, which is the shape of
+    // the bug this whole change exists to fix.
+    report.updated.push('.claude/settings.json (skitterspec hooks repointed at the renamed script)')
+  } else {
+    report.skipped.push('.claude/settings.json (skitterspec hooks already registered)')
+  }
+}
+
+function installHooks(dir, opts) {
+  for (const name of HOOKS) {
+    copyAsset(dir, path.join('hooks', name), path.join(dir, '.claude', 'hooks', name), opts)
+  }
+  registerReviewGateHook(dir)
+}
+
+function installFolders(dir) {
+  for (const folder of SPEC_FOLDERS) {
+    const abs = path.join(dir, 'specs', folder)
+    if (!fs.existsSync(abs)) {
+      ensureDir(abs)
+      report.created.push(rel(dir, abs) + '/')
+      // keep otherwise-empty folders in git
+      if (!fs.readdirSync(abs).length) {
+        fs.writeFileSync(path.join(abs, '.gitkeep'), '')
+      }
+    } else {
+      report.skipped.push(rel(dir, abs) + '/')
+    }
+  }
+}
+
+// Delete retired folder index files left by earlier versions. If removing one
+// empties its bucket, drop a `.gitkeep` so the folder stays tracked in git.
+function removeRetiredFiles(dir) {
+  for (const relPath of RETIRED_FILES) {
+    const target = path.join(dir, relPath)
+    if (!fs.existsSync(target)) continue
+    fs.unlinkSync(target)
+    report.removed.push(rel(dir, target))
+    const folder = path.dirname(target)
+    if (fs.existsSync(folder) && !fs.readdirSync(folder).length) {
+      fs.writeFileSync(path.join(folder, '.gitkeep'), '')
+    }
+  }
+}
+
+// Prune a file the manifest records as managed but the current package no longer
+// ships — a retired skill (e.g. `spec-pull` after the one-way switch), rule, or
+// template. Without this, upgrading leaves a live, model-visible skill on disk
+// whose instructions invoke a command that no longer exists. Delete it only when
+// PRISTINE (still matches the hash we last wrote) so a user edit is never lost; a
+// customized retired file is kept with a warning. An emptied skill folder is
+// removed. Takes the pre-flush manifest (which still holds the retired entries).
+function pruneRetiredManaged(dir, manifest) {
+  const managedRel = new Set(managedTargets(dir).map((t) => t.relPath))
+  for (const relPath of Object.keys(manifest.files || {})) {
+    if (managedRel.has(relPath)) continue // still shipped by this version
+    const abs = path.join(dir, relPath)
+    if (!fs.existsSync(abs)) continue // already gone
+    if (managedState(dir, relPath, manifest) === 'customized') {
+      report.warnings.push(`retired but kept (you edited it): ${relPath} — delete manually if unused`)
+      continue
+    }
+    fs.unlinkSync(abs)
+    report.removed.push(rel(dir, abs))
+    const folder = path.dirname(abs)
+    if (fs.existsSync(folder) && !fs.readdirSync(folder).length) fs.rmdirSync(folder)
+  }
+}
+
+// Scaffold the opt-in isolation templates into specs/.core/ (the example config
+// + its field docs). Copied, not activated: the feature stays off until the
+// consumer copies env.config.json.example → env.config.json.
+function installCore(dir, opts) {
+  for (const asset of CORE_FILES) {
+    copyAsset(
+      dir,
+      asset,
+      path.join(dir, 'specs', '.core', path.basename(asset)),
+      opts,
+    )
+  }
+}
+
+// Activate opt-in per-spec isolation: write specs/.core/env.config.json from the
+// example asset so /spec-start provisions a worktree for every in-progress spec.
+// Only called when the operator opts in, and never on `update` (adopting isolation
+// is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
+// never clobbers an existing env.config.json without --force.
+function installIsolation(dir, { enabled, workspaceMode }, opts) {
+  if (!enabled) return
+  const target = path.join(dir, 'specs', '.core', 'env.config.json')
+  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
+
+  // Only 'checkout' is written; 'worktree' is already what the template says and
+  // what the loader defaults to, so the common path leaves the file untouched.
+  // Guarded by existsSync because copyAsset legitimately declines to overwrite a
+  // config the operator already customized — rewriting it here would undo that.
+  if (workspaceMode === 'checkout' && fs.existsSync(target)) {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'))
+    parsed.mode = 'checkout'
+    fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
+  }
+  trustWorktreeRoot(dir)
+}
+
+// Activate opt-in release gating: write specs/.core/gating.config.json from the
+// example asset, so /spec and friends start asking whether a change ships behind
+// a feature flag and recording the answer.
+//
+// Only called when the operator opts in, and NEVER on `update` — for the same
+// reason as isolation: adopting a policy is a deliberate choice, not something a
+// re-sync flips on. Idempotent; copyAsset never clobbers an existing config
+// without --force, so an operator's edited `guidance` survives a re-init.
+function installGating(dir, { enabled }, opts) {
+  if (!enabled) return
+  copyAsset(
+    dir,
+    path.join('core', 'gating.config.json.example'),
+    path.join(dir, 'specs', '.core', 'gating.config.json'),
+    opts,
+  )
+}
+
+// Seed the absolute worktree root into .claude/settings.local.json (gitignored)
+// so the operator enabling isolation isn't prompted on every edit into a
+// freshly-provisioned worktree. Best-effort: an unreadable config or malformed
+// settings file is reported, never fatal. `spec-env up` re-ensures this on every
+// provision, so a miss here self-heals.
+function trustWorktreeRoot(dir) {
+  let root
+  try {
+    const cfg = JSON.parse(
+      fs.readFileSync(path.join(dir, 'specs', '.core', 'env.config.json'), 'utf8'),
+    )
+    root = cfg && cfg.worktree && cfg.worktree.root
+  } catch {
+    /* fall through to the warning below */
+  }
+  if (!root) {
+    report.warnings.push('could not read worktree.root — skipped trusting the worktree dir')
+    return
+  }
+  const { repo, repoSlug } = repoInfo(dir)
+  const rootAbs = path.resolve(dir, expandTokens(root, { repo, repoSlug }))
+  const res = ensureWorktreeDirTrusted(dir, rootAbs)
+  const label = '.claude/settings.local.json (trusted worktree root)'
+  if (res.reason === 'malformed') {
+    report.warnings.push(
+      '.claude/settings.local.json is not valid JSON — did not trust the worktree' +
+        ` dir; add ${rootAbs} to permissions.additionalDirectories yourself`,
+    )
+  } else if (res.reason === 'created') {
+    report.created.push(label)
+  } else if (res.reason === 'added') {
+    report.updated.push(label)
+  } else {
+    report.skipped.push('.claude/settings.local.json (worktree root already trusted)')
+  }
+}
+
+// Is the CLAUDE.md section this project has installed the one we ship?
+//
+// THREE answers, not two. `differs` deliberately does NOT mean "stale": the
+// block is a COPY, so a difference is either an out-of-date copy or the user's
+// own edit, and from here those read identically. Rule 4 of
+// `.claude/rules/negative-checks.md` — route the unknown case to the harmless
+// branch, which here means reporting a difference and naming the fix rather
+// than accusing them of being behind.
+//
+// WHAT WOULD FOOL THIS: absent markers mean the section was never installed, OR
+// that someone stripped it deliberately (`stripClaudeMdSection` exists and is
+// reachable from `reset`). Neither is a fault, so both answer `not installed`
+// and neither is reported as a problem.
+function claudeMdSectionState(dir) {
+  const target = path.join(dir, 'CLAUDE.md')
+  if (!fs.existsSync(target)) return 'not installed'
+  const existing = fs.readFileSync(target, 'utf8')
+  if (!existing.includes(SPEC_MARKER_START) || !existing.includes(SPEC_MARKER_END)) {
+    return 'not installed'
+  }
+  const shipped = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
+  const start = existing.indexOf(SPEC_MARKER_START) + SPEC_MARKER_START.length
+  const installed = existing.slice(start, existing.indexOf(SPEC_MARKER_END)).trim()
+  return installed === shipped ? 'fresh' : 'differs'
+}
+
+// `update --check`: say what `update` would change, write nothing, exit 0.
+// It reports; `update` without the flag stays the only thing that touches a
+// file. This exists because the section is a copy and a copy goes quietly out
+// of date — this repo's own was a whole spec behind the template it ships,
+// through a spec about that template, with every test green.
+function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  const manifest = readManifest(dir)
+  const rows = []
+  // Mirror `resyncManagedFile`'s decision exactly rather than re-deriving it:
+  // missing → it would create; customized → it would KEEP yours and say so;
+  // pristine → it would write only when the shipped content actually differs.
+  for (const { relPath, abs, bundled } of managedTargets(dir)) {
+    const state = managedState(dir, relPath, manifest, bundled)
+    if (state === 'missing') rows.push([relPath, 'missing — would be created'])
+    else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
+    else if (state === 'adopted')
+      rows.push([relPath, 'adopted upstream — yours kept, theirs not installed (--force takes theirs)'])
+    else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
+  }
+  const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
+  // A healthy area says NOTHING. A report that lists what is already fine is a
+  // report people learn to skim, and then the one line that mattered is missed.
+  if (section === 'differs') {
+    rows.push([
+      'CLAUDE.md (spec workflow section)',
+      'differs from the shipped one — `update` would replace it (it is a copy, so this is either your edit or an out-of-date one)',
+    ])
+  }
+  if (!rows.length) log('skitterspec update --check: everything is up to date.')
+  else {
+    log('skitterspec update --check: `skitterspec update` would:')
+    for (const [name, why] of rows) log(`  ${name} — ${why}`)
+  }
+  return { rows, section }
+}
+
+function installClaudeMd(dir, { mode }) {
+  const section = fs.readFileSync(path.join(ASSETS, 'claude-md-section.md'), 'utf8').trim()
+  const block = `${SPEC_MARKER_START}\n${section}\n${SPEC_MARKER_END}\n`
+  const target = path.join(dir, 'CLAUDE.md')
+
+  if (!fs.existsSync(target)) {
+    fs.writeFileSync(target, `# ${path.basename(dir)}\n\n${block}`)
+    report.created.push('CLAUDE.md')
+    return
+  }
+
+  const existing = fs.readFileSync(target, 'utf8')
+
+  if (existing.includes(SPEC_MARKER_START) && existing.includes(SPEC_MARKER_END)) {
+    if (mode !== 'update') {
+      report.skipped.push('CLAUDE.md (spec workflow already present)')
+      return
+    }
+    const re = new RegExp(`${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
+    const next = existing.replace(re, block)
+    if (next === existing) {
+      report.skipped.push('CLAUDE.md')
+    } else {
+      fs.writeFileSync(target, next)
+      report.updated.push('CLAUDE.md (spec workflow section)')
+    }
+    return
+  }
+
+  if (/^##\s+Spec workflow/m.test(existing)) {
+    report.skipped.push('CLAUDE.md (has a manual "Spec workflow" section — left alone)')
+    return
+  }
+
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n'
+  fs.writeFileSync(target, `${existing}${sep}${block}`)
+  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).
+// Is skitterspec already installed here? Matched on what we ACTUALLY install —
+// our managed files, our lifecycle folders, our CLAUDE.md marker — never on
+// `.claude/` merely existing: someone else's skills are not evidence of ours,
+// and reading them as ours would treat every Claude Code project as a
+// half-finished install.
+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, bundled)
+  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')
+  // `adopted` writes exactly as `customized` does — keep unless forced. Only the
+  // bucket differs, because only the REPORT was ever wrong about it.
+  if (state === 'customized' || state === 'adopted') {
+    if (force) return write('updated')
+    writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
+    // 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[state].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, diff = false } = {}) {
+  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)
+  pruneRetiredManaged(dir, manifest)
+  // The hook SCRIPT arrives above, as one more managed target; registering it is
+  // a separate write to a file we do not manage, so it has to be asked for here.
+  // It is easy to read this as duplication of `installHooks()` and delete it —
+  // it is not. `installHooks()` is unreachable from this path, and the two
+  // halves being in different functions is exactly how they drifted apart once:
+  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
+  // project, while reporting a file created. `init-review-gate-hook.test.js`
+  // asserts over the entry points rather than over this call.
+  registerReviewGateHook(dir)
+  if (claudeMd) installClaudeMd(dir, { mode: 'update' })
+  suggestReleaseWith(dir)
+  flushManifest(dir)
+  printReport(dir, 'resync', { diff })
+}
+
+// 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', 'jira.config.json', 'github.config.json', 'azure-boards.config.json']
+const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups', 'github-base', 'github-backups', 'azure-base', 'azure-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 })
+  installCommands(dir, { force: true })
+  installRule(dir, { force: true })
+  installHooks(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, { diff = false } = {}) {
+  const line = (label, items) => {
+    if (!items.length) return
+    process.stdout.write(`\n${label}:\n`)
+    for (const it of items) process.stdout.write(`  ${it}\n`)
+  }
+  process.stdout.write(`\nskitterspec ${mode} → ${dir}\n`)
+  line('created', report.created)
+  line('updated', report.updated)
+  line('removed', report.removed)
+  line(
+    'customized (kept)',
+    report.customized.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
+  line(
+    'adopted upstream (kept — ours was never installed)',
+    report.adopted.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
+  line('manifest repaired', report.healed)
+  line('unchanged', report.skipped)
+  if (report.refused.length) {
+    process.stdout.write('\nrefused (a symlink — writing would overwrite what it points at):\n')
+    for (const it of report.refused) process.stdout.write(`  ${it}\n`)
+    process.stdout.write(
+      '  These are links into the shipped assets. --force would follow them and\n' +
+        '  write composed content into the source. Unlink one to take the copy\n' +
+        '  (rm <path>, then re-run), or leave it linked and edit the asset.\n',
+    )
+  }
+  if (report.suggestions.length) {
+    process.stdout.write('\nsuggestions:\n')
+    for (const x of report.suggestions) process.stdout.write(`  - ${x}\n`)
+  }
+  if (report.warnings.length) {
+    process.stdout.write('\nwarnings:\n')
+    for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
+  }
+  const declined = [
+    ...report.customized.map((c) => [c, 'kept — this is what you declined']),
+    ...report.adopted.map((c) => [c, 'kept — this is what was not installed']),
+  ]
+  if (diff) {
+    for (const [c, why] of declined) {
+      if (!c.hunks.length) continue
+      process.stdout.write(`\n--- ${c.relPath} (${why})\n`)
+      for (const h of c.hunks) process.stdout.write(`${h}\n`)
+    }
+  } else if (declined.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' +
+      ' at /spec-start (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
+    : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
+      ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
+  const gatingOn = fs.existsSync(path.join(dir, 'specs', '.core', 'gating.config.json'))
+  const gatingNote = gatingOn
+    ? 'Release gating is ON: /spec asks whether a change ships behind a feature' +
+      ' flag and records the answer on the spec (skitterspec gating check reports' +
+      ' any that have none).\n'
+    : 'Release gating is opt-in: re-run with --gating (or copy' +
+      ' specs/.core/gating.config.json.example → gating.config.json) to enable it.\n'
+  // A provider superset ships its own `spec-<provider>-setup` skill; the base
+  // ships none. Discovering it from what was actually installed keeps this file
+  // tracker-free — it never has to know which tracker (if any) is in the box.
+  const setupSkill = SKILLS.find((s) => /^spec-.+-setup$/.test(s))
+  const provider = setupSkill ? /^spec-(.+)-setup$/.exec(setupSkill)[1] : null
+  // …and the same derivation gives the provider's config filename, so this can
+  // report tracker sync the way it reports isolation above — from what is
+  // actually on disk. It used to say "opt-in: run /…-setup" even on a repo that
+  // had already configured it, telling you to set up what was already set up.
+  const trackerOn =
+    provider && fs.existsSync(path.join(dir, 'specs', '.core', `${provider}.config.json`))
+  const trackerNote = !setupSkill
+    ? ''
+    : trackerOn
+      ? `Tracker sync is ON: ${provider} — the repo stays the source of truth;` +
+        ' /spec-push mirrors a spec up and /spec-status reports drift.\n'
+      : `Tracker sync is opt-in: run /${setupSkill} to configure it` +
+        ' (it discovers your workspace and writes the config), or see' +
+        ' specs/.core/SETUP.md.\n'
+  process.stdout.write(
+    '\nDone. Skills resolve as /spec, /spec-start, /spec-next, /spec-complete,' +
+      ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
+      'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
+      " project's stack, then run /spec.\n" +
+      isolationNote +
+      gatingNote +
+      trackerNote,
+  )
+}
+
+// `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
+// unrelated to the config's own `mode` key — which arrives as `workspaceMode`
+// precisely so the two cannot be confused at a call site.
+/**
+ * Suggest `hotfix.releaseWith` where skittership's hotfix release is installed
+ * and nothing is configured yet. SUGGESTED, NEVER WRITTEN: it changes what a
+ * hotfix land does — a version commit and the project's own tag scheme — and
+ * that is the project's decision, not something an install makes for it.
+ *
+ * Silent unless both signals are present: the script on disk, and an
+ * isolation config that leaves `releaseWith` empty. A config that cannot be
+ * read is cannot-tell, and says nothing.
+ */
+function suggestReleaseWith(dir) {
+  if (!fs.existsSync(path.join(dir, 'scripts', 'release-hotfix.cjs'))) return
+  let loaded
+  try {
+    loaded = require('./env/config.js').loadEnvConfig(dir)
+  } catch {
+    return
+  }
+  if (!loaded || !loaded.present || loaded.config.hotfix.releaseWith) return
+  report.suggestions.push(
+    'scripts/release-hotfix.cjs is installed — to have hotfix land cut its release, set ' +
+      '"hotfix": { "releaseWith": "node scripts/release-hotfix.cjs --json" } in ' +
+      'specs/.core/env.config.json',
+  )
+}
+
+async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating }) {
+  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
+  resetReport()
+
+  installSkills(dir, { force })
+  installCommands(dir, { force })
+  installRule(dir, { force })
+  installHooks(dir, { force })
+  installFolders(dir)
+  removeRetiredFiles(dir)
+  installCore(dir, { force })
+  // Adopting isolation writes the live env.config.json — init only, never update.
+  if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
+  if (mode !== 'update') installGating(dir, { enabled: gating }, { force })
+  if (claudeMd) installClaudeMd(dir, { mode })
+  suggestReleaseWith(dir)
+
+  // 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)
+}
+
+module.exports = {
+  init,
+  // A snapshot of the last run's report, for tests that need to assert on what a
+  // run DECIDED rather than only on what it left on disk. Copied, so a caller
+  // cannot mutate the live report between phases of a run.
+  lastReport: () => JSON.parse(JSON.stringify(report)),
+  SKILLS,
+  COMMANDS,
+  RULES,
+  SPEC_FOLDERS,
+  MANIFEST_FILE,
+  sha1,
+  readManifest,
+  writeManifest,
+  managedTargets,
+  managedState,
+  claudeMdSectionState,
+  checkSync,
+  isExistingSetup,
+  resync,
+  reset,
+  assertSafeToDelete,
+  assertComposedAssets,
+  detectPackageManager,
+  detectRunner,
+  renderCommand,
+}