Builds the checked inventory that ADR 0053 exit criterion 10 asks for (decision 2 compatibility surface).
What changed
scripts/generate_reference_docs.pywritesdocs/reference/generated/compatibility-surface.jsonalongside the existing references. It reuses the CLI and HTTP builders' data rather than parsing Click or FastAPI again.- The inventory covers the
blessed_coreprofile only:- CLI command paths and parameters (help text dropped) for commands owned by
blessed_corepackages: 135 /api/v1methods and paths plusGET /health: 166phlo.__all__, excluding underscore-prefixed names such as__version__: 65- entry-point groups from
PLUGIN_FAMILIESplusphlo.plugins.observatoryandphlo.project_templates: 15 groups, 46 entry points declared byblessed_coredistributions - hook event classes in
phlo.hooks.events: 11, plus envelope version1.0 release_set.schemas: configuration1, database5
- CLI command paths and parameters (help text dropped) for commands owned by
cli.jsongains apackagefield per command: the distribution whose module defines the command callback. This is what lets the inventory drop commands from preview and supported_optional packages (mcp,sling,transform,alerts, and so on).- The support matrix page has a short section explaining the file, how to regenerate it, and that a diff is an ADR 0053 decision 4 review item.
How it is checked
make docs-reference-check (part of make check and the CI Python lane step "Check generated reference documentation") regenerates and fails when the file is stale. I checked this by temporarily adding a name to phlo.__all__: the check failed and listed only compatibility-surface.json.
Verification
make check: all lanes passed except a C901 complexity finding incli_docs, since fixed.ruff check, the C901 check,generate_reference_docs.py --checkandtests/tooling/test_generate_reference_docs.py(15 passed) re-run green.make docs-build, codespell, markdown links,validate_support_manifest.py.
Notes
- Entry points come from installed distribution metadata, the same environment that produces
cli.jsonandhttp-api.json. - Hook event types are the event classes. Event type strings are open-ended, so the classes are listed instead.
- Parallel removals of the deprecated 0.19.0 names will shrink
python_api. Whichever PR lands second regenerates the file.
Activity
313No blocking findings. The generated inventory matches ADR 0053 exit criterion 10, and the committed data is internally consistent with its sources.
Checked
- Full diff at
07e86df: the new builder, thepackagefield added tocli.json, the committedcompatibility-surface.json, the support-matrix section, and the new test. - Counts agree with the file's contents: 135 CLI paths, 166 HTTP routes, 65
phlo.__all__names, 15 entry-point groups, 46 entry points, 11 hook event types, envelope1.0, andconfiguration=1/database=5taken fromregistry/support/v1.json. - CLI ownership is derived from the callback's top-level module via
packages_distributions(), with the editablephloroot named explicitly because that install has notop_level.txt. Commands fromphlo-airbyte,phlo-alerting,phlo-clickhouse,phlo-mcp,phlo-sling, andphlo-transformdrop out by package, and the test asserts those exclusions plus the/api/v1+/healthHTTP filter. - Entry points are limited to the 15 groups decision 2 names; excluding
phlo.plugins.dagsteris deliberate and asserted. - Wiring is accurate:
make docs-reference-checkis part ofmake check(Makefile:15) and the CI quality job (ci.yml:210). At this SHA the quality job's "Check generated reference documentation", Ruff (including C901),ty, the docs build, and the core test shards' test steps all passed, so the committed file is fresh in CI's environment.
Non-blocking wording note — docs/reference/support-matrix.md:9-13 says the file lists "the ADR 0053 decision 2 surface" and that a diff to it should be reviewed as a covered-surface change. The file is the exit-criterion-10 subset: decision 2 also covers HTTP request/response schemas, status codes, error envelope, pagination and authorisation actions; the CLI JSON envelope and exit status; phlo.plugins.base, capability specs and service.yaml; project layout/configuration shape; and the support manifest shape. None of those are recorded here, so a green diff could be read as full decision-2 coverage. Suggest describing it as the exit-criterion-10 inventory of those surfaces, leaving the rest to their decision-2 references.
Remaining validation — The API package tests and the workspace coverage shards were still running when I checked; they exercise this change only through the shared tooling suite, whose test step passed in the core shards.
github.comment.notice: falsein.github/pr-lens.ymlturns this note off