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.

Reglas que NUNCA se rompen

Bun es el runtime. Nunca sugerir npm, yarn ni pnpm.
Binarios locales vía bun <binary>. Si el paquete está en node_modules, ejecutar como bun eslint, bun prettier, bun czg, etc. — nunca npx, nunca bunx para paquetes instalados.
SEMVER sin prefijo. Las versiones son 1.2.0, 1.2.1, 2.0.0 — NUNCA v1.2.0.
No push directo a main ni a develop. Todos los cambios van por Merge Requests.
No auto-merge. Un desarrollador/agente NO hace merge de su propio MR.
No squash merge. Todos los merges son --no-ff.
merge.ff=false globalmente. Cada merge crea un commit de merge explícito.
Rebase antes del merge. Antes de que el MR se fusione, la rama feature se rebasa sobre develop.
Todos los commits usan bun commit o bun czg. El wizard czg 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.
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.
Siempre .yaml no .yml para todos los archivos de config YAML (lefthook.yaml, .gitlab-ci.yaml, docker-compose.yaml).
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.
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.
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.
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.
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).
Herramientas de IA — solo Claude. El único asistente de IA autorizado para desarrollo en Wiedii es Claude Code (CLI: claude-code) y Cowork (claude). Cursor y OpenCode no están autorizados. Cualquier otra herramienta IA requiere autorización explícita del TL.
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.

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	`"czg": "latest"`	`"czg": "1.13.1"`
`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.209.1@sha256:1ac704319b8aa45a412c35d287b7ca1afeabf3d25f042eb22e4c267faf86decc@sha256:3de1...`
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 czg version         # → 1.13.1
bun info @commitlint/cli version

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

# Docker — imagen con digest
docker pull renovate/renovate:43.209.1@sha256:1ac704319b8aa45a412c35d287b7ca1afeabf3d25f042eb22e4c267faf86decc
docker inspect renovate/renovate:43.209.1@sha256:1ac704319b8aa45a412c35d287b7ca1afeabf3d25f042eb22e4c267faf86decc --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

# 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](../entorno-local/configuracion-gpg.md))

Verificaciones rápidas:

git config --global merge.ff        # → false
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)
`commitlint.config.js`	Validación de mensajes de commit + configuración del wizard czg (ESM)
`renovate.json`	Habilita el runner de Renovate para este repo (sin este archivo el runner lo ignora)
`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 run setup
# Equivale a:
#   mise trust
#   mise install --yes   → instala herramientas + lefthook install (si no es CI)
#   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.

Referencia de políticas específicas

Cargar solo cuando la tarea lo requiera específicamente:

Tema	Política
Crear/fusionar ramas, abrir MRs	git-flow
Escribir mensajes de commit, configurar czg	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
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

Reglas que NUNCA se rompen​

Versiones pinneadas (obligatorio)​

Qué se pinna y cómo​

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

Renovate mantiene las versiones al día​

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

Git Global Config​

Archivos requeridos en cada repositorio​

Instalación de herramientas​

Referencia de políticas específicas​