reason_code vocabulary leaks a 13th value through an untyped public field

[guangyu-reflexio]

Found during review of #426. Pre-existing.

review_service.py emits reason_code="evidence_unavailable" into ReviewUserPlaybookResult.reason_code, which is declared as a plain str in models/api_schema/domain/entities.py — not the Literal used by CandidateReviewDecision.

So the public vocabulary is effectively Literal ∪ {evidence_unavailable}, enforced nowhere and documented nowhere.

Backward-compatible in the strict sense (the field was never an enum), but:

• API consumers branching on the value silently gain unhandled cases whenever the reviewer vocabulary grows. feat(reviewer): reject playbook entries about systems the agent does not drive #426 added not_agent_decision with no OpenAPI signal.
• The taxonomy itself is not MECE — unsupported_evidence is a genus and absence_inference, unsupported_causality, unseen_artifact, speculative, internal_status are all species of it. Measured consequence: six near-identical candidates asserting the same defect drew four different reject codes, plus a revise, plus an accept.
• Three codes (speculative, redundant, internal_status) have no numbered check defining when they apply, so the model picks among overlapping labels with no tie-breaker.

Worth deciding whether the public field should be typed, and separately whether the codes need a strict precedence order (most specific species first, unsupported_evidence as the catch-all genus last). The prompt already does this for checks 7–8 — "Checks 7-8 only" — and that is the one place labelling is consistent.

[guangyu-reflexio]

Vocabulary half fixed in #439 (+ enterprise #967 for the public docs).

ReviewUserPlaybookResult.reason_code is now a 13-value Literal — the reviewer's 12 plus evidence_unavailable — defined once in models/api_schema/domain/enums.py and imported by both the reviewer and the public entity, so the enforced schema and the advertised schema cannot drift. The JSON schema advertises one enum instead of an untyped string, and the docs enumerate it.

Leaving this open for the MECE half, which is the harder and more interesting part:

• unsupported_evidence is a genus; absence_inference, unsupported_causality, unseen_artifact, speculative and internal_status are all species of it. When a candidate is an absence-inference, both labels are literally correct — the model faces a genuine tie, not a comprehension failure.
• speculative, redundant and internal_status appear in the enum and in decision rule 4 but have no numbered check defining when they apply.
• Observed consequence: six near-identical candidates asserting the same defect drew four different reject codes, plus a revise, plus an accept in a single arm. The accept stored the defect.

The likely fix is precedence, not consolidation. Real taxonomies rarely achieve exclusivity; they impose an order. The prompt already does this for one pair — "Always reject a check-7 failure … Checks 7-8 only" — and that is the one place labelling is consistent. Extending a strict order (most specific species first, unsupported_evidence as the catch-all genus last) would fix the scatter without redesigning the contract.

Two cautions for whoever picks this up:

1. Do not merge codes that differ in remedy. Folding check 8 into internal_status was built and measured: it pruned the target identically but destroyed 3 healthy entries, because "entry about an internal event" is fatal while "entry resting on one as proof" is repairable by revision.
2. This is a prompt behaviour change, so it needs measurement, not a refactor. Both reviewer checks are dose-dependent — a ~60-word compression of check 8 fired zero times, and a trimmed check 7 went from 36% pruning to inert. See docs_for_coding_agent/prompt-change-evaluation.md in the enterprise repo for the harness, and test_reviewer_manifest_regression.py for the in-repo positive control.