diff --git a/docs/acceptance-policy.md b/docs/acceptance-policy.md new file mode 100644 index 0000000..d0402f3 --- /dev/null +++ b/docs/acceptance-policy.md @@ -0,0 +1,105 @@ +# Characteristic Acceptance Policy Boundary + +Policy version: `acceptance-policy/v1` + +repo-scoping separates fact generation, quality gating, and acceptance +judgement. This boundary exists so deterministic automation can stay useful and +fast without silently promoting weak or non-native claims into registry truth. + +## Boundary + +Deterministic scanners and extractors may create observed facts, source refs, +content chunks, candidate abilities, candidate capabilities, candidate features, +and candidate evidence. They may also run transparent quality gates. + +Deterministic quality gates may reject, invalidate, downgrade, merge, flag, or +require review when a criterion is formally expressible. They must record the +criterion identifier, outcome, rationale, and affected candidate element. + +Deterministic quality gates must not approve candidate characteristics. No +deterministic rule, scanner result, fixture match, vocabulary match, confidence +threshold, source-role score, or duplicate check may mark a candidate as +approved registry truth. + +Human reviewers may approve candidate characteristics. + +Trusted agentic reviewers may approve candidate characteristics only after +inspecting the evidence, applying the active quality criteria, and recording a +rationale tied to those criteria and source refs. + +All automated review outcomes must be inspectable, reversible, and auditable. + +## Allowed Deterministic Outcomes + +- `pass`: no formal criterion blocked the candidate; judgement is still pending. +- `requires_review`: a criterion found ambiguity that needs reviewer judgement. +- `downgraded`: the candidate remains visible but loses trust or native-utility + strength until a reviewer overrides or edits it. +- `rejected`: the candidate should not be accepted as stated, but remains + auditable with reason codes. +- `invalidated`: the candidate is structurally or evidentially unusable. +- `merged`: the candidate was folded into a better-supported equivalent. +- `flagged`: the candidate remains pending with a warning attached. + +These outcomes may prepare a candidate for review. They do not approve it. + +## Allowed Human Outcomes + +- `approve`: accept the candidate as registry truth. +- `approve_with_edits`: accept after reviewer edits, relinks, or merges. +- `reject`: reject the candidate as a matter of judgement. +- `downgrade`: preserve the candidate but reduce its standing or native claim. +- `request_changes`: ask for edited wording, source refs, hierarchy placement, + or evidence. +- `request_human_review`: defer to another curator or domain owner. + +## Allowed Agentic Outcomes + +- `approve`: accept only with evidence-linked rationale and criteria version. +- `approve_with_edits`: accept after proposed edits, relinks, or merges are + recorded. +- `reject`: reject with cited criteria and evidence. +- `downgrade`: keep visible but lower trust or native-utility standing. +- `request_human_review`: stop automation when evidence or intent is ambiguous. +- `propose_edit`: suggest wording, hierarchy, source-ref, or merge changes + without approving. + +Agentic approval requires: + +- reviewer identity or configuration +- criteria version +- prompt or policy version when applicable +- evidence inspected +- rationale +- exact candidate elements affected + +## Legacy Auto-Approval Terminology + +`trusted_auto_approve_candidate_graph` and UI labels such as "Trusted +auto-populate" are legacy terminology. They describe an existing migration-era +behavior, not an accepted policy direction. Future implementation must replace +that path with agentic review or leave candidates pending human review. + +Until the migration in `RREG-WP-0014` is complete, any artifacts produced by the +legacy path must be identifiable in review decisions and self-scoping +assessment artifacts. They should be treated as review debt, not as evidence +that deterministic approval is allowed. + +## Quality Criteria Relationship + +The quality criteria registry defines the formal checks deterministic gates may +apply. Criteria should be versioned, reviewable, and specific enough to explain +why a candidate was rejected, downgraded, invalidated, merged, flagged, or sent +to review. + +Examples of criteria families: + +- source-role quality +- native utility versus dependency, tooling, fixture, or mention-only context +- hierarchy fit between capability and feature +- evidence sufficiency +- circularity from generated `SCOPE.md` +- fixture and schema-example contamination + +Criteria can block bad output before judgement. They cannot stand in for +judgement. diff --git a/tests/test_acceptance_policy_docs.py b/tests/test_acceptance_policy_docs.py new file mode 100644 index 0000000..3e40e2c --- /dev/null +++ b/tests/test_acceptance_policy_docs.py @@ -0,0 +1,17 @@ +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +POLICY = ROOT / "docs" / "acceptance-policy.md" + + +def test_acceptance_policy_defines_deterministic_boundary(): + text = POLICY.read_text(encoding="utf-8") + + assert "Policy version: `acceptance-policy/v1`" in text + assert "Deterministic quality gates must not approve" in text + assert "`requires_review`" in text + assert "`invalidated`" in text + assert "`approve_with_edits`" in text + assert "`trusted_auto_approve_candidate_graph`" in text + assert "legacy terminology" in text diff --git a/workplans/RREG-WP-0014-agentic-characteristic-acceptance.md b/workplans/RREG-WP-0014-agentic-characteristic-acceptance.md index 111b715..456eae1 100644 --- a/workplans/RREG-WP-0014-agentic-characteristic-acceptance.md +++ b/workplans/RREG-WP-0014-agentic-characteristic-acceptance.md @@ -30,7 +30,7 @@ candidate into approved registry truth. ```task id: RREG-WP-0014-T01 -status: todo +status: done priority: high state_hub_task_id: "4bc2e749-ec9e-45d4-8095-63181efb752b" ``` @@ -56,6 +56,13 @@ Acceptance criteria: - The allowed deterministic outcomes are explicitly listed. - The allowed agentic outcomes are explicitly listed. +Implementation note 2026-05-15: added `docs/acceptance-policy.md` with policy +version `acceptance-policy/v1`, the deterministic gate versus acceptance +judgement boundary, allowed deterministic/human/agentic outcomes, audit +requirements, and migration language for legacy +`trusted_auto_approve_candidate_graph` terminology. Added a documentation test +that locks in the boundary language. + ## T02: Create Transparent Quality Criteria Registry ```task