trackops 2.0.5 → 2.1.0

package/lib/opera-bootstrap.js

@@ -9,6 +9,7 @@ const config = require("./config");
 const { t, setLocale } = require("./i18n");
 const { isInteractive } = require("./locale");
 const { resolveLocalizedFile } = require("./resources");
+const fmt = require("./cli-format");
 
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates", "opera");
 
@@ -372,6 +373,7 @@ function directMissingFields(discovery) {
   if (!discovery.payload) missing.push("payload");
   if (!Object.keys(discovery.inputSchema || {}).length) missing.push("inputSchema");
   if (!Object.keys(discovery.outputSchema || {}).length) missing.push("outputSchema");
+  if (!discovery.decisionOwnership) missing.push("decisionOwnership");
   return missing;
 }
 
@@ -426,9 +428,44 @@ function buildHandoffPrompt(control, profile) {
     `- ${t("handoff.instruction.writeSpec")}`,
     `- ${t("handoff.instruction.writeQuestions")}`,
     `- ${t("handoff.instruction.includeFields")}`,
+    `- ${t("handoff.instruction.schemaFormat")}`,
+    `- ${t("handoff.instruction.decisionOwnership")}`,
     `- ${t("handoff.instruction.respondInLanguage", { language: languageName })}`,
+    `- **${t("handoff.instruction.neverRename")}**`,
+    `- **${t("handoff.instruction.closure")}**`,
   ];
 
+  lines.push(
+    "",
+    `## ${t("handoff.section.intakeSchema")}`,
+    "",
+    t("handoff.instruction.intakeRequired"),
+    "",
+    "```json",
+    JSON.stringify({
+      problemStatement: "string — core problem the project solves",
+      targetUser: "string — primary user persona",
+      singularDesiredOutcome: "string — single most important outcome",
+      sourceOfTruth: "string — authoritative data source",
+      payload: "string — what gets delivered (NOT 'deliveryTarget')",
+      decisionOwnership: "user | shared | agent",
+      versionControl: {
+        remote: "boolean — whether the project uses a remote VCS",
+        provider: "string — github | gitlab | bitbucket | other",
+        developmentBranch: "string — main development branch",
+        releaseBranch: "string — publish/release branch",
+      },
+      deployment: {
+        mode: "string — manual | ci | platform",
+        target: "string — staging | production | preview | custom",
+        smokeCommand: "string — command to validate a releasable/deployed build",
+      },
+      inputSchema: { "fieldName": "type — at least one key required" },
+      outputSchema: { "fieldName": "type — at least one key required" },
+    }, null, 2),
+    "```",
+  );
+
   if (profile.discovery?.singularDesiredOutcome) {
     lines.push("", `${t("handoff.label.knownIntention")}: ${profile.discovery.singularDesiredOutcome}`);
   }
@@ -482,21 +519,34 @@ async function collectBootstrapProfile(root, control, options = {}) {
     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 : [],
-  };
+    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 || ""),
+    versionControl: options.answers?.versionControl || previous.versionControl || {
+      remote: false,
+      provider: "",
+      developmentBranch: context.branches.development || "develop",
+      releaseBranch: context.branches.publish || "master",
+    },
+    deployment: options.answers?.deployment || previous.deployment || {
+      mode: "",
+      target: "",
+      smokeCommand: "",
+    },
+    availableArtifacts: Array.isArray(previousDiscovery.availableArtifacts) ? previousDiscovery.availableArtifacts : [],
+  };
 
   const answers = { ...defaults };
 
   if (interactive) {
-    console.log("");
-    console.log(t("bootstrap.header"));
-    console.log(t("bootstrap.subtitle"));
-    console.log(t("bootstrap.instructions"));
+    fmt.header(t("bootstrap.header"));
+    fmt.blank();
+    fmt.info(t("bootstrap.subtitle"));
+    fmt.blank();
+    fmt.info(t("bootstrap.instructions"));
+    fmt.blank();
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
       answers.technicalLevel = await askEnumQuestion(rl, t("bootstrap.question.technicalLevel"), defaults.technicalLevel || "medium", TECHNICAL_LEVELS) || "medium";
@@ -593,25 +643,128 @@ function parseSpecSections(specText) {
   );
 }
 
