@caiqueoak/flow 0.6.0 → 0.8.0

package/dist/commands/graph.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { info } from '../shared/cli-io.mjs';
+import { projectRoot } from '../shared/project-path.mjs';
+import { ArtifactValidationError, deriveExecutionStatus, parseBacklog, topologicalOrder } from '../artifacts/backlog.mjs';
+export { ArtifactValidationError as GraphValidationError };
+function escapeMermaid(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+const CLASSES = [
+    '  classDef completed fill:#dcfce7,stroke:#16a34a,color:#14532d;',
+    '  classDef in_progress fill:#dbeafe,stroke:#2563eb,color:#1e3a8a;',
+    '  classDef eligible fill:#fef3c7,stroke:#d97706,color:#78350f;',
+    '  classDef blocked fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;'
+];
+const LINK_STYLES = {
+    completed: 'stroke:#16a34a,stroke-width:2px',
+    in_progress: 'stroke:#2563eb,stroke-width:3px',
+    eligible: 'stroke:#d97706,stroke-width:2px,stroke-dasharray:6 4',
+    blocked: 'stroke:#dc2626,stroke-width:2px,stroke-dasharray:2 3'
+};
+export function generateGraphMarkdown(backlogText) {
+    const { work_items: items } = typeof backlogText === 'string' ? parseBacklog(backlogText) : backlogText;
+    const ordered = topologicalOrder(items);
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const statuses = new Map(items.map((item) => [item.id, item.state ?? deriveExecutionStatus(item, byId).status]));
+    const edges = ordered.flatMap((source) => ordered
+        .filter((target) => target.depends_on.includes(source.id))
+        .map((target) => ({ source: source.id, target: target.id })));
+    const lines = [
+        '# Work-item dependency graph',
+        '',
+        '> Derived from canonical work-items. Do not edit this file manually.',
+        '',
+        '## Status',
+        '',
+        '- 🟩 **Completed** — accepted work.',
+        '- 🟦 **In Progress** — currently executing.',
+        '- 🟨 **Eligible** — pending work with dependencies and blockers satisfied.',
+        '- 🟥 **Blocked** — pending work with an incomplete dependency or unresolved blocker.',
+        '',
+        '```mermaid',
+        "%%{init: {'flowchart': {'curve': 'linear', 'nodeSpacing': 32, 'rankSpacing': 54}} }%%",
+        'flowchart TD'
+    ];
+    for (const item of ordered)
+        lines.push(`  ${item.id}["${escapeMermaid(item.id)}<br/>${escapeMermaid(item.title)}"]`);
+    lines.push('');
+    for (const edge of edges)
+        lines.push(`  ${edge.source} --> ${edge.target}`);
+    lines.push('');
+    edges.forEach((edge, index) => lines.push(`  linkStyle ${index} ${LINK_STYLES[statuses.get(edge.source)]};`));
+    lines.push('', ...CLASSES);
+    for (const status of ['completed', 'in_progress', 'eligible', 'blocked']) {
+        const ids = ordered.filter((item) => statuses.get(item.id) === status).map((item) => item.id);
+        if (ids.length)
+            lines.push(`  class ${ids.join(',')} ${status};`);
+    }
+    lines.push('```', '', 'Dependency arrows are authoritative for execution ordering. Flow executes one mutating task at a time; independent read-only research or review may run in parallel.', '');
+    return lines.join('\n');
+}
+export function writeGraph(root) {
+    const backlogPath = path.join(root, '_flow', 'backlog.yaml');
+    if (!fs.existsSync(backlogPath))
+        throw new ArtifactValidationError(`Backlog not found: ${backlogPath}`);
+    const graphPath = path.join(root, '_flow', 'docs', 'graph.md');
+    fs.mkdirSync(path.dirname(graphPath), { recursive: true });
+    const markdown = generateGraphMarkdown(fs.readFileSync(backlogPath, 'utf8'));
+    const temporaryPath = `${graphPath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporaryPath, markdown, 'utf8');
+    fs.renameSync(temporaryPath, graphPath);
+    return { graphPath, markdown };
+}
+export function runGraph({ args }) {
+    const result = writeGraph(projectRoot(args));
+    info(`Generated ${result.graphPath}`);
+}
+//# sourceMappingURL=graph.mjs.map

package/dist/commands/graph.mjs.map

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

package/dist/commands/init.d.mts

@@ -0,0 +1,6 @@
+export declare function runInit({ args, packageRoot, version }: {
+    args: any;
+    packageRoot: any;
+    version: any;
+}): Promise<void>;
+//# sourceMappingURL=init.d.mts.map

package/dist/commands/init.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.mts","sourceRoot":"","sources":["../../src/commands/init.mjs"],"names":[],"mappings":"AA4EA,wBAAsB,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE;;;;CAAA,iBA8C3D"}

package/dist/commands/init.mjs

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail, info, promptMultiSelect, promptSelect, promptText } from '../shared/cli-io.mjs';
+import { defaultConfig, readConfig, writeConfig } from '../shared/project-config.mjs';
+import { projectRoot, valueAfter } from '../shared/project-path.mjs';
+import { installRuntimeSkill } from '../shared/skill-installer.mjs';
+import { BROWNFIELD_POLICIES, ENGINEERING_PROFILES } from '../shared/profiles.mjs';
+import { FLOW_SCHEMA_VERSION, GATES_SCHEMA_VERSION } from '../domain/contracts.mjs';
+const RUNTIME_DEFINITIONS = {
+    codex: { label: 'Codex', skillsPath: '.codex/skills' },
+    claude: { label: 'Claude Code', skillsPath: '.claude/skills' }
+};
+function parseRuntimeFlag(args) {
+    const raw = valueAfter(args, '--runtime');
+    return raw
+        ? raw
+            .split(',')
+            .map((v) => v.trim().toLowerCase())
+            .filter(Boolean)
+        : null;
+}
+function missingBuiltinRuntimes(existing) {
+    const types = new Set(existing.map((r) => r.type));
+    return Object.keys(RUNTIME_DEFINITIONS).filter((type) => !types.has(type));
+}
+async function selectRuntimes(existing) {
+    const types = new Set(existing.map((r) => r.type));
+    const options = Object.entries(RUNTIME_DEFINITIONS)
+        .filter(([type]) => !types.has(type))
+        .map(([value, d]) => ({ value, label: d.label }));
+    options.push({ value: 'custom', label: 'Custom coding agent / skills path' });
+    return promptMultiSelect({
+        title: existing.length ? 'Select coding agents to add:' : 'Select coding agents:',
+        options
+    });
+}
+async function resolveRuntime(type, existing) {
+    if (RUNTIME_DEFINITIONS[type])
+        return { type, skills_path: RUNTIME_DEFINITIONS[type].skillsPath };
+    if (type !== 'custom')
+        fail(`unsupported runtime '${type}'. Use codex, claude, or custom.`);
+    const fallback = `custom-${existing.filter((r) => r.type.startsWith('custom')).length + 1}`;
+    const name = await promptText('Custom coding agent id', fallback);
+    while (true) {
+        const skillsPath = await promptText('Project-local skills directory', `.${name}/skills`);
+        if (!path.isAbsolute(skillsPath) && !skillsPath.split(/[\\/]/).includes('..'))
+            return { type: name, skills_path: skillsPath };
+        info('Skills path must be relative and remain inside the project.');
+    }
+}
+async function selectEngineering(args, root, config, existed) {
+    const profileFlag = valueAfter(args, '--profile');
+    const brownfieldFlag = valueAfter(args, '--existing-code');
+    if (args.includes('--brownfield'))
+        fail('Use --existing-code improve|preserve: improve recommends clearer structure; preserve keeps consistent conventions.');
+    if (existed && (profileFlag || brownfieldFlag))
+        fail('Change engineering through /flow and human approval, not init.');
+    if (profileFlag && !ENGINEERING_PROFILES[profileFlag])
+        fail(`unknown engineering profile '${profileFlag}'.`);
+    if (brownfieldFlag && !BROWNFIELD_POLICIES[brownfieldFlag])
+        fail(`unknown brownfield policy '${brownfieldFlag}'.`);
+    if (profileFlag)
+        config.engineering.profile = ENGINEERING_PROFILES[profileFlag].id;
+    const hasProjectFiles = fs
+        .readdirSync(root)
+        .some((name) => ['src', 'app', 'lib', 'packages'].includes(name) || /\.(m?[jt]sx?|py|java|go|rs|cs)$/.test(name));
+    if (brownfieldFlag)
+        config.engineering.existing_code_policy = brownfieldFlag;
+    else if (!existed && hasProjectFiles)
+        config.engineering.existing_code_policy = await promptSelect({
+            title: 'How should Flow treat existing code conventions?',
+            options: Object.entries(BROWNFIELD_POLICIES).map(([value, policy]) => ({
+                value,
+                label: policy.label,
+                description: policy.description
+            }))
+        });
+}
+export async function runInit({ args, packageRoot, version }) {
+    const root = projectRoot(args);
+    const flowDirectory = path.join(root, '_flow');
+    if (!fs.existsSync(flowDirectory) && fs.existsSync(path.join(root, '.flow')))
+        fail('Legacy .flow project requires flow migrate --plan and flow migrate --apply before init. No files were changed.');
+    const existed = fs.existsSync(flowDirectory);
+    const config = readConfig(root) || defaultConfig(version);
+    if (config.schema_version !== FLOW_SCHEMA_VERSION)
+        fail('Existing Flow project requires npx --no-install flow migrate before init. No files were changed.');
+    if (existed)
+        info('Flow project already exists. Canonical project artifacts will not be created or modified.');
+    await selectEngineering(args, root, config, existed);
+    const requested = parseRuntimeFlag(args);
+    if (existed && !requested && missingBuiltinRuntimes(config.runtimes).length === 0) {
+        writeConfig(root, config);
+        for (const runtime of config.runtimes)
+            installRuntimeSkill(root, runtime, packageRoot);
+        info('All built-in coding agents are already configured. Configuration is up to date.');
+        return;
+    }
+    const selected = requested || (await selectRuntimes(config.runtimes));
+    const known = new Set(config.runtimes.map((r) => r.type));
+    const added = [];
+    for (const type of selected) {
+        if (known.has(type))
+            continue;
+        const runtime = await resolveRuntime(type, config.runtimes);
+        if (known.has(runtime.type))
+            continue;
+        config.runtimes.push(runtime);
+        known.add(runtime.type);
+        added.push(runtime);
+    }
+    fs.mkdirSync(flowDirectory, { recursive: true });
+    config.flow_version = version;
+    writeConfig(root, config);
+    if (!existed) {
+        fs.writeFileSync(path.join(flowDirectory, 'gates.yaml'), `schema_version: ${GATES_SCHEMA_VERSION}\ngates: []\n`);
+        fs.mkdirSync(path.join(flowDirectory, 'work-items'), { recursive: true });
+        fs.mkdirSync(path.join(flowDirectory, 'generated'), { recursive: true });
+        fs.writeFileSync(path.join(flowDirectory, 'generated', '.gitignore'), '*\n!.gitignore\n');
+    }
+    for (const runtime of config.runtimes)
+        info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime, packageRoot))}`);
+    info(`Engineering profile: ${ENGINEERING_PROFILES[config.engineering.profile]?.label ?? config.engineering.profile}`);
+    info('Flow is ready. Invoke /flow; engineering bootstrap runs before implementation when no approved contract exists.');
+}
+//# sourceMappingURL=init.mjs.map

