nccgs 2.1.1 → 3.0.0-rc.2

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,40 @@
 {
   "name": "nccgs",
-  "version": "2.1.1",
-  "description": "Unity-first game-studio operating system for Claude Code",
+  "version": "3.0.0-rc.2",
+  "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/",
+    "tools/",
     "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"
   ]
 }

package/runtime/core/diag.mjs

@@ -0,0 +1,43 @@
+// Diagnostics: .nccgs/diagnostics.jsonl, one line per thing that went wrong or was blocked —
+// runtime errors, failed verifications, Unity CLI/Pipeline failures, hook blocks. Local only; nothing
+// leaves the machine unless the person runs `nccgs feedback` and sends the bundle themselves.
+// Rotated at 5 MB (the previous file is kept once as diagnostics.1.jsonl).
+import fs from "node:fs";
+import path from "node:path";
+import { at } from "./project.mjs";
+import { appendLine, readText } from "./fs.mjs";
+
+const MAX = 5 * 1024 * 1024;
+export const diagFile = root => path.join(at(root, "nccgs"), "diagnostics.jsonl");
+
+export function diag(root, kind, data = {}) {
+  try {
+    const file = diagFile(root);
+    try { if (fs.existsSync(file) && fs.statSync(file).size > MAX) fs.renameSync(file, file.replace(/\.jsonl$/, ".1.jsonl")); } catch {}
+    appendLine(file, JSON.stringify({ ...clean(data), at: new Date().toISOString(), kind, pid: process.pid }));
+  } catch {}
+}
+
+// Keep entries small and free of secrets: strings capped, absolute user paths trimmed, env never copied.
+function clean(data) {
+  const out = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (v === undefined) continue;
+    if (typeof v === "string") out[k] = v.length > 2000 ? v.slice(0, 2000) + "…" : v;
+    else if (v instanceof Error) out[k] = { message: v.message, stack: String(v.stack ?? "").split("\n").slice(0, 6).join("\n") };
+    else if (Array.isArray(v)) out[k] = v.slice(0, 50).map(x => typeof x === "string" && x.length > 500 ? x.slice(0, 500) + "…" : x);
+    else out[k] = v;
+  }
+  return out;
+}
+
+export function readDiag(root, { sinceMs = 0 } = {}) {
+  const out = [];
+  for (const f of [diagFile(root).replace(/\.jsonl$/, ".1.jsonl"), diagFile(root)]) {
+    for (const line of readText(f, "").split("\n")) {
+      if (!line.trim()) continue;
+      try { const j = JSON.parse(line); if (Date.parse(j.at) >= sinceMs) out.push(j); } catch {}
+    }
+  }
+  return out;
+}

package/runtime/core/feedback-policy.mjs

