feat(compile): autorewrite front matter via versioned migration chain

Introduces a Django/Rails-style schema-version field on FrontMatter and a
registered migration framework so breaking grammar changes auto-migrate
existing user sources during compile rather than hard-failing.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

AGENTS.md

@@ -61,6 +61,10 @@ Every compiled pipeline runs as three sequential jobs:
 │   │   │   ├── safe_outputs.rs # Always-on SafeOutputs MCP extension
 │   │   │   ├── trigger_filters.rs # Trigger filter extension (gate evaluator delivery)
 │   │   │   └── tests.rs  # Extension integration tests
+│   │   ├── migrations/   # Front-matter migrations (one file per version step)
+│   │   │   ├── mod.rs    # Migration struct, MIGRATIONS registry, runner, CURRENT_SCHEMA_VERSION
+│   │   │   └── helpers.rs # take_key, insert_no_overwrite, rename_key, ConflictPolicy
+│   │   ├── migration_integration_test.rs # White-box rewrite-path tests (stub registry injection)
 │   │   └── types.rs      # Front matter grammar and types
 │   ├── init.rs           # Repository initialization for AI-first authoring
 │   ├── execute.rs        # Stage 3 safe output execution
@@ -192,6 +196,9 @@ index to jump to the right page.
 - [`docs/filter-ir.md`](docs/filter-ir.md) — filter expression IR
   specification: `Fact`/`Predicate` types, three-pass compilation (lower →
   validate → codegen), gate step generation, adding new filter types.
+- [`docs/migrations.md`](docs/migrations.md) — front-matter migration
+  framework: schema-version field, automatic source rewrite on
+  breaking-change updates, contributor workflow for adding migrations.
 - [`docs/local-development.md`](docs/local-development.md) — local development
   setup notes.
 

docs/extending.md

@@ -9,6 +9,9 @@ When extending the compiler:
 1. **New CLI commands**: Add variants to the `Commands` enum in `main.rs`
 2. **New compile targets**: Implement the `Compiler` trait in a new file under `src/compile/`
 3. **New front matter fields**: Add fields to `FrontMatter` in `src/compile/types.rs`
+   - **Breaking changes** (renames, removals, type changes, added required fields)
+     require adding a migration under `src/compile/migrations/` in the same PR.
+     See [`docs/migrations.md`](migrations.md).
 4. **New template markers**: Handle replacements in the target-specific compiler (e.g., `standalone.rs` or `onees.rs`)
 5. **New safe-output tools**: Add to `src/safeoutputs/` — implement `ToolResult`, `Executor`, register in `mod.rs`, `mcp.rs`, `execute.rs`
 6. **New first-class tools**: Create `src/tools/<name>/` with `mod.rs` and `extension.rs` (CompilerExtension impl). Add `execute.rs` if the tool has Stage 3 runtime logic. Extend `ToolsConfig` in `types.rs`, add collection in `collect_extensions()`

docs/front-matter.md

@@ -8,6 +8,7 @@ The compiler expects markdown files with YAML front matter similar to gh-aw:
 
 ```markdown
 ---
+schema-version: 1               # Optional: front-matter schema version (defaults to 1). The compiler bumps this in place when migrations apply during compilation. See docs/migrations.md.
 name: "name for this agent"
 description: "One line description for this agent"
 target: standalone # Optional: "standalone" (default) or "1es". See docs/targets.md.