genesis-compiler 1.2.21 → 1.2.23

package/README.md

@@ -12,6 +12,7 @@ interaction.
 
 ```text
 genesis/
+  version            project-file format version used for deterministic migrations
   blueprint.md       non-technical product intent
   engineering.md     selected engineering profile and project-specific requirements
   stack.md           selected technology guidance, verification, declarations, and opaque extensions
@@ -106,7 +107,8 @@ type a command. It never runs adoption without approval and does nothing in an
 empty or already-adopted project.
 
 `genesis init` creates an empty Blueprint, a focused engineering approach, an
-empty optional Stack, three project Agent Skills, and project-local Codex hooks. The skills are ordinary
+empty optional Stack, the current `genesis/version`, three project Agent Skills,
+and project-local Codex hooks. The skills are ordinary
 [Agent Skills](https://agentskills.io): `genesis-project`, `genesis-program`,
 and `genesis-deslop`, each with standard `SKILL.md` and `agents/openai.yaml`
 metadata. Open `/hooks` once in Codex to review and trust the hooks. After
@@ -473,6 +475,8 @@ genesis check
 
 `check` is read-only. It reports only structural or recorded facts:
 
+- whether the project format is current, outdated, unversioned, newer than the
+  running CLI, or invalid;
 - Blueprint, engineering approach, and Stack validity;
 - selected Agent Skill presence and structural validity;
 - Program presence and structural validity;
@@ -491,6 +495,20 @@ hashes match. It does not mean that the product behavior makes sense. Generate
 Genesis does not label Program semantically current. Program is ordinary
 Markdown reviewed through Git.
 
+When `check` reports an outdated or unversioned project, migrate its Genesis
+files to the running CLI's project format:
+
+```bash
+genesis migrate
+```
+
+Migration is deterministic and forward-only. It updates only recognized
+Genesis formats, synchronizes managed skills and hooks, regenerates derived
+indexes, and then returns a fresh `check` result. A newer project is never
+downgraded. Every project-scoped CLI invocation warns when the recorded format
+does not match the running CLI, and ordinary project operations stop until the
+migration is resolved.
+
 ## Public API
 
 ```js
@@ -508,6 +526,7 @@ import {
   installCodex,
   listEngineeringProfiles,
   listStackPieces,
+  migrate,
   setEngineeringProfile,
   verify,
 } from 'genesis-compiler';
