nccgs 1.1.0 → 1.3.0

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,92 +57,131 @@ 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");
 const targetPolicy = fs.existsSync(targetPolicyPath) ? fs.readFileSync(targetPolicyPath, "utf8") : "";
 const policyModelProfile = targetPolicy.match(/^models:\s*$[\s\S]*?^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim();
-const modelProfile = requestedModelProfile || policyModelProfile || "quality";
-if (!new Set(["quality", "balanced", "inherit"]).has(modelProfile)) {
+const studio = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/studio.json"), "utf8"));
+const modelProfile = requestedModelProfile || policyModelProfile || studio.defaultProfile;
+if (!Object.hasOwn(studio.modelProfiles, modelProfile)) {
   console.error(`Unknown model profile: ${modelProfile}`);
   process.exit(2);
 }
 
 console.log(`NCCGS installation target: ${project}`);
-console.log(`Framework version: ${previousInstallState?.frameworkVersion ?? "not installed"} -> ${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 +189,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 +212,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 +228,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 +244,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 || /^profile_contracts:/m.test(installedPolicy)) {
   console.log("Project migration required: open a new Claude Code session and run `/migrate-project` once.");
 } else if (!previousInstallState) {
   console.log("First NCCGS adoption: run `/migrate-project` once for an existing project; a new project can start with `/status`.");
@@ -208,7 +257,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 +335,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 +390,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 +435,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

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { compile } from "../.claude/nccgs/tools/compile-policy.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const errors = [];
@@ -44,17 +45,29 @@ for (const relative of [
   "VERSION", "README.md", "CLAUDE.md", "LICENSE", "package.json",
   ".claude/nccgs/VERSION", ".claude/nccgs/constitution.md",
   ".claude/nccgs/studio.json", ".claude/nccgs/workflow-catalog.json",
+  ".claude/nccgs/pipeline.json", ".claude/nccgs/protocols/task-gates.md",
+  ".claude/nccgs/tools/task.mjs", ".claude/nccgs/tools/gates.mjs", ".claude/nccgs/tools/runtime.mjs",
+  "scaffold/.nccgs/gates.json", "tests/gates.test.mjs",
   ".claude/nccgs/settings.fragment.json", ".claude/nccgs/unity-skills-manifest.json",
   ".claude/nccgs/protocols/agent-contract.md", ".claude/nccgs/protocols/orchestration.md",
   ".claude/nccgs/protocols/model-routing.md", ".claude/nccgs/protocols/context-packets.md",
+  ".claude/nccgs/protocols/astra-claude.md", "scaffold/.nccgs/templates/implementation-report.md",
   ".claude/nccgs/protocols/evidence.md", ".claude/nccgs/protocols/unity-boundary.md",
   "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,
@@ -70,17 +83,22 @@ const rootClaude = fs.readFileSync(path.join(root, "CLAUDE.md"), "utf8");
 if (!rootClaude.includes("@.claude/nccgs/constitution.md")) errors.push("CLAUDE.md does not import the NCCGS constitution.");
 
 const studio = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/studio.json"), "utf8"));
+const pipeline = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/pipeline.json"), "utf8"));
+for (const stale of compile(root)) errors.push(`Stale generated policy: ${stale}; run npm run policy:build`);
 const agentNames = new Set();
 for (const agent of studio.agents ?? []) {
   if (agentNames.has(agent.name)) errors.push(`Duplicate catalog agent: ${agent.name}`);
   agentNames.add(agent.name);
-  const file = path.join(root, ".claude", "agents", `${agent.name}.md`);
+  const active = pipeline.profiles[pipeline.defaultProfile].activeAgents.includes(agent.name);
+  const file = path.join(root, active ? ".claude/agents" : ".claude/nccgs/agent-library", `${agent.name}.md`);
   if (!fs.existsSync(file)) { errors.push(`Catalog agent file missing: ${agent.name}`); continue; }
   const metadata = frontmatter(file);
   if (metadata?.name !== agent.name || !metadata?.description) errors.push(`Invalid agent frontmatter: ${agent.name}`);
   const expected = studio.modelProfiles[studio.defaultProfile]?.[agent.modelClass];
-  if (metadata?.model !== expected) errors.push(`Agent model mismatch: ${agent.name} expected ${expected}, found ${metadata?.model}`);
-  if ((metadata?.tools ?? "").split(/,\s*/).includes("Task")) errors.push(`Agent may recursively delegate: ${agent.name}`);
+  if (active && metadata?.model !== expected) errors.push(`Agent model mismatch: ${agent.name} expected ${expected}, found ${metadata?.model}`);
+  const expectedEffort = studio.effortProfiles?.[studio.defaultProfile]?.[agent.modelClass];
+  if (active && metadata?.effort !== expectedEffort) errors.push(`Agent effort mismatch: ${agent.name} expected ${expectedEffort}, found ${metadata?.effort}`);
+  if ((metadata?.tools ?? "").split(/,\s*/).some(tool => ["Task", "Agent"].includes(tool))) errors.push(`Agent may recursively delegate: ${agent.name}`);
   if (!fs.readFileSync(file, "utf8").includes("protocols/agent-contract.md")) errors.push(`Agent does not load common contract: ${agent.name}`);
   if (fs.readFileSync(file, "utf8").split(/\r?\n/).length > 80) errors.push(`Agent entrypoint exceeds 80 lines: ${agent.name}`);
 }
@@ -88,6 +106,7 @@ for (const agent of studio.agents ?? []) {
 const actualAgents = walk(path.join(root, ".claude/agents")).filter((file) => file.endsWith(".md"));
 for (const file of actualAgents) {
   if (!agentNames.has(path.basename(file, ".md"))) errors.push(`Uncataloged NCCGS agent: ${posix(path.relative(root, file))}`);
+  if (!pipeline.coreAgents.includes(path.basename(file, ".md"))) errors.push(`Non-core agent active in source package: ${posix(path.relative(root, file))}`);
 }
 
 const workflows = JSON.parse(fs.readFileSync(path.join(root, ".claude/nccgs/workflow-catalog.json"), "utf8"));
@@ -103,6 +122,10 @@ for (const workflow of workflows.workflows ?? []) {
   if (lines > 120) errors.push(`Workflow entrypoint exceeds 120 lines: ${workflow.name}`);
   if (fs.existsSync(path.join(path.dirname(file), "README.md"))) errors.push(`NCCGS-owned skill contains redundant README: ${workflow.name}`);
   for (const role of workflow.primaryRoles ?? []) if (!agentNames.has(role)) errors.push(`Workflow ${workflow.name} references unknown role ${role}`);
+  for (const [profile, roles] of Object.entries(workflow.primaryRolesByProfile ?? {})) {
+    if (!studio.modelProfiles[profile]) errors.push(`Workflow ${workflow.name} references unknown profile ${profile}`);
+    for (const role of roles) if (!agentNames.has(role)) errors.push(`Workflow ${workflow.name} references unknown role ${role}`);
+  }
 }
 for (const entry of workflows.entrypoints ?? []) if (!workflowNames.has(entry)) errors.push(`Missing entrypoint workflow: ${entry}`);
 
@@ -128,7 +151,12 @@ 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 [
+  ...walk(path.join(root, ".claude/nccgs/tools")).filter(file => file.endsWith(".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()}`);
 }
@@ -198,7 +226,7 @@ if (errors.length) {
 
 console.log("NCCGS validation passed.");
 console.log(`NCCGS workflows: ${workflowNames.size} (${workflows.entrypoints.length} entrypoints)`);
-console.log(`Studio agents: ${agentNames.size}`);
+console.log(`Studio agents: ${agentNames.size} in library; ${pipeline.coreAgents.length} active by default`);
 console.log(`Path-scoped rules: ${rules.length}`);
 console.log(`Managed hooks: ${hookCommands.length}`);
 console.log(`Vendored Unity Skills: ${manifest?.skills?.length ?? 0}`);