specatlas 0.1.29 → 0.1.30

package/dist/bin.js

@@ -1586,7 +1586,7 @@ var require_core = __commonJS({
 });
 
 // src/cli.ts
-import path46 from "path";
+import path48 from "path";
 
 // ../core/dist/index.js
 import path from "path";
@@ -9034,6 +9034,7 @@ import { parse as parseYaml8, stringify as stringifyYaml6 } from "yaml";
 import path19 from "path";
 import path20 from "path";
 import path21 from "path";
+import path22 from "path";
 var CORE_VERSION = "0.0.1";
 var REQ_ID_RE = /^REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}$/;
 var SCENARIO_ID_RE = /^REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}-S\d+$/;
@@ -9056,6 +9057,8 @@ 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({}),
     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({}),
@@ -9600,6 +9603,33 @@ function findScenarioHeading(lines, blockLineIndex) {
   }
   return void 0;
 }
+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: [] };
+}
 var HEADER_KEYS = /* @__PURE__ */ new Set(["t\xE9rmino", "termino", "term", "definici\xF3n", "definicion", "definition", "sin\xF3nimos", "sinonimos", "synonyms"]);
 var SEPARATOR_RE = /^:?-{2,}:?$/;
 function parseGlossary(md, filePath) {
@@ -9749,14 +9779,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, path222, line) {
+function lintText(text, code, terms, label, path232, line) {
   const out = [];
   const lower = text.toLowerCase();
   for (const term of terms) {
     if (wordBoundary(lower, term)) {
       out.push(
         diag(code, "error", `${label}: "${term}"`, {
-          path: path222,
+          path: path232,
           line,
           suggestion: "La especificaci\xF3n es funcional y de negocio: describe comportamiento, no tecnolog\xEDa ni adjetivos vagos"
         })
@@ -9765,7 +9795,7 @@ function lintText(text, code, terms, label, path222, line) {
   }
   return out;
 }
-function lintRequirement(req, path222, opts = {}) {
+function lintRequirement(req, path232, opts = {}) {
   const out = [];
   const vague = opts.language === "en" ? VAGUE_EN : VAGUE_ES;
   const tech = opts.language === "en" ? TECH_EN : TECH_ES;
@@ -9776,32 +9806,32 @@ function lintRequirement(req, path222, 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", path222, part.line));
+    out.push(...lintText(part.text, "LINT-BIZ-002", vague, "Palabra vaga en la especificaci\xF3n", path232, part.line));
     if (opts.businessOnly !== false) {
-      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path222, part.line));
+      out.push(...lintText(part.text, "LINT-BIZ-001", tech, "Jerga t\xE9cnica en la especificaci\xF3n de negocio", path232, part.line));
     }
   }
   if (req.scenarios.length === 0) {
-    out.push(diag("TRACE-001", "error", `El requisito ${req.id} no tiene ning\xFAn escenario`, { path: path222, 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: path232, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
   }
   return out;
 }
-function lintDelta(delta, livingRequirements, path222, opts = {}) {
+function lintDelta(delta, livingRequirements, path232, opts = {}) {
   const out = [...delta.diagnostics];
   for (const req of [...delta.added, ...delta.modified]) {
-    out.push(...lintRequirement(req, path222, opts));
+    out.push(...lintRequirement(req, path232, 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: path222, line: req.line }));
+      out.push(diag("TRACE-007", "error", `MODIFIED ${req.id} no existe en la spec viva; usa ADDED`, { path: path232, 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: path222,
+            path: path232,
             line: req.line,
             suggestion: "Copia el bloque completo de la spec viva y ed\xEDtalo; para quitarlo, decl\xE1ralo en REMOVED"
           })
@@ -9812,15 +9842,15 @@ function lintDelta(delta, livingRequirements, path222, 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: path222, line: req.line }));
+      out.push(diag("TRACE-007", "error", `REMOVED ${req.id} no existe en la spec viva`, { path: path232, 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: path222, 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: path232, 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: path222, line: rename2.line }));
+      out.push(diag("TRACE-007", "error", `RENAMED ${rename2.from.id} no existe en la spec viva`, { path: path232, line: rename2.line }));
     }
   }
   return out;
@@ -9844,7 +9874,7 @@ var MERMAID_KEYWORDS = [
   "architecture-beta"
 ];
 var MERMAID_BLOCKS = /^\s*(alt|loop|opt|par|rect|critical|break|subgraph)\b/;
-function lintPlan(planText, path222) {
+function lintPlan(planText, path232) {
   const out = [];
   const blocks = [...planText.matchAll(/```mermaid\r?\n([\s\S]*?)```/g)];
   for (const [index, block] of blocks.entries()) {
@@ -9854,7 +9884,7 @@ function lintPlan(planText, path222) {
     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: path222,
+          path: path232,
           suggestion: "Corrige el tipo del diagrama o elimina el bloque"
         })
       );
@@ -9868,7 +9898,7 @@ function lintPlan(planText, path222) {
     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: path222,
+          path: path232,
           suggestion: "Cierra cada bloque alt/loop/opt/par/rect/subgraph con `end`"
         })
       );
@@ -9880,7 +9910,7 @@ function lintPlan(planText, path222) {
         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: path222,
+              path: path232,
               suggestion: "Sustituye `;` por `\xB7` o `,` en los mensajes de sequenceDiagram"
             })
           );
@@ -10182,6 +10212,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;
@@ -10244,6 +10297,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) {
@@ -10257,6 +10320,10 @@ 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 };
+  }
   return { state: "ready", blockedBy, nextAction: next(`satlas archive ${change.slug}`, "Archivar el cambio y plegar los deltas"), progress };
 }
 function stateLabel(state) {
@@ -10270,6 +10337,7 @@ function stateLabel(state) {
     building: "construyendo",
     built: "construido",
     verified: "verificado",
+    reviewed: "revisado",
     ready: "listo para archivar",
     archived: "archivado"
   };
@@ -10596,6 +10664,19 @@ async function loadChange(root, slug, relDir) {
     diagnostics.push(...change.fix.diagnostics);
     change.fixCovers = parseFixCovers(fixRaw);
   }
+  const clarifyFile = path5.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 = path5.join(dir, "docs", name);
+    if (await exists(docFile)) docsPaths.push(docFile);
+  }
+  if (docsPaths.length > 0) change.docsPaths = docsPaths;
   const mockupManifest = path5.join(dir, "mockups", "manifest.yaml");
   if (await exists(mockupManifest)) change.mockupManifestPath = mockupManifest;
   return change;
