nccgs 2.1.1 → 3.0.0-rc.2

package/runtime/core/job-object.mjs

@@ -0,0 +1,73 @@
+// Windows Job Object through koffi (optional dependency). A process assigned to a job dies with
+// everything it spawned when the job is terminated (and, with KILL_ON_JOB_CLOSE, when the handle
+// closes), including grandchildren that re-parented themselves; taskkill /T cannot promise that.
+// Without koffi (not installed, not Windows, load error) every function here is a no-op that returns
+// null, and process-tree.mjs falls back to taskkill /T + the ppid walk.
+let koffi = null, api = null, tried = false;
+
+async function load() {
+  if (tried) return api;
+  tried = true;
+  if (process.platform !== "win32" || process.env.NCCGS_NO_JOB_OBJECT) return null;
+  try {
+    koffi = (await import("koffi")).default;
+    const k32 = koffi.load("kernel32.dll");
+    const BASIC = koffi.struct("JOBOBJECT_BASIC_LIMIT_INFORMATION", {
+      PerProcessUserTimeLimit: "int64", PerJobUserTimeLimit: "int64", LimitFlags: "uint32", MinimumWorkingSetSize: "size_t", MaximumWorkingSetSize: "size_t",
+      ActiveProcessLimit: "uint32", Affinity: "size_t", PriorityClass: "uint32", SchedulingClass: "uint32"
+    });
+    const IO = koffi.struct("IO_COUNTERS", { ReadOperationCount: "uint64", WriteOperationCount: "uint64", OtherOperationCount: "uint64", ReadTransferCount: "uint64", WriteTransferCount: "uint64", OtherTransferCount: "uint64" });
+    const EXT = koffi.struct("JOBOBJECT_EXTENDED_LIMIT_INFORMATION", { BasicLimitInformation: BASIC, IoInfo: IO, ProcessMemoryLimit: "size_t", JobMemoryLimit: "size_t", PeakProcessMemoryUsed: "size_t", PeakJobMemoryUsed: "size_t" });
+    api = {
+      EXT,
+      CreateJobObjectW: k32.func("void* __stdcall CreateJobObjectW(void* attrs, const char16_t* name)"),
+      SetInformationJobObject: k32.func("int __stdcall SetInformationJobObject(void* job, int cls, JOBOBJECT_EXTENDED_LIMIT_INFORMATION* info, uint32 len)"),
+      AssignProcessToJobObject: k32.func("int __stdcall AssignProcessToJobObject(void* job, void* process)"),
+      OpenProcess: k32.func("void* __stdcall OpenProcess(uint32 access, int inherit, uint32 pid)"),
+      TerminateJobObject: k32.func("int __stdcall TerminateJobObject(void* job, uint32 exitCode)"),
+      CloseHandle: k32.func("int __stdcall CloseHandle(void* h)"),
+      GetLastError: k32.func("uint32 __stdcall GetLastError()")
+    };
+    return api;
+  } catch { api = null; return null; }
+}
+
+const JobObjectExtendedLimitInformation = 9;
+const JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000;
+const PROCESS_SET_QUOTA = 0x0100, PROCESS_TERMINATE = 0x0001;
+
+// Create a job and put `pid` in it. `killOnClose` makes the whole tree die when the handle closes
+// (right for a tool whose children must not outlive it); off by default so a command such as
+// `unity open`, whose Editor child must survive, is only killed on an explicit terminate.
+export async function createJobFor(pid, { killOnClose = false } = {}) {
+  const a = await load();
+  if (!a) return null;
+  try {
+    const job = a.CreateJobObjectW(null, null);
+    if (!job) return { job: null, error: `CreateJobObject failed (${a.GetLastError()})` };
+    const info = { BasicLimitInformation: { PerProcessUserTimeLimit: 0, PerJobUserTimeLimit: 0, LimitFlags: killOnClose ? JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE : 0, MinimumWorkingSetSize: 0, MaximumWorkingSetSize: 0, ActiveProcessLimit: 0, Affinity: 0, PriorityClass: 0, SchedulingClass: 0 },
+      IoInfo: { ReadOperationCount: 0, WriteOperationCount: 0, OtherOperationCount: 0, ReadTransferCount: 0, WriteTransferCount: 0, OtherTransferCount: 0 }, ProcessMemoryLimit: 0, JobMemoryLimit: 0, PeakProcessMemoryUsed: 0, PeakJobMemoryUsed: 0 };
+    if (!a.SetInformationJobObject(job, JobObjectExtendedLimitInformation, info, koffi.sizeof(a.EXT))) { const e = a.GetLastError(); a.CloseHandle(job); return { job: null, error: `SetInformationJobObject failed (${e})` }; }
+    const proc = a.OpenProcess(PROCESS_SET_QUOTA | PROCESS_TERMINATE, 0, pid);
+    if (!proc) { const e = a.GetLastError(); a.CloseHandle(job); return { job: null, error: `OpenProcess failed (${e})` }; }
+    const ok = a.AssignProcessToJobObject(job, proc);
+    const err = ok ? 0 : a.GetLastError();
+    a.CloseHandle(proc);
+    if (!ok) { a.CloseHandle(job); return { job: null, error: `AssignProcessToJobObject failed (${err})` }; }
+    return { job, error: null };
+  } catch (e) { return { job: null, error: e.message }; }
+}
+
+export async function terminateJob(job) {
+  const a = await load();
+  if (!a || !job) return false;
+  try { const ok = !!a.TerminateJobObject(job, 1); a.CloseHandle(job); return ok; } catch { return false; }
+}
+
+export async function closeJob(job) {
+  const a = await load();
+  if (!a || !job) return;
+  try { a.CloseHandle(job); } catch {}
+}
+
+export async function available() { return !!(await load()); }

