nccgs 1.1.1 → 1.3.0

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

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { json, loadPipeline } from "./policy.mjs";
+
+export function renderAgent(template, route) {
+  const match = template.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error("Missing agent frontmatter");
+  const lines = match[1].split(/\r?\n/).filter(line => !/^(model|effort):/.test(line));
+  if (route.model) lines.push(`model: ${route.model}`);
+  if (route.effort) lines.push(`effort: ${route.effort}`);
+  return `---\n${lines.join("\n")}\n---${template.slice(match[0].length).replace(/\r\n/g, "\n")}`;
+}
+export function generated(project) {
+  const pipeline = loadPipeline(project);
+  const studio = json(path.join(project, ".claude/nccgs/studio.json"));
+  const workflows = json(path.join(project, ".claude/nccgs/workflow-catalog.json"));
+  const outputs = new Map();
+  studio.defaultProfile = pipeline.defaultProfile;
+  studio.modelProfiles = {};
+  studio.effortProfiles = {};
+  studio.sessionProfiles = {};
+  for (const [name, profile] of Object.entries(pipeline.profiles)) {
+    studio.modelProfiles[name] = Object.fromEntries(Object.entries(profile.models).map(([k, v]) => [k, v.model]));
+    studio.effortProfiles[name] = Object.fromEntries(Object.entries(profile.models).map(([k, v]) => [k, v.effort]));
+    if (profile.session) {
+      const route = profile.models[profile.session.class];
+      studio.sessionProfiles[name] = { model: route.model, effortLevel: route.effort };
+    }
+  }
+  const primary = pipeline.profiles[pipeline.defaultProfile];
+  for (const agent of studio.agents) {
+    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,
+    implementationModel: contractProfile.models.standard.model, implementationEffort: contractProfile.models.standard.effort,
+    reviewModel: contractProfile.models.review.model, reviewEffort: contractProfile.models.review.effort } };
+  for (const workflow of workflows.workflows) {
+    delete workflow.ownerByProfile;
+    delete workflow.primaryRolesByProfile;
+    if (contract.astraWorkflows.includes(workflow.name)) workflow.ownerByProfile = { "astra-claude": "Astra" };
+    if (contract.reviewWorkflows.includes(workflow.name)) workflow.primaryRolesByProfile = { "astra-claude": [contract.reviewAgent] };
+  }
+  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 scaffold = path.join(project, "scaffold/.nccgs/project.yaml");
+  if (fs.existsSync(scaffold)) {
+    const text = fs.readFileSync(scaffold, "utf8");
+    const start = text.indexOf("# Apply only when models.profile");
+    const end = text.indexOf("\nworkflow:", start);
+    const reference = "# Profile contracts are resolved from this canonical configuration.\npipeline_policy: .claude/nccgs/pipeline.json\n";
+    outputs.set("scaffold/.nccgs/project.yaml", start >= 0 && end > start ? text.slice(0, start) + reference + text.slice(end) : text);
+  }
+  return outputs;
+}
+export function compile(project, write = false) {
+  const differences = [];
+  for (const [relative, content] of generated(project)) {
+    const file = path.join(project, relative);
+    if (fs.existsSync(file) && fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n") === content.replace(/\r\n/g, "\n")) continue;
+    differences.push(relative);
+    if (write) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, content, "utf8"); }
+  }
+  return differences;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const project = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+  const write = process.argv.includes("--write");
+  const differences = compile(project, write);
+  console.log(`${write ? "Generated" : "Stale generated files"}: ${differences.length}`);
+  for (const file of differences) console.log(file);
+  if (!write && differences.length) process.exitCode = 1;
+}

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

@@ -1,44 +1,84 @@
 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 { renderAgent } from "./compile-policy.mjs";
+import { fingerprintFile } from "./integrity.mjs";
 
