Rule catalog

Status: Contract, Care Plan, Care Coordination, and Medication Management semantic rule map, v0.2

This is the target business-rule contract, subordinate to the source hierarchy in README.md, SETTLED decisions in 08_Decision_Log.md, the roles contract, and the applicable pillar SOP. machine/sop-0.2.schema.json and the Care Plan YAML do not yet implement every field below (notably edge-case linkage, rule-specific category assertions, and full clock/task/evidence execution). Until that migration is complete, the machine artifacts remain non-activatable.

Rule contract#

Every production rule contains or references the following machine-enforceable contract. Free-text purpose and action descriptions never substitute for typed guards, transitions, clocks, tasks, or evidence.

rule_id: CP-001
version: 2.0.0
status: draft | validated | active | retired
pillar: care_plan
material: true | false
purpose: plain-language description
edge_case_ids: [stable edge-case IDs]
automation_class: none | evidence_only | administrative | clinical_execution | external_release
input_requirements:
  - fact_id: stable fact ID
    accepted_record_states: [explicit epistemic states]
    current_required: true | false
    value_contract_id: typed value contract
condition:
  fact: stable fact ID
  target: record_state | value
  path: JSON Pointer declared by the value contract
  op: typed operator
  value: typed operand, omitted only for exists/not_exists
unknown_policy: explicit fail-safe or RULE_GAP_HOLD; never implicit permission
outcome:
  transition_id: stable transition ID
  transition_class: advance | hold | evidence_pursuit | safety_escalation | terminal | retry | task_outcome | rule_gap
  from_state: exact source
  to_state: exact destination
  permitted_automation: [bounded actions]
task:
  task_type: null or approved task type
  owner_role: exact role
  backup_role: exact role
  edge_case_ids: []
  payload_contract_id: typed task payload
  idempotency_key_fields: [declared paths]
  allowed_outcomes: [typed outcomes and transitions]
clock:
  origin: state/task/event timestamp
  duration: ISO-8601 duration or NONE
  calendar_id: versioned calendar
  timezone: IANA timezone
  on_miss_transition_id: explicit transition or null
retry:
  strategy: none | fixed | exponential
  max_attempts: bounded integer
  interval: ISO-8601 duration or NONE
  retry_transition_id: explicit transition or null
  exhaustion_transition_id: explicit transition or null
authority:
  required_actor: role or NONE
  decision_scope: exact affected element/version
priority: P0 | P1 | P2 | P3
blocked_actions: []
evidence_ids: []
audit_artifacts: []
billability_effect: none | supporting | qualifying | blocking
source_basis: []
test_case_ids: []
owner: named function
approval: [clinical, compliance, privacy, operations, product as applicable]
effective_at: timestamp or null
retired_at: timestamp or null

Condition evaluation uses TRUE, FALSE, and UNKNOWN. Only TRUE enables an ordinary action transition. Missing, stale, conflicted, retracted, superseded, future-received, or otherwise ineligible values cannot satisfy a negative comparison. Zero safe matches, unsafe unknowns, or overlaps enter an explicit rule-gap hold. Tests link bidirectionally to rules and must prove rule-specific positive, negative, ambiguous, and failure behavior rather than merely carry a category label.

Automation-class invariants:

• clinical_execution requires a structured, current, scope-matched licensed-authority event naming the actual actor, credentials, organization, affected element/version, and allowed action. required_actor: NONE is invalid.
• external_release is unavailable to L0 in V1 under D-007. Transmission requires an authorized-human release event matching the exact permission basis, recipient, purpose, channel, plan version, and approved content identity.
• Evidence preparation, routing, or task creation never inherits the authority of the person expected to resolve the task.
• Any OPEN/BLOCKED decision referenced by the rule prevents production activation and any closure path dependent on that decision.

Care Plan stable-ID migration map#

The current machine file contains CP-001 through CP-023 with gaps at CP-008, CP-015, and CP-016. Those gaps must not be reused because this folder has no Git history from which retirement can be disproved. Existing IDs are preserved; semantic rewrites increment their major version and remain draft.

