nccgs 1.0.0 → 1.1.0

package/.claude/nccgs/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

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

@@ -6,10 +6,11 @@ allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion
 
 # Migrate project
 
-Treat brownfield adoption and NCCGS upgrades as CONTROLLED work. Read the complete [migration procedure](references/procedure.md). Default to `review` when no mode is given.
+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`.
 
 ## 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.
 - `review`: read-only inventory and KEEP/ADAPT/MIGRATE/DEPRECATE/REMOVE/MISSING classification.
 - `plan`: write a dated reversible plan and proposed schema-2 policy without overwriting project truth.
 - `apply`: execute an approved plan in validated batches with backups.
@@ -17,5 +18,6 @@ Treat brownfield adoption and NCCGS upgrades as CONTROLLED work. Read the comple
 
 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.
 
-Never remove reports, registers, checklists, user settings, source assets, or legacy instructions until their live purpose is mapped and the Product Owner approves the replacement. Do not infer canon from code. Return batches, commits, preserved evidence, unresolved decisions, rollback, and final migration state.
+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.
 
+Never remove reports, registers, checklists, user settings, source assets, or legacy instructions until their live purpose is mapped and the Product Owner approves the replacement. Do not infer canon from code. Return batches, commits, preserved evidence, unresolved decisions, rollback, and final migration state.

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

@@ -1,5 +1,17 @@
 # Brownfield migration procedure
 
+## Full run
+
+`/migrate-project` without a mode executes Review -> Plan -> Apply -> Verify as one
+CONTROLLED operation. Keep the phase boundaries in the migration record, but do not
+make the user invoke each phase separately. Continue automatically when changes are
+reversible, backed up, within the requested adoption/migration scope, and do not
+alter unresolved project truth. Stop before apply only when review exposes a genuine
+Product Owner decision, destructive action, external side effect, or authority gap.
+
+If the NCCGS installer and current schema indicate that an ordinary framework update
+requires no project migration, report that fact and do not manufacture migration work.
+
 ## Review
 
 1. Inspect repository status and project root without modifying it.

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.0 contains:
+Version 1.1 contains:
 
 - 45 studio agents across leadership, design, programming, Unity, content, quality,
   and release;
@@ -48,13 +48,18 @@ npx nccgs@latest install
 For an existing NCCGS installation:
 
 ```powershell
-npx nccgs@latest install --dry-run
-npx nccgs@latest install --force
+npx nccgs@latest update --dry-run
+npx nccgs@latest update
+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.
+
 The installer validates the package, backs up replaced framework/settings files to
 `.nccgs/backups/<timestamp>/`, copies `.claude/`, initializes missing `.nccgs/`
 scaffold files without overwriting project truth, merges managed hooks into shared
@@ -64,13 +69,16 @@ import to `CLAUDE.md`.
 Select a model profile during installation when needed:
 
 ```powershell
-npx nccgs@latest install --force --model-profile quality
-npx nccgs@latest install --force --model-profile balanced
-npx nccgs@latest install --force --model-profile inherit
+npx nccgs@latest update --model-profile quality
+npx nccgs@latest update --model-profile balanced
+npx nccgs@latest update --model-profile inherit
 ```
 
-Open a new Claude Code session after installation. Run `/migrate-project review` for
-an existing project; installing framework files alone is not migration.
+Open a new Claude Code session after first-time adoption of an existing project and
+run `/migrate-project` once. It performs review, plan, apply, and verify as one
+CONTROLLED operation, pausing only for a real Product Owner decision or unsafe side
+effect. Ordinary framework updates report `No project migration required` and need
+no Claude migration command.
 
 ## Model routing
 

package/UPGRADING.md

@@ -4,23 +4,27 @@ Always inspect a dry run and preserve project policy.
 
 ```powershell
 cd "D:\path\to\UnityProject"
-npx nccgs@latest install --dry-run
-npx nccgs@latest install --force
+npx nccgs@latest update --dry-run
+npx nccgs@latest update
+npx nccgs@latest doctor
 ```
 