package/runtime/core/modes.mjs

@@ -0,0 +1,87 @@
+// Model modes: three built-in (package-owned, read-only) + custom (project-owned, .nccgs/modes.json).
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { readJson, writeJson, writeText, exists } from "./fs.mjs";
+import { at, loadConfig, saveConfig } from "./project.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const BUILTIN = readJson(path.join(here, "..", "modes.json"));
+
+export function allModes(root) {
+  const custom = exists(at(root, "modes")) ? readJson(at(root, "modes")).modes ?? {} : {};
+  return { ...BUILTIN.modes, ...Object.fromEntries(Object.entries(custom).map(([k, v]) => [k, { ...v, custom: true }])) };
+}
+export function getMode(root, name) {
+  const modes = allModes(root);
+  const mode = modes[name];
+  if (!mode) throw new Error(`Unknown mode ${name}. Available: ${Object.keys(modes).join(", ")}`);
+  return mode;
+}
+export function validateAgentSetting(setting) {
+  const warnings = [];
+  const m = String(setting.model ?? "");
+  if (!(BUILTIN.allowed.models.includes(m) || /^claude-[\w.-]+$/.test(m))) throw new Error(`model must be one of ${BUILTIN.allowed.models.join("|")} or a claude-... ID (got ${m})`);
+  if (setting.effort !== null && setting.effort !== undefined && !BUILTIN.allowed.efforts.includes(setting.effort)) throw new Error(`effort must be one of ${BUILTIN.allowed.efforts.join("|")}`);
+  if (m === "haiku" && ["xhigh", "max"].includes(setting.effort)) warnings.push("haiku with xhigh/max effort is unusual");
+  if (m === "fable") warnings.push("fable requires a subscription that includes it; set a fallback or expect `task review` to fall back");
+  return warnings;
+}
+export function createMode(root, { name, from = "BALANCE" }) {
+  if (!/^[A-Za-z][\w-]{1,30}$/.test(name)) throw new Error("mode name: letters, digits, _ or -, 2-31 chars");
+  if (BUILTIN.modes[name]) throw new Error(`${name} is a built-in mode; pick another name`);
+  const base = getMode(root, from);
+  const file = at(root, "modes");
+  const custom = exists(file) ? readJson(file) : { schemaVersion: 1, modes: {} };
+  if (custom.modes[name]) throw new Error(`mode ${name} already exists`);
+  const copy = structuredClone(base); delete copy.custom; copy.description = `Custom, copied from ${from}`;
+  custom.modes[name] = copy;
+  writeJson(file, custom);
+  return copy;
+}
+export function setModeAgent(root, { name, agent, model, effort, fallback }) {
+  if (BUILTIN.modes[name]) throw new Error(`${name} is built-in and read-only; create a copy with \`nccgs mode create --from ${name} --name <new>\``);
+  const file = at(root, "modes");
+  const custom = exists(file) ? readJson(file) : { schemaVersion: 1, modes: {} };
+  const mode = custom.modes[name]; if (!mode) throw new Error(`custom mode ${name} not found`);
+  if (!BUILTIN.agents.includes(agent)) throw new Error(`agent must be one of ${BUILTIN.agents.join("|")}`);
+  const setting = { ...(mode[agent] ?? {}) };
+  if (model) setting.model = model;
+  if (effort !== undefined) setting.effort = effort === "none" ? null : effort;
+  if (fallback !== undefined) setting.fallback = fallback === "none" ? null : fallback;
+  const warnings = validateAgentSetting(setting);
+  mode[agent] = setting;
+  writeJson(file, custom);
+  return { setting, warnings };
+}
+export function useMode(root, name, { templateDir }) {
+  const mode = getMode(root, name);
+  const config = loadConfig(root);
+  config.mode = name;
+  saveConfig(root, config);
+  const warnings = [];
+  for (const agent of BUILTIN.agents) if (mode[agent]) warnings.push(...validateAgentSetting(mode[agent]).map(w => `${agent}: ${w}`));
+  const written = renderAgents(root, name, { templateDir });
+  return { mode: name, written, warnings: [...new Set(warnings)] };
+}
+// Agent frontmatter is static in Claude Code, so a mode change regenerates .claude/agents/*.md.
+export function renderAgents(root, name, { templateDir }) {
+  const mode = getMode(root, name);
+  const dir = at(root, "agents");
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const agent of BUILTIN.agents) {
+    if (agent === "coordinator") continue;        // the main session; its model is passed to `claude --model`
+    const tpl = path.join(templateDir, "agents", `${agent}.md`);
+    if (!exists(tpl)) continue;
+    const s = mode[agent] ?? {};
+    const text = fs.readFileSync(tpl, "utf8")
+      .replace(/\{\{model\}\}/g, s.model ?? "inherit")
+      .replace(/\{\{effort_line\}\}/g, s.effort ? `effort: ${s.effort}\n` : "")
+      .replace(/\{\{mode\}\}/g, name);
+    const file = path.join(dir, `nccgs-${agent}.md`);
+    writeText(file, text);
+    written.push(path.relative(root, file));
+  }
+  return written;
+}

