ORA-2026-0121 - AR-Side Ground Truth Is Invoice-Only

ORA-2026-0121 - AR-Side Ground Truth Is Invoice-Only

Rule

For accounts receivable (AR), BuilderTrend invoices and QuickBooks invoices issued by HCB are the only source-of-truth records for what HCB billed a client. Bills and receipts are supporting evidence. They are not AR ground truth and must never be promoted into client-charge truth without HCB-issued invoice proof.

Accounts payable (AP) remains its own truth domain. Vendor-issued documents that say "invoice" on the page are AP evidence in this taxonomy. They can prove what HCB owed or paid; they cannot prove what HCB billed.

QuickBooks is being phased out, but any QuickBooks invoice that exists during the overlap period remains authoritative. BuilderTrend invoices are the forward source. The overlap creates a dual-invoice authority set, not permission to infer client billing from lower layers. If BuilderTrend and QuickBooks disagree for the same charge, the conflict is a hold requiring reconciliation; no consumer may pick a winner silently.

For this doctrine, the AR invoice authority set includes HCB-issued invoices plus their system-native voids, credits, credit memos, and adjustments. Non-invoice artifacts may explain or reduce an invoice only when the invoice system carries that effect.

Glossary:

• HCB-issued invoice: a BuilderTrend or QuickBooks invoice sent or recorded

by HCB as a client billing artifact.

• Bill: a BuilderTrend bill row, QuickBooks bill, vendor-issued invoice, or

vendor bill attachment that records cost/obligation evidence for HCB.

• Receipt: payment/settlement evidence for what HCB paid, including card

receipt, payment record, or statement-backed payment proof.

The One-Way Chain

invoice -> bill -> receipt -> physical event

This arrow is explanatory, not symmetric. An invoice can cite or be explained by bills, receipts, purchase evidence, selections, and physical work. A bill, receipt, vendor document, or physical event cannot by itself prove that HCB billed the client.

The arrow is also not a time-flow. Physical work and payment often happen before a client invoice. The arrow points from AR authority down to supporting evidence. Reading the chain right-to-left - promoting a physical event, receipt, bill, or vendor invoice into an HCB-issued invoice claim - is the canonical violation this doctrine forbids.

Bills and receipts sit at different AP altitudes. A bill says HCB owes or was charged; a receipt says HCB paid or settled. Partial payments, retainage, disputes, and revisions mean they do not always agree.

Inverting the chain creates false reconciliation: the map becomes structurally complete while materially wrong.

Authority Table

The bill-to-invoice relationship is not 1:1. Bills can be bundled, split, excluded, revised, charged differently, reimbursed differently, or never invoiced to the client. Any pipeline assuming one bill row becomes one client charge manufactures false reality.

Relationship To ORA-2026-0114

ORA-2026-0114 remains true: receipts, vendor registries, cost codes, labor, client invoices, change orders, and project financials belong in heartwood-db as client-facing financial truth.

This doctrine sharpens the authority altitude:

• Receipts are AP-side truth - what HCB paid, incurred, or can cost-code.
• Bills are AP-side truth for vendor obligation - what HCB owed, was

charged, or received as cost evidence.

• Bills are proxy or candidate AR evidence only - evidence of billing intent

or possible client-charge support, never client-charge truth by themselves.

• HCB-issued invoices are AR-side truth - what HCB actually billed the

client.

This distinction does not demote receipts. It prevents an AP fact from being silently recast as an AR fact.

When The Rule Fires

The rule fires whenever a write site, query, proof packet, UI, report, or agent judgment uses any of these meanings:

• billed
• charged
• client charge
• what we billed you
• invoice total
• owner billed
• AR balance
• client-facing financial display

If the claim is about billed-to-client truth, it must read from BuilderTrend or QuickBooks invoices. Bills, receipts, selections, vendor docs, and email evidence can be shown as support only when labeled as support.

A change order is AR-candidate, not AR truth. An executed change order becomes AR truth only when it appears on a BuilderTrend or QuickBooks invoice, or when the invoice system carries the corresponding adjustment.

Default Surface Contract

Client-facing and operator-facing AR surfaces MUST:

