@delegance/claude-autopilot 5.0.8 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## v5.2.0 — Migrate skill generalization
+
+### Added
+
+- **Generalized migrate phase** — `migrate@1` (thin orchestrator), `migrate.supabase@1` (rich Delegance runner, paths now parameterized via stack.md), `none@1` (no-op for `--skip-migrate`). Pipeline reads `.autopilot/stack.md` to dispatch the right skill.
+- **Auto-detection at init** — `claude-autopilot init` walks the repo, sniffs for Prisma / Drizzle / Rails / Go-migrate / Flyway / dbmate / Alembic / Django / Ecto / TypeORM / Supabase signals, writes a stack.md non-interactively when there's a single high-confidence match. Prompts otherwise.
+- **Stack.md schema validation** with security rules: shell metachars rejected in command args, env_file paths confined under project_root, dev_command-as-prod-command blocked.
+- **Versioned alias map** (`presets/aliases.lock.json`) with stable IDs (`migrate@1`, `migrate.supabase@1`, `none@1`) so future renames don't break user configs.
+- **Skill manifest version handshake** — every skill ships `skill.manifest.json` declaring `skill_runtime_api_version`, `min_runtime`, `max_runtime`. Dispatcher fails closed on incompatibility with explicit upgrade hints.
+- **Hash-chained audit log** at `.autopilot/audit.log` (JSONL, monotonic seq + SHA-256 prev_hash chain) for every migrate dispatch. `claude-autopilot doctor` validates the chain.
+- **Per-policy enforcement points** — `allow_prod_in_ci`, `require_clean_git`, `require_manual_approval`, `require_dry_run_first`. CI prod migrations require all 4 of: `--yes` flag, `AUTOPILOT_CI_POLICY=allow-prod`, `AUTOPILOT_TARGET_ENV=<env>`, stack.md `policy.allow_prod_in_ci: true`. Plus a recognized CI provider env (or `AUTOPILOT_CI_PROVIDER` override).
+- **Structured argv execution** — commands stored as `{ exec, args[] }` and executed via `spawn(shell:false)`. No shell injection vector. Legacy string form deprecated, auto-migrated by `doctor --fix`.
+- **`migrate doctor`** with read-only mode (default) and `--fix` mode for safe auto-corrections.
+- **Monorepo support** — per-workspace `.autopilot/stack.md` plus root `.autopilot/manifest.yaml` for cross-workspace coordination.
+- **Legacy migrate skill migrator** — automatically archives the existing `skills/migrate/` (legacy Delegance Supabase shape) to `skills/migrate.backup-<ISO>/` on `doctor --fix`, replaces with the thin shape.
+- **Multi-CI provider detection** — GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins recognized out of the box. `AUTOPILOT_CI_PROVIDER` override for self-hosted.
+- **Delegance regression CI lane** — required GitHub Actions job that runs the full migrate-supabase flow against an anonymized fixture, asserting byte-for-byte ledger compatibility with pre-dispatcher behavior.
+
+### Changed
+
+- `skills/autopilot/SKILL.md` Step 4 (Migrate) rewritten to describe the envelope-based dispatcher contract instead of invoking `/migrate` directly.
+
+### Backward-compat
+
+- Delegance's existing `npx tsx scripts/supabase/migrate.ts` CLI invocation still works unchanged. The script now ALSO honors the autopilot dispatcher when invoked with `AUTOPILOT_ENVELOPE` + `AUTOPILOT_RESULT_PATH` env vars; falls back to legacy CLI parsing otherwise.
+- The old `skills/migrate/` legacy SKILL.md is preserved (and will be auto-archived on first `doctor --fix` post-upgrade).
+
+### Migration guide for existing users
+
+```bash
+# Upgrade
+npm install -g @delegance/claude-autopilot@5.2.0
+
+# Audit current state (read-only, exits non-zero if migration needed)
+claude-autopilot doctor
+
+# Apply auto-fixes (archives legacy /migrate skill, writes new stack.md)
+claude-autopilot doctor --fix
+```
+
+Existing `npx tsx scripts/supabase/migrate.ts <file> --env dev` workflows are unaffected.
+
 ## [5.0.0] — 2026-04-27
 
 First GA release after a five-alpha soak cycle. Promotes `5.0.0-alpha.5` to GA unchanged on the code side; the only diff is the version bump, README rebranding away from `@alpha` channel guidance, and a new "Reproducing the benchmark" section.

