docs(claude): add Strict WSDL parity principle + guard test (#199)#200
Merged
Conversation
Closes #199. Two artifacts to make the strict-parity policy stick: 1. CLAUDE.md — new 'Strict WSDL parity' convention listing the five legitimate exclusion categories; explicitly bans «helper» / «legacy» / «not part of strict WSDL parity» rationale as mis-classification (as happened with bidmodifiers.delete pre-#194). 2. tests/test_api_coverage.py — guard test test_dry_run_exclusions_have_no_helper_or_legacy_rationale that fails if any rationale in DRY_RUN_PAYLOAD_EXCLUSIONS contains the banned phrases. The actual code-fix landed in PR #194 — this PR locks the policy in docs + CI so it cannot regress.
There was a problem hiding this comment.
Pull request overview
This PR formalizes the “Strict WSDL parity (no helper/legacy skip categories)” policy in documentation and adds a CI guard test to prevent regressions in DRY_RUN_PAYLOAD_EXCLUSIONS rationale wording.
Changes:
- Added a new
tests/test_api_coverage.pyguard that fails if anyDRY_RUN_PAYLOAD_EXCLUSIONSrationale contains banned “helper/legacy/strict parity” phrasing. - Documented the strict parity principle and the intended (limited) set of legitimate exclusion categories in
CLAUDE.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| tests/test_api_coverage.py | Adds a test that enforces banned rationale phrasing in DRY_RUN_PAYLOAD_EXCLUSIONS. |
| CLAUDE.md | Documents the strict WSDL parity principle and references the new guard test. |
Comment on lines
+46
to
+54
| **Strict WSDL parity:** `DRY_RUN_PAYLOAD_EXCLUSIONS` in `tests/api_coverage_payloads.py` must NOT contain any entry whose rationale claims the CLI surface is a «helper», «legacy», or «not part of strict WSDL parity». If the WSDL declares the operation, the CLI mirrors it 1:1 with a `PAYLOAD_CASES` fixture. Legitimate permanent exclusions are limited to: | ||
| - read-path `*.get` (covered by SelectionCriteria tests); | ||
| - runtime-deprecated methods (see `RUNTIME_DEPRECATED_METHODS`); | ||
| - v4 methods that have no v5 WSDL (covered by `direct_cli/v4_contracts.py`); | ||
| - custom non-RPC endpoints (e.g. `reports.get` — TSV stream); | ||
| - methods explicitly covered by `tests/test_dry_run.py::test_<service>_<op>_payload`. | ||
|
|
||
| A guard in `tests/test_api_coverage.py::test_dry_run_exclusions_have_no_helper_or_legacy_rationale` enforces this — any rationale outside those five categories that uses the banned phrasing is a mis-classification: write a `PAYLOAD_CASES` fixture instead. See post-mortem in issue #199. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #199 — locks the «strict WSDL parity, no helper/legacy skip categories» policy in docs and CI so the
bidmodifiers.deletemis-classification cannot regress.Why
bidmodifiers.deletewas incorrectly tagged as «Helper/legacy surface; not part of strict WSDL parity claim» inDRY_RUN_PAYLOAD_EXCLUSIONSand propagated through PR #185 body + #176 audit + final milestone report — until PR #194 finally removed the entry. The code-fix landed, but the policy gap that allowed the mis-classification in the first place was never closed.Change
CLAUDE.md — new «Strict WSDL parity» convention in Key Conventions, listing the only five legitimate permanent exclusion categories (read-path *.get / runtime-deprecated / v4-not-in-v5-wsdl / custom non-RPC / covered by test_dry_run.py). Explicitly bans helper/legacy/not-part-of-strict-WSDL-parity rationale as mis-classification.
tests/test_api_coverage.py — new
test_dry_run_exclusions_have_no_helper_or_legacy_rationaleguard that fails if any rationale uses banned phrases. Verified both positive (passes on clean main) and negative (temporarily addedHelper/legacy surface ...entry and it failed with clear offender list + 0.3.8 — Strict WSDL parity: убрать категорию «Helper/legacy» из DRY_RUN_PAYLOAD_EXCLUSIONS #199 ref).Verification
pytest -q tests/test_api_coverage.py::TestApiCoverage::test_dry_run_exclusions_have_no_helper_or_legacy_rationale→ 1 passed.ruff check tests/test_api_coverage.py→ clean.