@guilhermefsousa/open-spec-kit 0.1.0

package/src/schemas/spec.schema.js

@@ -0,0 +1,643 @@
+/**
+ * Zod schemas + 32 validation rules for spec artifacts.
+ *
+ * Each rule is a pure function:
+ *   Input: parsed data from markdown-sections parser
+ *   Output: { rule: number, pass: boolean, severity: 'ERROR'|'WARNING', message: string, details?: string[] }
+ *
+ * Rules 1-24, 28-32: per-spec
+ * Rules 25-27: cross-spec (implemented in validate.js)
+ */
+
+// --- Result helper ---
+
+function result(rule, pass, severity, message, details) {
+  return { rule, pass, severity, message, ...(details ? { details } : {}) };
+}
+
+// =============================================================================
+// RULES 1-7: Structure
+// =============================================================================
+
+const PRESET_ARTIFACTS = {
+  lean: ['brief.md', 'tasks.md'],
+  standard: ['brief.md', 'scenarios.md', 'contracts.md', 'tasks.md', 'links.md'],
+  enterprise: ['brief.md', 'scenarios.md', 'contracts.md', 'tasks.md', 'links.md'],
+};
+
+/**
+ * Rule 1: Required files exist per preset.
+ * @param {string[]} existingFiles - filenames that exist in the spec dir
+ * @param {string} preset
+ */
+export function rule01_requiredFiles(existingFiles, preset) {
+  const required = PRESET_ARTIFACTS[preset] || PRESET_ARTIFACTS.standard;
+  const missing = required.filter(f => !existingFiles.includes(f));
+  return result(1, missing.length === 0, 'ERROR',
+    missing.length === 0
+      ? `All ${required.length} required files present`
+      : `Missing files: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 2: Brief max 80 lines.
+ * @param {{ lineCount: number }} brief
+ */
+export function rule02_briefMaxLines(brief) {
+  return result(2, brief.lineCount <= 80, 'WARNING',
+    brief.lineCount <= 80
+      ? `Brief has ${brief.lineCount} lines (max 80)`
+      : `Brief has ${brief.lineCount} lines (max recommended: 80)`,
+  );
+}
+
+/**
+ * Rule 3: Brief has "Problema" section.
+ * @param {{ hasProblema: boolean }} brief
+ */
+export function rule03_briefHasProblema(brief) {
+  return result(3, brief.hasProblema, 'ERROR',
+    brief.hasProblema
+      ? 'Brief has "Problema" section'
+      : 'Brief missing "Problema" section — brief must start with the problem',
+  );
+}
+
+/**
+ * Rule 4: Brief has "Fora de Escopo" section.
+ * @param {{ hasForaDeEscopo: boolean }} brief
+ */
+export function rule04_briefHasForaDeEscopo(brief) {
+  return result(4, brief.hasForaDeEscopo, 'WARNING',
+    brief.hasForaDeEscopo
+      ? 'Brief has "Fora de Escopo" section'
+      : 'Brief missing "Fora de Escopo" section — recommended to define scope boundaries',
+  );
+}
+
+/**
+ * Rule 5: REQ-NNN format valid.
+ * @param {{ reqIds: string[] }} brief
+ */
+export function rule05_reqIdFormat(brief) {
+  const invalid = brief.reqIds.filter(id => !/^REQ-\d{3}$/.test(id));
+  return result(5, invalid.length === 0, 'ERROR',
+    invalid.length === 0
+      ? `All ${brief.reqIds.length} REQ IDs have valid format`
+      : `Invalid REQ ID format: ${invalid.join(', ')} (expected 3-digit zero-padded: REQ-001, REQ-011, NOT REQ-1 or REQ-11)`,
+    invalid.length > 0 ? invalid : undefined,
+  );
+}
+
+/**
+ * Rule 6: No duplicate REQ IDs in brief.
+ * @param {{ reqIds: string[] }} brief
+ */
+export function rule06_noDuplicateReqIds(brief) {
+  const seen = new Set();
+  const duplicates = [];
+  for (const id of brief.reqIds) {
+    if (seen.has(id)) duplicates.push(id);
+    seen.add(id);
+  }
+  return result(6, duplicates.length === 0, 'ERROR',
+    duplicates.length === 0
+      ? `No duplicate REQ IDs`
+      : `Duplicate REQ IDs: ${[...new Set(duplicates)].join(', ')}`,
+    duplicates.length > 0 ? [...new Set(duplicates)] : undefined,
+  );
+}
+
+/**
+ * Rule 7: CT-NNN-XX format valid on scenario headings.
+ * @param {{ allCtIds: string[] }} scenarios
+ */
+export function rule07_ctIdFormat(scenarios) {
+  const invalid = scenarios.allCtIds.filter(id => !/^CT-\d{3}-\d{2}$/.test(id));
+  return result(7, invalid.length === 0, 'ERROR',
+    invalid.length === 0
+      ? `All ${scenarios.allCtIds.length} CT IDs have valid format`
+      : `Invalid CT ID format: ${invalid.join(', ')} (expected CT-NNN-XX)`,
+    invalid.length > 0 ? invalid : undefined,
+  );
+}
+
+// =============================================================================
+// RULES 8-11: Traceability
+// =============================================================================
+
+/**
+ * Rule 8: Every REQ in brief has >= 1 CT in scenarios.
+ * REQs that are cross-spec references (contain "Usa", "Utiliza", "Ver contracts", etc.)
+ * are reported as WARNING instead of ERROR — they don't need their own scenarios.
+ */
+const REF_REQ_RE = /\b(usa\b|utiliza\b|referencia|reutiliza|ver contracts|definid[ao] em|já defini)/i;
+
+export function rule08_everyReqHasCt(brief, scenarios) {
+  const orphanReqs = brief.reqIds.filter(r => !scenarios.allReqRefs.includes(r));
+  if (orphanReqs.length === 0) {
+    return result(8, true, 'ERROR', `All ${brief.reqIds.length} REQs have scenarios`);
+  }
+
+  // Check if orphan REQs are cross-spec references (not behavioral)
+  const refOrphans = [];
+  const realOrphans = [];
+  for (const reqId of orphanReqs) {
+    const reqLineRe = new RegExp(`${reqId}[:\\s|]+(.+)`, 'i');
+    const match = (brief.rawContent || '').match(reqLineRe);
+    if (match && REF_REQ_RE.test(match[1])) {
+      refOrphans.push(reqId);
+    } else {
+      realOrphans.push(reqId);
+    }
+  }
+
+  if (realOrphans.length === 0 && refOrphans.length > 0) {
+    return result(8, true, 'WARNING',
+      `All behavioral REQs have scenarios (${refOrphans.length} cross-spec reference REQ(s) skipped: ${refOrphans.join(', ')})`,
+    );
+  }
+
+  return result(8, false, 'ERROR',
+    `REQs without scenarios: ${realOrphans.join(', ')}`,
+    realOrphans.length > 0 ? realOrphans : undefined,
+  );
+}
+
+/**
+ * Rule 9: Every CT references existing REQ from brief.
+ */
+export function rule09_everyCtRefsValidReq(brief, scenarios) {
+  const orphanRefs = scenarios.allReqRefs.filter(r => !brief.reqIds.includes(r));
+  const uniqueOrphans = [...new Set(orphanRefs)];
+  return result(9, uniqueOrphans.length === 0, 'ERROR',
+    uniqueOrphans.length === 0
+      ? `All CT references point to valid REQs`
+      : `CTs reference non-existent REQs: ${uniqueOrphans.join(', ')}`,
+    uniqueOrphans.length > 0 ? uniqueOrphans : undefined,
+  );
+}
+
+/**
+ * Rule 10: Every REQ in tasks has CT in scenarios.
+ */
+export function rule10_everyTaskReqHasCt(tasks, scenarios) {
+  const taskReqsWithoutCt = tasks.reqRefs.filter(r => !scenarios.allReqRefs.includes(r));
+  const unique = [...new Set(taskReqsWithoutCt)];
+  return result(10, unique.length === 0, 'WARNING',
+    unique.length === 0
+      ? `All task REQ references have corresponding CTs`
+      : `Task REQs without CT coverage: ${unique.join(', ')}`,
+    unique.length > 0 ? unique : undefined,
+  );
+}
+
+/**
+ * Rule 11: Every CT has >= 1 task referencing the REQ.
+ */
+export function rule11_everyCtHasTask(scenarios, tasks) {
+  const ctReqsWithoutTask = scenarios.allReqRefs.filter(r => !tasks.reqRefs.includes(r));
+  const unique = [...new Set(ctReqsWithoutTask)];
+  return result(11, unique.length === 0, 'WARNING',
+    unique.length === 0
+      ? `All CTs have tasks referencing their REQs`
+      : `CT REQs without tasks: ${unique.join(', ')}`,
+    unique.length > 0 ? unique : undefined,
+  );
+}
+
+// =============================================================================
+// RULES 12-15: Scenarios
+// =============================================================================
+
+/**
+ * Rule 12: Every scenario has Given.
+ * @param {{ scenarios: Array<{ id: string, hasGiven: boolean }> }} parsed
+ */
+export function rule12_scenarioHasGiven(parsed) {
+  const missing = parsed.scenarios.filter(s => !s.hasGiven).map(s => s.id);
+  return result(12, missing.length === 0, 'ERROR',
+    missing.length === 0
+      ? `All scenarios have Given`
+      : `Scenarios missing Given: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 13: Every scenario has When.
+ */
+export function rule13_scenarioHasWhen(parsed) {
+  const missing = parsed.scenarios.filter(s => !s.hasWhen).map(s => s.id);
+  return result(13, missing.length === 0, 'ERROR',
+    missing.length === 0
+      ? `All scenarios have When`
+      : `Scenarios missing When: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 14: Every scenario has Then.
+ */
+export function rule14_scenarioHasThen(parsed) {
+  const missing = parsed.scenarios.filter(s => !s.hasThen).map(s => s.id);
+  return result(14, missing.length === 0, 'ERROR',
+    missing.length === 0
+      ? `All scenarios have Then`
+      : `Scenarios missing Then: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 15: At least 1 scenario per REQ.
+ * @param {{ requirements: Array<{ id: string, scenarios: any[] }> }} parsed
+ */
+export function rule15_minOneScenarioPerReq(parsed) {
+  const empty = parsed.requirements.filter(r => r.scenarios.length === 0).map(r => r.id);
+  return result(15, empty.length === 0, 'ERROR',
+    empty.length === 0
+      ? `All REQs have at least 1 scenario`
+      : `REQs with 0 scenarios: ${empty.join(', ')}`,
+    empty.length > 0 ? empty : undefined,
+  );
+}
+
+// =============================================================================
+// RULES 16-20: Contracts
+// =============================================================================
+
+/**
+ * Rule 16: Contracts has content (endpoint OR entity OR event).
+ */
+export function rule16_contractsHasContent(contracts) {
+  const has = contracts.endpoints.length > 0 || contracts.entities.length > 0 || contracts.events.length > 0;
+  return result(16, has, 'ERROR',
+    has
+      ? `Contracts has ${contracts.endpoints.length} endpoints, ${contracts.entities.length} entities, ${contracts.events.length} events`
+      : `Contracts is empty — must have at least 1 endpoint, entity, or event`,
+  );
+}
+
+/**
+ * Rule 17: Contracts exist for each stack in projects.yml.
+ * @param {{ stackSections: string[] }} contracts - detected stack section headings
+ * @param {string[]} stacks - unique stacks from projects.yml repos
+ */
+const STACK_ALIASES = {
+  dotnet: ['c#', '.net', 'csharp', 'dotnet'],
+  nodejs: ['typescript', 'node', 'javascript', 'react', 'vue', 'angular', 'nodejs'],
+  java: ['java', 'spring', 'kotlin'],
+  python: ['python', 'fastapi', 'django', 'flask'],
+  react: ['react', 'typescript', 'frontend'],
+  go: ['go', 'golang'],
+};
+
+export function rule17_multiStackContracts(contracts, stacks) {
+  if (stacks.length <= 1) {
+    return result(17, true, 'WARNING', `Single stack — multi-stack check not applicable`);
+  }
+  const missing = stacks.filter(s => {
+    const aliases = STACK_ALIASES[s.toLowerCase()] || [s.toLowerCase()];
+    return !contracts.stackSections.some(sec =>
+      aliases.some(alias => sec.toLowerCase().includes(alias)),
+    );
+  });
+  return result(17, missing.length === 0, 'WARNING',
+    missing.length === 0
+      ? `Contracts cover all ${stacks.length} stacks`
+      : `Missing contracts for stacks: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 18: Editable entity has createdAt + updatedAt.
+ * Only checks entities that have PUT/PATCH endpoints (editable).
+ * Junction tables, logs, snapshots, and append-only entities are skipped.
+ */
+export function rule18_entityHasTimestamps(contracts) {
+  const CREATED_RE = /created_?at|criado_?em|data_?cria[cç][aã]o|date_?created/i;
+  const UPDATED_RE = /updated_?at|atualizado_?em|data_?atualiza[cç][aã]o|date_?updated|modified_?at/i;
+
+  // Build set of editable entity patterns from PUT/PATCH endpoints
+  const editablePatterns = contracts.endpoints
+    .filter(e => /put|patch/i.test(e.metodo || e.method || e['método'] || ''))
+    .map(e => (e.rota || e.route || '').replace(/`/g, '').replace(/\{[^}]+\}/g, ''))
+    .map(route => {
+      const match = route.match(/\/api\/([a-z-]+)/i);
+      return match ? match[1].toLowerCase().replace(/-/g, '').replace(/s$/, '') : null;
+    })
+    .filter(Boolean);
+
+  const failures = [];
+  const skipped = [];
+
+  for (const entity of contracts.entities) {
+    const entityNameNorm = entity.name.toLowerCase().replace(/[^a-z]/g, '');
+
+    // Check if entity is editable (has PUT/PATCH endpoint)
+    // Only check forward direction: entity name contains route pattern
+    // e.g., "planomodalidade" includes "plano" → editable (defensible)
+    // Reverse direction removed: "log" inside "logistica" = false positive
+    const isEditable = editablePatterns.some(p => entityNameNorm.includes(p));
+
+    if (!isEditable) {
+      skipped.push(entity.name);
+      continue;
+    }
+
+    const fieldNames = entity.fields.map(f => f.campo);
+    const fullContent = entity.fullContent || '';
+    const hasCreated = fieldNames.some(n => CREATED_RE.test(n)) || CREATED_RE.test(fullContent);
+    const hasUpdated = fieldNames.some(n => UPDATED_RE.test(n)) || UPDATED_RE.test(fullContent);
+    if (!hasCreated || !hasUpdated) {
+      const missing = [];
+      if (!hasCreated) missing.push('createdAt/CriadoEm');
+      if (!hasUpdated) missing.push('updatedAt/AtualizadoEm');
+      failures.push(`${entity.name}: missing ${missing.join(', ')}`);
+    }
+  }
+
+  const checkedCount = contracts.entities.length - skipped.length;
+  const skippedMsg = skipped.length > 0 ? ` (${skipped.length} non-editable skipped: ${skipped.join(', ')})` : '';
+
+  return result(18, failures.length === 0, 'ERROR',
+    failures.length === 0
+      ? checkedCount === 0
+        ? `No editable entities (no PUT/PATCH endpoints) — rule not applicable${skippedMsg}`
+        : `All ${checkedCount} editable entities have timestamp fields${skippedMsg}`
+      : `Editable entities missing audit fields: ${failures.join('; ')}${skippedMsg}`,
+    failures.length > 0 ? failures : undefined,
+  );
+}
+
+/**
+ * Rule 19: Auth 401 scenario exists if authenticated endpoint.
+ */
+export function rule19_auth401Scenario(contracts, scenariosRaw) {
+  const authEndpoints = contracts.endpoints.filter(e => {
+    // Flexible column name: autenticado, auth, authenticated, etc.
+    const authKey = Object.keys(e).find(k => /autenticad|auth/i.test(k));
+    const authValue = e.autenticado || e.auth || e.authenticated || e['requer auth']
+      || (authKey ? e[authKey] : '') || '';
+    return /sim|yes|true|✓|✅|x/i.test(String(authValue));
+  });
+
+  if (authEndpoints.length === 0) {
+    return result(19, true, 'ERROR', `No authenticated endpoints — rule not applicable`);
+  }
+
+  const has401 = /401|NAO_AUTORIZADO|UNAUTHORIZED|sem token|without token/i.test(scenariosRaw);
+  return result(19, has401, 'ERROR',
+    has401
+      ? `401 scenario found for ${authEndpoints.length} authenticated endpoints`
+      : `${authEndpoints.length} authenticated endpoints but no 401/unauthorized scenario found`,
+  );
+}
+
+/**
+ * Rule 20: Pagination scenarios if PaginatedResponse.
+ */
+export function rule20_paginationScenarios(contractsRaw, scenariosRaw, contracts) {
+  // Check if any endpoint USES pagination (not just defines the type as shared)
+  const endpointDescriptions = (contracts?.endpoints || []).map(e =>
+    `${e.descricao || e['descrição'] || ''} ${e.rota || e.route || ''} ${e.retorno || e.response || ''}`,
+  ).join(' ');
+  const hasPaginatedEndpoint = /PaginatedResponse|pageSize|page_size|PagedResult|paginad|listagem/i.test(endpointDescriptions);
+  const hasPagination = hasPaginatedEndpoint || /PaginatedResponse|pageSize|page_size|PagedResult/i.test(contractsRaw);
+
+  if (!hasPaginatedEndpoint && !hasPagination) {
+    return result(20, true, 'WARNING', `No pagination types found — rule not applicable`);
+  }
+  if (hasPagination && !hasPaginatedEndpoint) {
+    return result(20, true, 'WARNING', `PaginatedResponse defined as shared type but no paginated endpoints in this spec`);
+  }
+
+  const hasPaginationScenario = /pagina|pagination|page|default.*page|last.*page|invalid.*page/i.test(scenariosRaw);
+  return result(20, hasPaginationScenario, 'WARNING',
+    hasPaginationScenario
+      ? `Pagination scenarios found`
+      : `PaginatedResponse in contracts but no pagination scenarios found`,
+  );
+}
+
+// =============================================================================
+// RULES 21-24: Tasks & Links
+// =============================================================================
+
+/**
+ * Rule 21: Task ## headings reference repos from projects.yml.
+ */
+export function rule21_taskReposMatchProjects(tasks, repoNames) {
+  if (tasks.repoHeadings.length === 0) {
+    return result(21, false, 'WARNING', `No repo headings (##) found in tasks.md`);
+  }
+  if (repoNames.length === 0) {
+    return result(21, true, 'WARNING', `projects.yml has no repos — cannot validate task headings`);
+  }
+
+  const unknown = tasks.repoHeadings.filter(h => !repoNames.some(rn => h.includes(rn)));
+  return result(21, unknown.length === 0, 'WARNING',
+    unknown.length === 0
+      ? `All ${tasks.repoHeadings.length} task repo headings match projects.yml`
+      : `Task repos not in projects.yml: ${unknown.join(', ')}`,
+    unknown.length > 0 ? unknown : undefined,
+  );
+}
+
+/**
+ * Rule 22: Audit report has no failures (if exists).
+ * @param {string|null} auditContent - null if file doesn't exist
+ */
+export function rule22_auditReportClean(auditContent) {
+  if (auditContent === null) {
+    return result(22, true, 'WARNING', `audit-report.md not found (generated by /spec)`);
+  }
+  const hasFail = auditContent.includes('❌');
+  return result(22, !hasFail, 'ERROR',
+    hasFail
+      ? `audit-report.md contains failures (❌)`
+      : `audit-report.md is clean`,
+  );
+}
+
+/**
+ * Rule 23: links.md contains Confluence URL.
+ */
+export function rule23_linksHasUrl(linksContent) {
+  const hasUrl = /https?:\/\//.test(linksContent);
+  return result(23, hasUrl, 'WARNING',
+    hasUrl
+      ? `links.md contains URL reference`
+      : `links.md has no URL — should link to Confluence feature page`,
+  );
+}
+
+/**
+ * Rule 24: links.md has PR table with correct headers.
+ */
+export function rule24_linksPrTableHeaders(linksContent) {
+  // Check that a table header line contains Repo, PR/MR (any variant), and Status
+  const headerLine = linksContent.split('\n').find(l => /\|\s*Repo\b/i.test(l));
+  const hasPrTable = headerLine
+    ? (/\b(MR\/PR|PR\/MR|PR|MR)\b/i.test(headerLine) && /\bStatus\b/i.test(headerLine))
+    : false;
+  return result(24, hasPrTable, 'WARNING',
+    hasPrTable
+      ? `links.md has PR tracking table`
+      : `links.md missing PR tracking table (expected: Repo | PR/MR | Status)`,
+  );
+}
+
+// =============================================================================
+// RULES 28-32: Spec Hygiene
+// =============================================================================
+
+/**
+ * Rule 28: No unresolved markers in spec artifacts.
+ * @param {string[]} contents - raw content of brief, scenarios, contracts
+ */
+export function rule28_noUnresolvedMarkers(contents) {
+  // TODO separado sem flag i — evita falso positivo com "Método" (é é \W em JS, \b casa entre é e t)
+  const MARKER_RE = /\b(MOCKADO|A CONFIRMAR|TBD|FIXME|PLACEHOLDER|TKTK)\b/gi;
+  const TODO_RE = /\bTODO\b/g;
+  const allMarkers = [];
+  for (const content of contents) {
+    const matches = content.match(MARKER_RE) || [];
+    const todoMatches = content.match(TODO_RE) || [];
+    allMarkers.push(...matches, ...todoMatches);
+  }
+  const unique = [...new Set(allMarkers.map(m => m.toUpperCase()))];
+  return result(28, unique.length === 0, 'ERROR',
+    unique.length === 0
+      ? `No unresolved markers found`
+      : `Unresolved markers found: ${unique.join(', ')} — resolve before /dev`,
+    unique.length > 0 ? unique : undefined,
+  );
+}
+
+/**
+ * Rule 29: Spec directory follows NNN-kebab-case.
+ * @param {string} dirName
+ */
+export function rule29_specDirNaming(dirName) {
+  // Accept NNN-kebab-case (e.g. 001-consumer-shipment) OR SIGLA-NNN[-suffix] (e.g. TD-001, PROJ-002-auth)
+  const valid = /^\d{3}-[a-z0-9]+(-[a-z0-9]+)*$/.test(dirName)
+             || /^[A-Z]+-\d{3}(-[a-zA-Z0-9]+)*$/.test(dirName);
+  return result(29, valid, 'ERROR',
+    valid
+      ? `Spec directory "${dirName}" follows naming convention`
+      : `Spec directory "${dirName}" invalid — must be NNN-kebab-case (e.g., 001-consumer-shipment) or SIGLA-NNN (e.g., TD-001)`,
+  );
+}
+
+/**
+ * Rule 30: Spec numbers are unique (no duplicates).
+ * @param {string[]} allDirNames - all spec directory names
+ */
+export function rule30_specNumbersUnique(allDirNames) {
+  const numbers = allDirNames.map(d => d.match(/^(\d{3})/)?.[1]).filter(Boolean);
+  const seen = new Set();
+  const duplicates = [];
+  for (const n of numbers) {
+    if (seen.has(n)) duplicates.push(n);
+    seen.add(n);
+  }
+  const unique = [...new Set(duplicates)];
+  return result(30, unique.length === 0, 'ERROR',
+    unique.length === 0
+      ? `All spec numbers are unique`
+      : `Duplicate spec numbers: ${unique.join(', ')}`,
+    unique.length > 0 ? unique : undefined,
+  );
+}
+
+/**
+ * Rule 31: Every endpoint in table has response example in contracts.
+ */
+export function rule31_endpointsHaveResponseExample(contracts) {
+  if (contracts.endpoints.length === 0) {
+    return result(31, true, 'WARNING', `No endpoints — rule not applicable`);
+  }
+
+  const missing = [];
+  for (const ep of contracts.endpoints) {
+    const route = (ep.rota || ep.route || '').replace(/`/g, '').trim();
+    if (!route) continue;
+    // Check if the route path appears in a code block or example section
+    const routeEscaped = route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const routeRe = new RegExp(routeEscaped, 'i');
+    // Look beyond the endpoint table itself — in code blocks or example sections
+    if (!routeRe.test(contracts.examplesContent || '')) {
+      missing.push(route);
+    }
+  }
+
+  return result(31, missing.length === 0, 'WARNING',
+    missing.length === 0
+      ? `All ${contracts.endpoints.length} endpoints have response examples`
+      : `Endpoints without response examples: ${missing.join(', ')}`,
+    missing.length > 0 ? missing : undefined,
+  );
+}
+
+/**
+ * Rule 32: No duplicate scenario headings in same spec.
+ */
+export function rule32_noDuplicateScenarioHeadings(scenarios) {
+  const titles = scenarios.scenarios.map(s => s.title);
+  const seen = new Set();
+  const duplicates = [];
+  for (const t of titles) {
+    if (seen.has(t)) duplicates.push(t);
+    seen.add(t);
+  }
+  const unique = [...new Set(duplicates)];
+  return result(32, unique.length === 0, 'ERROR',
+    unique.length === 0
+      ? `No duplicate scenario headings`
+      : `Duplicate scenario headings: ${unique.join(', ')}`,
+    unique.length > 0 ? unique : undefined,
+  );
+}
+
+// =============================================================================
+// RULE 33: Exit gate — open decisions in architecture.md
+// =============================================================================
+
+/**
+ * Rule 33: No blocking open decisions in architecture.md.
+ * @param {string|null} architectureContent - null if file doesn't exist
+ */
+export function rule33_openDecisions(architectureContent) {
+  if (!architectureContent) {
+    return result(33, true, 'WARNING', `docs/architecture.md not found — skipping decision check`);
+  }
+
+  const lines = architectureContent.split('\n');
+  const blocking = [];
+
+  for (const line of lines) {
+    if (/\|\s*aberta\s*\|/i.test(line) && /\/spec|\/dev/i.test(line)) {
+      const cells = line.split('|').map(c => c.trim()).filter(Boolean);
+      blocking.push(cells[1] || line.trim());
+    }
+  }
+
+  return result(33, blocking.length === 0, 'WARNING',
+    blocking.length === 0
+      ? `No blocking open decisions in architecture.md`
+      : `${blocking.length} open decision(s) in architecture.md. Review before proceeding — some may block spec or dev: ${blocking.join('; ')}`,
+    blocking.length > 0 ? blocking : undefined,
+  );
+}
+
+// =============================================================================
+// EXPORTS: Preset artifacts config (used by validate.js)
+// =============================================================================
+
+export { PRESET_ARTIFACTS };