nccgs 2.1.1 → 3.0.0-rc.2

package/scripts/sync-unity-skills.mjs

@@ -1,126 +1,42 @@
-import crypto from "node:crypto";
+#!/usr/bin/env node
+// Sync the vendored Unity skills from a local clone of Unity-Technologies/skills and pin the commit.
+//   git clone https://github.com/Unity-Technologies/skills upstream-skills
+//   node scripts/sync-unity-skills.mjs --from upstream-skills [--only unity-cli,ui]
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { walk, sha256File, toPosix, writeJson, readJson } from "../runtime/core/fs.mjs";
 
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const root = path.resolve(scriptDir, "..");
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const args = process.argv.slice(2);
-const dryRun = args.includes("--dry-run");
-const sourceIndex = args.indexOf("--source");
-
-if (sourceIndex < 0 || !args[sourceIndex + 1]) {
-  console.error("Usage: node scripts/sync-unity-skills.mjs --source <UnitySkills directory> [--dry-run]");
-  process.exit(2);
-}
-
-const source = path.resolve(args[sourceIndex + 1]);
-if (!fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
-  console.error(`Unity Skills source directory does not exist: ${source}`);
-  process.exit(2);
-}
-
-const reserved = new Set(["work", "design", "audit", "migrate-project", "test", "review", "release", "status"]);
-const skillNames = fs.readdirSync(source, { withFileTypes: true })
-  .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(source, entry.name, "SKILL.md")))
-  .map((entry) => entry.name)
-  .sort((a, b) => a.localeCompare(b));
-
-if (!skillNames.length) {
-  console.error(`No Unity Skills containing SKILL.md were found in: ${source}`);
-  process.exit(2);
-}
-
-for (const name of skillNames) {
-  if (reserved.has(name)) {
-    console.error(`Unity Skill collides with an NCCGS public skill: ${name}`);
-    process.exit(2);
+const val = f => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const from = val("--from"); if (!from) { console.error("--from <clone of Unity-Technologies/skills> is required"); process.exit(2); }
+const only = val("--only")?.split(",").map(s => s.trim()).filter(Boolean);
+const srcSkills = path.join(from, "skills");
+if (!fs.existsSync(srcSkills)) { console.error(`${srcSkills} not found`); process.exit(2); }
+const rev = spawnSync("git", ["-C", from, "rev-parse", "HEAD"], { encoding: "utf8" }).stdout.trim() || "unknown-local-copy";
+const out = path.join(root, "unity-skills");
+const previous = readJson(path.join(out, "manifest.json"), { skills: [] });
+const names = only ?? fs.readdirSync(srcSkills).filter(n => fs.existsSync(path.join(srcSkills, n, "SKILL.md")));
+const skills = [];
+for (const name of names) {
+  const dir = path.join(srcSkills, name);
+  if (!fs.existsSync(dir)) { console.error(`skip ${name}: not upstream`); continue; }
+  fs.rmSync(path.join(out, name), { recursive: true, force: true });
+  const files = [];
+  for (const file of walk(dir)) {
+    const rel = toPosix(path.relative(dir, file));
+    if (rel.startsWith(".git/") || rel === ".gitignore") continue;
+    const dst = path.join(out, name, rel);
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(file, dst);
+    files.push({ path: rel, sha256: sha256File(dst) });
   }
+  skills.push({ name, files });
 }
-
-const skillsRoot = path.join(root, ".claude", "skills");
-const manifestPath = path.join(root, ".claude", "nccgs", "unity-skills-manifest.json");
-let previous = { skills: [] };
-if (fs.existsSync(manifestPath)) {
-  previous = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-}
-const previousNames = new Set((previous.skills ?? []).map((item) => item.name));
-
-for (const name of skillNames) {
-  const destination = path.join(skillsRoot, name);
-  if (fs.existsSync(destination) && !previousNames.has(name)) {
-    console.error(`Destination collides with a non-vendored skill: .claude/skills/${name}`);
-    process.exit(2);
-  }
-}
-
-console.log(`${dryRun ? "Would sync" : "Syncing"} ${skillNames.length} Unity Skills from ${source}`);
-for (const name of skillNames) console.log(`- ${name}`);
-if (dryRun) process.exit(0);
-
-fs.mkdirSync(skillsRoot, { recursive: true });
-fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-
-const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-const stage = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-unity-skills-"));
-const backupRoot = path.join(root, ".nccgs-maintenance", "unity-skills-backups", stamp);
-
-try {
-  for (const name of skillNames) {
-    fs.cpSync(path.join(source, name), path.join(stage, name), { recursive: true });
-  }
-
-  for (const name of new Set([...previousNames, ...skillNames])) {
-    const destination = path.join(skillsRoot, name);
-    if (!fs.existsSync(destination)) continue;
-    fs.mkdirSync(backupRoot, { recursive: true });
-    fs.renameSync(destination, path.join(backupRoot, name));
-  }
-
-  for (const name of skillNames) {
-    fs.cpSync(path.join(stage, name), path.join(skillsRoot, name), { recursive: true });
-  }
-
-  const manifest = {
-    schema_version: 1,
-    source_repository: "https://github.com/Unity-Technologies/skills",
-    source_label: path.basename(source),
-    source_revision: "unknown-local-copy",
-    synced_at: new Date().toISOString(),
-    license: "Unity Companion License for Unity-dependent projects",
-    license_url: "https://unity3d.com/legal/licenses/unity_companion_license",
-    policy: "Vendored files are upstream-managed and must remain unmodified.",
-    skills: skillNames.map((name) => ({
-      name,
-      files: walk(path.join(skillsRoot, name)).map((file) => ({
-        path: posix(path.relative(path.join(skillsRoot, name), file)),
-        bytes: fs.statSync(file).size,
-        sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"),
-      })),
-    })),
-  };
-  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-  console.log(`Unity Skills manifest written: ${manifestPath}`);
-  if (fs.existsSync(backupRoot)) console.log(`Previous snapshot backed up: ${backupRoot}`);
-} catch (error) {
-  console.error(`Unity Skills sync failed: ${error.message}`);
-  console.error(`The package may be restored from: ${backupRoot}`);
-  process.exit(1);
-} finally {
-  if (fs.existsSync(stage)) fs.rmSync(stage, { recursive: true, force: true });
-}
-
-function walk(directory) {
-  const output = [];
-  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-    const full = path.join(directory, entry.name);
-    if (entry.isDirectory()) output.push(...walk(full));
-    else if (entry.isFile()) output.push(full);
-  }
-  return output.sort((a, b) => a.localeCompare(b));
-}
-
-function posix(value) {
-  return value.split(path.sep).join("/");
-}
+// keep previously vendored skills that were not re-synced (when --only was used)
+for (const s of previous.skills) if (!skills.some(x => x.name === s.name) && only) skills.push(s);
+skills.sort((a, b) => a.name.localeCompare(b.name));
+writeJson(path.join(out, "manifest.json"), { schema_version: 2, source_repository: "https://github.com/Unity-Technologies/skills", source_label: "UnitySkills", source_revision: rev, synced_at: new Date().toISOString(), license: "Unity Companion License for Unity-dependent projects", license_url: "https://unity3d.com/legal/licenses/unity_companion_license", policy: "Vendored files are upstream-managed and must remain unmodified.", skills });
+console.log(`synced ${skills.length} skills at ${rev}`);

package/template/CLAUDE.md

@@ -0,0 +1,39 @@
+# NCCGS project rules
+
+This Unity project runs under NCCGS 3: a task is done when the game has run and been looked at, not when the code has been written.
+
+## Source of truth, in this order
+1. The user's current instruction.
+2. `.nccgs/state.md` (decisions and recent tasks) and the project's own design documents.
+3. The open task's contract (`.nccgs/tasks/<id>.json`): criteria, files in scope, rigor.
+4. Existing project code and test patterns.
+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. `/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.
+`task close` is the only thing that makes a task DONE. Reporting `partial` or `blocked` honestly is always allowed.
+
+## Unity
+- Transport is the Unity CLI and `com.unity.pipeline` only. Never install, configure or call a Unity MCP server.
+- Discover Pipeline command names at runtime (`unity command --detail compact --format json --project-path .`); never hard-code them. Names changed in Pipeline 0.9 (`editor_play` → `editor.playmode start`). See `.claude/nccgs/protocols/unity-cli-notes.md`.
+- Always pass `--editor-version` from `ProjectSettings/ProjectVersion.txt` to `unity test`/`run`/`open`; opening a project with a newer Editor upgrades it irreversibly.
+- Prefer `unity command` (scene, prefab, component, asset groups) over hand-editing `.unity`/`.prefab`/`.asset`/`.meta`.
+- After `editor.playmode start`, wait for `unity status` to report `ready` before the next command.
+
+## Code
+- Read `.claude/nccgs/ponytail/engineering.md` before designing a change: understand the flow, reuse before writing, keep the whole contract.
+- Simplicity rules apply to logic and infrastructure. They never apply to player feedback (VFX, audio, UI animation, juice).
+- Every criterion in a contract has a test or a runtime measurement. Bug fixes get a regression test.
+- Mark deliberate shortcuts `// ponytail: <limit>; revisit when <trigger>` so `task close` can list them.
+
+## Evidence
+- Only `task verify` writes `.nccgs/evidence/measurements/` and `screens/`. You never author evidence.
+- A verdict from the reviewer must name the screenshots it looked at.
+- Observed model/effort is recorded separately from requested model/effort; unknown stays unknown.
+
+## Safety
+- Hooks block destructive git, Unity MCP routes and edits to vendored skills/evidence; they warn on serialized-asset edits. They are guards, not a sandbox: review your own diff before closing.
+- Do not commit, push, publish or change project settings/packages without being asked.

package/template/agents/fast-fix.md

@@ -0,0 +1,9 @@
+---
+name: nccgs-fast-fix
+description: "Small, local, reversible fix in one or two files while the main session continues other work. Not for gameplay semantics, saves, networking, dependencies or anything player-visible."
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: {{model}}
+{{effort_line}}maxTurns: 40
+---
+
+Make the smallest change that satisfies the one requirement in your prompt (mode {{mode}}). Inspect the affected code and its direct callers, change it, run the targeted test with `node .claude/nccgs/runtime/task/task.mjs verify --id <task> --kind tests --filter <name>`, and report the diff and the result. If the fix needs a design decision, a new dependency, or touches a scene/prefab, stop and hand back instead.

package/template/agents/implementer.md

@@ -0,0 +1,19 @@
+---
+name: nccgs-implementer
+description: "Implements one NCCGS task contract in a Unity project with a clean context: edits code and assets, runs `task verify`, looks at the results, fixes, and hands back. Use for tasks too large for the main session to hold."
+tools: Read, Glob, Grep, Bash, Write, Edit
+model: {{model}}
+{{effort_line}}maxTurns: 150
+---
+
+You implement one task contract (mode {{mode}}). The prompt gives you the task id, the criteria, the files in scope and how to try the result. Read `CLAUDE.md` and `.claude/nccgs/protocols/unity-cli-notes.md` first; read `.claude/nccgs/ponytail/engineering.md` before designing the change.
+
+Loop until the criteria pass or you run out of fix rounds:
+
+1. Understand the affected flow before editing (callers, shared state, serialization).
+2. Edit only files in scope. Prefer `unity command` for scenes, prefabs and components over hand-editing YAML.
+3. Run `node .claude/nccgs/runtime/task/task.mjs verify --id <task> --kind tests` and, when the change is player-visible, `--kind observe --keys <keys>`.
+4. Look: open the screenshots the verify step produced and read the console summary. Decide from what you see, not from what you expect.
+5. Fix objective failures (`task fix --id <task>` counts the round). Subjective doubts go back to the coordinator as a question with 2-4 options, not a guess.
+
+Hand back: what changed (files), the verify results, open questions, and what a person should try in the Editor. Do not declare DONE; the coordinator closes the task after review.

package/template/agents/playtester.md

@@ -0,0 +1,15 @@
+---
+name: nccgs-playtester
+description: "Reads playtest telemetry and screenshots and judges feel with evidence. Runs scripted playtests through the task CLI when asked. Does not edit code."
+tools: Read, Glob, Grep, Bash
+model: {{model}}
+{{effort_line}}maxTurns: 60
+---
+
+You judge how the game plays, from evidence, for the question in your prompt (for example "does forgiveness feel fair or too easy?"). Mode {{mode}}.
+
+1. If the prompt names a playtest spec and no artifact yet: `node .claude/nccgs/runtime/task/task.mjs verify --id <task> --kind playtest --spec <spec>`; for a visual question also `... --kind observe --shots <ms,...>`.
+2. Read the artifact under `.nccgs/evidence/measurements/`: `summary` first, then scan `samples` for the moments that matter (death, first jump, speed changes). Open every screenshot named with the Read tool.
+3. Compare runs when there are several (different patterns or seeds): same seed, different presses = what the player's timing changes.
+
+Report in this order: what was run (presses, duration, seed), what the numbers say (distance, time of death and its cause if a probe shows it, counts), what the screens show, your judgement on the question with the evidence that supports it, then 2–4 concrete options for the person with the trade-off of each (tuning numbers, a rule change, keep as is). Do not change code or numbers yourself, do not leave Play Mode running, and never present a guess as a measurement.

package/template/agents/reviewer.md

@@ -0,0 +1,19 @@
+---
+name: nccgs-reviewer
+description: "Independent reviewer with a clean context. Reads the diff, the screenshots and the measurements for one NCCGS task and returns a verdict file. Never implements fixes."
+tools: Read, Glob, Grep, Bash
+model: {{model}}
+{{effort_line}}maxTurns: 200
+---
+
+You are the independent reviewer for an NCCGS task (mode {{mode}}). You did not write this change and you have not seen the conversation that produced it; that is the point.
+
+Your input is a prompt file under `.nccgs/evidence/review/<task>-prompt.md`. Follow it exactly:
+
+1. Read every file in scope and every changed file it lists. Read the Unity scripts, not just the diff.
+2. Open every screenshot it lists with the Read tool and describe what you see before judging. A verdict that does not list the screens you viewed is rejected by the ledger.
+3. Check each criterion against the evidence artifacts (`.nccgs/evidence/measurements/*.json`): is the evidence real, produced by Unity, and does it match the snapshot in the prompt?
+4. Apply the complexity pass in `.claude/nccgs/ponytail/complexity-review.md` to logic and infrastructure code only. Never ask for less feedback to the player (VFX, audio, UI animation, juice) in the name of simplicity.
+5. Bash is for read-only inspection (`git diff`, `git log`, `unity command ... get/status`). Do not edit, do not run Play Mode, do not fix anything.
+
+Write the verdict JSON exactly where the prompt says, with `verdict`, `snapshot`, `summary`, `screensViewed`, `findings[]` (severity BLOCKER | HIGH | MEDIUM | LOW, title, file, detail). PASS only when every criterion passes on that snapshot and no HIGH/BLOCKER finding is open. Then reply with two sentences: the verdict and the single most important finding.

package/template/agents/scout.md

@@ -0,0 +1,9 @@
+---
+name: nccgs-scout
+description: "Read-only scout: answers one factual question about the codebase or project (where is X, what calls Y, which prefab uses Z) without polluting the main context."
+tools: Read, Glob, Grep, Bash
+model: {{model}}
+{{effort_line}}maxTurns: 30
+---
+
+Answer the one question in your prompt with file paths and line references (mode {{mode}}). Bash is for read-only commands only (`grep`, `git log`, `unity command ... get/find`). Reply in at most ten lines: the answer, the evidence, and anything that contradicts it. Do not edit files.

package/template/ponytail/README.md

@@ -0,0 +1,8 @@
+# Ponytail (adapted) in NCCGS 3
+
+Two modules borrowed and adapted from Ponytail by DietrichGebert (MIT, see LICENSE and NOTICE.md):
+
+- `engineering.md` - read before designing or implementing a change: understand the flow, reuse before writing, keep the whole contract.
+- `complexity-review.md` - the reviewer's extra pass on logic and infrastructure code.
+
+NCCGS 3 additions (not upstream): simplicity never applies to player feedback (VFX, audio, UI animation, juice); the Unity reuse ladder prefers packages already in `Packages/manifest.json`, ScriptableObjects over custom config systems, and existing assembly definitions; `// ponytail:` markers are collected by `task close` into the report's deliberate-debt list; tests are never cut in the name of "only what the task needs".

package/{.claude/nccgs/packages → template}/ponytail/engineering.md

@@ -66,3 +66,13 @@ Report what changed, reuse/root-cause rationale when material, executed evidence
 unverified behavior and remaining decisions. Keep the existing NCCGS handoff and
 status format, including COMPLETE versus product PASS. Do not impose a three-line
 limit, suppress failures or generate an extra report solely for this package.
+
+## NCCGS 3 additions
+
+**Player feedback is exempt from simplification.** VFX, audio cues, UI animation, camera shake, hit-stop, particles and other "juice" are part of the requirement even when the brief does not list them. Do not remove or shrink them to shorten a diff; if they are missing from the brief, ask.
+
+**Unity reuse ladder.** Before writing infrastructure: (1) a package already in `Packages/manifest.json` (Input System, Cinemachine, Addressables, Localization); (2) a ScriptableObject for data and tuning instead of a custom config system; (3) the existing assembly definitions and folder layout; (4) a built-in Unity feature (Animator, NavMesh, Physics layers) over a hand-rolled one. Verify the version in the manifest before relying on an API.
+
+**Tests are not scope.** "Only what the task needs" never means fewer tests: every criterion keeps its test or measurement, and a bug fix keeps its regression test.
+
+**Markers.** `// ponytail: <limit and affected behaviour>; revisit when <measurable trigger>; upgrade <path>` is collected by `task close` into the report.

package/template/protocols/evidence.md

@@ -0,0 +1,52 @@
+# Evidence and criteria
+
+A criterion is a claim about the game that an artifact produced by Unity can confirm. Claude writes the criteria at `task open`; `task verify` produces the artifacts; `task close` evaluates them on the current source snapshot.
+
+## Criteria JSON
+
+```json
+[
+  {
+    "id": "dash-iframe",
+    "description": "No damage is taken during the first 0.2 s of a dash",
+    "assertions": [
+      { "artifact": ".nccgs/evidence/measurements/T-1-tests.json", "pointer": "/failed", "op": "eq", "value": 0 },
+      { "artifact": ".nccgs/evidence/measurements/T-1-tests.json", "pointer": "/passed", "op": "gte", "value": 1 }
+    ]
+  },
+  {
+    "id": "feel",
+    "description": "The dash feels responsive (person decides after playing)",
+    "kind": "manual"
+  }
+]
+```
+
+Operators: `eq`, `gte`, `lte`, `range` (`min`/`max`), `contains` (string or array), `exists` (file present and non-empty), `image` (PNG at least 64 px; a single-colour image is valid - an empty scene is blue). `kind: "manual"` criteria are decided by a person at `task close --decide feel=accepted`.
+
+## Artifacts `task verify` produces
+
+| `--kind` | Artifact | Fields |
+|---|---|---|
+| `tests` | `measurements/<id>-tests.json` (`--name X` writes `<id>-X.json`, e.g. `--mode playmode --name playmode`) | `source` (pipeline/batch), `total`, `passed`, `failed`, `skipped`, `failures[] {name, message}`, `durationSec`. A live PlayMode run starts async and polls `test status`; a Pipeline-level failure is `ok: false`, never 0/0 |
+| `observe` | `measurements/<id>-observe.json` + `screens/<id>/NN.png` | `enteredPlayMode`, `exitedPlayMode`, `exceptionCount`, `compilationFailed`, `consoleCounts`, `screens[]`, `keys[]`, `keyPresses`, `logMatches` (count of Play Mode log entries matching `--match-log <regex>`), `performance {render, memory, frameTiming}`. `--keys A,B` are pressed once, after the first hold and before frame 1 (frame 1 = the reaction, frame 2 = settled); `--keys-every-frame` repeats them before every frame. **Timed mode** `--shots 380,1200 [--hold-key 60]`: one `script eval` schedules the key down at t=0, key up after `hold-key` ms and a `ScreenCapture` at each offset inside the Editor (`timed: true`, `screens[].atMs`); use it for anything that happens within ~1 s of a press, since each Pipeline round trip costs ~0.9 s. `atMs` counts from the moment the schedule ran, about 2 s after Play (`scheduleDelayMs`); `screens[].gameTimeS` is `Time.timeSinceLevelLoad` at each capture and is the number to quote. `matchLog` records the pattern `logMatches` counted. Run In Background is switched on for the run so an unfocused Editor does not freeze Play Mode |
+| `console` | `measurements/<id>-console.json` | `counts`, `groundTruth.compilationFailed`, `entries[]` |
+| `playtest` (`--spec file`) | `measurements/<id>-playtest-<name>.json` | `presses`, `ranS`, `stoppedEarly`, `summary` per probe (`final`, `min`/`max`, `initial`/`changedAtS`), `samples[]` at 10 Hz, `console`; see `protocols/playtest.md` |
+| `assets` (`--spec file`) | `measurements/<id>-assets.json` | `checked`, `mismatchCount`, `mismatches[] {path, field, expected, actual}`, `assets[]` as the importer reports them |
+| `command` | `measurements/<id>-<name>.json` | `exitCode`, `timedOut`, `stdout`, `stderr` |
+
+Every artifact carries the snapshot it was produced on. A snapshot is a content hash of `Assets/`, `Packages/` and `ProjectSettings/` (files the Editor rewrites on its own, such as `ProjectSettings/ShaderGraphSettings.asset`, are excluded; see `files.volatile` in `.nccgs/project.json`), so entering Play Mode does not change it. An artifact older than the current source is `stale`; `task close --outcome success` refuses until `task verify` runs again.
+
+Reviewer findings stay attached to the task. After you fix a MEDIUM or LOW finding, record it: `task review --id <id> --resolve <index or title words> --reason "what changed"`; the report shows who resolved it and why. HIGH and BLOCKER findings are resolved only by a new review verdict.
+
+## What makes evidence good
+
+- Produced by Unity, not by Claude. Hooks block writes to `measurements/` and `screens/`.
+- Tied to the player's experience: the observe criterion exists so that "tests pass" can never close a task whose scene does not load.
+- Minimal: three to six criteria per task. More criteria mean more time looking at artifacts and less time looking at the game.
+- Honest when missing: `UNVERIFIED` is a status, not a failure to hide.
+
+## Default observe criterion
+
+Added automatically at rigor ≥ production when files in scope match scenes, prefabs, UI or shaders:
+`enteredPlayMode == true`, `exceptionCount == 0`, `screens/<id>/01.png` is an image. You can add assertions (for example `performance/frameTiming/cpuFrameTimeMs lte 16.7`) but not remove these at production/release rigor.

package/template/protocols/playtest.md

@@ -0,0 +1,45 @@
+# Playtest protocol
+
+A playtest is a scripted run inside the live Editor with telemetry, produced by `task verify --kind playtest --spec <file>`. The Editor presses the keys, samples the probes and writes the data; nobody types numbers by hand.
+
+## Spec (`.nccgs/design/playtests/<name>.json`)
+
+```json
+{
+  "name": "space-every-0.9s",
+  "durationS": 30,
+  "holdS": 1,
+  "sampleMs": 100,
+  "pattern": { "key": "Space", "everyS": 0.9, "fromS": 0.5, "holdMs": 60 },
+  "probes": [
+    { "name": "distance", "expr": "Runner.Instance.DistanceTravelled" },
+    { "name": "alive", "expr": "GameState.IsRunning" },
+    { "name": "speed", "expr": "Runner.Instance.speed" }
+  ],
+  "stopWhen": "!GameState.IsRunning",
+  "reset": "UnityEngine.SceneManagement.SceneManager.LoadScene(UnityEngine.SceneManagement.SceneManager.GetActiveScene().name)",
+  "settleS": 0.5
+}
+```
+
+- The schedule lands 2–3 s after Play started (Pipeline round trips), so the game is already mid-run; `reset` is a C# statement run at schedule time (reload the scene, call your game's restart) and the timeline starts `settleS` later. Every sample carries `gameTime` (`Time.timeSinceLevelLoad`) beside `t`.
+
+- `keys: [{ "at": 0.9, "key": "Space", "holdMs": 60 }, ...]` is an explicit timeline; `pattern` expands to one. Key names are Input System `Key` values.
+- `probes[].expr` is a C# expression over the game's public static surface, evaluated every `sampleMs` inside the Editor. A probe that throws samples as `null` instead of failing the run. Keep probes cheap; they run on the main thread.
+- `stopWhen` ends the run early (death, win, menu). `durationS` is the cap.
+- `rules: [{ "name": "jump-near-hazard", "when": "<C# bool expr>", "key": "Space", "holdMs": 60, "cooldownS": 0.3 }]` is reactive input: the key is pressed whenever `when` holds (after the cooldown). A metronome pattern never lines up with hazards; a rule plays like a person. Example for a runner: `"when": "System.Array.Exists(UnityEngine.Object.FindObjectsByType<Hazard>(UnityEngine.FindObjectsSortMode.None), h => h.transform.position.x > -3f && h.transform.position.x < -0.8f)"`. The artifact reports presses per rule (`rulePresses`).
+
+## Artifact (`measurements/<id>-playtest-<name>.json`)
+
+`presses`, `plannedPresses`, `ranS`, `stoppedEarly`, `stoppedAtS`, `summary` (`gameTimeStartS`/`gameTimeEndS` and (per probe: `final`, `min`/`max` for numbers, `initial`/`changedAtS` for booleans, so "death time" is `summary.alive.changedAtS`), `samples[]` (the full 10 Hz telemetry), `console` (warnings and errors logged during the run), `csv` (the raw file).
+
+## Criteria on a playtest
+
+```json
+{ "artifact": ".nccgs/evidence/measurements/<id>-playtest-space-every-0.9s.json", "pointer": "/summary/distance/final", "op": "gte", "value": 40 }
+{ "artifact": "...", "pointer": "/summary/alive/changedAtS", "op": "gte", "value": 8 }
+```
+
+## Judgement
+
+Numbers say what happened; the `nccgs-playtester` agent reads the artifact (and the screenshots, if an observe ran) and answers the feel question with evidence, ending in 2–4 options for the person. Feel decisions are never made by the coordinator alone.

package/template/protocols/review.md

@@ -0,0 +1,34 @@
+# Independent review
+
+Review exists to catch what the author cannot see. It is independent because the reviewer runs in a fresh context (the `nccgs-reviewer` subagent) and receives only the ledger's prompt: contract, evidence, changed files, screenshots.
+
+## Flow
+
+1. Coordinator: `task review --id <id>` writes `.nccgs/evidence/review/<id>-prompt.md` and prints the snapshot the review is bound to.
+2. Coordinator invokes the `nccgs-reviewer` subagent with the prompt file's contents. Nothing else from the conversation.
+3. Reviewer reads code and artifacts, opens every screenshot, writes `.nccgs/evidence/review/<id>-verdict.json`.
+4. Coordinator: `task review --id <id> --import [--model <observed>]`. The ledger rejects a verdict that lacks `screensViewed` when screenshots exist, that is not bound to a snapshot, or that says PASS with an open HIGH/BLOCKER finding.
+5. CHANGES_REQUIRED → fix (`task fix`), `task verify`, new review. A review on an older snapshot does not count for `task close`.
+
+## Verdict file
+
+```json
+{
+  "verdict": "PASS | CHANGES_REQUIRED | BLOCKED",
+  "snapshot": "<sha from the prompt>",
+  "summary": "Two sentences.",
+  "screensViewed": [".nccgs/evidence/screens/T-1/01.png"],
+  "findings": [
+    { "severity": "BLOCKER | HIGH | MEDIUM | LOW", "title": "", "file": "Assets/...", "detail": "", "resolved": false }
+  ],
+  "model": "the model the reviewer ran as, if known"
+}
+```
+
+## Rigor
+
+prototype: no review. production: one PASS on the current snapshot. release: two PASSes; the second reviewer should run on a different model than the implementer (set `review.model` in `.nccgs/project.json`).
+
+## Model
+
+The reviewer's model comes from the active mode. When the requested model is unavailable (for example Fable on an account without it), the subagent call fails; re-run it with the mode's fallback and pass `--model` on import so the report records what actually reviewed. Requested and observed models are never conflated.

package/template/protocols/unity-cli-notes.md

@@ -0,0 +1,56 @@
+# Unity CLI notes
+
+The official `unity-cli` and `unity-pipeline` skills (vendored, unmodified) are the reference for commands and parameters. This file is the NCCGS overlay: what we measured on real Editors that the skills do not say, and what the runtime relies on.
+
+Read this right after the `unity-cli` skill. The vendored skill is upstream's text; this file carries what upstream has not caught up with yet (verified on 2026-11-04 with Unity CLI 1.0.0-beta.14 and com.unity.pipeline 0.9.x on Editors 6000.3.17f1 and 6000.6.7f1). When the skill and this file disagree, this file wins.
+
+## Pipeline 0.9 renamed every command
+
+Commands are now `<group> <name>` (two argv tokens). Old flat names fail with "No command named 'editor_play' is available". Discover the catalog at runtime and never hard-code names:
+
+```
+unity command --detail compact --limit 500 --format json --project-path <project>   # 166 commands in 37 groups
+unity command --query <text> --format json --project-path <project>                 # JSON schema per command
+unity command --obsolete-command-names --format json --project-path <project>       # old -> new table
+```
+
+The renames you will meet most:
+
+| Old | New |
+|---|---|
+| `editor_play` / `editor_stop` | `editor.playmode start` / `editor.playmode stop` |
+| `screenshot` | `capture screenshot` (`--view game|scene --output <abs path> --width --height`) |
+| `eval` / `eval_file` | `script eval --code "<C#>"` / `script eval_file` |
+| `run_tests` / `test_status` / `list_tests` | `test run --mode editor|playmode [--filter]` / `test status` / `test list` |
+| `get_console` / `console_status` / `clear_console` | `console get --tail --level log|warn|error --since` / `console status` / `console clear` |
+| `get_scene_hierarchy` / `save_scene` / `open_scene` | `scene get_hierarchy` / `scene save` / `scene open` |
+| `create_gameobject` / `find_gameobjects` / `set_transform` | `gameobject create` / `gameobject find` / `gameobject set_transform` |
+| `add_component` / `attach_script` / `create_script` / `recompile` | `component add` / `script attach` / `script create` / `script recompile` |
+| `instantiate_prefab` | `prefab instantiate` |
+| `simulate_key` / `simulate_pointer` | `runtime simulate_key --key Space --action press` / `runtime simulate_pointer --x --y` |
+| `batch` | `job batch` (transactional, one Undo step; `job wait` waits server-side for a condition) |
+| `build` / `build_status` | `build run` / `build status` |
+
+Other 0.9 changes: `[CliCommand]` takes the group first; Code Reload is now Method Reload (`[MethodReload]`, group `script.methodreload`); each command has its own default timeout and honours `--timeout`.
+
+## The live Editor is the primary target
+
+- `unity test <project>` starts a **batch** Editor and fails with exit 6 "already open in a running Editor" when the project is open in the GUI. With an open Editor use Pipeline `test run` instead (returns `Summary {Total, Passed, Failed, Skipped}` and `Results[]` in seconds). NCCGS `task verify --kind tests` chooses automatically from `unity status`.
+- `unity status --format json` lists instances with `projectPath`, `editorVersion`, `port`, `state`. A batch-mode Editor is not listed there; confirm it with `unity command --project-path`.
+- After `editor.playmode start`, Unity 6.3 reloads the domain and the Pipeline server is gone for about 3 s (`EDITOR_NOT_RUNNING`, exit 12). Poll `unity status` until `ready` before the next command. 6.6 did not drop in our runs; wait anyway.
+- Screenshots: `capture screenshot --view game --output <absolute path>` writes the file where you say. `capture game_view --save_path` writes **under `Assets/`** and pollutes the project; avoid it.
+- Input: `runtime simulate_key` delivers key-down and key-up inside **one** Input System update, so polling `Keyboard.current.<key>.wasPressedThisFrame` in `Update` never sees it. Read input through an `InputAction` (`performed` callback) instead; it fires once per press for simulated and real keys alike (verified on 6000.3.17f1, Pipeline 0.9.1). Legacy `Input.GetKeyDown` is not driven at all.
+- `script eval` code is a method body: no `using` directives; fully qualify everything outside `UnityEngine`/`UnityEditor` (`UnityEngine.InputSystem.Keyboard.current`). A lambda registered on `UnityEditor.EditorApplication.update` keeps running after the eval returns, which is how `observe --shots` times key-up and `ScreenCapture.CaptureScreenshot` to the millisecond. `runtime simulate_key --action down|up` exists too, but each call is a ~0.9 s round trip.
+- Play Mode freezes when the Editor window loses focus unless Run In Background is on. `editor.playmode set_run_in_background --enable true|false` overrides the Player Setting for the session and restores it; `observe` does this around every run.
+- `job wait --condition '{member, target?, findType?, op, value}' --on_met '{capture: {...}}'` captures in the same frame a condition first holds (e.g. `Runner.Instance.IsJumping equals true`) and `--return_history` samples the member over time; use it when a frame must match a game state rather than a time offset.
+- PlayMode tests cannot run synchronously over the Pipeline (entering Play Mode drops the request): `test run --mode playmode --async_tests true` then poll `test status` until `completed`. `task verify --kind tests --mode playmode` does this.
+- Console: `console status` gives ground truth without entries (`compilationFailed`, `consoleErrors`, `consoleWarnings`); `console get` returns entries plus a `cursor`/`session` pair to read only new entries next time. This replaces parsing `Editor.log` (`unity logs` is the CLI's own log, not the Editor's).
+- Exit codes: `unity test` 0 pass, 8 tests failed (XML still written), 6 no verdict (compile error, license, project open), 14 timeout.
+
+## Editor versions on one machine
+
+Always pass `--editor-version <m_EditorVersion from ProjectSettings/ProjectVersion.txt>` to `unity test`, `unity run` and `unity open`. Without it the CLI may pick a newer installed Editor, and opening a project with a newer Editor upgrades it irreversibly. Never add `--allow-install` to a project command. The Pipeline package needs Unity 6.0+; `capture editor_element`/`runtime_element` need 6000.7+.
+
+## Still true from the skill
+
+Install (`unity editors install`), auth, projects, `unity pipeline install --project-path <project>`, build profiles (`build list_profiles` etc., Unity 6 only), and the `com.unity.pipeline` architecture are as the skill describes.

package/template/settings.fragment.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm -rf /*)",
+      "Bash(git push --force*)",
+      "Bash(git push -f *)",
+      "Bash(git reset --hard*)",
+      "Read(**/.env*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/session-start.mjs"], "timeout": 15 } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Bash|PowerShell", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/guard-shell.mjs"], "timeout": 10 } ] },
+      { "matcher": "Write|Edit|MultiEdit|NotebookEdit", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/guard-write.mjs"], "timeout": 10 } ] },
+      { "matcher": "mcp__.*", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/guard-mcp.mjs"], "timeout": 10 } ] }
+    ],
+    "Stop": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/done-guard.mjs"], "timeout": 10 } ] }
+    ],
+    "SubagentStart": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/session-log.mjs", "start"], "timeout": 5 } ] }
+    ],
+    "SubagentStop": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/session-log.mjs", "stop"], "timeout": 5 } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Agent|Task", "hooks": [ { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/nccgs/runtime/hooks/session-log.mjs", "agent"], "timeout": 5 } ] }
+    ]
+  }
+}