Draft version targets are 2.0.0 for CP-001-005, CP-007, CP-009-010, CP-012-014, CP-017-018, and CP-020-023; CP-006, CP-011, and CP-019 target 3.0.0. Every material rule uses exact rule-specific tests CP-T-<RULE-ID>-POS, -NEG, -AMB, and -FAIL, plus edge/boundary cases. source_basis must name the exact source IDs/sections or decision IDs in this catalog; a generic "CMS" citation is invalid.

Legacy Care Plan test-ID migration#

The existing IDs are preserved and rewritten as executable v0.2 fixtures; they are not silently retired or replaced. New rule-specific and edge-specific IDs supplement them.

Care Plan semantically versioned rules#

CP-006 v3.0.0 -- Unconfirmed conversational preference#

IF BENEFICIARY_CHOICES.record_state IN
   [CANDIDATE_EXTRACTED, PENDING_VERIFICATION]
OR BENEFICIARY_CHOICES.value.validation_status != AUTHENTICATED
THEN transition_class = EVIDENCE_PURSUIT
AND state = BENEFICIARY_VALIDATION_REQUIRED
AND create idempotent NAVIGATOR_VERIFY task
AND canonicalize/publish/release = BLOCKED for the affected element

Only L2 may validate the choice. Missing/stale/conflicted evidence yields UNKNOWN and the explicit safe hold; it never becomes a negative permission.

CP-011 v3.0.0 -- Decision-specific authority conflict#

IF an affected plan element has authenticated competing choices
AND controlling decision-specific authority is UNKNOWN, CONFLICTED,
    EXPIRED, CONDITIONAL_UNRESOLVED, or CAPACITY_REVIEW_REQUIRED
THEN state = AUTHORITY_UNCLEAR
AND affected_element = BLOCKED
AND all assertions/dissent remain immutable
AND create the authority/capacity task permitted by O-011

If a capable authenticated beneficiary controls the decision and caregiver authority is noncontrolling, CP-011 is FALSE; caregiver dissent is retained but does not block CP-009.

CP-019 v3.0.0 -- Version-bound care-plan distribution failure#

IF RECIPIENT_OBLIGATION_MANIFEST identifies a required current obligation
AND DISTRIBUTION_LEDGER records a release/transmission/delivery/access failure
AND the versioned channel policy requires correction, retry, or exhaustion handling
THEN state = DELIVERY_FAILED
AND the committed plan version remains active
AND create only the task allowed by recipient authority, D-007, O-012, and O-014

Release, transmission, delivery, access, receipt, refusal, failure, exhaustion, and authorized exception are distinct values. An automated retry may not create a new PHI release. Failure or retry exhaustion is never satisfaction and cannot enable CP-018; it remains open in DELIVERY_FAILED unless a pre-existing exception class is later permitted by settled O-012.

Proposed new Care Plan rule reservations#

The following are design reservations, not yet authoritative assignments. Confirm them against any external rule history before writing the v0.2 Care Plan YAML. CP-008, CP-015, and CP-016 remain unused/reserved. Each reservation targets draft version 1.0.0, must cite the source/decision shown, and must use stable rule-specific test IDs before integration.

Care Coordination semantic rule map#

Status: DRAFT v0.2 semantic meanings only. New numeric rule IDs are deliberately not assigned until the Care Coordination semantic contract, the full semantic SOP set, and the later fault gates are complete. Existing stable IDs CC-021, CC-033, and CC-047 are retained and require major semantic version changes rather than silent prose edits.

Care Coordination rules must preserve these business invariants:

• one parent case contains applicability-aware, route-specific obligations; there is no universal referral chain;
• receipt, access, appointment, encounter, document, service, and care-plan outcomes belong to their exact recipient/attempt/episode/version;
• missing proof is UNKNOWN or missing evidence, not Boolean false;
• an attempt, task escalation, local edge resolution, or child-obligation outcome does not automatically close the parent case;
• successful specialist-loop closure, truthful non-success case disposition, and GUIDE service qualification are different results;
• urgency is a cross-case interrupt, not a routing class;
• terminal cases are immutable; late material evidence may open a linked successor; and
• every OPEN/BLOCKED decision referenced by an obligation prevents activation of the dependent path.

