# Changelog 2026-07-09 -- Stage 4 runbook: MAAS enlist/commission/deploy per DC (DOCFIX-157)

No live infrastructure touched -- new runbook document only. Authored by a
delegated subagent (general-purpose, briefed with this repo's discipline,
D-103/D-100/D-107, the tooling gap register, `phase-00-teardown-maas-
reset.md` and `scripts/lib-net.sh`/`lib-hosts.sh` as primary sources),
reviewed before this commit -- repo-lint was clean on the first pass.

## Item

### 1. DOCFIX-157 -- `runbooks/dc-dc-phase3-maas-enlist-deploy.md`
FILES: `runbooks/dc-dc-phase3-maas-enlist-deploy.md` (new), `docs/dc-dc-
deployment-workflow.md` (Stage 4 row updated, tooling gap register items
11/12/13/14/15 added or corrected).

WHAT: adapts `phase-00-teardown-maas-reset.md`'s validated single-rack
MAAS commission/deploy/carve sequence to VR1's multi-rack, per-DC shape.
Run once per `$DC` (dc1/dc2), explicitly not mixed in one shell session.

**Mandates the `$DC` selector convention as its first real step** --
`lib_net_select_dc "$DC"` (a documented no-op for dc1, fail-loud for dc2)
followed HONESTLY by `lib_hosts_select_dc "$DC"`, which the runbook states
is EXPECTED TO FAIL for both DCs right now: no per-DC host data exists in
`scripts/lib-hosts.sh` yet, and populating it from THIS stage's own real
enrollment is exactly the follow-up delivery that lets the selector start
passing. This is documented as a deliberate chicken-and-egg, not a bug to
route around -- every step in the runbook resolves host identity LIVE from
MAAS instead.

**Seven real gaps found and named in a dedicated section, each logged as a
finding rather than silently worked around:**
1. No OpenTofu module stands up a per-DC MAAS rack controller VM itself --
   only registration (`modules/maas-vm-host`) exists.
2. `reenroll-hosts.sh`, `carve-host-interfaces.sh`, and `phase-00-maas-
   standup.sh` do not accept a `$DC` argument or call the new selector
   functions -- only `lib-net.sh`/`lib-hosts.sh` themselves gained them
   (DOCFIX-151). The runbook describes adapting each script's MECHANICS by
   hand rather than inventing a `--dc` flag those scripts don't have.
3. Per-DC node count/sizing is an unmade Phase-0 decision -- the runbook
   discovers however many nodes actually exist live (Step 2), never
   assuming DC0's four hosts carry over.
4. DC2 is additionally blocked at the `lib_net_select_dc` layer (no NetBox
   literals yet).
5. The per-DC artifact mirror (D-107) has no identified owning stage/
   module anywhere in this repo as surveyed -- flagged before Step 7's
   reachability check assumes one exists.
6. The MAAS status a VM-host-DISCOVERED (vs. PXE-enlisted) pre-existing
   domain lands in has never been observed in this repo -- Step 2 measures
   it live rather than assuming `New` or an auto-`Ready` per phase-00's
   different code path.
7. `lib-hosts.sh`'s `HOST_TAG`/boot-fabric-name literals (`openstack`,
   `2_metal`) are DC0-specific -- confirmed live per DC, not assumed reused.

**A real sequencing subtlety flagged, not glossed over:** phase-00's own
precedent carves interfaces BEFORE deploy (Ready-only); if Stage 3's
discovery+commission flow for a DC leaves nodes at `Ready` before this
stage's carve step, the runbook instructs reordering Steps 4/5 to match
phase-00's actual order and recording which order was used, rather than
blindly following this document's own numbering against contradicting live
machine states.

VERIFIED: `bash scripts/repo-lint.sh` 0 fail, 1 documented legacy warn (no
fixes needed). NOT YET EXECUTED.

REVERT: `rm runbooks/dc-dc-phase3-maas-enlist-deploy.md && git checkout
HEAD~ -- docs/dc-dc-deployment-workflow.md` (safe).

## Next actionable step

This stage's own delivery checklist requires populating `scripts/lib-
hosts.sh` with real per-DC host data once it actually runs -- that follow-
up unblocks `lib_hosts_select_dc` for the DC it ran against and is a
prerequisite named explicitly in Stage 5's own runbook.