docs: decide upgrade lifecycle direction (spike)

[dan2k3k4]

Adds a decision note on the currently-stubbed upgrade lifecycle: it is unreachable in production today, so no guard is added and implementation is staged for later. Docs only.

Greptile Summary

This PR adds a decision note documenting the outcome of a spike on the upgrade lifecycle in plans/notes/012-upgrade-lifecycle-decision.md. It establishes that the upgrade path (PENDING_PRE_UPGRADE and onward) is entirely unreachable in production today — no UI action, console command, API endpoint, or state-machine transition can enter it — so no guard is added, and implementation is deferred with a staged follow-up plan.

• Adds a 138-line analysis covering reachability vectors (Filament actions, console commands, API routes, state machine), the silent-stall mechanism in the stub jobs, and an implementation cost estimate.
• Recommends documenting the latent hazard now and deferring the actual upgrade wiring to a 4-stage follow-up (plumbing → upgrade action → polling → entry point), ensuring the entry point is only added last once the full chain is green.

Confidence Score: 5/5

Docs-only change with no production code modified; safe to merge.

The change is a single new markdown file containing a decision note. No source code, migrations, tests, or configuration are touched. The analysis itself is thorough — it cross-checks reachability across Filament actions, console commands, API routes, and the state machine, and the staged follow-up plan is logically sound. The only cosmetic concern is that the inline git diff --stat b6f2ff09d195..HEAD drift-check command will silently go stale as the repository evolves, but this has no runtime impact.

No files require special attention.

Important Files Changed

Filename	Overview
plans/notes/012-upgrade-lifecycle-decision.md	New documentation-only decision note; no code changed. Well-structured analysis of upgrade lifecycle reachability with clear recommendation and staged follow-up plan.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Admin / API / Console] -->|"No trigger_upgrade action exists"| B{Entry Point?}
    B -- "TODAY: None" --> C[❌ Unreachable\nPENDING_PRE_UPGRADE]
    B -- "Stage D future" --> C2[✅ trigger_upgrade action\nguarded to RUNNING_HEALTHY_*]
    C2 --> D[PENDING_PRE_UPGRADE]

    D --> E[PreUpgradeJob\n⚠️ stub – silent stall]
    E -->|"Stage A: add executeTransition"| F[PRE_UPGRADE_RUNNING\nPreUpgradeAppInstanceTrait ✅]
    F --> G[PRE_UPGRADE_COMPLETED]
    G --> H[UpgradeJob\n⚠️ stub]
    H -->|"Stage B: real Lagoon call"| I[UPGRADE_RUNNING\nUpgradeAppInstanceTrait 🔧]
    I --> J[UPGRADE_COMPLETED]
    J --> K[PostUpgradeJob\n⚠️ stub]
    K -->|"Stage B: implement"| L[POST_UPGRADE_COMPLETED\nPostUpgradeAppInstanceTrait 🔧]
    L --> M[PollUpgradeJob\n⚠️ stub]
    M -->|"Stage C: polling"| N[ProgressToNextStageJob\nalready routes correctly ✅]
    N --> O[RUNNING_HEALTHY_*]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Admin / API / Console] -->|"No trigger_upgrade action exists"| B{Entry Point?}
    B -- "TODAY: None" --> C[❌ Unreachable\nPENDING_PRE_UPGRADE]
    B -- "Stage D future" --> C2[✅ trigger_upgrade action\nguarded to RUNNING_HEALTHY_*]
    C2 --> D[PENDING_PRE_UPGRADE]

    D --> E[PreUpgradeJob\n⚠️ stub – silent stall]
    E -->|"Stage A: add executeTransition"| F[PRE_UPGRADE_RUNNING\nPreUpgradeAppInstanceTrait ✅]
    F --> G[PRE_UPGRADE_COMPLETED]
    G --> H[UpgradeJob\n⚠️ stub]
    H -->|"Stage B: real Lagoon call"| I[UPGRADE_RUNNING\nUpgradeAppInstanceTrait 🔧]
    I --> J[UPGRADE_COMPLETED]
    J --> K[PostUpgradeJob\n⚠️ stub]
    K -->|"Stage B: implement"| L[POST_UPGRADE_COMPLETED\nPostUpgradeAppInstanceTrait 🔧]
    L --> M[PollUpgradeJob\n⚠️ stub]
    M -->|"Stage C: polling"| N[ProgressToNextStageJob\nalready routes correctly ✅]
    N --> O[RUNNING_HEALTHY_*]

Loading

_{Reviews (1): Last reviewed commit: "docs: decide upgrade lifecycle direction..." | Re-trigger Greptile}