Route-specific obligation families#

CC-021 v2 target -- Required receipt or access evidence remains unknown#

CC-021 applies only when a route-specific policy requires receipt or access evidence for the exact release/request. Its trigger is a canonical release event, a due clock under settled policy, and the absence of a correctly matched receipt/access event as of evaluation. It must preserve explicit rejection, delivery failure, late evidence, wrong recipient/version, and unknown as distinct facts.

Its permitted outcome is a bounded administrative pursuit task and waiting/exhaustion disposition for that obligation. It cannot convert unknown to false, authorize a re-send, satisfy the obligation, or close the parent case. Timer origin, calendar, attempts, backup, channel sequence, and exhaustion remain blocked by O-004/O-020/O-021.

Minimum tests: required versus not-required receipt; no matched event; explicit failure; wrong-version receipt; late receipt; duplicate receipt; retry exhaustion; and parent case with another open obligation.

CC-033 v2 target -- Encounter occurred but matched documentation is absent#

CC-033 applies only to a specialist/provider path for which a canonical encounter-completion event exists and the required correctly matched visit documentation is absent as of the settled clock. A candidate, partial, illegible, wrong-patient, wrong-encounter, or unverified document does not satisfy the obligation.

Its permitted outcome is records pursuit and continued specialist-loop hold under D-009. Receipt of valid documentation resolves only the document obligation; successful loop closure still requires authorized reconciliation and resulting child work. Explicit no-record response and exhaustion remain non-success facts, not closure evidence.

Minimum tests: no encounter; encounter/no note; wrong note; partial note; valid note/no reconciliation; valid note/no-change disposition; late note after nonterminal case; and late material note after terminal case.

CC-047 v2 target -- Possible clinical instruction reaches administrative support#

A raw or candidate signal that may contain a new clinical instruction is sufficient to impose the conservative administrative block. It is not sufficient to verify the instruction or authorize action. L1 records the content verbatim, does not interpret or relay it, and invokes routing to the actual role required by O-003; an RN is not a universal destination.

Only an authenticated, scope-matched clinical disposition may clear the block and determine the resulting care-plan, medication, coordination, or communication action. Wrong-patient content also invokes identity/privacy review.

Minimum tests: purely administrative response; mixed content; false positive; unverified sender; wrong patient; medication order; urgent symptom; authorized no-action disposition; and attempted L1 relay.

Medication Management semantic rule map#

Status: DRAFT v0.2 semantic meanings only. New numeric rule IDs are deliberately not assigned until the Medication semantic contract, the full semantic SOP set, and the later fault gates are complete. Existing stable IDs MED-017, MED-023, and MED-041 are retained and require major semantic version changes rather than silent prose edits.

Medication rules must preserve these business invariants:

• request/proposal, order, transmission, pharmacy response, dispense/reversal, possession, reported use, administration, reconciliation, stop/cancel/disposal, provider agreement, instruction, and execution remain separate event families;
• CONFLICTED links retained assertions and never overwrites them;
• a shared reconciled regimen is a time-bound prescribing-clinician disposition over a named evidence snapshot, not proof of actual use and not a replacement for source provenance;
• every applicable initial/future assessment reaches a clinician with actual prescribing authority, including clean/no-change cases;
• terminology normalization and clinical-review-condition detection do not decide equivalence, risk, urgency, advisability, treatment, or causality;
• recommendation sharing, the relevant-provider agreement gate, final clinical decision/order, recipient instruction, pharmacy execution, and reported implementation are independent obligations;
• an outside-provider order/recommendation retains its own authority/effective status and reconciliation route; it is neither forced into the GUIDE-originated proposal route nor converted into a beneficiary instruction on receipt;
• missing, stale, reversed, wrong-version, wrong-scope, or otherwise ineligible evidence never becomes negative proof or permission;
• safety can interrupt any case and opens a separate US clinical pathway without asserting medication causality;
• route-specific case closure and GUIDE service qualification are independent; and
• terminal cases are immutable; late material evidence may open a linked successor.

