Add explicit force replacement workflow

docs/cli.md

@@ -13,7 +13,7 @@ This discovers the example source bundle and publishes source files to `workspac
 ```sh
 distributor [--help]
 distributor version
-distributor run [--config <path>] [--dry-run]
+distributor run [--config <path>] [--dry-run] [--force]
 distributor validate <path>
 distributor inspect <path>
 ```
@@ -39,6 +39,7 @@ All subcommands:
 
 - `--config <path>`: config file to load. If omitted, `run` uses `/usr/local/etc/distributor/config.yml`.
 - `--dry-run`: load config, discover bundles, inspect destination state, print planned actions and final status, and do not write files.
+- `--force`: allow explicit destructive replacement for supported conflict cases in this run only.
 
 `run` does not accept positional arguments. `validate` and `inspect` accept at most one path; omitting the path returns a required-path error.
 
@@ -80,18 +81,27 @@ Preview local fan-out publication:
 go run ./cmd/distributor run --config examples/fan-out.yml --dry-run
 ```
 
+Preview a forced replacement before publishing:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
 ## Output
 
 `run` prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Destination action lines include the bundle path, destination id, destination backend, action, outputs, and reason. Actions include:
 
 - `publish_new`: destination has no managed state and is empty.
 - `replace_older`: destination state is older than the source manifest.
+- `force_replace`: `--force` requested a supported destructive replacement.
 - `skip_same`: destination state already matches the source manifest.
 - `skip_destination_newer`: destination state is newer than the source manifest.
 - `error`: planning or execution failed for that destination.
 
 The command exits non-zero if any destination fails. Independent later destinations are still attempted.
 
+The final status line includes counters for `publish_new`, `replace_older`, `force_replace`, skipped destinations, failures, and whether the run was a dry run.
+
 ## Diagnostics
 
 Use `validate` before publication when a producer has written a new bundle. Use `inspect` to confirm normalized ids, timestamps, digests, file paths, and file sizes.

docs/config.md

@@ -170,8 +170,10 @@ Transfer policy:
 
 - `transfer.on_destination_same`: `skip` or `fail`; defaults to `skip`.
 - `transfer.on_destination_older`: `replace` or `fail`; defaults to `replace`.
-- `transfer.on_destination_newer`: `skip` or `fail`; defaults to `skip`.
-- `transfer.on_conflict`: only `fail`; defaults to `fail`.
+- `transfer.on_destination_newer`: `skip`, `replace`, or `fail`; defaults to `skip`.
+- `transfer.on_conflict`: `fail` or `replace`; defaults to `fail`.
+
+`replace` for `on_destination_newer` and `on_conflict` is honored only when `run --force` is used for that invocation. Force is CLI-only; there is no persistent config field that enables forced replacement by default.
 
 ## Defaults
 

docs/internal/app.md

@@ -6,7 +6,7 @@
 
 ## Inputs and outputs
 
-`Run` accepts a context, optional config path, dry-run flag, stdout writer, and optional notifier. It loads YAML config, discovers source bundles for each configured pipeline, plans each destination independently, optionally executes publish plans, writes summary output when stdout is supplied, and returns an aggregated error if any destination fails.
+`Run` accepts a context, optional config path, dry-run flag, force flag, stdout writer, and optional notifier. It loads YAML config, discovers source bundles for each configured pipeline, plans each destination independently, optionally executes publish plans, writes summary output when stdout is supplied, and returns an aggregated error if any destination fails.
 
 `Validate` and `Inspect` accept a local path. `Validate` discovers and validates bundles. `Inspect` writes bundle metadata and manifest file entries to stdout when provided.
 