package/template/skills/art-bible/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: art-bible
+description: Write the project's visual rules - camera and world scale, pixels per unit, palette, sprite sizes and pivots, naming and folders - as a document the asset-spec checks can enforce. Use before the first real art asset or when visuals are inconsistent.
+allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion
+---
+
+# /art-bible
+
+Output: `.nccgs/design/art-bible.md` and the matching `.nccgs/design/asset-rules.json` that `/asset-spec` validates against.
+
+1. Read `.nccgs/design/brief.md`, the camera settings in the scene (`unity command scene get_hierarchy` and `gameobject find`), and any sprite already imported (`unity command asset list` or `Assets/` listing).
+2. Settle with the user, one question at a time, only what is not already decided: orthographic size and reference resolution, pixels per unit (one value for the whole project), filter mode (point for pixel art, bilinear otherwise), palette (5–8 named colours with hex), sprite size classes (player, enemy, tile, UI icon) in pixels and in units, pivot rule, naming (`spr_player_idle_01`), folder layout.
+3. Write `art-bible.md` (short, every rule with a number) and `asset-rules.json`:
+
+```json
+{ "pixelsPerUnit": 64, "filterMode": "Point", "textureType": "Sprite", "maxTextureSize": 2048, "folders": { "Assets/Art/Sprites": { "pixelsPerUnit": 64 } } }
+```
+
+End with: both paths and `next: /asset-spec <asset>` for each new asset, `/work` for anything that changes the scene.

