@kontextmind/kxm 0.7.53 → 0.7.54

package/plugins/kxm/src/cli/project.ts

@@ -12,7 +12,6 @@ import {
   type KxmInitializationPlan,
 } from "../project-config.ts";
 import { initializeKxmProject } from "../init.ts";
-import { applyKxmMigration, planKxmMigration, verifyKxmMigration } from "../migrate.ts";
 import { diffKxmProjectAgainstRevision, formatKxmPermissionDiff } from "../permission.ts";
 import { readKxmLocalBindings, kxmUserStateRoot } from "../bindings.ts";
 import { loadKxmProject } from "../project-config.ts";
@@ -151,8 +150,8 @@ export async function cmdKxmInit(
     if (runtime.dryRun) {
       return finishInit(0, `init plan: ${initialized.plan.mode}`);
     }
-    const next = initialized.plan.mode === "migrate"
-      ? "legacy state requires reviewed migration; conversion is not available in this implementation slice"
+    const next = initialized.plan.mode === "legacy"
+      ? "legacy state is not migrated by this build: initialise a fresh project directory and copy the YAML definitions you want to keep"
       : initialized.repairPlan?.issues.length
         ? "managed-template repair is blocked by conflicts or authority changes; local files were preserved"
         : "partial or provenance-free KXM state requires explicit repair; no files were overwritten";
@@ -176,136 +175,6 @@ export async function cmdKxmInit(
   }
 }
 
