feat(FN-4108): persist scope override fields (+4 more)

Commits merged: - test(FN-4073): finalize invariant regression coverage - feat(FN-4073): complete Step 4 — document merge invariant - feat(FN-4073): complete Step 3 — enforce squash file-scope invariant - feat(FN-4073): complete Step 2 — add file-scope invariant helper - feat(FN-4073): complete Step 1 — persist scope override fields Files changed: .changeset/FN-4073-file-scope-invariant.md | 9 + AGENTS.md | 6 + packages/core/src/__tests__/store-update.test.ts | 18 ++ packages/core/src/db.ts | 2 + packages/core/src/store.ts | 34 +- packages/core/src/types.ts | 8 + .../__tests__/merger-file-scope-invariant.test.ts | 357 +++++++++++++++++++++ .../engine/src/__tests__/merger-test-helpers.ts | 5 + packages/engine/src/merger.ts | 155 ++++++++- 9 files changed, 582 insertions(+), 12 deletions(-) Fusion-Task-Id: FN-4108
2026-05-12 21:49:28 -07:00
parent ac59d5c71d
commit ad45a236fa
9 changed files with 582 additions and 12 deletions
--- a/.changeset/FN-4073-file-scope-invariant.md
+++ b/.changeset/FN-4073-file-scope-invariant.md
@@ -0,0 +1,9 @@
+---
+"@runfusion/fusion": patch
+---
+
+Merger now refuses to land a squash whose staged diff has zero overlap with the
+task's declared `## File Scope`. Tasks can opt out by setting
+`task.scopeOverride = true` (with optional `task.scopeOverrideReason`).
+Violating squashes leave the task in `in-review` with a structured agent-log
+entry instead of silently shipping out-of-scope changes.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -223,6 +223,12 @@ After any squash that auto-resolved conflicts, the merger now runs the post-squa

 Before those auto-resolved squash commits are written, the merger also runs a per-file diff-volume gate: it compares each file's staged squash delta against the branch's net delta vs its merge-base, and blocks the merge in `in-review` when a non-allowlisted file loses too much branch volume. This is the pre-commit guard against FN-3936-style silent drops where fallback resolution kept a branch's commit message but discarded the branch's main file edits.

+### File-Scope invariant on squash merges
+
+Every squash commit path now enforces a file-scope invariant immediately before writing the commit: the staged file set must overlap the task's declared `## File Scope` from `PROMPT.md`. The invariant runs on the standard squash path, the Attempt 3 `-X ours/theirs` fallback, and the verification-fix rebuild/finalize path. When the staged files have zero overlap with a non-empty declared scope, the merger throws a structured `FileScopeViolationError`, logs the declared scope + staged files to the merger agent log, resets the pre-squash state, and leaves the task in `in-review` for inspection instead of landing the commit.
+
+Tasks can opt out per task via `task.scopeOverride = true`; when present, the merger bypasses the invariant and logs `task.scopeOverrideReason` when provided. Empty declared file scopes are not enforced.
+
 When `mergeConflictStrategy="smart-prefer-main"`, the merger also runs an overlap guard before the Attempt 3 `-X ours` fallback. If recent `main` commits (30-commit lookback) touched files the task branch also changed, the default `mergeStrategyOverlapBehavior="flip-to-prefer-branch"` makes those overlapping files prefer the task branch instead of silently discarding branch hardening; `warn-only` preserves the legacy fallback while logging the risk, and `ignore` disables the guard.

 For manual follow-up, standalone auditing, or post-incident inspection, the script remains available:
--- a/packages/core/src/tests/store-update.test.ts
+++ b/packages/core/src/tests/store-update.test.ts
@@ -199,6 +199,24 @@ describe("TaskStore", () => {
  });


