nccgs 2.1.0 → 3.0.0-rc.1

package/bin/nccgs.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// nccgs CLI: install | update | doctor | run | uninstall | mode | task | version | help
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { projectRoot } from "../runtime/core/project.mjs";
+import { PKG, TEMPLATE, install } from "../cli/install.mjs";
+import { doctor } from "../cli/doctor.mjs";
+import { launch } from "../cli/run.mjs";
+import { uninstall } from "../cli/uninstall.mjs";
+import { allModes, createMode, setModeAgent, useMode, BUILTIN } from "../runtime/core/modes.mjs";
+import { renderProject } from "../runtime/task/project.mjs";
+import { release } from "../cli/release.mjs";
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+const sep = argv.indexOf("--");
+const own = sep < 0 ? argv.slice(1) : argv.slice(1, sep);
+const forwarded = sep < 0 ? [] : argv.slice(sep + 1);
+const opt = {}; const positional = [];
+for (let i = 0; i < own.length; i++) {
+  const a = own[i];
+  if (a.startsWith("--")) { const n = own[i + 1]; if (n === undefined || n.startsWith("--")) opt[a.slice(2)] = true; else { opt[a.slice(2)] = n; i++; } }
+  else positional.push(a);
+}
+const root = projectRoot(opt.project === true ? undefined : opt.project);
+const out = v => process.stdout.write(JSON.stringify(v, null, 2) + "\n");
+const die = m => { process.stderr.write(`nccgs ${command}: ${m}\n`); process.exit(1); };
+
+const HELP = `nccgs ${PKG.version} - Unity-first evidence loop for Claude Code
+
+  nccgs install   --project DIR [--mode BALANCE] [--rigor production] [--autonomy guarded] [--dry-run]
+  nccgs update    --project DIR [--dry-run] [--force] [--skills-only]
+  nccgs doctor    --project DIR [--check-models] [--check-updates]
+  nccgs run       --project DIR [--mode M] [--autonomy guarded|full] [--dry-run] [-- claude args]
+  nccgs uninstall --project DIR [--dry-run] [--force]
+  nccgs mode      list | show NAME | create --from BALANCE --name X | set --name X --agent reviewer --model opus --effort high | use NAME
+  nccgs task      <open|verify|review|close|inspect|list|fix|report|project> ...   (same as node .claude/nccgs/runtime/task/task.mjs)
+  nccgs status    --project DIR                 writes .nccgs/project.html (all tasks, open findings, cost) and prints the summary
+  nccgs release   --project DIR [--from TAG|DATE] [--to TAG|DATE|now] [--name v1.2.0]   changelog from tasks closed in the range
+`;
+
+try {
+  switch (command) {
+    case undefined: case "help": case "--help": case "-h": process.stdout.write(HELP); break;
+    case "version": case "--version": case "-v": process.stdout.write(PKG.version + "\n"); break;
+    case "install": out(install(root, { dryRun: !!opt["dry-run"], force: !!opt.force, mode: str(opt.mode), autonomy: str(opt.autonomy), rigor: str(opt.rigor) })); break;
+    case "update": out(install(root, { update: true, dryRun: !!opt["dry-run"], force: !!opt.force, skillsOnly: !!opt["skills-only"] })); break;
+    case "doctor": {
+      const r = await doctor(root, { checkModels: !!opt["check-models"], checkUpdatesNow: !!opt["check-updates"] });
+      for (const c of r.checks) process.stderr.write(`${c.status.toUpperCase().padEnd(4)} ${c.id.padEnd(20)} ${c.message}\n`);
+      if (r.summary) process.stderr.write(`\n${r.summary.pass} pass · ${r.summary.warn} warn · ${r.summary.fail} fail\n`);
+      if (opt.json) out(r);
+      process.exit(r.summary?.fail ? 1 : 0);
+    }
+    case "run": { const r = await launch(root, { mode: str(opt.mode), autonomy: str(opt.autonomy), dryRun: !!opt["dry-run"], forwarded }); if (opt["dry-run"]) out(r); process.exit(r.exitCode ?? 0); }
+    case "uninstall": out(uninstall(root, { dryRun: !!opt["dry-run"], force: !!opt.force })); break;
+    case "status": {
+      const r = renderProject(root);
+      const m = r.model;
+      process.stderr.write(`${m.project.name} · ${m.success.length}/${m.closed.length} closed SUCCESS · ${m.open.length} open · findings H ${m.bySeverity.BLOCKER + m.bySeverity.HIGH} / M ${m.bySeverity.MEDIUM} / L ${m.bySeverity.LOW}\n${r.file}\n`);
+      if (opt.json) out({ file: r.file, closed: m.closed.length, success: m.success.length, open: m.open.map(x => x.task.id), findings: m.bySeverity, tokens: m.tokens });
+      break;
+    }
+    case "release": { const r = release(root, { from: str(opt.from), to: str(opt.to) ?? "now", name: str(opt.name), write: !opt["dry-run"] }); process.stdout.write(r.markdown); if (r.file) process.stderr.write(`\n${r.file}\n`); break; }
+    case "mode": {
+      const sub = positional[0];
+      if (!sub || sub === "list") { const modes = allModes(root); out(Object.fromEntries(Object.entries(modes).map(([k, v]) => [k, { description: v.description, custom: !!v.custom, ...Object.fromEntries(BUILTIN.agents.map(a => [a, v[a] ? `${v[a].model}/${v[a].effort ?? "-"}` : "-"])) }]))); }
+      else if (sub === "show") out(allModes(root)[positional[1] ?? str(opt.name)] ?? die("mode not found"));
+      else if (sub === "create") out(createMode(root, { name: str(opt.name) ?? positional[1], from: str(opt.from) ?? "BALANCE" }));
+      else if (sub === "set") out(setModeAgent(root, { name: str(opt.name), agent: str(opt.agent), model: str(opt.model), effort: opt.effort === undefined ? undefined : str(opt.effort), fallback: opt.fallback === undefined ? undefined : (opt.fallback === "none" ? "none" : { model: str(opt.fallback), effort: str(opt["fallback-effort"]) ?? "high" }) }));
+      else if (sub === "use") out(useMode(root, positional[1] ?? str(opt.name), { templateDir: TEMPLATE }));
+      else die(`unknown mode subcommand ${sub}`);
+      break;
+    }
+    case "task": {
+      const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "runtime", "task", "task.mjs");
+      const child = spawn(process.execPath, [script, ...argv.slice(1), ...(opt.project ? [] : ["--project", root])], { stdio: "inherit" });
+      child.on("close", code => process.exit(code ?? 1));
+      break;
+    }
+    default: die(`unknown command ${command}\n${HELP}`);
+  }
+} catch (error) { die(error.message); }
+
+function str(v) { return v === undefined || v === true ? undefined : String(v); }

