kevinveenbirkenbachandClaude Opus 4.7
256e027525
Removes 67 live references to docs/requirements/<NNN>-*.md files across
43 contributor docs, role READMEs, code comments, task files, and tests.
Requirement docs are initial-creation-only artefacts; live references
freeze a snapshot that rots once the per-feature SPOT (a contributor
doc, a code module, a lint test) takes over the live behaviour.
In the same pass, fixes documentation.md violations on the touched
files: drops em-dashes used as thought breaks, removes "SPOT for ..."
self-labels, strips historical phrasing ("the legacy", "previously",
"used to", "is no longer used", "matching the historical"), and
reflows soft-wrapped sentences so each sentence stays on one logical
line.
The `test_inventory_vars_file_spot.py` whitelist for the literal
inventory path drops the docs/requirements/003 entry and instead
skips docs/requirements/ entirely; future requirement docs that
mention the literal path are then ignored automatically.
Verified by tests/lint/repository/test_no_stale_requirement_refs.py
(green tree-wide).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3.9 KiB
cli meta networks suggest 🌐
This page documents the contract of the cli meta networks suggest helper and the rules contributors MUST follow when calling it.
Primary file:
Purpose 🎯
cli meta networks suggest proposes the next free per-role IPv4 subnet(s) based on the live role tree.
It walks every roles/*/meta/server.yml, collects occupied networks.local.subnet assignments, picks the smallest CIDR prefix that fits the requested client count, and proposes free sub-blocks gap-first then by increment within the established umbrella blocks.
Inputs 🔧
| Flag | Required | Default | Description |
|---|---|---|---|
--clients N |
yes | n/a | Minimum number of usable client IPs the role's subnet MUST hold. |
--count K |
no | 1 |
How many free subnets to return. |
--block <cidr> |
no | n/a | Force suggestions inside a specific umbrella block (e.g. --block 192.168.101.0/24). Default is the union of currently used /24 umbrella blocks for the chosen prefix length. |
Behaviour 🧮
- Translate
--clients Nto the smallest CIDR prefix that fits (≤14 →/28, ≤30 →/27, ≤62 →/26, ≤126 →/25, ≤254 →/24, …). - Walk every
roles/*/meta/server.ymland collect occupied CIDRs fromnetworks.local.subnet. - Within each umbrella
/24block already in use for the chosen prefix length: enumerate all sub-blocks of that prefix length, mark occupied vs. free. - Gap-first: propose the lowest unoccupied sub-block.
- Increment fallback: if all sub-blocks of the active
/24blocks are used, propose the next/24block in the established sequence (currently192.168.101–105for/28,192.168.200–203for/24). - No established sequence: if the requested prefix size has no umbrella block established yet (e.g.
--clients 1000→/22and no/22is in use), exit non-zero with a clear error suggesting that the operator pass--block <cidr>to bootstrap a new umbrella block manually. - For each suggestion, also print the client capacity (
/28 → 14,/24 → 254, …).
Output 📤
- stdout prints one subnet per line.
- stderr prints per-suggestion capacity and a human-readable summary noting which umbrella block(s) were scanned.
Examples 💡
Suggest two free /28 subnets (14 clients each) inside the established umbrella blocks:
cli meta networks suggest --clients 14 --count 2
Suggest one free /24 subnet (254 clients) bootstrapped inside an explicit umbrella block:
cli meta networks suggest --clients 254 --block 192.168.200.0/22
Suggest a single /28 subnet (the default --count 1):
cli meta networks suggest --clients 14
Determinism 🧪
Given the same on-disk role layout and the same arguments, the helper produces identical output. It exits non-zero with a clear error when the requested capacity cannot be satisfied within the configured umbrella block(s).
Integration with cli create role 🧩
When cli create role scaffolds a new role, it prompts for --clients N and calls cli meta networks suggest --clients N --count 1 to fill in meta/server.yml.networks.local.subnet automatically.
The contributor MAY override the suggestion interactively.
See ports-suggest.md for the matching ports flow.
Related Pages 📚
- ports-suggest.md is the sibling helper for host-bound ports.
- layout.md describes the per-role
networks:shape inmeta/server.yml.