proposal: support deployah rollback

[atkrad]

Problem

Failed upgrades already trigger Helm RollbackOnFailure, but operators cannot deliberately undo a bad successful deploy (wrong image tag, bad config) without re-deploying an older spec by hand or calling helm rollback outside Deployah.

The plumbing exists (session.HelmClient.RollbackRelease, GetReleaseHistory in internal/helm/helm.go) and is unused by any user-facing command. deployah plan / list / status show revision numbers but not a rollback path.

Goals

• deployah rollback <environment> rolls the project release back to a previous Helm revision (default: previous successful revision).
• Optional --revision N to target a specific revision.
• Show what will happen before apply: revision list / confirmation (and --yes for CI).
• Wait with the same timeout / wait strategy as deploy where practical.
• Document that one release = whole project+environment (all components roll back together).
• Clear errors when there is no prior revision, release missing, or rollback in progress.

Non-goals

• Per-component rollback (Deployah uses one Helm release per project/environment today).
• Git-based "rollback the spec file" (user checks out old YAML and deploy; different workflow).
• Changing RollbackOnFailure behavior on deploy (already on).
• Full Helm history browser UI; a simple table is enough.
• Database / PVC data rollback (cluster state outside the release).
• Progressive traffic undo for blue/green (proposal: support blue/green deployments #33) or canary (proposal: support canary deployments #34); those use promote/abort, not Helm revision rollback (though Helm rollback remains a blunt escape hatch).

Proposed design

User experience

# List revisions (either a flag on rollback or a small history command)
deployah rollback staging --history
# REVISION  STATUS      UPDATED              DESCRIPTION
# 5         deployed    2026-07-26 21:00     Upgrade complete
# 4         superseded  2026-07-26 20:00     Upgrade complete
# 3         superseded  2026-07-26 19:00     Rollback to 2

deployah rollback staging              # -> previous successful revision
deployah rollback staging --revision 3
deployah rollback staging --revision 3 --yes

Optional companion:

deployah history staging               # if --history on rollback feels overloaded

Behavior

1. Resolve project + environment -> release name (same as deploy/plan).
2. Load history via existing GetReleaseHistory.
3. Pick target: --revision or newest superseded/deployed revision older than current.
4. Unless --yes, print target revision summary (and optionally a short note that this restores prior rendered manifests, not "git revert").
5. Call RollbackRelease with global --timeout.
6. Success message with new revision (Helm rollback creates a new revision that matches the old config).

Interactions

Concern	Behavior
Extras / CRDs	Rollback restores release manifests; CRDs applied outside normal ownership may not undo. Document.
Hostname guard	Rolling back may restore an older FQDN; decide if rollback should warn when FQDN changes.
Failed latest revision	Default target = last successful; align with LastSuccessfulRelease logic in internal/plan/history.go.
Drift	Out of scope for v1; user can plan after rollback.
Rolling strategy (#19)	Rollback restores prior rendered strategy knobs; it is not a rolling-update control.
Blue/green / canary (#33 / #34)	Prefer promote/abort for traffic; Helm rollback may still restore whole release state.

Failure modes

• No release / fresh install -> error.
• Only one revision -> error ("nothing to roll back to").
• Invalid --revision -> error.
• Rollback while another operation is pending -> surface Helm error clearly.

Alternatives considered

1. Document helm rollback only. Works but breaks the "no Helm knowledge" promise and skips Deployah labels/context resolution.
2. Rollback by re-deploying from git. Good practice, but slow in an incident; complementary, not a substitute.
3. Automatic rollback on failed readiness after success. Different feature (canary/health gates); see proposal: support canary deployments #34.

Compatibility and migration

• Additive CLI; uses existing client methods (RollbackRelease, GetReleaseHistory).
• No spec/schema change.
• Related: proposal: support configuring rolling update strategy #19 (rolling update strategy), proposal: Agent Skills catalog and deployah skills install #28 (skills should teach rollback), proposal: support blue/green deployments #33 (blue/green promote/abort), proposal: support canary deployments #34 (canary abort).

Test plan

• Unit: target revision selection (default previous, explicit N, none available)
• Integration/smoke: deploy v1 -> deploy v2 -> rollback -> status shows prior image/manifest
• Manual: rollback after failed upgrade leaves a usable deployed revision
• Docs: Commands table + note on whole-project rollback and new revision numbers

Checklist

• I searched existing issues and discussions
• This includes enough design detail for implementation (not only a wish)

[atkrad]

Cross-link: Kind-based e2e harness is tracked in #37; broader CLI live coverage is #39.

The deploy v1 → deploy v2 → rollback → status smoke in this test plan is a natural candidate for #39 once the base suite exists.