package/template/skills/asset-spec/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: asset-spec
+description: Specify an art or audio asset before it is made and verify imported assets against the art bible (import settings, size, pivot) with a measured check. Use when an asset is requested, delivered or looks wrong in game.
+allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion
+---
+
+# /asset-spec
+
+Output: `.nccgs/design/assets/<asset>.md` (the spec) and, for delivered assets, a passing `task verify --kind assets` on the open task.
+
+1. Spec first: purpose in game, size class from `art-bible.md`, pixel size, pivot, frames (if animated), colour keys, file name and folder, how it is used (SpriteRenderer, UI, tile). Write it; share the three lines an artist needs.
+2. When the asset exists: write or extend `.nccgs/design/asset-check.json`:
+
+```json
+{ "assets": [ { "path": "Assets/Art/Sprites/spr_player_idle_01.png", "pixelsPerUnit": 64, "filterMode": "Point", "textureType": "Sprite", "maxTextureSize": 512 } ] }
+```
+
+Then `node .claude/nccgs/runtime/task/task.mjs verify --id <task> --kind assets --spec .nccgs/design/asset-check.json`. The Editor reads each importer; the artifact lists mismatches. A criterion `{ "pointer": "/mismatchCount", "op": "eq", "value": 0 }` closes the task only when every setting matches.
+3. Fix import settings through `unity command` (asset group) and re-verify; never hand-edit `.meta` files.

package/template/skills/brainstorm/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: brainstorm
+description: Turn a game idea or feature request into a brief with options the user chooses from - player fantasy, core loop, pillars, scope, first feel numbers. Use before any code when the request is a new game, mode, mechanic or "what should we build".
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
+---
+
+# /brainstorm
+
+Output: `.nccgs/design/brief.md`, agreed with the user. No code, no tasks, no Unity calls.
+
+1. Read `.nccgs/state.md` and any existing `.nccgs/design/*.md` so you build on decisions already made.
+2. Restate the ask in three lines: who plays, what they do for 30 seconds, what makes them play again.
+3. Offer 2–4 concepts with AskUserQuestion. Each concept: one sentence of fantasy, the core loop in one line, the one risk, rough scope (sessions of work). Do not pick for the user.
+4. For the chosen concept, settle with the user, one question at a time: pillars (max 3), the first playable (what the vertical slice must prove), what is out of scope, the feel numbers to start from (speeds, timings, counts: numbers, not adjectives), and which decisions are subjective and will go to a playtest.
+5. Write `.nccgs/design/brief.md` with these headings: Fantasy, Core loop, Pillars, Vertical slice proves, Feel numbers (table: name, start value, who decides), Out of scope, Open questions. Keep it under 80 lines.
+
+End with: the brief path and `next: /map-systems`.