nccgs 1.0.0 → 1.1.1

package/scripts/doctor.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { matchesFingerprint, sameFingerprint } from "../.claude/nccgs/tools/integrity.mjs";
+
+const args = process.argv.slice(2);
+const projectIndex = args.indexOf("--project");
+const allowMigrationRequired = args.includes("--allow-migration-required") || args.includes("--allow-policy-migration");
+const warnings = [];
+const errors = [];
+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();
+for (const marker of ["Assets", "Packages", "ProjectSettings"]) {
+  if (!fs.existsSync(path.join(project, marker))) errors.push(`Missing Unity marker: ${marker}`);
+}
+
+const statePath = path.join(project, ".claude", "nccgs", "install-state.json");
+const overridePath = path.join(project, ".nccgs", "framework-overrides.json");
+const state = readJson(statePath, "NCCGS install state", true);
+const overrideManifest = readJson(overridePath, "NCCGS framework override manifest", false);
+if (state && ![1, 2, 3].includes(state.schemaVersion)) errors.push(`Unsupported install-state schema: ${state.schemaVersion ?? "unknown"}.`);
+if (overrideManifest && overrideManifest.schemaVersion !== 1) errors.push(`Unsupported framework override schema: ${overrideManifest.schemaVersion ?? "unknown"}.`);
+
+const overrides = new Map();
+for (const item of overrideManifest?.overrides ?? []) {
+  if (!isManagedRelative(item.path) || !new Set(["preserve", "absent"]).has(item.disposition)
+      || !new Set(["approved", "pending_review"]).has(item.status)) {
+    errors.push(`Invalid framework override record: ${item.path ?? "path missing"}`);
+    continue;
+  }
+  if (overrides.has(item.path)) errors.push(`Duplicate framework override: ${item.path}`);
+  overrides.set(item.path, item);
+}
+
+let verifiedManaged = 0;
+if (state) {
+  for (const item of state.files ?? []) {
+    if (!isManagedRelative(item.relative)) {
+      errors.push(`Unsafe managed path in install state: ${item.relative ?? "missing"}`);
+      continue;
+    }
+    const file = path.join(project, ...item.relative.split("/"));
+    const override = overrides.get(item.relative);
+    if (override) {
+      const recordedUpstream = {
+        sha256: override.upstreamSha256,
+        canonicalSha256: override.upstreamCanonicalSha256
+      };
+      if (!sameFingerprint(item, recordedUpstream)) errors.push(`Framework override has stale upstream hashes: ${item.relative}`);
+      validateOverride(override, file);
+      verifiedManaged++;
+      continue;
+    }
+    if (!fs.existsSync(file)) errors.push(`Managed file is missing: ${item.relative}`);
+    else if (!matchesFingerprint(file, item)) errors.push(`Managed file was modified: ${item.relative}`);
+    else verifiedManaged++;
+  }
+}
+for (const item of overrides.values()) {
+  if ((state?.files ?? []).some((managed) => managed.relative === item.path)) continue;
+  validateOverride(item, path.join(project, ...item.path.split("/")));
+}
+
+const claudePath = path.join(project, "CLAUDE.md");
+if (!fs.existsSync(claudePath) || !fs.readFileSync(claudePath, "utf8").includes("@.claude/nccgs/constitution.md")) {
+  errors.push("CLAUDE.md does not import the NCCGS constitution.");
+}
+
+const policyPath = path.join(project, ".nccgs", "project.yaml");
+let policySchema = null;
+if (!fs.existsSync(policyPath)) errors.push(".nccgs/project.yaml is missing.");
+else {
+  const match = fs.readFileSync(policyPath, "utf8").match(/^schema_version:\s*(\d+)\s*$/m);
+  policySchema = match ? Number(match[1]) : null;
+  if (policySchema !== 2) migrationIssue(`Project policy schema must be 2; found ${policySchema ?? "unknown"}.`);
+}
+
+if (errors.length) {
+  for (const error of errors) console.error(`ERROR: ${error}`);
+  for (const warning of warnings) console.warn(`WARN: ${warning}`);
+  console.error(`NCCGS doctor failed with ${errors.length} error(s).`);
+  process.exit(1);
+}
+
+for (const warning of warnings) console.warn(`WARN: ${warning}`);
+console.log("NCCGS doctor passed.");
+console.log(`Framework version: ${state.frameworkVersion}`);
+console.log(`Model profile: ${state.modelProfile}`);
+console.log(`Managed files verified: ${verifiedManaged}`);
+console.log(`Framework overrides: ${overrides.size} (${[...overrides.values()].filter((item) => item.status !== "approved").length} pending review)`);
+console.log(`Project policy schema: ${policySchema ?? "migration required"}`);
+
+function validateOverride(item, file) {
+  if (item.status !== "approved") migrationIssue(`Framework override awaits /migrate-project review: ${item.path}`);
+  if (item.disposition === "absent") {
+    if (fs.existsSync(file)) errors.push(`Override expects a missing file, but it exists: ${item.path}`);
+    return;
+  }
+  if (!fs.existsSync(file)) errors.push(`Preserved framework override is missing: ${item.path}`);
+  else if (!matchesFingerprint(file, item)) errors.push(`Preserved framework override changed after it was recorded: ${item.path}`);
+}
+
+function migrationIssue(message) {
+  if (allowMigrationRequired) warnings.push(message);
+  else errors.push(message);
+}
+
+function readJson(file, label, required) {
+  if (!fs.existsSync(file)) {
+    if (required) errors.push(`${label} is missing.`);
+    return null;
+  }
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) {
+    errors.push(`${label} is invalid JSON: ${error.message}`);
+    return null;
+  }
+}
+
+function isManagedRelative(value) {
+  if (typeof value !== "string" || !value.startsWith(".claude/")) return false;
+  const parts = value.split("/");
+  return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
+}

