Wiedii — Políticas de Desarrollo Core

Estas reglas aplican a todo repositorio Wiedii, sin excepción, tanto para el equipo humano como para agentes de desarrollo.

Gobernanza: el Tech Lead (TL) es el responsable de definir, implementar y mantener las políticas y directrices de Desarrollo. Las autorizaciones excepcionales que mencionan estas reglas (instalar fuera de Homebrew, agregar una herramienta de IA a la lista blanca, etc.) las concede el TL, y los cambios a las políticas pasan por él. Ver cosas-a-cargo-del-tl.

Reglas que NUNCA se rompen

Ordenadas por fase de montaje e importancia: primero el entorno, luego el gestor de paquetes y versiones, después las convenciones de código, el flujo Git, y por último contenedores y despliegue.

Entorno y herramientas

1. Todas las herramientas se instalan vía Homebrew. Sin curl | bash, sin npm install -g, sin descargas manuales de .dmg/.pkg. Si una herramienta genuinamente no está en Homebrew, requiere autorización explícita del TL antes de instalarla por otro método.
2. Herramientas de IA — lista blanca. Solo se autorizan Claude Code (claude-code) y Cowork (claude), siempre bajo la cuenta corporativa de Wiedii (nunca cuentas personales/individuales). Actualizado 2026-07-15: Codex, Antigravity CLI y el IDE Kiro quedan desautorizados con efecto inmediato — antes formaban parte de la lista blanca. Cualquier herramienta de IA que no aparezca en la lista no está autorizada; incorporar una nueva requiere autorización explícita del TL, que la agrega a la lista. Al remediar una tool fuera del whitelist ya presente en un repo (incluidas las recién desautorizadas), se erradica del disco — no basta des-trackearla (git rm --cached la deja usable en local e invisible a fd/rg, que respetan .gitignore); la entrada en .gitignore queda solo como barrera anti-recommit, y borrar archivos del repo se confirma primero con quien lo mantiene (ver [[cross-platform#Al actualizar .gitignore — refrescar el índice de git]]). Los archivos de instrucciones de las tools autorizadas (AGENTS.md, CLAUDE.md) se conservan y versionan.
3. Preferir herramientas Rust sobre nativas del sistema. Cuando existe una alternativa Rust instalada (bat, eza, fd, rg, sd, gping, tldr), usarla en lugar del equivalente Unix nativo (cat, ls, find, grep, sed, ping, man). Los aliases de .zshrc implementan esta preferencia automáticamente. Ver herramientas-rust.
4. Todos los repositorios viven en ~/Docker/. Nunca en ~/Documents/, ~/Desktop/ ni ninguna carpeta sincronizada por iCloud. iCloud puede corromper repositorios git: genera conflictos de merge en archivos de índice, bloquea .git/index, y puede modificar silenciosamente archivos de configuración. ~/Docker/ queda fuera del scope de iCloud.

Gestor de paquetes y versiones

5. Bun es el package manager. Nunca sugerir npm, yarn ni pnpm como gestores de paquetes. El runtime de ejecución es Node.js en la mayoría de proyectos — Bun como runtime es válido en proyectos donde la compatibilidad de librerías lo permite, pero Node.js es el default. Ver stack-tecnologico.
6. Binarios locales vía bun <binary>. Si el paquete está en node_modules, ejecutar como bun eslint, bun prettier, bun vitest, etc. — nunca npx, nunca bunx para paquetes instalados.
7. Versiones siempre pinneadas. Ninguna herramienta, dependencia ni imagen Docker puede usar "latest" ni rangos abiertos (^, ~, *). Todas las versiones deben ser exactas (1.2.3, no ^1.2.3 ni latest). Esto aplica a package.json, mise.toml, Dockerfile, configuraciones de CI/CD y cualquier otra referencia a herramientas o dependencias. Las dependencias se mantienen actualizadas automáticamente vía Renovate.

Convenciones de código y archivos

8. Todo el código se escribe en inglés. Nombres de variables, funciones, clases, interfaces, tipos, constantes, archivos fuente, comentarios en código, mensajes de error, commit messages — siempre en inglés, sin excepción.
9. La documentación de los proyectos va en inglés y español. README.md, CHANGELOG.md, documentación de API, wikis y guías técnicas deben tener versión en ambos idiomas. CLAUDE.md/AGENTS.md es excepción — siempre en inglés (instrucciones para agentes de IA).
   • Legibilidad para la audiencia (principio general). La documentación se escribe para quien la lee, no para quien la genera. En prosa (cualquier idioma), evitar caracteres tipográficos poco reconocidos por la audiencia objetivo. El caso concreto detectado y prohibido es el signo de sección §: escribir "sección N" / "section N" en prosa; reservar § solo para citas o notas al pie (uso legal/académico), no para referenciar secciones en texto corrido — en Colombia en particular se lee como ruido. Este principio se extiende a otros símbolos igualmente opacos (¶, †, ‡, etc.). La auditoría marca la presencia de § en documentación como primer detector (ver repo-setup → /audit-project / /review-pr).
10. SEMVER sin prefijo. Las versiones son 1.2.0, 1.2.1, 2.0.0 — NUNCA v1.2.0.
11. Siempre .yaml no .yml para todos los archivos de config YAML (lefthook.yaml, .gitlab-ci.yaml, compose.yaml).

Commits y flujo Git

12. Todos los commits usan wietoo commit. El asistente wietoo es obligatorio para commits interactivos. Excepción: el primer commit de cualquier repositorio es siempre git commit -m "chore: initial commit" — sin wizard, sin scope, sin body. Ver wietoo-cli.
13. Todo commit referencia su tarea de Squadlinx. El footer del commit debe incluir closed #<número> donde <número> es el ID de la tarea en Squadlinx. Exenciones: chore: initial commit, commits de Renovate y commits de release. Ver commits.
14. Push directo a main/develop: solo mantenedores. Los mantenedores del proyecto (rol Maintainer en GitLab) pueden hacer push directo a main y develop. El resto del equipo lo tiene prohibido y debe integrar cambios siempre vía Merge Request. Ver branch-protection.
15. No auto-merge. Un desarrollador/agente NO hace merge de su propio MR.
16. No squash merge. Todos los merges son --no-ff.
17. merge.ff=false globalmente. Cada merge crea un commit de merge explícito.
18. Rebase antes del merge. Antes de que el MR se fusione, la rama feature se rebasa sobre develop.

Contenedores y despliegue

19. Nunca instalar dependencias en runtime de contenedores. Todo npm install, bun install, pip install, composer install, apt-get install o descarga de binarios debe ocurrir durante el docker build — nunca en CMD, ENTRYPOINT ni scripts de arranque. Un contenedor solo ejecuta su artefacto; no instala. Incumplir esta regla ha causado incidentes en producción. La única excepción requiere aprobación explícita del Tech Lead y nunca aplica a contenedores de producción. Ver docker.
20. App non-root y puerto no privilegiado. Todo servicio corre como non-root con capabilities dropeadas y escucha en un puerto no privilegiado (≥1024; convención 8080); la exposición pública en 80/443 la maneja el borde (ingress/reverse-proxy), nunca el proceso. La medida de seguridad real es non-root + drop caps, no el número de puerto. Ver docker.
21. Toda API expone /health y /ready. /health (liveness) y /ready (readiness), sin autenticación y sin filtrar internos. Ver seguridad-api.
22. Build multi-arquitectura antes de sincronizar. Si el repo tiene Dockerfile, antes de hacer push/MR verificar que la imagen construye en linux/amd64 y linux/arm64 (en local trabajamos arm64; el CI construye amd64 por defecto). Ver docker.

Verificación de versiones en documentación

Toda nota del vault que incluya números de versión (imágenes Docker, herramientas de mise, dependencias de npm/Composer/pip) puede estar desactualizada. Los números reflejan el momento de la última edición del documento, no necesariamente el presente.

Antes de usar cualquier versión documentada, verificar que sigue siendo la estable más reciente:

# Imágenes Docker — consultar Docker Hub directamente
# https://hub.docker.com/_/node  |  https://hub.docker.com/_/golang  |  etc.

# npm / bun packages
bun info <paquete> version
# Ejemplo: bun info eslint version

# mise tools
mise ls-remote <herramienta> | tail -5
# Ejemplo: mise ls-remote bun | tail -5

# Brew formulas
brew info <formula>
# Ejemplo: brew info node

# Go — última versión estable
# https://go.dev/dl/

# PHP — últimas versiones
# https://www.php.net/releases/

# Python — últimas versiones
# https://www.python.org/downloads/

Cada nota con versiones debe incluir al inicio el callout estándar de verificación:

> ⚠️ **Verificar versiones antes de usar** — los números documentados pueden estar
> desactualizados. Ver [[politicas-core#Verificación de versiones en documentación]].

---

Versiones pinneadas (obligatorio)

Wiedii no permite versiones flotantes en ningún contexto. La razón es triple:

• Reproducibilidad: dos builds del mismo commit deben producir exactamente el mismo resultado.
• Seguridad de supply chain: "latest" puede instalar código malicioso publicado en el momento del build.
• Gestión centralizada: Renovate se encarga de proponer actualizaciones con PRs revisables — no hace falta delegar esa decisión a npm/Docker/mise en tiempo de build.

Qué se pinna y cómo

Contexto	Mal ❌	Bien ✅
package.json devDependencies	"prettier": "latest"	"prettier": "3.3.3"
package.json devDependencies	"eslint": "^9.0.0"	"eslint": "9.6.0"
mise.toml	bun = "latest"	bun = "1.3.14"
Dockerfile FROM	FROM node:latest	FROM node:24.1.0@sha256:abc...
Dockerfile FROM	FROM renovate/renovate	FROM renovate/renovate:43.222.1@sha256:04931b21787bb211161261a27f12069c342705ef4e03481c6d8189675e76a027
GitLab CI image	image: alpine	image: alpine:3.20.2

¿Cómo saber qué versión usar?

# npm — versión estable más reciente
bun info prettier version    # → 3.3.3
bun info @commitlint/cli version

# mise — versión disponible
mise ls-remote bun | tail -1

# Docker — imagen con digest
docker pull renovate/renovate:43.222.1@sha256:04931b21787bb211161261a27f12069c342705ef4e03481c6d8189675e76a027
docker inspect renovate/renovate:43.222.1@sha256:04931b21787bb211161261a27f12069c342705ef4e03481c6d8189675e76a027 --format '{{index .RepoDigests 0}}'

Renovate mantiene las versiones al día

Una vez que una versión está pinneada, Renovate (configurado via renovate-runner) abre automáticamente MRs con actualizaciones. No es necesario (ni correcto) actualizar versiones manualmente de forma ad-hoc.

Verificación pre-trabajo (OBLIGATORIA antes de cada tarea)

Antes de escribir cualquier código en un repo, verificar TODO lo siguiente. Si algo falta, configurarlo primero.

Git Global Config

# Comportamiento de merge y rebase
git config --global merge.ff false
git config --global pull.rebase false

# Limpieza de referencias remotas — sin esto, `git fetch`/`git pull` NUNCA
# borran las referencias remote-tracking de ramas ya eliminadas en GitLab (el
# auto-delete al mergear un MR sí funciona; lo que queda desactualizado es la
# copia local). Sin `fetch.prune`, `git branch -a` puede mostrar ramas
# "fantasma" indefinidamente — solo `git fetch --prune` las limpia.
git config --global fetch.prune true

# Normalización de archivos
git config --global core.autocrlf false
git config --global core.eol lf
git config --global core.ignorecase false

# Editor y UI
git config --global core.editor nano
git config --global color.ui auto

# Rama por defecto
git config --global init.defaultbranch main

# Firma GPG — estándar Wiedii
git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global gpg.program /opt/homebrew/bin/gpg
# user.signingkey se configura individualmente (ver [[configuracion-gpg]])

Verificaciones rápidas:

git config --global merge.ff        # → false
git config --global fetch.prune     # → true
git config --global commit.gpgsign  # → true
git config --global gpg.program     # → /opt/homebrew/bin/gpg

Para generar tu clave GPG, registrarla en GitLab y verificar que los commits aparecen como "Verified", ver configuracion-gpg.

Archivos requeridos en cada repositorio

Todo repo DEBE tener TODOS estos archivos:

Archivo	Propósito
mise.toml	Versiones de herramientas (bun, lefthook, taplo, etc.)
lefthook.yaml	Git hooks (pre-commit, commit-msg, post-merge, post-checkout)
.gitignore	Apropiado para el stack + globals de SO
.gitattributes	Normalización de line endings (LF para fuente, marcadores binarios)
.editorconfig	Configuración de editor (2 espacios, UTF-8, LF)
wietoo.toml (opcional)	Configuración de scopes del asistente de commits. Solo necesario si el proyecto define scopes propios. Se genera con wietoo init. Ver wietoo-cli
renovate.json	Habilita el runner de Renovate para este repo (sin este archivo el runner lo ignora)
README.md	Descripción del proyecto, instalación y uso. En inglés y español (regla #9)
CONTRIBUTING.md	Contrato de contribución del proyecto — setup, ramas, commits, MR, Definition of Done

Si falta algún archivo → crearlo siguiendo los templates de las políticas referenciadas abajo antes de hacer cualquier otro trabajo.

Instalación de herramientas

mise trust && mise run setup   # clon nuevo: `mise trust` ANTES — mise no corre tareas de un config no confiable
# `mise run setup` ejecuta:
#   mise install --yes   → instala herramientas + lefthook install (si no es CI)
#   mise lock            → crea/actualiza mise.lock
#   bun install          → solo si el proyecto tiene package.json

lefthook install se ejecuta via [hooks].postinstall en mise.toml, no via package.json. Funciona para cualquier stack (Node, Python, Go, etc.) y se salta automáticamente en CI. (En CI mise asume confianza, así que mise run setup corre sin el mise trust previo.)

Referencia de políticas específicas

Cargar solo cuando la tarea lo requiera específicamente:

Tema	Política
Evaluar y agregar dependencias externas	seleccion-dependencias
Crear/fusionar ramas, abrir MRs	git-flow
Escribir mensajes de commit, usar wietoo	commits
Configurar mise.toml, invocar herramientas	mise-tooling
Configurar o depurar hooks de lefthook	lefthook
Crear .gitignore / .gitattributes / .editorconfig	cross-platform
Configurar ESLint, ruff, golangci-lint, Prettier	linters
Agregar escáneres Trivy, Snyk, SonarQube	security-scanners
Seguridad de APIs (OWASP API Top 10, /health, /ready)	seguridad-api
Reglas de protección de ramas en GitLab	branch-protection
Pipeline GitLab CI con caching	ci-caching
Actualización automática de dependencias (Renovate)	renovate-runner
Crear un repo nuevo o template de CLAUDE.md	repo-setup
Números de versión y tags de git	versioning
Workspace Nx (monorepo)	nx-monorepo