-Version 1.0 is a framework and policy-schema upgrade from 0.2. The installer updates
-framework files and merges managed hooks, but deliberately does not overwrite an
-existing `.nccgs/project.yaml`. After installation, open a new Claude Code session
-and run:
+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.
+
+When the installer reports that project migration is required, open a new Claude
+Code session and run one command:
 
 ```text
-/migrate-project review
-/migrate-project plan
-/migrate-project apply
-/migrate-project verify
+/migrate-project
 /status full
 ```
 
+The workflow retains review, plan, apply, and verify internally. Do not run it after
+an ordinary update when the installer reports `No project migration required`.
+
 The migration plan must move schema 1 policy to schema 2, choose a model profile,
 enable departments, configure context packets and orchestration, preserve closure
 artifacts, verify hooks, and resolve obsolete global skills. Keep

package/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

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

@@ -1,6 +1,6 @@
-# Hướng dẫn migrate và sử dụng NCCGS 1.0
+# Hướng dẫn migrate và sử dụng NCCGS 1.1
 
-NCCGS 1.0 là studio operating system dành cho Unity project trong Claude Code. Nó
+NCCGS 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.
 
@@ -38,13 +38,18 @@ npx nccgs@latest install
 Nếu project đã có NCCGS:
 
 ```powershell
-npx nccgs@latest install --dry-run
-npx nccgs@latest install --force
+npx nccgs@latest update --dry-run
+npx nccgs@latest update
+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.
+
 Installer sẽ:
 
 1. validate NCCGS;
@@ -68,7 +73,7 @@ Sau khi cài, đóng phiên Claude Code cũ và mở phiên mới tại project
 Cài với profile cụ thể:
 
 ```powershell
-npx nccgs@latest install --force --model-profile quality
+npx nccgs@latest update --model-profile quality
 ```
 
 Đổi profile trong project đã cài:
@@ -82,12 +87,17 @@ khoản hoặc context mode hiện tại, dùng `inherit` hoặc cho phép inher
 
 ## 4. Migrate project cũ
 
-Migration gồm bốn bước:
+Thông thường chỉ cần gọi một command:
 
 ```text
-review -> plan -> apply -> verify
+/migrate-project
 ```
 
+NCCGS vẫn thực hiện bốn phase `review -> plan -> apply -> verify` ở bên trong một
+lần chạy. Nó chỉ dừng khi có quyết định Product Owner thật sự, thao tác destructive,
+external side effect hoặc thiếu authority. Các mode riêng dưới đây vẫn tồn tại để
+debug hoặc kiểm soát thủ công.
+
 ### Review
 
 ```text
@@ -258,7 +268,7 @@ Sau migration:
 ```powershell
 git add .claude .nccgs CLAUDE.md
 git status --short
-git commit -m "chore: adopt NCCGS 1.0 studio workflow"
+git commit -m "chore: adopt NCCGS 1.1 studio workflow"
 ```
 
 Luôn đọc diff trước commit.

package/docs/MIGRATION-MATRIX.md

@@ -1,6 +1,6 @@
-# CCGS to NCCGS 1.0 migration matrix
+# CCGS to NCCGS 1.1 migration matrix
 
-| CCGS capability | NCCGS 1.0 treatment | Reason |
+| CCGS capability | NCCGS 1.1 treatment | Reason |
 |---|---|---|
 | Three-tier studio hierarchy | ADAPT into 44 roles and a central one-level orchestrator | Preserve specialization without recursive context chains |
 | Opus/Sonnet/Haiku agent pins | ADAPT into quality/balanced/inherit profiles | Preserve model routing while handling compatibility and cost |

package/package.json

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

package/scripts/cli.mjs

@@ -19,13 +19,15 @@ if (command === "version" || command === "--version" || command === "-v") {
   process.exit(0);
 }
 
