fn_registry/.claude/commands/version.md

name, description

name	description
version	Bumpear semver de un modulo, framework, paquete o app del registry. Edita <target>.md::version +

/version

Bumpea la version de un modulo, framework, paquete o app del registry siguiendo SemVer estricto y mantiene el ## Capability growth log sincronizado con <target>.md::version.

Disenado para usarse desde /fix-issue cuando el cambio afecte:

• modules/<X>/ (cualquier modulo C++) — edita module.md
• cpp/framework/ — edita modules/framework/module.md
• apps/<X>/ o projects/<P>/apps/<X>/ — edita app.md
• Otros paquetes versionados con <target>.md y campo version:

Inputs

/version <path> <major|minor|patch> "<reason>"

• <path>: directorio del target (ej. modules/data_table, cpp/framework, apps/chart_demo, projects/fn_monitoring/apps/registry_dashboard).
• <major|minor|patch>: tipo de bump SemVer.
• <reason>: 1-frase humana — lo que cambia. Se inserta en el log.

Resolucion del archivo target

Path empieza por	Archivo a editar
modules/	<path>/module.md
cpp/framework	modules/framework/module.md
apps/	<path>/app.md
projects/*/apps/	<path>/app.md
projects/*/analysis/	<path>/analysis.md

Si no encuentra archivo target -> ERROR.

Reglas SemVer

Modulos / framework

Bump	Cuando
major	Cambios breaking en API publica: firma de entry function, layout de State struct expuesto, eliminacion de members, cambio incompatible de comportamiento.
minor	Adiciones backwards-compatible: nuevo evento opt-in, nuevo renderer, nuevo helper, nuevo miembro.
patch	Bugfix sin cambio de API.

Refactor interno SIN cambio de API publica -> minor (no major).

Apps

Bump	Cuando
major	Breaking observable por usuarios: CLI args incompatibles, schema BBDD propia rompe lectores viejos, formato wire (HTTP/gRPC) incompatible, eliminacion de panel/feature que la gente usaba.
minor	Feature aditiva: nuevo panel, nuevo endpoint, nueva opcion CLI, nueva tab, mejora visible no rompedora.
patch	Bugfix sin cambio observable. Refactor interno. Mejoras de perf.

Bump de dependencia (modulo/funcion del registry) que mejora la app pero la app no cambia su API -> patch (la app no es responsable de la mejora; el modulo si).

Flujo

1. Validar input

• <target_file> existe -> si no, ERROR.
• Bump type en {major, minor, patch} -> si no, ERROR.
• Reason no vacia -> si no, ERROR.

2. Leer version actual

Parsear frontmatter. Buscar version: X.Y.Z. Si no existe:

• Para module.md -> ERROR "module.md sin campo version".
• Para app.md -> asumir 0.1.0 (baseline) e insertar el campo despues de domain:.

3. Calcular proxima version

1.4.0 + major = 2.0.0
1.4.0 + minor = 1.5.0
1.4.0 + patch = 1.4.1

Major bump -> minor y patch a 0. Minor bump -> patch a 0.

4. Editar <target_file>

Cambiar linea version: <old> por version: <new>.

5. Anadir entrada a ## Capability growth log

Insertar al inicio de la lista (lineas posteriores al header ## Capability growth log):

- v<new> (<fecha YYYY-MM-DD>) — <reason>

Si la seccion no existe -> crearla al final del archivo antes de ## Notes (o al final si no hay Notes).

6. Verificar drift de members (solo modulos, opcional)

Si la herramienta fn doctor modules existe (post 0107a) y el target es modulo:

• Compara members: actual vs ultima version registrada en registry.db::modules_history.
• Si hay diff en members y bump es patch -> WARNING.
• Si hay diff en API publica y bump no es major -> ERROR (require --force).

No aplica a apps (no tienen members:).

7. Stage en git

git add <target_file>. NO commit. El commit final lo hace el flujo padre.

8. Reportar

/version apps/chart_demo minor "anade tab radar chart"

apps/chart_demo/app.md
  version: 1.2.0 -> 1.3.0
  ## Capability growth log: + v1.3.0 (2026-05-18) — anade tab radar chart

Staged. NO committed.
Next: terminar el fix-issue y hacer commit con el resto de cambios.

Reglas criticas

• NUNCA commit. /version solo edita + stage. El commit lo hace el flujo padre (/fix-issue, /git-push).
• NUNCA saltar version. No 1.4.0 -> 1.4.2 directo.
• NUNCA bajar version. Si rollback, crea nueva version superior con comportamiento viejo restaurado.
• fecha = HOY (date +%Y-%m-%d).
• reason comprensible sin contexto del PR actual.

Referenciado desde

• /fix-issue — al detectar cambios en modules/, cpp/framework/, apps/<X>/ o projects/*/apps/<X>/, sugiere ejecutar /version antes del commit final.
• .claude/rules/cpp_apps.md — politica de bump.
• dev/issues/0107-modules-standardization.md — origen del flujo (modulos).

Ejemplos

# Bug fix en data_table (modulo)
/version modules/data_table patch "fix off-by-one en seleccion multi-row con shift+click"
# -> 1.4.0 -> 1.4.1

# Feature opt-in en framework
/version cpp/framework minor "anade cfg.auto_dockspace para overlay de paneles flotantes"
# -> 1.1.0 -> 1.2.0

# Feature en app C++
/version apps/chart_demo minor "anade tab radar chart con datos sinteticos"
# -> 1.2.0 -> 1.3.0

# Bug fix en app de proyecto
/version projects/fn_monitoring/apps/registry_dashboard patch "fix tooltip que mostraba duration_ms en segundos"
# -> 0.4.1 -> 0.4.2

# Breaking en app: cambia schema de su BBDD propia
/version apps/kanban major "cards.assignee_id pasa a ser TEXT[] (era TEXT); requiere migracion 008"
# -> 1.0.0 -> 2.0.0

Anti-patrones

Anti-patron	Por que es malo
Editar version: a mano sin ## Capability growth log	Drift entre version y log; nadie sabe que cambio.
Bumpear major en app por refactor interno	Confunde al usuario; refactor es patch.
Patch para feature visible	Usuario no se entera que esta disponible.
Reason "cambios varios" / "mejoras"	Inutil para auditar. Una frase concreta.
Bump de app sin tocar codigo de la app (solo dep)	Bump va al modulo, no a la app.