# AWP I7a Machine Enrollment Acceleration — 2026-08-24

**Status:** COMPLETE — LANDED, DEPLOYED, READY FOR ONBOARDING
**Base authority:** `AWP-INCREMENTAL-DELIVERY-PLAN.md`, `AWP-INCREMENT-REALIZATION-MATRIX.md`
**Scope:** machine enrollment only; the remainder of I7 stays deferred.

## Decision

AWP needs to onboard a new physical machine while I2 is in progress. The already-specified machine-enrollment capability is therefore activated early as **I7a — Machine Enrollment MVP**. This is an intentional priority amendment, not accidental future-scope drift and not part of I2.

I7a runs in an isolated branch/worktree from current canonical `origin/main`. It must not depend on unmerged I2 implementation and must not change I2's Planning/Goal boundaries. Shared changes are limited to stable cross-increment contracts and must remain forward-compatible with full I7.

## I7a Scope

```text
Cluster -> Add Machine
  -> hostname/IP + SSH identity/auth + optional labels
  -> durable enrollment request
  -> preflight
       SSH/connectivity
       supported OS + architecture
       CPU/RAM/disk
       required network/ports
       existing Kubernetes/K3s state
       existing/foreign cluster membership
  -> explicit preflight result
  -> install/configure supported K3s worker role
  -> join the configured AWP Cluster
  -> wait for Kubernetes node registration
  -> verify Ready/network/scheduling/runtime
  -> discover + persist MachineCapability
  -> Machine ready + visible
```

I7a is deliberately worker-node enrollment first. K3s server/control-plane expansion is not required for this acceleration unless separately authorized.

## Security / Recovery Invariants

- SSH authentication remains behind `Connection` / `CredentialReference`; raw private keys/passwords are not persisted on `Machine` or enrollment records.
- The K3s join credential is projected only to the trusted enrollment boundary and is not exposed to AgentRuns.
- Enrollment has stable operation identity and is resumable/idempotent.
- Preflight detects already-correct enrollment, foreign-cluster ownership, unsupported hosts, conflicting runtime state and partial prior installation before mutation.
- Retry reconciles observed state first; it never blindly reinstalls K3s.
- Failed/partial enrollment remains visible with actionable state.
- Existing I1 execution isolation, immutable image pull and trusted-control boundaries remain unchanged.

## Explicitly Deferred to Full I7

The acceleration does **not** pull forward the rest of the Cluster product surface:

- rich capacity dashboards and historical metrics;
- generalized placement explainability / capacity-aware Queue UX;
- drain, maintenance and removal product flows beyond safety hooks required by enrollment;
- automated K3s upgrade lifecycle;
- multi-cluster/fleet management;
- cloud/tenant enrollment adapters;
- polished full Cluster page states beyond the minimal owner-facing enrollment surface.

## I7a Acceptance Gate

I7a is `READY FOR ONBOARDING`; all of the following are evidenced on landed canonical main and the live dogfood runtime:

- [x] canonical plan/spec timing is amended consistently;
- [x] clean supported-host preflight is implemented;
- [x] already-enrolled/foreign/partial-state detection is implemented and non-destructive;
- [x] credential material is not stored in machine/enrollment product state;
- [x] enrollment survives/reconciles retry with stable operation identity;
- [x] K3s worker join uses the configured canonical AWP cluster endpoint/credential;
- [x] Kubernetes node registration and `Ready` verification are implemented;
- [x] machine/capability state is durably persisted and readable;
- [x] an owner-facing Add Machine path can start and inspect enrollment without hand-running K3s commands;
- [x] focused unit/integration/security/regression tests pass;
- [x] existing I1/I2-independent architecture boundaries remain green;
- [x] a non-destructive live preflight against an existing cluster node proves existing-membership detection, or equivalent live evidence is recorded;
- [x] the exact onboarding command/UI path and machine prerequisites are documented.

Until this gate is green, the existing manual operator bootstrap remains the fallback and must not be removed.

## Parallel-Lane Rule

I7a may progress concurrently with I2 because it owns separate cluster/enrollment paths. If I2 changes shared contracts on `main`, this lane rebases/merges current `origin/main` deliberately and resolves only its own conflicts. It must not edit or overwrite the Slice 2 worktree.