# Implementation Roadmap

This roadmap records current implementation status and deferred work for
`distributor`. Implemented behavior is documented in the user, operator, and
internal documentation listed below.

Canonical current-behavior docs:

- `README.md`
- `docs/cli.md`
- `docs/config.md`
- `docs/operations.md`
- `docs/troubleshooting.md`
- `docs/internal/`
- `docs/integrations/markdown.md`
- `docs/policy/`
- `examples/`

Future, planned, or aspirational behavior belongs under `docs/roadmap/` until
it is implemented.

## Current State

`distributor` is ready for routine use against producer pipelines using the
implemented local, SSH/SFTP, and S3-compatible backends.

Implemented capabilities:

- standard-library CLI commands for `version`, `run`, `validate`, and
  `inspect`;
- YAML config loading, defaults, known-field rejection, and validation;
- local, SSH/SFTP, and S3-compatible source and destination backends;
- structured SSH/SFTP configuration with agent and key-file authentication,
  known-hosts handling, and backend-rooted path confinement;
- S3-compatible configuration with endpoint, region, addressing mode, TLS
  controls, credential environment references, streaming reads and writes,
  listing, metadata, and managed deletion;
- top-level `secrets.directory` loading for credential values, with process
  environment precedence and without mutating the process environment;
- backend-rooted storage interfaces with typed errors, safe logical paths,
  traversal, collision checks, managed deletion, and explicit forced
  replacement;
- source bundle discovery, manifest parsing, RFC3339 timestamp handling,
  duplicate path checks, path safety checks, symlink rejection, per-file digest
  validation, and bundle digest validation;
- destination `.distributor.json` state parsing, validation, output metadata,
  and source comparison;
- publication of source files, Markdown sidecar HTML, or both;
- destination output collision detection before writes;
- managed replacement for older destination state;
- conservative conflict failures by default for unmanaged destination content
  and conflicting managed destination content;
- explicit forced replacement with `run --force`, limited to the configured
  destination bundle path;
- deterministic dry-run output and final run summaries;
- deterministic sequential fan-out with aggregated destination failures;
- cleanup of outputs written during failed publish attempts where practical;
- no-op notification hook after successful publish or replacement;
- current user, operator, internal, integration, and development documentation
  for implemented behavior.

## Active Roadmap

There are no active implementation items in this roadmap.

Before implementing new product behavior, add a focused roadmap entry when the
work changes storage semantics, config, CLI behavior, state schema, transform
behavior, notification behavior, operational safety, or user-visible workflows.
Keep those entries out of current-behavior docs until the behavior exists.

## Deferred Work

These items are not implemented and should stay out of current-behavior docs
until a roadmap entry is selected and implemented:

- external notification adapters;
- warning-only digest mismatch handling;
- additional auth mechanisms beyond the implemented SSH and S3 credential
  paths;
- compatibility parsing for legacy SSH URI config;
- broad recursive destination deletion outside managed bundle paths;
- concurrent fan-out publishing;
- resumable multipart S3 uploads;
- cloud-provider-specific IAM integration docs;
- repository-managed packaging, release, and deployment automation.

## Roadmap Maintenance

When adding future roadmap work:

- describe user-visible behavior and safety boundaries;
- define which existing docs must change after implementation;
- keep examples secret-free and runnable or clearly environment-gated;
- avoid workflow labels in production code, tests, config fields, and user
  documentation;
- run focused tests for the changed behavior and `go test ./...` for
  cross-package changes.