nccgs 2.0.0 → 2.1.1

package/scripts/install.mjs

@@ -1,515 +1,530 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  equivalentFiles,
-  fingerprintFile,
-  matchesFingerprint,
-  sameFingerprint
-} from "../.claude/nccgs/tools/integrity.mjs";
-import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
-import { executionPolicy } from "../.claude/nccgs/tools/policy.mjs";
-import { autonomyPolicy, canonicalHookCommand } from "../.claude/nccgs/tools/autonomy.mjs";
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const root = path.resolve(scriptDir, "..");
-const args = process.argv.slice(2);
-const projectIndex = args.indexOf("--project");
-const dryRun = args.includes("--dry-run");
-const force = args.includes("--force");
-const updateOnly = args.includes("--update-only");
-const allowNonUnity = args.includes("--allow-non-unity");
-const modelProfileIndex = args.indexOf("--model-profile");
-const requestedModelProfile = modelProfileIndex >= 0 ? args[modelProfileIndex + 1] : null;
-const autonomyIndex = args.indexOf("--autonomy");
-const requestedAutonomy = autonomyIndex >= 0 ? args[autonomyIndex + 1] : null;
-if (autonomyIndex >= 0 && !["full", "guarded"].includes(requestedAutonomy)) {
-  console.error("--autonomy requires full or guarded"); process.exit(2);
-}
-
-if (projectIndex >= 0 && !args[projectIndex + 1]) {
-  console.error("--project requires a directory path.");
-  process.exit(2);
-}
-
-const project = projectIndex >= 0 ? path.resolve(args[projectIndex + 1]) : process.cwd();
-try { assertProjectRoot(project); }
-catch (error) {
-  console.error(`Unsafe installation target: ${error.message}`);
-  process.exit(2);
-}
-if (project === root) {
-  console.error("The NCCGS package directory cannot be its own installation target.");
-  process.exit(2);
-}
-
-const unityMarkers = ["Assets", "Packages", "ProjectSettings"];
-const missingMarkers = unityMarkers.filter((item) => !fs.existsSync(projectPath(item)));
-if (missingMarkers.length && !allowNonUnity) {
-  console.error(`Target does not look like a Unity project; missing: ${missingMarkers.join(", ")}`);
-  console.error("Use --allow-non-unity only when intentionally scaffolding before Unity project creation.");
-  process.exit(2);
-}
-
-const validation = spawnSync(process.execPath, [path.join(scriptDir, "validate.mjs")], {
-  cwd: root,
-  encoding: "utf8",
-});
-if (validation.status !== 0) {
-  process.stderr.write(validation.stdout ?? "");
-  process.stderr.write(validation.stderr ?? "");
-  console.error("NCCGS package validation failed; installation aborted.");
-  process.exit(1);
-}
-
-const frameworkSource = path.join(root, ".claude");
-const frameworkFiles = walk(frameworkSource).map((file) => ({
-  source: file,
-  relative: posix(path.relative(root, file)),
-  destination: projectPath(posix(path.relative(root, file))),
-}));
-const npmExcludedUnityFile = ".claude/skills/setup-vivox-voice-chat/evals/.gitignore";
-if (!frameworkFiles.some((item) => item.relative === npmExcludedUnityFile)) {
-  const fallback = path.join(root, "package-assets", "setup-vivox-voice-chat-evals.gitignore");
-  if (fs.existsSync(fallback)) {
-    frameworkFiles.push({
-      source: fallback,
-      relative: npmExcludedUnityFile,
-      destination: projectPath(npmExcludedUnityFile)
-    });
-    frameworkFiles.sort((a, b) => a.relative.localeCompare(b.relative));
-  }
-}
-
-const installStatePath = projectPath(".claude/nccgs/install-state.json");
-const overrideManifestPath = projectPath(".nccgs/framework-overrides.json");
-// Check shared/scaffold/configurator destinations before any framework mutation,
-// even when a pre-existing file would otherwise be preserved or skipped.
-for (const relative of ["CLAUDE.md", ".claude/settings.json", ".nccgs/project.yaml", ".nccgs/execution.json", ".nccgs/backups", ".nccgs/agent-activation.json"]) projectPath(relative);
-const previousInstallState = readJsonIfPresent(installStatePath, "NCCGS install state");
-const previousActivation = readJsonIfPresent(projectPath(".nccgs/agent-activation.json"), "NCCGS agent activation state");
-const executionFile = projectPath(".nccgs/execution.json");
-const previousExecution = readJsonIfPresent(executionFile, "NCCGS execution policy");
-const existingProjectPolicy = fs.existsSync(projectPath(".nccgs/project.yaml"));
-const existingInstallation = Boolean(previousInstallState || existingProjectPolicy);
-const autonomyFile = projectPath(".nccgs/autonomy.json");
-let previousAutonomy;
-try { previousAutonomy = autonomyPolicy(project); }
-catch (error) { console.error(error.message); process.exit(2); }
-const autonomyMode = requestedAutonomy || (existingInstallation ? previousAutonomy.mode : "full");
-try { if (previousExecution) executionPolicy(previousExecution); }
-catch (error) { console.error(`Invalid execution policy: ${error.message}`); process.exit(2); }
-const previousOverrideManifest = readJsonIfPresent(overrideManifestPath, "NCCGS framework override manifest");
-if (updateOnly && !previousInstallState) {
-  console.error("NCCGS is not installed in this project. Run `npx nccgs@latest install` first.");
-  process.exit(2);
-}
-if (previousOverrideManifest && previousOverrideManifest.schemaVersion !== 1) {
-  console.error(`Unsupported framework override schema: ${previousOverrideManifest.schemaVersion ?? "unknown"}`);
-  process.exit(2);
-}
-for (const item of previousInstallState?.files ?? []) {
-  if (!isManagedRelative(item.relative)) {
-    console.error(`Unsafe managed path in install state: ${item.relative ?? "missing"}`);
-    process.exit(2);
-  }
-  projectPath(item.relative);
-}
-for (const item of previousOverrideManifest?.overrides ?? []) {
-  if (!isManagedRelative(item.path)) {
-    console.error(`Unsafe path in framework override manifest: ${item.path ?? "missing"}`);
-    process.exit(2);
-  }
-  projectPath(item.path);
-}
-
-const previousFiles = new Map((previousInstallState?.files ?? []).map((item) => [item.relative, item]));
-const previousOverrides = new Map((previousOverrideManifest?.overrides ?? []).map((item) => [item.path, item]));
-const currentFrameworkNames = new Set(frameworkFiles.map((item) => item.relative));
-const currentVersion = fs.readFileSync(path.join(root, "VERSION"), "utf8").trim();
-
-const filePlans = frameworkFiles.map((item) => planFrameworkFile(item));
-const stalePlans = (previousInstallState?.files ?? [])
-  .filter((item) => !currentFrameworkNames.has(item.relative))
-  .map((item) => planStaleFile(item))
-  .filter(Boolean);
-
-const activeOverridePaths = new Set([
-  ...filePlans.filter((item) => item.override).map((item) => item.relative),
-  ...stalePlans.filter((item) => item.override).map((item) => item.relative)
-]);
-const carriedOverrides = [];
-for (const item of previousOverrides.values()) {
-  if (activeOverridePaths.has(item.path) || currentFrameworkNames.has(item.path) || previousFiles.has(item.path)) continue;
-  const destination = projectPath(item.path);
-  const absent = item.disposition === "absent";
-  const stillMatches = absent ? !fs.existsSync(destination) : matchesFingerprint(destination, item);
-  carriedOverrides.push({
-    ...item,
-    status: item.status === "approved" && stillMatches ? "approved" : "pending_review",
-    reason: stillMatches ? item.reason : "Previously approved override changed and requires migration review."
-  });
-}
-
-const overrideRecords = [
-  ...filePlans.filter((item) => item.override).map((item) => item.override),
-  ...stalePlans.filter((item) => item.override).map((item) => item.override),
-  ...carriedOverrides
-].sort((a, b) => a.path.localeCompare(b.path));
-const pendingOverrides = overrideRecords.filter((item) => item.status !== "approved");
-
-const newFiles = filePlans.filter((item) => item.action === "install");
-const currentFiles = filePlans.filter((item) => item.action === "current");
-const automaticReplacements = filePlans.filter((item) => item.action === "replace");
-const forcedReplacements = filePlans.filter((item) => item.action === "force-replace");
-const preservedFiles = filePlans.filter((item) => item.action.startsWith("preserve"));
-const automaticStale = stalePlans.filter((item) => item.action === "remove");
-const forcedStale = stalePlans.filter((item) => item.action === "force-remove");
-const preservedStale = stalePlans.filter((item) => item.action === "preserve-stale");
-
-const scaffoldFiles = walk(path.join(root, "scaffold")).map((file) => ({
-  source: file,
-  relative: posix(path.relative(path.join(root, "scaffold"), file)),
-  destination: projectPath(posix(path.relative(path.join(root, "scaffold"), file))),
-}));
-const npmExcludedScaffoldFile = ".nccgs/.gitignore";
-if (!scaffoldFiles.some((item) => posix(item.relative) === npmExcludedScaffoldFile)) {
-  const fallback = path.join(root, "package-assets", "nccgs-project.gitignore");
-  if (fs.existsSync(fallback)) {
-    scaffoldFiles.push({
-      source: fallback,
-      relative: npmExcludedScaffoldFile,
-      destination: projectPath(npmExcludedScaffoldFile)
-    });
-    scaffoldFiles.sort((a, b) => a.relative.localeCompare(b.relative));
-  }
-}
-// An update must not introduce standalone policy into an existing legacy project.
-const newScaffold = scaffoldFiles.filter((item) => !fs.existsSync(item.destination)
-  && item.relative !== ".nccgs/autonomy.json"
-  && !(existingInstallation && item.relative === ".nccgs/execution.json"));
-const settingsPlan = planManagedSettings(project);
-const targetPolicyPath = projectPath(".nccgs/project.yaml");
-const targetPolicy = fs.existsSync(targetPolicyPath) ? fs.readFileSync(targetPolicyPath, "utf8") : "";
-const policyModelProfile = targetPolicy.match(/^models:\s*$[\s\S]*?^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
-const studio = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/studio.json"), "utf8"));
-for (const agent of studio.agents) projectPath(`.claude/agents/${agent.name}.md`);
-const modelProfile = requestedModelProfile || policyModelProfile || previousInstallState?.modelProfile || (existingInstallation ? "astra-claude" : studio.defaultProfile);
-if (!Object.hasOwn(studio.modelProfiles, modelProfile)) {
-  console.error(`Unknown model profile: ${modelProfile}`);
-  process.exit(2);
-}
-
-console.log(`NCCGS installation target: ${project}`);
-console.log(`Framework version: ${previousInstallState?.frameworkVersion ?? "not installed"} -> ${currentVersion}`);
-console.log(`Framework files: ${frameworkFiles.length} (${newFiles.length} new, ${currentFiles.length} current, ${automaticReplacements.length} automatic update, ${preservedFiles.length} preserved override, ${forcedReplacements.length} forced override)`);
-console.log(`Stale framework files: ${automaticStale.length} automatic removal, ${preservedStale.length} preserved override, ${forcedStale.length} forced removal`);
-console.log(`Project scaffold files to initialize: ${newScaffold.length}`);
-console.log(`Managed Claude settings: ${settingsPlan.changed ? "update" : "already current"}`);
-console.log(`Task autonomy: ${autonomyMode}; activate native permissions with nccgs run. OS and managed restrictions still apply.`);
-console.log(`Agent model profile: ${modelProfile}`);
-console.log(`Execution policy: ${previousExecution?.name ?? (existingInstallation ? "compatibility (missing execution.json preserved)" : "standalone")}; external review: ${previousExecution?.externalReview?.mode ?? (existingInstallation ? "required" : "off")}`);
-if (pendingOverrides.length) {
-  console.log(`${pendingOverrides.length} project override(s) will be preserved for /migrate-project review:`);
-  for (const item of pendingOverrides.slice(0, 30)) console.log(`- ${item.path} (${item.disposition})`);
-}
-if (dryRun) {
-  console.log("Dry run complete; no files changed.");
-  process.exit(0);
-}
-
-const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-const backupRoot = projectPath(`.nccgs/backups/${stamp}`);
-const replacedFiles = [...automaticReplacements, ...forcedReplacements];
-const removedFiles = [...automaticStale, ...forcedStale];
-for (const item of replacedFiles) backupFile(item.destination, path.join(backupRoot, ...item.relative.split("/")));
-for (const item of removedFiles) {
-  backupFile(item.destination, path.join(backupRoot, ...item.relative.split("/")));
-  fs.unlinkSync(recheckTarget(item.destination));
-}
-if (previousOverrideManifest && JSON.stringify(previousOverrideManifest.overrides ?? []) !== JSON.stringify(overrideRecords)) {
-  backupFile(overrideManifestPath, path.join(backupRoot, ".nccgs", "framework-overrides.json"));
-}
-
-for (const item of filePlans.filter((entry) => new Set(["install", "replace", "force-replace"]).has(entry.action))) {
-  recheckTarget(item.destination);
-  fs.mkdirSync(path.dirname(item.destination), { recursive: true });
-  fs.copyFileSync(item.source, recheckTarget(item.destination));
-}
-for (const item of newScaffold) {
-  recheckTarget(item.destination);
-  fs.mkdirSync(path.dirname(item.destination), { recursive: true });
-  fs.copyFileSync(item.source, recheckTarget(item.destination));
-}
-
-installManagedSettings(settingsPlan, backupRoot);
-const autonomyText = `${JSON.stringify({ schemaVersion: 1, mode: autonomyMode }, null, 2)}\n`;
-if (!fs.existsSync(autonomyFile) || fs.readFileSync(autonomyFile, "utf8") !== autonomyText) {
-  if (fs.existsSync(autonomyFile)) backupFile(autonomyFile, path.join(backupRoot, ".nccgs/autonomy.json"));
-  fs.mkdirSync(path.dirname(autonomyFile), { recursive: true });
-  fs.writeFileSync(recheckTarget(autonomyFile), autonomyText);
-}
-installClaudeImport(project, backupRoot);
-
-const skipAgentPaths = preservedFiles
-  .filter((item) => item.relative.startsWith(".claude/agents/"))
-  .flatMap((item) => ["--skip-path", item.relative]);
-const modelConfiguration = spawnSync(process.execPath, [
-  path.join(root, ".claude", "nccgs", "tools", "configure-models.mjs"),
-  "--project", project,
-  "--profile", modelProfile,
-  ...skipAgentPaths
-], { cwd: project, encoding: "utf8" });
-if (modelConfiguration.status !== 0) {
-  process.stderr.write(modelConfiguration.stdout ?? "");
-  process.stderr.write(modelConfiguration.stderr ?? "");
-  console.error("NCCGS was copied, but agent model configuration failed.");
-  process.exit(1);
-}
-
-writeOverrideManifest(overrideManifestPath, overrideRecords, previousOverrideManifest, currentVersion);
-writeInstallState(project, modelProfile, frameworkFiles, installStatePath, previousInstallState, new Set(overrideRecords.map((item) => item.path)));
-
-const doctor = spawnSync(process.execPath, [
-  path.join(scriptDir, "doctor.mjs"),
-  "--project", project,
-  "--allow-migration-required"
-], { cwd: project, encoding: "utf8" });
-process.stdout.write(doctor.stdout ?? "");
-process.stderr.write(doctor.stderr ?? "");
-if (doctor.status !== 0) {
-  console.error("NCCGS files were installed, but post-install verification failed.");
-  process.exit(1);
-}
-
-console.log("NCCGS installation complete.");
-if (fs.existsSync(backupRoot)) {
-  console.log(`Replaced shared files were backed up under: ${backupRoot}`);
-}
-const installedPolicy = fs.readFileSync(targetPolicyPath, "utf8");
-const installedPolicySchema = Number(installedPolicy.match(/^schema_version:\s*(\d+)\s*$/m)?.[1] ?? 0);
-if (installedPolicySchema !== 2 || pendingOverrides.length || /^profile_contracts:/m.test(installedPolicy)) {
-  console.log("Project migration required: open a new Claude Code session and run `/migrate-project` once.");
-} else if (!previousInstallState) {
-  console.log("First NCCGS adoption: run `/migrate-project` once for an existing project; a new project can start with `/status`.");
-} else {
-  console.log("No project migration required for this NCCGS update.");
-}
-
-function planFrameworkFile(item) {
-  const previous = previousFiles.get(item.relative);
-  const existingOverride = previousOverrides.get(item.relative);
-  const upstream = fingerprintFile(item.source);
-  if (!fs.existsSync(item.destination)) {
-    if (!force && (previous || existingOverride?.disposition === "absent")) {
-      return { ...item, action: "preserve-absent", override: buildOverride(item, existingOverride, upstream, "absent") };
-    }
-    return { ...item, action: "install", override: null };
-  }
-  if (equivalentFiles(item.source, item.destination)) return { ...item, action: "current", override: null };
-  if (!force && previous && matchesFingerprint(item.destination, previous)) return { ...item, action: "replace", override: null };
-  // Older profiles could generate optional agents outside install-state.files.
-  // When a later package starts managing one, its recorded generated bytes are
-  // a valid baseline. Real local edits and explicit overrides still need review.
-  const generated = previousActivation?.schemaVersion === 1 && item.relative.startsWith(".claude/agents/")
-    ? { sha256: previousActivation.generated?.[item.relative], canonicalSha256: previousActivation.generatedCanonical?.[item.relative] }
-    : null;
-  if (!force && previousInstallState && !previous && !existingOverride && matchesFingerprint(item.destination, generated)) {
-    return { ...item, action: "replace", override: null };
-  }
-  if (force) return { ...item, action: "force-replace", override: null };
-  return { ...item, action: "preserve", override: buildOverride(item, existingOverride, upstream, "preserve") };
-}
-
-function planStaleFile(previous) {
-  const destination = projectPath(previous.relative);
-  if (!fs.existsSync(destination)) return null;
-  if (force) return { ...previous, relative: previous.relative, destination, action: "force-remove", override: null };
-  if (matchesFingerprint(destination, previous)) return { ...previous, relative: previous.relative, destination, action: "remove", override: null };
-  const existingOverride = previousOverrides.get(previous.relative);
-  const current = fingerprintFile(destination);
-  const stillApproved = existingOverride?.status === "approved" && matchesFingerprint(destination, existingOverride)
-    && existingOverride.upstreamSha256 === null;
-  return {
-    ...previous,
-    relative: previous.relative,
-    destination,
-    action: "preserve-stale",
-    override: {
-      path: previous.relative,
-      disposition: "preserve",
-      status: stillApproved ? "approved" : "pending_review",
-      ...current,
-      upstreamSha256: null,
-      upstreamCanonicalSha256: null,
-      retiredFromFramework: true,
-      reason: "Locally modified file was preserved after its framework path retired; review ownership during migration."
-    }
-  };
-}
-
-function buildOverride(item, existing, upstream, disposition) {
-  const current = disposition === "absent" ? { sha256: null, canonicalSha256: null } : fingerprintFile(item.destination);
-  const currentMatches = disposition === "absent"
-    ? existing?.disposition === "absent" && !fs.existsSync(item.destination)
-    : existing?.disposition === "preserve" && sameFingerprint(current, existing);
-  const previousUpstream = existing ? {
-    sha256: existing.upstreamSha256,
-    canonicalSha256: existing.upstreamCanonicalSha256
-  } : null;
-  const upstreamMatches = previousUpstream && sameFingerprint(upstream, previousUpstream);
-  const approved = existing?.status === "approved" && currentMatches && upstreamMatches;
-  return {
-    path: item.relative,
-    disposition,
-    status: approved ? "approved" : "pending_review",
-    ...current,
-    upstreamSha256: upstream.sha256,
-    upstreamCanonicalSha256: upstream.canonicalSha256 ?? null,
-    reason: approved
-      ? existing.reason
-      : "Project-specific framework change was preserved automatically; review and rebase it with /migrate-project."
-  };
-}
-
-function walk(directory) {
-  if (!fs.existsSync(directory)) return [];
-  const output = [];
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    const full = path.join(directory, entry.name);
-    if (entry.isDirectory()) output.push(...walk(full));
-    else if (entry.isFile()) output.push(full);
-  }
-  return output.sort((a, b) => a.localeCompare(b));
-}
-
-function posix(value) {
-  return value.split(path.sep).join("/");
-}
-
-function isManagedRelative(value) {
-  try { return assertRelativePath(value).startsWith(".claude/"); }
-  catch { return false; }
-}
-
-function projectPath(relative) {
-  try { return containedPath(project, relative); }
-  catch (error) {
-    console.error(`Unsafe NCCGS target: ${error.message}`);
-    process.exit(2);
-  }
-}
-
-function recheckTarget(file) {
-  return projectPath(posix(path.relative(project, file)));
-}
-
-function readJsonIfPresent(file, label) {
-  if (!fs.existsSync(file)) return null;
-  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
-  catch (error) {
-    console.error(`Invalid ${label} at ${file}: ${error.message}`);
-    process.exit(2);
-  }
-}
-
-function backupFile(source, destination) {
-  recheckTarget(source);
-  recheckTarget(destination);
-  fs.mkdirSync(path.dirname(destination), { recursive: true });
-  fs.copyFileSync(recheckTarget(source), recheckTarget(destination));
-}
-
-function planManagedSettings(projectRoot) {
-  const settingsPath = projectPath(".claude/settings.json");
-  let current = {};
-  if (fs.existsSync(settingsPath)) {
-    try { current = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
-    catch (error) {
-      console.error(`Cannot merge invalid JSON settings at ${settingsPath}: ${error.message}`);
-      process.exit(2);
-    }
-  }
-  const fragment = JSON.parse(fs.readFileSync(path.join(root, ".claude", "nccgs", "settings.fragment.json"), "utf8"));
-  const managedCommands = new Set(Object.values(fragment.hooks ?? {}).flatMap(groups => groups.flatMap(group => group.hooks ?? [])).map(hook => canonicalHookCommand(hook.command)));
-  const merged = structuredClone(current);
-  merged.permissions ??= {};
-  for (const key of ["allow", "deny", "ask"]) {
-    const existing = Array.isArray(merged.permissions[key]) ? merged.permissions[key] : [];
-    const additions = Array.isArray(fragment.permissions?.[key]) ? fragment.permissions[key] : [];
-    if (existing.length || additions.length) merged.permissions[key] = [...new Set([...existing, ...additions])];
-  }
-  merged.hooks ??= {};
-  for (const [event, groups] of Object.entries(fragment.hooks ?? {})) {
-    const existing = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
-    // A user's command may share a group with a managed command. Remove only
-    // the managed hook, preserving the group metadata and every custom hook.
-    const retained = existing.flatMap((group) => {
-      if (!Array.isArray(group.hooks)) return [group];
-      const hooks = group.hooks.filter((hook) => !managedCommands.has(canonicalHookCommand(hook.command)));
-      return hooks.length ? [{ ...group, hooks }] : [];
-    });
-    merged.hooks[event] = [...retained, ...groups];
-  }
-  const nextText = `${JSON.stringify(merged, null, 2)}\n`;
-  const currentText = fs.existsSync(settingsPath) ? fs.readFileSync(settingsPath, "utf8") : "";
-  return { settingsPath, existed: fs.existsSync(settingsPath), nextText, changed: currentText !== nextText };
-}
-
-function installManagedSettings(plan, backupDirectory) {
-  if (!plan.changed) return;
-  if (plan.existed) backupFile(plan.settingsPath, path.join(backupDirectory, ".claude", "settings.json"));
-  recheckTarget(plan.settingsPath);
-  fs.mkdirSync(path.dirname(plan.settingsPath), { recursive: true });
-  fs.writeFileSync(recheckTarget(plan.settingsPath), plan.nextText, "utf8");
-}
-
-function writeOverrideManifest(file, overrides, previous, frameworkVersion) {
-  if (!overrides.length && !previous) return;
-  const now = new Date().toISOString();
-  const manifest = {
-    schemaVersion: 1,
-    frameworkVersion,
-    createdAt: previous?.createdAt ?? now,
-    updatedAt: now,
-    overrides
-  };
-  recheckTarget(file);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(recheckTarget(file), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-}
-
-function writeInstallState(projectRoot, profile, files, statePath, previousState, overridePaths) {
-  const now = new Date().toISOString();
-  const state = {
-    schemaVersion: 3,
-    frameworkVersion: currentVersion,
-    previousFrameworkVersion: previousState?.frameworkVersion ?? null,
-    modelProfile: profile,
-    installedAt: previousState?.installedAt ?? now,
-    updatedAt: now,
-    files: files.map((item) => ({
-      relative: item.relative,
-      ...(overridePaths.has(item.relative) ? fingerprintFile(item.source) : fingerprintFile(projectPath(item.relative)))
-    }))
-  };
-  recheckTarget(statePath);
-  fs.mkdirSync(path.dirname(statePath), { recursive: true });
-  fs.writeFileSync(recheckTarget(statePath), `${JSON.stringify(state, null, 2)}\n`, "utf8");
-}
-
-function installClaudeImport(projectRoot, backupDirectory) {
-  const claudePath = projectPath("CLAUDE.md");
-  const begin = "<!-- NCCGS:BEGIN -->";
-  const block = `${begin}\n@.claude/nccgs/constitution.md\n<!-- NCCGS:END -->`;
-  if (!fs.existsSync(claudePath)) {
-    fs.copyFileSync(path.join(root, "CLAUDE.md"), recheckTarget(claudePath));
-    return;
-  }
-  const current = fs.readFileSync(claudePath, "utf8");
-  if (current.includes(begin) || current.includes("@.claude/nccgs/constitution.md")) return;
-  backupFile(claudePath, path.join(backupDirectory, "CLAUDE.md"));
-  const separator = current.endsWith("\n") ? "\n" : "\n\n";
-  fs.writeFileSync(recheckTarget(claudePath), `${current}${separator}${block}\n`, "utf8");
-}
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  equivalentFiles,
+  fingerprintFile,
+  matchesFingerprint,
+  sameFingerprint
+} from "../.claude/nccgs/tools/integrity.mjs";
+import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
+import { executionPolicy } from "../.claude/nccgs/tools/policy.mjs";
+import { autonomyPolicy } from "../.claude/nccgs/tools/autonomy.mjs";
+import { managedHookKey } from "../.claude/nccgs/tools/hook-transport.mjs";
+import { acquireInstallationLease, assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const args = process.argv.slice(2);
+const projectIndex = args.indexOf("--project");
+const dryRun = args.includes("--dry-run");
+const force = args.includes("--force");
+const updateOnly = args.includes("--update-only");
+const allowNonUnity = args.includes("--allow-non-unity");
+const modelProfileIndex = args.indexOf("--model-profile");
+const requestedModelProfile = modelProfileIndex >= 0 ? args[modelProfileIndex + 1] : null;
+const autonomyIndex = args.indexOf("--autonomy");
+const requestedAutonomy = autonomyIndex >= 0 ? args[autonomyIndex + 1] : null;
+if (autonomyIndex >= 0 && !["full", "guarded"].includes(requestedAutonomy)) {
+  console.error("--autonomy requires full or guarded"); process.exit(2);
+}
+
+if (projectIndex >= 0 && !args[projectIndex + 1]) {
+  console.error("--project requires a directory path.");
+  process.exit(2);
+}
+
+const project = projectIndex >= 0 ? path.resolve(args[projectIndex + 1]) : process.cwd();
+try { assertProjectRoot(project); }
+catch (error) {
+  console.error(`Unsafe installation target: ${error.message}`);
+  process.exit(2);
+}
+if (project === root) {
+  console.error("The NCCGS package directory cannot be its own installation target.");
+  process.exit(2);
+}
+try { assertInstallationAvailable(project); }
+catch (error) { console.error(error.message); process.exit(2); }
+
+const unityMarkers = ["Assets", "Packages", "ProjectSettings"];
+const missingMarkers = unityMarkers.filter((item) => !fs.existsSync(projectPath(item)));
+if (missingMarkers.length && !allowNonUnity) {
+  console.error(`Target does not look like a Unity project; missing: ${missingMarkers.join(", ")}`);
+  console.error("Use --allow-non-unity only when intentionally scaffolding before Unity project creation.");
+  process.exit(2);
+}
+
+const validation = spawnSync(process.execPath, [path.join(scriptDir, "validate.mjs")], {
+  cwd: root,
+  encoding: "utf8",
+});
+if (validation.status !== 0) {
+  process.stderr.write(validation.stdout ?? "");
+  process.stderr.write(validation.stderr ?? "");
+  console.error("NCCGS package validation failed; installation aborted.");
+  process.exit(1);
+}
+
+// Register before reading the installation to keep a concurrent uninstall from
+// invalidating the plan. The second guard closes the acquisition race. Dry-run
+// remains read-only; the exit handler covers all existing early exit paths.
+if (!dryRun) {
+  try {
+    const lease = acquireInstallationLease(project, "nccgs-install");
+    process.once("exit", () => lease.release());
+    assertInstallationAvailable(project);
+  } catch (error) { console.error(error.message); process.exit(2); }
+}
+
+const frameworkSource = path.join(root, ".claude");
+const frameworkFiles = walk(frameworkSource).map((file) => ({
+  source: file,
+  relative: posix(path.relative(root, file)),
+  destination: projectPath(posix(path.relative(root, file))),
+}));
+const npmExcludedUnityFile = ".claude/skills/setup-vivox-voice-chat/evals/.gitignore";
+if (!frameworkFiles.some((item) => item.relative === npmExcludedUnityFile)) {
+  const fallback = path.join(root, "package-assets", "setup-vivox-voice-chat-evals.gitignore");
+  if (fs.existsSync(fallback)) {
+    frameworkFiles.push({
+      source: fallback,
+      relative: npmExcludedUnityFile,
+      destination: projectPath(npmExcludedUnityFile)
+    });
+    frameworkFiles.sort((a, b) => a.relative.localeCompare(b.relative));
+  }
+}
+
+const installStatePath = projectPath(".claude/nccgs/install-state.json");
+const overrideManifestPath = projectPath(".nccgs/framework-overrides.json");
+// Check shared/scaffold/configurator destinations before any framework mutation,
+// even when a pre-existing file would otherwise be preserved or skipped.
+for (const relative of ["CLAUDE.md", ".claude/settings.json", ".nccgs/project.yaml", ".nccgs/execution.json", ".nccgs/backups", ".nccgs/agent-activation.json"]) projectPath(relative);
+const previousInstallState = readJsonIfPresent(installStatePath, "NCCGS install state");
+const previousActivation = readJsonIfPresent(projectPath(".nccgs/agent-activation.json"), "NCCGS agent activation state");
+const executionFile = projectPath(".nccgs/execution.json");
+const previousExecution = readJsonIfPresent(executionFile, "NCCGS execution policy");
+const existingProjectPolicy = fs.existsSync(projectPath(".nccgs/project.yaml"));
+const existingInstallation = Boolean(previousInstallState || existingProjectPolicy);
+const autonomyFile = projectPath(".nccgs/autonomy.json");
+let previousAutonomy;
+try { previousAutonomy = autonomyPolicy(project); }
+catch (error) { console.error(error.message); process.exit(2); }
+const autonomyMode = requestedAutonomy || (existingInstallation ? previousAutonomy.mode : "full");
+try { if (previousExecution) executionPolicy(previousExecution); }
+catch (error) { console.error(`Invalid execution policy: ${error.message}`); process.exit(2); }
+const previousOverrideManifest = readJsonIfPresent(overrideManifestPath, "NCCGS framework override manifest");
+if (updateOnly && !previousInstallState) {
+  console.error("NCCGS is not installed in this project. Run `npx nccgs@latest install` first.");
+  process.exit(2);
+}
+if (previousOverrideManifest && previousOverrideManifest.schemaVersion !== 1) {
+  console.error(`Unsupported framework override schema: ${previousOverrideManifest.schemaVersion ?? "unknown"}`);
+  process.exit(2);
+}
+for (const item of previousInstallState?.files ?? []) {
+  if (!isManagedRelative(item.relative)) {
+    console.error(`Unsafe managed path in install state: ${item.relative ?? "missing"}`);
+    process.exit(2);
+  }
+  projectPath(item.relative);
+}
+for (const item of previousOverrideManifest?.overrides ?? []) {
+  if (!isManagedRelative(item.path)) {
+    console.error(`Unsafe path in framework override manifest: ${item.path ?? "missing"}`);
+    process.exit(2);
+  }
+  projectPath(item.path);
+}
+
+const previousFiles = new Map((previousInstallState?.files ?? []).map((item) => [item.relative, item]));
+const previousOverrides = new Map((previousOverrideManifest?.overrides ?? []).map((item) => [item.path, item]));
+const currentFrameworkNames = new Set(frameworkFiles.map((item) => item.relative));
+const currentVersion = fs.readFileSync(path.join(root, "VERSION"), "utf8").trim();
+
+const filePlans = frameworkFiles.map((item) => planFrameworkFile(item));
+const stalePlans = (previousInstallState?.files ?? [])
+  .filter((item) => !currentFrameworkNames.has(item.relative))
+  .map((item) => planStaleFile(item))
+  .filter(Boolean);
+
+const activeOverridePaths = new Set([
+  ...filePlans.filter((item) => item.override).map((item) => item.relative),
+  ...stalePlans.filter((item) => item.override).map((item) => item.relative)
+]);
+const carriedOverrides = [];
+for (const item of previousOverrides.values()) {
+  if (activeOverridePaths.has(item.path) || currentFrameworkNames.has(item.path) || previousFiles.has(item.path)) continue;
+  const destination = projectPath(item.path);
+  const absent = item.disposition === "absent";
+  const stillMatches = absent ? !fs.existsSync(destination) : matchesFingerprint(destination, item);
+  carriedOverrides.push({
+    ...item,
+    status: item.status === "approved" && stillMatches ? "approved" : "pending_review",
+    reason: stillMatches ? item.reason : "Previously approved override changed and requires migration review."
+  });
+}
+
+const overrideRecords = [
+  ...filePlans.filter((item) => item.override).map((item) => item.override),
+  ...stalePlans.filter((item) => item.override).map((item) => item.override),
+  ...carriedOverrides
+].sort((a, b) => a.path.localeCompare(b.path));
+const pendingOverrides = overrideRecords.filter((item) => item.status !== "approved");
+
+const newFiles = filePlans.filter((item) => item.action === "install");
+const currentFiles = filePlans.filter((item) => item.action === "current");
+const automaticReplacements = filePlans.filter((item) => item.action === "replace");
+const forcedReplacements = filePlans.filter((item) => item.action === "force-replace");
+const preservedFiles = filePlans.filter((item) => item.action.startsWith("preserve"));
+const automaticStale = stalePlans.filter((item) => item.action === "remove");
+const forcedStale = stalePlans.filter((item) => item.action === "force-remove");
+const preservedStale = stalePlans.filter((item) => item.action === "preserve-stale");
+
+const scaffoldFiles = walk(path.join(root, "scaffold")).map((file) => ({
+  source: file,
+  relative: posix(path.relative(path.join(root, "scaffold"), file)),
+  destination: projectPath(posix(path.relative(path.join(root, "scaffold"), file))),
+}));
+const npmExcludedScaffoldFile = ".nccgs/.gitignore";
+if (!scaffoldFiles.some((item) => posix(item.relative) === npmExcludedScaffoldFile)) {
+  const fallback = path.join(root, "package-assets", "nccgs-project.gitignore");
+  if (fs.existsSync(fallback)) {
+    scaffoldFiles.push({
+      source: fallback,
+      relative: npmExcludedScaffoldFile,
+      destination: projectPath(npmExcludedScaffoldFile)
+    });
+    scaffoldFiles.sort((a, b) => a.relative.localeCompare(b.relative));
+  }
+}
+// An update must not introduce standalone policy into an existing legacy project.
+const newScaffold = scaffoldFiles.filter((item) => !fs.existsSync(item.destination)
+  && item.relative !== ".nccgs/autonomy.json"
+  && !(existingInstallation && item.relative === ".nccgs/execution.json"));
+const settingsPlan = planManagedSettings(project);
+const targetPolicyPath = projectPath(".nccgs/project.yaml");
+const targetPolicy = fs.existsSync(targetPolicyPath) ? fs.readFileSync(targetPolicyPath, "utf8") : "";
+const policyModelProfile = targetPolicy.match(/^models:\s*$[\s\S]*?^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+const studio = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/studio.json"), "utf8"));
+for (const agent of studio.agents) projectPath(`.claude/agents/${agent.name}.md`);
+const modelProfile = requestedModelProfile || policyModelProfile || previousInstallState?.modelProfile || (existingInstallation ? "astra-claude" : studio.defaultProfile);
+if (!Object.hasOwn(studio.modelProfiles, modelProfile)) {
+  console.error(`Unknown model profile: ${modelProfile}`);
+  process.exit(2);
+}
+
+console.log(`NCCGS installation target: ${project}`);
+console.log(`Framework version: ${previousInstallState?.frameworkVersion ?? "not installed"} -> ${currentVersion}`);
+console.log(`Framework files: ${frameworkFiles.length} (${newFiles.length} new, ${currentFiles.length} current, ${automaticReplacements.length} automatic update, ${preservedFiles.length} preserved override, ${forcedReplacements.length} forced override)`);
+console.log(`Stale framework files: ${automaticStale.length} automatic removal, ${preservedStale.length} preserved override, ${forcedStale.length} forced removal`);
+console.log(`Project scaffold files to initialize: ${newScaffold.length}`);
+console.log(`Managed Claude settings: ${settingsPlan.changed ? "update" : "already current"}`);
+console.log(`Task autonomy: ${autonomyMode}; activate native permissions with nccgs run. OS and managed restrictions still apply.`);
+console.log(`Agent model profile: ${modelProfile}`);
+console.log(`Execution policy: ${previousExecution?.name ?? (existingInstallation ? "compatibility (missing execution.json preserved)" : "standalone")}; external review: ${previousExecution?.externalReview?.mode ?? (existingInstallation ? "required" : "off")}`);
+if (pendingOverrides.length) {
+  console.log(`${pendingOverrides.length} project override(s) will be preserved for /migrate-project review:`);
+  for (const item of pendingOverrides.slice(0, 30)) console.log(`- ${item.path} (${item.disposition})`);
+}
+if (dryRun) {
+  console.log("Dry run complete; no files changed.");
+  process.exit(0);
+}
+
+const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+const backupRoot = projectPath(`.nccgs/backups/${stamp}`);
+const replacedFiles = [...automaticReplacements, ...forcedReplacements];
+const removedFiles = [...automaticStale, ...forcedStale];
+for (const item of replacedFiles) backupFile(item.destination, path.join(backupRoot, ...item.relative.split("/")));
+for (const item of removedFiles) {
+  backupFile(item.destination, path.join(backupRoot, ...item.relative.split("/")));
+  fs.unlinkSync(recheckTarget(item.destination));
+}
+if (previousOverrideManifest && JSON.stringify(previousOverrideManifest.overrides ?? []) !== JSON.stringify(overrideRecords)) {
+  backupFile(overrideManifestPath, path.join(backupRoot, ".nccgs", "framework-overrides.json"));
+}
+
+for (const item of filePlans.filter((entry) => new Set(["install", "replace", "force-replace"]).has(entry.action))) {
+  recheckTarget(item.destination);
+  fs.mkdirSync(path.dirname(item.destination), { recursive: true });
+  fs.copyFileSync(item.source, recheckTarget(item.destination));
+}
+for (const item of newScaffold) {
+  recheckTarget(item.destination);
+  fs.mkdirSync(path.dirname(item.destination), { recursive: true });
+  fs.copyFileSync(item.source, recheckTarget(item.destination));
+}
+
+installManagedSettings(settingsPlan, backupRoot);
+const autonomyText = `${JSON.stringify({ schemaVersion: 1, mode: autonomyMode }, null, 2)}\n`;
+if (!fs.existsSync(autonomyFile) || fs.readFileSync(autonomyFile, "utf8") !== autonomyText) {
+  if (fs.existsSync(autonomyFile)) backupFile(autonomyFile, path.join(backupRoot, ".nccgs/autonomy.json"));
+  fs.mkdirSync(path.dirname(autonomyFile), { recursive: true });
+  fs.writeFileSync(recheckTarget(autonomyFile), autonomyText);
+}
+installClaudeImport(project, backupRoot);
+
+const skipAgentPaths = preservedFiles
+  .filter((item) => item.relative.startsWith(".claude/agents/"))
+  .flatMap((item) => ["--skip-path", item.relative]);
+const modelConfiguration = spawnSync(process.execPath, [
+  path.join(root, ".claude", "nccgs", "tools", "configure-models.mjs"),
+  "--project", project,
+  "--profile", modelProfile,
+  ...skipAgentPaths
+], { cwd: project, encoding: "utf8" });
+if (modelConfiguration.status !== 0) {
+  process.stderr.write(modelConfiguration.stdout ?? "");
+  process.stderr.write(modelConfiguration.stderr ?? "");
+  console.error("NCCGS was copied, but agent model configuration failed.");
+  process.exit(1);
+}
+
+writeOverrideManifest(overrideManifestPath, overrideRecords, previousOverrideManifest, currentVersion);
+writeInstallState(project, modelProfile, frameworkFiles, installStatePath, previousInstallState, new Set(overrideRecords.map((item) => item.path)));
+
+const doctor = spawnSync(process.execPath, [
+  path.join(scriptDir, "doctor.mjs"),
+  "--project", project,
+  "--allow-migration-required"
+], { cwd: project, encoding: "utf8" });
+process.stdout.write(doctor.stdout ?? "");
+process.stderr.write(doctor.stderr ?? "");
+if (doctor.status !== 0) {
+  console.error("NCCGS files were installed, but post-install verification failed.");
+  process.exit(1);
+}
+
+console.log("NCCGS installation complete.");
+if (fs.existsSync(backupRoot)) {
+  console.log(`Replaced shared files were backed up under: ${backupRoot}`);
+}
+const installedPolicy = fs.readFileSync(targetPolicyPath, "utf8");
+const installedPolicySchema = Number(installedPolicy.match(/^schema_version:\s*(\d+)\s*$/m)?.[1] ?? 0);
+if (installedPolicySchema !== 2 || pendingOverrides.length || /^profile_contracts:/m.test(installedPolicy)) {
+  console.log("Project migration required: open a new Claude Code session and run `/migrate-project` once.");
+} else if (!previousInstallState) {
+  console.log("First NCCGS adoption: run `/migrate-project` once for an existing project; a new project can start with `/status`.");
+} else {
+  console.log("No project migration required for this NCCGS update.");
+}
+
+function planFrameworkFile(item) {
+  const previous = previousFiles.get(item.relative);
+  const existingOverride = previousOverrides.get(item.relative);
+  const upstream = fingerprintFile(item.source);
+  if (!fs.existsSync(item.destination)) {
+    if (!force && (previous || existingOverride?.disposition === "absent")) {
+      return { ...item, action: "preserve-absent", override: buildOverride(item, existingOverride, upstream, "absent") };
+    }
+    return { ...item, action: "install", override: null };
+  }
+  if (equivalentFiles(item.source, item.destination)) return { ...item, action: "current", override: null };
+  if (!force && previous && matchesFingerprint(item.destination, previous)) return { ...item, action: "replace", override: null };
+  // Older profiles could generate optional agents outside install-state.files.
+  // When a later package starts managing one, its recorded generated bytes are
+  // a valid baseline. Real local edits and explicit overrides still need review.
+  const generated = previousActivation?.schemaVersion === 1 && item.relative.startsWith(".claude/agents/")
+    ? { sha256: previousActivation.generated?.[item.relative], canonicalSha256: previousActivation.generatedCanonical?.[item.relative] }
+    : null;
+  if (!force && previousInstallState && !previous && !existingOverride && matchesFingerprint(item.destination, generated)) {
+    return { ...item, action: "replace", override: null };
+  }
+  if (force) return { ...item, action: "force-replace", override: null };
+  return { ...item, action: "preserve", override: buildOverride(item, existingOverride, upstream, "preserve") };
+}
+
+function planStaleFile(previous) {
+  const destination = projectPath(previous.relative);
+  if (!fs.existsSync(destination)) return null;
+  if (force) return { ...previous, relative: previous.relative, destination, action: "force-remove", override: null };
+  if (matchesFingerprint(destination, previous)) return { ...previous, relative: previous.relative, destination, action: "remove", override: null };
+  const existingOverride = previousOverrides.get(previous.relative);
+  const current = fingerprintFile(destination);
+  const stillApproved = existingOverride?.status === "approved" && matchesFingerprint(destination, existingOverride)
+    && existingOverride.upstreamSha256 === null;
+  return {
+    ...previous,
+    relative: previous.relative,
+    destination,
+    action: "preserve-stale",
+    override: {
+      path: previous.relative,
+      disposition: "preserve",
+      status: stillApproved ? "approved" : "pending_review",
+      ...current,
+      upstreamSha256: null,
+      upstreamCanonicalSha256: null,
+      retiredFromFramework: true,
+      reason: "Locally modified file was preserved after its framework path retired; review ownership during migration."
+    }
+  };
+}
+
+function buildOverride(item, existing, upstream, disposition) {
+  const current = disposition === "absent" ? { sha256: null, canonicalSha256: null } : fingerprintFile(item.destination);
+  const currentMatches = disposition === "absent"
+    ? existing?.disposition === "absent" && !fs.existsSync(item.destination)
+    : existing?.disposition === "preserve" && sameFingerprint(current, existing);
+  const previousUpstream = existing ? {
+    sha256: existing.upstreamSha256,
+    canonicalSha256: existing.upstreamCanonicalSha256
+  } : null;
+  const upstreamMatches = previousUpstream && sameFingerprint(upstream, previousUpstream);
+  const approved = existing?.status === "approved" && currentMatches && upstreamMatches;
+  return {
+    path: item.relative,
+    disposition,
+    status: approved ? "approved" : "pending_review",
+    ...current,
+    upstreamSha256: upstream.sha256,
+    upstreamCanonicalSha256: upstream.canonicalSha256 ?? null,
+    reason: approved
+      ? existing.reason
+      : "Project-specific framework change was preserved automatically; review and rebase it with /migrate-project."
+  };
+}
+
+function walk(directory) {
+  if (!fs.existsSync(directory)) return [];
+  const output = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) output.push(...walk(full));
+    else if (entry.isFile()) output.push(full);
+  }
+  return output.sort((a, b) => a.localeCompare(b));
+}
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function isManagedRelative(value) {
+  try { return assertRelativePath(value).startsWith(".claude/"); }
+  catch { return false; }
+}
+
+function projectPath(relative) {
+  try { return containedPath(project, relative); }
+  catch (error) {
+    console.error(`Unsafe NCCGS target: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+function recheckTarget(file) {
+  return projectPath(posix(path.relative(project, file)));
+}
+
+function readJsonIfPresent(file, label) {
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) {
+    console.error(`Invalid ${label} at ${file}: ${error.message}`);
+    process.exit(2);
+  }
+}
+
+function backupFile(source, destination) {
+  recheckTarget(source);
+  recheckTarget(destination);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(recheckTarget(source), recheckTarget(destination));
+}
+
+function planManagedSettings(projectRoot) {
+  const settingsPath = projectPath(".claude/settings.json");
+  let current = {};
+  if (fs.existsSync(settingsPath)) {
+    try { current = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+    catch (error) {
+      console.error(`Cannot merge invalid JSON settings at ${settingsPath}: ${error.message}`);
+      process.exit(2);
+    }
+  }
+  const fragment = JSON.parse(fs.readFileSync(path.join(root, ".claude", "nccgs", "settings.fragment.json"), "utf8"));
+  const managedCommands = new Set(Object.values(fragment.hooks ?? {}).flatMap(groups => groups.flatMap(group => group.hooks ?? [])).map(managedHookKey).filter(Boolean));
+  const merged = structuredClone(current);
+  merged.permissions ??= {};
+  for (const key of ["allow", "deny", "ask"]) {
+    const existing = Array.isArray(merged.permissions[key]) ? merged.permissions[key] : [];
+    const additions = Array.isArray(fragment.permissions?.[key]) ? fragment.permissions[key] : [];
+    if (existing.length || additions.length) merged.permissions[key] = [...new Set([...existing, ...additions])];
+  }
+  merged.hooks ??= {};
+  for (const [event, groups] of Object.entries(fragment.hooks ?? {})) {
+    const existing = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    // A user's command may share a group with a managed command. Remove only
+    // the managed hook, preserving the group metadata and every custom hook.
+    const retained = existing.flatMap((group) => {
+      if (!Array.isArray(group.hooks)) return [group];
+      const hooks = group.hooks.filter((hook) => !managedCommands.has(managedHookKey(hook)));
+      return hooks.length ? [{ ...group, hooks }] : [];
+    });
+    merged.hooks[event] = [...retained, ...groups];
+  }
+  const nextText = `${JSON.stringify(merged, null, 2)}\n`;
+  const currentText = fs.existsSync(settingsPath) ? fs.readFileSync(settingsPath, "utf8") : "";
+  return { settingsPath, existed: fs.existsSync(settingsPath), nextText, changed: currentText !== nextText };
+}
+
+function installManagedSettings(plan, backupDirectory) {
+  if (!plan.changed) return;
+  if (plan.existed) backupFile(plan.settingsPath, path.join(backupDirectory, ".claude", "settings.json"));
+  recheckTarget(plan.settingsPath);
+  fs.mkdirSync(path.dirname(plan.settingsPath), { recursive: true });
+  fs.writeFileSync(recheckTarget(plan.settingsPath), plan.nextText, "utf8");
+}
+
+function writeOverrideManifest(file, overrides, previous, frameworkVersion) {
+  if (!overrides.length && !previous) return;
+  const now = new Date().toISOString();
+  const manifest = {
+    schemaVersion: 1,
+    frameworkVersion,
+    createdAt: previous?.createdAt ?? now,
+    updatedAt: now,
+    overrides
+  };
+  recheckTarget(file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(recheckTarget(file), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+function writeInstallState(projectRoot, profile, files, statePath, previousState, overridePaths) {
+  const now = new Date().toISOString();
+  const state = {
+    schemaVersion: 3,
+    frameworkVersion: currentVersion,
+    previousFrameworkVersion: previousState?.frameworkVersion ?? null,
+    modelProfile: profile,
+    installedAt: previousState?.installedAt ?? now,
+    updatedAt: now,
+    files: files.map((item) => ({
+      relative: item.relative,
+      ...(overridePaths.has(item.relative) ? fingerprintFile(item.source) : fingerprintFile(projectPath(item.relative)))
+    }))
+  };
+  recheckTarget(statePath);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(recheckTarget(statePath), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function installClaudeImport(projectRoot, backupDirectory) {
+  const claudePath = projectPath("CLAUDE.md");
+  const begin = "<!-- NCCGS:BEGIN -->";
+  const block = `${begin}\n@.claude/nccgs/constitution.md\n<!-- NCCGS:END -->`;
+  if (!fs.existsSync(claudePath)) {
+    fs.copyFileSync(path.join(root, "CLAUDE.md"), recheckTarget(claudePath));
+    return;
+  }
+  const current = fs.readFileSync(claudePath, "utf8");
+  if (current.includes(begin) || current.includes("@.claude/nccgs/constitution.md")) return;
+  backupFile(claudePath, path.join(backupDirectory, "CLAUDE.md"));
+  const separator = current.endsWith("\n") ? "\n" : "\n\n";
+  fs.writeFileSync(recheckTarget(claudePath), `${current}${separator}${block}\n`, "utf8");
+}