Notas de Release RaiSE 3.1.0¶

Que cambio y que debes hacer.

Cada seccion sigue el formato: Cambio / Por que / Accion requerida.

Actualizas desde cualquier version anterior? La guia de actualizacion te enruta por metodo de instalacion y recorre el camino paso a paso -- incluido el defecto de rai self-update que afecta a todos los release candidates hasta rc5. Si vienes de un venv per-project o de pip, te deriva a la guia de migracion venv a binario.

1. Cambio en el metodo de instalacion¶

Cambio: El binario global es ahora el metodo de instalacion recomendado y soportado. Todos los metodos de venv per-project, pip, pipx y el antiguo install.sh son legacy.

Por que: Los venvs per-project crean 5 GB de entornos Python duplicados por checkout, producen residuos que confunden al escaner del grafo y la migracion de base de datos, y requieren activacion antes de cada comando. El binario global es una unica instalacion: sin Python, sin venv, sin activacion.

Accion requerida: Sigue la Guia de Migracion para desinstalar el metodo legacy e instalar el binario global. Ejecuta rai clean --dry-run en cada checkout de proyecto despues.

2. Nuevo: `rai clean`¶

Cambio: Un nuevo comando rai clean detecta y elimina residuos de instalaciones legacy. rai doctor gano una categoria de check legacy (rai doctor -c legacy). Al abrir sesion, se muestra un aviso unico si se detectan residuos legacy; se silencia una vez que el usuario ejecuta rai clean --dry-run.

Por que: Los usuarios que actualizan desde instalaciones per-project acumulan venvs huerfanos, bases de datos locales, entradas de config obsoletas y referencias de dependencias. Sin una herramienta para encontrarlos y limpiarlos, la migracion toma horas de inspeccion manual (un reporte de campo midio veinte horas a lo largo de dos dias).

Accion requerida: Ejecuta rai clean --dry-run una vez por checkout de proyecto para revisar los residuos. Luego rai clean para procesar los residuos gestionados, y rai clean --fix-config para reparar archivos de configuracion. Usa rai clean --force solo si tambien quieres procesar los residuos advisory (archivos que tu controlas, como pyproject.toml).

3. El grafo tiene alcance por checkout (schema v68)¶

Cambio: El indice del knowledge graph ahora tiene alcance por checkout. La particion compartida anterior (last-writer-wins entre checkouts del mismo repo) se descarta. El grafo debe reconstruirse por checkout.

Por que: Los proyectos multi-checkout compartian anteriormente una unica particion de grafo. El checkout que ejecutara rai graph build ultimo sobreescribia los datos de los demas. El layout con alcance por checkout atribuye los nodos correctamente y elimina la perdida silenciosa de datos.

Accion requerida:

Ejecuta rai clean --dry-run primero -- esto marca el repo cartridge obsoleto como un residuo advisory (repo-cartridge-self-ingest). rai clean no puede eliminarlo automaticamente; debes mover el cartridge obsoleto aparte manualmente:
```
mv .raise/cartridges/repo/instances /tmp/repo-instances-aside
```
Luego reconstruye por checkout:
```
cd ~/projects/my-app
rai graph build
```
Repite para cada checkout y worktree.

Si el graph build falla con RepoCartridgeCollapseError, mueve el cartridge obsoleto aparte primero:

mv .raise/cartridges/repo/instances /tmp/repo-instances-bak
rai graph build

4. La memoria ahora tiene niveles¶

Cambio: La memoria ahora esta organizada en dos niveles. Nivel-1 (MEMORY.md index) mantiene notas de alcance de mision, recientes y criticas. Nivel-2 almacena notas demovidas (notas project con mas de 30 dias, notas feedback no criticas y notas reference) para consulta via el hint oracle y queries al grafo.

Por que: A medida que los proyectos acumulan notas de memoria, la ventana de contexto se llena con entradas obsoletas o de baja relevancia. Los niveles mantienen el contexto de trabajo enfocado mientras preservan el conocimiento historico para consulta bajo demanda.

