Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 49 additions & 31 deletions docs/adr/ADR-0080-local-validation-gate-inviolable.md
Original file line number Diff line number Diff line change
@@ -1,51 +1,69 @@
# ADR-0080 — O gate de validação LOCAL é INVIOLÁVEL: check-all completo (all-greens, zero regressões) antes de QUALQUER push ou PR
# ADR 0080 — Local validation gate is inviolable: full check-all (all-greens, zero regressions) before ANY push or PR

- **Status:** Accepted
- **Date:** 2026-07-03
- **Deciders:** Fabio Tavares Leitão (operador / owner do repositório)
- **Gate-Change-Approved-By:** Fabio Tavares Leitão
- **Date (UTC):** 2026-07-03
- **Authors:** Fabio Leitao
- **Deciders:** Fabio Leitao

## Contexto
## Status

O tier de validação **LOCAL** — `pre-commit` + os testes anti-regressão completos (`pytest`, ~1600) + **Bandit** + **Zizmor** + **Semgrep** — foi construído ao longo de meses **exatamente para NÃO depender do round-trip do GitHub** (esperar minutos por erro remoto e refazer). As regras `check-all-gate.mdc` e `never-weaken-security-gates.mdc` sempre mandaram rodar isso local antes de push/PR.
Proposed

Em 2026-07-03 constatou-se: (a) não havia `pre-push` hook forçando o gate; (b) o executor pushou rodando apenas testes *targeted* (`2 passed`), não o suite completo; (c) um modelo chegou a **sugerir confiar no CI remoto**. E a tentativa de "reforçar" o mandato **degenerou em proliferar regras `alwaysApply: true`** — queimando contexto, **o oposto do objetivo.** Este ADR corrige as duas pontas: **rigor absoluto** no gate **e** **economia de contexto** no enforcement.
### Status history