package/runtime/core/process-tree.mjs

@@ -0,0 +1,109 @@
+// Cross-platform "run a command and own its whole process tree".
+// Layer 0: let the tool exit on its own (timeout belongs to the caller's args).
+// Layer 1: OS primitive - process group on POSIX; on Windows a Job Object (koffi, optional) with
+//          kill-on-close, falling back to taskkill /T when koffi is not installed.
+// Layer 2: env tag (NCCGS_TREE) so re-parented descendants can still be found on POSIX.
+// Layer 3: parent-pid walk as the fallback on both platforms.
+// Every kill is verified by re-enumerating; the result reports dead | alive | unknown.
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { createJobFor, terminateJob, closeJob } from "./job-object.mjs";
+
+const win = process.platform === "win32";
+
+export function run(executable, args, { cwd, timeoutMs = 0, env = {}, input, onLine, ownTree = false } = {}) {
+  return new Promise(resolve => {
+    const tag = crypto.randomUUID();
+    const child = spawn(executable, args, {
+      cwd, windowsHide: true, detached: !win, shell: false,
+      env: { ...process.env, ...env, NCCGS_TREE: tag, UNITY_NO_AUTH_BROKER: "1" },
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "", stderr = "", timedOut = false, settled = false, job = null, jobError = null, jobUsed = false;
+    if (win && child.pid) createJobFor(child.pid, { killOnClose: ownTree }).then(r => { if (r) { job = r.job; jobError = r.error; jobUsed = !!r.job; } else jobError = "koffi not available"; }).catch(e => { jobError = e.message; });
+    child.stdout.on("data", d => { stdout += d; onLine?.(String(d)); });
+    child.stderr.on("data", d => { stderr += d; });
+    if (input !== undefined) child.stdin.end(input); else child.stdin.end();
+    const timer = timeoutMs > 0 ? setTimeout(async () => {
+      timedOut = true;
+      await terminate({ pid: child.pid, tag, job });
+      job = null;
+    }, timeoutMs) : null;
+    const finish = (code, signal, error) => {
+      if (settled) return; settled = true;
+      if (timer) clearTimeout(timer);
+      if (job) { closeJob(job); job = null; }   // with ownTree, anything still alive in the job dies here
+      resolve({ code, signal, stdout, stderr, timedOut, error: error?.message, pid: child.pid, tag, jobObject: !win ? "n/a" : jobUsed ? "used" : `unavailable: ${jobError ?? "not created"}` });
+    };
+    child.on("error", error => finish(null, null, error));
+    child.on("close", (code, signal) => finish(code, signal));
+  });
+}
+
+// Kill a tree started by run(). Returns { state: "dead"|"alive"|"unknown", killed: number }.
+export async function terminate({ pid, tag, job = null }, { graceMs = 2000 } = {}) {
+  if (!pid) return { state: "unknown", killed: 0 };
+  const before = enumerate({ pid, tag });
+  if (win) {
+    const viaJob = job ? await terminateJob(job) : false;
+    if (!viaJob) spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { windowsHide: true, timeout: 10000 });
+  } else {
+    try { process.kill(-pid, "SIGTERM"); } catch { try { process.kill(pid, "SIGTERM"); } catch {} }
+    await sleep(graceMs);
+    for (const p of enumerate({ pid, tag })) { try { process.kill(p, "SIGKILL"); } catch {} }
+    try { process.kill(-pid, "SIGKILL"); } catch {}
+  }
+  await sleep(300);
+  const after = enumerate({ pid, tag });
+  return { state: after.length === 0 ? "dead" : "alive", killed: before.length - after.length, remaining: after };
+}
+
+// Enumerate live pids that belong to the tree: by env tag (POSIX) or by ppid walk (both).
+export function enumerate({ pid, tag }) {
+  const found = new Set();
+  if (!win) {
+    // Layer 2: env tag. Linux reads /proc; macOS uses `ps -E` (same-user processes only).
+    if (tag) {
+      if (fs.existsSync("/proc")) {
+        for (const entry of safeReaddir("/proc")) {
+          if (!/^\d+$/.test(entry)) continue;
+          try {
+            const environ = fs.readFileSync(`/proc/${entry}/environ`, "latin1");
+            if (environ.includes(`NCCGS_TREE=${tag}`)) found.add(Number(entry));
+          } catch {}
+        }
+      } else {
+        const out = spawnSync("ps", ["-axE", "-o", "pid=,command="], { encoding: "utf8", timeout: 5000 }).stdout || "";
+        for (const line of out.split("\n")) if (line.includes(`NCCGS_TREE=${tag}`)) found.add(Number(line.trim().split(/\s+/)[0]));
+      }
+    }
+    // Layer 3: ppid walk.
+    const out = spawnSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8", timeout: 5000 }).stdout || "";
+    const children = new Map();
+    for (const line of out.split("\n")) {
+      const [p, pp] = line.trim().split(/\s+/).map(Number);
+      if (!p) continue;
+      if (!children.has(pp)) children.set(pp, []);
+      children.get(pp).push(p);
+    }
+    const stack = [pid];
+    while (stack.length) { const p = stack.pop(); if (isAlive(p)) found.add(p); for (const c of children.get(p) || []) stack.push(c); }
+  } else {
+    const ps = spawnSync("powershell", ["-NoProfile", "-Command",
+      "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId | ConvertTo-Json -Compress"],
+      { encoding: "utf8", windowsHide: true, timeout: 15000 });
+    let list = [];
+    try { list = JSON.parse(ps.stdout || "[]"); if (!Array.isArray(list)) list = [list]; } catch {}
+    const children = new Map();
+    for (const row of list) { const pp = row.ParentProcessId; if (!children.has(pp)) children.set(pp, []); children.get(pp).push(row.ProcessId); }
+    const alive = new Set(list.map(r => r.ProcessId));
+    const stack = [pid];
+    while (stack.length) { const p = stack.pop(); if (alive.has(p)) found.add(p); for (const c of children.get(p) || []) stack.push(c); }
+  }
+  return [...found].filter(p => p && isAlive(p));
+}
+
+function isAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } }
+function safeReaddir(dir) { try { return fs.readdirSync(dir); } catch { return []; } }
+export const sleep = ms => new Promise(r => setTimeout(r, ms));

