nccgs 2.1.1 → 3.0.0-rc.2

package/runtime/task/project.mjs

@@ -0,0 +1,79 @@
+// Project page: .nccgs/project.html, one self-contained page a producer can read without Unity.
+// Everything on it comes from the ledger, the reports, state.md and the transcripts; nothing is written by hand.
+import path from "node:path";
+import { writeText, readText, exists, toPosix } from "../core/fs.mjs";
+import { at, loadConfig, editorVersion, pipelineVersion } from "../core/project.mjs";
+import { listTasks } from "./ledger.mjs";
+import { reportModel, esc, dataUri, CSS, tile, EN, VI } from "./report.mjs";
+import { fmtTokens } from "./cost.mjs";
+
+export function projectModel(root) {
+  const config = loadConfig(root);
+  const tasks = listTasks(root);
+  const models = tasks.map(t => { try { return reportModel(root, t); } catch { return null; } }).filter(Boolean);
+  const closed = models.filter(m => m.task.status === "closed");
+  const success = closed.filter(m => m.task.outcome === "success");
+  const open = models.filter(m => m.task.status !== "closed");
+  const findings = [];
+  for (const m of models) for (const f of m.findings) if (!f.resolved) findings.push({ task: m.task.id, title: m.task.title, ...f });
+  const bySeverity = { BLOCKER: 0, HIGH: 0, MEDIUM: 0, LOW: 0, INFO: 0 };
+  for (const f of findings) bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+  const tokens = models.reduce((a, m) => ({ in: a.in + (m.cost?.total ? m.cost.total.input + m.cost.total.cacheWrite + m.cost.total.cacheRead : 0), out: a.out + (m.cost?.total?.output ?? 0), usd: a.usd + (m.cost?.estimatedUsd ?? 0) }), { in: 0, out: 0, usd: 0 });
+  const lastTests = models.find(m => m.tests)?.tests ?? null;
+  const state = readText(at(root, "state"), "");
+  const decisions = state.split("\n").filter(l => l.startsWith("- ")).slice(0, 12);
+  const stateFile = exists(at(root, "installState")) ? JSON.parse(readText(at(root, "installState"), "{}")) : {};
+  return {
+    lang: config.report?.language === "vi" ? "vi" : "en",
+    project: { name: config.name || path.basename(root), editor: editorVersion(root), pipeline: pipelineVersion(root), nccgs: stateFile.version ?? null, mode: config.mode, rigor: config.rigor },
+    models, closed, success, open, findings, bySeverity, tokens, lastTests, decisions, generatedAt: new Date().toISOString()
+  };
+}
+
+export function renderProject(root) {
+  const m = projectModel(root);
+  const t = { ...(m.lang === "vi" ? VI : EN), ...(m.lang === "vi" ? PVI : PEN) };
+  const h = [];
+  h.push(`<main><h1>${esc(m.project.name)} <span class="sub">· ${t.projectPage}</span></h1>`);
+  h.push(`<div class="sub">Unity ${esc(m.project.editor ?? "?")} · Pipeline ${esc(m.project.pipeline ?? "?")} · NCCGS ${esc(m.project.nccgs ?? "?")} · ${t.mode} ${esc(m.project.mode)} · ${t.rigor} ${esc(m.project.rigor)} · ${esc(m.generatedAt.slice(0, 16).replace("T", " "))} UTC</div>`);
+  h.push(`<div class="tiles">`);
+  h.push(tile(`${m.success.length}/${m.closed.length}`, t.tasksSuccess));
+  h.push(tile(String(m.open.length), t.tasksOpen));
+  h.push(tile(m.lastTests ? `${m.lastTests.passed}/${m.lastTests.total}` : "–", t.latestTests));
+  h.push(tile(`${m.bySeverity.BLOCKER + m.bySeverity.HIGH} / ${m.bySeverity.MEDIUM} / ${m.bySeverity.LOW}`, t.findingsOpen));
+  h.push(tile(m.tokens.out ? fmtTokens(m.tokens.out) : "–", t.tokensOut));
+  h.push(tile(m.tokens.usd ? `$${m.tokens.usd.toFixed(2)}` : "–", t.estimatedUsd));
+  h.push(`</div>`);
+  h.push(`<h2>${t.tasks}</h2><table><tr><th>${t.task}</th><th>${t.outcome}</th><th>${t.criteria}</th><th>${t.tests}</th><th>${t.review}</th><th>${t.fixRounds}</th><th>${t.tokensOut}</th><th>${t.closedAt}</th><th>${t.report}</th></tr>`);
+  for (const x of m.models) {
+    const task = x.task;
+    const outcome = task.status === "closed" ? task.outcome : task.status;
+    const html = path.join(at(root, "reports"), `${task.id}.html`);
+    h.push(`<tr><td><b>${esc(task.id)}</b><div class="sub">${esc(task.title)}</div></td><td><span class="chip ${esc(outcome)}">${esc(String(outcome).toUpperCase())}</span></td><td>${x.evaluation.summary.pass}/${x.evaluation.summary.total}</td><td>${x.tests ? `${x.tests.passed}/${x.tests.total}` : "–"}</td><td>${x.review ? `${esc(x.review.verdict)}<div class="sub">${esc(x.review.model ?? "")}</div>` : "–"}</td><td>${task.fixRounds}/${task.maxFixRounds}</td><td>${x.cost?.total?.messages ? fmtTokens(x.cost.total.output) : "–"}</td><td>${esc((task.closedAt ?? task.openedAt).slice(0, 10))}</td><td>${exists(html) ? `<a href="${esc(toPosix(path.relative(at(root, "nccgs"), html)))}">html</a>` : ""} <a href="${esc(toPosix(path.relative(at(root, "nccgs"), path.join(at(root, "reports"), `${task.id}.md`))))}">md</a></td></tr>`);
+  }
+  h.push(`</table>`);
+  const shots = m.models.map(x => ({ id: x.task.id, s: x.screens.at(-1) })).filter(x => x.s).slice(0, 8);
+  if (shots.length) {
+    h.push(`<h2>${t.latestScreens}</h2><div class="shots">`);
+    for (const { id, s } of shots) { const uri = dataUri(path.resolve(root, s.path)); if (uri) h.push(`<figure><img src="${uri}" alt="${esc(id)}"><figcaption>${esc(id)} · ${esc(path.basename(s.path))}${s.gameTimeS != null ? ` · t = ${s.gameTimeS.toFixed(2)} s` : ""}</figcaption></figure>`); }
+    h.push(`</div>`);
+  }
+  h.push(`<h2>${t.findingsOpenTitle}</h2>`);
+  if (m.findings.length) {
+    h.push(`<table><tr><th>${t.severity}</th><th>${t.task}</th><th>${t.finding}</th></tr>`);
+    const order = { BLOCKER: 0, HIGH: 1, MEDIUM: 2, LOW: 3, INFO: 4 };
+    for (const f of [...m.findings].sort((a, b) => (order[a.severity] ?? 9) - (order[b.severity] ?? 9))) h.push(`<tr><td><span class="sev ${esc(f.severity)}">${esc(f.severity)}</span></td><td>${esc(f.task)}</td><td>${esc(f.title ?? f.summary ?? "")}${f.detail ? `<div class="sub">${esc(String(f.detail).length > 300 ? String(f.detail).slice(0, 300).replace(/\s+\S*$/, "") + " …" : f.detail)}</div>` : ""}</td></tr>`);
+    h.push(`</table>`);
+  } else h.push(`<p class="sub">${t.noFindings}</p>`);
+  h.push(`<h2>${t.decisionsTitle}</h2>`);
+  if (m.decisions.length) { h.push(`<ul>`); for (const d of m.decisions) h.push(`<li>${esc(d.slice(2).replace(/\s·\s\[report\]\([^)]*\)/, ""))}</li>`); h.push(`</ul>`); }
+  else h.push(`<p class="sub">${t.noDecisions}</p>`);
+  h.push(`<p class="sub">${t.generatedBy}</p></main>`);
+  const html = `<!doctype html><html lang="${m.lang}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(m.project.name)} · NCCGS</title><style>${CSS}</style></head><body>${h.join("\n")}</body></html>`;
+  const file = path.join(at(root, "nccgs"), "project.html");
+  writeText(file, html);
+  return { file, model: m };
+}
+
+const PEN = { projectPage: "project page", tasksSuccess: "tasks closed SUCCESS", tasksOpen: "tasks open", latestTests: "tests (latest task)", findingsOpen: "open findings H / M / L", estimatedUsd: "est. cost", tasks: "Tasks", task: "Task", outcome: "Outcome", closedAt: "Closed", report: "Report", latestScreens: "Latest frame per task", findingsOpenTitle: "Open review findings", severity: "Severity", finding: "Finding", noFindings: "No open findings.", decisionsTitle: "Recent closes (state.md)", noDecisions: "Nothing recorded yet.", generatedBy: "Generated by NCCGS from the task ledger, reports and transcripts. Nothing on this page was written by hand." };
+const PVI = { projectPage: "trang dự án", tasksSuccess: "task đóng SUCCESS", tasksOpen: "task đang mở", latestTests: "test (task mới nhất)", findingsOpen: "finding mở H / M / L", estimatedUsd: "chi phí ước tính", tasks: "Task", task: "Task", outcome: "Kết quả", closedAt: "Đóng", report: "Report", latestScreens: "Frame mới nhất mỗi task", findingsOpenTitle: "Finding review còn mở", severity: "Mức", finding: "Finding", noFindings: "Không còn finding mở.", decisionsTitle: "Các lần đóng gần đây (state.md)", noDecisions: "Chưa ghi gì.", generatedBy: "NCCGS sinh từ ledger, report và transcript. Không dòng nào viết tay." };

