nccgs 1.1.0 → 1.1.1

package/.claude/nccgs/VERSION

@@ -1 +1 @@
-1.1.0
+1.1.1

package/.claude/nccgs/tools/approve-overrides.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { fingerprintFile } from "./integrity.mjs";
+
+const ownDir = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const projectArg = args.indexOf("--project");
+const project = path.resolve(projectArg >= 0 ? args[projectArg + 1] : path.resolve(ownDir, "../../../.."));
+const approvePending = args.includes("--approve-pending");
+const manifestPath = path.join(project, ".nccgs", "framework-overrides.json");
+
+if (projectArg >= 0 && !args[projectArg + 1]) {
+  console.error("--project requires a directory path.");
+  process.exit(2);
+}
+if (!fs.existsSync(manifestPath)) {
+  console.log("No NCCGS framework overrides are recorded.");
+  process.exit(0);
+}
+
+let manifest;
+try { manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")); }
+catch (error) {
+  console.error(`Invalid framework override manifest: ${error.message}`);
+  process.exit(2);
+}
+if (manifest.schemaVersion !== 1) {
+  console.error(`Unsupported framework override schema: ${manifest.schemaVersion ?? "unknown"}`);
+  process.exit(2);
+}
+for (const item of manifest.overrides ?? []) {
+  if (!isManagedRelative(item.path) || !new Set(["preserve", "absent"]).has(item.disposition)
+      || !new Set(["approved", "pending_review"]).has(item.status)) {
+    console.error(`Invalid framework override record: ${item.path ?? "path missing"}`);
+    process.exit(2);
+  }
+}
+
+const pending = (manifest.overrides ?? []).filter((item) => item.status !== "approved");
+if (!approvePending) {
+  if (!pending.length) console.log("All NCCGS framework overrides are approved.");
+  else {
+    console.log(`${pending.length} NCCGS framework override(s) await migration review:`);
+    for (const item of pending) console.log(`- ${item.path} (${item.disposition})`);
+    console.log("After reviewing/rebasing every item, run again with --approve-pending.");
+  }
+  process.exit(pending.length ? 1 : 0);
+}
+
+for (const item of pending) {
+  const file = path.join(project, ...item.path.split("/"));
+  if (item.disposition === "absent") {
+    if (fs.existsSync(file)) {
+      console.error(`Cannot approve absent override because the file exists: ${item.path}`);
+      process.exit(2);
+    }
+    item.sha256 = null;
+    item.canonicalSha256 = null;
+  } else {
+    if (!fs.existsSync(file)) {
+      console.error(`Cannot approve preserved override because the file is missing: ${item.path}`);
+      process.exit(2);
+    }
+    Object.assign(item, fingerprintFile(file));
+  }
+  item.status = "approved";
+  item.reviewedAt = new Date().toISOString();
+}
+
+manifest.updatedAt = new Date().toISOString();
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+console.log(`Approved ${pending.length} NCCGS framework override(s) after migration review.`);
+
+function isManagedRelative(value) {
+  if (typeof value !== "string" || !value.startsWith(".claude/")) return false;
+  const parts = value.split("/");
+  return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
+}

package/.claude/nccgs/tools/configure-models.mjs

@@ -6,6 +6,10 @@ const ownDir = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
 const projectArg = args.indexOf("--project");
 const profileArg = args.indexOf("--profile");
+const skippedPaths = new Set();
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === "--skip-path" && args[index + 1]) skippedPaths.add(args[index + 1].replace(/\\/g, "/"));
+}
 const project = path.resolve(projectArg >= 0 ? args[projectArg + 1] : path.resolve(ownDir, "../../../.."));
 const catalogPath = path.join(project, ".claude", "nccgs", "studio.json");
 const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