@@ -515,6 +534,8 @@ import {
 
 `initialize()` installs the project files, Genesis workflow skills, selected
 Stack skills, and local Codex hooks.
+`migrate()` updates recognized older Genesis project-file formats and returns
+the resulting structural check for hosts such as Vibe64.
 `adoptProject()` also returns the initial `adopt` prompt for an existing
 codebase. `installCodex()` installs the optional global discovery plugin.
 `listEngineeringProfiles()`, `inspectEngineering()`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.21",
+  "version": "1.2.23",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.2.21",
+  "version": "1.2.23",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/src/cli.js

@@ -15,6 +15,7 @@ import {
   installCodex,
   listEngineeringProfiles,
   listStackPieces,
+  migrate,
   setEngineeringProfile,
   verify,
 } from './index.js';
@@ -28,6 +29,10 @@ import {
 } from './index/codex-hooks.js';
 import { engineeringProfile, readEngineeringBaseline } from './index/engineering.js';
 import { asDiagnostic, fail } from './index/errors.js';
+import {
+  inspectProjectFormat,
+  projectFormatDiagnostic,
+} from './index/project-format.js';
 
 const USAGE = `Usage:
   genesis init
@@ -40,6 +45,7 @@ const USAGE = `Usage:
   genesis stack add <piece...>
   genesis context <path...>
   genesis index [function-or-path...]
+  genesis migrate
   genesis inspect environment
   genesis inspect section <name>
   genesis prompt [request...]
@@ -59,7 +65,7 @@ prompt to the agent you already use. Review all edits through the ordinary Git
 diff, then run genesis verify for the Stack's concrete checks.
 `;
 
-const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'prompt', 'stack', 'verify']);
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'engineering', 'hook', 'index', 'init', 'inspect', 'migrate', 'prompt', 'stack', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -151,6 +157,9 @@ function namedItems(label, values) {
 }
 
 function writeCheck(result) {
+  const format = result.projectFormat;
+  const version = format.projectVersion === null ? format.status : format.projectVersion;
+  line(process.stdout, `Project format: ${version} (${format.status}; CLI supports ${format.supportedVersion})`);
   line(process.stdout, `Blueprint: ${result.blueprint}`);
   line(process.stdout, `Engineering approach: ${result.engineering}`);
   line(process.stdout, `Stack: ${result.stack}`);
@@ -301,6 +310,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
   const projectRoot = options.projectRoot || process.cwd();
   const stackPackages = options.stackPackages || [];
   if (command === 'init') return initialize({ projectRoot, stackPackages });
+  if (command === 'migrate') return migrate({ projectRoot, stackPackages });
   if (command === 'adopt') {
     return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
   }
@@ -401,6 +411,34 @@ async function execute({ command, operands, options }, { signal } = {}) {
   fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
 }
 
+async function optionalProjectFormat(projectRoot) {
+  try {
+    return await inspectProjectFormat({ projectRoot });
+  } catch (error) {
+    if (error?.code === 'GIT_REPOSITORY_REQUIRED') return null;
+    throw error;
+  }
+}
+
+function requiresCurrentProjectFormat(command, operands) {
+  if (['check', 'codex', 'hook', 'migrate'].includes(command)) return false;
+  if (command === 'engineering') {
+    return operands[0] === 'set' || (operands[0] === 'show' && operands.length === 1);
+  }
+  return command !== 'help';
+}
+
+function withProjectFormatWarning(result, projectFormat, diagnostic) {
+  if (!diagnostic) return result;
+  const warnings = [...(result.warnings || [])];
+  if (!warnings.some((warning) => warning.code === diagnostic.code)) warnings.unshift(diagnostic);
+  return {
+    ...result,
+    projectFormat: result.projectFormat || projectFormat,
+    warnings,
+  };
+}
+
 export async function runCli(argv = process.argv.slice(2)) {
   let options = {};
   const controller = new AbortController();
@@ -412,12 +450,24 @@ export async function runCli(argv = process.argv.slice(2)) {
       return 0;
     }
     options = parsed.options;
+    const projectFormat = await optionalProjectFormat(options.projectRoot || process.cwd());
+    const formatDiagnostic = projectFormatDiagnostic(projectFormat);
+    if (formatDiagnostic && !options.json) {
+      line(process.stderr, `WARNING: ${formatDiagnostic.message}`);
+    }
+    if (formatDiagnostic && requiresCurrentProjectFormat(parsed.command, parsed.operands)) {
+      fail(formatDiagnostic.code, formatDiagnostic.message, formatDiagnostic.details);
+    }
     const finiteCommand = parsed.command === 'verify';
     if (finiteCommand) {
       process.once('SIGINT', abort);
       process.once('SIGTERM', abort);
     }
-    const result = await execute(parsed, { signal: controller.signal });
+    const result = withProjectFormatWarning(
+      await execute(parsed, { signal: controller.signal }),
+      projectFormat,
+      formatDiagnostic,
+    );
     if (options.json) line(process.stdout, JSON.stringify(result));
     else writeResult(parsed.command, result);
     return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;

package/src/index/check.js

@@ -9,10 +9,15 @@ import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { inspectProjectEnvironment } from './environment-files.js';
 import { readEngineering } from './engineering.js';
+import {
+  inspectProjectFormatAtRoot,
+  projectFormatDiagnostic,
+} from './project-format.js';
 
-function invalidResult(area, error) {
+function invalidResult(area, error, projectFormat) {
   return {
     status: 'invalid',
+    projectFormat,
     blueprint: area === 'blueprint' ? 'invalid' : 'valid',
     engineering: area === 'engineering' ? 'invalid' : 'unknown',
     stack: area === 'stack' ? 'invalid' : 'unknown',
@@ -29,16 +34,44 @@ function invalidResult(area, error) {
   };
 }
 
+function formatMismatchResult(projectFormat) {
+  const diagnostic = projectFormatDiagnostic(projectFormat);
+  const status = ['unversioned', 'outdated'].includes(projectFormat.status)
+    ? 'attention'
+    : projectFormat.status === 'newer' ? 'blocked' : 'invalid';
+  return {
+    status,
+    projectFormat,
+    blueprint: 'unknown',
+    engineering: 'unknown',
+    stack: 'unknown',
+    skills: 'unknown',
+    program: 'unknown',
+    environment: 'unknown',
+    extensions: 'unknown',
+    resources: 'unknown',
+    verification: 'unknown',
+    programFiles: [],
+    subsystems: [],
+    diagnostics: [diagnostic],
+    guidance: diagnostic.message,
+  };
+}
+
 export async function checkProject({
   environment = process.env,
   projectRoot,
   stackPackages = [],
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
+  const projectFormat = await inspectProjectFormatAtRoot(root);
+  if (!['current', 'uninitialized'].includes(projectFormat.status)) {
+    return formatMismatchResult(projectFormat);
+  }
   try {
     await readBlueprint(root, { required: true, requireDescription: true });
   } catch (error) {
-    return invalidResult('blueprint', error);
+    return invalidResult('blueprint', error, projectFormat);
   }
 
   let stack;
@@ -46,13 +79,13 @@ export async function checkProject({
   try {
     engineering = await readEngineering(root);
   } catch (error) {
-    return invalidResult('engineering', error);
+    return invalidResult('engineering', error, projectFormat);
   }
 
   try {
     stack = await readStack(root, { stackPackages });
   } catch (error) {
-    return invalidResult('stack', error);
+    return invalidResult('stack', error, projectFormat);
   }
 
   let program;
@@ -119,6 +152,7 @@ export async function checkProject({
     status: program.status === 'invalid' || skills.status === 'invalid' || verification.status === 'invalid'
       ? 'invalid'
       : needsAttention ? 'attention' : 'ok',
+    projectFormat,
     blueprint: 'valid',
     engineering: engineering.status,
     stack: 'valid',

package/src/index/codex-hooks.js

@@ -214,6 +214,13 @@ function zeroPaths(buffer) {
   return normalizedPaths(buffer.toString('utf8').split('\0'));
 }
 
+function projectPathStates(projectRoot, files) {
+  return Promise.all(files.map(async (file) => ({
+    path: file,
+    state: await pathState(path.join(projectRoot, file)),
+  })));
+}
+
 async function repositorySnapshot(projectRoot) {
   const head = await runGitText(projectRoot, ['rev-parse', '--verify', 'HEAD']).catch(() => null);
   const results = await Promise.all([
@@ -227,10 +234,7 @@ async function repositorySnapshot(projectRoot) {
     .sort();
   return {
     head,
-    dirty: await Promise.all(dirty.map(async (file) => ({
-      path: file,
-      state: await pathState(path.join(projectRoot, file)),
-    }))),
+    dirty: await projectPathStates(projectRoot, dirty),
   };
 }
 
@@ -423,19 +427,27 @@ function changedPathLines(changedPaths) {
 }
 
 function changedRepositoryLines(repositories) {
-  return repositories.flatMap(({ projectRoot, changedPaths }) => [
+  return repositories.flatMap(({ projectRoot, changedPaths, driftedPaths = [] }) => [
     `## Repository: \`${projectRoot}\``,
     '',
     ...changedPathLines(changedPaths),
+    ...(driftedPaths.length > 0 ? [
+      '',
+      '### Concurrent changes excluded from cleanup',
+      '',
+      'These paths changed after the implementation scope was frozen. Report them, but do not edit them:',
+      '',
+      ...changedPathLines(driftedPaths),
+    ] : []),
     '',
   ]);
 }
 
