ai-delivery-workflow 0.2.2

package/lib/delivery-state.mjs

@@ -0,0 +1,1220 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const NODE_IDS = new Set([
+  "00-bootstrap",
+  "01-product-discovery",
+  "02-product-definition",
+  "03-architecture-initial",
+  "04-experience-design",
+  "05-architecture-reconcile",
+  "06-platform-preparation",
+  "07-iteration-planning",
+  "08-test-design",
+  "09-development",
+  "10-change-review",
+  "11-candidate-verification",
+  "12-version-closeout",
+  "12-release-preparation",
+  "13-production-approval",
+  "14-production-deployment",
+  "15-production-verification",
+  "16-version-archive",
+  "R00-release-request",
+  "R01-version-selection",
+  "R02-release-eligibility",
+  "R03-material-aggregation",
+  "R04-release-candidate",
+  "R05-release-verification",
+  "R06-release-preparation",
+  "R07-production-approval",
+  "R08-production-deployment",
+  "R09-production-verification",
+  "R10-release-archive",
+]);
+const ARTIFACT_STATUSES = new Set([
+  "draft",
+  "review-draft",
+  "pending-approval",
+  "approved",
+  "valid",
+  "invalid",
+  "blocked",
+  "stale",
+  "superseded",
+  "frozen",
+  "immutable",
+  "passed",
+  "failed",
+  "deployed",
+  "released",
+  "release-ready",
+  "included-in-release",
+  "rolled-back",
+  "archived",
+]);
+const GATE_DECISIONS = new Set(["approved", "rejected", "blocked", "not-required"]);
+const UX_GATE_IDS = new Set(["UX-LF", "UX-VS", "UX-UI"]);
+const SUCCESSFUL_ARTIFACT_STATUSES = new Set([
+  "approved", "valid", "frozen", "immutable", "passed", "deployed", "released",
+  "release-ready", "included-in-release", "archived",
+]);
+const NODE_RULES = new Map([
+  ["00-bootstrap", { scope: "development", prerequisites: [], gates: [] }],
+  ["01-product-discovery", { scope: "development", prerequisites: ["00-bootstrap"], gates: ["GATE-A"] }],
+  ["02-product-definition", { scope: "development", prerequisites: ["01-product-discovery"], gates: ["GATE-B"] }],
+  ["03-architecture-initial", { scope: "development", prerequisites: ["02-product-definition"], gates: [] }],
+  ["04-experience-design", { scope: "development", prerequisites: ["03-architecture-initial"], gates: ["UX-LF", "UX-VS", "UX-UI"] }],
+  ["05-architecture-reconcile", { scope: "development", prerequisites: ["04-experience-design"], gates: [] }],
+  ["06-platform-preparation", { scope: "development", prerequisites: ["03-architecture-initial"], gates: [] }],
+  ["07-iteration-planning", { scope: "development", prerequisites: ["05-architecture-reconcile", "06-platform-preparation"], gates: [] }],
+  ["08-test-design", { scope: "development", prerequisites: ["07-iteration-planning"], gates: [] }],
+  ["09-development", { scope: "development", prerequisites: ["08-test-design"], gates: [] }],
+  ["10-change-review", { scope: "development", prerequisites: ["09-development"], gates: [] }],
+  ["11-candidate-verification", { scope: "development", prerequisites: ["10-change-review"], gates: [] }],
+  ["12-version-closeout", { scope: "development", prerequisites: ["11-candidate-verification"], gates: [] }],
+  ["R00-release-request", { scope: "release", prerequisites: [], gates: [] }],
+  ["R01-version-selection", { scope: "release", prerequisites: ["R00-release-request"], gates: [] }],
+  ["R02-release-eligibility", { scope: "release", prerequisites: ["R01-version-selection"], gates: [] }],
+  ["R03-material-aggregation", { scope: "release", prerequisites: ["R02-release-eligibility"], gates: [] }],
+  ["R04-release-candidate", { scope: "release", prerequisites: ["R03-material-aggregation"], gates: [] }],
+  ["R05-release-verification", { scope: "release", prerequisites: ["R04-release-candidate"], gates: [] }],
+  ["R06-release-preparation", { scope: "release", prerequisites: ["R05-release-verification"], gates: [] }],
+  ["R07-production-approval", { scope: "release", prerequisites: ["R06-release-preparation"], gates: ["PRODUCTION-APPROVAL"] }],
+  ["R08-production-deployment", { scope: "release", prerequisites: ["R07-production-approval"], gates: [] }],
+  ["R09-production-verification", { scope: "release", prerequisites: ["R08-production-deployment"], gates: [] }],
+  ["R10-release-archive", { scope: "release", prerequisites: ["R09-production-verification"], gates: [] }],
+]);
+const WRITABLE_NODE_IDS = new Set(NODE_RULES.keys());
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = new Map();
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      options.set(value, true);
+      continue;
+    }
+    const current = options.get(value);
+    options.set(value, current === undefined ? next : Array.isArray(current) ? [...current, next] : [current, next]);
+    index += 1;
+  }
+  return { positional, options };
+}
+
+function lifecycleDescriptor(command, positional, flags) {
+  if (command === "artifact" && new Set(["register", "status"]).has(positional[1])) {
+    return {
+      kind: "artifact",
+      action: `artifact-${positional[1]}`,
+      subject_id: optionalFlag(flags, "--id") || optionalFlag(flags, "--artifact-id"),
+    };
+  }
+  if (command === "gate" && new Set(["request", "decide"]).has(positional[1])) {
+    return { kind: "gate", action: `gate-${positional[1]}`, subject_id: optionalFlag(flags, "--gate-id") };
+  }
+  if (command !== "transition") return null;
+  const transition = optionalFlag(flags, "--event") || "transition";
+  if (transition.startsWith("node-")) {
+    return { kind: "node", action: transition, subject_id: optionalFlag(flags, "--node") };
+  }
+  if (transition.startsWith("release-")) {
+    return { kind: "release", action: transition, subject_id: optionalFlag(flags, "--release-id") };
+  }
+  return {
+    kind: "version",
+    action: transition,
+    subject_id: optionalFlag(flags, "--iteration-id") || optionalFlag(flags, "--version-id"),
+  };
+}
+
+function dispatchLifecycle(options, files, descriptor, phase, flags, result = null, error = null) {
+  if (!descriptor || typeof options.onLifecycleEvent !== "function") return { decision: "pass" };
+  const revision = optionalFlag(flags, "--expected-revision") || "none";
+  const identity = descriptor.subject_id || "unspecified";
+  const idempotencyKey = `formal-state-${descriptor.kind}-${phase}-${descriptor.action}-${identity}-r${revision}`;
+  const event = {
+    schema_version: 1,
+    event_id: `EVT-${sha256(idempotencyKey).slice(0, 24)}`,
+    idempotency_key: idempotencyKey,
+    event_type: `${descriptor.kind}.${phase}`,
+    occurred_at: (options.now || (() => new Date().toISOString()))(),
+    sequence: revision,
+    scope: {
+      project_root: files.root,
+      subject_id: descriptor.subject_id,
+      action: descriptor.action,
+    },
+    source_ref: { command: descriptor.action, expected_revision: revision },
+    payload: error
+      ? { outcome: "failed", error: error.message }
+      : { outcome: phase === "before" ? "pending" : "succeeded", revision: result?.revision ?? null },
+  };
+  try {
+    return options.onLifecycleEvent(event) || { decision: "pass" };
+  } catch (hookError) {
+    return { decision: "warn", messages: [`Evolution Hook dispatch failed: ${hookError.message}`], evidence_refs: [] };
+  }
+}
+
+function requireYaml(yaml) {
+  if (typeof yaml?.parse !== "function" || typeof yaml?.stringify !== "function") {
+    throw new Error("A YAML parser and stringifier are required.");
+  }
+}
+
+function readYaml(file, yaml, label) {
+  if (!fs.existsSync(file)) throw new Error(`${label} is missing: ${file}`);
+  const value = yaml.parse(fs.readFileSync(file, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must contain a YAML mapping.`);
+  }
+  return value;
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, content, "utf8");
+  fs.renameSync(temporary, file);
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function requiredFlag(flags, name) {
+  const raw = flags.get(name);
+  const value = Array.isArray(raw) ? raw.at(-1) : raw;
+  if (value === undefined || value === true || String(value).trim() === "") {
+    throw new Error(`Missing required option: ${name}`);
+  }
+  return String(value).trim();
+}
+
+function optionalFlag(flags, name) {
+  const raw = flags.get(name);
+  const value = Array.isArray(raw) ? raw.at(-1) : raw;
+  return value === undefined || value === true ? null : String(value).trim();
+}
+
+function repeatedFlag(flags, name) {
+  const raw = flags.get(name);
+  if (raw === undefined || raw === true) return [];
+  return (Array.isArray(raw) ? raw : [raw]).map((value) => String(value).trim()).filter(Boolean);
+}
+
+function artifactStatus(flags) {
+  const status = requiredFlag(flags, "--status").toLowerCase().replaceAll("_", "-");
+  if (!ARTIFACT_STATUSES.has(status)) throw new Error(`Unsupported artifact status: ${status}`);
+  return status;
+}
+
+function expectedRevision(flags) {
+  const raw = requiredFlag(flags, "--expected-revision");
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error("--expected-revision must be a non-negative integer.");
+  }
+  return value;
+}
+
+function withLock(files, stream, action) {
+  fs.mkdirSync(files.lockRoot, { recursive: true });
+  const lockFile = path.join(files.lockRoot, "formal-state.lock");
+  let descriptor;
+  try {
+    descriptor = fs.openSync(lockFile, "wx");
+    fs.writeFileSync(descriptor, `${JSON.stringify({
+      pid: process.pid,
+      created_at: new Date().toISOString(),
+    })}\n`);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error(`Formal state is locked while updating: ${stream}`);
+    throw error;
+  }
+  try {
+    return action();
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    fs.rmSync(lockFile, { force: true });
+  }
+}
+
+function statePaths(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const workflow = path.join(root, ".workflow");
+  const delivery = path.join(root, ".workflow", "delivery");
+  return {
+    root,
+    workflow,
+    delivery,
+    project: path.join(delivery, "project.yaml"),
+    workflowState: path.join(delivery, "workflow-state.yaml"),
+    artifactRegistry: path.join(delivery, "artifact-registry.yaml"),
+    events: path.join(delivery, "state-events.jsonl"),
+    eventShards: path.join(workflow, "control", "events"),
+    lockRoot: path.join(delivery, "runtime", "formal-state-locks"),
+  };
+}
+
+function normalizeScope(value, scopeId = null) {
+  return {
+    scope_id: value?.scope_id ?? scopeId,
+    revision: value?.revision ?? 0,
+    active_nodes: Array.isArray(value?.active_nodes) ? value.active_nodes : [],
+    blocked_nodes: Array.isArray(value?.blocked_nodes) ? value.blocked_nodes : [],
+    completed_nodes: Array.isArray(value?.completed_nodes) ? value.completed_nodes : [],
+    pending_gates: Array.isArray(value?.pending_gates) ? value.pending_gates : [],
+    gate_decisions: Array.isArray(value?.gate_decisions) ? value.gate_decisions : [],
+    node_attempts: value?.node_attempts && typeof value.node_attempts === "object"
+      ? value.node_attempts
+      : {},
+    latest_candidate_id: value?.latest_candidate_id ?? null,
+    latest_release_id: value?.latest_release_id ?? null,
+    updated_at: value?.updated_at ?? "",
+    last_transition: value?.last_transition ?? null,
+  };
+}
+
+function exposeLegacyScopeAliases(state) {
+  const preferred = state.last_transition?.scope === "release"
+    ? state.release_state
+    : state.development_state.scope_id ? state.development_state : state.release_state;
+  const aliases = {
+    iteration_id: preferred.scope_id,
+    active_nodes: preferred.active_nodes,
+    blocked_nodes: preferred.blocked_nodes,
+    completed_nodes: preferred.completed_nodes,
+    pending_gates: preferred.pending_gates,
+    gate_decisions: preferred.gate_decisions,
+    latest_candidate_id: state.development_state.latest_candidate_id
+      || state.release_state.latest_candidate_id,
+    latest_release_id: state.release_state.latest_release_id,
+  };
+  for (const [key, alias] of Object.entries(aliases)) {
+    Object.defineProperty(state, key, { value: alias, enumerable: false, configurable: true });
+  }
+  return state;
+}
+
+function normalizeWorkflowState(value) {
+  const legacyNodes = [
+    ...(Array.isArray(value.active_nodes) ? value.active_nodes : []),
+    ...(Array.isArray(value.blocked_nodes) ? value.blocked_nodes : []),
+    ...(Array.isArray(value.completed_nodes) ? value.completed_nodes : []),
+  ];
+  const legacyRelease = legacyNodes.some((node) => String(node).startsWith("R"))
+    || String(value.iteration_id || "").startsWith("REL-");
+  const legacyScope = normalizeScope({
+    scope_id: value.iteration_id ?? null,
+    revision: value.revision ?? 0,
+    active_nodes: value.active_nodes,
+    blocked_nodes: value.blocked_nodes,
+    completed_nodes: value.completed_nodes,
+    pending_gates: value.pending_gates,
+    gate_decisions: value.gate_decisions,
+    latest_candidate_id: value.latest_candidate_id,
+    latest_release_id: value.latest_release_id,
+    updated_at: value.updated_at,
+    last_transition: value.last_transition,
+  });
+  const state = {
+    schema_version: value.schema_version ?? 1,
+    revision: value.revision ?? 0,
+    project_id: value.project_id ?? null,
+    development_state: normalizeScope(
+      value.development_state || (!legacyRelease ? legacyScope : null),
+      !legacyRelease ? value.iteration_id ?? null : null,
+    ),
+    release_state: normalizeScope(
+      value.release_state || (legacyRelease ? legacyScope : null),
+      legacyRelease ? value.iteration_id ?? null : null,
+    ),
+    latest_line_version_id: value.latest_line_version_id ?? null,
+    production_version_id: value.production_version_id ?? null,
+    production_release_id: value.production_release_id ?? null,
+    updated_at: value.updated_at ?? "",
+    last_transition: value.last_transition ?? null,
+  };
+  return exposeLegacyScopeAliases(state);
+}
+
+function scopeNameForNode(node) {
+  return NODE_RULES.get(node)?.scope || (String(node).startsWith("R") ? "release" : "development");
+}
+
+function scopeState(state, scopeName) {
+  return scopeName === "release" ? state.release_state : state.development_state;
+}
+
+function normalizeArtifactRegistry(value) {
+  return {
+    ...value,
+    schema_version: value.schema_version ?? 1,
+    revision: value.revision ?? 0,
+    artifacts: Array.isArray(value.artifacts) ? value.artifacts : [],
+  };
+}
+
+function appendEvent(files, event) {
+  const existing = fs.existsSync(files.events) ? fs.readFileSync(files.events, "utf8") : "";
+  const prefix = existing && !existing.endsWith("\n") ? `${existing}\n` : existing;
+  atomicWrite(files.events, `${prefix}${JSON.stringify(event)}\n`);
+}
+
+function writeStream(files, stream, file, value, event, options) {
+  const serialized = options.yaml.stringify(value);
+  const eventId = crypto.randomUUID();
+  const eventRecord = {
+    event_id: eventId,
+    stream,
+    revision: value.revision,
+    occurred_at: event.occurred_at,
+    ...event,
+    after_checksum: sha256(serialized),
+  };
+  const shardFile = path.join(files.eventShards, stream, `${String(value.revision).padStart(6, "0")}-${eventId}.yaml`);
+  atomicWrite(shardFile, options.yaml.stringify({ ...eventRecord, after_value: value }));
+  atomicWrite(file, serialized);
+  appendEvent(files, eventRecord);
+}
+
+function readEventShards(files, options) {
+  if (!fs.existsSync(files.eventShards)) return [];
+  const records = [];
+  for (const stream of fs.readdirSync(files.eventShards).sort()) {
+    const directory = path.join(files.eventShards, stream);
+    if (!fs.statSync(directory).isDirectory()) continue;
+    for (const name of fs.readdirSync(directory).filter((item) => /\.ya?ml$/i.test(item)).sort()) {
+      const record = readYaml(path.join(directory, name), options.yaml, `formal event shard ${stream}/${name}`);
+      if (record.stream !== stream || !Number.isInteger(record.revision) || !record.after_value) {
+        throw new Error(`Formal event shard is invalid: ${stream}/${name}`);
+      }
+      const checksum = sha256(options.yaml.stringify(record.after_value));
+      if (checksum !== record.after_checksum) throw new Error(`Formal event shard checksum mismatch: ${stream}/${name}`);
+      records.push(record);
+    }
+  }
+  return records.sort((left, right) =>
+    String(left.occurred_at).localeCompare(String(right.occurred_at))
+    || left.stream.localeCompare(right.stream)
+    || left.revision - right.revision);
+}
+
+function rebuildFormalViews(files, options) {
+  return withLock(files, "formal-state-rebuild", () => {
+    const records = readEventShards(files, options);
+    if (!records.length) {
+      return { command: "rebuild", rebuilt: false, event_shard_count: 0, message: "No formal event shards exist; legacy views were left unchanged." };
+    }
+    const latest = new Map();
+    for (const record of records) {
+      const current = latest.get(record.stream);
+      if (!current || record.revision > current.revision) latest.set(record.stream, record);
+    }
+    const workflow = latest.get("workflow-state");
+    const registry = latest.get("artifact-registry");
+    if (workflow) atomicWrite(files.workflowState, options.yaml.stringify(workflow.after_value));
+    if (registry) atomicWrite(files.artifactRegistry, options.yaml.stringify(registry.after_value));
+    const index = records.map(({ after_value: ignored, ...record }) => JSON.stringify(record)).join("\n");
+    atomicWrite(files.events, `${index}\n`);
+    return {
+      command: "rebuild",
+      rebuilt: true,
+      event_shard_count: records.length,
+      workflow_revision: workflow?.revision ?? 0,
+      artifact_registry_revision: registry?.revision ?? 0,
+    };
+  });
+}
+
+function registerArtifact(files, flags, options) {
+  const expected = expectedRevision(flags);
+  return withLock(files, "artifact-registry", () => {
+    const project = readYaml(files.project, options.yaml, "project.yaml");
+    const workflowState = normalizeWorkflowState(
+      readYaml(files.workflowState, options.yaml, "workflow-state.yaml"),
+    );
+    const registry = normalizeArtifactRegistry(
+      readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"),
+    );
+    if (registry.revision !== expected) {
+      throw new Error(`Artifact registry revision conflict: expected ${expected}, actual ${registry.revision}.`);
+    }
+
+    const artifactId = requiredFlag(flags, "--id");
+    if (registry.artifacts.some((item) => (item.artifact_id || item.id) === artifactId)) {
+      throw new Error(`Artifact ID is already registered: ${artifactId}`);
+    }
+    const artifactPath = requiredFlag(flags, "--path").replaceAll("\\", "/");
+    if (!artifactPath.startsWith(".workflow/")) {
+      throw new Error("Artifact path must be project-relative and start with .workflow/.");
+    }
+    if (registry.artifacts.some((item) =>
+      typeof item.path === "string" && item.path.replaceAll("\\", "/") === artifactPath)) {
+      throw new Error(`Artifact path is already registered: ${artifactPath}`);
+    }
+    const absolute = path.resolve(files.root, artifactPath);
+    if (!isInside(absolute, files.workflow) || !fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+      throw new Error(`Artifact file does not exist inside .workflow/: ${artifactPath}`);
+    }
+    if (!isInside(fs.realpathSync(absolute), fs.realpathSync(files.workflow))) {
+      throw new Error(`Artifact path resolves outside .workflow/: ${artifactPath}`);
+    }
+
+    const timestamp = (options.now || (() => new Date().toISOString()))();
+    const content = fs.readFileSync(absolute);
+    const supersedes = optionalFlag(flags, "--supersedes");
+    let predecessor = null;
+    if (supersedes) {
+      predecessor = registry.artifacts.find((item) => (item.artifact_id || item.id) === supersedes);
+      if (!predecessor) throw new Error(`Superseded artifact is not registered: ${supersedes}`);
+      if (predecessor.status === "superseded") {
+        throw new Error(`Artifact is already superseded: ${supersedes}`);
+      }
+    }
+    const node = requiredFlag(flags, "--node");
+    if (!NODE_IDS.has(node)) throw new Error(`Unknown workflow node: ${node}`);
+    const artifactScope = scopeNameForNode(node);
+    const artifactScopeState = scopeState(workflowState, artifactScope);
+    const artifact = {
+      artifact_id: artifactId,
+      artifact_type: optionalFlag(flags, "--artifact-type"),
+      path: artifactPath,
+      node,
+      scope: artifactScope,
+      iteration_id: artifactScopeState.scope_id || null,
+      status: artifactStatus(flags),
+      version: optionalFlag(flags, "--version"),
+      producer_skill: optionalFlag(flags, "--producer-skill"),
+      supersedes,
+      checksum_algorithm: "sha256",
+      checksum: sha256(content),
+      registered_at: timestamp,
+    };
+    if (predecessor) {
+      const previous = predecessor.status || "unknown";
+      predecessor.status = "superseded";
+      predecessor.superseded_by = artifactId;
+      predecessor.status_history = [
+        ...(Array.isArray(predecessor.status_history) ? predecessor.status_history : []),
+        {
+          from: previous,
+          to: "superseded",
+          evidence: [artifactId],
+          changed_at: timestamp,
+        },
+      ];
+    }
+    registry.schema_version = 1;
+    registry.project_id = registry.project_id || project.project_id || workflowState.project_id || null;
+    registry.iteration_id = workflowState.development_state.scope_id || registry.iteration_id || null;
+    registry.revision += 1;
+    registry.updated_at = timestamp;
+    registry.artifacts = [...registry.artifacts, artifact];
+    writeStream(files, "artifact-registry", files.artifactRegistry, registry, {
+      type: "artifact-registered",
+      occurred_at: timestamp,
+      artifact_id: artifactId,
+      path: artifactPath,
+    }, options);
+    return {
+      command: "artifact register",
+      project_id: registry.project_id,
+      iteration_id: registry.iteration_id,
+      revision: registry.revision,
+      artifact,
+      artifact_registry: registry,
+    };
+  });
+}
+
+function changeArtifactStatus(files, flags, options) {
+  const expected = expectedRevision(flags);
+  return withLock(files, "artifact-registry", () => {
+    const registry = normalizeArtifactRegistry(
+      readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"),
+    );
+    if (registry.revision !== expected) {
+      throw new Error(`Artifact registry revision conflict: expected ${expected}, actual ${registry.revision}.`);
+    }
+    const artifactId = requiredFlag(flags, "--id");
+    const artifact = registry.artifacts.find((item) => (item.artifact_id || item.id) === artifactId);
+    if (!artifact) throw new Error(`Artifact is not registered: ${artifactId}`);
+    const status = artifactStatus(flags);
+    const evidence = repeatedFlag(flags, "--evidence");
+    if (!evidence.length) throw new Error("artifact status requires at least one --evidence reference.");
+    if (artifact.status === status) throw new Error(`Artifact already has status ${status}: ${artifactId}`);
+    if (artifact.status === "superseded" || artifact.status === "archived") {
+      throw new Error(`Terminal artifact status cannot change: ${artifact.status}`);
+    }
+
+    const timestamp = (options.now || (() => new Date().toISOString()))();
+    const previous = artifact.status || "unknown";
+    artifact.status = status;
+    artifact.status_history = [
+      ...(Array.isArray(artifact.status_history) ? artifact.status_history : []),
+      { from: previous, to: status, evidence, changed_at: timestamp },
+    ];
+    registry.schema_version = 1;
+    registry.revision += 1;
+    registry.updated_at = timestamp;
+    writeStream(files, "artifact-registry", files.artifactRegistry, registry, {
+      type: "artifact-status-changed",
+      occurred_at: timestamp,
+      artifact_id: artifactId,
+      from: previous,
+      to: status,
+      evidence,
+    }, options);
+    return {
+      command: "artifact status",
+      revision: registry.revision,
+      artifact,
+      artifact_registry: registry,
+    };
+  });
+}
+
+function allowedCompletionStatuses(node) {
+  if (node === "12-version-closeout") return new Set(["release-ready"]);
+  if (node === "R08-production-deployment") return new Set(["deployed"]);
+  if (node === "R09-production-verification") return new Set(["passed"]);
+  if (node === "R10-release-archive") return new Set(["released", "archived"]);
+  return SUCCESSFUL_ARTIFACT_STATUSES;
+}
+
+function satisfiesMandatoryGate(node, decision) {
+  return decision?.decision === "approved"
+    || (node === "04-experience-design" && decision?.decision === "not-required");
+}
+
+function isProductTerminalEvidence(artifact) {
+  return artifact?.node === "02-product-definition"
+    && /terminal/i.test(artifact.artifact_type || "")
+    && SUCCESSFUL_ARTIFACT_STATUSES.has(artifact.status);
+}
+
+function persistScopeMutation(files, state, scope, timestamp, transition, eventRecord, options) {
+  state.schema_version = 2;
+  state.revision += 1;
+  scope.revision += 1;
+  scope.updated_at = timestamp;
+  state.updated_at = timestamp;
+  scope.last_transition = transition;
+  state.last_transition = transition;
+  writeStream(files, "workflow-state", files.workflowState, state, eventRecord, options);
+  exposeLegacyScopeAliases(state);
+}
+
+function transitionWorkflow(files, flags, options) {
+  const expected = expectedRevision(flags);
+  return withLock(files, "workflow-state", () => {
+    const state = normalizeWorkflowState(readYaml(files.workflowState, options.yaml, "workflow-state.yaml"));
+    if (state.revision !== expected) {
+      throw new Error(`Workflow state revision conflict: expected ${expected}, actual ${state.revision}.`);
+    }
+    const event = requiredFlag(flags, "--event");
+    const iterationId = requiredFlag(flags, "--iteration-id");
+    const evidence = repeatedFlag(flags, "--evidence");
+    const timestamp = (options.now || (() => new Date().toISOString()))();
+
+    const persist = (scopeName, details = {}) => {
+      const scope = scopeState(state, scopeName);
+      const transition = {
+        event,
+        scope: scopeName,
+        iteration_id: iterationId,
+        evidence,
+        ...details,
+        occurred_at: timestamp,
+      };
+      persistScopeMutation(files, state, scope, timestamp, transition, {
+        type: event,
+        occurred_at: timestamp,
+        scope: scopeName,
+        iteration_id: iterationId,
+        evidence,
+        ...details,
+      }, options);
+      return { command: "transition", event, revision: state.revision, scope_revision: scope.revision, workflow_state: state };
+    };
+
+    if (event === "iteration-started" || event === "release-started") {
+      const scopeName = event === "release-started" ? "release" : "development";
+      const current = scopeState(state, scopeName);
+      if (current.scope_id === iterationId) throw new Error(`${scopeName} scope is already current: ${iterationId}`);
+      if (current.active_nodes.length || current.blocked_nodes.length || current.pending_gates.length) {
+        throw new Error(`${event} requires its ${scopeName} scope to have no active nodes, blocked nodes, or pending gates.`);
+      }
+      if (event === "iteration-started") registeredEvidence(files, evidence, options);
+      const nextRevision = current.revision;
+      state[scopeName === "release" ? "release_state" : "development_state"] = normalizeScope({
+        scope_id: iterationId,
+        revision: nextRevision,
+      });
+      const project = readYaml(files.project, options.yaml, "project.yaml");
+      if (scopeName === "development") project.current_iteration_id = iterationId;
+      else project.current_release_id = iterationId;
+      atomicWrite(files.project, options.yaml.stringify(project));
+      return persist(scopeName);
+    }
+
+    if (event === "candidate-selected" || event === "release-selected") {
+      const artifactId = requiredFlag(flags, "--artifact-id");
+      const registry = normalizeArtifactRegistry(readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"));
+      const artifact = registry.artifacts.find((item) => (item.artifact_id || item.id) === artifactId);
+      if (!artifact) throw new Error(`Selected artifact is not registered: ${artifactId}`);
+      const expectedNodes = event === "candidate-selected"
+        ? new Set(["09-development", "R04-release-candidate"])
+        : new Set(["12-release-preparation", "R06-release-preparation"]);
+      if (!expectedNodes.has(artifact.node)) {
+        throw new Error(`Selected artifact ${artifactId} belongs to ${artifact.node}, not ${[...expectedNodes].join(" or ")}.`);
+      }
+      const scopeName = event === "release-selected" ? "release" : scopeNameForNode(artifact.node);
+      const scope = scopeState(state, scopeName);
+      if (!scope.scope_id) throw new Error(`${scopeName} scope must be started before ${event}.`);
+      if (scope.scope_id !== iterationId) {
+        throw new Error(`Iteration mismatch for ${scopeName} scope: state is ${scope.scope_id}, command is ${iterationId}.`);
+      }
+      if (artifact.iteration_id && artifact.iteration_id !== iterationId
+        && !(event === "release-selected" && artifact.node === "12-release-preparation")) {
+        throw new Error(`Selected artifact ${artifactId} belongs to iteration ${artifact.iteration_id}, not ${iterationId}.`);
+      }
+      const allowed = event === "candidate-selected" ? new Set(["immutable"]) : new Set(["immutable", "approved"]);
+      if (!allowed.has(artifact.status)) throw new Error(`Selected artifact ${artifactId} is not immutable or approved.`);
+      if (event === "release-selected") scope.latest_release_id = artifactId;
+      else scope.latest_candidate_id = artifactId;
+      return persist(scopeName, { artifact_id: artifactId, evidence: [artifactId] });
+    }
+
+    if (event === "version-closed" || event === "release-archived") {
+      const scopeName = event === "release-archived" ? "release" : "development";
+      const scope = scopeState(state, scopeName);
+      if (scope.scope_id !== iterationId) {
+        throw new Error(`Iteration mismatch for ${scopeName} scope: state is ${scope.scope_id}, command is ${iterationId}.`);
+      }
+      const artifactId = requiredFlag(flags, "--artifact-id");
+      const registry = normalizeArtifactRegistry(readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"));
+      const artifact = registry.artifacts.find((item) => (item.artifact_id || item.id) === artifactId);
+      if (!artifact) throw new Error(`Milestone artifact is not registered: ${artifactId}`);
+      const expectedNode = event === "version-closed" ? "12-version-closeout" : "R10-release-archive";
+      const expectedStatus = event === "version-closed" ? "release-ready" : "released";
+      if (!scope.completed_nodes.includes(expectedNode)) throw new Error(`${event} requires ${expectedNode} to be completed.`);
+      if (artifact.node !== expectedNode) throw new Error(`Milestone artifact ${artifactId} belongs to ${artifact.node}, not ${expectedNode}.`);
+      if (artifact.status !== expectedStatus) {
+        throw new Error(`Milestone artifact ${artifactId} must have status ${expectedStatus}, not ${artifact.status || "missing"}.`);
+      }
+      if (artifact.iteration_id && artifact.iteration_id !== iterationId) {
+        throw new Error(`Milestone artifact ${artifactId} belongs to iteration ${artifact.iteration_id}, not ${iterationId}.`);
+      }
+      if (event === "version-closed") {
+        if (state.latest_line_version_id === iterationId) throw new Error(`Version is already closed on the cumulative line: ${iterationId}`);
+        state.latest_line_version_id = iterationId;
+      } else {
+        if (state.production_release_id === iterationId) throw new Error(`Release is already archived as production: ${iterationId}`);
+        state.production_version_id = requiredFlag(flags, "--production-version-id");
+        state.production_release_id = iterationId;
+      }
+      return persist(scopeName, {
+        artifact_id: artifactId,
+        evidence: [artifactId],
+        ...(event === "release-archived" ? { production_version_id: state.production_version_id } : {}),
+      });
+    }
+
+    const node = requiredFlag(flags, "--node");
+    if (!WRITABLE_NODE_IDS.has(node)) {
+      if (NODE_IDS.has(node)) throw new Error(`Legacy workflow node is read-only: ${node}`);
+      throw new Error(`Unknown workflow node: ${node}`);
+    }
+    const scopeName = scopeNameForNode(node);
+    const scope = scopeState(state, scopeName);
+    if (!scope.scope_id) throw new Error(`${scopeName} scope must be started before node ${node}.`);
+    if (scope.scope_id !== iterationId) {
+      throw new Error(`Iteration mismatch for ${scopeName} scope: state is ${scope.scope_id}, command is ${iterationId}.`);
+    }
+    let reason = null;
+
+    if (event === "node-started") {
+      if (scope.blocked_nodes.includes(node)) throw new Error(`Blocked node must be unblocked before start: ${node}`);
+      if (scope.active_nodes.includes(node)) throw new Error(`Node is already active: ${node}`);
+      if (scope.completed_nodes.includes(node)) {
+        reason = requiredFlag(flags, "--reason");
+        scope.completed_nodes = scope.completed_nodes.filter((item) => item !== node);
+      }
+      const evidenceArtifacts = evidence.length ? registeredEvidence(files, evidence, options) : [];
+      if (node === "R00-release-request") {
+        const requestArtifact = evidenceArtifacts.find((artifact) =>
+          artifact.node === node
+          && artifact.artifact_type === "release-request"
+          && SUCCESSFUL_ARTIFACT_STATUSES.has(artifact.status));
+        if (!requestArtifact) {
+          throw new Error("R00-release-request requires successful explicit user request evidence with artifact type release-request.");
+        }
+      }
+      const prerequisites = NODE_RULES.get(node)?.prerequisites || [];
+      const missing = prerequisites.filter((prerequisite) =>
+        !scope.completed_nodes.includes(prerequisite)
+        && !evidenceArtifacts.some((artifact) => artifact.node === prerequisite
+          && SUCCESSFUL_ARTIFACT_STATUSES.has(artifact.status)));
+      if (missing.length) throw new Error(`Node prerequisite is not satisfied: ${missing.join(", ")}.`);
+      scope.active_nodes = [...scope.active_nodes, node];
+      scope.node_attempts[node] = Number(scope.node_attempts[node] || 0) + 1;
+    } else if (event === "node-completed") {
+      if (!scope.active_nodes.includes(node)) throw new Error(`Node is not active: ${node}`);
+      if (!evidence.length) throw new Error("node-completed requires at least one --evidence artifact ID.");
+      const artifacts = registeredEvidence(files, evidence, options, node);
+      const allowed = allowedCompletionStatuses(node);
+      const unsuccessful = artifacts.find((artifact) => !allowed.has(artifact.status));
+      if (unsuccessful) {
+        throw new Error(`Completion evidence ${unsuccessful.artifact_id || unsuccessful.id} has unsuccessful status ${unsuccessful.status}.`);
+      }
+      const attempt = Number(scope.node_attempts[node] || 1);
+      const pendingForNode = scope.pending_gates.filter((gate) =>
+        typeof gate === "string" || (gate?.node === node && Number(gate.node_attempt || attempt) === attempt));
+      if (pendingForNode.length) throw new Error(`Node has pending gates: ${node}`);
+      const latestGateDecisions = new Map();
+      for (const decision of scope.gate_decisions) {
+        if (decision?.node === node
+          && (!decision.iteration_id || decision.iteration_id === iterationId)
+          && Number(decision.node_attempt || attempt) === attempt
+          && decision.gate_id) latestGateDecisions.set(decision.gate_id, decision);
+      }
+      const nonApproving = [...latestGateDecisions.values()].find((decision) =>
+        !new Set(["approved", "not-required"]).has(decision.decision));
+      if (nonApproving) {
+        throw new Error(`Node has a non-approving Gate decision ${nonApproving.gate_id}: ${nonApproving.decision}.`);
+      }
+      const missingGates = (NODE_RULES.get(node)?.gates || []).filter((gateId) => {
+        const decision = latestGateDecisions.get(gateId);
+        return !satisfiesMandatoryGate(node, decision);
+      });
+      if (missingGates.length) throw new Error(`Node is missing mandatory Gate decisions: ${missingGates.join(", ")}.`);
+      scope.active_nodes = scope.active_nodes.filter((item) => item !== node);
+      scope.completed_nodes = [...new Set([...scope.completed_nodes, node])];
+    } else if (event === "node-blocked") {
+      reason = requiredFlag(flags, "--reason");
+      if (!scope.active_nodes.includes(node)) throw new Error(`Node is not active: ${node}`);
+      scope.active_nodes = scope.active_nodes.filter((item) => item !== node);
+      scope.blocked_nodes = [...new Set([...scope.blocked_nodes, node])];
+    } else if (event === "node-unblocked") {
+      reason = requiredFlag(flags, "--reason");
+      if (!scope.blocked_nodes.includes(node)) throw new Error(`Node is not blocked: ${node}`);
+      scope.blocked_nodes = scope.blocked_nodes.filter((item) => item !== node);
+      scope.active_nodes = [...new Set([...scope.active_nodes, node])];
+    } else {
+      throw new Error(
+        "transition --event must be iteration-started, release-started, node-started, node-completed, "
+        + "node-blocked, node-unblocked, candidate-selected, release-selected, version-closed, or release-archived.",
+      );
+    }
+    return persist(scopeName, { node, ...(reason ? { reason } : {}) });
+  });
+}
+
+function registeredEvidence(files, evidence, options, node = null) {
+  if (!evidence.length) throw new Error("At least one --evidence artifact ID is required.");
+  const registry = normalizeArtifactRegistry(
+    readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"),
+  );
+  return evidence.map((artifactId) => {
+    const artifact = registry.artifacts.find((item) => (item.artifact_id || item.id) === artifactId);
+    if (!artifact) throw new Error(`Evidence artifact is not registered: ${artifactId}`);
+    if (node && artifact.node && artifact.node !== node) {
+      throw new Error(`Evidence ${artifactId} belongs to ${artifact.node}, not ${node}.`);
+    }
+    return artifact;
+  });
+}
+
+function requestGate(files, flags, options) {
+  const expected = expectedRevision(flags);
+  return withLock(files, "workflow-state", () => {
+    const state = normalizeWorkflowState(
+      readYaml(files.workflowState, options.yaml, "workflow-state.yaml"),
+    );
+    if (state.revision !== expected) {
+      throw new Error(`Workflow state revision conflict: expected ${expected}, actual ${state.revision}.`);
+    }
+    const gateId = requiredFlag(flags, "--gate-id");
+    const iterationId = requiredFlag(flags, "--iteration-id");
+    const node = requiredFlag(flags, "--node");
+    if (!WRITABLE_NODE_IDS.has(node)) {
+      if (NODE_IDS.has(node)) throw new Error(`Legacy workflow node is read-only: ${node}`);
+      throw new Error(`Unknown workflow node: ${node}`);
+    }
+    const scopeName = scopeNameForNode(node);
+    const scope = scopeState(state, scopeName);
+    if (scope.scope_id !== iterationId) {
+      throw new Error(`Iteration mismatch for ${scopeName} scope: state is ${scope.scope_id}, command is ${iterationId}.`);
+    }
+    if (!scope.active_nodes.includes(node)) throw new Error(`Gate node is not active: ${node}`);
+    const pending = scope.pending_gates.map((gate) =>
+      typeof gate === "string" ? { gate_id: gate, node: null } : gate);
+    if (pending.some((gate) => gate?.gate_id === gateId)) throw new Error(`Gate is already pending: ${gateId}`);
+    const evidence = repeatedFlag(flags, "--evidence");
+    registeredEvidence(files, evidence, options, node);
+
+    const timestamp = (options.now || (() => new Date().toISOString()))();
+    const request = {
+      gate_id: gateId,
+      node,
+      iteration_id: iterationId,
+      scope: scopeName,
+      node_attempt: Number(scope.node_attempts[node] || 1),
+      evidence,
+      requested_at: timestamp,
+    };
+    scope.pending_gates = [...pending, request];
+    const transition = {
+      event: "gate-requested",
+      scope: scopeName,
+      gate_id: gateId,
+      node,
+      iteration_id: iterationId,
+      evidence,
+      occurred_at: timestamp,
+    };
+    persistScopeMutation(files, state, scope, timestamp, transition, {
+      type: "gate-requested",
+      occurred_at: timestamp,
+      scope: scopeName,
+      gate_id: gateId,
+      node,
+      iteration_id: iterationId,
+      evidence,
+    }, options);
+    return {
+      command: "gate request",
+      revision: state.revision,
+      gate: request,
+      workflow_state: state,
+    };
+  });
+}
+
+function decideGate(files, flags, options) {
+  const expected = expectedRevision(flags);
+  return withLock(files, "workflow-state", () => {
+    const state = normalizeWorkflowState(
+      readYaml(files.workflowState, options.yaml, "workflow-state.yaml"),
+    );
+    if (state.revision !== expected) {
+      throw new Error(`Workflow state revision conflict: expected ${expected}, actual ${state.revision}.`);
+    }
+    const gateId = requiredFlag(flags, "--gate-id");
+    const scopes = [state.development_state, state.release_state];
+    let owningScope = null;
+    let pending = [];
+    let request = null;
+    for (const scope of scopes) {
+      const candidates = scope.pending_gates.map((gate) =>
+        typeof gate === "string" ? { gate_id: gate, node: null, evidence: [] } : gate);
+      const candidate = candidates.find((gate) => gate?.gate_id === gateId);
+      if (candidate) {
+        if (request) throw new Error(`Gate ID is pending in more than one scope: ${gateId}`);
+        request = candidate;
+        pending = candidates;
+        owningScope = scope;
+      }
+    }
+    if (!request) throw new Error(`Gate is not pending: ${gateId}`);
+    const scopeName = request.scope || scopeNameForNode(request.node);
+    const decision = requiredFlag(flags, "--decision").toLowerCase().replaceAll("_", "-");
+    if (!GATE_DECISIONS.has(decision)) throw new Error(`Unsupported gate decision: ${decision}`);
+    const actor = requiredFlag(flags, "--actor");
+    const rationale = requiredFlag(flags, "--rationale");
+    const evidence = repeatedFlag(flags, "--evidence");
+    const evidenceArtifacts = registeredEvidence(files, evidence, options);
+    const crossNodeEvidence = evidenceArtifacts.filter((artifact) => artifact.node !== request.node);
+    if (decision === "not-required") {
+      if (request.node !== "04-experience-design" || !UX_GATE_IDS.has(gateId)) {
+        throw new Error(`Gate ${gateId} cannot use not-required.`);
+      }
+      if (!evidenceArtifacts.some(isProductTerminalEvidence)) {
+        throw new Error(`UX Gate ${gateId} requires successful product-terminal evidence for not-required.`);
+      }
+      if (crossNodeEvidence.some((artifact) => !isProductTerminalEvidence(artifact))) {
+        throw new Error(`Gate evidence belongs to another node: ${crossNodeEvidence[0].artifact_id || crossNodeEvidence[0].id}.`);
+      }
+    } else if (crossNodeEvidence.length) {
+      throw new Error(`Gate evidence belongs to another node: ${crossNodeEvidence[0].artifact_id || crossNodeEvidence[0].id}.`);
+    }
+    for (const requestedEvidence of request.evidence || []) {
+      if (!evidence.includes(requestedEvidence)) {
+        throw new Error(`Gate decision must retain requested evidence: ${requestedEvidence}`);
+      }
+    }
+
+    const timestamp = (options.now || (() => new Date().toISOString()))();
+    const record = {
+      gate_id: gateId,
+      node: request.node,
+      iteration_id: request.iteration_id || owningScope.scope_id,
+      scope: scopeName,
+      node_attempt: request.node_attempt || Number(owningScope.node_attempts[request.node] || 1),
+      decision,
+      actor,
+      rationale,
+      evidence,
+      decided_at: timestamp,
+    };
+    owningScope.pending_gates = pending.filter((gate) => gate?.gate_id !== gateId);
+    owningScope.gate_decisions = [...owningScope.gate_decisions, record];
+    const transition = {
+      event: "gate-decided",
+      scope: scopeName,
+      ...record,
+      occurred_at: timestamp,
+    };
+    persistScopeMutation(files, state, owningScope, timestamp, transition, {
+      type: "gate-decided",
+      occurred_at: timestamp,
+      scope: scopeName,
+      ...record,
+    }, options);
+    return {
+      command: "gate decide",
+      revision: state.revision,
+      gate: record,
+      workflow_state: state,
+    };
+  });
+}
+
+function readEvents(files, errors) {
+  if (!fs.existsSync(files.events)) return [];
+  const events = [];
+  const lines = fs.readFileSync(files.events, "utf8").split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    try {
+      const event = JSON.parse(lines[index]);
+      if (!event || typeof event !== "object" || Array.isArray(event)) {
+        errors.push(`Audit event at line ${index + 1} must be a JSON object.`);
+      } else {
+        events.push(event);
+      }
+    } catch {
+      errors.push(`Audit event at line ${index + 1} is not valid JSON.`);
+    }
+  }
+  return events;
+}
+
+function verifyStream(file, value, stream, events, errors, allowedSchemas = new Set([1])) {
+  if (!allowedSchemas.has(value.schema_version)) {
+    errors.push(`${stream} schema_version must be one of ${[...allowedSchemas].join(", ")}.`);
+  }
+  if (!Number.isInteger(value.revision) || value.revision < 0) {
+    errors.push(`${stream} revision must be a non-negative integer.`);
+    return;
+  }
+  const streamEvents = events.filter((event) => event.stream === stream);
+  if (value.revision === 0) {
+    if (streamEvents.length) errors.push(`${stream} revision is 0 but audit events exist.`);
+    return;
+  }
+  if (streamEvents.length !== value.revision) {
+    errors.push(
+      `Audit event count mismatch for ${stream}: expected ${value.revision}, actual ${streamEvents.length}.`,
+    );
+  }
+  const revisions = streamEvents.map((event) => event.revision);
+  for (let revision = 1; revision <= value.revision; revision += 1) {
+    if (revisions.filter((item) => item === revision).length !== 1) {
+      errors.push(`${stream} audit revision ${revision} must occur exactly once.`);
+    }
+  }
+  const latest = streamEvents.find((event) => event.revision === value.revision);
+  if (!latest) return;
+  const checksum = sha256(fs.readFileSync(file));
+  if (latest.after_checksum !== checksum) {
+    errors.push(`Audit checksum mismatch for ${stream}.`);
+  }
+}
+
+function verifyFormalState(files, options) {
+  const project = readYaml(files.project, options.yaml, "project.yaml");
+  const rawState = readYaml(files.workflowState, options.yaml, "workflow-state.yaml");
+  const rawRegistry = readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml");
+  const state = normalizeWorkflowState(rawState);
+  const registry = normalizeArtifactRegistry(rawRegistry);
+  const errors = [];
+  const events = readEvents(files, errors);
+  let shards = [];
+  try {
+    shards = readEventShards(files, options);
+  } catch (error) {
+    errors.push(error.message);
+  }
+
+  verifyStream(files.workflowState, rawState, "workflow-state", events, errors, new Set([1, 2]));
+  verifyStream(files.artifactRegistry, rawRegistry, "artifact-registry", events, errors);
+  if (shards.length) {
+    for (const [stream, value] of [["workflow-state", rawState], ["artifact-registry", rawRegistry]]) {
+      const latest = shards.filter((record) => record.stream === stream)
+        .sort((left, right) => right.revision - left.revision)[0];
+      if (latest && (latest.revision !== value.revision
+        || latest.after_checksum !== sha256(options.yaml.stringify(value)))) {
+        errors.push(`Derived view does not match latest authoritative shard for ${stream}.`);
+      }
+    }
+  }
+  if (project.project_id && state.project_id && project.project_id !== state.project_id) {
+    errors.push(`Project ID mismatch: project.yaml=${project.project_id}, workflow-state=${state.project_id}.`);
+  }
+  if (project.current_iteration_id && state.development_state.scope_id
+    && project.current_iteration_id !== state.development_state.scope_id) {
+    errors.push(
+      `Iteration mismatch: project.yaml=${project.current_iteration_id}, workflow-state=${state.development_state.scope_id}.`,
+    );
+  }
+  if (project.current_release_id && state.release_state.scope_id
+    && project.current_release_id !== state.release_state.scope_id) {
+    errors.push(
+      `Release mismatch: project.yaml=${project.current_release_id}, workflow-state=${state.release_state.scope_id}.`,
+    );
+  }
+
+  for (const [scopeName, scope] of [["development", state.development_state], ["release", state.release_state]]) {
+    const active = new Set(scope.active_nodes);
+    const blocked = new Set(scope.blocked_nodes);
+    const completed = new Set(scope.completed_nodes);
+    const hasScopedState = active.size || blocked.size || completed.size
+      || scope.pending_gates.length || scope.gate_decisions.length
+      || Object.keys(scope.node_attempts).length || scope.latest_candidate_id || scope.latest_release_id;
+    if (hasScopedState && !scope.scope_id) {
+      errors.push(`Workflow ${scopeName} scope has state but no scope_id.`);
+    }
+    for (const node of active) {
+      if (blocked.has(node) || completed.has(node)) {
+        errors.push(`Workflow node appears in incompatible states in ${scopeName}: ${node}.`);
+      }
+    }
+    for (const node of blocked) {
+      if (completed.has(node)) errors.push(`Workflow node appears in incompatible states in ${scopeName}: ${node}.`);
+    }
+    for (const node of [...active, ...blocked, ...completed]) {
+      if (!NODE_IDS.has(node)) errors.push(`Unknown workflow node in formal state: ${node}.`);
+      else if (scopeNameForNode(node) !== scopeName) {
+        errors.push(`Workflow node is stored in the wrong ${scopeName} scope: ${node}.`);
+      }
+    }
+  }
+
+  const artifactIds = new Set();
+  const artifactPaths = new Set();
+  for (const artifact of registry.artifacts) {
+    const artifactId = artifact.artifact_id || artifact.id;
+    if (!artifactId) {
+      errors.push("Registered artifact is missing artifact_id.");
+      continue;
+    }
+    if (artifactIds.has(artifactId)) errors.push(`Duplicate artifact ID: ${artifactId}.`);
+    artifactIds.add(artifactId);
+
+    const artifactPath = typeof artifact.path === "string" ? artifact.path.replaceAll("\\", "/") : "";
+    if (!artifactPath.startsWith(".workflow/")) {
+      errors.push(`Artifact path must start with .workflow/: ${artifactId}.`);
+      continue;
+    }
+    if (artifactPaths.has(artifactPath)) errors.push(`Duplicate artifact path: ${artifactPath}.`);
+    artifactPaths.add(artifactPath);
+
+    const absolute = path.resolve(files.root, artifactPath);
+    if (!isInside(absolute, files.workflow) || !fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+      errors.push(`Artifact file is missing or outside .workflow/: ${artifactId}.`);
+      continue;
+    }
+    if (!isInside(fs.realpathSync(absolute), fs.realpathSync(files.workflow))) {
+      errors.push(`Artifact path resolves outside .workflow/: ${artifactId}.`);
+      continue;
+    }
+    const checksum = sha256(fs.readFileSync(absolute));
+    if (artifact.checksum_algorithm !== "sha256" || artifact.checksum !== checksum) {
+      errors.push(`Checksum mismatch for artifact ${artifactId}.`);
+    }
+  }
+
+  if (errors.length) throw new Error(`Formal state verification failed:\n- ${errors.join("\n- ")}`);
+  return {
+    command: "verify",
+    valid: true,
+    errors: [],
+    workflow_revision: state.revision,
+    artifact_registry_revision: registry.revision,
+    artifact_count: registry.artifacts.length,
+    audit_event_count: events.length,
+    event_shard_count: shards.length,
+  };
+}
+
+export function executeDeliveryStateCommand(argv, options = {}) {
+  requireYaml(options.yaml);
+  const { positional, options: flags } = parseArgs(argv);
+  const command = positional[0];
+  const projectRoot = path.resolve(String(flags.get("--project") || options.projectRoot || process.cwd()));
+  const files = statePaths(projectRoot);
+  const descriptor = lifecycleDescriptor(command, positional, flags);
+  const before = dispatchLifecycle(options, files, descriptor, "before", flags);
+  if (before.decision === "block") {
+    const error = new Error(`Evolution Hook blocked ${descriptor.action}: ${(before.messages || []).join("; ") || "no rationale"}`);
+    dispatchLifecycle(options, files, descriptor, "failed", flags, null, error);
+    throw error;
+  }
+  try {
+    let result;
+    if (command === "artifact" && positional[1] === "register") {
+      result = registerArtifact(files, flags, options);
+    } else if (command === "artifact" && positional[1] === "status") {
+      result = changeArtifactStatus(files, flags, options);
+    } else if (command === "gate" && positional[1] === "request") {
+      result = requestGate(files, flags, options);
+    } else if (command === "gate" && positional[1] === "decide") {
+      result = decideGate(files, flags, options);
+    } else if (command === "transition") {
+      result = transitionWorkflow(files, flags, options);
+    } else if (command === "verify") {
+      result = verifyFormalState(files, options);
+    } else if (command === "rebuild") {
+      result = rebuildFormalViews(files, options);
+    } else if (command === "inspect") {
+      const project = readYaml(files.project, options.yaml, "project.yaml");
+      const workflowState = normalizeWorkflowState(
+        readYaml(files.workflowState, options.yaml, "workflow-state.yaml"),
+      );
+      const artifactRegistry = normalizeArtifactRegistry(
+        readYaml(files.artifactRegistry, options.yaml, "artifact-registry.yaml"),
+      );
+      result = {
+        command,
+        project_id: project.project_id || workflowState.project_id || path.basename(projectRoot),
+        project,
+        workflow_state: workflowState,
+        artifact_registry: artifactRegistry,
+      };
+    } else {
+      throw new Error("Use inspect, verify, rebuild, artifact register/status, transition, or gate request/decide.");
+    }
+    dispatchLifecycle(options, files, descriptor, "after", flags, result);
+    return result;
+  } catch (error) {
+    dispatchLifecycle(options, files, descriptor, "failed", flags, null, error);
+    throw error;
+  }
+}