package/runtime/core/project.mjs

@@ -0,0 +1,113 @@
+// Project layout, configuration and Unity version detection.
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, writeJson, readText, exists } from "./fs.mjs";
+
+export const LAYOUT = {
+  nccgs: ".nccgs",
+  config: ".nccgs/project.json",
+  modes: ".nccgs/modes.json",
+  state: ".nccgs/state.md",
+  tasks: ".nccgs/tasks",
+  evidence: ".nccgs/evidence",
+  measurements: ".nccgs/evidence/measurements",
+  screens: ".nccgs/evidence/screens",
+  review: ".nccgs/evidence/review",
+  reports: ".nccgs/reports",
+  cache: ".nccgs/cache",
+  events: ".nccgs/events.jsonl",
+  updateCheck: ".nccgs/cache/update-check.json",
+  runtime: ".claude/nccgs/runtime",
+  installState: ".claude/nccgs/install-state.json",
+  agents: ".claude/agents",
+  skills: ".claude/skills",
+  settings: ".claude/settings.json"
+};
+
+export const DEFAULT_CONFIG = {
+  schemaVersion: 3,
+  name: "",
+  mode: "BALANCE",
+  rigor: "production",          // prototype | production | release
+  autonomy: "guarded",          // guarded (acceptEdits) | full (bypassPermissions)
+  report: { language: "en" },
+  updates: { check: "daily", channels: ["nccgs", "unity-skills", "unity-cli", "pipeline"] },
+  unity: { version: null, pipelineVersion: null },   // null = detected from the project
+  review: { model: null, effort: null, fallback: "opus" },
+  files: {
+    protected: [],
+    ignoreForSnapshot: ["Library", "Temp", "Logs", "obj", "Build", "Builds", ".nccgs", ".git", "node_modules", "UserSettings"],
+    // Files the Editor rewrites on its own (Play Mode, domain reload) with no source meaning. Snapshots hash
+    // content, so an identical re-save is already ignored; this list is for files whose content churns.
+    volatile: ["ProjectSettings/ShaderGraphSettings.asset", "ProjectSettings/SceneTemplateSettings.json", "ProjectSettings/BurstAotSettings_*.json", "Assets/**/*.orig"],
+    hashMaxBytes: 8388608
+  },
+  unitySkills: { disabled: [] },
+  // USD per million tokens, keyed by a substring of the model id. Empty rows = tokens only, no dollars.
+  // Fill in from https://www.anthropic.com/pricing when you want estimates; subscription plans do not bill per token.
+  pricing: {},
+  // Feedback to the NCCGS maintainers. consent: "ask" (not decided yet: the next session asks once),
+  // "auto" (bundles are sent when an issue is detected or every periodicDays), "manual" (NCCGS only
+  // suggests `/feedback`; nothing is sent by itself), "off" (never suggests, never sends).
+  // A bundle holds versions, doctor, per-task numbers, diagnostics and your note: no source, no
+  // screenshots, no transcripts, no credentials. Project name and task titles are included.
+  feedback: { consent: "ask", endpoint: "https://nccgs-feedback.buihoanghachau.workers.dev/v1/bundle", periodicDays: 7, includeReports: false, lastSentAt: null, lastSuggestedAt: null }
+};
+
+export function projectRoot(explicit) {
+  const root = path.resolve(explicit || process.env.NCCGS_PROJECT_ROOT || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  return root;
+}
+
+export function isUnityProject(root) {
+  return exists(path.join(root, "Assets")) && exists(path.join(root, "ProjectSettings", "ProjectVersion.txt"));
+}
+
+export function at(root, key) { return path.join(root, LAYOUT[key] ?? key); }
+
+export function loadConfig(root) {
+  const file = at(root, "config");
+  const stored = exists(file) ? readJson(file) : {};
+  return deepMerge(structuredClone(DEFAULT_CONFIG), stored);
+}
+
+export function saveConfig(root, config) { writeJson(at(root, "config"), config); }
+
+export function editorVersion(root) {
+  const text = readText(path.join(root, "ProjectSettings", "ProjectVersion.txt"));
+  return text.match(/m_EditorVersion:\s*(\S+)/)?.[1] ?? null;
+}
+
+export function manifestPackages(root) {
+  const manifest = readJson(path.join(root, "Packages", "manifest.json"), { dependencies: {} });
+  return manifest.dependencies ?? {};
+}
+
+export function pipelineVersion(root) {
+  const deps = manifestPackages(root);
+  return deps["com.unity.pipeline"] ?? null;
+}
+
+// One line that session-start injects so Claude never has to guess versions.
+export function versionLine(root, cliVersion) {
+  const deps = manifestPackages(root);
+  const parts = [`Unity ${editorVersion(root) ?? "unknown"}`];
+  if (deps["com.unity.pipeline"]) parts.push(`pipeline ${deps["com.unity.pipeline"]}`);
+  if (cliVersion) parts.push(`CLI ${cliVersion}`);
+  for (const key of ["com.unity.render-pipelines.universal", "com.unity.inputsystem", "com.unity.test-framework"]) {
+    if (deps[key]) parts.push(`${key.split(".").pop()} ${deps[key]}`);
+  }
+  return parts.join(" · ");
+}
+
+export function deepMerge(base, extra) {
+  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return extra ?? base;
+  for (const [k, v] of Object.entries(extra)) {
+    base[k] = v && typeof v === "object" && !Array.isArray(v) && base[k] && typeof base[k] === "object" ? deepMerge(base[k], v) : v;
+  }
+  return base;
+}
+
+export function ensureLayout(root) {
+  for (const key of ["nccgs", "tasks", "measurements", "screens", "review", "reports", "cache"]) fs.mkdirSync(at(root, key), { recursive: true });
+}

package/runtime/core/snapshot.mjs

@@ -0,0 +1,114 @@
+// Source snapshot: a fingerprint of Assets/, Packages/ and ProjectSettings/ by file CONTENT.
+//
+// alpha.2 fingerprinted path+size+mtime. That was wrong for Unity: the Editor re-saves files such as
+// ProjectSettings/ShaderGraphSettings.asset every time it enters Play Mode, so `task verify --kind observe`
+// changed the snapshot without changing a byte of source, tests looked stale, and the report blamed
+// the task for an edit it never made. Hashing content fixes the question the ledger asks
+// ("did the source change since this evidence?") without exceptions for every file Unity touches.
+//
+// Cost: files are rehashed only when their size or mtime changed since the last snapshot
+// (.nccgs/cache/hash-cache.json). Files above `files.hashMaxBytes` (default 8 MB, usually textures,
+// audio, video) are fingerprinted by size+mtime; a rewritten texture still counts as a change.
+// Known Editor-volatile files (config `files.volatile`) are excluded entirely.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { walk, toPosix, readJson, writeJson, exists } from "./fs.mjs";
+import { loadConfig, at } from "./project.mjs";
+
+const ROOTS = ["Assets", "Packages", "ProjectSettings"];
+const CACHE_VERSION = 1;
+
+function cacheFile(root) { return path.join(at(root, "cache"), "hash-cache.json"); }
+function mapFile(root, sha) { return path.join(at(root, "cache"), "snapshots", `${sha}.json`); }
+
+// glob-lite: `*` within a segment, `**` across segments. Patterns are posix, relative to root.
+export function matchesPattern(rel, pattern) {
+  const re = "^" + pattern.split("**").map(p => p.split("*").map(s => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")).join(".*") + "$";
+  return new RegExp(re).test(rel);
+}
+
+function isVolatile(rel, volatile) { return volatile.some(p => matchesPattern(rel, p)); }
+
+// Returns { sha, files, at, map } where map is { "Assets/x.cs": "<sha256 or size:mtime>" }.
+export function snapshot(root, { config = loadConfig(root), persist = true } = {}) {
+  const skip = new Set(config.files.ignoreForSnapshot);
+  const volatile = config.files.volatile ?? [];
+  const maxBytes = config.files.hashMaxBytes ?? 8 * 1024 * 1024;
+  const cachePath = cacheFile(root);
+  const cached = exists(cachePath) ? readJson(cachePath, {}) : {};
+  const cache = cached.version === CACHE_VERSION ? cached.entries ?? {} : {};
+  const next = {};
+  const map = {};
+  for (const top of ROOTS) {
+    const dir = path.join(root, top);
+    if (!fs.existsSync(dir)) continue;
+    for (const file of walk(dir, { skipDirs: skip })) {
+      const rel = toPosix(path.relative(root, file));
+      if (isVolatile(rel, volatile)) continue;
+      let st;
+      try { st = fs.statSync(file); } catch { continue; }
+      const key = `${st.size}:${Math.floor(st.mtimeMs)}`;
+      let fingerprint;
+      if (st.size > maxBytes) fingerprint = `big:${key}`;
+      else if (cache[rel]?.key === key) fingerprint = cache[rel].sha;
+      else {
+        try { fingerprint = crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); } catch { continue; }
+      }
+      next[rel] = { key, sha: fingerprint };
+      map[rel] = fingerprint;
+    }
+  }
+  const rels = Object.keys(map).sort();
+  const hash = crypto.createHash("sha256");
+  for (const rel of rels) hash.update(`${rel}\0${map[rel]}\n`);
+  const sha = hash.digest("hex");
+  if (persist) {
+    try {
+      writeJson(cachePath, { version: CACHE_VERSION, entries: next });
+      const mf = mapFile(root, sha);
+      if (!exists(mf)) writeJson(mf, { sha, at: new Date().toISOString(), files: map });
+    } catch {}
+  }
+  return { sha, files: rels.length, at: new Date().toISOString(), map };
+}
+
+// Load the per-file map of an earlier snapshot by sha (written by snapshot()); null when unknown.
+export function snapshotMap(root, sha) {
+  const mf = sha ? mapFile(root, sha) : null;
+  return mf && exists(mf) ? readJson(mf).files ?? null : null;
+}
+
+// Files whose content differs between an earlier snapshot and now: added, modified or removed.
+// `since` is a snapshot object ({ sha, map? }) or a sha. Falls back to mtime when the earlier map is
+// unknown (tasks opened by alpha.2) and `sinceMs` is given.
+export function changedFiles(root, since, { config = loadConfig(root), sinceMs = null } = {}) {
+  const current = snapshot(root, { config });
+  const before = typeof since === "object" && since?.map ? since.map : snapshotMap(root, typeof since === "string" ? since : since?.sha);
+  if (!before) {
+    if (sinceMs == null) return Object.keys(current.map).sort();
+    const skip = new Set(config.files.ignoreForSnapshot);
+    const volatile = config.files.volatile ?? [];
+    const changed = [];
+    for (const top of ROOTS) {
+      const dir = path.join(root, top);
+      if (!fs.existsSync(dir)) continue;
+      for (const file of walk(dir, { skipDirs: skip })) {
+        const rel = toPosix(path.relative(root, file));
+        if (!isVolatile(rel, volatile) && fs.statSync(file).mtimeMs > sinceMs) changed.push(rel);
+      }
+    }
+    return changed.sort();
+  }
+  const changed = new Set();
+  for (const [rel, fp] of Object.entries(current.map)) if (before[rel] !== fp) changed.add(rel);
+  for (const rel of Object.keys(before)) if (!(rel in current.map)) changed.add(rel);
+  return [...changed].sort();
+}
+
+// Is `rel` covered by the task's declared files? A `.meta` belongs to the asset it describes.
+export function inScope(rel, files) {
+  if (!files?.length) return true;
+  const base = rel.endsWith(".meta") ? rel.slice(0, -5) : rel;
+  return files.some(p => base === p || rel === p || base.startsWith(p.replace(/\/?$/, "/")));
+}

package/runtime/hooks/common.mjs

@@ -0,0 +1,22 @@
+// Shared hook plumbing. Hooks are workflow guards, not a sandbox: they block the
+// obviously destructive, warn on the risky, and log the rest.
+import path from "node:path";
+import { projectRoot, at } from "../core/project.mjs";
+import { appendLine } from "../core/fs.mjs";
+import { diag } from "../core/diag.mjs";
+
+export async function readInput() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  try { return text.trim() ? JSON.parse(text) : {}; } catch { return {}; }
+}
+export const root = () => projectRoot();
+export function block(reason, extra = {}) { diag(root(), "hook.block", { hook: path.basename(process.argv[1] ?? "hook"), reason, ...extra }); process.stderr.write(`NCCGS blocked: ${reason}\n`); process.exit(2); }
+process.on("uncaughtException", e => { try { diag(root(), "hook.error", { hook: path.basename(process.argv[1] ?? "hook"), error: e }); } catch {} process.exit(0); });
+export function warn(hookEventName, message) {
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: `NCCGS warning: ${message}` } }) + "\n");
+  process.exit(0);
+}
+export function log(type, data) {
+  try { appendLine(at(root(), "events"), JSON.stringify({ at: new Date().toISOString(), type, ...data })); } catch {}
+}