@@ -19,6 +23,7 @@ if (!profile) throw new Error(`Unknown model profile '${profileName}'. Expected:
 let changed = 0;
 for (const agent of catalog.agents) {
   const file = path.join(project, ".claude", "agents", `${agent.name}.md`);
+  if (skippedPaths.has(`.claude/agents/${agent.name}.md`)) continue;
   if (!fs.existsSync(file)) continue;
   let text = fs.readFileSync(file, "utf8");
   const model = profile[agent.modelClass];

package/.claude/nccgs/tools/integrity.mjs

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+export function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function textContent(value) {
+  const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  if (buffer.includes(0)) return null;
+  try { return utf8.decode(buffer); }
+  catch { return null; }
+}
+
+export function normalizeLf(value) {
+  const text = textContent(value);
+  if (text === null) return null;
+  return `${text.replace(/\r\n?/g, "\n").replace(/\n*$/, "")}\n`;
+}
+
+export function fingerprintBuffer(value) {
+  const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  const normalized = normalizeLf(buffer);
+  return {
+    sha256: sha256(buffer),
+    ...(normalized === null ? {} : { canonicalSha256: sha256(Buffer.from(normalized, "utf8")) })
+  };
+}
+
+export function fingerprintFile(file) {
+  return fingerprintBuffer(fs.readFileSync(file));
+}
+
+export function equivalentBuffers(left, right) {
+  const a = fingerprintBuffer(left);
+  const b = fingerprintBuffer(right);
+  if (a.sha256 === b.sha256) return true;
+  return Boolean(a.canonicalSha256 && a.canonicalSha256 === b.canonicalSha256);
+}
+
+export function equivalentFiles(left, right) {
+  return equivalentBuffers(fs.readFileSync(left), fs.readFileSync(right));
+}
+
+export function matchesFingerprint(file, expected) {
+  if (!expected || !fs.existsSync(file)) return false;
+  const buffer = fs.readFileSync(file);
+  const actual = fingerprintBuffer(buffer);
+  if (expected.sha256 && actual.sha256 === expected.sha256) return true;
+  if (expected.canonicalSha256 && actual.canonicalSha256 === expected.canonicalSha256) return true;
+
+  // NCCGS 1.1.0 stored only a raw hash. Accept the two normal Git text
+  // representations so a checkout's LF policy does not manufacture drift.
+  if (expected.sha256 && actual.canonicalSha256) {
+    const lf = normalizeLf(buffer);
+    if (sha256(Buffer.from(lf, "utf8")) === expected.sha256) return true;
+    const crlf = lf.replace(/\n/g, "\r\n");
+    if (sha256(Buffer.from(crlf, "utf8")) === expected.sha256) return true;
+  }
+  return false;
+}
+
+export function sameFingerprint(left, right) {
+  if (!left || !right) return false;
+  if (left.sha256 && right.sha256 && left.sha256 === right.sha256) return true;
+  return Boolean(left.canonicalSha256 && right.canonicalSha256 && left.canonicalSha256 === right.canonicalSha256);
+}

package/.claude/nccgs/workflow-catalog.json

@@ -130,7 +130,7 @@
       "defaultClassification": "STANDARD"
     },
     {
-      "name": "code-review",
+      "name": "nccgs-code-review",
       "type": "module",
       "primaryRoles": [
         "nccgs-programming-lead"

package/.claude/skills/migrate-project/SKILL.md

@@ -8,6 +8,8 @@ allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion
 
 Treat brownfield adoption and migrations explicitly requested by the installer as CONTROLLED work. Read the complete [migration procedure](references/procedure.md). Default to `full` when no mode is given. Do not require migration merely because NCCGS was updated when the installer reported `No project migration required`.
 
+When `.nccgs/framework-overrides.json` exists, treat every `pending_review` entry as preserved project truth, not installer debris. Compare the project version with the current NCCGS version, keep or rebase the customization deliberately, and record the decision in the migration plan. Only after every pending item has been reviewed and the final bytes or intentional absence are correct, run `node .claude/nccgs/tools/approve-overrides.mjs --project . --approve-pending`. Never approve first to make `doctor` green.
+
 ## Modes
 
 - `full` (default): run review, plan, apply, and verify in one invocation. Continue across phase boundaries without asking for ceremonial approval. Pause only for an unresolved Product Owner decision, destructive action, external side effect, or authority outside the current request.
@@ -16,7 +18,7 @@ Treat brownfield adoption and migrations explicitly requested by the installer a
 - `apply`: execute an approved plan in validated batches with backups.
 - `verify`: prove policy, routing, hooks, Unity integration, evidence, closure, and a representative work path.
 
-Migration decisions must cover canonical sources, ownership/protected paths, architecture, Unity tooling, model profile/fallback, enabled departments, context packets, verification baselines, closure safeguards, Git tracking, local settings, obsolete global skills, and rollback.
+Migration decisions must cover canonical sources, ownership/protected paths, architecture, Unity tooling, model profile/fallback, enabled departments, context packets, verification baselines, closure safeguards, Git tracking, local settings, preserved framework overrides, obsolete global skills, and rollback.
 
 In `full` mode, write the plan before applying it, preserve the same evidence and rollback guarantees as the individual modes, and stop safely if review finds a decision that would materially change project truth. A reversible plan created within the same invocation is approved for in-scope application unless project policy explicitly requires a separate approval.
 

package/.claude/skills/migrate-project/references/procedure.md

@@ -28,6 +28,10 @@ requires no project migration, report that fact and do not manufacture migration
    strongest active safeguard until the PO explicitly accepts a weaker model.
 7. Determine the project model profile, enabled departments, permitted fallback,
    orchestration depth/parallelism, context-packet locations, and hook compatibility.
+8. If `.nccgs/framework-overrides.json` exists, inspect every override. Diff its
+   preserved bytes or intentional absence against the installed upstream version,
+   and distinguish a still-needed project policy from a customization now supplied
+   by NCCGS. Line-ending-only differences are not overrides.
 
 ## Plan
 
@@ -42,6 +46,7 @@ Create `.nccgs/migrations/<date>-migration-plan.md` with:
 - ordered reversible batches and dependencies;
 - exact broad/irreversible decisions requiring PO authority;
 - backup/rollback method;
+- an explicit KEEP/REBASE/RETIRE decision for every pending framework override;
 - validation for each batch and final end-to-end proof.
 
 Prioritize authority and policy conflicts, then model/routing conflicts, Unity
@@ -64,6 +69,12 @@ traceability/evidence, lifecycle hooks, workflow replacement, and cleanup.
 - Do not leave two active agents/skills advertising mutually exclusive Unity
   execution bridges. Disable obsolete global routing signals outside the repository
   through an explicit user action.
+- Preserve pending framework overrides while reviewing them. Rebase each retained
+  override onto the newly installed upstream content when needed. After all entries
+  match the migration decisions, run
+  `node .claude/nccgs/tools/approve-overrides.mjs --project . --approve-pending`.
+  Approval records the final hashes; it is the last apply step, never a substitute
+  for the review.
 
 ## Verify
 
@@ -72,4 +83,5 @@ role/workflow catalogs, bounded delegation, hook health, context packet freshnes
 canonical map, requirements/state, Unity Skills integrity, CLI/Pipeline operation,
 relevant tests, runtime evidence, and subjective-gate routing. Verify that required
 linked artifacts block DONE in `linked` or `strict` mode. Use a small representative
-task or dry run when product changes are not authorized.
+task or dry run when product changes are not authorized. Run `npx nccgs@latest doctor`
+and require zero pending framework overrides before declaring migration complete.

package/.claude/skills/{code-review → nccgs-code-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: code-review
+name: nccgs-code-review
 description: Performs a read-only code review against requirements, architecture, Unity constraints, ownership, tests, performance, security, and regression risk.
 allowed-tools: Read, Glob, Grep, Bash, Task
 ---
@@ -11,4 +11,3 @@ Read `.nccgs/project.yaml`, `.nccgs/state.md`, and the active context packet whe
 Read the context packet, final diff, governing decisions, affected callers, and tests. Route distinct Unity, networking, security, performance, or UI lenses when needed. Report only actionable findings with severity, exact evidence, impact, and remediation direction. Verify that tests assert requirements and that serialized/lifecycle behavior is addressed. Do not edit or praise generally; state when no material issue is found.
 
 Return outcome, evidence, affected records, blockers or decisions, residual risk, and the exact next workflow. Do not claim DONE unless this is the `closure` skill and every configured gate passes.
-

package/README.md

@@ -5,7 +5,7 @@ specialization of a full game-development team with project-aware governance,
 bounded orchestration, configurable model routing, official Unity Skills, objective
 evidence, and strict closure.
 
-Version 1.1 contains:
+Version 1.1.1 contains:
 
 - 45 studio agents across leadership, design, programming, Unity, content, quality,
   and release;
@@ -56,9 +56,12 @@ npx nccgs@latest doctor
 The current directory is the installation target. `--project <directory>` remains
 available for automation, but is not needed for ordinary use.
 
-Updates are hash-aware. Files that still match the previous install state are backed
-up and replaced automatically; project-modified files block the update until they
-are reviewed. Use `--force` only to back up and replace intentional overrides.
+Updates are hash-aware and line-ending-aware. Files that still match the previous
+install state update automatically even when Git converted CRLF to LF. Genuine
+project modifications are preserved, recorded in `.nccgs/framework-overrides.json`,
+and routed through one `/migrate-project` review instead of blocking the whole
+framework update. `--force` remains an explicit discard-and-replace escape hatch;
+it is not the normal upgrade path.
 
 The installer validates the package, backs up replaced framework/settings files to
 `.nccgs/backups/<timestamp>/`, copies `.claude/`, initializes missing `.nccgs/`
@@ -113,7 +116,7 @@ node .\.claude\nccgs\tools\configure-models.mjs --project . --profile inherit
 | `/status` | Current work, roles/models, evidence, blockers, closure, and next action |
 
 Thirty-six discoverable workflows include focused modules for architecture decisions,
-context packets, story readiness, code/design/evidence review, closure, QA planning,
+context packets, story readiness, NCCGS code/design/evidence review, closure, QA planning,
 triage, performance, security, accessibility, balance, prototypes, playtests,
 localization, hotfixes, milestones, assets, compatibility, incidents, and UI review.
 Ordinary natural-language requests still work; the user does not need to manually
@@ -124,6 +127,7 @@ chain these modules.
 ```text
 .nccgs/
   project.yaml       authority, model, studio, context, ownership and gate policy
+  framework-overrides.json  reviewed project-specific framework customizations
   state.md           compact recovery checkpoint
   requirements.yaml targeted requirement registry
   context/           task-specific source and ownership maps

package/UPGRADING.md

@@ -9,10 +9,23 @@ npx nccgs@latest update
 npx nccgs@latest doctor
 ```
 
-Version 1.1 adds hash-aware, idempotent updates. Managed files that still match the
-previous install state update automatically. Project-modified framework files stop
-the update and require review; `--force` backs them up before replacement. Existing
-`.nccgs/project.yaml` remains project-owned and is never blindly overwritten.
+Version 1.1.1 makes updates hash-aware, line-ending-aware, and override-aware.
+Managed files that still match the previous install state update automatically;
+CRLF/LF conversion alone is accepted as the same text. Genuine project-modified or
+intentionally missing framework files are preserved and recorded in
+`.nccgs/framework-overrides.json` as `pending_review`. The rest of the framework is
+updated normally, so `--force` is no longer required to get past intentional local
+customizations. Existing `.nccgs/project.yaml` remains project-owned and is never
+blindly overwritten.
+
+When pending overrides are reported, open a fresh Claude Code session and run
+`/migrate-project` once. The workflow reviews and rebases each override, migrates the
+project policy when needed, and records approval of the final hashes. A direct
+`doctor` remains red until pending override review is complete. Use `--force` only
+when you intentionally want to back up and discard every detected customization.
+
+NCCGS 1.1.1 also names its specialized review command `/nccgs-code-review` to avoid
+colliding with Claude Code's built-in `/code-review` command.
 
 When the installer reports that project migration is required, open a new Claude
 Code session and run one command:

package/VERSION

@@ -1 +1 @@
-1.1.0
+1.1.1

package/docs/HUONG-DAN-MIGRATE-VA-SU-DUNG.md

@@ -1,6 +1,6 @@
-# Hướng dẫn migrate và sử dụng NCCGS 1.1
+# Hướng dẫn migrate và sử dụng NCCGS 1.1.1
 
-NCCGS 1.1 là studio operating system dành cho Unity project trong Claude Code. Nó
+NCCGS 1.1.1 là studio operating system dành cho Unity project trong Claude Code. Nó
 không thay thế cách chat trực tiếp; nó tự phân loại rủi ro, chọn workflow, agent và
 model phù hợp, sử dụng official Unity Skills, thu thập bằng chứng và áp dụng closure.
 
@@ -46,9 +46,12 @@ npx nccgs@latest doctor
 NCCGS mặc định cài vào directory hiện tại. Bạn không cần truyền đường dẫn project;
 hãy mở PowerShell tại Unity project root hoặc dùng `cd` đến đó trước.
 
-Từ 1.1, update kiểm tra hash của lần cài trước. File NCCGS chưa bị project sửa sẽ tự
-được backup và cập nhật. File đã sửa tay sẽ chặn update; chỉ dùng `--force` sau khi
-đã review và chấp nhận thay thế bản override.
+Từ 1.1.1, update kiểm tra cả raw hash và hash text đã chuẩn hóa line ending. Việc Git
+đổi CRLF/LF không còn bị báo nhầm là sửa file. File thật sự đã customize hoặc cố ý
+xóa sẽ được giữ nguyên, ghi vào `.nccgs/framework-overrides.json` với trạng thái
+`pending_review`, còn các file an toàn khác vẫn cập nhật bình thường. Sau đó chỉ cần
+chạy `/migrate-project` một lần để review/rebase và phê duyệt các override. Không cần
+`--force`; chỉ dùng cờ đó khi thực sự muốn backup rồi loại bỏ customization.
 
 Installer sẽ:
 
@@ -60,6 +63,10 @@ Installer sẽ:
 6. cấu hình model cho agents;
 7. thêm NCCGS import vào `CLAUDE.md`.
 
+Nếu installer báo `Project migration required`, mở Claude Code session mới và chạy
+`/migrate-project`. `doctor` trực tiếp sẽ tiếp tục báo pending cho tới khi workflow
+đã review xong mọi override; đây là safety gate có chủ đích.
+
 Sau khi cài, đóng phiên Claude Code cũ và mở phiên mới tại project root.
 
 ## 3. Chọn model profile
@@ -185,7 +192,7 @@ NCCGS sẽ tự chọn:
 | `/release` | Tạo release candidate |
 | `/status` | Xem trạng thái, model, agents, evidence và blockers |
 
-Các workflow chuyên biệt như `/architecture-decision`, `/code-review`,
+Các workflow chuyên biệt như `/architecture-decision`, `/nccgs-code-review`,
 `/performance-audit`, `/security-audit`, `/balance-review`, `/playtest`, `/hotfix`,
 `/incident-recovery` có thể gọi trực tiếp, nhưng thông thường `/work` tự phối hợp.
 

package/docs/WORKFLOWS.md

@@ -33,7 +33,7 @@ available when a user wants a bounded workflow or output.
 - **Design**: `design`, `design-review`, `balance-review`, `accessibility-review`,
   `ui-review`, `prototype-feature`, `playtest`.
 - **Technical**: `architecture-decision`, `dependency-review`,
-  `compatibility-review`, `code-review`, `performance-audit`, `security-audit`.
+  `compatibility-review`, `nccgs-code-review`, `performance-audit`, `security-audit`.
 - **Implementation/quality**: `work`, `qa-plan`, `test`, `bug-triage`,
   `evidence-review`, `review`, `asset-audit`, `closure`.
 - **Delivery/recovery**: `release-readiness`, `release`, `hotfix`,

package/package-assets/nccgs-project.gitignore

@@ -0,0 +1,2 @@
+backups/
+runtime/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nccgs",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Unity-first game-studio operating system for Claude Code",
   "license": "MIT",
   "type": "module",

package/scripts/cli.mjs

@@ -53,7 +53,7 @@ Install target:
 
 Options:
   --dry-run                         Preview without writing files
-  --force                           Back up and replace framework conflicts
+  --force                           Back up and discard detected project overrides
   --model-profile <profile>         quality, balanced, or inherit
   --project <directory>             Optional explicit target directory
   --allow-non-unity                 Allow a target without Unity markers`);

