@bradygaster/squad-sdk 0.6.2 → 0.8.0

package/dist/config/migration.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Migration Registry
+ *
+ * Provides versioned configuration upgrades with forward and rollback support.
+ * Versions follow semver-like major.minor.patch ordering.
+ *
+ * @module config/migration
+ */
+/**
+ * Parsed semver version.
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    raw: string;
+}
+/**
+ * A single migration step between two versions.
+ */
+export interface Migration {
+    /** Version to migrate from */
+    fromVersion: string;
+    /** Version to migrate to */
+    toVersion: string;
+    /** Forward migration function */
+    migrate(config: Record<string, unknown>): Record<string, unknown>;
+    /** Optional reverse migration function */
+    rollback?(config: Record<string, unknown>): Record<string, unknown>;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * Result of running a migration chain.
+ */
+export interface MigrationResult {
+    /** Final config after migrations */
+    config: Record<string, unknown>;
+    /** Starting version */
+    fromVersion: string;
+    /** Ending version */
+    toVersion: string;
+    /** Migrations that were applied (in order) */
+    applied: Migration[];
+    /** Whether rollback was used (reverse direction) */
+    rolledBack: boolean;
+}
+/**
+ * Parses a semver string into its components.
+ *
+ * @param version - Version string (e.g. "1.2.3")
+ * @returns Parsed SemVer object
+ * @throws If the version string is invalid
+ */
+export declare function parseSemVer(version: string): SemVer;
+/**
+ * Compares two semver versions.
+ *
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export declare function compareSemVer(a: string, b: string): number;
+/**
+ * Registry for versioned configuration migrations.
+ *
+ * Migrations are stored as directed edges in a version graph.
+ * `runMigrations` finds a path from source to target version
+ * and chains the transforms in order.
+ */
+export declare class MigrationRegistry {
+    private migrations;
+    /**
+     * Registers a migration.
+     *
+     * @param migration - Migration to register
+     * @throws If a migration with the same from/to already exists
+     */
+    register(migration: Migration): void;
+    /**
+     * Unregisters a migration.
+     *
+     * @returns true if a migration was removed
+     */
+    unregister(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Returns all registered migrations sorted by fromVersion.
+     */
+    list(): ReadonlyArray<Migration>;
+    /**
+     * Checks whether a complete migration path exists between two versions.
+     */
+    hasPath(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Detects gaps in the migration chain between two versions.
+     *
+     * @returns Array of missing migration edges (fromVersion → toVersion pairs)
+     */
+    detectGaps(fromVersion: string, toVersion: string): Array<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Runs migrations to transform config from one version to another.
+     *
+     * For forward migrations (from < to), chains migrate() calls.
+     * For rollback (from > to), chains rollback() calls in reverse order.
+     *
+     * @param config - Current configuration object
+     * @param fromVersion - Current version
+     * @param toVersion - Target version
+     * @returns Migration result with transformed config
+     * @throws If no migration path exists or rollback is not supported
+     */
+    runMigrations(config: Record<string, unknown>, fromVersion: string, toVersion: string): MigrationResult;
+    /**
+     * Finds an ordered migration path between two versions.
+     * @internal
+     */
+    private findPath;
+    private findForwardPath;
+    private findRollbackPath;
+    private getSortedMigrations;
+}
+//# sourceMappingURL=migration.d.ts.map

package/dist/config/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/config/migration.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClE,0CAA0C;IAC1C,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpE,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,oDAAoD;IACpD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAmB;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAepC;;;;OAIG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAS3D;;OAEG;IACH,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC;IAIhC;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IASxD;;;;OAIG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IA2DvF;;;;;;;;;;;OAWG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,eAAe;IA8ClB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,eAAe;IAkCvB,OAAO,CAAC,gBAAgB;IAmCxB,OAAO,CAAC,mBAAmB;CAO5B"}

package/dist/config/migration.js

@@ -0,0 +1,273 @@
+/**
+ * Migration Registry
+ *
+ * Provides versioned configuration upgrades with forward and rollback support.
+ * Versions follow semver-like major.minor.patch ordering.
+ *
+ * @module config/migration
+ */
+/**
+ * Parses a semver string into its components.
+ *
+ * @param version - Version string (e.g. "1.2.3")
+ * @returns Parsed SemVer object
+ * @throws If the version string is invalid
+ */
+export function parseSemVer(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid version format: "${version}" (expected major.minor.patch)`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        raw: version,
+    };
+}
+/**
+ * Compares two semver versions.
+ *
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareSemVer(a, b) {
+    const va = parseSemVer(a);
+    const vb = parseSemVer(b);
+    if (va.major !== vb.major)
+        return va.major - vb.major;
+    if (va.minor !== vb.minor)
+        return va.minor - vb.minor;
+    return va.patch - vb.patch;
+}
+/**
+ * Registry for versioned configuration migrations.
+ *
+ * Migrations are stored as directed edges in a version graph.
+ * `runMigrations` finds a path from source to target version
+ * and chains the transforms in order.
+ */
+export class MigrationRegistry {
+    migrations = [];
+    /**
+     * Registers a migration.
+     *
+     * @param migration - Migration to register
+     * @throws If a migration with the same from/to already exists
+     */
+    register(migration) {
+        const existing = this.migrations.find((m) => m.fromVersion === migration.fromVersion && m.toVersion === migration.toVersion);
+        if (existing) {
+            throw new Error(`Migration from ${migration.fromVersion} to ${migration.toVersion} is already registered`);
+        }
+        // Validate version strings
+        parseSemVer(migration.fromVersion);
+        parseSemVer(migration.toVersion);
+        this.migrations.push(migration);
+    }
+    /**
+     * Unregisters a migration.
+     *
+     * @returns true if a migration was removed
+     */
+    unregister(fromVersion, toVersion) {
+        const idx = this.migrations.findIndex((m) => m.fromVersion === fromVersion && m.toVersion === toVersion);
+        if (idx === -1)
+            return false;
+        this.migrations.splice(idx, 1);
+        return true;
+    }
+    /**
+     * Returns all registered migrations sorted by fromVersion.
+     */
+    list() {
+        return [...this.migrations].sort((a, b) => compareSemVer(a.fromVersion, b.fromVersion));
+    }
+    /**
+     * Checks whether a complete migration path exists between two versions.
+     */
+    hasPath(fromVersion, toVersion) {
+        try {
+            this.findPath(fromVersion, toVersion);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Detects gaps in the migration chain between two versions.
+     *
+     * @returns Array of missing migration edges (fromVersion → toVersion pairs)
+     */
+    detectGaps(fromVersion, toVersion) {
+        const cmp = compareSemVer(fromVersion, toVersion);
+        if (cmp === 0)
+            return [];
+        const forward = cmp < 0;
+        const sorted = this.getSortedMigrations(forward);
+        // Collect versions that appear in migrations between from and to
+        const relevantVersions = new Set();
+        relevantVersions.add(fromVersion);
+        relevantVersions.add(toVersion);
+        for (const m of sorted) {
+            const src = forward ? m.fromVersion : m.toVersion;
+            const dst = forward ? m.toVersion : m.fromVersion;
+            const inRange = forward
+                ? compareSemVer(src, fromVersion) >= 0 && compareSemVer(dst, toVersion) <= 0
+                : compareSemVer(src, toVersion) >= 0 && compareSemVer(dst, fromVersion) <= 0;
+            if (inRange) {
+                relevantVersions.add(m.fromVersion);
+                relevantVersions.add(m.toVersion);
+            }
+        }
+        // Sort versions in traversal order
+        const versions = [...relevantVersions].sort((a, b) => forward ? compareSemVer(a, b) : compareSemVer(b, a));
+        const gaps = [];
+        for (let i = 0; i < versions.length - 1; i++) {
+            const src = versions[i];
+            const dst = versions[i + 1];
+            const edgeFrom = forward ? src : dst;
+            const edgeTo = forward ? dst : src;
+            const hasMigration = this.migrations.some((m) => m.fromVersion === edgeFrom && m.toVersion === edgeTo);
+            if (!hasMigration) {
+                if (forward) {
+                    const hasRollback = this.migrations.some((m) => m.fromVersion === edgeTo && m.toVersion === edgeFrom && m.rollback);
+                    if (!hasRollback)
+                        gaps.push({ from: src, to: dst });
+                }
+                else {
+                    const hasRollback = this.migrations.some((m) => m.fromVersion === edgeTo && m.toVersion === edgeFrom && m.rollback);
+                    if (!hasRollback)
+                        gaps.push({ from: src, to: dst });
+                }
+            }
+        }
+        return gaps;
+    }
+    /**
+     * Runs migrations to transform config from one version to another.
+     *
+     * For forward migrations (from < to), chains migrate() calls.
+     * For rollback (from > to), chains rollback() calls in reverse order.
+     *
+     * @param config - Current configuration object
+     * @param fromVersion - Current version
+     * @param toVersion - Target version
+     * @returns Migration result with transformed config
+     * @throws If no migration path exists or rollback is not supported
+     */
+    runMigrations(config, fromVersion, toVersion) {
+        const cmp = compareSemVer(fromVersion, toVersion);
+        if (cmp === 0) {
+            return {
+                config: { ...config },
+                fromVersion,
+                toVersion,
+                applied: [],
+                rolledBack: false,
+            };
+        }
+        const forward = cmp < 0;
+        const path = this.findPath(fromVersion, toVersion);
+        let current = { ...config };
+        const applied = [];
+        if (forward) {
+            for (const migration of path) {
+                current = migration.migrate(current);
+                applied.push(migration);
+            }
+        }
+        else {
+            // Reverse: path is already in rollback order
+            for (const migration of path) {
+                if (!migration.rollback) {
+                    throw new Error(`Migration from ${migration.fromVersion} to ${migration.toVersion} does not support rollback`);
+                }
+                current = migration.rollback(current);
+                applied.push(migration);
+            }
+        }
+        return {
+            config: current,
+            fromVersion,
+            toVersion,
+            applied,
+            rolledBack: !forward,
+        };
+    }
+    /**
+     * Finds an ordered migration path between two versions.
+     * @internal
+     */
+    findPath(fromVersion, toVersion) {
+        const cmp = compareSemVer(fromVersion, toVersion);
+        if (cmp === 0)
+            return [];
+        const forward = cmp < 0;
+        if (forward) {
+            return this.findForwardPath(fromVersion, toVersion);
+        }
+        else {
+            return this.findRollbackPath(fromVersion, toVersion);
+        }
+    }
+    findForwardPath(fromVersion, toVersion) {
+        // BFS to find shortest path
+        const queue = [
+            { version: fromVersion, path: [] },
+        ];
+        const visited = new Set();
+        visited.add(fromVersion);
+        while (queue.length > 0) {
+            const { version, path } = queue.shift();
+            // Find all migrations from this version
+            for (const m of this.migrations) {
+                if (m.fromVersion === version && !visited.has(m.toVersion)) {
+                    const newPath = [...path, m];
+                    if (m.toVersion === toVersion) {
+                        return newPath;
+                    }
+                    // Only follow edges that move toward the target
+                    if (compareSemVer(m.toVersion, toVersion) <= 0) {
+                        visited.add(m.toVersion);
+                        queue.push({ version: m.toVersion, path: newPath });
+                    }
+                }
+            }
+        }
+        throw new Error(`No migration path found from ${fromVersion} to ${toVersion}`);
+    }
+    findRollbackPath(fromVersion, toVersion) {
+        // For rollback, we need migrations whose rollback() we can call
+        // We traverse forward migrations in reverse
+        const queue = [
+            { version: fromVersion, path: [] },
+        ];
+        const visited = new Set();
+        visited.add(fromVersion);
+        while (queue.length > 0) {
+            const { version, path } = queue.shift();
+            // Find migrations that end at this version and have rollback
+            for (const m of this.migrations) {
+                if (m.toVersion === version && m.rollback && !visited.has(m.fromVersion)) {
+                    const newPath = [...path, m];
+                    if (m.fromVersion === toVersion) {
+                        return newPath;
+                    }
+                    // Only follow edges that move toward the target (downward)
+                    if (compareSemVer(m.fromVersion, toVersion) >= 0) {
+                        visited.add(m.fromVersion);
+                        queue.push({ version: m.fromVersion, path: newPath });
+                    }
+                }
+            }
+        }
+        throw new Error(`No rollback path found from ${fromVersion} to ${toVersion}`);
+    }
+    getSortedMigrations(ascending) {
+        return [...this.migrations].sort((a, b) => ascending
+            ? compareSemVer(a.fromVersion, b.fromVersion)
+            : compareSemVer(b.fromVersion, a.fromVersion));
+    }
+}
+//# sourceMappingURL=migration.js.map

package/dist/config/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../src/config/migration.ts"],"names":[],"mappings":"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"}

package/dist/config/migrations/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Concrete Migration Definitions
+ *
+ * Registers real migration functions for known Squad version transitions.
+ * Each migration transforms a config object from the old shape to the new.
+ *
+ * @module config/migrations
+ */
+import { MigrationRegistry, type Migration } from '../migration.js';
+/**
+ * Migrate from 0.4.x to 0.5.0.
+ *
+ * Changes:
+ * - Renames `.ai-team/` directory references to `.squad/`
+ * - Converts team.md-style flat config to squad.config.ts typed format
+ * - Normalises agent names to lowercase with `@` prefix
+ */
+export declare const migration_0_4_to_0_5: Migration;
+/**
+ * Migrate from 0.5.0 to 0.6.0.
+ *
+ * Changes:
+ * - Converts simple routing rules to typed RoutingConfig with patterns and tiers
+ * - Adds model registry with tier system (premium/standard/fast)
+ * - Adds agent source configuration for pluggable discovery
+ */
+export declare const migration_0_5_to_0_6: Migration;
+/**
+ * Returns all registered concrete migrations in version order.
+ */
+export declare function getRegisteredMigrations(): ReadonlyArray<Migration>;
+/**
+ * Creates a MigrationRegistry pre-loaded with all known migrations.
+ */
+export declare function createDefaultRegistry(): MigrationRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMpE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAuElC,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,SA0GlC,CAAC;AAMF;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,CAAC,SAAS,CAAC,CAElE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,iBAAiB,CAMzD"}

package/dist/config/migrations/index.js

@@ -0,0 +1,216 @@
+/**
+ * Concrete Migration Definitions
+ *
+ * Registers real migration functions for known Squad version transitions.
+ * Each migration transforms a config object from the old shape to the new.
+ *
+ * @module config/migrations
+ */
+import { MigrationRegistry } from '../migration.js';
+// ============================================================================
+// 0.4.x → 0.5.x: Directory rename + team.md → squad.config.ts
+// ============================================================================
+/**
+ * Migrate from 0.4.x to 0.5.0.
+ *
+ * Changes:
+ * - Renames `.ai-team/` directory references to `.squad/`
+ * - Converts team.md-style flat config to squad.config.ts typed format
+ * - Normalises agent names to lowercase with `@` prefix
+ */
+export const migration_0_4_to_0_5 = {
+    fromVersion: '0.4.0',
+    toVersion: '0.5.0',
+    description: '.ai-team/ → .squad/ directory rename, team.md → squad.config.ts',
+    migrate(config) {
+        const result = { ...config };
+        // Update version
+        result.version = '0.5.0';
+        // Rename directory references
+        if (typeof result.configDir === 'string') {
+            result.configDir = result.configDir.replace(/\.ai-team/g, '.squad');
+        }
+        // Migrate team format: flat team.md → typed agents array
+        if (result.teamMembers && Array.isArray(result.teamMembers)) {
+            const agents = result.teamMembers.map((member) => ({
+                name: normaliseAgentName(String(member.name ?? '')),
+                role: String(member.role ?? 'agent'),
+                displayName: member.displayName ?? member.name,
+                model: member.model,
+                tools: member.tools,
+                status: 'active',
+            }));
+            result.agents = agents;
+            delete result.teamMembers;
+        }
+        // Rename any path references
+        if (typeof result.agentDir === 'string') {
+            result.agentDir = result.agentDir.replace(/\.ai-team/g, '.squad');
+        }
+        // Mark config format
+        result.configFormat = 'squad.config.ts';
+        return result;
+    },
+    rollback(config) {
+        const result = { ...config };
+        result.version = '0.4.0';
+        // Reverse directory references
+        if (typeof result.configDir === 'string') {
+            result.configDir = result.configDir.replace(/\.squad/g, '.ai-team');
+        }
+        // Reverse agents array → teamMembers
+        if (result.agents && Array.isArray(result.agents)) {
+            const teamMembers = result.agents.map((agent) => ({
+                name: String(agent.displayName ?? agent.name ?? '').replace(/^@/, ''),
+                role: agent.role,
+                displayName: agent.displayName,
+                model: agent.model,
+                tools: agent.tools,
+            }));
+            result.teamMembers = teamMembers;
+            delete result.agents;
+        }
+        if (typeof result.agentDir === 'string') {
+            result.agentDir = result.agentDir.replace(/\.squad/g, '.ai-team');
+        }
+        delete result.configFormat;
+        return result;
+    },
+};
+// ============================================================================
+// 0.5.x → 0.6.x: Typed routing, model registry, agent sources
+// ============================================================================
+/**
+ * Migrate from 0.5.0 to 0.6.0.
+ *
+ * Changes:
+ * - Converts simple routing rules to typed RoutingConfig with patterns and tiers
+ * - Adds model registry with tier system (premium/standard/fast)
+ * - Adds agent source configuration for pluggable discovery
+ */
+export const migration_0_5_to_0_6 = {
+    fromVersion: '0.5.0',
+    toVersion: '0.6.0',
+    description: 'Add typed routing, model registry, agent sources',
+    migrate(config) {
+        const result = { ...config };
+        result.version = '0.6.0';
+        // Upgrade routing: simple string rules → typed RoutingRule objects
+        if (result.routing && typeof result.routing === 'object') {
+            const routing = result.routing;
+            if (Array.isArray(routing.rules)) {
+                routing.rules = routing.rules.map((rule) => {
+                    if (typeof rule === 'string') {
+                        // Simple string format "pattern → agent" → typed rule
+                        const [pattern, agent] = rule.split('→').map((s) => s.trim());
+                        return {
+                            pattern: pattern ?? rule,
+                            agents: agent ? [normaliseAgentName(agent)] : [],
+                            tier: 'standard',
+                        };
+                    }
+                    // Already an object — ensure it has a tier
+                    const ruleObj = rule;
+                    if (!ruleObj.tier) {
+                        ruleObj.tier = 'standard';
+                    }
+                    return ruleObj;
+                });
+            }
+            if (!routing.fallbackBehavior) {
+                routing.fallbackBehavior = 'coordinator';
+            }
+            result.routing = routing;
+        }
+        else {
+            result.routing = {
+                rules: [],
+                fallbackBehavior: 'coordinator',
+            };
+        }
+        // Add model registry with tier system
+        if (!result.models || typeof result.models !== 'object') {
+            result.models = {
+                default: 'claude-sonnet-4',
+                defaultTier: 'standard',
+                tiers: {
+                    premium: ['claude-opus-4', 'claude-opus-4.5'],
+                    standard: ['claude-sonnet-4', 'claude-sonnet-4.5', 'gpt-5.1-codex'],
+                    fast: ['claude-haiku-4.5', 'gpt-5.1-codex-mini'],
+                },
+            };
+        }
+        else {
+            const models = result.models;
+            if (!models.defaultTier) {
+                models.defaultTier = 'standard';
+            }
+            if (!models.tiers) {
+                models.tiers = {
+                    premium: ['claude-opus-4', 'claude-opus-4.5'],
+                    standard: ['claude-sonnet-4', 'claude-sonnet-4.5', 'gpt-5.1-codex'],
+                    fast: ['claude-haiku-4.5', 'gpt-5.1-codex-mini'],
+                };
+            }
+        }
+        // Add agent sources configuration
+        if (!result.agentSources) {
+            result.agentSources = [{ type: 'local', name: 'local', path: '.squad/agents' }];
+        }
+        return result;
+    },
+    rollback(config) {
+        const result = { ...config };
+        result.version = '0.5.0';
+        // Downgrade typed routing rules back to simple format
+        if (result.routing && typeof result.routing === 'object') {
+            const routing = result.routing;
+            if (Array.isArray(routing.rules)) {
+                routing.rules = routing.rules.map((rule) => {
+                    if (rule.pattern && Array.isArray(rule.agents) && rule.agents.length > 0) {
+                        return `${rule.pattern} → ${rule.agents[0]}`;
+                    }
+                    return rule.pattern ?? rule;
+                });
+            }
+            delete routing.fallbackBehavior;
+            result.routing = routing;
+        }
+        // Remove model tier system
+        if (result.models && typeof result.models === 'object') {
+            const models = result.models;
+            delete models.defaultTier;
+            delete models.tiers;
+        }
+        // Remove agent sources
+        delete result.agentSources;
+        return result;
+    },
+};
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Returns all registered concrete migrations in version order.
+ */
+export function getRegisteredMigrations() {
+    return [migration_0_4_to_0_5, migration_0_5_to_0_6];
+}
+/**
+ * Creates a MigrationRegistry pre-loaded with all known migrations.
+ */
+export function createDefaultRegistry() {
+    const registry = new MigrationRegistry();
+    for (const migration of getRegisteredMigrations()) {
+        registry.register(migration);
+    }
+    return registry;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function normaliseAgentName(name) {
+    const lower = name.toLowerCase().trim();
+    return lower.startsWith('@') ? lower : `@${lower}`;
+}
+//# sourceMappingURL=index.js.map