package/cli/doctor.mjs

@@ -0,0 +1,82 @@
+// nccgs doctor: facts about this machine and project, with pass | warn | fail per check.
+import path from "node:path";
+import { spawnToolSync } from "./spawn.mjs";
+import { readJson as readJsonFile } from "../runtime/core/fs.mjs";
+import path2 from "node:path";
+import { TEMPLATE } from "./install.mjs";
+import { readJson, exists, sha256File } from "../runtime/core/fs.mjs";
+import { at, isUnityProject, loadConfig, editorVersion, pipelineVersion, versionLine } from "../runtime/core/project.mjs";
+import { allModes, BUILTIN, validateAgentSetting } from "../runtime/core/modes.mjs";
+import * as unity from "../runtime/unity/unity.mjs";
+import { PKG } from "./install.mjs";
+import { checkUpdates } from "./update-check.mjs";
+import { available as jobObjectAvailable } from "../runtime/core/job-object.mjs";
+
+const MIN_CLAUDE = [2, 1, 295];
+const cmp = (a, b) => { for (let i = 0; i < 3; i++) { if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) - (b[i] ?? 0); } return 0; };
+const ver = s => (String(s).match(/(\d+)\.(\d+)\.(\d+)/) ?? []).slice(1, 4).map(Number);
+
+export async function doctor(root, { checkModels = false, checkUpdatesNow = false } = {}) {
+  const checks = [];
+  const add = (id, status, message, data) => checks.push({ id, status, message, ...(data ? { data } : {}) });
+  add("node", cmp(ver(process.version), [20, 0, 0]) >= 0 ? "pass" : "fail", `Node ${process.version} (needs >= 20)`);
+  if (process.platform === "win32") { const jo = await jobObjectAvailable(); add("process-tree", jo ? "pass" : "warn", jo ? "Windows Job Object available (koffi): timed-out Editors die with their whole tree" : "koffi not installed: falling back to taskkill /T + ppid walk (run `npm install` in the nccgs package, or `npx nccgs` installs it)"); }
+  else add("process-tree", "pass", `${process.platform}: process group + NCCGS_TREE tag + ppid walk`);
+  const claude = spawnToolSync("claude", ["--version"], { encoding: "utf8", windowsHide: true, timeout: 15000 });
+  const claudeVersion = claude.status === 0 ? claude.stdout.trim() : null;
+  add("claude", claudeVersion ? (cmp(ver(claudeVersion), MIN_CLAUDE) >= 0 ? "pass" : "warn") : "fail", claudeVersion ? `Claude Code ${claudeVersion}` : "claude not on PATH");
+  const cliVersion = await unity.cliVersion();
+  add("unity-cli", cliVersion ? "pass" : "fail", cliVersion ? `Unity CLI ${cliVersion}` : "unity CLI not on PATH (install: https://unity.com/en/blog/meet-the-unity-cli)");
+  if (!isUnityProject(root)) { add("project", "fail", `${root} is not a Unity project`); return { root, checks }; }
+  add("project", "pass", versionLine(root, cliVersion));
+  add("pipeline-package", pipelineVersion(root) ? "pass" : "fail", pipelineVersion(root) ? `com.unity.pipeline ${pipelineVersion(root)}` : "com.unity.pipeline missing: run `unity pipeline install --project-path <project>` in Unity 6.0+");
+  const state = exists(at(root, "installState")) ? readJson(at(root, "installState")) : null;
+  add("installed", state ? (state.version === PKG.version ? "pass" : "warn") : "fail", state ? `NCCGS ${state.version} installed${state.version !== PKG.version ? ` (package is ${PKG.version}: run update)` : ""}` : "NCCGS not installed");
+  if (state) {
+    const drift = [];
+    for (const [rel, sha] of Object.entries(state.files ?? {})) { const f = path.join(root, rel); if (!exists(f)) drift.push(`missing ${rel}`); else if (sha256File(f) !== sha) drift.push(`changed ${rel}`); }
+    add("inventory", drift.length ? "warn" : "pass", drift.length ? `${drift.length} managed file(s) differ: ${drift.slice(0, 5).join(", ")}${drift.length > 5 ? "…" : ""}` : "managed files match the inventory", { drift, overrides: state.overrides });
+  }
+  const settings = exists(at(root, "settings")) ? readJson(at(root, "settings")) : {};
+  const hookCount = Object.values(settings.hooks ?? {}).flat().filter(e => (e.hooks ?? []).some(h => (h.args ?? []).some(a => String(a).includes("/.claude/nccgs/runtime/hooks/")))).length;
+  const expectedHooks = Object.values(readJsonFile(path2.join(TEMPLATE, "settings.fragment.json")).hooks).flat().length;
+  add("hooks", hookCount >= expectedHooks ? "pass" : "fail", `${hookCount}/${expectedHooks} NCCGS hook entries in .claude/settings.json`);
+  const config = loadConfig(root);
+  const modes = allModes(root);
+  if (!modes[config.mode]) add("mode", "fail", `mode ${config.mode} not found`);
+  else {
+    const warnings = BUILTIN.agents.flatMap(a => modes[config.mode][a] ? validateAgentSetting(modes[config.mode][a]).map(w => `${a}: ${w}`) : []);
+    add("mode", "pass", `mode ${config.mode}${modes[config.mode].custom ? " (custom)" : ""} · rigor ${config.rigor} · autonomy ${config.autonomy}`, warnings.length ? { warnings } : undefined);
+  }
+  for (const agent of BUILTIN.agents.filter(a => a !== "coordinator")) {
+    if (!exists(path.join(at(root, "agents"), `nccgs-${agent}.md`))) add(`agent-${agent}`, "fail", `.claude/agents/nccgs-${agent}.md missing (run \`nccgs mode use ${config.mode}\`)`);
+  }
+  const instance = cliVersion ? await unity.instanceFor(root) : null;
+  add("editor", instance ? (instance.state === "ready" ? "pass" : "warn") : "warn", instance ? `Editor ${instance.editorVersion ?? instance.version} ${instance.state} on port ${instance.port} (live verify available)` : "no Editor open for this project (verify will use a batch Editor; open the project for screenshots)");
+  if (instance?.state === "ready") {
+    const cat = await unity.catalog(root, { refresh: true });
+    add("pipeline-commands", cat.commands.length ? "pass" : "fail", cat.commands.length ? `${cat.commands.length} Pipeline commands discovered (package ${cat.version})` : `cannot list Pipeline commands: ${cat.error}`);
+    for (const cap of ["playStart", "screenshot", "consoleGet", "testRun", "eval"]) {
+      const name = await unity.resolve(root, cap);
+      if (!name) add(`capability-${cap}`, "fail", `no Pipeline command for ${cap}`);
+    }
+  }
+  const skillsManifest = exists(path.join(root, ".claude/nccgs/unity-skills-manifest.json")) ? readJson(path.join(root, ".claude/nccgs/unity-skills-manifest.json")) : null;
+  if (skillsManifest) {
+    const age = Math.floor((Date.now() - Date.parse(skillsManifest.synced_at)) / 86400000);
+    add("unity-skills", age > 60 ? "warn" : "pass", `${skillsManifest.skills.length} vendored Unity skills, synced ${age} days ago (${skillsManifest.source_revision})`);
+  }
+  if (checkModels && claudeVersion) {
+    const mode = modes[config.mode];
+    for (const agent of ["reviewer", "implementer"]) {
+      const m = mode?.[agent]?.model; if (!m || m === "inherit") continue;
+      const probe = spawnToolSync("claude", ["-p", "Reply with OK", "--model", m, "--max-turns", "1", "--output-format", "text"], { encoding: "utf8", windowsHide: true, timeout: 90000 });
+      add(`model-${agent}`, probe.status === 0 ? "pass" : "warn", probe.status === 0 ? `${agent}: ${m} answered` : `${agent}: ${m} not available on this account (${(probe.stderr || probe.stdout).trim().slice(0, 120)})`);
+    }
+  }
+  if (checkUpdatesNow) {
+    const u = await checkUpdates(root, { force: true, cliVersion });
+    add("updates", u.notices.length ? "warn" : "pass", u.notices.length ? u.notices.map(n => `${n.component} ${n.current} -> ${n.latest}`).join("; ") : "everything current (or unreachable)", u);
+  }
+  return { root, version: PKG.version, checks, summary: { pass: checks.filter(c => c.status === "pass").length, warn: checks.filter(c => c.status === "warn").length, fail: checks.filter(c => c.status === "fail").length } };
+}