-const ownDir = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
-const projectArg = args.indexOf("--project");
-const profileArg = args.indexOf("--profile");
-const skippedPaths = new Set();
-for (let index = 0; index < args.length; index++) {
-  if (args[index] === "--skip-path" && args[index + 1]) skippedPaths.add(args[index + 1].replace(/\\/g, "/"));
+const values = flag => args.flatMap((arg, index) => {
+  if (arg !== flag) return [];
+  if (!args[index + 1] || args[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
+  return [args[index + 1]];
+});
+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);
+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");
+const previous = fs.existsSync(activationFile) ? json(activationFile) : { enabled: [], generated: {} };
+const extras = new Set(previous.enabled);
+for (const role of values("--enable")) {
+  if (!studio.agents.some(a => a.name === role)) throw new Error(`Unknown agent: ${role}`);
+  extras.add(role);
 }
-const project = path.resolve(projectArg >= 0 ? args[projectArg + 1] : path.resolve(ownDir, "../../../.."));
-const catalogPath = path.join(project, ".claude", "nccgs", "studio.json");
-const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
-const policyPath = path.join(project, ".nccgs", "project.yaml");
-const policy = fs.existsSync(policyPath) ? fs.readFileSync(policyPath, "utf8") : "";
-const configured = policy.match(/^models:\s*$[\s\S]*?^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim();
-const profileName = profileArg >= 0 ? args[profileArg + 1] : (configured || catalog.defaultProfile);
-const profile = catalog.modelProfiles[profileName];
-if (!profile) throw new Error(`Unknown model profile '${profileName}'. Expected: ${Object.keys(catalog.modelProfiles).join(", ")}`);
-
-let changed = 0;
-for (const agent of catalog.agents) {
-  const file = path.join(project, ".claude", "agents", `${agent.name}.md`);
-  if (skippedPaths.has(`.claude/agents/${agent.name}.md`)) continue;
-  if (!fs.existsSync(file)) continue;
-  let text = fs.readFileSync(file, "utf8");
-  const model = profile[agent.modelClass];
-  const next = model
-    ? (/^model:/m.test(text) ? text.replace(/^model:.*$/m, `model: ${model}`) : text.replace(/^maxTurns:/m, `model: ${model}\nmaxTurns:`))
-    : text.replace(/^model:.*\r?\n/m, "");
-  if (next !== text) {
-    fs.writeFileSync(file, next, "utf8");
-    changed++;
+for (const role of values("--disable")) {
+  if (pipeline.coreAgents.includes(role)) throw new Error(`Cannot disable core agent: ${role}`);
+  extras.delete(role);
+}
+const active = new Set(profile.activeAgents === "all" ? studio.agents.map(a => a.name) : [...profile.activeAgents, ...extras]);
+const settingsFile = contained(project, ".claude/settings.json");
+const oldSettings = fs.existsSync(settingsFile) ? fs.readFileSync(settingsFile, "utf8") : "";
+const settings = oldSettings ? JSON.parse(oldSettings) : {};
+const writes = [], removes = [], warnings = [], generated = {}, generatedCanonical = {};
+for (const agent of studio.agents) {
+  const relative = `.claude/agents/${agent.name}.md`;
+  const file = contained(project, relative);
+  const old = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+  if (skip.has(relative)) { warnings.push(`Preserved override: ${relative}`); continue; }
+  const template = fs.readFileSync(contained(project, `.claude/nccgs/agent-library/${agent.name}.md`), "utf8");
+  const route = profile.models[agent.modelClass];
+  if (!route) throw new Error(`Missing class: ${agent.modelClass}`);
+  const next = renderAgent(template, route);
+  const shipped = renderAgent(template, pipeline.profiles[pipeline.defaultProfile].models[agent.modelClass]);
+  const known = old === null || old.replace(/\r\n/g, "\n") === shipped || hash(old) === previous.generated?.[relative] || hash(old.replace(/\r\n/g, "\n")) === previous.generatedCanonical?.[relative];
+  if (!known) { warnings.push(`Preserved modified agent: ${relative}`); continue; }
+  if (active.has(agent.name)) {
+    if (old !== next) writes.push([file, next]);
+    generated[relative] = hash(next);
+    generatedCanonical[relative] = hash(next.replace(/\r\n/g, "\n"));
+  } else if (old !== null) removes.push(file);
+}
+// No writes until all inputs and existing settings have passed preflight.
+for (const [file, text] of writes) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, text, "utf8"); }
+for (const file of removes) fs.unlinkSync(file); // contained, known generated files only
+if (profile.session) {
+  const route = profile.models[profile.session.class];
+  const merged = { ...settings, model: route.model, effortLevel: route.effort,
+    modelSettings: { ...settings.modelSettings, [route.model]: { ...settings.modelSettings?.[route.model], effortLevel: route.effort } } };
+  const next = `${JSON.stringify(merged, null, 2)}\n`;
+  if (oldSettings !== next) {
+    if (oldSettings) {
+      const backup = contained(project, `.nccgs/backups/models-${Date.now()}/settings.json`);
+      fs.mkdirSync(path.dirname(backup), { recursive: true }); fs.writeFileSync(backup, oldSettings, "utf8");
+    }
+    fs.mkdirSync(path.dirname(settingsFile), { recursive: true }); fs.writeFileSync(settingsFile, next, "utf8");
   }
 }
-
-if (profileArg >= 0 && policy && /^models:\s*$/m.test(policy)) {
-  const nextPolicy = policy.replace(/(^models:\s*$[\s\S]*?^\s+profile:\s*)[^#\r\n]+/m, `$1${profileName}`);
-  if (nextPolicy !== policy) fs.writeFileSync(policyPath, nextPolicy, "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");
 }
-
-console.log(`NCCGS model profile '${profileName}' configured; ${changed} agent file(s) changed.`);
+atomicJson(activationFile, { schemaVersion: 1, profile: name, enabled: [...extras], generated, generatedCanonical, warnings });
+const installState = contained(project, ".claude/nccgs/install-state.json");
+if (fs.existsSync(installState)) {
+  const state = json(installState);
+  state.modelProfile = name;
+  state.files = state.files.filter(item => !removes.includes(contained(project, item.relative))).map(item =>
+    generated[item.relative] ? { ...item, ...fingerprintFile(contained(project, item.relative)) } : item);
+  atomicJson(installState, state);
+}
+console.log(`NCCGS model profile '${name}' configured; ${writes.length} agent file(s) changed; ${active.size} selected agents.`);
+for (const warning of warnings) console.warn(warning);

package/.claude/nccgs/tools/gates.mjs

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import path from "node:path";
+import { hash, json, contained, artifact, verifyArtifact, atomicJson, loadPipeline } from "./policy.mjs";
+
+export const stages = ["implementation", "review", "report", "astra", "acceptance"];
+function requireValue(condition, message) { if (!condition) throw new Error(message); }
+export function taskPath(project, id) {
+  requireValue(typeof id === "string" && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id), "Invalid task ID");
+  return contained(project, `.nccgs/tasks/${id}.json`);
+}
+export function snapshot(project) {
+  const excluded = new Set(loadPipeline(project).snapshotExcludes);
+  const files = [];
+  function walk(relative = "") {
+    for (const entry of fs.readdirSync(path.join(project, relative), { withFileTypes: true })) {
+      if (!relative && excluded.has(entry.name)) continue;
+      const name = relative ? `${relative}/${entry.name}` : entry.name;
+      const file = contained(project, name);
+      if (entry.isDirectory()) walk(name);
+      else if (entry.isFile()) files.push([name, hash(fs.readFileSync(file))]);
+      else throw new Error(`Unsupported snapshot entry: ${name}`);
+    }
+  }
+  walk();
+  files.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return { sha256: hash(JSON.stringify(files)), files: files.length };
+}
+function initializeUnlocked(project, id, plan, requirements = null) {
+  const file = taskPath(project, id);
+  requireValue(!fs.existsSync(file), `Task already exists: ${id}`);
+  const projectGates = artifact(project, ".nccgs/gates.json");
+  const projectPolicy = artifact(project, ".nccgs/project.yaml");
+  requireValue(json(verifyArtifact(project, projectGates)).policySha256 === projectPolicy.sha256, "Astra must map/review project gates against the current project.yaml hash");
+  const task = { schemaVersion: 1, id, profile: "astra-claude", createdAt: new Date().toISOString(), pipelineHash: hash(JSON.stringify(loadPipeline(project))), plan: artifact(project, plan), projectPolicy, projectGates, requirements: requirements ? artifact(project, requirements) : null, stages: {}, history: [] };
+  atomicJson(file, task);
+  return task;
+}
+function runtime(project, task, stage, expected, snap) {
+  const file = verifyArtifact(project, stage.runtime);
+  const trace = json(file);
+  requireValue(trace.schemaVersion === 1 && trace.origin === "runtime-observation", "Runtime evidence must be an observation, not configuration");
+  requireValue(trace.taskId === task.id && trace.snapshot === snap, "Runtime evidence belongs to another task/snapshot");
+  requireValue(trace.status === "completed" && trace.sessionId && trace.agentId, "Runtime observation is incomplete");
+  requireValue(Date.parse(trace.capturedAt) >= Date.parse(task.createdAt) && Date.parse(trace.capturedAt) <= Date.now(), "Runtime observation has invalid time");
+  const models = trace.modelsUsed?.length ? trace.modelsUsed : [trace.observedModel];
+  const matches = (model) => expected.model === "fable" ? /^claude-fable-\d[\w.-]*$/.test(model ?? "") : model === expected.model;
+  requireValue(matches(trace.observedModel) && models.every(matches), "Observed model/fallback does not satisfy pipeline");
+  requireValue(trace.observedEffort === expected.effort, "Observed effort missing or mismatched; configuration is not proof");
+  requireValue(trace.observationSource, "Runtime observation requires a source artifact");
+  const source = json(verifyArtifact(project, trace.observationSource));
+  requireValue((source.observedModel ?? source.resolvedModel) === trace.observedModel && source.observedEffort === trace.observedEffort, "Observation differs from its raw model/effort source");
+  requireValue(source.taskId === task.id && source.snapshot === snap && source.sessionId === trace.sessionId && source.agentId === trace.agentId, "Observation source identity/snapshot mismatch");
+  requireValue(source.capturedAt === trace.capturedAt && source.status === trace.status, "Observation source time/status mismatch");
+  const sourceModels = source.modelsUsed?.length ? source.modelsUsed : [source.observedModel ?? source.resolvedModel];
+  requireValue(JSON.stringify(sourceModels) === JSON.stringify(models), "Observation dropped or changed source fallback history");
+  return trace;
+}
+export function check(project, task, target = "done") {
+  requireValue(task.schemaVersion === 1 && task.profile === "astra-claude", "Unsupported task record");
+  taskPath(project, task.id);
+  const pipeline = loadPipeline(project);
+  requireValue(task.pipelineHash === hash(JSON.stringify(pipeline)), "Pipeline policy changed; create a new task against the new policy");
+  verifyArtifact(project, task.plan);
+  verifyArtifact(project, task.projectPolicy);
+  const obligations = [task.projectGates, task.requirements].filter(Boolean).map(ref => json(verifyArtifact(project, ref)));
+  requireValue(obligations.length > 0, "Project gate manifest is required");
+  for (const spec of obligations) requireValue(spec.schemaVersion === 1 && [spec.requiredChecks, spec.requiredArtifacts, spec.manualGates].every(Array.isArray), "Invalid gate manifest schema");
+  const snap = snapshot(project).sha256;
+  const end = target === "done" ? 5 : stages.indexOf(target);
+  requireValue(end >= 0, "Invalid gate target");
+  let previous = Date.parse(task.createdAt);
+  let implementer;
+  for (const name of stages.slice(0, end)) {
+    const stage = task.stages[name];
+    requireValue(stage && stage.snapshot === snap, `${name}: missing or stale for current snapshot`);
+    const at = Date.parse(stage.recordedAt);
+    requireValue(Number.isFinite(at) && at >= previous && at <= Date.now(), `${name}: invalid sequence timestamp`);
+    previous = at;
+    if (name === "implementation" || name === "review") {
+      const className = name === "review" ? "review" : "standard";
+      const trace = runtime(project, task, stage, pipeline.profiles[task.profile].models[className], snap);
+      if (name === "implementation") {
+        implementer = `${trace.sessionId}/${trace.agentId}`;
+        requireValue(Array.isArray(stage.checks) && stage.checks.length > 0, "Implementation requires verification evidence");
+        for (const test of stage.checks) {
+          requireValue(test.name && test.status === "PASS", "Verification contains missing/failed/unproven checks");
+          const evidenceFile = verifyArtifact(project, test.evidence);
+          if (test.evidence.path.endsWith(".json")) {
+            const evidence = json(evidenceFile);
+            if (evidence.origin === "verification-command") {
+              requireValue(evidence.taskId === task.id && evidence.name === test.name && evidence.snapshot === snap && evidence.status === "PASS" && evidence.exitCode === 0 && evidence.sourceUnchanged === true, "Recorded verification execution failed or is stale");
+              verifyArtifact(project, evidence.log);
+            }
+          }
+        }
+        for (const spec of obligations) for (const name of spec.requiredChecks) requireValue(stage.checks.some(c => c.name === name && c.status === "PASS"), `Required check missing: ${name}`);
+      } else {
+        requireValue(`${trace.sessionId}/${trace.agentId}` !== implementer, "Review must be independent of implementation");
+        requireValue(Date.parse(trace.capturedAt) >= Date.parse(task.stages.implementation.recordedAt), "Review runtime predates implementation evidence");
+        requireValue(stage.verdict === "PASS" && Array.isArray(stage.findings), "Fable review has not passed");
+        requireValue(!stage.findings.some(f => ["BLOCKER", "HIGH"].includes(f.severity) && f.status !== "RESOLVED"), "Review has open blocking findings");
+        requireValue(stage.criteriaMet === true, "Required acceptance criteria are not proven");
+        verifyArtifact(project, stage.evidence);
+      }
+    } else if (name === "report") {
+      verifyArtifact(project, stage.evidence);
+      for (const spec of obligations) for (const relative of spec.requiredArtifacts) {
+        const ref = stage.artifacts?.find(item => item.path === relative);
+        requireValue(ref, `Required closure artifact missing: ${relative}`);
+        verifyArtifact(project, ref);
+      }
+    }
+    else {
+      const approval = json(verifyArtifact(project, stage.evidence));
+      const actor = name === "astra" ? "Astra" : "Product Owner";
+      const decision = name === "astra" ? "PASS" : "ACCEPTED";
+      requireValue(approval.actor === actor && approval.decision === decision, `${name}: explicit ${actor} decision required`);
+      requireValue(approval.taskId === task.id && approval.snapshot === snap, `${name}: sign-off covers a different snapshot`);
+      requireValue(approval.statement?.trim() && approval.reference?.trim(), `${name}: decision statement and source reference required`);
+      requireValue(Date.parse(approval.decidedAt) >= Date.parse(task.stages[name === "astra" ? "report" : "astra"].recordedAt) && Date.parse(approval.decidedAt) <= at, `${name}: sign-off predates its prerequisite`);
+      if (name === "acceptance") for (const spec of obligations) for (const id of spec.manualGates) requireValue(approval.gates?.some(g => g.id === id && g.decision === "ACCEPTED" && g.reference?.trim()), `Manual gate missing: ${id}`);
+    }
+  }
+  return { allowed: true, target, snapshot: snap, phase: target === "done" ? "DONE" : `READY_FOR_${target.toUpperCase()}` };
+}
+function recordUnlocked(project, id, name, input) {
+  requireValue(stages.includes(name), "Unknown pipeline stage");
+  if (["astra", "acceptance"].includes(name) && (process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT)) throw new Error("External sign-offs must be imported outside the Claude session");
+  const file = taskPath(project, id);
+  const task = json(file);
+  const status = check(project, task, name);
+  requireValue(input.snapshot === status.snapshot, "Submitted evidence does not cover the current snapshot");
+  task.history.push({ recordedAt: new Date().toISOString(), replacedFrom: name, stages: structuredClone(task.stages) });
+  for (const downstream of stages.slice(stages.indexOf(name))) delete task.stages[downstream];
+  task.stages[name] = { ...input, recordedAt: new Date().toISOString() };
+  // Failed reviews can be retained as evidence but never unlock the next stage.
+  const externalDecision = ["astra", "acceptance"].includes(name) ? json(verifyArtifact(project, input.evidence)).decision : null;
+  const negative = (name === "review" && ["CHANGES_REQUIRED", "BLOCKED"].includes(input.verdict)) || ["CHANGES_REQUIRED", "REJECTED"].includes(externalDecision);
+  if (!negative) {
+    const next = stages[stages.indexOf(name) + 1] ?? "done";
+    check(project, task, next);
+  }
+  delete task.closed;
+  atomicJson(file, task);
+  return task;
+}
+function closeUnlocked(project, id) {
+  const file = taskPath(project, id);
+  const task = json(file);
+  const status = check(project, task, "done");
+  task.closed = { snapshot: status.snapshot, at: new Date().toISOString() };
+  atomicJson(file, task);
+  return status;
+}
+
+function mutate(project, id, action) {
+  const lock = `${taskPath(project, id)}.lock`;
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  let descriptor;
+  try { descriptor = fs.openSync(lock, "wx"); }
+  catch (error) { if (error.code === "EEXIST") throw new Error(`Task ${id} is locked by another writer; inspect ${lock} before recovering a crashed writer`); throw error; }
+  try { fs.writeSync(descriptor, JSON.stringify({ pid: process.pid, at: new Date().toISOString() })); return action(); }
+  finally { fs.closeSync(descriptor); fs.unlinkSync(lock); }
+}
+export const initialize = (project, id, plan, requirements = null) => mutate(project, id, () => initializeUnlocked(project, id, plan, requirements));
+export const record = (project, id, stage, evidence) => mutate(project, id, () => recordUnlocked(project, id, stage, evidence));
+export const close = (project, id) => mutate(project, id, () => closeUnlocked(project, id));

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

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const hash = (value) => crypto.createHash("sha256").update(value).digest("hex");
+export const json = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+export function loadPipeline(project) {
+  const pipeline = json(path.join(project, ".claude/nccgs/pipeline.json"));
+  if (pipeline.schemaVersion !== 1) throw new Error("Unsupported pipeline schema");
+  if (!pipeline.profiles?.[pipeline.defaultProfile]) throw new Error("Invalid default profile");
+  if (!Array.isArray(pipeline.coreAgents) || !pipeline.coreAgents.includes(pipeline.contract?.reviewAgent)) throw new Error("Core agents must include the required reviewer");
+  if (JSON.stringify(pipeline.profiles["astra-claude"]?.activeAgents) !== JSON.stringify(pipeline.coreAgents)) throw new Error("Default Astra active agents must match coreAgents");
+  for (const profile of Object.values(pipeline.profiles)) {
+    for (const route of Object.values(profile.models ?? {})) {
+      if (!(route.model === null || typeof route.model === "string") || ![null, "low", "medium", "high", "xhigh", "max"].includes(route.effort)) throw new Error("Invalid model/effort route");
+    }
+    if (profile.session && !profile.models[profile.session.class]) throw new Error("Unknown session model class");
+  }
+  return pipeline;
+}
+export function selectedProfile(project, explicit) {
+  const file = path.join(project, ".nccgs/project.yaml");
+  const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const block = text.match(/^models:[ \t]*\r?\n((?:[ \t]+[^\n]*\n?|\s*\n)*)/m)?.[1] ?? "";
+  const value = block.match(/^\s+profile:\s*([^#\r\n]+)/m)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+  return explicit || value || loadPipeline(project).defaultProfile;
+}
+export function profilePolicy(project, explicit) {
+  const pipeline = loadPipeline(project);
+  const name = selectedProfile(project, explicit);
+  if (!Object.hasOwn(pipeline.profiles, name)) throw new Error(`Unknown model profile '${name}'`);
+  return { pipeline, name, profile: pipeline.profiles[name] };
+}
+export function contained(project, relative) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative) || relative.includes("\\")) throw new Error("Expected a project-relative POSIX path");
+  const resolved = path.resolve(project, relative);
+  const rel = path.relative(path.resolve(project), resolved);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`Path escapes project: ${relative}`);
+  let current = path.resolve(project);
+  for (const part of rel.split(path.sep)) {
+    current = path.join(current, part);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) throw new Error(`Symlink/reparse path not supported: ${relative}`);
+  }
+  return resolved;
+}
+export function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
+  fs.renameSync(temp, file);
+}
+export function artifact(project, relative) {
+  const file = contained(project, relative);
+  if (!fs.statSync(file).isFile()) throw new Error(`Artifact is not a file: ${relative}`);
+  const bytes = fs.readFileSync(file);
+  if (!bytes.length) throw new Error(`Empty artifact: ${relative}`);
+  return { path: relative, sha256: hash(bytes) };
+}
+export function verifyArtifact(project, ref) {
+  if (!ref?.sha256 || artifact(project, ref.path).sha256 !== ref.sha256) throw new Error(`Missing or stale artifact: ${ref?.path ?? "unknown"}`);
+  return contained(project, ref.path);
+}

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

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { json, contained, artifact, atomicJson, profilePolicy } from "./policy.mjs";
+import { snapshot, taskPath } from "./gates.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; }
+  if (!/^[\w-]+$/.test(session ?? "")) return null;
+  const file = contained(project, `.nccgs/runtime/bindings/${session}.json`);
+  return fs.existsSync(file) ? json(file).taskId : null;
+}
+export function observe(project, input, event) {
+  const { profile } = profilePolicy(project);
+  const response = input.tool_response ?? {};
+  const role = input.agent_type || input.tool_input?.subagent_type || null;
+  const studio = json(contained(project, ".claude/nccgs/studio.json"));
+  const agent = studio.agents.find(a => a.name === role);
+  const requested = agent ? profile.models[agent.modelClass] : null;
+  const taskId = boundTask(project, input.session_id);
+  const observedModel = typeof response.resolvedModel === "string" ? response.resolvedModel : null;
+  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).sha256 : null;
+  const id = crypto.randomUUID();
+  // Only documented model telemetry is copied. Prompts, arbitrary tool results,
+  // credentials, and configuration guesses are never copied into observations.
+  const raw = { capturedAt, event, taskId, snapshot: sourceSnapshot, sessionId: input.session_id ?? null, agentId: input.agent_id ?? response.agentId ?? null,
+    resolvedModel: observedModel, modelsUsed, status: response.status ?? (event === "agent_stop" ? "completed" : "unknown"),
+    durationMs: response.totalDurationMs ?? null, toolUseCount: response.totalToolUseCount ?? null };
+  const source = `.nccgs/runtime/sources/${id}.json`;
+  atomicJson(contained(project, source), raw);
+  const observation = { schemaVersion: 1, origin: "runtime-observation", capturedAt,
+    taskId, snapshot: sourceSnapshot, sessionId: raw.sessionId, agentId: raw.agentId,
+    agentType: role, requestedModel: requested?.model ?? null, requestedEffort: requested?.effort ?? null,
+    observedModel, modelsUsed, observedEffort: null, status: raw.status,
+    missing: [observedModel ? null : "model", "effort"].filter(Boolean), observationSource: artifact(project, source) };
+  const relative = `.nccgs/runtime/observations/${id}.json`;
+  atomicJson(contained(project, relative), observation);
+  return { ...observation, path: relative };
+}

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

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { json, contained, artifact, atomicJson, profilePolicy } from "./policy.mjs";
+import { snapshot, initialize, record, check, close, taskPath } from "./gates.mjs";
+
+export function run(args) {
+  const command = args[0];
+  const options = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
+  const value = (flag) => {
+    const index = options.indexOf(flag);
+    if (index < 0) return null;
+    if (!options[index + 1] || options[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
+    return options[index + 1];
+  };
+  const project = path.resolve(value("--project") || process.cwd());
+  const id = value("--id");
+  if (profilePolicy(project).name !== "astra-claude") throw new Error("Task gates require astra-claude profile");
+  if (command === "snapshot") return snapshot(project);
+  if (command === "verify") {
+    json(taskPath(project, id));
+    const name = value("--name");
+    const separator = args.indexOf("--");
+    if (!name || separator < 0 || !args[separator + 1]) throw new Error("verify requires --name CHECK -- EXECUTABLE [ARGS]");
+    const before = snapshot(project).sha256;
+    const result = spawnSync(args[separator + 1], args.slice(separator + 2), { cwd: project, encoding: "utf8", timeout: 300000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+    const after = snapshot(project).sha256;
+    const stamp = crypto.randomUUID();
+    const log = `.nccgs/evidence/check-${stamp}.log`;
+    fs.mkdirSync(path.dirname(contained(project, log)), { recursive: true });
+    fs.writeFileSync(contained(project, log), `${result.stdout ?? ""}\n${result.stderr ?? ""}\n${result.error?.message ?? ""}`, "utf8");
+    const evidencePath = `.nccgs/evidence/check-${stamp}.json`;
+    const status = result.status === 0 && !result.error && before === after ? "PASS" : "FAIL";
+    atomicJson(contained(project, evidencePath), { schemaVersion: 1, origin: "verification-command", taskId: id, name, snapshot: before,
+      finishedAt: new Date().toISOString(), executable: args[separator + 1], arguments: args.slice(separator + 2), exitCode: result.status,
+      sourceUnchanged: before === after, status, log: artifact(project, log) });
+    return { name, status, evidence: artifact(project, evidencePath) };
+  }
+  if (command === "init") return initialize(project, id, value("--plan"), value("--requirements"));
+  if (command === "record") return record(project, id, value("--stage"), json(contained(project, value("--evidence"))));
+  if (command === "check") return check(project, json(taskPath(project, id)), value("--target") || "done");
+  if (command === "close") return close(project, id);
+  if (command === "ref") return artifact(project, value("--file"));
+  if (command === "observe") {
+    const task = json(taskPath(project, id));
+    const source = artifact(project, value("--file"));
+    const raw = json(contained(project, source.path));
+    if (raw.taskId !== id || raw.snapshot !== snapshot(project).sha256) throw new Error("Observation task/snapshot mismatch");
+    if (!["provider-log", "operator-observation"].includes(raw.provenance?.kind) || !raw.provenance.reference?.trim()) throw new Error("Runtime source provenance required");
+    if (!raw.sessionId || !raw.agentId || !raw.observedModel || !raw.observedEffort || raw.status !== "completed") throw new Error("Incomplete observed model/effort/run identity");
+    if (!(Date.parse(raw.capturedAt) >= Date.parse(task.createdAt) && Date.parse(raw.capturedAt) <= Date.now())) throw new Error("Invalid observation time");
+    const relative = `.nccgs/runtime/observations/${crypto.randomUUID()}.json`;
+    atomicJson(contained(project, relative), { schemaVersion: 1, origin: "runtime-observation", taskId: raw.taskId, snapshot: raw.snapshot,
+      sessionId: raw.sessionId, agentId: raw.agentId, capturedAt: raw.capturedAt, observedModel: raw.observedModel,
+      observedEffort: raw.observedEffort, modelsUsed: raw.modelsUsed ?? [raw.observedModel], status: raw.status,
+      provenance: raw.provenance, observationSource: source });
+    return artifact(project, relative);
+  }
+  if (command === "bind") {
+    const session = value("--session");
+    if (!session || !/^[\w-]+$/.test(session)) throw new Error("Invalid session ID");
+    json(taskPath(project, id));
+    atomicJson(contained(project, `.nccgs/runtime/bindings/${session}.json`), { taskId: id });
+    return { session, taskId: id };
+  }
+  throw new Error("Usage: task init|snapshot|ref|observe|verify|record|check|close|bind --id TASK [--project PATH] [--plan FILE] [--stage implementation|review|report|astra|acceptance] [--evidence FILE] [--target report|astra|done]; verify --name CHECK -- EXECUTABLE ARGS");
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = run(process.argv.slice(2));
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status === "FAIL") process.exitCode = 1;
+  }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}