nccgs 2.0.0-rc.2 → 2.0.0

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

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import { artifact, atomicJson, contained, hash, json, verifyArtifact } from "./policy.mjs";
+import { acquireLock, ownerState, pidState } from "./process-lock.mjs";
+import { sessionBudgetLock, settledCost, taskWithin } from "./session-budget.mjs";
+
+const need = (ok, message) => { if (!ok) throw new Error(`Review reserve: ${message}`); };
+const taskFile = (project, id) => {
+  need(typeof id === "string" && /^[a-zA-Z0-9][\w-]{0,79}$/.test(id), "invalid task ID");
+  return contained(project, `.nccgs/tasks/${id}.json`);
+};
+const planPath = id => `.nccgs/budgets/${id}.json`;
+const markerPath = id => `.nccgs/budgets/${id}.initialized.json`;
+const terms = plan => ({ schemaVersion: plan.schemaVersion, taskId: plan.taskId, limits: plan.limits,
+  request: plan.request, createdAt: plan.createdAt, deadline: plan.deadline, workDeadline: plan.workDeadline });
+function readPlan(project, id) {
+  const file = contained(project, planPath(id)), marker = contained(project, markerPath(id));
+  if (!fs.existsSync(file)) { need(!fs.existsSync(marker), "initialized budget history is missing; never reset it"); return null; }
+  const plan = json(file);
+  need(plan.schemaVersion === 1 && plan.taskId === id && Array.isArray(plan.allocations), "invalid budget plan");
+  need(fs.existsSync(marker) && json(marker).sha256 === hash(JSON.stringify(terms(plan))), "pinned budget terms changed or marker missing");
+  verifyArtifact(project, plan.request);
+  return plan;
+}
+export function findReviewBudget(project, id) {
+  const seen = new Set(); let found = null;
+  while (id) {
+    need(!seen.has(id), "task ancestry cycle"); seen.add(id);
+    const task = json(taskFile(project, id)), plan = readPlan(project, id);
+    need(!plan || !found, "nested budgets cannot mint another reserve");
+    if (plan) found = plan;
+    id = task.parentId;
+  }
+  return found;
+}
+function familyRuns(project, id) {
+  const dir = contained(project, ".nccgs/runs");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => {
+    const run = json(contained(project, `.nccgs/runs/${e.name}/run.json`));
+    need(run.id === e.name && run.project === project, "invalid native run history"); return run;
+  }).filter(run => taskWithin(project, run.taskId, id));
+}
+function requireWorkerCoverage(project, id, runs, ledger = null) {
+  const file = contained(project, ".nccgs/orchestration.json");
+  ledger ??= fs.existsSync(file) ? json(file) : null;
+  const sessions = new Set(runs.map(run => run.sessionId));
+  need(sessions.size === runs.length, "duplicate session across run records");
+  const workers = Object.values(ledger?.dispatches ?? {}).filter(d => d.startedAt && taskWithin(project, d.taskId, id));
+  need(workers.every(d => sessions.has(d.sessionId)), "worker session has no supervised cost coverage; preserve and reconcile historical spend");
+}
+function history(project, plan, currentId = null) {
+  const records = plan.allocations.map(ref => ({ ...json(verifyArtifact(project, ref)), reference: ref }));
+  need(new Set(records.map(r => r.runId)).size === records.length, "duplicate run allocation");
+  const runs = familyRuns(project, plan.taskId), ids = new Set(runs.map(r => r.id));
+  requireWorkerCoverage(project, plan.taskId, runs);
+  need(records.every(r => ids.has(r.runId)), "allocated run history is missing; spent allowances cannot be refunded");
+  const neverStarted = r => r.status === "blocked" && r.costCoverage === "complete" && r.invocations.length === 0 && r.cumulativeCostUsd === 0;
+  need(runs.every(r => r.id === currentId || records.some(a => a.runId === r.id) || neverStarted(r)), "unallocated native session; reconcile history before spending");
+  let workUsd = 0, reviewUsd = 0;
+  const sessions = [];
+  for (const run of runs.filter(r => r.id !== currentId)) {
+    const allocation = records.find(r => r.runId === run.id);
+    if (!allocation && neverStarted(run)) { sessions.push({ runId: run.id, sessionId: run.sessionId, phase: "not-started", costUsd: 0 }); continue; }
+    need(allocation.sessionId === run.sessionId && ["work", "final-review"].includes(allocation.phase), "allocation identity mismatch");
+    if (!allocation.legacy) need(run.budgetAllocation?.sha256 === allocation.reference.sha256, "native run allocation changed");
+    const cost = settledCost(project, run);
+    if (allocation.phase === "final-review") reviewUsd += cost; else workUsd += cost;
+    sessions.push({ runId: run.id, sessionId: run.sessionId, phase: allocation.phase, costUsd: cost });
+  }
+  return { records, sessions, workUsd, reviewUsd, totalUsd: workUsd + reviewUsd };
+}
+export function registerReviewBudget(project, id, relative) {
+  need(!process.env.CLAUDECODE && !process.env.CLAUDE_CODE_ENTRYPOINT, "budget allocation is external only");
+  const lock = acquireLock(contained(project, sessionBudgetLock), { operation: "register-review-reserve", taskId: id });
+  try {
+    const task = json(taskFile(project, id)), request = artifact(project, relative), input = json(verifyArtifact(project, request));
+    need(task.schemaVersion === 2 && !task.closed, "an open standalone root task is required");
+    const existing = findReviewBudget(project, id);
+    if (existing) { need(existing.taskId === id && existing.request.sha256 === request.sha256, "budget terms are already pinned; no replacement or extension"); return existing; }
+    need(!task.parentId, "register the reserve on the existing task root, never on a child");
+    need(input.schemaVersion === 1 && typeof input.authority === "string" && input.authority.trim(), "explicit external allocation authority is required");
+    const { totalUsd, finalReviewUsd, totalDurationMs, finalReviewDurationMs } = input;
+    need(Number.isFinite(totalUsd) && totalUsd > 0 && Number.isFinite(finalReviewUsd) && finalReviewUsd > 0 && finalReviewUsd < totalUsd, "invalid total/review cost allocation");
+    need(Number.isSafeInteger(totalDurationMs) && totalDurationMs >= 1000 && totalDurationMs <= 86400000
+      && Number.isSafeInteger(finalReviewDurationMs) && finalReviewDurationMs >= 1000 && finalReviewDurationMs < totalDurationMs, "invalid total/review time allocation");
+    const ledgerFile = contained(project, ".nccgs/orchestration.json"), ledger = fs.existsSync(ledgerFile) ? json(ledgerFile) : null;
+    need(!Object.values(ledger?.dispatches ?? {}).some(d => ["reserved", "running", "uncertain"].includes(d.status)), "settle all workers before allocating a reserve");
+    const pinned = ledger?.tasks[id]?.limits.maxCostUsd;
+    need(pinned == null || totalUsd <= pinned, "allocation cannot raise the pinned aggregate cap");
+    const prior = familyRuns(project, id);
+    requireWorkerCoverage(project, id, prior, ledger);
+    const spent = prior.reduce((sum, run) => sum + settledCost(project, run), 0);
+    need(spent < totalUsd - finalReviewUsd, "past spending leaves insufficient work/review reserve; cannot reserve spent money retroactively");
+    const createdAt = new Date().toISOString();
+    const deadline = prior.length ? Math.min(Date.now() + totalDurationMs, Math.max(...prior.map(r => r.deadline))) : Date.now() + totalDurationMs;
+    const workDeadline = deadline - finalReviewDurationMs;
+    need(Date.now() < workDeadline, "past elapsed time leaves no protected review window");
+    const plan = { schemaVersion: 1, taskId: id, request, limits: { totalUsd, finalReviewUsd, totalDurationMs, finalReviewDurationMs },
+      createdAt, deadline, workDeadline, allocations: [] };
+    for (const run of prior) {
+      const file = `.nccgs/budgets/allocations/${run.id}.json`;
+      atomicJson(contained(project, file), { runId: run.id, sessionId: run.sessionId, taskId: run.taskId, phase: "work", legacy: true, recordedAt: createdAt });
+      plan.allocations.push(artifact(project, file));
+    }
+    atomicJson(contained(project, markerPath(id)), { sha256: hash(JSON.stringify(terms(plan))) });
+    atomicJson(contained(project, planPath(id)), plan);
+    return plan;
+  } finally { lock.release(); }
+}
+export function allocateReviewBudget(project, state, phase = "work") {
+  const plan = findReviewBudget(project, state.taskId);
+  if (!plan) { need(phase === "work", "final-review needs a pinned aggregate reserve"); return null; }
+  need(["work", "final-review"].includes(phase), "unknown budget phase");
+  const lock = json(contained(project, sessionBudgetLock));
+  need(lock.runId === state.id && lock.sessionId === state.sessionId && ownerState(lock) === "alive", "exclusive supervisor ownership is required");
+  const task = json(taskFile(project, state.taskId));
+  need(phase !== "final-review" || ["implement", "audit"].includes(task.mode), "design review cannot consume the final delivery reserve");
+  const prior = history(project, plan, state.id), existing = prior.records.find(a => a.runId === state.id);
+  const available = phase === "work"
+    ? plan.limits.totalUsd - prior.workUsd - Math.max(plan.limits.finalReviewUsd, prior.reviewUsd)
+    : plan.limits.totalUsd - prior.totalUsd;
+  const deadline = phase === "work" ? plan.workDeadline : plan.deadline;
+  need(available > 0 && Date.now() < deadline, "phase allowance exhausted; retain the final review reserve and original total");
+  if (existing) {
+    need(existing.phase === phase && state.budgetAllocation?.sha256 === existing.reference.sha256
+      && state.budgetUsd === existing.allowanceUsd && state.deadline === existing.deadline, "recovery cannot alter the allocated phase, cost or deadline");
+    need(state.budgetUsd <= available + 1e-9 && state.deadline <= deadline && Date.now() < state.deadline, "historical spending/time no longer covers this allocation");
+    return existing;
+  }
+  const requestedUsd = state.budgetUsd, requestedDeadline = state.deadline;
+  state.budgetUsd = Math.min(requestedUsd, available); state.deadline = Math.min(requestedDeadline, deadline); state.budgetPhase = phase;
+  const value = { schemaVersion: 1, rootTaskId: plan.taskId, taskId: state.taskId, runId: state.id, sessionId: state.sessionId,
+    phase, requestedUsd, allowanceUsd: state.budgetUsd, requestedDeadline, deadline: state.deadline,
+    recordedAt: new Date().toISOString(), priorSessions: prior.sessions, protectedReviewUsd: Math.max(0, plan.limits.finalReviewUsd - prior.reviewUsd),
+    workerCostInferred: false };
+  const file = `.nccgs/budgets/allocations/${state.id}.json`;
+  need(!fs.existsSync(contained(project, file)), "allocation already exists; preserve interrupted history");
+  atomicJson(contained(project, file), value); state.budgetAllocation = artifact(project, file);
+  plan.allocations.push(state.budgetAllocation); atomicJson(contained(project, planPath(plan.taskId)), plan);
+  return value;
+}
+export function plannedDispatchBudget(project, id, request) {
+  const plan = findReviewBudget(project, id); if (!plan) return null;
+  const runId = process.env.NCCGS_SUPERVISED_RUN;
+  need(typeof runId === "string" && /^[a-f0-9-]{36}$/.test(runId), "planned tasks require their supervised allocation");
+  const state = json(contained(project, `.nccgs/runs/${runId}/run.json`));
+  need(state.taskId === id && state.sessionId === process.env.NCCGS_SUPERVISED_SESSION && state.status === "running"
+    && pidState(state.invocations.at(-1)?.pid) === "alive", "current allocated native session is not live/correlated");
+  const allocation = allocateReviewBudget(project, state, state.budgetPhase);
+  const task = json(taskFile(project, id));
+  if (allocation.phase === "final-review") need(request.kind === "review" && ["implement", "audit"].includes(task.mode), "final-review funds cannot dispatch implementation, repair, analysis or design workers");
+  else need(request.kind !== "review" || !["implement", "audit"].includes(task.mode), "delivery/audit review must use the protected final-review phase");
+  return { ...allocation, reference: state.budgetAllocation };
+}
+export function inFinalReviewPhase(project, sessionId) {
+  const id = process.env.NCCGS_SUPERVISED_RUN; if (!id) return false;
+  need(/^[a-f0-9-]{36}$/.test(id), "invalid supervised run ID");
+  const run = json(contained(project, `.nccgs/runs/${id}/run.json`));
+  need(run.sessionId === sessionId, "supervised session mismatch");
+  return run.budgetPhase === "final-review";
+}
+export function reviewBudgetStatus(project, id) {
+  const plan = findReviewBudget(project, id); if (!plan) return { taskId: id, planned: false };
+  const live = familyRuns(project, plan.taskId).filter(r => ["ready", "running", "waiting-for-verification"].includes(r.status));
+  need(live.length <= 1, "multiple unresolved native allocations");
+  const current = process.env.NCCGS_SUPERVISED_RUN ?? live[0]?.id ?? null, prior = history(project, plan, current);
+  return { taskId: id, planned: true, rootTaskId: plan.taskId, limits: plan.limits, deadline: plan.deadline, workDeadline: plan.workDeadline,
+    settledSessions: prior.sessions, settledCostUsd: prior.totalUsd, protectedReviewUsd: Math.max(0, plan.limits.finalReviewUsd - prior.reviewUsd),
+    currentAllocation: prior.records.find(a => a.runId === current) ?? null,
+    note: "In-flight actual cost remains unknown; the current allocation is a ceiling, never a worker cost or acceptance result." };
+}