package/dist/commands/init.mjs.map

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

package/dist/commands/migrate.d.mts

@@ -0,0 +1,27 @@
+export declare function migrationPlan(root: any, targetVersion?: string): {
+    from_version: any;
+    to_version: string;
+    changes: string[];
+    files_affected: any[];
+    incompatibilities: string[];
+    invalidated_plans: string[];
+    affected_approvals: string[];
+    human_decisions: string[];
+    can_apply: boolean;
+};
+export declare function migrateProject(root: any, { targetVersion }?: {
+    targetVersion?: string | undefined;
+}): {
+    unresolved: never[];
+    unchanged: boolean;
+    backup?: never;
+} | {
+    unresolved: string[];
+    unchanged: boolean;
+    backup: any;
+};
+export declare function runMigrate({ args, version }: {
+    args: any;
+    version: any;
+}): void;
+//# sourceMappingURL=migrate.d.mts.map

package/dist/commands/migrate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.mts","sourceRoot":"","sources":["../../src/commands/migrate.mjs"],"names":[],"mappings":"AA0NA,wBAAgB,aAAa,CAAC,IAAI,KAAA,EAAE,aAAa,SAAU;;;;;;;;;;EA6D1D;AAwCD,wBAAgB,cAAc,CAAC,IAAI,KAAA,EAAE,EAAE,aAAuB,EAAE;;CAAK;;;;;;;;EAwCpE;AACD,wBAAgB,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;;;CAAA,QAgB3C"}

