From 01e408f4d518f7b91a3202ca81b43829e4951c28 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 31 May 2026 17:31:49 +0000 Subject: [PATCH] Align readiness policies with implemented behavior --- docs/internal/config.md | 2 +- docs/policy/architecture.md | 6 ++++-- docs/policy/development.md | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/internal/config.md b/docs/internal/config.md index e76a50c..2a4a0da 100644 --- a/docs/internal/config.md +++ b/docs/internal/config.md @@ -51,7 +51,7 @@ S3 config requires `endpoint` and `bucket`, normalizes optional `prefix`, defaul The resolver checks the real process environment first and loaded secret values second. Differing process/secret conflicts are reported by variable name only. The resolver does not mutate `os.Environ`; default SDK credential chains continue to see only real process environment values. -Future credential-consuming backend code should resolve explicit credential environment variable references through `Environment.ResolveCredentials` or the same resolver pattern instead of calling `os.Getenv` directly. +Credential-consuming backend wiring should resolve explicit credential environment variable references through `Environment.ResolveCredentials` or the same resolver pattern instead of calling `os.Getenv` directly. The user-facing configuration reference is `docs/config.md`; this file documents package behavior for maintainers. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 3b5583b..b3a65b2 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -274,9 +274,11 @@ If the application writes durable state, writes should be atomic where practical Code that deletes, moves, or overwrites files must use narrow, explicit paths. Avoid broad parent-directory operations. Cleanup that can cause data loss must be opt-in. -`distributor` must never perform broad deletion against a configured source root or destination root. Destructive replacement may occur only inside a resolved destination bundle path when a valid `.distributor.json` confirms that the path is distributor-managed. +`distributor` must never perform broad deletion against a configured source root. Destination deletion must be bounded to the resolved destination bundle path for the current source bundle and backend root. -Replacement must be narrow, logged, test-covered, and configurable. Prefer deleting files recorded in `.distributor.json` and known generated outputs rather than blindly deleting parent directories. Backend implementations must guard against path traversal, prefix confusion, and accidental root deletion. +Normal destructive replacement may occur only when a valid `.distributor.json` confirms that the destination bundle path is distributor-managed. Explicit forced replacement is a per-run CLI workflow for supported conflict and unmanaged-content cases; it must be dry-runnable, clearly reported, and constrained to the destination bundle path. + +Replacement must be narrow, reported, test-covered, and configurable. Prefer normal replacement that deletes files recorded in `.distributor.json` and known generated outputs. Forced replacement may delete a bounded destination bundle prefix only when the operator explicitly requests it. Backend implementations must guard against path traversal, prefix confusion, and accidental deletion above the configured backend root. Where practical, publish operations should use staging paths or temporary objects and promote them into place only after validation and transform steps succeed. diff --git a/docs/policy/development.md b/docs/policy/development.md index aae8e25..0876a8d 100644 --- a/docs/policy/development.md +++ b/docs/policy/development.md @@ -16,7 +16,7 @@ Use it with `docs/policy/architecture.md` and `docs/policy/documentation.md`. - `internal/adapters/ssh`: SSH/SFTP backend. - `internal/adapters/s3`: S3-compatible object storage backend. - `internal/storage/fake`: in-memory backend for tests. -- `internal/publish`: destination inspection, output planning, reconciliation, execution, and managed cleanup. +- `internal/publish`: destination inspection, output planning, reconciliation, execution, managed cleanup, and explicit forced replacement. - `internal/transform`: transform interface and registry. - `internal/transform/markdown`: Markdown-to-HTML sidecar transform. - `internal/notify`: notification interface and current no-op notifier.