@specatlas/core 0.1.26 → 0.1.27

package/dist/index.d.ts

@@ -195,6 +195,17 @@ interface MockupManifest {
     tokens?: string;
     screens: MockupScreen[];
 }
+interface ClarifyItem {
+    text: string;
+    line: number;
+    answer?: string;
+}
+interface ClarifyFile {
+    path: string;
+    open: ClarifyItem[];
+    resolved: ClarifyItem[];
+    diagnostics: Diagnostic[];
+}
 interface Change {
     slug: string;
     dir: string;
@@ -204,6 +215,9 @@ interface Change {
     verify?: VerifyFile;
     fix?: VerifyFile;
     fixCovers?: string[];
+    clarify?: ClarifyFile;
+    clarifyPath?: string;
+    docsPaths?: string[];
     planPath?: string;
     reviewPath?: string;
     presentationPath?: string;
@@ -295,6 +309,20 @@ declare const atlasConfigSchema: z.ZodObject<{
         }, {
             mode?: "off" | "advisory" | "blocking" | undefined;
         }>>;
+        clarify: z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<["off", "advisory", "blocking"]>>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "off" | "advisory" | "blocking";
+        }, {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        }>>;
+        docs: z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<["off", "advisory", "blocking"]>>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "off" | "advisory" | "blocking";
+        }, {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        }>>;
         mockup: z.ZodDefault<z.ZodObject<{
             require_approval: z.ZodDefault<z.ZodBoolean>;
             compare_in_verify: z.ZodDefault<z.ZodBoolean>;
@@ -319,6 +347,12 @@ declare const atlasConfigSchema: z.ZodObject<{
         review: {
             mode: "off" | "advisory" | "blocking";
         };
+        clarify: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        docs: {
+            mode: "off" | "advisory" | "blocking";
+        };
         mockup: {
             require_approval: boolean;
             compare_in_verify: boolean;
@@ -337,6 +371,12 @@ declare const atlasConfigSchema: z.ZodObject<{
         review?: {
             mode?: "off" | "advisory" | "blocking" | undefined;
         } | undefined;
+        clarify?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        docs?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
         mockup?: {
             require_approval?: boolean | undefined;
             compare_in_verify?: boolean | undefined;
@@ -452,6 +492,12 @@ declare const atlasConfigSchema: z.ZodObject<{
         review: {
             mode: "off" | "advisory" | "blocking";
         };
+        clarify: {
+            mode: "off" | "advisory" | "blocking";
+        };
+        docs: {
+            mode: "off" | "advisory" | "blocking";
+        };
         mockup: {
             require_approval: boolean;
             compare_in_verify: boolean;
@@ -515,6 +561,12 @@ declare const atlasConfigSchema: z.ZodObject<{
         review?: {
             mode?: "off" | "advisory" | "blocking" | undefined;
         } | undefined;
+        clarify?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
+        docs?: {
+            mode?: "off" | "advisory" | "blocking" | undefined;
+        } | undefined;
         mockup?: {
             require_approval?: boolean | undefined;
             compare_in_verify?: boolean | undefined;
@@ -803,6 +855,8 @@ declare function parseApprovals(raw: string, filePath: string): {
     diagnostics: Diagnostic[];
 };
 
+declare function parseClarify(content: string, filePath: string): ClarifyFile;
+
 interface GlossaryTerm {
     term: string;
     definition: string;
@@ -910,7 +964,7 @@ declare function planWaves(tasks: TasksFile, opts?: {
 }): WavePlan;
 declare function planBlock(block: TaskBlock, maxParallel: number): BlockWavePlan;
 
-type ChangeState = 'draft' | 'spec_draft' | 'awaiting_mockups' | 'awaiting_approval' | 'approved' | 'planned' | 'building' | 'built' | 'verified' | 'ready' | 'archived';
+type ChangeState = 'draft' | 'spec_draft' | 'awaiting_mockups' | 'awaiting_approval' | 'approved' | 'planned' | 'building' | 'built' | 'verified' | 'reviewed' | 'ready' | 'archived';
 interface NextAction {
     command: string;
     description: string;
@@ -946,6 +1000,9 @@ interface DeriveInput {
     specContent?: string;
 }
 declare function requiresMockups(meta: ChangeMeta | undefined, cfg: AtlasConfig): boolean;
+declare function docsReady(change: Change): boolean;
+declare function clarifyAdvisory(change: Change, cfg: AtlasConfig): Diagnostic[];
+declare function docsAdvisory(change: Change, cfg: AtlasConfig): Diagnostic[];
 declare function deriveState(input: DeriveInput): DerivedState;
 declare function stateLabel(state: ChangeState): string;
 
@@ -1125,6 +1182,8 @@ interface TemplateSet {
     tasks: string;
     verify: string;
     fix: string;
+    docTecnica: string;
+    docManual: string;
 }
 declare function templatesFor(language: Language): TemplateSet;
 declare function renderTemplate(template: string, vars: Record<string, string>): string;
@@ -1829,6 +1888,27 @@ interface WriteLivingFixResult {
 }
 declare function writeLivingFix(root: string, input: WriteLivingFixInput): Promise<WriteLivingFixResult>;
 
+type DocsTipo = 'tecnica' | 'manual' | 'all';
+declare const DOCS_MARKER_START = "<!-- specatlas:generado:inicio -->";
+declare const DOCS_MARKER_END = "<!-- specatlas:generado:fin -->";
+interface GenerateDocsOptions {
+    root: string;
+    slug: string;
+    tipo?: DocsTipo;
+    now?: Date;
+}
+interface GeneratedDoc {
+    tipo: 'tecnica' | 'manual';
+    path: string;
+    created: boolean;
+}
+interface GenerateDocsResult {
+    slug: string;
+    files: GeneratedDoc[];
+    diagnostics: Diagnostic[];
+}
+declare function generateDocs(opts: GenerateDocsOptions): Promise<GenerateDocsResult>;
+
 declare const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
 declare const SARIF_VERSION = "2.1.0";
 declare const TOOL_NAME = "SpecAtlas";
@@ -1928,4 +2008,4 @@ declare function livingRequirementsMap(specs: Array<{
 }>): Map<string, Requirement>;
 declare function runCiGate(opts: CiOptions): Promise<CiResult>;
 
-export { type AdoptDomain, type AdoptOptions, type AdoptResult, type AgingBucket, type AnalyzeOptions, type AnalyzePackSummary, type AnalyzeResult, type Approval, type ApprovalStatus, type ApprovalsFile, type ApprovalsIndex, type ApproveFromGithubOptions, type ApproveFromGithubResult, type ArchiveOptions, type ArchiveResult, type AtlasConfig, type AttentionItem, BACKUP_DIRNAME, BACKUP_POINTER, BLOCK_HEAD_RE, BUILTIN_PACKS, type BlockWavePlan, CONFIG_FILE, CORE_VERSION, type CaptureResult, type Change, type ChangeMeta, type ChangeMetrics, type ChangeState, type CiCheck, type CiExtraCheck, type CiOptions, type CiResult, type Delta, type DeltaOp, type DeriveInput, type DerivedState, type DetectionResult, type Diagnostic, type DoctorReport, type Domain, type Evidence, type EvidenceMethod, type EvidenceResult, type ExecOptions, type ExecResult, type FoldOutcome, type FrontmatterResult, type GhRunner, type GitHubRepo, type GlossaryTerm, type ImpactEvidence, type ImpactReport, type ImpactTask, type InitOptions, type InitResult, type IssueBodyInput, LIVING_FIXES_DIR, type Lane, type Language, type LinkedIssue, type LintOptions, type LivingFix, type LoadedConfig, type MigrationSpec, type MockupCheckResult, type MockupManifest, type MockupPlan, type MockupPlanScreen, type MockupScreen, type MoveOps, type NewChangeOptions, type NewChangeResult, type NextAction, type Override, type Pack, type PackCheck, type PackCheckResult, type PackCheckType, type PackEvaluation, type ParsedGlossary, type PresentOptions, type PresentResult, type ProfileMatch, REQ_HEAD_RE, REQ_ID_RE, RULE_ID_RE, RULE_RE, RUN_EVENT_TYPES, type RecordEvidenceOptions, type RecordEvidenceResult, type Rename, type Requirement, type RiskLevel, type Rule, type RunEvent, type RunEventType, type RunRecord, type RunState, type RunStatus, SARIF_SCHEMA, SARIF_VERSION, SCENARIO_HEAD_RE, SCENARIO_ID_RE, SCHEMA_MIGRATIONS, SCHEMA_VERSION, SDD_DIR, SLUG_RE, type SarifLocation, type SarifOptions, type SarifReport, type SarifResult, type SarifRule, type Scenario, type Severity, type SignApprovalOptions, type SignApprovalResult, type SpecFile, type SpecRef, type StackProfile, type SyncGithubOptions, type SyncGithubResult, TASK_ID_RE, TASK_LINE_RE, TOOL_NAME, TOOL_URL, type Task, type TaskBlock, type TasksFile, type TemplateSet, type TraceEdge, type TraceFinding, type TraceGraph, type TraceInput, type TraceNode, type TraceResult, type UpgradeAdvisory, type UpgradeApplyReport, type UpgradeBackupInfo, type UpgradeIssue, type UpgradeItem, type UpgradePlan, type UpgradeRollbackReport, type VerifyFile, type WalkEntry, type WavePlan, type Workspace, type WorkspaceMetrics, type WriteLivingFixInput, type WriteLivingFixResult, adoptWorkspace, appendRunEvent, applyUpgrade, approvalsSchema, approveFromGithub, archiveChange, artifactHash, atlasConfigSchema, buildTraceGraph, canonicalizeMarkdown, captureMockups, changeMarker, changeMetaSchema, changeMetaYaml, checkMockups, checkTrace, collectMetrics, collectVersionedArtifacts, commentIssue, compareTaskIds, computeInputsHash, configToYaml, copyFile, countBySeverity, createChange, createIssue, createRun, defaultConfig, deriveState, detectProfiles, detectRepo, detectionToYaml, diag, editIssue, emitFrontmatter, ensureDir, ensureSddDirs, esc, evaluatePacks, evidenceSummary, exists, findLinkedIssue, findWorkspaceRoot, firstToken, foldDelta, generatePresentation, generateRunId, getNumber, getString, ghAuthStatus, ghAvailable, hasErrors, hasShellMetacharacters, impactOfFile, impactOfRequirement, indexMarkdown, initWorkspace, inline, isCommandAllowed, isDirectory, issueBody, issueLabels, laneOrDefault, lintDelta, lintMockupHtml, lintMockupManifest, lintPlan, lintRequirement, lintSpec, lintTasks, lintVerify, listChangeSlugs, listDir, listDirs, listRuns, livingRequirementsMap, loadActiveProfile, loadApprovals, loadChange, loadConfig, loadDetectedBest, loadLivingFixes, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseConfig, parseDelta, parseFixCovers, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseLivingFix, parseRequirementBlocks, parseSpecFile, parseTasksFile, parseVerifyFile, patchChangeMeta, planBlock, planMockups, planUpgrade, planWaves, profileSchema, readArtifactVersion, readMockupManifest, readRun, readText, readTextIfExists, recordEvidence, regenerateIndex, renderMarkdown, renderRequirement, renderTemplate, requiresMockups, resolvePacks, rollbackUpgrade, ruleDescription, runAnalyze, runCiGate, runDoctor, runProcess, sarifLevel, setMockupRequirement, sha256, shortHash, signApproval, specHashOf, splitCommand, stampSchemaVersion, stateLabel, syncGithubIssue, templatesFor, toPosix, toSarifReport, toSarifText, tokensFile, updateMockupScreenshots, updateRunStatus, upgradeAdvisory, verifyApproval, walkFiles, writeConfig, writeLivingFix, writeMockupManifest, writeMockupPlan, writeText };
+export { type AdoptDomain, type AdoptOptions, type AdoptResult, type AgingBucket, type AnalyzeOptions, type AnalyzePackSummary, type AnalyzeResult, type Approval, type ApprovalStatus, type ApprovalsFile, type ApprovalsIndex, type ApproveFromGithubOptions, type ApproveFromGithubResult, type ArchiveOptions, type ArchiveResult, type AtlasConfig, type AttentionItem, BACKUP_DIRNAME, BACKUP_POINTER, BLOCK_HEAD_RE, BUILTIN_PACKS, type BlockWavePlan, CONFIG_FILE, CORE_VERSION, type CaptureResult, type Change, type ChangeMeta, type ChangeMetrics, type ChangeState, type CiCheck, type CiExtraCheck, type CiOptions, type CiResult, type ClarifyFile, type ClarifyItem, DOCS_MARKER_END, DOCS_MARKER_START, type Delta, type DeltaOp, type DeriveInput, type DerivedState, type DetectionResult, type Diagnostic, type DocsTipo, type DoctorReport, type Domain, type Evidence, type EvidenceMethod, type EvidenceResult, type ExecOptions, type ExecResult, type FoldOutcome, type FrontmatterResult, type GenerateDocsOptions, type GenerateDocsResult, type GeneratedDoc, type GhRunner, type GitHubRepo, type GlossaryTerm, type ImpactEvidence, type ImpactReport, type ImpactTask, type InitOptions, type InitResult, type IssueBodyInput, LIVING_FIXES_DIR, type Lane, type Language, type LinkedIssue, type LintOptions, type LivingFix, type LoadedConfig, type MigrationSpec, type MockupCheckResult, type MockupManifest, type MockupPlan, type MockupPlanScreen, type MockupScreen, type MoveOps, type NewChangeOptions, type NewChangeResult, type NextAction, type Override, type Pack, type PackCheck, type PackCheckResult, type PackCheckType, type PackEvaluation, type ParsedGlossary, type PresentOptions, type PresentResult, type ProfileMatch, REQ_HEAD_RE, REQ_ID_RE, RULE_ID_RE, RULE_RE, RUN_EVENT_TYPES, type RecordEvidenceOptions, type RecordEvidenceResult, type Rename, type Requirement, type RiskLevel, type Rule, type RunEvent, type RunEventType, type RunRecord, type RunState, type RunStatus, SARIF_SCHEMA, SARIF_VERSION, SCENARIO_HEAD_RE, SCENARIO_ID_RE, SCHEMA_MIGRATIONS, SCHEMA_VERSION, SDD_DIR, SLUG_RE, type SarifLocation, type SarifOptions, type SarifReport, type SarifResult, type SarifRule, type Scenario, type Severity, type SignApprovalOptions, type SignApprovalResult, type SpecFile, type SpecRef, type StackProfile, type SyncGithubOptions, type SyncGithubResult, TASK_ID_RE, TASK_LINE_RE, TOOL_NAME, TOOL_URL, type Task, type TaskBlock, type TasksFile, type TemplateSet, type TraceEdge, type TraceFinding, type TraceGraph, type TraceInput, type TraceNode, type TraceResult, type UpgradeAdvisory, type UpgradeApplyReport, type UpgradeBackupInfo, type UpgradeIssue, type UpgradeItem, type UpgradePlan, type UpgradeRollbackReport, type VerifyFile, type WalkEntry, type WavePlan, type Workspace, type WorkspaceMetrics, type WriteLivingFixInput, type WriteLivingFixResult, adoptWorkspace, appendRunEvent, applyUpgrade, approvalsSchema, approveFromGithub, archiveChange, artifactHash, atlasConfigSchema, buildTraceGraph, canonicalizeMarkdown, captureMockups, changeMarker, changeMetaSchema, changeMetaYaml, checkMockups, checkTrace, clarifyAdvisory, collectMetrics, collectVersionedArtifacts, commentIssue, compareTaskIds, computeInputsHash, configToYaml, copyFile, countBySeverity, createChange, createIssue, createRun, defaultConfig, deriveState, detectProfiles, detectRepo, detectionToYaml, diag, docsAdvisory, docsReady, editIssue, emitFrontmatter, ensureDir, ensureSddDirs, esc, evaluatePacks, evidenceSummary, exists, findLinkedIssue, findWorkspaceRoot, firstToken, foldDelta, generateDocs, generatePresentation, generateRunId, getNumber, getString, ghAuthStatus, ghAvailable, hasErrors, hasShellMetacharacters, impactOfFile, impactOfRequirement, indexMarkdown, initWorkspace, inline, isCommandAllowed, isDirectory, issueBody, issueLabels, laneOrDefault, lintDelta, lintMockupHtml, lintMockupManifest, lintPlan, lintRequirement, lintSpec, lintTasks, lintVerify, listChangeSlugs, listDir, listDirs, listRuns, livingRequirementsMap, loadActiveProfile, loadApprovals, loadChange, loadConfig, loadDetectedBest, loadLivingFixes, loadProfileFile, loadProfilesFromDir, loadProjectPacks, loadSpecs, loadWorkspace, localCompact, localDate, localMonth, localOffset, localStamp, matchGlob, mockupManifestSchema, mockupsDir, mockupsReady, moveDirectory, packFindings, parseApprovals, parseChangeMeta, parseClarify, parseConfig, parseDelta, parseFixCovers, parseFrontmatter, parseGitHubRemote, parseGlossary, parseIssueUrl, parseLivingFix, parseRequirementBlocks, parseSpecFile, parseTasksFile, parseVerifyFile, patchChangeMeta, planBlock, planMockups, planUpgrade, planWaves, profileSchema, readArtifactVersion, readMockupManifest, readRun, readText, readTextIfExists, recordEvidence, regenerateIndex, renderMarkdown, renderRequirement, renderTemplate, requiresMockups, resolvePacks, rollbackUpgrade, ruleDescription, runAnalyze, runCiGate, runDoctor, runProcess, sarifLevel, setMockupRequirement, sha256, shortHash, signApproval, specHashOf, splitCommand, stampSchemaVersion, stateLabel, syncGithubIssue, templatesFor, toPosix, toSarifReport, toSarifText, tokensFile, updateMockupScreenshots, updateRunStatus, upgradeAdvisory, verifyApproval, walkFiles, writeConfig, writeLivingFix, writeMockupManifest, writeMockupPlan, writeText };

package/dist/index.js

@@ -61,6 +61,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({}),
@@ -640,6 +642,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,}:?$/;
@@ -794,14 +825,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, path23, 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: path23,
           line,
           suggestion: "La especificaci\xF3n es funcional y de negocio: describe comportamiento, no tecnolog\xEDa ni adjetivos vagos"
         })
@@ -810,7 +841,7 @@ function lintText(text, code, terms, label, path22, line) {
   }
   return out;
 }
-function lintRequirement(req, path22, opts = {}) {
+function lintRequirement(req, path23, opts = {}) {
   const out = [];
   const vague = opts.language === "en" ? VAGUE_EN : VAGUE_ES;
   const tech = opts.language === "en" ? TECH_EN : TECH_ES;
@@ -821,32 +852,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", path23, 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", path23, 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: path23, line: req.line, suggestion: "A\xF1ade al menos un escenario CUANDO/ENTONCES" }));
   }
   return out;
 }
-function lintDelta(delta, livingRequirements, path22, opts = {}) {
+function lintDelta(delta, livingRequirements, path23, opts = {}) {
   const out = [...delta.diagnostics];
   for (const req of [...delta.added, ...delta.modified]) {
-    out.push(...lintRequirement(req, path22, opts));
+    out.push(...lintRequirement(req, path23, 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: path23, 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: path23,
             line: req.line,
             suggestion: "Copia el bloque completo de la spec viva y ed\xEDtalo; para quitarlo, decl\xE1ralo en REMOVED"
           })
@@ -857,15 +888,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: path23, 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: path23, 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: path23, line: rename2.line }));
     }
   }
   return out;
@@ -895,7 +926,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, path23) {
   const out = [];
   const blocks = [...planText.matchAll(/```mermaid\r?\n([\s\S]*?)```/g)];
   for (const [index, block] of blocks.entries()) {
@@ -905,7 +936,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: path23,
           suggestion: "Corrige el tipo del diagrama o elimina el bloque"
         })
       );
