feat(FN-4482): complete Step 5 — docs and changeset

Fusion-Task-Id: FN-4482
Fusion-Task-Lineage: 5850cda2-ded5-42ac-a206-396839580748

.changeset/FN-4482-plan-only-scope-leak-guard.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Add executor-side scope-leak guard at fn_task_done for Plan-Only (Review Level 1) tasks. Off-scope uncommitted edits now produce a [scope-leak] activity-log entry (default warn) or refuse fn_task_done when planOnlyScopeLeakEnforcement="block". Respects task.scopeOverride and never blocks on git infrastructure failures.

docs/settings-reference.md

@@ -249,6 +249,7 @@ Override precedence for direct merges is:
 | `smartConflictResolution` | `boolean` | `true` | Alias/preferred flag for smart conflict handling. |
 | `mergerAutostashMaxAgeHours` | `number` | `24` | Maximum autostash age in hours before startup/periodic stale-stash sweep drops `fusion-merger-autostash:*` leftovers (minimum `1`). |
 | `workflowStepScopeEnforcement` | `"block" \| "warn" \| "off"` | `"block"` | Controls pre-merge **prompt-mode workflow-step** file-scope enforcement. `block` requests revision on off-scope writes, `warn` logs and passes, `off` disables the check. Task-level `scopeOverride` bypasses this check. |
+| `planOnlyScopeLeakEnforcement` | `"off" \| "warn" \| "block"` | `"warn"` | Controls executor-side `fn_task_done` scope-leak handling for **Plan-Only (Review Level 1)** tasks when touched files fall outside declared File Scope. `warn` logs a `[scope-leak]` activity entry and allows completion, `block` refuses `fn_task_done` with remediation guidance, and `off` disables this guard. `task.scopeOverride=true` bypasses enforcement. Review levels `0` and `>=2` stay warn-only telemetry. |
 | `workflowRevisionForkOnScopeMismatch` | `boolean` | `true` | When enabled, workflow revision feedback that explicitly names files outside the task's declared File Scope is forked into a dependent follow-up triage task instead of being appended to the original task's `PROMPT.md`. Set to `false` to keep the legacy append-and-rerun behavior. |
 | `strictScopeEnforcement` | `boolean` | `false` | Block merges on out-of-scope file changes. |
 | `buildRetryCount` | `number` | `0` | Build retry attempts during merge. |

docs/workflow-steps.md

@@ -221,6 +221,23 @@ After each successful **prompt-mode pre-merge** workflow step, Fusion runs a sco
   - `"warn"`: log the violation but allow the step to pass.
   - `"off"`: disable this pre-merge workflow-step invariant entirely.
 
+### Executor `fn_task_done` scope-leak guard for Plan-Only tasks (FN-4482)
+
+Fusion also enforces a completion-time scope-leak check in the executor `fn_task_done` path:
+
+- Applies to tasks with declared `## File Scope`.
+- Uses touched files from branch committed delta plus uncommitted working-tree edits at completion time.
+- Emits `[scope-leak]` activity-log entries when touched files are off-scope.
+- Honors `task.scopeOverride === true` as an explicit bypass.
+
+`planOnlyScopeLeakEnforcement` controls Review Level 1 behavior:
+
+- `"warn"` (default): log and allow completion.
+- `"block"`: refuse `fn_task_done` and ask the agent to revert off-scope paths.
+- `"off"`: disable this completion-time guard.
+
+Review Level `0` and `>=2` run in warn-only telemetry mode (never block).
+
 ### Hard Failures vs Revisions
 
 Not all workflow failures are revision requests: