Changelog 2026-07-09 -- Stage 2 runbook: Office1 headend standup (DOCFIX-154)

No live infrastructure touched -- new runbook document only. Authored by a delegated subagent (general-purpose, briefed with this repo's discipline, the buildout design, D-103/D-106/D-107, the tooling gap register, and the Stage 1 runbook as a style template), reviewed and lint-fixed before this commit.

Item

1. DOCFIX-154 -- runbooks/dc-dc-phase1-office1-standup.md

FILES: runbooks/dc-dc-phase1-office1-standup.md (new), docs/dc-dc- deployment-workflow.md (Stage 2 row updated).

WHAT: command-level runbook for buildout-design Section 4's Phase 1 (Office1 headend standup: MAAS region controller, OpenTofu reach re-verification, NetBox, GitBucket, Tailscale), matching this repo's runbook conventions.

Structural blocker surfaced, not silently resolved: none of the three Office1 service VMs (MAAS-region, NetBox, GitBucket) have an OpenTofu cloudinit-vm instantiation yet -- no image source chosen, no user_data/meta_data/network_config designed. Rather than inventing that content or silently defaulting to a manual path, every VM-creation step presents an explicit Option A (OpenTofu, blocked pending design) vs. Option B (manual virt-install, logged as debt) fork.

Genuine, previously-unnoticed gap found and flagged: no Office1-local virtual network is modeled anywhere in opentofu/ -- main.tf wires office1_pool_path (storage only) and the three inter-site mesh links (management-traffic-only per D-100's own sub-item ruling), but nothing the three service VMs (or the vcloud host's own management interface) could actually attach to as a shared local network. Flagged as an open question for whoever designs the cloudinit-vm content next, not resolved here.

Fixed during review (this session, not the subagent): the subagent's first draft cited the historical D-014 GitBucket path (jesse.austin/ openstack-caracal-ipv4) as context for why THIS stage's GitBucket instance is separate -- correctly sourced, but repo-lint's L2 rule flags that literal string as a "dead repo path" regardless of context (a blunt static check). Reworded onto a single line with the word "historical" so the rule's own existing EXEMPT pattern applies, rather than deleting a legitimate, correctly-attributed historical reference.

VERIFIED: bash scripts/repo-lint.sh 0 fail, 1 documented legacy warn. NOT YET EXECUTED -- authored with no live vcloud host, MAAS, NetBox, GitBucket, or Tailscale reachable this session; every command is written for the operator to run and individually gate later.

Honest exit state, per the runbook's own GATE section: MAAS/GitBucket/ Tailscale/OpenTofu-reach bullets are closeable in one real run; NetBox's "authoritative and populated" bullet is only PARTIAL -- the import mechanism (DOCFIX-152) is runnable, but the underlying literals (org ULA /48, per-DC GUA carve, DC2 supernet) are not assigned this session, so this runbook cannot close that half of Stage 2's gate. This is stated plainly in the runbook rather than rounded up to "done."

REVERT: rm runbooks/dc-dc-phase1-office1-standup.md && git checkout HEAD~ -- docs/dc-dc-deployment-workflow.md (safe -- no infrastructure touched).

Next actionable step

Stage 3's runbook (OpenTofu builds each DC substrate) depends on this stage's MAAS reachability for its own MAAS-registration step -- both were drafted in parallel tonight; Stage 3's runbook correctly states that dependency rather than assuming Stage 2 is done.