specatlas 0.1.25 → 0.1.27

package/dist/bin.js

@@ -6,13 +6,14 @@ import {
   localCompact,
   localDate,
   localMonth,
+  localOffset,
   localStamp,
   parseApprovals,
   parseChangeMeta,
   sha256,
   shortHash,
   signApproval
-} from "./chunk-HYN75DTZ.js";
+} from "./chunk-L2BWIT44.js";
 import {
   __commonJS,
   __toESM,
@@ -1585,7 +1586,7 @@ var require_core = __commonJS({
 });
 
 // src/cli.ts
-import path41 from "path";
+import path45 from "path";
 
 // ../core/dist/index.js
 import path from "path";
@@ -9025,8 +9026,12 @@ import path15 from "path";
 import { promises as fs } from "fs";
 import { cp, rename, rm } from "fs/promises";
 import path16 from "path";
+import { promises as fs2 } from "fs";
 import path17 from "path";
+import { parse as parseYaml8, stringify as stringifyYaml5 } from "yaml";
 import path18 from "path";
+import path19 from "path";
+import path20 from "path";
 var CORE_VERSION = "0.0.1";
 var REQ_ID_RE = /^REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}$/;
 var SCENARIO_ID_RE = /^REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}-S\d+$/;
@@ -9742,14 +9747,14 @@ function wordBoundary(text, term) {
   const re = new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, "iu");
   return re.test(text);
 }
-function lintText(text, code, terms, label, path192, line) {
+function lintText(text, code, terms, label, path212, line) {
   const out = [];
   const lower = text.toLowerCase();
   for (const term of terms) {
     if (wordBoundary(lower, term)) {
       out.push(
         diag(code, "error", `${label}: "${term}"`, {
-          path: path192,
+          path: path212,
           line,
           suggestion: "La especificaci\xF3n es funcional y de negocio: describe comportamiento, no tecnolog\xEDa ni adjetivos vagos"
         })
@@ -9758,7 +9763,7 @@ function lintText(text, code, terms, label, path192, line) {
   }
   return out;
 }
-function lintRequirement(req, path192, opts = {}) {
+function lintRequirement(req, path212, opts = {}) {
   const out = [];
   const vague = opts.language === "en" ? VAGUE_EN : VAGUE_ES;
   const tech = opts.language === "en" ? TECH_EN : TECH_ES;
@@ -9769,32 +9774,32 @@ function lintRequirement(req, path192, opts = {}) {
     ...req.scenarios.flatMap((s) => [...s.when.map((w) => ({ text: w, line: s.line })), ...s.then.map((t) => ({ text: t, line: s.line }))])
   ];
   for (const part of parts) {
-    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path192, part.line));
+    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path212, part.line));
     if (opts.businessOnly !== false) {
-      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path192, part.line));
+      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path212, part.line));
     }
   }
   if (req.scenarios.length === 0) {
-    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path192, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
+    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path212, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
   }
   return out;
 }
-function lintDelta(delta, livingRequirements, path192, opts = {}) {
+function lintDelta(delta, livingRequirements, path212, opts = {}) {
   const out = [...delta.diagnostics];
   for (const req of [...delta.added, ...delta.modified]) {
-    out.push(...lintRequirement(req, path192, opts));
+    out.push(...lintRequirement(req, path212, opts));
   }
   for (const req of delta.modified) {
     const living = livingRequirements.get(req.id);
     if (!living) {
-      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path192, line: req.line }));
+      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path212, line: req.line }));
       continue;
     }
     for (const existing of living.scenarios) {
       if (!req.scenarios.some((s) => s.id === existing.id)) {
         out.push(
           diag("TRACE-007", "error", `MODIFIED ${req.id} pierde el escenario ${existing.id}: copia el bloque completo`, {
-            path: path192,
+            path: path212,
             line: req.line,
             suggestion: "Copia el bloque completo de la spec viva y ed\xEDtalo; para quitarlo, decl\xE1ralo en REMOVED"
           })
@@ -9805,15 +9810,15 @@ function lintDelta(delta, livingRequirements, path192, opts = {}) {
   for (const req of delta.removed) {
     const living = livingRequirements.get(req.id);
     if (!living) {
-      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path192, line: req.line }));
+      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path212, line: req.line }));
     }
   }
   for (const rename2 of delta.renamed) {
     if (rename2.from.id !== rename2.to.id) {
-      out.push(diag("LINT-DLT-003", "error", `RENAMED cambia el id (${rename2.from.id} \u2192 ${rename2.to.id}); los ids son inmutables`, { path: path192, line: rename2.line }));
+      out.push(diag("LINT-DLT-003", "error", `RENAMED cambia el id (${rename2.from.id} \u2192 ${rename2.to.id}); los ids son inmutables`, { path: path212, line: rename2.line }));
     }
     if (!livingRequirements.has(rename2.from.id)) {
-      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path192, line: rename2.line }));
+      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path212, line: rename2.line }));
     }
   }
   return out;
@@ -9837,7 +9842,7 @@ var MERMAID_KEYWORDS = [
   "architecture-beta"
 ];
 var MERMAID_BLOCKS = /^\s*(alt|loop|opt|par|rect|critical|break|subgraph)\b/;