package/scripts/install.mjs

@@ -1,8 +1,13 @@
 import { spawnSync } from "node:child_process";
-import crypto from "node:crypto";
 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";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(scriptDir, "..");
@@ -10,6 +15,7 @@ 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;
@@ -51,57 +57,108 @@ if (validation.status !== 0) {
 const frameworkSource = path.join(root, ".claude");
 const frameworkFiles = walk(frameworkSource).map((file) => ({
   source: file,
-  relative: path.relative(root, file),
+  relative: posix(path.relative(root, file)),
   destination: path.join(project, path.relative(root, file)),
 }));
 const npmExcludedUnityFile = ".claude/skills/setup-vivox-voice-chat/evals/.gitignore";
-if (!frameworkFiles.some((item) => posix(item.relative) === npmExcludedUnityFile)) {
+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.split("/").join(path.sep),
+      relative: npmExcludedUnityFile,
       destination: path.join(project, ...npmExcludedUnityFile.split("/"))
     });
     frameworkFiles.sort((a, b) => a.relative.localeCompare(b.relative));
   }
 }
+
 const installStatePath = path.join(project, ".claude", "nccgs", "install-state.json");
-let previousInstallState = null;
-if (fs.existsSync(installStatePath)) {
-  try { previousInstallState = JSON.parse(fs.readFileSync(installStatePath, "utf8")); }
-  catch (error) {
-    console.error(`Invalid NCCGS install state at ${installStatePath}: ${error.message}`);
+const overrideManifestPath = path.join(project, ".nccgs", "framework-overrides.json");
+const previousInstallState = readJsonIfPresent(installStatePath, "NCCGS install state");
+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);
+  }
+}
+for (const item of previousOverrideManifest?.overrides ?? []) {
+  if (!isManagedRelative(item.path)) {
+    console.error(`Unsafe path in framework override manifest: ${item.path ?? "missing"}`);
     process.exit(2);
   }
 }
-const currentFrameworkNames = new Set(frameworkFiles.map((item) => posix(item.relative)));
-const staleFrameworkFiles = (previousInstallState?.files ?? [])
-  .filter((item) => !currentFrameworkNames.has(item.relative))
-  .map((item) => ({ ...item, destination: path.join(project, ...item.relative.split("/")) }))
-  .filter((item) => fs.existsSync(item.destination));
 
-const conflicts = frameworkFiles.filter((item) => {
-  if (!fs.existsSync(item.destination)) return false;
-  return !sameFile(item.source, item.destination);
-});
+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();
 
-if ((conflicts.length || staleFrameworkFiles.length) && !force) {
-  console.error(`Installation found ${conflicts.length} conflicting and ${staleFrameworkFiles.length} stale framework file(s):`);
-  for (const item of conflicts.slice(0, 30)) console.error(`- ${posix(item.relative)}`);
-  for (const item of staleFrameworkFiles.slice(0, 30)) console.error(`- stale: ${item.relative}`);
-  if (conflicts.length > 30) console.error(`- ... ${conflicts.length - 30} more`);
-  console.error("Re-run with --force to back up and replace these framework files.");
-  process.exit(2);
+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 = path.join(project, ...item.path.split("/"));
+  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 newFiles = frameworkFiles.filter((item) => !fs.existsSync(item.destination));
-const identicalFiles = frameworkFiles.length - newFiles.length - conflicts.length;
+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: path.relative(path.join(root, "scaffold"), file),
   destination: path.join(project, 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.split("/").join(path.sep),
+      destination: path.join(project, ...npmExcludedScaffoldFile.split("/"))
+    });
+    scaffoldFiles.sort((a, b) => a.relative.localeCompare(b.relative));
+  }
+}
 const newScaffold = scaffoldFiles.filter((item) => !fs.existsSync(item.destination));
 const settingsPlan = planManagedSettings(project);
 const targetPolicyPath = path.join(project, ".nccgs", "project.yaml");