Accion requerida: La consulta de Nivel-2 requiere ejecutar rai memory ingest --apply manualmente. Esto no es automatico hoy. Sin este paso, las notas demovidas salen del Nivel-1 pero no son consultables via Nivel-2 -- la democion es efectivamente de un solo sentido hasta que ejecutes el ingest. Ejecuta:

rai memory ingest --apply

Esto crea el memory cartridge en ~/.rai/cartridges/memory/ e indexa las notas demovidas para consulta basada en el grafo.

5. Las skills se exportan a otros harnesses¶

Cambio: Las skills ahora se exportan como archivos markdown portables que funcionan en multiples herramientas de programacion con IA (Claude Code, Cursor, Aider, Codex, etc.).

Por que: Las skills estaban previamente acopladas al mecanismo de comandos personalizados de Claude Code. El formato portable permite que los mismos flujos de gobernanza se ejecuten en cualquier herramienta que soporte instrucciones personalizadas.

Accion requerida: Re-sincroniza las skills en cada proyecto:

rai init --detect     # o rai upgrade

6. Migracion de DB de 45 a 79¶

Cambio: El schema de la base de datos migra de la version 45 a la 79. La migracion es solo hacia adelante y ocurre automaticamente la primera vez que cualquier comando rai abre la base de datos. Esto incluye comandos de solo lectura como rai db status y rai db check -- leer la version del schema es lo que dispara la migracion.

Por que: El nuevo schema soporta grafos con alcance por checkout, memoria con niveles, tracking de senales y otras funcionalidades de 3.1.

Accion requerida: Haz backup de tu base de datos antes de ejecutar cualquier comando rai con el nuevo binario. La migracion es irreversible.

cp ~/.rai/raise.db ~/.rai/raise.db.backup-pre-3.1

La migracion en si es rapida (medida en 1.7 segundos en una base de datos de produccion con 45 tablas) y exacta -- los ensayos coincidieron con la ejecucion en produccion fila por fila en las pruebas de campo.

Nota: rai db import-legacy (anteriormente rai db migrate) importa datos personales legacy en JSONL/YAML a SQLite (una importacion de datos unica, no la migracion de schema). La migracion de schema ocurre en create_all() al abrir cualquier base de datos.

7. Problemas conocidos¶

Los siguientes items son conocidos y estan documentados en la Guia de Solucion de Problemas:

PATH shadowing: Despues de instalar el binario global, los puntos de entrada legacy (.venv/bin/rai, shims de pipx) pueden ganar en la resolucion del PATH. Consulta la entrada de troubleshooting #1.
.mcp.json trackeado en git: Los proyectos que hicieron commit de .mcp.json en control de versiones bloquean el reprovisionamiento automatico. rai clean --fix-config lo maneja, pero el diff debe revisarse y committearse manualmente. Consulta la entrada de troubleshooting #2.
RepoCartridgeCollapseError en el primer graph build: El repo cartridge obsoleto de pre-3.1 reingesta sus propios nodos. rai clean lo marca como advisory; el workaround es mover instances/ aparte antes de reconstruir. Consulta la entrada de troubleshooting #4.
La consulta de memoria Nivel-2 requiere ingest manual: rai memory ingest --apply debe ejecutarse manualmente. El ingest automatico durante el tiering esta planeado pero aun no esta conectado.
La unicidad de patrones base es global: pattern_id es una primary key global. El primer proyecto en instalar patrones base los posee; otros proyectos ven cero patrones base. Esta es una restriccion de diseno conocida, no una regresion.

Consulta tambien la pagina completa de Problemas Conocidos.

Bugfixes incluidos en la version final (no en rc3)¶

RAISE-16215: Los venvs renombrados (.venv.old, .venv-backup) ahora son excluidos del escaner de codigo via _is_venv_like. En rc3, solo se excluian nombres exactos, lo que causaba que venvs renombrados produjeran grafos masivos de basura.

8. Cambios de comandos que rompen scripts¶

Cambio: cuatro superficies de comando cambiaron de forma que rompen automatizacion que funcionaba en 3.0 o en un release candidate.

