boma/docs/superpowers/plans/2026-06-01-hardware-capacity.md

Hardware Reference & Capacity Evaluation 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: Add a hand-maintained hardware reference doc, a stdlib-only capacity-scan.py that emits deterministic capacity facts, and an on-demand /capacity-review skill that reasons about HA / right-sizing / placement / upgrade timing.

Architecture: docs/hardware/reference.md is the single machine-readable source of truth (physical node capacities + workload allocations + placement intent). scripts/capacity-scan.py parses its tables, computes per-node allocated-vs-physical rollups, and cross-checks workload hostnames against terraform output -json / ansible-inventory --list to surface drift — degrading gracefully when nothing is provisioned. /capacity-review runs the scan, reads the intent columns, and writes a dated report to docs/hardware/reviews/. Live usage stats are a stubbed future hook. Mirrors the existing repo-scan.py → /review-repo → docs/reviews/ triad.

Tech Stack: Python 3 standard library only (no third-party imports in the script); pytest for unit tests (already in requirements.txt); markdown docs; a .claude slash-command skill.

---

Spec

Design spec: docs/superpowers/specs/2026-06-01-hardware-capacity-design.md.

Refinement vs spec: the spec said allocations come from Terraform. The current terraform output "vms" only exposes {ip, group}, not cores/RAM/disk, so numeric allocations are read from reference.md instead; Terraform/inventory are used only for hostname-drift cross-checks. This better honors the "self-contained markdown source of truth" decision and needs no Terraform module changes.

File Structure

• docs/hardware/reference.md — create. Source of truth. Human sections (physical compute, network gear) + two machine-readable tables (node capacity, workload placement) the script parses.
• scripts/capacity-scan.py — create. Stdlib-only. Pure parse/math functions
  • thin subprocess glue + main() emitting JSON to stdout.
• tests/test_capacity_scan.py — create. Pytest unit tests for the pure functions + a smoke test against the real reference.md.
• .claude/commands/capacity-review.md — create. The /capacity-review skill.
• docs/hardware/reviews/.gitkeep — create. Report output dir.
• docs/decisions/012-hardware-capacity.md — create. ADR recording the decision.
• STATUS.md — modify. Add real-vs-planned rows.
• CLAUDE.md — modify. Commands-table row + Further-reading pointer.
• scripts/README.md — modify. Document capacity-scan.py.

Machine-readable table contract (used by Task 1 and the parser)

reference.md must contain these two tables verbatim in header shape. The parser keys on header names, so column order is flexible and extra free-text columns are ignored.

Node capacity — header contains node, cores, ram_gb, disk_gb (integers/floats):

| node | cores | ram_gb | disk_gb |
|------|-------|--------|---------|
| pve0 | 20    | 64     | 4000    |

Workload placement — header contains the numeric columns workload, node, cores, ram_mb, disk_gb plus any free-text intent columns:

| workload | node | cores | ram_mb | disk_gb | criticality | ha_intent | profile | constraints | growth |
|----------|------|-------|--------|---------|-------------|-----------|---------|-------------|--------|
| dns1     | pve0 | 1     | 512    | 10      | high        | pair/dns2 | tiny    | anti-affinity: dns2 elsewhere | flat |

---

Task 1: Reference doc skeleton

Files:

• Create: docs/hardware/reference.md

• Create: docs/hardware/reviews/.gitkeep

• Step 1: Write docs/hardware/reference.md

# Hardware reference — boma

> Hand-maintained source of truth for **physical** compute + network gear and
> **workload placement intent**. The two machine-readable tables (Node capacity,
> Workload placement) are parsed by `scripts/capacity-scan.py` — keep their
> headers intact. Evaluated by `/capacity-review`. See ADR-012.
>
> _Status: skeleton. Replace example rows with real hardware once the cluster is
> stood up (STATUS.md tracks real-vs-planned)._

## 1. Physical compute

### pve0
- **Model / form factor:** _TBD (e.g. Minisforum MS-01, mini-PC)_
- **CPU:** _TBD (e.g. i9-13900H, 14C/20T)_
- **RAM:** _TBD total; max _; free DIMM slots _
- **Storage:** _TBD (disks → pools, e.g. 2× 2 TB NVMe → `local-zfs`)_
- **NICs:** _eno1 trunk (vmbr0), eno2 corosync (vmbr1)_
- **Notes:** _warranty, quirks_