@@ -919,7 +950,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: path23,
           suggestion: "Cierra cada bloque alt/loop/opt/par/rect/subgraph con `end`"
         })
       );
@@ -931,7 +962,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: path23,
               suggestion: "Sustituye `;` por `\xB7` o `,` en los mensajes de sequenceDiagram"
             })
           );
@@ -1240,6 +1271,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 +1356,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 +1379,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) {
@@ -1328,6 +1396,7 @@ function stateLabel(state) {
     building: "construyendo",
     built: "construido",
     verified: "verificado",
+    reviewed: "revisado",
     ready: "listo para archivar",
     archived: "archivado"
   };
@@ -1668,6 +1737,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;
@@ -1884,6 +1966,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 +2129,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) {
@@ -4600,8 +4758,89 @@ async function upgradeAdvisory(root) {
   return { plan, diagnostics };
 }
 
-// src/sarif.ts
+// src/docs.ts
 import path19 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 = 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: [] };
+}
+
+// src/sarif.ts
+import path20 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 +4878,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) },
@@ -4689,7 +4928,7 @@ function toSarifText(opts) {
 }
 
 // src/doctor.ts
-import path20 from "path";
+import path21 from "path";
 async function runDoctor(root) {
   const findings = [];
   const { workspace, config } = await loadWorkspace(root);
@@ -4697,7 +4936,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")) {
@@ -4719,7 +4958,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") }));
       }
     }
   }
