trackops 2.0.5 → 2.0.6

package/lib/init.js

@@ -12,15 +12,36 @@ const { t, setLocale } = require("./i18n");
 const { detectSystemLocale, promptForLocale, maybePromptForLocale, resolveLocale } = require("./locale");
 const runtimeState = require("./runtime-state");
 
-const GENERATED_SCRIPT_COMMANDS = {
+const GENERATED_SCRIPT_COMMANDS = {
   ops: "npx --yes trackops",
   "ops:help": "npx --yes trackops help",
   "ops:dashboard": "npx --yes trackops dashboard",
   "ops:status": "npx --yes trackops status",
   "ops:next": "npx --yes trackops next",
   "ops:sync": "npx --yes trackops sync",
-  "ops:repo": "npx --yes trackops refresh-repo",
-};
+  "ops:repo": "npx --yes trackops refresh-repo",
+};
+
+const ROOT_PRESERVED_ENTRIES = new Set([
+  ".git",
+  ".gitignore",
+  ".gitattributes",
+  ".gitmodules",
+  ".editorconfig",
+  ".env",
+  ".env.example",
+  ".vscode",
+  ".idea",
+  ".nvmrc",
+  ".node-version",
+  ".tool-versions",
+  ".npmrc",
+  ".yarnrc.yml",
+  ".pnp.cjs",
+  ".pnp.loader.mjs",
+  "pnpm-workspace.yaml",
+  "turbo.json",
+]);
 
 function nowIso() {
   return new Date().toISOString();
@@ -176,41 +197,117 @@ function installHooks(context) {
 
   if (fs.existsSync(path.join(context.workspaceRoot, ".git"))) {
     const hooksPath = context.layout === "split" ? "ops/.githooks" : ".githooks";
-    spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
+    const result = spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
+    if (result.status !== 0) {
+      console.log(t("cli.hooksError"));
+    }
   }
 }
 
-function ensureTmpDir(context) {
+function ensureTmpDir(context) {
   fs.mkdirSync(context.paths.tmpDir, { recursive: true });
   const gitkeep = path.join(context.paths.tmpDir, ".gitkeep");
   if (!fs.existsSync(gitkeep)) {
     fs.writeFileSync(gitkeep, "", "utf8");
-  }
-}
-
-function ensureSplitLayoutAllowed(targetRoot) {
-  const entries = fs.readdirSync(targetRoot, { withFileTypes: true });
-  const meaningful = entries.filter((entry) => ![".git"].includes(entry.name));
-  if (meaningful.length > 0) {
-    throw new Error("Directory is not empty. Run 'trackops workspace migrate' to convert an existing project.");
-  }
-}
-
-function initSplitProject(root, options) {
-  const targetRoot = path.resolve(root);
-  fs.mkdirSync(targetRoot, { recursive: true });
-  ensureSplitLayoutAllowed(targetRoot);
-
-  const manifest = workspace.buildManifest();
-  const context = config.createSplitContext(targetRoot, manifest);
-  fs.mkdirSync(context.appRoot, { recursive: true });
-  fs.mkdirSync(context.opsRoot, { recursive: true });
-  config.saveWorkspaceManifest(context, manifest);
-  workspace.ensureRootGitignore(targetRoot);
-
-  const control = buildDefaultControl(context, options);
-  control.meta.projectName = options.name || detectProjectName(context.workspaceRoot);
-  config.saveControl(context, control);
+  }
+}
+
+function isRetryableMoveError(error) {
+  return ["EPERM", "EXDEV", "EBUSY", "ENOTEMPTY"].includes(error?.code);
+}
+
+function moveEntry(fromPath, toPath) {
+  if (!fs.existsSync(fromPath)) return;
+  fs.mkdirSync(path.dirname(toPath), { recursive: true });
+  try {
+    fs.renameSync(fromPath, toPath);
+  } catch (error) {
+    if (!isRetryableMoveError(error)) throw error;
+    const stat = fs.statSync(fromPath);
+    if (stat.isDirectory()) {
+      fs.cpSync(fromPath, toPath, { recursive: true, force: true });
+      fs.rmSync(fromPath, { recursive: true, force: true });
+      return;
+    }
+    fs.copyFileSync(fromPath, toPath);
+    fs.rmSync(fromPath, { force: true });
+  }
+}
+
+function collectRootEntries(targetRoot) {
+  return fs.readdirSync(targetRoot, { withFileTypes: true })
+    .filter((entry) => ![".", ".."].includes(entry.name));
+}
+
+function analyzeSplitInit(targetRoot) {
+  const entries = collectRootEntries(targetRoot);
+  const manifestPath = path.join(targetRoot, config.WORKSPACE_MANIFEST);
+  const legacyControlPath = path.join(targetRoot, "project_control.json");
+  const hasManifest = fs.existsSync(manifestPath);
+
+  if (hasManifest) {
+    return { mode: "upgrade", entries };
+  }
+
+  if (fs.existsSync(legacyControlPath)) {
+    throw new Error(t("init.error.legacyDetected"));
+  }
+
+  const conflicts = entries
+    .map((entry) => entry.name)
+    .filter((name) => [config.DEFAULT_APP_DIR, config.DEFAULT_OPS_DIR, config.WORKSPACE_MANIFEST].includes(name));
+
+  if (conflicts.length) {
+    throw new Error(t("init.error.reservedConflict", { entries: conflicts.join(", ") }));
+  }
+
+  const movableEntries = entries.filter((entry) => !ROOT_PRESERVED_ENTRIES.has(entry.name));
+  return {
+    mode: movableEntries.length ? "adopt" : "new",
+    entries,
+    movableEntries,
+  };
+}
+
+function adoptExistingProject(targetRoot, appRoot, movableEntries) {
+  for (const entry of movableEntries) {
+    moveEntry(path.join(targetRoot, entry.name), path.join(appRoot, entry.name));
+  }
+}
+
+function initSplitProject(root, options) {
+  const targetRoot = path.resolve(root);
+  fs.mkdirSync(targetRoot, { recursive: true });
+  const projectName = options.name || detectProjectName(targetRoot);
+  const initMode = analyzeSplitInit(targetRoot);
+  const manifest = workspace.buildManifest();
+  const context = config.createSplitContext(targetRoot, manifest);
+
+  if (initMode.mode === "adopt") {
+    fs.mkdirSync(context.appRoot, { recursive: true });
+    adoptExistingProject(targetRoot, context.appRoot, initMode.movableEntries);
+  }
+
+  fs.mkdirSync(context.appRoot, { recursive: true });
+  fs.mkdirSync(context.opsRoot, { recursive: true });
+  config.saveWorkspaceManifest(context, manifest);
+  workspace.ensureRootGitignore(targetRoot);
+
+  const controlFile = context.controlFile || path.join(context.opsRoot, "project_control.json");
+  const isUpgrade = initMode.mode === "upgrade" && fs.existsSync(controlFile);
+  let control;
+  if (isUpgrade) {
+    control = JSON.parse(fs.readFileSync(controlFile, "utf8"));
+    if (!control.meta.phases) control.meta.phases = options.phases || config.buildDefaultPhases(options.locale);
+    if (!control.meta.locale) control.meta.locale = options.locale || config.DEFAULT_LOCALE;
+    if (!control.meta.controlVersion || control.meta.controlVersion < 2) control.meta.controlVersion = 2;
+    control.meta.updatedAt = nowIso();
+    config.saveControl(context, control);
+  } else {
+    control = buildDefaultControl(context, options);
+    control.meta.projectName = projectName;
+    config.saveControl(context, control);
+  }
 
   installHooks(context);
   ensureTmpDir(context);
@@ -224,16 +321,27 @@ function initSplitProject(root, options) {
     // ignore
   }
 
-  console.log(t("init.created", { file: ".trackops-workspace.json" }));
-  console.log(t("init.created", { file: "ops/project_control.json" }));
-  console.log(t("init.created", { file: "ops/.githooks/" }));
-  console.log(t("init.created", { file: ".env" }));
-  console.log(t("init.created", { file: ".env.example" }));
-  console.log("");
-  console.log(t("init.welcome"));
-
-  return { root: context.workspaceRoot, context, isUpgrade: false, operaDetected: false };
-}
+  if (isUpgrade) {
+    console.log(t("init.updated", { file: ".trackops-workspace.json" }));
+    console.log(t("init.updated", { file: "ops/project_control.json" }));
+    console.log(t("init.updated", { file: "ops/.githooks/" }));
+    console.log(t("init.updated", { file: ".env" }));
+    console.log(t("init.updated", { file: ".env.example" }));
+  } else {
+    console.log(t("init.created", { file: ".trackops-workspace.json" }));
+    console.log(t("init.created", { file: "ops/project_control.json" }));
+    console.log(t("init.created", { file: "ops/.githooks/" }));
+    console.log(t("init.created", { file: ".env" }));
+    console.log(t("init.created", { file: ".env.example" }));
+    if (initMode.mode === "adopt") {
+      console.log(t("init.adoptedExistingRepo", { dir: path.basename(context.appRoot) }));
+    }
+  }
+  console.log("");
+  console.log(t("init.welcome"));
+
+  return { root: context.workspaceRoot, context, isUpgrade, operaDetected: false };
+}
 
 function initLegacyProject(root, options) {
   const targetRoot = path.resolve(root);

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,33 @@ 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",
+      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}`);
   }
@@ -493,10 +519,12 @@ async function collectBootstrapProfile(root, control, options = {}) {
   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 +621,115 @@ 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 || []),
+  };
+}
+
+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,
+    },
+  };
+  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 +748,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;
@@ -795,7 +911,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 +1105,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 +1137,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 +1200,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,
@@ -1115,6 +1269,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 +1311,7 @@ module.exports = {
   collectBootstrapProfile,
   applyBootstrap,
   resumeBootstrap,
+  revalidateContract,
   detectLegacyBootstrap,
   getBootstrapState,
   buildQualityReport,