repo_Claude/.claude/commands/git-push.md

# Command: git push

Integra cambios a master y publica. Soporta ramas `issue/*` y `quick/*`.

## Flujo obligatorio

### 1. Verificar rama actual y estado

```bash
git branch --show-current
git status --short
```

#### Si estamos en una rama `issue/*` o `quick/*`

Continuar directamente al paso 2.

#### Si estamos en `master` con cambios pendientes

Crear una rama automaticamente antes de continuar:

1. Preguntar al usuario: **¿Este cambio esta asociado a un issue existente?**
2. **Si es un issue**: pedir el numero y slug, crear rama `issue/<NNNN>-<slug>`.
3. **Si NO es un issue**: pedir un slug descriptivo, crear rama `quick/<slug>`.

```bash
# Para issues:
git checkout -b issue/<NNNN>-<slug>
# Para cambios rapidos:
git checkout -b quick/<slug>
```

4. Continuar al paso 2 con los cambios ya en la rama nueva.

**IMPORTANTE**: No inventar numeros de issue. Solo usar `issue/` si el issue existe en `dev/issues/`.

#### Si estamos en `master` sin cambios

**STOP**: no hay nada que publicar.

### 2. Revisar cambios y crear commits por bloque

```bash
git status --short
git diff --stat
git diff
```

Crear commits **atomicos por bloque logico**. Cada commit agrupa cambios de la misma naturaleza:

```bash
git add <archivos_del_bloque_1>
git commit -m "<tipo>: <resumen breve>" -m "Descripcion larga en espanol explicando que cambia, por que se hizo, impacto esperado y alcance del bloque."

git add <archivos_del_bloque_2>
git commit -m "<tipo>: <resumen breve>" -m "Descripcion larga en espanol."
```

**Reglas criticas de commits:**
- **No WIP**: nunca commitear "wip", "tmp", "fix fix" ni codigo a medias. Cada commit debe ser atomico y completo.
- **No mezclar tipos**: no combinar `feat:` + `test:` en un mismo commit. Separar por bloque logico.
- **No squash**: los commits individuales se preservan en master via `--no-ff`. Usar `git log --first-parent master` para ver solo merge commits.
- **No rebase interactivo**: si los commits ya son limpios, no reescribir historia.

### 3. Ejecutar tests

**Obligatorio antes de mergear.** Si el proyecto tiene tests, ejecutarlos:

```bash
go test -tags goolm ./...
```

- Si los tests **fallan** → **STOP**: corregir antes de continuar. No mergear codigo roto.
- Si los tests **pasan** → continuar al paso 4.
- Si no hay tests aplicables (e.g. solo cambios de docs/config) → indicar al usuario y continuar.

### 4. Evaluar feature flags

Feature flags se usan cuando el issue es **parte de una feature multi-issue** o el cambio tiene riesgo y necesita poder desactivarse. **Feature flag ≠ WIP** — un flag protege codigo terminado y testeado, no codigo a medias.

Si se modifico `dev/feature_flags.json` o si los cambios son parte de una feature que se despliega en fases:

1. Verificar que `dev/feature_flags.json` existe y esta actualizado.
2. Confirmar que el flag correspondiente tiene el estado correcto (`enabled: true/false`).
3. Incluir el archivo en el commit correspondiente (no crear commit separado solo para flags).

Si el issue es autocontenido (se completa en esta rama), no necesita flag. Saltar este paso.

### 5. Actualizar master y hacer merge --no-ff

```bash
git checkout master
git pull --rebase
git merge --no-ff <rama> -m "merge: <rama> — <titulo breve>"
```

El merge commit debe tener formato:
- Titulo: `merge: <rama> — <descripcion corta>`
- Cuerpo (opcional): resumen de lo que entra

Ejemplos:
- `merge: issue/0021-threads-default-config — habilitar threads en agentes`
- `merge: quick/fix-typo-readme — corregir typo en README`

Si hay conflictos durante el merge:
1. Resolver los conflictos
2. `git add` los archivos resueltos
3. `git commit` (sin -m, para mantener el mensaje de merge)

### 6. Push a remoto

```bash
git push
```

### 7. Limpiar rama local

```bash
git branch -d <rama>
```

### 8. Confirmar al usuario

```
Rama `<rama>` integrada a master y publicada.
Rama local eliminada.
```

## Convencion de commits

- `feat:` nueva funcionalidad
- `fix:` correccion de error
- `refactor:` cambio estructural sin cambio funcional
- `docs:` documentacion
- `chore:` mantenimiento
- `test:` tests nuevos o modificados
- `merge:` commit de merge (generado por --no-ff)

## Regla de mensajes

- El titulo (`-m` corto) debe resumir el bloque.
- El cuerpo (`-m` largo) debe estar en espanol y explicar:
  - que se cambio,
  - por que se cambio,
  - que impacto tiene,
  - que no se toco.

## Checklist rapido

- [ ] Todos los cambios estan commiteados en una rama `issue/*` o `quick/*`.
- [ ] Se separaron cambios distintos en commits diferentes.
- [ ] Cada commit tiene descripcion larga en espanol.
- [ ] Tests ejecutados y pasando (o no aplican).
- [ ] Feature flags evaluados (o no aplican).
- [ ] `git merge --no-ff` ejecutado desde master.
- [ ] `git push` ejecutado correctamente.
- [ ] Rama local eliminada.