-if (command !== "install") {
+if (!new Set(["install", "update", "doctor"]).has(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(2);
 }
 
-const result = spawnSync(process.execPath, [path.join(scriptDir, "install.mjs"), ...args], {
+const script = command === "doctor" ? "doctor.mjs" : "install.mjs";
+const forwardedArgs = command === "update" ? ["--update-only", ...args] : args;
+const result = spawnSync(process.execPath, [path.join(scriptDir, script), ...forwardedArgs], {
   cwd: process.cwd(),
   stdio: "inherit"
 });
@@ -41,6 +43,8 @@ function printHelp() {
 
 Usage:
   nccgs install [options]
+  nccgs update [options]
+  nccgs doctor [options]
   nccgs --version
 
 Install target:

package/scripts/doctor.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const projectIndex = args.indexOf("--project");
+const allowPolicyMigration = args.includes("--allow-policy-migration");
+const warnings = [];
+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}`); }
+}
+
+if (state) {
+  for (const item of state.files ?? []) {
+    const file = path.join(project, ...item.relative.split("/"));
+    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}`);
+  }
+}
+
+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) {
+    const message = `Project policy schema must be 2; found ${policySchema ?? "unknown"}.`;
+    if (allowPolicyMigration) warnings.push(message);
+    else errors.push(message);
+  }
+}
+
+if (errors.length) {
+  for (const error of errors) console.error(`ERROR: ${error}`);
+  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: ${state.files.length}`);
+console.log(`Project policy schema: ${policySchema ?? "migration required"}`);
+
+function hashFile(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}

package/scripts/install.mjs

@@ -10,6 +10,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;
@@ -75,28 +76,45 @@ if (fs.existsSync(installStatePath)) {
     process.exit(2);
   }
 }
+if (updateOnly && !previousInstallState) {
+  console.error("NCCGS is not installed in this project. Run `npx nccgs@latest install` first.");
+  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 ?? [])
   .filter((item) => !currentFrameworkNames.has(item.relative))
-  .map((item) => ({ ...item, destination: path.join(project, ...item.relative.split("/")) }))
+  .map((item) => ({
+    ...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 conflicts = frameworkFiles.filter((item) => {
+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 || staleFrameworkFiles.length) && !force) {
-  console.error(`Installation found ${conflicts.length} conflicting and ${staleFrameworkFiles.length} stale framework file(s):`);
+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 staleFrameworkFiles.slice(0, 30)) console.error(`- stale: ${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("Re-run with --force to back up and replace these framework files.");
+  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);
 }
 
 const newFiles = frameworkFiles.filter((item) => !fs.existsSync(item.destination));
