harmony/ROADMAP.md

# Harmony roadmap

This file is the current priority index. Detailed plans under `ROADMAP/` are
working documents, not architecture decisions. The status written in an ADR's
body is authoritative; fix any mismatch with the ADR index before relying on
it.

## Current sprint

The sprint goal is a production release of Harmony Fleet with deployment code
that meets Harmony's UX/DX standard.

1. Keep the closed PR knowledge available without reviving its implementations.
   See [the July 2026 PR archive](ROADMAP/pr-archive-2026-07.md).
2. Make `harmony-fleet-deploy` the clear path for deploying the
   production Fleet release. Reduce setup friction and remove accidental
   complexity without redesigning the framework during cleanup.
3. Validate the real production composition from a clean client: explicit
   target, noninteractive configuration, stable credentials, visible platform
   prerequisites, and truthful readiness reporting.
4. Cut and validate the next customer release.
5. Add production-equivalent Fleet deployment E2E to CI/CD immediately after
   that release, using a dedicated test cluster.

## Framework direction

Use Fleet deployment as the current UX/DX case for framework changes. Simplify
and release `harmony-fleet-deploy` before applying those changes to
`harmony_app` or another client application.

Work in this area should:

- reuse existing Scores and capabilities before adding layers;
- keep app-specific behavior in deploy crates;
- move logic into Harmony only when it is demonstrably reusable;
- prefer small extractions, such as duplicated Helm/context handling, as
  separate changes;
- leave unresolved architecture choices to focused design work.

## Deployment UX/DX bar

These are evaluation criteria, not settled API decisions.

- A new contributor can find the deploy path from the repository root and run
  the documented local path from a clean checkout.
- The same declaration drives local, E2E, and production deployment. The
  context supplies target-specific access and policy.
- Production always has an explicit target. Scripts and agents never encounter
  a hidden prompt or an implicit fallback.
- Common work is visible in `--help` and examples. Users should not need branch
  history, a specific checkout layout, or undocumented platform knowledge.
- Human output is concise and actionable. Automation gets stable exit codes and
  machine-readable results without scraping terminal decoration.
- Errors identify the failed component, expected state, observed state, and a
  useful next action. A successful command must not claim more readiness than
  it verified.
- Deploy code reads as application and platform intent. Kubernetes, Helm, and
  identity-provider details stay in the owning module unless the application
  genuinely needs to choose them.
- Humans and LLMs use the same documented interface. Do not build a parallel
  agent API to compensate for an ambiguous CLI or deployment model.

This follows established CLI practice around discoverability, explicit remote
actions, noninteractive execution, stdout/stderr separation, and structured
output. See the [Command Line Interface Guidelines](https://clig.dev/).

## Evidence from a real application

A review of a real client application found useful evidence, but its proposed
APIs are not accepted designs.

Verified against current code:

- The short `ComposeDeploy` example does not yet cover the real application,
  which still assembles lower-level Scores.
- `ComposeDeploy` supports one public endpoint. Capability environment wiring
  applies to every Compose service, PostgreSQL exports one fixed variable, and
  the current Zitadel capability covers only a simple PKCE application.
- The real deploy still duplicates namespace-derived names and some provider
  conventions. Those are concrete DRY problems.
- The application layer does not yet prove its full readiness claim; Helm
  acceptance is not application smoke-test success.
- The current app CLI has human-only, decorated output and no stable machine
  format. Its agent and CI contract remains design work.
- Several onboarding defects in the original review have since been fixed,
  including the branch dependency, vault path, OIDC redirect, and unsafe
  production refresh-key fallback.

Ideas such as a generic environment-wiring API, typed Score outputs, a generic
secret loader, a Compose macro, a namespace topology marker, or a broad Zitadel
capability need focused design and another real use case. Fleet does not use
those application abstractions and does not validate them.

## Decisions requiring project-lead review

These remain undecided:

- readiness and idempotency contracts;
- the long-term crate and `harmony` core boundaries;
- ADR-024 fleet decomposition;
- ADR-026 application CLI contract;
- the final production Fleet composition and context shape.

## Active supporting tracks

| Track | Document | Status |
|---|---|---|
| Fleet production hardening | [Fleet v0.3](ROADMAP/fleet_platform/v0_3_plan.md) | Needs revalidation against current code and ADR-025 |
| Config consolidation | [Config crate](ROADMAP/01-config-crate.md), [migration](ROADMAP/02-refactor-harmony-config.md) | In progress |
| Application CLI | [Unified CLI](ROADMAP/13-unified-cli.md) | Design input; reconcile with ADR-026 before implementation |
| Core cleanup | [April code review](ROADMAP/12-code-review-april-2026.md) | Backlog; verify each item before work |
| Monitoring | [Tenant application monitoring](ROADMAP/14-tenant-application-monitoring.md) | Design pending |
| OPNsense and bare metal | [OPNsense](ROADMAP/07-opnsense-bare-metal.md), [HA production](ROADMAP/08-ha-okd-production.md) | Separate customer track |

## Deferred plans

The remaining numbered plans are retained as backlog and historical context:

- [Assets](ROADMAP/03-assets-crate.md)
- [GitHub publication](ROADMAP/04-publish-github.md)
- [Simple E2E](ROADMAP/05-e2e-tests-simple.md)
- [KVM E2E](ROADMAP/06-e2e-tests-kvm.md)
- [SSO and config hardening](ROADMAP/09-sso-config-hardening.md)
- [Firewall pair topology](ROADMAP/10-firewall-pair-topology.md)
- [Named config instances](ROADMAP/11-named-config-instances.md)

Do not infer priority from the phase number. Revalidate a plan against current
code and accepted ADRs before implementing it.