@@ -33,7 +33,7 @@ The app-level transform registry registers Markdown-to-HTML using `internal/tran
 
 ## Dry-run behavior
 
-Dry-run still loads config, opens backends, discovers bundles, inspects destinations, resolves transforms, and builds publish plans. It does not write destination outputs, write `.distributor.json`, delete managed outputs, or notify.
+Dry-run still loads config, opens backends, discovers bundles, inspects destinations, resolves transforms, and builds publish plans. It does not write destination outputs, write `.distributor.json`, delete managed outputs, perform forced prefix deletion, or notify.
 
 ## Failure behavior
 

docs/internal/config.md

@@ -33,6 +33,8 @@ Defaults are applied in `ApplyDefaults`:
 
 Validation requires at least one pipeline, slug-like unique pipeline ids, one source per pipeline, at least one destination, slug-like unique destination ids within each pipeline, backend-specific required fields, valid validation policy, valid publish and transform combinations, and valid transfer actions.
 
+Transfer validation accepts `replace` for `on_destination_newer` and `on_conflict`, but publish planning honors those destructive actions only when the current run explicitly requests force.
+
 `ValidatePublishTransformPolicy` is shared with publish planning so destination policy combinations are checked consistently. Publishing HTML requires an enabled Markdown-to-HTML transform in `sidecar` mode. A publish policy must select source output, HTML output, or both.
 
 ## Executable support boundary

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.

docs/internal/state.md

@@ -33,7 +33,7 @@ Comparison outcomes cover absent destination state, unmanaged destination conten
 
 ## Failure behavior
 
-Invalid JSON, invalid state schema, invalid embedded source manifests, unsafe output paths, unsupported output kinds, missing generated-output transform names, and mismatched pipeline or destination ids produce comparison outcomes that publish planning can turn into fail actions.
+Invalid JSON, invalid state schema, invalid embedded source manifests, unsafe output paths, unsupported output kinds, missing generated-output transform names, and mismatched pipeline or destination ids produce comparison outcomes that publish planning can turn into fail actions. Supported identity and source-manifest conflicts can become forced replacement only when publish planning receives explicit force and compatible transfer policy.
 
 ## Boundaries
 

docs/internal/storage.md

@@ -6,7 +6,7 @@
 
 ## Inputs and outputs
 
-The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, and guarded managed deletion.
+The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, guarded managed deletion, and bounded prefix deletion for explicit forced replacement.
 
 Entries report a logical path, type, and size when available. Entry types are `file`, `directory`, `symlink`, and `other`.
 
@@ -28,15 +28,17 @@ Backends may wrap implementation-specific errors, but callers should receive sto
 
 ## Deletion
 
-Backends expose guarded managed deletion only. `DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`; it does not provide broad recursive deletion.
+`DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`.
+
+`DeletePrefix` removes content at and below a logical prefix for explicit forced replacement. It must not delete above the requested prefix or above the configured backend root.
 
 ## Local, SSH, S3, and fake backends
 
 The local adapter maps logical paths to a configured filesystem root and keeps adapter-specific path handling behind the storage interface.
 
-The SSH adapter maps logical paths to a configured remote SFTP root. It uses native SSH and SFTP libraries, supports SSH agent and key-file authentication, applies host-key policies, rejects unsafe logical paths, reports symlink entries from `Lstat`, and limits deletion to managed targets.
+The SSH adapter maps logical paths to a configured remote SFTP root. It uses native SSH and SFTP libraries, supports SSH agent and key-file authentication, applies host-key policies, rejects unsafe logical paths, reports symlink entries from `Lstat`, and limits deletion to managed targets or explicit bounded prefixes.
 
-The S3 adapter maps logical paths to object keys below a configured bucket and optional prefix. It uses the AWS SDK for Go v2, treats prefixes as object trees, requires exact objects for `Stat`, paginates traversal, applies conservative overwrite checks with `HeadObject`, infers basic content types, and limits deletion to managed target objects.
+The S3 adapter maps logical paths to object keys below a configured bucket and optional prefix. It uses the AWS SDK for Go v2, treats prefixes as object trees, requires exact objects for `Stat`, paginates traversal, applies conservative overwrite checks with `HeadObject`, infers basic content types, and limits deletion to managed target objects or explicit bounded object-key prefixes.
 
 The fake backend is an in-memory implementation for package tests. It is not registered for runtime use.
 
@@ -56,4 +58,5 @@ Before changing storage behavior, inspect tests under:
 - Logical paths are slash-separated and confined to the backend root.
 - `storage.List` uses backend traversal and returns deterministic entries.
 - Managed deletion is limited to recorded outputs plus `.distributor.json`.
+- Prefix deletion is limited to the requested logical prefix.
 - Runtime backend registration is owned by `internal/app`.

docs/operations.md

@@ -74,7 +74,7 @@ Do not edit `.distributor.json` by hand during normal operation. If it is missin
 
 `--dry-run` loads and validates config, discovers source bundles, inspects destination state, plans outputs, and prints summary lines. It does not write output files or destination state.
 
-Dry-run output is useful before publishing to confirm actions such as `publish_new`, `replace_older`, `skip_same`, and `skip_destination_newer`.
+Dry-run output is useful before publishing to confirm actions such as `publish_new`, `replace_older`, `force_replace`, `skip_same`, and `skip_destination_newer`.
 
 Destination action lines include the destination backend, so mixed local, SSH, and S3 fan-out runs can be audited before publication.
 
@@ -86,7 +86,20 @@ If destination state is older than the source manifest and transfer policy allow
 
 If destination state is newer than the source manifest, the default behavior is to skip. If destination state has the same source id and created timestamp but a different digest, publication fails as a conflict.
 
-If a destination path has files but no valid `.distributor.json`, publication fails as unmanaged content. There is no force overwrite option.
+If a destination path has files but no valid `.distributor.json`, publication fails as unmanaged content unless the current run explicitly uses `--force`.
+
+## Force Workflow
+
+Use `--force` only after a dry run shows the intended `force_replace` action:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+go run ./cmd/distributor run --config <config-path> --force
+```
+
+Forced replacement can overwrite unmanaged non-empty destination paths. Destination state conflicts require `transfer.on_conflict: replace` plus `--force`. Newer destination state requires `transfer.on_destination_newer: replace` plus `--force`.
+
+Forced replacement deletes the current destination bundle path before writing outputs and state. It does not delete above that bundle path. For S3 destinations, deletion is constrained to the configured bucket and prefix plus the destination bundle prefix. Force is per run only and has no config default.
 
 ## Failure Handling
 