package/scripts/doctor.mjs

@@ -1,39 +1,70 @@
 #!/usr/bin/env node
 
-import crypto from "node:crypto";
 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 allowPolicyMigration = args.includes("--allow-policy-migration");
+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();
-const errors = [];
 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");
-let state = null;
-if (!fs.existsSync(statePath)) errors.push("NCCGS install state is missing.");
-else {
-  try { state = JSON.parse(fs.readFileSync(statePath, "utf8")); }
-  catch (error) { errors.push(`Install state is invalid JSON: ${error.message}`); }
+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 (hashFile(file) !== item.sha256) errors.push(`Managed file was modified: ${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")) {
@@ -46,15 +77,12 @@ 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) {
-    const message = `Project policy schema must be 2; found ${policySchema ?? "unknown"}.`;
-    if (allowPolicyMigration) warnings.push(message);
-    else errors.push(message);
-  }
+  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);
 }
@@ -63,9 +91,39 @@ 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: ${state.files.length}`);
+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 hashFile(file) {
-  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+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, "..");
@@ -52,74 +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}`);
-    process.exit(2);
-  }
-}
+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 previousFiles = new Map((previousInstallState?.files ?? []).map((item) => [item.relative, item]));
-const currentFrameworkNames = new Set(frameworkFiles.map((item) => posix(item.relative)));
-const staleFrameworkFiles = (previousInstallState?.files ?? [])
+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) => ({
+  .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,
-    destination: path.join(project, ...item.relative.split("/")),
-    unmodified: fs.existsSync(path.join(project, ...item.relative.split("/"))) && hashFile(path.join(project, ...item.relative.split("/"))) === item.sha256
-  }))
-  .filter((item) => fs.existsSync(item.destination));
-
-const differentFiles = frameworkFiles.filter((item) => {
-  if (!fs.existsSync(item.destination)) return false;
-  return !sameFile(item.source, item.destination);
-});
-const automaticReplacements = differentFiles.filter((item) => {
-  const previous = previousFiles.get(posix(item.relative));
-  return previous && hashFile(item.destination) === previous.sha256;
-});
-const conflicts = differentFiles.filter((item) => !automaticReplacements.includes(item));
-const automaticStale = staleFrameworkFiles.filter((item) => item.unmodified);
-const staleConflicts = staleFrameworkFiles.filter((item) => !item.unmodified);
-
-if ((conflicts.length || staleConflicts.length) && !force) {
-  console.error(`NCCGS found ${conflicts.length} modified and ${staleConflicts.length} modified-stale framework file(s):`);
-  for (const item of conflicts.slice(0, 30)) console.error(`- ${posix(item.relative)}`);
-  for (const item of staleConflicts.slice(0, 30)) console.error(`- stale: ${item.relative}`);
-  if (conflicts.length > 30) console.error(`- ... ${conflicts.length - 30} more`);
-  console.error("These files differ from the hashes recorded at the previous install.");
-  console.error("Review them, then re-run with --force to back up and replace intentional overrides.");
-  process.exit(2);
+    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 - differentFiles.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");
@@ -132,12 +171,16 @@ if (!new Set(["quality", "balanced", "inherit"]).has(modelProfile)) {
 }
 
 console.log(`NCCGS installation target: ${project}`);
-console.log(`Framework version: ${previousInstallState?.frameworkVersion ?? "not installed"} -> ${fs.readFileSync(path.join(root, "VERSION"), "utf8").trim()}`);
-console.log(`Framework files: ${frameworkFiles.length} (${newFiles.length} new, ${identicalFiles} current, ${automaticReplacements.length} automatic update, ${conflicts.length} forced override)`);
-console.log(`Stale framework files: ${automaticStale.length} automatic removal, ${staleConflicts.length} forced removal`);
+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);
@@ -145,23 +188,21 @@ if (dryRun) {
 
 const stamp = new Date().toISOString().replace(/[:.]/g, "-");
 const backupRoot = path.join(project, ".nccgs", "backups", stamp);
-for (const item of differentFiles) {
-  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);
@@ -170,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 ?? "");
@@ -182,12 +227,13 @@ if (modelConfiguration.status !== 0) {
   process.exit(1);
 }
 
-writeInstallState(project, modelProfile, frameworkFiles, installStatePath, previousInstallState);
+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-policy-migration"
+  "--allow-migration-required"
 ], { cwd: project, encoding: "utf8" });
 process.stdout.write(doctor.stdout ?? "");
 process.stderr.write(doctor.stderr ?? "");
@@ -197,10 +243,12 @@ if (doctor.status !== 0) {
 }
 
 console.log("NCCGS installation complete.");
-if (differentFiles.length || staleFrameworkFiles.length || settingsPlan.changed) console.log(`Changed shared files backed up under: ${backupRoot}`);
+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) {
+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`.");
@@ -208,7 +256,75 @@ if (installedPolicySchema !== 2) {
   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);
