@specatlas/core 0.1.26 → 0.1.28

package/dist/index.js

@@ -61,6 +61,9 @@ var atlasConfigSchema = z.object({
     analyze: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("blocking"), min_severity: z.enum(["low", "medium", "high"]).default("medium") }).default({}),
     verify: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("blocking"), require_evidence: z.boolean().default(true) }).default({}),
     review: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("advisory") }).default({}),
+    clarify: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("advisory") }).default({}),
+    docs: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("blocking") }).default({}),
+    contracts: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("advisory") }).default({}),
     mockup: z.object({ require_approval: z.boolean().default(false), compare_in_verify: z.boolean().default(false) }).default({})
   }).default({}),
   trace: z.object({ mode: z.enum(["off", "advisory", "blocking"]).default("blocking"), prefix: z.string().default("REQ") }).default({}),
@@ -209,6 +212,7 @@ var SCENARIO_HEAD_RE = /^####\s+(?:Scenario|Escenario):\s+(REQ-[A-Z0-9-]+-S\d+)\
 var RULE_RE = /^-\s*(?:Rule|Regla)\s+(BR-[A-Z0-9-]+)\s*:\s*(.+?)\s*$/;
 var WHEN_RE = /^-\s*\*\*\s*(?:WHEN|CUANDO|DADO QUE)\s*\*\*\s*(.+?)\s*$/i;
 var THEN_RE = /^-\s*\*\*\s*(?:THEN|ENTONCES|Y|AND)\s*\*\*\s*(.+?)\s*$/i;
+var CONTRACT_RE = /^-\s*\*\*\s*(?:CONTRATO|CONTRACT)\s*\*\*\s*:\s*(.+?)\s*$/i;
 function newDraft(id, title, line) {
   return { id, title, line, prose: [], rules: [], scenarios: [] };
 }
@@ -293,6 +297,16 @@ function parseRequirementBlocks(body, startLine = 1, filePath) {
       currentScenario.then.push(thenMatch[1] ?? "");
       continue;
     }
+    const contractMatch = CONTRACT_RE.exec(line);
+    if (contractMatch && currentScenario) {
+      const ref = (contractMatch[1] ?? "").trim();
+      if (ref !== "") {
+        const list = currentScenario.contracts ?? [];
+        if (!list.includes(ref)) list.push(ref);
+        currentScenario.contracts = list;
+      }
+      continue;
+    }
     if (current && !currentScenario) {
       if (line.trim() !== "") current.prose.push(line.trim());
     }
@@ -640,6 +654,35 @@ function findScenarioHeading(lines, blockLineIndex) {
   return void 0;
 }
 
+// src/parse/clarify.ts
+var OPEN_RE = /^\s*-\s*\[\s\]\s+(.+?)\s*$/;
+var DONE_RE = /^\s*-\s*\[[xX]\]\s+(.+?)\s*$/;
+var ANSWER_SEPARATOR = " \u2014 ";
+function splitAnswer(raw) {
+  const index = raw.indexOf(ANSWER_SEPARATOR);
+  if (index === -1) return { text: raw.trim() };
+  return { text: raw.slice(0, index).trim(), answer: raw.slice(index + ANSWER_SEPARATOR.length).trim() };
+}
+function parseClarify(content, filePath) {
+  const fm = parseFrontmatter(content, filePath);
+  const lines = fm.body.replace(/\r\n?/g, "\n").split("\n");
+  const open = [];
+  const resolved = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    const lineNo = fm.bodyStartLine + i;
+    const done = DONE_RE.exec(line);
+    if (done) {
+      const item = splitAnswer(done[1] ?? "");
+      resolved.push({ text: item.text, line: lineNo, ...item.answer !== void 0 ? { answer: item.answer } : {} });
+      continue;
+    }
+    const pending = OPEN_RE.exec(line);
+    if (pending) open.push({ text: pending[1] ?? "", line: lineNo });
+  }
+  return { path: filePath, open, resolved, diagnostics: [] };
+}
+
 // src/parse/glossary.ts
 var HEADER_KEYS = /* @__PURE__ */ new Set(["t\xE9rmino", "termino", "term", "definici\xF3n", "definicion", "definition", "sin\xF3nimos", "sinonimos", "synonyms"]);
 var SEPARATOR_RE = /^:?-{2,}:?$/;
@@ -731,6 +774,7 @@ function impactOfRequirement(workspace, reqId) {
   const id = reqId.toUpperCase();
   const scenarios = /* @__PURE__ */ new Set();
   let exists2 = false;
+  let origin;
   for (const spec of workspace.specs) {
     for (const req of spec.spec.requirements) {
       if (req.id !== id) continue;
@@ -747,6 +791,18 @@ function impactOfRequirement(workspace, reqId) {
     if ((change.delta?.removed ?? []).some((r) => r.id === id)) exists2 = true;
     if ((change.delta?.renamed ?? []).some((r) => r.from.id === id || r.to.id === id)) exists2 = true;
   }
+  if (!exists2) {
+    for (const link of workspace.links?.entries ?? []) {
+      const spec = workspace.links?.specs.find((candidate) => candidate.spec.requirements.some((req) => req.id === id));
+      if (!spec) continue;
+      const requirement = spec.spec.requirements.find((candidate) => candidate.id === id);
+      if (!requirement) continue;
+      exists2 = true;
+      origin = link.name;
+      for (const sc of requirement.scenarios) scenarios.add(sc.id);
+      break;
+    }
+  }
   const report = emptyReport(id, "requirement");
   if (!exists2) return report;
   report.exists = true;
@@ -754,6 +810,10 @@ function impactOfRequirement(workspace, reqId) {
   const reqOf = scenarioToReq(workspace);
   collect(workspace, report, /* @__PURE__ */ new Set([id, ...scenarios]), reqOf);
   if (!report.requirements.includes(id)) report.requirements.unshift(id);
+  if (origin !== void 0) {
+    report.external = true;
+    report.origin = origin;
+  }
   return report;
 }
 function impactOfFile(workspace, file) {
@@ -794,14 +854,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, path22, line) {
+function lintText(text, code, terms, label, path25, line) {
   const out = [];
   const lower = text.toLowerCase();
   for (const term of terms) {
     if (wordBoundary(lower, term)) {
       out.push(
         diag(code, "error", `${label}: "${term}"`, {
-          path: path22,
+          path: path25,
           line,
           suggestion: "La especificaci\xF3n es funcional y de negocio: describe comportamiento, no tecnolog\xEDa ni adjetivos vagos"
         })
@@ -810,7 +870,7 @@ function lintText(text, code, terms, label, path22, line) {
   }
   return out;
 }
-function lintRequirement(req, path22, opts = {}) {
+function lintRequirement(req, path25, opts = {}) {
   const out = [];
   const vague = opts.language === "en" ? VAGUE_EN : VAGUE_ES;
   const tech = opts.language === "en" ? TECH_EN : TECH_ES;
@@ -821,32 +881,32 @@ function lintRequirement(req, path22, 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", path22, part.line));
+    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path25, part.line));
     if (opts.businessOnly !== false) {
-      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path22, part.line));
+      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path25, part.line));
     }
   }
   if (req.scenarios.length === 0) {
-    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path22, 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: path25, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
   }
   return out;
 }
-function lintDelta(delta, livingRequirements, path22, opts = {}) {
+function lintDelta(delta, livingRequirements, path25, opts = {}) {
   const out = [...delta.diagnostics];
   for (const req of [...delta.added, ...delta.modified]) {
-    out.push(...lintRequirement(req, path22, opts));
+    out.push(...lintRequirement(req, path25, 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: path22, line: req.line }));
+      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path25, 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: path22,
+            path: path25,
             line: req.line,
             suggestion: "Copia el bloque completo de la spec viva y ed\xEDtalo; para quitarlo, decl\xE1ralo en REMOVED"
           })
@@ -857,15 +917,15 @@ function lintDelta(delta, livingRequirements, path22, 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: path22, line: req.line }));
+      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path25, 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: path22, 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: path25, 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: path22, line: rename2.line }));
+      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path25, line: rename2.line }));
     }
   }
   return out;
@@ -895,7 +955,7 @@ var MERMAID_KEYWORDS = [
   "architecture-beta"
 ];
 var MERMAID_BLOCKS = /^\s*(alt|loop|opt|par|rect|critical|break|subgraph)\b/;
-function lintPlan(planText, path22) {
+function lintPlan(planText, path25) {
   const out = [];
   const blocks = [...planText.matchAll(/```mermaid\r?\n([\s\S]*?)```/g)];
   for (const [index, block] of blocks.entries()) {
@@ -905,7 +965,7 @@ function lintPlan(planText, path22) {
     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: path22,
+          path: path25,
           suggestion: "Corrige el tipo del diagrama o elimina el bloque"
         })
       );
@@ -919,7 +979,7 @@ function lintPlan(planText, path22) {
     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: path22,
+          path: path25,
           suggestion: "Cierra cada bloque alt/loop/opt/par/rect/subgraph con `end`"
         })
       );
@@ -931,7 +991,7 @@ function lintPlan(planText, path22) {
         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: path22,
+              path: path25,
               suggestion: "Sustituye `;` por `\xB7` o `,` en los mensajes de sequenceDiagram"
             })
           );
@@ -1044,15 +1104,25 @@ function checkTrace(input) {
       );
     }
   }
