chore(23): governança de repositório — sem push/merge autônomo + prot…

.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "comment": "Git safety for team work (ADR-0023). ALLOW: push feature/bugfix/hotfix branches + open PRs to develop (owner's standing authorization) — the normal end of a slice. ASK: create a git tag (only on the owner's explicit request; never automatic). DENY: merge to develop/main, PR merge, release publish, force-push — protected branches change only via reviewed PR; the server-side branch protection is the real enforcement.",
+    "allow": [
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)"
+    ],
+    "ask": [
+      "Bash(git tag)",
+      "Bash(git tag:*)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(git merge)",
+      "Bash(git merge:*)",
+      "Bash(gh pr merge:*)",
+      "Bash(gh release create:*)",
+      "Bash(gh release delete:*)"
+    ]
+  }
+}

.github/CODEOWNERS

@@ -0,0 +1,28 @@
+# Code owners (ADR-0023). With branch protection's "Require review from Code Owners", a PR that
+# touches any path below needs the owner's approval before it can merge. The last matching pattern
+# wins, so the sensitive paths are listed after the catch-all.
+#
+# Replace @fkazeredo with additional maintainer handles/teams as the team grows.
+
+# Default owner for everything.
+*                                                       @fkazeredo
+
+# Governance, agent rules and CI/security config — highest scrutiny.
+/CLAUDE.md                                              @fkazeredo
+/.claude/                                               @fkazeredo
+/.github/                                               @fkazeredo
+/.gitleaks.toml                                         @fkazeredo
+/.pre-commit-config.yaml                                @fkazeredo
+/.gitignore                                             @fkazeredo
+/SECURITY.md                                            @fkazeredo
+/CONTRIBUTING.md                                        @fkazeredo
+
+# Security- and secret-handling code + infra.
+/docs/architecture/security.md                          @fkazeredo
+/backend/src/main/java/com/fksoft/infra/security/       @fkazeredo
+/backend/src/main/java/com/fksoft/infra/platform/       @fkazeredo
+/backend/src/main/resources/application.yml             @fkazeredo
+/infra/                                                 @fkazeredo
+/compose.prod.yaml                                      @fkazeredo
+/.env.example                                           @fkazeredo
+/.env.prod.example                                      @fkazeredo

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!-- Target branch must be `develop` (main is updated only via a release PR). See CONTRIBUTING.md. -->
+
+## Summary
+
+<!-- What changes and why. Link the spec / decision-log entry it implements. -->
+
+- Spec / DL / ADR:
+- Related issue:
+
+## Checklist
+
+- [ ] **No secrets/keys/`.env` committed** (gitleaks clean locally; only enumerated dev-defaults)
+- [ ] Tests added/updated; a **bug fix has a regression test** (fails before, passes after) in **every reachable layer** (unit / integration / contract / frontend / E2E)
+- [ ] `./mvnw verify` green; `npm run lint && npm test && npm run build` green
+- [ ] Spec updated/created; **ADR added** if architecture changed
+- [ ] Flyway **migration** for schema changes (idempotent; no editing an applied migration)
+- [ ] **OpenAPI**/contract snapshot regenerated if endpoints changed
+- [ ] **i18n** messages added (pt-BR **and** en) for user-facing text
+- [ ] **Bilingual docs in sync** (MANUAL / README / release-notes) if user-visible
+- [ ] Target branch is **`develop`** (main only via release PR)
+
+## Screenshots (UI changes)
+
+<!-- Before/after if this touches the frontend. -->

.github/workflows/gitleaks.yml

@@ -0,0 +1,37 @@
+# Secret scanning (ADR-0023 / DL-0152). Blocking gate — CodeQL is SAST only and does not scan for
+# secrets. Scans the full history on every push/PR; a leaked secret in ANY commit fails the check.
+# The check name "Gitleaks" is a required status check on main/develop branch protection.
+name: Gitleaks
+
+on:
+  push:
+    branches: [main, develop, "feature/**", "release/**", "hotfix/**"]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: gitleaks-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    name: Gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so a secret in any past commit is caught
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          # Required by gitleaks-action to scan pull_request events (it reads the PR's commit
+          # range via the API). The default GITHUB_TOKEN with `contents: read` is enough.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_CONFIG: .gitleaks.toml
+          # Personal/public repo: no license needed. If this repo ever moves under a GitHub ORG,
+          # set the GITLEAKS_LICENSE secret. License-free alternative (run the binary directly):
+          #   docker run --rm -v "$PWD:/repo" zricethezav/gitleaks:latest \
+          #     detect --source /repo --config /repo/.gitleaks.toml --redact --no-banner