-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) {
+function buildOpenQuestions(missingFields, contradictions) {
+  const lines = [`# ${t("bootstrap.scaffold.openQuestionsTitle")}`, ""];
+  if (missingFields.length) {
+    lines.push(`## ${t("bootstrap.scaffold.missingFields")}`, "");
+    missingFields.forEach((field) => lines.push(`- ${field}`));
+    lines.push("");
+  }
+  if (contradictions.length) {
+    lines.push(`## ${t("bootstrap.scaffold.contradictions")}`, "");
+    contradictions.forEach((item) => lines.push(`- ${item}`));
+    lines.push("");
+  }
+  if (!missingFields.length && !contradictions.length) {
+    lines.push(`- ${t("bootstrap.scaffold.none")}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function buildDirectIntakeTemplate(profile) {
+  return {
+    version: 1,
+    technicalLevel: profile.technicalLevel || null,
+    projectState: profile.projectState || null,
+    documentationState: profile.documentationState || null,
+    decisionOwnership: profile.discovery?.decisionOwnership || profile.decisionOwnership || null,
+    problemStatement: profile.discovery?.problemStatement || "",
+    targetUser: profile.discovery?.targetUser || "",
+    singularDesiredOutcome: profile.discovery?.singularDesiredOutcome || "",
+    userLanguage: profile.discovery?.userLanguage || null,
+    needsPlainLanguage: Boolean(profile.discovery?.needsPlainLanguage),
+    recommendedStack: normalizeList(profile.discovery?.recommendedStack || []),
+    externalServices: normalizeList(profile.discovery?.externalServices || []),
+    sourceOfTruth: profile.discovery?.sourceOfTruth || "",
+    payload: profile.discovery?.payload || "",
+    behaviorRules: normalizeList(profile.discovery?.behaviorRules || []),
+    inputSchema: profile.discovery?.inputSchema || {},
+    outputSchema: profile.discovery?.outputSchema || {},
+    architecturalInvariants: normalizeList(profile.discovery?.architecturalInvariants || []),
+    pipeline: normalizeList(profile.discovery?.pipeline || []),
+    templates: normalizeList(profile.discovery?.templates || []),
+    versionControl: profile.discovery?.versionControl || {
+      remote: false,
+      provider: "",
+      developmentBranch: "",
+      releaseBranch: "",
+    },
+    deployment: profile.discovery?.deployment || {
+      mode: "",
+      target: "",
+      smokeCommand: "",
+    },
+  };
+}
+
+function buildSpecDossierScaffold(profile) {
+  return [
+    `# ${t("bootstrap.scaffold.specTitle")}`,
+    "",
+    `## ${t("bootstrap.scaffold.problemStatement")}`,
+    profile.discovery?.problemStatement || "",
+    "",
+    `## ${t("bootstrap.scaffold.targetUser")}`,
+    profile.discovery?.targetUser || "",
+    "",
+    `## ${t("bootstrap.scaffold.singularDesiredOutcome")}`,
+    profile.discovery?.singularDesiredOutcome || "",
+    "",
+    `## ${t("bootstrap.scaffold.deliveryTarget")}`,
+    profile.discovery?.payload || "",
+    "",
+    `## ${t("bootstrap.scaffold.sourceOfTruth")}`,
+    profile.discovery?.sourceOfTruth || "",
+    "",
+  ].join("\n");
+}
+
+function ensureDirectBootstrapArtifacts(context, profile) {
+  const files = bootstrapFilePaths(context);
+  const existingIntake = readJson(files.intakeJson);
+  const intake = existingIntake && typeof existingIntake === "object"
+    ? existingIntake
+    : buildDirectIntakeTemplate(profile);
+  if (!existingIntake) {
+    writeJson(files.intakeJson, intake);
+  }
+
+  let specText = readText(files.specDossier);
+  if (!specText.trim()) {
+    specText = buildSpecDossierScaffold({ ...profile, discovery: { ...profile.discovery, ...intake } });
+    writeText(files.specDossier, specText);
+  }
+
+  const mergedProfile = {
+    ...profile,
+    discovery: {
+      ...(profile.discovery || {}),
+      ...intake,
+      externalServices: normalizeList(intake.externalServices || profile.discovery?.externalServices || []),
+      behaviorRules: normalizeList(intake.behaviorRules || profile.discovery?.behaviorRules || []),
+      architecturalInvariants: normalizeList(intake.architecturalInvariants || profile.discovery?.architecturalInvariants || []),
+      pipeline: normalizeList(intake.pipeline || profile.discovery?.pipeline || []),
+      templates: normalizeList(intake.templates || profile.discovery?.templates || []),
+      inputSchema: intake.inputSchema || profile.discovery?.inputSchema || {},
+      outputSchema: intake.outputSchema || profile.discovery?.outputSchema || {},
+      decisionOwnership: intake.decisionOwnership || profile.discovery?.decisionOwnership || profile.decisionOwnership || null,
+      versionControl: intake.versionControl || profile.discovery?.versionControl || null,
+      deployment: intake.deployment || profile.discovery?.deployment || null,
+    },
+  };
+  const qualityReport = buildQualityReport(context, mergedProfile, specText);
+  writeText(files.openQuestions, buildOpenQuestions(qualityReport.missingFields, qualityReport.contradictions));
+  writeJson(files.qualityReport, qualityReport);
+
+  return {
+    intake,
+    specText,
+    qualityReport,
+    profile: mergedProfile,
+  };
+}
+
+function qualityStatusFor(missingFields, contradictions) {
   if (missingFields.length >= 2) return "blocked";
   if (missingFields.length || contradictions.length) return "needs_review";
   return "ready";
@@ -630,23 +783,21 @@ function contractReadinessFor(profile, qualityStatus) {
   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];
+function buildQualityReport(context, profile, specText) {
+  const sections = parseSpecSections(specText);
+  const missingFields = directMissingFields(profile.discovery);
+
+  const contradictions = [];
+  const mappings = [
+    ["problem statement", "problemStatement", profile.discovery.problemStatement, "problema principal"],
+    ["target user", "targetUser", profile.discovery.targetUser, "usuario objetivo", "usuario objetivo principal"],
+    ["singular desired outcome", "singularDesiredOutcome", profile.discovery.singularDesiredOutcome, "resultado singular deseado", "resultado deseado"],
+    ["payload", "payload", profile.discovery.payload, "delivery target", "objetivo de entrega"],
+    ["source of truth", "sourceOfTruth", profile.discovery.sourceOfTruth, "fuente de la verdad"],
+  ];
+  for (const mapping of mappings) {
+    const [sectionName, fieldName, expected, ...aliases] = mapping;
+    const actual = sections[sectionName] || aliases.reduce((found, alias) => found || sections[alias], null);
     if (!actual) {
       missingFields.push(fieldName);
       continue;
@@ -700,23 +851,25 @@ function buildOperatingContract(control, profile, qualityReport, context) {
       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",
+    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 || [],
+      deployment: discovery.deployment || null,
+      phaseModel: "opera-v3",
+      taskSeeds: buildSeedTasks(control, profile).map((task) => task.id),
+    },
+    governance: {
+      policyFile: policyRelativePath(context),
+      versionControl: discovery.versionControl || null,
+      riskProfile: "standard",
       approvalRules: [
         "destructive_changes_require_approval",
         "production_deploy_requires_approval",
@@ -795,7 +948,10 @@ function renderGenesis(control, contract) {
 }
 
 function buildSeedTasks(control, profile) {
-  const phaseOrder = config.getPhases(control);
+  let phaseOrder = config.getPhases(control);
+  if (!phaseOrder || !phaseOrder.length) {
+    phaseOrder = config.buildDefaultPhases ? config.buildDefaultPhases(config.getLocale(control)) : config.DEFAULT_PHASES;
+  }
   const firstTaskStatus =
     profile.status === "completed"
       ? "completed"
@@ -986,8 +1142,21 @@ function applyBootstrap(root, control, profile) {
   control.meta.phases = config.getPhases(control);
   control.meta.opera.legacyStatus = "supported";
 
+  const existingBootstrap = new Map(
+    (control.tasks || []).filter((task) => task.origin === "bootstrap").map((task) => [task.id, task])
+  );
   const remainingTasks = (control.tasks || []).filter((task) => task.id !== "ops-bootstrap" && task.origin !== "bootstrap");
-  control.tasks = [...remainingTasks, ...buildSeedTasks(control, profile)];
+  const newSeeds = buildSeedTasks(control, profile).map((seed) => {
+    const existing = existingBootstrap.get(seed.id);
+    if (!existing) return seed;
+    return {
+      ...seed,
+      status: existing.status === "completed" ? "completed" : seed.status,
+      history: existing.history || seed.history,
+      blocker: existing.status === "blocked" ? existing.blocker : seed.blocker,
+    };
+  });
+  control.tasks = [...remainingTasks, ...newSeeds];
 
   control.decisionsPending = (profile.missingFields || [])
     .filter((field) => !["intakeJson", "specDossier"].includes(field))
@@ -1005,37 +1174,54 @@ function applyBootstrap(root, control, profile) {
   }
 
   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;
-  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;
+  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,
+        `# ${t("bootstrap.scaffold.specTitle")}\n\n${t("bootstrap.scaffold.specPlaceholder")}\n`,
+      );
+    }
+    writeText(files.openQuestions, buildOpenQuestions(["intakeJson", "specDossier"], []));
+  }
+  let directArtifacts = null;
+  if (profile.mode === "direct_cli") {
+    directArtifacts = ensureDirectBootstrapArtifacts(context, profile);
+    profile = directArtifacts.profile;
+    control.meta.opera.bootstrap = {
+      ...control.meta.opera.bootstrap,
+      ...profile,
+      handoffFiles: null,
+    };
+  }
+  const genesisPath = context.paths.genesisFile;
+  if (profile.status === "completed") {
+    const specText = directArtifacts?.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 = directArtifacts?.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;
-  }
+  } else if (["needs_review", "blocked"].includes(profile.status)) {
+    const qualityReport = directArtifacts?.qualityReport || profile.qualityReport || null;
+    control.meta.opera.contractVersion = null;
+    control.meta.opera.contractReadiness = qualityReport?.contractReadiness || "hypothesis";
+    control.meta.opera.qualityStatus = qualityReport?.status || profile.status;
+  } else {
+    const qualityReport = directArtifacts?.qualityReport || profile.qualityReport || null;
+    control.meta.opera.contractVersion = null;
+    control.meta.opera.contractReadiness = qualityReport?.contractReadiness || "hypothesis";
+    control.meta.opera.qualityStatus = qualityReport?.status || profile.status;
+  }
 
   config.saveControl(context, control);
   return control;
@@ -1051,9 +1237,14 @@ function resumeBootstrap(root, control) {
   const files = bootstrapFilePaths(context);
   const intake = readJson(files.intakeJson);
   const specDossier = readText(files.specDossier);
-  if (!intake || !specDossier.trim()) {
+  if (!intake || typeof intake !== "object") {
     return { resumed: false, status: "awaiting_agent", reason: "missing_agent_artifacts" };
   }
+  const meaningfulKeys = ["problemStatement", "targetUser", "singularDesiredOutcome", "payload", "sourceOfTruth"];
+  const hasContent = meaningfulKeys.some((k) => intake[k] && String(intake[k]).trim());
+  if (!hasContent && !specDossier.trim()) {
+    return { resumed: false, status: "awaiting_agent", reason: "empty_intake_and_spec" };
+  }
 
   const discovery = {
     ...bootstrap.discovery,
@@ -1062,11 +1253,13 @@ function resumeBootstrap(root, control) {
     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 || {},
-  };
+    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 || {},
+    versionControl: intake.versionControl || bootstrap.discovery?.versionControl || null,
+    deployment: intake.deployment || bootstrap.discovery?.deployment || null,
+  };
   const missingFields = directMissingFields(discovery);
   const profile = {
     ...bootstrap,
@@ -1081,12 +1274,13 @@ function resumeBootstrap(root, control) {
     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 };
-}
+  const qualityReport = buildQualityReport(context, profile, specDossier);
+  profile.status = qualityReport.status === "ready" ? "completed" : qualityReport.status;
+  profile.completedAt = qualityReport.status === "ready" ? nowIso() : null;
+  profile.missingFields = qualityReport.missingFields || [];
+  profile.qualityReport = qualityReport;
+  return { resumed: true, profile };
+}
 
 function detectLegacyBootstrap(root, control) {
   const context = config.ensureContext(root);
@@ -1115,6 +1309,31 @@ function detectLegacyBootstrap(root, control) {
   return null;
 }
 
+function revalidateContract(root, control) {
+  const context = config.ensureContext(root);
+  if (!config.isOperaInstalled(control)) return { changed: false };
+  if (!fs.existsSync(context.paths.contractFile)) return { changed: false };
+  const files = bootstrapFilePaths(context);
+  const intake = readJson(files.intakeJson);
+  const specDossier = readText(files.specDossier);
+  if (!intake) return { changed: false };
+  const bootstrapState = getBootstrapState(control, context);
+  if (!bootstrapState || !bootstrapState.discovery) return { changed: false };
+  const discovery = { ...bootstrapState.discovery, ...intake };
+  const profile = { ...bootstrapState, discovery };
+  const qualityReport = buildQualityReport(context, profile, specDossier);
+  const newContract = buildOperatingContract(control, profile, qualityReport, context);
+  const existing = readJson(context.paths.contractFile);
+  const changed = JSON.stringify(existing) !== JSON.stringify(newContract);
+  if (changed) {
+    writeJson(context.paths.contractFile, newContract);
+    control.meta.opera.contractReadiness = qualityReport.contractReadiness;
+    control.meta.opera.qualityStatus = qualityReport.status === "ready" ? "completed" : qualityReport.status;
+    config.saveControl(context, control);
+  }
+  return { changed, contractReadiness: qualityReport.contractReadiness };
+}
+
 module.exports = {
   TECHNICAL_LEVELS,
   PROJECT_STATES,
@@ -1132,6 +1351,7 @@ module.exports = {
   collectBootstrapProfile,
   applyBootstrap,
   resumeBootstrap,
+  revalidateContract,
   detectLegacyBootstrap,
   getBootstrapState,
   buildQualityReport,