@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/git-flow.en.md

@@ -0,0 +1,525 @@
+# Git Flow
+
+Mandatory versioning standard for every project adopting `development-utility-kit`. Combines classic Git Flow with Conventional Commits and the agent-driven review rules (`code-reviewer`, `tech-lead`, `release-engineer`).
+
+## Why Git Flow is mandatory
+
+- **Traceability**: every piece of work goes through an intention-named branch (`feature/`, `bugfix/`, `hotfix/`, `release/`) — history is easy to read and the origin of each change is obvious.
+- **Safe hotfixes**: production has a stable line (`main`) that never receives direct commits. Hotfixes leave `main`, return to `main` and `develop` simultaneously, without dragging in-progress features along.
+- **Prepared releases**: the `release/*` branch lets you stabilize a version (version bump, CHANGELOG, smoke tests) without freezing the whole team on `develop`.
+- **Senior+ gate compatibility**: the pipeline (`auto-test-guard`, `gate-keeper`, `code-reviewer`, `tech-lead`) assumes PRs between named branches. Direct work on `main` or `develop` breaks the pipeline.
+- **Cross-project standardization**: switching projects, the dev finds the same topology, branch names, and commit format.
+
+## Canonical branches
+
+```
+              hotfix/*
+               │
+               ▼
+     ┌────────main────────┐         ← production (only merges via PR from
+     │                     │           release/* or hotfix/*)
+     │  release/*          │
+     │     ▲               │
+     │     │               │
+     ▼─────┴──develop──────┘         ← integration (receives PRs from
+                ▲   ▲                  feature/* and bugfix/*)
+                │   │
+       feature/*│   │bugfix/*
+```
+
+| Branch       | Base       | Target (merge)          | Purpose                                                                                    |
+|--------------|------------|-------------------------|--------------------------------------------------------------------------------------------|
+| `main`       | —          | —                       | Production. Only merges via PR from `release/*` or `hotfix/*`. Every merge produces a tag. |
+| `develop`    | `main`     | —                       | Continuous integration of features. May be ahead of `main` by several features.            |
+| `feature/*`  | `develop`  | `develop` (via PR)      | New feature. Naming: `feature/<short-slug>` (e.g., `feature/auth-refresh-token`).          |
+| `release/*`  | `develop`  | `main` + `develop` (PR) | Release preparation. Version bump, CHANGELOG, smoke. Naming: `release/v1.4.0`.             |
+| `hotfix/*`   | `main`     | `main` + `develop` (PR) | Urgent production fix. Naming: `hotfix/<short-slug>` (e.g., `hotfix/payment-rounding`).    |
+| `bugfix/*`   | `develop`  | `develop` (via PR)      | Non-urgent dev bug fix. Naming: `bugfix/<short-slug>`.                                     |
+
+Absolute rule: **never commit directly to `main` or `develop`**. Every change enters via PR.
+
+## Feature flow
+
+### Start
+
+```bash
+git checkout develop
+git pull origin develop
+git flow feature start auth-refresh-token
+# manual equivalent:
+# git checkout -b feature/auth-refresh-token develop
+```
+
+### Development
+
+Make small, atomic commits with Conventional Commits messages:
+
+```bash
+git add src/auth/refresh-token.ts
+git commit -m "feat(auth): add POST /api/v1/auth/refresh endpoint"
+
+git add src/auth/refresh-token.spec.ts
+git commit -m "test(auth): cover refresh token rotation and expiry"
+
+git add docs/api/auth.md
+git commit -m "docs(auth): document refresh token payload"
+```
+
+### Finish
+
+Two valid options:
+
+**Option A — `git flow feature finish`** (local merge + branch delete). Use only on solo projects or with off-GitHub review:
+
+```bash
+git flow feature finish auth-refresh-token
+git push origin develop
+```
+
+**Option B — Pull Request (recommended for teams)**:
+
+```bash
+git push origin feature/auth-refresh-token
+gh pr create --base develop --head feature/auth-refresh-token \
+  --title "feat(auth): refresh token rotation" \
+  --body "$(cat .github/PULL_REQUEST_TEMPLATE.md)"
+```
+
+The PR triggers `code-reviewer` (initial review), then `tech-lead` for final approval. After merge, the remote branch is auto-deleted.
+
+## Release flow
+
+A release branches off `develop` and prepares the delivery for `main`.
+
+```bash
+git checkout develop
+git pull origin develop
+git flow release start v1.4.0
+# git checkout -b release/v1.4.0 develop
+```
+
+On the `release/*` branch, `release-engineer` runs:
+
+1. **Version bump**:
+   ```bash
+   # Backend (Maven)
+   mvn versions:set -DnewVersion=1.4.0 -DgenerateBackupPoms=false
+
+   # Frontend (npm)
+   npm version 1.4.0 --no-git-tag-version
+   ```
+2. **CHANGELOG**: generates/updates `CHANGELOG.md` from Conventional Commits since the previous tag.
+3. **Smoke tests**: runs `auto-test-guard` + `api-integration-test`.
+4. **Release commit**:
+   ```bash
+   git commit -am "chore(release): v1.4.0"
+   ```
+
+Finishing produces two simultaneous PRs (`main` and `develop`):
+
+```bash
+git push origin release/v1.4.0
+gh pr create --base main    --head release/v1.4.0 --title "chore(release): v1.4.0"
+gh pr create --base develop --head release/v1.4.0 --title "chore(release): v1.4.0 back-merge"
+```
+
+After `tech-lead` approval, merge **both**. Then create the tag:
+
+```bash
+git checkout main
+git pull origin main
+git tag -a v1.4.0 -m "Release v1.4.0"
+git push origin v1.4.0
+```
+
+`release-engineer` never runs `git push` or `git tag` directly — it only prepares the commands; the human executes them.
+
+## Hotfix flow
+
+Hotfix fixes production without going through `develop`.
+
+```bash
+git checkout main
+git pull origin main
+git flow hotfix start payment-rounding
+# git checkout -b hotfix/payment-rounding main
+```
+
+Apply the fix, commit, open two PRs:
+
+```bash
+git commit -am "fix(payment): correct cent rounding in BRL amounts"
+git push origin hotfix/payment-rounding
+
+gh pr create --base main    --head hotfix/payment-rounding
+gh pr create --base develop --head hotfix/payment-rounding
+```
+
+After merge, patch bump (`v1.4.1`) and tag, same as release flow. **The branch must be merged into `main` AND `develop`** — forgetting the back-merge makes the hotfix reappear as a regression in the next release.
+
+## Bugfix flow
+
+Identical to feature flow but signals a non-urgent fix:
+
+```bash
+git checkout develop
+git flow bugfix start dropdown-overflow-mobile
+# implementation + commit
+git push origin bugfix/dropdown-overflow-mobile
+gh pr create --base develop --head bugfix/dropdown-overflow-mobile
+```
+
+The difference vs `hotfix/*` is that bugfix **does not** go to `main` directly — it ships with the next normal release.
+
+## Conventional Commits
+
+Every commit message follows the format:
+
+```
+<type>(<scope>): <short description in imperative>
+
+[optional body, 72-char line breaks]
+
+[optional footer: BREAKING CHANGE, Closes #N, Refs #N]
+```
+
+### Allowed types
+
+| Type       | When to use                                                                  |
+|------------|------------------------------------------------------------------------------|
+| `feat`     | New user-facing feature or API consumer-visible feature                      |
+| `fix`      | Bug fix                                                                      |
+| `refactor` | Code reorganization with no behavior change                                  |
+| `test`     | Add/adjust tests (unit, integration, E2E)                                    |
+| `docs`     | Documentation change (Markdown, JSDoc, Javadoc)                              |
+| `chore`    | Maintenance task (dependencies, build, release)                              |
+| `perf`     | Performance improvement with no behavior change                              |
+| `style`    | Formatting, lint, whitespace (no logic changes)                              |
+| `build`    | Build system change (Docker, Maven, npm)                                     |
+| `ci`       | CI/CD pipeline change (GitHub Actions, GitLab CI)                            |
+| `revert`   | Reverts a previous commit — body must cite the reverted SHA                  |
+
+### Scope
+
+Optional but **strongly recommended**. Identifies the affected module: `auth`, `payment`, `user`, `web`, `db`, `mobile`, `infra`, `ci`. Enables history filtering:
+
+```bash
+git log --oneline --grep="^feat(auth)"
+```
+
+### Good examples
+
+```
+feat(auth): rotate refresh token every 24h
+fix(payment): correct cent rounding in BRL amounts
+refactor(user): extract email validation to domain service
+test(order): cover cancellation after payment scenario
+docs(api): document RFC 9457 error payload
+chore(deps): bump spring-boot to 4.0.3
+perf(query): add composite index on orders(user_id, created_at)
+build(docker): migrate base image to eclipse-temurin:25-jre-alpine
+ci(release): add automatic version bump job
+revert: revert "feat(payment): add recurring PIX"
+
+This reverts commit a1b2c3d4. Production bug with duplicated charges.
+```
+
+### Bad examples
+
+```
+# Too generic
+update code
+fix stuff
+WIP
+
+# Missing Conventional type
+added user endpoint
+Fixed bug
+
+# Subject too long (>72 chars)
+feat(auth): add endpoint POST /api/v1/auth/refresh that rotates refresh tokens every 24h with configurable expiry
+
+# Mixing concerns
+feat(auth): refresh token + payment bugfix + README update
+```
+
+### Body and footer
+
+Body explains **why** (not what — the diff already shows what). Footer marks breaking changes and issue references:
+
+```
+feat(api): switch pagination format to metadata wrapper
+
+The response used to be a bare array. It now returns
+{ data: [...], meta: { page, size, total } } to support
+pagination across all resources.
+
+BREAKING CHANGE: existing clients must change from
+res.data[0] to res.data.data[0].
+
+Closes #142
+Refs ADR-021
+```
+
+## Non-negotiable restrictions
+
+> **NON-NEGOTIABLE**
+>
+> - **NEVER** include references to "Claude", "Anthropic", "AI", "LLM", "assistant", or any AI tool in commit text (subject, body, trailers).
+> - **NEVER** add a `Co-Authored-By: Claude <noreply@anthropic.com>` line or anything similar.
+> - Commits must look 100% written by the human developer on the team.
+> - Violation = `tech-lead` refuses the merge and the commit must be rewritten.
+
+### Why this rule exists
+
+Commit history is the professional authorship record of the team. Leaking assistance tooling pollutes audit trails, adds noise to code review, and may breach internal IP policies. Whoever signs the commit owns it — and the owner is the human.
+
+### How to avoid accidents
+
+1. Configure your `~/.gitconfig` without auto-injected assistant trailers.
+2. Before `git commit`, read the full message (`git commit -v` shows the diff too).
+3. If a tool suggested a message containing any AI reference, **edit before committing**.
+4. Use a `commit-msg` hook (see Hooks section) to block automatically.
+
+### How to fix if it slipped through
+
+For the latest commit (not yet pushed):
+
+```bash
+git commit --amend
+# Rewrite removing the reference. Save.
+```
+
+For several commits (not yet pushed):
+
+```bash
+git rebase -i HEAD~5
+# Mark commits as `reword`, save, edit each message.
+```
+
+For commits already pushed on your own feature branch (not on `main`/`develop`):
+
+```bash
+git rebase -i origin/develop
+# Rewrite, then force-push ONLY on your branch:
+git push --force-with-lease origin feature/<your-branch>
+```
+
+If it already landed in `main` or `develop`, open an incident with `tech-lead` — rewriting shared history needs team coordination.
+
+## Pull Requests
+
+### Title
+
+Use Conventional Commits, same as the commit:
+
+```
+feat(auth): refresh token rotation
+```
+
+### Body
+
+Use a standard template (place it in `.github/PULL_REQUEST_TEMPLATE.md`):
+
+```markdown
+## What changed
+
+2-4 lines summary of what was done and why.
+
+## How to test
+
+Reproducible steps (curl, commands, UI scenario).
+
+```bash
+curl -X POST http://localhost:8080/api/v1/auth/refresh \
+  -H "Authorization: Bearer <token>"
+```
+
+## Checklist
+
+- [ ] Unit tests green (`./mvnw test` / `npm test`)
+- [ ] Coverage >= 85% lines, >= 80% branches
+- [ ] Mutation score >= 70% (`./mvnw verify -Ppitest`)
+- [ ] Lint zero warnings (`npm run lint -- --max-warnings 0`)
+- [ ] Documentation updated (if applicable)
+- [ ] No `// TODO` in production code
+- [ ] No `console.log` / `System.out.println`
+- [ ] No hardcoded secrets
+
+## References
+
+Closes #N
+ADR-XXX (if architectural decision involved)
+```
+
+### Reviewers
+
+| PR type                   | Automatic reviewer       | Human reviewer                |
+|---------------------------|--------------------------|-------------------------------|
+| `feature/*` → `develop`   | `code-reviewer`          | `tech-lead`                   |
+| `bugfix/*` → `develop`    | `code-reviewer`          | `tech-lead`                   |
+| `release/*` → `main`      | `code-reviewer`          | `tech-lead` + `product-owner` |
+| `hotfix/*` → `main`       | `code-reviewer`          | `tech-lead`                   |
+| Cross-team (touches >1 area) | `code-reviewer`       | `tech-lead` + area lead       |
+
+`code-reviewer` runs automatically when the PR opens and comments inline. `tech-lead` provides the final approval and blocks if the senior+ gate fails.
+
+## Agent integration
+
+| Agent              | Role in Git Flow                                                                                         |
+|--------------------|----------------------------------------------------------------------------------------------------------|
+| `release-engineer` | On `release/*`: version bump, CHANGELOG generation, prepares `git tag` commands for the human to run.    |
+| `tech-lead`        | Final review on every PR targeting `main` or `develop`. Blocks if senior+ gate fails.                    |
+| `code-reviewer`    | Automatic inline review when PR opens. Comments on patterns, dead code, naming, error handling.          |
+| `gate-keeper`      | Runs senior+ gate (coverage, mutation, a11y, Lighthouse). Blocks merge if thresholds are not met.        |
+| `qa-engineer`      | Generates missing tests during the feature, before the PR.                                               |
+| `analyst`          | Produces `PLAN_*.md` that becomes the base for the feature commits (1 PLAN = 1 `feature/*` branch typically). |
+
+`release-engineer` **does not** run `git push --tags` or `git push origin main` — it only prints commands for the human.
+
+## Relevant local git hooks
+
+> Note: these are **git hooks** (files in `.git/hooks/`), different from **Claude Code hooks** (see [Hooks reference](hooks-reference)).
+
+### `commit-msg` — validates Conventional Commits
+
+File: `.git/hooks/commit-msg`
+
+```bash
+#!/usr/bin/env bash
+# Blocks commits outside Conventional Commits format
+# and any AI/assistant reference in the message.
+
+msg_file="$1"
+msg=$(cat "$msg_file")
+
+# Conventional Commits pattern
+pattern='^(feat|fix|refactor|test|docs|chore|perf|style|build|ci|revert)(\([a-z0-9-]+\))?: .{1,72}'
+
+if ! echo "$msg" | head -n1 | grep -Eq "$pattern"; then
+  echo "ERROR: commit outside Conventional Commits format."
+  echo "Expected format: <type>(<scope>): <description>"
+  exit 1
+fi
+
+# Blocks AI references
+if echo "$msg" | grep -Eiq '(claude|anthropic|\bai\b|llm|co-authored-by:\s*claude|assistant)'; then
+  echo "ERROR: message contains AI/assistant reference — forbidden."
+  exit 1
+fi
+```
+
+Make it executable:
+
+```bash
+chmod +x .git/hooks/commit-msg
+```
+
+### `pre-push` — local gate (optional)
+
+File: `.git/hooks/pre-push`
+
+```bash
+#!/usr/bin/env bash
+# Runs tests before push. Skip with --no-verify if needed.
+
+if [ -f pom.xml ]; then
+  ./mvnw -q test || exit 1
+fi
+
+if [ -f package.json ]; then
+  npm test -- --watchAll=false || exit 1
+fi
+```
+
+### Distributing hooks in the project
+
+Hooks in `.git/hooks/` are not versioned. To share, use `core.hooksPath`:
+
+```bash
+# Version hooks in scripts/git-hooks/ and configure each clone
+git config core.hooksPath scripts/git-hooks
+```
+
+Other hook integrations are described in [Hooks reference](hooks-reference) — do not confuse the two systems.
+
+## Anti-patterns — what NOT to do
+
+- **Direct commit to `main` or `develop`**: violates the "everything via PR" rule. Configure branch protection on GitHub/GitLab to block it.
+- **Merge without PR**: skips `code-reviewer`, `tech-lead`, and the senior+ gate. Even when technically possible, the process forbids it.
+- **Squash that erases Conventional history**: when "Squash and merge"-ing, the final message must remain Conventional. Do not let GitHub generate messages like "Merge pull request #42 from feature/auth".
+- **Force push on shared branch**: `git push --force` on `main`, `develop`, `release/*` or `hotfix/*` breaks other devs' checkouts. Use `--force-with-lease` only on your own feature branch.
+- **Long branches (> 5 days without rebase)**: increase conflicts. Rebase against `develop` at least once a day.
+- **Mixing types in the same commit**: `feat + fix + refactor` in one commit pollutes the CHANGELOG and complicates revert. Split.
+- **Forgetting hotfix back-merge into `develop`**: guarantees regression in the next release. Always two PRs.
+- **Manual tag before merge to `main`**: only tag after confirmed merge. Tagging a commit not in `main` causes confusion.
+
+## Quick FAQ
+
+### How do I revert a merge on `main`?
+
+```bash
+git checkout main
+git revert -m 1 <merge-commit-SHA>
+git push origin main
+```
+
+`-m 1` tells git that parent 1 (the base, i.e., `main` before the merge) is what we want to keep. The revert becomes a new commit — history is preserved.
+
+### How do I cherry-pick a hotfix to `develop` manually?
+
+If you forgot to open the PR to `develop`:
+
+```bash
+git checkout develop
+git pull origin develop
+git cherry-pick <fix-commit-SHA>
+git push origin develop
+```
+
+If conflicts arise, resolve them, then `git cherry-pick --continue`.
+
+### How do I rebase safely on a long-running feature?
+
+```bash
+git checkout feature/my-feature
+git fetch origin
+git rebase origin/develop
+# Resolve conflicts commit by commit
+git push --force-with-lease origin feature/my-feature
+```
+
+`--force-with-lease` (not `--force`) protects against overwriting commits another dev may have pushed to your branch without your knowledge.
+
+### Can I use `merge --no-ff` instead of `git flow`?
+
+Yes, `git flow` is syntactic sugar. The essentials are:
+
+- Properly named branch.
+- Merge via PR (not local).
+- Merge commit preserved (`--no-ff`), so history clearly shows where the feature started and ended.
+
+### What if `commit-msg` hook complains about an old message during rebase?
+
+The hook only runs on new commits. In a rebase with `reword`, it validates the new message. Rewrite to Conventional. If it is an old merge you did not author, ask the `tech-lead` for guidance.
+
+### How do I block direct push to `main` on GitHub?
+
+In **Settings → Branches → Branch protection rules**:
+
+- Pattern: `main`
+- Require pull request before merging: on
+- Require approvals: 1+
+- Require status checks to pass: CI gate
+- Restrict pushes that create matching branches: on
+
+Replicate for `develop`.
+
+## References
+
+- [Pipeline](pipeline) — overview of the task pipeline, from discovery to merge.
+- [Agents reference](agents-reference) — details of each agent involved in the flow (`release-engineer`, `tech-lead`, `code-reviewer`, `gate-keeper`).
+- [Quality gate](quality-gate) — thresholds applied before merge.
+- [Autonomy matrix](autonomy-matrix) — who decides what in review conflicts.
+- [Hooks reference](hooks-reference) — difference between git hooks and Claude Code hooks.
+- [Troubleshooting](troubleshooting) — common issues in Git Flow, commits, and PRs.