_(repeat for pve1, pve2, askari)_

## 2. Network gear

| device   | model | ports | poe | throughput | uplinks | notes |
|----------|-------|-------|-----|------------|---------|-------|
| opnsense | _TBD_ | _TBD_ | n/a | _TBD_      | WAN+LAN | dedicated hardware |
| switch   | _TBD_ | _TBD_ | _TBD_ | _TBD_    | trunk   | managed, 802.1q |
| ap1      | _TBD_ | _TBD_ | _TBD_ | _TBD_    | trunk   | multi-SSID per VLAN |

## 3. Workload placement & intent

The numeric columns (`cores, ram_mb, disk_gb`) feed `capacity-scan.py`; the
free-text columns feed `/capacity-review`'s judgement.

| workload | node | cores | ram_mb | disk_gb | criticality | ha_intent | profile | constraints | growth |
|----------|------|-------|--------|---------|-------------|-----------|---------|-------------|--------|
| dns1     | pve0 | 1     | 512    | 10      | high        | pair/dns2 | tiny/steady | anti-affinity: dns2 on a different node | flat |
| dns2     | pve1 | 1     | 512    | 10      | high        | pair/dns1 | tiny/steady | anti-affinity: dns1 on a different node | flat |

## 4. Node capacity (machine-readable)

Physical totals per node. Integers; `ram_gb` and `disk_gb` may be decimals.

| node | cores | ram_gb | disk_gb |
|------|-------|--------|---------|
| pve0 | 20    | 64     | 4000    |
| pve1 | 20    | 64     | 4000    |

## 5. Capacity notes

Free-text running notes for the evaluator (trends, planned moves, upgrade ideas).

• Step 2: Create the reports directory

Run: mkdir -p docs/hardware/reviews && touch docs/hardware/reviews/.gitkeep Expected: both paths exist.

• Step 3: Verify the machine-readable headers match the contract

Run: grep -n '| node | cores | ram_gb | disk_gb |' docs/hardware/reference.md && grep -n '| workload | node | cores | ram_mb | disk_gb |' docs/hardware/reference.md Expected: each grep prints one matching line (the table headers the parser keys on).

• Step 4: Commit

git add docs/hardware/reference.md docs/hardware/reviews/.gitkeep
git commit -m "Add hardware reference doc skeleton + reviews dir"

---

Task 2: Scan script — parse_table()

Files:

• Create: scripts/capacity-scan.py

• Create: tests/test_capacity_scan.py

• Step 1: Write the failing test

Create tests/test_capacity_scan.py:

import importlib.util
import pathlib

_PATH = pathlib.Path(__file__).resolve().parent.parent / "scripts" / "capacity-scan.py"
_spec = importlib.util.spec_from_file_location("capacity_scan", _PATH)
cs = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(cs)


def test_parse_table_keys_on_header_and_ignores_extra_cols():
    md = """
intro text
| node | cores | ram_gb | disk_gb |
|------|-------|--------|---------|
| pve0 | 20    | 64     | 4000    |
| pve1 | 20    | 64     | 4000    |

trailing text
"""
    rows = cs.parse_table(md, ["node", "cores", "ram_gb", "disk_gb"])
    assert rows == [
        {"node": "pve0", "cores": "20", "ram_gb": "64", "disk_gb": "4000"},
        {"node": "pve1", "cores": "20", "ram_gb": "64", "disk_gb": "4000"},
    ]


def test_parse_table_returns_empty_when_header_absent():
    assert cs.parse_table("no tables here", ["node", "cores"]) == []

• Step 2: Run test to verify it fails

Run: python3 -m pytest tests/test_capacity_scan.py -v Expected: FAIL — ModuleNotFoundError/AttributeError (script or parse_table not defined yet).

• Step 3: Write minimal implementation

Create scripts/capacity-scan.py:

#!/usr/bin/env python3
"""capacity-scan.py — deterministic capacity facts for /capacity-review.

Python standard library only. Emits a JSON object to stdout.

Reads physical capacities and workload allocations from the machine-readable
tables in docs/hardware/reference.md, computes per-node allocated-vs-physical
rollups, and cross-checks workload hostnames against `terraform output -json`
and `ansible-inventory --list` to surface drift. Degrades gracefully when
nothing is provisioned. Live usage stats are a documented future hook.

Usage: python3 scripts/capacity-scan.py [--env staging] [--reference PATH]
"""
import argparse
import json
import os
import subprocess
import sys

REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))


def parse_table(markdown, required_cols):
    """Return row dicts for the first markdown table whose header contains all
    required_cols. Keys are header names; values are raw cell strings."""
    lines = markdown.splitlines()
    required = set(required_cols)
    for i, raw in enumerate(lines):
        line = raw.strip()
        if not line.startswith("|"):
            continue
        headers = [c.strip() for c in line.strip("|").split("|")]
        if not required.issubset(set(headers)):
            continue
        rows = []
        for body in lines[i + 2:]:
            if not body.strip().startswith("|"):
                break
            cells = [c.strip() for c in body.strip().strip("|").split("|")]
            if len(cells) == len(headers):
                rows.append(dict(zip(headers, cells)))
        return rows
    return []

• Step 4: Run test to verify it passes

Run: python3 -m pytest tests/test_capacity_scan.py -v Expected: PASS (2 passed).

• Step 5: Commit

git add scripts/capacity-scan.py tests/test_capacity_scan.py
git commit -m "Add capacity-scan.py with parse_table()"

---

Task 3: Rollup math — compute_rollup()

Files:

• Modify: scripts/capacity-scan.py

• Modify: tests/test_capacity_scan.py

• Step 1: Write the failing test (append to tests/test_capacity_scan.py)

def test_compute_rollup_sums_allocations_and_flags_headroom():
    node_rows = [{"node": "pve0", "cores": "20", "ram_gb": "64", "disk_gb": "4000"}]
    workload_rows = [
        {"workload": "dns1", "node": "pve0", "cores": "1", "ram_mb": "512", "disk_gb": "10"},
        {"workload": "forgejo", "node": "pve0", "cores": "4", "ram_mb": "8192", "disk_gb": "100"},
    ]
    nodes = cs.compute_rollup(node_rows, workload_rows)
    pve0 = nodes["pve0"]
    assert pve0["alloc_cores"] == 5
    assert pve0["alloc_ram_gb"] == 8.5          # (512 + 8192) / 1024
    assert pve0["alloc_disk_gb"] == 110.0
    assert pve0["ram_headroom_pct"] == 87        # round(100 * (64 - 8.5) / 64)
    assert pve0["oversubscribed"] is False


def test_compute_rollup_flags_oversubscription():
    node_rows = [{"node": "tiny", "cores": "2", "ram_gb": "4", "disk_gb": "50"}]
    workload_rows = [
        {"workload": "hog", "node": "tiny", "cores": "4", "ram_mb": "1024", "disk_gb": "10"},
    ]
    nodes = cs.compute_rollup(node_rows, workload_rows)
    assert nodes["tiny"]["oversubscribed"] is True   # 4 cores > 2


def test_compute_rollup_ignores_workloads_on_unknown_nodes():
    nodes = cs.compute_rollup(
        [{"node": "pve0", "cores": "20", "ram_gb": "64", "disk_gb": "4000"}],
        [{"workload": "ghost", "node": "nope", "cores": "1", "ram_mb": "512", "disk_gb": "10"}],
    )
    assert nodes["pve0"]["alloc_cores"] == 0

• Step 2: Run test to verify it fails

Run: python3 -m pytest tests/test_capacity_scan.py -k compute_rollup -v Expected: FAIL — AttributeError: module 'capacity_scan' has no attribute 'compute_rollup'.

• Step 3: Write minimal implementation (append to scripts/capacity-scan.py, before any main)