package/README.md

@@ -78,12 +78,16 @@ Each phase is a Claude Code skill (`.claude/skills/<name>/SKILL.md`). You can in
 | **Plan** | `writing-plans` | Breaks spec into phased, checklist-shaped implementation plan | Claude |
 | **Plan review** | `codex-review` | Second model critiques the plan before you execute it | Codex / GPT-5 |
 | **Implement** | `subagent-driven-development` | Executes plan in a git worktree, one phase at a time, with per-phase tests | Claude |
-| **Migrate** | `migrate` | Runs database migrations dev → QA → prod with per-env validation | Deterministic |
+| **Migrate** | `migrate` | Dispatches to the configured migration skill (see [Migrate phase](#migrate-phase)) — runs your migration tool dev → QA → prod with per-env validation | Deterministic |
 | **Validate** | `validate` | Static rules + tests + type check + security scan + LLM review | Any |
 | **PR** | `commit-push-pr` | Opens the PR with auto-generated title, summary, and test plan | Claude |
 | **Review** | `review-2pass` / `council` | Multi-model review of the diff (critical pass + informational pass) | Multiple |
 | **Triage** | `bugbot` | Fetches automated reviewer findings, auto-fixes real bugs, dismisses false positives | Claude |
 
+### Migrate phase
+
+Configure your migration tool in `.autopilot/stack.md`. The pipeline reads stack.md, dispatches to the configured skill (`migrate@1` for generic; `migrate.supabase@1` for rich Supabase ledger; `none@1` to skip), and runs your tool with full safety: structured argv (no shell injection), 4-flag CI prod gate, hash-chained audit log. Run `claude-autopilot init` to auto-detect your stack. See [docs/skills/rich-migrate-contract.md](docs/skills/rich-migrate-contract.md) for the skill contract and [docs/skills/version-compatibility.md](docs/skills/version-compatibility.md) for the version model.
+
 ## What's distinctive
 
 Features that are hard or impossible to find in the competitive set:

package/dist/src/cli/index.js

@@ -27,6 +27,9 @@ import { runWorker } from "./worker.js";
 import { runTestGen } from "./test-gen.js";
 import { runCouncilCmd } from "./council.js";
 import { runMigrateV4 } from "./migrate-v4.js";
+import { runMigrateDoctor } from "./migrate-doctor.js";
+import { initMigrate, NoMigrationToolDetectedError } from "./init-migrate.js";
+import { dispatch as runMigrateDispatch } from "../core/migrate/dispatcher.js";
 import { findPackageRoot } from "./_pkg-root.js";
 import { GuardrailError } from "../core/errors.js";
 // Format unhandled errors as a one-line user-facing message instead of dumping a
@@ -156,7 +159,7 @@ These are aliases for the flat subcommands; they still work without the 'advance
     }
     args.shift(); // drop 'advanced'
 }
-const SUBCOMMANDS = ['init', 'run', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'brainstorm', 'help', '--help', '-h'];
+const SUBCOMMANDS = ['init', 'run', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'brainstorm', 'help', '--help', '-h'];
 const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
