nccgs 3.0.0-rc.2 → 3.0.0-rc.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 3.0.0-rc.4 — 2026-11-07
+
+- Pipeline 0.10.0-exp.1 (3 Nov) renamed every command parameter to kebab-case (`--async-tests`, `--since-session`, `--enabled`, `--output-path`) and rejects the 0.9 spellings. The runtime now reads parameter names from `unity command --detail full` (cache `pipeline-commands-v2-<version>.json`) and maps its own names onto them, so `task verify` works on 0.9 and 0.10 without a flag. Verified against the real 0.10 catalog from 6000.3.17f1 (the catalog is a test fixture; the fake CLI has a strict 0.10 mode).
+- Unity CLI beta.17 prints Pipeline results bare (`--format json` = the old `data.result`, the listing as `{ commands }`); the runtime reads both envelope shapes (`unwrap()`), so results, errors and the catalog work on beta.14 and beta.17. Verified live on 2026-11-07: TestNCCGS1 task PT-010 closed 5/5 on 6000.3.17f1 + beta.17 + 0.10.0-exp.1 (EditMode 43/43, PlayMode 19/19, console, timed observe, 45 s playtest).
+- `unity-cli-notes.md`: the 0.9 → 0.10 parameter table, CLI beta.16/17 facts (streamed `unity command`, new exit codes, `pipeline editors`, `editor dialog`, `unity open` wanting `--editor-version`, `pipeline install --version`).
+- Unity Skills re-synced to upstream `60f95e6` (6 Nov): 36 skills; `localization` → `localize-unity-project`, `physics-3d-collision` → `fix-3d-physics-collisions`, new `manage-cloud-build`; `unity-cli` and `unity-pipeline` updated to the kebab-case parameters.
+- `nccgs upgrade --project . [--dry-run] [--skip cli,pipeline,files]`: managed files, then `unity self-update --target` and `unity pipeline install --version … --force` to the versions in `toolchain.json` (the ones this release was verified with), then `doctor`; never downgrades; every step reported, `nccgs.upgrade` event logged.
+- Update check runs by itself: the SessionStart hook refreshes `.nccgs/cache/update-check.json` in a detached process when it is older than `updates.check` (daily default) and shows the cached notices with the `upgrade` hint. Sources: npm dist-tags (rc tag for prereleases), Unity Skills HEAD, `unity self-update --check`, `unity pipeline list-versions`. A CLI or Pipeline newer than the verified one is reported as a caution, not an upgrade hint. `doctor` gained a `toolchain` check.
+- Fix: a project's own `CLAUDE.md` is never replaced by `update`/`--force` and never listed as an override; only a `CLAUDE.md` NCCGS wrote itself is refreshed, and only while unedited (`authored` in install-state).
+- `nccgs update` now retires managed files the new version no longer ships (unchanged ones are deleted, edited ones stay and are listed as overrides), so renamed skills do not pile up in `.claude/skills/`.
+
+## 3.0.0-rc.3 — 2026-11-06
+
+- `/adopt` skill for a project that already has code, scenes, tests and design documents: inventory (versions, asmdefs, tests, scenes, the team's own documents, existing Claude rules), `brief.md` and `systems.md` written from the project as it is, decisions recorded in `state.md`, and one `ADOPT` task (existing EditMode tests, console ground truth, Play Mode + one screenshot) that proves the loop runs there. Nothing in the game changes without the user agreeing to the item. `/unity-foundation` stays the empty-project version.
+- Coming from NCCGS 2.x: `install`/`update` now recognise a 2.x install state and refuse with the exact steps (`npx nccgs@<2.x> uninstall`, then `npx nccgs@rc install`, then `/adopt`) instead of stacking two frameworks' hooks and skills. 2.x task records left in `.nccgs/tasks/` (schema 1/2) are kept as history and never listed, so they cannot block a session, a close or an uninstall.
+
 ## 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).

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.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.
+**3.0.0-rc.4.** Built and verified on Unity 6000.3 and 6000.6 with Unity CLI 1.0.0-beta.14–17 and com.unity.pipeline 0.9 and 0.10, 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/` (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`).
+`install` adds `CLAUDE.md` (kept if you have one), `.claude/skills/` (12 NCCGS skills + 36 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. On a project that still carries NCCGS 2.x, `install` stops and prints the path (`npx nccgs@2.1.1 uninstall --project .`, then `install`, then `/adopt`); 2.x records under `.nccgs/` stay as history. `run` launches Claude Code with the permission mode and MCP policy NCCGS expects (`acceptEdits` by default; `--autonomy full` for `bypassPermissions`).
 
 ## Daily use
 
@@ -35,6 +35,7 @@ Open the project in the Editor (screenshots and live tests need it; without it t
 | `/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 |
+| `/adopt` | a project that already has code, scenes, tests, documents | `brief.md` + `systems.md` from what exists, `foundation.md`, one `ADOPT` task proving the loop runs here |
 | `/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 |
@@ -62,7 +63,7 @@ npx nccgs mode use mine --project .
 
 ## 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.
+Verified live, kept in `.claude/nccgs/protocols/unity-cli-notes.md` and `docs/EVIDENCE-VERIFICATION.md`: Pipeline command names and parameter names are discovered at runtime, never hard-coded (0.9 snake_case and 0.10 kebab-case both work); `--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
 
@@ -80,7 +81,16 @@ Failures are recorded locally in `.nccgs/diagnostics.jsonl` (task CLI errors, fa
 
 ## 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`).
+Every new Claude Code session checks for updates in the background (`updates.check` in `.nccgs/project.json`: `daily` by default, `weekly`, or `never`) and the next session says what is newer: NCCGS on npm, the Unity Skills upstream, the Unity CLI and `com.unity.pipeline`. Nothing is applied on its own. `nccgs doctor --check-updates` runs the same check now, and `doctor` warns when the project's CLI or Pipeline differs from the versions this release was verified with (`toolchain.json`).
+
+To move a project to a new NCCGS release and the toolchain it was verified with:
+
+```
+npx nccgs@rc upgrade --project . --dry-run
+npx nccgs@rc upgrade --project .
+```
+
+`upgrade` runs, in order: the managed files (`nccgs update`: runtime, skills, agents, hooks; edited files are kept as overrides, files the new version no longer ships are retired), `unity self-update --target <verified CLI>`, `unity pipeline install --version <verified Pipeline> --force`, then `doctor`. It never downgrades: a newer CLI or Pipeline than the verified one is kept and reported. `--skip cli,pipeline,files` leaves a step out; with the Editor open, Unity resolves the new package on focus (restart the Editor if the Pipeline server does not come back). `nccgs update` alone refreshes managed files; `--skills-only` just the vendored Unity Skills.
 
 ## Licenses
 

package/bin/nccgs.mjs

@@ -13,6 +13,7 @@ import { allModes, createMode, setModeAgent, useMode, BUILTIN } from "../runtime
 import { renderProject } from "../runtime/task/project.mjs";
 import { release } from "../cli/release.mjs";
 import { feedback } from "../cli/feedback.mjs";
+import { upgrade } from "../cli/upgrade.mjs";
 
 const argv = process.argv.slice(2);
 const command = argv[0];
@@ -32,7 +33,8 @@ const die = m => { process.stderr.write(`nccgs ${command}: ${m}\n`); process.exi
 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 update    --project DIR [--dry-run] [--force] [--skills-only]     managed files only
+  nccgs upgrade   --project DIR [--dry-run] [--skip cli,pipeline,files]    managed files + Unity CLI + com.unity.pipeline to the verified versions, then doctor
   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]
@@ -49,6 +51,13 @@ try {
     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 "upgrade": {
+      const r = await upgrade(root, { dryRun: !!opt["dry-run"], force: !!opt.force, skip: String(str(opt.skip) ?? "").split(",").map(s => s.trim()).filter(Boolean), runDoctor: !opt["no-doctor"] });
+      for (const s of r.steps) process.stderr.write(`${s.action.toUpperCase().padEnd(8)} ${s.id.padEnd(10)} ${s.from ?? "-"} -> ${s.to ?? "-"}${s.detail ? `  ${typeof s.detail === "string" ? s.detail : JSON.stringify(s.detail)}` : ""}\n`);
+      if (r.health) process.stderr.write(`doctor: ${r.health.pass} pass · ${r.health.warn} warn · ${r.health.fail} fail${r.health.failed.length ? `  (${r.health.failed.join("; ")})` : ""}\n`);
+      if (opt.json || opt["dry-run"]) out(r);
+      process.exit(r.ok ? 0 : 1);
+    }
     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`);

package/cli/doctor.mjs

@@ -9,7 +9,7 @@ import { at, isUnityProject, loadConfig, editorVersion, pipelineVersion, version
 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 { checkUpdates } from "../runtime/core/update-check.mjs";
 import { available as jobObjectAvailable } from "../runtime/core/job-object.mjs";
 
 const MIN_CLAUDE = [2, 1, 295];
@@ -37,6 +37,11 @@ export async function doctor(root, { checkModels = false, checkUpdatesNow = fals
     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 toolchain = readJson(path.join(root, ".claude", "nccgs", "toolchain.json"), null) ?? readJson(path.join(TEMPLATE, "..", "toolchain.json"), {});
+  const tcDiff = [];
+  if (cliVersion && toolchain.unityCli && cliVersion !== toolchain.unityCli) tcDiff.push(`Unity CLI ${cliVersion} (verified ${toolchain.unityCli})`);
+  if (pipelineVersion(root) && toolchain.pipeline && pipelineVersion(root) !== toolchain.pipeline) tcDiff.push(`com.unity.pipeline ${pipelineVersion(root)} (verified ${toolchain.pipeline})`);
+  add("toolchain", tcDiff.length ? "warn" : "pass", tcDiff.length ? `${tcDiff.join(", ")}: run \`nccgs upgrade\` to move to the verified versions` : `matches the verified toolchain (CLI ${toolchain.unityCli ?? "?"}, Pipeline ${toolchain.pipeline ?? "?"}, ${toolchain.verifiedAt ?? "?"})`);
   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;
@@ -75,7 +80,7 @@ export async function doctor(root, { checkModels = false, checkUpdatesNow = fals
     }
   }
   if (checkUpdatesNow) {
-    const u = await checkUpdates(root, { force: true, cliVersion });
+    const u = await checkUpdates(root, { force: true });
     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/install.mjs

@@ -26,6 +26,7 @@ function managedFiles() {
   add(path.join(TEMPLATE, "ponytail"), ".claude/nccgs/ponytail");
   add(path.join(PKG_ROOT, "unity-skills"), ".claude/skills", rel => rel !== "manifest.json");
   list.push({ from: path.join(PKG_ROOT, "unity-skills", "manifest.json"), to: ".claude/nccgs/unity-skills-manifest.json" });
+  list.push({ from: path.join(PKG_ROOT, "toolchain.json"), to: ".claude/nccgs/toolchain.json" });
   list.push({ from: path.join(TEMPLATE, "CLAUDE.md"), to: "CLAUDE.md", keepIfExists: true });
   return list;
 }
@@ -34,10 +35,12 @@ export function install(root, { update = false, force = false, dryRun = false, m
   if (!isUnityProject(root)) throw new Error(`${root} is not a Unity project (needs Assets/ and ProjectSettings/ProjectVersion.txt)`);
   const stateFile = at(root, "installState");
   const previous = exists(stateFile) ? readJson(stateFile) : null;
+  if (previous && isLegacy(previous)) throw new Error(legacyMessage(previous));
   if (update && !previous) throw new Error("NCCGS is not installed here; use `install`");
   if (!update && previous && !force) throw new Error(`NCCGS ${previous.version} is already installed; use \`update\``);
   const actions = [];            // { action: add|replace|keep|override|skip, path }
   const inventory = {};
+  const authored = {};           // keepIfExists files we wrote ourselves (sha at write time)
   for (const item of managedFiles()) {
     if (skillsOnly && !item.to.startsWith(".claude/skills/") && !item.to.endsWith("unity-skills-manifest.json")) continue;
     const target = path.join(root, item.to);
@@ -48,17 +51,30 @@ export function install(root, { update = false, force = false, dryRun = false, m
     let action;
     if (!existsNow) action = "add";
     else if (current === incoming) action = "keep";
-    else if (item.keepIfExists && !recorded) action = "keep-user";          // e.g. the user's own CLAUDE.md
+    // keepIfExists (the project's CLAUDE.md): ours only if we wrote it and nobody edited it since; the user's own
+    // file is kept as theirs on every install/update, never counted as an override, never replaced by --force.
+    else if (item.keepIfExists) action = previous?.authored?.[item.to] && current === previous.authored[item.to] ? "replace" : "keep-user";
     else if (recorded && current === recorded) action = "replace";          // unchanged managed file, new version
     else if (force) action = "replace-forced";
     else action = "override";                                               // user changed it: keep theirs, record it
     actions.push({ action, path: item.to });
     inventory[item.to] = ["add", "replace", "replace-forced", "keep"].includes(action) ? incoming : (current ?? incoming);
+    if (item.keepIfExists && ["add", "replace", "keep"].includes(action)) authored[item.to] = incoming;
     if (!dryRun && ["add", "replace", "replace-forced"].includes(action)) {
       fs.mkdirSync(path.dirname(target), { recursive: true });
       fs.copyFileSync(item.from, target);
     }
   }
+  // Managed files the previous version shipped and this one does not (a renamed skill, a dropped protocol):
+  // removed when still unchanged, kept and listed as an override when the user edited them.
+  for (const [rel, sha] of Object.entries(previous?.files ?? {})) {
+    if (rel in inventory) continue;
+    if (skillsOnly && !rel.startsWith(".claude/skills/")) continue;
+    const target = path.join(root, rel);
+    if (!exists(target)) continue;
+    if (sha256File(target) === sha) { actions.push({ action: "retire", path: rel }); if (!dryRun) { fs.unlinkSync(target); pruneEmptyDirs(path.dirname(target), root); } }
+    else { actions.push({ action: "override", path: rel }); inventory[rel] = sha256File(target); }
+  }
   // Scaffold .nccgs (never overwritten), config, modes.
   if (!dryRun && !skillsOnly) {
     ensureLayout(root);
@@ -76,11 +92,30 @@ export function install(root, { update = false, force = false, dryRun = false, m
   }
   const overrides = actions.filter(a => a.action === "override").map(a => a.path);
   if (!dryRun) {
-    writeJson(stateFile, { schemaVersion: 3, version: PKG.version, installedAt: previous?.installedAt ?? nowIso(), updatedAt: nowIso(), editor: editorVersion(root), files: inventory, overrides });
+    writeJson(stateFile, { schemaVersion: 3, version: PKG.version, installedAt: previous?.installedAt ?? nowIso(), updatedAt: nowIso(), editor: editorVersion(root), files: inventory, overrides, authored });
   }
   return { version: PKG.version, dryRun, counts: count(actions), overrides, actions: dryRun ? actions.filter(a => a.action !== "keep") : undefined };
 }
 
+// NCCGS 2.x wrote the same state file with `frameworkVersion` and a `files` array. Its hooks live in
+// .claude/nccgs/hooks/ (not runtime/hooks/), so a 3.x install on top would leave two frameworks running.
+export const isLegacy = state => !!state && (typeof state.frameworkVersion === "string" || Array.isArray(state.files) || typeof state.version !== "string");
+function legacyMessage(state) {
+  const v = state.frameworkVersion ?? "2.x";
+  return [
+    `NCCGS ${v} is installed here. 3.x does not upgrade a 2.x install in place (its hooks, 58 skills, agents, rules and .nccgs/project.yaml would stay active next to the new ones).`,
+    `Remove 2.x with its own package first, then install 3.x:`,
+    `  npx nccgs@${/^\d/.test(v) ? v : "2"} uninstall --project . --dry-run`,
+    `  npx nccgs@${/^\d/.test(v) ? v : "2"} uninstall --project .`,
+    `  npx nccgs@rc install --project .`,
+    `2.x uninstall keeps .nccgs/ (state.md, tasks, reviews, evidence) and your CLAUDE.md; 3.x reads state.md and leaves the rest in place. Then run /adopt in Claude Code to bring the project under the 3.x loop.`
+  ].join("\n");
+}
+
+function pruneEmptyDirs(dir, stopAt) {
+  while (dir.startsWith(stopAt) && dir !== stopAt && exists(dir) && !fs.readdirSync(dir).length) { fs.rmdirSync(dir); dir = path.dirname(dir); }
+}
+
 function count(actions) { return actions.reduce((acc, a) => { acc[a.action] = (acc[a.action] ?? 0) + 1; return acc; }, {}); }
 
 // Merge our hooks and deny rules into .claude/settings.json without touching anything else.

package/cli/run.mjs

@@ -4,7 +4,7 @@ import { spawnTool } from "./spawn.mjs";
 import { readJson, exists } from "../runtime/core/fs.mjs";
 import { at, isUnityProject, loadConfig } from "../runtime/core/project.mjs";
 import { allModes } from "../runtime/core/modes.mjs";
-import { checkUpdates } from "./update-check.mjs";
+import { checkUpdates } from "../runtime/core/update-check.mjs";
 
 const OWNED = /^(--permission-mode|--dangerously-skip-permissions|--allow-dangerously-skip-permissions|--strict-mcp-config|--mcp-config|--model)(=|$)/;
 

package/cli/upgrade.mjs

@@ -0,0 +1,74 @@
+// nccgs upgrade: bring an installed project to the toolchain this NCCGS release was verified with, in order:
+//   1. managed files (= `nccgs update`: runtime, skills, agents, hooks, toolchain.json)
+//   2. Unity CLI  -> toolchain.unityCli  (`unity self-update --target <v>`; never downgrades)
+//   3. com.unity.pipeline -> toolchain.pipeline (`unity pipeline install --version <v> --force`; never downgrades)
+//   4. doctor
+// Every step is reported; --dry-run plans without touching anything; --skip cli,pipeline,files leaves a step out.
+import path from "node:path";
+import { readJson, exists, nowIso, appendLine } from "../runtime/core/fs.mjs";
+import { at, isUnityProject, pipelineVersion, manifestPackages } from "../runtime/core/project.mjs";
+import { run } from "../runtime/core/process-tree.mjs";
+import { UNITY_BIN, unityArgv, cliVersion, instanceFor } from "../runtime/unity/unity.mjs";
+import { newer } from "../runtime/core/update-check.mjs";
+import { install, isLegacy, PKG, PKG_ROOT } from "./install.mjs";
+import { doctor } from "./doctor.mjs";
+
+export const TOOLCHAIN = readJson(path.join(PKG_ROOT, "toolchain.json"), {});
+
+export async function upgrade(root, { dryRun = false, skip = [], force = false, runDoctor = true } = {}) {
+  if (!isUnityProject(root)) throw new Error(`${root} is not a Unity project`);
+  const stateFile = at(root, "installState");
+  const previous = exists(stateFile) ? readJson(stateFile) : null;
+  if (!previous) throw new Error("NCCGS is not installed here; use `nccgs install`");
+  if (isLegacy(previous)) throw new Error(`NCCGS ${previous.frameworkVersion ?? "2.x"} is installed here: remove it first (npx nccgs@${previous.frameworkVersion ?? "2"} uninstall --project .), then \`nccgs install\``);
+  const steps = [];
+  const step = (id, from, to, action, detail) => { steps.push({ id, from, to, action, ...(detail ? { detail } : {}) }); return steps.at(-1); };
+
+  // 1. managed files
+  if (!skip.includes("files")) {
+    const r = install(root, { update: true, dryRun, force });
+    step("files", previous.version, PKG.version, dryRun ? "planned" : "updated", { counts: r.counts, overrides: r.overrides });
+  } else step("files", previous.version, PKG.version, "skipped");
+
+  // 2. Unity CLI
+  const want = TOOLCHAIN.unityCli ?? null;
+  const have = await cliVersion();
+  if (skip.includes("cli")) step("unity-cli", have, want, "skipped");
+  else if (!have) step("unity-cli", null, want, "failed", "unity CLI not on PATH (install: https://unity.com/en/blog/meet-the-unity-cli)");
+  else if (!want || have === want) step("unity-cli", have, want, "kept");
+  else if (newer(have, want)) step("unity-cli", have, want, "kept", `installed CLI is newer than the verified ${want}; not downgraded`);
+  else if (dryRun) step("unity-cli", have, want, "planned", `unity self-update --target ${want}`);
+  else {
+    let r = await run(UNITY_BIN, unityArgv(["self-update", "--target", want, "--format", "json"]), { timeoutMs: 300000 });
+    if (r.code !== 0) r = await run(UNITY_BIN, unityArgv(["self-update", ...(TOOLCHAIN.unityCliChannel ? ["--channel", TOOLCHAIN.unityCliChannel] : []), "--format", "json"]), { timeoutMs: 300000 });
+    const now = await cliVersion();
+    step("unity-cli", have, want, now && now !== have ? "updated" : "failed", now && now !== have ? `now ${now}` : `self-update exit ${r.code}: ${(r.stderr || r.stdout || "").trim().slice(-300)}`);
+  }
+
+  // 3. Pipeline package
+  const wantP = TOOLCHAIN.pipeline ?? null;
+  const haveP = pipelineVersion(root);
+  if (skip.includes("pipeline")) step("pipeline", haveP, wantP, "skipped");
+  else if (!wantP || haveP === wantP) step("pipeline", haveP, wantP, "kept");
+  else if (haveP && newer(haveP, wantP)) step("pipeline", haveP, wantP, "kept", `project has a newer com.unity.pipeline than the verified ${wantP}; not downgraded`);
+  else {
+    const open = await instanceFor(root).catch(() => null);
+    const note = open ? "the Editor is open: Unity resolves the new package when the window regains focus (watch the Console; restart the Editor if the Pipeline server does not come back)" : null;
+    if (dryRun) step("pipeline", haveP, wantP, "planned", [`unity pipeline install --version ${wantP} --force --project-path .`, note].filter(Boolean).join("; "));
+    else {
+      const r = await run(UNITY_BIN, unityArgv(["pipeline", "install", "--version", wantP, "--force", "--project-path", root, "--format", "json"]), { timeoutMs: 120000 });
+      const nowP = pipelineVersion(root);
+      step("pipeline", haveP, wantP, nowP === wantP ? "updated" : "failed", nowP === wantP ? note ?? undefined : `pipeline install exit ${r.code}: ${(r.stderr || r.stdout || "").trim().slice(-300)}`);
+    }
+  }
+
+  // 4. doctor
+  let health = null;
+  if (runDoctor && !dryRun) {
+    const d = await doctor(root);
+    health = { pass: d.summary?.pass ?? 0, warn: d.summary?.warn ?? 0, fail: d.summary?.fail ?? 0, failed: d.checks.filter(c => c.status === "fail").map(c => `${c.id}: ${c.message}`) };
+  }
+  if (!dryRun) appendLine(at(root, "events"), JSON.stringify({ at: nowIso(), type: "nccgs.upgrade", from: previous.version, to: PKG.version, steps: steps.map(s => `${s.id}:${s.action}`) }));
+  const failed = steps.filter(s => s.action === "failed");
+  return { version: PKG.version, from: previous.version, toolchain: { unityCli: want, pipeline: wantP, unitySkills: TOOLCHAIN.unitySkills?.slice(0, 7) ?? null, verifiedAt: TOOLCHAIN.verifiedAt ?? null }, dryRun, steps, health, ok: failed.length === 0 && !(health?.fail), packages: manifestPackages(root)["com.unity.pipeline"] ?? null };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nccgs",
-  "version": "3.0.0-rc.2",
+  "version": "3.0.0-rc.4",
   "description": "NCCGS 3 - a Unity-first evidence loop for Claude Code: contract, run, look, review, report.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
     "scripts/",
     "docs/",
     "tools/",
+    "toolchain.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

package/runtime/core/update-check.mjs

@@ -0,0 +1,117 @@
+// Update notices: NCCGS (npm dist-tags), Unity Skills (GitHub HEAD), Unity CLI (its own check), Pipeline
+// (`unity pipeline list-versions`). Notify only; `nccgs upgrade` applies. Cached under .nccgs/cache per the
+// `updates.check` interval (daily | weekly | never). Every source has a short timeout and network failures
+// are silent. The session-start hook runs this file detached (`node update-check.mjs --project <root>`) when
+// the cache is stale, so a session never waits on the network.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readJson, writeJson, exists } from "./fs.mjs";
+import { at, loadConfig, pipelineVersion, projectRoot } from "./project.mjs";
+import { run } from "./process-tree.mjs";
+import { UNITY_BIN, unityArgv } from "../unity/unity.mjs";
+
+const DAY = 86400000;
+export const intervalMs = config => config.updates?.check === "weekly" ? 7 * DAY : config.updates?.check === "never" ? Infinity : DAY;
+
+// semver compare with prerelease: 3.0.0-rc.3 < 3.0.0-rc.4 < 3.0.0 ; 2.1.1 < 3.0.0-rc.1
+export function newer(latest, current) {
+  const parse = v => { const m = String(v).match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?/); return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null; };
+  const a = parse(latest), b = parse(current); if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a.n[i] !== b.n[i]) return a.n[i] > b.n[i];
+  if (a.pre === b.pre) return false; if (a.pre === null) return true; if (b.pre === null) return false;
+  const pa = a.pre.split("."), pb = b.pre.split(".");
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if (pa[i] === pb[i]) continue; if (pa[i] === undefined) return false; if (pb[i] === undefined) return true;
+    const na = Number(pa[i]), nb = Number(pb[i]);
+    return Number.isFinite(na) && Number.isFinite(nb) ? na > nb : pa[i] > pb[i];
+  }
+  return false;
+}
+export const isPrerelease = v => /-/.test(String(v));
+
+async function fetchJson(url, timeoutMs = 3000, ua = "nccgs") {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const r = await fetch(url, { signal: ctl.signal, headers: { "user-agent": ua, accept: "application/json" } });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; } finally { clearTimeout(t); }
+}
+const parseJson = s => { try { return JSON.parse(String(s ?? "").replace(/^/, "")); } catch { return null; } };
+
+// What is installed here (from the managed copies, so the runtime works without the npm package around).
+export function installed(root) {
+  const state = exists(at(root, "installState")) ? readJson(at(root, "installState")) : {};
+  const manifest = readJson(path.join(root, ".claude", "nccgs", "unity-skills-manifest.json"), {});
+  const toolchain = readJson(path.join(root, ".claude", "nccgs", "toolchain.json"), {});
+  return { nccgs: state.version ?? null, unitySkills: manifest.source_revision ?? null, toolchain, pipeline: pipelineVersion(root) };
+}
+
+// Sources: live, or a stub file (NCCGS_UPDATE_STUB) for tests.
+async function sources(root, cur) {
+  const stub = process.env.NCCGS_UPDATE_STUB;
+  if (stub) return readJson(stub, {});
+  const out = {};
+  const tags = await fetchJson("https://registry.npmjs.org/-/package/nccgs/dist-tags", 3000, `nccgs/${cur.nccgs ?? "?"}`);
+  if (tags) out.nccgsTags = tags;
+  const head = await fetchJson("https://api.github.com/repos/Unity-Technologies/skills/commits/main", 3000, `nccgs/${cur.nccgs ?? "?"}`);
+  if (head?.sha) out.unitySkillsHead = head.sha;
+  const ver = await run(UNITY_BIN, unityArgv(["--version"]), { timeoutMs: 15000 });
+  if (ver.code === 0) out.unityCli = ver.stdout.trim();
+  const su = await run(UNITY_BIN, unityArgv(["self-update", "--check", "--format", "json"]), { timeoutMs: 15000 });
+  const sj = parseJson(su.stdout);
+  const latest = sj?.data?.latest ?? sj?.latest ?? sj?.data?.latestVersion ?? sj?.latestVersion ?? null;
+  if (latest) out.unityCliLatest = String(latest);
+  const pl = await run(UNITY_BIN, unityArgv(["pipeline", "list-versions", "--format", "json"]), { timeoutMs: 15000 });
+  const pj = parseJson(pl.stdout);
+  const pLatest = pj?.data?.latest ?? pj?.latest ?? null;
+  if (pLatest) out.pipelineLatest = String(pLatest);
+  return out;
+}
+
+export async function checkUpdates(root, { force = false } = {}) {
+  const config = loadConfig(root);
+  const file = at(root, "updateCheck");
+  const cached = exists(file) ? readJson(file) : null;
+  if (!force && cached && Date.now() - Date.parse(cached.checkedAt) < intervalMs(config)) return cached;
+  if (config.updates?.check === "never" && !force) return { checkedAt: new Date().toISOString(), notices: [], skipped: true };
+  const channels = new Set(config.updates?.channels ?? ["nccgs", "unity-skills", "unity-cli", "pipeline"]);
+  const cur = installed(root);
+  const src = await sources(root, cur);
+  const notices = [];
+  const tag = cur.nccgs && isPrerelease(cur.nccgs) ? "rc" : "latest";
+  if (channels.has("nccgs") && cur.nccgs && src.nccgsTags) {
+    const candidates = [src.nccgsTags.latest, tag === "rc" ? src.nccgsTags.rc : null].filter(Boolean);
+    const best = candidates.sort((a, b) => (newer(a, b) ? -1 : 1))[0];
+    if (best && newer(best, cur.nccgs)) notices.push({ component: "nccgs", current: cur.nccgs, latest: best, hint: `npx nccgs@${best} upgrade --project .` });
+  }
+  if (channels.has("unity-skills") && cur.unitySkills && src.unitySkillsHead && !src.unitySkillsHead.startsWith(cur.unitySkills) && cur.unitySkills !== "unknown-local-copy") {
+    notices.push({ component: "unity-skills", current: cur.unitySkills.slice(0, 7), latest: src.unitySkillsHead.slice(0, 7), hint: "ships with the next nccgs release (vendored and pinned)" });
+  }
+  if (channels.has("unity-cli") && src.unityCli && src.unityCliLatest && newer(src.unityCliLatest, src.unityCli)) {
+    const verified = cur.toolchain?.unityCli;
+    notices.push({ component: "unity-cli", current: src.unityCli, latest: src.unityCliLatest, hint: verified && newer(src.unityCliLatest, verified) ? `newer than the version NCCGS verified (${verified}); \`unity self-update\` at your own risk` : "npx nccgs upgrade --project ." });
+  }
+  if (channels.has("pipeline") && cur.pipeline && src.pipelineLatest && newer(src.pipelineLatest, cur.pipeline)) {
+    const verified = cur.toolchain?.pipeline;
+    notices.push({ component: "pipeline", current: cur.pipeline, latest: src.pipelineLatest, hint: verified && newer(src.pipelineLatest, verified) ? `newer than the version NCCGS verified (${verified}); wait for the next nccgs release` : "npx nccgs upgrade --project ." });
+  }
+  const value = { checkedAt: new Date().toISOString(), notices, sources: src, installed: { nccgs: cur.nccgs, unitySkills: cur.unitySkills, pipeline: cur.pipeline, toolchain: cur.toolchain } };
+  writeJson(file, value);
+  return value;
+}
+
+export function staleCache(root) {
+  const config = loadConfig(root);
+  if (config.updates?.check === "never") return false;
+  const file = at(root, "updateCheck");
+  if (!exists(file)) return true;
+  return Date.now() - Date.parse(readJson(file).checkedAt ?? 0) >= intervalMs(config);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const i = process.argv.indexOf("--project");
+  const root = projectRoot(i >= 0 ? process.argv[i + 1] : undefined);
+  checkUpdates(root, { force: process.argv.includes("--force") }).then(v => { if (process.argv.includes("--print")) process.stdout.write(JSON.stringify(v, null, 2) + "\n"); }).catch(() => {});
+}

package/runtime/hooks/session-start.mjs

@@ -7,6 +7,9 @@ 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";
+import { staleCache } from "../core/update-check.mjs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 const input = await readInput();
 const project = root();
@@ -27,7 +30,13 @@ try {
   if (exists(check)) {
     const u = readJson(check);
     const notices = (u.notices ?? []).map(n => `${n.component} ${n.current} -> ${n.latest} (${n.hint})`);
-    if (notices.length) lines.push(`Updates available (not applied): ${notices.join("; ")}`);
+    if (notices.length) lines.push(`Updates available (not applied; checked ${String(u.checkedAt).slice(0, 10)}): ${notices.join("; ")}. Mention it to the user in one line; \`npx nccgs@<version> upgrade --project .\` applies NCCGS, Unity CLI and Pipeline together.`);
+  }
+  // Refresh the cache in the background (daily by default; `updates.check` in project.json) so no session waits on the network.
+  if (staleCache(project) && !process.env.NCCGS_NO_UPDATE_CHECK) {
+    const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "core", "update-check.mjs");
+    const child = spawn(process.execPath, [script, "--project", project], { detached: true, stdio: "ignore", windowsHide: true, env: process.env });
+    child.unref();
   }
 } catch {}
 try {

package/runtime/task/ledger.mjs

@@ -15,13 +15,18 @@ export const taskFile = (root, id) => path.join(at(root, "tasks"), `${id}.json`)
 export function loadTask(root, id) {
   const file = taskFile(root, id);
   if (!exists(file)) throw new Error(`Task ${id} not found (${file})`);
-  return readJson(file);
+  const task = readJson(file);
+  if (!isOurs(task)) throw new Error(`Task ${id} is an NCCGS ${task.schemaVersion ?? "1"}.x record (${file}); 3.x reads only schema 3. It is kept as history and not opened or closed by this version.`);
+  return task;
 }
+// NCCGS 2.x kept its own records in the same folder (schema 1/2, `closed` flag). They stay as history
+// and are never listed, so a leftover 2.x task cannot block a session or an uninstall.
+const isOurs = task => task?.schemaVersion === 3 && typeof task.status === "string";
 export function saveTask(root, task) { task.updatedAt = nowIso(); writeJson(taskFile(root, task.id), task); return task; }
 export function listTasks(root) {
   const dir = at(root, "tasks");
   if (!exists(dir)) return [];
-  return fs.readdirSync(dir).filter(f => f.endsWith(".json")).map(f => readJson(path.join(dir, f))).sort((a, b) => (a.openedAt < b.openedAt ? 1 : -1));
+  return fs.readdirSync(dir).filter(f => f.endsWith(".json")).map(f => readJson(path.join(dir, f))).filter(isOurs).sort((a, b) => (a.openedAt < b.openedAt ? 1 : -1));
 }
 export function openTasks(root) { return listTasks(root).filter(t => t.status !== "closed"); }
 

package/runtime/unity/unity.mjs

@@ -1,6 +1,6 @@
 // Unity CLI + Pipeline wrapper. Every call goes through here so the rest of the
 // runtime never spells a Pipeline command name: names are discovered at runtime
-// (`unity command --detail compact`) and cached per package version.
+// (`unity command --detail full`, names and parameter names) and cached per package version.
 //
 // Verified on 2026-11-04 against Unity CLI 1.0.0-beta.14 and com.unity.pipeline 0.9.x
 // with Editors 6000.3.17f1 and 6000.6.7f1 (see docs/EVIDENCE-VERIFICATION.md).
@@ -69,34 +69,61 @@ export async function waitReady(root, { timeoutMs = 15000, intervalMs = 1000 } =
 
 // ---- Pipeline commands -----------------------------------------------------
 
-export async function command(root, name, params = {}, { timeoutMs = 120000, retries = 2 } = {}) {
+export async function command(root, name, params = {}, { timeoutMs = 120000, retries = 2, parameters = null } = {}) {
   const args = ["command", ...name.split(" ")];
-  for (const [k, v] of Object.entries(params)) { if (v !== undefined && v !== null) args.push(`--${k}`, String(v)); }
+  for (const [k, v] of Object.entries(params)) { if (v !== undefined && v !== null) args.push(`--${paramName(k, parameters)}`, String(v)); }
   args.push("--project-path", root);
   let r;
   for (let attempt = 0; attempt <= retries; attempt++) {
     r = await cli(args, { timeoutMs });
-    const code = r.json?.errors?.[0]?.code;
+    const code = r.json?.errors?.[0]?.code ?? r.json?.errorCode;
     if (code !== "EDITOR_NOT_RUNNING" || attempt === retries) break;
     await waitReady(root, { timeoutMs: 8000 });
   }
-  const ok = r.json?.success === true;
-  return { ok, result: r.json?.data?.result, errors: r.json?.errors ?? [], raw: r.json, code: r.code, stderr: r.stderr };
+  return { ...unwrap(r), raw: r.json, code: r.code, stderr: r.stderr };
+}
+
+// Two envelope shapes. CLI beta.14: { success, command, data: { result }, errors }. CLI beta.17 prints the
+// Pipeline result bare (what used to be data.result; a Pipeline-side failure is { success: false, errorCode,
+// error, errorDetails }, exit 6) and keeps the old envelope only for CLI-side errors (EDITOR_NOT_RUNNING…).
+export function unwrap(r) {
+  const j = r.json;
+  if (j === null || j === undefined) return { ok: false, result: undefined, errors: [{ code: r.timedOut ? "TIMEOUT" : "NO_JSON", message: (r.stderr || r.stdout || "").slice(0, 300) }] };
+  if (typeof j !== "object") return { ok: r.code === 0 && !r.timedOut, result: j, errors: [] };   // a bare primitive result ("Entered play mode")
+  const enveloped = "data" in j && "success" in j;
+  if (enveloped) return { ok: j.success === true, result: j.data?.result, errors: j.errors ?? [] };
+  if (j.success === false) return { ok: false, result: j, errors: [{ code: j.errorCode ?? "PIPELINE_ERROR", message: j.error ?? j.errorDetails ?? "command failed", details: j.errorDetails ?? null }] };
+  return { ok: r.code === 0 && !r.timedOut, result: j, errors: [] };
 }
 
 // Discover the command catalog; cached under .nccgs/cache keyed by pipeline version.
 export async function catalog(root, { refresh = false } = {}) {
   const version = pipelineVersion(root) || "unknown";
-  const file = path.join(at(root, "cache"), `pipeline-commands-${version.replace(/[^\w.-]/g, "_")}.json`);
+  const file = path.join(at(root, "cache"), `pipeline-commands-v2-${version.replace(/[^\w.-]/g, "_")}.json`);
   if (!refresh && exists(file)) return readJson(file);
-  const r = await cli(["command", "--detail", "compact", "--limit", "500", "--project-path", root], { timeoutMs: 60000 });
-  const commands = r.json?.data?.commands ?? [];
-  if (!commands.length) return { version, commands: [], discoveredAt: null, error: r.json?.errors?.[0]?.message ?? "no commands" };
-  const value = { version, discoveredAt: new Date().toISOString(), commands: commands.map(c => ({ command: c.command, group: c.group, name: c.name, description: c.description })) };
+  // --detail full carries each command's parameter names; Pipeline 0.10 renamed them to kebab-case
+  // (async_tests -> async-tests, since_session -> since-session, enable -> enabled, output -> output-path).
+  const r = await cli(["command", "--detail", "full", "--limit", "500", "--project-path", root], { timeoutMs: 60000 });
+  // CLI beta.17 prints the listing bare ({ commands, count, ... }); beta.14 wrapped it in { success, data: { commands } }.
+  const commands = r.json?.data?.commands ?? r.json?.commands ?? [];
+  if (!commands.length) return { version, commands: [], discoveredAt: null, error: r.json?.errors?.[0]?.message ?? (r.json ? `no commands in listing (keys: ${Object.keys(r.json).join(",")})` : `no JSON from unity command (exit ${r.code}): ${(r.stderr || r.stdout || "").slice(0, 200)}`) };
+  const value = { version, discoveredAt: new Date().toISOString(), commands: commands.map(c => ({ command: c.command, group: c.group, name: c.name, description: c.description, parameters: (c.parameters ?? []).map(p => p.name) })) };
   writeJson(file, value);
   return value;
 }
 
+// Map the parameter name the runtime uses to the one this Pipeline version declares. Spelling is
+// matched ignoring case, `-` and `_`; a few names changed meaning-preserving words between versions.
+const PARAM_ALIASES = { enable: ["enabled"], output: ["output-path", "output_path", "save_path", "path"] };
+export function paramName(key, declared) {
+  if (!Array.isArray(declared) || !declared.length) return key;
+  const norm = s => String(s).toLowerCase().replace(/[-_]/g, "");
+  const exact = declared.find(d => d === key); if (exact) return exact;
+  const same = declared.find(d => norm(d) === norm(key)); if (same) return same;
+  for (const alias of PARAM_ALIASES[key] ?? []) { const hit = declared.find(d => norm(d) === norm(alias)); if (hit) return hit; }
+  return key;
+}
+
 // Resolve a capability to the real command name (handles renames between Pipeline versions).
 const CAPABILITIES = {
   playStart: [/^editor\.playmode start$/, /^editor_play$/],
@@ -117,18 +144,19 @@ const CAPABILITIES = {
   recompileStatus: [/^script recompile_status$/]
 };
 
-export async function resolve(root, capability) {
+export async function resolve(root, capability, { withParameters = false } = {}) {
   const cat = await catalog(root);
   const patterns = CAPABILITIES[capability];
   if (!patterns) throw new Error(`Unknown capability ${capability}`);
   const hit = cat.commands.find(c => patterns.some(p => p.test(c.command)));
-  return hit?.command ?? null;
+  if (!hit) return null;
+  return withParameters ? { command: hit.command, parameters: hit.parameters ?? [] } : hit.command;
 }
 
-async function call(root, capability, params, options) {
-  const name = await resolve(root, capability);
-  if (!name) return { ok: false, errors: [{ code: "CAPABILITY_MISSING", message: `No Pipeline command for ${capability}` }] };
-  return command(root, name, params, options);
+async function call(root, capability, params, options = {}) {
+  const hit = await resolve(root, capability, { withParameters: true });
+  if (!hit) return { ok: false, errors: [{ code: "CAPABILITY_MISSING", message: `No Pipeline command for ${capability}` }] };
+  return command(root, hit.command, params, { ...options, parameters: hit.parameters });
 }
 
 // ---- High-level operations used by `task verify` -------------------------------