Saltar a contenido

Migrando de 2.x a 3.0

RaiSE 3.0 incluye varios cambios incompatibles. Esta guía explica cada uno con los pasos exactos para actualizar tu proyecto.

¿A quién aplica? A cualquiera que actualice un proyecto existente de RaiSE 2.4.x a 3.0.0.

Antes de Empezar

  1. Respalda tu directorio .raise/ (opcional pero recomendado): 

    cp -r .raise/ .raise.backup-2.4/

  2. Verifica tu versión actual: 

    rai --version

  3. Instala 3.0: 

    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --version 3.0.0
    O para la última pre-release: 
    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --pre

Cambios Incompatibles

BC1 — confluence.yaml renombrado a docs.yaml

Qué cambió: El archivo de configuración del adaptador de documentación se renombró de .raise/confluence.yaml a .raise/docs.yaml. El esquema también cambió: instances: ahora es targets:, default_instance: ahora es default_target:, y cada target requiere un campo type:.

¿Se migra automáticamente? Sí — la primera vez que ejecutas rai docs write, RaiSE crea automáticamente docs.yaml a partir de tu confluence.yaml. Sin embargo, el archivo antiguo no se elimina, por lo que debes limpiarlo manualmente.

Solución:

# Después de ejecutar cualquier comando rai docs una vez (la auto-migración crea docs.yaml):
git add .raise/docs.yaml
git rm .raise/confluence.yaml
git commit -m "chore: migrate confluence.yaml → docs.yaml (RaiSE 3.0)"

Antes (.raise/confluence.yaml): 

default_instance: my-space
instances:
  my-space:
    url: https://company.atlassian.net/wiki
    space_key: ENG
    instance_name: my-space
    routing:
      adr:
        parent_title: Architecture
        labels:
          - adr

Después (.raise/docs.yaml): 

default_target: my-space
targets:
  my-space:
    type: confluence
    url: https://company.atlassian.net/wiki
    space_key: ENG
    instance_name: my-space
    routing:
      adr:
        parent_title: Architecture
        labels:
          - adr

Verificación: 

rai doctor

BC2 — /rai-story-run eliminado

Qué cambió: El skill /rai-story-run fue eliminado. Los pipelines de stories ahora se inician a través de la herramienta MCP pipeline_start o el CLI rai pipeline.

Solución: Reemplaza cualquier invocación de /rai-story-run con una de las siguientes:

Opción A — Herramienta MCP (recomendada, desde Claude Code):

Pídele a tu asistente de IA que inicie el pipeline: 

Inicia el pipeline de story para RAISE-1234
El asistente llama a pipeline_start automáticamente y te guía a través de cada fase.

Opción B — Dentro de Claude Code con skill: 

/rai-story-start RAISE-1234
Luego sigue las fases del pipeline manualmente con /rai-story-design, /rai-story-plan, etc.

Nota: No existe un comando CLI rai pipeline — los pipelines corren exclusivamente a través de la herramienta MCP (pipeline_start, pipeline_advance, pipeline_status).

Ver también: Pipeline Quickstart

BC3 — SQLite reemplaza almacenamiento JSONL/JSON

Qué cambió: Todos los datos locales de RaiSE (sesiones, señales, patrones, artefactos, ejecuciones de pipeline) migraron de archivos planos (.raise/rai/personal/*.jsonl, *.json, *.yaml) a una base de datos SQLite en .raise/raise.db.

¿Se migra automáticamente? Sí — en el primer comando rai después de actualizar, la migración corre automáticamente. Tus archivos JSONL antiguos se renombran con extensión *.migrated (no se eliminan).

Migración manual (si la auto-migración no corrió): 

rai db migrate

Verificación: 

rai db status
# Debe mostrar: schema_version=24, tablas con conteos de filas

Rollback: Tus archivos *.migrated se conservan. Para restaurarlos, renómbralos de vuelta (contacta soporte para el script de restauración).

BC4 — Base de datos SQLite global

Qué cambió: RaiSE 3.0 introduce una sola base de datos global en ~/.rai/raise.db que contiene datos entre proyectos. Todas las tablas de alcance de proyecto ahora tienen una columna project_id.

Impacto para la mayoría de usuarios: Ninguno — el CLI rai maneja el filtrado por project_id automáticamente.

Impacto si consultas SQLite directamente (usuarios avanzados): 

-- Antes (2.x): la consulta funcionaba sin filtrar
SELECT * FROM sessions;

-- Después (3.0): debes filtrar por project_id
SELECT * FROM sessions WHERE project_id = '<tu-project-hash>';

Para encontrar tu project ID: 

rai db status
# Muestra: project_id: <hash>

BC5 — Ubicación de datos de sesión

Qué cambió: El estado de sesión migró de una mezcla de archivos globales ~/.rai/ y JSONL por proyecto a .raise/rai/personal/ (por proyecto) y ~/.rai/raise.db (índice global).

Impacto: Si tenías scripts leyendo los campos de sesión activa en ~/.rai/developer.yaml, esos campos ya no se actualizan. Los datos de sesión ahora están en SQLite.

Solución: 

# Consulta la sesión activa vía CLI en lugar de leer YAML
rai session list
rai session info

Verificación: 

rai session list
# Debe mostrar tus sesiones recientes desde SQLite

BC6 — Gate de integridad schema.sum

Qué cambió: RaiSE 3.0 requiere un archivo .raise/schema.sum que rastrea los hashes de migración. El gate gate-schema-sum (activado al cerrar una story) falla si este archivo falta o está desactualizado.

Impacto: Si omites esto, rai-story-close fallará en la verificación del gate.

Solución: 

# Genera schema.sum para tu proyecto
rai schema sum update

# Confírmalo en git
git add .raise/schema.sum
git commit -m "chore: add schema.sum integrity file (RaiSE 3.0)"

Verificación: 

rai schema sum check
# ✓ schema.sum is up to date (V24)

BC7 — Usa rai upgrade para proyectos existentes

Qué cambió: rai init ahora es solo para configuración inicial. Ejecutarlo en un proyecto ya inicializado mostrará un error y sugerirá usar rai upgrade en su lugar.

Antes (2.x): Re-ejecutar rai init actualizaba skills y archivos del framework.

Después (3.0): Usa rai upgrade para actualizar un proyecto existente: 

# Actualiza skills, archivos del framework y AGENTS.md
rai upgrade

# Previsualiza qué cambiaría
rai upgrade --dry-run

# También re-detecta agentes de IA
rai upgrade --detect

BC8 — Flujo dead-letter para backlog pending-ops

Qué cambió: Las operaciones fallidas de sincronización de backlog (por ejemplo, llamadas a Jira que fallaron durante trabajo offline) ahora van a una cola dead-letter en lugar de desaparecer silenciosamente.

Impacto: Si tienes ops de backlog no sincronizadas de 2.x que fallaron, aparecen en la cola dead-letter después de la migración.

Revisar ops dead-letter: 

rai backlog pending-ops list --dead

Drenar (reintentar o purgar): 

# Purgar una op fallida específica
rai backlog pending-ops purge --id <op-id>

# Purgar todas las ops (después de revisarlas)
rai backlog pending-ops purge --yes

Verificación Post-Migración

Después de completar todos los pasos aplicables:

# Diagnósticos completos
rai doctor

# Verificar estado de la base de datos
rai db status

# Verificar integridad del esquema
rai schema sum check

# Listar sesiones recientes (confirma que SQLite funciona)
rai session list

Todas las verificaciones deben pasar en verde. Si rai doctor reporta problemas, sigue las sugerencias de --fix:

rai doctor --fix

Obtener Ayuda