CR-2026-04-03: VyOS Runbook Decomposition into Project Hierarchy

Change Summary

Field Value

CR ID

CR-2026-04-03-001

Date

2026-04-03

Priority

P2: Important

Type

Documentation Restructure

Status

Approved

Requestor

Evan Rosado

Implementor

Evan Rosado

Target Repo

domus-infra-ops

Objective

Decompose runbooks/domusdigitalis-vyos-migration.adoc (758 lines) from a monolithic runbook into a multi-page project structure with thin wrapper pages and granular partials. This establishes the first subdirectory-based project in domus-infra-ops, matching the pattern proven in domus-captures (ThinkPad T16g deploy, Kora CLI, ISE 3.4 Migration).

Justification

Business Case

The VyOS migration is a completed infrastructure project (pfSense decommissioned 2026-03-07), not an active runbook. Treating it as a runbook creates three problems:

  1. Maintenance burden — 758 lines in a single file makes targeted updates painful. Updating one milestone’s status requires scrolling through 400+ lines of unrelated content.

  2. No reusability — Tables (SPOF inventory, HA deployment status) are trapped inside the monolith. Other docs can’t reference them via include::partial$.

  3. Pattern inconsistency — domus-captures projects use thin wrappers + partials. domus-infra-ops has zero multi-page projects. This creates cognitive overhead when switching between repos.

What This Enables

  • Independent updates to any phase without touching other phases

  • Reusable partials (SPOF table, HA deployment status) includable from other docs

  • Navigation that shows project structure at a glance (13 nav entries vs 1)

  • Sets the pattern for future domus-infra-ops projects (Vault PKI, k3s Platform, etc.)

Current State vs Target State

Component Current (Before) Target (After)

File structure

Single 758-line file at runbooks/domusdigitalis-vyos-migration.adoc

13 thin wrapper pages in projects/vyos-migration/ + 31 partials in partials/projects/vyos-migration/

Navigation

Single entry under Runbooks > Firewall & WAN (line 211)

15-entry hierarchy under Projects > Migrations with phases, rollback, reference, decisions, field notes

Content ownership

All content inline — monolithic

Each logical unit in its own partial — independently updatable

Partials

0 project-specific partials (existing vyos-*.adoc are infrastructure data, untouched)

31 new partials under partials/projects/vyos-migration/

Project pattern

No multi-page projects in domus-infra-ops

First multi-page project — sets the standard

Scope

In Scope

  • Create pages/projects/vyos-migration/ with 13 thin wrapper pages

  • Create partials/projects/vyos-migration/ with 31 content partials

  • Move validation script to examples/vyos/migration-final-validation.sh

  • Create 4 new content partials (status-dashboard, metadata, decisions, field-notes)

  • Update nav.adoc — remove old runbook entry, add project hierarchy

  • Delete the old monolith

Out of Scope

  • runbooks/vyos-deployment.adoc — untouched (includes existing vyos-*.adoc partials)

  • Existing partials/vyos-*.adoc files — infrastructure data, not project structure

  • Content changes — this is a restructure, not a rewrite

  • Other domus-infra-ops projects — they stay as single-file for now

What Stays Untouched

  • runbooks/vyos-deployment.adoc and all its partial includes

  • All existing partials/vyos-*.adoc files (infrastructure data)

  • All xref targets referenced in the monolith (runbook links still valid)

  • examples/vyos/ existing content

File Inventory

New Files (44 total)

Category Count

Thin wrapper pages

13

Extracted partials

22

New content partials

4

Example scripts

1

Total new files

44 [1]

Deleted Files (1)

  • pages/runbooks/domusdigitalis-vyos-migration.adoc

1. Replaces 1 monolithic file