package/runtime/task/report.mjs

@@ -0,0 +1,252 @@
+// Task report: one page for a person, generated from the ledger (never free-written).
+// `reportModel` gathers the facts once; `renderReport` writes <id>.md and <id>.html from it.
+// The HTML embeds the screenshots, so the file can be mailed or dropped in a chat on its own.
+import path from "node:path";
+import fs from "node:fs";
+import { writeText, toPosix, readText, exists } from "../core/fs.mjs";
+import { at, loadConfig, editorVersion } from "../core/project.mjs";
+import { evaluate } from "./criteria.mjs";
+import { inScope } from "../core/snapshot.mjs";
+import { taskCost, fmtTokens } from "./cost.mjs";
+
+const STATUS_WORD = { PASS: "pass", FAIL: "FAIL", UNVERIFIED: "unverified", PENDING: "pending" };
+
+export function reportModel(root, task, { outcome = task.outcome ?? "open", changedFiles = task.changedFiles ?? [] } = {}) {
+  const config = loadConfig(root);
+  const evaluation = evaluate(root, task.criteria, { manualDecisions: task.manualDecisions });
+  const review = task.reviews.at(-1);
+  const screens = [...new Map(task.verifications.flatMap(v => v.screens ?? []).map(s => [s.path, s])).values()].filter(s => s.path);
+  // Test runs count only on the task's final snapshot: exploratory runs on earlier snapshots (a probe with
+  // --name, a red run before the fix) are history, not the result.
+  const finalSnapshot = task.snapshotAtClose?.sha ?? task.verifications.at(-1)?.snapshot ?? null;
+  const testRuns = [...new Map(task.verifications.filter(v => v.kind === "tests" && (!finalSnapshot || v.snapshot === finalSnapshot)).map(v => [v.name, v])).values()];
+  const tests = testRuns.length ? testRuns.reduce((acc, v) => ({ passed: acc.passed + (v.summary.passed ?? 0), failed: acc.failed + (v.summary.failed ?? 0), skipped: acc.skipped + (v.summary.skipped ?? 0), total: acc.total + (v.summary.total ?? 0), failures: [...acc.failures, ...(v.summary.failures ?? [])] }), { passed: 0, failed: 0, skipped: 0, total: 0, failures: [] }) : null;
+  const observe = [...task.verifications].reverse().find(v => v.kind === "observe");
+  const observeJson = observe?.artifact && exists(path.resolve(root, observe.artifact)) ? JSON.parse(readText(path.resolve(root, observe.artifact), "{}")) : null;
+  const metas = changedFiles.filter(f => f.endsWith(".meta"));
+  const sources = changedFiles.filter(f => !f.endsWith(".meta"));
+  let cost = null;
+  try { cost = taskCost(root, task, { config }); } catch { cost = null; }
+  const findings = (review?.findings ?? []).map(f => ({ ...f, severity: (f.severity ?? "INFO").toUpperCase() }));
+  return {
+    lang: config.report?.language === "vi" ? "vi" : "en",
+    project: { name: config.name || path.basename(root), editor: editorVersion(root), mode: task.mode, rigor: task.rigor },
+    task, outcome, evaluation, review, findings, screens, testRuns, tests, observe: observeJson,
+    changes: { sources: sources.map(f => ({ path: f, inScope: inScope(f, task.files) })), metas, strayMetas: metas.filter(f => !inScope(f, task.files)) },
+    cost,
+    decisions: { pending: evaluation.rows.filter(r => r.status === "PENDING"), openFindings: findings.filter(f => !f.resolved && /HIGH|BLOCKER/.test(f.severity)) },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+export function renderReport(root, task, options = {}) {
+  const m = reportModel(root, task, options);
+  const dir = at(root, "reports");
+  const md = renderMarkdown(root, m);
+  const html = renderHtml(root, m);
+  const file = path.join(dir, `${task.id}.md`);
+  const htmlFile = path.join(dir, `${task.id}.html`);
+  writeText(file, md);
+  writeText(htmlFile, html);
+  return { file, htmlFile, markdown: md, model: m };
+}
+
+function renderMarkdown(root, m) {
+  const t = m.lang === "vi" ? VI : EN;
+  const { task, evaluation, review, tests, testRuns, screens } = m;
+  const lines = [];
+  lines.push(`# ${task.id} · ${task.title} · ${m.outcome.toUpperCase()} · ${m.generatedAt.slice(0, 10)}`, "");
+  lines.push(`**${t.summary}.** ${summaryLine(t, m)}`, "");
+  lines.push(`## ${t.criteria}`, "", `| ID | ${t.description} | ${t.result} | ${t.evidence} |`, "| --- | --- | --- | --- |");
+  for (const row of evaluation.rows) {
+    const ev = row.assertions.map(a => a.artifact.split("/").pop() + (a.pointer ? `#${a.pointer}` : "")).join(", ") || (row.kind === "manual" ? t.manual : "");
+    lines.push(`| ${row.id} | ${row.description} | ${STATUS_WORD[row.status]} | ${ev} |`);
+  }
+  lines.push("");
+  if (screens.length) {
+    lines.push(`## ${t.screens}`, "");
+    for (const s of screens.slice(-4)) lines.push(`![${path.basename(s.path)}${s.gameTimeS != null ? ` · t=${s.gameTimeS.toFixed(2)}s` : ""}](${toPosix(path.relative(at(root, "reports"), path.resolve(root, s.path)))})`);
+    lines.push("");
+  }
+  if (tests) {
+    lines.push(`## ${t.tests}`, "");
+    for (const v of testRuns) lines.push(`- ${v.name} (${v.summary.mode ?? "?"}): ${t.testsLine(v.summary)}`);
+    lines.push("");
+    for (const f of tests.failures.slice(0, 10)) lines.push(`- ${f.name}: ${f.message || ""}`);
+    if (tests.failures.length) lines.push("");
+  }
+  lines.push(`## ${t.changes}`, "");
+  if (m.changes.sources.length) for (const f of m.changes.sources.slice(0, 60)) lines.push(`- ${f.path}${f.inScope ? "" : ` ${t.outsideContract}`}`);
+  else lines.push(t.noChanges);
+  if (m.changes.metas.length) lines.push(`- ${t.metaLine(m.changes.metas.length)}${m.changes.strayMetas.length ? ` · ${t.outsideContract}: ${m.changes.strayMetas.join(", ")}` : ""}`);
+  lines.push("");
+  lines.push(`## ${t.review}`, "");
+  if (review) {
+    lines.push(`${review.verdict} (${review.model ?? "model unknown"}${review.effort ? "/" + review.effort : ""}, snapshot ${review.snapshot?.slice(0, 8) ?? "?"})`, "");
+    for (const f of m.findings) lines.push(`- ${f.severity}: ${f.title ?? f.summary ?? ""}${findingState(t, f)}`);
+    if (review.screensViewed?.length) lines.push("", `${t.screensViewed}: ${[...new Set(review.screensViewed)].join(", ")}`);
+  } else lines.push(task.rigor === "prototype" ? t.noReviewPrototype : t.noReview);
+  lines.push("");
+  lines.push(`## ${t.cost}`, "", costLine(t, m), "");
+  if (m.cost?.total?.messages) {
+    for (const [agent, v] of Object.entries(m.cost.byAgent)) lines.push(`- ${agent}: ${fmtTokens(v.input + v.cacheWrite + v.cacheRead)} in (${fmtTokens(v.cacheRead)} cached) · ${fmtTokens(v.output)} out · ${v.messages} ${t.messages}`);
+    for (const [model, v] of Object.entries(m.cost.byModel)) lines.push(`- ${model}: ${fmtTokens(v.input + v.cacheWrite + v.cacheRead)} in · ${fmtTokens(v.output)} out`);
+    lines.push("");
+  }
+  if (task.notes) lines.push(`## ${t.howToPlay}`, "", task.notes, "");
+  if (m.decisions.pending.length || m.decisions.openFindings.length) {
+    lines.push(`## ${t.decisions}`, "");
+    for (const r of m.decisions.pending) lines.push(`- [ ] ${r.description}`);
+    for (const f of m.decisions.openFindings) lines.push(`- [ ] ${f.title ?? f.summary}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function findingState(t, f) {
+  return f.resolved ? (f.resolvedBy ? ` (${t.resolvedBy(f.resolvedBy)}${f.resolvedReason ? `: ${f.resolvedReason}` : ""})` : ` (${t.resolved})`) : ` (${t.open})`;
+}
+
+function summaryLine(t, m) {
+  const parts = [`${t.criteriaShort} ${m.evaluation.summary.pass}/${m.evaluation.summary.total}`];
+  if (m.tests) parts.push(`${t.testsShort} ${m.tests.passed}/${m.tests.total}`);
+  if (m.review) parts.push(`${t.reviewShort} ${m.review.verdict}`);
+  parts.push(`${t.fixRounds} ${m.task.fixRounds}/${m.task.maxFixRounds}`);
+  if (m.cost?.total?.messages) parts.push(`${fmtTokens(m.cost.total.output)} ${t.tokensOut}`);
+  return parts.join(" · ") + ".";
+}
+
+function costLine(t, m) {
+  const base = `${m.task.verifications.length} ${t.verifyRuns} · ${m.task.fixRounds} ${t.fixRounds}`;
+  if (!m.cost?.total?.messages) return `${base} · ${t.noTranscript}`;
+  const c = m.cost.total;
+  const usd = m.cost.estimatedUsd != null ? ` · ≈ $${m.cost.estimatedUsd}${m.cost.unpricedModels ? ` (${m.cost.unpricedModels} ${t.unpriced})` : ""}` : "";
+  return `${base} · ${c.messages} ${t.messages} · ${fmtTokens(c.input + c.cacheWrite + c.cacheRead)} ${t.tokensIn} (${fmtTokens(c.cacheRead)} ${t.cached}) · ${fmtTokens(c.output)} ${t.tokensOut}${usd}`;
+}
+
+// ---- HTML --------------------------------------------------------------------------------------
+
+export const esc = s => String(s ?? "").replace(/[&<>"]/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+export function dataUri(file) {
+  try { return `data:image/png;base64,${fs.readFileSync(file).toString("base64")}`; } catch { return null; }
+}
+export const CSS = `
+:root{--bg:#fff;--fg:#1b1b1b;--muted:#666;--line:#e3e3e3;--card:#f7f7f5;--ok:#1e8e3e;--bad:#c5221f;--warn:#b26a00;--info:#1a73e8;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+@media(prefers-color-scheme:dark){:root{--bg:#141414;--fg:#e8e8e8;--muted:#9a9a9a;--line:#2c2c2c;--card:#1d1d1d;--ok:#5bbf72;--bad:#f28b82;--warn:#f0b35a;--info:#8ab4f8}}
+body{margin:0;background:var(--bg);color:var(--fg);line-height:1.45}
+main{max-width:1100px;margin:0 auto;padding:24px 16px 48px}
+h1{font-size:1.5rem;margin:0 0 4px}h2{font-size:1.05rem;margin:28px 0 8px;border-bottom:1px solid var(--line);padding-bottom:4px}
+.sub{color:var(--muted);font-size:.9rem}
+.chip{display:inline-block;padding:2px 10px;border-radius:999px;font-size:.8rem;font-weight:600;color:#fff;vertical-align:middle}
+.chip.success,.chip.pass{background:var(--ok)}.chip.failed,.chip.fail,.chip.blocked{background:var(--bad)}.chip.partial,.chip.pending,.chip.unverified{background:var(--warn)}.chip.open{background:var(--info)}
+.tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:10px;margin:16px 0}
+.tile{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:10px 12px}.tile b{display:block;font-size:1.3rem}.tile span{color:var(--muted);font-size:.8rem}
+table{border-collapse:collapse;width:100%;font-size:.9rem}th,td{text-align:left;padding:6px 8px;border-bottom:1px solid var(--line);vertical-align:top}th{color:var(--muted);font-weight:600}
+.shots{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:12px}.shots figure{margin:0}.shots img{width:100%;border:1px solid var(--line);border-radius:8px;background:#000}.shots figcaption{font-size:.8rem;color:var(--muted);margin-top:4px}
+.sev{font-weight:700}.sev.BLOCKER,.sev.HIGH{color:var(--bad)}.sev.MEDIUM{color:var(--warn)}.sev.LOW,.sev.INFO{color:var(--muted)}
+.res{color:var(--muted);font-size:.85rem}
+ul{padding-left:20px}code{background:var(--card);padding:1px 4px;border-radius:4px;font-size:.85em}
+.outside{color:var(--bad)}
+a{color:var(--info)}
+`;
+
+function renderHtml(root, m) {
+  const t = m.lang === "vi" ? VI : EN;
+  const { task, evaluation, review, tests, testRuns, screens } = m;
+  const h = [];
+  h.push(`<main>`);
+  h.push(`<h1>${esc(task.id)} · ${esc(task.title)} <span class="chip ${esc(m.outcome)}">${esc(m.outcome.toUpperCase())}</span></h1>`);
+  h.push(`<div class="sub">${esc(m.project.name)} · Unity ${esc(m.project.editor ?? "?")} · ${t.rigor} ${esc(task.rigor)} · ${t.mode} ${esc(task.mode)} · ${esc(m.generatedAt.slice(0, 16).replace("T", " "))} UTC</div>`);
+  const c = m.cost?.total;
+  h.push(`<div class="tiles">`);
+  h.push(tile(`${evaluation.summary.pass}/${evaluation.summary.total}`, t.criteria));
+  h.push(tile(tests ? `${tests.passed}/${tests.total}` : "–", t.tests));
+  h.push(tile(review ? review.verdict : "–", t.review));
+  h.push(tile(`${task.fixRounds}/${task.maxFixRounds}`, t.fixRounds));
+  h.push(tile(c?.messages ? fmtTokens(c.output) : "–", t.tokensOut));
+  h.push(tile(c?.messages ? fmtTokens(c.input + c.cacheWrite + c.cacheRead) : "–", t.tokensIn));
+  h.push(`</div>`);
+  h.push(`<h2>${t.criteria}</h2><table><tr><th>ID</th><th>${t.description}</th><th>${t.result}</th><th>${t.evidence}</th></tr>`);
+  for (const row of evaluation.rows) {
+    const ev = row.assertions.map(a => esc(a.artifact.split("/").pop() + (a.pointer ? `#${a.pointer}` : ""))).join(", ") || (row.kind === "manual" ? t.manual : "");
+    h.push(`<tr><td><code>${esc(row.id)}</code></td><td>${esc(row.description)}</td><td><span class="chip ${esc(STATUS_WORD[row.status]).toLowerCase()}">${esc(STATUS_WORD[row.status])}</span></td><td>${ev}</td></tr>`);
+  }
+  h.push(`</table>`);
+  if (screens.length) {
+    h.push(`<h2>${t.screens}</h2><div class="shots">`);
+    for (const s of screens.slice(-6)) {
+      const uri = dataUri(path.resolve(root, s.path));
+      const cap = `${esc(path.basename(s.path))}${s.gameTimeS != null ? ` · t = ${s.gameTimeS.toFixed(2)} s` : s.atMs != null ? ` · +${s.atMs} ms` : ""}`;
+      h.push(`<figure>${uri ? `<img src="${uri}" alt="${esc(s.path)}">` : `<div class="sub">${esc(s.path)} (missing)</div>`}<figcaption>${cap}</figcaption></figure>`);
+    }
+    h.push(`</div>`);
+  }
+  if (tests) {
+    h.push(`<h2>${t.tests}</h2><ul>`);
+    for (const v of testRuns) h.push(`<li><b>${esc(v.name)}</b> (${esc(v.summary.mode ?? "?")}): ${esc(t.testsLine(v.summary))}</li>`);
+    for (const f of tests.failures.slice(0, 10)) h.push(`<li class="outside">${esc(f.name)}: ${esc(f.message || "")}</li>`);
+    h.push(`</ul>`);
+  }
+  h.push(`<h2>${t.changes}</h2><ul>`);
+  if (m.changes.sources.length) for (const f of m.changes.sources.slice(0, 60)) h.push(`<li><code>${esc(f.path)}</code>${f.inScope ? "" : ` <span class="outside">${t.outsideContract}</span>`}</li>`);
+  else h.push(`<li>${t.noChanges}</li>`);
+  if (m.changes.metas.length) h.push(`<li class="sub">${esc(t.metaLine(m.changes.metas.length))}${m.changes.strayMetas.length ? ` · <span class="outside">${t.outsideContract}: ${esc(m.changes.strayMetas.join(", "))}</span>` : ""}</li>`);
+  h.push(`</ul>`);
+  h.push(`<h2>${t.review}</h2>`);
+  if (review) {
+    h.push(`<p><span class="chip ${review.verdict === "PASS" ? "pass" : "fail"}">${esc(review.verdict)}</span> <span class="sub">${esc(review.model ?? "model unknown")}${review.effort ? "/" + esc(review.effort) : ""} · snapshot ${esc(review.snapshot?.slice(0, 8) ?? "?")}</span></p><ul>`);
+    for (const f of m.findings) h.push(`<li><span class="sev ${esc(f.severity)}">${esc(f.severity)}</span> ${esc(f.title ?? f.summary ?? "")} <span class="res">${esc(findingState(t, f).trim())}</span>${f.detail ? `<div class="sub">${esc(f.detail)}</div>` : ""}</li>`);
+    h.push(`</ul>`);
+    if (review.screensViewed?.length) h.push(`<p class="sub">${t.screensViewed}: ${esc([...new Set(review.screensViewed)].join(", "))}</p>`);
+  } else h.push(`<p class="sub">${task.rigor === "prototype" ? t.noReviewPrototype : t.noReview}</p>`);
+  h.push(`<h2>${t.cost}</h2><p>${esc(costLine(t, m))}</p>`);
+  if (c?.messages) {
+    h.push(`<table><tr><th>${t.who}</th><th>${t.tokensIn}</th><th>${t.cached}</th><th>${t.tokensOut}</th><th>${t.messages}</th></tr>`);
+    for (const [agent, v] of Object.entries(m.cost.byAgent)) h.push(`<tr><td>${esc(agent)}</td><td>${fmtTokens(v.input + v.cacheWrite + v.cacheRead)}</td><td>${fmtTokens(v.cacheRead)}</td><td>${fmtTokens(v.output)}</td><td>${v.messages}</td></tr>`);
+    for (const [model, v] of Object.entries(m.cost.byModel)) h.push(`<tr><td><code>${esc(model)}</code></td><td>${fmtTokens(v.input + v.cacheWrite + v.cacheRead)}</td><td>${fmtTokens(v.cacheRead)}</td><td>${fmtTokens(v.output)}</td><td>${v.messages}</td></tr>`);
+    h.push(`</table>`);
+  }
+  if (task.notes) h.push(`<h2>${t.howToPlay}</h2><p>${esc(task.notes)}</p>`);
+  if (m.decisions.pending.length || m.decisions.openFindings.length) {
+    h.push(`<h2>${t.decisions}</h2><ul>`);
+    for (const r of m.decisions.pending) h.push(`<li>☐ ${esc(r.description)}</li>`);
+    for (const f of m.decisions.openFindings) h.push(`<li>☐ ${esc(f.title ?? f.summary)}</li>`);
+    h.push(`</ul>`);
+  }
+  h.push(`<p class="sub">${t.generatedBy}</p></main>`);
+  return `<!doctype html><html lang="${m.lang}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(task.id)} · ${esc(task.title)}</title><style>${CSS}</style></head><body>${h.join("\n")}</body></html>`;
+}
+
+export const tile = (value, label) => `<div class="tile"><b>${esc(value)}</b><span>${esc(label)}</span></div>`;
+
+// Append a short entry to .nccgs/state.md so the next session starts from facts.
+export function appendState(root, task, outcome, reportFile) {
+  const file = at(root, "state");
+  const existing = readText(file, "# Project state\n\nMaintained by `task close`. Newest first.\n\n");
+  const entry = `- ${new Date().toISOString().slice(0, 10)} · ${task.id} · ${task.title} · ${outcome.toUpperCase()} · [report](${toPosix(path.relative(root, reportFile))})\n`;
+  const marker = "Newest first.\n\n";
+  const idx = existing.indexOf(marker);
+  const next = idx >= 0 ? existing.slice(0, idx + marker.length) + entry + existing.slice(idx + marker.length) : existing + entry;
+  writeText(file, next);
+}
+
+export const EN = {
+  summary: "Summary", criteria: "Criteria", description: "Description", result: "Result", evidence: "Evidence", manual: "person decides",
+  screens: "Screens", tests: "Tests", changes: "Changes", review: "Review", cost: "Cost", howToPlay: "How to try it", decisions: "Needs your decision",
+  outsideContract: "(outside the contract)", noChanges: "No source changes recorded.", resolved: "resolved", open: "open", resolvedBy: by => `resolved by ${by}`, metaLine: n => `${n} .meta file${n === 1 ? "" : "s"} for the files above`, screensViewed: "Screens viewed by the reviewer",
+  noReview: "No independent review recorded.", noReviewPrototype: "No review (prototype rigor).",
+  criteriaShort: "criteria", testsShort: "tests", reviewShort: "review", fixRounds: "fix rounds", verifyRuns: "verification runs", rigor: "rigor", mode: "mode",
+  tokensIn: "tokens in", tokensOut: "tokens out", cached: "cached", messages: "messages", who: "Who", unpriced: "models without a price row", noTranscript: "token usage unavailable (no Claude Code transcript recorded for this window)",
+  generatedBy: "Generated by NCCGS from the task ledger. Nothing on this page was written by hand.",
+  testsLine: s => `${s.passed} passed, ${s.failed} failed, ${s.skipped} skipped of ${s.total} (${s.source}${s.durationSec ? `, ${s.durationSec}s` : ""}).`
+};
+export const VI = {
+  summary: "Tóm tắt", criteria: "Tiêu chí", description: "Mô tả", result: "Kết quả", evidence: "Bằng chứng", manual: "người quyết",
+  screens: "Ảnh", tests: "Test", changes: "Thay đổi", review: "Review", cost: "Chi phí", howToPlay: "Cách chơi thử", decisions: "Cần bạn quyết",
+  outsideContract: "(ngoài hợp đồng)", noChanges: "Không ghi nhận thay đổi source.", resolved: "đã xử lý", open: "còn mở", resolvedBy: by => `${by} đã xử lý`, metaLine: n => `${n} file .meta của các file trên`, screensViewed: "Ảnh reviewer đã xem",
+  noReview: "Chưa có review độc lập.", noReviewPrototype: "Không review (rigor prototype).",
+  criteriaShort: "tiêu chí", testsShort: "test", reviewShort: "review", fixRounds: "vòng sửa", verifyRuns: "lần verify", rigor: "rigor", mode: "mode",
+  tokensIn: "token vào", tokensOut: "token ra", cached: "cache", messages: "lượt gọi", who: "Ai", unpriced: "model chưa có giá", noTranscript: "chưa có số token (không ghi được transcript Claude Code cho khoảng này)",
+  generatedBy: "NCCGS sinh từ ledger của task. Không dòng nào viết tay.",
+  testsLine: s => `${s.passed} đạt, ${s.failed} lỗi, ${s.skipped} bỏ qua trên ${s.total} (${s.source}${s.durationSec ? `, ${s.durationSec}s` : ""}).`
+};

package/runtime/task/task.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// `node .claude/nccgs/runtime/task/task.mjs <command> ...`
+// Commands: open | verify | review | close | inspect | list | fix
+// Output is JSON on stdout so Claude can read it; errors go to stderr with exit code 1.
+import path from "node:path";
+import fs from "node:fs";
+import { projectRoot, at, loadConfig, isUnityProject } from "../core/project.mjs";
+import { readJson, writeJson, writeText, exists, nowIso, toPosix } from "../core/fs.mjs";
+import { snapshot, changedFiles, inScope } from "../core/snapshot.mjs";
+import { run } from "../core/process-tree.mjs";
+import * as unity from "../unity/unity.mjs";
+import { playtest } from "../unity/playtest.mjs";
+import { checkAssets } from "../unity/assets.mjs";
+import { openTask, loadTask, saveTask, listTasks, assess, recordVerification, readyToClose, event, reviewsNeeded, resolveFinding } from "./ledger.mjs";
+import { renderReport, appendState } from "./report.mjs";
+import { renderProject } from "./project.mjs";
+import { diag } from "../core/diag.mjs";
+import { autoFeedback } from "./feedback.mjs";
+import { loadPlan, planStatus, nextPlanned, planItem, savePlan } from "./plan.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 = {};
+for (let i = 0; i < own.length; i++) {
+  const a = own[i];
+  if (!a.startsWith("--")) continue;
+  const key = a.slice(2);
+  const next = own[i + 1];
+  if (next === undefined || next.startsWith("--")) opt[key] = true; else { opt[key] = next; i++; }
+}
+const root = projectRoot(opt.project);
+const out = value => process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+const fail = message => { try { diag(root, "task.error", { command, args: own.slice(0, 20), message }); } catch {} process.stderr.write(`task ${command}: ${message}\n`); process.exit(1); };
+const list = v => (typeof v === "string" ? v.split(",").map(s => s.trim()).filter(Boolean) : []);
+
+try {
+  if (!command || command === "help") {
+    out({ commands: ["open [--plan <id>]", "verify", "review [--resolve <index|title> --reason ...]", "close", "inspect", "list", "fix", "report --id", "project", "plan [--status|--next|--show <id>|--validate <file>]"], hint: "node .claude/nccgs/runtime/task/task.mjs <command> --id T ..." });
+  } else if (!isUnityProject(root)) {
+    fail(`${root} is not a Unity project (needs Assets/ and ProjectSettings/ProjectVersion.txt)`);
+  } else if (command === "open") await cmdOpen();
+  else if (command === "verify") await cmdVerify();
+  else if (command === "review") await cmdReview();
+  else if (command === "close") await cmdClose();
+  else if (command === "inspect") out(withAssessment(loadTask(root, need("id"))));
+  else if (command === "plan") {
+    const sub = opt.show ? "show" : opt.next ? "next" : opt.validate ? "validate" : "status";
+    if (sub === "validate") { const f = opt.validate === true ? undefined : path.resolve(root, opt.validate); const plan = f ? readJson(f) : loadPlan(root); out({ file: f ?? null, ok: true, tasks: plan.tasks.map(t => t.id), saved: f ? toPosix(path.relative(root, savePlan(root, plan))) : null }); }
+    else if (sub === "show") out(planItem(root, opt.show === true ? (nextPlanned(root)?.id ?? fail("no ready task")) : opt.show));
+    else if (sub === "next") out(nextPlanned(root) ?? { done: true });
+    else out({ plan: loadPlan(root).name ?? null, tasks: planStatus(root) });
+  }
+  else if (command === "report") { const task = loadTask(root, need("id")); const r = renderReport(root, task, { outcome: task.outcome ?? task.status, changedFiles: task.changedFiles ?? changesSinceOpen(task) }); out({ id: task.id, file: toPosix(path.relative(root, r.file)), html: toPosix(path.relative(root, r.htmlFile)), tokensOut: r.model.cost?.total?.output ?? null }); }
+  else if (command === "project") { const r = renderProject(root); out({ file: toPosix(path.relative(root, r.file)), closed: r.model.closed.length, success: r.model.success.length, open: r.model.open.map(x => x.task.id), findings: r.model.bySeverity }); }
+  else if (command === "list") out(listTasks(root).map(t => ({ id: t.id, title: t.title, rigor: t.rigor, status: t.status, outcome: t.outcome, openedAt: t.openedAt })));
+  else if (command === "fix") {
+    const task = loadTask(root, need("id"));
+    task.fixRounds += 1;
+    saveTask(root, task);
+    event(root, "task.fix", { id: task.id, round: task.fixRounds });
+    out({ id: task.id, fixRounds: task.fixRounds, maxFixRounds: task.maxFixRounds, exhausted: task.fixRounds >= task.maxFixRounds });
+  } else fail(`unknown command ${command}`);
+} catch (error) { try { diag(root, "task.exception", { command, args: own.slice(0, 20), error }); } catch {} fail(error.message); }
+
+// Content diff against the snapshot taken at open; mtime fallback for tasks opened before alpha.3.
+function changesSinceOpen(task) { return changedFiles(root, task.snapshotAtOpen?.sha, { sinceMs: Date.parse(task.openedAt) }); }
+function outside(task, changed) { return changed.filter(f => !inScope(f, task.files)); }
+
+function need(key) { if (!opt[key] || opt[key] === true) fail(`--${key} is required`); return opt[key]; }
+
+function withAssessment(task) {
+  const a = assess(root, task);
+  return { ...task, assessment: { criteria: a.evaluation.summary, rows: a.evaluation.rows.map(r => ({ id: r.id, status: r.status, reasons: r.assertions.filter(x => x.status !== "PASS").map(x => x.reason).filter(Boolean) })), stale: a.stale, currentSnapshot: a.snapshot.sha, reviewsNeeded: reviewsNeeded(task), reviewsPassed: task.reviews.filter(r => r.verdict === "PASS" && r.snapshot === a.snapshot.sha).length } };
+}
+
+async function cmdOpen() {
+  let criteria = [];
+  if (opt.criteria && opt.criteria !== true) criteria = readJson(path.resolve(root, opt.criteria));
+  if (opt["criteria-json"]) criteria = JSON.parse(opt["criteria-json"]);
+  if (criteria && !Array.isArray(criteria) && Array.isArray(criteria.criteria)) criteria = criteria.criteria;
+  let spec = { id: opt.id === true ? undefined : opt.id, title: opt.title === true ? "" : opt.title, rigor: opt.rigor === true ? undefined : opt.rigor, files: list(opt.files), criteria, notes: opt.notes === true ? "" : opt.notes ?? "" };
+  if (opt.plan) {
+    // --plan <id>: the contract comes from .nccgs/design/slice.json; flags on the command line override it.
+    const item = planItem(root, opt.plan === true ? (nextPlanned(root)?.id ?? fail("plan has no ready task")) : opt.plan);
+    spec = { id: item.id, title: spec.title || item.title, rigor: spec.rigor ?? item.rigor, files: spec.files.length ? spec.files : item.files, criteria: criteria.length ? criteria : item.criteria, notes: spec.notes || item.notes || "", plan: true };
+  }
+  const task = openTask(root, spec);
+  out({ id: task.id, rigor: task.rigor, criteria: task.criteria.map(c => c.id), maxFixRounds: task.maxFixRounds, reviewsNeeded: reviewsNeeded(task), unity: task.unity, next: `node .claude/nccgs/runtime/task/task.mjs verify --id ${task.id} --kind tests|observe|console|command` });
+}
+
+async function cmdVerify() {
+  const task = loadTask(root, need("id"));
+  if (task.status === "closed") fail("task is closed");
+  const kind = opt.kind === true ? "tests" : (opt.kind ?? (forwarded.length ? "command" : "tests"));   // tests|observe|console|playtest|assets|command
+  const measurements = at(root, "measurements");
+  fs.mkdirSync(measurements, { recursive: true });
+  let record;
+  if (kind === "tests") {
+    const mode = opt.mode === true ? undefined : opt.mode;
+    const result = await unity.testRun(root, { mode, filter: opt.filter === true ? undefined : opt.filter, timeout: Number(opt.timeout) || 600 });
+    const name = opt.name === true || !opt.name ? "tests" : opt.name; // --name playmode -> <id>-playmode.json
+    const file = path.join(measurements, `${task.id}-${name}.json`);
+    const summary = { ok: result.ok, source: result.source, mode: result.mode, total: result.total ?? 0, passed: result.passed ?? 0, failed: result.failed ?? 0, skipped: result.skipped ?? 0, failures: result.failures ?? [], errors: result.errors ?? [], durationSec: result.durationSec ?? null, at: nowIso() };
+    writeJson(file, summary);
+    record = { kind, name, ok: result.ok && (result.failed ?? 0) === 0, artifact: toPosix(path.relative(root, file)), summary };
+  } else if (kind === "observe") {
+    const screensDir = path.join(at(root, "screens"), task.id);
+    const o = await unity.observe(root, { screensDir, frames: Number(opt.frames) || 2, keys: list(opt.keys), holdMs: Number(opt.hold) || 1500, keysEveryFrame: opt["keys-every-frame"] === true, matchLog: typeof opt["match-log"] === "string" ? opt["match-log"] : null, shotsMs: typeof opt.shots === "string" ? list(opt.shots).map(Number).filter(n => Number.isFinite(n)) : null, holdKeyMs: Number(opt["hold-key"]) || 60 });
+    const exceptionCount = (o.console?.groundTruth?.consoleErrors ?? 0) + (o.console?.entries ?? []).filter(e => /exception/i.test(e.message ?? e.text ?? "")).length;
+    const file = path.join(measurements, `${task.id}-observe.json`);
+    const summary = { enteredPlayMode: o.enteredPlayMode, exitedPlayMode: o.exitedPlayMode, exceptionCount, compilationFailed: o.console?.groundTruth?.compilationFailed ?? null, consoleCounts: o.console?.counts ?? null, screens: o.screens.map(s => ({ path: s.path ? toPosix(path.relative(root, s.path)) : null, bytes: s.bytes, ...(s.atMs != null ? { atMs: s.atMs, gameTimeS: s.gameTimeS ?? null } : {}) })), keys: o.keys, keyPresses: o.keys.length, logMatches: o.logMatches, matchLog: typeof opt["match-log"] === "string" ? opt["match-log"] : null, timed: o.timed, runInBackground: o.runInBackground ?? false, scheduleDelayMs: o.scheduleDelayMs ?? null, scheduledAtGameTime: o.scheduledAtGameTime ?? null, performance: o.performance, errors: o.errors, at: nowIso() };
+    writeJson(file, summary);
+    record = { kind, name: opt.name === true ? "observe" : (opt.name ?? "observe"), ok: o.enteredPlayMode && o.exitedPlayMode && o.errors.length === 0 && exceptionCount === 0, artifact: toPosix(path.relative(root, file)), screens: summary.screens.filter(s => s.path), summary: { exceptionCount, screens: summary.screens.length } };
+  } else if (kind === "console") {
+    const r = await unity.consoleGet(root, { tail: Number(opt.tail) || 100, level: opt.level === true ? "warn" : (opt.level ?? "warn") });
+    const file = path.join(measurements, `${task.id}-console.json`);
+    const summary = { ok: r.ok, counts: r.result?.counts ?? null, groundTruth: r.result?.groundTruth ?? null, entries: (r.result?.entries ?? []).slice(-50), errors: r.errors, at: nowIso() };
+    writeJson(file, summary);
+    const why = r.ok ? null : (r.errors?.[0]?.code === "EDITOR_NOT_RUNNING" || !(await unity.instanceFor(root)) ? "no Editor open for this project: open it (unity open --project-path .) and run again; console needs a live Editor" : `${r.errors?.[0]?.code ?? "UNITY_ERROR"}: ${r.errors?.[0]?.message ?? r.stderr?.slice(0, 200) ?? ""}`);
+    record = { kind, name: "console", ok: r.ok && (summary.groundTruth?.compilationFailed !== true), artifact: toPosix(path.relative(root, file)), summary: { errors: summary.counts?.error ?? null, compilationFailed: summary.groundTruth?.compilationFailed ?? null, ...(why ? { reason: why } : {}) } };
+  } else if (kind === "playtest") {
+    const specFile = opt.spec && opt.spec !== true ? path.resolve(root, opt.spec) : fail("playtest needs --spec <file.json> (see protocols/playtest.md)");
+    const spec = readJson(specFile);
+    const name = opt.name === true || !opt.name ? (spec.name ?? "playtest") : opt.name;
+    const o = await playtest(root, { ...spec, name }, { outDir: path.join(at(root, "measurements"), "playtest", task.id) });
+    const file = path.join(measurements, `${task.id}-playtest-${name}.json`);
+    const summary = { name, spec: toPosix(path.relative(root, specFile)), enteredPlayMode: o.enteredPlayMode, exitedPlayMode: o.exitedPlayMode, presses: o.presses ?? null, plannedPresses: o.keys, ranS: o.ranS ?? null, stoppedEarly: o.stoppedEarly ?? null, stoppedAtS: o.stoppedAtS ?? null, rulePresses: o.rulePresses ?? [], summary: o.summary, samples: o.samples, console: o.console, errors: o.errors, csv: o.csv ? toPosix(path.relative(root, o.csv)) : null, at: nowIso() };
+    writeJson(file, summary);
+    record = { kind, name: `playtest-${name}`, ok: o.enteredPlayMode && o.exitedPlayMode && o.errors.length === 0, artifact: toPosix(path.relative(root, file)), summary: { presses: summary.presses, ranS: summary.ranS, stoppedEarly: summary.stoppedEarly, ...Object.fromEntries(Object.entries(o.summary ?? {}).filter(([k]) => !["samples"].includes(k)).map(([k, v]) => [k, v && typeof v === "object" ? v.final : v])) } };
+  } else if (kind === "assets") {
+    const specFile = opt.spec && opt.spec !== true ? path.resolve(root, opt.spec) : fail("assets needs --spec <file.json> (see skills/asset-spec)");
+    const spec = readJson(specFile);
+    const a = await checkAssets(root, spec);
+    const file = path.join(measurements, `${task.id}-assets.json`);
+    const summary = { spec: toPosix(path.relative(root, specFile)), checked: a.assets.length, mismatchCount: a.mismatches.length, mismatches: a.mismatches, assets: a.assets, errors: a.errors, at: nowIso() };
+    writeJson(file, summary);
+    record = { kind, name: "assets", ok: a.ok && a.mismatches.length === 0, artifact: toPosix(path.relative(root, file)), summary: { checked: summary.checked, mismatchCount: summary.mismatchCount, ...(a.errors.length ? { reason: a.errors[0].message } : {}) } };
+  } else if (kind === "command") {
+    if (!forwarded.length) fail("command kind needs `-- <executable> [args]`");
+    const name = opt.name === true || !opt.name ? "command" : opt.name;
+    const r = await run(forwarded[0], forwarded.slice(1), { cwd: root, timeoutMs: (Number(opt.timeout) || 600) * 1000 });
+    const file = path.join(measurements, `${task.id}-${name}.json`);
+    const summary = { command: forwarded, exitCode: r.code, timedOut: r.timedOut, stdout: r.stdout.slice(-4000), stderr: r.stderr.slice(-4000), at: nowIso() };
+    writeJson(file, summary);
+    record = { kind, name, ok: r.code === 0 && !r.timedOut, artifact: toPosix(path.relative(root, file)), summary: { exitCode: r.code, timedOut: r.timedOut } };
+  } else fail(`unknown --kind ${kind}`);
+  recordVerification(root, task, record);
+  if (!record.ok) diag(root, "verify.failed", { id: task.id, verifyKind: kind, name: record.name, summary: record.summary });
+  const a = assess(root, task);
+  out({ id: task.id, verification: record, criteria: a.evaluation.summary, rows: a.evaluation.rows.map(r => ({ id: r.id, status: r.status, reasons: r.assertions.filter(x => x.status !== "PASS").map(x => `${x.artifact}${x.pointer ?? ""}: ${x.reason}`) })) });
+}
+
+async function cmdReview() {
+  const task = loadTask(root, need("id"));
+  const dir = at(root, "review");
+  fs.mkdirSync(dir, { recursive: true });
+  if (opt.resolve) {
+    if (task.status === "closed") fail("task is closed");
+    const r = resolveFinding(root, task, { match: opt.resolve === true ? "" : opt.resolve, reason: opt.reason === true ? "" : opt.reason, by: opt.by === true ? "coordinator" : (opt.by ?? "coordinator") });
+    const open = (task.reviews.at(-1).findings ?? []).filter(f => !f.resolved).map(f => `${f.severity}: ${f.title ?? f.summary ?? ""}`);
+    out({ id: task.id, resolved: { index: r.index, severity: r.finding.severity, title: r.finding.title ?? r.finding.summary ?? "" }, stillOpen: open });
+    return;
+  }
+  if (opt.import) {
+    const file = path.resolve(root, opt.import === true ? path.join(dir, `${task.id}-verdict.json`) : opt.import);
+    const v = readJson(file);
+    const problems = [];
+    if (!["PASS", "CHANGES_REQUIRED", "BLOCKED"].includes(v.verdict)) problems.push("verdict must be PASS | CHANGES_REQUIRED | BLOCKED");
+    if (!Array.isArray(v.findings)) problems.push("findings must be an array (may be empty)");
+    const screens = task.verifications.flatMap(x => x.screens ?? []);
+    if (screens.length && !(Array.isArray(v.screensViewed) && v.screensViewed.length)) problems.push("screensViewed must list the screenshot files the reviewer looked at");
+    if (!v.snapshot) problems.push("snapshot (from the review prompt) is required");
+    if (v.verdict === "PASS" && (v.findings ?? []).some(f => /HIGH|BLOCKER/i.test(f.severity ?? "") && !f.resolved)) problems.push("PASS cannot carry unresolved HIGH/BLOCKER findings");
+    if (problems.length) fail(`verdict rejected:\n- ${problems.join("\n- ")}`);
+    const current = snapshot(root).sha;
+    const review = { verdict: v.verdict, findings: v.findings, screensViewed: v.screensViewed ?? [], summary: v.summary ?? "", model: opt.model === true ? null : (opt.model ?? v.model ?? null), effort: opt.effort === true ? null : (opt.effort ?? v.effort ?? null), snapshot: v.snapshot, snapshotCurrent: v.snapshot === current, at: nowIso(), file: toPosix(path.relative(root, file)) };
+    task.reviews.push(review);
+    task.status = review.verdict === "PASS" ? "reviewed" : "verifying";
+    saveTask(root, task);
+    event(root, "task.review", { id: task.id, verdict: review.verdict, model: review.model });
+    out({ id: task.id, review: { verdict: review.verdict, findings: review.findings.length, snapshotCurrent: review.snapshotCurrent }, reviewsPassed: task.reviews.filter(r => r.verdict === "PASS" && r.snapshot === current).length, reviewsNeeded: reviewsNeeded(task) });
+    return;
+  }
+  // --prepare (default): write the reviewer prompt from the ledger.
+  const a = assess(root, task);
+  const config = loadConfig(root);
+  const changed = changesSinceOpen(task);
+  const screens = task.verifications.flatMap(x => x.screens ?? []).map(s => s.path);
+  const tests = [...task.verifications].reverse().find(v => v.kind === "tests")?.summary;
+  const prompt = [
+    `# Independent review · ${task.id} · ${task.title}`, "",
+    `You are the independent reviewer. You did not write this change and you have not seen the conversation that produced it.`,
+    `Review the current source snapshot \`${a.snapshot.sha}\` against the contract below. Read the files, look at every screenshot, and return a verdict file.`, "",
+    `## Contract`, "", `Rigor: ${task.rigor}. Files in scope: ${task.files.length ? task.files.join(", ") : "(not declared)"}.`, "",
+    ...task.criteria.map(c => `- **${c.id}** — ${c.description} — current status: ${a.evaluation.rows.find(r => r.id === c.id)?.status}`), "",
+    `## Evidence`, "",
+    `- Changed files since open: ${changed.length ? changed.join(", ") : "none detected"}`,
+    `- Tests: ${tests ? `${tests.passed}/${tests.total} passed, ${tests.failed} failed (${tests.source})` : "no test run recorded"}`,
+    `- Screenshots (you must open each one and describe what you see): ${screens.length ? screens.join(", ") : "none"}`,
+    `- Measurements: ${task.verifications.map(v => v.artifact).join(", ") || "none"}`, "",
+    `## What to check`, "",
+    `1. Does the change satisfy each criterion, and is each piece of evidence real (produced by Unity, matching the snapshot)?`,
+    `2. Correctness and Unity lifecycle risks: null references, serialization, domain reload, physics timing, input handling.`,
+    `3. Scope: anything changed outside the files in scope, or any requirement quietly dropped?`,
+    `4. Simplicity (Ponytail complexity pass: see .claude/nccgs/ponytail/complexity-review.md) — but never ask for less feedback to the player.`, "",
+    `## Verdict file`, "",
+    `Write JSON to \`.nccgs/evidence/review/${task.id}-verdict.json\` with exactly these fields:`, "",
+    "```json", JSON.stringify({ verdict: "PASS | CHANGES_REQUIRED | BLOCKED", snapshot: a.snapshot.sha, summary: "two sentences", screensViewed: screens, findings: [{ severity: "BLOCKER | HIGH | MEDIUM | LOW", title: "", file: "", detail: "", resolved: false }], model: config.review?.model ?? "(the model you are running as, if known)" }, null, 2), "```", "",
+    `PASS only when every criterion passes on this snapshot and no HIGH/BLOCKER finding is open. Do not fix anything yourself.`
+  ].join("\n");
+  const file = path.join(dir, `${task.id}-prompt.md`);
+  writeText(file, prompt);
+  out({ id: task.id, promptFile: toPosix(path.relative(root, file)), verdictFile: toPosix(path.relative(root, path.join(dir, `${task.id}-verdict.json`))), snapshot: a.snapshot.sha, screens, next: `invoke the reviewer subagent with the prompt file, then: task review --id ${task.id} --import` });
+}
+
+async function cmdClose() {
+  const task = loadTask(root, need("id"));
+  const outcome = opt.outcome === true ? "success" : (opt.outcome ?? "success");
+  if (!["success", "partial", "blocked", "failed"].includes(outcome)) fail("outcome must be success | partial | blocked | failed");
+  for (const pair of list(opt.decide)) { const [id, decision] = pair.split("="); if (id && decision) task.manualDecisions[id] = decision; }
+  const ready = readyToClose(root, task, outcome);
+  if (!ready.ok && !opt.force) fail(`cannot close as ${outcome}:\n- ${ready.reasons.join("\n- ")}`);
+  const changed = changesSinceOpen(task);
+  const report = renderReport(root, task, { outcome, changedFiles: changed });
+  task.status = "closed"; task.outcome = outcome; task.closedAt = nowIso(); task.report = toPosix(path.relative(root, report.file)); task.reportHtml = toPosix(path.relative(root, report.htmlFile)); task.changedFiles = changed; task.snapshotAtClose = ready.snapshot;
+  saveTask(root, task);
+  appendState(root, task, outcome, report.file);
+  event(root, "task.close", { id: task.id, outcome });
+  let project = null;
+  try { project = toPosix(path.relative(root, renderProject(root).file)); } catch {}
+  // consent auto: a non-success close or accumulated diagnostics send a bundle now (best effort, 10 s cap)
+  let feedback = null;
+  try { const fb = await autoFeedback(root, { trigger: `task.close:${outcome}` }); feedback = fb.action === "send" ? (fb.sent?.ok ? `sent (${fb.reasons.join("; ")})` : `not sent: ${fb.sent?.reason ?? "?"}`) : fb.action === "none" ? null : `${fb.action}: ${fb.reasons.join("; ")}`; } catch {}
+  out({ id: task.id, outcome, report: task.report, reportHtml: task.reportHtml, project, feedback, tokensOut: report.model.cost?.total?.output ?? null, criteria: ready.evaluation.summary, changedFiles: changed.length, outsideContract: outside(task, changed) });
+}