@@ -218,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);
     }
@@ -264,27 +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, previousState) {
+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
+  };
+  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: 2,
-    frameworkVersion: fs.readFileSync(path.join(root, "VERSION"), "utf8").trim(),
+    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 });
@@ -299,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",
+  "package-assets/nccgs-project.gitignore",
   "scripts/cli.mjs", "scripts/doctor.mjs", "scripts/install.mjs",
-  "scripts/sync-unity-skills.mjs", "tests/framework.test.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/doctor.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()}`);
 }

package/tests/framework.test.mjs

@@ -129,7 +129,7 @@ test("installer preserves project truth, merges settings, and applies inherit pr
   }
 });
 
-test("update replaces untouched managed files, blocks local edits, and doctor verifies state", () => {
+test("update replaces untouched files, preserves local overrides, and doctor gates review", () => {
   const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-idempotent-update-test-"));
   try {
     for (const marker of ["Assets", "Packages", "ProjectSettings"]) fs.mkdirSync(path.join(temp, marker));
@@ -148,20 +148,84 @@ test("update replaces untouched managed files, blocks local edits, and doctor ve
 
     const update = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "update"], { cwd: temp, encoding: "utf8" });
     assert.equal(update.status, 0, update.stderr || update.stdout);
-    assert.match(update.stdout, /1\.0\.0 -> 1\.1\.0/);
+    assert.match(update.stdout, new RegExp(`1\\.0\\.0 -> ${frameworkVersion.replace(/\./g, "\\.")}`));
     assert.match(update.stdout, /automatic update/);
     assert.match(update.stdout, /No project migration required/);
     assert.equal(fs.readFileSync(managedPath, "utf8"), fs.readFileSync(path.join(root, managedRelative), "utf8"));
 
-    const doctor = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "doctor"], { cwd: temp, encoding: "utf8" });
+    let doctor = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "doctor"], { cwd: temp, encoding: "utf8" });
     assert.equal(doctor.status, 0, doctor.stderr || doctor.stdout);
     assert.match(doctor.stdout, /NCCGS doctor passed/);
 
     fs.writeFileSync(managedPath, "project-local override\n", "utf8");
