fkazeredo · fkazeredo · Jul 4, 2026 · Jul 4, 2026
@@ -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) |