Cambio	Que hacer
`rai init` es solo-plan — imprime lo que escribiria y sale	Agrega `--apply` donde corra desatendido. `--dry-run` queda como alias no-op deprecado. `rai upgrade` no esta afectado: sigue escribiendo por defecto.
`rai scm` perdio cinco comandos proxy (`repos`, `branches`, `disconnect`, `create-pr`, `get-pr`)	`create-pr` → `rai scm create-mr`; `get-pr` → el CLI de tu proveedor; los otros tres no tienen reemplazo. El grupo ahora expone `resolve-conflicts`, `create-mr` y `merge-mr`.
`rai db migrate` se renombro a `rai db import-legacy`	Renombra la llamada. El nombre viejo sigue funcionando pero esta deprecado.
`rai clean` escanea todos los proyectos registrados por defecto	Agrega `--path .` para el comportamiento anterior de solo-directorio-actual. Cuando stdin no es un tty, `rai clean` ya usa dry-run por defecto.

Por que: rai init se endurecio para adopcion en repositorios existentes, no greenfield, donde una escritura desatendida es destructiva — un unico gate explicito de escritura reemplazo la mezcla de escrituras implicitas y --dry-run. Los cinco comandos de rai scm hacian proxy a un adaptador del lado del servidor que fue eliminado; el protocolo local ScmAdapter lo reemplaza y funciona contra GitHub y GitLab sin round-trip al servidor. El nombre viejo db migrate sugeria erroneamente que corria la migracion de schema.

Accion requerida: audita scripts de shell, jobs de CI, tooling de aprovisionamiento y Makefiles buscando estos cuatro comandos. Si descubrias adaptadores SCM via el grupo de entry points rai.adapters.scm, ese grupo fue eliminado, no vaciado — carga el protocolo ScmAdapter desde raise_cli.scm con from_manifest().

Actualizando? La guia de actualizacion cubre la mecanica; esta seccion cubre que cambiar en tu propia automatizacion.

9. Otros cambios de comportamiento¶

rai a secas lanza el cockpit TUI de Textual. Correr rai sin subcomando inicia el nuevo cockpit de Textual en lugar del anterior de Rich. No se requiere accion salvo que dependas de la interfaz anterior:

rai --legacy                  # por invocacion
export RAI_COCKPIT_LEGACY=1   # persistente

rai --version reporta drift de estado git. En checkouts editables o de git ahora tambien advierte cuando la version declarada esta adelante de su tag de release, o no corresponde a ninguno. Las instalaciones de binario congelado no estan afectadas.

Operadores de servidor: migraciones Alembic aditivas. Los equipos que corren raise-server reciben varias migraciones aditivas. Corren automaticamente al reiniciar el servidor (alembic upgrade head en dev, el job de migrate en produccion). Toma un snapshot antes si tu tabla pipeline_runs es grande. Los usuarios solo-CLI no estan afectados.

10. Nuevo en 3.1.0¶

No tienes que adoptar nada de esto:

rai self-upgrade — la capa de paquete y la de proyecto en un comando, en el orden que importa. Ver la guia de actualizacion.
rai clean — encuentra y elimina residuos de instalaciones legacy; rai doctor -c legacy es el diagnostico correspondiente (ver seccion 2).
rai ddd — modelado tactico de dominio: discover, refine, validate y report.
rai graph gano fields, contexts, classify, assign-bcs y prune. Nota que rai graph prune es otra cosa que el flag --prune de rai graph build: elimina filas del grafo de worktrees cuyo checkout ya no existe en disco.
rai telemetry ingest-tool-cost y rai telemetry backfill-story-costs.
Dos adapters nuevos. local se suma al grupo rai.adapters.pm junto a filesystem y jira; platform se suma a rai.docs.targets junto a filesystem, confluence y gdrive. Los adapters filesystem de ambos grupos quedan sin cambios — el unico grupo de entry points eliminado en esta release es rai.adapters.scm (ver seccion 8).
UI de admin y cockpit TUI renovados, publicacion de artefactos HTML via rai docs publish, y orquestacion de agentes en contenedores.