nccgs 1.3.0 → 2.0.0-rc.2

package/.claude/nccgs/tools/compile-policy.mjs

@@ -30,29 +30,59 @@ export function generated(project) {
   }
   const primary = pipeline.profiles[pipeline.defaultProfile];
   for (const agent of studio.agents) {
+    const template = fs.readFileSync(path.join(project, ".claude/nccgs/agent-library", `${agent.name}.md`), "utf8");
+    const turns = template.match(/^maxTurns: (\d+)\r?$/m);
+    if (turns) agent.maxTurns = Number(turns[1]);
     const route = primary.models[agent.modelClass];
     if (!route) throw new Error(`Missing route for ${agent.name}`);
     agent.defaultModel = route.model;
     agent.defaultEffort = route.effort;
     if (primary.activeAgents === "all" || primary.activeAgents.includes(agent.name)) {
-      const template = fs.readFileSync(path.join(project, ".claude/nccgs/agent-library", `${agent.name}.md`), "utf8");
       outputs.set(`.claude/agents/${agent.name}.md`, renderAgent(template, route));
     }
   }
   const { contract } = pipeline;
   const contractProfile = pipeline.profiles["astra-claude"];
-  workflows.profileContracts = { "astra-claude": { ...contract,
+  const standalone = pipeline.executionPolicies.standalone;
+  const standaloneProfile = pipeline.profiles["claude-standalone"];
+  workflows.executionContracts = { standalone, compatibility: { ...contract, runtime: "claude-code" } };
+  workflows.profileContracts = { "claude-standalone": { ...standalone,
+    implementationRoutes: Object.fromEntries(Object.entries(contract.taskTiers).map(([risk, tier]) =>
+      [risk, { ...tier, ...standaloneProfile.models[tier.implementationClass] }])),
+    reviewModel: standaloneProfile.models.review.model, reviewEffort: standaloneProfile.models.review.effort }, "astra-claude": { ...contract,
     implementationModel: contractProfile.models.standard.model, implementationEffort: contractProfile.models.standard.effort,
+    implementationRoutes: Object.fromEntries(Object.entries(contract.taskTiers).map(([risk, tier]) =>
+      [risk, { ...tier, ...contractProfile.models[tier.implementationClass] }])),
     reviewModel: contractProfile.models.review.model, reviewEffort: contractProfile.models.review.effort } };
   for (const workflow of workflows.workflows) {
     delete workflow.ownerByProfile;
     delete workflow.primaryRolesByProfile;
+    workflow.ownerByExecution = { standalone: "Claude Code" };
+    if (contract.astraWorkflows.includes(workflow.name)) workflow.ownerByExecution.compatibility = "Astra";
     if (contract.astraWorkflows.includes(workflow.name)) workflow.ownerByProfile = { "astra-claude": "Astra" };
-    if (contract.reviewWorkflows.includes(workflow.name)) workflow.primaryRolesByProfile = { "astra-claude": [contract.reviewAgent] };
+    if (contract.reviewWorkflows.includes(workflow.name)) workflow.primaryRolesByProfile = { "astra-claude": [contract.reviewAgent], "claude-standalone": [contract.reviewAgent] };
+    const relative = `.claude/skills/${workflow.name}/SKILL.md`;
+    if (!fs.existsSync(path.join(project, relative))) continue; // Minimal policy fixtures may omit workflow files; validate checks package completeness.
+    const wrapper = fs.readFileSync(path.join(project, relative), "utf8").replace(/\r\n/g, "\n");
+    const frontmatter = wrapper.match(/^---\n[\s\S]*?\n---/);
+    const heading = wrapper.match(/^# .+$/m);
+    if (!frontmatter || !heading) throw new Error(`Invalid workflow wrapper: ${relative}`);
+    const designRoute = ["design", "design-review", "story-readiness"].includes(workflow.name)
+      ? "  Also load the [standalone design lifecycle](../../nccgs/protocols/design-lifecycle.md)\n  and follow its specific procedure for this workflow.\n" : "";
+    outputs.set(relative, `${frontmatter[0]}\n\n${heading[0]}\n\nResolve execution policy from .nccgs/execution.json before model routing. Missing\nexecution.json means compatibility; model profile alone never removes obligations.\n\n- standalone: load the [shared standalone procedure](../../nccgs/protocols/standalone.md)\n  for this workflow, using its intake, mode, bounded domain steps and report rules.\n${designRoute}  Do not load the compatibility branches or inherit their external approval chain.\n- compatibility: read models.profile from .nccgs/project.yaml and load exactly one:\n  astra-claude uses [Astra/Claude procedure](references/astra.md); quality, balanced\n  or inherit uses [Legacy procedure](references/legacy.md). Existing task records\n  retain their original gates even after project execution policy changes.\n\nUnknown execution policies or model profiles are configuration errors. External\nreview in standalone is off, advisory or required according to execution policy;\nconfigured routes do not prove actual provider model or effort.\n`);
   }
   outputs.set(".claude/nccgs/studio.json", `${JSON.stringify(studio, null, 2)}\n`);
   outputs.set(".claude/nccgs/workflow-catalog.json", `${JSON.stringify(workflows, null, 2)}\n`);
-  outputs.set(".claude/nccgs/routing.generated.md", `# Generated routing — edit pipeline.json, then compile-policy.mjs\n\n| Stage | Owner/model | Effort |\n|---|---|---|\n| Plan and documents | Astra | External session |\n| Implementation | ${primary.models.standard.model} | ${primary.models.standard.effort} |\n| Independent review | ${primary.models.review.model} | ${primary.models.review.effort} |\n| Report check | Astra | External session |\n| Acceptance | Product Owner | Explicit decision |\n\nDefault active agents: ${primary.activeAgents.length}. Full library: ${studio.agents.length}.\n`);
+  const tierRows = Object.entries(contract.taskTiers).map(([risk, tier]) => {
+    const route = standaloneProfile.models[tier.implementationClass];
+    return `| ${risk} implementation | ${route.model} | ${route.effort} | ${tier.maxReviewRounds} |`;
+  }).join("\n");
+  const activeCount = primary.activeAgents === "all" ? studio.agents.length : primary.activeAgents.length;
+  const legacyRows = Object.entries(contract.taskTiers).map(([risk, tier]) => {
+    const route = contractProfile.models[tier.implementationClass];
+    return `| ${risk} | ${route.model} | ${route.effort} |`;
+  }).join("\n");
+  outputs.set(".claude/nccgs/routing.generated.md", `# Generated routing — edit pipeline.json, then compile-policy.mjs\n\nNCCGS runs in Claude Code. New installations use standalone execution; model aliases describe requested routes, not observed provider versions. Model selection in project.yaml and execution obligations in execution.json are separate policies.\n\n| Stage | Owner/model | Effort | Maximum review rounds |\n|---|---|---|---|\n| Intake, plan and documents | Claude Code | Routed by task | — |\n${tierRows}\n| Independent review | ${standaloneProfile.models.review.model} | ${standaloneProfile.models.review.effort} | Shared task budget |\n| External review | Off by default; advisory or required when configured | External evidence | — |\n| Acceptance | Contract-defined Product Owner decision | Explicit when required | — |\n\nFAST: nccgs-fast-implementer. STANDARD: the relevant domain programmer. CONTROLLED: nccgs-unity-implementer with the affected specialists. Use nccgs-task-scout only for a bounded missing fact; it does not replace review.\n\nA task-wide review budget survives implementation retries and continuation. Exhaustion stops the loop; a reasoned extension is required. Report is available for blocked/partial work and is not approval. Missing runtime effort remains unknown unless supplied by observed evidence.\n\nExisting installations without execution.json retain compatibility execution: Astra plan/document ownership, required external check and Product Owner acceptance. Legacy astra-claude routes remain unchanged:\n\n| Risk | Model | Effort |\n|---|---|---|\n${legacyRows}\n\nLegacy independent review: ${contractProfile.models.review.model}/${contractProfile.models.review.effort}. Updating never converts historical approval into a current approval. Explicit migration preserves tasks and consumed budgets.\n\nDefault active agents: ${activeCount}. Full library: ${studio.agents.length}.\n`);
   const scaffold = path.join(project, "scaffold/.nccgs/project.yaml");
   if (fs.existsSync(scaffold)) {
     const text = fs.readFileSync(scaffold, "utf8");

package/.claude/nccgs/tools/configure-models.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { atomicJson, hash, json, profilePolicy, contained } from "./policy.mjs";
+import { atomicJson, hash, json, profilePolicy, contained, resolveExecution } from "./policy.mjs";
 import { renderAgent } from "./compile-policy.mjs";
 import { fingerprintFile } from "./integrity.mjs";
 
@@ -14,6 +14,8 @@ const values = flag => args.flatMap((arg, index) => {
 const project = path.resolve(values("--project")[0] || path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."));
 const explicit = values("--profile")[0];
 const { name, profile, pipeline } = profilePolicy(project, explicit);
+// Profile changes never change the execution policy or pending task obligations.
+resolveExecution(project);
 const studio = json(path.join(project, ".claude/nccgs/studio.json"));
 const skip = new Set(values("--skip-path").map(p => p.replaceAll("\\", "/")));
 const activationFile = contained(project, ".nccgs/agent-activation.json");
@@ -31,6 +33,12 @@ const active = new Set(profile.activeAgents === "all" ? studio.agents.map(a => a
 const settingsFile = contained(project, ".claude/settings.json");
 const oldSettings = fs.existsSync(settingsFile) ? fs.readFileSync(settingsFile, "utf8") : "";
 const settings = oldSettings ? JSON.parse(oldSettings) : {};
+if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("Claude settings must be an object");
+const policyFile = contained(project, ".nccgs/project.yaml");
+const oldPolicy = fs.existsSync(policyFile) ? fs.readFileSync(policyFile, "utf8") : "";
+const policyPattern = /(^models:[ \t]*\r?\n(?:[ \t]+[^\n]*\n)*?[ \t]+profile:[ \t]*)[^#\r\n]+/m;
+const legacyPolicy = /^schema_version:\s*1\s*$/m.test(oldPolicy);
+if (explicit && !policyPattern.test(oldPolicy) && !legacyPolicy) throw new Error("Project policy must declare models.profile before reconfiguration");
 const writes = [], removes = [], warnings = [], generated = {}, generatedCanonical = {};
 for (const agent of studio.agents) {
   const relative = `.claude/agents/${agent.name}.md`;
@@ -66,10 +74,8 @@ if (profile.session) {
     fs.mkdirSync(path.dirname(settingsFile), { recursive: true }); fs.writeFileSync(settingsFile, next, "utf8");
   }
 }
-const policyFile = contained(project, ".nccgs/project.yaml");
-if (explicit && fs.existsSync(policyFile)) {
-  const text = fs.readFileSync(policyFile, "utf8");
-  fs.writeFileSync(policyFile, text.replace(/(^models:[ \t]*\r?\n(?:[ \t]+[^\n]*\n)*?[ \t]+profile:[ \t]*)[^#\r\n]+/m, `$1${name}`), "utf8");
+if (explicit && policyPattern.test(oldPolicy)) {
+  fs.writeFileSync(policyFile, oldPolicy.replace(policyPattern, `$1${name}`), "utf8");
 }
 atomicJson(activationFile, { schemaVersion: 1, profile: name, enabled: [...extras], generated, generatedCanonical, warnings });
 const installState = contained(project, ".claude/nccgs/install-state.json");
@@ -81,4 +87,6 @@ if (fs.existsSync(installState)) {
   atomicJson(installState, state);
 }
 console.log(`NCCGS model profile '${name}' configured; ${writes.length} agent file(s) changed; ${active.size} selected agents.`);
+console.log("Model configuration records requested aliases/effort only. Runtime resolution requires Claude Code observation; execution policy and existing task approvals are unchanged.");
+if (legacyPolicy && !policyPattern.test(oldPolicy)) console.log("Legacy project policy preserved; model selection is stored in activation/install metadata until explicit policy migration.");
 for (const warning of warnings) console.warn(warning);

package/.claude/nccgs/tools/criteria.mjs

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import { artifact, atomicJson, contained, hash, json, verifyArtifact } from "./policy.mjs";
+
+const need = (condition, message) => { if (!condition) throw new Error(message); };
+const text = value => typeof value === "string" && value.trim().length > 0;
+const scalar = value => value === null || typeof value === "boolean" || typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+
+export function validateCriteria(project, criteria) {
+  for (const item of criteria) {
+    need(item.manual === undefined || typeof item.manual === "boolean", "Criterion manual must be boolean");
+    need(item.checkpoint === undefined || ["early", "final"].includes(item.checkpoint), "Criterion checkpoint must be early or final");
+    need(!(item.manual && (item.check || item.assertions || item.checkpoint === "early")), "Manual criteria cannot also declare automatic checks/assertions or an early checkpoint");
+    if (item.assertions === undefined) continue; // Old check-only criteria remain explicitly UNVERIFIED.
+    need(Array.isArray(item.assertions) && item.assertions.length > 0 && item.assertions.length <= 100, "Criterion assertions must be a nonempty bounded array");
+    for (const rule of item.assertions) {
+      need(rule && text(rule.artifact) && rule.artifact.startsWith(".nccgs/evidence/measurements/") && rule.artifact.endsWith(".json"), "Criterion measurement must be JSON under .nccgs/evidence/measurements/");
+      need(rule.artifact.split("/").every(part => part && part !== "." && part !== ".." && !/[:\\]/.test(part) && !/[. ]$/.test(part)), "Criterion measurement paths must be canonical and cannot alias governance files");
+      contained(project, rule.artifact);
+      need(typeof rule.pointer === "string" && (rule.pointer === "" || rule.pointer.startsWith("/")) && !/~(?![01])/.test(rule.pointer), "Criterion needs a valid JSON pointer");
+      need(["eq", "gte", "lte"].includes(rule.op) && Object.hasOwn(rule, "value") && scalar(rule.value), "Criterion assertion needs eq/gte/lte and an explicit scalar value");
+      need(rule.op === "eq" || (typeof rule.value === "number" && Number.isFinite(rule.value)), "Numeric criterion thresholds must be finite numbers");
+    }
+  }
+}
+
+function fingerprint(project, relative) {
+  const file = contained(project, relative);
+  if (!fs.existsSync(file)) return null;
+  const stat = fs.statSync(file, { bigint: true });
+  need(stat.isFile() && stat.size <= 1024n * 1024n, "Criterion measurement must be a file of at most 1 MiB");
+  return { sha256: hash(fs.readFileSync(file)), size: String(stat.size), mtimeNs: String(stat.mtimeNs), ctimeNs: String(stat.ctimeNs) };
+}
+export function measurementBaseline(project, criteria) {
+  return Object.fromEntries([...new Set(criteria.flatMap(c => (c.assertions ?? []).map(r => r.artifact)))].map(relative => [relative, fingerprint(project, relative)]));
+}
+function readPointer(value, pointer) {
+  for (const part of pointer === "" ? [] : pointer.slice(1).split("/").map(s => s.replaceAll("~1", "/").replaceAll("~0", "~"))) {
+    if (value === null || typeof value !== "object" || !Object.hasOwn(value, part)) return { found: false };
+    value = value[part];
+  }
+  return { found: true, value };
+}
+function evaluate(rule, data) {
+  const actual = readPointer(data, rule.pointer);
+  if (!actual.found || !scalar(actual.value)) return { status: "UNVERIFIED", reason: "Missing or non-scalar measurement", pointer: rule.pointer };
+  if (rule.op !== "eq" && typeof actual.value !== "number") return { status: "UNVERIFIED", reason: "Numeric measurement has the wrong type", pointer: rule.pointer };
+  const pass = rule.op === "eq" ? actual.value === rule.value : rule.op === "gte" ? actual.value >= rule.value : actual.value <= rule.value;
+  return { status: pass ? "PASS" : "FAIL", pointer: rule.pointer, actual: actual.value, op: rule.op, expected: rule.value };
+}
+const overall = items => items.some(i => i.status === "FAIL") ? "FAIL" : items.some(i => i.status !== "PASS") ? "UNVERIFIED" : "PASS";
+
+// Capture measurement bytes once, at command completion, independently of exit 0.
+export function captureCriteria(project, job, technicalStatus) {
+  const outputs = new Map();
+  const criteria = (job.criteria ?? []).map(criterion => {
+    const checks = (criterion.assertions ?? []).map(rule => {
+      if (!outputs.has(rule.artifact)) {
+        try {
+          const after = fingerprint(project, rule.artifact);
+          need(after && JSON.stringify(after) !== JSON.stringify(job.measurementBaseline?.[rule.artifact] ?? null), "Measurement missing or unchanged since command launch");
+          const bytes = fs.readFileSync(contained(project, rule.artifact));
+          need(hash(bytes) === after.sha256, "Measurement changed while capturing");
+          const data = JSON.parse(bytes.toString("utf8"));
+          const relative = `.nccgs/evidence/criteria/${job.id}/${outputs.size}.json`;
+          atomicJson(contained(project, relative), data);
+          outputs.set(rule.artifact, { data, evidence: artifact(project, relative) });
+        } catch (error) { outputs.set(rule.artifact, { error: error.message }); }
+      }
+      const output = outputs.get(rule.artifact);
+      return output.error ? { status: "UNVERIFIED", reason: output.error, artifact: rule.artifact }
+        : { ...evaluate(rule, output.data), artifact: rule.artifact, evidence: output.evidence };
+    });
+    const status = technicalStatus !== "PASS" || checks.length === 0 ? "UNVERIFIED" : overall(checks);
+    return { id: criterion.id, status, checks, ...(checks.length ? {} : { reason: "Criterion has no measurable assertions" }) };
+  });
+  return { schemaVersion: 1, criteria };
+}
+
+// Read-only assessment: latest attempts win, even failures/pending attempts.
+export function assessCriteria(project, task, snap, { earlyOnly = false } = {}) {
+  const directory = contained(project, ".nccgs/jobs");
+  const jobs = fs.existsSync(directory) ? fs.readdirSync(directory, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => {
+    const request = json(path.join(directory, e.name, "request.json"));
+    need(request.id === e.name && request.taskId, "Invalid criterion job identity");
+    return request;
+  }).filter(j => j.taskId === task.id) : [];
+  const criteria = (task.contract.acceptance ?? []).filter(c => !earlyOnly || c.checkpoint === "early").map(c => {
+    const base = { id: c.id, description: c.description, check: c.check ?? null, checkpoint: c.checkpoint ?? "final" };
+    if (c.manual) return { ...base, status: "MANUAL_PENDING", reason: "Requires separate Product Owner gate" };
+    const candidates = jobs.filter(j => j.name === c.check).sort((a, b) => Date.parse(b.queuedAt) - Date.parse(a.queuedAt));
+    const job = candidates[0];
+    let receiptRef = null;
+    try {
+      need(c.assertions?.length, "Check name alone does not prove the acceptance criterion; declare assertions");
+      need(job, "No verification attempt for criterion");
+      need(!candidates[1] || candidates[1].queuedAt !== job.queuedAt, "Ambiguous concurrent verification attempts");
+      need(job.snapshot === snap && job.contractHash === task.contractHash, "Criterion evidence is stale for source/contract");
+      const result = json(path.join(directory, job.id, "result.json"));
+      const receipt = json(verifyArtifact(project, result.evidence));
+      need(receipt.taskId === task.id && receipt.jobId === job.id && receipt.name === c.check && receipt.snapshot === snap && receipt.contractHash === task.contractHash, "Criterion receipt identity mismatch");
+      need(Date.parse(receipt.startedAt) >= Date.parse(task.canonicalInputs.pinnedAt), "Criterion evidence predates current input pin");
+      receiptRef = result.evidence;
+      need(receipt.status === "PASS" && receipt.exitCode === 0 && receipt.sourceUnchanged && !receipt.timedOut, "Technical verification failed or is incomplete");
+      verifyArtifact(project, receipt.log);
+      const captured = receipt.acceptance?.criteria?.find(x => x.id === c.id);
+      need(captured && captured.checks.length === c.assertions.length, "Receipt does not capture every criterion assertion");
+      const checks = c.assertions.map((rule, index) => {
+        const observed = captured.checks[index];
+        need(observed.artifact === rule.artifact, "Captured measurement mapping mismatch");
+        if (!observed.evidence) return { status: "UNVERIFIED", reason: observed.reason || "Missing captured measurement" };
+        return evaluate(rule, json(verifyArtifact(project, observed.evidence)));
+      });
+      return { ...base, status: overall(checks), checks, receipt: result.evidence, jobId: job.id };
+    } catch (error) { return { ...base, status: "UNVERIFIED", reason: error.message, jobId: job?.id ?? null, ...(receiptRef ? { receipt: receiptRef } : {}) }; }
+  });
+  const automatic = criteria.filter(c => c.status !== "MANUAL_PENDING");
+  return { schemaVersion: 1, taskId: task.id, snapshot: snap, contractHash: task.contractHash, criteria,
+    automaticPassed: automatic.every(c => c.status === "PASS"), manualPending: criteria.filter(c => c.status === "MANUAL_PENDING").map(c => c.id),
+    status: overall(automatic), scope: "Measured criteria only; technical PASS and human acceptance are separate" };
+}

package/.claude/nccgs/tools/delivery-budget.mjs

@@ -0,0 +1,52 @@
+import { verifyArtifact } from "./policy.mjs";
+import { assessCriteria } from "./criteria.mjs";
+
+const need = (condition, message) => { if (!condition) throw new Error(message); };
+export function deliveryBudget(entry, items) {
+  if (!entry?.deliveryReserve) return null;
+  const remaining = Object.fromEntries(Object.entries(entry.deliveryReserve).map(([purpose, count]) =>
+    [purpose, Math.max(0, count - items.filter(d => (d.purpose ?? (d.kind === "review" ? "review" : "delivery")) === purpose).length)]));
+  const protectedSlots = Object.values(remaining).reduce((a, b) => a + b, 0);
+  return { reserved: entry.deliveryReserve, remaining, protectedSlots,
+    totalRemaining: Math.max(0, entry.limits.maxDispatches - items.length),
+    deliveryRemaining: Math.max(0, entry.limits.maxDispatches - items.length - protectedSlots),
+    note: "Attempts consume quota even on failure/cancellation; protected slots are not extra budget" };
+}
+export function requireDeliveryRoom(entry, items, purpose, taskId) {
+  const next = deliveryBudget(entry, [...items, { purpose }]);
+  need(!next || items.length + 1 + next.protectedSlots <= entry.limits.maxDispatches,
+    `Delivery budget reserved for ${taskId}: repair, QA and independent review; stop expansion and report partial or use an eligible protected purpose`);
+}
+export function dispatchPurpose(project, task, request, snap) {
+  const purpose = request.purpose ?? (request.kind === "review" ? "review" : "delivery");
+  need(["delivery", "repair", "qa", "review"].includes(purpose), "Invalid dispatch purpose");
+  need((purpose === "review") === (request.kind === "review"), "Review dispatch requires review purpose");
+  need(purpose !== "repair" || request.kind === "implementation", "Repair purpose requires an implementation worker");
+  need(purpose !== "qa" || (request.kind === "analysis" && ["nccgs-qa-engineer", "nccgs-verification-engineer"].includes(request.agent)), "QA purpose requires a read-only QA/verification worker");
+  need(purpose !== "qa" || request.repairFeedback, "Protected QA is reserved for a completed repair; initial QA uses delivery purpose");
+  let feedback = null;
+  if (["repair", "qa"].includes(purpose)) {
+    const reviews = [task.stages?.review, ...(task.history ?? []).slice().reverse().map(h => h.stages?.review)].filter(Boolean);
+    const latest = reviews.find(r => r.contractHash === task.contractHash);
+    const negative = latest && ["CHANGES_REQUIRED", "BLOCKED"].includes(latest.verdict) ? latest : null;
+    if (negative) { verifyArtifact(project, negative.evidence); feedback = { kind: "review", evidence: negative.evidence, verdict: negative.verdict }; }
+    else {
+      const assessment = assessCriteria(project, task, snap);
+      const failed = assessment.criteria.filter(c => ["FAIL", "UNVERIFIED"].includes(c.status) && c.receipt);
+      if (failed.length) feedback = { kind: "criteria", criteria: failed.map(c => ({ id: c.id, status: c.status, receipt: c.receipt })) };
+    }
+    // QA must also be available after a repair changes source and invalidates
+    // the failing measurements. The caller supplies the pinned repair history.
+    if (!feedback && purpose === "qa" && request.repairFeedback) feedback = request.repairFeedback;
+    need(feedback, "Protected repair/QA requires recorded negative review or measured acceptance failure; missing initial evidence alone is not feedback");
+  }
+  return { purpose, feedback };
+}
+export function requireEarlyCheckpoint(project, task, entry, items, purpose, kind, snap) {
+  const early = (task.contract.acceptance ?? []).filter(c => c.checkpoint === "early");
+  if (kind !== "implementation" || purpose !== "delivery" || !early.length || !items.some(d => d.kind === "implementation" && (d.status === "completed" || d.runtime))) return;
+  if (entry.earlyCheckpoint?.contractHash === task.contractHash) return;
+  const assessment = assessCriteria(project, task, snap, { earlyOnly: true });
+  need(assessment.automaticPassed, `Early acceptance checkpoint blocks expansion: ${assessment.criteria.filter(c => c.status !== "PASS").map(c => `${c.id}=${c.status}`).join(", ")}; collect a playable-slice measurement or report partial`);
+  entry.earlyCheckpoint = { contractHash: task.contractHash, snapshot: snap, capturedAt: new Date().toISOString(), assessment };
+}

package/.claude/nccgs/tools/design-readiness.mjs

@@ -0,0 +1,158 @@
+import crypto from "node:crypto";
+import { artifact, atomicJson, contained, json, resolveExecution, verifyArtifact } from "./policy.mjs";
+import { check, taskPath } from "./gates.mjs";
+import { validateCriteria } from "./criteria.mjs";
+
+const need = (ok, message) => { if (!ok) throw new Error(`Design readiness: ${message}`); };
+const text = value => typeof value === "string" && value.trim().length > 0;
+const list = (value, label) => { need(Array.isArray(value), `${label} must be an array`); return value; };
+const strings = (value, label) => { list(value, label); need(value.every(text) && new Set(value).size === value.length, `${label} must contain unique nonempty strings`); return value; };
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+export const sameDesignValue = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+
+// Structural coverage is enforceable; the independent reviewer owns semantic adequacy.
+export function validateDesign(project, document) {
+  need(document?.schemaVersion === 1 && text(document.objective), "document needs schemaVersion 1 and objective");
+  need(["READY", "READY_WITH_RISKS", "BLOCKED"].includes(document.readiness), "invalid document readiness");
+  need(["local", "feature", "cross-system"].includes(document.scope), "invalid scope");
+  need(["fix", "learning-prototype", "alpha-ready", "production-change"].includes(document.target), "invalid target");
+  const ready = document.readiness !== "BLOCKED";
+  const sources = list(document.sources, "sources");
+  need(sources.length > 0, "at least one hashed canonical source is required");
+  for (const source of sources) verifyArtifact(project, source);
+  need(new Set(sources.map(s => s.path)).size === sources.length, "duplicate source path");
+  const citation = (value, label) => need(value && text(value.anchor) && sources.some(s => s.path === value.path && s.sha256 === value.sha256), `${label} needs a pinned source and section/excerpt anchor`);
+  const criteria = list(document.acceptance, "acceptance"), ids = new Set();
+  for (const criterion of criteria) {
+    need(text(criterion.id) && !ids.has(criterion.id) && text(criterion.description), "criterion needs unique id and description"); ids.add(criterion.id);
+    for (const field of ["procedure", "environment", "passCondition", "rationale"]) need(text(criterion[field]), `${criterion.id} needs ${field}`);
+    citation(criterion.authority, `${criterion.id} threshold authority`);
+    need(criterion.manual === true || (text(criterion.check) && criterion.assertions?.length > 0), `${criterion.id} needs measured assertions or an explicit human gate`);
+  }
+  validateCriteria(project, criteria);
+  const requirements = list(document.requirements, "requirements"), reqIds = new Set(), covered = new Set();
+  need(requirements.length > 0, "requirements are missing");
+  for (const requirement of requirements) {
+    need(text(requirement.id) && !reqIds.has(requirement.id), "requirement id is missing or duplicated"); reqIds.add(requirement.id);
+    citation(requirement.source, `${requirement.id} source`);
+    need(text(requirement.statement) && text(requirement.rules), `${requirement.id} needs statement and explicit rules/states/edge cases`);
+    need(["fixed", "delegated-tuning"].includes(requirement.kind), `${requirement.id} must distinguish fixed rules and delegated tuning`);
+    if (requirement.kind === "delegated-tuning") {
+      need(text(requirement.tuning?.bounds) && text(requirement.tuning?.parameters), `${requirement.id} needs tuning parameters and bounds`);
+      citation(requirement.tuning?.authority, `${requirement.id} tuning authority`);
+    }
+    strings(requirement.criteria, `${requirement.id} criteria`);
+    need(!ready || requirement.criteria.length > 0, `${requirement.id} has no acceptance mapping`);
+    for (const id of requirement.criteria) { need(ids.has(id), `${requirement.id} references unknown criterion ${id}`); covered.add(id); }
+  }
+  need(criteria.every(c => covered.has(c.id)), "an acceptance criterion has no requirement source");
+  const decisions = list(document.decisions, "decisions"), decisionIds = new Set();
+  for (const decision of decisions) {
+    need(text(decision.id) && !decisionIds.has(decision.id) && text(decision.question), "decision needs unique id and question"); decisionIds.add(decision.id);
+    need(["open", "resolved"].includes(decision.status), "invalid decision status");
+    if (decision.status === "resolved") { need(text(decision.resolution), "resolved decision needs resolution"); citation(decision.authority, `${decision.id} decision authority`); }
+    need(!ready || decision.status === "resolved", "open product decisions cannot be READY");
+  }
+  strings(document.requiredChecks, "requiredChecks"); strings(document.manualGates, "manualGates");
+  for (const criterion of criteria) need(criterion.manual ? document.manualGates.includes(criterion.id) : document.requiredChecks.includes(criterion.check), `${criterion.id} is absent from required checks/manual gates`);
+  strings(document.outOfScope, "outOfScope"); strings(document.risks, "risks");
+  for (const diagnostic of list(document.diagnostics, "diagnostics")) {
+    need(text(diagnostic.id) && text(diagnostic.procedure) && text(diagnostic.limitations), "diagnostics need id, procedure and limitations");
+    need(!ids.has(diagnostic.id), "a diagnostic cannot silently double as an acceptance criterion");
+  }
+  return document;
+}
+
+export function validateDesignCommand(project, id, relative) {
+  const task = json(taskPath(project, id));
+  need(task.schemaVersion === 2 && task.mode === "plan" && task.contract.workflow === "design", "design-validate requires a standalone /design plan task");
+  need(task.contract.analysisArtifacts.includes(relative), "document must be a declared analysis artifact");
+  need(task.contract.requiredChecks.includes("design-contract"), "plan must require the design-contract check");
+  const state = check(project, task, "analysis"); need(state.allowed, state.message);
+  const reference = artifact(project, relative), document = validateDesign(project, json(verifyArtifact(project, reference)));
+  const receipt = { schemaVersion: 1, origin: "design-contract-validation", taskId: id, contractHash: task.contractHash,
+    snapshot: state.snapshot, status: "PASS", name: "design-contract", document: reference,
+    readiness: document.readiness, capturedAt: new Date().toISOString(), scope: "Structural document validation only; independent semantic review is still required" };
+  const output = `.nccgs/evidence/design-checks/${crypto.randomUUID()}.json`;
+  atomicJson(contained(project, output), receipt);
+  return { ...receipt, evidence: artifact(project, output) };
+}
+
+export function verifyDesignReceipt(project, task, stage, receipt) {
+  need(receipt.origin === "design-contract-validation" && receipt.status === "PASS" && receipt.name === "design-contract"
+    && receipt.taskId === task.id && receipt.contractHash === task.contractHash && receipt.snapshot === stage.snapshot, "validation receipt is stale or belongs to another task");
+  need(sameDesignValue(receipt.document, stage.evidence), "validated document differs from the analysis handoff");
+  return validateDesign(project, json(verifyArtifact(project, receipt.document)));
+}
+
+// Fixed read-only comparison for plan coordinators; no arbitrary shell or code.
+// Allowed changes remain a semantic scope decision for the independent reviewer.
+export function compareDesignCommand(project, id, baselinePath, candidatePath) {
+  const task = json(taskPath(project, id));
+  need(task.schemaVersion === 2 && task.mode === "plan" && task.contract.workflow === "design", "design-compare requires a standalone /design plan task");
+  need(task.contract.analysisArtifacts.includes(candidatePath), "candidate must be a declared analysis artifact");
+  const baseline = task.contract.sources.find(ref => ref.path === baselinePath);
+  need(baseline && baselinePath !== candidatePath, "baseline must be a distinct pinned intake source");
+  const state = check(project, task, "analysis"); need(state.allowed, state.message);
+  const candidate = artifact(project, candidatePath);
+  const before = json(verifyArtifact(project, baseline)), after = json(verifyArtifact(project, candidate));
+  const changes = key => {
+    const index = document => {
+      const entries = list(document[key], key), ids = new Set();
+      for (const item of entries) { need(text(item.id) && !ids.has(item.id), `${key} needs unique ids`); ids.add(item.id); }
+      return new Map(entries.map(item => [item.id, item]));
+    };
+    const a = index(before), b = index(after);
+    return { added: [...b.keys()].filter(id => !a.has(id)), removed: [...a.keys()].filter(id => !b.has(id)),
+      changed: [...a.keys()].filter(id => b.has(id) && !sameDesignValue(a.get(id), b.get(id))),
+      orderChanged: !sameDesignValue([...a.keys()], [...b.keys()]) };
+  };
+  const otherKeys = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(key => !["requirements", "acceptance"].includes(key));
+  const receipt = { schemaVersion: 1, origin: "design-contract-comparison", taskId: id, contractHash: task.contractHash,
+    snapshot: state.snapshot, baseline, candidate, capturedAt: new Date().toISOString(),
+    requirements: changes("requirements"), acceptance: changes("acceptance"),
+    otherTopLevelChanges: otherKeys.filter(key => !sameDesignValue(before[key], after[key])),
+    scope: "JSON value comparison only; not semantic review, allowed-change approval or game acceptance" };
+  // Recheck the bytes after comparing so the receipt never pins a raced read.
+  verifyArtifact(project, baseline); verifyArtifact(project, candidate);
+  const output = `.nccgs/evidence/design-checks/${crypto.randomUUID()}.json`;
+  atomicJson(contained(project, output), receipt);
+  return { ...receipt, evidence: artifact(project, output) };
+}
+
+export function pinDesign(project, designId, consumerId) {
+  need(text(designId) && designId !== consumerId, "use a distinct completed design task");
+  const taskRef = artifact(project, `.nccgs/tasks/${designId}.json`), task = json(verifyArtifact(project, taskRef));
+  need(task.id === designId && task.mode === "plan" && task.contract.workflow === "design"
+    && task.closed?.snapshot && task.closed.snapshot === task.stages.review?.snapshot, "design task must be a completed /design plan");
+  const gate = check(project, task, "done"); need(gate.allowed, gate.message);
+  const analysis = task.stages.analysis, review = task.stages.review;
+  const document = validateDesign(project, json(verifyArtifact(project, analysis.evidence)));
+  need(document.readiness !== "BLOCKED", "design is BLOCKED");
+  const checked = analysis.checks.find(c => c.name === "design-contract"); need(checked, "design validation receipt missing");
+  verifyDesignReceipt(project, task, analysis, json(verifyArtifact(project, checked.evidence)));
+  const references = [taskRef, task.intake, analysis.evidence, checked.evidence, review.evidence, ...document.sources];
+  for (const stage of [analysis, review]) {
+    references.push(stage.runtime);
+    const runtime = json(verifyArtifact(project, stage.runtime)); references.push(runtime.observationSource);
+  }
+  return { schemaVersion: 1, taskId: designId, document: analysis.evidence, references,
+    reviewedSnapshot: review.snapshot, pinnedAt: new Date().toISOString(), specification: document };
+}
+
+export function requireDesignReady(project, task) {
+  if (task.schemaVersion !== 2 || task.mode !== "implement") return;
+  const pinned = task.contract.design;
+  const required = (task.execution ?? resolveExecution(project)).designReviewRequired === true;
+  if (!required && !pinned) return; // Historical policies retain their original obligations.
+  need(task.contract.readiness === "ready", "implementation still needs inspection or a product decision");
+  const localFix = task.contract.scope === "local" && task.contract.target === "fix" && task.contract.acceptance.length > 0;
+  if (!pinned && localFix) return; // Explicit, testable local fix; no new feature semantics.
+  need(pinned?.schemaVersion === 1, "reviewed design missing; complete /design -> /design-review -> /story-readiness before implementation");
+  for (const ref of pinned.references) verifyArtifact(project, ref);
+  const document = validateDesign(project, json(verifyArtifact(project, pinned.document)));
+  need(document.readiness !== "BLOCKED", "design is BLOCKED");
+  for (const key of ["objective", "scope", "target", "acceptance"]) need(sameDesignValue(task.contract[key], document[key]), `implementation ${key} differs from reviewed design`);
+  for (const key of ["requiredChecks", "manualGates"]) need(document[key].every(item => task.contract[key].includes(item)), `implementation omits reviewed ${key}`);
+}

package/.claude/nccgs/tools/evidence.mjs

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { artifact, contained, hash, verifyArtifact } from "./policy.mjs";
+
+const durableRoot = ".nccgs/evidence/runtime";
+const legacyRoot = ".nccgs/runtime/";
+const isRef = value => value && typeof value === "object" && typeof value.path === "string" && typeof value.sha256 === "string";
+const encode = value => Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+
+function readReference(project, ref, label) {
+  try {
+    const file = verifyArtifact(project, ref);
+    const bytes = fs.readFileSync(file);
+    if (hash(bytes) !== ref.sha256) throw new Error("Evidence changed while being copied");
+    return bytes;
+  } catch (error) {
+    throw new Error(`${label}: missing, stale, or unsafe evidence '${ref?.path ?? "unknown"}': ${error.message}`);
+  }
+}
+
+// Content-addressed copies retain the original bytes. Plan every copy before any
+// writes so a missing legacy source cannot produce a partly migrated task.
+function copyPlan(project) {
+  const writes = new Map();
+  const migrations = [];
+  const seenMigrations = new Set();
+  const add = (kind, bytes) => {
+    const sha256 = hash(bytes);
+    const relative = `${durableRoot}/${kind}/${sha256}.json`;
+    const file = contained(project, relative);
+    if (fs.existsSync(file)) {
+      if (!fs.statSync(file).isFile() || hash(fs.readFileSync(file)) !== sha256) {
+        throw new Error(`Durable evidence collision or corruption: ${relative}`);
+      }
+    } else writes.set(relative, bytes);
+    return { path: relative, sha256 };
+  };
+  const note = (from, to, kind) => {
+    if (from.path === to.path && from.sha256 === to.sha256) return;
+    const key = `${kind}:${from.path}:${from.sha256}:${to.path}`;
+    if (!seenMigrations.has(key)) {
+      migrations.push({ kind, from: { ...from }, to: { ...to } });
+      seenMigrations.add(key);
+    }
+  };
+  const source = ref => {
+    const bytes = readReference(project, ref, "Runtime source");
+    if (ref.path.startsWith(`${durableRoot}/sources/`)) return { ...ref };
+    const durable = add("sources", bytes);
+    note(ref, durable, "source");
+    return durable;
+  };
+  const observation = (value, sourceRef) => {
+    const durableSource = source(sourceRef);
+    const normalized = { ...value, observationSource: durableSource };
+    if (sourceRef.path !== durableSource.path || sourceRef.sha256 !== durableSource.sha256) {
+      normalized.originalObservationSource = value.originalObservationSource ?? { ...sourceRef };
+    }
+    return add("observations", encode(normalized));
+  };
+  const commit = () => {
+    // Recheck destinations before writing; never overwrite an existing artifact.
+    for (const [relative, bytes] of writes) {
+      const file = contained(project, relative);
+      if (fs.existsSync(file) && (!fs.statSync(file).isFile() || hash(fs.readFileSync(file)) !== hash(bytes))) {
+        throw new Error(`Durable evidence collision or corruption: ${relative}`);
+      }
+    }
+    for (const [relative, bytes] of writes) {
+      const file = contained(project, relative);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      try { fs.writeFileSync(file, bytes, { flag: "wx" }); }
+      catch (error) { if (error.code !== "EEXIST") throw error; }
+      if (artifact(project, relative).sha256 !== hash(bytes)) {
+        throw new Error(`Durable evidence copy failed verification: ${relative}`);
+      }
+    }
+  };
+  return { add, source, observation, note, migrations, commit };
+}
+
+/** Persist an observation and an exact durable copy of its raw source.
+ * Callers retain responsibility for validating runtime identity and provenance.
+ */
+export function persistRuntimeObservation(project, observation, sourceRef) {
+  if (!observation || typeof observation !== "object" || Array.isArray(observation)) {
+    throw new Error("Runtime observation must be an object");
+  }
+  const plan = copyPlan(project);
+  const result = plan.observation(observation, sourceRef);
+  plan.commit();
+  return result;
+}
+
+/** Return a migrated clone; the caller owns task locking and atomic task writes.
+ * No source, stage, history entry, review counter, or original artifact is deleted.
+ * This does not refresh snapshots, evidence times, approvals, or task validity.
+ */
+export function migrateTaskEvidence(project, task) {
+  const plan = copyPlan(project);
+  const cache = new Map();
+  const migrateReference = ref => {
+    const key = `${ref.path}:${ref.sha256}`;
+    if (cache.has(key)) return { ...ref, ...cache.get(key) };
+    const bytes = readReference(project, ref, "Runtime observation");
+    let value;
+    try { value = JSON.parse(bytes.toString("utf8")); }
+    catch {
+      if (ref.path.includes("/observations/")) throw new Error(`Invalid runtime observation JSON: ${ref.path}`);
+    }
+    let result = ref;
+    if (value?.origin === "runtime-observation") {
+      if (!isRef(value.observationSource)) throw new Error(`Runtime observation has no verifiable raw source: ${ref.path}`);
+      const sourceRef = value.observationSource;
+      const source = plan.source(sourceRef);
+      const needsCopy = !ref.path.startsWith(`${durableRoot}/observations/`) || source.path !== sourceRef.path;
+      if (needsCopy) {
+        const archive = plan.add("sources", bytes);
+        plan.note(ref, archive, "observation-archive");
+        const migrated = { ...value, observationSource: source,
+          originalObservationSource: value.originalObservationSource ?? { ...sourceRef },
+          evidenceMigration: { originalObservation: { ...ref }, archivedObservation: archive,
+            ...(value.evidenceMigration ? { previous: value.evidenceMigration } : {}) } };
+        result = plan.add("observations", encode(migrated));
+        plan.note(ref, result, "observation");
+      }
+    } else if (ref.path.startsWith(legacyRoot)) {
+      if (ref.path.includes("/observations/")) throw new Error(`Invalid runtime observation origin: ${ref.path}`);
+      result = plan.source(ref);
+    }
+    cache.set(key, result);
+    return { ...ref, ...result };
+  };
+  const walk = (value, key = "") => {
+    if (Array.isArray(value)) return value.map(item => walk(item, key));
+    if (!value || typeof value !== "object") return value;
+    // Original paths in our audit records describe where bytes came from; they
+    // are not live dependencies after a clean copy removes the ignored runtime.
+    if (value.action === "migrate-evidence" ||
+        (["source", "observation", "observation-archive"].includes(value.kind) && isRef(value.from) && isRef(value.to))) {
+      return structuredClone(value);
+    }
+    if (isRef(value)) {
+      // Do not revalidate unrelated old plan/report refs when migrating history.
+      if (key === "runtime" || value.path.startsWith(legacyRoot)) return migrateReference(value);
+      return { ...value };
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, walk(child, name)]));
+  };
+  const migrated = walk(task);
+  plan.commit();
+  return { task: migrated, migrations: plan.migrations, changed: plan.migrations.length > 0 };
+}