@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/risk-detector.js

@@ -1,81 +1,24 @@
-/**
- * Risk Detector — decides whether a gate should pause execution.
- *
- * In `trust: "auto"` mode (default), gates auto-pass UNLESS one of these
- * risk signals triggers a forced pause. In `trust: "manual"` mode, gates
- * always pause via AskUserQuestion.
- *
- * Signals checked (in order):
- *   - designSystemDivergence: boolean — conflicting design sources detected
- *   - standardsViolations: string[]   — violations of the plan's forbidden patterns
- *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa, qualquer gate)
- *   - e2eStatus + e2eReason + gate    — nó e2e do último verify. Um `skip`
- *     cuja razão NÃO seja dispensa legítima pausa SÓ no ship (gate 'review')
- *   - verificationStale + gate: bool/str — stamp de um commit cujo código já mudou
- *     (fora de .morph/) pausa SÓ no ship (gate 'review')
- *   - reviewReports + gate: object    — `reviewSignal` (review-reports.js): os
- *     relatórios exigidos e a cobertura dos Cn. No ship, só SHIP sem bloqueador
- *     em todo exigido, com todo Cn PROVADO, libera
- *   - mediaClaims + gate: object      — { section, featureGeneratesMedia }
- *   - screenChecklist + gate: object  — { mockups, legacy, screens, problems, exempt?,
- *     section?, uncovered? } derivado do 1-design/mockups.md. No uiux, checklist
- *     de tela incompleto pausa; no ship, item decidido sem a conferência do
- *     verificador pausa. Mockup legado é isento nos dois, com a razão listada
- *   - planChecks + gate: string       — `readPlanChecks(...).status`: os checks
- *     extraídos contra o plano; no gate do plano, tudo que não é `fresh` pausa
- *   - sliceCount: number              — fatias extraídas (pausa acima de MAX_SLICES)
- */
-
 import { MAX_SLICES } from './plan/checks.js';
 import { BLOCKER_TYPES, reviewFileName } from './review-reports.js';
 
-// Caminho alterado que pede a revisão de segurança (persona `security`, opus).
 const SECURITY_PATH_RE = /(^|[/._-])(auth|login|senha|password|token|secret|crypto|permiss|rbac|acl|lgpd|pii|privacy|payment|pagamento|billing|cobranca|invoice|asaas|stripe|migrations?)([/._-]|$)/i;
 
-// Work types whose ship gate (review) always pauses for a human, regardless
-// of trust mode — a type policy, not a per-feature risk signal. Mirrors
-// `forcedPauseGates` in src/core/work-types.js (hotfix.review); kept here too
-// because risk-detector is the deterministic layer consumed independent of
-// the work-type config object.
+// Espelha `forcedPauseGates` (hotfix.review) de src/core/work-types.js: os dois mudam juntos.
 const FORCED_PAUSE_WORK_TYPES = ['hotfix'];
 
-// As razões literais que `framework/hooks/shared/e2e-check.js` emite quando o
-// nó e2e pula. Casadas por PADRÃO e não por igualdade porque duas delas
-// carregam dado variável (o nome do grupo da task). Ordem irrelevante: os
-// padrões são disjuntos.
+// Razões literais que `e2e-check.js` emite ao pular; casadas por padrão porque algumas carregam dado variável.
 const E2E_SKIP_PATTERNS = [
-  // "docker is not available in this environment — e2e could not run"
-  // (e2e-check.js). A app não foi exercida porque a MÁQUINA não podia.
   [/docker is not available/i, 'environment'],
-  // `--skip-e2e` — o operador pediu para pular.
   [/^requested$/i, 'requested'],
-  // "project does not containerize (no compose file)" — não há app para subir.
   [/does not containerize/i, 'project'],
+  [/^not applicable:/i, 'not-applicable'],
 ];
 
-// Classes de skip que NÃO são dispensa: o e2e não rodou e nada no repositório
-// diz que ele não precisava rodar. `unknown` está aqui de propósito — inclui a
-// razão vazia/nula, e uma dispensa sem motivo é o mesmo no-op silencioso que
-// esta regra existe para eliminar.
+// `unknown` (razão vazia) pausa de propósito: dispensa sem motivo é o no-op silencioso que a regra elimina.
 const E2E_SKIP_CLASSES_THAT_PAUSE = ['environment', 'requested', 'unknown'];
 