Route-specific obligation families#

MED-017 v2 target -- Apparent dispense after authorized stop#

MED-017 applies only after the beneficiary/product identity, actual event type, authorized stop decision and effective time, and apparent post-stop dispense/handoff are sufficiently established. A delayed source record, preparation without handoff, partial fill, claim later reversed, wrong patient/product, or dispense that occurred before the stop does not satisfy the same condition.

When the condition is established, preserve the stop, pharmacy, possession, reported-use, and administration planes; create a conflict; withhold any new instruction that assumes either regimen; and route the exact evidence to the prescribing-authority clinician. The rule does not prove pickup, taking, harm, or urgency. P1 cannot be hardcoded while O-004 is open.

Resolving the pharmacy event alone does not close the medication case. The applicable current regimen, possession/use, recipient communication, pharmacy status, and safety obligations must receive their own dispositions.

Minimum tests: valid post-stop handoff; dispense before stop but received late; prepared/not handed over; reversed claim; partial fill; mail order; wrong identity; cancel acknowledgment; household possession; reported taking; no symptoms; and possible safety signal.

MED-023 v2 target -- Unresolved caregiver-reported medication identity#

MED-023 preserves a caregiver report verbatim and keeps the medication identity candidate-only when the source text does not support an exact approved terminology mapping. A probabilistic confidence score may route evidence pursuit; it cannot promote the identity, establish equivalence, or decide whether clinical review is safe to skip.

L0 may request the rule-selected label/source evidence; L1 may request the previously specified bottle image or verified source record; L2 may authenticate the report. Compounds, supplements/natural products, ambiguous strength/form, and illegible labels remain unresolved at the supported level. A possible safety signal from the raw report still invokes the safety path even while identity is unresolved.

Minimum tests: exact deterministic identity; ambiguous brand; wrong strength/form; compound; out-of-scope supplement; illegible image; high-confidence wrong OCR; wrong patient; caregiver correction; evidence never obtained; and concurrent safety signal.

MED-041 v2 target -- No current exact relevant-provider agreement#

MED-041 applies to an exact GUIDE change proposal only after the settled rule establishes two separate manifests: the PCP/applicable-specialist recommendation-sharing recipients and the PCP or medical specialist whose response is required for the agreement gate. It looks for a current, authenticated, scope-matched AGREES event from every provider required by the agreement manifest. It must not require agreement merely because a provider belongs on the sharing manifest, and valid agreement does not erase an unsatisfied sharing obligation. It must not use a generic agreement != AFFIRMATIVE comparison that collapses missing, stale, modified, declined, revoked, wrong-provider, wrong-scope, and wrong-version evidence.

Without the required current agreement, the proposed regimen cannot become active through this route, and dependent medication-change instruction/execution remains blocked. L1 may pursue administrative status; clinician-to-clinician work follows O-005/O-029. MODIFIES creates a new proposal; DECLINES, NO_RESPONSE, UNKNOWN, and REVOKED retain their truthful outcomes. Timeout never grants permission.

Agreement still does not create the final lawful order, recipient instruction, pharmacy execution, reported implementation, or service qualification.

Minimum tests: sharing recipient who is not an agreement authority; agreement authority who overlaps the sharing manifest; exact valid agreement with another share delivery still open; GUIDE prescriber is also the relevant PCP; multiple agreement authorities; office-staff receipt; silence; wrong provider/scope/version; stale agreement; partial/conditional agreement; MODIFIES; DECLINES; revocation; proposal changed after agreement; beneficiary refusal/self-change; and exhausted attempts.

Governance#

• Rule changes require version increments and named approval.
• Prior versions and every fact event remain replayable.
• A rule-gap event cannot be handled by allowing an LLM to improvise.
• Emergency and clinical rules require clinical approval before activation.
• Privacy/release rules require privacy/compliance approval.
• Billability rules require compliance and billing approval.
• Changes to executed-PA-dependent assumptions remain blocked until cross-checked against the participant's actual agreement.
• Structural or guard-path validation does not prove clocks, tasks, retries, communications, evidence, closure, regulatory approval, or operational activation.