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)**

```bash
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:

```yaml
---
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**

```bash
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:

```markdown
- **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**

```bash
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.