Reconcile COG write stability across registry, contract, and docstring

[brendancol]

Closes #2513.

Summary

The registry, the release contract, and the reference docs already declared COG writes stable under SUPPORTED_FEATURES['writer.cog']. The to_geotiff() docstring disagreed: it put cog=True and overview generation under [advanced] and tagged the cog parameter [advanced].

This PR picks option (a) from the issue. The COG layout is stable. The to_geotiff() docstring now lists cog=True under the [stable] tier bullet with an inline link to SUPPORTED_FEATURES['writer.cog'], and the cog parameter marker flips to [stable]. The overview_levels and overview_resampling knobs stay [advanced] because they map to the separately tracked writer.overviews sub-behaviour. geotiff.rst and geotiff_release_contract.md now spell that split out so the docs page agrees with the docstring.

Four tripwire gates land in test_stable_features.py: writer.cog stays stable, writer.overviews stays advanced, the docstring lists cog=True under [stable], and the overview knobs stay [advanced]. If any of those pins drops, the release gate fails before release.

Backend coverage

Docs and contract only. No code paths touched, no backend matrix to update.

Test plan

• pytest -q xrspatial/geotiff/tests -m 'not slow' (5917 passed, 74 skipped, 1 xfailed)
• New tripwire gates pass: pytest xrspatial/geotiff/tests/release_gates/test_stable_features.py -k "writer_cog_stays_stable or writer_overviews_stays_advanced or docstring_marks_cog_stable or docstring_marks_overview_knobs_advanced"

[brendancol]

PR Review: Reconcile COG write stability across registry, contract, and docstring

Blockers (must fix before merge)

None. Docs-and-contract reconciliation. The four new tripwire gates pass locally on Python 3.14, and the geotiff suite stays green.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/tests/release_gates/test_stable_features.py:2657,2704: the new tripwire tests regex against to_geotiff.__doc__. Python 3.13 trims leading whitespace from docstrings at compile time, but Python 3.12 (still supported per setup.cfg's python_requires = >=3.12) does not. The current regexes anchor at column 0 (r"^cog : bool\n \["), which works on 3.13 / 3.14 and breaks on 3.12 because every body line keeps its 4-space indent. PR CI only runs 3.14, so this PR lands green, but a 3.12 user running pytest locally trips a false positive. Wrap the docstring in inspect.getdoc(to_geotiff) (or inspect.cleandoc(to_geotiff.__doc__ or "")) before regexing; that normalises indent across every supported Python.

Nits (optional improvements)

• xrspatial/geotiff/tests/release_gates/test_stable_features.py:2655,2702: the two docstring tests do a local from xrspatial.geotiff import to_geotiff. The same name is already imported at module scope around line 81. Hoist for consistency with the rest of the file.
• xrspatial/geotiff/tests/release_gates/test_stable_features.py:2673-2674: the comment "Python strips the common leading indent on __doc__" is only true on 3.13+. Drop or rewrite if you stay on raw __doc__; if you move to inspect.getdoc, the comment goes away anyway.

What looks good

• The three surfaces (runtime registry, contract md, reference rst) now agree: writer.cog = stable, writer.overviews = advanced. The docstring tier markers match.
• The "COG layout is stable, pyramid customisation is advanced" split is spelled out in all three places using the same SUPPORTED_FEATURES['writer.overviews'] reference.
• Function-level [stable] bullet lists cog=True. Per-parameter [stable] marker on cog matches.
• Four tripwire gates pin every surface, so a future drift trips a release gate instead of shipping silently.
• No code paths touched; the geotiff suite remains green (5917 passed locally).
• The release contract's writer.overviews row names both the customisation knobs and the resampling output, so the boundary against writer.cog is unambiguous.

Checklist

• Algorithm matches reference/paper (N/A, docs only)
• All implemented backends produce consistent results (N/A, no backend code touched)
• NaN handling is correct (N/A)
• Edge cases are covered by tests
• Dask chunk boundaries handled correctly (N/A)
• No premature materialization or unnecessary copies (N/A)
• Benchmark exists or is not needed (not needed)
• README feature matrix updated (not needed; no new function)
• Docstrings present and accurate

[brendancol]

PR Review (follow-up after e75bd44)

Blockers

None.

Suggestions

None remaining.

Nits

None remaining.

What looks good

• The earlier Suggestion is addressed. Both docstring gates now go through inspect.getdoc(to_geotiff), so the regex anchors line up on Python 3.12, 3.13, and 3.14.
• The duplicate local imports are gone. The tests use the module-scope to_geotiff import at line 81.
• The misleading "Python strips the common leading indent on __doc__" comment is replaced with a docstring note that explains why inspect.getdoc is used.
• Tripwire gates still pass locally.
• No code paths touched. The surface change is still docs and tests only.

Checklist

• Algorithm matches reference/paper (N/A, docs only)
• All implemented backends produce consistent results (N/A, no backend code touched)
• NaN handling is correct (N/A)
• Edge cases are covered by tests
• Dask chunk boundaries handled correctly (N/A)
• No premature materialization or unnecessary copies (N/A)
• Benchmark exists or is not needed (not needed)
• README feature matrix updated (not needed; no new function)
• Docstrings present and accurate