-async function changedRepositories(repositories) {
+async function changedRepositories(repositories, { snapshotField = 'snapshot' } = {}) {
   return (await Promise.all(repositories.map(async (repository) => {
     const currentPaths = await changedProjectPaths(
       repository.projectRoot,
-      repository.snapshot,
+      repository[snapshotField] || repository.snapshot,
       await repositorySnapshot(repository.projectRoot),
     );
     const changedPaths = normalizedPaths([
@@ -446,6 +458,47 @@ async function changedRepositories(repositories) {
   }))).filter(Boolean);
 }
 
+async function freezeChangedRepositories(repositories, { startPostChange = false } = {}) {
+  return Promise.all(repositories.map(async (repository) => {
+    const changedPaths = normalizedPaths(repository.changedPaths || []).sort();
+    const [pathStates, phaseSnapshot] = await Promise.all([
+      projectPathStates(repository.projectRoot, changedPaths),
+      startPostChange ? repositorySnapshot(repository.projectRoot) : null,
+    ]);
+    const frozen = {
+      ...repository,
+      changedPaths,
+      pathStates,
+    };
+    delete frozen.driftedPaths;
+    delete frozen.phaseSnapshot;
+    if (phaseSnapshot) frozen.phaseSnapshot = phaseSnapshot;
+    return frozen;
+  }));
+}
+
+async function cleanupScopeRepositories(repositories) {
+  return (await Promise.all(repositories.map(async (repository) => {
+    const ownedPaths = normalizedPaths(repository.changedPaths || []).sort();
+    if (ownedPaths.length === 0) return null;
+    const expected = new Map((repository.pathStates || [])
+      .map(({ path: file, state }) => [file, state]));
+    const changedPaths = [];
+    const driftedPaths = [];
+    for (const { path: file, state } of await projectPathStates(repository.projectRoot, ownedPaths)) {
+      const destination = expected.has(file) && stableJson(expected.get(file)) !== stableJson(state)
+        ? driftedPaths
+        : changedPaths;
+      destination.push(file);
+    }
+    return {
+      ...repository,
+      changedPaths,
+      driftedPaths,
+    };
+  }))).filter(Boolean);
+}
+
 async function repositoryContexts(repositories) {
   return Promise.all(repositories.map(async (repository) => {
     const [stack, engineering] = await Promise.all([
@@ -572,13 +625,14 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
       await removeTurnState(statePath, input);
       return {};
     }
-    const repositories = await changedRepositories(registeredRepositories(state, root));
-    if (repositories.length === 0) {
+    const changed = await changedRepositories(registeredRepositories(state, root));
+    if (changed.length === 0) {
       await removeTurnState(statePath, input);
       return {};
     }
-    const contexts = await repositoryContexts(repositories);
+    const contexts = await repositoryContexts(changed);
     const postChange = contexts.some(({ stack }) => Boolean(stack?.postChange?.trim()));
+    const repositories = await freezeChangedRepositories(changed, { startPostChange: postChange });
     await writeTurnState(statePath, {
       ...state,
       phase: postChange ? 'post-change' : 'reconcile',
@@ -598,11 +652,14 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
   }
 
   if (state.phase === 'post-change') {
-    const repositories = await changedRepositories(registeredRepositories(state, root));
-    if (repositories.length === 0) {
+    const changed = await changedRepositories(registeredRepositories(state, root), {
+      snapshotField: 'phaseSnapshot',
+    });
+    if (changed.length === 0) {
       await removeTurnState(statePath, input);
       return {};
     }
+    const repositories = await freezeChangedRepositories(changed);
     await writeTurnState(statePath, {
       ...state,
       phase: 'reconcile',
@@ -616,7 +673,7 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
 
   if (state.phase === 'reconcile') {
     const registered = registeredRepositories(state, root);
-    const repositories = await changedRepositories(registered);
+    const repositories = await cleanupScopeRepositories(registered);
     if (repositories.length === 0) {
       await refreshProjectIndexes(registered);
       await removeTurnState(statePath, input);

package/src/index/init.js

@@ -6,7 +6,18 @@ import { BLUEPRINT_SKELETON_SOURCE } from './blueprint.js';
 import { installCodexHooks } from './codex-hooks.js';
 import { ENGINEERING_SKELETON_SOURCE } from './engineering.js';
 import { gitContext } from './git.js';
-import { BLUEPRINT_PATH, ENGINEERING_PATH, PROGRAM_ROOT, STACK_PATH } from './paths.js';
+import {
+  BLUEPRINT_PATH,
+  ENGINEERING_PATH,
+  PROGRAM_ROOT,
+  PROJECT_VERSION_PATH,
+  STACK_PATH,
+} from './paths.js';
+import {
+  CURRENT_PROJECT_FORMAT_SOURCE,
+  inspectProjectFormatAtRoot,
+  requireCurrentProjectFormat,
+} from './project-format.js';
 import { EMPTY_STACK_SOURCE, readStack } from './stack.js';
 
 async function createIfMissing(projectRoot, relativePath, source) {
@@ -23,6 +34,8 @@ async function createIfMissing(projectRoot, relativePath, source) {
 
 export async function initializeProject({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
+  const projectFormat = await inspectProjectFormatAtRoot(root);
+  requireCurrentProjectFormat(projectFormat, { allowUninitialized: true });
   const created = (await Promise.all([
     createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
     createIfMissing(root, ENGINEERING_PATH, ENGINEERING_SKELETON_SOURCE),
@@ -32,7 +45,12 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
   const stack = await readStack(root, { stackPackages });
   const skills = await syncProjectSkills({ projectRoot: root, stack });
   const hooks = await installCodexHooks({ projectRoot: root });
-  const changedFiles = [...created, ...hooks.changedFiles, ...skills.changedFiles].sort();
+  const version = projectFormat.status === 'uninitialized'
+    ? await createIfMissing(root, PROJECT_VERSION_PATH, CURRENT_PROJECT_FORMAT_SOURCE)
+    : null;
+  const changedFiles = [...created, ...hooks.changedFiles, ...skills.changedFiles, version]
+    .filter(Boolean)
+    .sort();
   return {
     status: changedFiles.length > 0 ? 'updated' : 'unchanged',
     summary: changedFiles.length > 0

package/src/index/migration.js

@@ -0,0 +1,85 @@
+import { readBlueprint } from './blueprint.js';
+import { readEngineering } from './engineering.js';
+import { asDiagnostic, GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { initializeProject } from './init.js';
+import { inspectProgram } from './program.js';
+import {
+  CURRENT_PROJECT_FORMAT_VERSION,
+  inspectProjectFormatAtRoot,
+  projectFormatDiagnostic,
+  writeProjectFormatVersion,
+} from './project-format.js';
+import { PROJECT_VERSION_PATH } from './paths.js';
+import { readStack } from './stack.js';
+import { uniqueSorted } from './utils.js';
+
+async function validateLegacyProject({ projectRoot, stackPackages }) {
+  try {
+    await readBlueprint(projectRoot, { required: true });
+    await readEngineering(projectRoot);
+    await readStack(projectRoot, { stackPackages });
+    try {
+      await inspectProgram(projectRoot);
+    } catch (error) {
+      if (error?.code !== 'PROGRAM_SOURCE_MISSING') throw error;
+    }
+  } catch (error) {
+    throw new GenesisError(
+      'PROJECT_FORMAT_MIGRATION_UNAVAILABLE',
+      `Genesis cannot automatically migrate these legacy project files: ${error.message}`,
+      { cause: asDiagnostic(error) },
+    );
+  }
+}
+
+const MIGRATIONS = new Map([
+  [0, validateLegacyProject],
+]);
+
+export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const initial = await inspectProjectFormatAtRoot(root);
+  if (initial.status === 'uninitialized') {
+    throw new GenesisError(
+      'PROJECT_INITIALIZATION_REQUIRED',
+      'No Genesis project files exist. Run `genesis init` first.',
+    );
+  }
+  if (['invalid', 'newer'].includes(initial.status)) {
+    const diagnostic = projectFormatDiagnostic(initial);
+    throw new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+  }
+
+  let version = initial.status === 'unversioned' ? 0 : initial.projectVersion;
+  const migratedFiles = [];
+  while (version < CURRENT_PROJECT_FORMAT_VERSION) {
+    const migration = MIGRATIONS.get(version);
+    if (!migration) {
+      throw new GenesisError(
+        'PROJECT_FORMAT_MIGRATION_UNAVAILABLE',
+        `No migration from project format ${version} is installed.`,
+        { projectVersion: version, supportedVersion: CURRENT_PROJECT_FORMAT_VERSION },
+      );
+    }
+    await migration({ projectRoot: root, stackPackages });
+    version += 1;
+    await writeProjectFormatVersion(root, version);
+    migratedFiles.push(PROJECT_VERSION_PATH);
+  }
+
+  const initialized = await initializeProject({ projectRoot: root, stackPackages });
+  const changedFiles = uniqueSorted([...migratedFiles, ...initialized.changedFiles]);
+  const migrated = initial.status !== 'current';
+  return {
+    status: changedFiles.length > 0 ? 'updated' : 'unchanged',
+    summary: migrated
+      ? `Migrated Genesis project format from ${initial.status === 'unversioned' ? 'unversioned' : initial.projectVersion} to ${CURRENT_PROJECT_FORMAT_VERSION}.`
+      : `Genesis project format ${CURRENT_PROJECT_FORMAT_VERSION} is current.`,
+    fromVersion: initial.projectVersion,
+    toVersion: CURRENT_PROJECT_FORMAT_VERSION,
+    projectFormat: await inspectProjectFormatAtRoot(root),
+    changedFiles,
+    diagnostics: initialized.diagnostics,
+  };
+}

package/src/index/paths.js

@@ -2,6 +2,7 @@ export const BLUEPRINT_PATH = 'genesis/blueprint.md';
 export const ENGINEERING_PATH = 'genesis/engineering.md';
 export const STACK_PATH = 'genesis/stack.md';
 export const PROGRAM_ROOT = 'genesis/program';
+export const PROJECT_VERSION_PATH = 'genesis/version';
 export const VERIFICATION_PATH = '.genesis/verification.json';
 
 export function isProjectContentPath(file) {

package/src/index/project-format.js

@@ -0,0 +1,138 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { asDiagnostic, GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import {
+  BLUEPRINT_PATH,
+  ENGINEERING_PATH,
+  PROGRAM_ROOT,
+  PROJECT_VERSION_PATH,
+  STACK_PATH,
+} from './paths.js';
+import { normalizeSource, pathState, writeFileAtomic } from './utils.js';
+
+export const CURRENT_PROJECT_FORMAT_VERSION = 1;
+export const CURRENT_PROJECT_FORMAT_SOURCE = `${CURRENT_PROJECT_FORMAT_VERSION}\n`;
+
+const VERSION_PATTERN = /^(0|[1-9][0-9]*)\n?$/u;
+
+function projectFormat(status, projectVersion, action, diagnostic = null) {
+  return {
+    path: PROJECT_VERSION_PATH,
+    status,
+    projectVersion,
+    supportedVersion: CURRENT_PROJECT_FORMAT_VERSION,
+    action,
+    ...(diagnostic ? { diagnostic } : {}),
+  };
+}
+
+export function parseProjectFormatVersion(source) {
+  const normalized = normalizeSource(source);
+  const match = normalized.match(VERSION_PATTERN);
+  const version = match ? Number(match[1]) : NaN;
+  if (!Number.isSafeInteger(version)) {
+    throw new GenesisError(
+      'PROJECT_FORMAT_INVALID',
+      `${PROJECT_VERSION_PATH} must contain exactly one non-negative integer.`,
+      { path: PROJECT_VERSION_PATH },
+    );
+  }
+  return version;
+}
+
+async function hasGenesisSource(projectRoot) {
+  const states = await Promise.all([
+    BLUEPRINT_PATH,
+    ENGINEERING_PATH,
+    STACK_PATH,
+    PROGRAM_ROOT,
+  ].map((relative) => pathState(path.join(projectRoot, relative))));
+  return states.some(({ exists }) => exists);
+}
+
+export async function inspectProjectFormatAtRoot(projectRoot) {
+  let source;
+  try {
+    source = await readFile(path.join(projectRoot, PROJECT_VERSION_PATH), 'utf8');
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+      const genesisSource = await hasGenesisSource(projectRoot);
+      return projectFormat(
+        genesisSource ? 'unversioned' : 'uninitialized',
+        null,
+        genesisSource ? 'migrate' : 'init',
+      );
+    }
+    const diagnostic = asDiagnostic(new GenesisError(
+      'PROJECT_FORMAT_INVALID',
+      `${PROJECT_VERSION_PATH} could not be read: ${error.message}.`,
+      { path: PROJECT_VERSION_PATH, cause: error.code || error.message },
+    ));
+    return projectFormat('invalid', null, 'repair', diagnostic);
+  }
+
+  let version;
+  try {
+    version = parseProjectFormatVersion(source);
+  } catch (error) {
+    return projectFormat('invalid', null, 'repair', asDiagnostic(error));
+  }
+  if (version < CURRENT_PROJECT_FORMAT_VERSION) {
+    return projectFormat('outdated', version, 'migrate');
+  }
+  if (version > CURRENT_PROJECT_FORMAT_VERSION) {
+    return projectFormat('newer', version, 'update-genesis');
+  }
+  return projectFormat('current', version, null);
+}
+
+export async function inspectProjectFormat({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  return inspectProjectFormatAtRoot(root);
+}
+
+export function projectFormatDiagnostic(format) {
+  if (!format || ['current', 'uninitialized'].includes(format.status)) return null;
+  if (format.status === 'invalid') return format.diagnostic;
+  if (format.status === 'unversioned') {
+    return {
+      code: 'PROJECT_FORMAT_UNVERSIONED',
+      message: `Genesis project files are unversioned; this CLI uses project format ${format.supportedVersion}. Run \`genesis migrate\`.`,
+      details: { path: format.path, supportedVersion: format.supportedVersion },
+    };
+  }
+  if (format.status === 'outdated') {
+    return {
+      code: 'PROJECT_FORMAT_OUTDATED',
+      message: `Project format ${format.projectVersion} is older than this CLI's format ${format.supportedVersion}. Run \`genesis migrate\`.`,
+      details: {
+        path: format.path,
+        projectVersion: format.projectVersion,
+        supportedVersion: format.supportedVersion,
+      },
+    };
+  }
+  return {
+    code: 'PROJECT_FORMAT_NEWER',
+    message: `Project format ${format.projectVersion} is newer than this CLI's format ${format.supportedVersion}. Update Genesis before using this project.`,
+    details: {
+      path: format.path,
+      projectVersion: format.projectVersion,
+      supportedVersion: format.supportedVersion,
+    },
+  };
+}
+
+export function requireCurrentProjectFormat(format, { allowUninitialized = false } = {}) {
+  if (format.status === 'current' || (allowUninitialized && format.status === 'uninitialized')) return;
+  const diagnostic = projectFormatDiagnostic(format);
+  throw new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+}
+
+export function writeProjectFormatVersion(projectRoot, version) {
+  const source = `${version}\n`;
+  parseProjectFormatVersion(source);
+  return writeFileAtomic(path.join(projectRoot, PROJECT_VERSION_PATH), source);
+}

package/src/index.js

@@ -11,17 +11,19 @@ import {
   selectEngineeringProfile,
 } from './index/engineering.js';
 import { initializeProject } from './index/init.js';
+import { migrateProject } from './index/migration.js';
 import { installCodexPlugin } from './index/codex-plugin.js';
 import { inspectProjectEnvironment } from './index/environment-files.js';
 import { inspectProjectStackSection } from './index/stack-section-inspection.js';
 import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces, readStack } from './index/stack.js';
+import { uniqueSorted } from './index/utils.js';
 import { verifyProject } from './index/verification.js';
 
 export { GENESIS_CONTRACTS };
 
 function withIndexResult(result, index) {
-  const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
+  const changedFiles = uniqueSorted([...result.changedFiles, ...index.changedFiles]);
   const refreshedOnly = result.status === 'unchanged' && index.changedFiles.length > 0;
   return {
     ...result,
@@ -42,6 +44,20 @@ export function initialize({ projectRoot = process.cwd(), stackPackages = [] } =
   return initializeWithIndex(projectRoot, stackPackages);
 }
 
+export async function migrate({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  const migrated = await migrateProject({ projectRoot, stackPackages });
+  const index = await buildProjectIndex({ projectRoot, stackPackages });
+  const result = withIndexResult(migrated, index);
+  const checked = await checkProject({ projectRoot, stackPackages });
+  return {
+    ...result,
+    projectFormat: checked.projectFormat,
+    check: checked,
+    diagnostics: [...result.diagnostics, ...checked.diagnostics],
+    guidance: checked.guidance,
+  };
+}
+
 export async function adoptProject({
   projectRoot = process.cwd(),
   request = '',