docs: declare the selected-window path public for walk-forward use, with a doc-lint rule that holds it - #564

What

Declares the selected-window path a public surface for walk-forward use. docs/pages/public-contract.md gets a new section ({#selected_windows_walk_forward}) that says, from what the tree shows:

• the public entry points, each cited with its symbol: the docker/run_json.py selected-window options and --capabilities-json, the capability record (capabilities.selected_window_contract_revisions), the report policy, and the two C headers selected_window.h and selected_window_plan.h with the PF_API functions each declares;
• how a consumer detects support and the contract revision before relying on it;
• the stability rule, in the words the page already uses for the other surfaces: append-only within 1.x, a contract revision changes only by a new revision literal, typed failures, and what only a major release may change;
• what is not public (the helper modules and anything not reachable from the CLI or the headers);
• the walk-forward use as the tree supports it: successive non-overlapping windows over one chart, each window an independent request, preroll and anchor, and where the report carries them.

It also adds a pointer from the README and a line under 1.8.0 in the changelog.

A new doc-lint rule holds the section: it reads the complete PF_API declarations of both headers and the selected-window add_argument block of docker/run_json.py at run time (parsing the CLI with ast, never importing it), and fails when the section is missing or duplicated, when a name the sources declare is absent from it, or when a source cannot be read or parsed. No name list is typed into the checker. Six cases in scripts/test_check_doc_lint.py cover it with temporary trees the test builds.

Verification

• The new rule fails on the base page, for the right reason: the doc-lint stage reports cannot read or parse the selected-window public section: expected one {#selected_windows_walk_forward} section (one offender) when the three documentation files are reverted and the checker is kept.
• On this head the full ci_preflight (59 stages, including doc-anchors, doc-lint and doc-reverts) and the documentation build pass.
• The change touches no engine code. Parity is measured on this exact tree.

🤖 Generated with Claude Code