.gitignore

@@ -50,3 +50,29 @@ backend/.jqwik-database
 # Segredos reais de producao e backups locais - NUNCA versionar.
 .env.prod
 backups/
+
+# ---- Segredos, chaves e certificados (regra de equipe; ADR-0023/DL-0152) ----
+# Qualquer variante de .env fica ignorada, EXCETO os templates rastreados (.example).
+# As negacoes DEVEM vir depois do glob .env.* — a ordem importa.
+.env.*
+!.env.example
+!.env.prod.example
+# Material de chave/certificado — nunca versionar (e-CNPJ, TLS, JWK, keystores).
+*.pem
+*.key
+*.crt
+*.cer
+*.der
+*.p12
+*.pfx
+*.jks
+*.keystore
+*.pkcs12
+*.ppk
+# Pastas/arquivos de credencial e chaves SSH.
+secrets/
+**/secrets/
+credentials.json
+id_rsa
+id_rsa*
+id_ed25519*

.gitleaks.toml

@@ -0,0 +1,34 @@
+# Gitleaks configuration for fkerp-java-sdd (ADR-0023 / DL-0152).
+# Extends the built-in rules and allowlists ONLY the enumerated, documented DEV-ONLY defaults, so a
+# NEW real secret still trips the scan. Do NOT path-allowlist application.yml — only its known dev
+# strings are regex-allowlisted below.
+title = "fkerp-java-sdd secret-scan config"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Intentional, documented DEV-ONLY defaults (blocked in prod by ProdReadinessValidator)."
+
+# Exact known dev tokens — allowed anywhere in the tree (they are seeded/documented on purpose).
+regexes = [
+  '''dev12345''',                                       # seed users (DevUserSeeder / docs / tests)
+  '''dev-metrics-secret''',                             # application.yml ${METRICS_CLIENT_SECRET:...}
+  '''dev-quotation-site-secret''',                      # ${QUOTATION_SITE_SECRET:...}
+  '''dev-payment-webhook-secret''',                     # ${PAYMENT_WEBHOOK_SECRET:...}
+  '''ZGV2LW9ubHktcGxhdGZvcm0tc2VjcmV0LWtleS0zMmI=''',   # AesGcmSecretCipher.DEV_DEFAULT_KEY_BASE64
+]
+
+# Files that carry placeholders / documented example values by design.
+paths = [
+  '''\.env\.example''',
+  '''\.env\.prod\.example''',
+  '''docs/PRODUCTION-CHECKLIST\.md''',                  # per-secret `openssl` generate table
+  '''docs/INSTALL(\.en-US)?\.md''',                     # test-user table (dev12345)
+  '''README(\.en-US)?\.md''',                           # test-user table
+  '''.*Test\.java''',                                   # test fixtures (acme/acme, dev secrets)
+  '''frontend/e2e/.*''',                                # E2E helpers/specs (dev12345)
+]
+
+# Ubiquitous dev tokens that are not secrets in this repo.
+stopwords = ["acme", "admin"]

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+# Local secret-scan guardrail (ADR-0023 / DL-0152). Optional but recommended — CI is the hard gate.
+# Install once:  pipx install pre-commit  &&  pre-commit install
+# It then runs gitleaks on staged changes before every commit, catching a secret before it is even
+# committed. Uses the same allowlist as CI via .gitleaks.toml.
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2 # pinned; bump deliberately
+    hooks:
+      - id: gitleaks

CLAUDE.md

@@ -39,6 +39,18 @@ Detailed guidelines live in `docs/architecture/` and are loaded on demand (see R
    E2E). One layer is not enough when the defect spans more; skipping an applicable layer
    requires an explicit stated reason. Details: `docs/architecture/testing.md` (§Regression
    tests). Owner rule (Fase 21a/22a) — never close a bug without its regression.
