nccgs 2.0.0-rc.3 → 2.1.0

package/scripts/uninstall.mjs

@@ -0,0 +1,292 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
+import { matchesFingerprint, equivalentBuffers, sha256 } from "../.claude/nccgs/tools/integrity.mjs";
+import { canonicalHookCommand } from "../.claude/nccgs/tools/autonomy.mjs";
+import { acquireLock, ownerState } from "../.claude/nccgs/tools/process-lock.mjs";
+import { assertInstallationAvailable } from "../.claude/nccgs/tools/installation-guard.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const statePath = ".claude/nccgs/install-state.json";
+const lockPath = ".nccgs/uninstall.lock";
+const need = (ok, message) => { if (!ok) throw new Error(message); };
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const digest = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const read = file => JSON.parse(fs.readFileSync(file, "utf8"));
+
+function files(project, relative) {
+  const directory = containedPath(project, relative);
+  if (!fs.existsSync(directory)) return [];
+  need(fs.statSync(directory).isDirectory(), `Expected a directory: ${relative}`);
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const name = `${relative}/${entry.name}`, file = containedPath(project, name);
+    if (entry.isDirectory()) return files(project, name);
+    need(entry.isFile() && fs.statSync(file).isFile(), `Unsupported entry: ${name}`);
+    return [name];
+  });
+}
+
+// Read only: do not settle/recover a job, rewrite a task, reclaim an old lock or
+// terminate a process merely to make uninstallation possible.
+export function assertUninstallIdle(project, ownToken = null) {
+  need(!(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT || process.env.NCCGS_SUPERVISED_SESSION),
+    "Close Claude Code and run uninstall from an external terminal.");
+  const at = relative => containedPath(project, relative);
+  const candidates = [...[".nccgs/orchestration.lock", ".nccgs/measurement-start.lock", lockPath].flatMap(name => [name, `${name}.recovery`]),
+    ...[".nccgs/tasks", ".nccgs/jobs", ".nccgs/runs", ".nccgs/sessions"].flatMap(dir => files(project, dir))];
+  for (const relative of candidates.filter(name => /\.lock(?:\.recovery)?$/.test(name))) {
+    if (!fs.existsSync(at(relative))) continue;
+    const lock = read(at(relative));
+    if (relative === lockPath && ownToken && lock.token === ownToken) continue;
+    need(ownerState(lock) === "dead", `Cannot uninstall: active or unverified process lock ${relative}. Stop/recover the owning work first.${relative.startsWith(".nccgs/sessions/") && lock.operation === "nccgs-run" ? " For a crashed launcher, see recover-session --dry-run and docs/UNINSTALL.md; never infer descendant shutdown from PID death." : ""}`);
+  }
+  const ledger = at(".nccgs/orchestration.json");
+  if (fs.existsSync(ledger)) {
+    const value = read(ledger);
+    need(object(value.dispatches), "Invalid dispatch ledger; inspect it before uninstalling.");
+    for (const dispatch of Object.values(value.dispatches)) {
+      need(object(dispatch) && ["completed", "failed", "cancelled"].includes(dispatch.status),
+        `Cannot uninstall: dispatch ${dispatch?.id ?? "unknown"} is active or unverified.`);
+    }
+  }
+  for (const relative of candidates.filter(name => /^\.nccgs\/jobs\/[^/]+\/request\.json$/.test(name))) {
+    const result = at(relative.replace(/request\.json$/, "result.json"));
+    need(fs.existsSync(result) && ["PASS", "FAIL"].includes(read(result).status), `Cannot uninstall: unsettled verification job ${relative}.`);
+  }
+  for (const relative of candidates.filter(name => /^\.nccgs\/runs\/[^/]+\/run\.json$/.test(name))) {
+    const run = read(at(relative));
+    need(["ready", "settled", "blocked"].includes(run.status) && Array.isArray(run.invocations)
+      && run.invocations.every(item => ["finished", "recovered"].includes(item.status)), `Cannot uninstall: active or unverified run ${relative}.`);
+  }
+}
+
+function catalog() {
+  const known = new Set(files(root, ".claude"));
+  known.add(".claude/skills/setup-vivox-voice-chat/evals/.gitignore");
+  const studio = read(path.join(root, ".claude/nccgs/studio.json"));
+  for (const agent of studio.agents) known.add(`.claude/agents/${agent.name}.md`);
+  return known;
+}
+
+function removeHooks(text) {
+  const settings = JSON.parse(text);
+  need(object(settings), "Claude settings must be an object.");
+  if (settings.hooks === undefined) return text;
+  need(object(settings.hooks), "Invalid Claude hooks; no files were removed.");
+  const fragment = read(path.join(root, ".claude/nccgs/settings.fragment.json"));
+  const commands = new Set(Object.values(fragment.hooks).flatMap(groups => groups.flatMap(g => g.hooks))
+    .map(hook => canonicalHookCommand(hook.command)));
+  let changed = false;
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    need(Array.isArray(groups), `Invalid hook groups: ${event}`);
+    settings.hooks[event] = groups.flatMap(group => {
+      need(object(group) && Array.isArray(group.hooks), `Invalid hook group: ${event}`);
+      const hooks = group.hooks.filter(hook => {
+        need(object(hook), `Invalid hook: ${event}`);
+        if (hook.type !== "command" || typeof hook.command !== "string") return true;
+        if (commands.has(canonicalHookCommand(hook.command))) { changed = true; return false; }
+        need(!/[\\/]\.claude[\\/]nccgs[\\/]|\.claude[\\/]nccgs[\\/]/i.test(hook.command),
+          `Customized NCCGS hook in ${event}; separate/remove it manually before uninstalling.`);
+        return true;
+      });
+      // Keep unrelated hooks and their matcher/timeout/metadata, even when they
+      // share a group with a framework hook.
+      return hooks.length || !group.hooks.length ? [{ ...group, hooks }] : [];
+    });
+    if (!settings.hooks[event].length && groups.length) delete settings.hooks[event];
+  }
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  // Old installers did not record ownership of generic deny/model preferences.
+  // Preserve those shared settings instead of guessing which values to remove.
+  return changed ? `${JSON.stringify(settings, null, 2)}\n` : text;
+}
+
+function removeImport(buffer) {
+  if (equivalentBuffers(buffer, fs.readFileSync(path.join(root, "CLAUDE.md")))) return null;
+  const text = buffer.toString("utf8");
+  need(Buffer.from(text, "utf8").equals(buffer), "CLAUDE.md must be UTF-8 to remove the NCCGS import safely.");
+  const next = text.replace(/^<!-- NCCGS:BEGIN -->\r?\n@\.claude\/nccgs\/constitution\.md\r?\n<!-- NCCGS:END -->(?:\r?\n|$)/gm, "")
+    .replace(/^[ \t]*@\.claude\/nccgs\/constitution\.md[ \t]*(?:\r?\n|$)/gm, "");
+  need(!/@\.claude\/nccgs\//.test(next), "Customized NCCGS import in CLAUDE.md; remove it manually before uninstalling.");
+  return Buffer.from(next, "utf8");
+}
+
+export function planUninstall(project, ownToken = null) {
+  project = assertProjectRoot(project);
+  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
+  assertUninstallIdle(project, ownToken);
+  const at = relative => containedPath(project, relative), known = catalog(), file = at(statePath);
+  if (!fs.existsSync(file)) return { project, status: "NOT_INSTALLED", changes: [], preserved: [], warnings: [] };
+  const state = read(file);
+  need([1, 2, 3].includes(state.schemaVersion) && Array.isArray(state.files) && typeof state.frameworkVersion === "string", "Invalid install state; refuse unsafe cleanup.");
+  const managed = new Map(), aliases = new Set();
+  for (const item of state.files) {
+    const relative = assertRelativePath(item.relative);
+    need(relative.startsWith(".claude/") && ![".claude/settings.json", ".claude/settings.local.json", statePath].includes(relative), `Unsafe managed path: ${relative}`);
+    need(digest(item.sha256) && (item.canonicalSha256 === undefined || digest(item.canonicalSha256)), `Invalid managed fingerprint: ${relative}`);
+    need(!aliases.has(relative.toLowerCase()), `Duplicate managed path: ${relative}`);
+    aliases.add(relative.toLowerCase()); at(relative); managed.set(relative, item);
+  }
+  const activationPath = at(".nccgs/agent-activation.json");
+  if (fs.existsSync(activationPath)) {
+    const activation = read(activationPath);
+    need(activation.schemaVersion === 1 && object(activation.generated), "Invalid generated-agent inventory.");
+    for (const [relative, hash] of Object.entries(activation.generated)) {
+      need(known.has(relative) && /^\.claude\/agents\/nccgs-[\w-]+\.md$/.test(relative) && digest(hash), `Unsafe generated agent: ${relative}`);
+      at(relative);
+      // Profile/optional-agent configuration can be newer than install-state.
+      const canonicalSha256 = activation.generatedCanonical?.[relative];
+      need(canonicalSha256 === undefined || digest(canonicalSha256), `Invalid generated-agent fingerprint: ${relative}`);
+      managed.set(relative, { sha256: hash, ...(canonicalSha256 ? { canonicalSha256 } : {}) });
+    }
+  }
+  const changes = [], preserved = [], warnings = [];
+  const change = (relative, after) => {
+    const current = fs.readFileSync(at(relative));
+    if (after !== null && current.equals(after)) return;
+    changes.push({ path: relative, before: sha256(current), after: after === null ? null : sha256(after), bytes: current, output: after });
+  };
+  for (const [relative, fingerprint] of managed) {
+    if (!fs.existsSync(at(relative))) continue;
+    need(fs.statSync(at(relative)).isFile(), `Managed target is not a file: ${relative}`);
+    if (!known.has(relative)) { preserved.push({ path: relative, reason: "Not in this package's trusted file catalog" }); continue; }
+    if (!matchesFingerprint(at(relative), fingerprint)) { preserved.push({ path: relative, reason: "Locally modified or pre-existing override" }); continue; }
+    change(relative, null);
+  }
+  if (fs.existsSync(at(".claude/settings.json"))) change(".claude/settings.json", Buffer.from(removeHooks(fs.readFileSync(at(".claude/settings.json"), "utf8"))));
+  if (fs.existsSync(at("CLAUDE.md"))) change("CLAUDE.md", removeImport(fs.readFileSync(at("CLAUDE.md"))));
+  // Removing this marker last makes repeated uninstall a no-op and stops run.
+  change(statePath, null);
+  warnings.push("Project .nccgs history, budgets, policy, backups and generic Claude permission/model settings are retained.");
+  if (preserved.length) warnings.push("Modified/unknown managed files remain in place; inspect the preserved list before removing them manually.");
+  return { project, status: "PLANNED", frameworkVersion: state.frameworkVersion, changes, preserved, warnings };
+}
+
+function manifestPath(id) {
+  need(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id), "Rollback requires the printed uninstall UUID.");
+  return `.nccgs/uninstall/${id}/manifest.json`;
+}
+
+function writeManifest(project, relative, value) {
+  const temporary = `${relative}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(containedPath(project, temporary), JSON.stringify(value, null, 2) + "\n", { flag: "wx" });
+  fs.renameSync(containedPath(project, temporary), containedPath(project, relative));
+}
+
+export function restoreUninstall(project, id, { dryRun = false, ownToken = null } = {}) {
+  project = assertProjectRoot(project); assertUninstallIdle(project, ownToken);
+  const relative = manifestPath(id), manifest = read(containedPath(project, relative));
+  need(manifest.schemaVersion === 1 && manifest.kind === "nccgs-uninstall" && manifest.id === id
+    && ["prepared", "applying", "completed", "restoring", "failed"].includes(manifest.status) && Array.isArray(manifest.files), "Invalid or already restored uninstall receipt.");
+  const known = catalog(), aliases = new Set(), restores = [];
+  for (const item of manifest.files) {
+    assertRelativePath(item.path);
+    need(known.has(item.path) || [statePath, "CLAUDE.md", ".claude/settings.json"].includes(item.path), `Unsafe rollback path: ${item.path}`);
+    need(!aliases.has(item.path.toLowerCase()) && digest(item.before) && (item.after === null || digest(item.after)), "Invalid rollback record.");
+    aliases.add(item.path.toLowerCase());
+    const destination = containedPath(project, item.path), backup = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
+    const bytes = fs.readFileSync(backup); need(sha256(bytes) === item.before, `Changed rollback backup: ${item.path}`);
+    const current = fs.existsSync(destination) ? sha256(fs.readFileSync(destination)) : null;
+    need(current === item.before || current === item.after, `File changed after uninstall; refusing to overwrite: ${item.path}`);
+    if (current !== item.before) restores.push({ ...item, bytes });
+  }
+  if (dryRun) return { status: "ROLLBACK_PREVIEW", id, restoredFiles: restores.map(x => x.path) };
+  manifest.status = "restoring"; writeManifest(project, relative, manifest);
+  for (const item of restores) {
+    const file = containedPath(project, item.path), current = fs.existsSync(file) ? sha256(fs.readFileSync(file)) : null;
+    need(current === item.after, `Concurrent change during rollback: ${item.path}`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(containedPath(project, item.path), item.bytes, { flag: item.after === null ? "wx" : "w" });
+  }
+  manifest.status = "restored"; manifest.restoredAt = new Date().toISOString(); writeManifest(project, relative, manifest);
+  return { status: "RESTORED", id, restoredFiles: restores.map(x => x.path) };
+}
+
+export function uninstall(project, { dryRun = false, rollback = null } = {}) {
+  project = assertProjectRoot(project);
+  need(fs.realpathSync(project) !== fs.realpathSync(root), "The NCCGS package cannot uninstall itself.");
+  if (!rollback) assertInstallationAvailable(project);
+  if (dryRun) return rollback ? restoreUninstall(project, rollback, { dryRun: true }) : summary(planUninstall(project));
+  assertUninstallIdle(project);
+  if (!rollback && !fs.existsSync(containedPath(project, statePath))) return summary(planUninstall(project));
+  const lock = acquireLock(containedPath(project, lockPath), { operation: "uninstall" });
+  try {
+    if (rollback) return restoreUninstall(project, rollback, { ownToken: lock.record.token });
+    // Planning is read-only, with our own lock explicitly recognized.
+    const plan = planUninstall(project, lock.record.token);
+    const id = crypto.randomUUID(), relative = manifestPath(id), directory = path.dirname(containedPath(project, relative));
+    for (const item of plan.changes) {
+      const file = containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(containedPath(project, `.nccgs/uninstall/${id}/files/${item.path}`), item.bytes, { flag: "wx" });
+    }
+    fs.mkdirSync(directory, { recursive: true });
+    const manifest = { schemaVersion: 1, kind: "nccgs-uninstall", id, frameworkVersion: plan.frameworkVersion,
+      createdAt: new Date().toISOString(), status: "prepared", files: plan.changes.map(({ path, before, after }) => ({ path, before, after })),
+      preserved: plan.preserved, warnings: plan.warnings };
+    writeManifest(project, relative, manifest);
+    let mutationStarted = false;
+    try {
+      assertUninstallIdle(project, lock.record.token);
+      for (const item of plan.changes) need(sha256(fs.readFileSync(containedPath(project, item.path))) === item.before, `Concurrent change before uninstall: ${item.path}`);
+      manifest.status = "applying"; writeManifest(project, relative, manifest);
+      for (const item of plan.changes) {
+        const file = containedPath(project, item.path);
+        need(sha256(fs.readFileSync(file)) === item.before, `Concurrent change during uninstall: ${item.path}`);
+        mutationStarted = true;
+        if (item.output === null) fs.unlinkSync(containedPath(project, item.path));
+        else fs.writeFileSync(containedPath(project, item.path), item.output);
+      }
+      manifest.status = "completed"; manifest.completedAt = new Date().toISOString(); writeManifest(project, relative, manifest);
+    } catch (error) {
+      if (!mutationStarted) {
+        manifest.status = "cancelled"; manifest.error = error.message; manifest.cancelledAt = new Date().toISOString();
+        writeManifest(project, relative, manifest);
+        throw new Error(`${error.message}; uninstall cancelled before changing files; receipt ${relative}`);
+      }
+      manifest.status = "failed"; manifest.error = error.message; writeManifest(project, relative, manifest);
+      try { restoreUninstall(project, id, { ownToken: lock.record.token }); }
+      catch (restoreError) { throw new Error(`${error.message}; backup ${relative}; recovery requires inspection: ${restoreError.message}`); }
+      throw new Error(`${error.message}; all planned files restored from ${relative}`);
+    }
+    // Only empty directories derived from individually checked managed paths.
+    const directories = new Set();
+    for (const item of plan.changes.filter(x => x.output === null && x.path.startsWith(".claude/"))) {
+      let dir = path.posix.dirname(item.path);
+      while (dir.startsWith(".claude/")) { directories.add(dir); dir = path.posix.dirname(dir); }
+    }
+    const cleanupWarnings = [];
+    for (const dir of [...directories].sort((a, b) => b.length - a.length)) {
+      try { fs.rmdirSync(containedPath(project, dir)); }
+      catch (error) {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code))
+          cleanupWarnings.push(`Empty-directory cleanup skipped for ${dir}: ${error.code || error.message}`);
+      }
+    }
+    return { ...summary(plan), warnings: [...plan.warnings, ...cleanupWarnings], status: plan.preserved.length ? "UNINSTALLED_WITH_PRESERVED_FILES" : "UNINSTALLED", id, backup: relative };
+  } finally { lock.release(); }
+}
+
+function summary(plan) {
+  return { project: plan.project, status: plan.status, frameworkVersion: plan.frameworkVersion,
+    remove: plan.changes.filter(x => x.after === null).map(x => x.path),
+    edit: plan.changes.filter(x => x.after !== null).map(x => x.path), preserved: plan.preserved, warnings: plan.warnings };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    let project = process.cwd(), dryRun = false, rollback = null;
+    const args = process.argv.slice(2), seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i]; need(!seen.has(arg), `Duplicate option: ${arg}`); seen.add(arg);
+      if (arg === "--dry-run") dryRun = true;
+      else if (["--project", "--rollback"].includes(arg)) {
+        const value = args[++i]; need(value && !value.startsWith("--"), `${arg} requires a value`);
+        if (arg === "--project") project = path.resolve(value); else rollback = value;
+      } else throw new Error(`Unknown uninstall option: ${arg}`);
+    }
+    console.log(JSON.stringify(uninstall(project, { dryRun, rollback }), null, 2));
+  } catch (error) { console.error(`NCCGS uninstall refused: ${error.message}`); process.exitCode = 1; }
+}

package/scripts/validate.mjs

@@ -50,7 +50,11 @@ for (const relative of [
   ".claude/nccgs/pipeline.json", ".claude/nccgs/protocols/task-gates.md",
   ".claude/nccgs/protocols/design-lifecycle.md", ".claude/nccgs/tools/design-readiness.mjs", "scaffold/.nccgs/templates/design-contract.json",
   ".claude/nccgs/tools/task.mjs", ".claude/nccgs/tools/gates.mjs", ".claude/nccgs/tools/runtime.mjs",
+  ".claude/nccgs/tools/handoff.mjs", "docs/HANDOFF-AUTOMATION.md",
+  ".claude/nccgs/tools/task-slices.mjs", ".claude/nccgs/protocols/task-slices.md",
+  "scaffold/.nccgs/templates/task-slices.json", "docs/TASK-SLICING.md", "tests/task-slices.test.mjs",
   ".claude/nccgs/tools/repair-packet.mjs", ".claude/nccgs/protocols/bounded-repair.md", "scaffold/.nccgs/templates/repair-packet.json", "docs/BOUNDED-REPAIR.md",
+  ".claude/nccgs/tools/unity-repair.mjs", "scaffold/.nccgs/templates/repair-unity-code.json", "scaffold/.nccgs/templates/repair-unity-editor.json",
   "scaffold/.nccgs/gates.json", "scaffold/.nccgs/execution.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",
@@ -62,6 +66,8 @@ for (const relative of [
   "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/uninstall.mjs", ".claude/nccgs/tools/installation-guard.mjs", "tests/uninstall.test.mjs", "docs/UNINSTALL.md",
+  "scripts/recover-session.mjs",
   "scripts/sync-unity-skills.mjs", "tests/framework.test.mjs",
   ".claude/nccgs/tools/integrity.mjs", ".claude/nccgs/tools/approve-overrides.mjs"
 ]) requireFile(relative);

package/scripts/work-handoff.mjs

@@ -0,0 +1,38 @@
+import { check, record, taskPath } from "../.claude/nccgs/tools/gates.mjs";
+import { json } from "../.claude/nccgs/tools/policy.mjs";
+import { assessCriteria } from "../.claude/nccgs/tools/criteria.mjs";
+import { status } from "../.claude/nccgs/tools/orchestration.mjs";
+import { listJobs, readJob } from "../.claude/nccgs/tools/verification-jobs.mjs";
+
+// Settle only an already recorded implementation. This is deterministic supervisor
+// bookkeeping, never a provider/reviewer verdict or permission to close the task.
+export function settleWorkHandoff(project, state, latestReceiptAt = 0) {
+  if (!state.budgetAllocation || state.budgetPhase !== "work" || state.costCoverage !== "complete") return null;
+  const last = state.invocations.at(-1);
+  if (!last || !["finished", "recovered"].includes(last.status) || last.terminal?.is_error ||
+      (last.code != null && last.code !== 0) || last.signal) return null;
+  const task = json(taskPath(project, state.taskId));
+  if (task.mode !== "implement" || task.closed || task.contractHash !== state.contractHash) return null;
+  if (Date.parse(task.stages.report?.recordedAt) >= Date.parse(state.createdAt)) return null;
+  if (!(Date.parse(task.stages.implementation?.recordedAt) >= Math.max(Date.parse(state.createdAt), latestReceiptAt))) return null;
+  const jobs = listJobs(project, task.id);
+  if (jobs.some(j => !["PASS", "FAIL"].includes(j.status)) || status(project, task.id).active.length) return null;
+  // A later failure cannot be hidden by re-recording an older PASS, even for a
+  // legacy check-only contract without measured acceptance assertions.
+  const byName = new Map();
+  for (const job of jobs) {
+    const queuedAt = Date.parse(readJob(project, job.jobId).queuedAt), previous = byName.get(job.name);
+    if (!Number.isFinite(queuedAt) || previous?.queuedAt === queuedAt) return null;
+    if (!previous || previous.queuedAt < queuedAt) byName.set(job.name, { ...job, queuedAt });
+  }
+  if ([...byName.values()].some(j => j.status !== "PASS")) return null;
+  let ready;
+  try {
+    ready = check(project, task, "review");
+    if (!ready.allowed || !assessCriteria(project, task, ready.snapshot).automaticPassed) return null;
+  } catch { return null; } // Incomplete/stale evidence still follows the bounded continuation path.
+  return record(project, task.id, "report", {
+    outcome: "partial", origin: "supervisor-work-handoff", runId: state.id,
+    summary: "Implementation and current measured checks recorded. Awaiting protected independent delivery review and all remaining acceptance gates. This handoff is deterministic supervisor bookkeeping, not a reviewer verdict."
+  });
+}

package/tests/editor-session-evidence.test.mjs

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { publishEditorSessionEvidence } from "../.claude/nccgs/tools/editor-session-evidence.mjs";
+const hash = bytes => crypto.createHash("sha256").update(bytes).digest("hex");
+function fixture(t) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-editor-evidence-"));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const project = path.join(root, "project"); fs.mkdirSync(project);
+  const identity = { pid: 123, windowsJob: true, groupName: "Local\\NCCGS-12345678-1234-1234-1234-123456789abc" };
+  const values = {
+    start: { at: "2026-01-01T00:00:00Z", project, identity },
+    stop: { identity, state: "dead", forced: false, result: { code: 0, signal: null } },
+    shutdown: { at: "2026-01-01T00:01:00Z", args: ["command", "eval", "UnityEditor.EditorApplication.Exit(0);", "--project-path", project], code: 0, signal: null, identity: { ...identity, pid: 124 }, treeState: "dead" }
+  };
+  const request = { sourceProject: project, id: crypto.randomUUID() };
+  const save = () => { for (const [key, value] of Object.entries(values)) { const f = path.join(root, key + ".json"); fs.writeFileSync(f, JSON.stringify(value)); request[key + "File"] = f; } };
+  save(); return { project, request, values, save, root };
+}
+test("publishes original bytes and hashes under reviewer-readable evidence without task mutation", t => {
+  const f = fixture(t); fs.mkdirSync(path.join(f.project, ".nccgs")); fs.writeFileSync(path.join(f.project, ".nccgs", "task-sentinel"), "original history and budgets");
+  const ref = publishEditorSessionEvidence(f.project, f.request), bytes = fs.readFileSync(path.join(f.project, ref.path)), receipt = JSON.parse(bytes);
+  assert.equal(hash(bytes), ref.sha256); assert.equal(receipt.origin, "external-operator-editor-evidence"); assert.equal(receipt.historicalImport, false);
+  for (const [key, value] of Object.entries(receipt.references)) { const copied = fs.readFileSync(path.join(f.project, value.path)); assert.equal(hash(copied), value.sha256); assert.deepEqual(copied, fs.readFileSync(f.request[key + "File"])); }
+  assert.equal(fs.readFileSync(path.join(f.project, ".nccgs", "task-sentinel"), "utf8"), "original history and budgets");
+  assert.throws(() => publishEditorSessionEvidence(f.project, f.request), /EEXIST/);
+});
+test("separate addendum identifies historical import and preserves the source project", t => {
+  const f = fixture(t), addendum = path.join(f.root, "addendum"); fs.mkdirSync(addendum);
+  const ref = publishEditorSessionEvidence(addendum, f.request), receipt = JSON.parse(fs.readFileSync(path.join(addendum, ref.path)));
+  assert.equal(receipt.historicalImport, true); assert.equal(receipt.sourceProject, f.project); assert.equal(fs.readdirSync(f.project).length, 0);
+});
+for (const [label, mutate] of Object.entries({
+  "mismatched ownership": f => { f.values.stop.identity = { ...f.values.stop.identity, pid: 999 }; },
+  "wrong project": f => { f.values.shutdown.args[4] = path.join(f.root, "other"); },
+  "live process": f => { f.values.stop.state = "alive"; },
+  "unknown process": f => { f.values.shutdown.treeState = "unknown"; },
+  "forced exit": f => { f.values.stop.forced = true; },
+  "failed exit": f => { f.values.stop.result.code = 1; },
+  "missing shutdown method": f => { f.values.shutdown.args[2] = "return 0;"; },
+  "reversed events": f => { f.values.shutdown.at = "2025-01-01T00:00:00Z"; }
+})) test(`rejects ${label} before publishing`, t => { const f = fixture(t); mutate(f); f.save(); assert.throws(() => publishEditorSessionEvidence(f.project, f.request)); assert.equal(fs.readdirSync(f.project).length, 0); });

package/tests/fixtures/compiler-shutdown.cs

@@ -0,0 +1,64 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.IO.Pipes;
+using System.Runtime.InteropServices;
+using System.Threading;
+using System.Threading.Tasks;
+
+// Synthetic IPC guard fixture, not Unity execution evidence.
+public static class CompilerShutdownFixture {
+  [DllImport("kernel32.dll")] static extern IntPtr CreateJobObject(IntPtr attributes,string name);
+  [DllImport("kernel32.dll")] static extern bool AssignProcessToJobObject(IntPtr job,IntPtr process);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  static void Need(bool ok,string message) { if(!ok) throw new Exception(message); }
+  static void Exchange(IntPtr job,IntPtr process,int pid,bool expected,bool answer) {
+    string name="nccgs-compiler-guard-"+Guid.NewGuid().ToString("N");
+    using(var server=new NamedPipeServerStream(name,PipeDirection.InOut,1,PipeTransmissionMode.Byte,PipeOptions.Asynchronous)) {
+      var connected=server.WaitForConnectionAsync();
+      var receive=Task.Run(()=>{
+        connected.GetAwaiter().GetResult();
+        var length=new byte[4]; int count=server.Read(length,0,4);
+        if(count==0) return 0; // Refused peers must receive no request bytes.
+        Need(count==4 && BitConverter.ToInt32(length,0)==117,"bad request frame");
+        int remaining=117; var buffer=new byte[117];
+        while(remaining>0) { int n=server.Read(buffer,117-remaining,remaining); Need(n>0,"truncated request"); remaining-=n; }
+        if(answer) {
+          using(var writer=new BinaryWriter(server,System.Text.Encoding.Unicode,true)) {
+            writer.Write(8); writer.Write(3); writer.Write(Process.GetCurrentProcess().Id); writer.Flush();
+          }
+        } else Thread.Sleep(1500);
+        return 121;
+      });
+      bool accepted=NccgsUnityCompilerShutdown.Request(job,process,pid,name);
+      Need(accepted==expected,"incorrect shutdown acknowledgement");
+      Need(receive.Wait(3000),"pipe fixture failed to settle");
+      if(!expected && answer) Need(receive.Result==0,"foreign/unowned peer received shutdown bytes");
+    }
+  }
+  public static int Main(string[] args) {
+    IntPtr job=CreateJobObject(IntPtr.Zero,null);
+    try {
+      Need(job!=IntPtr.Zero,"job creation failed");
+      var process=Process.GetCurrentProcess();
+      // Golden frame captured from the installed Roslyn 4.3.1 serializer, not a
+      // second implementation of our own encoder.
+      const string golden="75000000000000000000000000000000000000002125534450340031006100350061006600390064003200630034003500390061003000360063003000370039003500620066003200310061003100630030003400360032003000300066003300370035006200660001000000257214510000000000000000";
+      Need(BitConverter.ToString(NccgsUnityCompilerShutdown.ShutdownFrame()).Replace("-","").ToLowerInvariant()==golden,"Roslyn protocol changed");
+      Exchange(job,process.Handle,process.Id,false,true); // Same PID, foreign job.
+      Need(AssignProcessToJobObject(job,process.Handle),"fixture job assignment failed");
+      Exchange(job,process.Handle,process.Id+1000000,false,true); // Wrong pipe server PID.
+      Exchange(job,process.Handle,process.Id,true,true); // Exact owned pipe.
+      Exchange(job,process.Handle,process.Id,false,false); // Missing acknowledgement stays unconfirmed.
+      string data=Path.Combine(args[0],"Editor","Data");
+      string dll=Path.Combine(data,"DotNetSdkRoslyn","VBCSCompiler.dll"),host=Path.Combine(data,"NetCoreRuntime","dotnet.exe");
+      Directory.CreateDirectory(Path.GetDirectoryName(dll)); Directory.CreateDirectory(Path.GetDirectoryName(host));
+      File.WriteAllText(dll,"unqualified binary"); File.WriteAllText(host,"unqualified host");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:safe"})==null,"unqualified binaries accepted");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:../../foreign"})==null,"invalid pipe accepted");
+      Need(NccgsUnityCompilerShutdown.QualifiedPipe(host,new[]{host,"exec",dll,"-pipename:safe","-shutdown"})==null,"unexpected arguments accepted");
+      Console.WriteLine("compiler shutdown guards PASS"); return 0;
+    } catch(Exception error) { Console.Error.WriteLine(error); return 1; }
+    finally { if(job!=IntPtr.Zero) CloseHandle(job); }
+  }
+}

package/tests/orchestration-v15.test.mjs

@@ -11,8 +11,10 @@ import { pinInputs } from "../.claude/nccgs/tools/inputs.mjs";
 import { artifact, atomicJson, hash, json } from "../.claude/nccgs/tools/policy.mjs";
 import { persistRuntimeObservation } from "../.claude/nccgs/tools/evidence.mjs";
 import { observe } from "../.claude/nccgs/tools/runtime.mjs";
-import { validateStandaloneRuntime, initializeStandalone, recordStandalone } from "../.claude/nccgs/tools/lifecycle.mjs";
+import { validateStandaloneRuntime, initializeStandalone, recordStandalone, migrateFrameworkBaseline } from "../.claude/nccgs/tools/lifecycle.mjs";
 import { guardTool } from "../.claude/nccgs/tools/tool-guard.mjs";
+import { acquireLock } from "../.claude/nccgs/tools/process-lock.mjs";
+import { sessionBudgetLock } from "../.claude/nccgs/tools/session-budget.mjs";
 
 // These are synthetic framework fixtures, never Claude Code execution evidence.
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -87,6 +89,55 @@ function external(action) {
 function failRun(f, run) {
   return external(() => reconcile(f.project, run.reservation.id, { status: "failed", reason: "TEST FIXTURE process confirmed terminated", reference: "TEST FIXTURE external process-exit receipt" }));
 }
+test("external framework migration proves the old inventory, rejects game changes and invalidates all approvals without quota refunds", () => {
+  const f = fixture();
+  try {
+    f.write('.nccgs/intake.json', { objective: 'Synthetic plan migration', mode: 'plan', analysisArtifacts: ['.nccgs/evidence/analysis/plan.md'] });
+    const t = initializeStandalone(f.project, 'migration', { intake: '.nccgs/intake.json' });
+    const beforeFiles = snapshot(f.project, t, { includeFiles: true }).fileEntries;
+    const run = f.start('migration'); failRun(f, run);
+    t.reviewBudget.used = 1; t.stages = { analysis: { fixture: true }, report: { outcome: 'partial' } }; f.write('.nccgs/tasks/migration.json', t);
+    const decision = '.nccgs/evidence/migration.json';
+    f.write(decision, { reason: 'Fixture framework patch', authority: 'Synthetic external fixture', beforeFiles });
+    f.write('.claude/nccgs/new-tool.mjs', '// fixture framework update');
+    f.write('Assets/game.cs', '// unauthorized source change');
+    assert.throws(() => external(() => migrateFrameworkBaseline(f.project, 'migration', decision)), /non-framework/);
+    f.write('Assets/game.cs', '// TEST FIXTURE source, not a game implementation\n');
+    process.env.CLAUDECODE = 'fixture';
+    try { assert.throws(() => migrateFrameworkBaseline(f.project, 'migration', decision), /external|External/); } finally { delete process.env.CLAUDECODE; }
+    const result = external(() => migrateFrameworkBaseline(f.project, 'migration', decision));
+    assert.equal(result.contractHash, t.contractHash); assert.equal(result.reviewBudget.used, 1); assert.deepEqual(result.stages, {});
+    assert.deepEqual(result.history.at(-1).stages, t.stages); assert.equal(result.history.at(-1).previousBaseline, t.analysisBaseline);
+    assert.equal(status(f.project, 'migration').usage.dispatches, 1);
+    assert.throws(() => external(() => migrateFrameworkBaseline(f.project, 'migration', decision)), /inventory/);
+  } finally { f.dispose(); }
+});
+test("missing worker cost admits only its live supervised allowance and keeps telemetry/limits/history", () => {
+  const f = fixture(), saved = [process.env.NCCGS_SUPERVISED_RUN, process.env.NCCGS_SUPERVISED_SESSION];
+  let lock;
+  try {
+    f.task("budget");
+    const run = f.start("budget", f.request("analysis", { limits: { maxCostUsd: 3 } }));
+    const observed = f.observation(run); complete(f.project, run.reservation.id, { runtime: observed });
+    assert.throws(() => reserve(f.project, "budget", f.request("analysis")), /missing costUsd/);
+    const id = "12345678-1234-1234-1234-123456789abc", sessionId = run.identity.sessionId;
+    f.write(`.nccgs/runs/${id}/run.json`, { id, project: f.project, taskId: "budget", sessionId, budgetUsd: 3, cumulativeCostUsd: 0,
+      deadline: Date.now() + 60000, status: "running", invocations: [{ status: "running", pid: process.pid }] });
+    lock = acquireLock(path.join(f.project, sessionBudgetLock), { runId: id, sessionId });
+    process.env.NCCGS_SUPERVISED_RUN = id; process.env.NCCGS_SUPERVISED_SESSION = sessionId;
+    const next = reserve(f.project, "budget", f.request("analysis"));
+    assert.equal(next.budgetEvidence[0].ceilingUsd, 3);
+    assert.throws(() => claim(f.project, next.id, { sessionId: "other", toolUseId: "next", agent: next.agent }), /owns its budget/);
+    const current = status(f.project, "budget"); assert.equal(current.usage.dispatches, 2); assert.equal(current.limits.maxCostUsd, 3);
+    assert.equal(current.telemetry.metrics.costUsd.total, null); assert.equal(current.telemetry.metrics.costUsd.measured, 0);
+    lock.release(); lock = null;
+    assert.throws(() => reserve(f.project, "budget", f.request("analysis")), /ENOENT/);
+  } finally {
+    lock?.release();
+    for (const [i,k] of ["NCCGS_SUPERVISED_RUN", "NCCGS_SUPERVISED_SESSION"].entries()) { if(saved[i]===undefined) delete process.env[k]; else process.env[k]=saved[i]; }
+    f.dispose();
+  }
+});
 test("external dispatch extension keeps spent attempts and parent cap, and rejects live or native changes", () => {
   const f = fixture();
   try {