@@ -210,6 +213,32 @@ function flag(name) {
 function boolFlag(name) {
     return args.includes(`--${name}`);
 }
+/**
+ * Run the migrate-doctor with shared CLI formatting and exit handling.
+ *
+ * Both `migrate doctor` (two-word) and `migrate-doctor` (single-verb alias)
+ * resolve to this helper to keep their behavior locked together.
+ */
+async function runMigrateDoctorCLI() {
+    const fix = args.includes('--fix');
+    const result = await runMigrateDoctor({ repoRoot: process.cwd(), fix });
+    for (const r of result.results) {
+        const mark = r.result.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+        console.log(`${mark} ${r.name}${r.result.message ? ` — ${r.result.message}` : ''}`);
+        if (!r.result.ok && r.result.fixHint) {
+            console.log(`  \x1b[2mhint: ${r.result.fixHint}\x1b[0m`);
+        }
+    }
+    if (result.mutations && result.mutations.length > 0) {
+        console.log(`\n\x1b[1mFixes applied:\x1b[0m`);
+        for (const m of result.mutations)
+            console.log(`  - ${m}`);
+    }
+    if (result.migrationReportPath) {
+        console.log(`\n\x1b[2mMigration report: ${result.migrationReportPath}\x1b[0m`);
+    }
+    process.exit(result.allOk ? 0 : 1);
+}
 function printUsage() {
     console.log(`
 Usage: claude-autopilot <command> [options]  (legacy alias: guardrail)
@@ -225,7 +254,9 @@ Commands:
   fix          Auto-fix cached findings using the configured LLM
   costs        Show per-run cost summary
   ci           Opinionated CI entrypoint (post comments + SARIF)
-  init         Scaffold guardrail.config.yaml from a preset
+  init         Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)
+  migrate      Run database migrations via the stack-aware dispatcher
+  migrate doctor   Validate .autopilot/stack.md and skill manifests (alias: migrate-doctor)
   setup        Auto-detect stack, write config, install pre-push hook
   doctor       Check prerequisites (alias: preflight)
   preflight    Check prerequisites (alias: doctor)
@@ -280,6 +311,14 @@ Options (autoregress):
   --since <ref>            Git ref for changed-files detection
   --snapshot <slug>        Target a single snapshot
   --files <a,b,c>          Explicit file list for generate (skips git detection)
+
+Options (migrate):
+  --env <name>         Target environment from .autopilot/stack.md (default: dev)
+  --dry-run            Run skill in dry-run mode (no side effects)
+  --yes                Required to apply prod migrations in CI
+
+Options (migrate doctor / migrate-doctor):
+  --fix                Apply auto-fixable mutations (legacy stack.md, skills/migrate/, schema_version)
 `);
 }
 switch (subcommand) {
@@ -310,6 +349,42 @@ switch (subcommand) {
         // `init` and `setup` are aliases. Keep both supported — no nag banner.
         const force = args.includes('--force');
         await runSetup({ force });
+        // After the existing init/setup logic, sniff for a migration tool and write
+        // .autopilot/stack.md. Non-interactive: high-confidence single matches are
+        // auto-selected; ambiguity / no-match downgrades to a TODO 'none@1' shape so
+        // we don't block the user. (Interactive prompts come from the autopilot skill,
+        // not the CLI.)
+        try {
+            const result = await initMigrate({
+                repoRoot: process.cwd(),
+                force,
+            });
+            for (const ws of result.workspaces) {
+                const rel = ws.workspace === process.cwd() ? '.' : ws.workspace;
+                console.log(`\x1b[2m[init-migrate] ${ws.action} ${rel}/.autopilot/stack.md (skill: ${ws.skill})\x1b[0m`);
+            }
+        }
+        catch (err) {
+            if (err instanceof NoMigrationToolDetectedError) {
+                // No high-confidence match — fall back to skipMigrate shape so the user
+                // can edit it later. This matches the auto-detection contract documented
+                // in the v5.2.0 CHANGELOG.
+                try {
+                    await initMigrate({
+                        repoRoot: process.cwd(),
+                        force,
+                        skipMigrate: true,
+                    });
+                    console.log(`\x1b[33m[init-migrate] No migration tool detected — wrote 'none@1' stack.md (edit .autopilot/stack.md to configure)\x1b[0m`);
+                }
+                catch (fallbackErr) {
+                    console.error(`\x1b[31m[init-migrate] failed: ${fallbackErr.message}\x1b[0m`);
+                }
+            }
+            else {
+                console.error(`\x1b[31m[init-migrate] failed: ${err.message}\x1b[0m`);
+            }
+        }
         break;
     }
     case 'doctor':
@@ -577,6 +652,59 @@ switch (subcommand) {
         process.exit(code);
         break;
     }
+    case 'migrate': {
+        // Two-word `migrate doctor` is dispatched here before the generic migrate
+        // path so we don't try to read a stack.md or pick an env when the user is
+        // really asking for the doctor. `migrate-doctor` (single verb, below) is
+        // an equivalent alias.
+        if (args[1] === 'doctor') {
+            await runMigrateDoctorCLI();
+            break;
+        }
+        // Plain `migrate [--env <name>] [--dry-run] [--yes]` → dispatcher.
+        const envName = flag('env') ?? 'dev';
+        const dryRun = boolFlag('dry-run');
+        const yesFlag = boolFlag('yes');
+        // Read package version for the runtime handshake.
+        const root = findPackageRoot(import.meta.url);
+        let runtimeVersion = 'unknown';
+        if (root) {
+            try {
+                const nodeFs = await import('node:fs');
+                const nodePath = await import('node:path');
+                const pkg = JSON.parse(nodeFs.readFileSync(nodePath.join(root, 'package.json'), 'utf8'));
+                runtimeVersion = pkg.version;
+            }
+            catch {
+                /* fall through with 'unknown' — handshake will fail closed */
+            }
+        }
+        const result = await runMigrateDispatch({
+            repoRoot: process.cwd(),
+            env: envName,
+            yesFlag,
+            nonInteractive: !process.stdin.isTTY,
+            currentRuntimeVersion: runtimeVersion,
+            dryRun,
+        });
+        const ok = result.status === 'applied' || result.status === 'skipped';
+        const color = ok ? '\x1b[32m' : '\x1b[31m';
+        console.log(`${color}[migrate] status=${result.status} reason=${result.reasonCode}\x1b[0m`);
+        if (result.appliedMigrations.length > 0) {
+            console.log(`  applied: ${result.appliedMigrations.join(', ')}`);
+        }
+        if (result.nextActions.length > 0) {
+            console.log(`  next: ${result.nextActions.join('; ')}`);
+        }
+        process.exit(ok ? 0 : 1);
+        break;
+    }
+    case 'migrate-doctor': {
+        // Single-verb alias for `migrate doctor`. Documented for users whose shells
+        // or CI configs handle multi-word verbs awkwardly.
+        await runMigrateDoctorCLI();
+        break;
+    }
     case 'brainstorm': {
         // `brainstorm` is the front of the pipeline and is implemented as a Claude
         // Code skill (superpowers:brainstorming → autopilot), not a standalone CLI.

package/dist/src/cli/init-migrate.d.ts

@@ -0,0 +1,35 @@
+import { type DetectionMatch } from '../core/migrate/detector.ts';
+export declare class NoMigrationToolDetectedError extends Error {
+    constructor(message: string);
+}
+export interface PrompterArgs {
+    workspace: string;
+    matches: DetectionMatch[];
+}
+export type Prompter = (args: PrompterArgs) => Promise<DetectionMatch>;
+export interface InitMigrateOptions {
+    repoRoot: string;
+    skipMigrate?: boolean;
+    force?: boolean;
+    /**
+     * When true, computes what would be written but performs no write.
+     * Each workspace result includes a `diff` field showing the
+     * proposed change against the existing stack.md (or "would create
+     * new file" if missing). Used by `--force-rewrite` to preview
+     * changes before user confirmation.
+     */
+    dryRunPreview?: boolean;
+    prompter?: Prompter;
+}
+export interface WorkspaceResult {
+    workspace: string;
+    action: 'wrote' | 'updated' | 'skipped' | 'preview';
+    skill: string;
+    /** Populated only when dryRunPreview is true. */
+    diff?: string;
+}
+export interface InitMigrateResult {
+    workspaces: WorkspaceResult[];
+}
+export declare function initMigrate(opts: InitMigrateOptions): Promise<InitMigrateResult>;
+//# sourceMappingURL=init-migrate.d.ts.map

package/dist/src/cli/init-migrate.js

@@ -0,0 +1,299 @@
+// src/cli/init-migrate.ts
+//
+// Init flow extension for the migrate skill. Walks workspaces, runs
+// detection per workspace, and writes a per-workspace
+// `<workspace>/.autopilot/stack.md` (plus a root `<repoRoot>/.autopilot/
+// manifest.yaml` for monorepos).
+//
+// Decision tree per workspace:
+//   - --skipMigrate: write `migrate.skill: "none@1"` shape with TODO
+//   - autoSelect (1 high-confidence match): write the rule's defaults
+//   - prompt required (>1 match or non-high): call injected prompter
+//   - zero matches: throw NoMigrationToolDetectedError
+//
+// Idempotent: existing stack.md is loaded and merged. User-edited fields
+// (envs.*.command, custom env_file, etc.) are preserved; only
+// `detected_at` is refreshed and missing default policy keys are added.
+// `force: true` regenerates from scratch.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+import { detect } from "../core/migrate/detector.js";
+import { findWorkspaces } from "../core/migrate/monorepo.js";
+export class NoMigrationToolDetectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NoMigrationToolDetectedError';
+    }
+}
+const DEFAULT_POLICY_GENERIC = {
+    allow_prod_in_ci: false,
+    require_clean_git: true,
+    require_manual_approval: true,
+    require_dry_run_first: false,
+};
+const DEFAULT_POLICY_SUPABASE = {
+    allow_prod_in_ci: false,
+};
+const DEFAULT_PROMPTER = async () => {
+    throw new Error('interactive prompt not available — pass `prompter` in initMigrate options or run with --skip-migrate');
+};
+function buildFreshStack(rule, skipMigrate) {
+    const detectedAt = new Date().toISOString();
+    if (skipMigrate) {
+        return {
+            schema_version: 1,
+            migrate: {
+                skill: 'none@1',
+                detected_at: detectedAt,
+                project_root: '.',
+            },
+        };
+    }
+    if (rule.defaultSkill === 'migrate.supabase@1') {
+        return {
+            schema_version: 1,
+            migrate: {
+                skill: 'migrate.supabase@1',
+                supabase: {
+                    deltas_dir: 'data/deltas',
+                    types_out: 'types/supabase.ts',
+                    envs_file: '.claude/supabase-envs.json',
+                },
+                policy: { ...DEFAULT_POLICY_SUPABASE },
+                detected_at: detectedAt,
+                project_root: '.',
+            },
+        };
+    }
+    // Generic migrate@1 shape
+    const stack = {
+        schema_version: 1,
+        migrate: {
+            skill: 'migrate@1',
+            policy: { ...DEFAULT_POLICY_GENERIC },
+            detected_at: detectedAt,
+            project_root: '.',
+        },
+    };
+    if (rule.defaultCommand) {
+        stack.migrate.envs = {
+            dev: { command: { ...rule.defaultCommand, args: [...rule.defaultCommand.args] } },
+        };
+    }
+    else {
+        // No default command in the rule; init still writes envs.dev as a
+        // placeholder so schema validates. User is expected to fill it in.
+        stack.migrate.envs = {
+            dev: { command: { exec: 'TODO', args: ['configure-dev-command'] } },
+        };
+    }
+    return stack;
+}
+function mergePreserving(existing, fresh) {
+    // Preserve all user fields; only update detected_at and add missing
+    // defaults (schema_version, missing policy keys, project_root).
+    const merged = {
+        schema_version: existing.schema_version ?? fresh.schema_version,
+        migrate: { ...existing.migrate },
+    };
+    // Always refresh detected_at
+    merged.migrate.detected_at = fresh.migrate.detected_at;
+    // Backfill project_root if missing
+    if (!merged.migrate.project_root && fresh.migrate.project_root) {
+        merged.migrate.project_root = fresh.migrate.project_root;
+    }
+    // Merge missing default policy keys (do not overwrite user-set keys)
+    if (fresh.migrate.policy) {
+        const existingPolicy = (merged.migrate.policy ?? {});
+        const mergedPolicy = { ...existingPolicy };
+        for (const [k, v] of Object.entries(fresh.migrate.policy)) {
+            if (!(k in mergedPolicy))
+                mergedPolicy[k] = v;
+        }
+        merged.migrate.policy = mergedPolicy;
+    }
+    // Backfill supabase block if missing (preserve user values otherwise)
+    if (fresh.migrate.supabase && !merged.migrate.supabase) {
+        merged.migrate.supabase = { ...fresh.migrate.supabase };
+    }
+    // Backfill envs.dev if missing (preserve user-set commands otherwise)
+    if (fresh.migrate.envs?.dev && !merged.migrate.envs) {
+        merged.migrate.envs = {
+            dev: { ...fresh.migrate.envs.dev },
+        };
+    }
+    else if (fresh.migrate.envs?.dev && merged.migrate.envs && !merged.migrate.envs.dev) {
+        merged.migrate.envs.dev = { ...fresh.migrate.envs.dev };
+    }
+    return merged;
+}
+function readExistingStackMd(stackPath) {
+    try {
+        const content = fs.readFileSync(stackPath, 'utf8');
+        const parsed = yaml.load(content);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            'migrate' in parsed) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function serializeStackMd(stack, options) {
+    // YAML body
+    const body = yaml.dump(stack, { lineWidth: 120, noRefs: true });
+    if (options.skipMigrate) {
+        return (body +
+            '# TODO: configure your migration tool. See docs/skills/rich-migrate-contract.md\n');
+    }
+    return body;
+}
+/**
+ * Produce a unified-diff-style summary of the change from `oldText` to
+ * `newText`. Pure-line LCS — no external dependency. Output is for human
+ * review only; not intended to round-trip via `patch`.
+ */
+function unifiedDiff(oldText, newText) {
+    if (oldText === newText)
+        return '';
+    const a = oldText.split('\n');
+    const b = newText.split('\n');
+    const m = a.length;
+    const n = b.length;
+    // LCS table
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            if (a[i] === b[j]) {
+                lcs[i][j] = lcs[i + 1][j + 1] + 1;
+            }
+            else {
+                lcs[i][j] = Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+            }
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (a[i] === b[j]) {
+            out.push(`  ${a[i]}`);
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            out.push(`- ${a[i]}`);
+            i++;
+        }
+        else {
+            out.push(`+ ${b[j]}`);
+            j++;
+        }
+    }
+    while (i < m) {
+        out.push(`- ${a[i]}`);
+        i++;
+    }
+    while (j < n) {
+        out.push(`+ ${b[j]}`);
+        j++;
+    }
+    return out.join('\n');
+}
+function chooseRule(matches, autoSelect, prompter, workspace) {
+    if (autoSelect)
+        return Promise.resolve(matches[0]);
+    return prompter({ workspace, matches });
+}
+export async function initMigrate(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const skipMigrate = opts.skipMigrate ?? false;
+    const force = opts.force ?? false;
+    const dryRunPreview = opts.dryRunPreview ?? false;
+    const prompter = opts.prompter ?? DEFAULT_PROMPTER;
+    const workspaces = findWorkspaces(repoRoot);
+    const results = [];
+    for (const workspace of workspaces) {
+        const stackDir = path.join(workspace, '.autopilot');
+        const stackPath = path.join(stackDir, 'stack.md');
+        const exists = fs.existsSync(stackPath);
+        let chosenRule = null;
+        if (!skipMigrate) {
+            const det = detect(workspace);
+            if (det.matches.length === 0) {
+                throw new NoMigrationToolDetectedError(`No migration tool detected in ${workspace}. Re-run with --skip-migrate to write a 'none@1' stack.md and configure later.`);
+            }
+            const chosen = await chooseRule(det.matches, det.autoSelect, prompter, workspace);
+            chosenRule = chosen.rule;
+        }
+        // For skipMigrate, chosenRule stays null — buildFreshStack ignores it.
+        const fresh = buildFreshStack(chosenRule ?? {}, skipMigrate);
+        let toWrite;
+        let action;
+        if (dryRunPreview) {
+            // Preview always reflects the *fresh* content (mirrors `force: true`).
+            // Merge-preserving previews can be added later if needed.
+            toWrite = fresh;
+            action = 'preview';
+        }
+        else if (exists && !force) {
+            const existing = readExistingStackMd(stackPath);
+            if (existing) {
+                toWrite = mergePreserving(existing, fresh);
+                action = 'updated';
+            }
+            else {
+                toWrite = fresh;
+                action = 'wrote';
+            }
+        }
+        else {
+            toWrite = fresh;
+            action = 'wrote';
+        }
+        const newContent = serializeStackMd(toWrite, { skipMigrate });
+        if (dryRunPreview) {
+            // Compute diff against existing on disk; do NOT write.
+            const oldContent = exists ? fs.readFileSync(stackPath, 'utf8') : '';
+            const diff = exists
+                ? unifiedDiff(oldContent, newContent)
+                : `would create new file ${path.relative(repoRoot, stackPath) || stackPath}\n${newContent
+                    .split('\n')
+                    .map(l => `+ ${l}`)
+                    .join('\n')}`;
+            results.push({
+                workspace,
+                action,
+                skill: toWrite.migrate.skill,
+                diff,
+            });
+            continue;
+        }
+        fs.mkdirSync(stackDir, { recursive: true });
+        fs.writeFileSync(stackPath, newContent, 'utf8');
+        results.push({
+            workspace,
+            action,
+            skill: toWrite.migrate.skill,
+        });
+    }
+    // Multi-workspace repos: write a root manifest.yaml listing the workspaces.
+    if (workspaces.length > 1 && !dryRunPreview) {
+        const manifestDir = path.join(repoRoot, '.autopilot');
+        fs.mkdirSync(manifestDir, { recursive: true });
+        const manifest = {
+            schema_version: 1,
+            workspaces: results.map(r => ({
+                path: path.relative(repoRoot, r.workspace) || '.',
+                skill: r.skill,
+            })),
+        };
+        fs.writeFileSync(path.join(manifestDir, 'manifest.yaml'), yaml.dump(manifest, { lineWidth: 120, noRefs: true }), 'utf8');
+    }
+    return { workspaces: results };
+}
+//# sourceMappingURL=init-migrate.js.map

package/dist/src/cli/migrate-doctor.d.ts

@@ -0,0 +1,19 @@
+import { type NamedCheckResult } from '../core/migrate/doctor-checks.ts';
+export interface RunMigrateDoctorOptions {
+    repoRoot: string;
+    fix?: boolean;
+}
+export interface RunMigrateDoctorResult {
+    allOk: boolean;
+    results: NamedCheckResult[];
+    /** Populated only when fix=true. Empty if no fixes were needed. */
+    mutations?: string[];
+    /**
+     * Absolute path of the migration report (Markdown) written under
+     * .autopilot/. Populated when fix=true and the legacy migrator ran. Read-
+     * only mode never writes a report.
+     */
+    migrationReportPath?: string;
+}
+export declare function runMigrateDoctor(opts: RunMigrateDoctorOptions): Promise<RunMigrateDoctorResult>;
+//# sourceMappingURL=migrate-doctor.d.ts.map