Compatibility Contract

This document defines the backward-compatibility guarantees for ClaimStab-QC.

Guaranteed Stable Interfaces

1. CLI entrypoint forms remain valid:
2. python -m claimstab.cli ...
3. python -m claimstab.pipelines.claim_stability_app ...
4. python -m claimstab.pipelines.multidevice_app ...
5. Output artifact names remain stable under run directories:
6. claim_stability.json, rq_summary.json, robustness_map.json, scores.csv
7. combined_summary.json for multidevice workflows
8. Report path and structure remain stable:
9. stability_report.html
10. Evidence protocol compatibility remains stable:
11. experiments[*].evidence.cep fields stay schema-compatible
12. Active paper-bundle contract remains stable:
13. output/paper/evaluation_v2/runs/*
14. output/paper/evaluation_v2/derived_paper_evaluation/*
15. output/paper/evaluation_v2/pack/figures/*

Allowed Changes (Non-breaking)

• Additive JSON fields.
• New optional spec presets and optional scripts.
• New figures and tables in paper-pack output.
• Internal refactors that preserve external behavior.

Disallowed Changes (Breaking)

• Renaming/removing existing CLI flags or commands.
• Renaming/removing established artifact files.
• Changing meaning of existing decision fields without version bump.
• Mutating CEP required fields in incompatible ways.

Required Validation Before Merge

python -m pytest -q
python -m claimstab.scripts.check_refactor_compat --mode all
python -m claimstab.cli validate-spec --spec paper/experiments/specs/evaluation_v2/e1_maxcut_main.yml
python -m claimstab.cli validate-evidence --json output/paper/evaluation_v2/runs/E1_maxcut_main/claim_stability.json
python -m mkdocs build --strict

Rollback Policy

• If compatibility drift is detected, revert the latest offending commit and rerun compatibility checks before any further changes.