Add explicit force replacement workflow

docs/internal/publish.md

@@ -6,17 +6,17 @@
 
 ## Inputs and outputs
 
-Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transform policy, transformer resolver, transfer policy, destination bundle path, and existing destination state.
+Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transform policy, transformer resolver, transfer policy, destination bundle path, existing destination state, and whether explicit force was requested for the current run.
 
 Output is a plan with an action, reason, and selected source or generated outputs. Execution writes selected source files, generated files, and `.distributor.json` for publish or replacement actions.
 
 ## Actions
 
-Supported actions are `publish_new`, `replace_older`, `skip_same`, `skip_destination_newer`, `fail_conflict`, and `fail_unmanaged`.
+Supported actions are `publish_new`, `replace_older`, `force_replace`, `skip_same`, `skip_destination_newer`, `fail_conflict`, and `fail_unmanaged`.
 
 ## Failure behavior
 
-Planning fails when request fields are incomplete, publish and transform policies are invalid, selected outputs collide, HTML output is requested without Markdown inputs, destination state is invalid, destination content is unmanaged, or transfer policy maps the comparison outcome to failure.
+Planning fails when request fields are incomplete, publish and transform policies are invalid, selected outputs collide, HTML output is requested without Markdown inputs, destination state is invalid, destination content is unmanaged without force, or transfer policy maps the comparison outcome to failure.
 
 Execution fails if a write, delete, state serialization, or context check fails. Outputs written during a failed publish attempt are cleaned up through managed deletion where possible.
 
@@ -28,7 +28,7 @@ The package uses `internal/state` for destination comparison, `internal/storage`
 
 ## Safety
 
-Replacement deletes only outputs recorded in existing destination state plus `.distributor.json`. Failed writes trigger cleanup of outputs written during the failed attempt where practical.
+Normal replacement deletes only outputs recorded in existing destination state plus `.distributor.json`. Forced replacement deletes the bounded destination bundle path before writing outputs and state. Failed writes trigger cleanup of outputs written during the failed attempt where practical.
 
 ## Tests
 
@@ -37,7 +37,8 @@ Before changing publish behavior, inspect tests under `internal/publish` and run
 ## Invariants
 
 - Publish planning is deterministic for the same source, destination state, policies, and transform outputs.
-- Replacement deletes only managed paths recorded in existing state plus `.distributor.json`.
+- Normal replacement deletes only managed paths recorded in existing state plus `.distributor.json`.
+- Forced replacement is explicit per run and deletes only within the destination bundle path.
 - Publish execution writes destination state after selected outputs are written.
 - Transform implementations are resolved through an interface supplied by the caller.
-- Unmanaged destination content is never overwritten.
+- Unmanaged destination content is overwritten only by explicit forced replacement.