package/.claude/nccgs/tools/review-handoff.mjs

@@ -7,26 +7,60 @@ const canonical = value => Array.isArray(value) ? value.map(canonical) : value &
 const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 const text = value => typeof value === "string" && value.trim().length > 0;
 
-// The reviewer owns this block and the completed dispatch pins its bytes.
-// Coordinator input cannot remove conditions or replace a verdict/findings.
-export function verifyReviewHandoff(project, task, stage, dispatch) {
-  if (task.execution.reviewContractRequired !== true) return; // Preserve legacy policy/hash.
-  need(dispatch.handoff?.artifacts?.some(ref => same(ref, stage.evidence)), "evidence must be the completed reviewer's pinned handoff");
-  const content = fs.readFileSync(verifyArtifact(project, stage.evidence), "utf8");
-  need(/^NCCGS-HANDOFF: COMPLETE\r?$/m.test(content) && !/^NCCGS-HANDOFF: PARTIAL\r?$/m.test(content), "reviewer handoff is incomplete");
+// Structural inspection is also available before the invocation ends. It never
+// records a verdict, changes the document or substitutes for lifecycle gates.
+export function readReviewHandoff(content, task, snapshot, requireComplete = true) {
+  const markers = [...content.matchAll(/^NCCGS-HANDOFF: (COMPLETE|PARTIAL)\r?$/gm)];
+  // Preserve the existing record gate's marker semantics. Draft validation adds
+  // its exact-one-marker diagnostic separately, without rewriting old evidence.
+  const complete = markers.some(m => m[1] === "COMPLETE") && !markers.some(m => m[1] === "PARTIAL");
+  need(!requireComplete || complete, "reviewer handoff is incomplete");
   const blocks = [...content.matchAll(/^```nccgs-review\r?\n([\s\S]*?)^```\s*$/gm)];
   need(blocks.length === 1, "exactly one nccgs-review JSON block is required");
   let value; try { value = JSON.parse(blocks[0][1]); } catch { need(false, "invalid nccgs-review JSON"); }
   const fields = ["schemaVersion", "taskId", "contractHash", "snapshot", "verdict", "criteriaMet", "findings", "conditions"];
   need(value && !Array.isArray(value) && Object.keys(value).length === fields.length && fields.every(key => Object.hasOwn(value, key)), "review JSON fields are incomplete or unsupported");
-  need(value.schemaVersion === 1 && value.taskId === task.id && value.contractHash === task.contractHash && value.snapshot === stage.snapshot, "review JSON is for another task, contract or snapshot");
+  need(value.schemaVersion === 1 && value.taskId === task.id && value.contractHash === task.contractHash && value.snapshot === snapshot, "review JSON is for another task, contract or snapshot");
   need(Array.isArray(value.conditions), "conditions must be an explicit array, empty only when none remain");
   const ids = new Set();
   for (const condition of value.conditions) {
     need(condition && Object.keys(condition).length === 2 && text(condition.id) && text(condition.description) && !ids.has(condition.id), "conditions need unique id and description; coordinator cannot mark them resolved");
     ids.add(condition.id);
   }
+  return { value, complete };
+}
+
+export function validateReviewStructure(value, task) {
+  need(["PASS", "CHANGES_REQUIRED", "BLOCKED"].includes(value.verdict) && typeof value.criteriaMet === "boolean", "invalid verdict or criteriaMet");
+  need(Array.isArray(value.findings) && value.findings.every(f => f &&
+    ["BLOCKER", "HIGH", "MEDIUM", "LOW", "INFO"].includes(f.severity) &&
+    ["OPEN", "RESOLVED", "ACCEPTED"].includes(f.status) && text(f.description)),
+  "findings require severity, status (OPEN, RESOLVED or ACCEPTED) and description");
+  if (task.contract.workflow === "design") {
+    need(value.findings.every(f => ["none", "false-pass", "missing-coverage", "authority-gap"].includes(f.acceptanceImpact)), "design findings must classify acceptanceImpact");
+    need(value.verdict !== "PASS" || !value.findings.some(f => f.acceptanceImpact !== "none" && f.status !== "RESOLVED"), "unresolved design acceptance impacts block PASS");
+  }
+  need(value.verdict !== "PASS" || value.conditions.length === 0, "unresolved review conditions block PASS; complete the checks and obtain a fresh independent review");
+  need(value.verdict !== "PASS" || (value.criteriaMet && !value.findings.some(f => ["BLOCKER", "HIGH"].includes(f.severity) && f.status !== "RESOLVED")), "PASS requires criteriaMet and resolved blocking findings");
+}
+
+// The reviewer owns this block and the completed dispatch pins its bytes.
+// Coordinator input cannot remove conditions or replace a verdict/findings.
+export function verifyReviewHandoff(project, task, stage, dispatch) {
+  if (task.execution.reviewContractRequired !== true) return; // Preserve legacy policy/hash.
+  need(dispatch.handoff?.artifacts?.some(ref => same(ref, stage.evidence)), "evidence must be the completed reviewer's pinned handoff");
+  const content = fs.readFileSync(verifyArtifact(project, stage.evidence), "utf8");
+  const { value } = readReviewHandoff(content, task, stage.snapshot);
   for (const key of ["verdict", "criteriaMet", "findings", "conditions"]) need(same(stage[key], value[key]), `recorded ${key} differs from the reviewer's pinned handoff`);
   need(value.verdict !== "PASS" || value.conditions.length === 0, "unresolved review conditions block PASS; complete the checks and obtain a fresh independent review");
   return value;
 }
+
+export function handoffTemplate(task, dispatch) {
+  const draft = `NCCGS-HANDOFF: PARTIAL\n\nTask: ${task.id}\nDispatch: ${dispatch.id}\n\n`;
+  const fields = "## Outcome\nPending assigned work.\n\n## Changed/produced\nPending.\n\n## Evidence\nPending; do not invent checks or runtime observations.\n\n## Risks and deviations\nPending assessment.\n\n## Decisions needed\nPending assessment.\n\n## Next owner\nCoordinator after this bounded assignment.\n";
+  if (dispatch.kind !== "review") return draft + fields;
+  const value = { schemaVersion: 1, taskId: task.id, contractHash: task.contractHash, snapshot: dispatch.snapshot,
+    verdict: "BLOCKED", criteriaMet: false, findings: [], conditions: [{ id: "REVIEW-PENDING", description: "Independent review has not finished; reviewer must assess and replace this draft." }] };
+  return draft + "```nccgs-review\n" + JSON.stringify(value, null, 2) + "\n```\n\n" + fields;
+}

package/.claude/nccgs/tools/runtime.mjs

@@ -5,6 +5,7 @@ import { snapshot, taskPath } from "./gates.mjs";
 import { persistRuntimeObservation } from "./evidence.mjs";
 import { findDispatch, correlateAgentStart, attachAgent, complete, markUncertain } from "./orchestration.mjs";
 import { nativeCompletion } from "./native-completion.mjs";
+import { captureReturnedHandoff } from "./returned-handoff.mjs";
 
 export function boundTask(project, session) {
   if (process.env.NCCGS_TASK_ID) { taskPath(project, process.env.NCCGS_TASK_ID); return process.env.NCCGS_TASK_ID; }
@@ -16,7 +17,7 @@ export function observe(project, input, event) {
   const { profile } = profilePolicy(project);
   const standalone = resolveExecution(project).name === "standalone";
   const dispatch = standalone ? (event === "agent_start" ? correlateAgentStart(project, input) : findDispatch(project, input)) : null;
-  if (dispatch?.runtime && ["completed", "failed"].includes(dispatch.status)) {
+  if (dispatch?.runtime && (["completed", "failed"].includes(dispatch.status) || dispatch.workStatus === "incomplete-editor")) {
     const saved = json(verifyArtifact(project, dispatch.runtime));
     verifyArtifact(project, saved.observationSource);
     return { ...saved, path: dispatch.runtime.path, duplicate: true };
@@ -33,6 +34,8 @@ export function observe(project, input, event) {
   const modelsUsed = Array.isArray(response.modelsUsed) ? response.modelsUsed.filter(m => typeof m === "string") : observedModel ? [observedModel] : [];
   const capturedAt = new Date().toISOString();
   const sourceSnapshot = taskId ? snapshot(project, task).sha256 : null;
+  const returnedHandoff = event === "agent_result"
+    ? captureReturnedHandoff(project, dispatch, input, completion, sourceSnapshot) : null;
   const id = crypto.randomUUID();
   // Only documented model telemetry is copied. Prompts, arbitrary tool results,
   // credentials, and configuration guesses are never copied into observations.
@@ -43,6 +46,7 @@ export function observe(project, input, event) {
     contractHash: dispatch?.contractHash ?? task?.contractHash ?? null, toolUseId: input.tool_use_id ?? dispatch?.toolUseId ?? null,
     status: event === "agent_result" ? completion.status : event,
     ...(completion ? { nativeCompletion: completion } : {}),
+    ...(returnedHandoff ? { returnedHandoff } : {}),
     totalTokens: response.totalTokens ?? null, costUsd: null,
     provenance: { kind: "provider-log", reference: `Claude Code ${event} hook; session ${input.session_id ?? "unknown"}; tool ${input.tool_use_id ?? dispatch?.toolUseId ?? "unknown"}` } });
   const source = `.nccgs/evidence/runtime/sources/${id}.json`;
@@ -55,7 +59,8 @@ export function observe(project, input, event) {
   if (standalone) Object.assign(observation, { observedProvider: raw.observedProvider, dispatchId: raw.dispatchId,
     contractHash: raw.contractHash, toolUseId: raw.toolUseId, durationMs: raw.durationMs,
     toolUseCount: raw.toolUseCount, totalTokens: raw.totalTokens, costUsd: null, provenance: raw.provenance,
-    ...(completion ? { nativeCompletion: completion } : {}) });
+    ...(completion ? { nativeCompletion: completion } : {}),
+    ...(returnedHandoff ? { returnedHandoff } : {}) });
   const ref = persistRuntimeObservation(project, observation, artifact(project, source));
   if (dispatch) {
     if (raw.agentId) attachAgent(project, dispatch.id, raw.agentId);

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

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { contained, json, verifyArtifact } from "./policy.mjs";
+import { ownerState, pidState } from "./process-lock.mjs";
+
+const need = (value, message) => { if (!value) throw new Error(`Session budget: ${message}`); };
+export const sessionBudgetLock = ".nccgs/runs/supervision.lock";
+export function taskWithin(project, id, ancestor) {
+  const seen = new Set();
+  while (id) {
+    need(/^[\w-]{1,80}$/.test(id) && !seen.has(id), "invalid task ancestry"); seen.add(id);
+    if (id === ancestor) return true;
+    id = json(contained(project, `.nccgs/tasks/${id}.json`)).parentId;
+  }
+  return false;
+}
+export function settledCost(project, run) {
+  if (run.status === "blocked" && run.costCoverage === "complete" && run.invocations.length === 0 && run.cumulativeCostUsd === 0) return 0; // supervisor refused before issuing any native invocation
+  need(run.costCoverage === "complete" && run.invocations.length > 0, "prior session usage is unknown");
+  let cost = 0;
+  for (const invocation of run.invocations) {
+    need(["finished", "recovered"].includes(invocation.status), "prior invocation is live or uncertain");
+    const expected = `.nccgs/runs/${run.id}/${invocation.log}`;
+    need(invocation.evidence?.path === expected, "prior invocation lacks pinned native output");
+    const records = fs.readFileSync(verifyArtifact(project, invocation.evidence), "utf8").trim().split(/\r?\n/);
+    let terminal;
+    for (const line of records) { try { const item = JSON.parse(line); if (item.type === "result") terminal = item; } catch { /* native partial line */ } }
+    need(terminal?.session_id === run.sessionId && Number.isFinite(terminal.total_cost_usd) && terminal.total_cost_usd >= cost, "missing, mismatched or decreasing native session cost");
+    cost = terminal.total_cost_usd; // Session totals are cumulative, never sum resumed totals.
+  }
+  need(cost === run.cumulativeCostUsd, "stored cost differs from native terminal evidence");
+  return cost;
+}
+// This is a conservative session ceiling, not measured worker telemetry. A single
+// project supervisor owns the allowance; all historical sessions remain charged.
+export function sessionBudgetCoverage(project, ancestor, items, limit, current, { running = true } = {}) {
+  need(current && current.project === project && taskWithin(project, current.taskId, ancestor), "current run is outside budget ancestry");
+  need(Number.isFinite(current.budgetUsd) && current.budgetUsd > 0 && Date.now() < current.deadline, "current allowance/deadline is invalid or exhausted");
+  const lock = json(contained(project, sessionBudgetLock));
+  need(lock.runId === current.id && lock.sessionId === current.sessionId && ownerState(lock) === "alive", "exclusive supervisor ownership is missing");
+  if (running) {
+    need(process.env.NCCGS_SUPERVISED_SESSION === current.sessionId && process.env.NCCGS_SUPERVISED_RUN === current.id, "current session identity mismatch");
+    need(current.status === "running" && current.invocations.at(-1)?.status === "running" && pidState(current.invocations.at(-1).pid) === "alive", "current native invocation is not live");
+  }
+  const sessions = new Set([current.sessionId]), previous = [];
+  for (const entry of fs.readdirSync(contained(project, ".nccgs/runs"), { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === current.id) continue;
+    const run = json(contained(project, `.nccgs/runs/${entry.name}/run.json`));
+    need(run.id === entry.name && run.project === project && Array.isArray(run.invocations), "invalid supervised run history");
+    if (!taskWithin(project, run.taskId, ancestor)) continue;
+    need(!sessions.has(run.sessionId), "duplicate session across run records"); sessions.add(run.sessionId);
+    previous.push({ runId: run.id, sessionId: run.sessionId, costUsd: settledCost(project, run) });
+  }
+  need(items.filter(d => d.startedAt).every(d => sessions.has(d.sessionId)), "worker session has no supervised cost coverage");
+  const previousCostUsd = previous.reduce((sum, run) => sum + run.costUsd, 0);
+  const ceilingUsd = previousCostUsd + current.budgetUsd;
+  need(Number.isFinite(limit) && ceilingUsd <= limit + 1e-9, "session allowances plus historical spend exceed aggregate maxCostUsd");
+  need(current.cumulativeCostUsd < current.budgetUsd, "current session allowance exhausted");
+  return { basis: "supervised-session-ceiling", ancestor, limitUsd: limit, previous, previousCostUsd,
+    currentRunId: current.id, currentSessionId: current.sessionId, currentAllowanceUsd: current.budgetUsd,
+    ceilingUsd, deadline: current.deadline, workerCostInferred: false };
+}
+export function activeSessionBudget(project, ancestor, items, limit) {
+  const id = process.env.NCCGS_SUPERVISED_RUN;
+  need(typeof id === "string" && /^[a-f0-9-]{36}$/.test(id), "missing costUsd telemetry; use a covered supervised session or stop");
+  return sessionBudgetCoverage(project, ancestor, items, limit, json(contained(project, `.nccgs/runs/${id}/run.json`)));
+}

package/.claude/nccgs/tools/task-slices.mjs

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import { contained, hash, json, verifyArtifact } from "./policy.mjs";
+import { validateStandaloneRuntime } from "./lifecycle.mjs";
+
+const need = (ok, message) => { if (!ok) throw new Error(`Task slices: ${message}`); };
+const text = (v, max = 800) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+const keys = (v, names) => v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).every(k => names.includes(k));
+const id = v => typeof v === "string" && /^[a-zA-Z][\w-]{0,31}$/.test(v);
+const list = v => Array.isArray(v) && v.every(s => text(s)) && new Set(v).size === v.length;
+const canonical = v => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object"
+  ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])])) : v;
+export const sliceHash = value => hash(JSON.stringify(canonical(value)));
+export const sameSlice = (a, b) => sliceHash(a) === sliceHash(b);
+
+export function validateSlicePlan(project, task, plan) {
+  need(task.schemaVersion === 2 && task.mode === "implement", "requires an existing standalone implementation task");
+  need(keys(plan, ["schemaVersion", "taskId", "contractHash", "sourceSnapshot", "planId", "supersedes", "reason", "integration", "slices"]) && plan.schemaVersion === 1,
+    "unsupported plan fields; slicing cannot supply replacement criteria, routes or budgets");
+  need(plan.taskId === task.id && plan.contractHash === task.contractHash && text(plan.sourceSnapshot), "plan task/contract mismatch");
+  need(id(plan.planId) && (plan.supersedes === null || id(plan.supersedes)) && text(plan.reason), "planId, explicit supersedes (or null) and reason required");
+  need(Array.isArray(plan.slices) && plan.slices.length >= 2 && plan.slices.length <= 12, "use 2-12 bounded slices within the existing budget");
+  const registry = json(contained(project, ".claude/nccgs/studio.json"));
+  const assigned = new Set(), criteria = new Set(task.contract.acceptance.map(c => c.id)), index = new Map();
+  for (const s of plan.slices) {
+    need(keys(s, ["id", "objective", "agent", "dependsOn", "writePaths", "criteria"]) && id(s.id) && !index.has(s.id) && text(s.objective), "slice needs unique id and bounded objective");
+    const role = registry.agents.find(a => a.name === s.agent);
+    need(role && role.modelClass !== "review" && s.agent !== "nccgs-task-scout", "slice must use an implementation role; it cannot lower the task's risk/model route");
+    need(list(s.dependsOn) && list(s.criteria) && list(s.writePaths) && s.writePaths.length >= 1 && s.writePaths.length <= 8, "slice needs unique dependencies, criterion IDs and 1-8 exact file paths");
+    for (const file of s.writePaths) {
+      const full = contained(project, file);
+      need(!/^\.(?:nccgs|claude|git)(?:\/|$)/i.test(file), "slices cannot own governance/evidence files");
+      need(!fs.existsSync(full) || fs.statSync(full).isFile(), "slice writePaths must name exact files, not directory ownership");
+    }
+    need(new Set(s.writePaths.map(p => p.toLowerCase())).size === s.writePaths.length, "duplicate case-aliased file path");
+    for (const criterion of s.criteria) {
+      need(criteria.has(criterion) && !assigned.has(criterion), "every original criterion needs exactly one primary slice owner, without unknown IDs");
+      assigned.add(criterion);
+    }
+    index.set(s.id, s);
+  }
+  need([...criteria].every(c => assigned.has(c)), "plan omits original acceptance criteria, including manual criteria");
+  const ordered = [], visiting = new Set(), visited = new Set();
+  const visit = name => {
+    need(index.has(name), `unknown dependency ${name}`); need(!visiting.has(name), "dependency cycle");
+    if (visited.has(name)) return;
+    visiting.add(name); for (const dep of index.get(name).dependsOn) visit(dep);
+    visiting.delete(name); visited.add(name); ordered.push(index.get(name));
+  };
+  for (const s of plan.slices) visit(s.id);
+  const ancestors = name => new Set(index.get(name).dependsOn.flatMap(d => [d, ...ancestors(d)]));
+  need(index.has(plan.integration) && ancestors(plan.integration).size === plan.slices.length - 1, "integration slice must transitively depend on every other slice");
+  for (let a = 0; a < plan.slices.length; a++) for (const b of plan.slices.slice(a + 1)) {
+    const first = plan.slices[a], overlaps = first.writePaths.some(p => b.writePaths.some(q => p.toLowerCase() === q.toLowerCase()));
+    need(!overlaps || ancestors(first.id).has(b.id) || ancestors(b.id).has(first.id), "shared files require an explicit dependency order");
+  }
+  return ordered;
+}
+
+export function readSlicePlan(project, task, ledger) {
+  const registration = ledger.tasks[task.id]?.slicePlan;
+  if (!registration) return null;
+  const plan = json(verifyArtifact(project, registration.reference));
+  need(plan.planId === registration.planId, "stored plan identity changed");
+  const ordered = validateSlicePlan(project, task, plan);
+  return { plan, ordered, reference: registration.reference };
+}
+
+export function validateSliceRevision(previous, plan, reservations) {
+  need(plan.supersedes === (previous?.plan.planId ?? null), "supersedes must identify the current plan; do not detach its history");
+  if (!previous || previous.plan.contractHash !== plan.contractHash) return;
+  for (const old of previous.plan.slices) {
+    if (!reservations.some(d => d.contractHash === plan.contractHash && d.slice?.id === old.id)) continue;
+    const next = plan.slices.find(s => s.id === old.id);
+    need(next, `attempted slice ${old.id} cannot be removed or renamed; revise its scope explicitly and retain its original attempts`);
+  }
+}
+
+export function sliceProgress(project, task, ledger, stored = readSlicePlan(project, task, ledger)) {
+  if (!stored) return null;
+  const rows = [], byId = new Map();
+  for (const spec of stored.ordered) {
+    const attempts = Object.values(ledger.dispatches).filter(d => d.taskId === task.id && d.slice?.id === spec.id);
+    const latest = attempts.at(-1);
+    const definitionCurrent = latest?.contractHash === task.contractHash && latest.slice.definitionHash === sliceHash(spec);
+    const dependenciesCurrent = spec.dependsOn.every(dep => byId.get(dep)?.state === "DELIVERED" && latest?.slice.dependencies?.[dep] === byId.get(dep).dispatchId);
+    let state = !latest ? "PENDING" : !definitionCurrent || !dependenciesCurrent ? "STALE" : ["reserved", "running", "uncertain"].includes(latest.status) ? "IN_FLIGHT"
+      : latest.status === "completed" ? "DELIVERED" : "PARTIAL";
+    let reason = null;
+    if (state === "DELIVERED") try {
+      const original = json(verifyArtifact(project, latest.slice.plan));
+      const originalSlice = original.slices.find(s => s.id === spec.id);
+      need(originalSlice && sameSlice(originalSlice, spec), "dispatch's pinned slice definition changed");
+      need(latest.handoff?.artifacts?.length === 1 && !latest.handoff.partial?.length && !latest.handoff.missing?.length, "complete handoff missing");
+      for (const ref of latest.handoff.artifacts) verifyArtifact(project, ref);
+      validateStandaloneRuntime(project, task, { runtime: latest.runtime }, task.implementationRoute, latest.completedSnapshot);
+    } catch (error) { state = "BLOCKED"; reason = error.message; }
+    const row = { id: spec.id, state, dispatchId: latest?.id ?? null, attempts: attempts.map(d => ({ dispatchId: d.id, status: d.status })),
+      ready: !["DELIVERED", "IN_FLIGHT"].includes(state) && spec.dependsOn.every(dep => byId.get(dep)?.state === "DELIVERED"), reason };
+    rows.push(row); byId.set(row.id, row);
+  }
+  return { planId: stored.plan.planId, reference: stored.reference, integration: stored.plan.integration, slices: rows,
+    minimumRemainingDispatches: rows.filter(r => !["DELIVERED", "IN_FLIGHT"].includes(r.state)).length,
+    scope: "DELIVERED is a complete native handoff, not acceptance PASS. Full current verification and independent review remain required." };
+}
+
+export function bindSlice(project, task, ledger, request, purpose) {
+  const stored = readSlicePlan(project, task, ledger);
+  if (!stored) { need(request.sliceId === undefined, "register a plan before selecting a slice"); return null; }
+  if (request.kind !== "implementation" || purpose !== "delivery") {
+    need(request.sliceId === undefined, "sliceId is only for implementation delivery; repair/review retain their original workflow"); return null;
+  }
+  const spec = stored.plan.slices.find(s => s.id === request.sliceId);
+  need(spec, "planned delivery requires an explicit sliceId");
+  need(request.agent === spec.agent && sameSlice([...request.writePaths].sort(), [...spec.writePaths].sort()), "dispatch agent/writePaths must exactly match its slice");
+  need(request.handoffPaths?.length === 1, "slice requires one fresh handoff");
+  const progress = sliceProgress(project, task, ledger, stored);
+  const dependencies = Object.fromEntries(spec.dependsOn.map(dep => {
+    const row = progress.slices.find(r => r.id === dep);
+    need(row.state === "DELIVERED", `dependency ${dep} needs a complete current native handoff`); return [dep, row.dispatchId];
+  }));
+  return { id: spec.id, definitionHash: sliceHash(spec), plan: stored.reference, dependencies };
+}
+
+export function slicePromptContext(project, task, dispatch) {
+  if (!dispatch.slice) return "";
+  const plan = json(verifyArtifact(project, dispatch.slice.plan)), spec = plan.slices.find(s => s.id === dispatch.slice.id);
+  need(spec && sliceHash(spec) === dispatch.slice.definitionHash, "pinned slice context changed");
+  const integration = spec.id === plan.integration;
+  const criteria = integration ? task.contract.acceptance : task.contract.acceptance.filter(c => spec.criteria.includes(c.id));
+  const design = task.contract.design ? json(verifyArtifact(project, task.contract.design.document)) : null;
+  const requirements = (design?.requirements ?? []).filter(r => integration || r.criteria.some(id => spec.criteria.includes(id)));
+  return `\nSlice ${spec.id}: ${spec.objective}\nPinned plan: ${dispatch.slice.plan.path}\nDependency dispatches: ${JSON.stringify(dispatch.slice.dependencies)}\n` +
+    `Primary criterion IDs: ${JSON.stringify(spec.criteria)}\nOriginal criteria for this assignment (unchanged): ${JSON.stringify(criteria)}\n` +
+    `Reviewed requirements/rules: ${JSON.stringify(requirements)}\nGlobal constraints: ${JSON.stringify({ assumptions: task.contract.assumptions, decisions: design?.decisions ?? [], outOfScope: design?.outOfScope ?? [] })}\n` +
+    (integration ? "Integrate all preceding slices against the full original contract, required checks, artifacts and manual gates.\n"
+      : "Complete only this bounded slice. Other criteria remain obligations of the same task; this handoff is not task approval.\n") +
+    "Keep the same task, risk/model route and shared budget. The coordinator owns verification; independent review covers the integrated result.\n";
+}
+
+export function nextSliceRequest(task, ledger, stored, progress) {
+  if (Object.values(ledger.dispatches).some(d => d.taskId === task.id && ["reserved", "running", "uncertain"].includes(d.status))) return null;
+  const row = progress.slices.find(r => r.ready); if (!row) return null;
+  const spec = stored.plan.slices.find(s => s.id === row.id), attempt = row.attempts.length + 1;
+  const key = `slice-${stored.reference.sha256.slice(0, 12)}-${spec.id}-${attempt}`;
+  return { kind: "implementation", purpose: "delivery", sliceId: spec.id, agent: spec.agent, requestKey: key,
+    reason: spec.objective, writePaths: spec.writePaths, handoffPaths: [`.nccgs/evidence/analysis/${key}.md`] };
+}

package/.claude/nccgs/tools/task.mjs

@@ -3,10 +3,13 @@ import { fileURLToPath } from "node:url";
 import { json, contained, artifact, atomicJson, profilePolicy, resolveExecution } from "./policy.mjs";
 import { snapshot, initialize, record, check, close, extendReview, taskPath, refreshInputs, migrateEvidence, reclassify, exportExternal, importExternal } from "./gates.mjs";
 import { persistRuntimeObservation } from "./evidence.mjs";
-import { runDispatch } from "./orchestration.mjs";
+import { runDispatch, runRepairEditor, planTaskSlices, taskSliceStatus } from "./orchestration.mjs";
 import { startVerification, waitVerification, jobStatus, listJobs, readJob } from "./verification-jobs.mjs";
 import { assessCriteria } from "./criteria.mjs";
 import { validateDesignCommand, compareDesignCommand } from "./design-readiness.mjs";
+import { validateHandoff, recordReviewHandoff } from "./handoff.mjs";
+import { migrateFrameworkBaseline } from "./lifecycle.mjs";
+import { registerReviewBudget, reviewBudgetStatus } from "./review-budget.mjs";
 
 export function run(args) {
   const command = args[0];
@@ -19,6 +22,9 @@ export function run(args) {
   };
   const project = path.resolve(value("--project") || process.cwd());
   const id = value("--id");
+  if (command === "budget-plan") return registerReviewBudget(project, id, value("--file"));
+  if (command === "budget-status") return reviewBudgetStatus(project, id);
+  if (command === "migrate-framework") return migrateFrameworkBaseline(project, id, value("--decision"));
   if (command === "job-status") return value("--job") ? jobStatus(project, value("--job"), id) : listJobs(project, id);
   if (command === "job-wait") return waitVerification(project, value("--job"), id, Number(value("--timeout-ms") ?? 30000));
   // Diagnostics and failure reports must survive invalid/changed execution policy.
@@ -41,6 +47,37 @@ export function run(args) {
   if (delegated !== null && delegated !== undefined) return delegated;
   if (command === "design-validate") return validateDesignCommand(project, id, value("--file"));
   if (command === "design-compare") return compareDesignCommand(project, id, value("--baseline"), value("--file"));
+  if (["slice-preview", "slice-plan", "slice-status"].includes(command)) {
+    const allowed = new Set(["--id", "--project", ...(command === "slice-status" ? [] : ["--file"])]), seen = new Set();
+    for (let i = 1; i < args.length; i += 2) {
+      const flag = args[i];
+      if (!allowed.has(flag) || seen.has(flag) || !args[i + 1] || args[i + 1].startsWith("--")) throw new Error("Slice commands require unique --id, optional --project, and --file for preview/plan; no forwarded arguments");
+      seen.add(flag);
+    }
+    if (!seen.has("--id") || (command !== "slice-status" && !seen.has("--file"))) throw new Error("Slice command requires --id TASK and --file PLAN for preview/plan");
+    return command === "slice-status" ? taskSliceStatus(project, id) : planTaskSlices(project, id, value("--file"), command === "slice-plan");
+  }
+  if (command === "repair-editor") {
+    const allowed = new Set(["--id", "--dispatch", "--step", "--project"]), seen = new Set();
+    for (let i = 1; i < args.length; i += 2) {
+      const flag = args[i];
+      if (!allowed.has(flag) || seen.has(flag) || !args[i + 1] || args[i + 1].startsWith("--")) throw new Error("repair-editor requires unique --id, --dispatch, --step and optional --project values; no forwarded commands");
+      seen.add(flag);
+    }
+    if (!["--id", "--dispatch", "--step"].every(flag => seen.has(flag))) throw new Error("repair-editor requires --id TASK --dispatch ID --step STEP");
+    return runRepairEditor(project, id, value("--dispatch"), value("--step"));
+  }
+  if (["handoff-validate", "record-review"].includes(command)) {
+    const allowed = new Set(["--id", "--dispatch", "--file", "--project"]), seen = new Set();
+    if (args.includes("--")) throw new Error("Handoff commands do not forward shell commands");
+    for (let i = 1; i < args.length; i += 2) {
+      const flag = args[i];
+      if (!allowed.has(flag) || seen.has(flag) || !args[i + 1] || args[i + 1].startsWith("--")) throw new Error("Handoff commands require unique --id, --dispatch, --file and optional --project values");
+      seen.add(flag);
+    }
+    if (!["--id", "--dispatch", "--file"].every(flag => seen.has(flag))) throw new Error("Handoff command requires --id TASK --dispatch ID --file PATH");
+    return (command === "handoff-validate" ? validateHandoff : recordReviewHandoff)(project, id, value("--dispatch"), value("--file"));
+  }
   if (command === "snapshot") return snapshot(project, id ? json(taskPath(project, id)) : null);
   if (command === "acceptance-status") {
     const task = json(taskPath(project, id));
@@ -96,7 +133,7 @@ export function run(args) {
     atomicJson(contained(project, `.nccgs/runtime/bindings/${session}.json`), { taskId: id });
     return { session, taskId: id };
   }
-  throw new Error("Usage: task init|inspect|snapshot|ref|observe|verify|record|check|close|bind|extend-review|extend-dispatch|refresh-inputs|migrate-evidence|reclassify|report|export-external|import-external --id TASK [--project PATH]; init --intake|--contract|--plan FILE [--mode implement|audit|plan] [--risk FAST|STANDARD|CONTROLLED --reason TEXT]; reclassify --classification FILE; report --outcome success|partial|blocked|failed --summary TEXT; export-external --out FILE; import-external --file FILE; extend-review --reason TEXT --rounds N (external only); extend-dispatch --request FILE (external only); verify --name CHECK -- EXECUTABLE ARGS");
+  throw new Error("Usage: task init|inspect|snapshot|ref|observe|verify|dispatch-prompt|handoff-validate|record-review|repair-editor|slice-preview|slice-plan|slice-status|record|check|close|bind|extend-review|extend-dispatch|refresh-inputs|migrate-evidence|reclassify|report|export-external|import-external --id TASK [--project PATH]; slice-preview|slice-plan --file PLAN; init --intake|--contract|--plan FILE [--mode implement|audit|plan] [--risk FAST|STANDARD|CONTROLLED --reason TEXT]; reclassify --classification FILE; report --outcome success|partial|blocked|failed --summary TEXT; export-external --out FILE; import-external --file FILE; extend-review --reason TEXT --rounds N (external only); extend-dispatch --request FILE (external only); verify --name CHECK -- EXECUTABLE ARGS");
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {