@coordiation/agent 0.1.0 → 1.0.0-rc.1

package/src/lifecycle.js

@@ -0,0 +1,1751 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+export const LIFECYCLE_SCHEMA_VERSION = "1.0";
+export const LIFECYCLE_STAGES = ["specification", "prd", "ux", "prototype", "development", "qa", "release", "production"];
+export const LIFECYCLE_GATES = {
+  specification: "GATE-SPEC",
+  prd: "GATE-PRD",
+  ux: "GATE-UX",
+  prototype: "GATE-PROTOTYPE",
+  development: "GATE-DEVELOPMENT",
+  qa: "GATE-QA",
+  release: "GATE-RELEASE",
+  production: "GATE-PRODUCTION",
+};
+
+const COORDIATION_DIRECTORY = ".coordiation";
+const ARTIFACT_DIRECTORY = "artifacts";
+const PROJECT_PATH = `${COORDIATION_DIRECTORY}/project.json`;
+const LIFECYCLE_PATH = `${COORDIATION_DIRECTORY}/lifecycle.json`;
+const TRACEABILITY_PATH = `${COORDIATION_DIRECTORY}/traceability.json`;
+const APPROVALS_PATH = `${COORDIATION_DIRECTORY}/approvals.json`;
+const EVIDENCE_PATH = `${COORDIATION_DIRECTORY}/evidence.json`;
+
+const loginQuestions = [
+  {
+    id: "audience",
+    priority: "blocking",
+    question: "Who will use this login?",
+    why: "The audience determines account rules, language, security expectations, and where users go next.",
+    choices: [
+      { value: "customers", label: "Existing customers", effect: "Use a customer-facing flow and familiar recovery language.", recommended: true },
+      { value: "staff", label: "Internal staff", effect: "Expect organization-managed accounts and stricter access controls." },
+      { value: "both", label: "Customers and staff", effect: "The product may need separate entry paths or role-aware routing." },
+    ],
+    recommendedValue: "customers",
+    example: "Existing customers who already have an account.",
+  },
+  {
+    id: "method",
+    priority: "blocking",
+    question: "Which sign-in method should be available?",
+    why: "This changes the form, backend integration, recovery flow, and security behavior.",
+    choices: [
+      { value: "email-password", label: "Email and password", effect: "Familiar flow that requires password recovery.", recommended: true },
+      { value: "magic-link", label: "Magic link", effect: "No password field, but reliable email delivery is required." },
+      { value: "social", label: "Google or social login", effect: "Requires a third-party identity provider." },
+      { value: "existing-provider", label: "Existing authentication provider", effect: "Coordiation follows the provider contract already used by the project." },
+    ],
+    recommendedValue: "email-password",
+    example: "Email and password through our existing authentication API.",
+  },
+  {
+    id: "destination",
+    priority: "blocking",
+    question: "Where should users go after a successful login?",
+    why: "A clear destination makes success behavior testable and prevents ambiguous redirects.",
+    choices: [
+      { value: "/dashboard", label: "Main dashboard", effect: "Every successful login opens the primary workspace.", recommended: true },
+      { value: "original-page", label: "Originally requested page", effect: "Users continue the task that first required authentication." },
+      { value: "/account", label: "Account page", effect: "Users land on their profile or account overview." },
+    ],
+    recommendedValue: "/dashboard",
+    example: "Take successful users to /dashboard.",
+  },
+  {
+    id: "recovery",
+    priority: "recommended",
+    question: "Should the login include account recovery?",
+    why: "Password-based users need a safe way to regain access without support intervention.",
+    choices: [
+      { value: "forgot-password", label: "Forgot-password link", effect: "Adds a visible recovery path.", recommended: true },
+      { value: "support-only", label: "Contact support", effect: "Recovery is handled manually outside this page." },
+      { value: "not-needed", label: "No recovery", effect: "Suitable only when the selected authentication method has no password." },
+    ],
+    recommendedValue: "forgot-password",
+    example: "Show a forgot-password link below the password field.",
+  },
+  {
+    id: "registration",
+    priority: "recommended",
+    question: "Can new users create an account from this page?",
+    why: "Registration changes scope, fields, verification, legal consent, and navigation.",
+    choices: [
+      { value: "out-of-scope", label: "No, login only", effect: "Keeps this release focused on existing users.", recommended: true },
+      { value: "link-only", label: "Link to registration", effect: "The login page links to a separate registration flow." },
+      { value: "same-flow", label: "Login and registration together", effect: "Requires a larger combined authentication flow." },
+    ],
+    recommendedValue: "out-of-scope",
+    example: "Registration is out of scope for this page.",
+  },
+  {
+    id: "mfa",
+    priority: "recommended",
+    question: "Is multi-factor authentication required in this release?",
+    why: "MFA adds a second verification step and additional success, error, recovery, and trusted-device states.",
+    choices: [
+      { value: "not-in-first-release", label: "Not in the first release", effect: "Keep the initial login flow smaller and record MFA as future scope.", recommended: true },
+      { value: "required", label: "Required for everyone", effect: "Every successful credential check continues to a second factor." },
+      { value: "role-based", label: "Required for selected roles", effect: "The backend must return a role-aware MFA requirement." },
+    ],
+    recommendedValue: "not-in-first-release",
+    example: "MFA is not required in the first release.",
+  },
+  {
+    id: "auth-service",
+    priority: "blocking",
+    question: "What authentication service or API should the page use?",
+    why: "Development cannot safely invent endpoints, session rules, or provider configuration.",
+    choices: [
+      { value: "existing-api", label: "Existing project API", effect: "The implementation uses the current backend contract.", recommended: true },
+      { value: "provider-sdk", label: "Existing provider SDK", effect: "The implementation follows the installed identity provider." },
+      { value: "not-decided", label: "Not decided yet", effect: "The PRD remains draft and development cannot pass its gate." },
+    ],
+    recommendedValue: "existing-api",
+    example: "Use the existing POST /api/auth/login endpoint and current session cookie.",
+  },
+  {
+    id: "brand-tone",
+    priority: "optional",
+    question: "What visual tone should the login use?",
+    why: "A visual direction helps the UX and prototype stages choose suitable typography, spacing, and imagery.",
+    choices: [
+      { value: "current-system", label: "Current product design system", effect: "Reuse existing tokens and components.", recommended: true },
+      { value: "minimal", label: "Minimal and neutral", effect: "Use a quiet, focused form with little decoration." },
+      { value: "brand-led", label: "Strong brand presence", effect: "Use recognizable brand color, message, and imagery." },
+    ],
+    recommendedValue: "current-system",
+    example: "Use our current monochrome Coordiation design system.",
+  },
+  {
+    id: "success-check",
+    priority: "blocking",
+    question: "How will the team know the login works correctly?",
+    why: "A concrete success check becomes acceptance criteria and QA evidence.",
+    choices: [
+      { value: "redirect-and-session", label: "Redirect plus authenticated session", effect: "QA verifies both navigation and persisted authenticated state.", recommended: true },
+      { value: "redirect-only", label: "Successful redirect", effect: "QA checks navigation but does not prove session persistence." },
+      { value: "api-success", label: "Successful API response", effect: "QA validates the backend response but still needs a UI outcome." },
+    ],
+    recommendedValue: "redirect-and-session",
+    example: "Valid credentials create a session and redirect to /dashboard.",
+  },
+];
+
+function genericFeatureQuestions(capability) {
+  return [
+    {
+      id: "outcome",
+      priority: "blocking",
+      question: `What should people accomplish with this ${capability}?`,
+      why: "The user outcome keeps the product contract focused on a useful result instead of a collection of UI elements.",
+      choices: [
+        { value: "complete-primary-task", label: "Complete one primary task", effect: "The experience is optimized around one clear action.", recommended: true },
+        { value: "review-and-decide", label: "Review information and decide", effect: "The experience prioritizes comparison, context, and decision support." },
+        { value: "manage-existing-data", label: "Manage existing information", effect: "The experience prioritizes finding, editing, and organizing records." },
+      ],
+      recommendedValue: "complete-primary-task",
+      example: `People can complete the main ${capability} task without needing support.`,
+    },
+    {
+      id: "audience",
+      priority: "blocking",
+      question: `Who is the primary user of this ${capability}?`,
+      why: "The primary user determines language, permissions, complexity, and accessibility expectations.",
+      choices: [
+        { value: "customers", label: "Customers or public users", effect: "Use approachable language and avoid internal assumptions.", recommended: true },
+        { value: "staff", label: "Internal staff", effect: "The flow may use organization roles and operational terminology." },
+        { value: "administrators", label: "Administrators", effect: "The contract must include elevated permissions and safer destructive actions." },
+        { value: "multiple-roles", label: "Several user roles", effect: "Role-specific visibility and permissions become explicit requirements." },
+      ],
+      recommendedValue: "customers",
+      example: "Existing customers using the product on mobile and desktop.",
+    },
+    {
+      id: "primary-action",
+      priority: "blocking",
+      question: "What is the single most important action on this experience?",
+      why: "Naming one primary action creates a testable happy path and prevents competing calls to action.",
+      choices: [
+        { value: "submit", label: "Submit information", effect: "The contract centers on form completion and confirmation.", recommended: true },
+        { value: "select", label: "Find and select something", effect: "Search, filtering, comparison, and selection become central." },
+        { value: "review", label: "Review status or information", effect: "Hierarchy, freshness, and next steps become central." },
+        { value: "contact", label: "Start a conversation", effect: "The contract centers on a contact, booking, or inquiry path." },
+      ],
+      recommendedValue: "submit",
+      example: "The user submits the form and receives a clear confirmation.",
+    },
+    {
+      id: "entry-point",
+      priority: "recommended",
+      question: "How do users arrive at this experience?",
+      why: "Entry context determines navigation, prerequisite state, and what the page must explain.",
+      choices: [
+        { value: "main-navigation", label: "Main product navigation", effect: "The experience can rely on the product shell and signed-in context.", recommended: true },
+        { value: "direct-link", label: "Direct or shared link", effect: "The experience must stand on its own and handle missing context." },
+        { value: "previous-step", label: "Previous workflow step", effect: "The contract preserves data and progress from an earlier step." },
+      ],
+      recommendedValue: "main-navigation",
+      example: "Users open it from the main navigation after signing in.",
+    },
+    {
+      id: "data-source",
+      priority: "blocking",
+      question: "Where does the experience read or save its data?",
+      why: "An implementation cannot responsibly invent API fields, persistence rules, or ownership of sensitive data.",
+      choices: [
+        { value: "existing-api", label: "Existing project API", effect: "Development follows the current backend contract.", recommended: true },
+        { value: "local-static", label: "Local or static content", effect: "No remote persistence is required for the first release." },
+        { value: "third-party", label: "Third-party service", effect: "Credentials, limits, errors, and provider ownership must be documented." },
+        { value: "not-decided", label: "Not decided yet", effect: "The specification remains draft and cannot pass its gate." },
+      ],
+      recommendedValue: "existing-api",
+      example: "Use the existing project API and authenticated session.",
+    },
+    {
+      id: "success-behavior",
+      priority: "blocking",
+      question: "What should users see immediately after the primary action succeeds?",
+      why: "A visible success outcome becomes part of the acceptance and QA contract.",
+      choices: [
+        { value: "confirmation", label: "Confirmation in the same experience", effect: "Show a clear success state without changing location.", recommended: true },
+        { value: "detail-view", label: "Open the resulting detail view", effect: "Navigate to the created or selected record." },
+        { value: "next-step", label: "Continue to the next step", effect: "Move forward in a multi-step workflow." },
+      ],
+      recommendedValue: "confirmation",
+      example: "Show a confirmation with the saved result and the safest next action.",
+    },
+    {
+      id: "edge-states",
+      priority: "recommended",
+      question: "Which non-happy states must the first release handle?",
+      why: "Loading, empty, invalid, denied, and unavailable states are part of a complete product—not optional polish.",
+      choices: [
+        { value: "standard-complete", label: "Loading, empty, invalid, and unavailable", effect: "Covers the minimum complete state set.", recommended: true },
+        { value: "permission-aware", label: "Standard states plus permission denied", effect: "Adds role and access handling." },
+        { value: "offline-aware", label: "Standard states plus offline recovery", effect: "Adds connection-loss and retry behavior." },
+      ],
+      recommendedValue: "standard-complete",
+      example: "Handle loading, no data, validation failure, and service unavailable.",
+    },
+    {
+      id: "experience-constraints",
+      priority: "recommended",
+      question: "Which experience constraints are required?",
+      why: "Responsive and accessible behavior must be contractual so they survive design and implementation changes.",
+      choices: [
+        { value: "responsive-accessible", label: "Responsive and accessible", effect: "Require 320px support, keyboard completion, visible focus, labels, and announced status.", recommended: true },
+        { value: "desktop-accessible", label: "Desktop-first and accessible", effect: "Mobile optimization is deferred but accessibility remains required." },
+        { value: "project-contract", label: "Use the existing project contract", effect: "Inherit documented platform, localization, and accessibility requirements." },
+      ],
+      recommendedValue: "responsive-accessible",
+      example: "Support 320px upward, keyboard use, screen readers, and reduced motion.",
+    },
+    {
+      id: "verification",
+      priority: "blocking",
+      question: "How will the team verify that this feature is useful and working?",
+      why: "Verification turns an intention into acceptance criteria and concrete QA evidence.",
+      choices: [
+        { value: "outcome-and-state", label: "Primary outcome plus persisted state", effect: "QA verifies both the visible result and the underlying saved state.", recommended: true },
+        { value: "task-completion", label: "Successful task completion", effect: "QA verifies the happy path and required error recovery." },
+        { value: "analytics-event", label: "Task completion plus analytics event", effect: "QA also verifies a measurable product signal." },
+      ],
+      recommendedValue: "outcome-and-state",
+      example: "The primary task completes, the result persists after refresh, and required error states are recoverable.",
+    },
+  ];
+}
+
+function defineBuiltinTemplate({ id, intent, capability, aliases = [] }) {
+  return {
+    id,
+    intent,
+    capability,
+    aliases,
+    artifactStrategy: "generic-feature",
+    questions: genericFeatureQuestions(capability),
+    maxQuestionsPerTurn: 3,
+  };
+}
+
+const capabilityTemplateRegistry = new Map();
+
+export function registerCapabilityTemplate(template, { overwrite = false } = {}) {
+  if (!template || typeof template !== "object") throw new Error("A capability template object is required.");
+  const id = slug(template.id);
+  if (!id || !template.intent || !Array.isArray(template.questions) || template.questions.length === 0) throw new Error("A capability template requires id, intent, and questions.");
+  const maxQuestionsPerTurn = template.maxQuestionsPerTurn ?? 3;
+  if (!Number.isInteger(maxQuestionsPerTurn) || maxQuestionsPerTurn < 1 || maxQuestionsPerTurn > 3) throw new Error("Capability templates may ask between one and three questions per turn.");
+  const questionIds = new Set();
+  for (const question of template.questions) {
+    if (!question.id || !question.question || !question.why || !question.example || !question.recommendedValue) throw new Error(`Every ${id} question requires id, question, why, example, and recommendedValue.`);
+    if (questionIds.has(question.id)) throw new Error(`Duplicate ${id} question id: ${question.id}.`);
+    questionIds.add(question.id);
+    if (!Array.isArray(question.choices) || question.choices.length < 2 || question.choices.length > 4) throw new Error(`${id}.${question.id} requires two to four answer choices.`);
+    if (!question.choices.some(({ value }) => value === question.recommendedValue)) throw new Error(`${id}.${question.id} recommendation must match one of its choices.`);
+  }
+  const strategy = template.artifactStrategy ?? "generic-feature";
+  const requiredQuestionIds = strategy === "login"
+    ? ["audience", "method", "destination", "recovery", "registration", "mfa", "auth-service", "brand-tone", "success-check"]
+    : ["outcome", "audience", "primary-action", "entry-point", "data-source", "success-behavior", "edge-states", "experience-constraints", "verification"];
+  const missing = requiredQuestionIds.filter((questionId) => !questionIds.has(questionId));
+  if (missing.length) throw new Error(`${id} is missing required ${strategy} questions: ${missing.join(", ")}.`);
+  if (capabilityTemplateRegistry.has(id) && !overwrite) throw new Error(`Capability template already registered: ${id}.`);
+  const normalized = { ...template, id, artifactStrategy: strategy, aliases: [...new Set((template.aliases ?? []).map(slug))], maxQuestionsPerTurn };
+  capabilityTemplateRegistry.set(id, normalized);
+  return normalized;
+}
+
+registerCapabilityTemplate({
+  id: "login",
+  intent: "Create a complete login experience",
+  capability: "login experience",
+  aliases: ["login-page", "sign-in", "signin"],
+  artifactStrategy: "login",
+  questions: loginQuestions,
+  maxQuestionsPerTurn: 3,
+});
+
+for (const template of [
+  { id: "custom-feature", intent: "Define a custom product feature", capability: "product feature", aliases: ["feature", "custom"] },
+  { id: "dashboard", intent: "Create a useful dashboard", capability: "dashboard", aliases: ["overview", "analytics-dashboard"] },
+  { id: "landing-page", intent: "Create a focused landing page", capability: "landing page", aliases: ["landing", "marketing-page"] },
+  { id: "checkout", intent: "Create a recoverable checkout", capability: "checkout", aliases: ["payment", "purchase"] },
+  { id: "profile", intent: "Create a profile experience", capability: "profile experience", aliases: ["account-profile"] },
+  { id: "settings", intent: "Create a safe settings experience", capability: "settings experience", aliases: ["preferences"] },
+  { id: "search", intent: "Create a useful search experience", capability: "search experience", aliases: ["find"] },
+  { id: "upload", intent: "Create a reliable upload experience", capability: "upload experience", aliases: ["file-upload"] },
+  { id: "notifications", intent: "Create a manageable notification experience", capability: "notification experience", aliases: ["notification"] },
+]) registerCapabilityTemplate(defineBuiltinTemplate(template));
+
+export const interviewTemplates = Object.fromEntries([...capabilityTemplateRegistry.values()].flatMap((template) => [[template.id, template], ...template.aliases.map((alias) => [alias, template])]));
+
+export function listCapabilityTemplates() {
+  return [...capabilityTemplateRegistry.values()].map(({ id, intent, capability, aliases, questions, maxQuestionsPerTurn }) => ({ id, intent, capability, aliases, questionCount: questions.length, maxQuestionsPerTurn }));
+}
+
+export function resolveCapabilityTemplate(intent) {
+  const requested = String(intent ?? "").trim();
+  if (!requested) throw new Error("A capability intent is required.");
+  const normalized = slug(requested);
+  for (const template of capabilityTemplateRegistry.values()) {
+    if (template.id === normalized || template.aliases.includes(normalized)) return template;
+  }
+  const detected = [...capabilityTemplateRegistry.values()].find((template) => [template.id, ...template.aliases].some((candidate) => normalized.includes(candidate)));
+  if (detected) return detected;
+  return defineBuiltinTemplate({ id: normalized, intent: `Define ${requested}`, capability: requested, aliases: [] });
+}
+
+async function exists(pathname) {
+  try { await access(pathname, constants.F_OK); return true; } catch { return false; }
+}
+
+function projectPath(cwd, pathname) {
+  const root = resolve(cwd);
+  const destination = resolve(root, pathname);
+  if (destination !== root && !destination.startsWith(`${root}${sep}`)) throw new Error(`Lifecycle path leaves the project: ${pathname}`);
+  return destination;
+}
+
+async function readJson(filename) {
+  return JSON.parse(await readFile(filename, "utf8"));
+}
+
+async function writeJson(filename, value) {
+  await mkdir(dirname(filename), { recursive: true });
+  await writeFile(filename, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function now(clock) {
+  return (clock?.() ?? new Date()).toISOString();
+}
+
+function slug(value) {
+  return String(value ?? "coordiation-product").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "coordiation-product";
+}
+
+function relativePath(cwd, filename) {
+  return relative(resolve(cwd), filename).split(sep).join("/");
+}
+
+function stageDirectory(stage) {
+  return stage === "specification" ? "specification" : stage;
+}
+
+export async function initializeLifecycleProject({ cwd = process.cwd(), name, ownerName, ownerEmail, clock } = {}) {
+  const root = resolve(cwd);
+  const projectFile = projectPath(root, PROJECT_PATH);
+  if (await exists(projectFile)) {
+    const evidenceFile = projectPath(root, EVIDENCE_PATH);
+    if (!(await exists(evidenceFile))) await writeJson(evidenceFile, { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-evidence", records: [], updatedAt: now(clock) });
+    else {
+      const ledger = await readJson(evidenceFile);
+      let migrated = false;
+      for (const record of ledger.records ?? []) {
+        if (!Number.isInteger(record.artifactRevision)) {
+          record.artifactRevision = 1;
+          migrated = true;
+        }
+      }
+      if (migrated) {
+        ledger.updatedAt = now(clock);
+        await writeJson(evidenceFile, ledger);
+      }
+    }
+    return { created: false, project: await readJson(projectFile), paths: [PROJECT_PATH, LIFECYCLE_PATH, TRACEABILITY_PATH, APPROVALS_PATH, EVIDENCE_PATH] };
+  }
+  const timestamp = now(clock);
+  const projectName = name || basename(root);
+  const owner = { name: ownerName || "Project owner", email: ownerEmail || null, role: "owner" };
+  const project = {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    kind: "coordiation-product-project",
+    id: slug(projectName),
+    name: projectName,
+    artifactFormat: "canonical-json-with-generated-markdown",
+    owners: [owner],
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+  const lifecycle = {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    kind: "coordiation-lifecycle",
+    currentStage: "specification",
+    stages: LIFECYCLE_STAGES.map((stage, index) => ({ id: stage, order: index + 1, status: index === 0 ? "active" : "pending", gate: LIFECYCLE_GATES[stage] })),
+    gates: LIFECYCLE_STAGES.map((stage) => ({ id: LIFECYCLE_GATES[stage], stage, status: "pending", approvalId: null })),
+    updatedAt: timestamp,
+  };
+  const traceability = { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-traceability", nodes: [], edges: [], updatedAt: timestamp };
+  const approvals = { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-approvals", approvals: [], updatedAt: timestamp };
+  const evidence = { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-evidence", records: [], updatedAt: timestamp };
+  await Promise.all([
+    writeJson(projectFile, project),
+    writeJson(projectPath(root, LIFECYCLE_PATH), lifecycle),
+    writeJson(projectPath(root, TRACEABILITY_PATH), traceability),
+    writeJson(projectPath(root, APPROVALS_PATH), approvals),
+    writeJson(projectPath(root, EVIDENCE_PATH), evidence),
+    ...LIFECYCLE_STAGES.map((stage) => mkdir(projectPath(root, join(ARTIFACT_DIRECTORY, stageDirectory(stage))), { recursive: true })),
+    mkdir(projectPath(root, join(COORDIATION_DIRECTORY, "interviews")), { recursive: true }),
+    mkdir(projectPath(root, join(COORDIATION_DIRECTORY, "context")), { recursive: true }),
+  ]);
+  return { created: true, project, paths: [PROJECT_PATH, LIFECYCLE_PATH, TRACEABILITY_PATH, APPROVALS_PATH, EVIDENCE_PATH] };
+}
+
+async function requireInitialized(cwd) {
+  const projectFile = projectPath(cwd, PROJECT_PATH);
+  if (!(await exists(projectFile))) throw new Error("Coordiation lifecycle is not initialized. Run `coordiation init` first.");
+}
+
+async function artifactFiles(cwd) {
+  const files = [];
+  for (const stage of LIFECYCLE_STAGES) {
+    const directory = projectPath(cwd, join(ARTIFACT_DIRECTORY, stageDirectory(stage)));
+    let entries = [];
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".json")) files.push(join(directory, entry.name));
+  }
+  return files.sort();
+}
+
+export async function getLifecycleStatus({ cwd = process.cwd() } = {}) {
+  await requireInitialized(cwd);
+  const [project, lifecycle, approvals, files] = await Promise.all([
+    readJson(projectPath(cwd, PROJECT_PATH)),
+    readJson(projectPath(cwd, LIFECYCLE_PATH)),
+    readJson(projectPath(cwd, APPROVALS_PATH)),
+    artifactFiles(cwd),
+  ]);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  return {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    kind: "coordiation-lifecycle-status",
+    project: { id: project.id, name: project.name },
+    currentStage: lifecycle.currentStage,
+    stages: lifecycle.stages,
+    gates: lifecycle.gates,
+    artifactCount: artifacts.length,
+    artifacts: artifacts.map(({ id, kind, stage, status, revision }) => ({ id, kind, stage, status, revision })),
+    approvalCount: approvals.approvals.length,
+  };
+}
+
+function publicQuestion(question) {
+  return {
+    id: question.id,
+    priority: question.priority,
+    question: question.question,
+    why: question.why,
+    choices: question.choices,
+    recommendedValue: question.recommendedValue,
+    example: question.example,
+    customAnswerAllowed: true,
+    unknownUsesRecommendation: true,
+  };
+}
+
+function normalizeAnswer(question, answer) {
+  const value = String(answer ?? "").trim();
+  if (!value) throw new Error(`Answer for ${question.id} cannot be empty.`);
+  if (["recommended", "recommendation", "default", "i don't know", "i dont know", "tidak tahu", "gunakan rekomendasi"].includes(value.toLowerCase())) {
+    return { value: question.recommendedValue, source: "user-confirmed-recommendation" };
+  }
+  return { value, source: "user" };
+}
+
+function answerValue(session, id) {
+  return session.answers[id]?.value;
+}
+
+function artifactEnvelope({ id, kind, title, stage, timestamp, body, derivedFrom = [], acceptanceCriteria = [] }) {
+  return {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    id,
+    kind,
+    title,
+    stage,
+    status: "draft",
+    revision: 1,
+    owners: ["product"],
+    derivedFrom,
+    acceptanceCriteria,
+    dependencies: [],
+    risks: [],
+    evidence: [],
+    approvals: [],
+    body,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+}
+
+function markdownArtifact(artifact) {
+  const lines = [
+    `# ${artifact.id} — ${artifact.title}`,
+    "",
+    `Status: ${artifact.status}`,
+    "",
+    `Revision: ${artifact.revision}`,
+    "",
+    `Stage: ${artifact.stage}`,
+    "",
+  ];
+  for (const [key, value] of Object.entries(artifact.body)) {
+    lines.push(`## ${key.replace(/([A-Z])/g, " $1").replace(/^./, (character) => character.toUpperCase())}`, "");
+    if (Array.isArray(value)) for (const item of value) lines.push(`- ${typeof item === "string" ? item : JSON.stringify(item)}`);
+    else lines.push(String(value));
+    lines.push("");
+  }
+  if (artifact.acceptanceCriteria.length) {
+    lines.push("## Acceptance criteria", "");
+    for (const criterion of artifact.acceptanceCriteria) lines.push(`- ${criterion}`);
+    lines.push("");
+  }
+  return `${lines.join("\n").trim()}\n`;
+}
+
+async function writeArtifact(cwd, artifact) {
+  const base = projectPath(cwd, join(ARTIFACT_DIRECTORY, stageDirectory(artifact.stage), artifact.id));
+  await writeJson(`${base}.json`, artifact);
+  await writeFile(`${base}.md`, markdownArtifact(artifact));
+  return { json: relativePath(cwd, `${base}.json`), markdown: relativePath(cwd, `${base}.md`) };
+}
+
+function artifactId(prefix, number) {
+  return `${prefix}-${String(number).padStart(3, "0")}`;
+}
+
+async function allocateArtifactIds(cwd, acceptanceCriterionCount = 6) {
+  const artifacts = await Promise.all((await artifactFiles(cwd)).map((file) => readJson(file)));
+  const numbers = (prefix) => artifacts
+    .map(({ id }) => new RegExp(`^${prefix}-(\\d+)$`).exec(id)?.[1])
+    .filter(Boolean)
+    .map(Number);
+  const contractNumber = Math.max(0, ...numbers("SPEC"), ...numbers("PRD")) + 1;
+  const firstCriterion = Math.max(0, ...numbers("AC")) + 1;
+  return {
+    specification: artifactId("SPEC", contractNumber),
+    prd: artifactId("PRD", contractNumber),
+    acceptanceCriteria: Array.from({ length: acceptanceCriterionCount }, (_, index) => artifactId("AC", firstCriterion + index)),
+  };
+}
+
+function createLoginArtifacts(session, timestamp, ids) {
+  const audience = answerValue(session, "audience");
+  const method = answerValue(session, "method");
+  const destination = answerValue(session, "destination");
+  const recovery = answerValue(session, "recovery");
+  const registration = answerValue(session, "registration");
+  const mfa = answerValue(session, "mfa");
+  const authService = answerValue(session, "auth-service");
+  const brandTone = answerValue(session, "brand-tone");
+  const successCheck = answerValue(session, "success-check");
+  const openDecisions = authService === "not-decided"
+    ? ["Choose and document the authentication service or API contract."]
+    : [];
+  const acceptanceCriteria = ids.acceptanceCriteria;
+  const specification = artifactEnvelope({
+    id: ids.specification,
+    kind: "product-specification",
+    title: "Provide a clear and secure login experience",
+    stage: "specification",
+    timestamp,
+    body: {
+      problem: `${audience} need a clear and secure way to access the authenticated product area.`,
+      desiredOutcome: `A successful login establishes authenticated state and continues to ${destination}.`,
+      authenticationMethod: method,
+      constraints: [`Authentication integration: ${authService}`, "Responsive and keyboard-accessible behavior is required.", "Errors must not reveal whether a specific account exists."],
+      nonGoals: [`Registration: ${registration}`, `Multi-factor authentication: ${mfa}`],
+      successSignal: successCheck,
+      visualDirection: brandTone,
+      openDecisions,
+    },
+  });
+  const prd = artifactEnvelope({
+    id: ids.prd,
+    kind: "product-requirement-document",
+    title: "Login page product contract",
+    stage: "prd",
+    timestamp,
+    derivedFrom: [ids.specification],
+    acceptanceCriteria,
+    body: {
+      scope: [`Authenticate ${audience} using ${method}.`, `Continue successful users to ${destination}.`, `Provide recovery behavior: ${recovery}.`, "Cover idle, submitting, success, invalid input, invalid credentials, lockout or rate limit, and service unavailable states."],
+      nonScope: [`Registration behavior: ${registration}.`, `MFA behavior: ${mfa}.`],
+      integration: authService,
+      responsive: "Required from 320px upward without horizontal overflow.",
+      accessibility: "Keyboard completion, visible focus, associated labels, announced errors, and non-color-only status are required.",
+      security: "Use the existing authentication contract, avoid account enumeration, preserve secure session handling, and never log credentials.",
+      openDecisions,
+    },
+  });
+  const statements = [
+    `Valid credentials create authenticated state and continue to ${destination}.`,
+    "Invalid credentials show a non-enumerating inline error without clearing the identifier.",
+    "Keyboard and screen-reader users can identify, complete, submit, and recover from errors in the form.",
+    `The login exposes the confirmed recovery behavior: ${recovery}.`,
+    "Submitting, locked or rate-limited, and service-unavailable states prevent duplicate submission and explain the next action.",
+    "The page remains readable and free of horizontal overflow from 320px through desktop layouts.",
+  ];
+  const criteria = statements.map((statement, index) => artifactEnvelope({ id: acceptanceCriteria[index], kind: "acceptance-criterion", title: statement, stage: "prd", timestamp, derivedFrom: [ids.prd], body: { statement } }));
+  return [specification, prd, ...criteria];
+}
+
+function createGenericFeatureArtifacts(session, template, timestamp, ids) {
+  const outcome = answerValue(session, "outcome");
+  const audience = answerValue(session, "audience");
+  const primaryAction = answerValue(session, "primary-action");
+  const entryPoint = answerValue(session, "entry-point");
+  const dataSource = answerValue(session, "data-source");
+  const successBehavior = answerValue(session, "success-behavior");
+  const edgeStates = answerValue(session, "edge-states");
+  const experienceConstraints = answerValue(session, "experience-constraints");
+  const verification = answerValue(session, "verification");
+  const capability = template.capability;
+  const openDecisions = dataSource === "not-decided" ? ["Choose and document the data source or persistence contract."] : [];
+  const specification = artifactEnvelope({
+    id: ids.specification,
+    kind: "product-specification",
+    title: `Enable a useful ${capability}`,
+    stage: "specification",
+    timestamp,
+    body: {
+      capability,
+      problem: `${audience} need a clear way to use the ${capability} and achieve ${outcome}.`,
+      desiredOutcome: `Users can ${primaryAction} and receive ${successBehavior}.`,
+      entryPoint,
+      constraints: [`Data contract: ${dataSource}`, `Experience contract: ${experienceConstraints}`],
+      requiredStates: edgeStates,
+      successSignal: verification,
+      nonGoals: ["Capabilities not confirmed by this interview are outside the first release."],
+      openDecisions,
+    },
+  });
+  const prd = artifactEnvelope({
+    id: ids.prd,
+    kind: "product-requirement-document",
+    title: `${capability} product contract`,
+    stage: "prd",
+    timestamp,
+    derivedFrom: [ids.specification],
+    acceptanceCriteria: ids.acceptanceCriteria,
+    body: {
+      capability,
+      scope: [`Serve ${audience}.`, `Support the primary action: ${primaryAction}.`, `Enter through: ${entryPoint}.`, `Show success behavior: ${successBehavior}.`, `Handle states: ${edgeStates}.`],
+      integration: dataSource,
+      responsive: experienceConstraints === "desktop-accessible" ? "Desktop-first; smaller viewports are explicitly deferred." : "Required from 320px upward without horizontal overflow.",
+      accessibility: "Keyboard completion, visible focus, associated labels, announced status, and non-color-only feedback are required.",
+      verification,
+      nonScope: ["Unconfirmed secondary workflows and integrations."],
+      openDecisions,
+    },
+  });
+  const statements = [
+    `${audience} can complete ${primaryAction} and receive ${successBehavior}.`,
+    `The experience handles ${edgeStates} with a clear explanation and next action.`,
+    `Data reads and writes follow the confirmed contract: ${dataSource}.`,
+    "Keyboard and screen-reader users can understand, complete, and recover from the primary workflow.",
+    experienceConstraints === "desktop-accessible" ? "The supported desktop layout remains readable without clipped content." : "The experience remains readable and free of horizontal overflow from 320px through desktop layouts.",
+    `QA records evidence for the confirmed verification method: ${verification}.`,
+  ];
+  const criteria = statements.map((statement, index) => artifactEnvelope({ id: ids.acceptanceCriteria[index], kind: "acceptance-criterion", title: statement, stage: "prd", timestamp, derivedFrom: [ids.prd], body: { statement } }));
+  return [specification, prd, ...criteria];
+}
+
+async function finalizeInterview(cwd, session, template, timestamp) {
+  const ids = await allocateArtifactIds(cwd);
+  const artifacts = template.artifactStrategy === "login"
+    ? createLoginArtifacts(session, timestamp, ids)
+    : createGenericFeatureArtifacts(session, template, timestamp, ids);
+  const paths = [];
+  for (const artifact of artifacts) paths.push({ id: artifact.id, ...(await writeArtifact(cwd, artifact)) });
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  const nodes = artifacts.map((artifact) => ({ id: artifact.id, kind: artifact.kind, stage: artifact.stage, status: artifact.status, revision: artifact.revision, path: paths.find((entry) => entry.id === artifact.id).json }));
+  const edges = [
+    { from: ids.prd, to: ids.specification, relation: "derives_from" },
+    ...artifacts.filter((artifact) => artifact.kind === "acceptance-criterion").map((artifact) => ({ from: artifact.id, to: ids.prd, relation: "derives_from" })),
+  ];
+  trace.nodes = [...trace.nodes.filter((node) => !nodes.some((candidate) => candidate.id === node.id)), ...nodes];
+  trace.edges = [...trace.edges.filter((edge) => !edges.some((candidate) => candidate.from === edge.from && candidate.to === edge.to && candidate.relation === edge.relation)), ...edges];
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  session.status = "completed";
+  session.completedAt = timestamp;
+  session.generatedArtifacts = paths;
+  return paths;
+}
+
+export async function runRequirementInterview({ cwd = process.cwd(), intent = "login", answers = {}, clock } = {}) {
+  await requireInitialized(cwd);
+  const template = resolveCapabilityTemplate(intent);
+  const timestamp = now(clock);
+  const sessionFile = projectPath(cwd, join(COORDIATION_DIRECTORY, "interviews", `${template.id}.json`));
+  const session = await exists(sessionFile) ? await readJson(sessionFile) : {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    kind: "coordiation-requirement-interview",
+    id: `INTERVIEW-${template.id.toUpperCase()}-001`,
+    intent: template.id,
+    status: "active",
+    maxQuestionsPerTurn: template.maxQuestionsPerTurn,
+    answers: {},
+    generatedArtifacts: [],
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+  if (session.status === "completed" && Object.keys(answers).length) throw new Error(`The ${template.id} interview is already completed. Start a new artifact revision before changing confirmed answers.`);
+  for (const [id, answer] of Object.entries(answers)) {
+    const question = template.questions.find((entry) => entry.id === id);
+    if (!question) throw new Error(`Unknown ${template.id} interview question: ${id}.`);
+    session.answers[id] = { ...normalizeAnswer(question, answer), answeredAt: timestamp };
+  }
+  session.updatedAt = timestamp;
+  const unanswered = template.questions.filter((question) => !session.answers[question.id]);
+  if (unanswered.length === 0 && session.status !== "completed") await finalizeInterview(cwd, session, template, timestamp);
+  await writeJson(sessionFile, session);
+  return {
+    schemaVersion: LIFECYCLE_SCHEMA_VERSION,
+    kind: "coordiation-interview-result",
+    id: session.id,
+    intent: session.intent,
+    status: session.status,
+    answered: Object.keys(session.answers).length,
+    totalQuestions: template.questions.length,
+    nextQuestions: session.status === "completed" ? [] : unanswered.slice(0, template.maxQuestionsPerTurn).map(publicQuestion),
+    generatedArtifacts: session.generatedArtifacts,
+    sessionPath: relativePath(cwd, sessionFile),
+  };
+}
+
+async function loadArtifact(cwd, artifactId) {
+  const normalized = String(artifactId).trim().toUpperCase();
+  for (const file of await artifactFiles(cwd)) {
+    const artifact = await readJson(file);
+    if (artifact.id === normalized) return { artifact, file };
+  }
+  throw new Error(`Unknown lifecycle artifact: ${artifactId}.`);
+}
+
+function uxScreenStates(prd) {
+  const capability = prd.body.capability ?? "login experience";
+  if (capability === "login experience" || /login/i.test(prd.title)) {
+    return [
+      { id: "idle", purpose: "Explain the login and accept credentials.", content: ["Identifier field", "Password field", "Primary sign-in action", "Recovery path"], actions: ["Enter credentials", "Submit", "Open recovery"] },
+      { id: "submitting", purpose: "Prevent duplicate submission while authentication is in progress.", content: ["Progress status", "Preserved identifier"], actions: ["Wait"] },
+      { id: "invalid-input", purpose: "Explain correctable field-level problems.", content: ["Associated field errors", "Summary when several fields fail"], actions: ["Correct input", "Submit again"] },
+      { id: "invalid-credentials", purpose: "Explain authentication failure without revealing whether an account exists.", content: ["Non-enumerating error", "Recovery path"], actions: ["Try again", "Open recovery"] },
+      { id: "rate-limited", purpose: "Protect the account and explain when another attempt is safe.", content: ["Temporary restriction", "Safe next step"], actions: ["Wait", "Open support or recovery"] },
+      { id: "service-unavailable", purpose: "Preserve user input and provide a recoverable service failure.", content: ["Availability message", "Retry guidance"], actions: ["Retry"] },
+      { id: "success", purpose: "Confirm authenticated state before continuing.", content: ["Authenticated status"], actions: ["Continue to the confirmed destination"] },
+    ];
+  }
+  const states = [
+    { id: "idle", purpose: `Orient the user within the ${capability}.`, content: ["Purpose", "Current data", "Primary action"], actions: ["Begin the primary task"] },
+    { id: "loading", purpose: "Explain that required information is being retrieved.", content: ["Progress status", "Stable layout skeleton"], actions: ["Wait"] },
+    { id: "empty", purpose: "Explain why no information is available and how to continue.", content: ["Empty-state reason", "Recommended next action"], actions: ["Start the primary task"] },
+    { id: "invalid", purpose: "Explain correctable validation or business-rule failures.", content: ["Associated errors", "Preserved user input"], actions: ["Correct input", "Try again"] },
+    { id: "service-unavailable", purpose: "Make a temporary dependency failure recoverable.", content: ["Availability message", "Retry guidance"], actions: ["Retry"] },
+    { id: "success", purpose: "Confirm the completed outcome and resulting state.", content: ["Result summary", "Safe next action"], actions: ["Review result", "Continue"] },
+  ];
+  const requiredStates = String(prd.body.scope?.find((entry) => entry.startsWith("Handle states:")) ?? "").toLowerCase();
+  if (requiredStates.includes("permission")) states.splice(-1, 0, { id: "permission-denied", purpose: "Explain missing access without exposing restricted information.", content: ["Access status", "Safe escalation path"], actions: ["Return", "Request access"] });
+  if (requiredStates.includes("offline")) states.splice(-1, 0, { id: "offline", purpose: "Preserve progress while the connection is unavailable.", content: ["Connection status", "Preserved work"], actions: ["Retry when online"] });
+  return states;
+}
+
+function uxPrimaryFlow(prd) {
+  const capability = prd.body.capability ?? "login experience";
+  if (capability === "login experience" || /login/i.test(prd.title)) {
+    return [
+      { step: 1, actor: "user", action: "Open the login experience", outcome: "The idle state explains the required credentials and recovery path." },
+      { step: 2, actor: "user", action: "Enter and submit credentials", outcome: "Input is validated and duplicate submission is prevented." },
+      { step: 3, actor: "system", action: "Authenticate through the confirmed integration", outcome: "The system returns success or a safe, recoverable failure." },
+      { step: 4, actor: "system", action: "Establish authenticated state", outcome: "The user continues to the PRD destination." },
+    ];
+  }
+  return [
+    { step: 1, actor: "user", action: "Enter from the confirmed entry point", outcome: `The ${capability} explains context and the primary action.` },
+    { step: 2, actor: "system", action: "Load required data and permissions", outcome: "Loading, empty, denied, or ready state is explicit." },
+    { step: 3, actor: "user", action: "Complete the primary action", outcome: "Input and business rules are validated without losing work." },
+    { step: 4, actor: "system", action: "Persist or apply the confirmed outcome", outcome: "The system uses the PRD data contract." },
+    { step: 5, actor: "system", action: "Present success and the safest next action", outcome: "The user can verify the result and continue." },
+  ];
+}
+
+function uxNumberFor(prd, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(prd.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("UX-")).map(({ id }) => Number(id.slice(3))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+export async function createUxContract({ cwd = process.cwd(), prdId, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: prd } = await loadArtifact(cwd, prdId);
+  if (prd.stage !== "prd" || prd.kind !== "product-requirement-document") throw new Error(`${prd.id} is not a PRD artifact.`);
+  if (prd.status !== "approved") throw new Error(`${prd.id} must be approved before deriving UX.`);
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "ux" && artifact.status !== "superseded" && artifact.derivedFrom.includes(prd.id));
+  if (existing) return { created: false, artifact: existing, paths: { json: `artifacts/ux/${existing.id}.json`, markdown: `artifacts/ux/${existing.id}.md` } };
+  const timestamp = now(clock);
+  const id = artifactId("UX", uxNumberFor(prd, artifacts));
+  const screenStates = uxScreenStates(prd);
+  const ux = artifactEnvelope({
+    id,
+    kind: "ux-contract",
+    title: `${prd.body.capability ?? "Login experience"} UX contract`,
+    stage: "ux",
+    timestamp,
+    derivedFrom: [prd.id],
+    acceptanceCriteria: prd.acceptanceCriteria,
+    body: {
+      capability: prd.body.capability ?? "login experience",
+      primaryFlow: uxPrimaryFlow(prd),
+      screenStates,
+      informationArchitecture: { primaryRegion: "Task context and primary action", secondaryRegion: "Supporting information and safe next actions", navigation: "Preserve the confirmed entry and return path." },
+      interactionContract: ["One visually dominant primary action per state.", "Submitting actions expose progress and prevent accidental duplication.", "Errors preserve recoverable input and remain adjacent to their source.", "Success communicates the resulting state and safest next action."],
+      responsiveContract: { minimumViewport: "320px", requirements: ["No horizontal page overflow.", "Touch targets remain operable.", "Reading and focus order remain logical.", "Primary actions remain visible without covering content."] },
+      accessibilityContract: { keyboard: "The complete primary flow works without a pointer.", focus: "Focus is visible, ordered, and moved only when context changes materially.", semantics: "Landmarks, headings, labels, descriptions, and status messages expose their purpose.", motion: "Non-essential motion respects prefers-reduced-motion.", errors: "Errors are associated, announced, and never communicated by color alone." },
+      contentContract: ["Use plain, action-oriented language.", "Explain what happened and what the user can do next.", "Do not expose sensitive existence, permission, or system details."],
+      verificationPlan: prd.acceptanceCriteria.map((criterionId) => ({ criterionId, evidence: "UX state or flow reference plus prototype and QA evidence in downstream stages." })),
+      openDecisions: [...(prd.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, ux);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: ux.id, kind: ux.kind, stage: ux.stage, status: ux.status, revision: ux.revision, path: paths.json });
+  trace.edges.push(
+    { from: ux.id, to: prd.id, relation: "derives_from" },
+    ...ux.acceptanceCriteria.map((criterionId) => ({ from: ux.id, to: criterionId, relation: "satisfies" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: ux, paths };
+}
+
+function prototypeComponentPlan(ux) {
+  const capability = ux.body.capability;
+  const common = [
+    { registryId: "typography", role: "Semantic headings, instructions, metadata, and status copy." },
+    { registryId: "button", role: "Primary, secondary, retry, and safe navigation actions." },
+    { registryId: "alert", role: "Associated error, warning, unavailable, and success feedback." },
+    { registryId: "skeleton", role: "Stable loading placeholders without layout shift." },
+  ];
+  if (capability === "login experience") return [
+    { registryId: "card", role: "Bounded authentication surface and supporting content." },
+    { registryId: "field", role: "Label, description, control, and associated validation message." },
+    { registryId: "input", role: "Identifier and password entry using native input semantics." },
+    { registryId: "spinner", role: "Submitting status inside the primary action." },
+    ...common,
+  ];
+  if (/dashboard/i.test(capability)) return [
+    { registryId: "sidebar", role: "Responsive product navigation and current-location context." },
+    { registryId: "navigation-menu", role: "Primary destinations and keyboard navigation." },
+    { registryId: "card", role: "Summary metrics and bounded information groups." },
+    { registryId: "data-table", role: "Structured records with semantic headers and actions." },
+    { registryId: "chart", role: "Data visualization with an equivalent textual summary." },
+    { registryId: "badge", role: "Compact status with text, never color alone." },
+    { registryId: "select", role: "Explicit time range or view selection." },
+    { registryId: "empty", role: "No-data explanation and recommended next action." },
+    ...common,
+  ];
+  return [
+    { registryId: "card", role: "Primary task region and supporting information." },
+    { registryId: "field", role: "Label, description, input, and associated error composition." },
+    { registryId: "input", role: "Native text or data entry where required by the PRD." },
+    { registryId: "empty", role: "No-data state with a useful next action." },
+    { registryId: "spinner", role: "Compact progress status for actions." },
+    ...common,
+  ];
+}
+
+function prototypeLayout(ux) {
+  const dashboard = /dashboard/i.test(ux.body.capability);
+  return {
+    shell: dashboard
+      ? ["co-min-h-screen", "co-grid", "co-grid-cols-1", "lg:co-grid-cols-4"]
+      : ["co-min-h-screen", "co-flex", "co-items-center", "co-justify-center", "co-p-4"],
+    content: dashboard
+      ? ["co-w-full", "co-grid", "co-gap-6", "co-p-4", "md:co-grid-cols-2", "lg:co-col-span-3"]
+      : ["co-w-full", "co-grid", "co-gap-4", "md:co-max-w-lg"],
+    rules: [
+      "Keep every Coordiation utility candidate literal; do not construct co-* classes dynamically.",
+      "Preserve DOM order as the reading and keyboard order at every viewport.",
+      "Use intrinsic sizing and wrapping before introducing fixed dimensions.",
+      "Do not allow page-level horizontal overflow at 320px.",
+    ],
+  };
+}
+
+function prototypeNumberFor(ux, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(ux.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("PROTO-")).map(({ id }) => Number(id.slice(6))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+export async function createPrototypeContract({ cwd = process.cwd(), uxId, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: ux } = await loadArtifact(cwd, uxId);
+  if (ux.stage !== "ux" || ux.kind !== "ux-contract") throw new Error(`${ux.id} is not a UX contract.`);
+  if (ux.status !== "approved") throw new Error(`${ux.id} must be approved before deriving a prototype.`);
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.status !== "superseded" && artifact.derivedFrom.includes(ux.id));
+  if (existing) return { created: false, artifact: existing, paths: { json: `artifacts/prototype/${existing.id}.json`, markdown: `artifacts/prototype/${existing.id}.md` } };
+  const timestamp = now(clock);
+  const id = artifactId("PROTO", prototypeNumberFor(ux, artifacts));
+  const componentPlan = prototypeComponentPlan(ux);
+  const prototype = artifactEnvelope({
+    id,
+    kind: "prototype-contract",
+    title: `${ux.body.capability} interactive prototype contract`,
+    stage: "prototype",
+    timestamp,
+    derivedFrom: [ux.id],
+    acceptanceCriteria: ux.acceptanceCriteria,
+    body: {
+      capability: ux.body.capability,
+      fidelity: "Interactive, state-complete, implementation-oriented prototype using mock adapters.",
+      frameworkContract: { css: "@coordiation/css with literal co-* candidates", components: "Owned source installed from @coordiation/ui", icons: "Use @coordiation/icons components; raw inline SVG and Unicode arrow substitutes are not allowed.", runtime: "Use the target framework only for state and interaction; Coordiation CSS adds no browser runtime." },
+      componentPlan,
+      layoutContract: prototypeLayout(ux),
+      statePreviews: ux.body.screenStates.map((state) => ({ id: state.id, fixture: `Deterministic ${state.id} fixture`, purpose: state.purpose, visibleContent: state.content, availableActions: state.actions, componentIds: componentPlan.map(({ registryId }) => registryId) })),
+      interactionMap: ux.body.primaryFlow.map((flowStep) => ({ step: flowStep.step, trigger: flowStep.actor === "user" ? flowStep.action : `system:${flowStep.action}`, expectedOutcome: flowStep.outcome, keyboardRequired: true })),
+      viewportMatrix: [
+        { width: 320, label: "compact", requirement: "Single-column, no page overflow, operable touch and keyboard targets." },
+        { width: 768, label: "medium", requirement: "Use available space without changing reading or focus order." },
+        { width: 1280, label: "wide", requirement: "Apply the confirmed multi-region layout without excessive line length." },
+      ],
+      motionContract: { classes: ["co-transition", "co-duration-200", "co-ease-out", "motion-reduce:co-duration-0"], rules: ["Animate only opacity and transform when possible.", "Motion must explain state or spatial change, not delay task completion.", "Reduced-motion mode removes non-essential movement while preserving status feedback."] },
+      mockAdapter: { policy: "No production credentials or undocumented endpoints.", fixtures: ux.body.screenStates.map(({ id }) => id), reset: "Every state preview can be opened directly and reset deterministically." },
+      evidenceRequirements: { screenshots: ux.body.screenStates.flatMap(({ id: stateId }) => [320, 768, 1280].map((width) => ({ stateId, width }))), keyboardPath: "Record focus order and successful keyboard-only completion of the primary flow.", accessibility: "Record automated checks plus manual labels, status announcement, contrast, zoom, and reduced-motion observations.", acceptanceCriteria: ux.acceptanceCriteria.map((criterionId) => ({ criterionId, requiredEvidence: "Linked state preview, viewport evidence, or interaction recording." })) },
+      openDecisions: [...(ux.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, prototype);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: prototype.id, kind: prototype.kind, stage: prototype.stage, status: prototype.status, revision: prototype.revision, path: paths.json });
+  trace.edges.push(
+    { from: prototype.id, to: ux.id, relation: "derives_from" },
+    ...prototype.acceptanceCriteria.map((criterionId) => ({ from: prototype.id, to: criterionId, relation: "satisfies" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: prototype, paths };
+}
+
+async function detectDevelopmentTarget(cwd) {
+  const packageFile = projectPath(cwd, "package.json");
+  let dependencies = {};
+  if (await exists(packageFile)) {
+    const packageJson = await readJson(packageFile);
+    dependencies = { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}) };
+  }
+  if (dependencies.next) return { framework: "Next.js", language: "TypeScript/React", extension: "tsx", sourceRoot: "src/features", nativeComponentModel: "React Server and Client Components as required by interaction." };
+  if (dependencies.react) return { framework: "React", language: "TypeScript/React", extension: "tsx", sourceRoot: "src/features", nativeComponentModel: "React components and hooks only where state is required." };
+  if (dependencies.svelte || dependencies["@sveltejs/kit"]) return { framework: "Svelte", language: "Svelte/TypeScript", extension: "svelte", sourceRoot: "src/lib/features", nativeComponentModel: "Native Svelte components and stores." };
+  if (dependencies.astro) return { framework: "Astro", language: "Astro/TypeScript", extension: "astro", sourceRoot: "src/components", nativeComponentModel: "Astro components with isolated interactive islands." };
+  if (await exists(projectPath(cwd, "composer.json"))) return { framework: "Laravel/PHP", language: "Blade/PHP", extension: "blade.php", sourceRoot: "resources/views", nativeComponentModel: "Blade views and project-native controllers or Livewire only when already installed." };
+  if (await exists(projectPath(cwd, "wp-content"))) return { framework: "WordPress", language: "PHP", extension: "php", sourceRoot: "wp-content/themes/coordiation", nativeComponentModel: "Theme templates, blocks, and WordPress APIs." };
+  return { framework: "HTML", language: "HTML/CSS/JavaScript", extension: "html", sourceRoot: "src", nativeComponentModel: "Standards-first HTML with progressive enhancement." };
+}
+
+function developmentNumberFor(prototype, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(prototype.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("DEV-")).map(({ id }) => Number(id.slice(4))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+export async function createDevelopmentContract({ cwd = process.cwd(), prototypeId, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: prototype } = await loadArtifact(cwd, prototypeId);
+  if (prototype.stage !== "prototype" || prototype.kind !== "prototype-contract") throw new Error(`${prototype.id} is not a prototype contract.`);
+  if (prototype.status !== "approved") throw new Error(`${prototype.id} must be approved before deriving development work.`);
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "development" && artifact.status !== "superseded" && artifact.derivedFrom.includes(prototype.id));
+  if (existing) return { created: false, artifact: existing, paths: { json: `artifacts/development/${existing.id}.json`, markdown: `artifacts/development/${existing.id}.md` } };
+  const timestamp = now(clock);
+  const id = artifactId("DEV", developmentNumberFor(prototype, artifacts));
+  const target = await detectDevelopmentTarget(cwd);
+  const featureSlug = slug(prototype.body.capability);
+  const featureRoot = `${target.sourceRoot}/${featureSlug}`;
+  const utilityCandidates = [...new Set([
+    ...prototype.body.layoutContract.shell,
+    ...prototype.body.layoutContract.content,
+    ...prototype.body.motionContract.classes,
+  ])];
+  const workItems = [
+    { id: `${id}-WORK-001`, title: "Install or reuse approved Coordiation primitives", outputs: prototype.body.componentPlan.map(({ registryId }) => `@coordiation/ui:${registryId}`), dependsOn: [] },
+    { id: `${id}-WORK-002`, title: "Implement semantic layout with literal Coordiation utilities", outputs: [`${featureRoot}/${featureSlug}.${target.extension}`], dependsOn: [`${id}-WORK-001`] },
+    { id: `${id}-WORK-003`, title: "Implement every prototype state and transition", outputs: [`${featureRoot}/${featureSlug}-state.${target.extension}`], dependsOn: [`${id}-WORK-002`] },
+    { id: `${id}-WORK-004`, title: "Connect the documented data adapter without embedding credentials", outputs: [`${featureRoot}/${featureSlug}-adapter.ts`], dependsOn: [`${id}-WORK-003`] },
+    { id: `${id}-WORK-005`, title: "Add acceptance, accessibility, responsive, and failure-path tests", outputs: [`tests/${featureSlug}.test.js`], dependsOn: [`${id}-WORK-003`, `${id}-WORK-004`] },
+  ];
+  const development = artifactEnvelope({
+    id,
+    kind: "development-contract",
+    title: `${prototype.body.capability} development contract`,
+    stage: "development",
+    timestamp,
+    derivedFrom: [prototype.id],
+    acceptanceCriteria: prototype.acceptanceCriteria,
+    body: {
+      capability: prototype.body.capability,
+      target,
+      sourcePlan: { root: featureRoot, files: [...new Set(workItems.flatMap(({ outputs }) => outputs).filter((output) => !output.startsWith("@coordiation/")))], ownership: "Project-owned open code; generated source may be edited without a Coordiation runtime dependency." },
+      dependencies: { components: prototype.body.componentPlan.map(({ registryId }) => registryId), icons: "@coordiation/icons only", css: "@coordiation/css", external: "No new third-party UI system may be introduced by generation." },
+      utilityCandidates,
+      stateImplementation: prototype.body.statePreviews.map(({ id: stateId, fixture, availableActions }) => ({ stateId, fixture, availableActions, requirement: "Reachable through a deterministic adapter or explicit preview control." })),
+      interactionImplementation: prototype.body.interactionMap,
+      workItems,
+      dataBoundary: { adapter: `${featureRoot}/${featureSlug}-adapter.ts`, rule: "UI components depend on a typed feature adapter, not undocumented endpoints.", secrets: "Environment or server configuration only; never generated into source, fixtures, logs, or artifacts.", failures: "Map provider failures into the approved UX states." },
+      testPlan: prototype.acceptanceCriteria.map((criterionId, index) => ({ id: `${id}-TEST-${String(index + 1).padStart(3, "0")}`, criterionId, levels: ["component", "integration"], requiredEvidence: "Passing test command plus the hashed test source." })),
+      qualityCommands: { test: "npm test", build: "npm run build", accessibility: "npm run test:a11y", note: "Projects may record equivalent native commands when these scripts are not present." },
+      definitionOfDone: ["All planned project-owned source files exist.", "Every acceptance criterion maps to a test plan entry.", "Tests and production build exit successfully.", "Keyboard, accessibility, responsive, and reduced-motion checks pass.", "No dynamic co-* class construction or non-Coordiation icon substitute is introduced."],
+      requiredEvidence: ["source", "test", "build", "accessibility"],
+      openDecisions: [...(prototype.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, development);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: development.id, kind: development.kind, stage: development.stage, status: development.status, revision: development.revision, path: paths.json });
+  trace.edges.push(
+    { from: development.id, to: prototype.id, relation: "derives_from" },
+    ...development.acceptanceCriteria.map((criterionId) => ({ from: development.id, to: criterionId, relation: "satisfies" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: development, paths };
+}
+
+function nextEvidenceId(records) {
+  return `EVIDENCE-${String(records.length + 1).padStart(3, "0")}`;
+}
+
+function qaNumberFor(development, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(development.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("QA-")).map(({ id }) => Number(id.slice(3))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+export async function createQaReport({ cwd = process.cwd(), developmentId, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: development } = await loadArtifact(cwd, developmentId);
+  if (development.stage !== "development" || development.kind !== "development-contract") throw new Error(`${development.id} is not a development contract.`);
+  if (development.status !== "approved") throw new Error(`${development.id} must be approved before deriving QA.`);
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "qa" && artifact.status !== "superseded" && artifact.derivedFrom.includes(development.id));
+  if (existing) return { created: false, artifact: existing, paths: { json: `artifacts/qa/${existing.id}.json`, markdown: `artifacts/qa/${existing.id}.md` } };
+  const prototype = artifacts.find((artifact) => artifact.stage === "prototype" && development.derivedFrom.includes(artifact.id));
+  const criteria = new Map(artifacts.filter((artifact) => artifact.kind === "acceptance-criterion").map((artifact) => [artifact.id, artifact]));
+  const timestamp = now(clock);
+  const id = artifactId("QA", qaNumberFor(development, artifacts));
+  const qa = artifactEnvelope({
+    id,
+    kind: "qa-report",
+    title: `${development.body.capability} QA contract and report`,
+    stage: "qa",
+    timestamp,
+    derivedFrom: [development.id],
+    acceptanceCriteria: development.acceptanceCriteria,
+    body: {
+      capability: development.body.capability,
+      strategy: "Risk-based verification of every acceptance criterion, prototype state, supported viewport, accessibility behavior, security boundary, and regression surface.",
+      testCases: development.body.testPlan.map((plannedTest, index) => ({ id: `${id}-CASE-${String(index + 1).padStart(3, "0")}`, criterionId: plannedTest.criterionId, statement: criteria.get(plannedTest.criterionId)?.body?.statement ?? "Verify the linked acceptance criterion.", preconditions: ["Approved development contract", "Deterministic test data or fixture"], steps: ["Open the linked feature state.", "Perform the criterion action using the supported input method.", "Observe the visible outcome and persisted state."], expected: "The acceptance criterion passes without introducing an accessibility, security, responsive, or regression failure.", evidenceTypes: ["functional", "regression"] })),
+      stateCoverage: development.body.stateImplementation.map(({ stateId, fixture }) => ({ stateId, fixture, checks: ["Content and actions match the UX contract.", "Keyboard and announced status are correct.", "State is resettable and does not leak production data."] })),
+      viewportCoverage: prototype?.body?.viewportMatrix ?? [
+        { width: 320, label: "compact", requirement: "No overflow and operable controls." },
+        { width: 768, label: "medium", requirement: "Logical reading and focus order." },
+        { width: 1280, label: "wide", requirement: "Confirmed multi-region layout." },
+      ],
+      accessibilityChecklist: ["Keyboard-only completion", "Visible and logical focus", "Labels, descriptions, landmarks, and headings", "Status and errors announced", "Contrast and non-color-only meaning", "200% zoom and reflow", "Reduced motion"],
+      securityChecklist: ["No credentials, tokens, or private records in source, fixtures, logs, or artifacts", "Authorization is enforced outside visual hiding", "Errors do not reveal sensitive account or system details", "User-controlled content is safely handled", "Dependencies and data adapters match the approved boundary"],
+      regressionScope: { components: development.body.dependencies.components, utilities: development.body.utilityCandidates, upstreamArtifacts: development.derivedFrom, requirement: "Existing consumers of shared components and utilities remain functional." },
+      requiredEvidence: ["functional", "visual", "accessibility", "security", "regression"],
+      releaseBlockers: [],
+      openDecisions: [...(development.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, qa);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: qa.id, kind: qa.kind, stage: qa.stage, status: qa.status, revision: qa.revision, path: paths.json });
+  trace.edges.push(
+    { from: qa.id, to: development.id, relation: "verifies" },
+    ...qa.acceptanceCriteria.map((criterionId) => ({ from: qa.id, to: criterionId, relation: "verifies" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: qa, paths };
+}
+
+function releaseNumberFor(qa, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(qa.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("RELEASE-")).map(({ id }) => Number(id.slice(8))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+async function defaultReleaseVersion(cwd) {
+  const packageFile = projectPath(cwd, "package.json");
+  if (!(await exists(packageFile))) return "0.1.0";
+  const packageJson = await readJson(packageFile);
+  return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version.trim() : "0.1.0";
+}
+
+export async function createReleaseRecord({ cwd = process.cwd(), qaId, version, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: qa } = await loadArtifact(cwd, qaId);
+  if (qa.stage !== "qa" || qa.kind !== "qa-report") throw new Error(`${qa.id} is not a QA report.`);
+  if (qa.status !== "approved") throw new Error(`${qa.id} must be approved before deriving a release.`);
+  const normalizedVersion = String(version ?? await defaultReleaseVersion(cwd)).trim();
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(normalizedVersion)) throw new Error("Release version must be semantic versioning such as 1.0.0 or 1.0.0-rc.1.");
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "release" && artifact.status !== "superseded" && artifact.derivedFrom.includes(qa.id));
+  if (existing) {
+    if (existing.body.version !== normalizedVersion) throw new Error(`${existing.id} already releases ${qa.id} as version ${existing.body.version}. Create a new QA revision before changing the release version.`);
+    return { created: false, artifact: existing, paths: { json: `artifacts/release/${existing.id}.json`, markdown: `artifacts/release/${existing.id}.md` } };
+  }
+  const development = artifacts.find((artifact) => artifact.stage === "development" && qa.derivedFrom.includes(artifact.id));
+  const evidenceFile = projectPath(cwd, EVIDENCE_PATH);
+  const ledger = await exists(evidenceFile) ? await readJson(evidenceFile) : { records: [] };
+  const qaEvidence = ledger.records
+    .filter((record) => record.artifactId === qa.id && record.status === "passed" && record.verified)
+    .map(({ id, type, sha256 }) => ({ id, type, sha256 }));
+  const timestamp = now(clock);
+  const id = artifactId("RELEASE", releaseNumberFor(qa, artifacts));
+  const snapshot = {
+    version: normalizedVersion,
+    qa: { id: qa.id, revision: qa.revision },
+    development: development ? { id: development.id, revision: development.revision } : null,
+    acceptanceCriteria: qa.acceptanceCriteria,
+    qaEvidence,
+  };
+  const snapshotSha256 = createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+  const release = artifactEnvelope({
+    id,
+    kind: "release-record",
+    title: `${qa.body.capability} release ${normalizedVersion}`,
+    stage: "release",
+    timestamp,
+    derivedFrom: [qa.id],
+    acceptanceCriteria: qa.acceptanceCriteria,
+    body: {
+      capability: qa.body.capability,
+      version: normalizedVersion,
+      candidate: { id: `${slug(qa.body.capability)}-v${normalizedVersion}`, snapshotSha256, sourceQa: { id: qa.id, revision: qa.revision }, acceptanceCriteria: qa.acceptanceCriteria },
+      changelog: [{ type: "feature", summary: `Deliver the approved ${qa.body.capability} contract.`, requirementIds: qa.acceptanceCriteria }],
+      compatibility: { framework: development?.body?.target?.framework ?? "project-native", coordiation: ["@coordiation/css", "@coordiation/ui", "@coordiation/icons"], breakingChanges: [], support: "No compatibility claim beyond the approved development target and recorded candidate evidence." },
+      migration: { required: false, steps: ["No data or configuration migration is required by the current contract."], reversibility: "The previous immutable release candidate remains deployable." },
+      environment: { variableNames: [], secretValuesStored: false, validation: "Validate required configuration names in the deployment environment; never store secret values in lifecycle artifacts." },
+      rollout: { strategy: "progressive", batches: [{ name: "internal", audience: "Release operators and internal verification", percentage: 0 }, { name: "limited", audience: "A controlled production cohort", percentage: 10 }, { name: "general", audience: "All intended users after health confirmation", percentage: 100 }], pauseConditions: ["Any health check fails.", "A security, privacy, accessibility, or data-integrity regression is reported."] },
+      healthChecks: [{ id: `${id}-HEALTH-001`, signal: "availability", successCondition: "The deployed feature and required dependencies respond successfully." }, { id: `${id}-HEALTH-002`, signal: "critical user journey", successCondition: "The primary acceptance path completes in the production-like environment." }, { id: `${id}-HEALTH-003`, signal: "errors", successCondition: "No material increase in client, server, authorization, or data-integrity errors." }],
+      rollback: { triggers: ["A required health check fails or degrades after rollout.", "A blocker security, privacy, accessibility, or data-integrity defect is confirmed."], steps: ["Pause further rollout and preserve diagnostic evidence.", "Restore the previous immutable candidate and compatible configuration.", "Run availability and critical-journey health checks, then communicate status."], owner: "Named release approver", maximumDecisionTime: "15 minutes" },
+      requiredEvidence: ["candidate", "release-notes", "rollback-validation"],
+      releaseBlockers: [],
+      openDecisions: [...(qa.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, release);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: release.id, kind: release.kind, stage: release.stage, status: release.status, revision: release.revision, path: paths.json });
+  trace.edges.push(
+    { from: release.id, to: qa.id, relation: "releases" },
+    ...release.acceptanceCriteria.map((criterionId) => ({ from: release.id, to: criterionId, relation: "includes" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: release, paths };
+}
+
+function productionNumberFor(releaseRecord, artifacts) {
+  const preferred = Number(/-(\d+)$/.exec(releaseRecord.id)?.[1]);
+  const occupied = new Set(artifacts.filter(({ id }) => id.startsWith("DEPLOY-")).map(({ id }) => Number(id.slice(7))));
+  if (preferred && !occupied.has(preferred)) return preferred;
+  return Math.max(0, ...occupied) + 1;
+}
+
+export async function createProductionRecord({ cwd = process.cwd(), releaseId, environment = "production", sourceRevision, clock } = {}) {
+  await requireInitialized(cwd);
+  const { artifact: releaseRecord } = await loadArtifact(cwd, releaseId);
+  if (releaseRecord.stage !== "release" || releaseRecord.kind !== "release-record") throw new Error(`${releaseRecord.id} is not a release record.`);
+  if (releaseRecord.status !== "approved") throw new Error(`${releaseRecord.id} must be approved before deriving Production.`);
+  const normalizedEnvironment = String(environment ?? "production").trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(normalizedEnvironment)) throw new Error("Production environment must use lowercase letters, numbers, and hyphens.");
+  const normalizedRevision = String(sourceRevision ?? releaseRecord.body.candidate.snapshotSha256).trim();
+  if (!/^[0-9A-Za-z][0-9A-Za-z._/-]{6,127}$/.test(normalizedRevision)) throw new Error("Source revision must be a commit, digest, or immutable candidate identifier of at least 7 characters.");
+  const files = await artifactFiles(cwd);
+  const artifacts = await Promise.all(files.map((file) => readJson(file)));
+  const existing = artifacts.find((artifact) => artifact.stage === "production" && artifact.status !== "superseded" && artifact.derivedFrom.includes(releaseRecord.id));
+  if (existing) {
+    if (existing.body.deployment.environment !== normalizedEnvironment || existing.body.deployment.sourceRevision !== normalizedRevision) throw new Error(`${existing.id} already binds ${releaseRecord.id} to ${existing.body.deployment.environment} at ${existing.body.deployment.sourceRevision}. Create a new approved release before changing the deployment target.`);
+    return { created: false, artifact: existing, paths: { json: `artifacts/production/${existing.id}.json`, markdown: `artifacts/production/${existing.id}.md` } };
+  }
+  const timestamp = now(clock);
+  const id = artifactId("DEPLOY", productionNumberFor(releaseRecord, artifacts));
+  const production = artifactEnvelope({
+    id,
+    kind: "production-record",
+    title: `${releaseRecord.body.capability} ${releaseRecord.body.version} production deployment`,
+    stage: "production",
+    timestamp,
+    derivedFrom: [releaseRecord.id],
+    acceptanceCriteria: releaseRecord.acceptanceCriteria,
+    body: {
+      capability: releaseRecord.body.capability,
+      deployment: { id: `${releaseRecord.body.candidate.id}-${normalizedEnvironment}`, environment: normalizedEnvironment, releaseId: releaseRecord.id, version: releaseRecord.body.version, candidateId: releaseRecord.body.candidate.id, sourceRevision: normalizedRevision, status: "planned", completedAt: null },
+      authority: { releaseApprovalRequired: true, releaseId: releaseRecord.id, rule: "Only the exact approved release candidate may be deployed; deriving this record does not execute deployment." },
+      configuration: { requiredVariableNames: releaseRecord.body.environment.variableNames, secretValuesStored: false, validation: "Resolve secret values from the authorized environment at deployment time and record only validation evidence." },
+      rollout: { strategy: releaseRecord.body.rollout.strategy, batches: releaseRecord.body.rollout.batches, currentBatch: "not-started", pauseConditions: releaseRecord.body.rollout.pauseConditions },
+      healthChecks: releaseRecord.body.healthChecks,
+      healthStatus: "pending",
+      monitoring: { signals: ["availability", "critical user journey", "error rate", "performance"], alerts: [{ signal: "availability or critical journey", condition: "A required health check fails.", owner: "Production operator" }, { signal: "security, privacy, accessibility, or data integrity", condition: "A blocker regression is detected.", owner: "Release approver" }], observationWindow: "Observe every rollout batch before advancing." },
+      monitoringStatus: "pending",
+      rollback: { candidate: releaseRecord.body.migration.reversibility, triggers: releaseRecord.body.rollback.triggers, steps: releaseRecord.body.rollback.steps, owner: releaseRecord.body.rollback.owner, readiness: "pending" },
+      requiredEvidence: ["deployment", "health", "monitoring", "rollback-readiness"],
+      incidents: [],
+      feedback: [],
+      productionBlockers: [],
+      openDecisions: [...(releaseRecord.body.openDecisions ?? [])],
+    },
+  });
+  const paths = await writeArtifact(cwd, production);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  trace.nodes.push({ id: production.id, kind: production.kind, stage: production.stage, status: production.status, revision: production.revision, path: paths.json });
+  trace.edges.push(
+    { from: production.id, to: releaseRecord.id, relation: "deploys" },
+    ...production.acceptanceCriteria.map((criterionId) => ({ from: production.id, to: criterionId, relation: "operationalizes" })),
+  );
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  return { created: true, artifact: production, paths };
+}
+
+export async function recordLifecycleEvidence({ cwd = process.cwd(), artifactId, developmentId, qaId, type, status = "passed", path: evidencePath, command, exitCode, summary, recordedBy = "agent", clock } = {}) {
+  await requireInitialized(cwd);
+  const targetId = artifactId ?? developmentId ?? qaId;
+  const { artifact, file } = await loadArtifact(cwd, targetId);
+  const developmentTypes = ["source", "test", "build", "accessibility"];
+  const qaTypes = ["functional", "visual", "accessibility", "security", "regression"];
+  const releaseTypes = ["candidate", "release-notes", "rollback-validation"];
+  const productionTypes = ["deployment", "health", "monitoring", "rollback-readiness"];
+  const allowedTypes = artifact.stage === "development" ? developmentTypes : artifact.stage === "qa" ? qaTypes : artifact.stage === "release" ? releaseTypes : artifact.stage === "production" ? productionTypes : null;
+  if (!allowedTypes) throw new Error(`${artifact.id} does not accept implementation or QA evidence.`);
+  const normalizedType = String(type ?? "").trim().toLowerCase();
+  if (!allowedTypes.includes(normalizedType)) throw new Error(`${artifact.stage} evidence type must be one of: ${allowedTypes.join(", ")}.`);
+  if (!["passed", "failed"].includes(status)) throw new Error("Evidence status must be passed or failed.");
+  let normalizedPath = null;
+  let sha256 = null;
+  if (evidencePath) {
+    const filename = projectPath(cwd, evidencePath);
+    if (!(await exists(filename))) throw new Error(`Evidence file does not exist: ${evidencePath}.`);
+    const bytes = await readFile(filename);
+    normalizedPath = relativePath(cwd, filename);
+    sha256 = createHash("sha256").update(bytes).digest("hex");
+  }
+  if (!normalizedPath) throw new Error(`${normalizedType} evidence requires --path to an existing project file or report.`);
+  const normalizedExitCode = exitCode === undefined || exitCode === null ? null : Number(exitCode);
+  const commandRequired = artifact.stage === "development" ? normalizedType !== "source" : artifact.stage === "qa" ? normalizedType !== "visual" : artifact.stage === "release" ? normalizedType !== "release-notes" : normalizedType !== "monitoring";
+  if (commandRequired && (!command || !Number.isInteger(normalizedExitCode))) throw new Error(`${normalizedType} evidence requires --command and --exit-code.`);
+  if (status === "passed" && normalizedExitCode !== null && normalizedExitCode !== 0) throw new Error("Passed command evidence must have exit code 0.");
+  const evidenceFile = projectPath(cwd, EVIDENCE_PATH);
+  const timestamp = now(clock);
+  const ledger = await exists(evidenceFile) ? await readJson(evidenceFile) : { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-evidence", records: [], updatedAt: timestamp };
+  const comparable = { artifactId: artifact.id, artifactRevision: artifact.revision, type: normalizedType, status, path: normalizedPath, sha256, command: command ?? null, exitCode: normalizedExitCode };
+  const existing = ledger.records.find((record) => Object.entries(comparable).every(([key, value]) => record[key] === value));
+  if (existing) return { created: false, evidence: existing };
+  const verified = commandRequired ? Boolean(sha256 && command && normalizedExitCode === 0) : Boolean(sha256);
+  const evidence = { id: nextEvidenceId(ledger.records), ...comparable, verified, summary: summary ?? `${normalizedType} evidence recorded`, recordedBy, createdAt: timestamp };
+  ledger.records.push(evidence);
+  ledger.updatedAt = timestamp;
+  artifact.evidence.push(evidence.id);
+  artifact.updatedAt = timestamp;
+  if (artifact.stage === "production") {
+    if (normalizedType === "deployment") {
+      artifact.body.deployment.status = status === "passed" && verified ? "deployed" : "failed";
+      artifact.body.deployment.completedAt = timestamp;
+    }
+    if (normalizedType === "health") artifact.body.healthStatus = status === "passed" && verified ? "healthy" : "unhealthy";
+    if (normalizedType === "monitoring") artifact.body.monitoringStatus = status === "passed" && verified ? "active" : "degraded";
+    if (normalizedType === "rollback-readiness") artifact.body.rollback.readiness = status === "passed" && verified ? "ready" : "not-ready";
+  }
+  await Promise.all([writeJson(evidenceFile, ledger), writeJson(file, artifact), writeFile(file.replace(/\.json$/, ".md"), markdownArtifact(artifact))]);
+  return { created: true, evidence };
+}
+
+export function recordDevelopmentEvidence(options = {}) {
+  return recordLifecycleEvidence({ ...options, artifactId: options.developmentId });
+}
+
+export function recordQaEvidence(options = {}) {
+  return recordLifecycleEvidence({ ...options, artifactId: options.qaId });
+}
+
+export function recordReleaseEvidence(options = {}) {
+  return recordLifecycleEvidence({ ...options, artifactId: options.releaseId });
+}
+
+export function recordProductionEvidence(options = {}) {
+  return recordLifecycleEvidence({ ...options, artifactId: options.productionId });
+}
+
+export async function getTraceability({ cwd = process.cwd(), id } = {}) {
+  await requireInitialized(cwd);
+  const trace = await readJson(projectPath(cwd, TRACEABILITY_PATH));
+  if (!id) return trace;
+  const normalized = String(id).trim().toUpperCase();
+  const edges = trace.edges.filter((edge) => edge.from === normalized || edge.to === normalized);
+  const related = new Set([normalized, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+  return { ...trace, focus: normalized, nodes: trace.nodes.filter((node) => related.has(node.id)), edges };
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export async function reviseLifecycleArtifact({ cwd = process.cwd(), artifactId, reason, bodyPatch = {}, clock } = {}) {
+  await requireInitialized(cwd);
+  const normalizedReason = String(reason ?? "").trim();
+  if (!normalizedReason) throw new Error("Artifact revision requires a reason.");
+  if (!isPlainObject(bodyPatch) || ["__proto__", "prototype", "constructor"].some((key) => Object.hasOwn(bodyPatch, key))) throw new Error("Artifact body patch must be a safe JSON object.");
+  const files = await artifactFiles(cwd);
+  const entries = await Promise.all(files.map(async (file) => ({ file, artifact: await readJson(file) })));
+  const target = entries.find(({ artifact }) => artifact.id === String(artifactId ?? "").trim().toUpperCase());
+  if (!target) throw new Error(`Unknown lifecycle artifact: ${artifactId}.`);
+  if (target.artifact.status === "superseded") throw new Error(`${target.artifact.id} is superseded and cannot be revised in place.`);
+  const unknownPatchKeys = Object.keys(bodyPatch).filter((key) => !Object.hasOwn(target.artifact.body, key));
+  if (unknownPatchKeys.length) throw new Error(`Revision patch contains unknown ${target.artifact.kind} body fields: ${unknownPatchKeys.join(", ")}.`);
+  const timestamp = now(clock);
+  const priorRevision = structuredClone(target.artifact);
+  const archive = projectPath(cwd, join(COORDIATION_DIRECTORY, "revisions", target.artifact.id, `revision-${target.artifact.revision}.json`));
+  await writeJson(archive, { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-artifact-revision-history", reason: normalizedReason, archivedAt: timestamp, artifact: priorRevision });
+
+  const invalidated = new Set();
+  const frontier = [target.artifact.id];
+  while (frontier.length) {
+    const upstreamId = frontier.shift();
+    for (const entry of entries) {
+      if (entry.artifact.id === target.artifact.id || invalidated.has(entry.artifact.id)) continue;
+      if (entry.artifact.derivedFrom.includes(upstreamId) || entry.artifact.acceptanceCriteria.includes(upstreamId)) {
+        invalidated.add(entry.artifact.id);
+        frontier.push(entry.artifact.id);
+      }
+    }
+  }
+
+  target.artifact.revision += 1;
+  target.artifact.status = "draft";
+  target.artifact.body = { ...target.artifact.body, ...structuredClone(bodyPatch) };
+  target.artifact.approvals = [];
+  target.artifact.evidence = [];
+  target.artifact.risks = [...target.artifact.risks, { type: "revision", reason: normalizedReason, priorRevision: priorRevision.revision }];
+  target.artifact.updatedAt = timestamp;
+  const writes = [writeJson(target.file, target.artifact), writeFile(target.file.replace(/\.json$/, ".md"), markdownArtifact(target.artifact))];
+  for (const entry of entries) {
+    if (!invalidated.has(entry.artifact.id)) continue;
+    entry.artifact.status = "superseded";
+    entry.artifact.updatedAt = timestamp;
+    entry.artifact.risks = [...entry.artifact.risks, { type: "upstream-revision", upstreamId: target.artifact.id, upstreamRevision: target.artifact.revision }];
+    writes.push(writeJson(entry.file, entry.artifact), writeFile(entry.file.replace(/\.json$/, ".md"), markdownArtifact(entry.artifact)));
+  }
+  await Promise.all(writes);
+
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  for (const node of trace.nodes) {
+    if (node.id === target.artifact.id) {
+      node.revision = target.artifact.revision;
+      node.status = "draft";
+    } else if (invalidated.has(node.id)) node.status = "superseded";
+  }
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+
+  const lifecycleFile = projectPath(cwd, LIFECYCLE_PATH);
+  const lifecycle = await readJson(lifecycleFile);
+  const stageIndex = lifecycle.stages.findIndex(({ id }) => id === target.artifact.stage);
+  lifecycle.currentStage = target.artifact.stage;
+  for (let index = stageIndex; index < lifecycle.stages.length; index += 1) lifecycle.stages[index].status = index === stageIndex ? "active" : "pending";
+  for (let index = stageIndex; index < lifecycle.gates.length; index += 1) {
+    lifecycle.gates[index].status = "pending";
+    lifecycle.gates[index].approvalId = null;
+  }
+  lifecycle.updatedAt = timestamp;
+  await writeJson(lifecycleFile, lifecycle);
+  return { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-revision-result", artifact: { id: target.artifact.id, revision: target.artifact.revision, status: target.artifact.status }, invalidated: [...invalidated].sort(), reason: normalizedReason, archive: relativePath(cwd, archive), lifecycle: { currentStage: lifecycle.currentStage } };
+}
+
+function check(id, passed, message) {
+  return { id, passed, message };
+}
+
+async function interviewSessions(cwd) {
+  const directory = projectPath(cwd, join(COORDIATION_DIRECTORY, "interviews"));
+  let entries = [];
+  try { entries = await readdir(directory, { withFileTypes: true }); } catch { return []; }
+  return Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => readJson(join(directory, entry.name))));
+}
+
+function latestArtifact(artifacts, stage) {
+  return artifacts.filter((artifact) => artifact.stage === stage).sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true })).at(-1);
+}
+
+export async function checkLifecycleGate({ cwd = process.cwd(), gate, artifactId: requestedArtifactId } = {}) {
+  await requireInitialized(cwd);
+  const normalizedGate = String(gate ?? "").trim().toUpperCase();
+  const stage = Object.entries(LIFECYCLE_GATES).find(([, value]) => value === normalizedGate)?.[0];
+  if (!stage) throw new Error(`Unknown lifecycle gate: ${gate}.`);
+  const files = await artifactFiles(cwd);
+  const allArtifacts = await Promise.all(files.map((file) => readJson(file)));
+  const requestedArtifact = requestedArtifactId ? allArtifacts.find((artifact) => artifact.id === String(requestedArtifactId).trim().toUpperCase()) : null;
+  if (requestedArtifactId && !requestedArtifact) throw new Error(`Unknown lifecycle artifact: ${requestedArtifactId}.`);
+  if (requestedArtifact?.status === "superseded") return { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-gate-report", gate: normalizedGate, stage, artifactId: requestedArtifact.id, ready: false, checks: [check("artifact-current", false, `${requestedArtifact.id} is superseded and cannot authorize a gate.`)] };
+  const artifacts = allArtifacts.filter((artifact) => artifact.status !== "superseded");
+  let specification;
+  let prd;
+  let ux;
+  let prototype;
+  let development;
+  let qa;
+  let releaseRecord;
+  let productionRecord;
+  if (requestedArtifact?.stage === "specification") {
+    specification = requestedArtifact;
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && artifact.derivedFrom.includes(specification.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && artifact.derivedFrom.includes(prd?.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux?.id));
+  } else if (requestedArtifact?.stage === "prd") {
+    prd = requestedArtifact;
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && artifact.derivedFrom.includes(prd.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux?.id));
+  } else if (requestedArtifact?.stage === "ux") {
+    ux = requestedArtifact;
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux.id));
+  } else if (requestedArtifact?.stage === "prototype") {
+    prototype = requestedArtifact;
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  } else if (requestedArtifact?.stage === "development") {
+    development = requestedArtifact;
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && development.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype?.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  } else if (requestedArtifact?.stage === "qa") {
+    qa = requestedArtifact;
+    development = artifacts.find((artifact) => artifact.stage === "development" && qa.derivedFrom.includes(artifact.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && development?.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype?.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  } else if (requestedArtifact?.stage === "release") {
+    releaseRecord = requestedArtifact;
+    qa = artifacts.find((artifact) => artifact.stage === "qa" && releaseRecord.derivedFrom.includes(artifact.id));
+    development = artifacts.find((artifact) => artifact.stage === "development" && qa?.derivedFrom.includes(artifact.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && development?.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype?.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  } else if (requestedArtifact?.stage === "production") {
+    productionRecord = requestedArtifact;
+    releaseRecord = artifacts.find((artifact) => artifact.stage === "release" && productionRecord.derivedFrom.includes(artifact.id));
+    qa = artifacts.find((artifact) => artifact.stage === "qa" && releaseRecord?.derivedFrom.includes(artifact.id));
+    development = artifacts.find((artifact) => artifact.stage === "development" && qa?.derivedFrom.includes(artifact.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && development?.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype?.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  } else if (normalizedGate === "GATE-SPEC") {
+    specification = latestArtifact(artifacts, "specification");
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && artifact.derivedFrom.includes(specification?.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && artifact.derivedFrom.includes(prd?.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux?.id));
+  } else if (normalizedGate === "GATE-PRD") {
+    prd = latestArtifact(artifacts, "prd");
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && artifact.derivedFrom.includes(prd?.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux?.id));
+  } else if (normalizedGate === "GATE-UX") {
+    ux = latestArtifact(artifacts, "ux");
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+    prototype = artifacts.find((artifact) => artifact.stage === "prototype" && artifact.derivedFrom.includes(ux?.id));
+  } else {
+    prototype = latestArtifact(artifacts, "prototype");
+    ux = artifacts.find((artifact) => artifact.stage === "ux" && prototype?.derivedFrom.includes(artifact.id));
+    prd = artifacts.find((artifact) => artifact.stage === "prd" && ux?.derivedFrom.includes(artifact.id));
+    specification = artifacts.find((artifact) => artifact.stage === "specification" && prd?.derivedFrom.includes(artifact.id));
+  }
+  development ??= artifacts.find((artifact) => artifact.stage === "development" && artifact.derivedFrom.includes(prototype?.id));
+  qa ??= artifacts.find((artifact) => artifact.stage === "qa" && artifact.derivedFrom.includes(development?.id));
+  releaseRecord ??= artifacts.find((artifact) => artifact.stage === "release" && artifact.derivedFrom.includes(qa?.id));
+  productionRecord ??= artifacts.find((artifact) => artifact.stage === "production" && artifact.derivedFrom.includes(releaseRecord?.id));
+  const sessions = await interviewSessions(cwd);
+  const interview = sessions.find((session) => session.generatedArtifacts?.some(({ id }) => id === specification?.id));
+  const evidenceFile = projectPath(cwd, EVIDENCE_PATH);
+  const evidenceLedger = await exists(evidenceFile) ? await readJson(evidenceFile) : { records: [] };
+  const developmentEvidence = evidenceLedger.records.filter((record) => record.artifactId === development?.id && record.artifactRevision === development?.revision);
+  const qaEvidence = evidenceLedger.records.filter((record) => record.artifactId === qa?.id && record.artifactRevision === qa?.revision);
+  const releaseEvidence = evidenceLedger.records.filter((record) => record.artifactId === releaseRecord?.id && record.artifactRevision === releaseRecord?.revision);
+  const productionEvidence = evidenceLedger.records.filter((record) => record.artifactId === productionRecord?.id && record.artifactRevision === productionRecord?.revision);
+  let checks;
+  if (normalizedGate === "GATE-SPEC") {
+    checks = [
+      check("interview-complete", interview?.status === "completed", "The requirement interview is complete."),
+      check("specification-exists", Boolean(specification), `${specification?.id ?? "A specification"} exists.`),
+      check("no-blocking-open-decisions", Array.isArray(specification?.body?.openDecisions) && specification.body.openDecisions.length === 0, "The specification has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-PRD") {
+    checks = [
+      check("specification-approved", specification?.status === "approved", `${specification?.id ?? "The linked specification"} is approved.`),
+      check("prd-exists", Boolean(prd), `${prd?.id ?? "A PRD"} exists.`),
+      check("acceptance-criteria-linked", (prd?.acceptanceCriteria?.length ?? 0) >= 4, "The PRD links testable acceptance criteria."),
+      check("no-blocking-open-decisions", Array.isArray(prd?.body?.openDecisions) && prd.body.openDecisions.length === 0, "The PRD has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-UX") {
+    checks = [
+      check("prd-approved", prd?.status === "approved", `${prd?.id ?? "The linked PRD"} is approved.`),
+      check("ux-contract-exists", Boolean(ux), `${ux?.id ?? "A UX contract"} exists.`),
+      check("primary-flow-complete", (ux?.body?.primaryFlow?.length ?? 0) >= 4, "The UX contract contains a complete primary flow."),
+      check("screen-states-complete", (ux?.body?.screenStates?.length ?? 0) >= 5, "The UX contract defines happy, loading, empty or invalid, unavailable, and success behavior."),
+      check("acceptance-criteria-linked", (ux?.acceptanceCriteria?.length ?? 0) >= 4, "The UX contract links the PRD acceptance criteria."),
+      check("responsive-contract", Boolean(ux?.body?.responsiveContract?.minimumViewport), "Responsive behavior is explicit."),
+      check("accessibility-contract", Boolean(ux?.body?.accessibilityContract?.keyboard && ux?.body?.accessibilityContract?.errors), "Keyboard, focus, semantics, motion, and error behavior are explicit."),
+      check("no-blocking-open-decisions", Array.isArray(ux?.body?.openDecisions) && ux.body.openDecisions.length === 0, "The UX contract has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-PROTOTYPE") {
+    const previewIds = new Set(prototype?.body?.statePreviews?.map(({ id }) => id) ?? []);
+    const uxStateIds = ux?.body?.screenStates?.map(({ id }) => id) ?? [];
+    const viewports = prototype?.body?.viewportMatrix?.map(({ width }) => width) ?? [];
+    const layoutClasses = [...(prototype?.body?.layoutContract?.shell ?? []), ...(prototype?.body?.layoutContract?.content ?? [])];
+    checks = [
+      check("ux-approved", ux?.status === "approved", `${ux?.id ?? "The linked UX contract"} is approved.`),
+      check("prototype-contract-exists", Boolean(prototype), `${prototype?.id ?? "A prototype contract"} exists.`),
+      check("coordiation-components", (prototype?.body?.componentPlan?.length ?? 0) >= 5 && prototype?.body?.frameworkContract?.components?.includes("@coordiation/ui"), "The prototype uses a concrete Coordiation component plan."),
+      check("coordiation-icons", prototype?.body?.frameworkContract?.icons?.includes("@coordiation/icons"), "Icon use is constrained to Coordiation icon components."),
+      check("literal-co-classes", layoutClasses.length >= 6 && layoutClasses.every((candidate) => candidate.includes("co-")), "Layout utilities are explicit literal co-* candidates."),
+      check("all-states-previewable", uxStateIds.length >= 5 && uxStateIds.every((id) => previewIds.has(id)), "Every UX state has a deterministic prototype preview."),
+      check("viewport-matrix", [320, 768, 1280].every((width) => viewports.includes(width)), "Compact, medium, and wide prototype viewports are defined."),
+      check("reduced-motion", prototype?.body?.motionContract?.classes?.some((candidate) => candidate.startsWith("motion-reduce:")), "The prototype defines a reduced-motion path."),
+      check("evidence-plan", (prototype?.body?.evidenceRequirements?.screenshots?.length ?? 0) >= uxStateIds.length * 3 && (prototype?.body?.evidenceRequirements?.acceptanceCriteria?.length ?? 0) === (prototype?.acceptanceCriteria?.length ?? -1), "Screenshot, keyboard, accessibility, and acceptance evidence are planned."),
+      check("no-blocking-open-decisions", Array.isArray(prototype?.body?.openDecisions) && prototype.body.openDecisions.length === 0, "The prototype contract has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-DEVELOPMENT") {
+    const requiredEvidence = ["source", "test", "build", "accessibility"];
+    const stateIds = new Set(development?.body?.stateImplementation?.map(({ stateId }) => stateId) ?? []);
+    const prototypeStateIds = prototype?.body?.statePreviews?.map(({ id }) => id) ?? [];
+    checks = [
+      check("prototype-approved", prototype?.status === "approved", `${prototype?.id ?? "The linked prototype contract"} is approved.`),
+      check("development-contract-exists", Boolean(development), `${development?.id ?? "A development contract"} exists.`),
+      check("framework-target", Boolean(development?.body?.target?.framework && development?.body?.target?.nativeComponentModel), "The implementation target and native component model are explicit."),
+      check("work-items-complete", (development?.body?.workItems?.length ?? 0) >= 5, "Source, states, adapter, components, and tests have implementation work items."),
+      check("state-coverage", prototypeStateIds.length >= 5 && prototypeStateIds.every((stateId) => stateIds.has(stateId)), "Every prototype state is covered by the development plan."),
+      check("acceptance-test-coverage", (development?.body?.testPlan?.length ?? 0) === (development?.acceptanceCriteria?.length ?? -1), "Every acceptance criterion maps to a development test."),
+      check("literal-utilities", (development?.body?.utilityCandidates?.length ?? 0) >= 6 && development.body.utilityCandidates.every((candidate) => candidate.includes("co-")), "The development contract contains only explicit literal Coordiation utility candidates."),
+      ...requiredEvidence.map((type) => check(`evidence-${type}`, developmentEvidence.some((record) => record.type === type && record.status === "passed" && record.verified), `Verified passing ${type} evidence is recorded.`)),
+      check("no-blocking-open-decisions", Array.isArray(development?.body?.openDecisions) && development.body.openDecisions.length === 0, "The development contract has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-QA") {
+    const requiredEvidence = ["functional", "visual", "accessibility", "security", "regression"];
+    const latestEvidence = new Map();
+    for (const record of qaEvidence) latestEvidence.set(record.type, record);
+    const qaStateIds = new Set(qa?.body?.stateCoverage?.map(({ stateId }) => stateId) ?? []);
+    const developmentStateIds = development?.body?.stateImplementation?.map(({ stateId }) => stateId) ?? [];
+    const viewports = qa?.body?.viewportCoverage?.map(({ width }) => width) ?? [];
+    checks = [
+      check("development-approved", development?.status === "approved", `${development?.id ?? "The linked development contract"} is approved.`),
+      check("qa-report-exists", Boolean(qa), `${qa?.id ?? "A QA report"} exists.`),
+      check("acceptance-cases", (qa?.body?.testCases?.length ?? 0) === (qa?.acceptanceCriteria?.length ?? -1), "Every acceptance criterion has an executable QA case."),
+      check("state-coverage", developmentStateIds.length >= 5 && developmentStateIds.every((stateId) => qaStateIds.has(stateId)), "Every implemented state is covered by QA."),
+      check("viewport-coverage", [320, 768, 1280].every((width) => viewports.includes(width)), "QA covers compact, medium, and wide viewports."),
+      check("accessibility-checklist", (qa?.body?.accessibilityChecklist?.length ?? 0) >= 7, "Keyboard, focus, semantics, errors, contrast, zoom, and reduced motion are covered."),
+      check("security-checklist", (qa?.body?.securityChecklist?.length ?? 0) >= 5, "Secrets, authorization, disclosure, input handling, and dependency boundaries are covered."),
+      ...requiredEvidence.map((type) => {
+        const record = latestEvidence.get(type);
+        return check(`evidence-${type}`, record?.status === "passed" && record?.verified, `Latest ${type} evidence is verified and passing.`);
+      }),
+      check("no-release-blockers", Array.isArray(qa?.body?.releaseBlockers) && qa.body.releaseBlockers.length === 0, "QA has no unresolved release blockers."),
+      check("no-blocking-open-decisions", Array.isArray(qa?.body?.openDecisions) && qa.body.openDecisions.length === 0, "The QA report has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-RELEASE") {
+    const requiredEvidence = ["candidate", "release-notes", "rollback-validation"];
+    const latestEvidence = new Map();
+    for (const record of releaseEvidence) latestEvidence.set(record.type, record);
+    const rolloutPercentages = releaseRecord?.body?.rollout?.batches?.map(({ percentage }) => percentage) ?? [];
+    checks = [
+      check("qa-approved", qa?.status === "approved", `${qa?.id ?? "The linked QA report"} is approved.`),
+      check("release-record-exists", Boolean(releaseRecord), `${releaseRecord?.id ?? "A release record"} exists.`),
+      check("semantic-version", /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(releaseRecord?.body?.version ?? ""), "The release has a semantic version."),
+      check("immutable-candidate", Boolean(releaseRecord?.body?.candidate?.id) && /^[a-f0-9]{64}$/.test(releaseRecord?.body?.candidate?.snapshotSha256 ?? ""), "The release candidate has a stable identity and SHA-256 snapshot."),
+      check("acceptance-coverage", (releaseRecord?.body?.candidate?.acceptanceCriteria?.length ?? 0) === (releaseRecord?.acceptanceCriteria?.length ?? -1), "The candidate includes every approved acceptance criterion."),
+      check("release-notes", (releaseRecord?.body?.changelog?.length ?? 0) >= 1, "The release contains requirement-linked changelog entries."),
+      check("compatibility-migration", Boolean(releaseRecord?.body?.compatibility?.support) && (releaseRecord?.body?.migration?.steps?.length ?? 0) >= 1, "Compatibility and migration behavior are explicit."),
+      check("secret-safe-environment", releaseRecord?.body?.environment?.secretValuesStored === false && Array.isArray(releaseRecord?.body?.environment?.variableNames), "Environment configuration stores names only, never secret values."),
+      check("progressive-rollout", rolloutPercentages.length >= 2 && rolloutPercentages.includes(100) && (releaseRecord?.body?.rollout?.pauseConditions?.length ?? 0) >= 2, "The rollout is staged, reaches general availability, and has pause conditions."),
+      check("health-checks", (releaseRecord?.body?.healthChecks?.length ?? 0) >= 3, "Availability, critical journey, and error health checks are defined."),
+      check("rollback-ready", (releaseRecord?.body?.rollback?.triggers?.length ?? 0) >= 2 && (releaseRecord?.body?.rollback?.steps?.length ?? 0) >= 3 && Boolean(releaseRecord?.body?.rollback?.owner), "Rollback triggers, ordered steps, and ownership are explicit."),
+      ...requiredEvidence.map((type) => {
+        const record = latestEvidence.get(type);
+        return check(`evidence-${type}`, record?.status === "passed" && record?.verified, `Latest ${type} evidence is verified and passing.`);
+      }),
+      check("no-release-blockers", Array.isArray(releaseRecord?.body?.releaseBlockers) && releaseRecord.body.releaseBlockers.length === 0, "The release has no unresolved blockers."),
+      check("no-blocking-open-decisions", Array.isArray(releaseRecord?.body?.openDecisions) && releaseRecord.body.openDecisions.length === 0, "The release has no blocking open decisions."),
+    ];
+  } else if (normalizedGate === "GATE-PRODUCTION") {
+    const requiredEvidence = ["deployment", "health", "monitoring", "rollback-readiness"];
+    const latestEvidence = new Map();
+    for (const record of productionEvidence) latestEvidence.set(record.type, record);
+    const rolloutPercentages = productionRecord?.body?.rollout?.batches?.map(({ percentage }) => percentage) ?? [];
+    const unresolvedIncidents = productionRecord?.body?.incidents?.filter((incident) => incident.status !== "resolved") ?? [];
+    checks = [
+      check("release-approved", releaseRecord?.status === "approved", `${releaseRecord?.id ?? "The linked release"} is approved.`),
+      check("production-record-exists", Boolean(productionRecord), `${productionRecord?.id ?? "A Production record"} exists.`),
+      check("immutable-deployment-identity", Boolean(productionRecord?.body?.deployment?.id && productionRecord?.body?.deployment?.sourceRevision) && productionRecord?.body?.deployment?.releaseId === releaseRecord?.id, "Deployment identity binds the approved release, environment, candidate, and source revision."),
+      check("deployment-succeeded", productionRecord?.body?.deployment?.status === "deployed" && Boolean(productionRecord?.body?.deployment?.completedAt), "The deployment completed successfully."),
+      check("secret-safe-configuration", productionRecord?.body?.configuration?.secretValuesStored === false && Array.isArray(productionRecord?.body?.configuration?.requiredVariableNames), "Production records configuration names but never secret values."),
+      check("controlled-rollout", rolloutPercentages.length >= 2 && rolloutPercentages.includes(100) && (productionRecord?.body?.rollout?.pauseConditions?.length ?? 0) >= 2, "The Production rollout has staged cohorts and pause conditions."),
+      check("health-plan", (productionRecord?.body?.healthChecks?.length ?? 0) >= 3, "Availability, critical journey, and error health checks are defined."),
+      check("healthy", productionRecord?.body?.healthStatus === "healthy", "The latest Production health result is healthy."),
+      check("monitoring-active", productionRecord?.body?.monitoringStatus === "active" && (productionRecord?.body?.monitoring?.signals?.length ?? 0) >= 4 && (productionRecord?.body?.monitoring?.alerts?.length ?? 0) >= 2, "Monitoring and owned alerts are active."),
+      check("rollback-ready", productionRecord?.body?.rollback?.readiness === "ready" && (productionRecord?.body?.rollback?.triggers?.length ?? 0) >= 2 && (productionRecord?.body?.rollback?.steps?.length ?? 0) >= 3, "The exact rollback path has been validated."),
+      ...requiredEvidence.map((type) => {
+        const record = latestEvidence.get(type);
+        return check(`evidence-${type}`, record?.status === "passed" && record?.verified, `Latest ${type} evidence is verified and passing.`);
+      }),
+      check("no-unresolved-incidents", unresolvedIncidents.length === 0, "Production has no unresolved incidents."),
+      check("no-production-blockers", Array.isArray(productionRecord?.body?.productionBlockers) && productionRecord.body.productionBlockers.length === 0, "Production has no unresolved blockers."),
+      check("no-blocking-open-decisions", Array.isArray(productionRecord?.body?.openDecisions) && productionRecord.body.openDecisions.length === 0, "The Production record has no blocking open decisions."),
+    ];
+  } else {
+    checks = [check("stage-implementation", false, `${normalizedGate} is defined by the blueprint but is not implemented in the first lifecycle slice.`)];
+  }
+  const gateArtifact = stage === "specification" ? specification : stage === "prd" ? prd : stage === "ux" ? ux : stage === "prototype" ? prototype : stage === "development" ? development : stage === "qa" ? qa : stage === "release" ? releaseRecord : stage === "production" ? productionRecord : requestedArtifact;
+  return { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-gate-report", gate: normalizedGate, stage, artifactId: requestedArtifact?.id ?? gateArtifact?.id ?? null, ready: checks.every((entry) => entry.passed), checks };
+}
+
+function nextApprovalId(approvals) {
+  return `APPROVAL-${String(approvals.length + 1).padStart(3, "0")}`;
+}
+
+export async function approveLifecycleArtifact({ cwd = process.cwd(), artifactId, gate, approverName, approverEmail, comment = "Approved", clock } = {}) {
+  await requireInitialized(cwd);
+  if (!approverName) throw new Error("Approval requires --approver-name.");
+  const normalizedGate = String(gate ?? "").trim().toUpperCase();
+  const { artifact, file } = await loadArtifact(cwd, artifactId);
+  const expectedGate = LIFECYCLE_GATES[artifact.stage];
+  if (normalizedGate !== expectedGate) throw new Error(`${artifact.id} belongs to ${expectedGate}, not ${normalizedGate || "an unspecified gate"}.`);
+  if (artifact.status === "approved") throw new Error(`${artifact.id} revision ${artifact.revision} is already approved.`);
+  const report = await checkLifecycleGate({ cwd, gate: normalizedGate, artifactId: artifact.id });
+  if (!report.ready) throw new Error(`${normalizedGate} is not ready: ${report.checks.filter((entry) => !entry.passed).map((entry) => entry.id).join(", ")}`);
+  const timestamp = now(clock);
+  const approvalsFile = projectPath(cwd, APPROVALS_PATH);
+  const approvals = await readJson(approvalsFile);
+  const approval = {
+    id: nextApprovalId(approvals.approvals),
+    artifactId: artifact.id,
+    revision: artifact.revision,
+    gate: normalizedGate,
+    decision: "approved",
+    approver: { name: approverName, email: approverEmail || null, role: "human-approver" },
+    comment,
+    createdAt: timestamp,
+  };
+  approvals.approvals.push(approval);
+  approvals.updatedAt = timestamp;
+  artifact.status = "approved";
+  artifact.approvals.push(approval.id);
+  artifact.updatedAt = timestamp;
+  await Promise.all([writeJson(file, artifact), writeFile(file.replace(/\.json$/, ".md"), markdownArtifact(artifact)), writeJson(approvalsFile, approvals)]);
+  const traceFile = projectPath(cwd, TRACEABILITY_PATH);
+  const trace = await readJson(traceFile);
+  const node = trace.nodes.find((entry) => entry.id === artifact.id);
+  if (node) node.status = "approved";
+  trace.updatedAt = timestamp;
+  await writeJson(traceFile, trace);
+  const lifecycleFile = projectPath(cwd, LIFECYCLE_PATH);
+  const lifecycle = await readJson(lifecycleFile);
+  const gateEntry = lifecycle.gates.find((entry) => entry.id === normalizedGate);
+  gateEntry.status = "approved";
+  gateEntry.approvalId = approval.id;
+  const stageIndex = lifecycle.stages.findIndex((entry) => entry.id === artifact.stage);
+  const currentStageIndex = lifecycle.stages.findIndex((entry) => entry.id === lifecycle.currentStage);
+  lifecycle.stages[stageIndex].status = "approved";
+  if (stageIndex >= currentStageIndex && stageIndex + 1 < lifecycle.stages.length) {
+    lifecycle.stages[stageIndex + 1].status = "active";
+    lifecycle.currentStage = lifecycle.stages[stageIndex + 1].id;
+  }
+  lifecycle.updatedAt = timestamp;
+  await writeJson(lifecycleFile, lifecycle);
+  return { schemaVersion: LIFECYCLE_SCHEMA_VERSION, kind: "coordiation-approval-result", approval, artifact: { id: artifact.id, revision: artifact.revision, status: artifact.status }, lifecycle: { currentStage: lifecycle.currentStage } };
+}