package/cli/install.mjs

@@ -0,0 +1,111 @@
+// nccgs install | update: copy the managed files into a Unity project, merge settings, scaffold .nccgs.
+// Managed files are inventoried with hashes; a file the user changed is never overwritten (recorded as an override).
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readJson, writeJson, writeText, readText, exists, sha256File, walk, toPosix, nowIso } from "../runtime/core/fs.mjs";
+import { at, LAYOUT, isUnityProject, loadConfig, saveConfig, ensureLayout, DEFAULT_CONFIG, editorVersion } from "../runtime/core/project.mjs";
+import { renderAgents } from "../runtime/core/modes.mjs";
+
+export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const PKG = readJson(path.join(PKG_ROOT, "package.json"));
+export const TEMPLATE = path.join(PKG_ROOT, "template");
+
+// Managed set: (packageRelative -> projectRelative)
+function managedFiles() {
+  const list = [];
+  const add = (fromDir, toDir, filter = () => true) => {
+    for (const file of walk(fromDir)) {
+      const rel = toPosix(path.relative(fromDir, file));
+      if (filter(rel)) list.push({ from: file, to: path.posix.join(toDir, rel) });
+    }
+  };
+  add(path.join(PKG_ROOT, "runtime"), ".claude/nccgs/runtime");
+  add(path.join(TEMPLATE, "skills"), ".claude/skills");
+  add(path.join(TEMPLATE, "protocols"), ".claude/nccgs/protocols");
+  add(path.join(TEMPLATE, "ponytail"), ".claude/nccgs/ponytail");
+  add(path.join(PKG_ROOT, "unity-skills"), ".claude/skills", rel => rel !== "manifest.json");
+  list.push({ from: path.join(PKG_ROOT, "unity-skills", "manifest.json"), to: ".claude/nccgs/unity-skills-manifest.json" });
+  list.push({ from: path.join(TEMPLATE, "CLAUDE.md"), to: "CLAUDE.md", keepIfExists: true });
+  return list;
+}
+
+export function install(root, { update = false, force = false, dryRun = false, mode, autonomy, rigor, skillsOnly = false } = {}) {
+  if (!isUnityProject(root)) throw new Error(`${root} is not a Unity project (needs Assets/ and ProjectSettings/ProjectVersion.txt)`);
+  const stateFile = at(root, "installState");
+  const previous = exists(stateFile) ? readJson(stateFile) : null;
+  if (update && !previous) throw new Error("NCCGS is not installed here; use `install`");
+  if (!update && previous && !force) throw new Error(`NCCGS ${previous.version} is already installed; use \`update\``);
+  const actions = [];            // { action: add|replace|keep|override|skip, path }
+  const inventory = {};
+  for (const item of managedFiles()) {
+    if (skillsOnly && !item.to.startsWith(".claude/skills/") && !item.to.endsWith("unity-skills-manifest.json")) continue;
+    const target = path.join(root, item.to);
+    const incoming = sha256File(item.from);
+    const existsNow = exists(target);
+    const current = existsNow ? sha256File(target) : null;
+    const recorded = previous?.files?.[item.to] ?? null;
+    let action;
+    if (!existsNow) action = "add";
+    else if (current === incoming) action = "keep";
+    else if (item.keepIfExists && !recorded) action = "keep-user";          // e.g. the user's own CLAUDE.md
+    else if (recorded && current === recorded) action = "replace";          // unchanged managed file, new version
+    else if (force) action = "replace-forced";
+    else action = "override";                                               // user changed it: keep theirs, record it
+    actions.push({ action, path: item.to });
+    inventory[item.to] = ["add", "replace", "replace-forced", "keep"].includes(action) ? incoming : (current ?? incoming);
+    if (!dryRun && ["add", "replace", "replace-forced"].includes(action)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(item.from, target);
+    }
+  }
+  // Scaffold .nccgs (never overwritten), config, modes.
+  if (!dryRun && !skillsOnly) {
+    ensureLayout(root);
+    const config = exists(at(root, "config")) ? loadConfig(root) : structuredClone(DEFAULT_CONFIG);
+    if (!config.name) config.name = path.basename(root);
+    if (mode) config.mode = mode;
+    if (autonomy) config.autonomy = autonomy;
+    if (rigor) config.rigor = rigor;
+    saveConfig(root, config);
+    if (!exists(at(root, "state"))) writeText(at(root, "state"), "# Project state\n\nMaintained by `task close`. Newest first.\n\n");
+    const gi = path.join(root, ".nccgs", ".gitignore");
+    if (!exists(gi)) writeText(gi, "evidence/screens/\nevidence/measurements/\ncache/\nevents.jsonl\n");
+    renderAgents(root, config.mode, { templateDir: TEMPLATE });
+    mergeSettings(root);
+  }
+  const overrides = actions.filter(a => a.action === "override").map(a => a.path);
+  if (!dryRun) {
+    writeJson(stateFile, { schemaVersion: 3, version: PKG.version, installedAt: previous?.installedAt ?? nowIso(), updatedAt: nowIso(), editor: editorVersion(root), files: inventory, overrides });
+  }
+  return { version: PKG.version, dryRun, counts: count(actions), overrides, actions: dryRun ? actions.filter(a => a.action !== "keep") : undefined };
+}
+
+function count(actions) { return actions.reduce((acc, a) => { acc[a.action] = (acc[a.action] ?? 0) + 1; return acc; }, {}); }
+
+// Merge our hooks and deny rules into .claude/settings.json without touching anything else.
+export function mergeSettings(root) {
+  const fragment = readJson(path.join(TEMPLATE, "settings.fragment.json"));
+  const file = at(root, "settings");
+  const settings = exists(file) ? readJson(file) : {};
+  settings.permissions ??= {};
+  settings.permissions.deny = [...new Set([...(settings.permissions.deny ?? []), ...fragment.permissions.deny])];
+  settings.hooks ??= {};
+  for (const [event, entries] of Object.entries(fragment.hooks)) {
+    const existing = (settings.hooks[event] ?? []).filter(e => !isOurs(e));
+    settings.hooks[event] = [...existing, ...entries];
+  }
+  writeJson(file, settings);
+}
+export function removeSettings(root) {
+  const file = at(root, "settings");
+  if (!exists(file)) return;
+  const settings = readJson(file);
+  for (const [event, entries] of Object.entries(settings.hooks ?? {})) {
+    settings.hooks[event] = entries.filter(e => !isOurs(e));
+    if (!settings.hooks[event].length) delete settings.hooks[event];
+  }
+  if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
+  writeJson(file, settings);
+}
+const isOurs = entry => (entry.hooks ?? []).some(h => (h.args ?? []).some(a => String(a).includes("/.claude/nccgs/runtime/hooks/")) || String(h.command ?? "").includes(".claude/nccgs/runtime/hooks/"));