+9. **Git & secret safety (owner rule, Fase 23 / ADR-0023).** Work happens on a `feature/*`/
+   `bugfix/*` branch with local commits. **When the slice is complete and green (tested)**, the
+   agent **pushes the feature branch and opens a PR targeting `develop`** — that is the normal end
+   of a slice. The agent **NEVER merges to `develop` or `main`** and **never force-pushes**; it
+   creates a **tag only on the owner's explicit request** (never automatically). Merging a PR into a
+   protected branch and cutting a release are **human, reviewed** actions (`main` changes only via a
+   release PR). Enforced by `.claude/settings.json` (allow `git push`/`gh pr create`; ask `git tag`;
+   deny `git merge`, `gh pr merge`, `gh release create`, force-push). **Never commit a secret, key,
+   certificate or
+   `.env`** — gitleaks (CI + optional pre-commit) blocks them; the only in-repo credentials are the
+   enumerated dev-only defaults (allowlisted in `.gitleaks.toml`, blocked in prod by
+   `ProdReadinessValidator`). See `CONTRIBUTING.md`, `SECURITY.md`, ADR-0023.
 
 ## Definition of Done (every meaningful change)
 
@@ -88,6 +100,7 @@ Regra do dono (Fase 22a). Sempre que estiver executando em modo autônomo/auto-a
 | Angular code, components, forms, state, UI | `docs/architecture/frontend-angular.md` |
 | Writing or changing tests | `docs/architecture/testing.md` |
 | Build, dependencies, Git, CI/CD, Docker, deploy, feature flags | `docs/architecture/delivery.md` |
+| Git push/merge/PR policy, branch protection, secrets, contributing | `CONTRIBUTING.md` · `SECURITY.md` · `docs/architecture/delivery.md` (ADR-0023) |
 | Creating a new project from this template | `docs/architecture/workflow.md` (section: New Project) |
 
 ## Project commands
