refactor(management): add composable connection-based procedure cores

[kewde]

Description

Adds composable "conn" variants of two management procedures, so several procedures can be chained over one already-open P2PConnection instead of each one opening and closing its own:

• dm_restart_r_co(conn) — the actual KNX v02.01.02 - Management Procedures 03.05.02 - §3.7.3 procedure name for the connection-based variant of DM_Restart. dm_restart(xknx, address) now just opens a connection and delegates to it.
• nm_individual_address_check_conn(conn) — an xknx-only naming convention (not a KNX spec name) for the connection-based core of nm_individual_address_check. nm_individual_address_write now calls this directly on its own already-open connections instead of duplicating the DeviceDescriptorRead/timeout handling inline.

All existing top-level procedures (dm_restart, nm_individual_address_check, nm_individual_address_write, nm_individual_address_read, nm_individual_address_serial_number_read/_write) keep their familiar (xknx, ...) signature — no breaking change to any of those call sites.

Also:

• Add P2PConnection.send_data(payload, wait_for_ack=True), replacing the near-duplicate send_data_no_ack/private _send_data pair, so dm_restart_r_co and the request-based procedures share one send path instead of two copies of the same TDataConnected construction.
• Remove the nm_invididual_address_write typo alias — the misspelled name is no longer exported. This is the only breaking change in this PR.
• Add CLAUDE.md documenting how to cite the KNX Standard in code (document + version, since different KNX documents version independently), the management procedure naming convention, changelog conventions, and PR template usage.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code quality improvements to existing code or addition of tests

Checklist

• The documentation has been adjusted accordingly
• Tests have been added that prove the fix is effective or that the feature works
• The changes are documented in the changelog (docs/changelog.md)

[kewde]

Problem: procedures that need multiple connections

Some procedures require sequential A_Connects to different addresses:

• NM_IndividualAddress_Write — 2 serial A_Connects (occupancy check + verify/restart).
• NM_Router_Scan — loop of up to 256 A_Connects, one per subnet address 0–255.
• NM_DomainAddress_Scan / NM_DomainAddress_Scan2 — same pattern.

These can't take conn: P2PConnection — they need a connection factory.

Options

1. Move address into connect()

P2PConnection becomes a reusable session object; address is passed at connect-time:

# procedure signature
async def nm_router_scan(conn: P2PConnection) -> list[IndividualAddress]:
    for i in range(256):
        async with conn.connect(IndividualAddress(f"1.{i}.0")):
            ...

# caller
conn = P2PConnection(xknx)
await nm_router_scan(conn)

2. Pass ConnectionManager to scanning procedures

Remove the raise guard in Management.connect() — allow reconnecting to the same or a new
address — and let scanning procedures own their loop:

async def nm_router_scan(manager: ConnectionManager) -> list[IndividualAddress]:
    for i in range(256):
        async with manager.connection(IndividualAddress(f"1.{i}.0")) as conn:
            ...

# caller
await nm_router_scan(xknx.management)

This is already the pattern for nm_individual_address_write — scanning procedures are just
another case of a procedure that manages its own connection lifecycle.

[farmio]

In my opinion Option 2 is a cleaner API.
Regarding removing the raise:

if address in self._connections:
            raise ManagementConnectionError(f"Connection to {address} already exists.")

We remove the adddress from self._connections on disconnect. Parallel connections aren't possible iirc. So I think we can - and should - keep this. Connections to new addresses are possible anyway.

I could imagine to have some kind of backoff retry mechanism if an address is already connected by another procedure. But that's out of scope for this PR. And maybe better handled by the user of the API.

[kewde]

to provide a clean way to do restarts

[codecov]

Codecov Report

❌ Patch coverage is 97.22222% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.79%. Comparing base (f5ab709) to head (96a0b31).

Files with missing lines	Patch %	Lines
.../procedures/network/nm_individual_address_check.py	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1832      +/-   ##
==========================================
+ Coverage   97.76%   97.79%   +0.03%     
==========================================
  Files         181      181              
  Lines       13195    13202       +7     
==========================================
+ Hits        12900    12911      +11     
+ Misses        295      291       -4     

