docs(FN-4956): complete Step 6 — document layer3 scope partition

Fusion-Task-Id: FN-4956
Fusion-Task-Lineage: 7105cd5e-27f4-4e84-b2ae-e811a183803f

.changeset/FN-4956-layer3-ai-arbiter-scope.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Harden merge conflict arbitration so Layer 3 AI resolution respects task File Scope by resolving out-of-scope conflicted files to main before AI handling and emitting scope-partition audit events.

AGENTS.md

@@ -226,6 +226,7 @@ Hard-won rules (FN-2370 silently reverted three commits' worth of work):
 6. **Post-squash audit on auto-resolved conflicts.** `postMergeAuditMode`: `warn` (default), `block` (refuse on findings), `off`. Rebase-strategy overlap-only findings auto-clear when deterministic verification has proven the merged tree. When findings still block, the `mergeAuditAutoRecovery` pipeline runs (Stages 1–5: deterministic → programmatic → ai-assisted → bounded retries → park-with-follow-up).
 7. **Pre-commit diff-volume gate.** Before writing an auto-resolved squash commit, the merger compares each file's staged squash delta against branch net delta vs merge-base. Non-allowlisted files losing too much branch volume block the merge in `in-review`. Guard against FN-3936-style silent drops.
 8. **Smart-prefer-main overlap guard.** When `mergeConflictStrategy="smart-prefer-main"`, recent main commits (30-commit lookback) overlapping branch-modified files flip to prefer-branch by default (`mergeStrategyOverlapBehavior="flip-to-prefer-branch"`).
+9. **Layer 3 scope partition for AI arbitration (FN-4956).** Before handing conflicted files to the Layer 3 AI arbiter, merger partitions conflicts against declared task File Scope. Out-of-scope conflicts are resolved to main (`--ours`) and unstaged so they cannot enter the squash; only in-scope conflicts reach AI. `task.scopeOverride=true` bypasses this partition. Run-audit emits `merge:layer3:foreign-file-skipped` (skip path) or `merge:layer3:scope-override-bypass` (override path).
 
 ### Gitignored-path guard on squash merges
 

docs/architecture.md

@@ -700,6 +700,7 @@ Guardrails: this routine does **not** retry merges, does **not** apply to mixed/
 ### Observability and reflection
 - `AgentLogger` (`agent-logger.ts`) — structured per-agent run logging
 - `RunAudit` (`run-audit.ts`) — mutation audit tracking (DB/git/filesystem)
+  - FN-4956: Layer 3 merge-conflict arbitration now scope-partitions conflicted files before AI resolution. Out-of-scope conflicts are deterministically resolved to main (`git checkout --ours`) and unstaged, while only in-scope conflicts flow to AI. Audit events: `merge:layer3:foreign-file-skipped` and `merge:layer3:scope-override-bypass`.
 
 #### Key diagnostic points (log subsystem tags)
 - `[self-healing]` — startup/maintenance recovery pass outcomes.