MakerFLOSS/notes/dev/plans/2026-06-24-hardware-naming-migration.md

Hardware Naming Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Apply the approved hardware naming scheme by renaming the placeholder compute nodes mf00–mf04 to srv01–srv05, recording cluster membership in frontmatter, and syncing the prose references — leaving all generated artifacts and the drift guard green.

Architecture: Pure data + docs migration; no generator logic changes. The compute files are renamed (git mv), their hostname: field updated to match (the repo enforces filename-stem == hostname), cluster: tappaas added to the one known node, then make docs-index regenerates the hardware index and rack artifacts. Because mf00–mf04 are referenced only by themselves (their power:/links: point outward to pdu*/sw*/pp*, with no reverse references), the rename cascades cleanly through regeneration.

Tech Stack: Markdown frontmatter, Python generators (gen_overview.py, gen_rack.py) run via make, MkDocs Material, pytest.

Spec: docs/guides/hardware-naming-scheme.md.

Global Constraints

• No code changes to scripts/*.py, tests/*, Makefile, CI, mkdocs.yml, or scripts/overview_config.yml. The cluster: field is free-form frontmatter the generators ignore by design; it needs no enum or validation in this migration (the spec defers generator/grouping work).
• Identifier format per the scheme: <kind-abbrev><NN>, 2-digit zero-padded, unique within a kind, starting at 01. Compute = srv.
• A renamed file's hostname: field MUST equal its new filename stem, or gen_overview.py fails (filename stem != hostname).
• Preserve each file's body and all other frontmatter unchanged — only hostname: changes (plus the one added cluster: line).
• cluster: values are provisional except the one known mapping: srv01 (was mf00, "TaPPaaS node 1") → cluster: tappaas. Do not invent cluster values for srv02–srv05; leave the field off them until real assignments are given.
• makerfloss.eu (cloud FQDN) is untouched — it keeps its real hostname and gets no cluster:.
• Test-fixture hostnames in tests/test_gen_rack.py (synthetic mf00/mf01 strings) and the historical phase specs/plans under notes/dev/ are out of scope — they are illustrative/historical, not references to the renamed files.
• After each task: make test passes (49 tests, unaffected — fixtures are synthetic), mkdocs build --strict passes, and make docs-check exits 0.

Name mapping (this migration)

Old file	New file	hostname:	cluster:
mf00.md	srv01.md	srv01	tappaas
mf01.md	srv02.md	srv02	(omit)
mf02.md	srv03.md	srv03	(omit)
mf03.md	srv04.md	srv04	(omit)
mf04.md	srv05.md	srv05	(omit)

---

Task 1: Rename mf00–mf04 → srv01–srv05, add cluster, regenerate

Files:

• Rename: docs/hardware/mf00.md→srv01.md, mf01.md→srv02.md, mf02.md→srv03.md, mf03.md→srv04.md, mf04.md→srv05.md
• Modify (each renamed file): hostname: line; add cluster: tappaas to srv01.md
• Regenerate: docs/hardware/index.md, docs/infrastructure/racks/rack01.md, docs/infrastructure/racks/rack01-elevation.svg

Interfaces:

• Consumes: make docs-index (runs gen_overview.py + gen_rack.py), make test, make docs-check, mkdocs build --strict.

• Step 1: Rename the five files with git mv (preserves history + body)

cd /home/sjat/Projects/MakerFLOSS
git mv docs/hardware/mf00.md docs/hardware/srv01.md
git mv docs/hardware/mf01.md docs/hardware/srv02.md
git mv docs/hardware/mf02.md docs/hardware/srv03.md
git mv docs/hardware/mf03.md docs/hardware/srv04.md
git mv docs/hardware/mf04.md docs/hardware/srv05.md

• Step 2: Update the hostname: field in each renamed file

In each file, change the hostname: line (line 2) to match its new stem. Make exactly these five edits:

• docs/hardware/srv01.md: hostname: mf00 → hostname: srv01
• docs/hardware/srv02.md: hostname: mf01 → hostname: srv02
• docs/hardware/srv03.md: hostname: mf02 → hostname: srv03
• docs/hardware/srv04.md: hostname: mf03 → hostname: srv04
• docs/hardware/srv05.md: hostname: mf04 → hostname: srv05

Do not change any other line in these files.

• Step 3: Add cluster: tappaas to srv01.md only

In docs/hardware/srv01.md, insert a cluster: tappaas line immediately after the status: staging line, so the top of the frontmatter reads:

---
hostname: srv01
kind: server
status: staging
cluster: tappaas
location: The pile

Leave srv02.md–srv05.md without a cluster: field.

• Step 4: Regenerate all indices and rack artifacts

Run: make docs-index Expected: gen_overview.py rewrites docs/hardware/index.md (now listing srv01–srv05 under Servers, no mf0x); gen_rack.py prints Wrote rack01.md + rack01-elevation.svg (9 item(s)). No gen_overview schema error (each stem now matches its hostname).

• Step 5: Confirm no mf0x remains anywhere under docs/

Run: grep -rn -E "mf0[0-4]" docs/ ; echo "exit=$?" Expected: no matches, exit=1 (grep found nothing).

Run: ls docs/hardware/srv0*.md | wc -l Expected: 5.

Run: grep -n "cluster: tappaas" docs/hardware/srv01.md Expected: one match.

• Step 6: Run the full test suite

Run: make test Expected: PASS (49 tests — the suite uses synthetic fixtures and is unaffected by the rename).

• Step 7: Build the site strictly

Run: mkdocs build --strict (if mkdocs is not on PATH, use python3 -m mkdocs build --strict) Expected: build succeeds with no warnings-as-errors. The rack page and hardware index now show srv01–srv05.

• Step 8: Confirm the drift guard is satisfied

Run: make docs-check Expected: exit 0 — committed artifacts match a fresh regeneration.

• Step 9: Commit

git add docs/hardware/ docs/infrastructure/racks/
git commit -m "refactor(hardware): rename mf00-mf04 to srv01-srv05, add cluster field"

---

Task 2: Sync prose references and record the scheme in CLAUDE.md

Files:

• Modify: CLAUDE.md (stale hardware hint + new naming-scheme note)
• Modify: README.md (stale hardware hint)

Interfaces:

• Consumes: grep, make test, make docs-check (sanity).

• Step 1: Fix the stale hardware hint in CLAUDE.md

In CLAUDE.md, change the repository-structure comment line:

  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)

to:

  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)

• Step 2: Add a naming-scheme note to the CLAUDE.md working norms

In CLAUDE.md, immediately after the existing - **Filenames**: … bullet, add this new bullet:

- **Hardware identifiers**: `<kind-abbrev><NN>` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`.

• Step 3: Fix the stale hardware hint in README.md

In README.md, change the repository-layout comment line:

  hardware/       # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu)

to:

  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)

• Step 4: Confirm no stale mf0x hint remains in the two files

Run: grep -n -E "mf0[0-4]" CLAUDE.md README.md ; echo "exit=$?" Expected: no matches, exit=1.

Run: grep -c "Hardware identifiers" CLAUDE.md Expected: 1.

• Step 5: Sanity-check tests and drift still pass

Run: make test Expected: PASS (49 tests).

Run: make docs-check Expected: exit 0 (CLAUDE.md/README.md are not generated artifacts, so this only confirms nothing regressed).

• Step 6: Commit

git add CLAUDE.md README.md
git commit -m "docs: record hardware naming scheme, refresh stale mf0x hints"

---

Self-Review

Spec coverage (docs/guides/hardware-naming-scheme.md):

• Format <kind-abbrev><NN>, srv for compute — Task 1 (rename to srv01–srv05). ✔
• Stable identifier + cluster: in frontmatter — Task 1 (rename + add cluster: tappaas to the one known node). ✔
• srv01 = tappaas; others provisional/omitted — Task 1 Step 3 + Global Constraints. ✔
• makerfloss.eu FQDN exception untouched — Global Constraints (not in the rename set). ✔
• No generator/grouping/validation work (deferred by spec) — Global Constraints (no *.py/config changes). ✔
• Scheme discoverable to contributors — Task 2 (CLAUDE.md note + spec pointer). ✔
• Stale prose hints corrected — Task 2 (CLAUDE.md + README.md). ✔

Placeholder scan: No "TBD"/"handle edge cases"/"similar to Task N". Cluster values for srv02–srv05 are intentionally omitted (real-data dependency, explicitly bounded), not a placeholder.

Type consistency: No code interfaces in this migration. The name mapping table (Task 1) and the hostname: edits (Step 2) are internally consistent: mf00→srv01, mf01→srv02, mf02→srv03, mf03→srv04, mf04→srv05, with cluster: tappaas on srv01 only. Verification greps reference the same srv0x names produced by the edits.