+  const linkedIds = new Set(input.linked?.ids ?? []);
+  const unavailableLinks = input.linked?.unavailable ?? [];
   for (const task of taskById.values()) {
     for (const c of task.covers) {
-      if (!livingReqs.has(c) && !deltaScenarios.has(c) && !allScenarioIds.has(c)) {
+      if (!livingReqs.has(c) && !deltaScenarios.has(c) && !allScenarioIds.has(c) && !linkedIds.has(c)) {
         findings.push(
           diag("TRACE-003", "error", `La tarea ${task.id} cubre ${c}, que no existe`, {
             path: change.tasks?.path,
-            suggestion: "Corrige el id o crea el requisito/escenario"
+            suggestion: unavailableLinks.length > 0 ? "Corrige el id o revisa los enlaces no disponibles (`satlas link list`)" : "Corrige el id o crea el requisito/escenario"
           })
         );
+        if (unavailableLinks.length > 0) {
+          findings.push(
+            diag("ATLAS-LINK-003", "warning", `Referencia no resuelta: ${c} (hay ${unavailableLinks.length} enlace(s) no disponible(s): ${unavailableLinks.join(", ")})`, {
+              path: change.tasks?.path,
+              suggestion: "Restaura la ruta del enlace o corrige la referencia"
+            })
+          );
+        }
       }
     }
     for (const dep of task.dependsOn) {
@@ -1219,12 +1289,172 @@ function planBlock(block, maxParallel) {
 }
 
 // src/lifecycle.ts
+import path3 from "path";
+
+// src/contracts.ts
 import path2 from "path";
+import { parse as parseYaml4 } from "yaml";
+var CONTRACTS_DIR = "contracts";
+var OPENAPI_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+var SUPPORTED_HINT = "Formatos esperados: OpenAPI 3.x (.yaml/.json), GraphQL SDL (.graphql/.gql) y protobuf (.proto)";
+function lineOf(content, needle) {
+  const index = content.indexOf(needle);
+  if (index < 0) return 1;
+  return content.slice(0, index).split("\n").length;
+}
+function formatOf(file, content) {
+  const ext = path2.extname(file).toLowerCase();
+  if (ext === ".proto") return "protobuf";
+  if (ext === ".graphql" || ext === ".gql") return "graphql";
+  if (ext === ".yaml" || ext === ".yml" || ext === ".json") {
+    return /(^|\n)\s*openapi\s*:/.test(content) || /"openapi"\s*:/.test(content) ? "openapi" : "unsupported";
+  }
+  return "unsupported";
+}
+function parseOpenApi(file, content) {
+  const findings = [];
+  let data;
+  try {
+    data = parseYaml4(content);
+  } catch (error) {
+    return { operations: [], findings: [diag("ATLAS-CONTRACT-001", "error", `Contrato OpenAPI ilegible: ${error.message}`, { path: file })] };
+  }
+  const doc = data;
+  if (!doc || typeof doc !== "object" || typeof doc.openapi !== "string" || typeof doc.paths !== "object" || doc.paths === null || Array.isArray(doc.paths)) {
+    return {
+      operations: [],
+      findings: [diag("ATLAS-CONTRACT-001", "error", "Contrato OpenAPI inv\xE1lido: faltan la versi\xF3n (openapi) o los caminos (paths)", { path: file, line: lineOf(content, "paths"), suggestion: SUPPORTED_HINT })]
+    };
+  }
+  const operations = [];
+  for (const [route, value] of Object.entries(doc.paths)) {
+    if (!route.startsWith("/") || typeof value !== "object" || value === null) continue;
+    for (const method of OPENAPI_METHODS) {
+      if (method in value) {
+        operations.push({ id: `${method.toUpperCase()} ${route}`, kind: "openapi", file, line: lineOf(content, route) });
+      }
+    }
+  }
+  return { operations, findings };
+}
+function parseGraphql(file, content) {
+  const operations = [];
+  const blockRe = /type\s+(Query|Mutation|Subscription)\s*\{([\s\S]*?)\}/g;
+  for (const match of content.matchAll(blockRe)) {
+    const typeName = match[1] ?? "";
+    const body = match[2] ?? "";
+    for (const field of body.split("\n")) {
+      const fieldMatch = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(\(|:)/.exec(field);
+      if (fieldMatch) operations.push({ id: `${typeName}.${fieldMatch[1]}`, kind: "graphql", file, line: lineOf(content, field.trim()) });
+    }
+  }
+  if (operations.length === 0) {
+    return {
+      operations,
+      findings: [diag("ATLAS-CONTRACT-001", "error", "Contrato GraphQL inv\xE1lido: no declara consultas (type Query), mutaciones ni suscripciones", { path: file, suggestion: SUPPORTED_HINT })]
+    };
+  }
+  return { operations, findings: [] };
+}
+function parseProtobuf(file, content) {
+  const operations = [];
+  const serviceRe = /service\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\}/g;
+  for (const match of content.matchAll(serviceRe)) {
+    const service = match[1] ?? "";
+    const body = match[2] ?? "";
+    for (const rpc of body.matchAll(/rpc\s+([A-Za-z_][A-Za-z0-9_]*)/g)) {
+      operations.push({ id: `${service}.${rpc[1]}`, kind: "protobuf", file, line: lineOf(content, `rpc ${rpc[1]}`) });
+    }
+  }
+  if (operations.length === 0 && !/message\s+[A-Za-z_]/.test(content)) {
+    return {
+      operations,
+      findings: [diag("ATLAS-CONTRACT-001", "error", "Contrato protobuf inv\xE1lido: no declara servicios ni mensajes", { path: file, suggestion: SUPPORTED_HINT })]
+    };
+  }
+  return { operations, findings: [] };
+}
+function parseContract(file, content) {
+  const format = formatOf(file, content);
+  if (format === "unsupported") {
+    return {
+      path: file,
+      format,
+      operations: [],
+      findings: [diag("ATLAS-CONTRACT-002", "warning", "Formato de contrato no soportado; el archivo no se interpreta ni se toca", { path: file, suggestion: SUPPORTED_HINT })]
+    };
+  }
+  const parsed = format === "openapi" ? parseOpenApi(file, content) : format === "graphql" ? parseGraphql(file, content) : parseProtobuf(file, content);
+  return { path: file, format, operations: parsed.operations, findings: parsed.findings };
+}
+async function loadContracts(changeDir) {
+  const dir = path2.join(changeDir, CONTRACTS_DIR);
+  const files = [];
+  const operations = [];
+  const findings = [];
+  const entries = (await listDir(dir)).sort();
+  for (const entry of entries) {
+    const file = path2.join(dir, entry);
+    const content = await readTextIfExists(file);
+    if (content === void 0) continue;
+    const parsed = parseContract(file, content);
+    files.push({ path: parsed.path, format: parsed.format, operations: parsed.operations });
+    operations.push(...parsed.operations);
+    findings.push(...parsed.findings);
+  }
+  return { files, operations, findings };
+}
+function contractCoverage(change, mode) {
+  const state = change.contracts;
+  if (mode === "off" || !state || state.files.length === 0 || state.operations.length === 0) return [];
+  const scenarioContracts = /* @__PURE__ */ new Map();
+  for (const requirement of [...change.delta?.added ?? [], ...change.delta?.modified ?? []]) {
+    for (const scenario of requirement.scenarios) {
+      for (const ref of scenario.contracts ?? []) {
+        if (!scenarioContracts.has(ref)) scenarioContracts.set(ref, scenario.id);
+      }
+    }
+  }
+  const findings = [];
+  for (const operation of state.operations) {
+    if (!scenarioContracts.has(operation.id)) {
+      findings.push(
+        diag("ATLAS-CONTRACT-003", "warning", `Operaci\xF3n sin escenario: ${operation.id}`, {
+          path: operation.file,
+          line: operation.line,
+          suggestion: `Declara la operaci\xF3n en un escenario con \xB7 **Contrato**: ${operation.id}`
+        })
+      );
+    }
+  }
+  const known = new Set(state.operations.map((operation) => operation.id));
+  for (const [ref, scenarioId] of scenarioContracts) {
+    if (!known.has(ref)) {
+      findings.push(
+        diag("ATLAS-CONTRACT-004", "warning", `Referencia rota: el escenario ${scenarioId} declara "${ref}", que no existe en el contrato`, {
+          path: change.delta?.path,
+          suggestion: "Corrige la referencia o a\xF1ade la operaci\xF3n al contrato"
+        })
+      );
+    }
+  }
+  return findings;
+}
+function contractsAdvisory(change, cfg) {
+  const state = change.contracts;
+  if (!state || state.files.length === 0) return [];
+  const mode = cfg.gates.contracts.mode;
+  const form = state.findings;
+  if (mode === "advisory") return [...form, ...contractCoverage(change, mode)];
+  return form;
+}
+
+// src/lifecycle.ts
 function verifyApproval(change, approvals, cfg, specContent) {
   if (cfg.gates.approval === "none") return { status: "not_required" };
   if ((change.meta?.overrides ?? []).some((o) => o.gate === "approval")) return { status: "overridden" };
   if (!change.delta) return { status: "missing" };
-  const key = path2.posix.join("changes", change.slug, "spec.md");
+  const key = path3.posix.join("changes", change.slug, "spec.md");
   const approval = approvals.get(key) ?? approvals.get(`${key}`);
   if (!approval) return { status: "missing" };
   if (specContent === void 0) return { status: "valid", approvedBy: approval.by, approvedAt: approval.at };
@@ -1240,6 +1470,29 @@ function requiresMockups(meta, cfg) {
 function mockupOverride(change) {
   return (change.meta?.overrides ?? []).some((override) => override.gate === "mockup");
 }
+function docsReady(change) {
+  const paths = change.docsPaths ?? [];
+  return paths.some((p) => p.endsWith("tecnica.md")) && paths.some((p) => p.endsWith("manual.md"));
+}
+function clarifyAdvisory(change, cfg) {
+  const open = change.clarify?.open.length ?? 0;
+  if (cfg.gates.clarify.mode !== "advisory" || open === 0) return [];
+  return [
+    diag("ATLAS-CLARIFY-001", "warning", `El cambio "${change.slug}" tiene ${open} pregunta(s) sin aclarar`, {
+      ...change.clarifyPath !== void 0 ? { path: change.clarifyPath } : {},
+      suggestion: `Aclara antes de planificar: /satlas.clarify ${change.slug} (o satlas clarify ${change.slug})`
+    })
+  ];
+}
+function docsAdvisory(change, cfg) {
+  const lane = change.meta?.lane ?? cfg.lanes.default;
+  if (lane !== "full" || cfg.gates.docs.mode !== "advisory" || docsReady(change)) return [];
+  return [
+    diag("ATLAS-DOCS-001", "warning", `El cambio "${change.slug}" (carril completo) no tiene su documentaci\xF3n t\xE9cnica y manual`, {
+      suggestion: `Genera la documentaci\xF3n: satlas docs ${change.slug} (o /satlas.docs ${change.slug})`
+    })
+  ];
+}
 function deriveState(input) {
   const { change, cfg, approval, blockingFindings } = input;
   const lane = change.meta?.lane ?? cfg.lanes.default;
@@ -1302,6 +1555,16 @@ function deriveState(input) {
     };
   }
   if (!change.planPath && !change.tasks) {
+    const openQuestions = change.clarify?.open.length ?? 0;
+    if (openQuestions > 0 && cfg.gates.clarify.mode === "blocking") {
+      blockedBy.push(`aclaraci\xF3n pendiente (${openQuestions})`);
+      return {
+        state: "approved",
+        blockedBy,
+        nextAction: next(`/satlas.clarify ${change.slug}`, `Aclarar ${openQuestions} pregunta(s) antes de planificar`, true),
+        progress
+      };
+    }
     return { state: "approved", blockedBy, nextAction: next(`/satlas.plan ${change.slug}`, "Crear el plan t\xE9cnico y las tareas", true), progress };
   }
   if (tasksTotal > 0 && tasksDone < tasksTotal) {
@@ -1315,6 +1578,17 @@ function deriveState(input) {
     blockedBy.push("review pendiente");
     return { state: "verified", blockedBy, nextAction: next(`/satlas.review ${change.slug}`, "Revisi\xF3n de c\xF3digo", true), progress };
   }
+  if (lane === "full" && cfg.gates.docs.mode === "blocking" && !docsReady(change)) {
+    blockedBy.push("documentaci\xF3n pendiente");
+    return { state: "reviewed", blockedBy, nextAction: next(`/satlas.docs ${change.slug}`, "Generar la documentaci\xF3n t\xE9cnica y manual del cambio", true), progress };
+  }
+  if (cfg.gates.contracts.mode === "blocking") {
+    const contractFindings = contractCoverage(change, "blocking");
+    if (contractFindings.length > 0) {
+      blockedBy.push(`contratos con hallazgos (${contractFindings.length})`);
+      return { state: "verified", blockedBy, nextAction: next(`satlas contracts ${change.slug}`, "Resolver los hallazgos de contrato antes de archivar"), progress };
+    }
+  }
   return { state: "ready", blockedBy, nextAction: next(`satlas archive ${change.slug}`, "Archivar el cambio y plegar los deltas"), progress };
 }
 function stateLabel(state) {
@@ -1328,6 +1602,7 @@ function stateLabel(state) {
     building: "construyendo",
     built: "construido",
     verified: "verificado",
+    reviewed: "revisado",
     ready: "listo para archivar",
     archived: "archivado"
   };
@@ -1335,8 +1610,8 @@ function stateLabel(state) {
 }
 
 // src/profiles.ts
-import path3 from "path";
-import { parse as parseYaml4 } from "yaml";
+import path4 from "path";
+import { parse as parseYaml5 } from "yaml";
 import { z as z3 } from "zod";
 var profileSchema = z3.object({
   name: z3.string().min(1),
@@ -1383,7 +1658,7 @@ async function loadProfileFile(filePath) {
   if (raw === void 0) return void 0;
   let data;
   try {
-    data = parseYaml4(raw);
+    data = parseYaml5(raw);
   } catch {
     return void 0;
   }
@@ -1395,7 +1670,7 @@ async function loadProfilesFromDir(dir) {
   const out = [];
   for (const entry of entries) {
     if (!/\.ya?ml$/i.test(entry)) continue;
-    const profile = await loadProfileFile(path3.join(dir, entry));
+    const profile = await loadProfileFile(path4.join(dir, entry));
     if (profile) out.push(profile);
   }
   return out;
@@ -1433,10 +1708,10 @@ async function detectProfiles(root, profiles) {
   return result;
 }
 async function loadDetectedBest(sddDir) {
-  const raw = await readTextIfExists(path3.join(sddDir, "profiles", "detected.yaml"));
+  const raw = await readTextIfExists(path4.join(sddDir, "profiles", "detected.yaml"));
   if (raw === void 0) return void 0;
   try {
-    const data = parseYaml4(raw);
+    const data = parseYaml5(raw);
     return typeof data?.best === "string" ? data.best : void 0;
   } catch {
     return void 0;
@@ -1473,12 +1748,12 @@ function detectionToYaml(result, generatedAt) {
 }
 
 // src/workspace.ts
-import path5 from "path";
+import path7 from "path";
 
 // src/fixes.ts
-import path4 from "path";
+import path5 from "path";
 import { stringify as stringifyYaml3 } from "yaml";
-var LIVING_FIXES_DIR = path4.join(".sdd", "fixes");
+var LIVING_FIXES_DIR = path5.join(".sdd", "fixes");
 var COMMENT_RE = /<!--[\s\S]*?-->/g;
 function parseFixCovers(content) {
   const clean = content.replace(COMMENT_RE, "");
@@ -1505,7 +1780,7 @@ function coversOf(value) {
 function parseLivingFix(content, file) {
   const fm = parseFrontmatter(content, file);
   const data = fm.data;
-  const base = path4.basename(file).replace(/\.md$/i, "");
+  const base = path5.basename(file).replace(/\.md$/i, "");
   const slug = typeof data["slug"] === "string" && data["slug"].trim() !== "" ? data["slug"].trim() : base.replace(/^\d{4}-\d{2}-/, "");
   const fix = {
     slug,
@@ -1521,14 +1796,14 @@ function parseLivingFix(content, file) {
   return fix;
 }
 async function archivedFixes(root, known) {
-  const archiveDir = path4.join(root, ".sdd", "changes", "archive");
+  const archiveDir = path5.join(root, ".sdd", "changes", "archive");
   const fixes = [];
   for (const entry of await listDirs(archiveDir)) {
-    const dir = path4.join(archiveDir, entry);
-    const fixFile = path4.join(dir, "fix.md");
+    const dir = path5.join(archiveDir, entry);
+    const fixFile = path5.join(dir, "fix.md");
     const fixRaw = await readTextIfExists(fixFile);
     if (fixRaw === void 0) continue;
-    const metaFile = path4.join(dir, "meta.yaml");
+    const metaFile = path5.join(dir, "meta.yaml");
     const metaRaw = await readTextIfExists(metaFile);
     const meta = metaRaw !== void 0 ? parseChangeMeta(metaRaw, metaFile).meta : void 0;
     if (meta?.lane !== "fix") continue;
@@ -1551,11 +1826,11 @@ async function archivedFixes(root, known) {
   return fixes;
 }
 async function loadLivingFixes(root) {
-  const dir = path4.join(root, LIVING_FIXES_DIR);
+  const dir = path5.join(root, LIVING_FIXES_DIR);
   const entries = (await listDir(dir)).filter((entry) => entry.toLowerCase().endsWith(".md")).sort();
   const fixes = [];
   for (const entry of entries) {
-    const file = path4.join(dir, entry);
+    const file = path5.join(dir, entry);
     const content = await readTextIfExists(file);
     if (content === void 0) continue;
     fixes.push(parseLivingFix(content, file));
@@ -1564,10 +1839,10 @@ async function loadLivingFixes(root) {
   return fixes.sort((a, b) => b.date.localeCompare(a.date) || b.slug.localeCompare(a.slug));
 }
 async function writeLivingFix(root, input) {
-  const dir = path4.join(root, LIVING_FIXES_DIR);
+  const dir = path5.join(root, LIVING_FIXES_DIR);
   const month = input.date.slice(0, 7);
-  const file = path4.join(dir, `${month}-${input.slug}.md`);
-  const relativePath = toPosix(path4.relative(root, file));
+  const file = path5.join(dir, `${month}-${input.slug}.md`);
+  const relativePath = toPosix(path5.relative(root, file));
   if (await exists(file)) return { file, relativePath, created: false };
   const data = {
     slug: input.slug,
@@ -1587,35 +1862,170 @@ ${body}
   return { file, relativePath, created: true };
 }
 
+// src/links.ts
+import path6 from "path";
+import { parse as parseYaml6, stringify as stringifyYaml4 } from "yaml";
+var LINKS_FILE = "links.yaml";
+function parseLinksDocument(raw, file) {
+  let data;
+  try {
+    data = parseYaml6(raw);
+  } catch (error) {
+    return { diagnostics: [diag("ATLAS-LINK-001", "error", `links.yaml ilegible: ${error.message}`, { path: file })] };
+  }
+  const doc = data;
+  if (!doc || typeof doc !== "object" || !Array.isArray(doc.links)) {
+    return { diagnostics: [diag("ATLAS-LINK-001", "error", "links.yaml inv\xE1lido: falta la lista de enlaces", { path: file })] };
+  }
+  const links = [];
+  const diagnostics = [];
+  for (const item of doc.links) {
+    const entry = item;
+    if (typeof entry?.name !== "string" || typeof entry?.path !== "string" || entry.name.trim() === "" || entry.path.trim() === "") {
+      diagnostics.push(diag("ATLAS-LINK-001", "error", "Enlace inv\xE1lido en links.yaml: cada enlace necesita nombre y ruta", { path: file }));
+      continue;
+    }
+    links.push({ name: entry.name.trim(), path: entry.path.trim() });
+  }
+  return { document: { schema_version: typeof doc.schema_version === "number" ? doc.schema_version : 1, links }, diagnostics };
+}
+async function readLinks(root) {
+  const file = path6.join(root, ".sdd", LINKS_FILE);
+  const raw = await readTextIfExists(file);
+  if (raw === void 0) return { document: { schema_version: 1, links: [] }, file, diagnostics: [] };
+  const parsed = parseLinksDocument(raw, file);
+  return { document: parsed.document ?? { schema_version: 1, links: [] }, file, diagnostics: parsed.diagnostics };
+}
+async function writeLinks(root, document) {
+  const file = path6.join(root, ".sdd", LINKS_FILE);
+  const lines = ["# Enlaces a otros proyectos (specs compartidas en solo lectura). Generado por `satlas link`.", stringifyYaml4(document, { lineWidth: 120 }).trimEnd(), ""];
+  await writeText(file, lines.join("\n"));
+}
+function resolveLinkPath(root, linkPath) {
+  return path6.isAbsolute(linkPath) ? path6.normalize(linkPath) : path6.resolve(root, linkPath);
+}
+async function linkedSpecs(absPath) {
+  const specsDir = path6.join(absPath, ".sdd", "specs");
+  const specs = [];
+  for (const domain of await listDirs(specsDir)) {
+    const file = path6.join(specsDir, domain, "spec.md");
+    const content = await readTextIfExists(file);
+    if (content === void 0) continue;
+    specs.push({ domain, path: file, spec: parseSpecFile(content, file) });
+  }
+  return specs;
+}
+async function loadLinks(root) {
+  const { document, diagnostics } = await readLinks(root);
+  const entries = [];
+  const specs = [];
+  const unavailable = [];
+  for (const entry of document.links) {
+    const abs = resolveLinkPath(root, entry.path);
+    const sddDir = path6.join(abs, ".sdd");
+    const available = await isDirectory(sddDir) && await isDirectory(path6.join(sddDir, "specs"));
+    if (!available) {
+      unavailable.push(entry.name);
+      entries.push({ name: entry.name, path: abs, available: false, requirements: 0, domains: [], error: "el enlace no est\xE1 disponible" });
+      continue;
+    }
+    const linked = await linkedSpecs(abs);
+    specs.push(...linked);
+    entries.push({
+      name: entry.name,
+      path: abs,
+      available: true,
+      requirements: linked.reduce((total, spec) => total + spec.spec.requirements.length, 0),
+      domains: linked.map((spec) => spec.domain)
+    });
+  }
+  void diagnostics;
+  return { entries, specs, unavailable };
+}
+async function addLink(root, opts) {
+  const abs = resolveLinkPath(root, opts.path);
+  const sddDir = path6.join(abs, ".sdd");
+  if (!await isDirectory(sddDir)) {
+    return {
+      diagnostics: [
+        diag("ATLAS-LINK-002", "error", `El enlace no es un proyecto inicializado: ${abs}`, {
+          suggestion: "Indica la ruta de un proyecto con su estado inicializado (satlas init)"
+        })
+      ]
+    };
+  }
+  const { document } = await readLinks(root);
+  let name = opts.name?.trim();
+  if (!name) {
+    const linkedConfig = await loadConfig(sddDir);
+    name = linkedConfig.config.project.name || path6.basename(abs);
+  }
+  const entry = { name, path: toPosix(abs) };
+  const existing = document.links.findIndex((link) => link.name === name || resolveLinkPath(root, link.path) === abs);
+  if (existing >= 0) document.links[existing] = entry;
+  else document.links.push(entry);
+  await writeLinks(root, document);
+  return { entry, diagnostics: [] };
+}
+async function removeLink(root, ref) {
+  const { document } = await readLinks(root);
+  const index = document.links.findIndex((link) => link.name === ref || link.path === ref || resolveLinkPath(root, link.path) === resolveLinkPath(root, ref));
+  if (index < 0) {
+    return {
+      diagnostics: [diag("ATLAS-LINK-003", "warning", `No existe un enlace "${ref}"`, { suggestion: "Consulta los enlaces con `satlas link list`" })]
+    };
+  }
+  const [removed] = document.links.splice(index, 1);
+  await writeLinks(root, document);
+  return { removed: removed?.name, diagnostics: [] };
+}
+function linkedRequirementIds(state) {
+  if (!state) return [];
+  const ids = [];
+  for (const spec of state.specs) {
+    for (const requirement of spec.spec.requirements) ids.push(requirement.id);
+  }
+  return ids;
+}
+function linkedTraceInput(workspace) {
+  if (!workspace.links || workspace.links.entries.length === 0) return void 0;
+  return { ids: linkedRequirementIds(workspace.links), unavailable: workspace.links.unavailable };
+}
+async function ensureLinksFile(root) {
+  const file = path6.join(root, ".sdd", LINKS_FILE);
+  if (await exists(file)) return;
+  await writeLinks(root, { schema_version: 1, links: [] });
+}
+
 // src/workspace.ts
 var SDD_DIR = ".sdd";
 async function findWorkspaceRoot(start) {
-  let current = path5.resolve(start);
+  let current = path7.resolve(start);
   for (let i = 0; i < 40; i += 1) {
-    if (await isDirectory(path5.join(current, SDD_DIR))) return current;
-    const parent = path5.dirname(current);
+    if (await isDirectory(path7.join(current, SDD_DIR))) return current;
+    const parent = path7.dirname(current);
     if (parent === current) return void 0;
     current = parent;
   }
   return void 0;
 }
 async function loadApprovals(sddDir) {
-  const file = path5.join(sddDir, "approvals.yaml");
+  const file = path7.join(sddDir, "approvals.yaml");
   const raw = await readTextIfExists(file);
   if (raw === void 0) return { byArtifact: /* @__PURE__ */ new Map(), diagnostics: [] };
   const parsed = parseApprovals(raw, file);
   const map = /* @__PURE__ */ new Map();
   for (const a of parsed.approvals?.approvals ?? []) {
-    map.set(a.artifact.split(path5.sep).join("/"), { hash: a.artifactHash, by: a.approvedBy, at: a.approvedAt });
+    map.set(a.artifact.split(path7.sep).join("/"), { hash: a.artifactHash, by: a.approvedBy, at: a.approvedAt });
   }
   return { byArtifact: map, diagnostics: parsed.diagnostics };
 }
 async function loadSpecs(sddDir) {
-  const specsDir = path5.join(sddDir, "specs");
+  const specsDir = path7.join(sddDir, "specs");
   const domains = await listDirs(specsDir);
   const out = [];
   for (const domain of domains) {
-    const file = path5.join(specsDir, domain, "spec.md");
+    const file = path7.join(specsDir, domain, "spec.md");
     if (!await exists(file)) continue;
     const content = await readText(file);
     out.push({ domain, path: file, spec: parseSpecFile(content, file) });
@@ -1623,10 +2033,10 @@ async function loadSpecs(sddDir) {
   return out;
 }
 async function loadChange(root, slug, relDir) {
-  const dir = path5.join(root, SDD_DIR, "changes", relDir ?? slug);
+  const dir = path7.join(root, SDD_DIR, "changes", relDir ?? slug);
   const diagnostics = [];
   const change = { slug, dir, diagnostics };
-  const metaFile = path5.join(dir, "meta.yaml");
+  const metaFile = path7.join(dir, "meta.yaml");
   const metaRaw = await readTextIfExists(metaFile);
   if (metaRaw === void 0) {
     diagnostics.push(diag("ATLAS-FILES-001", "error", `El cambio "${slug}" no tiene meta.yaml`, { path: metaFile, suggestion: "Crea meta.yaml con slug, lane y dominio" }));
@@ -1635,7 +2045,7 @@ async function loadChange(root, slug, relDir) {
     diagnostics.push(...parsed.diagnostics);
     if (parsed.meta) change.meta = parsed.meta;
   }
-  const deltaFile = path5.join(dir, "spec.md");
+  const deltaFile = path7.join(dir, "spec.md");
   const deltaRaw = await readTextIfExists(deltaFile);
   if (deltaRaw !== void 0) {
     change.delta = parseDelta(deltaRaw, deltaFile);
@@ -1643,42 +2053,57 @@ async function loadChange(root, slug, relDir) {
   } else {
     diagnostics.push(diag("ATLAS-FILES-002", "warning", `El cambio "${slug}" no tiene spec.md (delta)`, { path: deltaFile }));
   }
-  const planFile = path5.join(dir, "plan.md");
+  const planFile = path7.join(dir, "plan.md");
   if (await exists(planFile)) change.planPath = planFile;
-  const reviewFile = path5.join(dir, "review.md");
+  const reviewFile = path7.join(dir, "review.md");
   if (await exists(reviewFile)) change.reviewPath = reviewFile;
-  const presentationFile = path5.join(dir, "presentation", "index.html");
+  const presentationFile = path7.join(dir, "presentation", "index.html");
   if (await exists(presentationFile)) change.presentationPath = presentationFile;
-  const tasksFile = path5.join(dir, "tasks.md");
+  const tasksFile = path7.join(dir, "tasks.md");
   const tasksRaw = await readTextIfExists(tasksFile);
   if (tasksRaw !== void 0) {
     change.tasks = parseTasksFile(tasksRaw, tasksFile);
     diagnostics.push(...change.tasks.diagnostics);
   }
-  const verifyFile = path5.join(dir, "verify.md");
+  const verifyFile = path7.join(dir, "verify.md");
   const verifyRaw = await readTextIfExists(verifyFile);
   if (verifyRaw !== void 0) {
     change.verify = parseVerifyFile(verifyRaw, verifyFile);
     diagnostics.push(...change.verify.diagnostics);
   }
-  const fixFile = path5.join(dir, "fix.md");
+  const fixFile = path7.join(dir, "fix.md");
   const fixRaw = await readTextIfExists(fixFile);
   if (fixRaw !== void 0) {
     change.fix = parseVerifyFile(fixRaw, fixFile);
     diagnostics.push(...change.fix.diagnostics);
     change.fixCovers = parseFixCovers(fixRaw);
   }
-  const mockupManifest = path5.join(dir, "mockups", "manifest.yaml");
+  const clarifyFile = path7.join(dir, "clarify.md");
+  const clarifyRaw = await readTextIfExists(clarifyFile);
+  if (clarifyRaw !== void 0) {
+    change.clarify = parseClarify(clarifyRaw, clarifyFile);
+    change.clarifyPath = clarifyFile;
+    diagnostics.push(...change.clarify.diagnostics);
+  }
+  const docsPaths = [];
+  for (const name of ["tecnica.md", "manual.md"]) {
+    const docFile = path7.join(dir, "docs", name);
+    if (await exists(docFile)) docsPaths.push(docFile);
+  }
+  if (docsPaths.length > 0) change.docsPaths = docsPaths;
+  const contracts = await loadContracts(dir);
+  if (contracts.files.length > 0) change.contracts = contracts;
+  const mockupManifest = path7.join(dir, "mockups", "manifest.yaml");
   if (await exists(mockupManifest)) change.mockupManifestPath = mockupManifest;
   return change;
 }
 async function listChangeSlugs(root, opts = {}) {
-  const changesDir = path5.join(root, SDD_DIR, "changes");
+  const changesDir = path7.join(root, SDD_DIR, "changes");
   const dirs = await listDirs(changesDir);
   return dirs.filter((d) => opts.includeArchived ? true : d !== "archive");
 }
 async function loadWorkspace(root) {
-  const sddDir = path5.join(root, SDD_DIR);
+  const sddDir = path7.join(root, SDD_DIR);
   const { config, diagnostics: configDiags } = await loadConfig(sddDir);
   const diagnostics = [...configDiags];
   const specs = await loadSpecs(sddDir);
@@ -1691,20 +2116,24 @@ async function loadWorkspace(root) {
     diagnostics.push(...change.diagnostics);
   }
   const archived = [];
-  const archivedDir = path5.join(sddDir, "changes", "archive");
+  const archivedDir = path7.join(sddDir, "changes", "archive");
   if (await isDirectory(archivedDir)) {
     for (const entry of await listDirs(archivedDir)) {
-      archived.push(await loadChange(root, entry.replace(/^\d{4}-\d{2}-/, ""), path5.join("archive", entry)));
+      archived.push(await loadChange(root, entry.replace(/^\d{4}-\d{2}-/, ""), path7.join("archive", entry)));
     }
   }
-  return { workspace: { root, sddDir, specs, changes, archived, diagnostics }, config };
+  const workspace = { root, sddDir, specs, changes, archived, diagnostics };
+  if (await exists(path7.join(sddDir, LINKS_FILE))) {
+    workspace.links = await loadLinks(root);
+  }
+  return { workspace, config };
 }
 async function ensureSddDirs(sddDir) {
   const created = [];
-  const dirs = ["specs", "changes", "runs", "metrics", "fixes", path5.join("profiles", "custom")];
+  const dirs = ["specs", "changes", "runs", "metrics", "fixes", path7.join("profiles", "custom")];
   const { ensureDir: ensureDir2 } = await import("./fsx-VF2P7ALA.js");
   for (const d of dirs) {
-    const full = path5.join(sddDir, d);
+    const full = path7.join(sddDir, d);
     if (!await exists(full)) {
       await ensureDir2(full);
       created.push(full);
@@ -1714,7 +2143,7 @@ async function ensureSddDirs(sddDir) {
 }
 
 // src/templates.ts
-import { stringify as stringifyYaml4 } from "yaml";
+import { stringify as stringifyYaml5 } from "yaml";
 var ES = {
   constitution: `# Constituci\xF3n del proyecto
 
@@ -1884,6 +2313,44 @@ satlas verify <slug> --file fix --scenario REQ-DOMINIO-001-S1 --command "<comand
 o, si es manual:
 satlas verify <slug> --file fix --scenario REQ-DOMINIO-001-S1 --method manual --result pass --by "<nombre>" --notes "<c\xF3mo se comprob\xF3>"
 -->
+`,
+  docTecnica: `# Documentaci\xF3n t\xE9cnica \u2014 {{TITLE}}
+
+## Resumen del cambio
+
+- **Cambio**: \`{{SLUG}}\` \xB7 dominio \`{{DOMAIN}}\` \xB7 carril \`{{LANE}}\`
+- **Actualizado**: {{DATE}}
+- **Tareas**: {{TASKS}}
+
+## Requisitos y escenarios
+
+{{REQUIREMENTS}}
+
+## Evidencia registrada
+
+{{EVIDENCE}}
+
+## Pendiente de evidencia
+
+{{PENDING}}
+`,
+  docManual: `# Manual \u2014 {{TITLE}}
+
+## Qu\xE9 hace este cambio
+
+{{TITLE}} \u2014 dominio \`{{DOMAIN}}\` (cambio \`{{SLUG}}\`, carril \`{{LANE}}\`).
+
+## C\xF3mo se usa
+
+{{SCENARIOS}}
+
+## C\xF3mo se comprob\xF3
+
+{{EVIDENCE}}
+
+## Pendiente de comprobar
+
+{{PENDING}}
 `
 };
 var EN = {
@@ -2009,6 +2476,44 @@ Cubre: REQ-DOMAIN-001
 <!-- Register real evidence with:
 satlas verify <slug> --file fix --scenario REQ-DOMAIN-001-S1 --command "<command>" --by "<name>"
 -->
+`,
+  docTecnica: `# Technical documentation \u2014 {{TITLE}}
+
+## Change summary
+
+- **Change**: \`{{SLUG}}\` \xB7 domain \`{{DOMAIN}}\` \xB7 lane \`{{LANE}}\`
+- **Updated**: {{DATE}}
+- **Tasks**: {{TASKS}}
+
+## Requirements and scenarios
+
+{{REQUIREMENTS}}
+
+## Recorded evidence
+
+{{EVIDENCE}}
+
+## Pending evidence
+
+{{PENDING}}
+`,
+  docManual: `# Manual \u2014 {{TITLE}}
+
+## What this change does
+
+{{TITLE}} \u2014 domain \`{{DOMAIN}}\` (change \`{{SLUG}}\`, lane \`{{LANE}}\`).
+
+## How to use it
+
+{{SCENARIOS}}
+
+## How it was verified
+
+{{EVIDENCE}}
+
+## Pending verification
+
+{{PENDING}}
 `
 };
 function templatesFor(language) {
@@ -2030,7 +2535,7 @@ function changeMetaYaml(meta) {
   if (meta.owner) doc["owner"] = meta.owner;
   if (meta.mockups) doc["mockups"] = meta.mockups;
   return `# Estado del cambio. La fase se DERIVA de los artefactos; aqu\xED solo hechos.
-` + stringifyYaml4(doc, { lineWidth: 120 });
+` + stringifyYaml5(doc, { lineWidth: 120 });
 }
 function indexMarkdown(input) {
   const es = input.language !== "en";
@@ -2068,8 +2573,8 @@ ${input.archived} change(s) in \`changes/archive/\`.`);
 }
 
 // src/github.ts
-import path6 from "path";
-import { parse as parseYaml5 } from "yaml";
+import path8 from "path";
+import { parse as parseYaml7 } from "yaml";
 
 // src/exec.ts
 import { execFile } from "child_process";
@@ -2213,8 +2718,8 @@ function issueBody(input) {
   lines.push(`- Siguiente: \`${input.next}\` \u2014 ${input.nextDescription}`);
   lines.push("");
   lines.push("### Artefactos");
-  lines.push(`- Spec: \`${path6.posix.join(".sdd", "changes", change.slug, "spec.md")}\``);
-  if (change.planPath) lines.push(`- Plan: \`${path6.posix.join(".sdd", "changes", change.slug, "plan.md")}\``);
+  lines.push(`- Spec: \`${path8.posix.join(".sdd", "changes", change.slug, "spec.md")}\``);
+  if (change.planPath) lines.push(`- Plan: \`${path8.posix.join(".sdd", "changes", change.slug, "plan.md")}\``);
   if (change.tasks) lines.push(`- Tareas: ${change.tasks.counts.done}/${change.tasks.counts.total}`);
   if (change.verify) lines.push(`- Evidencia registrada: ${change.verify.evidence.length}`);
   lines.push("");
@@ -2282,14 +2787,14 @@ async function commentIssue(root, number, body, runner = defaultRunner) {
   return result.ok ? [] : [diag("ATLAS-GH-006", "error", `No se pudo comentar el issue #${number}: ${(result.stderr || result.stdout).trim().slice(0, 300)}`)];
 }
 async function patchChangeMeta(root, slug, patch) {
-  const file = path6.join(path6.resolve(root), ".sdd", "changes", slug, "meta.yaml");
+  const file = path8.join(path8.resolve(root), ".sdd", "changes", slug, "meta.yaml");
   const raw = await readTextIfExists(file);
   if (raw === void 0) {
-    return { path: file, diagnostics: [diag("ATLAS-GH-007", "error", `No existe ${path6.relative(root, file)}`)] };
+    return { path: file, diagnostics: [diag("ATLAS-GH-007", "error", `No existe ${path8.relative(root, file)}`)] };
   }
   let data;
   try {
-    data = parseYaml5(raw) ?? {};
+    data = parseYaml7(raw) ?? {};
   } catch (err) {
     return { path: file, diagnostics: [diag("ATLAS-GH-007", "error", `meta.yaml inv\xE1lido: ${err.message}`)] };
   }
@@ -2339,7 +2844,7 @@ async function approveFromGithub(opts) {
   const { signApproval: signApproval2 } = await import("./approvals-2PO6223I.js");
   const signed = await signApproval2({
     root: opts.root,
-    artifact: path6.posix.join("changes", opts.slug, "spec.md"),
+    artifact: path8.posix.join("changes", opts.slug, "spec.md"),
     by,
     channel: "tracker",
     note: `Aprobado v\xEDa GitHub issue #${number} (etiqueta "${label}")`
@@ -2399,7 +2904,7 @@ async function syncGithubIssue(root, slug, opts = {}) {
 }
 
 // src/evidence.ts
-import path7 from "path";
+import path9 from "path";
 var SCENARIO_HEAD_RE2 = /^###\s+(REQ-[A-Z0-9-]+-S\d+)\b/;
 function locateBlocks(content) {
   const normalized = content.replace(/\r\n?/g, "\n");
@@ -2437,10 +2942,10 @@ function buildEvidenceYaml(evidence) {
   return lines.join("\n");
 }
 async function recordEvidence(opts) {
-  const root = path7.resolve(opts.root);
+  const root = path9.resolve(opts.root);
   const slug = opts.slug;
   const fileKind = opts.file ?? "verify";
-  const file = path7.join(root, ".sdd", "changes", slug, fileKind === "fix" ? "fix.md" : "verify.md");
+  const file = path9.join(root, ".sdd", "changes", slug, fileKind === "fix" ? "fix.md" : "verify.md");
   const diagnostics = [];
   const scenario = opts.scenario.toUpperCase();
   if (!SCENARIO_ID_RE.test(scenario)) {
@@ -2537,7 +3042,7 @@ function evidenceSummary(content) {
 }
 
 // src/runs.ts
-import path8 from "path";
+import path10 from "path";
 import { randomBytes } from "crypto";
 var RUN_EVENT_TYPES = [
   "run_started",
@@ -2563,7 +3068,7 @@ function generateRunId(now = /* @__PURE__ */ new Date()) {
   return `${iso.slice(0, 8)}-${iso.slice(8, 14)}-${randomBytes(3).toString("hex")}`;
 }
 function runsDir(root) {
-  return path8.join(path8.resolve(root), ".sdd", "runs");
+  return path10.join(path10.resolve(root), ".sdd", "runs");
 }
 async function createRun(root, slug, phase, inputs, now = /* @__PURE__ */ new Date()) {
   const runId = generateRunId(now);
@@ -2576,25 +3081,25 @@ async function createRun(root, slug, phase, inputs, now = /* @__PURE__ */ new Da
     updatedAt: localStamp(now)
   };
   if (inputs) state.inputs = inputs;
-  const dir = path8.join(runsDir(root), runId);
+  const dir = path10.join(runsDir(root), runId);
   await ensureDir(dir);
-  await writeText(path8.join(dir, "state.json"), `${JSON.stringify(state, null, 2)}
+  await writeText(path10.join(dir, "state.json"), `${JSON.stringify(state, null, 2)}
 `);
-  await writeText(path8.join(dir, "events.jsonl"), "");
+  await writeText(path10.join(dir, "events.jsonl"), "");
   await appendRunEvent(root, runId, "run_started", { slug, phase });
   return state;
 }
 async function appendRunEvent(root, runId, type, data, now = /* @__PURE__ */ new Date()) {
   const event = { eventId: randomBytes(4).toString("hex"), at: localStamp(now), type };
   if (data) event.data = data;
-  const file = path8.join(runsDir(root), runId, "events.jsonl");
+  const file = path10.join(runsDir(root), runId, "events.jsonl");
   const previous = await readTextIfExists(file) ?? "";
   await writeText(file, `${previous}${JSON.stringify(event)}
 `);
   return event;
 }
 async function updateRunStatus(root, runId, status, now = /* @__PURE__ */ new Date()) {
-  const file = path8.join(runsDir(root), runId, "state.json");
+  const file = path10.join(runsDir(root), runId, "state.json");
   const raw = await readTextIfExists(file);
   if (raw === void 0) return;
   const state = JSON.parse(raw);
@@ -2604,13 +3109,13 @@ async function updateRunStatus(root, runId, status, now = /* @__PURE__ */ new Da
 `);
 }
 async function readRun(root, runId) {
-  const dir = path8.join(runsDir(root), runId);
-  const stateRaw = await readTextIfExists(path8.join(dir, "state.json"));
+  const dir = path10.join(runsDir(root), runId);
+  const stateRaw = await readTextIfExists(path10.join(dir, "state.json"));
   if (stateRaw === void 0) {
     return { diagnostics: [diag("ATLAS-RUN-001", "error", `No existe el run ${runId}`, { path: dir })] };
   }
   const state = JSON.parse(stateRaw);
-  const eventsRaw = await readTextIfExists(path8.join(dir, "events.jsonl")) ?? "";
+  const eventsRaw = await readTextIfExists(path10.join(dir, "events.jsonl")) ?? "";
   const events = [];
   for (const line of eventsRaw.split("\n")) {
     if (line.trim() === "") continue;
@@ -2627,7 +3132,7 @@ async function listRuns(root, filter = {}) {
   const ids = await listDirs(dir);
   const out = [];
   for (const id of ids) {
-    const raw = await readTextIfExists(path8.join(dir, id, "state.json"));
+    const raw = await readTextIfExists(path10.join(dir, id, "state.json"));
     if (raw === void 0) continue;
     try {
       const state = JSON.parse(raw);
@@ -2641,11 +3146,11 @@ async function listRuns(root, filter = {}) {
 }
 
 // src/analyze.ts
-import path11 from "path";
+import path13 from "path";
 
 // src/mockups.ts
-import path9 from "path";
-import { parse as parseYaml6, stringify as stringifyYaml5 } from "yaml";
+import path11 from "path";
+import { parse as parseYaml8, stringify as stringifyYaml6 } from "yaml";
 import { z as z4 } from "zod";
 var mockupManifestSchema = z4.object({
   schema_version: z4.number().int().positive().default(1),
@@ -2670,20 +3175,20 @@ var mockupManifestSchema = z4.object({
 });
 var TOKEN_CANDIDATES = ["design/tokens.json", "DESIGN.md", "design/DESIGN.md", ".sdd/design/tokens.json"];
 function mockupsDir(root, slug) {
-  return path9.join(path9.resolve(root), ".sdd", "changes", slug, "mockups");
+  return path11.join(path11.resolve(root), ".sdd", "changes", slug, "mockups");
 }
 async function tokensFile(root) {
   for (const candidate of TOKEN_CANDIDATES) {
-    const abs = path9.join(root, candidate);
+    const abs = path11.join(root, candidate);
     if (await exists(abs)) return candidate;
   }
   return void 0;
 }
 async function computeInputsHash(root, change) {
-  const deltaPath = path9.join(change.dir, "spec.md");
+  const deltaPath = path11.join(change.dir, "spec.md");
   const delta = await readTextIfExists(deltaPath) ?? "";
   const tokens = await tokensFile(root);
-  const tokensContent = tokens ? await readTextIfExists(path9.join(root, tokens)) ?? "" : "";
+  const tokensContent = tokens ? await readTextIfExists(path11.join(root, tokens)) ?? "" : "";
   return artifactHash(`${delta}
 ---tokens---
 ${tokensContent}`);
@@ -2708,12 +3213,12 @@ function planMockups(change, platform = "web") {
   return { platform, screens };
 }
 async function readMockupManifest(root, slug) {
-  const file = path9.join(mockupsDir(root, slug), "manifest.yaml");
+  const file = path11.join(mockupsDir(root, slug), "manifest.yaml");
   const raw = await readTextIfExists(file);
   if (raw === void 0) return { diagnostics: [] };
   let data;
   try {
-    data = parseYaml6(raw);
+    data = parseYaml8(raw);
   } catch (err) {
     return { path: file, diagnostics: [diag("ATLAS-MKP-002", "error", `manifest.yaml inv\xE1lido: ${err.message}`, { path: file })] };
   }
@@ -2800,7 +3305,7 @@ async function checkMockups(root, slug, change) {
   const { manifest, path: manifestPath, diagnostics } = await readMockupManifest(root, slug);
   const findings = [...diagnostics];
   if (!manifest || !manifestPath) {
-    return { findings: [...findings, diag("LINT-MKP-004", "error", "No existe mockups/manifest.yaml", { path: path9.join(dir, "manifest.yaml") })], stale: false };
+    return { findings: [...findings, diag("LINT-MKP-004", "error", "No existe mockups/manifest.yaml", { path: path11.join(dir, "manifest.yaml") })], stale: false };
   }
   const known = /* @__PURE__ */ new Set();
   for (const req of [...change.delta?.added ?? [], ...change.delta?.modified ?? []]) {
@@ -2808,12 +3313,12 @@ async function checkMockups(root, slug, change) {
   }
   findings.push(...lintMockupManifest(manifest, known, manifestPath));
   for (const screen of manifest.screens) {
-    const html = await readTextIfExists(path9.join(dir, screen.file));
+    const html = await readTextIfExists(path11.join(dir, screen.file));
     if (html === void 0) {
-      findings.push(diag("ATLAS-MKP-004", "error", `Falta el archivo del mockup: ${screen.file}`, { path: path9.join(dir, screen.file) }));
+      findings.push(diag("ATLAS-MKP-004", "error", `Falta el archivo del mockup: ${screen.file}`, { path: path11.join(dir, screen.file) }));
       continue;
     }
-    findings.push(...lintMockupHtml(html, path9.join(dir, screen.file)));
+    findings.push(...lintMockupHtml(html, path11.join(dir, screen.file)));
   }
   const inputsHash = await computeInputsHash(root, change);
   const stale = manifest.inputsHash !== void 0 && manifest.inputsHash !== inputsHash;
@@ -2828,7 +3333,7 @@ async function checkMockups(root, slug, change) {
   return { findings, stale, manifest, manifestPath };
 }
 async function writeMockupPlan(root, slug, plan, now = /* @__PURE__ */ new Date()) {
-  const file = path9.join(mockupsDir(root, slug), "plan.yaml");
+  const file = path11.join(mockupsDir(root, slug), "plan.yaml");
   if (await exists(file)) return file;
   const doc = {
     schema_version: 1,
@@ -2836,11 +3341,11 @@ async function writeMockupPlan(root, slug, plan, now = /* @__PURE__ */ new Date(
     platform: plan.platform,
     screens: plan.screens.map((s) => ({ id: s.id, title: s.title, file: s.file, illustrates: s.illustrates, states: s.states, breakpoints: s.breakpoints }))
   };
-  await writeText(file, stringifyYaml5(doc, { lineWidth: 120 }));
+  await writeText(file, stringifyYaml6(doc, { lineWidth: 120 }));
   return file;
 }
 async function writeMockupManifest(root, slug, plan, inputsHash, now = /* @__PURE__ */ new Date()) {
-  const file = path9.join(mockupsDir(root, slug), "manifest.yaml");
+  const file = path11.join(mockupsDir(root, slug), "manifest.yaml");
   if (await exists(file)) return file;
   const doc = {
     schema_version: 1,
@@ -2852,16 +3357,16 @@ async function writeMockupManifest(root, slug, plan, inputsHash, now = /* @__PUR
     screens: plan.screens.map((s) => ({ id: s.id, title: s.title, file: s.file, illustrates: s.illustrates, states: s.states, breakpoints: s.breakpoints })),
     screenshots: []
   };
-  await writeText(file, stringifyYaml5(doc, { lineWidth: 120 }));
+  await writeText(file, stringifyYaml6(doc, { lineWidth: 120 }));
   return file;
 }
 async function updateMockupScreenshots(root, slug, screenshots) {
-  const file = path9.join(mockupsDir(root, slug), "manifest.yaml");
+  const file = path11.join(mockupsDir(root, slug), "manifest.yaml");
   const raw = await readTextIfExists(file);
   if (raw === void 0) return void 0;
-  const data = parseYaml6(raw) ?? {};
+  const data = parseYaml8(raw) ?? {};
   data["screenshots"] = screenshots;
-  await writeText(file, stringifyYaml5(data, { lineWidth: 120 }));
+  await writeText(file, stringifyYaml6(data, { lineWidth: 120 }));
   return file;
 }
 async function captureMockups(root, slug, manifest, now = /* @__PURE__ */ new Date()) {
@@ -2886,9 +3391,9 @@ async function captureMockups(root, slug, manifest, now = /* @__PURE__ */ new Da
       const page2 = await browser.newPage();
       for (const bp of screen.breakpoints && screen.breakpoints.length > 0 ? screen.breakpoints : [1440]) {
         await page2.setViewportSize({ width: bp, height: 900 });
-        await page2.goto(`file://${path9.join(dir, screen.file).split(path9.sep).join("/")}`);
-        const rel = path9.posix.join("screens", `${screen.id}-${bp}.png`);
-        await page2.screenshot({ path: path9.join(dir, rel) });
+        await page2.goto(`file://${path11.join(dir, screen.file).split(path11.sep).join("/")}`);
+        const rel = path11.posix.join("screens", `${screen.id}-${bp}.png`);
+        await page2.screenshot({ path: path11.join(dir, rel) });
         screenshots.push(rel);
       }
       await page2.close();
@@ -2904,7 +3409,7 @@ async function mockupsReady(root, slug, change) {
   return Boolean(check.manifest && check.manifest.screens.length > 0 && !check.stale);
 }
 async function setMockupRequirement(root, slug, value) {
-  const file = path9.join(root, ".sdd", "changes", slug, "meta.yaml");
+  const file = path11.join(root, ".sdd", "changes", slug, "meta.yaml");
   const raw = await readTextIfExists(file) ?? `schema_version: 1
 slug: ${slug}
 lane: standard
@@ -2923,8 +3428,8 @@ lane: standard
 }
 
 // src/packs.ts
-import path10 from "path";
-import { parse as parseYaml7 } from "yaml";
+import path12 from "path";
+import { parse as parseYaml9 } from "yaml";
 import { z as z5 } from "zod";
 var checkSchema = z5.object({
   id: z5.string().min(1),
@@ -3139,17 +3644,17 @@ ${texts.scenarios}`);
   }
 }
 async function loadProjectPacks(sddDir) {
-  const dir = path10.join(sddDir, "packs");
+  const dir = path12.join(sddDir, "packs");
   const diagnostics = [];
   const packs = [];
   for (const entry of await listDir(dir)) {
     if (!/\.ya?ml$/i.test(entry)) continue;
-    const file = path10.join(dir, entry);
+    const file = path12.join(dir, entry);
     const raw = await readTextIfExists(file);
     if (raw === void 0) continue;
     let data;
     try {
-      data = parseYaml7(raw);
+      data = parseYaml9(raw);
     } catch (err) {
       diagnostics.push(diag("PACK-000", "error", `Pack inv\xE1lido (${entry}): ${err.message}`, { path: file }));
       continue;
@@ -3233,7 +3738,7 @@ function packFindings(evaluations, change) {
 // src/analyze.ts
 var UI_DOMAINS = /* @__PURE__ */ new Set(["frontend", "mobile", "fullstack"]);
 async function runAnalyze(opts) {
-  const root = path11.resolve(opts.root);
+  const root = path13.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const change = workspace.changes.find((c) => c.slug === opts.slug);
   if (!change) {
@@ -3251,9 +3756,9 @@ async function runAnalyze(opts) {
     for (const req of spec.spec.requirements) living.set(req.id, req);
   }
   if (change.delta) {
-    findings.push(...lintDelta(change.delta, living, path11.join(change.dir, "spec.md"), { language: config.spec.language }));
+    findings.push(...lintDelta(change.delta, living, path13.join(change.dir, "spec.md"), { language: config.spec.language }));
   }
-  const trace = checkTrace({ specs: workspace.specs, change, requireEvidence: false });
+  const trace = checkTrace({ specs: workspace.specs, change, requireEvidence: false, linked: linkedTraceInput(workspace) });
   findings.push(...trace.findings);
   let waves;
   if (change.tasks && change.tasks.counts.total > 0) {
@@ -3300,7 +3805,7 @@ async function runAnalyze(opts) {
   if (mockups) result.mockups = mockups;
   if (packs) result.packs = packs;
   if (opts.write !== false) {
-    const file = path11.join(change.dir, "analyze.md");
+    const file = path13.join(change.dir, "analyze.md");
     await writeText(file, renderAnalyze(change, result, localStamp(opts.now)));
     result.path = file;
   }
@@ -3343,9 +3848,9 @@ function renderAnalyze(change, result, generatedAt) {
 }
 
 // src/metrics.ts
-import path12 from "path";
+import path14 from "path";
 async function collectMetrics(root, now = /* @__PURE__ */ new Date()) {
-  const resolved = path12.resolve(root);
+  const resolved = path14.resolve(root);
   const { workspace, config } = await loadWorkspace(resolved);
   const approvals = await loadApprovals(workspace.sddDir);
   const living = /* @__PURE__ */ new Map();
@@ -3360,11 +3865,12 @@ async function collectMetrics(root, now = /* @__PURE__ */ new Date()) {
     const deltaContent = await readDelta(change);
     const approval = verifyApproval(change, approvals.byArtifact, config, deltaContent);
     const findings = [];
-    if (change.delta) findings.push(...lintDelta(change.delta, living, path12.join(change.dir, "spec.md"), { language: config.spec.language }));
+    if (change.delta) findings.push(...lintDelta(change.delta, living, path14.join(change.dir, "spec.md"), { language: config.spec.language }));
     const trace = checkTrace({
       specs: workspace.specs,
       change,
-      requireEvidence: config.gates.verify.mode !== "off" && config.gates.verify.require_evidence
+      requireEvidence: config.gates.verify.mode !== "off" && config.gates.verify.require_evidence,
+      linked: linkedTraceInput(workspace)
     });
     findings.push(...trace.findings);
     const state = deriveState({ change, cfg: config, approval, blockingFindings: change.delta ? countBySeverity(findings).errors : 0 });
@@ -3425,7 +3931,7 @@ async function collectMetrics(root, now = /* @__PURE__ */ new Date()) {
       attention.push({ slug: change.slug, kind: "missing-evidence", detail: `evidencia ${change.scenariosPassed}/${change.scenariosTotal}` });
     }
   }
-  const archiveDir = path12.join(workspace.sddDir, "changes", "archive");
+  const archiveDir = path14.join(workspace.sddDir, "changes", "archive");
   const archivedEntries = await listDirs(archiveDir);
   const throughputByMonth = {};
   for (const entry of archivedEntries) {
@@ -3463,15 +3969,15 @@ async function collectMetrics(root, now = /* @__PURE__ */ new Date()) {
 }
 async function readDelta(change) {
   const { readTextIfExists: readTextIfExists2 } = await import("./fsx-VF2P7ALA.js");
-  return readTextIfExists2(path12.join(change.dir, "spec.md"));
+  return readTextIfExists2(path14.join(change.dir, "spec.md"));
 }
 
 // src/present.ts
-import path13 from "path";
+import path15 from "path";
 import { escapeHtml, inlineMarkdown, renderMarkdown as renderRich } from "@specatlas/render";
 import { defaultTokens, renderDocument, renderStyles } from "@specatlas/render";
 async function generatePresentation(opts) {
-  const root = path13.resolve(opts.root);
+  const root = path15.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const language = config.project.language;
   const change = workspace.changes.find((c) => c.slug === opts.slug);
@@ -3481,17 +3987,17 @@ async function generatePresentation(opts) {
   if (!change.delta) {
     return { slug: opts.slug, diagnostics: [diag("ATLAS-PRESENT-001", "error", `El cambio "${opts.slug}" no tiene spec.md (delta)`)] };
   }
-  const deltaPath = path13.join(change.dir, "spec.md");
+  const deltaPath = path15.join(change.dir, "spec.md");
   const deltaContent = await readTextIfExists(deltaPath) ?? "";
   const hash = artifactHash(deltaContent);
   const now = opts.now ?? /* @__PURE__ */ new Date();
-  const presentationDir = path13.join(change.dir, "presentation");
-  const mockupsCopyDir = path13.join(presentationDir, "mockups");
+  const presentationDir = path15.join(change.dir, "presentation");
+  const mockupsCopyDir = path15.join(presentationDir, "mockups");
   await ensureDir(presentationDir);
   const mockupInfo = await copyMockups(root, change, mockupsCopyDir);
-  const proposalRaw = await readTextIfExists(path13.join(change.dir, "proposal.md"));
+  const proposalRaw = await readTextIfExists(path15.join(change.dir, "proposal.md"));
   const proposalBody = proposalRaw ? parseFrontmatter(proposalRaw).body : "";
-  const approvals = await loadApprovals(path13.join(root, ".sdd"));
+  const approvals = await loadApprovals(path15.join(root, ".sdd"));
   const approval = verifyApproval(change, approvals.byArtifact, config, deltaContent);
   const labels = labelsFor(language);
   const html = page({
@@ -3512,7 +4018,7 @@ async function generatePresentation(opts) {
     approveHint: `satlas approve ${change.slug} --by "<nombre>" --channel presentation`,
     ...approval.status === "valid" && approval.approvedBy ? { approval: { by: approval.approvedBy, at: approval.approvedAt ?? "" } } : {}
   });
-  const outFile = path13.join(presentationDir, "index.html");
+  const outFile = path15.join(presentationDir, "index.html");
   await writeText(outFile, html);
   return { slug: change.slug, path: outFile, hash, diagnostics: mockupInfo.diagnostics };
 }
@@ -3524,12 +4030,12 @@ async function copyMockups(root, change, destDir) {
   await ensureDir(destDir);
   const screens = [];
   for (const screen of manifest.screens) {
-    const src = path13.join(dir, screen.file);
+    const src = path15.join(dir, screen.file);
     if (!await exists(src)) {
       diagnostics.push(diag("ATLAS-PRESENT-002", "warning", `El mockup ${screen.file} no existe y no se incluir\xE1`, { path: src }));
       continue;
     }
-    await copyFile(src, path13.join(destDir, screen.file));
+    await copyFile(src, path15.join(destDir, screen.file));
     screens.push({
       id: screen.id,
       title: screen.title ?? screen.id,
@@ -3539,13 +4045,13 @@ async function copyMockups(root, change, destDir) {
     });
   }
   const screenshots = [];
-  const shotsDir = path13.join(dir, "screens");
+  const shotsDir = path15.join(dir, "screens");
   if (await exists(shotsDir)) {
-    await ensureDir(path13.join(destDir, "screens"));
+    await ensureDir(path15.join(destDir, "screens"));
     const { listDir: listDir4 } = await import("./fsx-VF2P7ALA.js");
     for (const file of await listDir4(shotsDir)) {
       if (!/\.(png|jpe?g|webp)$/i.test(file)) continue;
-      await copyFile(path13.join(shotsDir, file), path13.join(destDir, "screens", file));
+      await copyFile(path15.join(shotsDir, file), path15.join(destDir, "screens", file));
       screenshots.push(`mockups/screens/${file}`);
     }
   }
@@ -3720,7 +4226,7 @@ function renderMarkdown(markdown) {
 }
 
 // src/adopt.ts
-import path14 from "path";
+import path16 from "path";
 var COMMON_ROOTS = ["src", "app", "lib", "modules", "services", "packages", "api", "features", "domain", "internal", "components"];
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", "coverage", ".git", ".sdd", ".opencode", ".claude", "test", "tests", "__tests__", "e2e", "docs", "scripts", "assets", "public", "migrations", "vendor", "bin", "obj"]);
 var SOURCE_EXT = /* @__PURE__ */ new Set([
@@ -3764,11 +4270,11 @@ var SOURCE_EXT = /* @__PURE__ */ new Set([
   ".groovy"
 ]);
 async function adoptWorkspace(opts) {
-  const root = path14.resolve(opts.root);
+  const root = path16.resolve(opts.root);
   const dryRun = opts.dryRun ?? false;
   const diagnostics = [];
-  const sddDir = path14.join(root, ".sdd");
-  if (!await exists(path14.join(sddDir, "config.yaml"))) {
+  const sddDir = path16.join(root, ".sdd");
+  if (!await exists(path16.join(sddDir, "config.yaml"))) {
     return {
       root,
       domains: [],
@@ -3779,8 +4285,8 @@ async function adoptWorkspace(opts) {
   }
   const { config } = await loadConfig(sddDir);
   const files = await walkFiles(root, { skipDirs: [...SKIP_DIRS] });
-  const inventoried = files.map((f) => toPosix(path14.relative(root, f.path)));
-  const relative = inventoried.filter((f) => SOURCE_EXT.has(path14.extname(f).toLowerCase()));
+  const inventoried = files.map((f) => toPosix(path16.relative(root, f.path)));
+  const relative = inventoried.filter((f) => SOURCE_EXT.has(path16.extname(f).toLowerCase()));
   if (relative.length === 0) {
     diagnostics.push(diag("ATLAS-ADOPT-002", "warning", "No se encontraron archivos de c\xF3digo para inventariar", { path: root, suggestion: "A\xF1ade el dominio a mano con --domains <nombre>" }));
   }
@@ -3808,13 +4314,13 @@ async function adoptWorkspace(opts) {
   const createdSpecs = [];
   for (const name of domainNames.sort()) {
     const domainFiles = (counts.get(name) ?? []).sort();
-    const existingSpec = await exists(path14.join(sddDir, "specs", name, "spec.md"));
+    const existingSpec = await exists(path16.join(sddDir, "specs", name, "spec.md"));
     domains.push({ name, files: domainFiles.length, samples: domainFiles.slice(0, 8), existingSpec });
     if (existingSpec) {
-      diagnostics.push(diag("ATLAS-ADOPT-003", "info", `La spec de "${name}" ya existe; se conserva`, { path: path14.join(sddDir, "specs", name, "spec.md") }));
+      diagnostics.push(diag("ATLAS-ADOPT-003", "info", `La spec de "${name}" ya existe; se conserva`, { path: path16.join(sddDir, "specs", name, "spec.md") }));
       continue;
     }
-    const specPath = path14.join(sddDir, "specs", name, "spec.md");
+    const specPath = path16.join(sddDir, "specs", name, "spec.md");
     if (!dryRun) {
       await writeText(specPath, baselineSpec(name, domainFiles));
       createdSpecs.push(specPath);
@@ -3822,7 +4328,7 @@ async function adoptWorkspace(opts) {
       createdSpecs.push(specPath);
     }
   }
-  const reportPath = path14.join(sddDir, "adopt-report.md");
+  const reportPath = path16.join(sddDir, "adopt-report.md");
   if (!dryRun) {
     await writeText(reportPath, adoptReport({ root, config, domains, detection: detection?.best, language: config.project.language, files: relative.length, inventoried: inventoried.length, now: opts.now ?? /* @__PURE__ */ new Date() }));
   }
@@ -3842,12 +4348,12 @@ async function loadProjectProfiles(root, dirs) {
     if (!await exists(dir)) continue;
     out.push(...await loadProfilesFromDir(dir));
   }
-  const custom = path14.join(root, ".sdd", "profiles", "custom");
+  const custom = path16.join(root, ".sdd", "profiles", "custom");
   if (await exists(custom)) out.push(...await loadProfilesFromDir(custom));
   return out;
 }
 async function fallbackDomainName(root, projectName) {
-  const pkg = await readTextIfExists(path14.join(root, "package.json"));
+  const pkg = await readTextIfExists(path16.join(root, "package.json"));
   if (pkg) {
     try {
       const data = JSON.parse(pkg);
@@ -3935,13 +4441,13 @@ function adoptReport(input) {
 }
 
 // src/init.ts
-import path15 from "path";
+import path17 from "path";
 async function initWorkspace(opts) {
-  const root = path15.resolve(opts.root);
-  const sddDir = path15.join(root, ".sdd");
+  const root = path17.resolve(opts.root);
+  const sddDir = path17.join(root, ".sdd");
   const diagnostics = [];
   const created = [];
-  if (await exists(path15.join(sddDir, "config.yaml"))) {
+  if (await exists(path17.join(sddDir, "config.yaml"))) {
     return {
       sddDir,
       created,
@@ -3951,29 +4457,29 @@ async function initWorkspace(opts) {
   created.push(...await ensureSddDirs(sddDir));
   const language = opts.language ?? "es";
   const cfg = defaultConfig({ name: opts.name, language });
-  cfg.project.name = opts.name ?? path15.basename(root);
+  cfg.project.name = opts.name ?? path17.basename(root);
   await writeConfig(sddDir, cfg);
-  created.push(path15.join(sddDir, "config.yaml"));
+  created.push(path17.join(sddDir, "config.yaml"));
   const templates = templatesFor(language);
-  await writeText(path15.join(sddDir, "constitution.md"), templates.constitution);
-  created.push(path15.join(sddDir, "constitution.md"));
-  await writeText(path15.join(sddDir, "glossary.md"), templates.glossary);
-  created.push(path15.join(sddDir, "glossary.md"));
+  await writeText(path17.join(sddDir, "constitution.md"), templates.constitution);
+  created.push(path17.join(sddDir, "constitution.md"));
+  await writeText(path17.join(sddDir, "glossary.md"), templates.glossary);
+  created.push(path17.join(sddDir, "glossary.md"));
   const detected = await detectIfPossible(root, opts.profilesDir);
   if (detected) {
     const yaml = detectionToYaml(detected, localStamp(opts.now));
-    await writeText(path15.join(sddDir, "profiles", "detected.yaml"), yaml);
-    created.push(path15.join(sddDir, "profiles", "detected.yaml"));
+    await writeText(path17.join(sddDir, "profiles", "detected.yaml"), yaml);
+    created.push(path17.join(sddDir, "profiles", "detected.yaml"));
     if (detected.best) {
       diagnostics.push(diag("ATLAS-INIT-002", "info", `Stack detectado: ${detected.best.displayName} (${detected.best.score} puntos)`, { suggestion: "Revisa .sdd/profiles/detected.yaml" }));
     } else {
       diagnostics.push(diag("ATLAS-INIT-003", "info", "No se detect\xF3 un stack conocido: se usar\xE1 el perfil gen\xE9rico", { suggestion: "Crea un perfil propio con `satlas profile` (F2) o edita .sdd/profiles/custom/" }));
     }
   }
-  await writeText(path15.join(sddDir, "INDEX.md"), initialIndex(language, cfg.project.name));
-  created.push(path15.join(sddDir, "INDEX.md"));
+  await writeText(path17.join(sddDir, "INDEX.md"), initialIndex(language, cfg.project.name));
+  created.push(path17.join(sddDir, "INDEX.md"));
   if (opts.local) {
-    const gitignore = path15.join(root, ".gitignore");
+    const gitignore = path17.join(root, ".gitignore");
     const current = await readTextIfExists(gitignore) ?? "";
     if (!/(^|\n)\.sdd\/?(\n|$)/.test(current)) {
       const next = current.endsWith("\n") || current === "" ? `${current}.sdd/
@@ -4008,13 +4514,13 @@ ${es ? "## Archivados\n\n0 cambio(s) en `changes/archive/`." : "## Archived\n\n0
 }
 
 // src/new.ts
-import path16 from "path";
+import path18 from "path";
 var SLUG_RE = /^[a-z0-9][a-z0-9-]{1,49}$/;
 async function createChange(opts) {
   const diagnostics = [];
   const slug = opts.slug.trim().toLowerCase();
   const language = opts.language ?? opts.cfg?.project.language ?? "es";
-  const dir = path16.join(path16.resolve(opts.root), ".sdd", "changes", slug);
+  const dir = path18.join(path18.resolve(opts.root), ".sdd", "changes", slug);
   if (!SLUG_RE.test(slug)) {
     return {
       slug,
@@ -4045,20 +4551,20 @@ async function createChange(opts) {
   await ensureDir(dir);
   const templates = templatesFor(language);
   const files = [];
-  const metaFile = path16.join(dir, "meta.yaml");
+  const metaFile = path18.join(dir, "meta.yaml");
   await writeText(metaFile, changeMetaYaml(meta));
   files.push(metaFile);
   if (lane === "fix") {
-    const fixFile = path16.join(dir, "fix.md");
+    const fixFile = path18.join(dir, "fix.md");
     await writeText(fixFile, renderTemplate(templates.fix, { TITLE: title }));
     files.push(fixFile);
     return { slug, dir, files, diagnostics };
   }
-  const proposalFile = path16.join(dir, "proposal.md");
+  const proposalFile = path18.join(dir, "proposal.md");
   await writeText(proposalFile, renderTemplate(templates.proposal, { TITLE: title }));
   files.push(proposalFile);
   const domainUpper = domain.replace(/[^a-z0-9]/gi, "").toUpperCase() || "GEN";
-  const deltaFile = path16.join(dir, "spec.md");
+  const deltaFile = path18.join(dir, "spec.md");
   await writeText(deltaFile, templates.specDelta({ title, domainUpper, domain }));
   files.push(deltaFile);
   return { slug, dir, files, diagnostics };
@@ -4067,7 +4573,7 @@ async function createChange(opts) {
 // src/archive.ts
 import { promises as fs } from "fs";
 import { cp, rename, rm } from "fs/promises";
-import path17 from "path";
+import path19 from "path";
 var REQ_HEADER_RE = /^###\s+(?:Requisito|Requirement):\s+(REQ-[A-Z0-9-]+)\s*(?:—|-|–)\s*(.*)$/;
 function foldDelta(livingBody, delta, language = "es") {
   const diagnostics = [];
@@ -4176,7 +4682,7 @@ async function restoreFile(file, previous) {
   }
 }
 async function archiveChange(opts) {
-  const root = path17.resolve(opts.root);
+  const root = path19.resolve(opts.root);
   const diagnostics = [];
   const { config } = await loadWorkspace(root);
   const language = opts.language ?? config.project.language;
@@ -4192,7 +4698,7 @@ async function archiveChange(opts) {
       return { slug: opts.slug, fold: emptyFold, diagnostics, dryRun: opts.dryRun ?? false };
     }
     const nowFix = opts.now ?? /* @__PURE__ */ new Date();
-    const targetFix = path17.join(root, ".sdd", "changes", "archive", `${localMonth(nowFix)}-${opts.slug}`);
+    const targetFix = path19.join(root, ".sdd", "changes", "archive", `${localMonth(nowFix)}-${opts.slug}`);
     if (await exists(targetFix)) {
       diagnostics.push(diag("ATLAS-ARCH-002", "error", `Ya existe un cambio archivado en ${targetFix}`, { path: targetFix }));
       return { slug: opts.slug, fold: emptyFold, diagnostics, dryRun: opts.dryRun ?? false };
@@ -4200,7 +4706,7 @@ async function archiveChange(opts) {
     let livingFix;
     let livingCreated = false;
     if (!opts.dryRun) {
-      const fixRaw = await readTextIfExists(path17.join(change.dir, "fix.md")) ?? "";
+      const fixRaw = await readTextIfExists(path19.join(change.dir, "fix.md")) ?? "";
       try {
         const written = await writeLivingFix(root, {
           slug: opts.slug,
@@ -4216,7 +4722,7 @@ async function archiveChange(opts) {
       } catch (error) {
         diagnostics.push(
           diag("ATLAS-ARCH-006", "error", `No se pudo conservar el fix vivo: ${error.message}`, {
-            path: path17.join(root, ".sdd", "fixes"),
+            path: path19.join(root, ".sdd", "fixes"),
             suggestion: "Revisa los permisos de .sdd/fixes y vuelve a intentar; el fix sigue sin archivar"
           })
         );
@@ -4224,11 +4730,11 @@ async function archiveChange(opts) {
       }
     }
     if (!opts.dryRun) {
-      await ensureDir(path17.dirname(targetFix));
+      await ensureDir(path19.dirname(targetFix));
       try {
         await moveDirectory(change.dir, targetFix);
       } catch (error) {
-        if (livingCreated && livingFix) await removeFile(path17.join(root, livingFix));
+        if (livingCreated && livingFix) await removeFile(path19.join(root, livingFix));
         diagnostics.push(
           diag("ATLAS-ARCH-004", "error", `No se pudo mover el cambio al hist\xF3rico: ${error.message}`, {
             path: change.dir,
@@ -4254,10 +4760,10 @@ async function archiveChange(opts) {
   }
   const domain = change.meta.domain;
   if (!domain) {
-    diagnostics.push(diag("ATLAS-ARCH-001", "error", `El cambio "${opts.slug}" no declara domain en meta.yaml`, { path: path17.join(change.dir, "meta.yaml") }));
+    diagnostics.push(diag("ATLAS-ARCH-001", "error", `El cambio "${opts.slug}" no declara domain en meta.yaml`, { path: path19.join(change.dir, "meta.yaml") }));
     return { slug: opts.slug, fold: { content: "", applied: { added: [], modified: [], removed: [], renamed: [] }, diagnostics }, diagnostics, dryRun: opts.dryRun ?? false };
   }
-  const specFile = path17.join(root, ".sdd", "specs", domain, "spec.md");
+  const specFile = path19.join(root, ".sdd", "specs", domain, "spec.md");
   const existing = await readTextIfExists(specFile);
   const base = existing ?? `---
 domain: ${domain}
@@ -4287,8 +4793,8 @@ ${Object.entries(nextFm).map(([k, v]) => `${k}: ${String(v)}`).join("\n")}
 
 ${body}`;
   const month = localMonth(now);
-  const archiveDir = path17.join(root, ".sdd", "changes", "archive");
-  const target = path17.join(archiveDir, `${month}-${opts.slug}`);
+  const archiveDir = path19.join(root, ".sdd", "changes", "archive");
+  const target = path19.join(archiveDir, `${month}-${opts.slug}`);
   if (await exists(target)) {
     diagnostics.push(diag("ATLAS-ARCH-002", "error", `Ya existe un cambio archivado en ${target}`, { path: target }));
     return { slug: opts.slug, domain, fold, diagnostics, dryRun: opts.dryRun ?? false };
@@ -4314,7 +4820,7 @@ ${body}`;
 }
 async function regenerateIndex(root, cfg, now = /* @__PURE__ */ new Date()) {
   const { workspace, config } = cfg ? { workspace: (await loadWorkspace(root)).workspace, config: cfg } : await loadWorkspace(root);
-  const archiveDir = path17.join(root, ".sdd", "changes", "archive");
+  const archiveDir = path19.join(root, ".sdd", "changes", "archive");
   const archived = await exists(archiveDir) ? (await fs.readdir(archiveDir)).filter((e) => !e.startsWith(".")).length : 0;
   const fixes = await loadLivingFixes(root);
   const markdown = indexMarkdown({
@@ -4326,7 +4832,7 @@ async function regenerateIndex(root, cfg, now = /* @__PURE__ */ new Date()) {
     archived
   });
   void now;
-  await writeText(path17.join(root, ".sdd", "INDEX.md"), markdown);
+  await writeText(path19.join(root, ".sdd", "INDEX.md"), markdown);
 }
 async function removeFile(file) {
   try {
@@ -4337,8 +4843,8 @@ async function removeFile(file) {
 
 // src/migrations.ts
 import { promises as fs2 } from "fs";
-import path18 from "path";
-import { parse as parseYaml8, stringify as stringifyYaml6 } from "yaml";
+import path20 from "path";
+import { parse as parseYaml10, stringify as stringifyYaml7 } from "yaml";
 var SCHEMA_VERSION = 1;
 var BACKUP_DIRNAME = ".backup";
 var BACKUP_POINTER = ".latest";
@@ -4350,35 +4856,35 @@ var SCHEMA_MIGRATIONS = [
     to: SCHEMA_VERSION
   }
 ];
-var FIXED_ARTIFACTS = ["config.yaml", "approvals.yaml", path18.join("profiles", "detected.yaml")];
-var CHANGE_ARTIFACTS = ["meta.yaml", path18.join("mockups", "manifest.yaml")];
+var FIXED_ARTIFACTS = ["config.yaml", "approvals.yaml", path20.join("profiles", "detected.yaml")];
+var CHANGE_ARTIFACTS = ["meta.yaml", path20.join("mockups", "manifest.yaml")];
 async function pushChangeArtifacts(out, sddDir, relDir) {
   for (const rel of CHANGE_ARTIFACTS) {
-    const abs = path18.join(sddDir, relDir, rel);
-    if (await exists(abs)) out.push({ artifact: toPosix(path18.join(relDir, rel)), path: abs });
+    const abs = path20.join(sddDir, relDir, rel);
+    if (await exists(abs)) out.push({ artifact: toPosix(path20.join(relDir, rel)), path: abs });
   }
 }
 async function collectVersionedArtifacts(root) {
-  const sddDir = path18.join(root, ".sdd");
+  const sddDir = path20.join(root, ".sdd");
   const out = [];
   for (const rel of FIXED_ARTIFACTS) {
-    const abs = path18.join(sddDir, rel);
+    const abs = path20.join(sddDir, rel);
     if (await exists(abs)) out.push({ artifact: toPosix(rel), path: abs });
   }
-  const changesDir = path18.join(sddDir, "changes");
+  const changesDir = path20.join(sddDir, "changes");
   for (const slug of await listDirs(changesDir)) {
     if (slug === "archive") continue;
-    await pushChangeArtifacts(out, sddDir, path18.join("changes", slug));
+    await pushChangeArtifacts(out, sddDir, path20.join("changes", slug));
   }
-  for (const entry of await listDirs(path18.join(changesDir, "archive"))) {
-    await pushChangeArtifacts(out, sddDir, path18.join("changes", "archive", entry));
+  for (const entry of await listDirs(path20.join(changesDir, "archive"))) {
+    await pushChangeArtifacts(out, sddDir, path20.join("changes", "archive", entry));
   }
   return out;
 }
 function readArtifactVersion(content) {
   let data;
   try {
-    data = parseYaml8(content);
+    data = parseYaml10(content);
   } catch (err) {
     return { state: "unreadable", reason: `YAML inv\xE1lido (${err.message})` };
   }
@@ -4468,22 +4974,22 @@ function backupName(now) {
 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 = path18.join(root, ".sdd");
-  const backupRoot = path18.join(sddDir, BACKUP_DIRNAME);
+  const sddDir = path20.join(root, ".sdd");
+  const backupRoot = path20.join(sddDir, BACKUP_DIRNAME);
   const name = backupName(now);
-  const backupDir = path18.join(backupRoot, name);
-  const pointerFile = path18.join(backupRoot, BACKUP_POINTER);
+  const backupDir = path20.join(backupRoot, name);
+  const pointerFile = path20.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(path18.join(backupDir, "files", ...item.artifact.split("/")), content);
+      await writeText(path20.join(backupDir, "files", ...item.artifact.split("/")), content);
     }
     await writeText(
-      path18.join(backupDir, "backup.yaml"),
-      stringifyYaml6(
+      path20.join(backupDir, "backup.yaml"),
+      stringifyYaml7(
         {
           schema_version: SCHEMA_VERSION,
           created_at: localStamp(now),
@@ -4523,7 +5029,7 @@ async function applyUpgrade(root, now = /* @__PURE__ */ new Date()) {
     }
   }
   for (const dir of await listDirs(backupRoot)) {
-    if (dir !== name) await removeDir(path18.join(backupRoot, dir));
+    if (dir !== name) await removeDir(path20.join(backupRoot, dir));
   }
   return {
     status: "applied",
@@ -4532,32 +5038,32 @@ async function applyUpgrade(root, now = /* @__PURE__ */ new Date()) {
     backup: {
       name,
       dir: backupDir,
-      relativeDir: toPosix(path18.relative(root, backupDir)),
+      relativeDir: toPosix(path20.relative(root, backupDir)),
       createdAt: localStamp(now),
       files: plan.pending.map((i) => i.artifact)
     }
   };
 }
 async function rollbackUpgrade(root) {
-  const sddDir = path18.join(root, ".sdd");
-  const backupRoot = path18.join(sddDir, BACKUP_DIRNAME);
-  const pointerFile = path18.join(backupRoot, BACKUP_POINTER);
+  const sddDir = path20.join(root, ".sdd");
+  const backupRoot = path20.join(sddDir, BACKUP_DIRNAME);
+  const pointerFile = path20.join(backupRoot, BACKUP_POINTER);
   const name = (await readTextIfExists(pointerFile))?.trim();
   if (!name) return { status: "no-backup", restored: [] };
-  const backupDir = path18.join(backupRoot, name);
-  const manifestRaw = await readTextIfExists(path18.join(backupDir, "backup.yaml"));
+  const backupDir = path20.join(backupRoot, name);
+  const manifestRaw = await readTextIfExists(path20.join(backupDir, "backup.yaml"));
   if (manifestRaw === void 0) return { status: "no-backup", restored: [] };
   let files = [];
   try {
-    const parsed = parseYaml8(manifestRaw);
+    const parsed = parseYaml10(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 = path18.join(backupDir, "files", ...file.artifact.split("/"));
-    const to = path18.join(sddDir, ...file.artifact.split("/"));
+    const from = path20.join(backupDir, "files", ...file.artifact.split("/"));
+    const to = path20.join(sddDir, ...file.artifact.split("/"));
     const content = await readTextIfExists(from);
     if (content === void 0) continue;
     try {
@@ -4600,8 +5106,89 @@ async function upgradeAdvisory(root) {
   return { plan, diagnostics };
 }
 
+// src/docs.ts
+import path21 from "path";
+var DOCS_MARKER_START = "<!-- specatlas:generado:inicio -->";
+var DOCS_MARKER_END = "<!-- specatlas:generado:fin -->";
+function docData(change, language, now) {
+  const es = language !== "en";
+  const requirements = [...change.delta?.added ?? [], ...change.delta?.modified ?? []];
+  const evidence = change.verify?.evidence ?? [];
+  const passed = new Set(evidence.filter((entry) => entry.result === "pass").map((entry) => entry.scenario));
+  const requirementsText = requirements.length === 0 ? es ? "_Sin requisitos en el delta._" : "_No requirements in the delta._" : requirements.map((requirement) => {
+    const lines = [`### ${requirement.id} \u2014 ${requirement.title}`, ""];
+    for (const scenario of requirement.scenarios) lines.push(`- \`${scenario.id}\` \u2014 ${scenario.title}`);
+    return lines.join("\n");
+  }).join("\n\n");
+  const scenarioList = requirements.flatMap((requirement) => requirement.scenarios);
+  const scenariosText = scenarioList.length === 0 ? es ? "_Sin escenarios._" : "_No scenarios._" : scenarioList.map((scenario) => `- \`${scenario.id}\` \u2014 ${scenario.title}`).join("\n");
+  const evidenceText = evidence.length === 0 ? es ? "_Sin evidencia registrada._" : "_No evidence recorded._" : evidence.map((entry) => `- \`${entry.scenario}\` \u2014 ${entry.method} \xB7 ${entry.result}${entry.date ? ` \xB7 ${entry.date}` : ""}`).join("\n");
+  const pending = scenarioList.filter((scenario) => !passed.has(scenario.id));
+  const pendingText = pending.length === 0 ? es ? "_Nada pendiente: todos los escenarios tienen evidencia en pass._" : "_Nothing pending: every scenario has passing evidence._" : pending.map((scenario) => `- \`${scenario.id}\` \u2014 ${scenario.title}`).join("\n");
+  return {
+    TITLE: change.meta?.title ?? change.slug,
+    SLUG: change.slug,
+    DOMAIN: change.meta?.domain ?? "\u2014",
+    LANE: change.meta?.lane ?? "standard",
+    DATE: localDate(now),
+    TASKS: change.tasks ? `${change.tasks.counts.done}/${change.tasks.counts.total}` : es ? "sin tareas" : "no tasks",
+    REQUIREMENTS: requirementsText,
+    SCENARIOS: scenariosText,
+    EVIDENCE: evidenceText,
+    PENDING: pendingText
+  };
+}
+function mergeManaged(existing, block, language) {
+  const managed = `${DOCS_MARKER_START}
+${block.trimEnd()}
+${DOCS_MARKER_END}`;
+  if (existing === void 0) {
+    const notes = language === "en" ? "## Notes\n\n(Write here whatever you want to keep across regenerations.)" : "## Notas\n\n(Escribe aqu\xED lo que quieras conservar entre regeneraciones.)";
+    return `${managed}
+
+${notes}
+`;
+  }
+  const start = existing.indexOf(DOCS_MARKER_START);
+  const end = existing.indexOf(DOCS_MARKER_END);
+  if (start >= 0 && end > start) {
+    const before = existing.slice(0, start);
+    const after = existing.slice(end + DOCS_MARKER_END.length);
+    return `${before}${managed}${after}`;
+  }
+  return `${managed}
+
+${existing}`;
+}
+async function generateDocs(opts) {
+  const root = path21.resolve(opts.root);
+  const { config } = await loadWorkspace(root);
+  const change = await loadChange(root, opts.slug);
+  if (!change.meta) {
+    return {
+      slug: opts.slug,
+      files: [],
+      diagnostics: [diag("ATLAS-DOCS-002", "error", `No existe el cambio "${opts.slug}"`, { suggestion: "Comprueba el nombre del cambio" })]
+    };
+  }
+  const language = config.project.language;
+  const tipo = opts.tipo ?? "all";
+  const tipos = tipo === "all" ? ["tecnica", "manual"] : [tipo];
+  const templates = templatesFor(language);
+  const data = docData(change, language, opts.now ?? /* @__PURE__ */ new Date());
+  const files = [];
+  for (const current of tipos) {
+    const file = path21.join(change.dir, "docs", `${current}.md`);
+    const block = renderTemplate(current === "tecnica" ? templates.docTecnica : templates.docManual, data);
+    const existing = await readTextIfExists(file);
+    await writeText(file, mergeManaged(existing, block, language));
+    files.push({ tipo: current, path: file, created: existing === void 0 });
+  }
+  return { slug: opts.slug, files, diagnostics: [] };
+}
+
 // src/sarif.ts
-import path19 from "path";
+import path22 from "path";
 var SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
 var SARIF_VERSION = "2.1.0";
 var TOOL_NAME = "SpecAtlas";
@@ -4639,7 +5226,7 @@ function resultOf(diagnostic, root) {
     message: { text: diagnostic.message }
   };
   if (diagnostic.path) {
-    const rel = path19.relative(root, diagnostic.path);
+    const rel = path22.relative(root, diagnostic.path);
     if (rel !== "") {
       const physicalLocation = {
         artifactLocation: { uri: toPosix(rel) },
@@ -4689,7 +5276,7 @@ function toSarifText(opts) {
 }
 
 // src/doctor.ts
-import path20 from "path";
+import path23 from "path";
 async function runDoctor(root) {
   const findings = [];
   const { workspace, config } = await loadWorkspace(root);
@@ -4697,7 +5284,7 @@ async function runDoctor(root) {
   const approvals = await loadApprovals(workspace.sddDir);
   findings.push(...approvals.diagnostics);
   for (const change of workspace.changes) {
-    const deltaPath = path20.join(change.dir, "spec.md");
+    const deltaPath = path23.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")) {
@@ -4719,7 +5306,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: path20.join(change.dir, "meta.yaml") }));
+        findings.push(diag("ATLAS-LIFECYCLE-004", "error", `Override del gate "${override.gate}" sin motivo o autor`, { path: path23.join(change.dir, "meta.yaml") }));
       }
     }
   }
@@ -4742,7 +5329,7 @@ async function specHashOf(filePath) {
 }
 
 // src/gate.ts
-import path21 from "path";
+import path24 from "path";
 var UI_DOMAINS2 = /* @__PURE__ */ new Set(["frontend", "mobile", "fullstack"]);
 function count(name, diagnostics) {
   return {
@@ -4759,7 +5346,7 @@ function livingRequirementsMap(specs) {
   return map;
 }
 async function runCiGate(opts) {
-  const root = path21.resolve(opts.root);
+  const root = path24.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const diagnostics = [];
   const checks = [];
@@ -4770,11 +5357,12 @@ async function runCiGate(opts) {
   let changesErrors = 0;
   let changesWarnings = 0;
   for (const change of workspace.changes) {
-    const lintFindings = change.delta ? lintDelta(change.delta, living, path21.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
+    const lintFindings = change.delta ? lintDelta(change.delta, living, path24.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
     const trace = checkTrace({
       specs: workspace.specs,
       change,
-      requireEvidence: config.gates.verify.mode !== "off" && config.gates.verify.require_evidence
+      requireEvidence: config.gates.verify.mode !== "off" && config.gates.verify.require_evidence,
+      linked: linkedTraceInput(workspace)
     });
     const changeDiags = [...lintFindings, ...trace.findings];
     if (change.planPath) {
@@ -4819,7 +5407,11 @@ export {
   BLOCK_HEAD_RE,
   BUILTIN_PACKS,
   CONFIG_FILE,
+  CONTRACTS_DIR,
   CORE_VERSION,
+  DOCS_MARKER_END,
+  DOCS_MARKER_START,
+  LINKS_FILE,
   LIVING_FIXES_DIR,
   REQ_HEAD_RE,
   REQ_ID_RE,
@@ -4838,6 +5430,7 @@ export {
   TASK_LINE_RE,
   TOOL_NAME,
   TOOL_URL,
+  addLink,
   adoptWorkspace,
   appendRunEvent,
   applyUpgrade,
@@ -4854,12 +5447,15 @@ export {
   changeMetaYaml,
   checkMockups,
   checkTrace,
+  clarifyAdvisory,
   collectMetrics,
   collectVersionedArtifacts,
   commentIssue,
   compareTaskIds,
   computeInputsHash,
   configToYaml,
+  contractCoverage,
+  contractsAdvisory,
   copyFile,
   countBySeverity,
   createChange,
@@ -4872,9 +5468,12 @@ export {
   detectRepo,
   detectionToYaml,
   diag,
+  docsAdvisory,
+  docsReady,
   editIssue,
   emitFrontmatter,
   ensureDir,
+  ensureLinksFile,
   ensureSddDirs,
   esc,
   evaluatePacks,
@@ -4884,6 +5483,8 @@ export {
   findWorkspaceRoot,
   firstToken,
   foldDelta,
+  formatOf,
+  generateDocs,
   generatePresentation,
   generateRunId,
   getNumber,
@@ -4902,6 +5503,8 @@ export {
   issueBody,
   issueLabels,
   laneOrDefault,
+  linkedRequirementIds,
+  linkedTraceInput,
   lintDelta,
   lintMockupHtml,
   lintMockupManifest,
@@ -4919,7 +5522,9 @@ export {
   loadApprovals,
   loadChange,
   loadConfig,
+  loadContracts,
   loadDetectedBest,
+  loadLinks,
   loadLivingFixes,
   loadProfileFile,
   loadProfilesFromDir,
@@ -4939,7 +5544,9 @@ export {
   packFindings,
   parseApprovals,
   parseChangeMeta,
+  parseClarify,
   parseConfig,
+  parseContract,
   parseDelta,
   parseFixCovers,
   parseFrontmatter,
@@ -4964,12 +5571,14 @@ export {
   readTextIfExists,
   recordEvidence,
   regenerateIndex,
+  removeLink,
   renderDocument,
   renderMarkdown,
   renderRequirement,
   renderStyles,
   renderTemplate,
   requiresMockups,
+  resolveLinkPath,
   resolvePacks,
   rollbackUpgrade,
   ruleDescription,