nccgs 2.1.1 → 3.0.0-rc.2

package/README.md

@@ -1,206 +1,87 @@
-# NCCGS — New Claude Code Game Studio
-
-**2.1.1** is the prepared local release for standalone game-development
-orchestration in **Claude Code**, derived from the accepted local R11 r05
-baseline. The registry already contains a different `nccgs@2.1.0` tarball. This prepared
-2.1.1 package derives from the accepted local R11 r05 qualification; it does not
-replace or retroactively qualify the registry artifact. No npm tags are changed.
-
-It retains handoff automation, bounded task slicing and Unity repair, protected
-final-review allocation, managed Unity settlement and exact first-import output
-declarations. New repair steps block unsaved loaded scenes before execution.
-See [handoff operations](docs/HANDOFF-AUTOMATION.md), [bounded repair](docs/BOUNDED-REPAIR.md),
-[task slicing](docs/TASK-SLICING.md), [uninstallation](docs/UNINSTALL.md) and [release notes](CHANGELOG.md).
-
-Claude Code handles intake, planning, specialist dispatch, testing, independent
-review and reporting. External review can be configured separately. This major
-version introduces standalone defaults and explicit execution-policy migration
-from the older compatibility workflow; existing task obligations remain preserved.
-
-## Validation and limits
-
-The frozen exact RC4 archive was exercised through actual Claude Code on a
-controlled Unity scene repair: dirty-scene refusal preserved unsaved content,
-a fresh worker repaired the target, deterministic PARTIAL handoff required no
-continuation, all five checks and 28 criteria/385 assertions passed, and a fresh
-independent reviewer returned unconditional PASS before normal task closure.
-This is scoped workflow evidence, not broad game-quality or productivity proof.
-
-Version 2.0.0 keeps those runtime guards and adds a receipt publisher so external
-Editor stop evidence is available inside the reviewer's project. It does not
-operate processes or alter acceptance. See [Editor evidence](docs/EDITOR-SESSION-EVIDENCE.md).
-The exact 2.0.0 archive subsequently passed its scoped native Unity qualification
-and was published on 2026-10-28. Frozen release receipts retain its tests and
-independent reviews. The accepted local R11 r05 baseline accounts for 353 passing
-top-level cases and 13 explicitly host-skipped link cases, with independent Fable
-static review PASS and no mandatory conditions. The 2.1.1 preparation changes
-package identity and current guidance only; runtime code, profiles, role ceilings,
-guards and budgets remain unchanged. Its exact package/release checks are recorded
-in the accompanying qualification receipts. Effective native effort stays UNKNOWN;
-this does not claim managed-worker completion or a new Claude Code/Unity run.
-Earlier negative verdicts remain unchanged in their separate receipts.
-Frozen history remains intact.
-See [release status](docs/RELEASE-STATUS.md), [upgrading](UPGRADING.md),
-[Vietnamese quick start](docs/HUONG-DAN-MIGRATE-VA-SU-DUNG.md) and [decisions](MEMORY.md).
-
-## What changed
-
-Standalone `/design`, `/design-review` and `/story-readiness` now load the
-[design lifecycle](.claude/nccgs/protocols/design-lifecycle.md). New installs require
-a reviewed design handoff before dependent feature implementation; criteria and
-their source/threshold authority are pinned across that handoff. The fixed
-`task design-validate` command supports plan tasks without granting arbitrary
-shell execution. Existing policies and frozen evaluations retain their obligations;
-see [upgrading](UPGRADING.md). Schema validation is not semantic or gameplay acceptance.
-
-
-
-NCCGS includes a [shared Ponytail package](.claude/nccgs/packages/ponytail/README.md)
-for technical planning, implementation, supplementary complexity review and known
-code limits. The coordinator and agents load it by assignment through their common
-contracts. It borrows selected guidance from DietrichGebert/Ponytail under MIT;
-the [original license](.claude/nccgs/packages/ponytail/LICENSE) and
-[attribution/change notice](.claude/nccgs/packages/ponytail/NOTICE.md) ship with every
-installation. It preserves full design and QA obligations; no separate Ponytail
-plugin or global hooks are installed. Broad comparative effectiveness remains unmeasured.
-
-- Separate execution policy, model profile and external review (`off`, `advisory`,
-  `required`); project updates preserve existing obligations.
-- Task contracts for `implement`, `audit` and `plan`, with conservative
-  FAST/STANDARD/CONTROLLED classification, reasons, inputs and acceptance gates.
-- Durable dispatch reservations, path ownership checks, two-worker ceiling,
-  independent reviewer slot, ancestor quotas and recovery without budget refunds.
-- Final evidence tied to task, source, contract, runtime invocation and raw source.
-  Missing model/effort/usage is explicit; requested settings do not prove execution.
-- Reports for success, partial, blocked and failed outcomes; strict successful
-  closure, optional external receipts and explicit acceptance when configured.
-- Execution migration with dry-run, archived configuration and guarded rollback.
-
-The studio retains 47 roles (13 active by default, including Game Designer), 36 NCCGS workflows, scoped
-rules, lifecycle hooks and unmodified official Unity Skills. Enable specialists
-when their expertise resolves a concrete problem; do not dispatch the whole studio.
-
-## Try the local 2.1.1 package
-
-Requirements: Claude Code and Node.js 18+. Unity CLI/Pipeline is needed for live
-Unity operations. Run against a disposable Unity project first:
-
-Use the locally prepared archive and its accompanying SHA-256 manifest:
-
-```powershell
-$NccgsArchive = "D:\path\to\nccgs-2.1.1.tgz"
-npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject" --dry-run
-npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject"
-npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
-```
-
-Before 2.1.1 publication, use this exact local archive. The registry's existing
-2.1.0 has different bytes and is not the accepted local R11 r05 archive. Published
-nccgs@2.0.0 does not include the uninstall command. Use update for an existing installation only after reviewing its
-dry run and backup. See [the tested upgrade matrix](docs/UPGRADE-QUALIFICATION.md) and its limits.
-The installer preserves customized files and unrelated Claude settings, records
-overrides and backs up replacements. Do not use --force as an ordinary update path.
-
-New installs default to standalone with `claude-standalone`. Existing installations
-without execution.json remain compatibility. To migrate explicitly:
-
-```powershell
-npx --yes --package "$NccgsArchive" nccgs migrate-execution --project "D:\path\to\UnityProject" --to standalone --model-profile claude-standalone --dry-run
-```
-
-Inspect the dry run, then remove `--dry-run`. Omitting `--model-profile` preserves
-existing model routes. See [upgrading](UPGRADING.md) for rollback and historical
-task handling. Updating files never converts an old approval into a new one.
-
-## Operating flow
-
-Start a task session with native permissions already selected:
-
-```powershell
-npx --yes --package "$NccgsArchive" nccgs run --project "D:\path\to\UnityProject"
-```
-
-New installations default to task autonomy `full`. Existing installations keep
-their setting; use `update --autonomy full` to select it explicitly. For a resumed
-session, append `-- --resume SESSION_ID`. If Claude is not on PATH, pass
-`--claude "C:\path\to\claude.exe"` before the separator. Model and tool settings
-are inherited. Ordinary Bash, report writing and task work outside the project
-need no repeated permission; explicit deny rules and integrity/destructive-action
-guards remain effective. See [task autonomy](.claude/nccgs/protocols/task-autonomy.md).
-
-```text
-User request -> bounded contract + mode + risk
-            -> reserved Claude Code worker(s)
-            -> targeted evidence + independent internal review
-            -> honest report of outcome and unresolved findings
-            -> configured external/manual/acceptance gates -> DONE
-```
-
-| Workflow | Outcome |
-|---|---|
-| `/work` | Implement a feature, fix, refactor, tool or content change |
-| `/design` | Plan design and requirements |
-| `/audit` | Examine the project without source edits |
-| `/migrate-project` | Review and apply authorized project adoption changes |
-| `/test` | Verify declared requirements |
-| `/review` | Independent review |
-| `/release` | Prepare a verified release candidate |
-| `/status` | Read state, evidence, blockers and next action |
-
-FAST uses Sonnet/high; STANDARD uses Opus/high; CONTROLLED uses Opus/xhigh.
-Leadership requests Opus/xhigh. Independent review uses Fable/high. These aliases are requested routes. Real Claude
-model resolution and provider access must be verified in the target session.
-Historical `astra-claude` routes remain available under compatibility execution.
-
-## Remove NCCGS when it is no longer needed
-
-Close Claude Code sessions, then preview and apply from an external terminal:
-
-```powershell
-npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject" --dry-run
-npx --yes --package "$NccgsArchive" nccgs uninstall --project "D:\path\to\UnityProject"
-```
-
-This also supports an existing 2.0.0 installation without updating it first.
-Game source, customized files and `.nccgs` history/budgets remain. The command
-removes unchanged managed files and exact framework hooks/imports, saves a backup
-and refuses active or uncertain work. Use `uninstall --rollback ID` to restore
-that backup when no later edits conflict. Shared permission/model settings stay
-because their ownership was not recorded by earlier installers.
-See [details and recovery](docs/UNINSTALL.md).
-
-## Maintainer verification and limits
-
-These commands run from a source/package checkout. They are not extra steps for
-users installing with npx, and do not initiate a Claude Code game run.
-
-```text
-npm run policy:build
-npm run policy:check
-npm run validate
-npm test
-node scripts/benchmark-v15.mjs --out PATH_TO_JSON
-npm pack --dry-run
-```
-
-Generated catalogs, workflow wrappers and agents come from pipeline.json and the
-agent library. Do not patch generated model pins directly. Official Unity Skills
-remain the source for generic Editor/asset mechanics.
-
-Reservations and direct edit hooks enforce declared path ownership. Arbitrary
-implementation shell/MCP tools are not filesystem-sandboxed; review actual changes.
-Background or uncertain workers retain slots until final correlated evidence or
-external reconciliation. Worker telemetry has explicit coverage and excludes
-unobserved coordinator/human/provider activity. It is not account-wide billing.
-
-See [the Claude Code pilot and benchmark protocol](docs/NCCGS-1.5-PILOT.md),
-[the standalone workflow](.claude/nccgs/protocols/standalone.md), and
-[the 1.4.1 integrity guide](docs/NCCGS-1.4.1.md).
-
-## Direct Unity transport
-
-Unity uses CLI/Pipeline only. `nccgs run` supplies `--strict-mcp-config --mcp-config '{"mcpServers":{}}'` by default, preserving prompt/model/permission policy. An external operator may explicitly supply a JSON non-Unity MCP configuration or JSON-file path; Unity/Coplay/AnkleBreaker server identities and routes are rejected. Global MCP settings and plugins are never edited. The universal transport hook also refuses Unity MCP tools and ordinary registration/launch shell commands before task/profile routing.
-
-Generic Unity Skills retain their upstream hashes and licenses. Their optional MCP examples do not override this package's [Unity boundary](.claude/nccgs/protocols/unity-boundary.md). These checks do not sandbox arbitrary/encoded programs or a hostile client. Actual source review, native permissions and measured runtime evidence remain necessary.
-
-R07 review repair: Claude Code declares its MCP-config option variadic. The one validated config is therefore placed at argv end or immediately before the explicit option terminator, preserving positional prompts and preventing an unchecked second config. Recovery requires that canonical boundary without rewriting retained state. Ordinary Claude/Codex Unity MCP registration is denied; non-Unity community server/method names remain available. Provider instruction-pattern warnings remain fail-closed; qualification handoffs describe settings in prose instead of reproducing configuration JSON.
+# NCCGS 3
+
+A Unity-first evidence loop for Claude Code. A task is done when the game has run and been looked at, not when the code has been written.
+
+```
+brief → options for the user → contract → edit → run (tests, Play Mode, screenshots, console, playtest)
+      → look → fix or ask → independent review → close → one-page report with real token cost
+```
+
+**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
+
+Node 20+, Claude Code 2.1.295+, Unity 6.0+ with `com.unity.pipeline` in the project (`unity pipeline install --project-path <project>`), the Unity CLI on PATH. Windows, macOS and Linux; on Windows the optional `koffi` dependency gives Job Object process control (installed automatically by `npx`).
+
+## Install
+
+```
+npx nccgs install --project D:\Games\MyGame --dry-run
+npx nccgs install --project D:\Games\MyGame
+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/` (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
+
+Open the project in the Editor (screenshots and live tests need it; without it tests run in a batch Editor pinned to the project's own version), run `nccgs run`, then:
+
+| Skill | When | Output |
+| --- | --- | --- |
+| `/work` | any change to code, scenes, prefabs or assets | a closed task with `.nccgs/reports/<id>.md` + `.html` |
+| `/test` | run tests and observe without changing anything | measurements under `.nccgs/evidence/` |
+| `/status` | where are we | `.nccgs/project.html` and ten lines of status |
+| `/brainstorm` → `/map-systems` → `/vertical-slice` | a new game or a multi-task feature | `brief.md`, `systems.md`, `slice.json`, then one `/work` per planned task |
+| `/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.
+
+## What a task carries
+
+- **Contract**: files in scope, criteria as assertions on artifacts `task verify` produces (`eq | gte | lte | exists | contains | range | image`), rigor (`prototype`: no review, 6 fix rounds · `production`: one review, 4 · `release`: two reviews, 2), a manual criterion for anything only a person can judge.
+- **Evidence**, written only by the runtime: `tests` (EditMode/PlayMode, live Pipeline or batch), `observe` (Play Mode, keys, screenshots at exact milliseconds with `--shots`, console, performance), `console`, `playtest` (scripted keys or reactive rules, probes sampled at 10 Hz), `assets` (importer settings vs the art bible), `command`.
+- **Review** by a fresh-context reviewer whose verdict must name the screenshots it looked at; `PASS` cannot carry an unresolved HIGH/BLOCKER; MEDIUM/LOW are closed with `task review --resolve ... --reason ...` and the report shows who closed what.
+- **Report**: criteria, tests per run, changes with scope marks, findings, screenshots with game time, and the token cost per agent and model read from the Claude Code transcripts (USD only when `pricing` in `.nccgs/project.json` has a row). `nccgs status` rewrites `project.html`; `nccgs release --from <tag|date> --to <tag|date|now>` writes a changelog from the tasks closed in the range.
+
+## Modes
+
+`FAST`, `BALANCE` (default) and `PERFORMANCE` set model and effort per agent (coordinator, implementer, reviewer, fast-fix, scout, playtester). They are read-only; copy one and edit the copy:
+
+```
+npx nccgs mode create --from PERFORMANCE --name mine --project .
+npx nccgs mode set --name mine --agent reviewer --model opus --effort xhigh --project .
+npx nccgs mode use mine --project .
+```
+
+`PERFORMANCE` asks for Fable for review and falls back to Opus/xhigh when the account does not have it; the report records which model reviewed. `nccgs doctor --check-models` probes the current mode's models.
+
+## Unity facts the runtime relies on
+
+Verified live, kept in `.claude/nccgs/protocols/unity-cli-notes.md` and `docs/EVIDENCE-VERIFICATION.md`: Pipeline command names are discovered at runtime, never hard-coded; `--editor-version` is always pinned from `ProjectVersion.txt`; entering Play Mode drops the Pipeline server for ~3 s on 6.3 and the runtime waits; PlayMode tests run async and are polled; `simulate_key` delivers key-down and key-up in one input update, so input is read through `InputAction`s; every Pipeline round trip costs ~0.9 s, so anything that must happen within a second of a key press is scheduled inside the Editor by one `script eval`; Run In Background is switched on for every run so an unfocused Editor does not freeze.
+
+## Layout
+
+```
+.claude/nccgs/runtime/   task CLI, Unity wrapper, hooks (managed)
+.claude/nccgs/protocols/ evidence.md, review.md, playtest.md, unity-cli-notes.md
+.claude/nccgs/ponytail/  engineering.md, complexity-review.md (MIT, adapted)
+.claude/skills/          NCCGS skills + official Unity Skills (do not edit; `nccgs update --skills-only`)
+.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`).
+
+## Licenses
+
+MIT for NCCGS (LacBird). Vendored Unity Skills: Unity Companion License (see `THIRD_PARTY_NOTICES.md`). Ponytail material: MIT, DietrichGebert.

package/THIRD_PARTY_NOTICES.md

@@ -1,38 +1,10 @@
 # Third-party notices
 
-## Ponytail
+## Official Unity Skills (vendored, unmodified)
+The directories listed in `unity-skills/manifest.json` are an unmodified snapshot of https://github.com/Unity-Technologies/skills, licensed under the Unity Companion License for Unity-dependent projects (https://unity3d.com/legal/licenses/unity_companion_license). They are installed into `.claude/skills/` and must not be edited there; NCCGS carries its own guidance in `.claude/nccgs/protocols/`.
 
-The shared package under `.claude/nccgs/packages/ponytail/` borrows and adapts
-engineering, complexity-review and deliberate-simplification guidance from
-**Ponytail by DietrichGebert**, v4.10.3, commit
-`c982cd411abb53323c4baa1baa3c2f020b8d0b08`.
+## Ponytail (adapted)
+`template/ponytail/engineering.md` and `complexity-review.md` adapt material from Ponytail by DietrichGebert, v4.10.3, commit c982cd411abb53323c4baa1baa3c2f020b8d0b08, MIT License. The complete license and the attribution/change notice ship in `template/ponytail/LICENSE` and `NOTICE.md`.
 
-Source: https://github.com/DietrichGebert/ponytail
-
-Copyright (c) 2026 DietrichGebert. Licensed under the **MIT License**. The complete
-original [license](.claude/nccgs/packages/ponytail/LICENSE) and
-[attribution with adaptation details](.claude/nccgs/packages/ponytail/NOTICE.md)
-are included and installed with the shared package. Retain them on redistribution.
-This is an NCCGS adaptation, not the unmodified Ponytail plugin.
-
-## Claude Code Game Studios
-
-NCCGS was informed by the workflow, traceability, brownfield adoption, and QA
-ideas in Donchitos/Claude-Code-Game-Studios. The supplied source is MIT licensed.
-NCCGS replaces its multi-engine agent hierarchy rather than redistributing that
-hierarchy verbatim.
-
-Source: https://github.com/Donchitos/Claude-Code-Game-Studios
-
-## Unity Skills
-
-The directories identified in `.claude/nccgs/unity-skills-manifest.json` are an
-unmodified snapshot of Unity Technologies' Unity Skills. Unity Skills are
-copyright Unity Technologies and are governed by the Unity Companion License for
-Unity-dependent projects.
-
-Source: https://github.com/Unity-Technologies/skills
-
-License: https://unity3d.com/legal/licenses/unity_companion_license
-
-Do not remove this notice when redistributing NCCGS with the vendored snapshot.
+## Prior work
+NCCGS 3 is a fresh implementation informed by NCCGS 2.x (LacBird) and by Donchitos/Claude-Code-Game-Studios (MIT). No code is copied from either.

package/bin/nccgs.mjs

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

package/cli/doctor.mjs

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

package/cli/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;
+}