Files with missing lines	Coverage Δ
xknx/management/management.py	92.30% <100.00%> (+1.08%)	⬆️
xknx/management/procedures/__init__.py	100.00% <100.00%> (ø)
xknx/management/procedures/device/__init__.py	100.00% <100.00%> (ø)
...nx/management/procedures/device/dm_restart_r_co.py	100.00% <100.00%> (ø)
xknx/management/procedures/network/__init__.py	100.00% <100.00%> (ø)
.../procedures/network/nm_individual_address_write.py	100.00% <100.00%> (+7.14%)	⬆️
.../procedures/network/nm_individual_address_check.py	96.15% <93.75%> (+1.41%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[farmio]

Claude Code 🤖:

I like where this is heading — splitting "procedure logic" from "connection lifecycle" is the right move, and dm_restart(conn) reads much better than the old telegram-crafting inline. A few things I'd change before this lands, all with "what does the call site look like for a user?" as the yardstick.

1. Drop protocols.py — annotate with the real classes

Re: the Protocol discussion above — I'm with @farmio here. Concretely:

• xknx.management.protocols.P2PConnection and xknx.management.management.P2PConnection are two different things with the same name. Anyone reading conn: P2PConnection now has to check which import it is. That alone is a strong argument.
• The protocols are @runtime_checkable, but nothing does isinstance() on them — and for P2PConnection (which has a data member address) issubclass() wouldn't work anyway. So the decorator buys nothing.
• "third parties can bring their own Management" is a real use case, but it's already served by subclassing Management — and if we ever do need structural typing, converting Management → Protocol later is a typing-only change. It's not a decision we have to make now, and making it now costs indirection on every procedure and one more file to keep in sync whenever request() or connection() changes.

So: conn: P2PConnection, management: Management — the actual classes.

2. Never pass the same object twice

nm_individual_address_write(xknx.management, xknx.management, individual_address_new)

This is the clearest signal that the split is at the wrong seam. Management is both the connection manager and the broadcaster; the two-argument form exists only to describe the protocol split from (1). With concrete types this collapses to:

await nm_individual_address_write(xknx.management, "1.2.3")

Same for nm_individual_address_read(xknx.management, ...) etc. — one management argument everywhere a procedure owns its own connections, one conn argument where it operates on an established one. That's a rule a user can hold in their head.

3. No legacy layer, please — let's just break it

The management procedures have very few users, and we're happy to cut a major release for an API change here. That's much cheaper for everyone than what's currently in the PR:

• the _legacy modules are more code than the procedures themselves, and we'd have to carry and test them for a couple of releases;
• they force a second public name for every procedure;
• and today from xknx.management.procedures import dm_restart and from xknx.management.procedures.device import dm_restart are two different functions with the same name and incompatible signatures, differing only by import path — that's a trap no IDE or traceback will help with.

So: drop device/legacy.py, network/legacy.py and the module-level aliasing, keep one public name per procedure with the new signature, and describe the change in docs/changelog.md with before/after snippets. While we're at it, the nm_invididual_address_write typo alias can go too.

4. nm_individual_address_check(conn) leaks its own semantics

The procedure is specified as "is IA_new occupied?", and per 03.05.02 §2.3 an A_Disconnect counts as occupied. After the split, part of that answer lives outside the function — the ManagementConnectionRefused from connect()/disconnect() — which is why the legacy wrapper has to re-implement it:

except ManagementConnectionRefused:
    return True

and why nm_individual_address_write needs this:

try:
    async with manager.connection(individual_address) as conn:
        address_found = await nm_individual_address_check(conn)
except ManagementConnectionRefused:
    pass

Two callers, two different handlings of the same condition, and in the second one address_found is only bound if the exception came from disconnect() in the finally — if it ever comes from anywhere earlier, the next line raises UnboundLocalError. Even if that path isn't reachable today, it shouldn't depend on where inside the context manager the exception originates.

Suggestion: nm_individual_address_check keeps owning its connection (management, address), so "refused == occupied" stays in one place. If a raw "does this device answer on an open connection" primitive is useful for scanning, give it its own name (device_responds(conn) / dd_read_check(conn)) rather than overloading the spec-named procedure. At minimum, set address_found = True in that except and drop the reliance on the earlier assignment.

5. P2PConnection.send_data_no_ack() — 👍

Good addition, this is exactly the kind of thing that belongs on the connection rather than being open-coded in two procedures. Only bikeshed: send_data_no_ack next to the private _send_data reads a bit like an internal; send_unacknowledged() or send_data(payload, wait_for_ack=False) might age better. Your call.

Suggested target shape

# procedures that talk to one device and own the connection
await dm_restart(xknx.management, "1.2.3")
await nm_individual_address_check(xknx.management, "1.2.3")
await nm_individual_address_write(xknx.management, "1.2.3")

# broadcast-only
await nm_individual_address_read(xknx.management)

# power users / multiple procedures on one connection
async with xknx.management.connection(IndividualAddress("1.2.3")) as conn:
    await dm_restart_r_co(conn)

i.e. the conn-taking functions stay (they're the composable core, and scanning procedures like NM_Router_Scan will want them), but the spec-named public procedures keep the one-liner ergonomics. On your NM_Router_Scan question above: option 2 (pass Management, loop over manager.connection(...)) — a connection object that can be re-pointed at another address (option 1) means conn.address is no longer stable, and every procedure taking conn would have to care about that.

[farmio]

Personally I'd drop the Protocols and the Legacy shims. It should be fine to break these APIs and do a major release when we are ready.