def compute_rollup(node_rows, workload_rows):
    """Per node: physical totals, summed allocations, RAM headroom %, and an
    oversubscribed flag. Workloads on unknown nodes are ignored."""
    nodes = {}
    for r in node_rows:
        nodes[r["node"]] = {
            "cores": int(r["cores"]),
            "ram_gb": float(r["ram_gb"]),
            "disk_gb": float(r["disk_gb"]),
            "alloc_cores": 0,
            "alloc_ram_mb": 0,
            "alloc_disk_gb": 0.0,
        }
    for w in workload_rows:
        node = nodes.get(w["node"])
        if node is None:
            continue
        node["alloc_cores"] += int(w["cores"])
        node["alloc_ram_mb"] += int(w["ram_mb"])
        node["alloc_disk_gb"] += float(w["disk_gb"])
    for node in nodes.values():
        node["alloc_ram_gb"] = round(node.pop("alloc_ram_mb") / 1024, 1)
        node["ram_headroom_pct"] = (
            round(100 * (node["ram_gb"] - node["alloc_ram_gb"]) / node["ram_gb"])
            if node["ram_gb"]
            else 0
        )
        node["oversubscribed"] = (
            node["alloc_cores"] > node["cores"]
            or node["alloc_ram_gb"] > node["ram_gb"]
            or node["alloc_disk_gb"] > node["disk_gb"]
        )
    return nodes

• Step 4: Run test to verify it passes

Run: python3 -m pytest tests/test_capacity_scan.py -k compute_rollup -v Expected: PASS (3 passed).

• Step 5: Commit

git add scripts/capacity-scan.py tests/test_capacity_scan.py
git commit -m "Add compute_rollup() to capacity-scan.py"

---

Task 4: Drift detection — find_drift() + hostname parsers

Files:

• Modify: scripts/capacity-scan.py

• Modify: tests/test_capacity_scan.py

• Step 1: Write the failing test (append)

def test_parse_tf_hostnames_reads_vms_value_keys():
    tf_json = '{"vms": {"value": {"dns1": {"ip": "10.20.0.10", "group": "docker_hosts"}}}}'
    assert cs.parse_tf_hostnames(tf_json) == {"dns1"}


def test_parse_inventory_hostnames_reads_meta_hostvars():
    inv_json = '{"_meta": {"hostvars": {"dns1": {}, "proxy": {}}}}'
    assert cs.parse_inventory_hostnames(inv_json) == {"dns1", "proxy"}


def test_find_drift_reports_both_directions():
    workload_rows = [{"workload": "dns1", "node": "pve0", "cores": "1", "ram_mb": "512", "disk_gb": "10"}]
    warnings = cs.find_drift(workload_rows, {"proxy"})
    assert any("dns1" in w and "no Terraform" in w for w in warnings)
    assert any("proxy" in w and "absent from reference.md" in w for w in warnings)


def test_find_drift_silent_when_no_hostnames_known():
    workload_rows = [{"workload": "dns1", "node": "pve0", "cores": "1", "ram_mb": "512", "disk_gb": "10"}]
    assert cs.find_drift(workload_rows, set()) == []

• Step 2: Run test to verify it fails

Run: python3 -m pytest tests/test_capacity_scan.py -k "drift or hostnames" -v Expected: FAIL — attributes parse_tf_hostnames / parse_inventory_hostnames / find_drift not defined.

• Step 3: Write minimal implementation (append)

def parse_tf_hostnames(tf_json):
    """Hostnames from `terraform output -json` (the `vms` map keys)."""
    data = json.loads(tf_json)
    return set(data.get("vms", {}).get("value", {}).keys())


def parse_inventory_hostnames(inv_json):
    """Hostnames from `ansible-inventory --list` (_meta.hostvars keys)."""
    data = json.loads(inv_json)
    return set(data.get("_meta", {}).get("hostvars", {}).keys())


def find_drift(workload_rows, known_hostnames):
    """Warn when reference.md workloads and live hostnames disagree. Silent when
    no hostnames are known (pre-provisioning) — nothing to compare against."""
    warnings = []
    declared = {w["workload"] for w in workload_rows}
    if not known_hostnames:
        return warnings
    for name in sorted(declared - known_hostnames):
        warnings.append(
            f"reference.md lists '{name}' but no Terraform/inventory host declares it"
        )
    for name in sorted(known_hostnames - declared):
        warnings.append(
            f"host '{name}' exists in Terraform/inventory but is absent from reference.md"
        )
    return warnings