@@ -114,11 +171,16 @@ if (!new Set(["quality", "balanced", "inherit"]).has(modelProfile)) {
 }
 
 console.log(`NCCGS installation target: ${project}`);
-console.log(`Framework files: ${frameworkFiles.length} (${newFiles.length} new, ${identicalFiles} identical, ${conflicts.length} replace)`);
-console.log(`Stale framework files to back up and remove: ${staleFrameworkFiles.length}`);
+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(`Agent model profile: ${modelProfile}`);
+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);
@@ -126,23 +188,21 @@ if (dryRun) {
 
 const stamp = new Date().toISOString().replace(/[:.]/g, "-");
 const backupRoot = path.join(project, ".nccgs", "backups", stamp);
-for (const item of conflicts) {
-  const backup = path.join(backupRoot, item.relative);
-  fs.mkdirSync(path.dirname(backup), { recursive: true });
-  fs.copyFileSync(item.destination, backup);
-}
-for (const item of staleFrameworkFiles) {
-  const backup = path.join(backupRoot, ...item.relative.split("/"));
-  fs.mkdirSync(path.dirname(backup), { recursive: true });
-  fs.copyFileSync(item.destination, backup);
+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(item.destination);
 }
+if (previousOverrideManifest && JSON.stringify(previousOverrideManifest.overrides ?? []) !== JSON.stringify(overrideRecords)) {
+  backupFile(overrideManifestPath, path.join(backupRoot, ".nccgs", "framework-overrides.json"));
+}
 
-for (const item of frameworkFiles) {
+for (const item of filePlans.filter((entry) => new Set(["install", "replace", "force-replace"]).has(entry.action))) {
   fs.mkdirSync(path.dirname(item.destination), { recursive: true });
   fs.copyFileSync(item.source, item.destination);
 }
-
 for (const item of newScaffold) {
   fs.mkdirSync(path.dirname(item.destination), { recursive: true });
   fs.copyFileSync(item.source, item.destination);
@@ -151,10 +211,14 @@ for (const item of newScaffold) {
 installManagedSettings(settingsPlan, backupRoot);
 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(project, ".claude", "nccgs", "tools", "configure-models.mjs"),
+  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 ?? "");
@@ -163,13 +227,104 @@ if (modelConfiguration.status !== 0) {
   process.exit(1);
 }
 
-writeInstallState(project, modelProfile, frameworkFiles, installStatePath);
+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 (conflicts.length) console.log(`Replaced files backed up under: ${backupRoot}`);
-console.log("Next: open Claude Code and run /migrate-project review for an existing project, or /status for a configured project.");
+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) {
+  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 };
+  if (force) return { ...item, action: "force-replace", override: null };
+  return { ...item, action: "preserve", override: buildOverride(item, existingOverride, upstream, "preserve") };
+}
+
+function planStaleFile(previous) {
+  const destination = path.join(project, ...previous.relative.split("/"));
+  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);
@@ -179,27 +334,36 @@ function walk(directory) {
   return output.sort((a, b) => a.localeCompare(b));
 }
 
-function sameFile(left, right) {
-  const a = fs.readFileSync(left);
-  const b = fs.readFileSync(right);
-  return a.length === b.length && a.equals(b);
+function posix(value) {
+  return value.split(path.sep).join("/");
 }
 
-function hashFile(file) {
-  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+function isManagedRelative(value) {
+  if (typeof value !== "string" || !value.startsWith(".claude/")) return false;
+  const parts = value.split("/");
+  return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }
 
-function posix(value) {
-  return value.split(path.sep).join("/");
+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) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
 }
 
 function planManagedSettings(projectRoot) {
   const settingsPath = path.join(projectRoot, ".claude", "settings.json");
   let current = {};
   if (fs.existsSync(settingsPath)) {
-    try {
-      current = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-    } catch (error) {
+    try { current = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+    catch (error) {
       console.error(`Cannot merge invalid JSON settings at ${settingsPath}: ${error.message}`);
       process.exit(2);
     }
@@ -225,23 +389,37 @@ function planManagedSettings(projectRoot) {
 
 function installManagedSettings(plan, backupDirectory) {
   if (!plan.changed) return;
-  if (plan.existed) {
-    const backup = path.join(backupDirectory, ".claude", "settings.json");
-    fs.mkdirSync(path.dirname(backup), { recursive: true });
-    fs.copyFileSync(plan.settingsPath, backup);
-  }
+  if (plan.existed) backupFile(plan.settingsPath, path.join(backupDirectory, ".claude", "settings.json"));
   fs.mkdirSync(path.dirname(plan.settingsPath), { recursive: true });
   fs.writeFileSync(plan.settingsPath, plan.nextText, "utf8");
 }
 
-function writeInstallState(projectRoot, profile, files, statePath) {
-  const state = {
+function writeOverrideManifest(file, overrides, previous, frameworkVersion) {
+  if (!overrides.length && !previous) return;
+  const now = new Date().toISOString();
+  const manifest = {
     schemaVersion: 1,
-    frameworkVersion: fs.readFileSync(path.join(root, "VERSION"), "utf8").trim(),
+    frameworkVersion,
+    createdAt: previous?.createdAt ?? now,
+    updatedAt: now,
+    overrides
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(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: posix(item.relative),
-      sha256: hashFile(path.join(projectRoot, item.relative))
+      relative: item.relative,
+      ...(overridePaths.has(item.relative) ? fingerprintFile(item.source) : fingerprintFile(path.join(projectRoot, ...item.relative.split("/"))))
     }))
   };
   fs.mkdirSync(path.dirname(statePath), { recursive: true });
@@ -256,12 +434,9 @@ function installClaudeImport(projectRoot, backupDirectory) {
     fs.copyFileSync(path.join(root, "CLAUDE.md"), claudePath);
     return;
   }
-
   const current = fs.readFileSync(claudePath, "utf8");
   if (current.includes(begin) || current.includes("@.claude/nccgs/constitution.md")) return;
-
-  fs.mkdirSync(backupDirectory, { recursive: true });
-  fs.copyFileSync(claudePath, path.join(backupDirectory, "CLAUDE.md"));
+  backupFile(claudePath, path.join(backupDirectory, "CLAUDE.md"));
   const separator = current.endsWith("\n") ? "\n" : "\n\n";
   fs.writeFileSync(claudePath, `${current}${separator}${block}\n`, "utf8");
 }

package/scripts/validate.mjs

@@ -51,10 +51,18 @@ for (const relative of [
   "scaffold/.nccgs/project.yaml", "scaffold/.nccgs/state.md",
   "scaffold/.nccgs/requirements.yaml", "scaffold/.nccgs/templates/context-packet.yaml",
   "scaffold/.nccgs/templates/closure-record.md", "package-assets/setup-vivox-voice-chat-evals.gitignore",
-  "scripts/cli.mjs", "scripts/install.mjs",
-  "scripts/sync-unity-skills.mjs", "tests/framework.test.mjs"
+  "package-assets/nccgs-project.gitignore",
+  "scripts/cli.mjs", "scripts/doctor.mjs", "scripts/install.mjs",
+  "scripts/sync-unity-skills.mjs", "tests/framework.test.mjs",
+  ".claude/nccgs/tools/integrity.mjs", ".claude/nccgs/tools/approve-overrides.mjs"
 ]) requireFile(relative);
 
+const scaffoldIgnore = path.join(root, "scaffold/.nccgs/.gitignore");
+const scaffoldIgnoreFallback = path.join(root, "package-assets/nccgs-project.gitignore");
+if (fs.existsSync(scaffoldIgnore) && fs.readFileSync(scaffoldIgnore, "utf8") !== fs.readFileSync(scaffoldIgnoreFallback, "utf8")) {
+  errors.push("Scaffold .nccgs/.gitignore differs from its npm fallback asset.");
+}
+
 const versions = [
   fs.readFileSync(path.join(root, "VERSION"), "utf8").trim(),
   JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version,
@@ -128,7 +136,14 @@ for (const command of hookCommands) {
   const check = spawnSync(process.execPath, ["--check", file], { encoding: "utf8" });
   if (check.status !== 0) errors.push(`Hook syntax failure ${match[1]}: ${check.stderr.trim()}`);
 }
-for (const file of [path.join(root, ".claude/nccgs/tools/configure-models.mjs"), path.join(root, "scripts/cli.mjs"), path.join(root, "scripts/install.mjs")]) {
+for (const file of [
+  path.join(root, ".claude/nccgs/tools/configure-models.mjs"),
+  path.join(root, ".claude/nccgs/tools/integrity.mjs"),
+  path.join(root, ".claude/nccgs/tools/approve-overrides.mjs"),
+  path.join(root, "scripts/cli.mjs"),
+  path.join(root, "scripts/doctor.mjs"),
+  path.join(root, "scripts/install.mjs")
+]) {
   const check = spawnSync(process.execPath, ["--check", file], { encoding: "utf8" });
   if (check.status !== 0) errors.push(`Script syntax failure ${posix(path.relative(root, file))}: ${check.stderr.trim()}`);
 }