@@ -0,0 +1,54 @@
+// When to suggest or send feedback. Pure functions over the ledger and diagnostics; the hooks and the
+// task CLI call `evaluate()` and act on consent. Everything is rate-limited so a person is asked at
+// most once per 6 hours and the periodic bundle goes at most once per `periodicDays`.
+import { loadConfig, saveConfig } from "./project.mjs";
+import { readDiag } from "./diag.mjs";
+import { listTasks } from "../task/ledger.mjs";
+
+const HOUR = 3600000, DAY = 86400000;
+const ISSUE_KINDS = { "task.exception": 1, "hook.error": 1, "unity.failed": 3, "verify.failed": 5, "task.error": 8 };
+
+export function evaluate(root, { now = Date.now(), config = loadConfig(root) } = {}) {
+  const fb = config.feedback ?? {};
+  if (fb.consent === "off") return { action: "none", reasons: [] };
+  const since = Date.parse(fb.lastSentAt ?? 0) || 0;
+  const diags = readDiag(root, { sinceMs: since });
+  const counts = {};
+  for (const d of diags) counts[d.kind] = (counts[d.kind] ?? 0) + 1;
+  const reasons = [];
+  for (const [kind, threshold] of Object.entries(ISSUE_KINDS)) if ((counts[kind] ?? 0) >= threshold) reasons.push(`${counts[kind]} × ${kind}`);
+  const bad = listTasks(root).filter(t => t.status === "closed" && t.outcome !== "success" && Date.parse(t.closedAt) > since && !/^T-|^PT-/.test(t.id));
+  if (bad.length) reasons.push(`${bad.length} task(s) closed ${[...new Set(bad.map(t => t.outcome))].join("/")}: ${bad.map(t => t.id).slice(0, 5).join(", ")}`);
+  const periodicDue = (fb.periodicDays ?? 7) > 0 && now - since >= (fb.periodicDays ?? 7) * DAY && listTasks(root).some(t => Date.parse(t.updatedAt ?? t.openedAt) > since);
+  if (periodicDue) reasons.push(`periodic (${fb.periodicDays ?? 7} days)`);
+  if (!reasons.length) return { action: "none", reasons: [], counts };
+  if (fb.consent === "ask") return { action: "ask-consent", reasons, counts };
+  if (fb.consent === "auto") return { action: "send", reasons, counts };
+  const suggestedRecently = now - (Date.parse(fb.lastSuggestedAt ?? 0) || 0) < 6 * HOUR;
+  return { action: suggestedRecently ? "none" : "suggest", reasons, counts };
+}
+
+export function setConsent(root, consent) {
+  if (!["ask", "auto", "manual", "off"].includes(consent)) throw new Error("consent must be ask | auto | manual | off");
+  const config = loadConfig(root);
+  config.feedback = { ...(config.feedback ?? {}), consent };
+  saveConfig(root, config);
+  return config.feedback;
+}
+
+export function markSuggested(root, now = new Date().toISOString()) {
+  const config = loadConfig(root);
+  config.feedback = { ...(config.feedback ?? {}), lastSuggestedAt: now };
+  saveConfig(root, config);
+}
+
+export function markSent(root, now = new Date().toISOString()) {
+  const config = loadConfig(root);
+  config.feedback = { ...(config.feedback ?? {}), lastSentAt: now };
+  saveConfig(root, config);
+}
+
+export const CONSENT_TEXT = {
+  en: "NCCGS can send anonymous-ish feedback bundles to its maintainers when something fails or every 7 days: versions, doctor output, per-task numbers (criteria, tests, review verdicts, fix rounds, minutes, tokens), diagnostics and any note you add. Project name and task titles are included; source code, screenshots, transcripts and credentials never are. Options: auto (send by itself), manual (only suggest `/feedback`), off (never). Change later with `npx nccgs feedback --consent <auto|manual|off>`.",
+  vi: "NCCGS có thể gửi gói feedback cho nhóm phát triển khi có lỗi hoặc mỗi 7 ngày: phiên bản, kết quả doctor, số liệu từng task (criteria, test, verdict review, vòng sửa, phút, token), diagnostics và ghi chú của bạn. Tên dự án và tiêu đề task có trong gói; mã nguồn, ảnh, transcript và credential không bao giờ có. Lựa chọn: auto (tự gửi), manual (chỉ gợi ý `/feedback`), off (không bao giờ). Đổi sau bằng `npx nccgs feedback --consent <auto|manual|off>`."
+};

package/runtime/core/fs.mjs

@@ -0,0 +1,80 @@
+// Small filesystem helpers shared by the runtime and the CLI. No dependencies.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const exists = p => fs.existsSync(p);
+
+export function readJson(file, fallback = undefined) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8").replace(/^/, ""));
+  } catch (error) {
+    if (fallback !== undefined && error.code === "ENOENT") return fallback;
+    throw new Error(`Cannot read JSON ${file}: ${error.message}`);
+  }
+}
+
+// Atomic write: write to a sibling temp file, then rename over the target.
+export function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, file);
+}
+
+export function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, "utf8");
+}
+
+export function readText(file, fallback = "") {
+  try { return fs.readFileSync(file, "utf8").replace(/^/, ""); } catch { return fallback; }
+}
+
+export function appendLine(file, line) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, line.endsWith("\n") ? line : line + "\n", "utf8");
+}
+
+export const sha256 = buffer => crypto.createHash("sha256").update(buffer).digest("hex");
+export const sha256File = file => sha256(fs.readFileSync(file));
+
+// Resolve `relative` under `root` and refuse anything that escapes it.
+export function contained(root, relative) {
+  const absolute = path.resolve(root, relative);
+  const rel = path.relative(root, absolute);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`Path escapes project: ${relative}`);
+  return absolute;
+}
+
+export const toPosix = p => p.split(path.sep).join("/");
+
+// Walk a directory tree (files only), skipping the given directory names.
+export function* walk(dir, { skipDirs = new Set(), maxFiles = Infinity } = {}) {
+  const stack = [dir];
+  let count = 0;
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) { if (!skipDirs.has(entry.name)) stack.push(full); }
+      else if (entry.isFile()) { yield full; if (++count >= maxFiles) return; }
+    }
+  }
+}
+
+export function copyDir(from, to, { filter = () => true, onFile } = {}) {
+  for (const file of walk(from)) {
+    const rel = path.relative(from, file);
+    if (!filter(rel)) continue;
+    const target = path.join(to, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(file, target);
+    onFile?.(rel, target);
+  }
+}
+
+export const nowIso = () => new Date().toISOString();
+export const shortId = () => crypto.randomBytes(4).toString("hex");