feat: ship machine-readable schemas for every report transport

[seonghobae]

Buyer-visible outcome

RankWeave 0.13.0 publishes machine-readable JSON Schema Draft 2020-12 contracts for every stable pairwise and candidate-family report transport.

rankweave schema --report-type pairwise --schema-version v2
python -m rankweave schema --report-type family --schema-version v1

Python and MSA consumers can discover and load the same packaged resources through ReportSchemaDescriptor, available_report_schemas, load_report_schema_text, and load_report_schema.

Compatibility and architecture

• Existing pairwise and family v1/v2 report documents are unchanged.
• Four strict Draft 2020-12 resources describe the exact transport field sets and domains.
• Every report object rejects additional properties and constrains required fields, metrics, alternatives, methods, digests, counts, and value ranges.
• Cross-field invariants that portable JSON Schema cannot fully express remain documented with $comment and enforced by RankWeave generation APIs.
• Runtime remains Python 3.10+, standard-library-only, store-agnostic, standalone-usable, and suitable for naruon or another MSA consumer.
• The package does not embed a partial validator or add a runtime jsonschema dependency.
• ARCHITECTURE.md, CLAUDE.md, AGENTS.md, README, CLI documentation, report-schema documentation, research grounding, and CHANGELOG.md are synchronized.

Supply-chain and release controls

• Build and development inputs are pinned in pyproject.toml.
• uv.lock contains exact artifact hashes across supported Python versions.
• CI uses immutable GitHub Action SHAs, pinned uv 0.11.29, and uv sync --frozen.
• Installed-wheel checks require all four schema resources and verify console/module output parity outside the source tree.
• No GitHub Copilot Agent Task or COPILOT_GITHUB_TOKEN path is introduced; the existing NVIDIA NIM/OpenCode product loop and review-agent credentials remain unchanged.

Exact current-head verification

Current head: 7d9b86c17001657662d9ef23109f321ba4e666f4

The current PR merge ref includes the latest main and passed:

• Ruff and compileall on Python 3.10, 3.11, 3.12, and 3.13
• 455 tests on every Python matrix entry
• 1086/1086 production statements and 286/286 production branches, 100%
• complete production docstring enforcement
• JSON Schema meta-schema checks and validation of real generated pairwise/family v1/v2 reports
• wheel build and required-resource inspection
• isolated installed-wheel API, schema command, pairwise/family v1/v2 console/module smoke tests
• dependency consistency check
• Security Scan
• SAST Semgrep
• zero unresolved review threads

Standards and interpretation boundary

The package records APA 7th references for JSON Schema Core and Validation Draft 2020-12. Structural schema conformance is not producer authentication, digital-signature verification, external artifact-digest verification, trusted-execution evidence, or proof that a statistical inference is scientifically valid.

No tag, GitHub Release, package publication, attestation, or release-provenance claim is created before protected merge.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 23 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0b0ba065-48e8-466a-af1a-eda9c96c5fb3

📥 Commits

Reviewing files that changed from the base of the PR and between 16b76c4 and 7d9b86c.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .github/workflows/ci.yml
• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• CLAUDE.md
• README.md
• docs/cli.md
• docs/report-schemas.md
• docs/research/README.md
• docs/superpowers/plans/2026-08-05-report-json-schema.md
• docs/superpowers/specs/2026-08-05-report-json-schema-design.md
• pyproject.toml
• src/rankweave/__init__.py
• src/rankweave/cli.py
• src/rankweave/report_schemas.py
• src/rankweave/schemas/__init__.py
• src/rankweave/schemas/trec-comparison-v1.schema.json
• src/rankweave/schemas/trec-comparison-v2.schema.json
• src/rankweave/schemas/trec-family-comparison-v1.schema.json
• src/rankweave/schemas/trec-family-comparison-v2.schema.json
• tests/test_report_schemas.py
• tests/test_schema_cli.py
• tests/test_version.py

---

_{Comment @coderabbitai help to get the list of available commands.}