1. Read billed amounts from invoice records only. 2. Label bill-derived values as bill evidence, candidate cost, internal cost, or another non-AR term. 3. Label receipt-derived values as paid cost, receipt evidence, or AP-side proof. 4. Preserve invoice source identity: BuilderTrend versus QuickBooks, invoice id/number, date, status, credit/void/adjustment state, and provenance. 5. Treat missing invoice proof as a hold, not as permission to fill the gap from a bill. 6. Treat BT/QB invoice disagreement as a hold until reconciled.

Internal diagnostic surfaces MAY show bill and receipt candidates near AR records, but the row must carry its authority role before its amount is interpreted.

Query Interface Discipline

Flat query outputs hide altitude. A row from bt_bill, a receipt table, and an invoice table can all expose amount, project_id, vendor, and date, but those columns do not mean the same thing.

Every finance query that could feed AR reasoning must first ask:

what kind of financial fact is this row?
HCB-issued invoice | invoice-native adjustment | bill | vendor-issued invoice | receipt | payment | physical-event evidence | proxy/candidate

Then it must ask:

what effects may this row have?
render client charge | corroborate invoice | cost-code AP | candidate review | diagnostic only

Rows without an explicit authority role default to non-AR evidence.

Audit-And-File Pattern

Do not mass-rotate finance code from this doctrine alone. When a Codex seat finds a live surface treating bills or receipts as AR truth, file or claim one narrow ticket per independent write site.

Each violation ticket should include:

SURFACE:
FALSE_PROMOTION:
CURRENT_SOURCE:
REQUIRED_INVOICE_SOURCE:
USER_RISK:
SCOPE_BOUNDARY:

SCOPE_BOUNDARY names the line that keeps the fix from becoming a broad finance migration. This keeps the fix faithful to the real surface instead of turning one correction into a speculative bundle.

Marquet Frame

Control

Seats can state intent without asking Chad: if the output says what HCB billed a client, demand invoice proof or route a narrow violation ticket.

Competence

Competence is recognizing that similarly shaped finance rows carry different authority. amount on a bill is not the same world-model claim as amount on an HCB-issued invoice, and a vendor-issued invoice is not an HCB-issued invoice.

Clarity

Surfaces must name the financial altitude before the value is read: AR invoice, AP receipt, bill candidate, supporting evidence, diagnostic witness.

World-Model Fidelity

The correction protects the map from a quiet but expensive lie: treating cost evidence as client-charge truth. Fidelity improves when the map can explain a client invoice using bills and receipts without confusing explanation for authority.

Anti-Patterns

• Rendering a bill amount as "what we billed you for."
• Treating a receipt match as proof that a client was invoiced.
• Auto-linking selection -> bill -> invoice without an actual invoice record.
• Replacing a QuickBooks invoice with a bill-derived BuilderTrend value during

phase-out.

• Silently choosing BuilderTrend or QuickBooks when both contain conflicting

invoice records for the same charge.

• Treating a vendor-issued invoice as if HCB issued it to the client.
• Building reconciliation dashboards where bills and invoices appear as peer

truth rows without authority labels.

• Calling a bill "ground truth" because it has a project, amount, vendor, and

date.

USER-VALUE-CLOSURE

• user: Zack and HCB finance reviewers; downstream client-facing Dollhouse

readers

• surface: BuilderTrend invoice mirror, QuickBooks invoice mirror, Camber

reconciliation/prodigy surfaces, Dollhouse "what we billed you for" views

• change: AR-side reasoning now starts from BT/QB invoices only, while bills

and receipts remain usable as labeled supporting evidence. This prevents bill-as-invoice false reconciliation in finance, attribution, and client-facing surfaces.

• closure_date: doctrine landed 2026-05-02; code rotations proceed only

through narrow violation tickets when live surfaces are proven to invert the chain.

Cross-Stamps

• 2026-05-03 - HWD-0926: Heartwood lane boot files (AGENTS.md, CLAUDE.md, GEMINI.md) now require client-charge surfaces to read AR truth from BT/QB invoice records while labeling bills, receipts, vendor invoices, and change orders as supporting evidence unless invoice proof exists.