nccgs 3.0.0-rc.1 → 3.0.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 3.0.0-rc.2 — 2026-11-05
+
+- Feedback with consent and transport: `feedback.consent` in project.json is `ask` until the person decides (`auto` / `manual` / `off`); the first session where an issue shows up asks once through Claude. With `auto`, a bundle is POSTed to `feedback.endpoint` when diagnostics cross a threshold (any task crash or hook error, 3 failed Unity calls, 5 failed verifications), when a task closes partial/blocked/failed, or every `periodicDays`; with `manual`, NCCGS suggests `/feedback` at most once per 6 h. Every send is logged in `.nccgs/feedback/sent.jsonl`; a copy of each bundle stays local. `nccgs feedback --send | --consent <level>`. Receiver: `tools/feedback-worker` (Cloudflare Worker → GitHub issue).
+
+- Diagnostics (`.nccgs/diagnostics.jsonl`, local, rotated at 5 MB): every task CLI error, failed verification, failed Unity CLI/Pipeline call (args without the project path, exit code, error codes, last stderr) and hook block or crash is recorded with a timestamp.
+- `nccgs feedback [--since 14] [--note "..."] [--with-reports]` and the `/feedback` skill: a local `.md` + `.json` bundle under `.nccgs/feedback/` with versions, doctor, per-task metadata (rigor, outcome, verifications by kind and failures, reviews and finding counts, fix rounds, out-of-scope edits, minutes, tokens by agent), diagnostics grouped by cause, pending updates, the person's note. No source, screenshots, transcripts or credentials; nothing is uploaded.
+
 ## 3.0.0-rc.1 — 2026-11-05 — phase 5: clean-up and release candidate
 
 - Windows: process trees run inside a Job Object through `koffi` (optional dependency; `npx nccgs` installs it). A timed-out batch Editor dies with every descendant, including re-parented ones; `unity open`'s Editor is never touched because kill-on-close is used only for `unity test`/`build`. Without koffi the taskkill /T + ppid walk stays. `doctor` reports which layer is active; `scripts/check-job-object.mjs` proves it on a machine.

package/README.md

