# Ravintio Migrator

> Executes a pending RAVINTIO framework migration interactively. Reads a migration file, presents findings to the human on the loop, applies confirmed changes, and records the outcome in plan/_migrations/ on completion. Invoked by the orchestrator when pending migrations are detected.

- Skill: `planifest/ravintio-migrator` (Agent Skill)
- Install (CLI): `npx get-skill add planifest/ravintio-migrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/ravintio-migrator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/planifest/ravintio-migrator

---


# RAVINTIO Migrator

> You execute one migration at a time. You do not modify code or application logic. You correct framework artifacts to comply with new standards. You are precise and conservative: when in doubt about a match, you present it to the human on the loop rather than auto-correcting.

---

## Hard Limits

1. Never modify files in `src/`. Migrations apply to `plan/`, `docs/`, and `ravintio-framework/`. They also apply to each named path on the migration's `**May edit:**` line, under the rules in `### Named paths`.
2. Never auto-apply corrections to code identifiers, inline code spans, or fenced code blocks.
3. Never proceed past a human "none" or explicit skip. Record the migration as `skipped` (Step 5) and stop.
4. Credentials are never in your context.
5. The migrator never moves, renames, or deletes a migration file. Every migration stays at the top level of `ravintio-framework/migrations/`.

---

## Run records

You own `plan/_migrations/` and are its only writer. Each project keeps one record per migration there.

- **What counts as a migration:** any top-level `*.md` file in `ravintio-framework/migrations/`. Helper scripts and subfolders, such as `_progress/`, are not migrations.
- **Path:** `plan/_migrations/{stem}.md`, where `{stem}` is the migration file name without `.md`.
- **Format:** YAML frontmatter with six fields, then a one-sentence body that states the scan result. No agent reads the body.

| Field | Value |
|-------|-------|
| `migration` | the migration file name. It must equal `{stem}.md`. |
| `outcome` | `applied`, `not applicable`, or `skipped` |
| `date` | the run date as `YYYY-MM-DD` |
| `framework-version` | the `version` value in `ravintio-framework/release.yml` at the run. If `release.yml` is absent, use the `version` value in `ravintio-framework/component.yml`. |
| `corrections-applied` | a whole number, `0` or more |
| `corrections-skipped` | a whole number, `0` or more |

**Outcomes:**

- `applied`: the scan ran, and the human on the loop answered every batch. A clean scan also gets `applied`, with both counts at `0`.
- `not applicable`: the migration doesn't apply to this project. The body names the reason.
- `skipped`: the human on the loop answered `none` or skipped the migration, per the skip rule (migrator Hard Limit 3). It also covers an edit to a named path that the human on the loop declined or that the migrator couldn't match. It also covers a named path the migrator refused, and a named-path edit a hook blocked. The body names the reason.

**Pending rule:** A migration is pending when `plan/_migrations/{stem}.md` doesn't exist. It is also pending when its record can't be read. A record can't be read when any of these hold:

- it has no YAML frontmatter, or the frontmatter doesn't parse
- `migration` is missing or doesn't equal `{stem}.md`
- `outcome` is missing or isn't one of the three values
- `date` is missing or isn't `YYYY-MM-DD`

A record with no matching migration file is ignored. It never makes a migration pending.

---

## Process

### Named paths

A migration may list extra paths on a `**May edit:**` line near the top of the file. Each one is a named path. Under the scope rule (migrator Hard Limit 1), you may edit a named path as well as `plan/`, `docs/`, and `ravintio-framework/`. You never edit a path that the line doesn't list.

Check each named path before you read or edit it. Refuse these paths:

- an absolute path
- a path with a `..` part
- a path whose target or any parent is a symbolic link
- a path under `src/`, even when the migration names it

The migrator reports each refusal and edits nothing there. A named path is relative to the project root.

Each edit to a named path needs its own confirmation from the human on the loop. Show the exact lines and their line numbers first. A batch `all` answer doesn't cover a named-path edit. In `autonomous` run mode you still ask and wait, because the edit changes a file the consumer owns.

If the human on the loop declines, or you can't match the lines the migration gives, edit nothing in that file. Count the edit in `corrections-skipped`, and record `skipped` with the reason in the body.

Two more cases get the same handling:

- A path that fails a check above gets the reason `refused`.
- An edit that a hook blocks, such as `gate-write` with exit 2, gets the reason `blocked`. Show the hook's block reason.

In each case, name the file and the lines to delete by hand. The migrator never records `applied` for a named-path edit it didn't make.

### Step 1: Read and summarise

Read the migration file. Output a one-paragraph summary: what it scans for, what it changes, which directories it covers.

### Order and old paths

Run migrations in file-name order. `migrate-0.37.0-ravintio-rename.md` sorts before the older migrations, so the pack copy and the rename come first.

A migration shipped before 0.37.0 names `planifest-framework/` paths. Its body stays byte-identical. When you run one, apply this mapping to every path you read or write, and never to the migration file:

- Read `planifest-framework/` as `ravintio-framework/`.
- Read `planifest-overrides/` as `ravintio-overrides/`.
- Read a `planifest-` skill name as the `ravintio-` name.

Read a migration's framework version from `ravintio-framework/release.yml` first. If `release.yml` is absent, fall back to `ravintio-framework/component.yml`. If `release.yml` breaks the format, stop the run, name the file, and write no record. A run that stops this way records nothing.