package/runtime/hooks/done-guard.mjs

@@ -0,0 +1,15 @@
+// Stop hook: a DONE claim needs a closed task. It never traps the session (stop_hook_active).
+import { readInput, root } from "./common.mjs";
+import { openTasks } from "../task/ledger.mjs";
+
+const input = await readInput();
+if (input?.stop_hook_active) process.exit(0);
+const text = String(input?.last_assistant_message ?? "");
+const claimsDone = /(^|\n)\s*(\*\*)?(status|state|final state|trạng thái)(\*\*)?\s*:\s*(\*\*)?done\b/i.test(text) || /\b(task|work)\s+(is\s+)?done\b[^.]*\.(\s|$)/i.test(text) && /\bDONE\b/.test(text);
+if (!claimsDone) process.exit(0);
+let open = [];
+try { open = openTasks(root()); } catch {}
+if (open.length) {
+  process.stdout.write(JSON.stringify({ decision: "block", reason: `NCCGS: ${open.map(t => t.id).join(", ")} still open. Run \`task close\` (criteria + review must pass) before reporting DONE, or report partial/blocked honestly.` }) + "\n");
+}
+process.exit(0);

package/runtime/hooks/guard-mcp.mjs

@@ -0,0 +1,8 @@
+// PreToolUse for mcp__* tools: refuse Unity MCP servers by name.
+import { readInput, block } from "./common.mjs";
+import { PROVIDER } from "./unity-transport.mjs";
+const input = await readInput();
+const tool = String(input?.tool_name ?? "");
+const server = tool.startsWith("mcp__") ? (tool.split("__")[1] ?? "") : "";
+if (server && PROVIDER.test(server)) block(`Unity MCP tool ${tool} is disabled by the project's transport policy`);
+process.exit(0);