@@ -7,7 +7,7 @@ brief → options for the user → contract → edit → run (tests, Play Mode,
       → look → fix or ask → independent review → close → one-page report with real token cost
 ```
 
-**3.0.0-rc.1.** Built and verified on Unity 6000.3 and 6000.6 with Unity CLI 1.0.0-beta.14 and com.unity.pipeline 0.9, Claude Code 2.1.3xx, Windows. The sample game (a 2D endless runner) went from an empty scene to a vertical slice in four tasks with this loop; its reports are the reference for what a closed task looks like.
+**3.0.0-rc.2.** Built and verified on Unity 6000.3 and 6000.6 with Unity CLI 1.0.0-beta.14 and com.unity.pipeline 0.9, Claude Code 2.1.3xx, Windows. The sample game (a 2D endless runner) went from an empty scene to a vertical slice in four tasks with this loop; its reports are the reference for what a closed task looks like.
 
 ## Requirements
 
@@ -22,7 +22,7 @@ npx nccgs doctor  --project D:\Games\MyGame
 npx nccgs run     --project D:\Games\MyGame
 ```
 
-`install` adds `CLAUDE.md` (kept if you have one), `.claude/skills/` (10 NCCGS skills + 35 official Unity Skills), `.claude/agents/nccgs-*.md`, `.claude/nccgs/` (runtime, protocols, Ponytail) and `.nccgs/` (project config, tasks, evidence, reports). It merges hooks into `.claude/settings.json` without touching your other settings. `update` replaces managed files you did not change and records the ones you did; `uninstall` removes managed files, keeps `.nccgs/` and backs up what it removes. `run` launches Claude Code with the permission mode and MCP policy NCCGS expects (`acceptEdits` by default; `--autonomy full` for `bypassPermissions`).
+`install` adds `CLAUDE.md` (kept if you have one), `.claude/skills/` (11 NCCGS skills + 35 official Unity Skills), `.claude/agents/nccgs-*.md`, `.claude/nccgs/` (runtime, protocols, Ponytail) and `.nccgs/` (project config, tasks, evidence, reports). It merges hooks into `.claude/settings.json` without touching your other settings. `update` replaces managed files you did not change and records the ones you did; `uninstall` removes managed files, keeps `.nccgs/` and backs up what it removes. `run` launches Claude Code with the permission mode and MCP policy NCCGS expects (`acceptEdits` by default; `--autonomy full` for `bypassPermissions`).
 
 ## Daily use
 
@@ -37,6 +37,7 @@ Open the project in the Editor (screenshots and live tests need it; without it t
 | `/unity-foundation` | a fresh project, or tests cannot run | asmdefs, test assemblies, input, pipeline as a measured task |
 | `/playtest` | does it feel right, tuning, difficulty | telemetry artifact, the playtester's judgement, your decision |
 | `/art-bible`, `/asset-spec` | before and after art | visual rules; import settings checked against them |
+| `/feedback` | something went wrong, or after a few days of use | a local bundle (`.nccgs/feedback/`) of what ran, failed and was blocked, to send for review |
 
 The loop refuses to lie: `task close --outcome success` is rejected when a criterion fails, the source changed after the last verify, or the review is missing; `partial` and `blocked` are always allowed and reported as such.
 
@@ -73,6 +74,10 @@ Verified live, kept in `.claude/nccgs/protocols/unity-cli-notes.md` and `docs/EV
 .nccgs/                  project.json, modes.json, state.md, design/, tasks/, evidence/, reports/, project.html
 ```
 
+## Feedback
+
+Failures are recorded locally in `.nccgs/diagnostics.jsonl` (task CLI errors, failed verifications, failed Unity calls, hook blocks). A bundle (`nccgs feedback`) holds versions, doctor, per-task numbers and diagnostics grouped by cause — no code, screenshots, transcripts or credentials; project name and task titles are included. The first session where something fails asks you once: `auto` sends bundles to the maintainers by itself when an issue is detected or every 7 days, `manual` only suggests `/feedback`, `off` never does either. Change it any time with `npx nccgs feedback --project . --consent <auto|manual|off>`; every send is listed in `.nccgs/feedback/sent.jsonl` and a copy stays local.
+
 ## Updating
 
 `nccgs doctor --check-updates` reports newer NCCGS, Unity Skills, Unity CLI and Pipeline versions; nothing is applied on its own. `nccgs update` refreshes managed files; `--skills-only` refreshes just the vendored Unity Skills (pinned to an upstream commit in `unity-skills/manifest.json`).

package/bin/nccgs.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { projectRoot } from "../runtime/core/project.mjs";
+import { readText } from "../runtime/core/fs.mjs";
 import { PKG, TEMPLATE, install } from "../cli/install.mjs";
 import { doctor } from "../cli/doctor.mjs";
 import { launch } from "../cli/run.mjs";
@@ -11,6 +12,7 @@ import { uninstall } from "../cli/uninstall.mjs";
 import { allModes, createMode, setModeAgent, useMode, BUILTIN } from "../runtime/core/modes.mjs";
 import { renderProject } from "../runtime/task/project.mjs";
 import { release } from "../cli/release.mjs";
+import { feedback } from "../cli/feedback.mjs";
 
 const argv = process.argv.slice(2);
 const command = argv[0];
@@ -37,6 +39,7 @@ const HELP = `nccgs ${PKG.version} - Unity-first evidence loop for Claude Code
   nccgs mode      list | show NAME | create --from BALANCE --name X | set --name X --agent reviewer --model opus --effort high | use NAME
   nccgs task      <open|verify|review|close|inspect|list|fix|report|project> ...   (same as node .claude/nccgs/runtime/task/task.mjs)
   nccgs status    --project DIR                 writes .nccgs/project.html (all tasks, open findings, cost) and prints the summary
+  nccgs feedback  --project DIR [--since 14] [--note "..."] [--with-reports] [--send] [--consent auto|manual|off]   bundle of what ran, failed and was blocked; --send posts it
   nccgs release   --project DIR [--from TAG|DATE] [--to TAG|DATE|now] [--name v1.2.0]   changelog from tasks closed in the range
 `;
 
@@ -62,6 +65,13 @@ try {
       if (opt.json) out({ file: r.file, closed: m.closed.length, success: m.success.length, open: m.open.map(x => x.task.id), findings: m.bySeverity, tokens: m.tokens });
       break;
     }
+    case "feedback": {
+      const r = await feedback(root, { sinceDays: Number(opt.since) || 14, note: str(opt.note) ?? "", withReports: !!opt["with-reports"], runDoctor: !opt["no-doctor"], send: !!opt.send, consent: str(opt.consent) ?? null, dryRun: !!opt["dry-run"] });
+      if (r.consent) { process.stdout.write(`feedback consent: ${r.consent.consent}\n`); break; }
+      process.stderr.write(`${r.mdFile}\n${r.jsonFile}\n${r.sent ? (r.sent.ok ? `sent (id ${r.sent.id ?? "?"}, ${r.sent.bytes} bytes)` : `not sent: ${r.sent.reason ?? r.sent.status}`) : "not sent (add --send)"}\n`);
+      if (opt.json) out({ md: r.mdFile, json: r.jsonFile, totals: r.bundle.totals, sent: r.sent ?? null, decision: r.decision }); else process.stdout.write(readText(r.mdFile));
+      break;
+    }
     case "release": { const r = release(root, { from: str(opt.from), to: str(opt.to) ?? "now", name: str(opt.name), write: !opt["dry-run"] }); process.stdout.write(r.markdown); if (r.file) process.stderr.write(`\n${r.file}\n`); break; }
     case "mode": {
       const sub = positional[0];

package/cli/feedback.mjs

@@ -0,0 +1,13 @@
+// nccgs feedback: build the local bundle (with doctor), send it or set consent. See runtime/task/feedback.mjs.
+import { buildBundle, sendBundle } from "../runtime/task/feedback.mjs";
+import { evaluate, setConsent, CONSENT_TEXT } from "../runtime/core/feedback-policy.mjs";
+import { readText } from "../runtime/core/fs.mjs";
+import { doctor } from "./doctor.mjs";
+
+export async function feedback(root, { sinceDays = 14, note = "", withReports = false, runDoctor = true, send = false, consent = null, dryRun = false } = {}) {
+  if (consent) return { consent: setConsent(root, consent), text: CONSENT_TEXT.en };
+  const r = await buildBundle(root, { sinceDays, note, withReports, doctor: runDoctor ? doctor : null, trigger: "manual", reasons: evaluate(root).reasons });
+  if (send && !dryRun) r.sent = await sendBundle(root, { bundle: r.bundle, markdown: readText(r.mdFile, "") });
+  r.decision = evaluate(root);
+  return r;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nccgs",
-  "version": "3.0.0-rc.1",
+  "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",
@@ -18,6 +18,7 @@
     "unity-skills/",
     "scripts/",
     "docs/",
+    "tools/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

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/project.mjs

@@ -45,7 +45,13 @@ export const DEFAULT_CONFIG = {
   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: {}
+  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) {

package/runtime/hooks/common.mjs

@@ -1,7 +1,9 @@
 // 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 = "";
@@ -9,7 +11,8 @@ export async function readInput() {
   try { return text.trim() ? JSON.parse(text) : {}; } catch { return {}; }
 }
 export const root = () => projectRoot();
-export function block(reason) { process.stderr.write(`NCCGS blocked: ${reason}\n`); process.exit(2); }
+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);

package/runtime/hooks/session-start.mjs

@@ -5,6 +5,8 @@ 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();
@@ -28,5 +30,11 @@ try {
     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");

package/runtime/task/feedback.mjs

@@ -0,0 +1,136 @@
+// nccgs feedback: one bundle a person can send after days of use — what ran, what failed, what was
+// blocked, how long and how many tokens each task took, the doctor's view and any note they add.
+// Everything comes from local files (ledger, events, diagnostics, reports); no code, no screenshots,
+// no transcripts, no secrets. Nothing is uploaded: the bundle is written under .nccgs/feedback/ and
+// the person decides where it goes.
+import path from "node:path";
+import os from "node:os";
+import { writeJson, writeText, readText, exists, toPosix, appendLine } from "../core/fs.mjs";
+import { at, loadConfig, editorVersion, pipelineVersion } from "../core/project.mjs";
+import { listTasks } from "../task/ledger.mjs";
+import { readEvents, taskCost, fmtTokens } from "../task/cost.mjs";
+import { readDiag } from "../core/diag.mjs";
+import { inScope } from "../core/snapshot.mjs";
+import { readJson } from "../core/fs.mjs";
+import { fileURLToPath } from "node:url";
+import { evaluate, markSent } from "../core/feedback-policy.mjs";
+
+// the runtime is installed into the project; its version is in install-state.json, falling back to the package
+function nccgsVersion(root) { try { return readJson(at(root, "installState")).version; } catch { try { return readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json")).version; } catch { return "unknown"; } } }
+
+const DAY = 86400000;
+const count = (arr, key) => arr.reduce((m, x) => { const k = key(x); m[k] = (m[k] ?? 0) + 1; return m; }, {});
+
+export async function buildBundle(root, { sinceDays = 14, note = "", withReports = false, doctor = null, trigger = "manual", reasons = [] } = {}) {
+  const sinceMs = Date.now() - sinceDays * DAY;
+  const config = loadConfig(root);
+  const events = readEvents(root).filter(e => Date.parse(e.at) >= sinceMs);
+  const diags = readDiag(root, { sinceMs });
+  const tasks = listTasks(root).filter(t => Date.parse(t.updatedAt ?? t.openedAt) >= sinceMs);
+  const taskRows = tasks.map(t => {
+    let cost = null; try { cost = taskCost(root, t); } catch {}
+    const verifications = t.verifications ?? [];
+    return {
+      id: t.id, title: t.title, rigor: t.rigor, mode: t.mode, status: t.status, outcome: t.outcome ?? null, fromPlan: !!t.fromPlan,
+      openedAt: t.openedAt, closedAt: t.closedAt ?? null, minutes: t.closedAt ? Math.round((Date.parse(t.closedAt) - Date.parse(t.openedAt)) / 60000) : null,
+      criteria: (t.criteria ?? []).length, manualCriteria: (t.criteria ?? []).filter(c => c.kind === "manual").length,
+      verifications: { total: verifications.length, failed: verifications.filter(v => !v.ok).length, byKind: count(verifications, v => v.kind) },
+      reviews: (t.reviews ?? []).map(r => ({ verdict: r.verdict, model: r.model, findings: count(r.findings ?? [], f => (f.severity ?? "INFO").toUpperCase()), resolved: (r.findings ?? []).filter(f => f.resolved).length })),
+      fixRounds: `${t.fixRounds}/${t.maxFixRounds}`,
+      changedFiles: (t.changedFiles ?? []).length, outsideContract: (t.changedFiles ?? []).filter(f => !inScope(f, t.files)).length,
+      tokens: cost?.total?.messages ? { in: cost.total.input + cost.total.cacheWrite + cost.total.cacheRead, cached: cost.total.cacheRead, out: cost.total.output, messages: cost.total.messages, byAgent: Object.fromEntries(Object.entries(cost.byAgent).map(([k, v]) => [k, v.output])) } : null
+    };
+  });
+  let doc = null;
+  if (doctor) { try { doc = await doctor(root); doc = { summary: doc.summary, checks: doc.checks.map(c => ({ id: c.id, status: c.status, message: c.message })) }; } catch (e) { doc = { error: e.message }; } }
+  const bundle = {
+    schemaVersion: 1, generatedAt: new Date().toISOString(), sinceDays, trigger, reasons,
+    nccgs: nccgsVersion(root), node: process.version, platform: `${os.platform()} ${os.release()} ${os.arch()}`,
+    project: { editor: editorVersion(root), pipeline: pipelineVersion(root), mode: config.mode, rigor: config.rigor, autonomy: config.autonomy, reportLanguage: config.report?.language ?? "en" },
+    doctor: doc,
+    totals: {
+      tasks: taskRows.length, closed: taskRows.filter(t => t.status === "closed").length, byOutcome: count(taskRows.filter(t => t.status === "closed"), t => t.outcome),
+      verifications: taskRows.reduce((a, t) => a + t.verifications.total, 0), failedVerifications: taskRows.reduce((a, t) => a + t.verifications.failed, 0),
+      fixRounds: taskRows.reduce((a, t) => a + Number(t.fixRounds.split("/")[0]), 0),
+      tokensOut: taskRows.reduce((a, t) => a + (t.tokens?.out ?? 0), 0),
+      sessions: events.filter(e => e.type === "session.start").length,
+      agentRuns: count(events.filter(e => e.type === "agent.start"), e => e.agent || "unknown"),
+      diagnostics: count(diags, d => d.kind)
+    },
+    tasks: taskRows,
+    diagnostics: diags.slice(-300),
+    updateNotices: exists(at(root, "updateCheck")) ? JSON.parse(readText(at(root, "updateCheck"), "{}")).notices ?? [] : [],
+    state: readText(at(root, "state"), "").split("\n").filter(l => l.startsWith("- ")).slice(0, 30),
+    note: note || null,
+    reports: withReports ? Object.fromEntries(tasks.filter(t => t.report && exists(path.resolve(root, t.report))).map(t => [t.id, readText(path.resolve(root, t.report), "")])) : undefined
+  };
+  const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-").slice(0, 16);
+  const dir = path.join(at(root, "nccgs"), "feedback");
+  const jsonFile = path.join(dir, `nccgs-feedback-${stamp}.json`);
+  const mdFile = path.join(dir, `nccgs-feedback-${stamp}.md`);
+  writeJson(jsonFile, bundle);
+  writeText(mdFile, renderSummary(bundle));
+  return { jsonFile, mdFile, bundle };
+}
+
+const MAX_BYTES = 512 * 1024;
+
+// POST the bundle to the configured endpoint. Never throws; the outcome is appended to
+// .nccgs/feedback/sent.jsonl so a person can see what left the machine and when.
+export async function sendBundle(root, { bundle, markdown, endpoint = loadConfig(root).feedback?.endpoint, timeoutMs = 10000 } = {}) {
+  const log = path.join(at(root, "nccgs"), "feedback", "sent.jsonl");
+  const record = async r => { try { appendLine(log, JSON.stringify({ at: new Date().toISOString(), endpoint, ...r })); } catch {} return r; };
+  if (!endpoint) return record({ ok: false, reason: "no endpoint configured" });
+  let body = JSON.stringify({ bundle, markdown });
+  if (body.length > MAX_BYTES) { body = JSON.stringify({ bundle: { ...bundle, diagnostics: bundle.diagnostics.slice(-50), reports: undefined, truncated: true }, markdown }); }
+  if (body.length > MAX_BYTES) return record({ ok: false, reason: `bundle too large (${body.length} bytes)` });
+  const ctl = new AbortController(); const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const r = await fetch(endpoint, { method: "POST", headers: { "content-type": "application/json", "user-agent": `nccgs/${bundle.nccgs}` }, body, signal: ctl.signal });
+    const text = await r.text().catch(() => "");
+    let id = null; try { id = JSON.parse(text).id ?? null; } catch {}
+    if (!r.ok) return record({ ok: false, status: r.status, reason: text.slice(0, 200) });
+    markSent(root);
+    return record({ ok: true, status: r.status, id, bytes: body.length });
+  } catch (e) { return record({ ok: false, reason: e.name === "AbortError" ? "timeout" : e.message }); }
+  finally { clearTimeout(t); }
+}
+
+// Called by hooks and `task close`: decide, and either send (consent auto) or return a suggestion.
+// Returns { action, reasons, sent? } and never throws.
+export async function autoFeedback(root, { trigger = "hook" } = {}) {
+  try {
+    const d = evaluate(root);
+    if (d.action !== "send") return d;
+    const { bundle, mdFile } = await buildBundle(root, { sinceDays: 14, trigger, reasons: d.reasons });
+    const sent = await sendBundle(root, { bundle, markdown: readText(mdFile, "") });
+    return { ...d, sent };
+  } catch (e) { return { action: "none", reasons: [], error: e.message }; }
+}
+
+export function renderSummary(b) {
+  const L = [];
+  L.push(`# NCCGS feedback · ${b.generatedAt.slice(0, 10)} · last ${b.sinceDays} days`, "");
+  L.push(`NCCGS ${b.nccgs} · Node ${b.node} · ${b.platform} · Unity ${b.project.editor ?? "?"} · Pipeline ${b.project.pipeline ?? "?"} · mode ${b.project.mode} · rigor ${b.project.rigor} · autonomy ${b.project.autonomy}`, "");
+  const t = b.totals;
+  L.push(`**Totals.** ${t.tasks} tasks (${t.closed} closed: ${Object.entries(t.byOutcome).map(([k, v]) => `${v} ${k}`).join(", ") || "none"}) · ${t.verifications} verifications (${t.failedVerifications} failed) · ${t.fixRounds} fix rounds · ${fmtTokens(t.tokensOut)} tokens out · ${t.sessions} sessions · agents: ${Object.entries(t.agentRuns).map(([k, v]) => `${k} ×${v}`).join(", ") || "none"}`, "");
+  if (b.doctor?.summary) L.push(`**Doctor.** ${b.doctor.summary.pass} pass · ${b.doctor.summary.warn} warn · ${b.doctor.summary.fail} fail${b.doctor.checks.filter(c => c.status !== "pass").map(c => `\n- ${c.status.toUpperCase()} ${c.id}: ${c.message}`).join("")}`, "");
+  L.push(`## Tasks`, "", `| Task | Rigor | Outcome | Verify (failed) | Review | Fix | Outside scope | Minutes | Tokens out |`, `| --- | --- | --- | --- | --- | --- | --- | --- | --- |`);
+  for (const x of b.tasks) L.push(`| ${x.id} ${x.title.slice(0, 40)} | ${x.rigor} | ${x.status === "closed" ? x.outcome : x.status} | ${x.verifications.total} (${x.verifications.failed}) | ${x.reviews.map(r => `${r.verdict}${Object.keys(r.findings).length ? ` ${Object.entries(r.findings).map(([k, v]) => `${k[0]}${v}`).join("/")}` : ""}`).join(" → ") || "–"} | ${x.fixRounds} | ${x.outsideContract} | ${x.minutes ?? "–"} | ${x.tokens ? fmtTokens(x.tokens.out) : "–"} |`);
+  L.push("");
+  const kinds = Object.entries(t.diagnostics);
+  L.push(`## Diagnostics (${b.diagnostics.length})`, "");
+  if (!kinds.length) L.push("Nothing recorded: no runtime errors, failed verifications, Unity failures or hook blocks in the window.", "");
+  else {
+    L.push(kinds.map(([k, v]) => `${k} ×${v}`).join(" · "), "");
+    const groups = {};
+    for (const d of b.diagnostics) { const key = `${d.kind}: ${(d.reason ?? d.message ?? d.error?.message ?? (d.errors?.[0]?.code ?? d.errors?.[0]?.message) ?? d.name ?? "").toString().slice(0, 100)}`; groups[key] = (groups[key] ?? 0) + 1; }
+    for (const [k, v] of Object.entries(groups).sort((a, b) => b[1] - a[1]).slice(0, 30)) L.push(`- ×${v} ${k}`);
+    L.push("");
+  }
+  if (b.updateNotices?.length) L.push(`## Updates pending`, "", ...b.updateNotices.map(n => `- ${n.component} ${n.current} → ${n.latest}`), "");
+  if (b.note) L.push(`## Note from the person`, "", b.note, "");
+  L.push(`## Recent closes`, "", ...(b.state.length ? b.state : ["(none)"]), "");
+  L.push("_Local bundle. Contains task metadata, counts, diagnostics and the note above; no source code, screenshots, transcripts or credentials. The JSON beside this file has the detail._");
+  return L.join("\n");
+}

package/runtime/task/task.mjs

@@ -14,6 +14,8 @@ 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);
@@ -31,7 +33,7 @@ for (let i = 0; i < own.length; i++) {
 }
 const root = projectRoot(opt.project);
 const out = value => process.stdout.write(JSON.stringify(value, null, 2) + "\n");
-const fail = message => { process.stderr.write(`task ${command}: ${message}\n`); process.exit(1); };
+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 {
@@ -61,7 +63,7 @@ try {
     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) { fail(error.message); }
+} 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) }); }
@@ -146,6 +148,7 @@ async function cmdVerify() {
     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}`) })) });
 }
@@ -228,5 +231,8 @@ async function cmdClose() {
   event(root, "task.close", { id: task.id, outcome });
   let project = null;
   try { project = toPosix(path.relative(root, renderProject(root).file)); } catch {}
-  out({ id: task.id, outcome, report: task.report, reportHtml: task.reportHtml, project, tokensOut: report.model.cost?.total?.output ?? null, criteria: ready.evaluation.summary, changedFiles: changed.length, outsideContract: outside(task, changed) });
+  // 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) });
 }

package/runtime/unity/unity.mjs

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import { run, sleep } from "../core/process-tree.mjs";
 import { readJson, writeJson, exists } from "../core/fs.mjs";
 import { at, editorVersion, pipelineVersion } from "../core/project.mjs";
+import { diag } from "../core/diag.mjs";
 
 export const UNITY_BIN = process.env.NCCGS_UNITY_BIN || "unity";
 // Test seam: NCCGS_UNITY_ARGS prepends fixed arguments (used to point NCCGS_UNITY_BIN=node at a fake CLI).
@@ -27,7 +28,13 @@ function parseEnvelope(result) {
 export async function cli(args, { cwd, timeoutMs = 120000 } = {}) {
   const ownTree = ["test", "build"].includes(args[0]);
   const result = await run(UNITY_BIN, unityArgv([...args, "--format", "json"]), { cwd, timeoutMs, ownTree });
-  return parseEnvelope(result);
+  const env = parseEnvelope(result);
+  if (result.timedOut || result.error || (env.json && env.json.success === false) || (!env.json && result.code !== 0)) {
+    const i = args.indexOf("--project-path");
+    const shown = i >= 0 ? [...args.slice(0, i), ...args.slice(i + 2)] : args;
+    diag(i >= 0 ? args[i + 1] : (process.env.NCCGS_PROJECT_ROOT ?? process.cwd()), "unity.failed", { args: shown.map(a => String(a).slice(0, 200)), code: result.code, timedOut: result.timedOut, errors: env.json?.errors ?? null, stderr: result.stderr?.slice(-500) ?? null, jobObject: result.jobObject });
+  }
+  return env;
 }
 
 export async function cliVersion() {

package/template/CLAUDE.md

@@ -10,7 +10,7 @@ This Unity project runs under NCCGS 3: a task is done when the game has run and
 5. `.claude/nccgs/protocols/*.md`, then the official Unity Skills in `.claude/skills/`, then your own inference.
 
 ## Skills
-`/brainstorm` → `/map-systems` → `/vertical-slice` for a new game or a multi-task feature (brief, systems map + slice plan, then `/work` per planned task). `/unity-foundation` on a fresh project. `/playtest` for feel and tuning (telemetry + playtester judgement + user decision). `/art-bible` and `/asset-spec` before and after art. `/status` for where we are.
+`/brainstorm` → `/map-systems` → `/vertical-slice` for a new game or a multi-task feature (brief, systems map + slice plan, then `/work` per planned task). `/unity-foundation` on a fresh project. `/playtest` for feel and tuning (telemetry + playtester judgement + user decision). `/art-bible` and `/asset-spec` before and after art. `/status` for where we are. `/feedback` when something went wrong or after a few days of use.
 
 ## The loop (skill `/work`)
 Brief → options for the user when the decision is subjective → `task open` → edit → `task verify` → **look at the screenshots and console** → fix or ask → `task review` (rigor ≥ production) → `task close` → report.

package/template/skills/feedback/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: feedback
+description: Send or prepare a feedback bundle for the NCCGS maintainers (what ran, what failed, what was blocked, tokens per task) with the person's note, and set the consent level (auto / manual / off). Use when something went wrong, when NCCGS suggests it, or when the session asks for consent.
+allowed-tools: Read, Bash, AskUserQuestion
+---
+
+# /feedback
+
+A bundle holds versions, doctor, per-task numbers, diagnostics and the person's note. No source code, screenshots, transcripts or credentials; project name and task titles are included. Where it goes is `feedback.endpoint` in `.nccgs/project.json`; a copy always stays under `.nccgs/feedback/`.
+
+1. **Consent first.** If `.nccgs/project.json` has `feedback.consent: "ask"` (or the session told you consent is not set), ask once with AskUserQuestion — options `auto` (send by itself when an issue is detected or every 7 days), `manual` (only suggest), `off` (never) — then `npx nccgs feedback --project . --consent <choice>`. `off` ends here.
+2. **What happened.** Ask in one question what to report (a problem now, an impression after some days, or the periodic bundle) and whether to include reports.
+3. `npx nccgs feedback --project . --since <days> --note "<their words>" [--with-reports] --send` (omit `--send` when they only want the file). The `.md` path and the send result print on stderr.
+4. Tell the person the three numbers (tasks closed / failed verifications / diagnostics), the top diagnostic line, whether it was sent (and the id) or where the file is.
+
+Never add `--send` without the person's yes in this session unless consent is `auto`.

package/tools/feedback-worker/README.md

@@ -0,0 +1,12 @@
+# NCCGS feedback receiver
+
+One Cloudflare Worker that turns a feedback bundle into a GitHub issue, so bundles can be read, labelled and closed like any other issue.
+
+Setup (once, by the maintainer):
+
+1. Create the repository `LacBird/nccgs-feedback` (private is fine). Labels are created on demand by the API.
+2. Create a fine-grained personal access token limited to that repository with **Issues: read and write** only.
+3. `npm i -g wrangler && wrangler login`, then in this folder: `wrangler secret put GITHUB_TOKEN`, optionally `wrangler secret put INGEST_KEY`, and `wrangler deploy`. The URL is `https://nccgs-feedback.<account>.workers.dev/v1/bundle`.
+4. Put that URL in `DEFAULT_CONFIG.feedback.endpoint` (`runtime/core/project.mjs`) before the next release, or users set `feedback.endpoint` in `.nccgs/project.json`.
+
+What a client sends: `{ bundle, markdown }` as built by `nccgs feedback` (≤ 512 KB). What the issue contains: the Markdown summary and, under a collapsed block, the JSON bundle. No code, screenshots, transcripts or credentials are in a bundle; project name and task titles are.

package/tools/feedback-worker/worker.js

@@ -0,0 +1,39 @@
+// NCCGS feedback receiver — a Cloudflare Worker. POST /v1/bundle {bundle, markdown} → one GitHub issue
+// in FEEDBACK_REPO. Secrets: GITHUB_TOKEN (fine-grained, Issues: read/write on that repo only).
+// Vars: FEEDBACK_REPO ("owner/name"). Optional: INGEST_KEY (clients send header x-nccgs-key).
+// Limits: 512 KB body, 20 bundles per IP per day (KV binding RATE optional; without it no limit).
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (request.method === "GET" && url.pathname === "/") return new Response("nccgs feedback receiver", { status: 200 });
+    if (request.method !== "POST" || url.pathname !== "/v1/bundle") return json({ error: "not found" }, 404);
+    if (env.INGEST_KEY && request.headers.get("x-nccgs-key") !== env.INGEST_KEY) return json({ error: "unauthorized" }, 401);
+    const len = Number(request.headers.get("content-length") || 0);
+    if (len > 512 * 1024) return json({ error: "too large" }, 413);
+    let payload; try { payload = await request.json(); } catch { return json({ error: "bad json" }, 400); }
+    const b = payload?.bundle;
+    if (!b || b.schemaVersion !== 1 || typeof payload.markdown !== "string") return json({ error: "bad bundle" }, 400);
+    if (env.RATE) {
+      const ip = request.headers.get("cf-connecting-ip") || "unknown";
+      const key = `rate:${ip}:${new Date().toISOString().slice(0, 10)}`;
+      const n = Number(await env.RATE.get(key) || 0);
+      if (n >= 20) return json({ error: "rate limited" }, 429);
+      await env.RATE.put(key, String(n + 1), { expirationTtl: 86400 });
+    }
+    const t = b.totals || {};
+    const topDiag = Object.entries(t.diagnostics || {}).sort((a, c) => c[1] - a[1])[0];
+    const title = `[feedback] nccgs ${b.nccgs} · ${(b.platform || "").split(" ")[0]} · ${t.closed ?? 0}/${t.tasks ?? 0} closed · ${t.failedVerifications ?? 0} failed verify${topDiag ? ` · ${topDiag[0]}×${topDiag[1]}` : ""}${b.trigger ? ` · ${b.trigger}` : ""}`;
+    const jsonText = JSON.stringify(b, null, 1);
+    const details = jsonText.length < 60000 ? `\n\n<details><summary>bundle.json</summary>\n\n\`\`\`json\n${jsonText}\n\`\`\`\n</details>` : `\n\n_bundle.json omitted (${jsonText.length} bytes); diagnostics count ${(b.diagnostics || []).length}._`;
+    const labels = ["feedback", `v${b.nccgs}`, ...(b.trigger && b.trigger !== "manual" ? ["auto"] : []), ...((t.failedVerifications ?? 0) > 0 || topDiag ? ["has-issues"] : [])];
+    const gh = await fetch(`https://api.github.com/repos/${env.FEEDBACK_REPO}/issues`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${env.GITHUB_TOKEN}`, accept: "application/vnd.github+json", "content-type": "application/json", "user-agent": "nccgs-feedback-worker", "x-github-api-version": "2022-11-28" },
+      body: JSON.stringify({ title: title.slice(0, 250), body: payload.markdown.slice(0, 60000) + details, labels })
+    });
+    if (!gh.ok) return json({ error: "github", status: gh.status, detail: (await gh.text()).slice(0, 300) }, 502);
+    const issue = await gh.json();
+    return json({ id: issue.number, url: issue.html_url }, 201);
+  }
+};
+const json = (o, status = 200) => new Response(JSON.stringify(o), { status, headers: { "content-type": "application/json" } });

package/tools/feedback-worker/wrangler.toml

@@ -0,0 +1,12 @@
+name = "nccgs-feedback"
+main = "worker.js"
+compatibility_date = "2026-01-01"
+
+[vars]
+FEEDBACK_REPO = "LacBird/nccgs-feedback"
+
+# secrets (set with `wrangler secret put`): GITHUB_TOKEN, optionally INGEST_KEY
+# optional rate limit:
+# [[kv_namespaces]]
+# binding = "RATE"
+# id = "<kv id>"