Correct ~30 comments that describe behaviour the framework no longer has

[Yaraslaut]

Output of a twelve-way audit over all 64 headers in include/morph (28,496 lines). Stacked on #492 — merge that first; this PR's base is bridge-async-threading-contract.

What the audit actually found

The brief asked for both correctness and "comments up to date and compressed enough". The dominant defect is not verbosity — this codebase's long why comments are house style and carry real reasoning. It is comments that are false: roughly 60 assert behaviour the code no longer has. This PR fixes the ~30 verified by reading the code they describe, plus the spec passages carrying the same wrong claim.

Doxygen is clean: four audit agents ran it with the repo's exact WARN_AS_ERROR=FAIL_ON_WARNINGS settings and validated their harness against a planted gap. Zero warnings.

Highlights

The ones most likely to mislead someone mid-debugging:

• scaleFactorsFor's @return was exactly backwards (rational.hpp) — leftScaled and rightScaled swapped relative to all four call sites. The single comment an overflow audit would most trust.
• liveness() said ~BridgeHandler checks it. It uses the BridgeLifetime gate — that distinction is morph#486, and this is the comment a reader hits first.
• The shutdown gate rejects attach too, and has since PR Stateful models: keyed shareable instances, instance subscriptions, and a bank example that demonstrates them (closes #18) #20; two comments said "register and execute only", misdescribing graceful shutdown for the shared-instance topology.
• finding 035 resolves to nothing. examples/FINDINGS.md retired that citation form and records that it has already silently resolved to the wrong finding once. This was the last surviving instance in include/.
• BridgeLifetime's "sole guarded region" — PR Batch: forms boundaries, bridge lifetime sites 1-3, replay-ledger promotion, scheduled mutation gate #491 added two more, and the paragraph's whole non-blocking argument covers only the first.
• "lock-free snapshot of the backend" ×2 — loadBackend() takes _backendMtx; docs/spec/core/bridge.md already had this right.
• core/shared_instances.md said "There is no assignPrimaryAsync." There is; QtWebSocketBackend overrides it and Bridge::assignHandlerPrimary prefers it.
• util/rational.md warned about a hazard that was fixed (an absoluteNumerator local that no longer exists) while the real one, one file away, was undocumented — now pointed at morph#496.

Plus counts that had drifted, four "added in a later task" markers for code already above the reader, two dead docs/planned/ paths, two "Task 6" references to an unrelated Kanban plan task, and several direction words pointing the wrong way.

Corrections made during review

Correcting stale comments carries its own risk: replacing a wrong statement with a differently-wrong one. Three rounds of self-review plus /code-review high caught eight such cases in this PR, all fixed here rather than merged:

• bridge.hpp — I replaced a wrong count ("five other sites") with a wrong universal ("every other site"). registerHandlerImpl reads contextKey at two sites holding neither lock. Now names the exception; the underlying defect is filed as bridge: registerHandlerImpl reads binding->contextKey under neither lock, violating the invariant _attachMtx's own comment states #505.
• forms.hpp — "glaze never derives required from member types" is false: glz::requires_key derives one when Opts.error_on_missing_keys is set. Nothing is derived under the options schemaJson<A>() uses, which is the load-bearing part, so it now says that instead of an unconditional property of glaze.
• remote.hpp — the new handleInline enumeration listed six kinds and said "all six"; SimulatedRemoteBackend::deregisterModel makes it seven, and deregister was the omitted one.
• model_key.hpp — fixing the macro name broke the description: BRIDGE_MODEL_KEY deduces the key type, it does not name it.
• render/i18n.hpp — turned a stale prediction into a false present-tense claim; SlotRegistry is a QML type in no C++ namespace.
• journal.md — qualified IActionLog's append-only rule with two FileActionLog members, one of them private and constructor-only.
• file_offline_queue.hpp — a literal `@throws` in prose broke the Windows build under -Weverything -Werror (-Wdocumentation: "empty paragraph passed to '@throws' command"). Backticks do not stop clang parsing it as a command.
• branch_partial_allowlist.json — the sharpest: line fields were re-pinned but three reason prose cross-references still cited the old numbers, which is exactly this PR's own subject.

Scope

Comments and documentation only — no behavioural change. Where a comment was wrong because the code is wrong, the code defect is filed and left alone here: #493–#502, #505.

Verification

• All edited headers pass clang++ -std=c++23 -fsyntax-only and -Wdocumentation -Werror with glaze as a system header, matching how CI treats it.
• scripts/check_spec_citations.sh clean.
• scripts/branch_partial_allowlist.json audited both ways: every source pin lands on its own text, and every line N / .hpp:N reference inside reason prose resolves to a real entry. 25/25.
• Spec-sync satisfied for every touched sub-domain, with genuine corrections — each touched spec carried the same stale claim as its header.

Not in this PR

~30 further stale comments and the cross-cutting duplication (the "public macro surface" paragraph appears 17-18 times repo-wide) are tracked in #504.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SxkvtHvan2fWKDDaBpqkgv

[Yaraslaut]

Auto-closed by GitHub when its base branch (bridge-async-threading-contract, PR #492) was deleted on merge — not closed deliberately, and not abandoned.

The same branch, rebased onto master, continues as #508. All review history, including the /code-review round and the nine self-corrections it prompted, is on this issue and carried forward in the new PR's description.