trackops 1.1.0 → 2.0.0

package/lib/opera-bootstrap.js

@@ -12,7 +12,7 @@ const { resolveLocalizedFile } = require("./resources");
 
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates", "opera");
 
-const SERVICE_HINTS = [
+const SERVICE_HINTS = [
   ["openai", "OpenAI"],
   ["anthropic", "Anthropic"],
   ["stripe", "Stripe"],
@@ -24,8 +24,17 @@ const SERVICE_HINTS = [
   ["s3", "Amazon S3"],
   ["aws", "AWS"],
   ["gcp", "Google Cloud"],
-  ["azure", "Azure"],
-];
+  ["azure", "Azure"],
+];
+
+const TECHNICAL_LEVELS = ["low", "medium", "high", "senior"];
+const PROJECT_STATES = ["idea", "draft", "existing_repo", "advanced"];
+const DOC_STATES = ["none", "notes", "sos", "spec_dossier", "repo_docs"];
+const DECISION_OWNERSHIPS = ["user", "shared", "agent"];
+const BOOTSTRAP_MODES = ["auto", "direct", "handoff"];
+const QUALITY_STATUSES = ["ready", "needs_review", "blocked"];
+const CONTRACT_READINESS = ["hypothesis", "provisional", "verified", "locked"];
+const CONTRACT_VERSION = 3;
 
 function nowIso() {
   return new Date().toISOString();
@@ -37,9 +46,27 @@ function git(args, root) {
   return result.stdout.trim();
 }
 
-function readText(filePath) {
-  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
-}
+function readText(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeText(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content.replace(/\r?\n/g, "\n"), "utf8");
+}
+
+function writeJson(filePath, data) {
+  writeText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
 
 function safeJson(text) {
   try {
@@ -49,9 +76,66 @@ function safeJson(text) {
   }
 }
 
-function unique(items) {
-  return [...new Set(items.filter(Boolean))];
-}
+function unique(items) {
+  return [...new Set((items || []).map((item) => String(item || "").trim()).filter(Boolean))];
+}
+
+function normalizeEnum(value, allowed) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return allowed.includes(normalized) ? normalized : null;
+}
+
+function explanationModeFor(technicalLevel) {
+  if (technicalLevel === "low") return "guided";
+  if (technicalLevel === "medium") return "balanced";
+  return "expert";
+}
+
+function bootstrapRelativePaths(context) {
+  if (context.layout === "split") {
+    return {
+      markdown: "ops/bootstrap/agent-handoff.md",
+      json: "ops/bootstrap/agent-handoff.json",
+      intakeJson: "ops/bootstrap/intake.json",
+      specDossier: "ops/bootstrap/spec-dossier.md",
+      openQuestions: "ops/bootstrap/open-questions.md",
+      qualityReport: "ops/bootstrap/quality-report.json",
+    };
+  }
+
+  return {
+    markdown: "bootstrap/agent-handoff.md",
+    json: "bootstrap/agent-handoff.json",
+    intakeJson: "bootstrap/intake.json",
+    specDossier: "bootstrap/spec-dossier.md",
+    openQuestions: "bootstrap/open-questions.md",
+    qualityReport: "bootstrap/quality-report.json",
+  };
+}
+
+function bootstrapFilePaths(context) {
+  return {
+    dir: context.paths.bootstrapDir,
+    markdown: path.join(context.paths.bootstrapDir, "agent-handoff.md"),
+    json: path.join(context.paths.bootstrapDir, "agent-handoff.json"),
+    intakeJson: path.join(context.paths.bootstrapDir, "intake.json"),
+    specDossier: path.join(context.paths.bootstrapDir, "spec-dossier.md"),
+    openQuestions: path.join(context.paths.bootstrapDir, "open-questions.md"),
+    qualityReport: path.join(context.paths.bootstrapDir, "quality-report.json"),
+  };
+}
+
+function contractRelativePath(context) {
+  return context.layout === "split"
+    ? "ops/contract/operating-contract.json"
+    : "contract/operating-contract.json";
+}
+
+function policyRelativePath(context) {
+  return context.layout === "split"
+    ? "ops/policy/autonomy.json"
+    : "policy/autonomy.json";
+}
 
 function firstParagraph(text) {
   return String(text || "")
@@ -150,132 +234,490 @@ function normalizeList(value) {
     .filter(Boolean);
 }
 
-function parseJsonValue(value) {
-  if (!String(value || "").trim()) return {};
-  try {
-    return JSON.parse(value);
-  } catch (_error) {
-    return {};
-  }
-}
-
-async function askQuestion(rl, message, defaultValue) {
-  const suffix = defaultValue ? ` (${defaultValue})` : "";
-  const answer = await rl.question(`${message}${suffix}: `);
-  return String(answer || "").trim() || String(defaultValue || "").trim();
-}
+function parseJsonValue(value) {
+  if (!String(value || "").trim()) return {};
+  try {
+    return JSON.parse(value);
+  } catch (_error) {
+    return {};
+  }
+}
+
+function getBootstrapState(control, contextOrRoot) {
+  const context = config.ensureContext(contextOrRoot);
+  const bootstrap = control.meta?.opera?.bootstrap;
+  if (!bootstrap) return null;
+  const relative = bootstrapRelativePaths(context);
+  return {
+    ...bootstrap,
+    handoffFiles: bootstrap.handoffFiles || {
+      markdown: relative.markdown,
+      json: relative.json,
+    },
+    intakeFiles: bootstrap.intakeFiles || {
+      json: relative.intakeJson,
+      specDossier: relative.specDossier,
+    },
+    reviewFiles: bootstrap.reviewFiles || {
+      openQuestions: relative.openQuestions,
+      qualityReport: relative.qualityReport,
+    },
+  };
+}
+
+function buildAvailableArtifacts(context, docsState) {
+  const artifacts = [];
+  if (docsState === "repo_docs") {
+    const readmePath = path.join(context.appRoot, "README.md");
+    if (fs.existsSync(readmePath)) {
+      artifacts.push({
+        kind: "readme",
+        location: "repo",
+        path: path.relative(context.workspaceRoot, readmePath).replace(/\\/g, "/"),
+      });
+    }
+  }
+  return artifacts;
+}
+
+function determineBootstrapMode(intake, requestedMode) {
+  const normalizedRequested = normalizeEnum(requestedMode || "auto", BOOTSTRAP_MODES) || "auto";
+
+  if (normalizedRequested === "handoff") {
+    return { requestedMode: normalizedRequested, mode: "agent_handoff", routeReason: "forced_handoff" };
+  }
+
+  if (normalizedRequested === "direct") {
+    const hasCore = intake.technicalLevel && intake.projectState && intake.documentationState && intake.decisionOwnership;
+    return {
+      requestedMode: normalizedRequested,
+      mode: hasCore ? "direct_cli" : "agent_handoff",
+      routeReason: hasCore ? "forced_direct" : "insufficient_docs",
+    };
+  }
+
+  if (!["high", "senior"].includes(intake.technicalLevel)) {
+    return { requestedMode: normalizedRequested, mode: "agent_handoff", routeReason: "non_technical_user" };
+  }
+  if (!["existing_repo", "advanced"].includes(intake.projectState)) {
+    return { requestedMode: normalizedRequested, mode: "agent_handoff", routeReason: "idea_stage" };
+  }
+  if (!["sos", "spec_dossier", "repo_docs"].includes(intake.documentationState)) {
+    return { requestedMode: normalizedRequested, mode: "agent_handoff", routeReason: "insufficient_docs" };
+  }
+  if (!["user", "shared"].includes(intake.decisionOwnership)) {
+    return { requestedMode: normalizedRequested, mode: "agent_handoff", routeReason: "agent_owned_decisions" };
+  }
+  return { requestedMode: normalizedRequested, mode: "direct_cli", routeReason: "technical_existing_project" };
+}
+
+function directMissingFields(discovery) {
+  const missing = [];
+  if (!discovery.problemStatement) missing.push("problemStatement");
+  if (!discovery.targetUser) missing.push("targetUser");
+  if (!discovery.singularDesiredOutcome) missing.push("singularDesiredOutcome");
+  if (!discovery.sourceOfTruth) missing.push("sourceOfTruth");
+  if (!discovery.payload) missing.push("payload");
+  if (!Object.keys(discovery.inputSchema || {}).length) missing.push("inputSchema");
+  if (!Object.keys(discovery.outputSchema || {}).length) missing.push("outputSchema");
+  return missing;
+}
+
+function buildHandoffPayload(control, profile, context) {
+  const relative = bootstrapRelativePaths(context);
+  return {
+    version: 1,
+    skill: "project-starter-skill",
+    technicalLevel: profile.technicalLevel,
+    explanationMode: explanationModeFor(profile.technicalLevel),
+    decisionOwnership: profile.discovery?.decisionOwnership || profile.decisionOwnership || null,
+    projectState: profile.projectState,
+    documentationState: profile.documentationState,
+    availableArtifacts: control.meta?.discovery?.availableArtifacts || [],
+    problemStatement: profile.discovery?.problemStatement || "",
+    targetUser: profile.discovery?.targetUser || "",
+    singularDesiredOutcome: profile.discovery?.singularDesiredOutcome || "",
+    files: {
+      intakeJson: relative.intakeJson,
+      specDossier: relative.specDossier,
+      openQuestions: relative.openQuestions,
+    },
+  };
+}
+
+function buildHandoffPrompt(control, profile) {
+  const lines = [
+    "# TrackOps agent handoff",
+    "",
+    "Use `project-starter-skill` as a discovery and structuring skill for this project.",
+    "",
+    "## User profile",
+    `- Technical level: ${profile.technicalLevel || "unknown"}`,
+    `- Explanation mode: ${explanationModeFor(profile.technicalLevel)}`,
+    `- Decision ownership: ${profile.discovery?.decisionOwnership || profile.decisionOwnership || "unknown"}`,
+    "",
+    "## Project state",
+    `- Project state: ${profile.projectState || "unknown"}`,
+    `- Documentation state: ${profile.documentationState || "unknown"}`,
+    "",
+    "## What to do",
+    "- Start from the user, not from architecture assumptions.",
+    "- Adapt depth and language to the user's technical level.",
+    "- If documentation exists, read it, summarize it, and consolidate it.",
+    "- If documentation does not exist, help the user turn the idea into a workable project specification.",
+    "- Write `ops/bootstrap/intake.json` with the structured discovery output.",
+    "- Write `ops/bootstrap/spec-dossier.md` with the narrative or technical specification that OPERA will ingest.",
+    "- Write `ops/bootstrap/open-questions.md` if important uncertainties remain.",
+    "- Include explicit fields for problem statement, target user, desired outcome, source of truth, delivery target, and schemas.",
+  ];
+
+  if (profile.discovery?.singularDesiredOutcome) {
+    lines.push("", `Known project intention: ${profile.discovery.singularDesiredOutcome}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
 
+async function askQuestion(rl, message, defaultValue) {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = await rl.question(`${message}${suffix}: `);
+  return String(answer || "").trim() || String(defaultValue || "").trim();
+}
+
 async function collectBootstrapProfile(root, control, options = {}) {
   const context = config.ensureContext(root);
   const locale = config.getLocale(control);
   setLocale(locale);
   const scan = scanProject(context);
-  const previous = control.meta?.opera?.bootstrap?.discovery || {};
-  const interactive = options.interactive !== false && isInteractive();
-
-  const defaults = {
-    desiredOutcome: options.answers?.desiredOutcome || previous.desiredOutcome || scan.description || "",
-    externalServices: normalizeList(options.answers?.externalServices || previous.externalServices || scan.services),
-    sourceOfTruth: options.answers?.sourceOfTruth || previous.sourceOfTruth || scan.sourceOfTruthHint || "",
-    payload: options.answers?.payload || previous.payload || scan.payloadHint || "",
-    behaviorRules: normalizeList(options.answers?.behaviorRules || previous.behaviorRules || ""),
-    inputSchema: options.answers?.inputSchema || previous.inputSchema || {},
-    outputSchema: options.answers?.outputSchema || previous.outputSchema || {},
-    architecturalInvariants: normalizeList(options.answers?.architecturalInvariants || previous.architecturalInvariants || ""),
-    pipeline: normalizeList(options.answers?.pipeline || previous.pipeline || ""),
-    templates: normalizeList(options.answers?.templates || previous.templates || ""),
-    repoTaskPolicy: options.answers?.repoTaskPolicy || control.meta?.opera?.bootstrap?.repoTaskPolicy || "optional_pending",
-  };
-
-  const answers = { ...defaults };
-
-  if (interactive) {
+  const previousUser = control.meta?.userProfile || {};
+  const previousDiscovery = control.meta?.discovery || {};
+  const previousBootstrap = getBootstrapState(control, context);
+  const previous = previousBootstrap?.discovery || {};
+  const interactive = options.interactive !== false && isInteractive();
+
+  const defaults = {
+    technicalLevel: normalizeEnum(options.technicalLevel || options.answers?.technicalLevel || previousUser.technicalLevel, TECHNICAL_LEVELS),
+    projectState: normalizeEnum(options.projectState || options.answers?.projectState || previousDiscovery.projectState, PROJECT_STATES),
+    documentationState: normalizeEnum(options.docsState || options.answers?.documentationState || previousDiscovery.documentationState, DOC_STATES),
+    decisionOwnership: normalizeEnum(options.decisionOwnership || options.answers?.decisionOwnership || previous.decisionOwnership, DECISION_OWNERSHIPS),
+    problemStatement: options.answers?.problemStatement || previous.problemStatement || "",
+    targetUser: options.answers?.targetUser || previous.targetUser || "",
+    singularDesiredOutcome:
+      options.answers?.singularDesiredOutcome ||
+      options.answers?.desiredOutcome ||
+      previous.singularDesiredOutcome ||
+      previous.desiredOutcome ||
+      scan.description ||
+      "",
+    userLanguage: options.answers?.userLanguage || previous.userLanguage || locale,
+    needsPlainLanguage: options.answers?.needsPlainLanguage ?? previous.needsPlainLanguage ?? false,
+    recommendedStack: normalizeList(options.answers?.recommendedStack || previous.recommendedStack || scan.stacks),
+    externalServices: normalizeList(options.answers?.externalServices || previous.externalServices || scan.services),
+    sourceOfTruth: options.answers?.sourceOfTruth || previous.sourceOfTruth || scan.sourceOfTruthHint || "",
+    payload: options.answers?.payload || previous.payload || scan.payloadHint || "",
+    behaviorRules: normalizeList(options.answers?.behaviorRules || previous.behaviorRules || ""),
+    inputSchema: options.answers?.inputSchema || previous.inputSchema || {},
+    outputSchema: options.answers?.outputSchema || previous.outputSchema || {},
+    architecturalInvariants: normalizeList(options.answers?.architecturalInvariants || previous.architecturalInvariants || ""),
+    pipeline: normalizeList(options.answers?.pipeline || previous.pipeline || ""),
+    templates: normalizeList(options.answers?.templates || previous.templates || ""),
+    availableArtifacts: Array.isArray(previousDiscovery.availableArtifacts) ? previousDiscovery.availableArtifacts : [],
+  };
+
+  const answers = { ...defaults };
+
+  if (interactive) {
     console.log("");
-    console.log(t("bootstrap.header"));
-    console.log(t("bootstrap.subtitle"));
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    try {
-      answers.desiredOutcome = await askQuestion(rl, t("bootstrap.question.desiredOutcome"), defaults.desiredOutcome);
-      answers.externalServices = normalizeList(await askQuestion(rl, t("bootstrap.question.externalServices"), defaults.externalServices.join(", ")));
-      answers.sourceOfTruth = await askQuestion(rl, t("bootstrap.question.sourceOfTruth"), defaults.sourceOfTruth);
-      answers.payload = await askQuestion(rl, t("bootstrap.question.payload"), defaults.payload);
-      answers.behaviorRules = normalizeList(await askQuestion(rl, t("bootstrap.question.behaviorRules"), defaults.behaviorRules.join("; ")));
-      answers.inputSchema = parseJsonValue(await askQuestion(rl, t("bootstrap.question.inputSchema"), JSON.stringify(defaults.inputSchema)));
-      answers.outputSchema = parseJsonValue(await askQuestion(rl, t("bootstrap.question.outputSchema"), JSON.stringify(defaults.outputSchema)));
-      answers.architecturalInvariants = normalizeList(await askQuestion(rl, t("bootstrap.question.invariants"), defaults.architecturalInvariants.join("; ")));
-      answers.pipeline = normalizeList(await askQuestion(rl, t("bootstrap.question.pipeline"), defaults.pipeline.join("; ")));
-      answers.templates = normalizeList(await askQuestion(rl, t("bootstrap.question.templates"), defaults.templates.join(", ")));
-      const repoDefault = defaults.repoTaskPolicy === "skip" ? "n" : "y";
-      const includeRepoTasks = await askQuestion(rl, t("bootstrap.question.repoTasks"), repoDefault);
-      answers.repoTaskPolicy = includeRepoTasks.toLowerCase().startsWith("n") ? "skip" : "optional_pending";
-    } finally {
-      rl.close();
-    }
-  }
-
-  const missingFields = [];
-  if (!answers.desiredOutcome) missingFields.push("desiredOutcome");
-  if (!answers.sourceOfTruth) missingFields.push("sourceOfTruth");
-  if (!answers.payload) missingFields.push("payload");
-  if (!Object.keys(answers.inputSchema || {}).length) missingFields.push("inputSchema");
-  if (!Object.keys(answers.outputSchema || {}).length) missingFields.push("outputSchema");
-
-  return {
-    version: 1,
-    localeAtBootstrap: locale,
-    status: missingFields.length ? "pending" : "completed",
-    mode: interactive ? "guided" : "non_interactive",
-    source: "hybrid",
-    startedAt: control.meta?.opera?.bootstrap?.startedAt || nowIso(),
-    completedAt: missingFields.length ? null : nowIso(),
-    missingFields,
-    repoTaskPolicy: answers.repoTaskPolicy || "optional_pending",
-    discovery: answers,
-    inference: scan,
-  };
-}
-
-function isVirginGenesis(content) {
-  const text = String(content || "");
-  return !text.trim() || /TODO:/i.test(text) || /The Constitution of the project/i.test(text) || /La Constitución del proyecto/i.test(text);
-}
-
-function renderGenesis(control, profile) {
-  const locale = config.getLocale(control);
-  const templatePath = resolveLocalizedFile(TEMPLATES_DIR, locale, "genesis.md");
-  let content = fs.readFileSync(templatePath, "utf8");
-  const rules = (profile.discovery.behaviorRules || []).map((item) => `- ${item}`).join("\n") || `- ${t("bootstrap.noneDefined")}`;
-  const invariants = (profile.discovery.architecturalInvariants || []).map((item) => `- ${item}`).join("\n") || `- ${t("bootstrap.noneDefined")}`;
-  const services = (profile.discovery.externalServices || []).length
-    ? profile.discovery.externalServices.map((item) => `| ${item} | ${t("bootstrap.servicePending")} | ${t("bootstrap.servicePending")} |`).join("\n")
-    : `| — | — | — |`;
-  const pipeline = (profile.discovery.pipeline || []).length
-    ? profile.discovery.pipeline.map((item) => `- ${item}`).join("\n")
-    : `- ${t("bootstrap.noneDefined")}`;
-  const templates = (profile.discovery.templates || []).length
-    ? profile.discovery.templates.map((item) => `- \`${item}\``).join("\n")
-    : `- ${t("bootstrap.noneDefined")}`;
-  const schema = JSON.stringify({
-    input: {
-      source: profile.discovery.sourceOfTruth,
-      schema: profile.discovery.inputSchema || {},
-    },
-    output: {
-      destination: profile.discovery.payload,
-      schema: profile.discovery.outputSchema || {},
-    },
-  }, null, 2);
+    console.log(t("bootstrap.header"));
+    console.log(t("bootstrap.subtitle"));
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      answers.technicalLevel = normalizeEnum(await askQuestion(rl, t("bootstrap.question.technicalLevel"), defaults.technicalLevel || "medium"), TECHNICAL_LEVELS) || "medium";
+      answers.projectState = normalizeEnum(await askQuestion(rl, t("bootstrap.question.projectState"), defaults.projectState || "idea"), PROJECT_STATES) || "idea";
+      answers.documentationState = normalizeEnum(await askQuestion(rl, t("bootstrap.question.docsState"), defaults.documentationState || "none"), DOC_STATES) || "none";
+      answers.decisionOwnership = normalizeEnum(await askQuestion(rl, t("bootstrap.question.decisionOwnership"), defaults.decisionOwnership || "shared"), DECISION_OWNERSHIPS) || "shared";
+    } finally {
+      rl.close();
+    }
+  }
+
+  answers.availableArtifacts = answers.availableArtifacts.length
+    ? answers.availableArtifacts
+    : buildAvailableArtifacts(context, answers.documentationState);
+
+  const routing = determineBootstrapMode(answers, options.bootstrapMode);
+
+  if (routing.mode === "agent_handoff") {
+    return {
+      version: 2,
+      status: "awaiting_agent",
+      mode: "agent_handoff",
+      routeReason: routing.routeReason,
+      technicalLevel: answers.technicalLevel,
+      projectState: answers.projectState,
+      documentationState: answers.documentationState,
+      decisionOwnership: answers.decisionOwnership,
+      startedAt: previousBootstrap?.startedAt || nowIso(),
+      completedAt: null,
+      missingFields: ["intakeJson", "specDossier"],
+      discovery: answers,
+      inference: scan,
+    };
+  }
+
+  if (interactive) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      answers.problemStatement = await askQuestion(rl, t("bootstrap.question.problemStatement"), defaults.problemStatement);
+      answers.targetUser = await askQuestion(rl, t("bootstrap.question.targetUser"), defaults.targetUser);
+      answers.singularDesiredOutcome = await askQuestion(rl, t("bootstrap.question.desiredOutcome"), defaults.singularDesiredOutcome);
+      answers.externalServices = normalizeList(await askQuestion(rl, t("bootstrap.question.externalServices"), defaults.externalServices.join(", ")));
+      answers.sourceOfTruth = await askQuestion(rl, t("bootstrap.question.sourceOfTruth"), defaults.sourceOfTruth);
+      answers.payload = await askQuestion(rl, t("bootstrap.question.payload"), defaults.payload);
+      answers.behaviorRules = normalizeList(await askQuestion(rl, t("bootstrap.question.behaviorRules"), defaults.behaviorRules.join("; ")));
+      answers.inputSchema = parseJsonValue(await askQuestion(rl, t("bootstrap.question.inputSchema"), JSON.stringify(defaults.inputSchema)));
+      answers.outputSchema = parseJsonValue(await askQuestion(rl, t("bootstrap.question.outputSchema"), JSON.stringify(defaults.outputSchema)));
+      answers.architecturalInvariants = normalizeList(await askQuestion(rl, t("bootstrap.question.invariants"), defaults.architecturalInvariants.join("; ")));
+      answers.pipeline = normalizeList(await askQuestion(rl, t("bootstrap.question.pipeline"), defaults.pipeline.join("; ")));
+      answers.templates = normalizeList(await askQuestion(rl, t("bootstrap.question.templates"), defaults.templates.join(", ")));
+    } finally {
+      rl.close();
+    }
+  }
+
+  const missingFields = directMissingFields(answers);
+  return {
+    version: 2,
+    status: missingFields.length ? "awaiting_intake" : "completed",
+    mode: "direct_cli",
+    routeReason: routing.routeReason,
+    technicalLevel: answers.technicalLevel,
+    projectState: answers.projectState,
+    documentationState: answers.documentationState,
+    decisionOwnership: answers.decisionOwnership,
+    startedAt: previousBootstrap?.startedAt || nowIso(),
+    completedAt: missingFields.length ? null : nowIso(),
+    missingFields,
+    discovery: answers,
+    inference: scan,
+  };
+}
 
-  const replacements = {
-    PROJECT_NAME: control.meta.projectName || "Project",
-    DESIRED_OUTCOME: profile.discovery.desiredOutcome || t("bootstrap.pendingValue"),
-    SERVICES_TABLE: services,
-    SOURCE_OF_TRUTH: profile.discovery.sourceOfTruth || t("bootstrap.pendingValue"),
-    PAYLOAD: profile.discovery.payload || t("bootstrap.pendingValue"),
-    BEHAVIOR_RULES: rules,
-    DATA_SCHEMA: schema,
-    ARCHITECTURAL_INVARIANTS: invariants,
-    PIPELINE_ITEMS: pipeline,
+function isVirginGenesis(content) {
+  const text = String(content || "");
+  return !text.trim() || /TODO:/i.test(text) || /The Constitution of the project/i.test(text) || /La Constitución del proyecto/i.test(text);
+}
+
+function parseSpecSections(specText) {
+  const sections = {};
+  const lines = String(specText || "").split(/\r?\n/);
+  let current = null;
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      current = heading[1].trim().toLowerCase();
+      sections[current] = [];
+      continue;
+    }
+    if (current) sections[current].push(line);
+  }
+  return Object.fromEntries(
+    Object.entries(sections).map(([key, value]) => [key, value.join("\n").trim()]),
+  );
+}
+
+function buildOpenQuestions(missingFields, contradictions) {
+  const lines = ["# Open questions", ""];
+  if (missingFields.length) {
+    lines.push("## Missing fields", "");
+    missingFields.forEach((field) => lines.push(`- ${field}`));
+    lines.push("");
+  }
+  if (contradictions.length) {
+    lines.push("## Contradictions", "");
+    contradictions.forEach((item) => lines.push(`- ${item}`));
+    lines.push("");
+  }
+  if (!missingFields.length && !contradictions.length) {
+    lines.push("- None.");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function qualityStatusFor(missingFields, contradictions) {
+  if (missingFields.length >= 2) return "blocked";
+  if (missingFields.length || contradictions.length) return "needs_review";
+  return "ready";
+}
+
+function contractReadinessFor(profile, qualityStatus) {
+  if (qualityStatus === "blocked") return "hypothesis";
+  if (qualityStatus === "needs_review") return "provisional";
+  if (
+    ["sos", "spec_dossier"].includes(profile.documentationState) &&
+    profile.discovery?.decisionOwnership === "user" &&
+    profile.mode === "direct_cli"
+  ) {
+    return "locked";
+  }
+  return "verified";
+}
+
+function buildQualityReport(context, profile, specText) {
+  const sections = parseSpecSections(specText);
+  const missingFields = directMissingFields(profile.discovery);
+  if (!profile.discovery.decisionOwnership) missingFields.push("decisionOwnership");
+  if (!profile.discovery.problemStatement) missingFields.push("problemStatement");
+  if (!profile.discovery.targetUser) missingFields.push("targetUser");
+
+  const contradictions = [];
+  const mappings = [
+    ["problem statement", "problemStatement", profile.discovery.problemStatement],
+    ["target user", "targetUser", profile.discovery.targetUser],
+    ["singular desired outcome", "singularDesiredOutcome", profile.discovery.singularDesiredOutcome],
+    ["delivery target", "payload", profile.discovery.payload],
+    ["source of truth", "sourceOfTruth", profile.discovery.sourceOfTruth],
+  ];
+  for (const [sectionName, fieldName, expected] of mappings) {
+    const actual = sections[sectionName];
+    if (!actual) {
+      missingFields.push(fieldName);
+      continue;
+    }
+    if (expected && actual && normalizeText(actual) !== normalizeText(expected)) {
+      contradictions.push(`${sectionName}: spec dossier and intake disagree`);
+    }
+  }
+
+  const status = qualityStatusFor(unique(missingFields), contradictions);
+  const contractReadiness = contractReadinessFor(profile, status);
+  const report = {
+    version: 1,
+    status,
+    missingFields: unique(missingFields),
+    contradictions,
+    contractReadiness,
+    validatedAt: nowIso(),
+    handoffMode: profile.mode,
+  };
+  const files = bootstrapFilePaths(context);
+  writeJson(files.qualityReport, report);
+  writeText(files.openQuestions, buildOpenQuestions(report.missingFields, report.contradictions));
+  return report;
+}
+
+function normalizeText(value) {
+  return String(value || "").trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function buildOperatingContract(control, profile, qualityReport, context) {
+  const discovery = profile.discovery || {};
+  return {
+    version: CONTRACT_VERSION,
+    intent: {
+      problemStatement: discovery.problemStatement || "",
+      targetUser: discovery.targetUser || "",
+      singularDesiredOutcome: discovery.singularDesiredOutcome || "",
+      deliveryTarget: discovery.payload || "",
+    },
+    userModel: {
+      technicalLevel: profile.technicalLevel || null,
+      explanationMode: explanationModeFor(profile.technicalLevel),
+      decisionOwnership: discovery.decisionOwnership || profile.decisionOwnership || null,
+      language: discovery.userLanguage || config.getLocale(control),
+      needsPlainLanguage: Boolean(discovery.needsPlainLanguage || profile.technicalLevel === "low"),
+    },
+    evidence: {
+      projectState: profile.projectState || null,
+      documentationState: profile.documentationState || null,
+      sourceArtifacts: discovery.availableArtifacts || [],
+      repoScan: profile.inference || {},
+    },
+    system: {
+      sourceOfTruth: discovery.sourceOfTruth || "",
+      externalServices: discovery.externalServices || [],
+      inputSchema: discovery.inputSchema || {},
+      outputSchema: discovery.outputSchema || {},
+      behaviorRules: discovery.behaviorRules || [],
+      architecturalInvariants: discovery.architecturalInvariants || [],
+    },
+    execution: {
+      pipeline: discovery.pipeline || [],
+      templates: discovery.templates || [],
+      phaseModel: "opera-v3",
+      taskSeeds: buildSeedTasks(control, profile).map((task) => task.id),
+    },
+    governance: {
+      policyFile: policyRelativePath(context),
+      riskProfile: "standard",
+      approvalRules: [
+        "destructive_changes_require_approval",
+        "production_deploy_requires_approval",
+        "external_side_effects_require_approval",
+      ],
+    },
+    quality: {
+      contractReadiness: qualityReport.contractReadiness,
+      openQuestions: qualityReport.missingFields.concat(qualityReport.contradictions),
+      lastValidatedAt: qualityReport.validatedAt,
+    },
+  };
+}
+
+function writeAutonomyPolicy(context) {
+  const payload = {
+    version: 1,
+    defaultRiskProfile: "standard",
+    levels: {
+      green: ["read_files", "run_tests", "update_operational_docs", "write_tmp_files"],
+      yellow: ["install_dependencies", "change_structure", "modify_pipeline"],
+      red: ["delete_persistent_data", "deploy_to_production", "external_side_effects", "security_changes"],
+    },
+    approvalRules: {
+      destructive_changes_require_approval: true,
+      production_deploy_requires_approval: true,
+      external_side_effects_require_approval: true,
+    },
+  };
+  writeJson(context.paths.autonomyPolicyFile, payload);
+}
+
+function renderGenesis(control, contract) {
+  const locale = config.getLocale(control);
+  const templatePath = resolveLocalizedFile(TEMPLATES_DIR, locale, "genesis.md");
+  let content = fs.readFileSync(templatePath, "utf8");
+  const rules = (contract.system.behaviorRules || []).map((item) => `- ${item}`).join("\n") || `- ${t("bootstrap.noneDefined")}`;
+  const invariants = (contract.system.architecturalInvariants || []).map((item) => `- ${item}`).join("\n") || `- ${t("bootstrap.noneDefined")}`;
+  const services = (contract.system.externalServices || []).length
+    ? contract.system.externalServices.map((item) => `| ${item} | ${t("bootstrap.servicePending")} | ${t("bootstrap.servicePending")} |`).join("\n")
+    : `| — | — | — |`;
+  const pipeline = (contract.execution.pipeline || []).length
+    ? contract.execution.pipeline.map((item) => `- ${item}`).join("\n")
+    : `- ${t("bootstrap.noneDefined")}`;
+  const templates = (contract.execution.templates || []).length
+    ? contract.execution.templates.map((item) => `- \`${item}\``).join("\n")
+    : `- ${t("bootstrap.noneDefined")}`;
+  const schema = JSON.stringify({
+    input: {
+      source: contract.system.sourceOfTruth,
+      schema: contract.system.inputSchema || {},
+    },
+    output: {
+      destination: contract.intent.deliveryTarget,
+      schema: contract.system.outputSchema || {},
+    },
+  }, null, 2);
+
+  const replacements = {
+    PROJECT_NAME: control.meta.projectName || "Project",
+    DESIRED_OUTCOME: contract.intent.singularDesiredOutcome || t("bootstrap.pendingValue"),
+    SERVICES_TABLE: services,
+    SOURCE_OF_TRUTH: contract.system.sourceOfTruth || t("bootstrap.pendingValue"),
+    PAYLOAD: contract.intent.deliveryTarget || t("bootstrap.pendingValue"),
+    BEHAVIOR_RULES: rules,
+    DATA_SCHEMA: schema,
+    ARCHITECTURAL_INVARIANTS: invariants,
+    PIPELINE_ITEMS: pipeline,
     TEMPLATE_ITEMS: templates,
   };
 
@@ -285,29 +727,49 @@ function renderGenesis(control, profile) {
   return content;
 }
 
-function buildSeedTasks(control, profile) {
-  const phaseOrder = config.getPhases(control);
-  const tasks = [
-    {
-      id: "opera-bootstrap",
-      origin: "bootstrap",
-      title: t("bootstrap.task.bootstrap.title"),
-      phase: phaseOrder[0]?.id || "O",
-      stream: "Operations",
-      priority: "P0",
-      status: profile.status === "completed" ? "completed" : "blocked",
-      required: true,
-      dependsOn: [],
-      summary: t("bootstrap.task.bootstrap.summary"),
-      acceptance: [
-        t("bootstrap.acceptance.discovery"),
-        t("bootstrap.acceptance.schema"),
-        t("bootstrap.acceptance.rules"),
-        t("bootstrap.acceptance.plan"),
-      ],
-      blocker: profile.status === "completed" ? undefined : t("bootstrap.blocker.missingData"),
-      history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
-    },
+function buildSeedTasks(control, profile) {
+  const phaseOrder = config.getPhases(control);
+  const firstTaskStatus =
+    profile.status === "completed"
+      ? "completed"
+      : ["blocked", "needs_review"].includes(profile.status)
+        ? "blocked"
+      : profile.mode === "agent_handoff"
+        ? (profile.status === "awaiting_agent" ? "blocked" : "pending")
+        : "blocked";
+  const tasks = [
+    {
+      id: "opera-bootstrap",
+      origin: "bootstrap",
+      title: t("bootstrap.task.bootstrap.title"),
+      phase: phaseOrder[0]?.id || "O",
+      stream: "Operations",
+      priority: "P0",
+      status: firstTaskStatus,
+      required: true,
+      dependsOn: [],
+      summary: profile.mode === "agent_handoff"
+        ? t("bootstrap.task.bootstrap.handoffSummary")
+        : t("bootstrap.task.bootstrap.summary"),
+      acceptance: profile.mode === "agent_handoff"
+        ? [
+            t("bootstrap.acceptance.intake"),
+            t("bootstrap.acceptance.specDossier"),
+            t("bootstrap.acceptance.resume"),
+          ]
+        : [
+            t("bootstrap.acceptance.discovery"),
+            t("bootstrap.acceptance.schema"),
+            t("bootstrap.acceptance.rules"),
+            t("bootstrap.acceptance.plan"),
+          ],
+      blocker: profile.status === "completed"
+        ? undefined
+        : profile.mode === "agent_handoff"
+          ? t("bootstrap.blocker.awaitingAgent")
+          : t("bootstrap.blocker.missingData"),
+      history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
+    },
     {
       id: "opera-prove-integrations",
       origin: "bootstrap",
@@ -385,139 +847,229 @@ function buildSeedTasks(control, profile) {
     },
   ];
 
-  if (profile.repoTaskPolicy !== "skip") {
-    tasks.push(
-      {
-        id: "repo-readme-align",
-        origin: "bootstrap",
-        title: t("bootstrap.task.repoReadme.title"),
-        phase: phaseOrder[0]?.id || "O",
-        stream: "Repository",
-        priority: "P2",
-        status: "pending",
-        required: false,
-        dependsOn: [],
-        summary: t("bootstrap.task.repoReadme.summary"),
-        acceptance: [],
-        history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
-      },
-      {
-        id: "repo-license-review",
-        origin: "bootstrap",
-        title: t("bootstrap.task.repoLicense.title"),
-        phase: phaseOrder[0]?.id || "O",
-        stream: "Repository",
-        priority: "P3",
-        status: "pending",
-        required: false,
-        dependsOn: [],
-        summary: t("bootstrap.task.repoLicense.summary"),
-        acceptance: [],
-        history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
-      },
-      {
-        id: "repo-changelog-policy",
-        origin: "bootstrap",
-        title: t("bootstrap.task.repoChangelog.title"),
-        phase: phaseOrder[0]?.id || "O",
-        stream: "Repository",
-        priority: "P3",
-        status: "pending",
-        required: false,
-        dependsOn: [],
-        summary: t("bootstrap.task.repoChangelog.summary"),
-        acceptance: [],
-        history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
-      },
-    );
-
-    if (profile.inference.gitRemote && profile.inference.gitRemote.includes("github")) {
-      tasks.push({
-        id: "repo-github-governance",
-        origin: "bootstrap",
-        title: t("bootstrap.task.repoGithub.title"),
-        phase: phaseOrder[0]?.id || "O",
-        stream: "Repository",
-        priority: "P3",
-        status: "pending",
-        required: false,
-        dependsOn: [],
-        summary: t("bootstrap.task.repoGithub.summary"),
-        acceptance: [],
-        history: [{ at: nowIso(), action: "create", note: t("bootstrap.history.seeded") }],
-      });
-    }
-  }
-
-  return tasks;
-}
-
+  return tasks;
+}
+
+function createAwaitingBootstrapState(context) {
+  return {
+    version: CONTRACT_VERSION,
+    mode: null,
+    status: "awaiting_intake",
+    routeReason: null,
+    technicalLevel: null,
+    projectState: null,
+    documentationState: null,
+    decisionOwnership: null,
+    startedAt: nowIso(),
+    completedAt: null,
+    missingFields: [],
+    discovery: {},
+    handoffFiles: {
+      markdown: bootstrapRelativePaths(context).markdown,
+      json: bootstrapRelativePaths(context).json,
+    },
+    intakeFiles: {
+      json: bootstrapRelativePaths(context).intakeJson,
+      specDossier: bootstrapRelativePaths(context).specDossier,
+    },
+    reviewFiles: {
+      openQuestions: bootstrapRelativePaths(context).openQuestions,
+      qualityReport: bootstrapRelativePaths(context).qualityReport,
+    },
+    inference: scanProject(context),
+  };
+}
+
 function applyBootstrap(root, control, profile) {
   const context = config.ensureContext(root);
   setLocale(config.getLocale(control));
-  control.meta.opera = control.meta.opera || {};
-  control.meta.opera.bootstrap = profile;
-  control.meta.currentFocus = profile.discovery.desiredOutcome || t("bootstrap.defaultFocus");
-  control.meta.deliveryTarget = profile.discovery.payload || t("bootstrap.defaultTarget");
-  control.meta.focusPhase = profile.status === "completed" ? "P" : "O";
-  control.meta.phases = config.getPhases(control);
-
-  const remainingTasks = (control.tasks || []).filter((task) => task.id !== "ops-bootstrap" && task.origin !== "bootstrap");
-  control.tasks = [...remainingTasks, ...buildSeedTasks(control, profile)];
-
-  control.decisionsPending = (profile.missingFields || []).map((field) => ({
-    owner: "user",
-    title: t(`bootstrap.field.${field}`),
-    impact: t("bootstrap.decisionImpact"),
-  }));
+  control.meta = control.meta || {};
+  control.meta.opera = control.meta.opera || {};
+  control.meta.opera.model = "v3";
+  writeAutonomyPolicy(context);
+  control.meta.userProfile = {
+    technicalLevel: profile.technicalLevel || null,
+    explanationMode: explanationModeFor(profile.technicalLevel),
+    capturedAt: nowIso(),
+  };
+  control.meta.discovery = {
+    projectState: profile.projectState || null,
+    documentationState: profile.documentationState || null,
+    availableArtifacts: Array.isArray(profile.discovery?.availableArtifacts) ? profile.discovery.availableArtifacts : [],
+  };
+  const relative = bootstrapRelativePaths(context);
+  control.meta.opera.bootstrap = {
+    ...profile,
+    handoffFiles: {
+      markdown: relative.markdown,
+      json: relative.json,
+    },
+    intakeFiles: {
+      json: relative.intakeJson,
+      specDossier: relative.specDossier,
+    },
+    reviewFiles: {
+      openQuestions: relative.openQuestions,
+      qualityReport: relative.qualityReport,
+    },
+  };
+  control.meta.currentFocus = profile.discovery.singularDesiredOutcome || profile.discovery.desiredOutcome || t("bootstrap.defaultFocus");
+  control.meta.deliveryTarget = profile.discovery.payload || t("bootstrap.defaultTarget");
+  control.meta.focusPhase = profile.status === "completed" ? "P" : "O";
+  control.meta.phases = config.getPhases(control);
+  control.meta.opera.legacyStatus = "supported";
+
+  const remainingTasks = (control.tasks || []).filter((task) => task.id !== "ops-bootstrap" && task.origin !== "bootstrap");
+  control.tasks = [...remainingTasks, ...buildSeedTasks(control, profile)];
 
-  control.findings = control.findings || [];
+  control.decisionsPending = (profile.missingFields || [])
+    .filter((field) => !["intakeJson", "specDossier"].includes(field))
+    .map((field) => ({
+      owner: "user",
+      title: t(`bootstrap.field.${field}`),
+      impact: t("bootstrap.decisionImpact"),
+    }));
+  if (profile.mode === "agent_handoff" && profile.status !== "completed") {
+    control.decisionsPending.unshift({
+      owner: "user",
+      title: t("bootstrap.pendingDecision.handoff"),
+      impact: t("bootstrap.pendingDecision.handoffImpact"),
+    });
+  }
+
+  control.findings = control.findings || [];
+  const files = bootstrapFilePaths(context);
+  if (profile.mode === "agent_handoff") {
+    writeJson(files.json, buildHandoffPayload(control, profile, context));
+    writeText(files.markdown, buildHandoffPrompt(control, profile));
+    if (!fs.existsSync(files.specDossier)) {
+      writeText(files.specDossier, "# Spec dossier\n\nUse this file to consolidate the project specification before OPERA ingest.\n");
+    }
+    writeText(files.openQuestions, buildOpenQuestions(["intakeJson", "specDossier"], []));
+  }
   const genesisPath = context.paths.genesisFile;
-  const existingGenesis = readText(genesisPath);
-  if (!existingGenesis || isVirginGenesis(existingGenesis)) {
-    fs.writeFileSync(genesisPath, `${renderGenesis(control, profile)}\n`, "utf8");
-  } else if (profile.status !== "completed") {
-    const duplicate = control.findings.some((finding) => finding.title === t("bootstrap.finding.genesisConflictTitle"));
-    if (!duplicate) {
-      control.findings.push({
-        status: "open",
-        severity: "medium",
-        title: t("bootstrap.finding.genesisConflictTitle"),
-        detail: t("bootstrap.finding.genesisConflictDetail"),
-        impact: t("bootstrap.finding.genesisConflictImpact"),
-      });
-    }
-    control.meta.opera.bootstrap.status = "needs_review";
-  }
-
+  if (profile.status === "completed") {
+    const specText = fs.existsSync(files.specDossier) && readText(files.specDossier).trim()
+      ? readText(files.specDossier)
+      : `## Problem statement\n${profile.discovery.problemStatement || ""}\n\n## Target user\n${profile.discovery.targetUser || ""}\n\n## Singular desired outcome\n${profile.discovery.singularDesiredOutcome || ""}\n\n## Delivery target\n${profile.discovery.payload || ""}\n\n## Source of truth\n${profile.discovery.sourceOfTruth || ""}\n`;
+    const qualityReport = profile.qualityReport || buildQualityReport(context, profile, specText);
+    const contract = buildOperatingContract(control, profile, qualityReport, context);
+    writeJson(context.paths.contractFile, contract);
+    fs.writeFileSync(genesisPath, `${renderGenesis(control, contract)}\n`, "utf8");
+    control.meta.opera.contractVersion = CONTRACT_VERSION;
+    control.meta.opera.contractReadiness = qualityReport.contractReadiness;
+    control.meta.opera.contractFile = contractRelativePath(context);
+    control.meta.opera.qualityStatus = qualityReport.status;
+  } else if (["needs_review", "blocked"].includes(profile.status)) {
+    control.meta.opera.contractVersion = null;
+    control.meta.opera.contractReadiness = profile.qualityReport?.contractReadiness || "hypothesis";
+    control.meta.opera.qualityStatus = profile.qualityReport?.status || profile.status;
+  } else {
+    control.meta.opera.contractVersion = null;
+    control.meta.opera.contractReadiness = "hypothesis";
+    control.meta.opera.qualityStatus = profile.status;
+  }
+
   config.saveControl(context, control);
   return control;
 }
 
-function detectLegacyBootstrap(root, control) {
+function resumeBootstrap(root, control) {
   const context = config.ensureContext(root);
-  if (!config.isOperaInstalled(control)) return null;
-  if (control.meta?.opera?.bootstrap) return control.meta.opera.bootstrap;
-  const genesisContent = readText(context.paths.genesisFile);
-  return {
-    version: 1,
-    localeAtBootstrap: config.getLocale(control),
-    status: isVirginGenesis(genesisContent) ? "pending" : "needs_review",
-    mode: "legacy",
-    source: "legacy",
-    startedAt: control.meta?.opera?.installedAt || nowIso(),
-    completedAt: null,
-    missingFields: isVirginGenesis(genesisContent) ? ["desiredOutcome", "sourceOfTruth", "payload", "inputSchema", "outputSchema"] : [],
-    repoTaskPolicy: "optional_pending",
-    discovery: {},
+  const bootstrap = getBootstrapState(control, context);
+  if (!bootstrap) {
+    return { resumed: false, status: "awaiting_intake", reason: "no_bootstrap_state" };
+  }
+
+  const files = bootstrapFilePaths(context);
+  const intake = readJson(files.intakeJson);
+  const specDossier = readText(files.specDossier);
+  if (!intake || !specDossier.trim()) {
+    return { resumed: false, status: "awaiting_agent", reason: "missing_agent_artifacts" };
+  }
+
+  const discovery = {
+    ...bootstrap.discovery,
+    ...intake,
+    singularDesiredOutcome: intake.singularDesiredOutcome || bootstrap.discovery?.singularDesiredOutcome || "",
+    externalServices: normalizeList(intake.externalServices || bootstrap.discovery?.externalServices || []),
+    behaviorRules: normalizeList(intake.behaviorRules || bootstrap.discovery?.behaviorRules || []),
+    architecturalInvariants: normalizeList(intake.architecturalInvariants || bootstrap.discovery?.architecturalInvariants || []),
+    pipeline: normalizeList(intake.pipeline || bootstrap.discovery?.pipeline || []),
+    templates: normalizeList(intake.templates || bootstrap.discovery?.templates || []),
+    inputSchema: intake.inputSchema || bootstrap.discovery?.inputSchema || {},
+    outputSchema: intake.outputSchema || bootstrap.discovery?.outputSchema || {},
+  };
+  const missingFields = directMissingFields(discovery);
+  const profile = {
+    ...bootstrap,
+    mode: bootstrap.mode || "agent_handoff",
+    status: missingFields.length ? "needs_review" : "completed",
+    technicalLevel: intake.technicalLevel || bootstrap.technicalLevel || null,
+    projectState: intake.projectState || bootstrap.projectState || null,
+    documentationState: intake.documentationState || bootstrap.documentationState || null,
+    decisionOwnership: intake.decisionOwnership || bootstrap.decisionOwnership || null,
+    completedAt: missingFields.length ? null : nowIso(),
+    missingFields,
+    discovery,
     inference: scanProject(context),
   };
+  const qualityReport = buildQualityReport(context, profile, specDossier);
+  profile.status = qualityReport.status === "ready" ? "completed" : qualityReport.status;
+  profile.completedAt = qualityReport.status === "ready" ? nowIso() : null;
+  profile.qualityReport = qualityReport;
+  return { resumed: true, profile };
 }
-
-module.exports = {
-  scanProject,
-  collectBootstrapProfile,
-  applyBootstrap,
-  detectLegacyBootstrap,
-  isVirginGenesis,
-};
+
+function detectLegacyBootstrap(root, control) {
+  const context = config.ensureContext(root);
+  if (!config.isOperaInstalled(control)) return null;
+  if (control.meta?.opera?.bootstrap) return getBootstrapState(control, context);
+  if (control.meta?.opera?.model === "v3") {
+    return createAwaitingBootstrapState(context);
+  }
+  if (!fs.existsSync(context.paths.contractFile)) {
+    return {
+      version: CONTRACT_VERSION,
+      status: "legacy_unsupported",
+      mode: null,
+      routeReason: "legacy_unsupported",
+      technicalLevel: null,
+      projectState: null,
+      documentationState: null,
+      decisionOwnership: null,
+      startedAt: control.meta?.opera?.installedAt || nowIso(),
+      completedAt: null,
+      missingFields: [],
+      discovery: {},
+      inference: scanProject(context),
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  TECHNICAL_LEVELS,
+  PROJECT_STATES,
+  DOC_STATES,
+  DECISION_OWNERSHIPS,
+  BOOTSTRAP_MODES,
+  QUALITY_STATUSES,
+  CONTRACT_READINESS,
+  CONTRACT_VERSION,
+  bootstrapFilePaths,
+  bootstrapRelativePaths,
+  contractRelativePath,
+  policyRelativePath,
+  scanProject,
+  collectBootstrapProfile,
+  applyBootstrap,
+  resumeBootstrap,
+  detectLegacyBootstrap,
+  getBootstrapState,
+  buildQualityReport,
+  buildOperatingContract,
+  writeAutonomyPolicy,
+  createAwaitingBootstrapState,
+  isVirginGenesis,
+};