package/runtime/hooks/guard-shell.mjs

@@ -0,0 +1,16 @@
+// PreToolUse for Bash|PowerShell: block destructive git/filesystem commands and any Unity MCP route.
+import { readInput, block } from "./common.mjs";
+import { unityMcpViolation } from "./unity-transport.mjs";
+
+const input = await readInput();
+const cmd = String(input?.tool_input?.command ?? "");
+const DESTRUCTIVE = [
+  [/\bgit\s+(push\s+[^\n|;&]*(--force|-f\b)|reset\s+--hard|clean\s+-[a-z]*f|checkout\s+--\s+\.|restore\s+\.)/i, "destructive git command"],
+  [/\brm\s+-[a-z]*r[a-z]*f?\s+(\/|~|\.\.?(\s|$)|\*|Assets\b|Packages\b|ProjectSettings\b)/i, "recursive delete of a project root"],
+  [/\b(Remove-Item|rmdir|rd)\b[^\n]*\s(-Recurse|\/s)[^\n]*\s(\.|Assets|Packages|ProjectSettings|\*)\b/i, "recursive delete of a project root"],
+  [/\bgit\s+commit\s+[^\n]*--amend/i, "amending commits is reserved for the user"]
+];
+for (const [re, why] of DESTRUCTIVE) if (re.test(cmd)) block(`${why}: ${cmd.slice(0, 120)}`);
+const mcp = unityMcpViolation(cmd);
+if (mcp) block(mcp);
+process.exit(0);