package/cli/release.mjs

@@ -0,0 +1,59 @@
+// nccgs release: a changelog section from the tasks closed between two points in time.
+// Points are git refs (tags, commits; dates come from `git log -1 --format=%cI`) or ISO dates.
+// Output: Markdown grouped by outcome, each task with its criteria score, tests, review and report link.
+import path from "node:path";
+import { spawnToolSync } from "./spawn.mjs";
+import { writeText, toPosix } from "../runtime/core/fs.mjs";
+import { at, loadConfig } from "../runtime/core/project.mjs";
+import { listTasks } from "../runtime/task/ledger.mjs";
+import { reportModel } from "../runtime/task/report.mjs";
+import { fmtTokens } from "../runtime/task/cost.mjs";
+
+function refDate(root, ref) {
+  if (!ref || ref === "now") return Date.now();
+  if (/^\d{4}-\d{2}-\d{2}/.test(ref)) return Date.parse(ref);
+  const r = spawnToolSync("git", ["log", "-1", "--format=%cI", ref], { cwd: root, encoding: "utf8", windowsHide: true, timeout: 15000 });
+  if (r.status !== 0 || !r.stdout.trim()) throw new Error(`cannot resolve ${ref} to a date: not an ISO date and git says "${(r.stderr || "").trim().slice(0, 120)}"`);
+  return Date.parse(r.stdout.trim());
+}
+
+export function release(root, { from, to = "now", name, write = true } = {}) {
+  const fromMs = from ? refDate(root, from) : 0;
+  const toMs = refDate(root, to);
+  if (!(toMs > fromMs)) throw new Error("`to` must be after `from`");
+  const config = loadConfig(root);
+  const lang = config.report?.language === "vi" ? "vi" : "en";
+  const t = lang === "vi" ? VI : EN;
+  const tasks = listTasks(root).filter(x => x.status === "closed" && Date.parse(x.closedAt) > fromMs && Date.parse(x.closedAt) <= toMs).sort((a, b) => a.closedAt < b.closedAt ? -1 : 1);
+  const models = tasks.map(task => reportModel(root, task));
+  const label = name ?? (to === "now" ? new Date(toMs).toISOString().slice(0, 10) : to);
+  const lines = [`## ${label}${from ? ` (${t.since} ${from})` : ""}`, ""];
+  const groups = [["success", t.shipped], ["partial", t.partial], ["blocked", t.blocked], ["failed", t.failed]];
+  let any = false;
+  for (const [outcome, title] of groups) {
+    const g = models.filter(m => m.task.outcome === outcome);
+    if (!g.length) continue;
+    any = true;
+    lines.push(`### ${title}`, "");
+    for (const m of g) {
+      const rel = toPosix(path.relative(root, path.join(at(root, "reports"), `${m.task.id}.md`)));
+      const bits = [`${t.criteriaShort} ${m.evaluation.summary.pass}/${m.evaluation.summary.total}`];
+      if (m.tests) bits.push(`${t.testsShort} ${m.tests.passed}/${m.tests.total}`);
+      if (m.review) bits.push(`${t.reviewShort} ${m.review.verdict}${m.review.model ? ` (${m.review.model})` : ""}`);
+      if (m.cost?.total?.messages) bits.push(`${fmtTokens(m.cost.total.output)} ${t.tokensOut}`);
+      const open = m.findings.filter(f => !f.resolved);
+      lines.push(`- **${m.task.id}** ${m.task.title} — ${bits.join(" · ")} — [${t.report}](${rel})${open.length ? ` — ${open.length} ${t.openFindings}` : ""}`);
+    }
+    lines.push("");
+  }
+  if (!any) lines.push(t.nothing, "");
+  const totals = models.reduce((a, m) => ({ tasks: a.tasks + 1, tests: a.tests + (m.tests?.total ?? 0), out: a.out + (m.cost?.total?.output ?? 0), fix: a.fix + m.task.fixRounds }), { tasks: 0, tests: 0, out: 0, fix: 0 });
+  if (any) lines.push(`${t.totals}: ${totals.tasks} ${t.tasksWord} · ${totals.tests} ${t.testsWord} · ${totals.fix} ${t.fixRounds} · ${fmtTokens(totals.out)} ${t.tokensOut}`, "");
+  const markdown = lines.join("\n");
+  let file = null;
+  if (write) { file = path.join(at(root, "nccgs"), "releases", `${label.replace(/[^\w.-]+/g, "_")}.md`); writeText(file, markdown); }
+  return { label, from: from ?? null, to, tasks: tasks.map(x => x.id), file, markdown };
+}
+
+const EN = { since: "since", shipped: "Shipped", partial: "Partial", blocked: "Blocked", failed: "Failed", criteriaShort: "criteria", testsShort: "tests", reviewShort: "review", tokensOut: "tokens out", report: "report", openFindings: "open finding(s)", nothing: "No tasks closed in this range.", totals: "Totals", tasksWord: "tasks", testsWord: "tests", fixRounds: "fix rounds" };
+const VI = { since: "từ", shipped: "Đã giao", partial: "Dở dang", blocked: "Bị chặn", failed: "Thất bại", criteriaShort: "tiêu chí", testsShort: "test", reviewShort: "review", tokensOut: "token ra", report: "report", openFindings: "finding còn mở", nothing: "Không có task nào đóng trong khoảng này.", totals: "Tổng", tasksWord: "task", testsWord: "test", fixRounds: "vòng sửa" };