-export async function cmdKxmMigratePlan(runtime: Runtime): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate plan",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  try {
-    const result = planKxmMigration(runtime.cwd, {});
-    const ambiguities = (result.plan.ambiguities as Array<{ key: string; message: string }> | undefined) ?? [];
-    const unmapped = (result.plan.unmapped as unknown[] | undefined) ?? [];
-    const payload = {
-      ok: result.plan.canApply === true,
-      command: "migrate plan",
-      plan: result.plan,
-      plannedOnly: result.plan.canApply !== true,
-    };
-    if (result.plan.canApply === true) {
-      print(runtime.io, runtime.json, payload, `migration plan: ${ambiguities.length} ambiguities, ${unmapped.length} preserved fields; ready to apply`);
-      return 0;
-    }
-    print(
-      runtime.io,
-      runtime.json,
-      payload,
-      `migration plan requires ${ambiguities.length} reviewed decision(s):\n${ambiguities.map((candidate) => `  - ${candidate.key}: ${candidate.message}`).join("\n")}`,
-    );
-    return 1;
-  } catch (error) {
-    if (error instanceof KxmConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate plan", error: "migration_plan_failed", issues: error.issues }, `migration plan failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate plan", error: "migration_plan_io_failed" }, "migration plan failed because a local filesystem operation did not complete");
-    return 1;
-  }
-}
-
-export async function cmdKxmMigrateApply(runtime: Runtime, options: { decisions?: string | undefined; projectId?: string | undefined; name?: string | undefined }): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate apply",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  try {
-    const result = applyKxmMigration(runtime.cwd, {
-      ...(options.decisions?.trim() ? { decisionsFile: options.decisions.trim() } : {}),
-      ...(options.projectId?.trim() ? { projectId: options.projectId.trim() } : {}),
-      ...(options.name?.trim() ? { projectName: options.name.trim() } : {}),
-      localStateRoot: kxmUserStateRoot({ env: runtime.env }),
-      dryRun: runtime.dryRun,
-    });
-    const payload = {
-      ok: result.action !== "planned" || (runtime.dryRun === true && result.plan?.canApply === true),
-      command: "migrate apply",
-      action: result.action,
-      files: result.files,
-      ...(result.configRevision ? { configRevision: result.configRevision } : {}),
-      ...(result.receiptPath ? { receiptPath: result.receiptPath } : {}),
-      plannedOnly: result.action === "planned",
-    };
-    if (result.action === "applied") {
-      print(runtime.io, runtime.json, payload, `migration applied: ${result.files.length} resources installed, receipt at ${result.receiptPath ?? ""}`);
-      return 0;
-    }
-    if (result.action === "already-migrated") {
-      print(runtime.io, runtime.json, payload, "migration receipt already exists; nothing to apply");
-      return 0;
-    }
-    if (runtime.dryRun && result.plan?.canApply === true) {
-      print(runtime.io, runtime.json, payload, `migration dry run: ${result.files.length} resources would be installed`);
-      return 0;
-    }
-    const ambiguities = (result.plan?.ambiguities as Array<{ key: string; message: string }> | undefined) ?? [];
-    print(
-      runtime.io,
-      runtime.json,
-      { ...payload, plan: result.plan },
-      `migration blocked by ${ambiguities.length} unresolved decision(s); review 'kxm migrate plan' and pass --decisions:\n${ambiguities.map((candidate) => `  - ${candidate.key}: ${candidate.message}`).join("\n")}`,
-    );
-    return 1;
-  } catch (error) {
-    if (error instanceof KxmConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate apply", error: "migration_apply_failed", issues: error.issues }, `migration apply failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate apply", error: "migration_apply_io_failed" }, "migration apply failed because a local filesystem operation did not complete");
-    return 1;
-  }
-}
-
-export async function cmdKxmMigrateVerify(runtime: Runtime): Promise<number> {
-  if (runtime.workspaceFlag !== undefined) {
-    print(runtime.io, runtime.json, {
-      ok: false,
-      command: "migrate verify",
-      error: "workspace_option_unsupported",
-    }, "kxm migrate discovers the authoritative Git root from the current directory; --workspace is not supported");
-    return 2;
-  }
-  let result: ReturnType<typeof verifyKxmMigration>;
-  try {
-    result = verifyKxmMigration(runtime.cwd, {});
-  } catch (error) {
-    if (error instanceof KxmConfigError) {
-      print(runtime.io, runtime.json, { ok: false, command: "migrate verify", error: "migration_verify_failed", issues: error.issues }, `migration verification failed: ${error.message}`);
-      return 1;
-    }
-    print(runtime.io, runtime.json, { ok: false, command: "migrate verify", error: "migration_verify_io_failed" }, "migration verification failed because a local filesystem operation did not complete");
-    return 1;
-  }
-  const payload = {
-    ok: result.ok,
-    command: "migrate verify",
-    ...(result.configRevision ? { configRevision: result.configRevision } : {}),
-    issues: result.issues,
-  };
-  if (result.ok) {
-    print(runtime.io, runtime.json, payload, `migration receipt verified: legacy sources unchanged, target bundle matches ${result.configRevision ?? ""}`);
-    return 0;
-  }
-  print(runtime.io, runtime.json, payload, `migration verification failed:\n${result.issues.map((issue) => `  - ${issue.file}: ${issue.code}: ${issue.message}`).join("\n")}`);
-  return 1;
-}
-
 export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined }): Promise<number> {
   try {
     const { manifest, outDir } = createBackup({

package/plugins/kxm/src/cli.ts

@@ -7,7 +7,7 @@
  * - Role & workflow governance (`kxm role`, `kxm workflow`, `kxm gate`, `kxm signal`)
  * - Task & goal management (`kxm goal`, `kxm task`, `kxm suggest`, `kxm studio`)
  * - Knowledge, skills, and memory (`kxm context`, `kxm skills`, `kxm memory`)
- * - KXM runtime & initialization (`kxm init`, `kxm migrate`, `kxm trust`, `kxm run`, `kxm harness`)
+ * - KXM runtime & initialization (`kxm init`, `kxm trust`, `kxm run`, `kxm harness`)
  * - Hub, workers, and dashboard (`kxm hub`, `kxm worker`, `kxm dash`, `kxm session`, `kxm auth`)
  * - System, update, and configuration (`kxm update`, `kxm config`, `kxm completion`, `kxm improve`)
  */
@@ -98,10 +98,7 @@ import {
 
 import {
   cmdKxmInit,
-  cmdKxmMigratePlan,
-  cmdKxmMigrateApply,
-  cmdKxmMigrateVerify,
-  cmdBackup,
+cmdBackup,
   cmdRestore,
   cmdKxmTrust,
   cmdKxmRun,
@@ -334,7 +331,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .helpCommand("help", "Show help");
   addGlobalOptions(program);
 
-  program.command("init").description("Create, validate, or plan migration of a KXM project")
+  program.command("init").description("Create, validate, repair, or join a KXM project")
     .option("--json", "Print machine-readable JSON")
     .option("--dry-run", "Plan without making changes")
     .option("--name <name>", "Project display name for a new project")
@@ -347,24 +344,6 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  const migrate = addGlobalOptions(program.command("migrate").description("Plan, apply, and verify legacy JSON configuration migration"));
-  migrate.helpCommand("help", "Show migrate help");
-  addGlobalOptions(migrate.command("plan").description("Compute the deterministic legacy-to-KXM migration plan without writes"))
-    .action(async function migratePlanAction(this: Command) {
-      result.code = await cmdKxmMigratePlan(runtimeFrom(ctx, this));
-    });
-  addGlobalOptions(migrate.command("apply").description("Install a reviewed migration with a hash-linked receipt"))
-    .option("--decisions <file>", "Reviewed kxm.migration-decision.v1 YAML file")
-    .option("--project-id <id>", "Stable project ID for controlled provisioning")
-    .option("--name <name>", "Project display name")
-    .action(async function migrateApplyAction(this: Command, options: { decisions?: string; projectId?: string; name?: string }) {
-      result.code = await cmdKxmMigrateApply(runtimeFrom(ctx, this), options);
-    });
-  addGlobalOptions(migrate.command("verify").description("Verify a migration receipt against current sources and target bundle"))
-    .action(async function migrateVerifyAction(this: Command) {
-      result.code = await cmdKxmMigrateVerify(runtimeFrom(ctx, this));
-    });
-
   addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of all stores with a hashed manifest"))
     .option("--out <dir>", "Directory to write backup and manifest")
     .action(async function backupAction(this: Command, options: { out?: string }) {

package/plugins/kxm/src/database.ts

@@ -179,7 +179,7 @@ export function openDatabase(file: string, description: string, spec: DatabaseSc
       throw databaseError(
         "runtime_schema_outdated",
         file,
-        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh — upgrading old state in place is deliberately unsupported`,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file to start fresh and let its owning process recreate it (\`kxm hub start\` for hub state, the Runtime for registry/event stores); \`kxm init\` is project-only and rebuilds no database — upgrading old state in place is deliberately unsupported`,
       );
     }
 

package/plugins/kxm/src/init.ts

@@ -207,9 +207,18 @@ function initializeKxmProjectAtGitRoot(
   const loaderOptions = configOptions(options, repositoryBindings);
   const transactionOptions = repairOptions(options, repositoryBindings);
 
+  const plan = planKxmInitialization(start, loaderOptions);
+  if (plan.mode === "legacy") {
+    // Classified **before** any transaction or lock work. A legacy tree used to reach the
+    // recovery branch first, so an interrupted create/repair journal made ordinary init
+    // acquire the project mutation lock, clean or resume the transaction, and write files
+    // while reporting `mode: "legacy"`. Nothing is resumed, cleaned, or written here: the
+    // pending journal stays exactly as it is until the legacy inputs are dealt with.
+    return { action: "planned", plan, ...(plan.projectRoot ? { projectRoot: plan.projectRoot } : {}), files: [] };
+  }
+
   if (hasKxmInitTransaction(gitRoot)) {
     const operation = inspectKxmInitTransaction(gitRoot, options.schemasDir);
-    const plan = planKxmInitialization(start, loaderOptions);
     if (!operation) {
       if (options.dryRun) return { action: "planned", plan, projectRoot: gitRoot, resumePending: true, files: [] };
       if (!mutationLock) throw new Error("project mutation lock is required to clean an empty transaction");
@@ -267,11 +276,6 @@ function initializeKxmProjectAtGitRoot(
     }
   }
 
-  const plan = planKxmInitialization(start, loaderOptions);
-  if (plan.mode === "migrate") {
-    return { action: "planned", plan, ...(plan.projectRoot ? { projectRoot: plan.projectRoot } : {}), files: [] };
-  }
-
   if (plan.mode === "repair") {
     const projectRoot = plan.projectRoot ?? gitRoot;
     let templateRepair: KxmTemplateRepairPlan | undefined;

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.53";
+const VERSION = "0.7.54";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/project-config.ts

@@ -58,7 +58,6 @@ export interface KxmProjectBundle {
   environments: readonly KxmResource[];
   gateRegistry?: KxmResource;
   templateProvenance?: JsonObject;
-  migrationReceipt?: JsonObject;
   resources: readonly KxmResource[];
   configRevision: string;
 }
@@ -69,11 +68,9 @@ export interface KxmConfigOptions {
   registeredExecutors?: Iterable<string>;
   registeredToolPresets?: Iterable<string>;
   registeredHarnesses?: Iterable<string>;
-  /** Internal: migration apply validates the staged target before the receipt exists. */
-  allowUnreceiptedLegacyConfig?: boolean;
 }
 
-export type KxmInitializationMode = "create" | "migrate" | "repair" | "ready";
+export type KxmInitializationMode = "create" | "legacy" | "repair" | "ready";
 
 export interface KxmInitializationPlan {
   mode: KxmInitializationMode;
@@ -161,9 +158,6 @@ export class KxmSchemaRegistry {
   readonly localBindingsValidator: ValidateFunction;
   readonly templateProvenanceValidator: ValidateFunction;
   readonly initOperationValidator: ValidateFunction;
-  readonly migrationPlanValidator: ValidateFunction;
-  readonly migrationDecisionValidator: ValidateFunction;
-  readonly migrationReceiptValidator: ValidateFunction;
   readonly permissionDiffValidator: ValidateFunction;
   readonly runEventValidator: ValidateFunction;
   readonly driveReceiptValidator: ValidateFunction;
@@ -181,9 +175,6 @@ export class KxmSchemaRegistry {
     const localBindingsFile = "local-repository-bindings.schema.json";
     const templateProvenanceFile = "template-provenance.schema.json";
     const initOperationFile = "init-operation.schema.json";
-    const migrationPlanFile = "migration-plan.schema.json";
-    const migrationDecisionFile = "migration-decision.schema.json";
-    const migrationReceiptFile = "migration-receipt.schema.json";
     const permissionDiffFile = "permission-diff.schema.json";
     const runEventFile = "run-event.schema.json";
     const driveReceiptFile = "drive-receipt.schema.json";
@@ -192,9 +183,6 @@ export class KxmSchemaRegistry {
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, localBindingsFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, templateProvenanceFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, initOperationFile)));
-    this.ajv.addSchema(readJsonObject(join(this.schemasDir, migrationPlanFile)));
-    this.ajv.addSchema(readJsonObject(join(this.schemasDir, migrationDecisionFile)));
-    this.ajv.addSchema(readJsonObject(join(this.schemasDir, migrationReceiptFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, permissionDiffFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, runEventFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, driveReceiptFile)));
@@ -208,9 +196,6 @@ export class KxmSchemaRegistry {
     const localBindingsValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${localBindingsFile}`);
     const templateProvenanceValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${templateProvenanceFile}`);
     const initOperationValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${initOperationFile}`);
-    const migrationPlanValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationPlanFile}`);
-    const migrationDecisionValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationDecisionFile}`);
-    const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${migrationReceiptFile}`);
     const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${permissionDiffFile}`);
     const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${runEventFile}`);
     const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/${driveReceiptFile}`);
@@ -219,9 +204,6 @@ export class KxmSchemaRegistry {
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
-    if (!migrationPlanValidator) throw new Error(`schema did not compile: ${migrationPlanFile}`);
-    if (!migrationDecisionValidator) throw new Error(`schema did not compile: ${migrationDecisionFile}`);
-    if (!migrationReceiptValidator) throw new Error(`schema did not compile: ${migrationReceiptFile}`);
     if (!permissionDiffValidator) throw new Error(`schema did not compile: ${permissionDiffFile}`);
     if (!runEventValidator) throw new Error(`schema did not compile: ${runEventFile}`);
     if (!driveReceiptValidator) throw new Error(`schema did not compile: ${driveReceiptFile}`);
@@ -230,9 +212,6 @@ export class KxmSchemaRegistry {
     this.localBindingsValidator = localBindingsValidator;
     this.templateProvenanceValidator = templateProvenanceValidator;
     this.initOperationValidator = initOperationValidator;
-    this.migrationPlanValidator = migrationPlanValidator;
-    this.migrationDecisionValidator = migrationDecisionValidator;
-    this.migrationReceiptValidator = migrationReceiptValidator;
     this.permissionDiffValidator = permissionDiffValidator;
     this.runEventValidator = runEventValidator;
     this.driveReceiptValidator = driveReceiptValidator;
@@ -263,18 +242,6 @@ export class KxmSchemaRegistry {
     return this.validateAuxiliary(value, file, "kxm.init-operation.v1", this.initOperationValidator);
   }
 
-  validateMigrationPlan(value: JsonObject, file: string): KxmConfigIssue[] {
-    return this.validateAuxiliary(value, file, "kxm.migration-plan.v1", this.migrationPlanValidator);
-  }
-
-  validateMigrationDecision(value: JsonObject, file: string): KxmConfigIssue[] {
-    return this.validateAuxiliary(value, file, "kxm.migration-decision.v1", this.migrationDecisionValidator);
-  }
-
-  validateMigrationReceipt(value: JsonObject, file: string): KxmConfigIssue[] {
-    return this.validateAuxiliary(value, file, "kxm.migration-receipt.v1", this.migrationReceiptValidator);
-  }
-
   validatePermissionDiff(value: JsonObject, file: string): KxmConfigIssue[] {
     return this.validateAuxiliary(value, file, "kxm.permission-diff.v1", this.permissionDiffValidator);
   }
@@ -1279,11 +1246,17 @@ export function assertNoRegisteredGates(options: object): void {
 export function loadKxmProject(projectRoot: string, options: KxmConfigOptions = {}): KxmProjectBundle {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
-  let migrationReceipt: JsonObject | undefined;
-  if (legacyConfigFilesAt(root).length > 0 && options.allowUnreceiptedLegacyConfig !== true) {
-    const receiptCheck = readKxmMigrationReceipt(root, options);
-    if (receiptCheck.issues.length > 0) throw new KxmConfigError(receiptCheck.issues);
-    migrationReceipt = receiptCheck.receipt;
+  const legacyPresent = legacyConfigFilesAt(root);
+  if (legacyPresent.length > 0) {
+    // Nothing can unlock this any more. The migration path was deleted under the
+    // single-operator decision, so a tree still holding legacy JSON fails closed here
+    // rather than being loadable on proof of a past conversion.
+    throw new KxmConfigError(legacyPresent.map((file) => issue(
+      "semantic",
+      "legacy_state_unsupported",
+      file,
+      "legacy JSON configuration is present and this build does not migrate it: delete these files once their YAML replacements exist in .kxm/, or initialise a fresh project",
+    )));
   }
   const registry = new KxmSchemaRegistry(options.schemasDir);
   const project = readResource(registry, root, join(root, ".kxm", "project.yaml"), ".kxm/project.yaml", "project");
@@ -1296,9 +1269,6 @@ export function loadKxmProject(projectRoot: string, options: KxmConfigOptions =
       earlyIssues.push(issue("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  if (migrationReceipt && stringValue(migrationReceipt.projectId) !== stringValue(project.value.id)) {
-    earlyIssues.push(issue("semantic", "migration_project_mismatch", KXM_MIGRATION_RECEIPT_PATH, "migration receipt belongs to a different project identity"));
-  }
   const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories")
     .map((candidate) => stringValue(objectValue(candidate)?.id))
     .filter((candidate): candidate is string => candidate !== undefined));
@@ -1383,6 +1353,18 @@ export function loadKxmProject(projectRoot: string, options: KxmConfigOptions =
         continue;
       }
     }
+    // A member worktree is authoritative for its own repo.yaml/env.yaml, so the legacy
+    // refusal has to cover it too — checking only the control root let a member full of
+    // legacy JSON load normally. Throws before a single byte of that member is read.
+    const memberLegacy = binding === root ? [] : legacyConfigFilesAt(binding);
+    if (memberLegacy.length > 0) {
+      throw new KxmConfigError(memberLegacy.map((file) => issue(
+        "semantic",
+        "legacy_state_unsupported",
+        `${repositoryId}/${file}`,
+        `repository ${repositoryId} holds legacy JSON configuration and this build does not migrate it: delete those files once their YAML replacements exist, or bind a clean worktree`,
+      )));
+    }
     const foldedBinding = canonicalHostPath(binding).toLocaleLowerCase("en-US");
     const priorBinding = seenBindings.get(foldedBinding);
     if (priorBinding && priorBinding !== repositoryId) {
@@ -1434,64 +1416,12 @@ export function loadKxmProject(projectRoot: string, options: KxmConfigOptions =
     environments,
     ...(gateRegistry ? { gateRegistry } : {}),
     ...(templateProvenance === undefined ? {} : { templateProvenance }),
-    ...(migrationReceipt === undefined ? {} : { migrationReceipt }),
     resources,
     configRevision: bundleRevision(resources),
   };
 }
 
-/**
- * Fully verify a migration receipt against the loaded target bundle: target
- * revision and per-resource bytes. Load-time coexistence only pins the
- * legacy sources; this stricter check backs `kxm migrate verify`.
- */
-export function verifyKxmMigrationReceiptTarget(
-  root: string,
-  receipt: JsonObject,
-  resources: readonly KxmResource[],
-  configRevision: string,
-): KxmConfigIssue[] {
-  const issues: KxmConfigIssue[] = [];
-  if (receipt.configRevision !== configRevision) {
-    issues.push(issue("semantic", "migration_target_changed", KXM_MIGRATION_RECEIPT_PATH, "target configuration revision no longer matches the migration receipt"));
-  }
-  const declared = new Map<string, JsonObject>();
-  for (const candidate of Array.isArray(receipt.resources) ? receipt.resources : []) {
-    if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
-      const record = candidate as JsonObject;
-      if (typeof record.path === "string") declared.set(record.path, record);
-    }
-  }
-  const installedPaths = new Set<string>();
-  for (const resource of resources) {
-    // Repository resources are loaded from their bound worktree paths; only
-    // control-tree files participate in receipt byte checks.
-    const relative = resource.file.startsWith(root) ? relativePortable(root, resource.file) : undefined;
-    if (!relative) continue;
-    installedPaths.add(relative);
-    const record = declared.get(relative);
-    if (!record) {
-      issues.push(issue("semantic", "migration_target_unreceipted", relative, "installed resource is not covered by the migration receipt"));
-      continue;
-    }
-    const current = hashFileRecord(root, relative);
-    if (!current || current.sha256 !== record.sha256 || current.bytes !== record.bytes) {
-      issues.push(issue("semantic", "migration_target_modified", relative, "installed resource bytes differ from the migration receipt"));
-    }
-  }
-  for (const path of declared.keys()) {
-    if (!installedPaths.has(path)) {
-      issues.push(issue("semantic", "migration_target_missing", path, "receipt-covered resource is not part of the validated configuration"));
-    }
-  }
-  return sortIssues(issues);
-}
 
-function relativePortable(root: string, absolute: string): string | undefined {
-  const rel = relative(root, absolute);
-  if (!rel || isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) return undefined;
-  return rel.split(sep).join("/");
-}
 
 function legacyInputsAt(root: string): string[] {
   const candidates = [
@@ -1503,7 +1433,6 @@ function legacyInputsAt(root: string): string[] {
   return candidates.filter((candidate) => existsSync(join(root, ...candidate.split("/"))));
 }
 
-export const KXM_MIGRATION_RECEIPT_PATH = ".kxm/migration-receipt.yaml";
 const LEGACY_CONFIG_FILES = [".kxm/config/agents.json", ".kxm/config/gates.json"] as const;
 
 /** Individual legacy configuration files (not directories, not runtime state) that a migration receipt must cover. */
@@ -1540,83 +1469,9 @@ export function legacyConfigFilesAt(root: string): string[] {
   return files;
 }
 
-export interface KxmMigrationReceiptCheck {
-  receipt?: JsonObject;
-  issues: KxmConfigIssue[];
-}
 
-function hashFileRecord(root: string, relativePath: string): { path: string; sha256: string; bytes: number } | undefined {
-  const absolute = join(root, ...relativePath.split("/"));
-  if (!existsSync(absolute)) return undefined;
-  const bytes = readFileSync(absolute);
-  return {
-    path: relativePath,
-    sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
-    bytes: bytes.byteLength,
-  };
-}
 
-export function migrationReceiptSelfHash(receipt: JsonObject): string {
-  const { receiptSha256: _ignored, ...unsigned } = receipt;
-  return `sha256:${createHash("sha256").update(kxmCanonicalJson(unsigned as JsonObject), "utf8").digest("hex")}`;
-}
 
-/**
- * Read and structurally verify a migration receipt: schema, self-hash, and
- * exact coverage of the legacy configuration files still present. Does not
- * compare the target configuration revision (computed by the caller).
- */
-export function readKxmMigrationReceipt(root: string, options: KxmConfigOptions = {}): KxmMigrationReceiptCheck {
-  const receiptPath = join(root, ...KXM_MIGRATION_RECEIPT_PATH.split("/"));
-  const legacyFiles = legacyConfigFilesAt(root);
-  if (!existsSync(receiptPath)) {
-    return {
-      issues: legacyFiles.map((file) => issue("semantic", "legacy_kxm_conflict", file, "legacy and KXM configuration cannot coexist before an accepted migration receipt")),
-    };
-  }
-  const receiptStat = lstatSync(receiptPath);
-  if (receiptStat.isSymbolicLink() || !receiptStat.isFile()) {
-    return { issues: [issue("path", "migration_receipt_invalid", KXM_MIGRATION_RECEIPT_PATH, "migration receipt must be a regular file, not a link")] };
-  }
-  let receipt: JsonObject;
-  try {
-    receipt = parseRestrictedYaml(readFileSync(receiptPath), KXM_MIGRATION_RECEIPT_PATH);
-  } catch (error) {
-    if (error instanceof KxmConfigError) return { issues: [...error.issues] };
-    throw error;
-  }
-  const registry = new KxmSchemaRegistry(options.schemasDir);
-  const schemaIssues = registry.validateMigrationReceipt(receipt, KXM_MIGRATION_RECEIPT_PATH);
-  if (schemaIssues.length > 0) return { issues: schemaIssues };
-  if (receipt.receiptSha256 !== migrationReceiptSelfHash(receipt)) {
-    return { issues: [issue("semantic", "migration_receipt_hash_mismatch", KXM_MIGRATION_RECEIPT_PATH, "receipt self-hash does not match its content")] };
-  }
-  const sources = (Array.isArray(receipt.sources) ? receipt.sources : [])
-    .map((candidate) => (candidate && typeof candidate === "object" && !Array.isArray(candidate) ? (candidate as JsonObject).path : undefined))
-    .filter((candidate): candidate is string => typeof candidate === "string")
-    .sort(compareCodeUnits);
-  const issues: KxmConfigIssue[] = [];
-  const declared = new Set(sources);
-  for (const file of legacyFiles) {
-    if (!declared.has(file)) {
-      issues.push(issue("semantic", "migration_source_unmigrated", file, "legacy configuration file is not covered by the migration receipt"));
-      continue;
-    }
-    const record = (Array.isArray(receipt.sources) ? receipt.sources : [])
-      .map((candidate) => (candidate && typeof candidate === "object" && !Array.isArray(candidate) ? candidate as JsonObject : undefined))
-      .find((candidate) => candidate?.path === file);
-    const current = hashFileRecord(root, file);
-    if (!current || current.sha256 !== record?.sha256 || current.bytes !== record?.bytes) {
-      issues.push(issue("semantic", "migration_source_changed", file, "legacy configuration changed after the migration receipt was issued"));
-    }
-  }
-  for (const file of sources) {
-    if (!legacyFiles.includes(file)) {
-      issues.push(issue("semantic", "migration_source_missing", file, "receipt covers a legacy configuration file that no longer exists"));
-    }
-  }
-  return issues.length > 0 ? { issues } : { receipt, issues: [] };
-}
 
 function discoverLegacyRoot(start: string): { root: string; inputs: string[] } | undefined {
   let initial = resolve(start);
@@ -1628,7 +1483,11 @@ function discoverLegacyRoot(start: string): { root: string; inputs: string[] } |
   return inputs.length > 0 ? { root: candidate, inputs } : undefined;
 }
 
-/** Classify init without changing files. Applying create/repair/migration is a separate, explicit operation. */
+/**
+ * Classify init without changing files. Applying create/repair is a separate, explicit
+ * operation; a legacy-only tree is **reported and never written** — this build carries no
+ * migration path, so init says what to do instead of doing it.
+ */
 export function planKxmInitialization(start = process.cwd(), options: KxmConfigOptions = {}): KxmInitializationPlan {
   const inspectedFrom = resolve(start);
   const projectRoot = discoverKxmProjectRoot(inspectedFrom);
@@ -1638,16 +1497,38 @@ export function planKxmInitialization(start = process.cwd(), options: KxmConfigO
       return { mode: "ready", inspectedFrom, projectRoot, changesRequired: false, issues: [], legacyInputs: [], configRevision: bundle.configRevision };
     } catch (error) {
       if (!(error instanceof KxmConfigError)) throw error;
+      const legacyIssues = error.issues.filter((candidate) => candidate.code === "legacy_state_unsupported");
       const legacyInputs = legacyInputsAt(projectRoot);
-      if (legacyInputs.length > 0) {
-        return { mode: "migrate", inspectedFrom, projectRoot, legacyRoot: projectRoot, changesRequired: true, issues: error.issues, legacyInputs };
+      if (legacyInputs.length > 0 || legacyIssues.length > 0) {
+        // Terminal for **any** legacy input, including one that lives in a bound member
+        // worktree. Classifying a member's legacy JSON as `repair` let init take the
+        // mutation lock and resume an interrupted create/repair journal, installing
+        // resources into a tree the loader had just refused.
+        return {
+          mode: "legacy",
+          inspectedFrom,
+          projectRoot,
+          legacyRoot: projectRoot,
+          changesRequired: true,
+          issues: [...error.issues, ...(legacyInputs.length > 0
+            ? [issue("discovery", "legacy_state_unsupported", ".kxm", "legacy configuration is present and this build does not migrate it: initialise a fresh project directory and carry over the YAML definitions you want to keep")]
+            : [])],
+          legacyInputs: [...new Set([...legacyInputs, ...legacyIssues.map((candidate) => candidate.file)])],
+        };
       }
       return { mode: "repair", inspectedFrom, projectRoot, changesRequired: true, issues: error.issues, legacyInputs: [] };
     }
   }
   const legacy = discoverLegacyRoot(inspectedFrom);
   if (legacy) {
-    return { mode: "migrate", inspectedFrom, legacyRoot: legacy.root, changesRequired: true, issues: [], legacyInputs: legacy.inputs };
+    return {
+      mode: "legacy",
+      inspectedFrom,
+      legacyRoot: legacy.root,
+      changesRequired: true,
+      issues: [issue("discovery", "legacy_state_unsupported", legacy.root, "legacy KXM/Mesh configuration discovered; this build does not migrate it — initialise a fresh project directory and copy the YAML definitions you want to keep")],
+      legacyInputs: legacy.inputs,
+    };
   }
   const gitRoot = discoverGitRoot(inspectedFrom);
   const candidateRoot = gitRoot ?? inspectedFrom;

package/schemas/README.md

@@ -14,9 +14,6 @@ Runtime-local records, and JSON events/results for the planned KXM contract.
 | `template-provenance.schema.json` | `kxm.template-provenance.v1` |
 | `local-repository-bindings.schema.json` | `kxm.local-repository-bindings.v1` |
 | `init-operation.schema.json` | `kxm.init-operation.v1` |
-| `migration-plan.schema.json` | `kxm.migration-plan.v1` |
-| `migration-decision.schema.json` | `kxm.migration-decision.v1` |
-| `migration-receipt.schema.json` | `kxm.migration-receipt.v1` |
 | `permission-diff.schema.json` | `kxm.permission-diff.v1` |
 | `run-event.schema.json` | `kxm.run-event.v1` |
 | `coordinator.schema.json` | `kxm.coordinator.v1` |