• Step 4: Run test to verify it passes

Run: python3 -m pytest tests/test_capacity_scan.py -k "drift or hostnames" -v Expected: PASS (4 passed).

• Step 5: Commit

git add scripts/capacity-scan.py tests/test_capacity_scan.py
git commit -m "Add hostname parsers + find_drift() to capacity-scan.py"

---

Task 5: Subprocess glue + usage stub + main()

Files:

• Modify: scripts/capacity-scan.py

• Modify: tests/test_capacity_scan.py

• Step 1: Write the failing test (append)

import json as _json


def test_gather_usage_is_stubbed_unavailable():
    usage = cs.gather_usage()
    assert usage["available"] is False
    assert "reason" in usage


def test_known_hostnames_degrades_to_empty(monkeypatch):
    # Simulate terraform/ansible-inventory being absent or failing.
    def boom(*a, **k):
        raise FileNotFoundError("no such tool")

    monkeypatch.setattr(cs.subprocess, "run", boom)
    assert cs.known_hostnames("staging") == set()


def test_main_emits_valid_json_against_real_reference(monkeypatch, capsys):
    # Isolate from the host: no real terraform/ansible needed.
    monkeypatch.setattr(cs, "known_hostnames", lambda env: set())
    monkeypatch.setattr("sys.argv", ["capacity-scan.py"])
    cs.main()
    out = _json.loads(capsys.readouterr().out)
    assert set(out) == {"nodes", "workloads", "usage", "warnings"}
    assert out["usage"]["available"] is False
    assert "pve0" in out["nodes"]            # from the skeleton reference.md (Task 1)

• Step 2: Run test to verify it fails

Run: python3 -m pytest tests/test_capacity_scan.py -k "usage or known_hostnames or main" -v Expected: FAIL — gather_usage / known_hostnames / main not defined.

• Step 3: Write minimal implementation (append)

def gather_usage():
    """FUTURE: live per-VM CPU/RAM/disk usage history. Requires the physical
    cluster online; source UNDECIDED (Proxmox RRD vs Prometheus/Loki/Grafana —
    see docs/TODO.md 8.4). Until then the evaluator reasons on declared intent."""
    return {"available": False, "reason": "cluster not provisioned (see STATUS.md)"}


def _run_json(cmd):
    return subprocess.run(cmd, capture_output=True, text=True, check=True).stdout


def known_hostnames(env):
    """Union of hostnames from Terraform output and Ansible inventory. Each
    source is best-effort: missing tool / no state / bad JSON yields nothing."""
    hosts = set()
    tf_dir = os.path.join(REPO_ROOT, "terraform", "environments", env)
    try:
        hosts |= parse_tf_hostnames(_run_json(["terraform", f"-chdir={tf_dir}", "output", "-json"]))
    except Exception:
        pass
    inv = os.path.join(REPO_ROOT, "inventories", env, "hosts.yml")
    try:
        hosts |= parse_inventory_hostnames(_run_json(["ansible-inventory", "-i", inv, "--list"]))
    except Exception:
        pass
    return hosts


def main():
    parser = argparse.ArgumentParser(description="Deterministic capacity facts for /capacity-review.")
    parser.add_argument("--env", default="staging")
    parser.add_argument(
        "--reference",
        default=os.path.join(REPO_ROOT, "docs", "hardware", "reference.md"),
    )
    args = parser.parse_args()

    with open(args.reference, encoding="utf-8") as fh:
        markdown = fh.read()

    node_rows = parse_table(markdown, ["node", "cores", "ram_gb", "disk_gb"])
    workload_rows = parse_table(markdown, ["workload", "node", "cores", "ram_mb", "disk_gb"])
    nodes = compute_rollup(node_rows, workload_rows)
    warnings = find_drift(workload_rows, known_hostnames(args.env))

    json.dump(
        {"nodes": nodes, "workloads": workload_rows, "usage": gather_usage(), "warnings": warnings},
        sys.stdout,
        indent=2,
        sort_keys=True,
    )
    sys.stdout.write("\n")


