fix: stop the tool making claims its own code does not support

[webdevsamran]

Four defects, all the same shape: something asserted a fact that was never checked against the thing it described. This is the plan's §2.0 finding, closed.

The README showed output the code cannot produce

README claimed	Code emits
CHG-OPERATION-REMOVED-1	CHG-OPERATION_REMOVED-…
CHG-PARAM-REQUIREDNESS-2	CHG-PARAMETER_REQUIREDNESS-…
DRIFT-FIELD	DRIFT-MISSING-FIELD
DRIFT-UNDECLARED	DRIFT-UNDECLARED-FIELD

Change ids are built from kind.value.upper() and every ChangeKind value is snake_case, so a hyphen there is not producible. A reader who copied an id out of the README and grepped for it found nothing.

Examples are now captured from real runs by scripts/capture_readme_examples.py and spliced between markers, with --check wired into CI. Confirmed non-vacuous: restoring one hyphenated id fails the check with a diff.

Capturing it surfaced why nobody noticed

The shared terminal renderer looks for a severity and a rule_id. A Change has neither, so apiverity diff printed:

[]  operation 'DELETE /users/{id}' was removed

An empty bracket, and the change id dropped entirely — even though every Change carries one for exactly this purpose. Now:

[meta] CHG-OPERATION_REMOVED-92658ed2-1  operation 'DELETE /users/{id}' was removed

Change ids lacked the property the docs promised

Documented as CHG-{kind}-{operation-hash}-{index}; emitted as a flat CHG-{KIND}-{N} from one counter shared across every operation. Measured:

GET /zebra alone     : CHG-PARAMETER_REQUIREDNESS-1
after adding /alpha  : CHG-PARAMETER_REQUIREDNESS-2     ← same change, new id

An id quoted in a review, or used to suppress a finding, pointed somewhere else once an unrelated endpoint appeared. The ordinal is now scoped per (kind, operation).

Being precise about what was not broken, because the doc's wording implied more than was wrong: stability under document reordering already held, since run() iterates sorted() over operation keys. I checked before claiming credit for it — 3 of the 7 new tests pass against the old implementation. ARCHITECTURE.md now separates the two guarantees instead of attributing both to the id format.

The artifact envelope asserted three unchecked things

• tool_version was the literal "0.1.0" — every result bundle, JSON export and SARIF upload ever written claimed 0.1.0 whatever produced it. A consumer diffing two bundles would conclude the tool had not changed. Read from the installed package now, and the test compares it to pyproject.toml rather than to a literal, so the test cannot go stale itself.
• protocol_version was fixed at "openapi-3.x" — a gRPC or AsyncAPI run wrote an artifact claiming to be OpenAPI. Now grpc for a .proto, verified.
• redaction was {"applied": true, "sensitive_field_count": 10} on every artifact, unconditionally. enrich() performs no redaction at all. That was a fabricated claim about a security control, stamped identically onto outputs with nothing sensitive in them — and it was machine-readable, so tooling consumed it. It now reports that no redaction applied here and points at traffic/redact.py, where redaction genuinely happens.

The existing test asserted redaction["applied"] is True, pinning the fabrication in place. It asserts the truth now.

Verification

ruff ✅ · mypy (90 files) ✅ · pytest 81.08% against a 72% floor ✅ · e2e ✅ · capture_readme_examples.py --check ✅ · generate_rule_catalog.py --check ✅

Also corrects ARCHITECTURE.md's "React 18" against a package.json on 19.2.8.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

API Verity — contract review

One comment per PR — updated on each push.