package/runtime/hooks/guard-write.mjs

@@ -0,0 +1,25 @@
+// PreToolUse for Write|Edit|MultiEdit|NotebookEdit:
+//  - block edits to vendored Unity skills and to evidence that only `task verify` may write
+//  - warn (never block) on hand-editing serialized Unity assets
+import path from "node:path";
+import { readInput, root, block, warn } from "./common.mjs";
+import { readJson } from "../core/fs.mjs";
+
+const input = await readInput();
+const raw = String(input?.tool_input?.file_path ?? input?.tool_input?.path ?? input?.tool_input?.notebook_path ?? "");
+if (!raw) process.exit(0);
+const project = root();
+const rel = path.relative(project, path.resolve(project, raw)).split(path.sep).join("/");
+
+if (rel.startsWith(".claude/skills/")) {
+  const skill = rel.split("/")[2];
+  let vendored = [];
+  try { vendored = readJson(path.join(project, ".claude/nccgs/unity-skills-manifest.json")).skills.map(s => s.name); } catch {}
+  if (vendored.includes(skill)) block(`'${skill}' is a vendored official Unity Skill; project guidance belongs in CLAUDE.md or .claude/nccgs/protocols/`);
+}
+if (/^\.nccgs\/evidence\/(measurements|screens)\//.test(rel)) block("evidence under measurements/ and screens/ is written only by `task verify`");
+if (/^\.nccgs\/(tasks|reports|cache)\//.test(rel)) block("task records, reports and the snapshot cache are written only by the task CLI");
+if (/\.(unity|prefab|asset|meta|controller|anim|physicMaterial|lighting)$/i.test(rel) && !/^\.nccgs\//.test(rel)) {
+  warn("PreToolUse", `hand-editing a serialized Unity asset (${rel}). Prefer \`unity command\` (scene/prefab/component groups) so GUIDs and references stay valid; if you must edit, keep the YAML header and fileIDs intact.`);
+}
+process.exit(0);

package/runtime/hooks/session-log.mjs

@@ -0,0 +1,7 @@
+// SubagentStart/SubagentStop/PostToolUse(Agent): append usage and agent events to .nccgs/events.jsonl.
+import { readInput, log } from "./common.mjs";
+const input = await readInput();
+const type = process.argv[2] || input?.hook_event_name || "event";
+const usage = input?.tool_response?.usage ?? input?.usage ?? null;
+log(`agent.${type}`, { sessionId: input?.session_id ?? null, transcriptPath: input?.transcript_path ?? null, agentTranscriptPath: input?.agent_transcript_path ?? null, agent: input?.tool_input?.subagent_type ?? input?.agent_type ?? null, agentId: input?.agent_id ?? null, model: input?.tool_response?.model ?? input?.model ?? null, usage });
+process.exit(0);

package/runtime/hooks/session-start.mjs

@@ -0,0 +1,40 @@
+// SessionStart: inject the project's Unity versions, open tasks and (cached) update notices.
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { readInput, root, log } from "./common.mjs";
+import { versionLine, loadConfig, at } from "../core/project.mjs";
+import { openTasks } from "../task/ledger.mjs";
+import { readJson, exists, readText } from "../core/fs.mjs";
+import { autoFeedback } from "../task/feedback.mjs";
+import { markSuggested, CONSENT_TEXT } from "../core/feedback-policy.mjs";
+
+const input = await readInput();
+const project = root();
+const lines = [];
+try {
+  const cli = spawnSync(process.env.NCCGS_UNITY_BIN || "unity", [...(process.env.NCCGS_UNITY_ARGS ? process.env.NCCGS_UNITY_ARGS.split("|") : []), "--version"], { encoding: "utf8", timeout: 8000, windowsHide: true });
+  lines.push(`NCCGS project: ${versionLine(project, cli.status === 0 ? cli.stdout.trim() : null)}`);
+} catch { lines.push(`NCCGS project: ${versionLine(project, null)}`); }
+try {
+  const config = loadConfig(project);
+  lines.push(`NCCGS mode ${config.mode} · rigor ${config.rigor} · autonomy ${config.autonomy}`);
+  const open = openTasks(project);
+  if (open.length) lines.push(`Open tasks: ${open.map(t => `${t.id} (${t.status}, ${t.rigor})`).join(", ")}`);
+  const state = readText(at(project, "state"));
+  const recent = state.split("\n").filter(l => l.startsWith("- ")).slice(0, 3);
+  if (recent.length) lines.push(`Recent: ${recent.join(" | ")}`);
+  const check = at(project, "updateCheck");
+  if (exists(check)) {
+    const u = readJson(check);
+    const notices = (u.notices ?? []).map(n => `${n.component} ${n.current} -> ${n.latest} (${n.hint})`);
+    if (notices.length) lines.push(`Updates available (not applied): ${notices.join("; ")}`);
+  }
+} catch {}
+try {
+  const fb = await autoFeedback(project, { trigger: "session-start" });
+  if (fb.action === "ask-consent") lines.push(`FEEDBACK CONSENT NOT SET. Before other work, ask the user once with AskUserQuestion (options: auto / manual / off) using this text: ${CONSENT_TEXT.en} Then run \`npx nccgs feedback --project . --consent <choice>\` and continue. Reasons it came up now: ${fb.reasons.join("; ")}.`);
+  else if (fb.action === "suggest") { markSuggested(project); lines.push(`NCCGS noticed issues since the last feedback (${fb.reasons.join("; ")}). Suggest to the user, once, that \`/feedback\` would send a bundle for review; do not run it without their yes.`); }
+  else if (fb.action === "send") lines.push(fb.sent?.ok ? `Feedback bundle sent automatically (consent auto): ${fb.reasons.join("; ")}. Mention it in one line.` : `Feedback bundle could not be sent (${fb.sent?.reason ?? "unknown"}); it is saved under .nccgs/feedback/. Mention it in one line.`);
+} catch {}
+log("session.start", { sessionId: input?.session_id ?? null, transcriptPath: input?.transcript_path ?? null, model: input?.model ?? null });
+process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }) + "\n");