@@ -101,8 +114,11 @@ cd backend && ./mvnw spotless:apply   # format
 npm run lint && npm test              # frontend (from spec 0002)
 ```
 
-Destructive operations are governed by `.claude/settings.json` permissions. Do not attempt
-to work around a denied command; explain the risk and ask the user to run it themselves.
+Destructive and remote operations are governed by `.claude/settings.json` permissions (invariant 9 /
+ADR-0023): pushing a **feature branch** and `gh pr create` (PR → `develop`) are **allowed** as the
+normal end of a slice; `git tag` **asks** (only on the owner's explicit request); `git merge`,
+`gh pr merge`, `gh release create` and **force-push** are **denied** (protected branches change only
+via reviewed PR). Do not work around a denied command; explain the risk and ask the user to run it.
 
 ## Command — User manual (pt-BR) [`/manual`]
 

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for helping improve the Acme Travel ERP. This project uses a **protected, PR-only** workflow.
+The operating rules for every change live in [CLAUDE.md](CLAUDE.md); this file is the
+human/team-facing summary.
+
+## Branching & Pull Requests
+
+- **`main`** = production; **`develop`** = integration. Both are **protected**: **no direct pushes**,
+  **no direct merges** — changes land only through a **reviewed Pull Request** with green checks.
+- Work on a branch off `develop`: `feature/<slug>` (or `bugfix/<slug>`, `hotfix/<slug>`). Use
+  [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `test:`, `docs:`, …).
+- **Open your PR against `develop`.** `main` is updated **only via a release PR** (`develop → main`)
+  at the end of a phase, from which the release tag is cut by a maintainer.
+- Keep PRs focused and reviewable: include tests, spec/ADR updates, Flyway migrations, screenshots
+  for UI changes and API-contract impacts.
+
+### AI agents (Claude Code) — hard rule
+
+An automated agent works on a `feature/*`/`bugfix/*` branch with local commits. **When the slice is
+complete and green (tested), the agent pushes the feature branch and opens a PR targeting
+`develop`** — the normal end of a slice. The agent **must NOT** `git merge` (to `develop` **or**
+`main`), `gh pr merge`, or **force-push**; it creates a **tag only on the owner's explicit request**.
+**Merging** the PR into a protected branch and cutting a release are **human, reviewed** actions.
+Enforced locally by `.claude/settings.json` (allow `git push`/`gh pr create`; ask `git tag`; deny
+merge/pr-merge/release/force) and on the server by branch protection (ADR-0023).
+
+## Branch protection (maintainer setup on GitHub)
+
+Configure identical rules for `main` and `develop` (Settings → Branches / Rulesets):
+
+- Require a pull request before merging; **≥ 1 approving review**; **require review from Code Owners**
+  (`.github/CODEOWNERS`); dismiss stale approvals on new commits; require conversation resolution.
+- Require status checks to pass and branches to be up to date. Required checks: **Backend verify**,
+  **Mutation (PIT)**, **Flyway validate**, **Frontend lint/test/build**, **Playwright E2E**,
+  **CodeQL (java-kotlin)**, **CodeQL (javascript-typescript)**, **Gitleaks**.
+- Require **linear history**; **block force pushes**; **restrict deletions**; **include
+  administrators** (no bypass).
+- Enable **Secret scanning + Push protection** and **Dependabot alerts** (Settings → Code security).
+
+## Quality gates (run before opening a PR)
+
+```bash
+cd backend && ./mvnw spotless:apply && ./mvnw verify   # ArchUnit, Modulith, Testcontainers, JaCoCo, OpenAPI gate
+cd frontend && npm run lint && npm test && npm run build
+npm run e2e:up && npx playwright test && npm run e2e:down   # E2E (isolated stack)
+```
+
+Never weaken, skip or delete a gate to make code pass (CLAUDE.md invariant). A **bug fix requires a
+regression test** in every reachable layer (fails before, passes after).
+
+## Secrets
+
+**Never commit a secret, key, certificate or `.env` file.** Gitleaks (CI + optional pre-commit)
+blocks them; see [SECURITY.md](SECURITY.md). The only in-repo credentials are the **enumerated
+dev-only defaults** (e.g. `dev12345`), allowlisted in `.gitleaks.toml` and blocked in production by
+`ProdReadinessValidator`. Optional local guard:
+
+```bash
+pipx install pre-commit && pre-commit install   # runs gitleaks on every commit
+```
+
+## Documentation
+
+- **Bilingual, in sync in the same PR:** user manual (`docs/MANUAL.md` + `.en-US.md`), `README`
+  (+ `.en-US`), release notes (`docs/release-notes/CHANGELOG.md` + `.en-US.md`).
+- **pt-BR only** (Rule Zero — no ceremony translations): specs, ADRs, decision-log, plans, reports.
+- Update the user manual for any user-visible change; add an ADR when architecture changes; record
+  autonomous decisions in `docs/decision-log/`.
+
+See also: [docs/architecture/delivery.md](docs/architecture/delivery.md) (Git/CI/CD) and
+[ADR-0023](docs/adr/0023-repo-governance-branch-protection-and-secret-scanning.md).

README.en-US.md

@@ -375,8 +375,15 @@ The key documents, in the new organization (technical artifacts are pt-BR by con
 | 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) |
 | Configure via environment variables | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |
+| Contribute (PR flow, gates) | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Report a vulnerability / secret policy | [SECURITY.md](SECURITY.md) |
 | The complete documentation index | [docs/README.md](docs/README.md) |
 
+> **Contributing & security.** `main` and `develop` are **protected branches** — they change **only
+> via a reviewed Pull Request** (no direct push). See [CONTRIBUTING.md](CONTRIBUTING.md). Found a
+> security issue? **Do not open a public issue** — report it privately (see [SECURITY.md](SECURITY.md)).
+> No secret is ever committed (gitleaks + `.gitignore`); rules in [ADR-0023](docs/adr/README.md).
+
 ## 10. License and usage
 
 This project is licensed under **[0BSD](LICENSE)** (BSD Zero Clause): **use it however you

README.md

@@ -374,8 +374,15 @@ Os documentos-chave, na nova organização:
 | 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) |
 | Configurar por variável de ambiente | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |
+| Contribuir (fluxo de PR, gates) | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Reportar vulnerabilidade / política de segredos | [SECURITY.md](SECURITY.md) |
 | O índice completo da documentação | [docs/README.md](docs/README.md) |
 
+> **Contribuição e segurança.** `main` e `develop` são **branches protegidas** — mudam **só via
+> Pull Request revisado** (sem push direto). Veja [CONTRIBUTING.md](CONTRIBUTING.md). Encontrou uma
+> falha de segurança? **Não abra issue pública** — reporte em privado (ver [SECURITY.md](SECURITY.md)).
+> Nenhum segredo é commitado (gitleaks + `.gitignore`); regras em [ADR-0023](docs/adr/README.md).
+
 ## 10. Licença e uso
 
 Este projeto está sob a licença **[0BSD](LICENSE)** (BSD Zero Clause): **use como bem