ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/visual-standard.mjs

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+import { parse as parseYaml } from "./yaml-runtime.mjs";
+
+function containedPath(root, relative, label) {
+  if (!relative || path.isAbsolute(relative)) throw new Error(`${label} must be a project-relative path.`);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  const relation = path.relative(resolvedRoot, resolved);
+  if (relation === ".." || relation.startsWith(`..${path.sep}`)) {
+    throw new Error(`${label} resolves outside the project.`);
+  }
+  return resolved;
+}
+
+function readYaml(file, label) {
+  if (!fs.existsSync(file)) throw new Error(`${label} is missing: ${file}`);
+  const value = parseYaml(fs.readFileSync(file, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must contain a YAML mapping.`);
+  }
+  return value;
+}
+
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function requireChecksum(value, label) {
+  const checksum = String(value || "");
+  if (!/^[a-f0-9]{64}$/.test(checksum)) throw new Error(`${label} checksum is missing or invalid.`);
+  return checksum;
+}
+
+function addRequiredInput(required, scope, ref, checksum, label) {
+  if (!ref || typeof ref !== "string") throw new Error(`${label} reference is missing.`);
+  const identity = `${scope}:${ref}`;
+  const expected = requireChecksum(checksum, label);
+  if (required.has(identity) && required.get(identity).checksum !== expected) {
+    throw new Error(`${label} has conflicting checksums for ${ref}.`);
+  }
+  required.set(identity, { scope, ref, checksum: expected });
+}
+
+function requiredVisualStandardInputs(projectRoot, experienceRoot, confirmation) {
+  const required = new Map();
+  const direct = [
+    ["visual_direction", "Visual direction"],
+    ["design_reference_selection", "Design reference selection"],
+    ["visual_reference_manifest", "Visual Reference manifest"],
+    ["visual_reference", "Visual Reference"],
+    ["design_tokens", "Design tokens"],
+    ["ui_framework_selection", "UI framework selection"],
+    ["component_state_matrix", "Component state matrix"],
+  ];
+  for (const [prefix, label] of direct) {
+    addRequiredInput(
+      required,
+      "experience",
+      confirmation[`${prefix}_ref`],
+      confirmation[`${prefix}_checksum`],
+      label,
+    );
+  }
+
+  const selection = readYaml(
+    containedPath(experienceRoot, confirmation.design_reference_selection_ref, "Design reference selection"),
+    "Design reference selection",
+  );
+  if (selection.decision !== "selected" || !String(selection.rationale || "").trim()) {
+    throw new Error("Design reference selection must be selected and include a rationale.");
+  }
+  for (const [prefix, label] of [
+    ["catalog", "Design Reference Library catalog"],
+    ["license", "Design Reference Library license"],
+    ["upstream", "Design Reference Library upstream attribution"],
+  ]) {
+    addRequiredInput(required, "project", selection[`${prefix}_ref`], selection[`${prefix}_checksum`], label);
+  }
+  if (!/^[a-f0-9]{40}$/.test(String(selection.upstream_version || ""))) {
+    throw new Error("Design reference selection must pin the upstream version commit.");
+  }
+  const upstream = readYaml(
+    containedPath(projectRoot, selection.upstream_ref, "Design Reference Library upstream attribution"),
+    "Design Reference Library upstream attribution",
+  );
+  if (upstream.source_commit !== selection.upstream_version) {
+    throw new Error("Design reference upstream version does not match UPSTREAM.yaml.");
+  }
+  if (upstream.license !== "MIT" || upstream.license_ref !== path.basename(selection.license_ref || "")) {
+    throw new Error("Design Reference Library license does not match UPSTREAM.yaml attribution.");
+  }
+  const evaluated = Array.isArray(selection.evaluated_references) ? selection.evaluated_references : [];
+  if (evaluated.length < 2 || evaluated.length > 3) {
+    throw new Error("Design reference selection must evaluate exactly two or three references.");
+  }
+  const evaluatedIdentities = new Set();
+  for (const reference of evaluated) {
+    addRequiredInput(required, "project", reference?.ref, reference?.checksum, "Evaluated design reference");
+    evaluatedIdentities.add(reference.ref);
+  }
+  const primary = selection.primary_reference;
+  if (!primary || !evaluatedIdentities.has(primary.ref)) {
+    throw new Error("Primary design reference must be one of the evaluated references.");
+  }
+  addRequiredInput(required, "project", primary.ref, primary.checksum, "Primary design reference");
+  if (selection.max_supporting_references !== 1) {
+    throw new Error("Design reference selection must allow at most one supporting reference.");
+  }
+  const supporting = selection.supporting_reference;
+  if (supporting) {
+    if (!evaluatedIdentities.has(supporting.ref) || !String(supporting.scope || "").trim()) {
+      throw new Error("Supporting design reference must be evaluated and declare a narrow scope.");
+    }
+    addRequiredInput(required, "project", supporting.ref, supporting.checksum, "Supporting design reference");
+  }
+
+  const framework = readYaml(
+    containedPath(experienceRoot, confirmation.ui_framework_selection_ref, "UI framework selection"),
+    "UI framework selection",
+  );
+  if (![framework.selected_framework, framework.selected_version,
+    framework.selected_component_system, framework.selected_component_system_version,
+    framework.selected_icon_library, framework.selected_icon_library_version]
+    .every((value) => String(value || "").trim())) {
+    throw new Error("UI framework, component system, and icon library versions must all be pinned.");
+  }
+  if (!framework.component_registry || !framework.component_registry_version) {
+    throw new Error("UI framework selection must pin the component registry and version.");
+  }
+  addRequiredInput(
+    required,
+    "experience",
+    framework.component_configuration_ref,
+    framework.component_configuration_checksum,
+    "Component configuration",
+  );
+  if (!Array.isArray(framework.selected_components) || !framework.selected_components.length) {
+    throw new Error("UI framework selection must list the selected components.");
+  }
+  if (!Array.isArray(framework.local_adaptations)) {
+    throw new Error("UI framework selection local_adaptations must be a list.");
+  }
+  for (const adaptation of framework.local_adaptations) {
+    addRequiredInput(required, "experience", adaptation?.ref, adaptation?.checksum, "Local adaptation");
+  }
+  if (framework.selection_source === "workflow-default"
+      && framework.architecture_compatibility?.react_web === true
+      && (framework.selected_component_system !== "shadcn" || framework.selected_icon_library !== "lucide")) {
+    throw new Error("Compatible React Web defaults must select shadcn and lucide.");
+  }
+  if (confirmation.component_system !== framework.selected_component_system
+      || confirmation.icon_library !== framework.selected_icon_library) {
+    throw new Error("UX-VS component system or icon library does not match the framework selection.");
+  }
+
+  const manifest = readYaml(
+    containedPath(experienceRoot, confirmation.visual_reference_manifest_ref, "Visual Reference manifest"),
+    "Visual Reference manifest",
+  );
+  for (const [refField, checksumField, label] of [
+    ["entrypoint", "entrypoint_checksum", "Visual Reference entrypoint"],
+    ["design_reference_selection_ref", "design_reference_selection_checksum", "Manifest design reference selection"],
+    ["design_tokens_ref", "design_tokens_checksum", "Manifest design tokens"],
+    ["component_state_matrix_ref", "component_state_matrix_checksum", "Manifest component state matrix"],
+  ]) addRequiredInput(required, "experience", manifest[refField], manifest[checksumField], label);
+
+  return required;
+}
+
+export function validateVisualStandard(projectRoot, options = {}) {
+  const experienceRoot = containedPath(projectRoot, options.experience, "Experience directory");
+  const confirmation = readYaml(
+    path.join(experienceRoot, "visual-system-confirmation.yaml"),
+    "Visual system confirmation",
+  );
+  if (confirmation.decision !== "approved" || confirmation.human_approval?.decision !== "approved") {
+    throw new Error("Visual Standard requires an approved human UX-VS decision.");
+  }
+  if (!confirmation.human_approval?.approver || !confirmation.human_approval?.decided_at) {
+    throw new Error("Visual Standard approval must identify the human approver and decision time.");
+  }
+  const validatedAt = options.now ? Number(options.now()) : Date.now();
+  if (!Number.isFinite(validatedAt)) throw new Error("Visual Standard validation clock is invalid.");
+  const expiresAt = Date.parse(confirmation.approval_expires_at || "");
+  if (!Number.isFinite(expiresAt)) {
+    throw new Error("Visual Standard approval must declare a valid approval_expires_at time.");
+  }
+  if (validatedAt >= expiresAt) throw new Error("Visual Standard approval expired.");
+  const inputs = Array.isArray(confirmation.design_input_checksums)
+    ? confirmation.design_input_checksums
+    : [];
+  if (!inputs.length) throw new Error("Visual Standard must bind every design input checksum.");
+  const requiredInputs = requiredVisualStandardInputs(projectRoot, experienceRoot, confirmation);
+  const seenInputs = new Set();
+  for (const input of inputs) {
+    if (!input || !new Set(["project", "experience"]).has(input.scope)) {
+      throw new Error("Every design input must declare project or experience scope.");
+    }
+    if (!/^[a-f0-9]{64}$/.test(String(input.checksum || ""))) {
+      throw new Error(`Design input checksum is invalid for ${input.ref || "unknown input"}.`);
+    }
+    const identity = `${input.scope}:${input.ref}`;
+    if (seenInputs.has(identity)) throw new Error(`Duplicate design input: ${identity}.`);
+    seenInputs.add(identity);
+    const inputFile = containedPath(
+      input.scope === "project" ? projectRoot : experienceRoot,
+      input.ref,
+      `Design input ${input.ref || "path"}`,
+    );
+    if (!fs.existsSync(inputFile) || !fs.statSync(inputFile).isFile()) {
+      throw new Error(`Design input is missing: ${input.ref}.`);
+    }
+    if (sha256(inputFile) !== input.checksum) {
+      throw new Error(`Design input checksum mismatch for ${input.ref}.`);
+    }
+  }
+  for (const [identity, required] of requiredInputs) {
+    if (!seenInputs.has(identity)) throw new Error(`Required design input is missing: ${required.ref}.`);
+    const declared = inputs.find((input) => `${input.scope}:${input.ref}` === identity);
+    if (declared.checksum !== required.checksum) {
+      throw new Error(`Required design input checksum conflicts with its source artifact: ${required.ref}.`);
+    }
+  }
+  return {
+    valid: true,
+    experience: path.relative(path.resolve(projectRoot), experienceRoot).replaceAll("\\", "/"),
+    design_input_count: inputs.length,
+    approval_expires_at: confirmation.approval_expires_at || null,
+  };
+}

package/lib/workflow-manager-contracts.mjs

@@ -0,0 +1,367 @@
+import crypto from "node:crypto";
+
+export const WORKFLOW_MANAGER_CONTRACTS_SCHEMA_VERSION = "workflow-manager.contracts.v1";
+
+const jsonType = (type, description) => ({ type, description });
+const string = (description) => jsonType("string", description);
+const nonEmptyString = (description) => ({ type: "string", minLength: 1, description });
+const nullableString = (description) => ({ type: ["string", "null"], description });
+const integer = (description) => jsonType("integer", description);
+const array = (description) => ({ type: "array", description, items: { type: "string" } });
+const object = (description) => ({ type: "object", description, additionalProperties: true });
+
+function actionContract(action, {
+  required = [],
+  properties = {},
+  actor = "human-or-agent",
+  concurrency = "target-revision-or-checksum",
+  idempotency = "required",
+  plan = "not-required",
+  mutability = "governed",
+}) {
+  return Object.freeze({
+    action,
+    contract_version: 1,
+    mutability,
+    authorization: { actor },
+    concurrency: { mode: concurrency },
+    retry: { idempotency },
+    planning: { mode: plan },
+    input_schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      $id: `urn:ai-delivery:workflow-manager:action:${action}:v1`,
+      type: "object",
+      required,
+      properties,
+      additionalProperties: false,
+    },
+    output_schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      $id: `urn:ai-delivery:workflow-manager:result:${action}:v1`,
+      type: "object",
+      required: ["outcome"],
+      properties: {
+        outcome: string("Applied, planned, not-registered, or idempotent-replay outcome."),
+        result: object("Action-specific structured result."),
+        receipt: object("Immutable Workflow Manager receipt when the action mutates state."),
+        event: object("Immutable Workflow Manager event when the action mutates state."),
+      },
+      additionalProperties: true,
+    },
+  });
+}
+
+const exactPrototype = {
+  prototype_revision_id: string("Exact Prototype Revision identity."),
+  prototype_revision_checksum: string("Exact Prototype Revision checksum."),
+  terminal_id: string("Exact registered Logical Terminal identity."),
+  page_id: string("Stable Prototype Page identity."),
+  page_checksum: string("Exact Page checksum."),
+};
+const exactCandidateTransition = {
+  revision: string("Exact frozen Prototype revision reference."),
+  prototype_revision_id: string("Exact frozen Prototype Revision identity."),
+  prototype_revision_checksum: string("Exact frozen Prototype Revision checksum."),
+  terminal_id: string("Exact source Logical Terminal for the Component Candidate."),
+  component_id: string("Stable Component Candidate identity."),
+  expected_lifecycle: string("Expected current Component Candidate lifecycle."),
+  target_lifecycle: string("Requested legal successor Component Candidate lifecycle."),
+  experience: string("Registered Experience root."),
+};
+const governed = {
+  actor: string("Authenticated human or agent actor identity."),
+  idempotency_key: string("Caller-generated retry identity."),
+};
+const candidateTransitionGoverned = {
+  ...governed,
+  idempotency_key: nonEmptyString("Non-empty caller-generated retry identity."),
+};
+const collectionConcurrency = {
+  expected_revision: integer("Expected collection revision."),
+  expected_checksum: nullableString("Expected collection checksum, or null for an unregistered collection."),
+};
+
+export const WORKFLOW_MANAGER_ACTION_CONTRACTS = Object.freeze([
+  actionContract("requirement-apply", {
+    required: ["operation", "requirement_id", "title", "summary", "status", "acceptance", "expected_revision", "expected_checksum", "actor", "idempotency_key"],
+    properties: {
+      operation: string("create or update."), requirement_id: string("Stable requirement identity."),
+      iteration_id: string("Required when creating."), title: string("Requirement title."),
+      summary: string("Requirement summary."), status: string("Requirement lifecycle state."),
+      acceptance: array("Acceptance statements."), expected_entity_revision: integer("Required when updating."),
+      ...collectionConcurrency, ...governed,
+    },
+  }),
+  actionContract("task-apply", {
+    required: ["operation", "task_id", "next_action", "expected_shared_revision", "actor", "idempotency_key"],
+    properties: {
+      operation: string("create, activate, checkpoint, or finish."), task_id: string("Stable task identity."),
+      iteration_id: string("Iteration identity for create."), node: string("Formal seven-node identity for create."),
+      skill: string("Owning installed skill for create."), goal: string("Stable logical task goal."),
+      responsibility: string("Task responsibility."), scope: array("Task scope identities."),
+      acceptance: array("Task acceptance identities."), depends_on: array("Blocking task identities."),
+      status: string("Writer-supported task state."), phase: string("Writer-supported attempt phase."),
+      next_action: string("Concrete next action."), next_action_owner: string("agent, user, or external."),
+      completed_steps: array("Completed step descriptions."), blockers: array("Current blockers."),
+      evidence: array("Evidence identities."), actual_outputs: array("Produced output paths or identities."),
+      sequence: integer("Optional ordering sequence."), derived_from: string("Source task identity."),
+      supersedes: string("Superseded task identity."), new_attempt: { type: "boolean", description: "Start a new attempt after failure." },
+      expected_shared_revision: integer("Expected shared task revision; zero when creating."),
+      ...governed,
+    },
+    concurrency: "task-state-writer-shared-revision",
+  }),
+  actionContract("test-case-apply", {
+    required: ["operation", "test_case_id", "title", "kind", "status", "steps", "expected_result", "expected_revision", "expected_checksum", "actor", "idempotency_key"],
+    properties: {
+      operation: string("create or update."), test_case_id: string("Stable test-case identity."),
+      iteration_id: string("Required when creating."), title: string("Test-case title."), kind: string("Test category."),
+      status: string("Test-case lifecycle state."), steps: array("Ordered test steps."),
+      expected_result: string("Expected observable result."), expected_entity_revision: integer("Required when updating."),
+      ...collectionConcurrency, ...governed,
+    },
+  }),
+  actionContract("test-run-record", {
+    required: ["test_run_id", "test_case_id", "test_case_version", "iteration_id", "candidate_id", "outcome", "evidence", "expected_revision", "expected_checksum", "actor", "idempotency_key"],
+    properties: {
+      test_run_id: string("Unique immutable test-run identity."), test_case_id: string("Bound test-case identity."),
+      test_case_version: integer("Exact test-case version."), iteration_id: string("Iteration identity."),
+      candidate_id: string("Exact candidate identity."), outcome: string("Observed test outcome."),
+      evidence: array("Evidence identities."), ...collectionConcurrency, ...governed,
+    },
+  }),
+  actionContract("artifact-register", {
+    required: ["artifact_id", "artifact_type", "path", "node", "status", "expected_revision", "actor", "idempotency_key"],
+    properties: {
+      artifact_id: string("Stable artifact identity."), artifact_type: string("Artifact semantic type."),
+      path: string("Existing project-relative .workflow path."), node: string("Owning formal node."),
+      status: string("Artifact status."), version: string("Artifact semantic version."),
+      producer_skill: string("Producing skill identity."), candidate_id: string("Bound candidate identity."),
+      supersedes: string("Superseded artifact identity."), expected_revision: integer("Expected formal artifact Registry revision."),
+      ...governed,
+    },
+    concurrency: "formal-artifact-registry-revision",
+  }),
+  actionContract("prototype-change-request-create", {
+    required: ["prototype_revision_id", "prototype_revision_checksum", "terminal_id", "page_id", "page_checksum", "body", "actor", "idempotency_key"],
+    properties: { ...exactPrototype, review_scene_id: string("Optional Review Scene identity."), body: string("Required change request body."), ...governed },
+    actor: "human",
+  }),
+  actionContract("prototype-change-request-edit", {
+    required: ["change_request_id", "expected_revision", "body", "actor", "idempotency_key"],
+    properties: { change_request_id: string("Change request identity."), expected_revision: integer("Expected request revision."), body: string("Replacement draft body."), ...governed },
+    actor: "human",
+  }),
+  actionContract("prototype-change-request-attachment-add", {
+    required: ["change_request_id", "expected_revision", "content_base64", "media_type", "actor", "idempotency_key"],
+    properties: { change_request_id: string("Change request identity."), expected_revision: integer("Expected request revision."), content_base64: string("Bounded base64 image content."), media_type: string("Allowed image media type."), ...governed },
+    actor: "human",
+  }),
+  actionContract("prototype-review-batch-finalize", {
+    required: ["prototype_revision_id", "prototype_revision_checksum", "terminal_id", "page_id", "change_request_ids", "actor", "idempotency_key"],
+    properties: { ...exactPrototype, change_request_ids: array("Exact request identities included in the batch."), ...governed },
+    actor: "human",
+  }),
+  actionContract("prototype-page-review-apply", {
+    required: ["revision", "terminal_id", "page_id", "target_checksum", "page_checksum", "decision", "actor", "idempotency_key"],
+    properties: { revision: string("Prototype revision reference."), terminal_id: string("Exact registered Logical Terminal identity."), page_id: string("Stable Page identity."), review_scene_id: string("Optional selected Review Scene identity."), target_checksum: string("Prototype checksum."), page_checksum: string("Page checksum."), decision: string("approved or changes-requested."), expected_scope_revision: integer("Required when final approval decides UX-UI."), rationale: string("Decision rationale."), comment: string("AI-readable optional comment."), experience: string("Registered Experience root."), ...governed },
+    actor: "human",
+  }),
+  actionContract("prototype-visual-standard-review-apply", {
+    required: ["revision", "prototype_revision_id", "prototype_revision_checksum", "visual_standard_checksum", "terminal_id", "decision", "actor", "idempotency_key"],
+    properties: {
+      revision: string("Exact Prototype revision reference."),
+      prototype_revision_id: string("Exact Prototype Revision identity."),
+      prototype_revision_checksum: string("Exact Prototype Revision checksum."),
+      visual_standard_checksum: string("Exact Visual Standard checksum bound by the Prototype Revision."),
+      terminal_id: string("all or one exact registered Logical Terminal identity."),
+      decision: string("approved or changes-requested."),
+      comment: string("Required non-empty modification comment when changes are requested."),
+      experience: string("Registered Experience root."),
+      ...governed,
+    },
+    actor: "human",
+  }),
+  actionContract("prototype-component-candidate-transition-plan", {
+    required: ["revision", "prototype_revision_id", "prototype_revision_checksum", "terminal_id", "component_id", "expected_lifecycle", "target_lifecycle", "actor", "idempotency_key"],
+    properties: { ...exactCandidateTransition, ...candidateTransitionGoverned },
+    actor: "human",
+    concurrency: "prototype-revision-checksum-and-candidate-lifecycle",
+    plan: "plan-only",
+  }),
+  actionContract("prototype-component-candidate-transition-apply", {
+    required: ["revision", "prototype_revision_id", "prototype_revision_checksum", "terminal_id", "component_id", "expected_lifecycle", "target_lifecycle", "expected_plan_checksum", "actor", "idempotency_key"],
+    properties: {
+      ...exactCandidateTransition,
+      expected_plan_checksum: string("Exact checksum returned by prototype-component-candidate-transition-plan."),
+      ...candidateTransitionGoverned,
+    },
+    actor: "human",
+    concurrency: "prototype-revision-checksum-and-candidate-lifecycle",
+    plan: "required-before-apply",
+  }),
+  actionContract("prototype-change-request-execution-start", {
+    required: ["change_request_id", "expected_revision", "actor", "idempotency_key"],
+    properties: { change_request_id: string("Change request identity."), expected_revision: integer("Expected request revision."), ...governed },
+    actor: "agent",
+  }),
+  actionContract("prototype-change-request-discard", {
+    required: ["change_request_id", "expected_revision", "rationale", "actor", "idempotency_key"],
+    properties: { change_request_id: string("Change request identity."), expected_revision: integer("Expected request revision."), rationale: string("Human discard rationale."), ...governed },
+    actor: "human",
+  }),
+  actionContract("system-initialization-script-plan", {
+    required: ["system_id", "script_id", "expected_registry_revision", "expected_registry_checksum", "idempotency_key"],
+    properties: { system_id: string("Project System identity."), script_id: string("Initialization script identity."), name: string("Human-readable script name."), content: string("Final edited script content."), source_path: string("Optional registered import provenance."), expected_registry_revision: integer("Expected Registry revision."), expected_registry_checksum: string("Expected Registry checksum."), expected_script_checksum: string("Expected current script checksum."), branch: string("Current branch."), ...governed },
+    plan: "required-before-apply",
+  }),
+  actionContract("system-initialization-script-apply", {
+    required: ["system_id", "script_id", "content", "expected_registry_revision", "expected_registry_checksum", "actor", "idempotency_key"],
+    properties: { system_id: string("Project System identity."), script_id: string("Initialization script identity."), name: string("Human-readable script name."), content: string("Final edited script content."), source_path: string("Optional registered import provenance."), expected_registry_revision: integer("Expected Registry revision."), expected_registry_checksum: string("Expected Registry checksum."), expected_script_checksum: string("Expected current script checksum."), branch: string("Current branch."), ...governed },
+    plan: "required-before-apply",
+  }),
+  actionContract("system-lifecycle-plan", {
+    required: ["system_id", "operation", "expected_registry_revision", "expected_registry_checksum", "branch", "idempotency_key"],
+    properties: { system_id: string("Project System identity."), operation: string("start, stop, restart, or status."), expected_registry_revision: integer("Expected Registry revision."), expected_registry_checksum: string("Expected Registry checksum."), branch: string("Current branch."), ...governed },
+    plan: "required-before-apply",
+  }),
+  actionContract("system-lifecycle-apply", {
+    required: ["system_id", "operation", "expected_registry_revision", "expected_registry_checksum", "expected_plan_checksum", "branch", "actor", "idempotency_key"],
+    properties: { system_id: string("Project System identity."), operation: string("start, stop, restart, or status."), expected_registry_revision: integer("Expected Registry revision."), expected_registry_checksum: string("Expected Registry checksum."), expected_plan_checksum: string("Exact prior plan checksum."), branch: string("Current branch."), ...governed },
+    plan: "required-before-apply",
+  }),
+  actionContract("mock-sync-plan", {
+    required: ["idempotency_key"], properties: { ...governed }, plan: "required-before-apply",
+  }),
+  actionContract("mock-sync-apply", {
+    required: ["expected_plan_checksum", "actor", "idempotency_key"], properties: { expected_plan_checksum: string("Exact prior sync plan checksum."), ...governed }, plan: "required-before-apply",
+  }),
+  actionContract("gate-decision-apply", {
+    required: ["gate_id", "decision", "expected_scope_revision", "evidence", "actor", "idempotency_key"],
+    properties: { gate_id: string("Pending non-UX Gate identity."), decision: string("approved or rejected."), expected_scope_revision: integer("Expected formal scope revision."), evidence: array("Gate evidence identities."), comment: string("Optional AI-readable comment."), ...governed }, actor: "human", concurrency: "formal-scope-revision",
+  }),
+  actionContract("workflow-transition-apply", {
+    required: ["event", "iteration_id", "node_id", "expected_scope_revision", "evidence", "actor", "idempotency_key"],
+    properties: { event: string("node-started or node-completed."), iteration_id: string("Exact iteration identity."), node_id: string("Formal seven-node identity."), expected_scope_revision: integer("Expected formal scope revision."), evidence: array("Transition evidence identities."), ...governed }, actor: "human", concurrency: "formal-scope-revision",
+  }),
+  actionContract("relationship-suggest", {
+    required: ["from", "from_entity_type", "to", "to_entity_type", "relation_type", "rationale", "expected_revision", "expected_checksum", "actor", "idempotency_key"], properties: { from: string("Source entity identity."), from_entity_type: string("Source entity type."), to: string("Target entity identity."), to_entity_type: string("Target entity type."), relation_type: string("Governed relationship type."), rationale: string("AI suggestion rationale."), ...collectionConcurrency, ...governed }, actor: "agent",
+  }),
+  actionContract("relationship-decide", {
+    required: ["relation_id", "decision", "expected_revision", "expected_checksum", "actor", "idempotency_key"], properties: { relation_id: string("Relationship identity."), decision: string("confirmed or rejected."), comment: string("Optional human comment."), ...collectionConcurrency, ...governed }, actor: "human",
+  }),
+  actionContract("relationship-invalidate", {
+    required: ["relation_id", "rationale", "expected_revision", "expected_checksum", "actor", "idempotency_key"], properties: { relation_id: string("Relationship identity."), rationale: string("Human invalidation rationale."), ...collectionConcurrency, ...governed }, actor: "human",
+  }),
+  actionContract("settings-update-plan", {
+    required: ["expected_revision", "expected_checksum", "changes", "actor", "idempotency_key"], properties: { expected_revision: integer("Expected settings revision."), expected_checksum: nullableString("Expected settings checksum, or null before first write."), changes: object("Whitelisted Manager preference changes."), ...governed }, actor: "human", plan: "plan-only",
+  }),
+  actionContract("settings-update-apply", {
+    required: ["expected_revision", "expected_checksum", "expected_plan_checksum", "changes", "actor", "idempotency_key"], properties: { expected_revision: integer("Expected settings revision."), expected_checksum: nullableString("Expected settings checksum, or null before first write."), expected_plan_checksum: string("Exact checksum returned by settings-update-plan."), changes: object("Whitelisted Manager preference changes."), ...governed }, actor: "human", plan: "required-before-apply",
+  }),
+]);
+
+export const WORKFLOW_MANAGER_ACTION_NAMES = Object.freeze(
+  WORKFLOW_MANAGER_ACTION_CONTRACTS.map((contract) => contract.action),
+);
+
+const ACTION_CONTRACT_BY_NAME = new Map(
+  WORKFLOW_MANAGER_ACTION_CONTRACTS.map((contract) => [contract.action, contract]),
+);
+
+function schemaType(schema = {}) {
+  return Array.isArray(schema.type) ? schema.type.join("|") : schema.type || "any";
+}
+
+export function renderWorkflowManagerActionHelp(action, options = {}) {
+  const contract = ACTION_CONTRACT_BY_NAME.get(action);
+  if (!contract) throw new Error(`Unknown Workflow Manager action contract: ${action}`);
+  const command = options.command || "manager";
+  const required = new Set(contract.input_schema.required || []);
+  const fields = Object.entries(contract.input_schema.properties || {});
+  return [
+    `Workflow Manager contract: ${WORKFLOW_MANAGER_CONTRACTS_SCHEMA_VERSION}`,
+    `Action: ${contract.action}`,
+    `Usage: ${command} action ${contract.action} [workspace-directory] --input <json-file>`,
+    `Authorization: ${contract.authorization.actor}`,
+    `Concurrency: ${contract.concurrency.mode}`,
+    `Idempotency: ${contract.retry.idempotency}`,
+    `Planning: ${contract.planning.mode}`,
+    "",
+    "Required input fields:",
+    ...fields.filter(([field]) => required.has(field)).map(([field, schema]) =>
+      `  ${field} (${schemaType(schema)})  ${schema.description || ""}`.trimEnd()),
+    "",
+    "Optional input fields:",
+    ...fields.filter(([field]) => !required.has(field)).map(([field, schema]) =>
+      `  ${field} (${schemaType(schema)})  ${schema.description || ""}`.trimEnd()),
+    "",
+    "Result: structured outcome plus immutable receipt and event for applied mutations.",
+  ].join("\n");
+}
+
+function valueMatchesType(value, schema) {
+  if (Array.isArray(schema.type)) return schema.type.some((type) => valueMatchesType(value, { ...schema, type }));
+  if (schema.type === "null") return value === null;
+  if (schema.type === "object") return value !== null && typeof value === "object" && !Array.isArray(value);
+  if (schema.type === "array") return Array.isArray(value);
+  if (schema.type === "integer") return Number.isInteger(value);
+  if (schema.type === "boolean") return typeof value === "boolean";
+  if (schema.type === "string") return typeof value === "string";
+  return true;
+}
+
+export function validateWorkflowManagerActionInput(action, input) {
+  const contract = ACTION_CONTRACT_BY_NAME.get(action);
+  if (!contract) throw new Error(`Unknown Workflow Manager action contract: ${action}`);
+  const actor = String(input.actor || "");
+  if (contract.authorization.actor === "human" && !/^human:[A-Za-z0-9._@/-]+$/.test(actor)) {
+    return { valid: false, message: `${action} requires a human actor` };
+  }
+  if (contract.authorization.actor === "agent" && !/^agent:[A-Za-z0-9._@/-]+$/.test(actor)) {
+    return { valid: false, message: `${action} requires an agent actor` };
+  }
+  if (contract.authorization.actor === "human-or-agent"
+      && !/^(human|agent):[A-Za-z0-9._@/-]+$/.test(actor)) {
+    return { valid: false, message: `${action} requires a human or agent actor` };
+  }
+  for (const field of contract.input_schema.required || []) {
+    if (!(field in input) || input[field] === undefined) {
+      return { valid: false, message: `${field} is required for ${action}` };
+    }
+  }
+  if (contract.input_schema.additionalProperties === false) {
+    for (const field of Object.keys(input)) {
+      if (!(field in contract.input_schema.properties)) {
+        return { valid: false, message: `Unsupported field for ${action}: ${field}` };
+      }
+    }
+  }
+  for (const [field, value] of Object.entries(input)) {
+    const schema = contract.input_schema.properties[field];
+    if (!schema || value === undefined) continue;
+    if (!valueMatchesType(value, schema)) {
+      const expected = Array.isArray(schema.type) ? schema.type.join(" or ") : schema.type;
+      return { valid: false, message: `${field} must be ${expected} for ${action}` };
+    }
+    if (schema.type === "string" && Number.isInteger(schema.minLength) && value.length < schema.minLength) {
+      return { valid: false, message: `${field} must not be empty for ${action}` };
+    }
+    if (schema.type === "array" && schema.items) {
+      const invalid = value.findIndex((item) => !valueMatchesType(item, schema.items));
+      if (invalid >= 0) return { valid: false, message: `${field}[${invalid}] has an invalid type for ${action}` };
+    }
+  }
+  return { valid: true, contract };
+}
+
+export function inspectWorkflowManagerContracts() {
+  const actions = WORKFLOW_MANAGER_ACTION_CONTRACTS.map((contract) => structuredClone(contract));
+  const checksum = crypto.createHash("sha256").update(JSON.stringify(actions)).digest("hex");
+  return {
+    schema_version: WORKFLOW_MANAGER_CONTRACTS_SCHEMA_VERSION,
+    revision: 1,
+    checksum,
+    actions,
+  };
+}