@@ -114,7 +127,7 @@ S3 execution uses the AWS SDK for Go v2. Configure `endpoint`, `bucket`, optiona
 
 When explicit credential env names are configured, both variables must resolve to non-empty values through the real process environment or `secrets.directory`. When they are omitted, the AWS SDK default credential chain is used as-is.
 
-Replacement and failed-write cleanup delete only managed output objects recorded in `.distributor.json` plus the state object. Distributor does not perform recursive prefix deletion and does not manage bucket versioning or delete markers.
+Normal replacement and failed-write cleanup delete only managed output objects recorded in `.distributor.json` plus the state object. Forced replacement deletes objects under the bounded destination bundle prefix. Distributor does not manage bucket versioning or delete markers.
 
 ## Secrets Directory
 
@@ -131,6 +144,6 @@ Real process environment values take precedence over files with the same name. I
 
 ## Caveats
 
-External notification adapters and force overwrite behavior are unavailable.
+External notification adapters are unavailable. Force overwrite behavior is available only through the explicit `run --force` workflow.
 
 For symptom-oriented fixes, see [troubleshooting](troubleshooting.md). For config details, see [configuration](config.md). For command syntax, see [CLI](cli.md).

docs/troubleshooting.md

@@ -257,7 +257,7 @@ Diagnostic:
 find <destination-path> -maxdepth 2 -print
 ```
 
-Safe fix: choose an empty destination path or move existing files aside after confirming they are not needed. There is no force overwrite option.
+Safe fix: choose an empty destination path or move existing files aside after confirming they are not needed. If the destination should be claimed by distributor, preview with `run --dry-run --force` and publish with `run --force` only after confirming the reported `force_replace` action is bounded to the intended bundle path.
 
 ## `fail_conflict`
 
@@ -270,7 +270,31 @@ cat <destination-path>/.distributor.json
 go run ./cmd/distributor inspect <source-root>
 ```
 
-Safe fix: verify you are publishing the intended source to the intended destination. Use a separate destination path for unrelated content.
+Safe fix: verify you are publishing the intended source to the intended destination. Use a separate destination path for unrelated content. If the existing state should be replaced, configure `transfer.on_conflict: replace`, preview with `run --dry-run --force`, then publish with `run --force`.
+
+## `destination is newer and replacement requires --force`
+
+Likely cause: config explicitly allows newer-destination replacement, but the current run did not include `--force`.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
+Safe fix: prefer the default `transfer.on_destination_newer: skip` unless replacing newer destination state is intentional. To replace it, keep `transfer.on_destination_newer: replace`, confirm the dry-run output shows `force_replace`, then run with `--force`.
+
+## `force_replace`
+
+Likely cause: the current run used `--force` and publish planning selected a supported destructive replacement.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
+Safe fix: inspect the printed pipeline id, destination id, backend, and bundle path. Proceed only if deleting all content within that destination bundle path is intended.
 
 ## `destination output path collision`