+  describe("updateTask — scope override", () => {
+    it("persists scopeOverride and scopeOverrideReason via updateTask", async () => {
+      const task = await store.createTask({ title: "Scope override task", description: "A task" });
+
+      const updated = await store.updateTask(task.id, {
+        scopeOverride: true,
+        scopeOverrideReason: "hotfix",
+      });
+
+      expect(updated.scopeOverride).toBe(true);
+      expect(updated.scopeOverrideReason).toBe("hotfix");
+
+      const fetched = await store.getTask(task.id);
+      expect(fetched.scopeOverride).toBe(true);
+      expect(fetched.scopeOverrideReason).toBe("hotfix");
+    });
+  });
+
  describe("updateTask — assigneeUserId", () => {
    it("sets assigneeUserId via updateTask", async () => {
      const task = await store.createTask({ title: "User task", description: "A task" });
--- a/packages/core/src/db.ts
+++ b/packages/core/src/db.ts
@@ -250,6 +250,8 @@ CREATE TABLE IF NOT EXISTS tasks (
  modifiedFiles TEXT DEFAULT '[]',
  missionId TEXT,
  sliceId TEXT,
+  scopeOverride INTEGER,
+  scopeOverrideReason TEXT,
  assignedAgentId TEXT,
  pausedByAgentId TEXT,
  assigneeUserId TEXT,
--- a/packages/core/src/store.ts
+++ b/packages/core/src/store.ts
@@ -113,6 +113,8 @@ interface TaskRow {
  modifiedFiles: string | null;
  missionId: string | null;
  sliceId: string | null;
+  scopeOverride: number | null;
+  scopeOverrideReason: string | null;
  assignedAgentId: string | null;
  pausedByAgentId: string | null;
  assigneeUserId: string | null;
@@ -876,6 +878,8 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      executionStartBranch: row.executionStartBranch || undefined,
      branch: row.branch || undefined,
      baseCommitSha: row.baseCommitSha || undefined,
+      scopeOverride: row.scopeOverride ? true : undefined,
+      scopeOverrideReason: row.scopeOverrideReason || undefined,
      modelPresetId: row.modelPresetId || undefined,
      modelProvider: row.modelProvider || undefined,
      modelId: row.modelId || undefined,
@@ -1230,7 +1234,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      "dependencies", "steps", "comments", "review", "reviewState", "workflowStepResults", "steeringComments",
      "attachments", "prInfo", "issueInfo", "githubTracking", "sourceIssueProvider", "sourceIssueRepository", "sourceIssueExternalIssueId", "sourceIssueNumber", "sourceIssueUrl", "mergeDetails",
      "breakIntoSubtasks", "enabledWorkflowSteps", "modifiedFiles",
-      "missionId", "sliceId", "assignedAgentId", "pausedByAgentId", "assigneeUserId", "nodeId", "effectiveNodeId", "effectiveNodeSource",
+      "missionId", "sliceId", "scopeOverride", "scopeOverrideReason", "assignedAgentId", "pausedByAgentId", "assigneeUserId", "nodeId", "effectiveNodeId", "effectiveNodeSource",
      "sourceType", "sourceAgentId", "sourceRunId", "sourceSessionId", "sourceMessageId", "sourceParentTaskId", "sourceMetadata",
      "checkedOutBy", "checkedOutAt", "checkoutNodeId", "checkoutRunId", "checkoutLeaseRenewedAt", "checkoutLeaseEpoch",
      // `log` is fetched in slim mode so the server can aggregate
@@ -1279,7 +1283,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      "dependencies", "steps", "attachments", "steeringComments",
      "comments", "review", "reviewState", "workflowStepResults", "prInfo", "issueInfo", "githubTracking", "sourceIssueProvider", "sourceIssueRepository", "sourceIssueExternalIssueId", "sourceIssueNumber", "sourceIssueUrl", "mergeDetails",
      "breakIntoSubtasks", "enabledWorkflowSteps", "modifiedFiles",
-      "missionId", "sliceId", "assignedAgentId", "pausedByAgentId", "assigneeUserId", "nodeId", "effectiveNodeId", "effectiveNodeSource",
+      "missionId", "sliceId", "scopeOverride", "scopeOverrideReason", "assignedAgentId", "pausedByAgentId", "assigneeUserId", "nodeId", "effectiveNodeId", "effectiveNodeSource",
      "sourceType", "sourceAgentId", "sourceRunId", "sourceSessionId", "sourceMessageId", "sourceParentTaskId", "sourceMetadata",
      "checkedOutBy", "checkedOutAt", "checkoutNodeId", "checkoutRunId", "checkoutLeaseRenewedAt", "checkoutLeaseEpoch",
    ];
@@ -1379,6 +1383,8 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      toJson(task.modifiedFiles || []),
      task.missionId ?? null,
      task.sliceId ?? null,
+      task.scopeOverride ? 1 : null,
+      task.scopeOverrideReason ?? null,
      task.assignedAgentId ?? null,
      task.pausedByAgentId ?? null,
      task.assigneeUserId ?? null,
@@ -1418,9 +1424,9 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
        dependencies, steps, log, attachments, steeringComments,
        comments, review, reviewState, workflowStepResults, prInfo, issueInfo, githubTracking,
        sourceIssueProvider, sourceIssueRepository, sourceIssueExternalIssueId, sourceIssueNumber, sourceIssueUrl,
-        mergeDetails, breakIntoSubtasks, enabledWorkflowSteps, modifiedFiles, missionId, sliceId, assignedAgentId, pausedByAgentId, assigneeUserId, nodeId, effectiveNodeId, effectiveNodeSource, sourceType, sourceAgentId, sourceRunId, sourceSessionId, sourceMessageId, sourceParentTaskId, sourceMetadata, checkedOutBy, checkedOutAt, checkoutNodeId, checkoutRunId, checkoutLeaseRenewedAt, checkoutLeaseEpoch
+        mergeDetails, breakIntoSubtasks, enabledWorkflowSteps, modifiedFiles, missionId, sliceId, scopeOverride, scopeOverrideReason, assignedAgentId, pausedByAgentId, assigneeUserId, nodeId, effectiveNodeId, effectiveNodeSource, sourceType, sourceAgentId, sourceRunId, sourceSessionId, sourceMessageId, sourceParentTaskId, sourceMetadata, checkedOutBy, checkedOutAt, checkoutNodeId, checkoutRunId, checkoutLeaseRenewedAt, checkoutLeaseEpoch
      ) VALUES (
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
      )
    `).run(...this.getTaskPersistValues(task));
    this.db.bumpLastModified();
@@ -1443,9 +1449,9 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
        dependencies, steps, log, attachments, steeringComments,
        comments, review, reviewState, workflowStepResults, prInfo, issueInfo, githubTracking,
        sourceIssueProvider, sourceIssueRepository, sourceIssueExternalIssueId, sourceIssueNumber, sourceIssueUrl,
-        mergeDetails, breakIntoSubtasks, enabledWorkflowSteps, modifiedFiles, missionId, sliceId, assignedAgentId, pausedByAgentId, assigneeUserId, nodeId, effectiveNodeId, effectiveNodeSource, sourceType, sourceAgentId, sourceRunId, sourceSessionId, sourceMessageId, sourceParentTaskId, sourceMetadata, checkedOutBy, checkedOutAt, checkoutNodeId, checkoutRunId, checkoutLeaseRenewedAt, checkoutLeaseEpoch
+        mergeDetails, breakIntoSubtasks, enabledWorkflowSteps, modifiedFiles, missionId, sliceId, scopeOverride, scopeOverrideReason, assignedAgentId, pausedByAgentId, assigneeUserId, nodeId, effectiveNodeId, effectiveNodeSource, sourceType, sourceAgentId, sourceRunId, sourceSessionId, sourceMessageId, sourceParentTaskId, sourceMetadata, checkedOutBy, checkedOutAt, checkoutNodeId, checkoutRunId, checkoutLeaseRenewedAt, checkoutLeaseEpoch
      ) VALUES (
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
      )
      ON CONFLICT(id) DO UPDATE SET
        lineageId = excluded.lineageId,
@@ -1518,6 +1524,8 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
        modifiedFiles = excluded.modifiedFiles,
        missionId = excluded.missionId,
        sliceId = excluded.sliceId,
+        scopeOverride = excluded.scopeOverride,
+        scopeOverrideReason = excluded.scopeOverrideReason,
        assignedAgentId = excluded.assignedAgentId,
        pausedByAgentId = excluded.pausedByAgentId,
        assigneeUserId = excluded.assigneeUserId,
@@ -2800,6 +2808,8 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      modelPresetId: input.modelPresetId,
      assignedAgentId: input.assignedAgentId,
      assigneeUserId: input.assigneeUserId,
+      scopeOverride: input.scopeOverride === true ? true : undefined,
+      scopeOverrideReason: input.scopeOverrideReason,
      nodeId: input.nodeId,
      modelProvider: input.modelProvider,
      modelId: input.modelId,
@@ -3644,7 +3654,7 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {

  async updateTask(
    id: string,
-    updates: { title?: string; description?: string; priority?: TaskPriority | null; prompt?: string; worktree?: string | null; status?: string | null; dependencies?: string[]; steps?: import("./types.js").TaskStep[]; currentStep?: number; blockedBy?: string | null; assignedAgentId?: string | null; pausedByAgentId?: string | null; assigneeUserId?: string | null; nodeId?: string | null; effectiveNodeId?: string | null; effectiveNodeSource?: string | null; checkedOutBy?: string | null; checkedOutAt?: string | null; checkoutNodeId?: string | null; checkoutRunId?: string | null; checkoutLeaseRenewedAt?: string | null; checkoutLeaseEpoch?: number | null; paused?: boolean; baseBranch?: string | null; branch?: string | null; executionStartBranch?: string | null; baseCommitSha?: string | null; size?: "S" | "M" | "L"; reviewLevel?: number; executionMode?: import("./types.js").ExecutionMode | null; mergeRetries?: number; workflowStepRetries?: number; stuckKillCount?: number | null; postReviewFixCount?: number | null; recoveryRetryCount?: number | null; taskDoneRetryCount?: number | null; verificationFailureCount?: number | null; mergeConflictBounceCount?: number | null; nextRecoveryAt?: string | null; enabledWorkflowSteps?: string[]; modelProvider?: string | null; modelId?: string | null; validatorModelProvider?: string | null; validatorModelId?: string | null; planningModelProvider?: string | null; planningModelId?: string | null; thinkingLevel?: string | null; error?: string | null; summary?: string | null; sessionFile?: string | null; executionStartedAt?: string | null; executionCompletedAt?: string | null; review?: import("./types.js").TaskReview | null; reviewState?: import("./types.js").TaskReviewState | null; workflowStepResults?: import("./types.js").WorkflowStepResult[] | null; mergeDetails?: import("./types.js").MergeDetails | null; sourceIssue?: import("./types.js").TaskSourceIssue | null; githubTracking?: import("./types.js").TaskGithubTracking | null; tokenUsage?: import("./types.js").TaskTokenUsage | null; modifiedFiles?: string[] | null; missionId?: string | null; sliceId?: string | null },
+    updates: { title?: string; description?: string; priority?: TaskPriority | null; prompt?: string; worktree?: string | null; status?: string | null; dependencies?: string[]; steps?: import("./types.js").TaskStep[]; currentStep?: number; blockedBy?: string | null; assignedAgentId?: string | null; pausedByAgentId?: string | null; assigneeUserId?: string | null; scopeOverride?: boolean | null; scopeOverrideReason?: string | null; nodeId?: string | null; effectiveNodeId?: string | null; effectiveNodeSource?: string | null; checkedOutBy?: string | null; checkedOutAt?: string | null; checkoutNodeId?: string | null; checkoutRunId?: string | null; checkoutLeaseRenewedAt?: string | null; checkoutLeaseEpoch?: number | null; paused?: boolean; baseBranch?: string | null; branch?: string | null; executionStartBranch?: string | null; baseCommitSha?: string | null; size?: "S" | "M" | "L"; reviewLevel?: number; executionMode?: import("./types.js").ExecutionMode | null; mergeRetries?: number; workflowStepRetries?: number; stuckKillCount?: number | null; postReviewFixCount?: number | null; recoveryRetryCount?: number | null; taskDoneRetryCount?: number | null; verificationFailureCount?: number | null; mergeConflictBounceCount?: number | null; nextRecoveryAt?: string | null; enabledWorkflowSteps?: string[]; modelProvider?: string | null; modelId?: string | null; validatorModelProvider?: string | null; validatorModelId?: string | null; planningModelProvider?: string | null; planningModelId?: string | null; thinkingLevel?: string | null; error?: string | null; summary?: string | null; sessionFile?: string | null; executionStartedAt?: string | null; executionCompletedAt?: string | null; review?: import("./types.js").TaskReview | null; reviewState?: import("./types.js").TaskReviewState | null; workflowStepResults?: import("./types.js").WorkflowStepResult[] | null; mergeDetails?: import("./types.js").MergeDetails | null; sourceIssue?: import("./types.js").TaskSourceIssue | null; githubTracking?: import("./types.js").TaskGithubTracking | null; tokenUsage?: import("./types.js").TaskTokenUsage | null; modifiedFiles?: string[] | null; missionId?: string | null; sliceId?: string | null },
    runContext?: RunMutationContext,
  ): Promise<Task> {
    return this.withTaskLock(id, async () => {
@@ -3777,6 +3787,16 @@ export class TaskStore extends EventEmitter<TaskStoreEvents> {
      } else if (updates.assigneeUserId !== undefined) {
        task.assigneeUserId = updates.assigneeUserId;
      }
+      if (updates.scopeOverride === null) {
+        task.scopeOverride = undefined;
+      } else if (updates.scopeOverride !== undefined) {
+        task.scopeOverride = updates.scopeOverride || undefined;
+      }
+      if (updates.scopeOverrideReason === null) {
+        task.scopeOverrideReason = undefined;
+      } else if (updates.scopeOverrideReason !== undefined) {
+        task.scopeOverrideReason = updates.scopeOverrideReason;
+      }
      if (updates.nodeId === null) {
        task.nodeId = undefined;
      } else if (updates.nodeId !== undefined) {
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -1162,6 +1162,10 @@ export interface Task {
  baseCommitSha?: string;
  /** List of files modified by this task (populated during execution) */
  modifiedFiles?: string[];
+  /** Opt out of the squash file-scope invariant for this task. */
+  scopeOverride?: boolean;
+  /** Optional justification for bypassing the squash file-scope invariant. */
+  scopeOverrideReason?: string;
  /** Mission ID this task is linked to (for mission hierarchy) */
  missionId?: string;
  /** Slice ID this task is linked to (for mission hierarchy) */
@@ -1415,6 +1419,10 @@ export interface TaskCreateInput {
  nodeId?: string;
  /** Optional explicit user assignment for this task (used during review handoff) */
  assigneeUserId?: string;
+  /** Opt out of the squash file-scope invariant for this task. */
+  scopeOverride?: boolean;
+  /** Optional justification for bypassing the squash file-scope invariant. */
+  scopeOverrideReason?: string;
  /** Per-task GitHub issue tracking overrides for Fusion-created linked issues. */
  githubTracking?: Pick<TaskGithubTracking, "enabled" | "repoOverride">;
  /** Review level for task execution — controls review rigor: 0=None, 1=Plan Only, 2=Plan and Code, 3=Full */
--- a/packages/engine/src/tests/merger-file-scope-invariant.test.ts
+++ b/packages/engine/src/tests/merger-file-scope-invariant.test.ts
@@ -0,0 +1,357 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_SETTINGS, type MergeResult, type Task } from "@fusion/core";
+import { createMockStore, mockedExecSync } from "./merger-test-helpers.js";
+import {
+  assertSquashOverlapsFileScope,
+  attemptWithSideStrategy,
+  commitOrAmendMergeWithFixes,
+  executeMergeAttempt,
+  FileScopeViolationError,
+} from "../merger.js";
+
+function createInvariantStore(scope: string[], taskOverrides: Record<string, unknown> = {}) {
+  const store = createMockStore(taskOverrides) as unknown as {
+    parseFileScopeFromPrompt: ReturnType<typeof vi.fn>;
+    appendAgentLog: ReturnType<typeof vi.fn>;
+    moveTask: ReturnType<typeof vi.fn>;
+    updateTask: ReturnType<typeof vi.fn>;
+    logEntry: ReturnType<typeof vi.fn>;
+  };
+  store.parseFileScopeFromPrompt = vi.fn().mockResolvedValue(scope);
+  store.appendAgentLog = vi.fn().mockResolvedValue(undefined);
+  store.moveTask = vi.fn().mockResolvedValue(undefined);
+  store.updateTask = vi.fn().mockResolvedValue(undefined);
+  store.logEntry = vi.fn().mockResolvedValue(undefined);
+  return store;
+}
+
+function createMergeResult(): MergeResult {
+  const task: Task = {
+    id: "FN-4073",
+    description: "Test task",
+    column: "in-review",
+    dependencies: [],
+    steps: [],
+    currentStep: 0,
+    log: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  return {
+    task,
+    branch: "fn/fn-4073",
+    merged: false,
+    worktreeRemoved: false,
+    branchDeleted: false,
+  };
+}
+
+describe("assertSquashOverlapsFileScope", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function mockStagedFiles(files: string[]) {
+    mockedExecSync.mockImplementation((cmd: any) => {
+      const cmdStr = String(cmd);
+      if (cmdStr === "git diff --cached --name-only") {
+        return files.join("\n");
+      }
+      return "";
+    });
+  }
+
+  it("passes without logging when no declared scope exists", async () => {
+    const store = createInvariantStore([]);
+    mockStagedFiles(["packages/engine/src/merger.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+
+    expect(store.appendAgentLog).not.toHaveBeenCalled();
+  });
+
+  it("passes without logging when staged files fully overlap scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockStagedFiles(["packages/engine/src/merger.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+
+    expect(store.appendAgentLog).not.toHaveBeenCalled();
+  });
+
+  it("passes when staged files partially overlap scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockStagedFiles([
+      "packages/engine/src/merger.ts",
+      "packages/core/src/store.ts",
+    ]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+  });
+
+  it("throws when staged files have zero overlap with scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockStagedFiles(["packages/core/src/store.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).rejects.toMatchObject({
+      name: "FileScopeViolationError",
+      taskId: "FN-4073",
+      stagedFiles: ["packages/core/src/store.ts"],
+      declaredScope: ["packages/engine/src/merger.ts"],
+    } satisfies Partial<FileScopeViolationError>);
+  });
+
+  it("matches nested files against glob entries", async () => {
+    const store = createInvariantStore(["packages/foo/**"]);
+    mockStagedFiles(["packages/foo/src/bar/baz.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+  });
+
+  it("ignores .changeset files for overlap and still throws without real overlap", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockStagedFiles([".changeset/foo.md"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).rejects.toMatchObject({
+      name: "FileScopeViolationError",
+      stagedFiles: [".changeset/foo.md"],
+    } satisfies Partial<FileScopeViolationError>);
+  });
+
+  it("bypasses enforcement and logs once when scopeOverride is true", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"], { scopeOverride: true });
+    mockStagedFiles(["packages/core/src/store.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+
+    expect(store.appendAgentLog).toHaveBeenCalledTimes(1);
+    expect(store.appendAgentLog).toHaveBeenCalledWith(
+      "FN-4073",
+      "file-scope invariant bypassed via scopeOverride",
+      "text",
+      undefined,
+      "merger",
+    );
+  });
+
+  it("includes the override reason in the bypass log", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"], {
+      scopeOverride: true,
+      scopeOverrideReason: "hotfix",
+    });
+    mockStagedFiles(["packages/core/src/store.ts"]);
+
+    await expect(assertSquashOverlapsFileScope({
+      store: store as never,
+      taskId: "FN-4073",
+      rootDir: "/tmp/root",
+      task: await (store as any).getTask("FN-4073"),
+    })).resolves.toBeUndefined();
+
+    expect(store.appendAgentLog).toHaveBeenCalledWith(
+      "FN-4073",
+      "file-scope invariant bypassed via scopeOverride — reason: hotfix",
+      "text",
+      undefined,
+      "merger",
+    );
+  });
+});
+
+describe("file-scope invariant wiring", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("blocks the standard merge AI path before the commit when staged files are out of scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockedExecSync.mockImplementation((cmd: any) => {
+      const cmdStr = String(cmd);
+      if (cmdStr.includes("git diff --cached --quiet")) return "1";
+      if (cmdStr === "git diff --cached --name-only") return "packages/core/src/store.ts";
+      return "";
+    });
+
+    const result = createMergeResult();
+    await expect(executeMergeAttempt({
+      store: store as never,
+      rootDir: "/tmp/root",
+      taskId: "FN-4073",
+      branch: "fn/fn-4073",
+      commitLog: "feat: branch work",
+      diffStat: "1 file changed",
+      includeTaskId: true,
+      smartConflictResolution: true,
+      mergeConflictStrategy: "smart-prefer-branch",
+      attemptNum: 1,
+      options: {},
+      result,
+      settings: { ...DEFAULT_SETTINGS },
+    }, { aiWasInvoked: false })).rejects.toBeInstanceOf(FileScopeViolationError);
+
+    expect(store.appendAgentLog).toHaveBeenCalledWith(
+      "FN-4073",
+      expect.stringContaining("File-scope invariant violation"),
+      "tool_error",
+      expect.stringContaining("declaredScope:"),
+      "merger",
+    );
+    expect(mockedExecSync).toHaveBeenCalledWith("git reset --merge", expect.objectContaining({ cwd: "/tmp/root" }));
+    expect(store.moveTask).not.toHaveBeenCalled();
+  });
+
+  it("allows the -X fallback commit when staged files partially overlap scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockedExecSync.mockImplementation((cmd: any) => {
+      const cmdStr = String(cmd);
+      if (cmdStr.includes("git merge -X ours --squash")) return "";
+      if (cmdStr.includes("git diff --name-only --diff-filter=U")) return "";
+      if (cmdStr.includes("git diff --cached --quiet")) return "1";
+      if (cmdStr === "git diff --cached --name-only") return "packages/engine/src/merger.ts\npackages/core/src/store.ts";
+      if (cmdStr.includes("git commit ")) return "";
+      return "";
+    });
+
+    await expect(attemptWithSideStrategy({
+      store: store as never,
+      rootDir: "/tmp/root",
+      taskId: "FN-4073",
+      branch: "fn/fn-4073",
+      commitLog: "feat: branch work",
+      diffStat: "1 file changed",
+      includeTaskId: true,
+      sourceIssueRef: undefined,
+      smartConflictResolution: true,
+      mergeConflictStrategy: "smart-prefer-main",
+      attemptNum: 3,
+      options: {},
+      result: createMergeResult(),
+      settings: { ...DEFAULT_SETTINGS },
+    }, "ours")).resolves.toBe(true);
+
+    expect(store.appendAgentLog).not.toHaveBeenCalledWith(
+      "FN-4073",
+      expect.stringContaining("File-scope invariant violation"),
+      expect.anything(),
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  it("bypasses the -X fallback invariant when scopeOverride is true and logs the reason", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"], {
+      scopeOverride: true,
+      scopeOverrideReason: "hotfix",
+    });
+    mockedExecSync.mockImplementation((cmd: any) => {
+      const cmdStr = String(cmd);
+      if (cmdStr.includes("git merge -X ours --squash")) return "";
+      if (cmdStr.includes("git diff --name-only --diff-filter=U")) return "";
+      if (cmdStr.includes("git diff --cached --quiet")) return "1";
+      if (cmdStr.includes("git commit ")) return "";
+      return "";
+    });
+
+    await expect(attemptWithSideStrategy({
+      store: store as never,
+      rootDir: "/tmp/root",
+      taskId: "FN-4073",
+      branch: "fn/fn-4073",
+      commitLog: "feat: branch work",
+      diffStat: "1 file changed",
+      includeTaskId: true,
+      sourceIssueRef: undefined,
+      smartConflictResolution: true,
+      mergeConflictStrategy: "smart-prefer-main",
+      attemptNum: 3,
+      options: {},
+      result: createMergeResult(),
+      settings: { ...DEFAULT_SETTINGS },
+    }, "ours")).resolves.toBe(true);
+
+    expect(store.appendAgentLog).toHaveBeenCalledWith(
+      "FN-4073",
+      "file-scope invariant bypassed via scopeOverride — reason: hotfix",
+      "text",
+      undefined,
+      "merger",
+    );
+  });
+
+  it("blocks verification-fix finalization when staged files are out of scope", async () => {
+    const store = createInvariantStore(["packages/engine/src/merger.ts"]);
+    mockedExecSync.mockImplementation((cmd: any) => {
+      const cmdStr = String(cmd);
+      if (cmdStr === "git diff --cached --name-only") return "packages/core/src/store.ts";
+      if (cmdStr === "git diff --name-only") return "";
+      if (cmdStr === "git status -z --porcelain") return "";
+      if (cmdStr === "git diff --cached --raw") return "";
+      if (cmdStr === "git rev-parse HEAD") return "head-before";
+      if (cmdStr.includes("git commit ")) return "";
+      return "";
+    });
+
+    await expect(commitOrAmendMergeWithFixes(
+      "/tmp/root",
+      "FN-4073",
+      "fn/fn-4073",
+      "feat: branch work",
+      true,
+      "head-before",
+      "",
+      "1 file changed",
+      { ...DEFAULT_SETTINGS },
+      undefined,
+      undefined,
+      undefined,
+      new Set(),
+      store as never,
+    )).rejects.toBeInstanceOf(FileScopeViolationError);
+
+    expect(store.appendAgentLog).toHaveBeenCalledWith(
+      "FN-4073",
+      expect.stringContaining("File-scope invariant violation"),
+      "tool_error",
+      expect.stringContaining("stagedFiles:"),
+      "merger",
+    );
+    expect(mockedExecSync).toHaveBeenCalledWith("git reset --merge", expect.objectContaining({ cwd: "/tmp/root" }));
+  });
+});
--- a/packages/engine/src/tests/merger-test-helpers.ts
+++ b/packages/engine/src/tests/merger-test-helpers.ts
@@ -131,6 +131,8 @@ import {
  parseDiffStat,
  extractFileScope,
  validateDiffScope,
+  assertSquashOverlapsFileScope,
+  FileScopeViolationError,
  shouldSyncDependenciesForMerge,
  summarizeVerificationOutput,
  inferDefaultTestCommand,
@@ -165,6 +167,8 @@ export {
  parseDiffStat,
  extractFileScope,
  validateDiffScope,
+  assertSquashOverlapsFileScope,
+  FileScopeViolationError,
  shouldSyncDependenciesForMerge,
  summarizeVerificationOutput,
  inferDefaultTestCommand,
@@ -211,6 +215,7 @@ export function createMockStore(taskOverrides: Partial<Task> = {}, allTasks: Tas
    updateSettings: vi.fn().mockResolvedValue({}),
    getSettings: vi.fn().mockResolvedValue({ ...DEFAULT_SETTINGS }),
    getActiveMergingTask: vi.fn().mockReturnValue(null),
+    parseFileScopeFromPrompt: vi.fn().mockResolvedValue([]),
    emit: vi.fn(),
    on: vi.fn(),
    clearStaleExecutionStartBranchReferences: vi.fn().mockReturnValue([]),
--- a/packages/engine/src/merger.ts
+++ b/packages/engine/src/merger.ts
@@ -3415,6 +3415,15 @@ export async function commitOrAmendMergeWithFixes(
      // This is the phantom-merge fix: previously the code blindly amended
      // HEAD (the previous task's commit), silently dropping the current
      // task's branch and inheriting the prior task's stats.
+      if (store) {
+        await enforceSquashFileScopeInvariant({
+          store,
+          taskId,
+          rootDir,
+          task: await store.getTask(taskId),
+          resetLabel: "file-scope invariant violation",
+        });
+      }
      await runDiffVolumeGate({
        rootDir,
        branch,
@@ -3448,6 +3457,15 @@ export async function commitOrAmendMergeWithFixes(
    // HEAD moved — AI agent committed already. Amend with deterministic
    // message + any new staged fixes folded in. `--amend -m` replaces both
    // the message and includes any newly-staged content.
+    if (store) {
+      await enforceSquashFileScopeInvariant({
+        store,
+        taskId,
+        rootDir,
+        task: await store.getTask(taskId),
+        resetLabel: "file-scope invariant violation",
+      });
+    }
    await runDiffVolumeGate({
      rootDir,
      branch,
@@ -3477,7 +3495,7 @@ export async function commitOrAmendMergeWithFixes(
    mergerLog.log(`${taskId}: amended merge commit with verification fixes (deterministic message)`);
    return { ok: true, reason: "completed" };
  } catch (err: unknown) {
-    if (err instanceof DiffVolumeRegressionError) {
+    if (err instanceof DiffVolumeRegressionError || err instanceof FileScopeViolationError) {
      throw err;
    }
    const errorMessage = err instanceof Error ? err.message : String(err);
@@ -3582,6 +3600,104 @@ function matchesScope(filePath: string, scopePatterns: string[]): boolean {
 * When `strict` is true, throws an error on scope violations instead of
 * just returning warnings (hard guardrail that blocks merge).
 */
+
+export class FileScopeViolationError extends Error {
+  taskId: string;
+  stagedFiles: string[];
+  declaredScope: string[];
+
+  constructor(taskId: string, stagedFiles: string[], declaredScope: string[]) {
+    const stagedList = stagedFiles.length > 0 ? stagedFiles.join(", ") : "<none outside .changeset/>";
+    const scopeList = declaredScope.join(", ");
+    super(
+      `File-scope invariant violation for ${taskId}: staged files [${stagedList}] have zero overlap with declared File Scope [${scopeList}]. Refile genuinely out-of-scope work as a follow-up task via fn_task_create before retrying this merge.`,
+    );
+    this.name = "FileScopeViolationError";
+    this.taskId = taskId;
+    this.stagedFiles = stagedFiles;
+    this.declaredScope = declaredScope;
+  }
+}
+
+export async function assertSquashOverlapsFileScope(params: {
+  store: TaskStore;
+  taskId: string;
+  rootDir: string;
+  task: Task;
+}): Promise<void> {
+  const { store, taskId, rootDir, task } = params;
+
+  if (task.scopeOverride === true) {
+    const reasonSuffix = task.scopeOverrideReason?.trim()
+      ? ` — reason: ${task.scopeOverrideReason.trim()}`
+      : "";
+    await store.appendAgentLog(
+      taskId,
+      `file-scope invariant bypassed via scopeOverride${reasonSuffix}`,
+      "text",
+      undefined,
+      "merger",
+    );
+    return;
+  }
+
+  if (typeof (store as Partial<TaskStore>).parseFileScopeFromPrompt !== "function") {
+    return;
+  }
+
+  const declaredScope = await store.parseFileScopeFromPrompt(taskId);
+  if (declaredScope.length === 0) {
+    return;
+  }
+
+  const { stdout } = await execAsync("git diff --cached --name-only", {
+    cwd: rootDir,
+    encoding: "utf-8",
+  });
+  const stagedFiles = stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  const scopedStagedFiles = stagedFiles.filter((file) => !file.startsWith(".changeset/"));
+  const hasOverlap = scopedStagedFiles.some((file) => matchesScope(file, declaredScope));
+  if (!hasOverlap) {
+    throw new FileScopeViolationError(taskId, stagedFiles, declaredScope);
+  }
+}
+
+function formatFileScopeViolationAgentLog(error: FileScopeViolationError): string {
+  const stagedFiles = error.stagedFiles.length > 0 ? error.stagedFiles.join("\n") : "<none>";
+  return [
+    `taskId: ${error.taskId}`,
+    "declaredScope:",
+    ...error.declaredScope.map((entry) => `- ${entry}`),
+    "stagedFiles:",
+    ...stagedFiles.split("\n").map((entry) => `- ${entry}`),
+  ].join("\n");
+}
+
+async function enforceSquashFileScopeInvariant(params: {
+  store: TaskStore;
+  taskId: string;
+  rootDir: string;
+  task: Task;
+  resetLabel: string;
+}): Promise<void> {
+  try {
+    await assertSquashOverlapsFileScope(params);
+  } catch (error: unknown) {
+    if (!(error instanceof FileScopeViolationError)) {
+      throw error;
+    }
+    await params.store.appendAgentLog(
+      params.taskId,
+      error.message,
+      "tool_error",
+      formatFileScopeViolationAgentLog(error),
+      "merger",
+    );
+    resetMergeWithWarn(params.rootDir, params.taskId, params.resetLabel);
+    throw error;
+  }
+}
+
 export async function validateDiffScope(
  store: TaskStore,
  taskId: string,
@@ -6106,7 +6222,11 @@ export async function aiMergeTask(
        throw error;
      }

-      if (error instanceof DiffVolumeRegressionError || error?.name === "DiffVolumeRegressionError") {
+      if (
+        error instanceof DiffVolumeRegressionError
+        || error?.name === "DiffVolumeRegressionError"
+        || error?.name === "FileScopeViolationError"
+      ) {
        throw error;
      }

@@ -7187,6 +7307,13 @@ export async function executeMergeAttempt(
              aiSummary: safeBody,
              aiSubject,
            });
+            await enforceSquashFileScopeInvariant({
+              store,
+              taskId,
+              rootDir,
+              task: await store.getTask(taskId),
+              resetLabel: "file-scope invariant violation",
+            });
            await runDiffVolumeGate({
              rootDir,
              branch,
@@ -7317,6 +7444,13 @@ export async function executeMergeAttempt(
    // Spawn AI agent
    throwIfAborted(options.signal, taskId);
    aiTracker.aiWasInvoked = true; // Track that AI was invoked
+    await enforceSquashFileScopeInvariant({
+      store,
+      taskId,
+      rootDir,
+      task: await store.getTask(taskId),
+      resetLabel: "file-scope invariant violation",
+    });
    const agentResult = await runAiAgentForCommit({
      store,
      rootDir,
@@ -7444,7 +7578,11 @@ export async function executeMergeAttempt(
    // and trip the phantom-merge guard even though the task's content is
    // already on HEAD. Retrying with auto-conflict-resolution can't help a
    // verification failure anyway — there are no conflicts to resolve.
-    if (error?.name === "VerificationError" || error?.name === "DiffVolumeRegressionError") {
+    if (
+      error?.name === "VerificationError"
+      || error?.name === "DiffVolumeRegressionError"
+      || error?.name === "FileScopeViolationError"
+    ) {
      throw error;
    }

@@ -7492,7 +7630,7 @@ export async function attemptWithSideStrategy(

    return finalizeSideStrategyAttempt(params, side, aiTracker);
  } catch (error) {
-    if (error instanceof Error && (error.name === "MergeAbortedError" || error.name === "DiffVolumeRegressionError")) {
+    if (error instanceof Error && (error.name === "MergeAbortedError" || error.name === "DiffVolumeRegressionError" || error.name === "FileScopeViolationError")) {
      throw error;
    }
    mergerLog.error(`${taskId}: -X ${side} merge failed: ${error}`);
@@ -7533,7 +7671,7 @@ async function attemptWithMixedSideStrategy(

    return finalizeSideStrategyAttempt(params, strategy.defaultSide, aiTracker);
  } catch (error) {
-    if (error instanceof Error && (error.name === "MergeAbortedError" || error.name === "DiffVolumeRegressionError")) {
+    if (error instanceof Error && (error.name === "MergeAbortedError" || error.name === "DiffVolumeRegressionError" || error.name === "FileScopeViolationError")) {
      throw error;
    }
    mergerLog.error(`${taskId}: overlap-aware merge failed: ${error}`);
@@ -7593,6 +7731,13 @@ async function finalizeSideStrategyAttempt(
    aiSummary: aiSummary?.trim().length ? aiSummary : safeBody,
    aiSubject,
  });
+  await enforceSquashFileScopeInvariant({
+    store,
+    taskId,
+    rootDir,
+    task: await store.getTask(taskId),
+    resetLabel: "file-scope invariant violation",
+  });
  await runDiffVolumeGate({
    rootDir,
    branch,