-function lintPlan(planText, path192) {
+function lintPlan(planText, path212) {
   const out = [];
   const blocks = [...planText.matchAll(/```mermaid\r?\n([\s\S]*?)```/g)];
   for (const [index, block] of blocks.entries()) {
@@ -9847,7 +9852,7 @@ function lintPlan(planText, path192) {
     if (!MERMAID_KEYWORDS.some((keyword) => first.startsWith(keyword))) {
       out.push(
         diag("LINT-PLN-002", "error", `Diagrama mermaid ${index + 1}: la primera l\xEDnea debe declarar el tipo (${MERMAID_KEYWORDS.slice(0, 5).join(", ")}\u2026) y empieza por "${first.slice(0, 30)}"`, {
-          path: path192,
+          path: path212,
           suggestion: "Corrige el tipo del diagrama o elimina el bloque"
         })
       );
@@ -9861,7 +9866,7 @@ function lintPlan(planText, path192) {
     if (open !== 0) {
       out.push(
         diag("LINT-PLN-002", "error", `Diagrama mermaid ${index + 1}: faltan ${Math.abs(open)} \`end\` (bloques alt/loop/subgraph sin cerrar)`, {
-          path: path192,
+          path: path212,
           suggestion: "Cierra cada bloque alt/loop/opt/par/rect/subgraph con `end`"
         })
       );
@@ -9873,7 +9878,7 @@ function lintPlan(planText, path192) {
         if (message.includes(";")) {
           out.push(
             diag("LINT-PLN-003", "error", `Diagrama mermaid ${index + 1}: el mensaje "${message.trim().slice(0, 40)}\u2026" usa \`;\` y mermaid lo interpreta como fin de sentencia`, {
-              path: path192,
+              path: path212,
               suggestion: "Sustituye `;` por `\xB7` o `,` en los mensajes de sequenceDiagram"
             })
           );
@@ -11105,7 +11110,7 @@ async function approveFromGithub(opts) {
   if (!by) {
     return { approved: false, label, issueNumber: number, diagnostics: [diag("ATLAS-GH-011", "error", "No se pudo determinar qui\xE9n aprueba (--by ni `gh api user`)")] };
   }
-  const { signApproval: signApproval2 } = await import("./approvals-2PO6223I-54L7NGZ5.js");
+  const { signApproval: signApproval2 } = await import("./approvals-2PO6223I-DENKLEXU.js");
   const signed = await signApproval2({
     root: opts.root,
     artifact: path5.posix.join("changes", opts.slug, "spec.md"),
@@ -12988,6 +12993,351 @@ async function regenerateIndex(root, cfg, now = /* @__PURE__ */ new Date()) {
   void now;
   await writeText(path16.join(root, ".sdd", "INDEX.md"), markdown2);
 }
+var SCHEMA_VERSION = 1;
+var BACKUP_DIRNAME = ".backup";
+var BACKUP_POINTER = ".latest";
+var SCHEMA_MIGRATIONS = [
+  {
+    id: "0001-sellar-version-de-esquema",
+    description: "Sella la versi\xF3n de esquema vigente en los elementos que no la declaran",
+    from: 0,
+    to: SCHEMA_VERSION
+  }
+];
+var FIXED_ARTIFACTS = ["config.yaml", "approvals.yaml", path17.join("profiles", "detected.yaml")];
+var CHANGE_ARTIFACTS = ["meta.yaml", path17.join("mockups", "manifest.yaml")];
+async function pushChangeArtifacts(out, sddDir, relDir) {
+  for (const rel of CHANGE_ARTIFACTS) {
+    const abs = path17.join(sddDir, relDir, rel);
+    if (await exists(abs)) out.push({ artifact: toPosix(path17.join(relDir, rel)), path: abs });
+  }
+}
+async function collectVersionedArtifacts(root) {
+  const sddDir = path17.join(root, ".sdd");
+  const out = [];
+  for (const rel of FIXED_ARTIFACTS) {
+    const abs = path17.join(sddDir, rel);
+    if (await exists(abs)) out.push({ artifact: toPosix(rel), path: abs });
+  }
+  const changesDir = path17.join(sddDir, "changes");
+  for (const slug of await listDirs(changesDir)) {
+    if (slug === "archive") continue;
+    await pushChangeArtifacts(out, sddDir, path17.join("changes", slug));
+  }
+  for (const entry of await listDirs(path17.join(changesDir, "archive"))) {
+    await pushChangeArtifacts(out, sddDir, path17.join("changes", "archive", entry));
+  }
+  return out;
+}
+function readArtifactVersion(content) {
+  let data;
+  try {
+    data = parseYaml8(content);
+  } catch (err) {
+    return { state: "unreadable", reason: `YAML inv\xE1lido (${err.message})` };
+  }
+  if (data === null || data === void 0) return { state: "absent" };
+  if (typeof data !== "object" || Array.isArray(data)) return { state: "unreadable", reason: "la ra\xEDz no es un mapa de claves y valores" };
+  const raw = data["schema_version"];
+  if (raw === void 0) return { state: "absent" };
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1) return { state: "unreadable", reason: `schema_version con valor no v\xE1lido: ${String(raw)}` };
+  return { state: "ok", version: raw };
+}
+function stampSchemaVersion(content, version) {
+  const line = `schema_version: ${version}`;
+  const bom = content.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const body = bom ? content.slice(1) : content;
+  if (body.trim() === "") return `${bom}${line}
+`;
+  const eol = body.includes("\r\n") ? "\r\n" : "\n";
+  const lines = body.split(/\r?\n/);
+  const trailing = lines.length > 1 && lines[lines.length - 1] === "";
+  let index = 0;
+  while (index < lines.length) {
+    const trimmed = (lines[index] ?? "").trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      index += 1;
+      continue;
+    }
+    break;
+  }
+  if ((lines[index] ?? "").trim() === "---") index += 1;
+  const insertAt = trailing ? Math.min(index, lines.length - 1) : index;
+  lines.splice(insertAt, 0, line);
+  const next = bom + lines.join(eol);
+  const check = readArtifactVersion(next);
+  if (check.state !== "ok" || check.version !== version) return void 0;
+  return next;
+}
+async function planUpgrade(root) {
+  const artifacts = await collectVersionedArtifacts(root);
+  const pending = [];
+  const newer = [];
+  const unreadable = [];
+  for (const found of artifacts) {
+    const content = await readTextIfExists(found.path);
+    if (content === void 0) continue;
+    const state = readArtifactVersion(content);
+    if (state.state === "unreadable") {
+      unreadable.push({ ...found, reason: state.reason });
+      continue;
+    }
+    if (state.state === "ok") {
+      if (state.version > SCHEMA_VERSION) {
+        newer.push({ ...found, reason: `produce la versi\xF3n ${state.version}, m\xE1s nueva que la vigente (${SCHEMA_VERSION})` });
+        continue;
+      }
+      if (state.version === SCHEMA_VERSION) continue;
+    }
+    const from = state.state === "ok" ? state.version : 0;
+    const migration = SCHEMA_MIGRATIONS.find((m) => m.from === from);
+    if (!migration) {
+      unreadable.push({ ...found, reason: `no hay migraci\xF3n registrada desde la versi\xF3n ${from}` });
+      continue;
+    }
+    const stamped = stampSchemaVersion(content, migration.to);
+    if (stamped === void 0) {
+      unreadable.push({ ...found, reason: "no se pudo sellar con seguridad sin alterar el resto del contenido" });
+      continue;
+    }
+    pending.push({ ...found, from, to: migration.to, migration: migration.id, summary: migration.description });
+  }
+  return { root, currentVersion: SCHEMA_VERSION, pending, newer, unreadable, upToDate: pending.length === 0 };
+}
+async function removeDir(dir) {
+  try {
+    await fs2.rm(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+async function removeFile(file) {
+  try {
+    await fs2.rm(file, { force: true });
+  } catch {
+  }
+}
+function backupName(now) {
+  return `${localCompact(now)}${localOffset(now).replace(":", "")}`;
+}
+async function applyUpgrade(root, now = /* @__PURE__ */ new Date()) {
+  const plan = await planUpgrade(root);
+  if (plan.pending.length === 0) return { status: "up-to-date", plan, applied: [] };
+  const sddDir = path17.join(root, ".sdd");
+  const backupRoot = path17.join(sddDir, BACKUP_DIRNAME);
+  const name = backupName(now);
+  const backupDir = path17.join(backupRoot, name);
+  const pointerFile = path17.join(backupRoot, BACKUP_POINTER);
+  const previous = [];
+  try {
+    for (const item of plan.pending) {
+      const content = await readTextIfExists(item.path);
+      if (content === void 0) throw new Error("el elemento desapareci\xF3 mientras se respaldaba");
+      previous.push({ item, contents: content });
+      await writeText(path17.join(backupDir, "files", ...item.artifact.split("/")), content);
+    }
+    await writeText(
+      path17.join(backupDir, "backup.yaml"),
+      stringifyYaml5(
+        {
+          schema_version: SCHEMA_VERSION,
+          created_at: localStamp(now),
+          to_version: SCHEMA_VERSION,
+          files: plan.pending.map((i) => ({ artifact: i.artifact, from: i.from, to: i.to, migration: i.migration }))
+        },
+        { lineWidth: 120 }
+      )
+    );
+    await writeText(pointerFile, `${name}
+`);
+  } catch (err) {
+    await removeDir(backupDir);
+    await removeFile(pointerFile);
+    return { status: "failed", plan, applied: [], failure: { artifact: "(respaldo)", message: err.message } };
+  }
+  const written = [];
+  for (const { item, contents } of previous) {
+    try {
+      const next = stampSchemaVersion(contents, item.to);
+      if (next === void 0) throw new Error("no se pudo sellar con seguridad");
+      await writeText(item.path, next);
+      written.push(item);
+    } catch (err) {
+      for (const w of written) {
+        const prev = previous.find((p) => p.item.artifact === w.artifact);
+        if (prev) {
+          try {
+            await writeText(prev.item.path, prev.contents);
+          } catch {
+          }
+        }
+      }
+      await removeFile(pointerFile);
+      await removeDir(backupDir);
+      return { status: "failed", plan, applied: [], failure: { artifact: item.artifact, message: err.message } };
+    }
+  }
+  for (const dir of await listDirs(backupRoot)) {
+    if (dir !== name) await removeDir(path17.join(backupRoot, dir));
+  }
+  return {
+    status: "applied",
+    plan,
+    applied: written,
+    backup: {
+      name,
+      dir: backupDir,
+      relativeDir: toPosix(path17.relative(root, backupDir)),
+      createdAt: localStamp(now),
+      files: plan.pending.map((i) => i.artifact)
+    }
+  };
+}
+async function rollbackUpgrade(root) {
+  const sddDir = path17.join(root, ".sdd");
+  const backupRoot = path17.join(sddDir, BACKUP_DIRNAME);
+  const pointerFile = path17.join(backupRoot, BACKUP_POINTER);
+  const name = (await readTextIfExists(pointerFile))?.trim();
+  if (!name) return { status: "no-backup", restored: [] };
+  const backupDir = path17.join(backupRoot, name);
+  const manifestRaw = await readTextIfExists(path17.join(backupDir, "backup.yaml"));
+  if (manifestRaw === void 0) return { status: "no-backup", restored: [] };
+  let files = [];
+  try {
+    const parsed = parseYaml8(manifestRaw);
+    files = (parsed?.files ?? []).filter((f) => typeof f?.artifact === "string");
+  } catch {
+    return { status: "no-backup", restored: [] };
+  }
+  const restored = [];
+  for (const file of files) {
+    const from = path17.join(backupDir, "files", ...file.artifact.split("/"));
+    const to = path17.join(sddDir, ...file.artifact.split("/"));
+    const content = await readTextIfExists(from);
+    if (content === void 0) continue;
+    try {
+      await writeText(to, content);
+      restored.push(file.artifact);
+    } catch (err) {
+      return { status: "failed", restored, backup: name, failure: { artifact: file.artifact, message: err.message } };
+    }
+  }
+  await removeDir(backupDir);
+  await removeFile(pointerFile);
+  return { status: "restored", restored, backup: name };
+}
+async function upgradeAdvisory(root) {
+  const plan = await planUpgrade(root);
+  const diagnostics = [];
+  if (plan.pending.length > 0) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-001", "warning", `El estado del proyecto no corresponde a la versi\xF3n vigente: ${plan.pending.length} elemento(s) por actualizar`, {
+        suggestion: "Vista previa: `satlas upgrade` \xB7 Aplicar: `satlas upgrade --apply`"
+      })
+    );
+  }
+  for (const item of plan.newer) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-002", "warning", `El proyecto fue producido por una versi\xF3n m\xE1s nueva: "${item.artifact}" (${item.reason})`, {
+        path: item.path,
+        suggestion: "Actualiza la herramienta; no se actualiza hacia atr\xE1s"
+      })
+    );
+  }
+  for (const item of plan.unreadable) {
+    diagnostics.push(
+      diag("ATLAS-UPGRADE-003", "warning", `No se pudo interpretar "${item.artifact}": ${item.reason}`, {
+        path: item.path,
+        suggestion: "Revisa el elemento; no se modificar\xE1"
+      })
+    );
+  }
+  return { plan, diagnostics };
+}
+var SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+var SARIF_VERSION = "2.1.0";
+var TOOL_NAME = "SpecAtlas";
+var TOOL_URL = "https://github.com/AlonsoAM/specatlas";
+var RULE_FAMILIES = [
+  [/^LINT-STR-/, "Estructura de los artefactos"],
+  [/^LINT-BIZ-/, "Lenguaje de negocio de la especificaci\xF3n"],
+  [/^LINT-DLT-/, "Delta de especificaci\xF3n"],
+  [/^LINT-EVD-/, "Evidencia registrada"],
+  [/^LINT-TSK-/, "Tareas declaradas"],
+  [/^LINT-PLN-/, "Plan t\xE9cnico"],
+  [/^(LINT-MKP|MKP)-/, "Mockups"],
+  [/^TRACE-/, "Trazabilidad requisito, escenario, tarea y evidencia"],
+  [/^PACK-/, "Pack de cumplimiento"],
+  [/^ATLAS-UPGRADE-/, "Actualizaci\xF3n del estado del proyecto"],
+  [/^ATLAS-ADAPTERS-/, "Adaptadores de agente"],
+  [/^ATLAS-CI-/, "Comprobaci\xF3n continua"],
+  [/^ATLAS-/, "Estado del proyecto"]
+];
+function ruleDescription(code) {
+  for (const [pattern, description] of RULE_FAMILIES) {
+    if (pattern.test(code)) return description;
+  }
+  return code;
+}
+function sarifLevel(severity) {
+  if (severity === "error") return "error";
+  if (severity === "warning") return "warning";
+  return "note";
+}
+function resultOf(diagnostic, root) {
+  const result = {
+    ruleId: diagnostic.code,
+    level: sarifLevel(diagnostic.severity),
+    message: { text: diagnostic.message }
+  };
+  if (diagnostic.path) {
+    const rel = path18.relative(root, diagnostic.path);
+    if (rel !== "") {
+      const physicalLocation = {
+        artifactLocation: { uri: toPosix(rel) },
+        ...diagnostic.line ? { region: { startLine: diagnostic.line } } : {}
+      };
+      result.locations = [{ physicalLocation }];
+    }
+  }
+  return result;
+}
+function toSarifReport(opts) {
+  const rules = /* @__PURE__ */ new Map();
+  const results = [];
+  for (const diagnostic of opts.diagnostics) {
+    let rule = rules.get(diagnostic.code);
+    if (!rule) {
+      rule = { id: diagnostic.code, shortDescription: { text: ruleDescription(diagnostic.code) } };
+      if (diagnostic.suggestion) rule.help = { text: diagnostic.suggestion };
+      rules.set(diagnostic.code, rule);
+    } else if (!rule.help && diagnostic.suggestion) {
+      rule.help = { text: diagnostic.suggestion };
+    }
+    results.push(resultOf(diagnostic, opts.root));
+  }
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: TOOL_NAME,
+            informationUri: TOOL_URL,
+            version: opts.version,
+            rules: [...rules.values()]
+          }
+        },
+        results,
+        invocations: [{ executionSuccessful: !(opts.failed ?? false) }]
+      }
+    ]
+  };
+}
+function toSarifText(opts) {
+  return `${JSON.stringify(toSarifReport(opts), null, 2)}
+`;
+}
 async function runDoctor(root) {
   const findings = [];
   const { workspace, config } = await loadWorkspace(root);
@@ -12995,7 +13345,7 @@ async function runDoctor(root) {
   const approvals = await loadApprovals(workspace.sddDir);
   findings.push(...approvals.diagnostics);
   for (const change of workspace.changes) {
-    const deltaPath = path17.join(change.dir, "spec.md");
+    const deltaPath = path19.join(change.dir, "spec.md");
     const deltaContent = await readTextIfExists(deltaPath);
     const approval = verifyApproval(change, approvals.byArtifact, config, deltaContent ?? void 0);
     if ((change.planPath || change.tasks) && (approval.status === "missing" || approval.status === "stale")) {
@@ -13017,7 +13367,7 @@ async function runDoctor(root) {
     }
     for (const override of change.meta?.overrides ?? []) {
       if (!override.reason.trim() || !override.by.trim()) {
-        findings.push(diag("ATLAS-LIFECYCLE-004", "error", `Override del gate "${override.gate}" sin motivo o autor`, { path: path17.join(change.dir, "meta.yaml") }));
+        findings.push(diag("ATLAS-LIFECYCLE-004", "error", `Override del gate "${override.gate}" sin motivo o autor`, { path: path19.join(change.dir, "meta.yaml") }));
       }
     }
   }
@@ -13049,7 +13399,7 @@ function livingRequirementsMap(specs) {
   return map;
 }
 async function runCiGate(opts) {
-  const root = path18.resolve(opts.root);
+  const root = path20.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const diagnostics = [];
   const checks = [];
@@ -13060,7 +13410,7 @@ async function runCiGate(opts) {
   let changesErrors = 0;
   let changesWarnings = 0;
   for (const change of workspace.changes) {
-    const lintFindings = change.delta ? lintDelta(change.delta, living, path18.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
+    const lintFindings = change.delta ? lintDelta(change.delta, living, path20.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
     const trace = checkTrace({
       specs: workspace.specs,
       change,
@@ -13169,6 +13519,7 @@ var CATALOG = [
   { name: "trace", description: "Verifica la trazabilidad requisito \u2192 escenario \u2192 tarea \u2192 evidencia", flags: ["change", "require-evidence", "json"], usage: "satlas trace [--change <slug>] [--require-evidence] [--json]" },
   { name: "waves", description: "Calcula las olas paralelas de construcci\xF3n", flags: ["change", "max-parallel", "json"], usage: "satlas waves [--change <slug>] [--max-parallel N] [--json]" },
   { name: "doctor", description: "Diagn\xF3stico de salud del workspace", flags: ["json"], usage: "satlas doctor [--json]" },
+  { name: "upgrade", description: "Actualiza el estado del proyecto a la versi\xF3n vigente (vista previa por defecto)", flags: ["apply", "rollback", "json"], usage: "satlas upgrade [--apply | --rollback] [--json]" },
   { name: "approve", description: "Firma la aprobaci\xF3n de un artefacto (spec): local o desde la etiqueta de un issue de GitHub", flags: ["by", "channel", "note", "dry-run", "from-github", "label", "json"], usage: 'satlas approve <slug|ruta> --by "<nombre>" | satlas approve <slug> --from-github' },
   { name: "issue", description: "Sincroniza el cambio con un issue de GitHub (tracker, no gate)", flags: ["labels", "json"], usage: "satlas issue sync <slug> [--labels a,b] | satlas issue status <slug>" },
   { name: "adapters", description: "Compila (o verifica) los prompts a artefactos de agente", flags: ["targets", "check", "json"], usage: "satlas adapters [--targets opencode,claude-code,cursor,copilot,gemini,codex,generic] [--check]" },
@@ -13179,7 +13530,7 @@ var CATALOG = [
   { name: "analyze", description: "Chequeo cruzado (lint + trace + waves + mockups) y escribe analyze.md", flags: ["json"], usage: "satlas analyze <slug>" },
   { name: "mockup", description: "Planifica, valida o captura los mockups del cambio", flags: ["plan", "check", "capture", "require", "json"], usage: "satlas mockup <slug> [--plan|--check|--capture|--require]" },
   { name: "present", description: "Genera el paquete de propuesta para el stakeholder (HTML autocontenido)", flags: ["json"], usage: "satlas present <slug>" },
-  { name: "ci", description: "Gate de pipeline: specs + cambios + doctor + adaptadores (sin agente)", flags: ["strict", "json"], usage: "satlas ci [--strict]" },
+  { name: "ci", description: "Gate de pipeline: specs + cambios + doctor + adaptadores (sin agente)", flags: ["strict", "sarif", "json"], usage: "satlas ci [--strict] [--sarif <ruta>]" },
   { name: "mcp", description: "V\xEDa de consulta de solo lectura para asistentes (protocolo MCP sobre entrada/salida est\xE1ndar)", flags: [], usage: "satlas mcp" },
   { name: "metrics", description: "M\xE9tricas locales del workspace (progreso, WIP, throughput, evidencia)", flags: ["json"], usage: "satlas metrics [--json]" },
   { name: "run", description: "Persiste runs y eventos de ejecuci\xF3n (auditor\xEDa y reanudaci\xF3n)", flags: ["phase", "inputs", "data", "slug", "status", "json"], usage: "satlas run start|event|status|show|list" },
@@ -13216,6 +13567,8 @@ var ES2 = {
   "init.done": "Workspace SDD creado.",
   "new.title": "Nuevo cambio",
   "new.done": "Cambio creado. Siguiente: escribe la spec funcional.",
+  "upgrade.title": "Actualizar el estado del proyecto",
+  "upgrade.preview": "Vista previa",
   "summary.findings": "hallazgos",
   "label.errors": "errores",
   "label.warnings": "avisos",
@@ -13248,6 +13601,8 @@ var EN2 = {
   "init.done": "SDD workspace created.",
   "new.title": "New change",
   "new.done": "Change created. Next: write the business spec.",
+  "upgrade.title": "Upgrade project state",
+  "upgrade.preview": "Preview",
   "summary.findings": "findings",
   "label.errors": "errors",
   "label.warnings": "warnings",
@@ -13275,26 +13630,26 @@ function cliVersion() {
 }
 
 // src/commands/adapters.ts
-import path21 from "path";
+import path24 from "path";
 
 // ../adapters/dist/index.js
-import path19 from "path";
-import { stringify as stringifyYaml5 } from "yaml";
+import path21 from "path";
+import { stringify as stringifyYaml6 } from "yaml";
 import path22 from "path";
 async function loadWorkflow(workflowDir) {
-  const phasesDir = path19.join(workflowDir, "phases");
-  const snippetsDir = path19.join(workflowDir, "snippets");
+  const phasesDir = path21.join(workflowDir, "phases");
+  const snippetsDir = path21.join(workflowDir, "snippets");
   const phases = [];
   const snippets = /* @__PURE__ */ new Map();
   const hashParts = [];
   for (const entry of (await listDir(phasesDir)).sort()) {
     if (!entry.endsWith(".md")) continue;
-    const filePath = path19.join(phasesDir, entry);
+    const filePath = path21.join(phasesDir, entry);
     const raw = await readText(filePath);
     hashParts.push(raw);
     const fm = parseFrontmatter(raw, filePath);
     const data = fm.data;
-    const id = typeof data["id"] === "string" ? data["id"] : path19.basename(entry, ".md");
+    const id = typeof data["id"] === "string" ? data["id"] : path21.basename(entry, ".md");
     phases.push({
       id,
       title: typeof data["title"] === "string" ? data["title"] : id,
@@ -13308,9 +13663,9 @@ async function loadWorkflow(workflowDir) {
   }
   for (const entry of (await listDir(snippetsDir)).sort()) {
     if (!entry.endsWith(".md")) continue;
-    const raw = await readTextIfExists(path19.join(snippetsDir, entry)) ?? "";
+    const raw = await readTextIfExists(path21.join(snippetsDir, entry)) ?? "";
     hashParts.push(raw);
-    snippets.set(path19.basename(entry, ".md"), raw.trim());
+    snippets.set(path21.basename(entry, ".md"), raw.trim());
   }
   return { phases: phases.sort((a, b) => a.id.localeCompare(b.id)), snippets, sourceHash: sha256(hashParts.join("\n---\n")) };
 }
@@ -13334,7 +13689,7 @@ function vars(language, slugToken, commandPrefix) {
   return { SLUG: slugToken, LANGUAGE: language, LANGUAGE_NAME: LANGUAGE_NAMES[language], SDD_DIR: ".sdd", COMMAND_PREFIX: commandPrefix };
 }
 function frontmatter(data, body) {
-  const yaml2 = stringifyYaml5(data, { lineWidth: 0 }).trimEnd();
+  const yaml2 = stringifyYaml6(data, { lineWidth: 0 }).trimEnd();
   return `---
 ${yaml2}
 ---
@@ -13614,7 +13969,7 @@ async function checkAdapters(opts) {
 }
 
 // src/paths.ts
-import path20 from "path";
+import path23 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function resolveProfilesDir() {
   const env = process.env["SPECATLAS_PROFILES_DIR"];
@@ -13624,16 +13979,16 @@ async function resolveProfilesDir() {
 async function resolveWorkflowDir() {
   const env = process.env["SPECATLAS_WORKFLOW_DIR"];
   if (env && await exists(env)) return env;
-  return walkUpFor(path20.join("workflow", "phases"));
+  return walkUpFor(path23.join("workflow", "phases"));
 }
 async function walkUpFor(relative) {
-  let dir = path20.dirname(fileURLToPath2(import.meta.url));
+  let dir = path23.dirname(fileURLToPath2(import.meta.url));
   for (let i = 0; i < 8; i += 1) {
-    const candidate = path20.join(dir, relative);
+    const candidate = path23.join(dir, relative);
     if (await exists(candidate)) {
-      return relative.includes(path20.sep) ? path20.dirname(candidate) : candidate;
+      return relative.includes(path23.sep) ? path23.dirname(candidate) : candidate;
     }
-    const parent = path20.dirname(dir);
+    const parent = path23.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -13711,7 +14066,7 @@ async function runAdapters(ctx) {
   for (const [target, count2] of byTarget) lines.push(`  ${target}: ${count2} archivo(s)`);
   if (report.written.length > 0) {
     lines.push("");
-    for (const p of report.written) lines.push(`  + ${path21.relative(ctx.cwd, path21.join(root, p))}`);
+    for (const p of report.written) lines.push(`  + ${path24.relative(ctx.cwd, path24.join(root, p))}`);
   } else {
     lines.push("");
     lines.push("Sin cambios: los adaptadores ya estaban al d\xEDa.");
@@ -13722,7 +14077,7 @@ async function runAdapters(ctx) {
 }
 
 // src/commands/adopt.ts
-import path23 from "path";
+import path25 from "path";
 async function runAdopt(ctx) {
   const { root } = await requireWorkspace(ctx);
   const domainsFlag = flagString(ctx.flags, "domains") ?? flagString(ctx.flags, "domain");
@@ -13742,11 +14097,11 @@ async function runAdopt(ctx) {
   }
   if (result.createdSpecs.length > 0) {
     lines.push("");
-    for (const spec of result.createdSpecs) lines.push(`  ${result.dryRun ? "[dry-run] " : "+ "}${path23.relative(ctx.cwd, spec)}`);
+    for (const spec of result.createdSpecs) lines.push(`  ${result.dryRun ? "[dry-run] " : "+ "}${path25.relative(ctx.cwd, spec)}`);
   }
   if (result.reportPath && !result.dryRun) {
     lines.push("");
-    lines.push(`  Informe: ${path23.relative(ctx.cwd, result.reportPath)}`);
+    lines.push(`  Informe: ${path25.relative(ctx.cwd, result.reportPath)}`);
   }
   lines.push("");
   lines.push("Siguiente: fase /satlas-adopt por dominio (requisitos AS-IS) y luego:");
@@ -13759,8 +14114,8 @@ async function runAdopt(ctx) {
     diagnostics: result.diagnostics,
     data: {
       domains: result.domains.map((d) => ({ name: d.name, files: d.files, existingSpec: d.existingSpec })),
-      createdSpecs: result.createdSpecs.map((s) => path23.relative(ctx.cwd, s)),
-      reportPath: result.reportPath ? path23.relative(ctx.cwd, result.reportPath) : void 0,
+      createdSpecs: result.createdSpecs.map((s) => path25.relative(ctx.cwd, s)),
+      reportPath: result.reportPath ? path25.relative(ctx.cwd, result.reportPath) : void 0,
       stack: result.stack,
       dryRun: result.dryRun
     },
@@ -13769,7 +14124,7 @@ async function runAdopt(ctx) {
 }
 
 // src/commands/analyze.ts
-import path24 from "path";
+import path26 from "path";
 async function runAnalyzeCommand(ctx) {
   const { root } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -13780,23 +14135,23 @@ async function runAnalyzeCommand(ctx) {
   const lines = [`An\xE1lisis \u2014 ${slug}`, "", `  estado: ${result.status}`, `  hallazgos: ${result.summary.errors} errores, ${result.summary.warnings} avisos`, `  evidencia: ${result.evidence.done}/${result.evidence.total} escenarios`];
   if (result.waves) lines.push(`  olas: ${result.waves.blocks} bloque(s), ${result.waves.waves} ola(s), ${result.waves.tasks} tarea(s)`);
   if (result.mockups) lines.push(`  mockups: ${result.mockups.screens} pantalla(s)${result.mockups.stale ? " (desactualizados)" : ""}`);
-  if (result.path) lines.push("", `  informe: ${path24.relative(ctx.cwd, result.path)}`);
+  if (result.path) lines.push("", `  informe: ${path26.relative(ctx.cwd, result.path)}`);
   for (const finding of result.findings) {
     lines.push(`  ${finding.severity.toUpperCase()} ${finding.code} \u2014 ${finding.message}`);
   }
   return {
     exitCode: result.status === "blocked" ? 1 : 0,
     diagnostics: result.findings,
-    data: result.path ? { ...result, path: path24.relative(ctx.cwd, result.path) } : result,
+    data: result.path ? { ...result, path: path26.relative(ctx.cwd, result.path) } : result,
     text: lines
   };
 }
 
 // src/commands/approve.ts
-import path26 from "path";
+import path28 from "path";
 
 // src/commands/issue.ts
-import path25 from "path";
+import path27 from "path";
 async function runIssue(ctx) {
   const action = ctx.positionals[0] ?? "status";
   const slug = ctx.positionals[1];
@@ -13824,7 +14179,7 @@ async function runIssue(ctx) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-ISSUE-000", severity: "error", message: "Falta el slug: satlas issue status <slug>" }] };
     }
     const change = await loadChange(root, slug);
-    const { config } = await loadConfig(path25.join(root, ".sdd"));
+    const { config } = await loadConfig(path27.join(root, ".sdd"));
     const tracker = change.meta?.tracker;
     const lines = [`Issue de ${slug}`, ""];
     if (!tracker || tracker.provider !== "github") {
@@ -13895,7 +14250,7 @@ async function runApprove(ctx) {
     };
   }
   const { root, workspace, config } = await requireWorkspace(ctx);
-  const artifact = target.includes("/") || target.includes("\\") ? target : path26.join("changes", target, "spec.md");
+  const artifact = target.includes("/") || target.includes("\\") ? target : path28.join("changes", target, "spec.md");
   const channelFlag = flagString(ctx.flags, "channel");
   const channel = channelFlag === "presentation" || channelFlag === "editor" || channelFlag === "pr" || channelFlag === "tracker" ? channelFlag : "cli";
   const change = workspace.changes.find(
@@ -13936,13 +14291,13 @@ async function runApprove(ctx) {
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: result.approval ? { ...result.approval, file: path26.relative(ctx.cwd, result.file) } : void 0,
+    data: result.approval ? { ...result.approval, file: path28.relative(ctx.cwd, result.file) } : void 0,
     text: lines
   };
 }
 
 // src/commands/archive.ts
-import path27 from "path";
+import path29 from "path";
 async function runArchive(ctx) {
   const slug = ctx.positionals[0];
   if (!slug) {
@@ -13972,7 +14327,7 @@ async function runArchive(ctx) {
     lines.push(`  modificados: ${result.fold.applied.modified.join(", ") || "\u2014"}`);
     lines.push(`  eliminados: ${result.fold.applied.removed.join(", ") || "\u2014"}`);
     lines.push(`  renombrados: ${result.fold.applied.renamed.join(", ") || "\u2014"}`);
-    if (result.archivedTo) lines.push(`  archivado en: ${path27.relative(ctx.cwd, result.archivedTo)}`);
+    if (result.archivedTo) lines.push(`  archivado en: ${path29.relative(ctx.cwd, result.archivedTo)}`);
   } else {
     lines.push("El delta no contiene operaciones (ADDED/MODIFIED/REMOVED/RENAMED).");
   }
@@ -13986,9 +14341,11 @@ async function runArchive(ctx) {
 }
 
 // src/commands/ci.ts
+import path30 from "path";
 async function runCi(ctx) {
   const { root, config } = await requireWorkspace(ctx);
   const strict = flagBool(ctx.flags, "strict");
+  const sarifPath = flagString(ctx.flags, "sarif");
   const extra = [];
   const workflowDir = await resolveWorkflowDir();
   if (workflowDir) {
@@ -14006,28 +14363,54 @@ async function runCi(ctx) {
     });
   }
   const gate = await runCiGate({ root, strict, extra });
+  const diagnostics = [...gate.diagnostics];
   const lines = ["CI de SpecAtlas", ""];
+  let sarifWritten;
+  if (sarifPath) {
+    const target = path30.resolve(ctx.cwd, sarifPath);
+    try {
+      await writeText(target, toSarifText({ diagnostics: gate.diagnostics, root, version: cliVersion(), failed: gate.failed }));
+      sarifWritten = path30.relative(ctx.cwd, target);
+    } catch (err) {
+      diagnostics.push({
+        code: "ATLAS-CI-SARIF-001",
+        severity: "warning",
+        message: `No se pudo escribir el informe SARIF en "${sarifPath}": ${err.message}`,
+        suggestion: "Revisa que la ruta sea escribible; el veredicto de la comprobaci\xF3n no cambia"
+      });
+    }
+  }
   for (const check of gate.checks) {
     lines.push(`  ${check.errors === 0 && check.warnings === 0 ? "OK  " : "FALLA"} ${check.name}: ${check.errors} errores, ${check.warnings} avisos`);
   }
   lines.push("");
   lines.push(gate.failed ? "Resultado: BLOQUEADO" : "Resultado: OK");
   if (strict) lines.push("(modo estricto: los avisos tambi\xE9n bloquean)");
+  if (sarifPath) {
+    lines.push(sarifWritten ? `Informe SARIF: ${sarifWritten} (${gate.diagnostics.length} hallazgo(s))` : `Informe SARIF: no se pudo escribir en "${sarifPath}"`);
+  }
   return {
     exitCode: gate.failed ? 1 : 0,
-    diagnostics: gate.diagnostics,
-    data: { checks: gate.checks, errors: gate.errors, warnings: gate.warnings, strict, failed: gate.failed },
+    diagnostics,
+    data: {
+      checks: gate.checks,
+      errors: gate.errors,
+      warnings: gate.warnings,
+      strict,
+      failed: gate.failed,
+      ...sarifWritten ? { sarif: sarifWritten } : {}
+    },
     text: lines
   };
 }
 
 // src/commands/profile.ts
-import path28 from "path";
+import path31 from "path";
 async function runProfile(ctx) {
   const action = ctx.positionals[0] ?? "detect";
   const { root, workspace } = await requireWorkspace(ctx);
   const officialDir = await resolveProfilesDir();
-  const customDir = path28.join(workspace.sddDir, "profiles", "custom");
+  const customDir = path31.join(workspace.sddDir, "profiles", "custom");
   const profiles = [...officialDir ? await loadProfilesFromDir(officialDir) : [], ...await loadProfilesFromDir(customDir)];
   if (action === "detect") {
     const result = await detectProfiles(root, profiles);
@@ -14056,7 +14439,7 @@ async function runProfile(ctx) {
     if (!name) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-PROFILE-001", severity: "error", message: "Falta el nombre del perfil: satlas profile create <nombre>" }] };
     }
-    const file = path28.join(customDir, `${name}.yaml`);
+    const file = path31.join(customDir, `${name}.yaml`);
     if (await exists(file)) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-PROFILE-002", severity: "error", message: `El perfil ya existe: ${file}` }] };
     }
@@ -14065,7 +14448,7 @@ async function runProfile(ctx) {
       exitCode: 0,
       diagnostics: [],
       data: { file },
-      text: [`Perfil creado: ${path28.relative(ctx.cwd, file)}`, "", "Ed\xEDtalo con los comandos reales de tu stack (build/lint/test) y tus anti-patrones."]
+      text: [`Perfil creado: ${path31.relative(ctx.cwd, file)}`, "", "Ed\xEDtalo con los comandos reales de tu stack (build/lint/test) y tus anti-patrones."]
     };
   }
   return {
@@ -14074,7 +14457,7 @@ async function runProfile(ctx) {
   };
 }
 async function isInside(dir, name) {
-  return exists(path28.join(dir, `${name}.yaml`));
+  return exists(path31.join(dir, `${name}.yaml`));
 }
 function profileTemplate(name) {
   return `name: ${name}
@@ -14102,7 +14485,7 @@ assumptions: []
 }
 
 // src/commands/doctor.ts
-import path29 from "path";
+import path32 from "path";
 async function runDoctorCommand(ctx) {
   const { root, config } = await requireWorkspace(ctx);
   const report = await runDoctor(root);
@@ -14119,12 +14502,15 @@ async function runDoctorCommand(ctx) {
       report.summary.warnings += 1;
     }
   }
+  const advisory = await upgradeAdvisory(root);
+  report.findings.push(...advisory.diagnostics);
+  report.summary = countBySeverity(report.findings);
   const lines = [msg("doctor.title", ctx.language), ""];
   if (report.findings.length === 0) {
     lines.push("Sin hallazgos. El workspace est\xE1 sano.");
   } else {
     for (const finding of report.findings) {
-      const location = finding.path ? ` ${path29.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""}` : "";
+      const location = finding.path ? ` ${path32.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""}` : "";
       lines.push(`  ${finding.severity.toUpperCase()}  ${finding.code}${location} \u2014 ${finding.message}`);
       if (finding.suggestion) lines.push(`       \u21B3 ${finding.suggestion}`);
     }
@@ -14198,7 +14584,7 @@ async function runHelp(ctx, commandName) {
 }
 
 // src/commands/init.ts
-import path30 from "path";
+import path33 from "path";
 async function runInit(ctx) {
   const languageFlag = flagString(ctx.flags, "language");
   const language = languageFlag === "en" ? "en" : languageFlag === "es" ? "es" : void 0;
@@ -14245,11 +14631,11 @@ async function runInit(ctx) {
   const lines = [msg("init.title", ctx.language), ""];
   if (result.created.length > 0) {
     lines.push(msg("init.done", ctx.language));
-    for (const file of result.created) lines.push(`  + ${path30.relative(ctx.cwd, file)}`);
+    for (const file of result.created) lines.push(`  + ${path33.relative(ctx.cwd, file)}`);
     if (compiled.length > 0) {
       lines.push("");
       lines.push("Adaptadores compilados:");
-      for (const file of compiled) lines.push(`  + ${path30.relative(ctx.cwd, path30.join(ctx.cwd, file))}`);
+      for (const file of compiled) lines.push(`  + ${path33.relative(ctx.cwd, path33.join(ctx.cwd, file))}`);
     }
     lines.push("");
     lines.push("Siguiente: crea un cambio con `satlas new <slug>` y escribe la spec funcional.");
@@ -14259,8 +14645,8 @@ async function runInit(ctx) {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
     data: {
-      sddDir: path30.relative(ctx.cwd, result.sddDir),
-      created: result.created.map((f) => path30.relative(ctx.cwd, f)),
+      sddDir: path33.relative(ctx.cwd, result.sddDir),
+      created: result.created.map((f) => path33.relative(ctx.cwd, f)),
       detected: result.detected?.matches.map((m) => ({ name: m.name, score: m.score })),
       best: result.detected?.best?.name
     },
@@ -14301,7 +14687,7 @@ async function runMetrics(ctx) {
 }
 
 // src/commands/mockup.ts
-import path31 from "path";
+import path34 from "path";
 async function runMockup(ctx) {
   const { root, workspace, config } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -14350,17 +14736,17 @@ async function runMockup(ctx) {
     `  pantallas: ${plan.screens.length}`,
     ...plan.screens.map((s) => `    - ${s.id}: ${s.title} (${s.illustrates.length} escenario(s))`),
     "",
-    `  plan: ${path31.relative(ctx.cwd, planFile)}`,
-    `  manifiesto: ${path31.relative(ctx.cwd, manifestFile)}`,
+    `  plan: ${path34.relative(ctx.cwd, planFile)}`,
+    `  manifiesto: ${path34.relative(ctx.cwd, manifestFile)}`,
     "",
     "Siguiente: genera el HTML de cada pantalla (fase /satlas-mockup) y valida con `satlas mockup " + slug + " --check`."
   ];
-  return { exitCode: 0, diagnostics: [], data: { plan, planFile: path31.relative(ctx.cwd, planFile), manifestFile: path31.relative(ctx.cwd, manifestFile) }, text: lines };
+  return { exitCode: 0, diagnostics: [], data: { plan, planFile: path34.relative(ctx.cwd, planFile), manifestFile: path34.relative(ctx.cwd, manifestFile) }, text: lines };
 }
 
 // src/mcp/server.ts
-import { promises as fs2 } from "fs";
-import path34 from "path";
+import { promises as fs3 } from "fs";
+import path37 from "path";
 import { createInterface } from "readline/promises";
 
 // src/mcp/protocol.ts
@@ -14422,12 +14808,12 @@ function stringArg(args, key) {
 }
 
 // src/mcp/tools/glossary.ts
-import path32 from "path";
+import path35 from "path";
 async function runAtlasGlossary(_args, host) {
   const resolved = await host.getWorkspace();
   if (!resolved) return noWorkspaceResult();
   const { root, config } = resolved;
-  const glossaryPath = path32.resolve(root, config.spec.glossary);
+  const glossaryPath = path35.resolve(root, config.spec.glossary);
   const raw = await readTextIfExists(glossaryPath);
   if (raw === void 0) {
     return jsonResult({
@@ -14473,7 +14859,7 @@ async function runAtlasImpact(args, host) {
 }
 
 // src/evaluate.ts
-import path33 from "path";
+import path36 from "path";
 function livingRequirementsMap2(specs) {
   const map = /* @__PURE__ */ new Map();
   for (const spec of specs) {
@@ -14482,7 +14868,7 @@ function livingRequirementsMap2(specs) {
   return map;
 }
 async function evaluateChange(workspace, config, change, approvals) {
-  const deltaPath = path33.join(change.dir, "spec.md");
+  const deltaPath = path36.join(change.dir, "spec.md");
   const deltaContent = await readTextIfExists(deltaPath);
   const approval = verifyApproval(change, approvals, config, deltaContent ?? void 0);
   const living = livingRequirementsMap2(workspace.specs);
@@ -14744,12 +15130,12 @@ var WorkspaceCache = class {
   }
 };
 async function workspaceStamp(root) {
-  const sddDir = path34.join(root, ".sdd");
-  const markers = [sddDir, path34.join(sddDir, "config.yaml"), path34.join(sddDir, "changes"), path34.join(sddDir, "specs"), path34.join(sddDir, "approvals.yaml")];
+  const sddDir = path37.join(root, ".sdd");
+  const markers = [sddDir, path37.join(sddDir, "config.yaml"), path37.join(sddDir, "changes"), path37.join(sddDir, "specs"), path37.join(sddDir, "approvals.yaml")];
   let stamp = 0;
   for (const marker of markers) {
     try {
-      const st = await fs2.stat(marker);
+      const st = await fs3.stat(marker);
       stamp = Math.max(stamp, st.mtimeMs);
     } catch {
     }
@@ -14763,7 +15149,7 @@ async function resolveMcpWorkspace(cwd, cache) {
   const cached2 = cache.get(root);
   if (cached2 && cached2.mtimeMs === stamp) return cached2.value;
   const { workspace, config } = await loadWorkspace(root);
-  const approvals = await loadApprovals(path34.join(root, ".sdd"));
+  const approvals = await loadApprovals(path37.join(root, ".sdd"));
   const value = { root, workspace, config, approvals: approvals.byArtifact };
   cache.set(root, stamp, value);
   return value;
@@ -14855,7 +15241,7 @@ async function runMcp(ctx) {
 }
 
 // src/commands/packs.ts
-import path35 from "path";
+import path38 from "path";
 async function runPacks(ctx) {
   const { root, config, workspace } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "check");
@@ -14913,14 +15299,14 @@ async function runPacks(ctx) {
     data: {
       slug,
       packs: evaluations.map((evaluation) => ({ id: evaluation.pack.id, status: evaluation.status, passed: evaluation.passed, failed: evaluation.failed, results: evaluation.results })),
-      analyzePath: path35.posix.join(".sdd", "changes", slug, "analyze.md")
+      analyzePath: path38.posix.join(".sdd", "changes", slug, "analyze.md")
     },
     text: lines
   };
 }
 
 // src/commands/new.ts
-import path36 from "path";
+import path39 from "path";
 async function runNew(ctx) {
   const slug = ctx.positionals[0];
   if (!slug) {
@@ -14946,14 +15332,14 @@ async function runNew(ctx) {
     msg("new.title", ctx.language),
     "",
     msg("new.done", ctx.language),
-    ...result.files.map((f) => `  + ${path36.relative(ctx.cwd, f)}`),
+    ...result.files.map((f) => `  + ${path39.relative(ctx.cwd, f)}`),
     "",
     `Siguiente: /satlas.specify ${result.slug} \u2014 escribe la especificaci\xF3n 100% funcional y de negocio.`
   ];
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: { slug: result.slug, files: result.files.map((f) => path36.relative(ctx.cwd, f)) },
+    data: { slug: result.slug, files: result.files.map((f) => path39.relative(ctx.cwd, f)) },
     text: lines
   };
 }
@@ -14988,7 +15374,7 @@ async function runNext(ctx) {
 }
 
 // src/commands/present.ts
-import path37 from "path";
+import path40 from "path";
 async function runPresentCommand(ctx) {
   const { root } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -15000,7 +15386,7 @@ async function runPresentCommand(ctx) {
   if (result.path) {
     lines.push("Propuesta generada");
     lines.push("");
-    lines.push(`  archivo: ${path37.relative(ctx.cwd, result.path)}`);
+    lines.push(`  archivo: ${path40.relative(ctx.cwd, result.path)}`);
     if (result.hash) lines.push(`  hash de la spec: ${shortHash(result.hash)}`);
     lines.push("");
     lines.push("\xC1brela en el navegador y comp\xE1rtela con el stakeholder.");
@@ -15010,7 +15396,7 @@ async function runPresentCommand(ctx) {
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: result.path ? { path: path37.relative(ctx.cwd, result.path), hash: result.hash } : void 0,
+    data: result.path ? { path: path40.relative(ctx.cwd, result.path), hash: result.hash } : void 0,
     text: lines
   };
 }
@@ -15086,7 +15472,8 @@ function usage(usageText) {
 
 // src/commands/status.ts
 async function runStatus(ctx) {
-  const { workspace, config, approvals } = await requireWorkspace(ctx);
+  const { root, workspace, config, approvals } = await requireWorkspace(ctx);
+  const advisory = await upgradeAdvisory(root);
   const lines = [msg("status.title", ctx.language), ""];
   const changes = [];
   if (workspace.changes.length === 0) {
@@ -15118,17 +15505,27 @@ async function runStatus(ctx) {
   for (const spec of workspace.specs) {
     lines.push(`  ${spec.domain} \u2014 ${spec.spec.requirements.length} requisitos`);
   }
-  const errors = workspace.diagnostics.filter((d) => d.severity === "error").length;
+  const diagnostics = [...workspace.diagnostics, ...advisory.diagnostics];
+  const errors = diagnostics.filter((d) => d.severity === "error").length;
   return {
     exitCode: errors > 0 ? 1 : 0,
-    diagnostics: workspace.diagnostics,
-    data: { changes, specs: workspace.specs.map((s) => ({ domain: s.domain, requirements: s.spec.requirements.length })) },
+    diagnostics,
+    data: {
+      changes,
+      specs: workspace.specs.map((s) => ({ domain: s.domain, requirements: s.spec.requirements.length })),
+      upgrade: {
+        currentVersion: advisory.plan.currentVersion,
+        pending: advisory.plan.pending.length,
+        newer: advisory.plan.newer.length,
+        unreadable: advisory.plan.unreadable.length
+      }
+    },
     text: lines
   };
 }
 
 // src/commands/trace.ts
-import path38 from "path";
+import path41 from "path";
 async function runTrace(ctx) {
   const { workspace, config } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "change");
@@ -15148,7 +15545,7 @@ async function runTrace(ctx) {
     data.push({ slug: change.slug, nodes: result.graph.nodes.length, edges: result.graph.edges.length, summary: result.summary, findings: result.findings });
     lines.push(`  ${change.slug}: ${result.graph.nodes.length} nodos, ${result.graph.edges.length} aristas, ${errors} errores, ${result.summary.warnings} avisos`);
     for (const finding of result.findings) {
-      const location = finding.path ? ` (${path38.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""})` : "";
+      const location = finding.path ? ` (${path41.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""})` : "";
       lines.push(`    ${finding.severity.toUpperCase()} ${finding.code} \u2014 ${finding.message}${location}`);
     }
   }
@@ -15157,12 +15554,130 @@ async function runTrace(ctx) {
   return { exitCode: blockingErrors > 0 ? 1 : 0, diagnostics, data: { changes: data }, text: lines };
 }
 
+// src/commands/upgrade.ts
+import path42 from "path";
+async function runUpgrade(ctx) {
+  const { root } = await requireWorkspace(ctx);
+  const apply = flagBool(ctx.flags, "apply");
+  const rollback = flagBool(ctx.flags, "rollback");
+  if (apply && rollback) {
+    return {
+      exitCode: 2,
+      diagnostics: [
+        {
+          code: "ATLAS-UPGRADE-CLI-001",
+          severity: "error",
+          message: "Elige una sola acci\xF3n: --apply o --rollback",
+          suggestion: "Vista previa: `satlas upgrade` \xB7 Aplicar: `satlas upgrade --apply` \xB7 Revertir: `satlas upgrade --rollback`"
+        }
+      ]
+    };
+  }
+  if (rollback) return renderRollback(await rollbackUpgrade(root), ctx);
+  if (apply) return renderApply(await applyUpgrade(root), ctx);
+  return renderPreview(await planUpgrade(root), root, ctx);
+}
+function summarizable(plan) {
+  return {
+    currentVersion: plan.currentVersion,
+    upToDate: plan.upToDate,
+    pending: plan.pending.map((i) => ({ artifact: i.artifact, from: i.from, to: i.to, migration: i.migration })),
+    newer: plan.newer.map((n) => ({ artifact: n.artifact, reason: n.reason })),
+    unreadable: plan.unreadable.map((u) => ({ artifact: u.artifact, reason: u.reason }))
+  };
+}
+function renderPreview(plan, root, ctx) {
+  const lines = [msg("upgrade.title", ctx.language), ""];
+  if (plan.upToDate && plan.newer.length === 0 && plan.unreadable.length === 0) {
+    lines.push(`El estado del proyecto est\xE1 al d\xEDa (versi\xF3n ${plan.currentVersion}). No hay nada que actualizar.`);
+    return { exitCode: 0, diagnostics: [], data: summarizable(plan), text: lines };
+  }
+  lines.push(`${msg("upgrade.preview", ctx.language)}: no se modifica nada.`);
+  lines.push(`  Versi\xF3n vigente: ${plan.currentVersion}`);
+  if (plan.pending.length === 0) {
+    lines.push("  Elementos por actualizar: 0");
+  } else {
+    lines.push(`  Elementos por actualizar: ${plan.pending.length}`);
+    for (const item of plan.pending) {
+      lines.push(`    ${item.artifact}  ${item.from} \u2192 ${item.to}  (${item.migration})`);
+    }
+    lines.push("");
+    lines.push(`Aplica la actualizaci\xF3n con \`satlas upgrade --apply\`.`);
+  }
+  for (const item of plan.newer) {
+    lines.push(`  Aviso: "${item.artifact}" ${item.reason}`);
+  }
+  for (const item of plan.unreadable) {
+    lines.push(`  Ilegible: "${item.artifact}" \u2014 ${item.reason}`);
+    lines.push(`    \u21B3 ${path42.relative(ctx.cwd, item.path)}`);
+  }
+  return { exitCode: 0, diagnostics: [], data: summarizable(plan), text: lines };
+}
+function renderApply(report, ctx) {
+  const lines = [msg("upgrade.title", ctx.language), ""];
+  if (report.status === "up-to-date") {
+    lines.push("No hab\xEDa nada que actualizar; no se escribi\xF3 ning\xFAn elemento.");
+    return { exitCode: 0, diagnostics: [], data: { status: report.status, plan: summarizable(report.plan) }, text: lines };
+  }
+  if (report.status === "failed") {
+    lines.push(`La actualizaci\xF3n fall\xF3 en "${report.failure?.artifact}": ${report.failure?.message}`);
+    lines.push("El proyecto qued\xF3 exactamente como estaba.");
+    return {
+      exitCode: 1,
+      diagnostics: [{ code: "ATLAS-UPGRADE-101", severity: "error", message: `Fall\xF3 la actualizaci\xF3n en "${report.failure?.artifact}": ${report.failure?.message}` }],
+      data: { status: report.status, failure: report.failure },
+      text: lines
+    };
+  }
+  lines.push(`Actualizaci\xF3n aplicada: ${report.applied.length} elemento(s) a la versi\xF3n ${report.plan.currentVersion}.`);
+  lines.push(`Respaldo recuperable: ${report.backup?.relativeDir}`);
+  if (report.plan.unreadable.length > 0) {
+    lines.push(`No se tocaron ${report.plan.unreadable.length} elemento(s) ilegible(s).`);
+  }
+  return {
+    exitCode: 0,
+    diagnostics: [],
+    data: {
+      status: report.status,
+      applied: report.applied.map((i) => i.artifact),
+      backup: report.backup,
+      plan: summarizable(report.plan)
+    },
+    text: lines
+  };
+}
+function renderRollback(report, ctx) {
+  const lines = [msg("upgrade.title", ctx.language), ""];
+  if (report.status === "no-backup") {
+    lines.push("No hay respaldo disponible para revertir; no se modific\xF3 nada.");
+    return {
+      exitCode: 1,
+      diagnostics: [{ code: "ATLAS-UPGRADE-102", severity: "warning", message: "No hay respaldo disponible para revertir la \xFAltima actualizaci\xF3n" }],
+      data: { status: report.status },
+      text: lines
+    };
+  }
+  if (report.status === "failed") {
+    lines.push(`La reversi\xF3n fall\xF3 en "${report.failure?.artifact}": ${report.failure?.message}`);
+    lines.push("El respaldo se conserva para reintentar.");
+    return {
+      exitCode: 1,
+      diagnostics: [{ code: "ATLAS-UPGRADE-103", severity: "error", message: `Fall\xF3 la reversi\xF3n en "${report.failure?.artifact}": ${report.failure?.message}` }],
+      data: { status: report.status, failure: report.failure },
+      text: lines
+    };
+  }
+  lines.push(`Se restaur\xF3 el estado previo: ${report.restored.length} elemento(s). El respaldo qued\xF3 consumido.`);
+  return { exitCode: 0, diagnostics: [], data: { status: report.status, restored: report.restored, backup: report.backup }, text: lines };
+}
+
 // src/commands/validate.ts
-import path39 from "path";
+import path43 from "path";
 async function runValidate(ctx) {
-  const { workspace, config, approvals } = await requireWorkspace(ctx);
+  const { root, workspace, config, approvals } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "change");
   const strict = flagBool(ctx.flags, "strict");
+  const advisory = slug ? void 0 : await upgradeAdvisory(root);
   const diagnostics = [];
   const lines = [msg("validate.title", ctx.language), ""];
   for (const spec of workspace.specs) {
@@ -15184,22 +15699,35 @@ async function runValidate(ctx) {
     for (const finding of evaluation.lintFindings) {
       lines.push(`    ${finding.severity.toUpperCase()} ${finding.code}${finding.line ? `:${finding.line}` : ""} \u2014 ${finding.message}`);
     }
-    lines.push(`    archivo: ${path39.relative(ctx.cwd, path39.join(change.dir, "spec.md"))}`);
+    lines.push(`    archivo: ${path43.relative(ctx.cwd, path43.join(change.dir, "spec.md"))}`);
   }
   if (targets.length === 0) lines.push("Sin cambios activos.");
+  if (advisory && advisory.plan.pending.length > 0) {
+    lines.push(`Actualizaci\xF3n pendiente: ${advisory.plan.pending.length} elemento(s) (vista previa: \`satlas upgrade\`).`);
+  }
   const errors = diagnostics.filter((d) => d.severity === "error").length;
   const warnings = diagnostics.filter((d) => d.severity === "warning").length;
   if (errors === 0 && warnings === 0) lines.push(msg("validate.ok", ctx.language));
   return {
     exitCode: errors > 0 || strict && warnings > 0 ? 1 : 0,
-    diagnostics,
-    data: { changes, errors, warnings },
+    diagnostics: advisory ? [...diagnostics, ...advisory.diagnostics] : diagnostics,
+    data: {
+      changes,
+      errors,
+      warnings,
+      upgrade: advisory ? {
+        currentVersion: advisory.plan.currentVersion,
+        pending: advisory.plan.pending.length,
+        newer: advisory.plan.newer.length,
+        unreadable: advisory.plan.unreadable.length
+      } : void 0
+    },
     text: lines
   };
 }
 
 // src/commands/verify.ts
-import path40 from "path";
+import path44 from "path";
 async function runVerify(ctx) {
   const { root, workspace } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -15242,7 +15770,7 @@ async function runVerify(ctx) {
     return { exitCode: 2, diagnostics: [{ code: "ATLAS-VERIFY-001", severity: "error", message: "Falta --by <nombre> (o define meta.owner)" }] };
   }
   const profilesDir = await resolveProfilesDir();
-  const profile = await loadActiveProfile(path40.join(root, ".sdd"), [profilesDir ?? "", path40.join(root, ".sdd", "profiles", "custom")].filter(Boolean));
+  const profile = await loadActiveProfile(path44.join(root, ".sdd"), [profilesDir ?? "", path44.join(root, ".sdd", "profiles", "custom")].filter(Boolean));
   const record = await recordEvidence({
     root,
     slug,
@@ -15264,7 +15792,7 @@ async function runVerify(ctx) {
     if (record.evidence.command) lines.push(`  comando: ${record.evidence.command}`);
     lines.push(`  resultado: ${record.evidence.result}`);
     if (record.evidence.outputHash) lines.push(`  hash:    ${record.evidence.outputHash}`);
-    lines.push(`  archivo: ${path40.relative(ctx.cwd, record.path)}`);
+    lines.push(`  archivo: ${path44.relative(ctx.cwd, record.path)}`);
     if (record.stdout) {
       lines.push("");
       lines.push("  salida (\xFAltimas l\xEDneas):");
@@ -15279,7 +15807,7 @@ async function runVerify(ctx) {
   return {
     exitCode: record.exitCode === 0 ? 0 : 1,
     diagnostics: record.diagnostics,
-    data: { evidence: record.evidence, path: path40.relative(ctx.cwd, record.path), exitCode: record.exitCode },
+    data: { evidence: record.evidence, path: path44.relative(ctx.cwd, record.path), exitCode: record.exitCode },
     text: lines
   };
 }
@@ -15334,6 +15862,7 @@ var HANDLERS2 = {
   trace: runTrace,
   waves: runWaves,
   doctor: runDoctorCommand,
+  upgrade: runUpgrade,
   approve: runApprove,
   issue: runIssue,
   adapters: runAdapters,
@@ -15378,7 +15907,7 @@ async function requireWorkspace(ctx) {
     throw new CliError("ATLAS-WS-001", msg("cli.noWorkspace", ctx.language), 2);
   }
   const { workspace, config } = await loadWorkspace(root);
-  const approvals = await loadApprovals(path41.join(root, ".sdd"));
+  const approvals = await loadApprovals(path45.join(root, ".sdd"));
   return { root, workspace, config, approvals: approvals.byArtifact };
 }
 var CliError = class extends Error {
@@ -15445,7 +15974,7 @@ function printResult(command, result, json2, language) {
   }
   const lines = [...result.text ?? []];
   for (const d of result.diagnostics) {
-    const location = d.path ? ` ${path41.relative(process.cwd(), d.path)}${d.line ? `:${d.line}` : ""}` : "";
+    const location = d.path ? ` ${path45.relative(process.cwd(), d.path)}${d.line ? `:${d.line}` : ""}` : "";
     lines.push(`${d.severity === "error" ? "ERROR" : d.severity === "warning" ? "AVISO" : "NOTA"}  ${d.code}${location} \u2014 ${d.message}`);
     if (d.suggestion) lines.push(`       \u21B3 ${d.suggestion}`);
   }