Flujo de trabajo con Git

Ramas

Rama	Uso	Despliegue
`feature/`, `fix/`, `docs/`, `chore/` + área y tema	Trabajo de cada tarea	No
`dev`	Integración y QA	No
`stage`	Preproducción	Sí
`main`	Producción	Sí

flowchart LR
  W[feature/... fix/... docs/... chore/...] -- PR + squash --> D[dev]
  D -- PR + merge --> S[stage]
  S -- PR + merge --> M[main]

Todo cambio llega por Pull Request; no hay push directo a dev, stage ni main.
Ningún PR se fusiona si el CI falla, y no se saltan etapas. Las correcciones urgentes siguen el mismo camino.
Ejemplos de nombres: feature/back-incidents-crud, docs/front-design-tokens.

Commits

Se usa Conventional Commits: tipo y ámbito en inglés, descripción en español.

feat(incidents): agregar filtro por rango de vencimiento
fix(auth): corregir bloqueo progresivo tras reinicio de contraseña
docs(adr): registrar decisión de tablas catálogo

Tipos permitidos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Hooks locales

Al instalar las dependencias de la raíz (npm install) se activan los hooks de Lefthook. Revisan solo lo que cambió, para que sean rápidos; la validación completa la hace el CI.

Hook	Qué revisa
`pre-commit`	Formato del PHP modificado (Pint, dentro del contenedor), ESLint, Prettier y Stylelint del frontend, y secretos con Gitleaks
`commit-msg`	Formato Conventional Commits del mensaje

Los hooks del backend y de secretos usan Docker, así que el stack o al menos Docker Desktop deben estar encendidos.

Versiones

Cada llegada a main se etiqueta con SemVer y el CHANGELOG se genera a partir de los commits.

Dónde está en el código

lefthook.yml: hooks configurados, y scripts/git/scan-secrets.mjs para los secretos.
scripts/git/check-commit-msg.mjs: validación del mensaje de commit.
.github/pull_request_template.md: checklist de cada PR.
Decisión: ADR-0033.