Saltar a contenido

Migrating from 2.x to 3.0

RaiSE 3.0 includes several breaking changes. This guide walks through each one with the exact steps to upgrade your project.

Who needs this: Anyone upgrading an existing project from RaiSE 2.4.x to 3.0.0.

Before You Start

  1. Back up your .raise/ directory (optional but recommended): 

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

  2. Check your current version: 

    rai --version

  3. Install 3.0: 

    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --version 3.0.0
    Or for the latest pre-release: 
    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --pre

Breaking Changes

BC1 — confluence.yaml renamed to docs.yaml

What changed: The documentation adapter config file was renamed from .raise/confluence.yaml to .raise/docs.yaml. The schema also changed: instances: is now targets:, default_instance: is now default_target:, and each target requires a type: field.

Is it auto-migrated? Yes — the first time you run rai docs write, RaiSE auto-creates docs.yaml from your confluence.yaml. However, the old file is not deleted, so you need to clean it up manually.

Fix:

# After running any rai docs command once (auto-migration creates docs.yaml):
git add .raise/docs.yaml
git rm .raise/confluence.yaml
git commit -m "chore: migrate confluence.yaml → docs.yaml (RaiSE 3.0)"

Before (.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

After (.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

Verify: 

rai doctor

BC2 — /rai-story-run removed

What changed: The /rai-story-run skill has been removed. Story pipelines are now started through the pipeline_start MCP tool or the rai pipeline CLI.

Fix: Replace any /rai-story-run invocations with one of the following:

Option A — MCP tool (recommended, from Claude Code):

Ask your AI assistant to start the pipeline: 

Start the story pipeline for RAISE-1234
The assistant calls pipeline_start automatically and guides you through each phase.

Option B — Inside Claude Code via skill: 

/rai-story-start RAISE-1234
Then follow the pipeline phases manually with /rai-story-design, /rai-story-plan, etc.

Note: There is no rai pipeline CLI command — pipelines run exclusively through the MCP tool (pipeline_start, pipeline_advance, pipeline_status).

See also: Pipeline Quickstart

BC3 — SQLite replaces JSONL/JSON storage

What changed: All local RaiSE data (sessions, signals, patterns, artifacts, pipeline runs) has moved from flat files (.raise/rai/personal/*.jsonl, *.json, *.yaml) to a SQLite database at .raise/raise.db.

Is it auto-migrated? Yes — on the first rai command after upgrading, the migration runs automatically. Your old JSONL files are renamed *.migrated (not deleted).

Manual migration (if auto-migration didn't run): 

rai db migrate

Verify: 

rai db status
# Should show: schema_version=24, tables with row counts

Rollback: Your *.migrated files are preserved. To restore them, rename them back (contact support for the restore script).

BC4 — Global SQLite database

What changed: RaiSE 3.0 introduces a single global database at ~/.rai/raise.db that holds cross-project data. All project-scoped tables now have a project_id column.

Impact for most users: None — the rai CLI handles project_id filtering automatically.

Impact if you query SQLite directly (advanced users): 

-- Before (2.x): query worked without filtering
SELECT * FROM sessions;

-- After (3.0): must filter by project_id
SELECT * FROM sessions WHERE project_id = '<your-project-hash>';

To find your project ID: 

rai db status
# Shows: project_id: <hash>

BC5 — Session data location

What changed: Session state moved from a mix of ~/.rai/ global files and per-project JSONL into .raise/rai/personal/ (per-project) and ~/.rai/raise.db (global index).

Impact: If you had scripts reading ~/.rai/developer.yaml active session fields, those fields are no longer updated. Session data is now in SQLite.

Fix: 

# Query active session via CLI instead of reading YAML
rai session list
rai session info

Verify: 

rai session list
# Should show your recent sessions from SQLite

BC6 — schema.sum integrity gate

What changed: RaiSE 3.0 requires a .raise/schema.sum file that tracks migration hashes. The gate-schema-sum gate (triggered at story close) fails if this file is missing or stale.

Impact: If you skip this, rai-story-close will fail at the gate check.

Fix: 

# Generate schema.sum for your project
rai schema sum update

# Commit it
git add .raise/schema.sum
git commit -m "chore: add schema.sum integrity file (RaiSE 3.0)"

Verify: 

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

BC7 — Use rai upgrade for existing projects

What changed: rai init is now for first-time setup only. Running it on an already-initialized project will show an error and suggest rai upgrade instead.

Before (2.x): Re-running rai init updated skills and framework files.

After (3.0): Use rai upgrade to update an existing project: 

# Update skills, framework files, and AGENTS.md
rai upgrade

# Preview what would change
rai upgrade --dry-run

# Also re-detect AI agents
rai upgrade --detect

BC8 — Backlog pending-ops dead-letter workflow

What changed: Failed backlog sync operations (e.g., Jira calls that failed during offline work) now go to a dead-letter queue instead of silently disappearing.

Impact: If you have unsynced backlog ops from 2.x that failed, they appear in the dead-letter queue after migration.

Check for dead-letter ops: 

rai backlog pending-ops list --dead

Drain (retry or purge): 

# Purge a specific failed op
rai backlog pending-ops purge --id <op-id>

# Purge all dead-letter ops (after reviewing them)
rai backlog pending-ops purge --yes

Post-Migration Verification

After completing all applicable steps above:

# Full diagnostics
rai doctor

# Check database state
rai db status

# Verify schema integrity
rai schema sum check

# List recent sessions (confirms SQLite is working)
rai session list

All checks should pass green. If rai doctor reports issues, follow the --fix suggestions:

rai doctor --fix

Getting Help