package/cli/run.mjs

@@ -0,0 +1,35 @@
+// nccgs run: launch Claude Code for a project with NCCGS's permission and transport policy.
+// acceptEdits by default; bypassPermissions only with --autonomy full (or config.autonomy = full).
+import { spawnTool } from "./spawn.mjs";
+import { readJson, exists } from "../runtime/core/fs.mjs";
+import { at, isUnityProject, loadConfig } from "../runtime/core/project.mjs";
+import { allModes } from "../runtime/core/modes.mjs";
+import { checkUpdates } from "./update-check.mjs";
+
+const OWNED = /^(--permission-mode|--dangerously-skip-permissions|--allow-dangerously-skip-permissions|--strict-mcp-config|--mcp-config|--model)(=|$)/;
+
+export async function plan(root, { mode, autonomy, forwarded = [], claudeBin = process.env.NCCGS_CLAUDE_BIN || "claude" } = {}) {
+  if (!isUnityProject(root)) throw new Error(`${root} is not a Unity project`);
+  if (!exists(at(root, "installState"))) throw new Error("NCCGS is not installed here; run `nccgs install --project <dir>`");
+  const config = loadConfig(root);
+  const modeName = mode || config.mode;
+  const modes = allModes(root);
+  if (!modes[modeName]) throw new Error(`Unknown mode ${modeName}`);
+  const auto = autonomy || config.autonomy;
+  if (!["guarded", "full"].includes(auto)) throw new Error("autonomy must be guarded | full");
+  for (const a of forwarded) if (OWNED.test(a)) throw new Error(`NCCGS owns ${a}; set it through project.json or nccgs mode`);
+  const coordinator = modes[modeName].coordinator ?? {};
+  const args = ["--permission-mode", auto === "full" ? "bypassPermissions" : "acceptEdits", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}'];
+  if (coordinator.model && coordinator.model !== "inherit") args.push("--model", coordinator.model);
+  const env = { ...process.env, NCCGS_PROJECT_ROOT: root, NCCGS_MODE: modeName, NCCGS_AUTONOMY: auto, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1" };
+  return { root, claudeBin, args: [...args, ...forwarded], env, mode: modeName, autonomy: auto, coordinator };
+}
+
+export async function launch(root, options = {}) {
+  const p = await plan(root, options);
+  try { await checkUpdates(root); } catch {}
+  process.stderr.write(`NCCGS run · ${p.mode} · ${p.autonomy === "full" ? "bypassPermissions (full autonomy)" : "acceptEdits"} · ${p.root}\n`);
+  if (options.dryRun) return { ...p, env: undefined };
+  const child = spawnTool(p.claudeBin, p.args, { cwd: p.root, env: p.env, stdio: "inherit", windowsHide: false });
+  return new Promise(resolve => child.on("close", code => resolve({ ...p, env: undefined, exitCode: code })));
+}

package/cli/spawn.mjs

@@ -0,0 +1,20 @@
+// Spawn helpers that avoid `shell: true` + args (Node DEP0190) while still resolving .cmd shims on Windows.
+import { spawn, spawnSync } from "node:child_process";
+
+const win = process.platform === "win32";
+// Quote one argument for cmd.exe /c: wrap in double quotes, escape embedded quotes, neutralise cmd metacharacters.
+export function quoteWin(arg) {
+  const s = String(arg);
+  const body = /[\s"]/.test(s) || s === "" ? `"${s.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"` : s;
+  return body.replace(/([()%!^<>&|])/g, "^$1");
+}
+export function commandLine(bin, args) { return [bin, ...args].map(quoteWin).join(" "); }
+
+export function spawnTool(bin, args, options = {}) {
+  if (!win) return spawn(bin, args, options);
+  return spawn("cmd.exe", ["/d", "/s", "/c", `"${commandLine(bin, args)}"`], { ...options, windowsVerbatimArguments: true });
+}
+export function spawnToolSync(bin, args, options = {}) {
+  if (!win) return spawnSync(bin, args, options);
+  return spawnSync("cmd.exe", ["/d", "/s", "/c", `"${commandLine(bin, args)}"`], { ...options, windowsVerbatimArguments: true });
+}

package/cli/uninstall.mjs

@@ -0,0 +1,43 @@
+// nccgs uninstall: remove managed files that are unchanged, detach hooks, keep .nccgs/ history
+// and anything the user modified. Everything removed is copied to .nccgs/backups/<id>/ first.
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, writeJson, exists, sha256File, nowIso } from "../runtime/core/fs.mjs";
+import { at } from "../runtime/core/project.mjs";
+import { removeSettings } from "./install.mjs";
+import { openTasks } from "../runtime/task/ledger.mjs";
+
+export function uninstall(root, { dryRun = false, force = false } = {}) {
+  const stateFile = at(root, "installState");
+  if (!exists(stateFile)) throw new Error("NCCGS is not installed here");
+  const state = readJson(stateFile);
+  const open = openTasks(root);
+  if (open.length && !force) throw new Error(`open tasks: ${open.map(t => t.id).join(", ")}. Close them or pass --force (history is kept either way)`);
+  const id = `uninstall-${nowIso().replace(/[:.]/g, "-")}`;
+  const backup = path.join(root, ".nccgs", "backups", id);
+  const removed = [], kept = [];
+  for (const [rel, sha] of Object.entries(state.files ?? {})) {
+    const file = path.join(root, rel);
+    if (!exists(file)) continue;
+    if (sha256File(file) !== sha && !force) { kept.push(rel); continue; }
+    removed.push(rel);
+    if (!dryRun) {
+      const dest = path.join(backup, rel); fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.copyFileSync(file, dest); fs.unlinkSync(file);
+    }
+  }
+  const agentsDir = at(root, "agents");
+  if (exists(agentsDir)) for (const f of fs.readdirSync(agentsDir)) if (/^nccgs-.*\.md$/.test(f)) { removed.push(`.claude/agents/${f}`); if (!dryRun) { const file = path.join(agentsDir, f); const dest = path.join(backup, ".claude/agents", f); fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.copyFileSync(file, dest); fs.unlinkSync(file); } }
+  if (!dryRun) {
+    removeSettings(root);
+    writeJson(path.join(backup, "manifest.json"), { id, at: nowIso(), version: state.version, removed, kept });
+    fs.unlinkSync(stateFile);
+    pruneEmpty(path.join(root, ".claude"));
+  }
+  return { id, dryRun, removed: removed.length, kept, backup: path.relative(root, backup), note: ".nccgs/ (tasks, evidence, reports, config) is kept" };
+}
+
+function pruneEmpty(dir) {
+  if (!exists(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) if (entry.isDirectory()) pruneEmpty(path.join(dir, entry.name));
+  if (!fs.readdirSync(dir).length) fs.rmdirSync(dir);
+}

package/cli/update-check.mjs

@@ -0,0 +1,66 @@
+// Update notices: NCCGS (npm), Unity Skills (GitHub HEAD), Unity CLI (its own notification), Pipeline.
+// Notify only. Never installs. Cached once per day under .nccgs/cache; every source has a 3 s timeout
+// and network failures are silent.
+import { readJson, writeJson, exists } from "../runtime/core/fs.mjs";
+import { at, loadConfig, pipelineVersion } from "../runtime/core/project.mjs";
+import { PKG, PKG_ROOT } from "./install.mjs";
+import path from "node:path";
+import { run } from "../runtime/core/process-tree.mjs";
+import { UNITY_BIN, unityArgv } from "../runtime/unity/unity.mjs";
+
+const DAY = 86400000;
+// semver compare with prerelease: 3.0.0-alpha.1 < 3.0.0 ; 2.1.1 < 3.0.0-alpha.1
+export function newer(latest, current) {
+  const parse = v => { const m = String(v).match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?/); return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null; };
+  const a = parse(latest), b = parse(current); if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a.n[i] !== b.n[i]) return a.n[i] > b.n[i];
+  if (a.pre === b.pre) return false; if (a.pre === null) return true; if (b.pre === null) return false; return a.pre > b.pre;
+}
+
+async function fetchJson(url, timeoutMs = 3000) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const r = await fetch(url, { signal: ctl.signal, headers: { "user-agent": `nccgs/${PKG.version}`, accept: "application/json" } });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; } finally { clearTimeout(t); }
+}
+
+export async function checkUpdates(root, { force = false, cliVersion = null } = {}) {
+  const config = loadConfig(root);
+  const file = at(root, "updateCheck");
+  const cached = exists(file) ? readJson(file) : null;
+  const interval = config.updates.check === "weekly" ? 7 * DAY : config.updates.check === "never" ? Infinity : DAY;
+  if (!force && cached && Date.now() - Date.parse(cached.checkedAt) < interval) return cached;
+  if (config.updates.check === "never" && !force) return { checkedAt: new Date().toISOString(), notices: [], skipped: true };
+  const channels = new Set(config.updates.channels ?? []);
+  const notices = [];
+  const sources = {};
+  if (channels.has("nccgs")) {
+    const j = await fetchJson("https://registry.npmjs.org/nccgs/latest");
+    sources.nccgs = j?.version ?? null;
+    if (j?.version && newer(j.version, PKG.version)) notices.push({ component: "nccgs", current: PKG.version, latest: j.version, hint: "npx nccgs@latest update --project . --dry-run" });
+  }
+  if (channels.has("unity-skills")) {
+    const manifest = readJson(path.join(PKG_ROOT, "unity-skills", "manifest.json"), {});
+    const j = await fetchJson("https://api.github.com/repos/Unity-Technologies/skills/commits/main");
+    sources.unitySkills = j?.sha ?? null;
+    if (j?.sha && manifest.source_revision && !j.sha.startsWith(manifest.source_revision) && manifest.source_revision !== "unknown-local-copy") notices.push({ component: "unity-skills", current: manifest.source_revision.slice(0, 7), latest: j.sha.slice(0, 7), hint: "nccgs update --skills-only --dry-run" });
+    else if (j?.sha && manifest.source_revision === "unknown-local-copy") notices.push({ component: "unity-skills", current: "unknown", latest: j.sha.slice(0, 7), hint: "node scripts/sync-unity-skills.mjs to pin a commit" });
+  }
+  if (channels.has("unity-cli")) {
+    // The CLI reports its own update in the JSON envelope's notifications (seen on beta.14).
+    const r = await run(UNITY_BIN, unityArgv(["editors", "--installed", "--format", "json"]), { timeoutMs: 8000 });
+    try {
+      const j = JSON.parse(r.stdout.replace(/^/, ""));
+      const n = (j.notifications ?? []).find(x => x.code === "CLI_UPDATE_AVAILABLE");
+      sources.unityCli = n?.data?.latest ?? cliVersion;
+      if (n) notices.push({ component: "unity-cli", current: n.data.current, latest: n.data.latest, hint: n.remediation?.command ?? "unity self-update" });
+    } catch {}
+  }
+  if (channels.has("pipeline")) sources.pipeline = pipelineVersion(root);   // latest version requires a registry call we do not make in alpha
+  const value = { checkedAt: new Date().toISOString(), notices, sources };
+  writeJson(file, value);
+  return value;
+}