## Decisão (absoluta, não-negociável)
- 2026-07-03 — Born in violation. Created with Status: Accepted, breaching ADR-0045 §5 — the ADR that governs the ADR lifecycle itself: agents MUST NOT set Accepted on first commit; new ADRs are born Proposed until the operator ratifies. Every checkpoint of the review mesh failed: the Cursor executor committed it, the Claude Code auditor reviewed the prose but never checked the Status field, the claude.ai steering node validated progress, and all three celebrated the operator Ed25519 attestation on an ADR that was illegal at birth, merged via PR #1160 (commit e5722193) with no agent objecting at any stage. The operator caught what three AI auditors did not. PR #1160 is preserved as the scar.
- 2026-07-04 — Amended: corrected to Proposed; premature ratification metadata removed, lifecycle restored via PR #1161.
- 2026-07-04 — Amended: brought into full ADR-0045 conformance after two further violations surfaced, again missed by the review mesh and flagged by the operator: (a) the entire body had been authored in pt-BR, breaching §7 (ADRs are en_US technical documents) — the only pt-BR ADR of 78; (b) the H1 title used the ADR-0080 filename-hyphen form instead of the canonical ADR NNNN heading (§3). Body translated to en_US, title corrected, sections aligned to the §3 canonical set.
- 2026-07-04 — Root cause and accountability (recorded verbatim per operator directive, kept as scar, not a footnote): (1) These violations breached not only ADR-0045 (§5 — agents must not materialize an ADR as Accepted; §7 — ADRs are en_US) but also always-on governance loaded at every session cold-start and ignored: .cursor/rules/docs-locale-pt-br-contract.mdc (alwaysApply: true) and AGENTS.md (session-start contract; English-only prose uses en-US). (2) Despite the operator repeatedly and explicitly ordering it, no agent performed a complete reading of ADR-0045 — the ADR that governs ADRs — nor a single full sanity check of the ADR-0080 they were authoring; each surfaced one defect, declared it "the" error, and missed the rest. (3) With every rule, guardrail, guideline, skill, and ADR in place, the review mesh earned no trust: the operator personally identified every violation across multiple rounds. (4) The three reviewers ran in different environments, on different models, as different agents — the decorrelation meant to make their blind spots independent. It did not: all three showed the identical failure (plausibility over conformance; never reading the governing law in full). When the failure mode is architectural to LLMs, vendor/model decorrelation buys nothing — three "independent" auditors sharing one habit are one check repeated three times.
- 2026-07-04 — Additional violation logged: when the operator first flagged the Accepted-at-birth error, the corrective instinct of the review mesh was to DELETE the ADR (a straight revert — the original intent of PR #1161), itself a breach of ADR-0045 §Decision item 1 (ADRs are NEVER deleted; correction is by status transition / amendment only). The operator rejected delete-for-amend; #1160 is preserved as the scar and the record is corrected in place, not erased.

**Nenhum agente, modelo, ferramenta ou automação tem o direito de sequer SUSPEITAR que o `check-all` e todo o ritual de validações locais possa não rodar antes de QUALQUER push ou PR.**
## Context

1. O código **NUNCA** sai desta máquina com a menor chance de qualquer coisa exceto **ALL GREENS** e **NO REGRESSIONS**.
2. O ritual local completo (`./scripts/check-all.sh --enforced`) **DEVE passar 100% verde LOCAL, ANTES** de todo push e de toda abertura/atualização de PR. *(Commit local intermediário = pre-commit + checks leves; o full check-all é antes de PUBLICAR no GitHub.)*
3. O que o GitHub CI faz **DEPOIS** é **IRRELEVANTE** para esta regra. CI é *backstop*, **NUNCA substituto**. **Confiar no CI em vez do gate local é PROIBIDO.**
4. **Sugerir, adiar, reduzir ou agir como se** o gate pudesse ser pulado = **VIOLAÇÃO desta ADR.**
The **LOCAL** validation tier — `pre-commit` plus the full anti-regression test suite (`pytest`, ~1600) plus **Bandit**, **Zizmor**, and **Semgrep** — was built over months **specifically to avoid depending on the GitHub round-trip** (waiting minutes for a remote failure and redoing work). The rules `check-all-gate.mdc` and `never-weaken-security-gates.mdc` have always required running this locally before push/PR.

## Como é imposto — ENFORCEMENT (mecânico + econômico em contexto)
On 2026-07-03 it was found that: (a) there was no `pre-push` hook enforcing the gate; (b) the executor pushed after running only *targeted* tests (`2 passed`), not the full suite; (c) a model **suggested relying on remote CI**. And the attempt to "reinforce" the mandate **degenerated into proliferating `alwaysApply: true` rules** — burning context, **the opposite of the goal.** This ADR corrects both ends: **absolute rigor** on the gate **and** **enforcement economy** in context.

São **duas peças, e só duas**:
## Decision

1. **TRAVA mecânica:** o pre-push hook **VERSIONADO** (`.githooks/pre-push` + `core.hooksPath`) roda `check-all.sh --enforced`; falhou → **push abortado**. + teste **tamper-evident** no CI-*required* (removeu o hook → CI falha → não merge). *(issue #1151)*
2. **UMA regra que JÁ é always-on:** `check-all-gate.mdc` (two-tier: commit-local leve / push-PR full). **Nada além dela.**
**Absolute, non-negotiable:** No agent, model, tool, or automation may even **suspect** that `check-all` and the full local validation ritual may be skipped before **ANY** push or PR.

### Economia de enforcement (parte da decisão — igual peso ao rigor)
1. Code **NEVER** leaves this machine with anything other than **ALL GREENS** and **NO REGRESSIONS**.
2. The full local ritual (`./scripts/check-all.sh --enforced`) **MUST pass 100% green LOCALLY, BEFORE** every push and every PR open/update. *(Intermediate local commit = pre-commit plus light checks; full check-all is before PUBLISHING to GitHub.)*
3. What GitHub CI does **AFTER** is **IRRELEVANT** to this rule. CI is a *backstop*, **NEVER a substitute**. **Relying on CI instead of the local gate is FORBIDDEN.**
4. **Suggesting, deferring, reducing, or acting as if** the gate may be skipped = **VIOLATION of this ADR.**

**É PROIBIDO criar regras `alwaysApply: true` novas para reafirmar este mandato.** Repetir a regra em N always-on **queima contexto sem adicionar enforcement.** A trava é o **hook**; a regra always-on é **uma só** (`check-all-gate.mdc`). Documentação **contextual/situacional** (globs, `@rule`, session-token) é permitida e encorajada; **always-on nova, não.** Novas always-on ferem `docs/ops/CURSOR_RULES_PHASE2_SITUATIONALIZATION.md` (economia de contexto) e são **anti-padrão**.
### Enforcement (mechanical + context-economical)

## Registro ≠ Enforcement (não confundir — foi a raiz do incidente)
**Two pieces, and only two:**

- **Este ADR** = registro durável do **PORQUÊ** + governança. É **DOC** (`docs/adr/`), lido **on-demand** — **NÃO carrega em toda sessão, NÃO causa bloat.**
- **O enforcement** = **hook** (mecânico) + **1 regra** já-always-on. **O rigor vem do mecanismo, não de repetir a regra.**
1. **Mechanical lock:** the versioned pre-push hook (`.githooks/pre-push` + `core.hooksPath`) runs `check-all.sh --enforced`; on failure → **push aborted**. Plus a **tamper-evident** test in CI-*required* (hook removed → CI fails → no merge). *(issue #1151)*
2. **ONE already-always-on rule:** `check-all-gate.mdc` (two-tier: light commit-local / full push-PR). **Nothing beyond it.**

## Governança da mudança
**Enforcement economy (same weight as rigor):** **FORBIDDEN** to create new `alwaysApply: true` rules to restate this mandate. Repeating the rule in N always-on rules **burns context without adding enforcement.** The lock is the **hook**; the always-on rule is **one only** (`check-all-gate.mdc`). **Contextual/situational** documentation (globs, `@rule`, session-token) is permitted and encouraged; **new always-on, not.** New always-on rules violate `docs/ops/CURSOR_RULES_PHASE2_SITUATIONALIZATION.md` (context economy) and are **anti-pattern.**

Mudar/remover/bypassar o gate exige trailer **`Gate-Change-Approved-By: <operador>`**. `git push --no-verify` só com aprovação **explícita e logada**. Violação → **Safe-Hold** + report ao operador.
### Gate change governance

## Consequências
Changing, removing, or bypassing the gate requires trailer **`Gate-Change-Approved-By: <operator>`**. `git push --no-verify` only with **explicit, logged** operator approval. Violation → **Safe-Hold** + report to the operator.

- Pushes mais lentos localmente (1600 + scans). **ACEITÁVEL e INTENCIONAL** — custo de nunca entregar quebrado e nunca depender do round-trip remoto.
- Todo clone (main dev box — hoje a workstation Linux primária, pode voltar à primária Windows — + secondary) herda o gate no setup.
- Violação = falha de governança.
**Authority:** Owner = **operator (Fabio Leitao)**. Claude = read-only auditor. Cursor = executor. This ADR **supersedes any agent or model default.**

## Autoridade
## Rationale

Owner = **operador (Fabio Tavares Leitão)**. Claude = auditor read-only. Cursor = executor. Esta ADR **supera qualquer default de agente ou modelo.**
1. **Record ≠ Enforcement (do not conflate — root of the incident):** This ADR = durable record of **WHY** + governance. It is **DOC** (`docs/adr/`), read **on-demand** — **does NOT load every session, does NOT cause bloat.** Enforcement = **hook** (mechanical) + **1** already-always-on rule. **Rigor comes from the mechanism, not from repeating the rule.**
2. **CI backstop vs local gate:** Remote CI cannot replace the cost of a broken push round-trip; local all-green is the contract every contributor and agent must internalize before publish.
3. **Enforcement economy:** Proliferating always-on rules to "reinforce" discipline without mechanical locks only inflates agent context; the hook plus one rule is the minimum sufficient stack.

## Consequences

- **Positive:** Broken code does not leave the dev machine; agents cannot treat CI as a substitute for local validation.
- **Negative:** Slower local pushes (~1600 tests + scans). **ACCEPTABLE and INTENTIONAL** — cost of never shipping broken and never depending on the remote round-trip.
- Every clone (primary dev box — today the primary Linux workstation, may return to the primary Windows workstation — plus secondary) inherits the gate on setup.
- Violation = governance failure.

## Related Decisions

- [ADR 0045 — ADR metadata and format standardization](ADR-0045-adr-metadata-and-format-standardization.md) (§5 new ADR materialization → **Proposed**; §7 en_US)
- [ADR 0072 — Commit Gate vs Release Gate: distinct criteria](ADR-0072-commit-gate-vs-release-gate-distinct-criteria.md) (commit gate = `check-all`; distinct from release gate)
- GitHub [#1151](https://github.com/DataBoar/data-boar/issues/1151) — versioned pre-push hook (enforcement)
- GitHub [#1152](https://github.com/DataBoar/data-boar/issues/1152) — ADR materialization
- GitHub [#1160](https://github.com/DataBoar/data-boar/pull/1160) — scar (illegal Accepted birth)
- GitHub [#1161](https://github.com/DataBoar/data-boar/pull/1161) — lifecycle correction amend
6 changes: 3 additions & 3 deletions docs/adr/INVENTORY.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# ADR Inventory - generated by scripts/inv-adr.ps1
# GeneratedUtc: 2026-07-03T23:48:05Z
# GeneratedUtc: 2026-07-04T05:17:52Z
# Algorithm: SHA256
# Format: NUMBER | STATUS | FILE_HASH | FILENAME | TITLE | RATIFIED_BY
# RATIFIED_BY: - = N/A; PENDING = ratification line with signature PENDING; @op = stamped
Expand Down Expand Up @@ -81,6 +81,6 @@
0077 | Accepted | F8A4C9D3B2BE2BEE3721C5AE09476F9CD066DB0B58E6B3174D4B783B123A1BAF | ADR-0077-filesystem-scan-no-client-gitignore-by-design.md | Filesystem scan does not honor client `.gitignore` (deliberate design) | -
0078 | Proposed | 5FEF0DCAC3DA292E33519F24FE6387584C04A850771958FF78B19D3EEB856990 | ADR-0078-multi-pattern-regex-benchmark-gate-regexset-before-vectorscan.md | Multi-pattern regex acceleration gated by benchmark (RegexSet before Vectorscan) | -
0079 | Proposed | 158C68D90B9C6934F0FAAC392E86C6C889FA8F5A6E9AD8197168205946435F9D | ADR-0079-ecosystem-engineering-rigor-canon.md | Ecosystem engineering rigor canon (UMADR satellites) | -
0080 | Accepted | B217F4C1FA5C96661EEF968C37500E20C09023C3D86186580496CEE7CB61E422 | ADR-0080-local-validation-gate-inviolable.md | local validation gate inviolable | -
0080 | Proposed | 5084990188A98B0454A3FA377C6180DBE5D9CC23B4F71398DBEDFDBB73D31045 | ADR-0080-local-validation-gate-inviolable.md | Local validation gate is inviolable: full check-all (all-greens, zero regressions) before ANY push or PR | -
#
# InventoryHash: 87BD2025208408CE4DB3386EEC40EC0FC161078FBF38E3D7217BE236087A5F5B
# InventoryHash: 6E7B04DF01C09300B8C43A593786854D90BFA59EFEC6781C09A831BF0573E97A
2 changes: 1 addition & 1 deletion docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ Short, durable notes that capture **why** the project chose an approach—not on
| 0077 | [Filesystem scan does not honor client `.gitignore`](ADR-0077-filesystem-scan-no-client-gitignore-by-design.md) | Accepted |
| 0078 | [Multi-pattern regex: RegexSet before Vectorscan (benchmark gate)](ADR-0078-multi-pattern-regex-benchmark-gate-regexset-before-vectorscan.md) | Proposed |
| 0079 | [Ecosystem engineering rigor canon (UMADR satellites)](ADR-0079-ecosystem-engineering-rigor-canon.md) | Proposed |
| 0080 | [Local validation gate is inviolable: full check-all before any push or PR](ADR-0080-local-validation-gate-inviolable.md) | Accepted |
| 0080 | [Local validation gate is inviolable: full check-all before any push or PR](ADR-0080-local-validation-gate-inviolable.md) | Proposed |

## Related docs

Expand Down