@@ -10809,6 +10890,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 = {
@@ -10934,6 +11053,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) {
@@ -13433,6 +13590,84 @@ async function upgradeAdvisory(root) {
   }
   return { plan, diagnostics };
 }
+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 = path19.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 = path19.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: [] };
+}
 var SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
 var SARIF_VERSION = "2.1.0";
 var TOOL_NAME = "SpecAtlas";
@@ -13470,7 +13705,7 @@ function resultOf(diagnostic, root) {
     message: { text: diagnostic.message }
   };
   if (diagnostic.path) {
-    const rel = path19.relative(root, diagnostic.path);
+    const rel = path20.relative(root, diagnostic.path);
     if (rel !== "") {
       const physicalLocation = {
         artifactLocation: { uri: toPosix(rel) },
@@ -13525,7 +13760,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 = path21.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")) {
@@ -13547,7 +13782,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: path21.join(change.dir, "meta.yaml") }));
       }
     }
   }
@@ -13579,7 +13814,7 @@ function livingRequirementsMap(specs) {
   return map;
 }
 async function runCiGate(opts) {
-  const root = path21.resolve(opts.root);
+  const root = path22.resolve(opts.root);
   const { workspace, config } = await loadWorkspace(root);
   const diagnostics = [];
   const checks = [];
@@ -13590,7 +13825,7 @@ async function runCiGate(opts) {
   let changesErrors = 0;
   let changesWarnings = 0;
   for (const change of workspace.changes) {
-    const lintFindings = change.delta ? lintDelta(change.delta, living, path21.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
+    const lintFindings = change.delta ? lintDelta(change.delta, living, path22.join(change.dir, "spec.md"), { language: config.spec.language }) : [];
     const trace = checkTrace({
       specs: workspace.specs,
       change,
@@ -13699,6 +13934,8 @@ var CATALOG = [
   { name: "trace", description: "Verifica la trazabilidad requisito \u2192 escenario \u2192 tarea \u2192 evidencia", flags: ["change", "require-evidence", "json"], usage: "satlas trace [--change <slug>] [--require-evidence] [--json]" },
   { name: "waves", description: "Calcula las olas paralelas de construcci\xF3n", flags: ["change", "max-parallel", "json"], usage: "satlas waves [--change <slug>] [--max-parallel N] [--json]" },
   { name: "doctor", description: "Diagn\xF3stico de salud del workspace", flags: ["json"], usage: "satlas doctor [--json]" },
+  { name: "clarify", description: "Preguntas abiertas y aclaraciones del cambio (informe; aclarar es fase del agente)", flags: ["json"], usage: "satlas clarify <slug>" },
+  { name: "docs", description: "Genera la documentaci\xF3n t\xE9cnica y manual del cambio (carril completo) desde la evidencia", flags: ["tipo", "json"], usage: "satlas docs <slug> [--tipo tecnica|manual|all]" },
   { name: "upgrade", description: "Actualiza el estado del proyecto a la versi\xF3n vigente (vista previa por defecto)", flags: ["apply", "rollback", "json"], usage: "satlas upgrade [--apply | --rollback] [--json]" },
   { name: "approve", description: "Firma la aprobaci\xF3n de un artefacto (spec): local o desde la etiqueta de un issue de GitHub", flags: ["by", "channel", "note", "dry-run", "from-github", "label", "json"], usage: 'satlas approve <slug|ruta> --by "<nombre>" | satlas approve <slug> --from-github' },
   { name: "issue", description: "Sincroniza el cambio con un issue de GitHub (tracker, no gate)", flags: ["labels", "json"], usage: "satlas issue sync <slug> [--labels a,b] | satlas issue status <slug>" },
@@ -13750,6 +13987,13 @@ var ES2 = {
   "new.done": "Cambio creado. Siguiente: escribe la spec funcional.",
   "upgrade.title": "Actualizar el estado del proyecto",
   "upgrade.preview": "Vista previa",
+  "clarify.title": "Aclaraciones del cambio",
+  "clarify.mode": "modo",
+  "clarify.open": "preguntas abiertas",
+  "clarify.resolved": "aclaradas",
+  "docs.title": "Documentaci\xF3n del cambio",
+  "docs.created": "creado",
+  "docs.updated": "actualizado",
   "summary.findings": "hallazgos",
   "label.errors": "errores",
   "label.warnings": "avisos",
@@ -13785,6 +14029,13 @@ var EN2 = {
   "new.done": "Change created. Next: write the business spec.",
   "upgrade.title": "Upgrade project state",
   "upgrade.preview": "Preview",
+  "clarify.title": "Change clarifications",
+  "clarify.mode": "mode",
+  "clarify.open": "open questions",
+  "clarify.resolved": "clarified",
+  "docs.title": "Change documentation",
+  "docs.created": "created",
+  "docs.updated": "updated",
   "summary.findings": "findings",
   "label.errors": "errors",
   "label.warnings": "warnings",
@@ -13812,26 +14063,26 @@ function cliVersion() {
 }
 
 // src/commands/adapters.ts
-import path25 from "path";
+import path26 from "path";
 
 // ../adapters/dist/index.js
-import path22 from "path";
-import { stringify as stringifyYaml7 } from "yaml";
 import path23 from "path";
+import { stringify as stringifyYaml7 } from "yaml";
+import path24 from "path";
 async function loadWorkflow(workflowDir) {
-  const phasesDir = path22.join(workflowDir, "phases");
-  const snippetsDir = path22.join(workflowDir, "snippets");
+  const phasesDir = path23.join(workflowDir, "phases");
+  const snippetsDir = path23.join(workflowDir, "snippets");
   const phases = [];
   const snippets = /* @__PURE__ */ new Map();
   const hashParts = [];
   for (const entry of (await listDir(phasesDir)).sort()) {
     if (!entry.endsWith(".md")) continue;
-    const filePath = path22.join(phasesDir, entry);
+    const filePath = path23.join(phasesDir, entry);
     const raw = await readText(filePath);
     hashParts.push(raw);
     const fm = parseFrontmatter(raw, filePath);
     const data = fm.data;
-    const id = typeof data["id"] === "string" ? data["id"] : path22.basename(entry, ".md");
+    const id = typeof data["id"] === "string" ? data["id"] : path23.basename(entry, ".md");
     phases.push({
       id,
       title: typeof data["title"] === "string" ? data["title"] : id,
@@ -13845,9 +14096,9 @@ async function loadWorkflow(workflowDir) {
   }
   for (const entry of (await listDir(snippetsDir)).sort()) {
     if (!entry.endsWith(".md")) continue;
-    const raw = await readTextIfExists(path22.join(snippetsDir, entry)) ?? "";
+    const raw = await readTextIfExists(path23.join(snippetsDir, entry)) ?? "";
     hashParts.push(raw);
-    snippets.set(path22.basename(entry, ".md"), raw.trim());
+    snippets.set(path23.basename(entry, ".md"), raw.trim());
   }
   return { phases: phases.sort((a, b) => a.id.localeCompare(b.id)), snippets, sourceHash: sha256(hashParts.join("\n---\n")) };
 }
@@ -14029,11 +14280,11 @@ Reglas: la spec es funcional y de negocio (sin tecnolog\xEDa); la trazabilidad e
 function tomlString(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-var MANIFEST_REL = path23.join(".sdd", ".generated", "manifest.json");
+var MANIFEST_REL = path24.join(".sdd", ".generated", "manifest.json");
 var BEGIN = "<!-- BEGIN specatlas -->";
 var END = "<!-- END specatlas -->";
 async function compileTargets(opts) {
-  const root = path23.resolve(opts.root);
+  const root = path24.resolve(opts.root);
   const language = opts.language ?? "es";
   const diagnostics = [];
   const sources = await loadWorkflow(opts.workflowDir);
@@ -14041,7 +14292,7 @@ async function compileTargets(opts) {
     diagnostics.push({
       code: "ATLAS-ADAPTERS-002",
       severity: "error",
-      message: `No hay fases en ${path23.join(opts.workflowDir, "phases")}`,
+      message: `No hay fases en ${path24.join(opts.workflowDir, "phases")}`,
       suggestion: "Revisa la carpeta workflow/phases del proyecto"
     });
   }
@@ -14053,7 +14304,7 @@ async function compileTargets(opts) {
     }
   }
   const compiled = [...deduped.values()];
-  const manifestPath = path23.join(root, MANIFEST_REL);
+  const manifestPath = path24.join(root, MANIFEST_REL);
   const previous = await readManifest(manifestPath);
   const previousHashes = /* @__PURE__ */ new Map();
   for (const files2 of Object.values(previous?.targets ?? {})) {
@@ -14064,7 +14315,7 @@ async function compileTargets(opts) {
   const stale = [];
   const missing = [];
   for (const file of compiled) {
-    const abs = path23.join(root, file.path);
+    const abs = path24.join(root, file.path);
     const finalContent = file.path === "AGENTS.md" ? mergeAgentsBlock(await readTextIfExists(abs) ?? "", file.content) : file.content;
     const hash = artifactHash(finalContent);
     const existing = await readTextIfExists(abs);
@@ -14080,7 +14331,7 @@ async function compileTargets(opts) {
       stale.push(file.path);
     }
     if (!opts.check && status !== "unchanged") {
-      await ensureDir(path23.dirname(abs));
+      await ensureDir(path24.dirname(abs));
       await writeText(abs, finalContent);
       written.push(file.path);
     }
@@ -14134,7 +14385,7 @@ async function readManifest(manifestPath) {
   }
 }
 async function checkAdapters(opts) {
-  const manifestPath = path23.join(path23.resolve(opts.root), MANIFEST_REL);
+  const manifestPath = path24.join(path24.resolve(opts.root), MANIFEST_REL);
   const manifestRaw = await readTextIfExists(manifestPath);
   if (manifestRaw === void 0) return { ok: false, manifest: false, stale: [], missing: [], orphaned: [] };
   const manifest = await readManifest(manifestPath);
@@ -14151,7 +14402,7 @@ async function checkAdapters(opts) {
 }
 
 // src/paths.ts
-import path24 from "path";
+import path25 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function resolveProfilesDir() {
   const env = process.env["SPECATLAS_PROFILES_DIR"];
@@ -14161,16 +14412,16 @@ async function resolveProfilesDir() {
 async function resolveWorkflowDir() {
   const env = process.env["SPECATLAS_WORKFLOW_DIR"];
   if (env && await exists(env)) return env;
-  return walkUpFor(path24.join("workflow", "phases"));
+  return walkUpFor(path25.join("workflow", "phases"));
 }
 async function walkUpFor(relative) {
-  let dir = path24.dirname(fileURLToPath2(import.meta.url));
+  let dir = path25.dirname(fileURLToPath2(import.meta.url));
   for (let i = 0; i < 8; i += 1) {
-    const candidate = path24.join(dir, relative);
+    const candidate = path25.join(dir, relative);
     if (await exists(candidate)) {
-      return relative.includes(path24.sep) ? path24.dirname(candidate) : candidate;
+      return relative.includes(path25.sep) ? path25.dirname(candidate) : candidate;
     }
-    const parent = path24.dirname(dir);
+    const parent = path25.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -14248,7 +14499,7 @@ async function runAdapters(ctx) {
   for (const [target, count2] of byTarget) lines.push(`  ${target}: ${count2} archivo(s)`);
   if (report.written.length > 0) {
     lines.push("");
-    for (const p of report.written) lines.push(`  + ${path25.relative(ctx.cwd, path25.join(root, p))}`);
+    for (const p of report.written) lines.push(`  + ${path26.relative(ctx.cwd, path26.join(root, p))}`);
   } else {
     lines.push("");
     lines.push("Sin cambios: los adaptadores ya estaban al d\xEDa.");
@@ -14259,7 +14510,7 @@ async function runAdapters(ctx) {
 }
 
 // src/commands/adopt.ts
-import path26 from "path";
+import path27 from "path";
 async function runAdopt(ctx) {
   const { root } = await requireWorkspace(ctx);
   const domainsFlag = flagString(ctx.flags, "domains") ?? flagString(ctx.flags, "domain");
@@ -14279,11 +14530,11 @@ async function runAdopt(ctx) {
   }
   if (result.createdSpecs.length > 0) {
     lines.push("");
-    for (const spec of result.createdSpecs) lines.push(`  ${result.dryRun ? "[dry-run] " : "+ "}${path26.relative(ctx.cwd, spec)}`);
+    for (const spec of result.createdSpecs) lines.push(`  ${result.dryRun ? "[dry-run] " : "+ "}${path27.relative(ctx.cwd, spec)}`);
   }
   if (result.reportPath && !result.dryRun) {
     lines.push("");
-    lines.push(`  Informe: ${path26.relative(ctx.cwd, result.reportPath)}`);
+    lines.push(`  Informe: ${path27.relative(ctx.cwd, result.reportPath)}`);
   }
   lines.push("");
   lines.push("Siguiente: fase /satlas-adopt por dominio (requisitos AS-IS) y luego:");
@@ -14296,8 +14547,8 @@ async function runAdopt(ctx) {
     diagnostics: result.diagnostics,
     data: {
       domains: result.domains.map((d) => ({ name: d.name, files: d.files, existingSpec: d.existingSpec })),
-      createdSpecs: result.createdSpecs.map((s) => path26.relative(ctx.cwd, s)),
-      reportPath: result.reportPath ? path26.relative(ctx.cwd, result.reportPath) : void 0,
+      createdSpecs: result.createdSpecs.map((s) => path27.relative(ctx.cwd, s)),
+      reportPath: result.reportPath ? path27.relative(ctx.cwd, result.reportPath) : void 0,
       stack: result.stack,
       dryRun: result.dryRun
     },
@@ -14306,7 +14557,7 @@ async function runAdopt(ctx) {
 }
 
 // src/commands/analyze.ts
-import path27 from "path";
+import path28 from "path";
 async function runAnalyzeCommand(ctx) {
   const { root } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -14317,23 +14568,23 @@ async function runAnalyzeCommand(ctx) {
   const lines = [`An\xE1lisis \u2014 ${slug}`, "", `  estado: ${result.status}`, `  hallazgos: ${result.summary.errors} errores, ${result.summary.warnings} avisos`, `  evidencia: ${result.evidence.done}/${result.evidence.total} escenarios`];
   if (result.waves) lines.push(`  olas: ${result.waves.blocks} bloque(s), ${result.waves.waves} ola(s), ${result.waves.tasks} tarea(s)`);
   if (result.mockups) lines.push(`  mockups: ${result.mockups.screens} pantalla(s)${result.mockups.stale ? " (desactualizados)" : ""}`);
-  if (result.path) lines.push("", `  informe: ${path27.relative(ctx.cwd, result.path)}`);
+  if (result.path) lines.push("", `  informe: ${path28.relative(ctx.cwd, result.path)}`);
   for (const finding of result.findings) {
     lines.push(`  ${finding.severity.toUpperCase()} ${finding.code} \u2014 ${finding.message}`);
   }
   return {
     exitCode: result.status === "blocked" ? 1 : 0,
     diagnostics: result.findings,
-    data: result.path ? { ...result, path: path27.relative(ctx.cwd, result.path) } : result,
+    data: result.path ? { ...result, path: path28.relative(ctx.cwd, result.path) } : result,
     text: lines
   };
 }
 
 // src/commands/approve.ts
-import path29 from "path";
+import path30 from "path";
 
 // src/commands/issue.ts
-import path28 from "path";
+import path29 from "path";
 async function runIssue(ctx) {
   const action = ctx.positionals[0] ?? "status";
   const slug = ctx.positionals[1];
@@ -14361,7 +14612,7 @@ async function runIssue(ctx) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-ISSUE-000", severity: "error", message: "Falta el slug: satlas issue status <slug>" }] };
     }
     const change = await loadChange(root, slug);
-    const { config } = await loadConfig(path28.join(root, ".sdd"));
+    const { config } = await loadConfig(path29.join(root, ".sdd"));
     const tracker = change.meta?.tracker;
     const lines = [`Issue de ${slug}`, ""];
     if (!tracker || tracker.provider !== "github") {
@@ -14432,7 +14683,7 @@ async function runApprove(ctx) {
     };
   }
   const { root, workspace, config } = await requireWorkspace(ctx);
-  const artifact = target.includes("/") || target.includes("\\") ? target : path29.join("changes", target, "spec.md");
+  const artifact = target.includes("/") || target.includes("\\") ? target : path30.join("changes", target, "spec.md");
   const channelFlag = flagString(ctx.flags, "channel");
   const channel = channelFlag === "presentation" || channelFlag === "editor" || channelFlag === "pr" || channelFlag === "tracker" ? channelFlag : "cli";
   const change = workspace.changes.find(
@@ -14473,13 +14724,13 @@ async function runApprove(ctx) {
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: result.approval ? { ...result.approval, file: path29.relative(ctx.cwd, result.file) } : void 0,
+    data: result.approval ? { ...result.approval, file: path30.relative(ctx.cwd, result.file) } : void 0,
     text: lines
   };
 }
 
 // src/commands/archive.ts
-import path30 from "path";
+import path31 from "path";
 async function runArchive(ctx) {
   const slug = ctx.positionals[0];
   if (!slug) {
@@ -14516,7 +14767,7 @@ async function runArchive(ctx) {
   } else {
     lines.push("El delta no contiene operaciones (ADDED/MODIFIED/REMOVED/RENAMED).");
   }
-  if (result.archivedTo) lines.push(`  archivado en: ${path30.relative(ctx.cwd, result.archivedTo)}`);
+  if (result.archivedTo) lines.push(`  archivado en: ${path31.relative(ctx.cwd, result.archivedTo)}`);
   const hasErrors2 = result.diagnostics.some((d) => d.severity === "error");
   return {
     exitCode: hasErrors2 ? 1 : 0,
@@ -14527,7 +14778,7 @@ async function runArchive(ctx) {
 }
 
 // src/commands/ci.ts
-import path31 from "path";
+import path32 from "path";
 async function runCi(ctx) {
   const { root, config } = await requireWorkspace(ctx);
   const strict = flagBool(ctx.flags, "strict");
@@ -14553,10 +14804,10 @@ async function runCi(ctx) {
   const lines = ["CI de SpecAtlas", ""];
   let sarifWritten;
   if (sarifPath) {
-    const target = path31.resolve(ctx.cwd, sarifPath);
+    const target = path32.resolve(ctx.cwd, sarifPath);
     try {
       await writeText(target, toSarifText({ diagnostics: gate.diagnostics, root, version: cliVersion(), failed: gate.failed }));
-      sarifWritten = path31.relative(ctx.cwd, target);
+      sarifWritten = path32.relative(ctx.cwd, target);
     } catch (err) {
       diagnostics.push({
         code: "ATLAS-CI-SARIF-001",
@@ -14590,13 +14841,83 @@ async function runCi(ctx) {
   };
 }
 
+// src/commands/clarify.ts
+async function runClarify(ctx) {
+  const slug = ctx.positionals[0];
+  if (!slug) {
+    return { exitCode: 2, diagnostics: [{ code: "ATLAS-CLARIFY-000", severity: "error", message: "Falta el slug: satlas clarify <slug>" }] };
+  }
+  const { workspace, config } = await requireWorkspace(ctx);
+  const change = workspace.changes.find((c) => c.slug === slug);
+  if (!change) {
+    return { exitCode: 2, diagnostics: [{ code: "ATLAS-CLARIFY-000", severity: "error", message: `No existe el cambio "${slug}"` }] };
+  }
+  const open = change.clarify?.open ?? [];
+  const resolved = change.clarify?.resolved ?? [];
+  const mode = config.gates.clarify.mode;
+  const lines = [msg("clarify.title", ctx.language), ""];
+  lines.push(`  ${msg("clarify.mode", ctx.language)}: ${mode}`);
+  lines.push(`  ${msg("clarify.open", ctx.language)}: ${open.length}`);
+  for (const item of open) lines.push(`    [ ] ${item.text}`);
+  lines.push(`  ${msg("clarify.resolved", ctx.language)}: ${resolved.length}`);
+  for (const item of resolved) lines.push(`    [x] ${item.text}${item.answer ? ` \u2014 ${item.answer}` : ""}`);
+  if (open.length > 0) {
+    lines.push("");
+    lines.push(`Aclara con la fase del agente: /satlas.clarify ${slug}`);
+  } else if (resolved.length === 0) {
+    lines.push("");
+    lines.push("El cambio no tiene preguntas abiertas ni aclaraciones registradas.");
+  }
+  return {
+    exitCode: 0,
+    diagnostics: [],
+    data: {
+      slug,
+      mode,
+      open: open.map((item) => ({ text: item.text, line: item.line })),
+      resolved: resolved.map((item) => ({ text: item.text, line: item.line, answer: item.answer })),
+      ...open.length > 0 ? { action: `/satlas.clarify ${slug}` } : {}
+    },
+    text: lines
+  };
+}
+
+// src/commands/docs.ts
+import path33 from "path";
+async function runDocs(ctx) {
+  const slug = ctx.positionals[0];
+  if (!slug) {
+    return { exitCode: 2, diagnostics: [{ code: "ATLAS-DOCS-000", severity: "error", message: "Falta el slug: satlas docs <slug> [--tipo tecnica|manual|all]" }] };
+  }
+  const { root } = await requireWorkspace(ctx);
+  const tipoFlag = flagString(ctx.flags, "tipo");
+  const tipo = tipoFlag === "tecnica" || tipoFlag === "manual" || tipoFlag === "all" ? tipoFlag : "all";
+  const result = await generateDocs({ root, slug, tipo });
+  const errors = result.diagnostics.filter((d) => d.severity === "error");
+  const lines = [msg("docs.title", ctx.language), ""];
+  for (const file of result.files) {
+    lines.push(`  ${file.created ? msg("docs.created", ctx.language) : msg("docs.updated", ctx.language)}: ${path33.relative(ctx.cwd, file.path)}`);
+  }
+  for (const error of errors) lines.push(`  ERROR ${error.code} \u2014 ${error.message}`);
+  return {
+    exitCode: errors.length > 0 ? 2 : 0,
+    diagnostics: result.diagnostics,
+    data: {
+      slug: result.slug,
+      tipo,
+      files: result.files.map((file) => ({ tipo: file.tipo, path: path33.relative(ctx.cwd, file.path), created: file.created }))
+    },
+    text: lines
+  };
+}
+
 // src/commands/profile.ts
-import path32 from "path";
+import path34 from "path";
 async function runProfile(ctx) {
   const action = ctx.positionals[0] ?? "detect";
   const { root, workspace } = await requireWorkspace(ctx);
   const officialDir = await resolveProfilesDir();
-  const customDir = path32.join(workspace.sddDir, "profiles", "custom");
+  const customDir = path34.join(workspace.sddDir, "profiles", "custom");
   const profiles = [...officialDir ? await loadProfilesFromDir(officialDir) : [], ...await loadProfilesFromDir(customDir)];
   if (action === "detect") {
     const result = await detectProfiles(root, profiles);
@@ -14625,7 +14946,7 @@ async function runProfile(ctx) {
     if (!name) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-PROFILE-001", severity: "error", message: "Falta el nombre del perfil: satlas profile create <nombre>" }] };
     }
-    const file = path32.join(customDir, `${name}.yaml`);
+    const file = path34.join(customDir, `${name}.yaml`);
     if (await exists(file)) {
       return { exitCode: 2, diagnostics: [{ code: "ATLAS-PROFILE-002", severity: "error", message: `El perfil ya existe: ${file}` }] };
     }
@@ -14634,7 +14955,7 @@ async function runProfile(ctx) {
       exitCode: 0,
       diagnostics: [],
       data: { file },
-      text: [`Perfil creado: ${path32.relative(ctx.cwd, file)}`, "", "Ed\xEDtalo con los comandos reales de tu stack (build/lint/test) y tus anti-patrones."]
+      text: [`Perfil creado: ${path34.relative(ctx.cwd, file)}`, "", "Ed\xEDtalo con los comandos reales de tu stack (build/lint/test) y tus anti-patrones."]
     };
   }
   return {
@@ -14643,7 +14964,7 @@ async function runProfile(ctx) {
   };
 }
 async function isInside(dir, name) {
-  return exists(path32.join(dir, `${name}.yaml`));
+  return exists(path34.join(dir, `${name}.yaml`));
 }
 function profileTemplate(name) {
   return `name: ${name}
@@ -14671,7 +14992,7 @@ assumptions: []
 }
 
 // src/commands/doctor.ts
-import path33 from "path";
+import path35 from "path";
 async function runDoctorCommand(ctx) {
   const { root, config } = await requireWorkspace(ctx);
   const report = await runDoctor(root);
@@ -14696,7 +15017,7 @@ async function runDoctorCommand(ctx) {
     lines.push("Sin hallazgos. El workspace est\xE1 sano.");
   } else {
     for (const finding of report.findings) {
-      const location = finding.path ? ` ${path33.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""}` : "";
+      const location = finding.path ? ` ${path35.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""}` : "";
       lines.push(`  ${finding.severity.toUpperCase()}  ${finding.code}${location} \u2014 ${finding.message}`);
       if (finding.suggestion) lines.push(`       \u21B3 ${finding.suggestion}`);
     }
@@ -14770,7 +15091,7 @@ async function runHelp(ctx, commandName) {
 }
 
 // src/commands/init.ts
-import path34 from "path";
+import path36 from "path";
 async function runInit(ctx) {
   const languageFlag = flagString(ctx.flags, "language");
   const language = languageFlag === "en" ? "en" : languageFlag === "es" ? "es" : void 0;
@@ -14817,11 +15138,11 @@ async function runInit(ctx) {
   const lines = [msg("init.title", ctx.language), ""];
   if (result.created.length > 0) {
     lines.push(msg("init.done", ctx.language));
-    for (const file of result.created) lines.push(`  + ${path34.relative(ctx.cwd, file)}`);
+    for (const file of result.created) lines.push(`  + ${path36.relative(ctx.cwd, file)}`);
     if (compiled.length > 0) {
       lines.push("");
       lines.push("Adaptadores compilados:");
-      for (const file of compiled) lines.push(`  + ${path34.relative(ctx.cwd, path34.join(ctx.cwd, file))}`);
+      for (const file of compiled) lines.push(`  + ${path36.relative(ctx.cwd, path36.join(ctx.cwd, file))}`);
     }
     lines.push("");
     lines.push("Siguiente: crea un cambio con `satlas new <slug>` y escribe la spec funcional.");
@@ -14831,8 +15152,8 @@ async function runInit(ctx) {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
     data: {
-      sddDir: path34.relative(ctx.cwd, result.sddDir),
-      created: result.created.map((f) => path34.relative(ctx.cwd, f)),
+      sddDir: path36.relative(ctx.cwd, result.sddDir),
+      created: result.created.map((f) => path36.relative(ctx.cwd, f)),
       detected: result.detected?.matches.map((m) => ({ name: m.name, score: m.score })),
       best: result.detected?.best?.name
     },
@@ -14873,7 +15194,7 @@ async function runMetrics(ctx) {
 }
 
 // src/commands/mockup.ts
-import path35 from "path";
+import path37 from "path";
 async function runMockup(ctx) {
   const { root, workspace, config } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -14922,17 +15243,17 @@ async function runMockup(ctx) {
     `  pantallas: ${plan.screens.length}`,
     ...plan.screens.map((s) => `    - ${s.id}: ${s.title} (${s.illustrates.length} escenario(s))`),
     "",
-    `  plan: ${path35.relative(ctx.cwd, planFile)}`,
-    `  manifiesto: ${path35.relative(ctx.cwd, manifestFile)}`,
+    `  plan: ${path37.relative(ctx.cwd, planFile)}`,
+    `  manifiesto: ${path37.relative(ctx.cwd, manifestFile)}`,
     "",
     "Siguiente: genera el HTML de cada pantalla (fase /satlas-mockup) y valida con `satlas mockup " + slug + " --check`."
   ];
-  return { exitCode: 0, diagnostics: [], data: { plan, planFile: path35.relative(ctx.cwd, planFile), manifestFile: path35.relative(ctx.cwd, manifestFile) }, text: lines };
+  return { exitCode: 0, diagnostics: [], data: { plan, planFile: path37.relative(ctx.cwd, planFile), manifestFile: path37.relative(ctx.cwd, manifestFile) }, text: lines };
 }
 
 // src/mcp/server.ts
 import { promises as fs3 } from "fs";
-import path38 from "path";
+import path40 from "path";
 import { createInterface } from "readline/promises";
 
 // src/mcp/protocol.ts
@@ -15021,12 +15342,12 @@ async function runAtlasFixes(_args, host) {
 }
 
 // src/mcp/tools/glossary.ts
-import path36 from "path";
+import path38 from "path";
 async function runAtlasGlossary(_args, host) {
   const resolved = await host.getWorkspace();
   if (!resolved) return noWorkspaceResult();
   const { root, config } = resolved;
-  const glossaryPath = path36.resolve(root, config.spec.glossary);
+  const glossaryPath = path38.resolve(root, config.spec.glossary);
   const raw = await readTextIfExists(glossaryPath);
   if (raw === void 0) {
     return jsonResult({
@@ -15072,7 +15393,7 @@ async function runAtlasImpact(args, host) {
 }
 
 // src/evaluate.ts
-import path37 from "path";
+import path39 from "path";
 function livingRequirementsMap2(specs) {
   const map = /* @__PURE__ */ new Map();
   for (const spec of specs) {
@@ -15081,7 +15402,7 @@ function livingRequirementsMap2(specs) {
   return map;
 }
 async function evaluateChange(workspace, config, change, approvals) {
-  const deltaPath = path37.join(change.dir, "spec.md");
+  const deltaPath = path39.join(change.dir, "spec.md");
   const deltaContent = await readTextIfExists(deltaPath);
   const approval = verifyApproval(change, approvals, config, deltaContent ?? void 0);
   const living = livingRequirementsMap2(workspace.specs);
@@ -15100,7 +15421,8 @@ async function evaluateChange(workspace, config, change, approvals) {
     blockingFindings: change.delta ? blocking : 0,
     ...mockupsAreReady !== void 0 ? { mockupsReady: mockupsAreReady } : {}
   });
-  return { change, approval, lintFindings, trace, blocking, state };
+  const phaseAdvisories = [...clarifyAdvisory(change, config), ...docsAdvisory(change, config)];
+  return { change, approval, lintFindings: [...lintFindings, ...phaseAdvisories], trace, blocking, state };
 }
 
 // src/mcp/tools/next.ts
@@ -15353,8 +15675,8 @@ var WorkspaceCache = class {
   }
 };
 async function workspaceStamp(root) {
-  const sddDir = path38.join(root, ".sdd");
-  const markers = [sddDir, path38.join(sddDir, "config.yaml"), path38.join(sddDir, "changes"), path38.join(sddDir, "specs"), path38.join(sddDir, "approvals.yaml")];
+  const sddDir = path40.join(root, ".sdd");
+  const markers = [sddDir, path40.join(sddDir, "config.yaml"), path40.join(sddDir, "changes"), path40.join(sddDir, "specs"), path40.join(sddDir, "approvals.yaml")];
   let stamp = 0;
   for (const marker of markers) {
     try {
@@ -15372,7 +15694,7 @@ async function resolveMcpWorkspace(cwd, cache) {
   const cached2 = cache.get(root);
   if (cached2 && cached2.mtimeMs === stamp) return cached2.value;
   const { workspace, config } = await loadWorkspace(root);
-  const approvals = await loadApprovals(path38.join(root, ".sdd"));
+  const approvals = await loadApprovals(path40.join(root, ".sdd"));
   const value = { root, workspace, config, approvals: approvals.byArtifact };
   cache.set(root, stamp, value);
   return value;
@@ -15464,7 +15786,7 @@ async function runMcp(ctx) {
 }
 
 // src/commands/packs.ts
-import path39 from "path";
+import path41 from "path";
 async function runPacks(ctx) {
   const { root, config, workspace } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "check");
@@ -15522,14 +15844,14 @@ async function runPacks(ctx) {
     data: {
       slug,
       packs: evaluations.map((evaluation) => ({ id: evaluation.pack.id, status: evaluation.status, passed: evaluation.passed, failed: evaluation.failed, results: evaluation.results })),
-      analyzePath: path39.posix.join(".sdd", "changes", slug, "analyze.md")
+      analyzePath: path41.posix.join(".sdd", "changes", slug, "analyze.md")
     },
     text: lines
   };
 }
 
 // src/commands/new.ts
-import path40 from "path";
+import path42 from "path";
 async function runNew(ctx) {
   const slug = ctx.positionals[0];
   if (!slug) {
@@ -15555,14 +15877,14 @@ async function runNew(ctx) {
     msg("new.title", ctx.language),
     "",
     msg("new.done", ctx.language),
-    ...result.files.map((f) => `  + ${path40.relative(ctx.cwd, f)}`),
+    ...result.files.map((f) => `  + ${path42.relative(ctx.cwd, f)}`),
     "",
     `Siguiente: /satlas.specify ${result.slug} \u2014 escribe la especificaci\xF3n 100% funcional y de negocio.`
   ];
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: { slug: result.slug, files: result.files.map((f) => path40.relative(ctx.cwd, f)) },
+    data: { slug: result.slug, files: result.files.map((f) => path42.relative(ctx.cwd, f)) },
     text: lines
   };
 }
@@ -15597,7 +15919,7 @@ async function runNext(ctx) {
 }
 
 // src/commands/present.ts
-import path41 from "path";
+import path43 from "path";
 async function runPresentCommand(ctx) {
   const { root } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -15609,7 +15931,7 @@ async function runPresentCommand(ctx) {
   if (result.path) {
     lines.push("Propuesta generada");
     lines.push("");
-    lines.push(`  archivo: ${path41.relative(ctx.cwd, result.path)}`);
+    lines.push(`  archivo: ${path43.relative(ctx.cwd, result.path)}`);
     if (result.hash) lines.push(`  hash de la spec: ${shortHash(result.hash)}`);
     lines.push("");
     lines.push("\xC1brela en el navegador y comp\xE1rtela con el stakeholder.");
@@ -15619,7 +15941,7 @@ async function runPresentCommand(ctx) {
   return {
     exitCode: hasErrors2 ? 1 : 0,
     diagnostics: result.diagnostics,
-    data: result.path ? { path: path41.relative(ctx.cwd, result.path), hash: result.hash } : void 0,
+    data: result.path ? { path: path43.relative(ctx.cwd, result.path), hash: result.hash } : void 0,
     text: lines
   };
 }
@@ -15767,7 +16089,7 @@ async function runStatus(ctx) {
 }
 
 // src/commands/trace.ts
-import path42 from "path";
+import path44 from "path";
 async function runTrace(ctx) {
   const { workspace, config } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "change");
@@ -15787,7 +16109,7 @@ async function runTrace(ctx) {
     data.push({ slug: change.slug, nodes: result.graph.nodes.length, edges: result.graph.edges.length, summary: result.summary, findings: result.findings });
     lines.push(`  ${change.slug}: ${result.graph.nodes.length} nodos, ${result.graph.edges.length} aristas, ${errors} errores, ${result.summary.warnings} avisos`);
     for (const finding of result.findings) {
-      const location = finding.path ? ` (${path42.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""})` : "";
+      const location = finding.path ? ` (${path44.relative(ctx.cwd, finding.path)}${finding.line ? `:${finding.line}` : ""})` : "";
       lines.push(`    ${finding.severity.toUpperCase()} ${finding.code} \u2014 ${finding.message}${location}`);
     }
   }
@@ -15797,7 +16119,7 @@ async function runTrace(ctx) {
 }
 
 // src/commands/upgrade.ts
-import path43 from "path";
+import path45 from "path";
 async function runUpgrade(ctx) {
   const { root } = await requireWorkspace(ctx);
   const apply = flagBool(ctx.flags, "apply");
@@ -15851,7 +16173,7 @@ function renderPreview(plan, root, ctx) {
   }
   for (const item of plan.unreadable) {
     lines.push(`  Ilegible: "${item.artifact}" \u2014 ${item.reason}`);
-    lines.push(`    \u21B3 ${path43.relative(ctx.cwd, item.path)}`);
+    lines.push(`    \u21B3 ${path45.relative(ctx.cwd, item.path)}`);
   }
   return { exitCode: 0, diagnostics: [], data: summarizable(plan), text: lines };
 }
@@ -15914,7 +16236,7 @@ function renderRollback(report, ctx) {
 }
 
 // src/commands/validate.ts
-import path44 from "path";
+import path46 from "path";
 async function runValidate(ctx) {
   const { root, workspace, config, approvals } = await requireWorkspace(ctx);
   const slug = flagString(ctx.flags, "change");
@@ -15941,7 +16263,7 @@ async function runValidate(ctx) {
     for (const finding of evaluation.lintFindings) {
       lines.push(`    ${finding.severity.toUpperCase()} ${finding.code}${finding.line ? `:${finding.line}` : ""} \u2014 ${finding.message}`);
     }
-    lines.push(`    archivo: ${path44.relative(ctx.cwd, path44.join(change.dir, "spec.md"))}`);
+    lines.push(`    archivo: ${path46.relative(ctx.cwd, path46.join(change.dir, "spec.md"))}`);
   }
   if (targets.length === 0) lines.push("Sin cambios activos.");
   if (advisory && advisory.plan.pending.length > 0) {
@@ -15969,7 +16291,7 @@ async function runValidate(ctx) {
 }
 
 // src/commands/verify.ts
-import path45 from "path";
+import path47 from "path";
 async function runVerify(ctx) {
   const { root, workspace } = await requireWorkspace(ctx);
   const slug = ctx.positionals[0];
@@ -16012,7 +16334,7 @@ async function runVerify(ctx) {
     return { exitCode: 2, diagnostics: [{ code: "ATLAS-VERIFY-001", severity: "error", message: "Falta --by <nombre> (o define meta.owner)" }] };
   }
   const profilesDir = await resolveProfilesDir();
-  const profile = await loadActiveProfile(path45.join(root, ".sdd"), [profilesDir ?? "", path45.join(root, ".sdd", "profiles", "custom")].filter(Boolean));
+  const profile = await loadActiveProfile(path47.join(root, ".sdd"), [profilesDir ?? "", path47.join(root, ".sdd", "profiles", "custom")].filter(Boolean));
   const record = await recordEvidence({
     root,
     slug,
@@ -16034,7 +16356,7 @@ async function runVerify(ctx) {
     if (record.evidence.command) lines.push(`  comando: ${record.evidence.command}`);
     lines.push(`  resultado: ${record.evidence.result}`);
     if (record.evidence.outputHash) lines.push(`  hash:    ${record.evidence.outputHash}`);
-    lines.push(`  archivo: ${path45.relative(ctx.cwd, record.path)}`);
+    lines.push(`  archivo: ${path47.relative(ctx.cwd, record.path)}`);
     if (record.stdout) {
       lines.push("");
       lines.push("  salida (\xFAltimas l\xEDneas):");
@@ -16049,7 +16371,7 @@ async function runVerify(ctx) {
   return {
     exitCode: record.exitCode === 0 ? 0 : 1,
     diagnostics: record.diagnostics,
-    data: { evidence: record.evidence, path: path45.relative(ctx.cwd, record.path), exitCode: record.exitCode },
+    data: { evidence: record.evidence, path: path47.relative(ctx.cwd, record.path), exitCode: record.exitCode },
     text: lines
   };
 }
@@ -16104,6 +16426,8 @@ var HANDLERS2 = {
   trace: runTrace,
   waves: runWaves,
   doctor: runDoctorCommand,
+  clarify: runClarify,
+  docs: runDocs,
   upgrade: runUpgrade,
   approve: runApprove,
   issue: runIssue,
@@ -16149,7 +16473,7 @@ async function requireWorkspace(ctx) {
     throw new CliError("ATLAS-WS-001", msg("cli.noWorkspace", ctx.language), 2);
   }
   const { workspace, config } = await loadWorkspace(root);
-  const approvals = await loadApprovals(path46.join(root, ".sdd"));
+  const approvals = await loadApprovals(path48.join(root, ".sdd"));
   return { root, workspace, config, approvals: approvals.byArtifact };
 }
 var CliError = class extends Error {
@@ -16216,7 +16540,7 @@ function printResult(command, result, json2, language) {
   }
   const lines = [...result.text ?? []];
   for (const d of result.diagnostics) {
-    const location = d.path ? ` ${path46.relative(process.cwd(), d.path)}${d.line ? `:${d.line}` : ""}` : "";
+    const location = d.path ? ` ${path48.relative(process.cwd(), d.path)}${d.line ? `:${d.line}` : ""}` : "";
     lines.push(`${d.severity === "error" ? "ERROR" : d.severity === "warning" ? "AVISO" : "NOTA"}  ${d.code}${location} \u2014 ${d.message}`);
     if (d.suggestion) lines.push(`       \u21B3 ${d.suggestion}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specatlas",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "SpecAtlas: kernel determinista de Spec-Driven Development (CLI)",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@specatlas/adapters": "0.1.1",
-    "@specatlas/core": "0.1.26"
+    "@specatlas/core": "0.1.27"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/workflow/phases/clarify.md

@@ -0,0 +1,39 @@
+---
+id: clarify
+title: Aclarar
+description: >-
+  Resuelve supuestos, dependencias y preguntas abiertas de un cambio ya especificado
+  antes de aprobar y planificar. Usar cuando el usuario pide aclarar, resolver dudas
+  o cerrar preguntas abiertas de una especificación.
+requires: []
+produces:
+  - changes/<slug>/clarify.md
+arguments: true
+agent:
+  mode: primary
+---
+
+# Fase: Aclarar (vaciar las preguntas abiertas)
+
+## Objetivo
+
+Resolver los supuestos, dependencias y preguntas abiertas del cambio `{{SLUG}}` y dejarlos registrados en `.sdd/changes/{{SLUG}}/clarify.md`.
+El contenido se escribe en **{{LANGUAGE_NAME}}**.
+
+## Pasos
+
+1. Lee `.sdd/changes/{{SLUG}}/spec.md`, `proposal.md` y, si existe, `clarify.md`.
+2. Detecta supuestos, dependencias y preguntas abiertas **reales** de la especificación; no inventes preguntas.
+3. Pregunta una a una (máximo 5, las que más cambien el resultado), con opciones concretas cuando ayuden a decidir. No des nada por respondido sin respuesta del humano.
+4. Escribe o actualiza `clarify.md` con la gramática canónica:
+   - `- [ ] pregunta` para lo que sigue abierto.
+   - `- [x] pregunta — respuesta` para lo aclarado.
+5. Refleja el resumen de lo decidido en la propuesta (`proposal.md`), en su sección correspondiente.
+6. Si una respuesta cambia lo especificado: corrige `spec.md` y avisa de que la firma quedó obsoleta (hay que volver a aprobar con `satlas approve`).
+7. Cierra con `satlas clarify {{SLUG}}` (estado de la aclaración) y `satlas next {{SLUG}}`.
+
+## Prohibido
+
+- Inventar preguntas o respuestas.
+- Cambiar la especificación sin avisar de la re-firma.
+- Marcar como aclarada una pregunta que el humano no respondió.

package/workflow/phases/docs.md

@@ -0,0 +1,36 @@
+---
+id: docs
+title: Documentar
+description: >-
+  Genera la documentación técnica y manual del cambio (carril completo) desde la
+  evidencia registrada. Usar cuando el usuario pide documentar, generar el manual
+  o cerrar la documentación antes de archivar.
+requires: []
+produces:
+  - changes/<slug>/docs/tecnica.md
+  - changes/<slug>/docs/manual.md
+arguments: true
+agent:
+  mode: primary
+---
+
+# Fase: Documentar (técnica y manual del cambio)
+
+## Objetivo
+
+Dejar la documentación técnica y manual del cambio `{{SLUG}}` en `.sdd/changes/{{SLUG}}/docs/`, construida desde lo real (especificación, tareas y evidencia).
+El contenido se escribe en **{{LANGUAGE_NAME}}**.
+
+## Pasos
+
+1. Ejecuta `satlas docs {{SLUG}}` para generar el esqueleto de los dos documentos desde las plantillas y la evidencia.
+2. Revisa lo generado: si un dato falta o es incorrecto, corrige **la fuente** (spec, tareas o evidencia) y vuelve a ejecutar el comando; no retoques los datos generados.
+3. Completa lo que no se puede generar — decisiones, límites, ejemplos de uso y notas — **fuera del bloque gestionado** (lo que está entre los marcadores se reemplaza al regenerar; lo de fuera se conserva).
+4. Señala expresamente lo que quedó sin evidencia; nunca lo presentes como hecho.
+5. Cierra con `satlas docs {{SLUG}}` (regenera el bloque gestionado) y `satlas next {{SLUG}}`.
+
+## Prohibido
+
+- Documentar como hecho algo sin evidencia.
+- Escribir dentro del bloque gestionado (se reemplaza al regenerar).
+- Tocar la especificación, el plan o las tareas desde esta fase.