package/docs/EVIDENCE-VERIFICATION.md

@@ -0,0 +1,22 @@
+# Evidence layer verification (2026-11-04)
+
+Machine: Windows x64, Node 24.12, Claude Code 2.1.316, Unity CLI 1.0.0-beta.14, com.unity.pipeline 0.9.1-exp.1.
+Projects: TestNCCGS1 (6000.3.17f1) and TestNCCGS2 (6000.6.7f1), both open in the Editor.
+
+| Capability | Command | 6000.3.17f1 | 6000.6.7f1 |
+|---|---|---|---|
+| Tests with the project open | `test run --mode editor` (Pipeline) - `unity test` refuses with "already open" (exit 6) | OK | OK |
+| Enter / exit Play Mode | `editor.playmode start` / `stop` | OK | OK |
+| First command after Play start | `script eval` | EDITOR_NOT_RUNNING for ~3 s (domain reload), then OK | OK after 1 s |
+| Screenshot | `capture screenshot --view game --output <abs>` | OK (PNG seen) | OK |
+| Console | `console status` / `console get` | OK | OK |
+| Simulated input | `runtime simulate_key --key Space` | OK | OK |
+| Performance | `diagnostics get_performance` | OK | OK |
+| Command discovery | `command --detail compact` (166 commands, 37 groups), `--query`, `--obsolete-command-names` | OK | OK |
+| Orphan processes after tests | none new after 10 s | 0 | not measured |
+
+NCCGS 3.0.0-alpha.1 end-to-end on TestNCCGS1: `install` (152 files) → `doctor` 11 pass / 0 fail → `task open` (3 criteria, observe auto-added) → `verify --kind tests` (pipeline, 4 s) → `verify --kind observe` (Play, Space, 2 screenshots, console, performance, stop; 21 s; 3/3 criteria pass) → `review` prompt written → `close --outcome success` correctly refused without a review.
+
+Consequences baked into the runtime: live/batch selection by `unity status`; `waitReady` after Play start; names resolved from the catalog cache; `--editor-version` pinned from ProjectVersion.txt; `capture game_view --save_path` avoided (writes under Assets/).
+
+Added during phases 2–4 (all measured on 6000.3.17f1 / Pipeline 0.9.1-exp.1): `simulate_key` delivers key-down and key-up in one input update (polling misses it; `InputAction` does not); PlayMode tests only run async (`--async_tests` + `test status`); each Pipeline round trip costs ~0.9 s, so sub-second timing is scheduled inside the Editor by one `script eval` (`observe --shots`, playtests with probes at 10 Hz and reactive rules); `script eval` is a method body without `using` and can reference the project's own types; `set_run_in_background` keeps Play Mode alive when the Editor loses focus; the Editor rewrites `ProjectSettings/ShaderGraphSettings.asset` and `SceneTemplateSettings.json` on its own (excluded from snapshots).

