Dev: Auto-clean TypeScript types when switching branches

.gitignore

@@ -12,6 +12,7 @@ coverage
 .phpunit.result.cache
 .reassure
 .dev-ready
+.dev-head
 
 
 # Directories/files that may appear in your environment

bin/dev.mjs

@@ -110,6 +110,45 @@ const readyMarkerFile = {
 	},
 };
 
+/**
+ * Track the git HEAD to detect branch switches.
+ * Stale TypeScript declaration files from a previous branch cause build
+ * errors, so we clean them automatically when the HEAD changes.
+ */
+const headTracker = {
+	markerPath: path.join( ROOT_DIR, '.dev-head' ),
+	getCurrentHead() {
+		try {
+			return fs
+				.readFileSync( path.join( ROOT_DIR, '.git', 'HEAD' ), 'utf8' )
+				.trim();
+		} catch {
+			return null;
+		}
+	},
+	hasChanged() {
+		const currentHead = this.getCurrentHead();
+		if ( ! currentHead ) {
+			return false;
+		}
+		try {
+			const previousHead = fs
+				.readFileSync( this.markerPath, 'utf8' )
+				.trim();
+			return currentHead !== previousHead;
+		} catch {
+			// No marker file means first run — no need to clean.
+			return false;
+		}
+	},
+	save() {
+		const currentHead = this.getCurrentHead();
+		if ( currentHead ) {
+			fs.writeFileSync( this.markerPath, currentHead );
+		}
+	},
+};
+
 /**
  * Main dev orchestration function.
  */
@@ -126,6 +165,17 @@ async function dev() {
 		console.log( '🧹 Cleaning packages...' );
 		await exec( 'npm', [ 'run', 'clean:packages' ], { silent: true } );
 
+		// Step 1.5: Clean TypeScript types if git HEAD changed (e.g. branch switch).
+		// Stale build-types from a previous branch cause compilation errors.
+		if ( headTracker.hasChanged() ) {
+			console.log(
+				'\n🔄 Branch change detected — cleaning TypeScript types...'
+			);
+			await exec( 'npm', [ 'run', 'clean:package-types' ], {
+				silent: true,
+			} );
+		}
+
 		// Step 2: Build workspaces
 		console.log( '\n📦 Building workspaces...' );
 		await exec(
@@ -156,6 +206,9 @@ async function dev() {
 			throw new Error( 'TypeScript compilation failed' );
 		} );
 
+		// Save current HEAD so next run can detect branch switches.
+		headTracker.save();
+
 		// Step 5: Check build type declaration files
 		console.log( '\n✅ Checking type declaration files...' );
 		await exec( 'node', [