Cap build-plan auto-fix terrain shifts

Author: aaronaalmendarez

README.md

@@ -435,6 +435,7 @@ Agents should not treat the build planner as a black box. The most important rul
 - The planner now returns structured `issues` identifying floating cuboids or block targets, their `gapBelow`, and a `suggestedY` to ground them correctly.
 - The planner only adds support pillars for real unsupported columns and caps auto-support at 24 columns.
 - If more than 80% of the lowest build columns are already within 2 blocks of solid ground and `autoFix=true`, the planner can auto-lower the whole build instead of spamming pillars.
+- Automatic Y correction is intentionally conservative and capped to small terrain fixes. It will not bury a build deep into the ground just because one mixed-terrain column reports a large gap.
 - `resolvedOrigin` in the result tells you the exact world origin that was actually used.
 - `autoFixAvailable` tells you whether the planner believes a safe grounding fix exists.
 

run-mcp-sidecar-node.js

@@ -1020,9 +1020,11 @@ function buildBuildPlanGuide() {
     "- It returns structured `issues` identifying which cuboids or block targets are floating, their `gapBelow`, and a `suggestedY` for grounding.",
     "- Only columns with real air/fluid gaps below them are considered for auto-support pillars.",
     "- If more than 80% of the lowest-layer columns are within 2 blocks of valid ground and `autoFix=true`, the planner can auto-lower the whole build instead of spamming pillars.",
+    "- Automatic Y correction is conservative. It only applies small grounding shifts and will not freefall a build deep into mixed terrain just because one column reports a large gap.",
     "- Auto-support pillars use `minecraft:stone_bricks` and are capped at 24 columns.",
     "- If there is no valid solid ground below some lowest columns at all, the planner rejects the build and tells the agent to lower the build or add a foundation.",
     "- Repeated retries with the same floating `y=0` plan are the wrong response. Fix the base Y, add a foundation phase, or use preview issues plus `suggestedY` to revise the plan.",
+    "- In practice, agents should treat `autoFix` as a small-terrain correction helper, not as permission to bury the structure until all issues disappear.",
     "",
     "Example issue payload:",
     "",

src/main/java/com/aaron/gemini/VoxelBuildPlanner.java

@@ -32,6 +32,7 @@ final class VoxelBuildPlanner {
 	private static final int MAX_SITE_SCAN_UP = 6;
 	private static final int MAX_SITE_SCAN_HEIGHT = 6;
 	private static final int MAX_AUTO_FOUNDATION_COLUMNS = 24;
+	private static final int MAX_AUTO_FIX_SHIFT = 3;
 	private static final String DEFAULT_FOUNDATION_BLOCK = "minecraft:stone_bricks";
 
 	private VoxelBuildPlanner() {
@@ -1421,31 +1422,27 @@ private static BuildPlan shiftPlanForIssues(BuildPlan plan, List<SupportIssue> i
 		if (plan == null || issues == null || issues.isEmpty()) {
 			return null;
 		}
-		Map<String, Integer> deltasByName = new LinkedHashMap<>();
-		for (SupportIssue issue : issues) {
-			if (issue == null || issue.cuboid() == null || issue.cuboid().isBlank() || issue.gapBelow() <= 0) {
-				continue;
-			}
-			deltasByName.put(issue.cuboid(), -issue.gapBelow());
-		}
-		if (deltasByName.isEmpty()) {
-			return null;
-		}
-		ShiftResult result = shiftPlanForIssuesRecursive(plan, deltasByName, repairs);
+		ShiftResult result = shiftPlanForIssuesRecursive(plan, issues, repairs);
 		return result.changed() ? result.plan() : null;
 	}
 
-	private static ShiftResult shiftPlanForIssuesRecursive(BuildPlan plan, Map<String, Integer> deltasByName, List<String> repairs) {
+	private static ShiftResult shiftPlanForIssuesRecursive(BuildPlan plan, List<SupportIssue> issues, List<String> repairs) {
 		List<Integer> directDeltas = new ArrayList<>();
+		Map<String, SupportIssue> issuesByName = new LinkedHashMap<>();
+		for (SupportIssue issue : issues) {
+			if (issue != null && issue.cuboid() != null && !issue.cuboid().isBlank()) {
+				issuesByName.put(issue.cuboid(), issue);
+			}
+		}
 		for (Cuboid cuboid : plan.cuboids()) {
-			Integer delta = deltasByName.get(cuboid.name());
-			if (delta != null && delta != 0) {
+			Integer delta = safeAutoFixDelta(issuesByName.get(cuboid.name()), Math.min(cuboid.from().y(), cuboid.to().y()));
+			if (delta != null) {
 				directDeltas.add(delta);
 			}
 		}
 		for (BlockPlacement block : plan.blocks()) {
-			Integer delta = deltasByName.get(block.name());
-			if (delta != null && delta != 0) {
+			Integer delta = safeAutoFixDelta(issuesByName.get(block.name()), block.pos().y());
+			if (delta != null) {
 				directDeltas.add(delta);
 			}
 		}
@@ -1458,7 +1455,7 @@ private static ShiftResult shiftPlanForIssuesRecursive(BuildPlan plan, Map<Strin
 		boolean changed = false;
 		List<BuildStep> shiftedSteps = new ArrayList<>();
 		for (BuildStep step : plan.steps()) {
-			ShiftResult result = shiftPlanForIssuesRecursive(step.plan(), deltasByName, repairs);
+			ShiftResult result = shiftPlanForIssuesRecursive(step.plan(), issues, repairs);
 			changed |= result.changed();
 			shiftedSteps.add(new BuildStep(step.phase(), result.plan()));
 		}
@@ -1492,6 +1489,20 @@ private static int chooseShiftDelta(List<Integer> deltas) {
 				.orElse(0);
 	}
 
+	private static Integer safeAutoFixDelta(SupportIssue issue, int currentY) {
+		if (issue == null || issue.suggestedY() <= 0) {
+			return null;
+		}
+		int delta = issue.suggestedY() - currentY;
+		if (delta == 0) {
+			return null;
+		}
+		if (Math.abs(delta) > MAX_AUTO_FIX_SHIFT) {
+			return null;
+		}
+		return delta;
+	}
+
 	private static BuildPlan shiftWholePlan(BuildPlan plan, int deltaY) {
 		if (plan == null || deltaY == 0) {
 			return plan;