diff --git a/packages/core/src/migrate/client.ts b/packages/core/src/migrate/client.ts
index f59235a1c2..1c7b8cea27 100644
--- a/packages/core/src/migrate/client.ts
+++ b/packages/core/src/migrate/client.ts
@@ -109,6 +109,13 @@ export class LaunchQLMigrate {
     }
   }
 
+  /**
+   * Resolve toChange parameter, handling tag resolution if needed
+   */
+  private resolveToChange(toChange: string | undefined, planPath: string, project: string): string | undefined {
+    return toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, project) : toChange;
+  }
+
   /**
    * Deploy changes according to plan file
    */
@@ -118,7 +125,7 @@ export class LaunchQLMigrate {
     const { modulePath, toChange, useTransaction = true, debug = false, logOnly = false } = options;
     const planPath = join(modulePath, 'launchql.plan');
     const plan = parsePlanFileSimple(planPath);
-    const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange;
+    const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project);
     const changes = getChangesInOrder(planPath);
     
     const fullPlanResult = parsePlanFile(planPath);
@@ -266,7 +273,7 @@ export class LaunchQLMigrate {
     const { modulePath, toChange, useTransaction = true } = options;
     const planPath = join(modulePath, 'launchql.plan');
     const plan = parsePlanFileSimple(planPath);
-    const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange;
+    const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project);
     const changes = getChangesInOrder(planPath, true); // Reverse order for revert
     
     const reverted: string[] = [];
@@ -341,7 +348,7 @@ export class LaunchQLMigrate {
     const { modulePath, toChange } = options;
     const planPath = join(modulePath, 'launchql.plan');
     const plan = parsePlanFileSimple(planPath);
-    const resolvedToChange = toChange && toChange.includes('@') ? resolveTagToChangeName(planPath, toChange, plan.project) : toChange;
+    const resolvedToChange = this.resolveToChange(toChange, planPath, plan.project);
     const changes = getChangesInOrder(planPath);
     
     const verified: string[] = [];
diff --git a/packages/core/src/migrate/types.ts b/packages/core/src/migrate/types.ts
index 566efa4c87..0146a22c9e 100644
--- a/packages/core/src/migrate/types.ts
+++ b/packages/core/src/migrate/types.ts
@@ -16,6 +16,10 @@ export interface MigratePlanFile {
 
 export interface DeployOptions {
   modulePath: string;
+  /** 
+   * Target change name or tag (e.g., "changeName" or "@tagName").
+   * Note: Project name is already resolved upstream by LaunchQLProject.
+   */
   toChange?: string;
   useTransaction?: boolean;
   // Add debug mode for enhanced error reporting
@@ -25,6 +29,10 @@ export interface DeployOptions {
 
 export interface RevertOptions {
   modulePath: string;
+  /** 
+   * Target change name or tag (e.g., "changeName" or "@tagName").
+   * Note: Project name is already resolved upstream by LaunchQLProject.
+   */
   toChange?: string;
   useTransaction?: boolean;
   // Add debug mode for enhanced error reporting
@@ -33,6 +41,10 @@ export interface RevertOptions {
 
 export interface VerifyOptions {
   modulePath: string;
+  /** 
+   * Target change name or tag (e.g., "changeName" or "@tagName").
+   * Note: Project name is already resolved upstream by LaunchQLProject.
+   */
   toChange?: string;
 }