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¶

Respalda tu directorio .raise/ (opcional pero recomendado):
```
cp -r .raise/ .raise.backup-2.4/
```
Verifica tu versión actual:
```
rai --version
```
Instala el binario global (recomendado para 3.1+):
```
curl -fsSL https://github.com/humansys/raise/releases/latest/download/install.sh | bash
```
Esto instala el binario 3.1.x más reciente. Consulta las notas de release 3.1.0 y la guía de migración venv a binario para más detalles.

Legacy: para instalar una versión estable 3.0.x específica vía el método per-project venv:

curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --version 3.0.0

Upgrade guiado (3.1+): el pipeline `upgrade`¶

Desde 3.1 existe un camino guiado que automatiza la migración estructural y construye el grafo de conocimiento de tu proyecto a partir de los docs y el código que ya tienes — usando la inferencia del agente que ya maneja tu CLI, sin API key externa. Los pasos manuales de abajo siguen siendo la referencia; el pipeline los orquesta con gates human-in-the-loop.

Instala y haz scaffold:

rai init --detect --force   # scaffold v3.x e instala los skills del upgrade

Corre el pipeline desde tu sesión de agente (Claude Code con el MCP rai-workspace):

"corre el pipeline de upgrade"

Cinco fases, cada una pausa en un gate de revisión:

Fase	Qué hace
`structural`	Scaffold de manifest/config v3.x, migra datos YAML/JSONL a SQLite (originales como `.migrated`)
`discover`	Escanea el código al grafo de conocimiento
`curate-corpus`	Clasifica tus documentos por relevancia de governance — logs, transcripciones y pitches se excluyen; tú confirmas el corpus
`cartridge-governance`	Construye un cartridge de governance consultable desde los docs curados, con la inferencia del agente local (sin API key)
`verify`	Reconstruye el grafo y lista los cartridges instalados

Consulta el conocimiento que acabas de construir:

rai cartridge query <proyecto>-governance "tu pregunta"

Requisitos

El pipeline se orquesta desde una sesión de agente (Claude Code + el MCP rai-workspace). Los pasos de migración de datos por sí solos están disponibles como CLI plano (rai init --detect --force y luego rai db import-legacy). También existe un comando rai upgrade, pero solo refresca skills y archivos del framework — no es el pipeline de migración.

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? Parcialmente — algunos datos migran lazily en el primer uso, pero no todos. Para asegurar que todo se importa (sesiones, señales, journals, patterns, pipeline runs), ejecuta el import explícitamente:

rai db import-legacy

Tus archivos JSONL antiguos se renombran con extensión *.migrated (no se eliminan). El comando es idempotente — seguro de ejecutar múltiples veces.

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¶

Reportar problemas: github.com/humansys/raise
Guía de Instalación
Comenzar

Migrando de 2.x a 3.0¶

Antes de Empezar¶

Upgrade guiado (3.1+): el pipeline upgrade¶

Cambios Incompatibles¶

BC1 — confluence.yaml renombrado a docs.yaml¶

BC2 — /rai-story-run eliminado¶

BC3 — SQLite reemplaza almacenamiento JSONL/JSON¶

BC4 — Base de datos SQLite global¶

BC5 — Ubicación de datos de sesión¶

BC6 — Gate de integridad schema.sum¶

BC7 — Usa rai upgrade para proyectos existentes¶

BC8 — Flujo dead-letter para backlog pending-ops¶

Verificación Post-Migración¶

Obtener Ayuda¶

Upgrade guiado (3.1+): el pipeline `upgrade`¶

BC1 — `confluence.yaml` renombrado a `docs.yaml`¶

BC2 — `/rai-story-run` eliminado¶

BC6 — Gate de integridad `schema.sum`¶

BC7 — Usa `rai upgrade` para proyectos existentes¶