nccgs 1.3.0 → 2.0.0-rc.2

package/scripts/benchmark-v15.mjs

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import { atomicJson, hash, json } from "../.claude/nccgs/tools/policy.mjs";
+import { initialize, record, snapshot, taskPath } from "../.claude/nccgs/tools/gates.mjs";
+import { reserve, reconcile, status } from "../.claude/nccgs/tools/orchestration.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const label = "SYNTHETIC FRAMEWORK BENCHMARK — no provider/model or game execution";
+export const scenarios = [
+  { id: "tiny-fix", name: "Tiny local fix", mode: "implement", scope: "local", target: "fix", expectedRisk: "FAST", objective: "Fix a local display label alignment with a known expected value" },
+  { id: "learning-prototype", name: "Learning prototype", mode: "implement", scope: "feature", target: "learning-prototype", expectedRisk: "STANDARD", objective: "Explore a bounded feedback hypothesis in a synthetic prototype" },
+  { id: "alpha-ready-prototype", name: "Alpha-ready prototype", mode: "implement", scope: "feature", target: "alpha-ready", expectedRisk: "STANDARD", objective: "Prepare a prototype feature for a declared end-to-end readiness check" },
+  { id: "cross-system-design", name: "Cross-system optimization and design plan", mode: "plan", scope: "cross-system", target: "production-change", expectedRisk: "CONTROLLED", objective: "Plan cross-system allocation and update-order optimization from a measured baseline" },
+  { id: "large-system-audit", name: "Large feature and system audit", mode: "audit", scope: "cross-system", target: "production-change", expectedRisk: "CONTROLLED", objective: "Audit dependencies and acceptance coverage across a large feature's systems" }
+];
+const measure = action => {
+  const start = performance.now(), value = action();
+  return { value, ms: performance.now() - start };
+};
+const rounded = value => Math.round(value * 1000) / 1000;
+function distribution(values) {
+  const sorted = [...values].sort((a, b) => a - b), mid = Math.floor(sorted.length / 2);
+  return { samples: sorted.length, min: rounded(sorted[0]), median: rounded(sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2), max: rounded(sorted.at(-1)), total: rounded(sorted.reduce((a, b) => a + b, 0)) };
+}
+function workspace(sourceFiles) {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), "nccgs-v15-benchmark-"));
+  function write(relative, value) {
+    const file = path.join(project, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`);
+  }
+  for (const file of ["pipeline.json", "studio.json"]) write(`.claude/nccgs/${file}`, fs.readFileSync(path.join(root, ".claude/nccgs", file), "utf8"));
+  write(".nccgs/project.yaml", "schema_version: 2\nmodels:\n  profile: claude-standalone\n");
+  write(".nccgs/execution.json", { schemaVersion: 1, name: "standalone", externalReview: { mode: "off" }, acceptanceRequired: false, requireObservedEffort: false, maxParallelWorkers: 2 });
+  for (let i = 0; i < sourceFiles; i++) write(`SyntheticSource/component-${i}.txt`, `Synthetic framework fixture component ${i}.\n${"Boundary and dependency data only.\n".repeat(24)}`);
+  return { project, write,
+    init(id, scenario, parentId = null) {
+      const relative = `.nccgs/intakes/${id}.json`;
+      write(relative, { schemaVersion: 1, objective: scenario.objective, mode: scenario.mode, scope: scenario.scope, target: scenario.target, readiness: "ready", systems: ["synthetic-component"], requiredChecks: ["fixture-acceptance"] });
+      return initialize(project, id, null, null, null, { intake: relative, parentId });
+    },
+    dispose() {
+      const resolved = path.resolve(project), expectedParent = path.resolve(os.tmpdir());
+      assert.equal(path.dirname(resolved), expectedParent);
+      assert.ok(path.basename(resolved).startsWith("nccgs-v15-benchmark-"));
+      fs.rmSync(resolved, { recursive: true, force: true });
+    } };
+}
+function request(task, key, maxDispatches = null) {
+  // The stress parameter counts ordinary delivery attempts; protected slots stay
+  // inside the actual total ceiling and must remain untouched by this fixture.
+  const protectedSlots = Object.values(task.contract.deliveryReserve ?? {}).reduce((a, b) => a + b, 0);
+  return { kind: task.mode === "implement" ? "implementation" : "analysis", agent: task.mode === "implement" ? "nccgs-gameplay-programmer" : "nccgs-task-scout",
+    requestKey: key, reason: "Synthetic reservation only; no worker/provider is invoked", writePaths: task.mode === "implement" ? ["SyntheticSource"] : [],
+    ...(maxDispatches === null ? {} : { limits: { maxDispatches: maxDispatches + protectedSlots } }) };
+}
+function cancelFixture(project, dispatch) {
+  return reconcile(project, dispatch.id, { status: "cancelled", reason: "Synthetic framework reservation completed without dispatching a model", reference: "benchmark-v15: intentionally no provider invocation" });
+}
+function scenarioRun(scenario, iterations, sourceFiles) {
+  const times = { init: [], snapshot: [], reserve: [], report: [] }, counts = { initialized: 0, snapshots: 0, reservations: 0, reports: 0, providerAttempts: 0 };
+  let source = null, observed = null;
+  for (let i = 0; i < iterations; i++) {
+    const fixture = workspace(sourceFiles);
+    try {
+      const initialized = measure(() => fixture.init(scenario.id, scenario));
+      const task = initialized.value;
+      assert.equal(task.mode, scenario.mode); assert.equal(task.risk, scenario.expectedRisk);
+      assert.equal(task.schemaVersion, 2);
+      const expectedRoute = { FAST: { class: "lightweight", model: "sonnet", effort: "medium" }, STANDARD: { class: "standard", model: "opus", effort: "medium" }, CONTROLLED: { class: "deep", model: "opus", effort: "high" } }[scenario.expectedRisk];
+      assert.deepEqual(task.implementationRoute, expectedRoute);
+      observed = { mode: task.mode, risk: task.risk, implementationRoute: task.implementationRoute };
+      times.init.push(initialized.ms); counts.initialized++;
+      const captured = measure(() => snapshot(fixture.project, task));
+      times.snapshot.push(captured.ms); counts.snapshots++;
+      source = { syntheticFiles: sourceFiles, snapshotFiles: captured.value.files, snapshotBytes: captured.value.bytes };
+      const reserved = measure(() => reserve(fixture.project, task.id, request(task, "measurement")));
+      times.reserve.push(reserved.ms); counts.reservations++;
+      cancelFixture(fixture.project, reserved.value);
+      const reported = measure(() => record(fixture.project, task.id, "report", { outcome: "blocked", summary: `${label}. Classification, snapshot, reservation and reporting were exercised; there is no runtime/model evidence.` }));
+      times.report.push(reported.ms); counts.reports++;
+      const usage = status(fixture.project, task.id);
+      assert.equal(usage.usage.dispatches, 1);
+      assert.equal(usage.telemetry.attempts, 0);
+      assert.equal(reported.value.reviewBudget.used, 0);
+      assert.equal(reported.value.stages.report.verificationState.verified, false);
+      assert.equal(reported.value.outcome, "blocked");
+    } finally { fixture.dispose(); }
+  }
+  return { id: scenario.id, name: scenario.name, expected: { mode: scenario.mode, risk: scenario.expectedRisk }, observed, result: "PASS",
+    counts, source, timingsMs: Object.fromEntries(Object.entries(times).map(([name, values]) => [name, distribution(values)])) };
+}
+function stressQuota(sourceFiles, quota) {
+  const fixture = workspace(sourceFiles), start = performance.now();
+  try {
+    const task = fixture.init("bounded", scenarios[0]);
+    for (let i = 0; i < quota; i++) cancelFixture(fixture.project, reserve(fixture.project, task.id, request(task, `try-${i}`, quota)));
+    assert.throws(() => reserve(fixture.project, task.id, request(task, "over-budget", quota)), /budget reserved for bounded/i);
+    const after = status(fixture.project, task.id);
+    assert.equal(after.usage.dispatches, quota);
+    assert.equal(after.telemetry.attempts, 0);
+    assert.equal(after.active.length, 0);
+    assert.equal(after.deliveryBudget.protectedSlots, 4);
+    return { id: "repeated-reservation-exhaustion", result: "PASS", quota, reservations: after.usage.dispatches, rejectedAdditionalReservation: true,
+      quotaKind: "ordinary-delivery", totalDispatchLimit: after.limits.maxDispatches, protectedRemaining: after.deliveryBudget.remaining,
+      cancelledAttemptsRefunded: false, providerAttempts: 0, durationMs: rounded(performance.now() - start) };
+  } finally { fixture.dispose(); }
+}
+function stressParent(sourceFiles) {
+  const fixture = workspace(sourceFiles), start = performance.now();
+  try {
+    const parent = fixture.init("parent", scenarios[1]);
+    cancelFixture(fixture.project, reserve(fixture.project, parent.id, request(parent, "parent-integration", 4)));
+    const first = fixture.init("child-a", scenarios[0], parent.id);
+    for (let i = 0; i < 2; i++) cancelFixture(fixture.project, reserve(fixture.project, first.id, request(first, `child-a-${i}`, 3)));
+    const second = fixture.init("child-b", scenarios[0], parent.id);
+    cancelFixture(fixture.project, reserve(fixture.project, second.id, request(second, "child-b-0", 3)));
+    assert.throws(() => reserve(fixture.project, second.id, request(second, "child-b-over-parent", 3)), /budget reserved for parent/i);
+    const third = fixture.init("child-c", scenarios[0], parent.id);
+    assert.throws(() => reserve(fixture.project, third.id, request(third, "new-child-no-refund", 3)), /budget reserved for parent/i);
+    const aggregate = status(fixture.project, parent.id);
+    assert.equal(aggregate.usage.dispatches, 4);
+    assert.equal(aggregate.telemetry.attempts, 0);
+    assert.equal(json(taskPath(fixture.project, parent.id)).reviewBudget.used, 0);
+    return { id: "parent-child-aggregate-exhaustion", result: "PASS", parentQuota: 4, aggregateReservations: 4,
+      quotaKind: "ordinary-delivery", totalDispatchLimit: aggregate.limits.maxDispatches, protectedRemaining: aggregate.deliveryBudget.remaining,
+      ownParentReservations: 1, childReservations: { "child-a": 2, "child-b": 1, "child-c": 0 },
+      blockedExistingChildDespiteLocalCapacity: true, blockedNewChildDespiteLocalCapacity: true,
+      providerAttempts: 0, durationMs: rounded(performance.now() - start) };
+  } finally { fixture.dispose(); }
+}
+export function runBenchmark({ iterations = 3, sourceFiles = 40, stressQuota: quota = 6 } = {}) {
+  assert(!(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT), "Run the synthetic framework benchmark outside Claude Code; it uses explicit fixture reconciliation");
+  assert(Number.isSafeInteger(iterations) && iterations >= 1 && iterations <= 10, "iterations must be 1..10");
+  assert(Number.isSafeInteger(sourceFiles) && sourceFiles >= 1 && sourceFiles <= 1000, "sourceFiles must be 1..1000");
+  assert(Number.isSafeInteger(quota) && quota >= 1 && quota <= 32, "stressQuota must be 1..32");
+  const start = performance.now();
+  const results = scenarios.map(scenario => scenarioRun(scenario, iterations, sourceFiles));
+  const stress = [stressQuota(sourceFiles, quota), stressParent(sourceFiles)];
+  return { schemaVersion: 1, benchmark: "nccgs-v15-framework-only", label, recordedAt: new Date().toISOString(), result: "PASS",
+    environment: { node: process.version, platform: process.platform, architecture: process.arch },
+    framework: { packageVersion: json(path.join(root, "package.json")).version, pipelineSha256: hash(fs.readFileSync(path.join(root, ".claude/nccgs/pipeline.json"))) },
+    parameters: { iterations, sourceFiles, stressQuota: quota },
+    scenarios: results, stress,
+    totals: { scenarioRuns: scenarios.length * iterations, stressCases: stress.length, providerAttempts: 0, frameworkDurationMs: rounded(performance.now() - start) },
+    evidenceBoundary: { evidenceKind: "synthetic-framework-fixtures", modelExecution: "NOT_RUN", gameExecution: "NOT_RUN", tokenCost: "NOT_MEASURED", productivityComparison: "NOT_MEASURED",
+      interpretation: "Timings measure local framework I/O and bookkeeping only; total duration also includes fixture setup and cleanup. Fixture classification and quota assertions do not establish natural-language classification accuracy, model quality or whole-workflow efficiency." } };
+}
+export function run(args) {
+  const accepted = new Set(["--out", "--iterations", "--source-files", "--stress-quota"]);
+  const options = {};
+  for (let i = 0; i < args.length; i += 2) {
+    assert(accepted.has(args[i]) && args[i + 1] && !args[i + 1].startsWith("--"), "Usage: benchmark-v15.mjs [--out FILE] [--iterations 1..10] [--source-files 1..1000] [--stress-quota 1..32]");
+    assert(options[args[i]] === undefined, `Duplicate option: ${args[i]}`);
+    options[args[i]] = args[i + 1];
+  }
+  const result = runBenchmark({ ...(options["--iterations"] ? { iterations: Number(options["--iterations"]) } : {}),
+    ...(options["--source-files"] ? { sourceFiles: Number(options["--source-files"]) } : {}), ...(options["--stress-quota"] ? { stressQuota: Number(options["--stress-quota"]) } : {}) });
+  if (options["--out"]) {
+    const file = path.resolve(options["--out"]);
+    atomicJson(file, result);
+    return { result: result.result, label, output: file, totals: result.totals };
+  }
+  return result;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { console.log(JSON.stringify(run(process.argv.slice(2)), null, 2)); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/scripts/cli.mjs

@@ -4,6 +4,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import crypto from "node:crypto";
+import { atomicJson, contained, executionPolicy, hash, json, profilePolicy, resolveExecution } from "../.claude/nccgs/tools/policy.mjs";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(scriptDir, "..");
@@ -19,6 +21,14 @@ if (command === "version" || command === "--version" || command === "-v") {
   process.exit(0);
 }
 
+if (command === "run") {
+  try { process.exitCode = await (await import("./run.mjs")).run(args); }
+  catch (error) { console.error(`NCCGS run failed: ${error.message}`); process.exitCode = 1; }
+} else if (command === "migrate-execution") {
+  try { migrateExecution(); }
+  catch (error) { console.error(`Execution migration failed: ${error.message}`); process.exitCode = 1; }
+} else {
+
 if (!new Set(["install", "update", "doctor", "task", "agents", "policy"]).has(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -39,6 +49,116 @@ if (result.error) {
   process.exit(1);
 }
 process.exit(result.status ?? 1);
+}
+
+function migrateExecution() {
+  const value = flag => {
+    const index = args.indexOf(flag);
+    if (index < 0) return undefined;
+    if (!args[index + 1] || args[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
+    return args[index + 1];
+  };
+  const target = path.resolve(value("--project") || process.cwd());
+  const dryRun = args.includes("--dry-run");
+  const rollback = value("--rollback");
+  const allowed = new Set(["--project", "--to", "--external-review", "--model-profile", "--rollback", "--dry-run"]);
+  for (let i = 0; i < args.length; i++) {
+    if (!allowed.has(args[i])) throw new Error(`Unknown migration option: ${args[i]}`);
+    if (args[i] !== "--dry-run") i++;
+  }
+  const at = relative => contained(target, relative);
+  if (!fs.existsSync(at(".claude/nccgs/install-state.json"))) throw new Error("Install/update NCCGS before migrating execution");
+  const studio = json(at(".claude/nccgs/studio.json"));
+  const permitted = new Set([".nccgs/execution.json", ".nccgs/project.yaml", ".claude/settings.json", ".nccgs/agent-activation.json", ".claude/nccgs/install-state.json",
+    ...studio.agents.map(agent => `.claude/agents/${agent.name}.md`)]);
+  const currentHash = relative => fs.existsSync(at(relative)) ? hash(fs.readFileSync(at(relative))) : null;
+  const tasks = [];
+  const tasksDir = at(".nccgs/tasks");
+  if (fs.existsSync(tasksDir)) for (const file of fs.readdirSync(tasksDir).filter(file => file.endsWith(".json"))) {
+    const task = json(at(`.nccgs/tasks/${file}`));
+    if (!task.closed) tasks.push(task.id || file);
+  }
+  const reportTasks = () => console.log(`Active tasks (${tasks.length}): ${tasks.join(", ") || "none"}. Existing tasks retain pinned obligations, evidence and consumed budgets; use an explicit continuation/re-pin before applying changed policy. No approval is created.`);
+  const restore = (manifest, directory) => {
+    for (const item of manifest.files) {
+      const destination = at(item.path);
+      if (item.before === null) { if (fs.existsSync(destination)) fs.unlinkSync(at(item.path)); }
+      else {
+        const source = at(`${directory}/files/${item.path}`);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.copyFileSync(source, at(item.path));
+      }
+    }
+  };
+  if (rollback) {
+    if (value("--to") || value("--external-review") || value("--model-profile")) throw new Error("Rollback cannot be combined with migration changes");
+    if (!/^[0-9a-f-]{36}$/.test(rollback)) throw new Error("Rollback requires the migration UUID printed by this command");
+    const directory = `.nccgs/backups/execution/${rollback}`;
+    const manifest = json(at(`${directory}/manifest.json`));
+    if (manifest.schemaVersion !== 1 || manifest.kind !== "execution-migration" || manifest.id !== rollback || manifest.status !== "applied" || !Array.isArray(manifest.files)) throw new Error("Invalid or already restored execution migration");
+    if (new Set(manifest.files.map(item => item.path)).size !== manifest.files.length || manifest.files.length !== permitted.size) throw new Error("Incomplete or duplicate migration configuration records");
+    for (const item of manifest.files) {
+      if (!permitted.has(item.path)) throw new Error(`Unsafe migration record: ${item.path}`);
+      if (currentHash(item.path) !== item.after) throw new Error(`Configuration changed after migration: ${item.path}; rollback would overwrite later work`);
+      if (item.before !== null && hash(fs.readFileSync(at(`${directory}/files/${item.path}`))) !== item.before) throw new Error(`Migration backup missing or changed: ${item.path}`);
+    }
+    console.log(`Restore execution migration ${rollback}; framework version must match the archived configuration. Tasks and evidence are preserved.`);
+    reportTasks();
+    if (dryRun) { console.log("Dry run complete; no files changed."); return; }
+    restore(manifest, directory);
+    atomicJson(at(`${directory}/manifest.json`), { ...manifest, status: "rolled-back", restoredAt: new Date().toISOString() });
+    console.log("Execution configuration restored; run doctor and continue/re-pin active tasks explicitly.");
+    return;
+  }
+  const to = value("--to");
+  if (to !== "standalone") throw new Error("Use --to standalone, or --rollback <migration-id>");
+  const previous = resolveExecution(target);
+  const selected = value("--model-profile");
+  if (selected) profilePolicy(target, selected);
+  const mode = value("--external-review") ?? (previous.name === "standalone" ? previous.externalReview.mode : "off");
+  const next = executionPolicy({ schemaVersion: 1, name: "standalone", externalReview: { mode },
+    acceptanceRequired: previous.name === "standalone" ? previous.acceptanceRequired : false,
+    requireObservedEffort: previous.name === "standalone" ? previous.requireObservedEffort : false,
+    maxParallelWorkers: previous.name === "standalone" ? previous.maxParallelWorkers : 2,
+    ...(previous.designReviewRequired !== undefined ? { designReviewRequired: previous.designReviewRequired } : {}),
+    ...(previous.reviewContractRequired !== undefined ? { reviewContractRequired: previous.reviewContractRequired } : {}) });
+  console.log(`Execution: ${previous.name} -> standalone; external review: ${previous.externalReview.mode} -> ${next.externalReview.mode}; model profile: ${previous.profileName} -> ${selected || previous.profileName}.`);
+  console.log("New tasks use Claude Code intake/plan, implementation or audit/plan mode, verification, independent review and report. Acceptance is required only by contract/policy. Existing tasks are not converted.");
+  reportTasks();
+  const id = crypto.randomUUID();
+  const directory = `.nccgs/backups/execution/${id}`;
+  const files = [...permitted].map(relative => {
+    const before = currentHash(relative);
+    at(`${directory}/files/${relative}`);
+    return { path: relative, before };
+  });
+  at(`${directory}/manifest.json`);
+  if (dryRun) { console.log("Dry run complete; no files changed."); return; }
+  const manifest = { schemaVersion: 1, kind: "execution-migration", id, status: "prepared", createdAt: new Date().toISOString(), from: previous,
+    to: { ...next, profileName: selected || previous.profileName }, activeTasks: tasks, files };
+  for (const item of files) if (item.before !== null) {
+    const backup = at(`${directory}/files/${item.path}`);
+    fs.mkdirSync(path.dirname(backup), { recursive: true });
+    fs.copyFileSync(at(item.path), at(`${directory}/files/${item.path}`));
+  }
+  atomicJson(at(`${directory}/manifest.json`), manifest);
+  try {
+    atomicJson(at(".nccgs/execution.json"), { schemaVersion: 1, ...next });
+    if (selected) {
+      const result = spawnSync(process.execPath, [path.join(root, ".claude/nccgs/tools/configure-models.mjs"), "--project", target, "--profile", selected], { cwd: target, encoding: "utf8" });
+      if (result.status !== 0) throw new Error(result.stderr || result.stdout || "Model reconfiguration failed");
+      process.stdout.write(result.stdout ?? "");
+      process.stderr.write(result.stderr ?? "");
+    }
+    for (const item of files) item.after = currentHash(item.path);
+    atomicJson(at(`${directory}/manifest.json`), { ...manifest, files, status: "applied", appliedAt: new Date().toISOString() });
+  } catch (error) {
+    restore(manifest, directory);
+    atomicJson(at(`${directory}/manifest.json`), { ...manifest, status: "failed-restored", failure: error.message });
+    throw error;
+  }
+  console.log(`Execution migration ${id} applied. Rollback: nccgs migrate-execution --rollback ${id} --dry-run`);
+}
 
 function printHelp() {
   console.log(`NCCGS
@@ -47,9 +167,14 @@ Usage:
   nccgs install [options]
   nccgs update [options]
   nccgs doctor [options]
-  nccgs task init|snapshot|ref|observe|verify|record|check|close|bind [options]
+  nccgs run [--project DIR] [--claude EXECUTABLE] [--dry-run] -- [Claude arguments/prompt]
+  nccgs run --supervise --task ID --prompt-file FILE --session-budget-usd N [--max-resumes 2] [--timeout-ms 3600000] -- [provider options]
+  nccgs run --recover-run RUN_ID [--project DIR] [--claude EXECUTABLE]
+  nccgs task init|snapshot|ref|observe|verify|acceptance-status|record|check|close|bind|extend-review|refresh-inputs|migrate-evidence [options]
   nccgs agents --enable <role> | --disable <role> [--project <directory>]
   nccgs policy [--write]              Check/regenerate package routing
+  nccgs migrate-execution --to standalone [--external-review off|advisory|required] [--model-profile <profile>] [--dry-run]
+  nccgs migrate-execution --rollback <migration-id> [--dry-run]
   nccgs --version
 
 Install target:
@@ -59,7 +184,9 @@ Install target:
 Options:
   --dry-run                         Preview without writing files
   --force                           Back up and discard detected project overrides
-  --model-profile <profile>         astra-claude (default), quality, balanced, inherit
+  --model-profile <profile>         claude-standalone (new default), astra-claude, quality, balanced, inherit
+  --autonomy full|guarded           Install/update: task authority for nccgs run (new install: full; update: preserve)
   --project <directory>             Optional explicit target directory
+  --risk <tier>                     task init: FAST, STANDARD (default), CONTROLLED
   --allow-non-unity                 Allow a target without Unity markers`);
 }

package/scripts/doctor.mjs

@@ -4,7 +4,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { matchesFingerprint, sameFingerprint } from "../.claude/nccgs/tools/integrity.mjs";
 import { check as checkTask, snapshot, stages } from "../.claude/nccgs/tools/gates.mjs";
-import { contained, hash, json } from "../.claude/nccgs/tools/policy.mjs";
+import { hash, json, profilePolicy, resolveExecution, verifyArtifact } from "../.claude/nccgs/tools/policy.mjs";
+import { assertProjectRoot, assertRelativePath, containedPath } from "../.claude/nccgs/tools/paths.mjs";
+import { inputPolicy } from "../.claude/nccgs/tools/inputs.mjs";
+import { autonomyPolicy } from "../.claude/nccgs/tools/autonomy.mjs";
 
 const args = process.argv.slice(2);
 const projectIndex = args.indexOf("--project");
@@ -17,12 +20,15 @@ if (projectIndex >= 0 && !args[projectIndex + 1]) {
 }
 
 const project = projectIndex >= 0 ? path.resolve(args[projectIndex + 1]) : process.cwd();
+try { assertProjectRoot(project); }
+catch (error) { console.error(`ERROR: ${error.message}`); process.exit(1); }
 for (const marker of ["Assets", "Packages", "ProjectSettings"]) {
-  if (!fs.existsSync(path.join(project, marker))) errors.push(`Missing Unity marker: ${marker}`);
+  const file = safePath(marker);
+  if (file && !fs.existsSync(file)) errors.push(`Missing Unity marker: ${marker}`);
 }
 
-const statePath = path.join(project, ".claude", "nccgs", "install-state.json");
-const overridePath = path.join(project, ".nccgs", "framework-overrides.json");
+const statePath = safePath(".claude/nccgs/install-state.json");
+const overridePath = safePath(".nccgs/framework-overrides.json");
 const state = readJson(statePath, "NCCGS install state", true);
 const overrideManifest = readJson(overridePath, "NCCGS framework override manifest", false);
 if (state && ![1, 2, 3].includes(state.schemaVersion)) errors.push(`Unsupported install-state schema: ${state.schemaVersion ?? "unknown"}.`);
@@ -46,7 +52,8 @@ if (state) {
       errors.push(`Unsafe managed path in install state: ${item.relative ?? "missing"}`);
       continue;
     }
-    const file = path.join(project, ...item.relative.split("/"));
+    const file = safePath(item.relative);
+    if (!file) continue;
     const override = overrides.get(item.relative);
     if (override) {
       const recordedUpstream = {
@@ -65,18 +72,19 @@ if (state) {
 }
 for (const item of overrides.values()) {
   if ((state?.files ?? []).some((managed) => managed.relative === item.path)) continue;
-  validateOverride(item, path.join(project, ...item.path.split("/")));
+  const file = safePath(item.path);
+  if (file) validateOverride(item, file);
 }
 
-const claudePath = path.join(project, "CLAUDE.md");
-if (!fs.existsSync(claudePath) || !fs.readFileSync(claudePath, "utf8").includes("@.claude/nccgs/constitution.md")) {
+const claudePath = safePath("CLAUDE.md");
+if (claudePath && (!fs.existsSync(claudePath) || !fs.readFileSync(claudePath, "utf8").includes("@.claude/nccgs/constitution.md"))) {
   errors.push("CLAUDE.md does not import the NCCGS constitution.");
 }
 
-const policyPath = path.join(project, ".nccgs", "project.yaml");
+const policyPath = safePath(".nccgs/project.yaml");
 let policySchema = null;
-if (!fs.existsSync(policyPath)) errors.push(".nccgs/project.yaml is missing.");
-else {
+if (policyPath && !fs.existsSync(policyPath)) errors.push(".nccgs/project.yaml is missing.");
+else if (policyPath) {
   const policyText = fs.readFileSync(policyPath, "utf8");
   const match = policyText.match(/^schema_version:\s*(\d+)\s*$/m);
   policySchema = match ? Number(match[1]) : null;
@@ -84,24 +92,42 @@ else {
   if (/^profile_contracts:/m.test(policyText)) migrationIssue("Legacy embedded profile_contracts require Astra migration to pipeline.json plus project gate mapping.");
 }
 
-const activationPath = path.join(project, ".nccgs/agent-activation.json");
-if (fs.existsSync(activationPath)) {
+validateSettings();
+let execution = null;
+try {
+  execution = resolveExecution(project);
+  if (!fs.existsSync(containedPath(project, ".nccgs/execution.json"))) warnings.push("No execution.json: compatibility obligations remain active. Standalone requires explicit migrate-execution; updating does not waive pending external review.");
+  if (!execution.requireObservedEffort) warnings.push("Execution permits unknown observed effort; configured effort is intent, not runtime proof. Report unavailable provider model/effort evidence as unknown.");
+} catch (error) { errors.push(`Invalid execution policy: ${error.message}`); }
+try { inputPolicy(project); }
+catch (error) { errors.push(`Invalid canonical input/output policy: ${error.message}`); }
+
+const activationPath = safePath(".nccgs/agent-activation.json");
+if (activationPath && fs.existsSync(activationPath)) {
   try {
     const activation = json(activationPath);
     for (const [relative, expected] of Object.entries(activation.generated)) {
-      const bytes = fs.readFileSync(contained(project, relative));
+      const bytes = fs.readFileSync(containedPath(project, relative));
       if (hash(bytes) !== expected && hash(bytes.toString("utf8").replace(/\r\n/g, "\n")) !== activation.generatedCanonical?.[relative]) errors.push(`Activated agent modified: ${relative}`);
     }
     for (const warning of activation.warnings ?? []) migrationIssue(warning);
   } catch (error) { errors.push(`Invalid agent activation state: ${error.message}`); }
 }
-const tasksDir = path.join(project, ".nccgs/tasks");
-if (fs.existsSync(tasksDir)) for (const file of fs.readdirSync(tasksDir).filter(f => f.endsWith(".json"))) {
+const tasksDir = safePath(".nccgs/tasks");
+if (tasksDir && fs.existsSync(tasksDir)) for (const file of fs.readdirSync(tasksDir).filter(f => f.endsWith(".json"))) {
   try {
-    const task = json(path.join(tasksDir, file));
+    const task = json(containedPath(project, `.nccgs/tasks/${file}`));
+    if (task.schemaVersion !== 2 && execution?.name === "standalone") warnings.push(`Legacy task ${task.id} retains compatibility stages and budget; explicit continuation/re-pin is required to adopt standalone policy.`);
+    const executionCurrent = task.schemaVersion !== 2 || hash(JSON.stringify(execution)) === task.executionHash;
+    if (!executionCurrent) warnings.push(`Task ${task.id} is pinned to another execution policy; preserve its history and explicitly continue/re-pin before claiming completion.`);
+    if (!task.canonicalInputs) warnings.push(`Task ${task.id} predates canonical input pins; it is historical only until refresh-inputs and fresh evidence are recorded.`);
     if (task.closed) {
-      if (!stages.every(s => task.stages?.[s]) || task.closed.snapshot !== task.stages.acceptance.snapshot) throw new Error("Closure lacks its required stage records");
-      if (task.closed.snapshot === snapshot(project).sha256) checkTask(project, task, "done");
+      const required = task.schemaVersion === 2 ? [task.mode === "implement" ? "implementation" : "analysis", "review", "report"] : stages;
+      const terminal = task.schemaVersion === 2 ? task.stages?.report : task.stages?.acceptance;
+      if (!required.every(s => task.stages?.[s]) || task.closed.snapshot !== terminal?.snapshot) throw new Error("Closure lacks its required stage records");
+      if (task.schemaVersion === 2 && (task.execution?.acceptanceRequired || task.contract?.acceptanceRequired) && !task.stages?.acceptance) throw new Error("Closure lacks required acceptance");
+      verifyStoredEvidence(task);
+      if (executionCurrent && task.canonicalInputs && task.closed.snapshot === snapshot(project, task).sha256) checkTask(project, task, "done");
       else warnings.push(`Historical closure ${task.id} is for a different snapshot; it cannot approve current work.`);
     }
   } catch (error) { errors.push(`Invalid closed task ${file}: ${error.message}`); }
@@ -117,9 +143,12 @@ for (const warning of warnings) console.warn(`WARN: ${warning}`);
 console.log("NCCGS doctor passed.");
 console.log(`Framework version: ${state.frameworkVersion}`);
 console.log(`Model profile: ${state.modelProfile}`);
+console.log(`Execution policy: ${execution?.name}; external review: ${execution?.externalReview.mode}; maximum parallel workers: ${execution?.maxParallelWorkers}`);
+console.log(`Reviewed design gate: ${execution?.name === "standalone" && execution?.designReviewRequired === true ? "required for feature implementation" : "legacy/compatibility policy; not proof of document readiness"}`);
 console.log(`Managed files verified: ${verifiedManaged}`);
 console.log(`Framework overrides: ${overrides.size} (${[...overrides.values()].filter((item) => item.status !== "approved").length} pending review)`);
 console.log(`Project policy schema: ${policySchema ?? "migration required"}`);
+console.log("Settings scope: project settings and observable local overrides only; CLI, user/managed settings, provider routing and active-session model/effort still require runtime verification.");
 
 function validateOverride(item, file) {
   if (item.status !== "approved") migrationIssue(`Framework override awaits /migrate-project review: ${item.path}`);
@@ -137,6 +166,7 @@ function migrationIssue(message) {
 }
 
 function readJson(file, label, required) {
+  if (!file) return null;
   if (!fs.existsSync(file)) {
     if (required) errors.push(`${label} is missing.`);
     return null;
@@ -149,7 +179,83 @@ function readJson(file, label, required) {
 }
 
 function isManagedRelative(value) {
-  if (typeof value !== "string" || !value.startsWith(".claude/")) return false;
-  const parts = value.split("/");
-  return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
+  try { return assertRelativePath(value).startsWith(".claude/"); }
+  catch { return false; }
+}
+
+function safePath(relative) {
+  try { return containedPath(project, relative); }
+  catch (error) { errors.push(`Unsafe NCCGS path: ${error.message}`); return null; }
+}
+
+function verifyStoredEvidence(task) {
+  const verify = (ref, runtime = false) => {
+    const file = verifyArtifact(project, ref);
+    if (!ref.path.endsWith(".json")) return;
+    const record = json(file);
+    if (runtime) {
+      verifyArtifact(project, record.observationSource);
+      if (record.evidenceMigration?.archivedObservation) verifyArtifact(project, record.evidenceMigration.archivedObservation);
+    } else if (record.origin === "verification-command") verifyArtifact(project, record.log);
+  };
+  for (const stage of Object.values(task.stages ?? {})) {
+    if (stage.runtime) verify(stage.runtime, true);
+    if (stage.evidence) verify(stage.evidence);
+    for (const check of stage.checks ?? []) verify(check.evidence);
+    for (const artifact of stage.artifacts ?? []) verify(artifact);
+  }
+  for (const receipt of task.externalReviews ?? []) verify(receipt.evidence);
+}
+
+function validateSettings() {
+  const settings = readJson(safePath(".claude/settings.json"), "Claude project settings", true);
+  const fragment = readJson(safePath(".claude/nccgs/settings.fragment.json"), "NCCGS settings fragment", true);
+  const local = readJson(safePath(".claude/settings.local.json"), "Claude local settings", false);
+  const object = value => value && typeof value === "object" && !Array.isArray(value);
+  if (!object(settings) || !object(fragment)) {
+    errors.push("Claude project settings and NCCGS settings fragment must be JSON objects.");
+    return;
+  }
+  if (local !== null && !object(local)) errors.push("Claude local settings must be a JSON object.");
+  for (const [label, value] of [["project", settings], ["local", local]]) {
+    if (value?.disableAllHooks === true) errors.push(`Claude ${label} settings disable all hooks.`);
+  }
+  for (const [event, groups] of Object.entries(fragment.hooks ?? {})) {
+    for (const expected of groups) for (const hook of expected.hooks ?? []) {
+      const actualGroups = Array.isArray(settings.hooks?.[event]) ? settings.hooks[event] : [];
+      const present = actualGroups.some(group => group && (group.matcher ?? "") === (expected.matcher ?? "")
+        && Array.isArray(group.hooks) && group.hooks.some(actual => actual && actual.type === hook.type && actual.command === hook.command
+          && actual.async !== true && (actual.timeout === undefined || actual.timeout >= hook.timeout)));
+      if (!present) errors.push(`Required NCCGS hook missing or altered: ${event} [${expected.matcher ?? ""}] ${hook.command}`);
+    }
+  }
+  let autonomy = "guarded";
+  try { autonomy = autonomyPolicy(project).mode; }
+  catch (error) { errors.push(error.message); }
+  for (const [key, required] of Object.entries(fragment.permissions ?? {})) {
+    for (const rule of required) if (!Array.isArray(settings.permissions?.[key]) || !settings.permissions[key].includes(rule)) {
+      errors.push(`Required NCCGS permission ${key} rule missing: ${rule}`);
+    }
+  }
+  if (autonomy === "full") {
+    console.log("Task autonomy: full (native permission mode requires nccgs run; configuration is not runtime proof).");
+    console.log("NCCGS integrity/destructive-action guards, explicit deny/ask rules and managed/OS restrictions remain effective.");
+  }
+  try {
+    if (!safePath(".claude/nccgs/pipeline.json")) return;
+    const { name, profile } = profilePolicy(project, state?.modelProfile);
+    const declared = policyPath && fs.existsSync(policyPath)
+      ? fs.readFileSync(policyPath, "utf8").match(/^models:[ \t]*\r?\n((?:[ \t]+[^\n]*\n?|\s*\n)*)/m)?.[1]?.match(/^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "") : null;
+    if (declared && declared !== name) errors.push(`Project model profile ${declared} differs from installed profile ${name}; reconfigure models.`);
+    if (profile.session) {
+      const route = profile.models[profile.session.class];
+      if (settings.model !== route.model) errors.push(`Project session model must be ${route.model}; found ${settings.model ?? "missing"}.`);
+      if (settings.effortLevel !== route.effort) errors.push(`Project session effort must be ${route.effort}; found ${settings.effortLevel ?? "missing"}.`);
+      if (settings.modelSettings?.[route.model]?.effortLevel !== route.effort) errors.push(`Project per-model effort for ${route.model} must be ${route.effort}.`);
+      if (local?.model !== undefined && local.model !== route.model) errors.push(`Local settings override the required session model ${route.model}.`);
+      if (local?.effortLevel !== undefined && local.effortLevel !== route.effort) errors.push(`Local settings override the required session effort ${route.effort}.`);
+      if (local?.modelSettings?.[route.model]?.effortLevel !== undefined && local.modelSettings[route.model].effortLevel !== route.effort) errors.push(`Local settings override the required per-model effort for ${route.model}.`);
+    }
+  } catch (error) { errors.push(`Cannot verify session model policy: ${error.message}`); }
+  if (local) warnings.push("Local Claude settings are present; project requirements were checked without treating local hook additions as replacements. Runtime overrides are not fully observable by doctor.");
 }