Saltar a contenido

Persistencia Local

RaiSE incluye adaptadores respaldados por sistema de archivos para gestión de backlog y publicación de documentación. Estos son los predeterminados cuando no hay servicios externos configurados (Jira, Confluence) — no requieren configuración.

Cuándo Usar Adaptadores de Sistema de Archivos

Escenario Backlog Docs
Comenzar — explorar RaiSE antes de conectar Jira/Confluence filesystem filesystem
Trabajo offline — sin acceso a red filesystem filesystem
Proyectos open-source — sin licencia Atlassian filesystem filesystem
Equipo con Atlassian — conectado a Jira y Confluence jira confluence o composite
Doble seguridad — backup local + publicación remota jira composite (ambos)

Backlog de Sistema de Archivos (FilesystemPMAdapter)

Almacenamiento

Cada issue es un archivo YAML en .raise/backlog/items/{KEY}.yaml:

.raise/backlog/items/
├── E1.yaml          # Epic
├── S1.1.yaml        # Story bajo E1
├── S1.2.yaml        # Story bajo E1
├── E2.yaml          # Otro epic
└── S2.1.yaml        # Story bajo E2

Esquema de Issue

key: E1
summary: "Implementar autenticación de usuario"
issue_type: Epic
status: in-progress
description: "Flujo OAuth2 + PKCE para clientes web y CLI"
labels:
  - security
  - v1.0
priority: high
assignee: [email protected]
parent: null
created: "2026-04-01T09:00:00+00:00"
updated: "2026-04-03T14:30:00+00:00"
comments:
  - id: E1-1
    body: "Decidido PKCE sobre flujo implícito"
    author: rai
    created: "2026-04-02T10:00:00+00:00"
links:
  - target: E2
    link_type: blocks

Generación de Keys

Las keys se generan automáticamente según el tipo de issue:

  • Epics: E1, E2, E3, ...
  • Stories: S{num_epic}.1, S{num_epic}.2, ... (requiere parent_key en metadatos)
  • Tasks: Igual que epics (E{N})

Uso del CLI

Todos los comandos rai backlog funcionan transparentemente con el adaptador de sistema de archivos:

# Crear un epic
rai backlog create "Implementar auth" -p LOCAL -t Epic

# Crear una story bajo él
rai backlog create "Flujo OAuth2" -p LOCAL -t Story --parent E1

# Buscar
rai backlog search "auth"
rai backlog search "status = in-progress"

# Transicionar
rai backlog transition E1 done

# Comentar
rai backlog comment E1 "Implementación OAuth2 completada"

# Obtener detalles
rai backlog get E1

Selección de Adaptador

Cuando solo hay un adaptador registrado, se selecciona automáticamente. Cuando hay múltiples adaptadores disponibles (filesystem + jira), especifica cuál usar:

rai backlog search "auth" -a filesystem    # Forzar filesystem
rai backlog search "auth" -a jira          # Forzar Jira

Target de Documentación de Sistema de Archivos (FilesystemDocsTarget)

Qué Hace

Escribe documentación en archivos markdown locales. Es la contrapartida de solo-escritura de Confluence — guarda archivos localmente pero no soporta búsqueda o recuperación (usa tu editor o grep para eso).

Uso

# Publicar desde convención de gobernanza (governance/roadmap.md)
rai docs publish roadmap --title "Roadmap Q2"

# Publicar desde cualquier archivo
rai docs publish adr --title "ADR-045" --file dev/decisions/adr-045.md

# Publicar desde stdin
echo "# Mi Doc" | rai docs publish notes --title "Notas de Sesión" --path docs/notes.md --stdin

Dónde Van los Archivos

El flag --path (o metadata["path"]) determina la ubicación de salida. Cuando se publica desde un archivo existente, la ruta toma como default la ubicación de ese archivo.

Validación de Frontmatter

El target de sistema de archivos valida el frontmatter YAML antes de escribir:

  • Campos requeridos: title, status
  • Docs a nivel epic: también requieren epic_id
  • Docs a nivel story: también requieren story_id y epic_id

Target Composite (Escritura Dual)

El CompositeDocTarget publica tanto en sistema de archivos como en Confluence en una sola llamada:

  1. Sistema de archivos primero (garantía de durabilidad — tu archivo siempre se guarda)
  2. Confluence segundo (retorna la URL remota)
  3. Si Confluence falla pero el sistema de archivos tiene éxito: retorna éxito con advertencia "sync pending"