-/**
- * Classifica a razão literal de um `skip` do nó e2e — de QUEM é a ausência de
- * prova. Existe porque `verificationStatus` é o rollup do `verify` e um nó que
- * pula NÃO o reprova: sem classificar a razão, "o e2e rodou e passou" e "o e2e
- * nunca rodou" chegam ao gate como o mesmo `pass`.
- *
- * A assimetria é o ponto: `project` descreve o REPOSITÓRIO dizendo que
- * não há runtime a exercer (dispensa legítima, registrada com motivo);
- * `environment`/`requested` descrevem a MÁQUINA ou o operador, e nenhum dos
- * dois é evidência sobre o código. `unknown` cai no lado seguro pelo mesmo
- * motivo: recusar é barato, aprovar sem prova não é.
- *
- * @param {string|null|undefined} reason - `verification.e2eReason` (a razão
- *   literal que o `morph-spec verify` carimbou). Vazia/ausente ⇒ 'unknown' —
- *   DESCONHECIDO, jamais lido como dispensa.
- * @returns {'environment'|'requested'|'project'|'unknown'}
- */
+// `project` diz que o repositório não tem runtime (dispensa legítima); `environment`/`requested` falam
+// da máquina ou do operador, nunca do código. Razão vazia é `unknown`, jamais dispensa.
 export function classifyE2eSkip(reason) {
   const text = typeof reason === 'string' ? reason.trim() : '';
   if (text === '') return 'unknown';
@@ -85,7 +28,6 @@ export function classifyE2eSkip(reason) {
   return 'unknown';
 }
 
-/** Mensagem de pausa por classe — nomeia SEMPRE a razão literal do verify. */
 function e2ePauseReason(klass, reason) {
   const literal = typeof reason === 'string' && reason.trim() !== '' ? reason.trim() : null;
   if (klass === 'environment') {
@@ -102,38 +44,32 @@ function e2ePauseReason(klass, reason) {
   return `e2e pulado por razão não classificada: "${literal}" — sem classificação, não há dispensa`;
 }
 
-/** A razão gravada no sinal quando o checklist de tela isenta um mockup legado. */
 export const LEGACY_MOCKUP_EXEMPTION = 'checklist dispensado: mockup no formato antigo';
 
-/** Os dois primeiros itens de uma lista, e quantos ficaram de fora. */
 function firstOf(items) {
   const shown = items.slice(0, 2).join('; ');
   return items.length > 2 ? `${shown} (+${items.length - 2})` : shown;
 }
 
-/**
- * Por que o checklist de tela pausa o Gate uiux, ou null. Exportada porque o
- * `approve`/`advance` com assinatura `auto` recusam pela MESMA regra: uma
- * aprovação automática que passasse onde o gate-check pausa seria o atalho.
- *
- * Mockup ausente (`mockups: false`) não conta — nem toda feature de UI tem
- * tela —, e o legado chega sem problemas: a auditoria o isenta.
- *
- * @param {object|undefined} screenChecklist - o sinal de `collectScreenChecklist`
- * @returns {string|null}
- */
+// Exportada porque approve/advance `auto` recusam pela mesma regra. Sem design de tela não conta,
+// e o legado chega sem problemas: a auditoria o isenta. Checklist
+// completo ainda deve o protótipo e os prints 1280/390 (`prototypes`).
 export function uiuxChecklistPause(screenChecklist) {
   if (screenChecklist?.mockups !== true) return null;
   const problems = screenChecklist.problems ?? [];
-  if (problems.length === 0) return null;
-  return `checklist de tela incompleto em 1-design/mockups.md: ${firstOf(problems)}`
-       + ' — volume, paginação, ordenação, filtro, os três estados, mobile e abas por tela'
-       + ' ("não se aplica" vale, se escrito)';
+  if (problems.length > 0) {
+    return `checklist de tela incompleto em 1-design/mockups.md: ${firstOf(problems)}`
+         + ' — volume, paginação, ordenação, filtro, os três estados, mobile e abas por tela'
+         + ' ("não se aplica" vale, se escrito)';
+  }
+  const prototypes = screenChecklist.prototypes ?? [];
+  if (prototypes.length === 0) return null;
+  return `protótipo incompleto: ${firstOf(prototypes)}`
+       + ' — cada tela aponta o HTML renderizado e deixa os prints de 1280 e 390 ao lado dele';
 }
 
 const ROLE_PERSONA = { verifier: 'morph-verifier', reviewer: 'morph-reviewer', security: 'morph-security' };
 
-/** Por que os relatórios de review seguram o ship, ou null. */
 export function reviewPause(signal) {
   const required = signal?.required ?? ['verifier'];
   const reports = signal?.reports ?? {};
@@ -164,6 +100,7 @@ export function reviewPause(signal) {
     if (r.verdict !== 'SHIP') return `veredito do ${role} é ${r.verdict}`;
   }
   const checks = signal?.checks;
+  if (checks?.status === 'not-required') return null;
   if (!checks || checks.status !== 'ok') {
     return 'sem `2-plan/checks.json` legível — a cobertura dos cenários pelo verificador não é conferível';
   }
@@ -190,14 +127,7 @@ function reviewSummary(signal) {
   return `review: ${verdicts}; ${blockers} bloqueador(es)${checks}`;
 }
 
-/**
- * Modelo do verificador: `opus` quando a feature mexe em prompt/modelo ou
- * gera mídia; `sonnet` no resto. Caminho sensível não muda o verificador:
- * despacha a persona `security` ({@link securityReviewFor}).
- *
- * @param {{ promptModelTouched?: boolean, generatesMedia?: boolean }} input
- * @returns {{ model: 'opus'|'sonnet', reasons: string[] }}
- */
+// Caminho sensível não muda o verificador: despacha a persona `security` (`securityReviewFor`).
 export function verifierModelFor({ promptModelTouched = false, generatesMedia = false } = {}) {
   const reasons = [];
   if (promptModelTouched) reasons.push('prompt/modelo alterado');
@@ -205,13 +135,6 @@ export function verifierModelFor({ promptModelTouched = false, generatesMedia =
   return { model: reasons.length ? 'opus' : 'sonnet', reasons };
 }
 
-/**
- * A revisão de segurança é exigida quando o diff toca auth, segredo,
- * permissão, dado pessoal, pagamento ou migration.
- *
- * @param {string[]} changedFiles
- * @returns {{ required: boolean, reasons: string[] }}
- */
 export function securityReviewFor(changedFiles = []) {
   const risky = changedFiles.filter((f) => SECURITY_PATH_RE.test(f.replaceAll('\\', '/')));
   return { required: risky.length > 0, reasons: risky.length ? [`caminho sensível: ${firstOf(risky)}`] : [] };
@@ -224,27 +147,13 @@ const PLAN_CHECKS_REASONS = {
   stale: '2-plan/checks.json não corresponde ao plan.md atual',
 };
 
-/**
- * Por que o gate do plano não fecha sem pessoa: os checks extraídos são o que
- * o apply despacha, o report-check confere e a review cobra — um plano sem
- * eles, ou com os de outra versão do plano, aprovaria critérios que ninguém
- * extraiu.
- * Regra única do gate-check (pausa) e do approve/advance automáticos (recusa).
- *
- * @param {string|undefined} status - `readPlanChecks(...).status`
- * @returns {string|null}
- */
+// Regra única do gate-check (pausa) e do approve/advance automáticos (recusa).
 export function planChecksPause(status) {
   if (status === undefined || status === 'fresh') return null;
   const what = PLAN_CHECKS_REASONS[status] ?? `checks.json em estado "${status}"`;
   return `${what} — rode \`morph-spec plan-check {feature}\` até zero erro antes do gate do plano`;
 }
 
-/**
- * @param {object} config - .morph/config/config.json contents (uses `trust`)
- * @param {object} signals
- * @returns {{ pause: boolean, reason: string }}
- */
 export function shouldPauseGate(config, signals) {
   const trust = config?.trust ?? 'auto';
 
@@ -270,10 +179,7 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
-  // Verify vermelho no momento do gate = a barreira determinística (build/
-  // testes/validadores) está falhando — código antes do juiz vale também
-  // para a decisão de pausa. Só 'fail' pausa: ausência de stamp não é sinal
-  // (features antigas não têm o campo).
+  // Só 'fail' pausa aqui: features antigas não têm o stamp.
   if (signals.verificationStatus === 'fail') {
     return {
       pause: true,
@@ -281,7 +187,7 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
-  // No ship, ausência de stamp não é "verde": uma feature foi aprovada em campo sem verify nenhum.
+  // No ship, ausência de stamp não é verde.
   if (signals.gate === 'review' && !signals.verificationStatus) {
     return {
       pause: true,
@@ -289,16 +195,8 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
-  // No gate de SHIP apenas: o nó e2e do último verify PULOU. Um skip não
-  // reprova o rollup, então `verificationStatus` sai 'pass' e o gate ficava
-  // cego — auto-passando um Gate 3 sobre uma app que ninguém subiu. A razão
-  // literal decide: dispensa legítima (o projeto não containeriza) passa e
-  // fica REGISTRADA nos signals; ausência de
-  // prova (docker indisponível, `--skip-e2e`, razão nenhuma) pausa. É a prosa
-  // do morph-review virando regra — "docker indisponível não é dispensa" — e
-  // é o que dispensa o `gate-decision --pause false` manual que ela mandava
-  // rodar. Só no review: pausar o Gate 1/2 numa máquina sem docker travaria
-  // trabalho legítimo de planejamento.
+  // Skip não reprova o rollup, então só a razão literal separa dispensa de ausência de prova.
+  // Só no ship: pausar plan/uiux numa máquina sem docker travaria planejamento legítimo.
   if (signals.gate === 'review' && signals.e2eStatus === 'skip') {
     const klass = classifyE2eSkip(signals.e2eReason);
     if (E2E_SKIP_CLASSES_THAT_PAUSE.includes(klass)) {
@@ -306,13 +204,7 @@ export function shouldPauseGate(config, signals) {
     }
   }
 
-  // Furo 2: no gate de SHIP (review) apenas, um stamp de verification cujo
-  // sha diverge do HEAD atual significa que código mudou depois do último
-  // `morph-spec verify` — o resultado carimbado não cobre mais o que está
-  // prestes a ser aprovado. Pausa só aqui, nunca em plan/uiux: essa
-  // é uma regra de ship, não uma regra geral de gate. Stamp AUSENTE não entra
-  // aqui (verificationStale é fail-open para `false` em collectSignals
-  // quando não há stamp) — features legadas sem stamp continuam liberadas.
+  // Regra de ship, não de gate em geral; stamp ausente é fail-open (`false`) em collectSignals.
   if (signals.gate === 'review' && signals.verificationStale === true) {
     return {
       pause: true,
@@ -325,18 +217,9 @@ export function shouldPauseGate(config, signals) {
     if (reason) return { pause: true, reason };
   }
 
-  // No gate de SHIP apenas: a feature mexeu num caminho que o PROJETO declarou
-  // como prompt ou modelo, e não há eval verde carimbado. Prompt e modelo são a
-  // única parte do produto cujo comportamento não é lido por build nem por teste
-  // unitário: os dois continuam verdes com o prompt trocado.
-  //
-  // DEPOIS dos relatórios de review, de propósito: relatório ausente é o
-  // defeito mais grave dos dois e é a razão reportada.
-  //
-  // PAUSA, jamais bloqueia: `approve review` não ganha precondição nova. Uma
-  // segunda precondição dura ali tornaria inaprovável, inclusive por decisão
-  // humana, toda feature legada. Pausa é a severidade certa — o humano lê a
-  // razão e decide.
+  // Prompt e modelo não são lidos por build nem por teste. Depois dos relatórios de review de propósito:
+  // relatório ausente é o defeito mais grave. Pausa, nunca bloqueia: bloquear tornaria inaprovável
+  // toda feature legada.
   if (signals.gate === 'review' && (signals.promptModel?.touched?.length ?? 0) > 0) {
     const touched = signals.promptModel.touched;
     const where = `${touched.slice(0, 3).join(', ')}${touched.length > 3 ? ` (+${touched.length - 3})` : ''}`;
@@ -358,9 +241,7 @@ export function shouldPauseGate(config, signals) {
               + ' — rode `morph-spec verify {feature}` (escopo de feature) antes do ship',
       };
     }
-    // 'fail' cai fora: um eval vermelho já avermelha o rollup e a regra de
-    // `verificationStatus` acima pausou antes daqui. 'pass' com stamp velho
-    // também já pausou, por `verificationStale`.
+    // 'fail' já pausou por `verificationStatus`; 'pass' com stamp velho, por `verificationStale`.
   }
 
   // Feature que gera mídia: custo, revisão humana, marcação e hot path só valem provados na seção.
@@ -375,19 +256,13 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
-  // No fecho do DESIGN: o mockup declara telas sem o checklist de tela
-  // completo. É ele que faz paginação, ordenação, filtro e os três estados
-  // virarem cenário do plano — sem ele, uma lista de 2 000 linhas é aprovada
-  // listando tudo, e o implementador entrega exatamente o cenário.
+  // Sem o checklist de tela completo, paginação, ordenação, filtro e os três estados não viram cenário.
   if (signals.gate === 'uiux') {
     const reason = uiuxChecklistPause(signals.screenChecklist);
     if (reason) return { pause: true, reason };
   }
 
-  // No SHIP, depois da cláusula de mídia e pela mesma disciplina: o design
-  // decidiu itens de tela e o verificador não registrou a conferência deles
-  // contra a tela entregue. Cobra-se o item DEVIDO (`uncovered`): tela toda
-  // "não se aplica", mockup legado ou ausente não devem nada.
+  // Cobra-se só o item devido (`uncovered`): tela toda "não se aplica", design legado ou ausente não devem nada.
   if (signals.gate === 'review' && (signals.screenChecklist?.uncovered?.length ?? 0) > 0) {
     const { section, uncovered } = signals.screenChecklist;
     if (section !== true) {
@@ -420,10 +295,6 @@ export function shouldPauseGate(config, signals) {
   return { pause: false, reason: '' };
 }
 
-/**
- * Human-readable list of risk signals present (for logging/Gate summary).
- * @returns {string[]}
- */
 export function getRiskSignals(signals) {
   const out = [];
   if (FORCED_PAUSE_WORK_TYPES.includes(signals.workType)) out.push('hotfix (gate humano obrigatório)');
@@ -432,8 +303,7 @@ export function getRiskSignals(signals) {
     out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
   }
   if (signals.verificationStatus === 'fail') out.push('verify vermelho');
-  // Listado mesmo quando NÃO pausa: uma dispensa que passa silenciosamente é
-  // indistinguível de uma omissão. A classe diz de quem é a ausência de prova.
+  // Listado mesmo quando não pausa: dispensa silenciosa é indistinguível de omissão.
   if (signals.gate === 'review' && signals.e2eStatus === 'skip') {
     const klass = classifyE2eSkip(signals.e2eReason);
     const literal = typeof signals.e2eReason === 'string' && signals.e2eReason.trim() !== ''
@@ -445,9 +315,7 @@ export function getRiskSignals(signals) {
     out.push('verification stamp desatualizado (stale) no ship');
   }
   if (signals.gate === 'review') out.push(reviewSummary(signals.reviewReports));
-  // Listado mesmo quando NÃO pausa, pela mesma razão do e2e: um projeto que não
-  // declara caminho de prompt/modelo é indistinguível, no relatório, de um que
-  // declara e não tocou em nada — e as duas coisas significam coisas diferentes.
+  // Listado mesmo quando não pausa, pela mesma razão do e2e.
   if (signals.gate === 'review' && signals.promptModel) {
     const { declared, touched } = signals.promptModel;
     if (!declared) {
@@ -462,17 +330,12 @@ export function getRiskSignals(signals) {
   if (typeof signals.sliceCount === 'number' && signals.sliceCount > MAX_SLICES) {
     out.push(`${signals.sliceCount} fatias (acima de ${MAX_SLICES})`);
   }
-  // Listado mesmo quando NÃO pausa, pela mesma razão do sinal irmão: a isenção
-  // de uma feature que não gera mídia tem de ser VISÍVEL, senão é
-  // indistinguível de uma omissão.
   if (signals.gate === 'review' && signals.mediaClaims?.featureGeneratesMedia === true) {
     out.push(signals.mediaClaims.section === true
       ? 'prova de mídia registrada'
       : 'verifier.md sem a seção `## Mídia gerada` (prova de mídia ausente)');
   }
 
-  // Listado mesmo quando NÃO pausa: a isenção (sem mockup, legado, nada
-  // devido) e o checklist conferido precisam ser distinguíveis de uma omissão.
   if ((signals.gate === 'uiux' || signals.gate === 'review') && signals.screenChecklist) {
     const { mockups, legacy, exempt, screens = [], problems = [], section, uncovered = [] } = signals.screenChecklist;
     if (!mockups) {
@@ -483,13 +346,18 @@ export function getRiskSignals(signals) {
       out.push(problems.length > 0
         ? `checklist de tela incompleto (${problems.length} problema(s))`
         : `checklist de tela completo (${screens.length} tela(s))`);
+      const prototypes = signals.screenChecklist.prototypes ?? [];
+      if (screens.length > 0) {
+        out.push(prototypes.length > 0
+          ? `protótipo incompleto em ${prototypes.length} tela(s)`
+          : `protótipo e prints 1280/390 presentes (${screens.length} tela(s))`);
+      }
     } else if (uncovered.length > 0) {
       out.push(section !== true
         ? 'verifier.md sem a seção `## Checklist de tela`'
         : `checklist de tela sem conferência em ${uncovered.length} tela(s)`);
     } else if (screens.length === 0) {
-      // O design passou pela uiux sem tela nenhuma: nada a cobrar no ship, mas
-      // não pode ler igual a uma tela toda "não se aplica".
+      // Sem tela nenhuma: nada a cobrar no ship, mas não pode ler igual a uma tela toda "não se aplica".
       out.push(`checklist de tela: ${firstOf(problems)}`);
     } else if (section === true) {
       out.push(`checklist de tela conferido (${screens.length} tela(s))`);

package/src/lib/specs/adr-index.js

@@ -1,12 +1,4 @@
-/**
- * The index of the ADRs that still hold across the project:
- * `.morph/specs/adrs/`, one file per ADR, maintained by finish/archive alone,
- * inside the archive commit, from the closing feature's `2-plan/plan.md`:
- *   - enters: an ADR of `## Decisões` with `**Alcance:** projeto`;
- *   - leaves: an ADR its `### Conflitos com o acervo` revokes in full (file deleted);
- *   - narrows: one it revokes in part keeps its file, with `scope:` where it still holds.
- * One file per ADR so parallel features that index different ADRs merge cleanly.
- */
+// One file per ADR under `.morph/specs/adrs/`, so parallel features that index different ADRs merge cleanly.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
@@ -48,11 +40,7 @@ function renderAdrFile({ ref, title, body }, feature) {
   ].join('\n');
 }
 
-/**
- * The ADRs the index holds; `[]` when there is none or it cannot be read.
- *
- * @returns {Array<{ ref: string, file: string, title: string|null, scope: string|null }>}
- */
+/** `[]` when there is no index or it cannot be read. */
 export function readAdrIndex(cwd) {
   const dir = join(cwd, ADR_INDEX_PATHSPEC);
   try {
@@ -61,7 +49,7 @@ export function readAdrIndex(cwd) {
       const ref = refOf(file);
       if (!ref) return [];
       let content = '';
-      try { content = readFileSync(join(dir, file), 'utf8'); } catch { /* listed, unreadable */ }
+      try { content = readFileSync(join(dir, file), 'utf8'); } catch {}
       return [{ ref, file, title: readFrontmatterField(content, 'title'), scope: readFrontmatterField(content, 'scope') }];
     });
   } catch {
@@ -69,16 +57,7 @@ export function readAdrIndex(cwd) {
   }
 }
 
-/**
- * Apply a closing feature's plan to the index: its project-wide ADRs enter, and
- * the ADRs its conflicts table revokes are deleted (total) or narrowed (parcial).
- * An unreadable or absent plan touches nothing.
- *
- * @param {string} cwd
- * @param {string} featureDir - the feature folder (already archived, at close time)
- * @returns {{ changed: boolean, added: string[], revoked: string[], narrowed: string[],
- *   problems: Array<{ id: string|null, reason: string, message: string }> }}
- */
+/** An unreadable or absent plan touches nothing. */
 export function updateAdrIndex(cwd, featureDir) {
   const result = { changed: false, added: [], revoked: [], narrowed: [], problems: [] };
   const feature = basename(featureDir);
@@ -88,7 +67,7 @@ export function updateAdrIndex(cwd, featureDir) {
   try {
     const planPath = join(featureDir, PLAN.phaseDir, PLAN.filename);
     if (existsSync(planPath)) plan = parsePlan(readFileSync(planPath, 'utf8'));
-  } catch { /* unreadable plan.md — nothing enters or leaves */ }
+  } catch {}
   if (!plan) return result;
 
   for (const { id, title, body } of plan.adrs.filter((a) => a.scope === 'projeto')) {
@@ -128,14 +107,7 @@ export function updateAdrIndex(cwd, featureDir) {
   return result;
 }
 
-/**
- * What the finish would fail to apply from a plan's revocation table, reported
- * while the plan can still change.
- *
- * @param {string} cwd
- * @param {ReturnType<typeof parsePlan>} plan
- * @returns {string[]}
- */
+/** What the finish would fail to apply from the revocation table, reported while the plan can still change. */
 export function revocationWarnings(cwd, plan) {
   const { entries, problems } = parseRevocations(plan.conflicts?.text);
   const warnings = problems.map((p) => `### Conflitos com o acervo: ${p.message}`);

package/src/lib/specs/frontmatter.js

@@ -1,15 +1,6 @@
 const FRONTMATTER_RE = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/;
 
-/**
- * Set (or replace) a single top-level frontmatter field, preserving every
- * other line, the original EOL style, and anything after the closing `---`.
- * A document with no frontmatter block is returned unchanged.
- *
- * @param {string} content
- * @param {string} key
- * @param {string} value - written as-is; quote it first when it is free text
- * @returns {string}
- */
+/** Preserves every other line, the EOL style and the body; no frontmatter block → unchanged. `value` is written as-is. */
 export function setFrontmatterField(content, key, value) {
   const m = FRONTMATTER_RE.exec(content);
   if (!m || m.index !== 0) return content;
@@ -25,11 +16,7 @@ export function setFrontmatterField(content, key, value) {
   return open + next + close + content.slice(full.length);
 }
 
-/**
- * Read a single top-level frontmatter field; `null` when absent or there is no
- * frontmatter block. A double-quoted value is read as the JSON string it is
- * written as; a single-quoted one as YAML reads it (`''` is a quote).
- */
+/** `null` when absent; double-quoted values read as JSON strings, single-quoted as YAML (`''` is a quote). */
 export function readFrontmatterField(content, key) {
   const m = FRONTMATTER_RE.exec(content);
   if (!m || m.index !== 0) return null;

package/src/lib/specs/gfm-table.js

@@ -4,13 +4,7 @@ export const SEPARATOR_ROW_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s
 /** A line that belongs to a table: it carries an unescaped pipe (GFM does not require the leading one). */
 export const isTableLine = (line) => /(?<!\\)\|/.test(line);
 
-/**
- * Split a table row on unescaped pipes, outer pipes optional; `\|` inside a
- * cell is a literal pipe.
- *
- * @param {string} row
- * @returns {string[]} trimmed cells
- */
+/** Splits on unescaped pipes, outer pipes optional; `\|` inside a cell is a literal pipe. */
 export function tableCells(row) {
   const inner = row.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
   return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());

package/src/lib/specs/revocations.js

@@ -1,10 +1,4 @@
-/**
- * The ADRs of the project index that a plan revokes: the table under
- * `### Conflitos com o acervo` whose first header cell is `ADR`, with columns
- * `{feature}/ADR-{nnn}`, `total|parcial` and the scope where the old one still holds.
- * plan-check reports the problems while the plan can still change (it freezes
- * at the plan gate); nothing ambiguous reaches the finish.
- */
+// plan-check reports the problems while the plan can still change, so nothing ambiguous reaches the finish.
 
 import { SEPARATOR_ROW_RE, isTableLine, tableCells } from './gfm-table.js';
 
@@ -46,13 +40,6 @@ function readRow(line) {
   return { entry: problems.length ? { id } : { id, change, scope }, problems };
 }
 
-/**
- * @param {string|null} conflicts - the text of `### Conflitos com o acervo` (`parsePlan(...).conflicts.text`)
- * @returns {{
- *   entries: Array<{ id: string, change: 'total'|'parcial', scope: string|null }>,
- *   problems: Array<{ id: string|null, reason: string, message: string }>
- * }}
- */
 export function parseRevocations(conflicts) {
   const problems = [];
   const rows = [];