if __name__ == "__main__":
    main()

• Step 4: Run the full test file

Run: python3 -m pytest tests/test_capacity_scan.py -v Expected: PASS (all tests).

• Step 5: Smoke-run the script end to end

Run: python3 scripts/capacity-scan.py | python3 -m json.tool Expected: valid JSON with nodes.pve0, a workloads list, usage.available: false, and a warnings array (likely empty with no Terraform state).

• Step 6: Commit

git add scripts/capacity-scan.py tests/test_capacity_scan.py
git commit -m "Complete capacity-scan.py: usage stub, subprocess glue, main()"

---

Task 6: The /capacity-review skill

Files:

• Create: .claude/commands/capacity-review.md

• Step 1: Confirm the existing command pattern

Run: ls .claude/commands/ && sed -n '1,20p' .claude/commands/review-repo.md Expected: lists existing commands; shows the frontmatter/structure to mirror.

• Step 2: Write .claude/commands/capacity-review.md

Mirror the frontmatter style of review-repo.md (adjust description/allowed-tools to match that file's actual keys). Body:

---
description: Evaluate hardware capacity and placement; recommend optimizations
---

# /capacity-review

Evaluate the homelab's hardware capacity and workload placement, and recommend
optimizations. On-demand only (scheduling is deferred — see docs/TODO.md 8.4).

## Steps

1. **Gather facts.** Run `python3 scripts/capacity-scan.py` and parse its JSON
   (`nodes`, `workloads`, `usage`, `warnings`). If `usage.available` is false,
   note in the report that recommendations are **intent-based, not usage-based**.
2. **Read intent.** Read `docs/hardware/reference.md` for the free-text columns
   the scan does not parse: `criticality`, `ha_intent`, `profile`, `constraints`,
   `growth`, plus the "Capacity notes" section.
3. **Reason across dimensions.** Produce recommendations, each tagged with its
   type and the basis it rests on (declared intent vs measured usage):
   - **HA / redundancy** — anti-affinity violations (e.g. an HA pair sharing one
     node), single points of failure, HA that looks like overkill, or a
     high-criticality workload with no redundancy.
   - **Right-sizing** — over/under-provisioned workloads. Today this is
     intent-based (allocation vs `profile`); flag that it becomes usage-based
     once the `gather_usage()` hook is live.
   - **Placement / moves** — oversubscribed nodes (`oversubscribed: true`, low
     `ram_headroom_pct`) or constraint-driven relocations.
   - **Upgrade timing** — `growth` notes vs headroom → rough runway.
   - **Drift** — surface every entry in the scan's `warnings` array.
4. **Write the report.** Save to `docs/hardware/reviews/YYYY-MM-DD-capacity.md`
   and copy it to `docs/hardware/reviews/latest.md`. Structure: a one-line
   summary, then a section per dimension with concrete, actionable items. State
   the basis (intent vs usage) on every recommendation.

• Step 3: Verify the file is well-formed

Run: head -5 .claude/commands/capacity-review.md Expected: frontmatter block present and consistent with review-repo.md's keys.

• Step 4: Commit

git add .claude/commands/capacity-review.md
git commit -m "Add /capacity-review skill"

---

Task 7: ADR-012, STATUS, CLAUDE.md, scripts/README

Files:

• Create: docs/decisions/012-hardware-capacity.md

• Modify: STATUS.md

• Modify: CLAUDE.md

• Modify: scripts/README.md

• Step 1: Write docs/decisions/012-hardware-capacity.md

Match the heading style of an existing ADR (sed -n '1,15p' docs/decisions/010-forgejo-ci.md first). Content:

# ADR-012 — Hardware reference & capacity evaluation

## Context

The repo modelled the logical/network layer (Terraform VM specs, ADR-007
topology) but not the physical layer — node CPU/RAM/disk capacity, network gear,
or which workloads are designed to run where with what headroom. There was also
no way to ask "is this well-proportioned?" — e.g. HA that isn't needed, a
workload that should move, or a node due an upgrade.

## Decision

- `docs/hardware/reference.md` is the single, hand-maintained source of truth for
  physical compute + network gear and workload placement intent. Two
  machine-readable tables (node capacity, workload placement) carry the numbers.
- `scripts/capacity-scan.py` (stdlib-only, like `repo-scan.py` / `tf_to_inventory.py`)
  parses those tables, computes per-node allocated-vs-physical rollups, and
  cross-checks workload hostnames against `terraform output -json` /
  `ansible-inventory --list` to surface drift.
- `/capacity-review` reads the scan + intent columns and writes a dated report to
  `docs/hardware/reviews/`, mirroring `/review-repo` → `docs/reviews/`.
- Numeric allocations live in `reference.md`, not Terraform: the current
  `terraform output` exposes only `{ip, group}`. Terraform/inventory are used
  only for hostname-drift cross-checks.
- **Live usage stats are a future hook.** The cluster is not stood up;
  `gather_usage()` returns `available: false` and the evaluator reasons on
  declared intent. The usage source (Proxmox RRD vs Prometheus/Loki/Grafana/
  Alloy) is undecided — see docs/TODO.md 8.4, to be settled before any hook is
  built.

## Consequences

- Right-sizing advice is intent-based until usage data exists; reports say so.
- `reference.md` table headers are a parser contract — changing them needs a
  matching `capacity-scan.py` change.

See also: ADR-001 (architecture), ADR-007 (network), ADR-009 (TF↔Ansible handoff).

• Step 2: Add STATUS.md rows

In STATUS.md, add to the "Real and working today" table:

| `docs/hardware/reference.md` + `scripts/capacity-scan.py` | Present — reference doc (skeleton until real hardware) + stdlib scan; emits capacity JSON |
| `/capacity-review` | Works — on-demand capacity evaluation → `docs/hardware/reviews/`. Intent-based (no live usage yet) |

And to the "Designed but not built" table:

| Live usage stats for `/capacity-review` | ADR-012 / TODO 8.4 | `gather_usage()` stubbed; source undecided (Proxmox RRD vs PLG stack); needs the cluster |

• Step 3: Add the CLAUDE.md command row + further-reading pointer

In CLAUDE.md "Key commands" table, add:

| Review hardware capacity        | `/capacity-review` (Claude command)              |

In the "Further reading" table, add:

| Hardware & capacity    | `docs/decisions/012-hardware-capacity.md` |

• Step 4: Document the script in scripts/README.md

Add under the existing list in scripts/README.md:

- `capacity-scan.py` — deterministic capacity facts for `/capacity-review`: parses
  the machine-readable tables in `docs/hardware/reference.md`, computes per-node
  allocated-vs-physical rollups, and cross-checks workload hostnames against
  Terraform output / Ansible inventory for drift. Emits JSON. See **ADR-012**.

• Step 5: Verify references resolve

Run: python3 scripts/repo-scan.py | python3 -c "import json,sys; d=json.load(sys.stdin); print('broken_refs:', [f for f in d.get('findings',{}).get('broken_refs',[]) if '012' in str(f) or 'hardware' in str(f)])" Expected: no broken refs mentioning ADR-012 or the hardware paths (empty list). If the scan's JSON shape differs, instead run python3 scripts/repo-scan.py >/dev/null && echo OK and eyeball the findings.

• Step 6: Commit

git add docs/decisions/012-hardware-capacity.md STATUS.md CLAUDE.md scripts/README.md
git commit -m "Record ADR-012 + STATUS/CLAUDE/scripts docs for capacity tooling"

---

Task 8: Final verification

Files: none (verification only)

• Step 1: Run the full unit-test suite

Run: python3 -m pytest tests/test_capacity_scan.py -v Expected: all tests pass.

• Step 2: Run the lint suite

Run: make lint Expected: passes (markdown/script changes do not break ansible-lint/yamllint).

• Step 3: End-to-end scan

Run: python3 scripts/capacity-scan.py Expected: valid JSON; nodes.pve0 present; usage.available: false.

• Step 4: Confirm working tree is clean

Run: git status --short Expected: no uncommitted changes from this plan (pre-existing FRICTION.md / ADR-011 may remain — leave them).