Este es el comportamiento predeterminado cuando ambos targets están registrados. No se necesita configuración.

# Esto escribe localmente Y publica en Confluence
rai docs publish adr --title "ADR-045"

# Output:
# Published: adr → https://yoursite.atlassian.net/wiki/spaces/SPACE/pages/12345

Si Confluence no está disponible:

# Published: adr → docs/governance/adr-045.md
# Warning: Remote publish failed (sync pending) — retry with rai docs publish

Migrar a Jira/Confluence Después

El adaptador de sistema de archivos es un punto de partida, no un callejón sin salida. Cuando estés listo para conectar servicios externos:

  1. Sigue la guía Configurar Jira y Confluence
  2. Tu backlog de sistema de archivos se mantiene tal cual — no entra en conflicto con Jira
  3. Usa el flag -a para elegir qué adaptador usar por comando

No hay migración automática de YAML de sistema de archivos a issues de Jira. El enfoque recomendado es crear nuevos issues en Jira y referenciar las keys de sistema de archivos en descripciones o comentarios para trazabilidad.

Almacenamiento SQLite

RaiSE almacena todos los datos internos — sesiones, señales, patrones, ejecuciones de pipeline, artifacts y entradas de diario — en una única base de datos SQLite.

Ubicación de la Base de Datos

~/.rai/raise.db

Hay una base de datos global compartida entre todos tus proyectos RaiSE. Los datos por proyecto se aíslan internamente via una columna project_id — el CLI lo gestiona automáticamente, nunca necesitas filtrar por proyecto tú mismo.

Qué se Almacena

Tabla Contenido
sessions Registros de sesión (ID, inicio/fin, resumen)
signals Eventos de ciclo de vida de trabajo (inicio/completado de story, transiciones de fase)
patterns Patrones del knowledge graph acumulados entre sesiones
pipeline_runs Estado de ejecución de pipeline para todas las ejecuciones de story/epic/bugfix
artifacts Artifacts estructurados de diseño, plan y revisión
journal_entries Entradas de diario y diario de sesión
pending_sync Operaciones de backlog en cola para sincronización remota

Archivos de Modo WAL

Cuando RaiSE está en ejecución, puedes ver dos archivos extra junto a la base de datos:

~/.rai/raise.db
~/.rai/raise.db-wal    ← Write-Ahead Log (transacciones activas)
~/.rai/raise.db-shm    ← Índice de memoria compartida

Estos son archivos normales de modo WAL de SQLite — no son corrupción. Desaparecen cuando ningún proceso de RaiSE tiene la base de datos abierta. Si persisten tras el cierre de todos los procesos de RaiSE, se incorporan de forma segura a la DB principal en la próxima apertura.

Comandos Clave

Verificar salud de la base de datos:

rai db status

RaiSE DB: /home/alice/.rai/raise.db (8,988 KB)
Schema version: 24
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Tabla                  ┃  Filas ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ sessions               │   543 │
│ signals                │ 1,204 │
│ patterns               │ 1,713 │
│ pipeline_runs          │ 1,539 │
│ artifacts              │     7 │
└────────────────────────┴───────┘

Exportar para backup:

rai db export

Exporta todas las tablas como archivos JSONL a un directorio con timestamp:

Exported 16 tables to .raise/rai/personal/export/20260506T081234/

Cada tabla se convierte en un archivo .jsonl (p.ej. sessions.jsonl, signals.jsonl). Ejecuta esto antes de actualizar RaiSE o antes de una migración de máquina.

Migrar desde RaiSE 2.x:

Si estás actualizando desde 2.x (donde los datos se almacenaban en archivos .raise/rai/personal/*.jsonl), ejecuta la migración de una sola vez:

rai db migrate

Esto importa tus datos JSONL/YAML legacy a SQLite. Los archivos antiguos se renombran a *.migrated (no se eliminan). Consulta la Guía de Migración para el procedimiento completo de actualización.

Verificar integridad del esquema:

rai schema sum check

Verifica que .raise/schema.sum coincide con los hashes de migración actuales. Ejecuta esto tras actualizar RaiSE para confirmar que el esquema es consistente.

Regenerar el archivo de integridad (tras actualizaciones de raise-cli que agregan nuevas migraciones):

rai schema sum update

Reescribe .raise/schema.sum con los hashes de migración actuales. Haz commit del resultado junto con cualquier cambio de migración de esquema. Si check reporta obsoleto, ejecuta update y vuelve a ejecutar check.