-    const blocked = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "update", "--dry-run"], { cwd: temp, encoding: "utf8" });
-    assert.equal(blocked.status, 2);
-    assert.match(blocked.stderr, /modified/);
+    const preserved = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "update"], { cwd: temp, encoding: "utf8" });
+    assert.equal(preserved.status, 0, preserved.stderr || preserved.stdout);
+    assert.match(preserved.stdout, /preserved override/);
+    assert.match(preserved.stdout, /Project migration required/);
     assert.equal(fs.readFileSync(managedPath, "utf8"), "project-local override\n");
+
+    const overridePath = path.join(temp, ".nccgs/framework-overrides.json");
+    const overrides = JSON.parse(fs.readFileSync(overridePath, "utf8"));
+    const override = overrides.overrides.find((item) => item.path === managedRelative);
+    assert.equal(override.status, "pending_review");
+    assert.equal(override.disposition, "preserve");
+
+    doctor = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "doctor"], { cwd: temp, encoding: "utf8" });
+    assert.equal(doctor.status, 1);
+    assert.match(doctor.stderr, /awaits \/migrate-project review/);
+
+    const approve = spawnSync(process.execPath, [path.join(temp, ".claude/nccgs/tools/approve-overrides.mjs"), "--project", temp, "--approve-pending"], { cwd: temp, encoding: "utf8" });
+    assert.equal(approve.status, 0, approve.stderr || approve.stdout);
+    doctor = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "doctor"], { cwd: temp, encoding: "utf8" });
+    assert.equal(doctor.status, 0, doctor.stderr || doctor.stdout);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+});
+
+test("doctor accepts a legacy CRLF raw hash after Git normalizes the file to LF", () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-eol-test-"));
+  try {
+    for (const marker of ["Assets", "Packages", "ProjectSettings"]) fs.mkdirSync(path.join(temp, marker));
+    const install = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "install"], { cwd: temp, encoding: "utf8" });
+    assert.equal(install.status, 0, install.stderr || install.stdout);
+
+    const relative = ".claude/nccgs/constitution.md";
+    const file = path.join(temp, ...relative.split("/"));
+    const lf = fs.readFileSync(file, "utf8").replace(/\r\n?/g, "\n");
+    fs.writeFileSync(file, lf, "utf8");
+    const statePath = path.join(temp, ".claude/nccgs/install-state.json");
+    const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    const record = state.files.find((item) => item.relative === relative);
+    record.sha256 = sha256(lf.replace(/\n/g, "\r\n"));
+    delete record.canonicalSha256;
+    state.schemaVersion = 2;
+    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+
+    const doctor = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "doctor"], { cwd: temp, encoding: "utf8" });
+    assert.equal(doctor.status, 0, doctor.stderr || doctor.stdout);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+});
+
+test("update preserves an intentionally missing managed file until migration review", () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-absent-override-test-"));
+  try {
+    for (const marker of ["Assets", "Packages", "ProjectSettings"]) fs.mkdirSync(path.join(temp, marker));
+    const install = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "install"], { cwd: temp, encoding: "utf8" });
+    assert.equal(install.status, 0, install.stderr || install.stdout);
+
+    const relative = ".claude/skills/status/SKILL.md";
+    const file = path.join(temp, ...relative.split("/"));
+    fs.unlinkSync(file);
+    const update = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "update"], { cwd: temp, encoding: "utf8" });
+    assert.equal(update.status, 0, update.stderr || update.stdout);
+    assert.ok(!fs.existsSync(file));
+    const manifest = JSON.parse(fs.readFileSync(path.join(temp, ".nccgs/framework-overrides.json"), "utf8"));
+    const override = manifest.overrides.find((item) => item.path === relative);
+    assert.equal(override.disposition, "absent");
+    assert.equal(override.status, "pending_review");
   } finally {
     fs.rmSync(temp, { recursive: true, force: true });
   }