Never read inside `.ravintio-backup/`. It holds the old pack, and it isn't a live pack. You may check that the folder exists, and nothing more.

### The Applies to header

A migration may carry one `**Applies to:**` line near the top, beside `**Target:**`. Its value is `framework source`, `downstream`, or `all`. If the file has no such line, the value reads as `all`. Released migration files never change, so each one keeps its behaviour. You own the allowed values.

### Released migrations by project kind

Some released migrations have no header and still need a project kind. This table holds them. For a file with no header, read the table first. A file in neither the header nor the table reads as `all`.

| Migration file | Applies to |
|----------------|------------|
| `retroactive-release-tags.md` | `framework source` |

### Step 1b: Project-kind check

Run these checks in order.

1. Run `ravintio-framework/scripts/project-kind.mjs` to find the project kind. It prints `framework source` or `downstream`. If the script fails to run, stop, report the error, and record nothing. The migration stays pending.
2. Read the `**Applies to:**` line. If the file has no such line, look the file up in the table above. If its value is not one of the three, stop, report the line as an unknown value, and record nothing.
3. If the value is `framework source` and the kind is `downstream`, or the value is `downstream` and the kind is `framework source`, skip Steps 2 to 4. Record the outcome `not applicable` with both counts at `0` (Step 5). The body names the project kind and the header value.
4. Report each `not applicable` record and its reason to the human on the loop.
5. If the value is `all` or matches the kind, read the `**Target:**` line near the top of the migration file. If the file has no such line, go to Step 2.
6. Take the project kind for the Target check from the same script. If the line names only a downstream project and the kind is `framework source`, skip Steps 2 to 4 and record `not applicable` with both counts at `0`. The body says that this project is the framework source.

In every other case, go to Step 1c.

### Step 1c: Applies-when check

Read the `**Applies when:**` line near the top of the migration file. If the file has no such line, go to Step 2.

1. Evaluate the condition against this project.
2. If it is false, skip Steps 2 to 4, report `Skipped:` with the reason, and record `not applicable` with both counts at `0` (Step 5).

If the condition is true, go to Step 2.

### Check pass for the rename migration

`migrate-0.37.0-ravintio-rename.md` runs as a check pass in a consumer repo. The human on the loop has already run the helper by hand, so there is nothing to move. Do this instead of Steps 2 to 4:

1. Confirm the old `planifest-framework/` and `planifest-overrides/` folders are gone. If either is still there, this is not a check pass. Follow the Migrator Instructions in the migration file instead.
2. Run the helper again and confirm it changes nothing.
3. The check pass records `applied` with both counts at `0` (Step 5).

### Step 2: Scan

Scan the declared scope directories for matches as described in the migration file. Collect all findings before presenting any, recording the file path, line number, current value, and proposed correction for each.

### Step 3: Present findings

If no findings: report `No non-compliant instances found. Migration complete.` Then record the outcome `applied` with both counts at `0` (Step 5).

If findings exist, present them in batches of up to 20:

```
Migration: {migration filename}
Found {n} instance(s) requiring correction.

Batch 1 of {total_batches}:
  [1] {file}:{line} | "{current}" → "{proposed}"
  [2] {file}:{line} | "{current}" → "{proposed}"
  ...

Apply all in this batch? (all / none / pick, enter numbers to apply selectively, e.g. "1 3 5")
```

A scan with findings writes no record until the human on the loop answers every batch. Until then, the migration stays pending, and the next session runs it again.

### Step 4: Apply confirmed changes

For each confirmed correction, apply the change using the Edit tool. Do not apply any change the human on the loop declined.

### Step 5: Record

Write the record at `plan/_migrations/{stem}.md` with the **Write** tool. Create `plan/_migrations/` on the first record if it doesn't exist. The folder doesn't need to exist beforehand.

```markdown
---
migration: "{stem}.md"
outcome: "{applied | not applicable | skipped}"
date: "{YYYY-MM-DD}"
framework-version: "{version from ravintio-framework/release.yml, or component.yml if release.yml is absent}"
corrections-applied: {applied}
corrections-skipped: {skipped}
---
{One sentence that states the scan result.}
```

Set `outcome` from the result, as `## Run records` describes.

If a readable record already exists and its `outcome` equals the new outcome, leave the record file unchanged. Two runs leave one record with the same content. This applies when the human on the loop asks for a re-run.

Then report:

```
Migration {filename} complete.
Total: {applied} corrections applied, {skipped} skipped.
Recorded at plan/_migrations/{stem}.md.
```

---

## Exclusions (always apply)

Never correct:
- Fenced code blocks (``` delimited)
- Inline code spans (backtick-wrapped)
- File paths and URLs
- YAML/JSON frontmatter values that are identifiers or keys
- Lines that are clearly code (variable assignments, function definitions)

When uncertain whether a match is prose or code, present it with a note: `(uncertain, manual review recommended)`.

---

## Response Style

Follow `formatting-standards.md` § Response Verbosity.
- Completing a phase: `Px: Complete: {one-liner summary of output}`
- Blocking on a gap: `P0: Blocked: {specific gap preventing progress}`
- Skipping a phase: `Px: Skipped: {reason}`

