From 3035569d6aae62d39aeb56d2146b852bed640e6d Mon Sep 17 00:00:00 2001 From: "franklin.azeredo" Date: Sat, 4 Jul 2026 00:57:58 -0300 Subject: [PATCH] =?UTF-8?q?docs(readme):=20m=C3=A9tricas=20medidas=20p?= =?UTF-8?q?=C3=B3s-03/07=20(0.54.0)=20+=20Dia=205=20(Fases=2022=20e=2023)?= =?UTF-8?q?=20=E2=80=94=20pt/en=20em=20sincronia?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Números MEDIDOS no repo (regra da casa — não inventados): 464 commits, 55 releases (0.1.0→0.54.0) · 59 tags, 37.665 linhas Java main (783 main + 158 teste), 627 testes backend + 334 frontend + 28 E2E (hero: 961), 44 migrações, 42 controllers, 5 dashboards + 10 alertas (22b/22c), 23 ADRs, 152 DLs, ~4,5 dias corridos (06-29 → 07-03). Corrige inconsistência pré-existente: são 33 specs (SPEC-0001…0034, não há 0030) — o hub docs/README já dizia 33. História: novo bloco 'Dia 5 (03/07)' — Fase 22 completa (i18n gates, monitoramento enterprise, log inteligente, manual com 31 screenshots, INSTALL) + Fase 23 (governança PR-only, gitleaks, CODEOWNERS/SECURITY/CONTRIBUTING) + toolkit .claude (PR #15, mergeado 04/07). Novo imprevisto documentado (nada escondido): o CI estava vermelho desde a Fase 20b e o primeiro PR revisado o expôs — gitleaks sem GITHUB_TOKEN (config) + teste flaky por resíduo no Postgres compartilhado; lição: branch protection é o que faz os checks serem vistos. Processos (§5): gitflow → PR-only; linha nova de governança de repo + secret scanning (ADR-0023); observabilidade com os números reais. Mapa (§9): .claude/ na árvore + linha do GUIA-TIME-CLAUDE. Cobertura JaCoCo anotada como medição da Fase 21 (v0.51.1) — não re-executada nesta fatia docs-only. Docs-only: sem bump (ADR-0015), sem MANUAL (README não é o manual do usuário). As duas faces (pt-BR e en-US) atualizadas na mesma fatia. Co-Authored-By: Claude Opus 4.8 --- README.en-US.md | 76 +++++++++++++++++++++++++++++++++--------------- README.md | 77 +++++++++++++++++++++++++++++++++---------------- 2 files changed, 104 insertions(+), 49 deletions(-) diff --git a/README.en-US.md b/README.en-US.md index 876dc3c..d712b6a 100644 --- a/README.en-US.md +++ b/README.en-US.md @@ -3,16 +3,18 @@ > 🌐 **Language / Idioma:** **English** · [Português (pt-BR)](README.md) [![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue.svg)](LICENSE) -[![Version](https://img.shields.io/badge/version-0.51.1-informational)](docs/release-notes/CHANGELOG.en-US.md) +[![Version](https://img.shields.io/badge/version-0.54.0-informational)](docs/release-notes/CHANGELOG.en-US.md) [![Java 21](https://img.shields.io/badge/Java-21-orange)](backend/pom.xml) [![Spring Boot 4.1](https://img.shields.io/badge/Spring%20Boot-4.1.0-6DB33F)](backend/pom.xml) [![Angular 22](https://img.shields.io/badge/Angular-22-DD0031)](frontend/package.json) -**A complete ERP — 23 modules, 42 REST controllers, 31 screens, 948 automated tests — built in -~3.5 calendar days by one person supervising [Claude Code](https://claude.com/claude-code), +**A complete ERP — 23 modules, 42 REST controllers, 31 screens, 961 automated tests — built in +~4.5 calendar days by one person supervising [Claude Code](https://claude.com/claude-code), using Spec-Driven Development.** This repository is the entire proof of concept: the code, the -34 specifications, the 22 ADRs, the 147 recorded decisions and the execution log of every phase. -Nothing was hidden — the mishaps are documented right next to what worked. +33 specifications, the 23 ADRs, the 152 recorded decisions and the execution log of every phase. +Nothing was hidden — the mishaps are documented right next to what worked (Phase 21's final +verification found three defects, fixed and recorded; the first reviewed PR exposed a red CI +that direct pushes had been hiding). It is a **study project, free for any use**: download, copy, modify, sell — no permission needed and no attribution required ([0BSD](LICENSE) license). @@ -51,25 +53,26 @@ The full domain document (the "source of truth" that fed everything) is ## 2. The outcome in numbers -Measured on the repository (final Phase 21 commit, version 0.51.1): +Measured on the repository (develop after Phases 22 and 23, version 0.54.0 — 2026-07-03): | Metric | Value | |---|---| -| **Build time** | **2026-06-29 03:57 → 2026-07-02 18:03** (≈ 3.5 calendar days) | -| Commits | **443** | -| Published releases | **52** (SemVer `0.1.0` → `0.51.1`, one MINOR per slice + 1 fix PATCH — ADR-0015) · 56 tags | -| Backend code | **37,436 lines** of Java (780 main + 153 test files) | +| **Build time** | **2026-06-29 03:57 → 2026-07-03 10:30** (≈ 4.5 calendar days) | +| Commits | **464** | +| Published releases | **55** (SemVer `0.1.0` → `0.54.0`, one MINOR per slice + fix PATCHes — ADR-0015) · 59 tags | +| Backend code | **37,665 lines** of main Java (783 main + 158 test files) | | Frontend code | **16,856 lines** of TS/HTML/SCSS (31 screens, specs excluded) | | Database | **44 Flyway migrations** (1,696 lines of SQL), PostgreSQL 16 | | Verified modules | **23** (Spring Modulith, acyclic graph with a build gate) | | API | **42 REST controllers** · OpenAPI snapshot with a **drift gate** | -| Backend tests | **617** (unit + Testcontainers integration + 18 ArchUnit rules + jqwik) | -| Frontend tests | **331** (Vitest) + **28 E2E journeys** (Playwright, isolated stack) | -| Coverage (measured) | JaCoCo **90.1%** instruction (80% floor) · **68.8%** branch (65% floor) | +| Backend tests | **627** (unit + Testcontainers integration + 18 ArchUnit rules + jqwik) | +| Frontend tests | **334** (Vitest) + **28 E2E journeys** (Playwright, isolated stack) | +| Coverage (measured at Phase 21, v0.51.1) | JaCoCo **90.1%** instruction (80% floor) · **68.8%** branch (65% floor) | | Mutation testing | PIT (last full run, Phase 20): 185 mutants, **68% killed**, **89% test strength** (60% floor) | -| Specifications | **34** (SPEC-0001…0034) — [docs/specs/](docs/specs/) | -| ADRs | **22** — [docs/adr/](docs/adr/) | -| Recorded autonomous decisions | **147** (DL-0001…0147, with confidence and reversibility) — [docs/decision-log/](docs/decision-log/) | +| Observability | **5 provisioned Grafana dashboards** · **10 alerts** (optional e-mail delivery) — Phases 22b/22c | +| Specifications | **33** (SPEC-0001…0034 — there is no 0030) — [docs/specs/](docs/specs/) | +| ADRs | **23** — [docs/adr/](docs/adr/) | +| Recorded autonomous decisions | **152** (DL-0001…0152, with confidence and reversibility) — [docs/decision-log/](docs/decision-log/) | | Configuration | full environment-variable reference in [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | > Every number above is verifiable in the repo itself: the per-phase execution log (with @@ -133,6 +136,20 @@ upgrade), 15 (bilingual docs), 16 (the 18 missing operation screens), 17 (Keyclo hardening, supply-chain CI, production posture with TLS/backup/DR) and Phase 20 (keyboard-first UX, universal Esc/Enter, real DSS, 2026 design). +**Day 5 (Jul 3) — enterprise operations and team governance.** Phase 22 complete (5 slices, +`0.52.0`→`0.54.0`): permanent i18n parity gates (pt/en, 110 domain exceptions in both +languages), **enterprise monitoring** (5 Grafana dashboards, 10 alerts with e-mail delivery), +**smart logging** (Loki/Alloy with `correlationId`/`username` as structured metadata), a +field-by-field manual with **31 screenshots** generated by a versioned script, and a +from-scratch install guide. Plus **Phase 23 — repository governance for team work**: +`main`/`develop` protected (**PR required**, no direct push), the agent guardrail in +`.claude/settings.json` (merge/tag/force-push denied), **secret scanning** with gitleaks +(blocking CI + pre-commit + a dev-defaults allowlist), CODEOWNERS, SECURITY.md, +CONTRIBUTING.md. The first PR-only cycle (PR #14) paid for itself the same day — it exposed a +red CI that direct pushes had been hiding (see the mishaps). Right after, the **`.claude/` team +toolkit** was born (10 skills + an agent team with a coordinating architect; PR #15, merged on +Jul 4 — see [docs/GUIA-TIME-CLAUDE.md](docs/GUIA-TIME-CLAUDE.md), pt-BR). + ### What worked (and why) - **The gates held the AI accountable.** The Spring Modulith gate **caught a dependency cycle** @@ -143,11 +160,11 @@ UX, universal Esc/Enter, real DSS, 2026 design). - **Test-first found real bugs.** Phase 19i proved **red→green a real concurrency race** (an entry slipping into a just-closed period) and 20c caught a listener that silently did not persist (read-only transaction → `REQUIRES_NEW`). -- **The decision log paid for itself.** The 140 DLs (each with the gap, the decision, sourced +- **The decision log paid for itself.** The 152 DLs (each with the gap, the decision, sourced justification, discarded alternatives and reversal cost) enabled a **batch review of decisions** (Phase 19b) and safe reversals of the ones that aged badly. - **Living specs prevented rework.** A rule changed midway? The spec was updated in the same - PR. The spec → test → code traceability survived all 48 releases. + PR. The spec → test → code traceability survived all 55 releases. ### The mishaps (nothing hidden) @@ -176,23 +193,32 @@ UX, universal Esc/Enter, real DSS, 2026 design). pending; the supervisor finished the slice from where it stood. - **Phase 1 was preempted by the owner** right at the start to institute SemVer/release management (ADR-0015) before any business code — then restarted clean. +- **The CI had been red since Phase 20b — and nobody saw it (Jul 3):** with direct pushes, + nobody looked at the checks; the **first reviewed PR** (Phase 23) exposed them. Two real + problems: the gitleaks action requiring `GITHUB_TOKEN` on pull-request events (configuration — + not a leak) and a *flaky* integration test — green on local Windows, red on the Linux runner — + caused by residue on the shared singleton Postgres (an absolute-count assertion without + `@BeforeEach` cleanup). Both fixed in the PR itself, with the lesson codified as a house rule + (`@BeforeEach` isolation + Linux repro only from a clean checkout). The bigger lesson: branch + protection + PRs are not ceremony — **they are what makes the checks get seen**. ## 5. Software engineering processes used | Process | How it shows up in this repo | |---|---| -| **Spec-Driven Development** | 32 specs with testable rules, examples and Open Questions; living specs updated in the slice's PR | +| **Spec-Driven Development** | 33 specs with testable rules, examples and Open Questions; living specs updated in the slice's PR | | **TDD (red→green→refactor)** | The 7-step loop of every slice ([TUTORIAL](docs/TUTORIAL.md)); bugs get a regression test that fails first | | **Pragmatic DDD** | 22 bounded contexts from the [domain](docs/DOMAIN.md) → 23 modules; ubiquitous language; events as business facts | | **Modular monolith** | Spring Modulith + ArchUnit as *fitness functions* (boundaries break the build) — ADR-0001/0012 | | **Vertical slices** | Every delivery crosses migration → domain → API → screen and ships demonstrable; walking skeleton first | -| **ADRs + decision log** | 21 ADRs for architecture; 140 DLs for autonomous decisions with confidence/reversibility | -| **Gitflow + Conventional Commits + SemVer** | `main`/`develop`/`feature/*`; 48 releases tagged from `main`; version source of truth in `pom.xml` (ADR-0015) | -| **CI/CD with quality gates** | GitHub Actions: build+tests+gates, E2E, CodeQL, Dependabot, `npm audit`, GHCR images per tag | +| **ADRs + decision log** | 23 ADRs for architecture; 152 DLs for autonomous decisions with confidence/reversibility | +| **Gitflow + Conventional Commits + SemVer** | `main`/`develop` **protected (PR required — Phase 23)** + `feature/*`; 55 releases tagged from `main`; version source of truth in `pom.xml` (ADR-0015) | +| **Repo governance + secret scanning** | PR-only branch protection, CODEOWNERS, SECURITY/CONTRIBUTING, agent guardrail (`.claude/settings.json`), gitleaks (blocking CI + pre-commit, dev-defaults allowlist) — ADR-0023 | +| **CI/CD with quality gates** | GitHub Actions: build+tests+gates, E2E, CodeQL, gitleaks, Dependabot, `npm audit`, GHCR images per tag | | **Contract testing** | Committed OpenAPI snapshot + drift test; module diagram likewise | | **Property-based + mutation testing** | jqwik (8 properties × 1000 cases over money math); PIT with a 60% floor | | **Isolated E2E** | Playwright against a disposable stack (`compose.e2e.yaml`, tmpfs Postgres) — never the dev database | -| **Observability** | Provisioned Micrometer/Prometheus/Loki/Grafana, JSON logs with correlation, 5 alerts, `/api/version` | +| **Observability** | Provisioned Micrometer/Prometheus/Loki/Grafana — **5 dashboards, 10 alerts** (optional e-mail), JSON logs with `correlationId`/`username` as structured metadata, `/api/version` | | **Security by default** | Default-deny authorization with a completeness test, OIDC+PKCE, HMAC+anti-replay, prod secret fail-fast, AES-GCM vault | | **DR/backup** | Daily `pg_dump` + vault tar, 30d/12m/7y retention, RPO 24h / RTO 4h, quarterly restore drill (ADR-0021) | | **i18n + a11y + LGPD** | pt-BR/en-US end to end; WCAG 2.1.4 (single-key toggle), `prefers-reduced-motion`; consent/erasure/masking | @@ -209,7 +235,7 @@ of finish** (tests, gates, observability, bilingual docs): deliver this scope in **12–18 months** ≈ **48–72 person-months** — assuming requirements already consolidated as they are in [docs/DOMAIN.md](docs/DOMAIN.md). -**What it actually took: ~3.5 calendar days**, with **1 person** supervising (approving plans, +**What it actually took: ~4.5 calendar days**, with **1 person** supervising (approving plans, deciding business Open Questions, auditing deliveries) and Claude Code executing — often in autonomous 30–90-minute phases. Even counting every hour of the owner's attention, the human effort was in the **tens of hours against tens of thousands**. @@ -353,6 +379,7 @@ fkerp-java-sdd/ ├── frontend/ # Angular 22 + PrimeNG 21 + Tailwind 4 → frontend/README.md ├── infra/ # prometheus/ loki/ alloy/ grafana/ proxy/ backup/ wiremock/ ├── docs/ # ALL the documentation → docs/README.md (master index) +├── .claude/ # team toolkit: 10 skills + agents (architect, devs, QA) + git guardrail ├── docker-compose.yml # dev: app + db + observability (+ emulators profile) ├── compose.e2e.yaml # isolated E2E stack (ephemeral Postgres, frontend :4201) ├── compose.prod.yaml # production: TLS proxy + prod profile + internal network @@ -371,6 +398,7 @@ The key documents, in the new organization (technical artifacts are pt-BR by con | Read the specifications | [docs/specs/](docs/specs/) | | See the decisions (architecture / autonomous) | [docs/adr/](docs/adr/) · [docs/decision-log/](docs/decision-log/) | | Reproduce the method (the per-slice loop) | [docs/TUTORIAL.md](docs/TUTORIAL.md) · [docs/RUN-PHASE.md](docs/RUN-PHASE.md) | +| Operate the agent team and the `/` commands | [docs/GUIA-TIME-CLAUDE.md](docs/GUIA-TIME-CLAUDE.md) (didactic, from zero — pt-BR) | | See the plan and what was executed (with test results) | [docs/ROADMAP.md](docs/ROADMAP.md) · [docs/ROADMAP-STATUS.md](docs/ROADMAP-STATUS.md) | | See what changed per version | [CHANGELOG en-US](docs/release-notes/CHANGELOG.en-US.md) · [pt-BR](docs/release-notes/CHANGELOG.md) | | Go to production (owner's pending items) | [docs/PRODUCTION-CHECKLIST.md](docs/PRODUCTION-CHECKLIST.md) | diff --git a/README.md b/README.md index 66720f5..ad994d8 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,19 @@ > 🌐 **Idioma / Language:** **Português (pt-BR)** · [English](README.en-US.md) [![Licença: 0BSD](https://img.shields.io/badge/licen%C3%A7a-0BSD-blue.svg)](LICENSE) -[![Versão](https://img.shields.io/badge/vers%C3%A3o-0.51.1-informational)](docs/release-notes/) +[![Versão](https://img.shields.io/badge/vers%C3%A3o-0.54.0-informational)](docs/release-notes/) [![Java 21](https://img.shields.io/badge/Java-21-orange)](backend/pom.xml) [![Spring Boot 4.1](https://img.shields.io/badge/Spring%20Boot-4.1.0-6DB33F)](backend/pom.xml) [![Angular 22](https://img.shields.io/badge/Angular-22-DD0031)](frontend/package.json) -**Um ERP completo — 23 módulos, 42 controllers REST, 31 telas, 948 testes automatizados — -construído em ~3,5 dias corridos por uma pessoa supervisionando o +**Um ERP completo — 23 módulos, 42 controllers REST, 31 telas, 961 testes automatizados — +construído em ~4,5 dias corridos por uma pessoa supervisionando o [Claude Code](https://claude.com/claude-code), usando Spec-Driven Development.** Este -repositório é a prova de conceito inteira: o código, as 34 especificações, os 22 ADRs, as 147 +repositório é a prova de conceito inteira: o código, as 33 especificações, os 23 ADRs, as 152 decisões registradas e o log de execução de cada fase. Nada foi escondido — os imprevistos -estão documentados junto com o que deu certo (a própria verificação final desta fase encontrou -três defeitos, corrigidos e registrados). +estão documentados junto com o que deu certo (a verificação final da Fase 21 encontrou três +defeitos, corrigidos e registrados; o primeiro PR revisado expôs um CI vermelho que o push +direto escondia). É um projeto de **estudo, livre para qualquer uso**: baixe, copie, modifique, comercialize — sem pedir permissão e sem obrigação de atribuição (licença [0BSD](LICENSE)). @@ -52,25 +53,26 @@ O documento de domínio completo (a "fonte da verdade" que alimentou tudo) está ## 2. O resultado em números -Números medidos no repositório (commit final da Fase 21, versão 0.51.1): +Números medidos no repositório (develop após as Fases 22 e 23, versão 0.54.0 — 03/07/2026): | Métrica | Valor | |---|---| -| **Tempo de construção** | **2026-06-29 03:57 → 2026-07-02 18:03** (≈ 3,5 dias corridos) | -| Commits | **443** | -| Releases publicadas | **52** (SemVer `0.1.0` → `0.51.1`, uma MINOR por fatia + 1 PATCH de correção — ADR-0015) · 56 tags | -| Código backend | **37.436 linhas** de Java (780 arquivos main + 153 de teste) | +| **Tempo de construção** | **2026-06-29 03:57 → 2026-07-03 10:30** (≈ 4,5 dias corridos) | +| Commits | **464** | +| Releases publicadas | **55** (SemVer `0.1.0` → `0.54.0`, uma MINOR por fatia + PATCHes de correção — ADR-0015) · 59 tags | +| Código backend | **37.665 linhas** de Java main (783 arquivos main + 158 de teste) | | Código frontend | **16.856 linhas** de TS/HTML/SCSS (31 telas, exclui specs) | | Banco | **44 migrações Flyway** (1.696 linhas de SQL), PostgreSQL 16 | | Módulos verificados | **23** (Spring Modulith, grafo acíclico com gate de build) | | API | **42 controllers REST** · snapshot OpenAPI com **gate de drift** | -| Testes backend | **617** (unitários + integração Testcontainers + 18 regras ArchUnit + jqwik) | -| Testes frontend | **331** (Vitest) + **28 jornadas E2E** (Playwright, stack isolada) | -| Cobertura (medida) | JaCoCo **90,1%** de instrução (piso 80%) · **68,8%** de branch (piso 65%) | +| Testes backend | **627** (unitários + integração Testcontainers + 18 regras ArchUnit + jqwik) | +| Testes frontend | **334** (Vitest) + **28 jornadas E2E** (Playwright, stack isolada) | +| Cobertura (medida na Fase 21, v0.51.1) | JaCoCo **90,1%** de instrução (piso 80%) · **68,8%** de branch (piso 65%) | | Mutation testing | PIT (última medição completa, Fase 20): 185 mutantes, **68% mortos**, **89% de test strength** (piso 60%) | -| Especificações | **34** (SPEC-0001…0034) — [docs/specs/](docs/specs/) | -| ADRs | **22** — [docs/adr/](docs/adr/) | -| Decisões autônomas registradas | **147** (DL-0001…0147, com confiança e reversibilidade) — [docs/decision-log/](docs/decision-log/) | +| Observabilidade | **5 dashboards** Grafana provisionados · **10 alertas** (entrega por e-mail opcional) — Fases 22b/22c | +| Especificações | **33** (SPEC-0001…0034 — não há 0030) — [docs/specs/](docs/specs/) | +| ADRs | **23** — [docs/adr/](docs/adr/) | +| Decisões autônomas registradas | **152** (DL-0001…0152, com confiança e reversibilidade) — [docs/decision-log/](docs/decision-log/) | | Configuração | referência completa de variáveis de ambiente em [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | > Cada número acima é verificável no próprio repo: o log de execução por fase (com horários e @@ -133,6 +135,20 @@ dia (autorização default-deny, hardening, OpenAPI real, emuladores, multi-inst QA hardening, CI supply-chain, postura de produção com TLS/backup/DR) e Fase 20 (teclado-first, Esc/Enter universais, DSS real, design 2026). +**Dia 5 (03/07) — operação enterprise e governança de equipe.** Fase 22 completa (5 fatias, +`0.52.0`→`0.54.0`): gates permanentes de paridade i18n (pt/en, 110 exceções de domínio nos dois +idiomas), **monitoramento enterprise** (5 dashboards Grafana, 10 alertas com entrega por +e-mail), **log inteligente** (Loki/Alloy com `correlationId`/`username` como metadados +estruturados), manual minucioso com **31 screenshots** gerados por script versionado e guia de +instalação do zero. E a **Fase 23 — governança de repositório para trabalho em equipe**: +`main`/`develop` protegidas (**PR obrigatório**, sem push direto), trava do agente em +`.claude/settings.json` (merge/tag/force-push negados), **varredura de segredos** gitleaks +(CI bloqueante + pre-commit + allowlist dos dev-defaults), CODEOWNERS, SECURITY.md, +CONTRIBUTING.md. O primeiro ciclo PR-only (PR #14) pagou o investimento no mesmo dia — expôs +um CI vermelho que o push direto vinha escondendo (ver imprevistos). Na sequência nasceu o +**toolkit de equipe `.claude/`** (10 skills + time de agentes com arquiteto coordenador; +PR #15, mergeado em 04/07 — ver [docs/GUIA-TIME-CLAUDE.md](docs/GUIA-TIME-CLAUDE.md)). + ### O que deu certo (e por quê) - **Os portões seguraram a IA.** O gate do Spring Modulith **pegou um ciclo de dependência** @@ -143,11 +159,11 @@ Esc/Enter universais, DSS real, design 2026). - **Teste primeiro encontrou bugs reais.** A Fase 19i provou **vermelho→verde uma corrida de concorrência real** (lançamento escapando para um período recém-fechado) e o 20c pegou um listener que silenciosamente não persistia (transação read-only → `REQUIRES_NEW`). -- **O decision log pagou o investimento.** As 140 DLs (cada uma com lacuna, decisão, +- **O decision log pagou o investimento.** As 152 DLs (cada uma com lacuna, decisão, justificativa com fontes, alternativas descartadas e custo de reversão) permitiram **revisar decisões em lote** (Fase 19b) e reverter com segurança as que envelheceram mal. - **Specs vivas evitaram retrabalho.** Regra mudou no meio? A spec foi atualizada no mesmo PR. - A rastreabilidade spec → teste → código sobreviveu às 48 releases. + A rastreabilidade spec → teste → código sobreviveu às 55 releases. ### Os imprevistos (nada escondido) @@ -178,23 +194,32 @@ Esc/Enter universais, DSS real, design 2026). pendentes; o supervisor concluiu a fatia de onde ela parou. - **Fase 1 preemptada pelo dono** logo no início para instituir SemVer/versionamento (ADR-0015) antes de qualquer código de negócio — e reiniciada limpa em seguida. +- **O CI estava vermelho desde a Fase 20b — e ninguém viu (03/07):** com push direto, ninguém + olhava os checks; o **primeiro PR revisado** (Fase 23) os expôs. Eram dois problemas reais: + a action do gitleaks exigindo `GITHUB_TOKEN` em eventos de pull request (configuração — não + era vazamento) e um teste de integração *flaky* — verde no Windows local, vermelho no runner + Linux — por resíduo no Postgres singleton compartilhado (asserção de contagem absoluta sem + limpeza `@BeforeEach`). Corrigidos no próprio PR, com a lição codificada como regra da casa + (isolamento `@BeforeEach` + repro Linux só com checkout limpo). Lição maior: branch + protection + PR não é cerimônia — **é o que faz os checks serem vistos**. ## 5. Processos de engenharia de software utilizados | Processo | Como aparece neste repo | |---|---| -| **Spec-Driven Development** | 32 specs com regras testáveis, exemplos e Open Questions; specs vivas atualizadas no PR da fatia | +| **Spec-Driven Development** | 33 specs com regras testáveis, exemplos e Open Questions; specs vivas atualizadas no PR da fatia | | **TDD (red→green→refactor)** | O laço de 7 passos de toda fatia ([TUTORIAL](docs/TUTORIAL.md)); bugs ganham teste de regressão que falha antes | | **DDD pragmático** | 22 bounded contexts do [domínio](docs/DOMAIN.md) → 23 módulos; linguagem ubíqua; eventos como fatos de negócio | | **Monólito modular** | Spring Modulith + ArchUnit como *fitness functions* (fronteiras quebram o build) — ADR-0001/0012 | | **Fatias verticais** | Cada entrega atravessa migração → domínio → API → tela e sai demonstrável; walking skeleton primeiro | -| **ADRs + decision log** | 21 ADRs para arquitetura; 140 DLs para decisões autônomas com confiança/reversibilidade | -| **Gitflow + Conventional Commits + SemVer** | `main`/`develop`/`feature/*`; 48 releases tagueadas de `main`; versão fonte no `pom.xml` (ADR-0015) | -| **CI/CD com quality gates** | GitHub Actions: build+testes+gates, E2E, CodeQL, Dependabot, `npm audit`, imagens GHCR por tag | +| **ADRs + decision log** | 23 ADRs para arquitetura; 152 DLs para decisões autônomas com confiança/reversibilidade | +| **Gitflow + Conventional Commits + SemVer** | `main`/`develop` **protegidas (PR obrigatório — Fase 23)** + `feature/*`; 55 releases tagueadas de `main`; versão fonte no `pom.xml` (ADR-0015) | +| **Governança de repo + secret scanning** | Branch protection PR-only, CODEOWNERS, SECURITY/CONTRIBUTING, trava do agente (`.claude/settings.json`), gitleaks (CI bloqueante + pre-commit, allowlist de dev-defaults) — ADR-0023 | +| **CI/CD com quality gates** | GitHub Actions: build+testes+gates, E2E, CodeQL, gitleaks, Dependabot, `npm audit`, imagens GHCR por tag | | **Contract testing** | Snapshot OpenAPI committado + teste de drift; diagrama de módulos idem | | **Property-based + mutation testing** | jqwik (8 propriedades × 1000 casos na matemática de dinheiro); PIT com piso de 60% | | **E2E isolado** | Playwright contra stack descartável (`compose.e2e.yaml`, Postgres em tmpfs) — nunca o banco de dev | -| **Observabilidade** | Micrometer/Prometheus/Loki/Grafana provisionados, logs JSON com correlação, 5 alertas, `/api/version` | +| **Observabilidade** | Micrometer/Prometheus/Loki/Grafana provisionados — **5 dashboards, 10 alertas** (e-mail opcional), logs JSON com `correlationId`/`username` como metadados estruturados, `/api/version` | | **Security by default** | Autorização default-deny com teste de completude, OIDC+PKCE, HMAC+anti-replay, fail-fast de segredos em prod, cofre AES-GCM | | **DR/backup** | `pg_dump` diário + tar do cofre, retenção 30d/12m/7a, RPO 24h/RTO 4h, ensaio trimestral (ADR-0021) | | **i18n + a11y + LGPD** | pt-BR/en-US de ponta a ponta; WCAG 2.1.4 (toggle de tecla única), `prefers-reduced-motion`; consentimento/erasure/mascaramento | @@ -210,7 +235,7 @@ nível de acabamento** (testes, gates, observabilidade, docs bilíngues): entregaria este escopo em **12–18 meses** ≈ **48–72 pessoas-mês** — assumindo requisitos já consolidados como estão em [docs/DOMAIN.md](docs/DOMAIN.md). -**O que levou de fato: ~3,5 dias corridos**, com **1 pessoa** supervisionando (aprovando +**O que levou de fato: ~4,5 dias corridos**, com **1 pessoa** supervisionando (aprovando planos, decidindo Open Questions de negócio, auditando entregas) e o Claude Code executando — frequentemente em fases autônomas de 30–90 minutos. Mesmo contando cada hora do dono, o esforço humano ficou na casa de **dezenas de horas contra dezenas de milhares**. @@ -352,6 +377,7 @@ fkerp-java-sdd/ ├── frontend/ # Angular 22 + PrimeNG 21 + Tailwind 4 → frontend/README.md ├── infra/ # prometheus/ loki/ alloy/ grafana/ proxy/ backup/ wiremock/ ├── docs/ # TODA a documentação → docs/README.md (índice-mestre) +├── .claude/ # toolkit do time: 10 skills + agentes (arquiteto, devs, QA) + guarda git ├── docker-compose.yml # dev: app + banco + observabilidade (+ profile emulators) ├── compose.e2e.yaml # stack E2E isolada (Postgres efêmero, frontend :4201) ├── compose.prod.yaml # produção: proxy TLS + perfil prod + rede interna @@ -370,6 +396,7 @@ Os documentos-chave, na nova organização: | Ler as especificações | [docs/specs/](docs/specs/) | | Ver as decisões (arquitetura / autônomas) | [docs/adr/](docs/adr/) · [docs/decision-log/](docs/decision-log/) | | Reproduzir o método (o laço por fatia) | [docs/TUTORIAL.md](docs/TUTORIAL.md) · [docs/RUN-PHASE.md](docs/RUN-PHASE.md) | +| Operar o time de agentes e os comandos `/` | [docs/GUIA-TIME-CLAUDE.md](docs/GUIA-TIME-CLAUDE.md) (didático, do zero) | | Ver o plano e o que foi executado (com resultados de teste) | [docs/ROADMAP.md](docs/ROADMAP.md) · [docs/ROADMAP-STATUS.md](docs/ROADMAP-STATUS.md) | | Ver o que mudou em cada versão | [CHANGELOG](docs/release-notes/CHANGELOG.md) · [CHANGELOG en-US](docs/release-notes/CHANGELOG.en-US.md) | | Subir produção (pendências do dono) | [docs/PRODUCTION-CHECKLIST.md](docs/PRODUCTION-CHECKLIST.md) |