@@ -4742,7 +4981,7 @@ async function specHashOf(filePath) {
 }
 
 // src/gate.ts
-import path21 from "path";
+import path22 from "path";
 var UI_DOMAINS2 = /* @__PURE__ */ new Set(["frontend", "mobile", "fullstack"]);
 function count(name, diagnostics) {
   return {
@@ -4759,7 +4998,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 = [];
@@ -4770,7 +5009,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,
@@ -4820,6 +5059,8 @@ export {
   BUILTIN_PACKS,
   CONFIG_FILE,
   CORE_VERSION,
+  DOCS_MARKER_END,
+  DOCS_MARKER_START,
   LIVING_FIXES_DIR,
   REQ_HEAD_RE,
   REQ_ID_RE,
@@ -4854,6 +5095,7 @@ export {
   changeMetaYaml,
   checkMockups,
   checkTrace,
+  clarifyAdvisory,
   collectMetrics,
   collectVersionedArtifacts,
   commentIssue,
@@ -4872,6 +5114,8 @@ export {
   detectRepo,
   detectionToYaml,
   diag,
+  docsAdvisory,
+  docsReady,
   editIssue,
   emitFrontmatter,
   ensureDir,
@@ -4884,6 +5128,7 @@ export {
   findWorkspaceRoot,
   firstToken,
   foldDelta,
+  generateDocs,
   generatePresentation,
   generateRunId,
   getNumber,
@@ -4939,6 +5184,7 @@ export {
   packFindings,
   parseApprovals,
   parseChangeMeta,
+  parseClarify,
   parseConfig,
   parseDelta,
   parseFixCovers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specatlas/core",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Kernel determinista de SpecAtlas: parsing, validación, trazabilidad, olas y ciclo de vida",
   "license": "MIT",
   "type": "module",