-const identicalFiles = frameworkFiles.length - newFiles.length - conflicts.length;
+const identicalFiles = frameworkFiles.length - newFiles.length - differentFiles.length;
 const scaffoldFiles = walk(path.join(root, "scaffold")).map((file) => ({
   source: file,
   relative: path.relative(path.join(root, "scaffold"), file),
@@ -114,8 +132,9 @@ 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"} -> ${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(`Project scaffold files to initialize: ${newScaffold.length}`);
 console.log(`Managed Claude settings: ${settingsPlan.changed ? "update" : "already current"}`);
 console.log(`Agent model profile: ${modelProfile}`);
@@ -126,7 +145,7 @@ if (dryRun) {
 
 const stamp = new Date().toISOString().replace(/[:.]/g, "-");
 const backupRoot = path.join(project, ".nccgs", "backups", stamp);
-for (const item of conflicts) {
+for (const item of differentFiles) {
   const backup = path.join(backupRoot, item.relative);
   fs.mkdirSync(path.dirname(backup), { recursive: true });
   fs.copyFileSync(item.destination, backup);
@@ -163,11 +182,31 @@ if (modelConfiguration.status !== 0) {
   process.exit(1);
 }
 
-writeInstallState(project, modelProfile, frameworkFiles, installStatePath);
+writeInstallState(project, modelProfile, frameworkFiles, installStatePath, previousInstallState);
+
+const doctor = spawnSync(process.execPath, [
+  path.join(scriptDir, "doctor.mjs"),
+  "--project", project,
+  "--allow-policy-migration"
+], { 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 (differentFiles.length || staleFrameworkFiles.length || settingsPlan.changed) console.log(`Changed shared files 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) {
+  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 walk(directory) {
   const output = [];
@@ -234,11 +273,15 @@ function installManagedSettings(plan, backupDirectory) {
   fs.writeFileSync(plan.settingsPath, plan.nextText, "utf8");
 }
 
-function writeInstallState(projectRoot, profile, files, statePath) {
+function writeInstallState(projectRoot, profile, files, statePath, previousState) {
+  const now = new Date().toISOString();
   const state = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     frameworkVersion: fs.readFileSync(path.join(root, "VERSION"), "utf8").trim(),
+    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))

package/scripts/validate.mjs

@@ -51,7 +51,7 @@ 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/cli.mjs", "scripts/doctor.mjs", "scripts/install.mjs",
   "scripts/sync-unity-skills.mjs", "tests/framework.test.mjs"
 ]) requireFile(relative);
 
@@ -128,7 +128,7 @@ 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, "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

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -9,6 +10,8 @@ import { fileURLToPath } from "node:url";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const studio = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/studio.json"), "utf8"));
 const workflows = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/workflow-catalog.json"), "utf8"));
+const frameworkVersion = fs.readFileSync(path.join(root, "VERSION"), "utf8").trim();
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
 
 test("studio roles are unique and workflow references resolve", () => {
   const roles = new Set(studio.agents.map((agent) => agent.name));
@@ -24,6 +27,12 @@ test("quality profile assigns all model classes", () => {
   }
 });
 
+test("migrate-project defaults to a single full run", () => {
+  const skill = fs.readFileSync(path.join(root, ".claude/skills/migrate-project/SKILL.md"), "utf8");
+  assert.match(skill, /Default to `full`/);
+  assert.match(skill, /review, plan, apply, and verify in one invocation/i);
+});
+
 test("model configurator can remove and restore model pins", () => {
   const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-model-test-"));
   try {
@@ -104,7 +113,7 @@ test("installer preserves project truth, merges settings, and applies inherit pr
     assert.ok(fs.existsSync(path.join(temp, ".nccgs/backups")));
     const installStatePath = path.join(temp, ".claude/nccgs/install-state.json");
     const installState = JSON.parse(fs.readFileSync(installStatePath, "utf8"));
-    assert.equal(installState.frameworkVersion, "1.0.0");
+    assert.equal(installState.frameworkVersion, frameworkVersion);
     assert.equal(installState.modelProfile, "inherit");
 
     const obsoleteRelative = ".claude/agents/nccgs-obsolete.md";
@@ -119,3 +128,53 @@ test("installer preserves project truth, merges settings, and applies inherit pr
     fs.rmSync(temp, { recursive: true, force: true });
   }
 });
+
+test("update replaces untouched managed files, blocks local edits, and doctor verifies state", () => {
+  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));
+    const install = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "install", "--model-profile", "quality"], { cwd: temp, encoding: "utf8" });
+    assert.equal(install.status, 0, install.stderr || install.stdout);
+
+    const managedRelative = ".claude/nccgs/constitution.md";
+    const managedPath = path.join(temp, ...managedRelative.split("/"));
+    const statePath = path.join(temp, ".claude/nccgs/install-state.json");
+    const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    const oldManagedContent = "managed by NCCGS 1.0.0\n";
+    fs.writeFileSync(managedPath, oldManagedContent, "utf8");
+    state.frameworkVersion = "1.0.0";
+    state.files.find((item) => item.relative === managedRelative).sha256 = sha256(oldManagedContent);
+    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+
+    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, /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" });
+    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/);
+    assert.equal(fs.readFileSync(managedPath, "utf8"), "project-local override\n");
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+});
+
+test("update refuses a project without an NCCGS install state", () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-update-missing-test-"));
+  try {
+    for (const marker of ["Assets", "Packages", "ProjectSettings"]) fs.mkdirSync(path.join(temp, marker));
+    const result = spawnSync(process.execPath, [path.join(root, "scripts/cli.mjs"), "update"], { cwd: temp, encoding: "utf8" });
+    assert.equal(result.status, 2);
+    assert.match(result.stderr, /not installed/);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+});