package/package.json

@@ -1,47 +1,39 @@
 {
   "name": "nccgs",
-  "version": "2.1.0",
-  "description": "Unity-first game-studio operating system for Claude Code",
+  "version": "3.0.0-rc.1",
+  "description": "NCCGS 3 - a Unity-first evidence loop for Claude Code: contract, run, look, review, report.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "nccgs": "scripts/cli.mjs"
+    "nccgs": "bin/nccgs.mjs"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "files": [
-    ".claude/",
-    "docs/",
-    "package-assets/",
-    "scaffold/",
+    "bin/",
+    "cli/",
+    "runtime/",
+    "template/",
+    "unity-skills/",
     "scripts/",
-    "tests/",
-    "CLAUDE.md",
-    "MEMORY.md",
-    "LICENSE",
+    "docs/",
     "README.md",
-    "THIRD_PARTY_NOTICES.md",
-    "UPGRADING.md",
-    "VERSION",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "latest",
-    "registry": "https://registry.npmjs.org/"
-  },
   "scripts": {
-    "validate": "node scripts/validate.mjs",
-    "test": "node --test tests/*.test.mjs",
-    "pack:check": "npm pack --dry-run",
-    "policy:build": "node .claude/nccgs/tools/compile-policy.mjs --write",
-    "policy:check": "node .claude/nccgs/tools/compile-policy.mjs"
+    "test": "node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "optionalDependencies": {
+    "koffi": "^3.3.6"
   },
   "keywords": [
     "claude-code",
-    "game-development",
     "unity",
-    "workflow"
+    "game-development",
+    "evidence"
   ]
 }