teqo-backup/docs/plans/audit-pass6-bypass-ratchet-impl.md

49 lines
3.5 KiB
Markdown

# Impl: Ratchet de bypass endurecido (P6-1)
Status: aprovado
Atualizado em: 2026-08-25
Issue: —
Intenção: docs/plans/entrega-engenharia-p6.md
Appetite restante: herdado (guarda classe 3, spec única — entrega S)
## Leitura da intenção
- **Outcome:** Comentário de módulo (header) não zera mais o arquivo — bypass só conta como documentado com comentário per-site; arquivos novos entram pinados na contagem atual; zero mudança de runtime.
- **O que NÃO negociar:** nenhuma mudança de comportamento, sem migration, sem dependências novas; o ratchet continua só-diminui (pins = contagem medida hoje, nunca arredondada para baixo).
- **O que reavaliar:** a premissa "arquivos novos invisíveis" — medida: a invisibilidade vem do header rule, não do mapa; o walk já cobre todo `src/` e `pinnedUndocumented.get(path) ?? 0` já faz arquivo sem pin com N indocumentados falhar. O bug é o header zerar a contagem.
## Abordagem recomendada
**Opções consideradas:** A | B | C
**Recomendação:** A — remover o zero-by-header em `countUndocumented` (mantendo a janela de 10 linhas per-site) e pinar os arquivos recém-visíveis na contagem medida. Delta mínimo que satisfaz (a)/(b)/(c).
**Rejeitadas:** B — apertar para "comentário contíguo imediatamente acima": rederrata ~64 arquivos, exige SUBIR pins de ~30 arquivos já pinados, violando o espírito só-diminui. C — migrar o pin map para snapshot JSON commitado: cerimônia nova sem ganho.
### Componentes / mudanças
- **`countUndocumented`** (`tests/unit/codebaseConventions.unit.spec.ts:691-704`): deletar o cálculo de `header` (linha 693) e a condição `!header.includes('bypass')` (linha 701). Documentado ⇔ `context` (10 linhas acima) contém "bypass". Atualizar a prosa do describe.
- **`pinnedUndocumented`** (648-689): adicionar pins P6-1 (comentário "P6-1 baseline"), valores = contagem per-site medida na fase 1 (o RED da fase 1 é a medição — colar os números que o RED reportar). Os pins existentes NÃO mudam se per-site == pin atual.
- **Migration:** sem migration. **Access/Consent:** nenhuma — guard-only. **UI:** N/A.
## Fases verificáveis
1. **Hardening do contador** — remover o header rule + atualizar a prosa; rodar o spec: `pnpm test:unit -- codebaseConventions` (bare). Esperado: RED nos arquivos recém-visíveis (`N undocumented (pin: 0)`). Negative check opcional: criar `src/utilities/__bypassProbe.ts` com 1 `overrideAccess: true` sem comentário → spec falha → deletar o probe.
2. **Pinning** — adicionar os pins medidos na fase 1; spec GREEN.
3. **Gates** — `pnpm gate:fast`; push via `pnpm push`.
## Rabbit holes / Não escopo (engenharia)
- **Comentários per-site nos piores arquivos** (`personDelete.ts`, `notification/*`, `Consent.ts`, `loadNamesByIds.ts`) — FORA de escopo deste pass; os pins os cobrem e o ratchet bloqueia crescimento.
- Apertar a janela para comentário contíguo (Opção B); re-justificar bypasses; mexer no `localApiOverrideAccessConventions.unit.spec.ts`.
## Riscos e mitigação
- Contagem medida pelo RED da fase 1 (não estimativa); nenhum pin abaixo do medido — fase 2 confere GREEN.
- O probe negativo é temporário e deletado na mesma fase.
## Aceite de engenharia
- [x] Aceite de produto da intenção ainda coberto (guard hardening, runtime intocado)
- [x] Invariantes AGENTS/engineering-standards (sem migration, sem deps, sem twin)
- [x] Testes de domínio: a spec É o teste — RED sem hardening (fase 1), GREEN com (fase 2)
Self-score decision-quality: 5/5