test(FN-3842): align finalize-result assertions and docs

packages/engine/src/__tests__/merger-no-op-fix-finalize.test.ts

@@ -72,7 +72,7 @@ describe("commitOrAmendMergeWithFixes no-op finalize", () => {
       new Set<string>(),
     );
 
-    expect(result).toBe(true);
+    expect(result.ok).toBe(true);
     const committedFiles = git(dir, "git diff --name-only HEAD~1 HEAD").split("\n").filter(Boolean);
     expect(committedFiles).toContain("feature-a.ts");
   });
@@ -100,6 +100,7 @@ describe("commitOrAmendMergeWithFixes no-op finalize", () => {
       new Set<string>(),
     );
 
-    expect(result).toBe(false);
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("unknown-phantom");
   });
 });

packages/engine/src/merger.ts

@@ -2558,8 +2558,9 @@ async function buildDeterministicMergeMessage(params: {
  * modified are staged. Any other dirty files in the working tree are left
  * untouched and a warning is emitted for each one.
  *
- * Returns true on a successful commit/amend. Never throws — errors are logged
- * and the function returns false (callers decide whether to abort the merge).
+ * Returns a structured result with `{ ok: true, reason: ... }` on success or
+ * `{ ok: false, reason: ... }` on failure. Never throws — errors are logged and
+ * callers decide whether to abort the merge based on the returned reason.
  *
  * @internal Exported for integration tests only — not part of the public API.
  */