package/dist/commands/migrate.mjs

@@ -0,0 +1,379 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+import { info } from '../shared/cli-io.mjs';
+import { projectRoot } from '../shared/project-path.mjs';
+import { emptyState, stringifyState } from '../artifacts/state.mjs';
+import { parseBacklog } from '../artifacts/backlog.mjs';
+import { parseGates } from '../artifacts/gates.mjs';
+import { syncProject } from './sync.mjs';
+import { validateProject } from './validate.mjs';
+import { readConfig, writeConfig, defaultConfig } from '../shared/project-config.mjs';
+import { BACKLOG_SCHEMA_VERSION, FLOW_SCHEMA_VERSION, GATES_SCHEMA_VERSION, TASKS_SCHEMA_VERSION } from '../domain/contracts.mjs';
+const STATES = {
+    done: 'completed',
+    complete: 'completed',
+    completed: 'completed',
+    in_progress: 'in_progress',
+    blocked: 'pending',
+    pending: 'pending',
+    todo: 'pending'
+};
+function lifecycle(value) {
+    if (!STATES[value])
+        throw new Error(`Unknown legacy state '${value}'.`);
+    return STATES[value];
+}
+function number(value) {
+    const match = String(value).match(/\d+/);
+    if (!match)
+        throw new Error(`Cannot normalize ID '${value}'.`);
+    return match[0].padStart(3, '0');
+}
+function temporarySibling(file) {
+    const directory = path.dirname(file);
+    const base = path.basename(file);
+    let attempt = 0;
+    let temporary;
+    do {
+        temporary = path.join(directory, `.${base}_flow-migration-${process.pid}-${Date.now()}-${attempt++}`);
+    } while (fs.existsSync(temporary));
+    return temporary;
+}
+function sameEntry(from, to) {
+    return fs.realpathSync.native(from) === fs.realpathSync.native(to);
+}
+function move(from, to) {
+    if (!fs.existsSync(from))
+        return;
+    if (path.resolve(from) === path.resolve(to))
+        return;
+    if (fs.existsSync(to)) {
+        if (!sameEntry(from, to))
+            throw new Error(`Migration destination already exists: ${to}`);
+        const temporary = temporarySibling(from);
+        fs.renameSync(from, temporary);
+        try {
+            fs.renameSync(temporary, to);
+        }
+        catch (error) {
+            try {
+                fs.renameSync(temporary, from);
+            }
+            catch (recoveryError) {
+                error.preserveRecoveryData = true;
+                error.recovery = { from, to, temporary, recoveryError };
+            }
+            throw error;
+        }
+        return;
+    }
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(from, to);
+}
+function createCanonicalShell(base, item) {
+    fs.mkdirSync(base, { recursive: true });
+    fs.writeFileSync(path.join(base, 'spec.md'), `---\n${stringify({
+        schema_version: 1,
+        work_item: item.id,
+        title: item.title,
+        kind: item.kind,
+        priority: item.priority,
+        depends_on: item.depends_on,
+        blockers: [],
+        maturity: 'outlined'
+    }).trimEnd()}\n---\n\n# Work Item Specification\n`);
+    fs.writeFileSync(path.join(base, 'tasks.yaml'), stringify({ schema_version: TASKS_SCHEMA_VERSION, work_item: item.id, tasks: [] }, { lineWidth: 0 }));
+    fs.writeFileSync(path.join(base, 'implementation-plan.md'), `---\nschema_version: 1\nwork_item: ${item.id}\nstatus: draft\n---\n\n# Implementation Plan\n`);
+    fs.writeFileSync(path.join(base, 'review.yaml'), `schema_version: 1\nwork_item: ${item.id}\nstatus: pending\n`);
+}
+function migrateStaged(root) {
+    const flow = path.join(root, '_flow');
+    const oldConfig = readConfig(root);
+    const oldFile = path.join(flow, fs.existsSync(path.join(flow, 'BACKLOG.yaml')) ? 'BACKLOG.yaml' : 'backlog.yaml');
+    const raw = parse(fs.readFileSync(oldFile, 'utf8'));
+    const mapping = new Map();
+    const ids = new Set();
+    for (const item of raw.work_items ?? []) {
+        const id = `W${number(item.id)}`;
+        if (ids.has(id))
+            throw new Error(`Work-item ID collision: ${id}`);
+        ids.add(id);
+        mapping.set(item.id, id);
+    }
+    const original = new Map();
+    const work_items = (raw.work_items ?? []).map((item) => {
+        const id = mapping.get(item.id);
+        const folder = `${id}-${String(item.folder ?? item.title)
+            .replace(new RegExp(`^${id}-`, 'i'), '')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '') || 'work-item'}`;
+        original.set(id, item.folder);
+        return {
+            id,
+            folder,
+            title: item.title,
+            kind: item.kind,
+            state: lifecycle(item.state ?? item.status ?? 'pending'),
+            priority: item.priority ?? 1,
+            spec_maturity: 'ready',
+            depends_on: (item.depends_on ?? []).map((dep) => {
+                if (!mapping.has(dep))
+                    throw new Error(`Unknown work-item dependency '${dep}'.`);
+                return mapping.get(dep);
+            }),
+            blockers: []
+        };
+    });
+    const text = stringify({ schema_version: BACKLOG_SCHEMA_VERSION, work_items }, { lineWidth: 0 });
+    parseBacklog(text);
+    const workRoot = path.join(flow, 'work-items');
+    for (const item of work_items) {
+        const previous = path.join(workRoot, original.get(item.id) ?? item.folder);
+        const folder = path.join(workRoot, item.folder);
+        if (previous !== folder && fs.existsSync(previous))
+            move(previous, folder);
+        const archive = path.join(flow, 'docs', 'legacy-work-items', item.folder);
+        if (fs.existsSync(folder)) {
+            fs.mkdirSync(path.dirname(archive), { recursive: true });
+            fs.cpSync(folder, archive, { recursive: true });
+            fs.rmSync(folder, { recursive: true, force: true });
+        }
+        createCanonicalShell(folder, item);
+    }
+    fs.mkdirSync(path.join(flow, 'docs'), { recursive: true });
+    for (const [old, next] of [
+        ['PRD.md', 'prd.md'],
+        ['ENGINEERING.md', 'legacy-engineering.md'],
+        ['STATE.md', 'legacy-state.md'],
+        ['DECISIONS.md', 'legacy-decisions.md'],
+        ['SUMMARY.md', 'legacy-summary.md']
+    ])
+        move(path.join(flow, old), path.join(flow, 'docs', next));
+    if (fs.existsSync(path.join(flow, 'GRAPH.md')))
+        fs.unlinkSync(path.join(flow, 'GRAPH.md'));
+    if (fs.existsSync(oldFile))
+        move(oldFile, path.join(flow, 'docs', 'legacy-backlog.yaml'));
+    const state = emptyState();
+    state.execution.phase = 'reconcile';
+    state.execution.step = 'resolve_conflicts';
+    state.migration.status = 'pending_reconciliation';
+    fs.writeFileSync(path.join(flow, 'state.yaml'), stringifyState(state));
+    if (!fs.existsSync(path.join(flow, 'gates.yaml')))
+        fs.writeFileSync(path.join(flow, 'gates.yaml'), `schema_version: ${GATES_SCHEMA_VERSION}\ngates: []\n`);
+    const config = defaultConfig();
+    config.runtimes = oldConfig?.runtimes ?? [];
+    config.engineering.existing_code_policy = 'improve';
+    writeConfig(root, config);
+}
+function hasLegacyBacklog(flow) {
+    return fs.existsSync(path.join(flow, 'BACKLOG.yaml')) || fs.existsSync(path.join(flow, 'backlog.yaml'));
+}
+function inspectCurrent(root, targetVersion) {
+    const flow = path.join(root, '_flow');
+    const changes = [];
+    try {
+        const config = readConfig(root);
+        if (!config || config.schema_version !== FLOW_SCHEMA_VERSION || config.flow_version !== targetVersion)
+            changes.push('upgrade config.yaml');
+    }
+    catch {
+        changes.push('upgrade config.yaml');
+    }
+    const workItems = path.join(flow, 'work-items');
+    if (!fs.existsSync(workItems))
+        changes.push('restore work-items directory');
+    else
+        for (const entry of fs.readdirSync(workItems, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const tasks = path.join(workItems, entry.name, 'tasks.yaml');
+            if (!fs.existsSync(tasks)) {
+                changes.push(`restore work-items/${entry.name}/tasks.yaml`);
+                continue;
+            }
+            try {
+                const value = parse(fs.readFileSync(tasks, 'utf8')) ?? {};
+                if (value.schema_version !== TASKS_SCHEMA_VERSION ||
+                    (value.tasks ?? []).some((task) => ['traceability', 'implementation', 'commit_sha'].some((field) => Object.hasOwn(task, field))))
+                    changes.push(`upgrade work-items/${entry.name}/tasks.yaml`);
+            }
+            catch {
+                changes.push(`upgrade work-items/${entry.name}/tasks.yaml`);
+            }
+        }
+    try {
+        parseGates(fs.readFileSync(path.join(flow, 'gates.yaml'), 'utf8'));
+    }
+    catch {
+        changes.push('upgrade gates.yaml');
+    }
+    return [...new Set(changes)];
+}
+export function migrationPlan(root, targetVersion = '0.6.0') {
+    const currentFlow = path.join(root, '_flow');
+    const legacyFlow = path.join(root, '.flow');
+    if (fs.existsSync(currentFlow) && fs.existsSync(legacyFlow))
+        return {
+            from_version: 'ambiguous',
+            to_version: targetVersion,
+            changes: [],
+            files_affected: [],
+            incompatibilities: ['Both .flow and _flow exist; reconcile the authoritative directory first.'],
+            invalidated_plans: [],
+            affected_approvals: [],
+            human_decisions: ['Choose the authoritative Flow directory.'],
+            can_apply: false
+        };
+    const usesLegacyDirectory = !fs.existsSync(currentFlow) && fs.existsSync(legacyFlow);
+    const flow = usesLegacyDirectory ? legacyFlow : currentFlow;
+    if (!fs.existsSync(flow))
+        throw new Error('_flow does not exist.');
+    const rawConfigFile = path.join(flow, 'config.yaml');
+    const rawConfig = fs.existsSync(rawConfigFile) ? (parse(fs.readFileSync(rawConfigFile, 'utf8')) ?? {}) : {};
+    const config = usesLegacyDirectory
+        ? { flow_version: rawConfig.flow_version ?? rawConfig.framework?.version ?? null }
+        : readConfig(root);
+    const files = fs.readdirSync(flow);
+    const legacy = files.filter((name) => ['BACKLOG.yaml', 'PRD.md', 'ENGINEERING.md', 'STATE.md', 'DECISIONS.md', 'SUMMARY.md', 'GRAPH.md'].includes(name));
+    const changes = [];
+    const invalidatedPlans = [];
+    if (usesLegacyDirectory)
+        changes.push('rename the canonical project directory from .flow to _flow');
+    if (!config?.flow_version || config.flow_version !== targetVersion)
+        changes.push('record executed Flow package version');
+    if (legacy.length)
+        changes.push('normalize legacy artifact names and IDs');
+    if (!usesLegacyDirectory)
+        changes.push(...inspectCurrent(root, targetVersion));
+    const backlogFile = path.join(flow, 'backlog.yaml');
+    if (usesLegacyDirectory && fs.existsSync(backlogFile)) {
+        const backlog = parse(fs.readFileSync(backlogFile, 'utf8'));
+        backlog.schema_version = BACKLOG_SCHEMA_VERSION;
+        if ((backlog.work_items ?? []).some((item) => !item.spec_maturity))
+            changes.push('derive initial spec_maturity from existing artifacts');
+        for (const item of backlog.work_items ?? []) {
+            const planFile = path.join(flow, 'work-items', item.folder ?? '', 'implementation-plan.md');
+            if ((item.state ?? item.status) !== 'completed' && fs.existsSync(planFile))
+                invalidatedPlans.push(`${item.id}: work-items/${item.folder}/implementation-plan.md`);
+        }
+    }
+    const source = config?.flow_version ?? 'legacy';
+    const knownSource = source === 'legacy' || source === targetVersion || /^0\.[45]\./.test(source);
+    return {
+        from_version: source,
+        to_version: targetVersion,
+        changes,
+        files_affected: [...legacy, 'config.yaml', 'backlog.yaml', 'state.yaml', 'gates.yaml'],
+        incompatibilities: knownSource ? [] : [`Unknown source version '${source}'.`],
+        invalidated_plans: invalidatedPlans,
+        affected_approvals: invalidatedPlans,
+        human_decisions: changes.length
+            ? ['Reconcile preserved product, engineering, spec and traceability semantics before implementation.']
+            : [],
+        can_apply: knownSource
+    };
+}
+function upgradeCanonicalStaged(root, targetVersion) {
+    const flow = path.join(root, '_flow');
+    const workItems = path.join(flow, 'work-items');
+    if (fs.existsSync(workItems))
+        for (const entry of fs.readdirSync(workItems, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const taskPath = path.join(workItems, entry.name, 'tasks.yaml');
+            if (!fs.existsSync(taskPath))
+                continue;
+            const value = parse(fs.readFileSync(taskPath, 'utf8')) ?? {};
+            value.schema_version = TASKS_SCHEMA_VERSION;
+            for (const task of value.tasks ?? []) {
+                if (task.state === 'completed' && task.commit_sha) {
+                    task.legacy_commit ??= task.commit_sha;
+                    task.provenance = 'legacy_migration';
+                }
+                delete task.traceability;
+                delete task.implementation;
+                delete task.commit_sha;
+            }
+            fs.writeFileSync(taskPath, stringify(value, { lineWidth: 0 }));
+        }
+    const config = readConfig(root) ?? defaultConfig(targetVersion);
+    config.flow_version = targetVersion;
+    writeConfig(root, config);
+    const gatesFile = path.join(flow, 'gates.yaml');
+    if (!fs.existsSync(gatesFile))
+        fs.writeFileSync(gatesFile, `schema_version: ${GATES_SCHEMA_VERSION}\ngates: []\n`);
+    else {
+        const gates = parse(fs.readFileSync(gatesFile, 'utf8'));
+        gates.schema_version = GATES_SCHEMA_VERSION;
+        for (const gate of gates.gates ?? []) {
+            gate.stage ??= 'full';
+            gate.cost ??= 'medium';
+            gate.scope ??= {};
+        }
+        fs.writeFileSync(gatesFile, stringify(gates, { lineWidth: 0 }));
+    }
+}
+export function migrateProject(root, { targetVersion = '0.6.0' } = {}) {
+    const plan = migrationPlan(root, targetVersion);
+    if (!plan.can_apply)
+        throw new Error(plan.incompatibilities.join(' '));
+    const targetFlow = path.join(root, '_flow');
+    const legacyFlow = path.join(root, '.flow');
+    const sourceFlow = fs.existsSync(targetFlow) ? targetFlow : legacyFlow;
+    const usesLegacyDirectory = sourceFlow === legacyFlow;
+    if (!usesLegacyDirectory && plan.changes.length === 0)
+        return { unresolved: [], unchanged: true };
+    const staging = fs.mkdtempSync(path.join(root, '_flow-migration-'));
+    const backup = path.join(staging, 'backup');
+    const staged = path.join(staging, '_flow');
+    let preserveStaging = false;
+    try {
+        fs.cpSync(sourceFlow, staged, { recursive: true });
+        if (usesLegacyDirectory || hasLegacyBacklog(staged))
+            migrateStaged(staging);
+        else
+            upgradeCanonicalStaged(staging, targetVersion);
+        syncProject(staging);
+        const findings = validateProject(staging);
+        if (findings.length)
+            throw new Error(`Migration staging validation failed: ${findings.map((x) => x.code).join(', ')}.`);
+        fs.renameSync(sourceFlow, backup);
+        try {
+            fs.renameSync(staged, targetFlow);
+        }
+        catch (error) {
+            fs.renameSync(backup, sourceFlow);
+            throw error;
+        }
+        const backupRoot = path.join(root, '_flow-backups');
+        fs.mkdirSync(backupRoot, { recursive: true });
+        const backupTarget = path.join(backupRoot, `migration-${Date.now()}`);
+        fs.renameSync(backup, backupTarget);
+        return { unresolved: ['semantic reconciliation'], unchanged: false, backup: backupTarget };
+    }
+    catch (error) {
+        preserveStaging = Boolean(error?.preserveRecoveryData);
+        throw error;
+    }
+    finally {
+        // Retain the original backup if even rollback failed; never delete the only copy.
+        if (!preserveStaging && (!fs.existsSync(backup) || fs.existsSync(targetFlow) || fs.existsSync(sourceFlow)))
+            fs.rmSync(staging, { recursive: true, force: true });
+    }
+}
+export function runMigrate({ args, version }) {
+    const root = projectRoot(args);
+    if (args.includes('--plan')) {
+        const plan = migrationPlan(root, version);
+        return info(args.includes('--json')
+            ? JSON.stringify(plan, null, 2)
+            : `Migration ${plan.from_version} -> ${plan.to_version}\n${plan.changes.length ? plan.changes.map((change) => `- ${change}`).join('\n') : 'No structural changes required.'}`);
+    }
+    const result = migrateProject(root, { targetVersion: version });
+    info(result.unchanged
+        ? 'Already migrated; no files changed.'
+        : 'Structural migration complete. Invoke /flow for semantic reconciliation before implementation.');
+}
+//# sourceMappingURL=migrate.mjs.map