Skip to main content

Supplemental invoices bill a drifted week's late hours; reissue is only for wrong invoices

Drift (a sent invoice missing billable hours logged after send) previously had one remedy: void-and-reissue. That dead-ends on a paid parent (voiding a settled invoice is wrong), forces an unapply/re-apply dance on a partial one, and makes the facility disregard a number it already processed — churn for a document that was never wrong, merely incomplete. We split the remedies: a supplemental invoice — a child invoice with origin='supplemental' and a parent link, billing only the week's late hours — is the drift remedy; reissue remains for invoices whose billed content was wrong (rate, lines, over-billing). Drift only ever detects under-billing, so the badge steers to "Bill late hours".

The supplemental prices the delta at the parent line's rates (one week, one rate, regardless of when hours were keyed), shares the week's contracted cap with its family (unapproved overage is attributed but billed at zero, per the established overage rule), and gets its own number, terms, and aging. Drift becomes family-aware: a family is clear when every billable hour in the week is attributed to a live member, and paid parents re-enter the drift badge — for the first time there is an action for them. A parent with live supplementals cannot be voided, reissued, or deleted (void the children first; a voided child honestly re-drifts its parent). Repeat supplementals are allowed — the delta math makes the Nth as safe as the first — with one open draft at a time.

Rejected: reusing replaces_invoice_id for the parent link — "disregard the old invoice" and "the old invoice remains payable" are opposite AR instructions and must not share a column. Rejected: widening drift and supplementals to scan all facility-week assignments rather than the parent's line items — every live assignment already gets a line (even at zero hours), so the only invisible case is a contractor terminated before generation or an assignment created after send; two stacked rarities don't justify a heavier predicate on the hot dashboard path. That gap is the documented limit of this design.

Known limit — attribution vs. delta on over-cap hours: a supplemental's send claims every unattributed payable hour of the week on its line assignments, but bills only the capped delta, so unapproved over-cap hours are attributed at $0 and the family's drift badge clears while they stay unbilled. That is the established overage rule, not a leak — the hours remain recoverable (approving the week's overage lifts the family cap and a later supplemental bills exactly the lifted delta), and the dashboard's unbilled-overage figure is the standing backstop. Note the backstop's own limits: it looks back four weeks and only at active assignments. (Owner decision 2026-08-20: accepted, with a follow-up — a family-level "billed hours < capped hours" drift predicate, so the badge does not clear while capped-out hours remain unbilled. Built as invoice_drift v4 in migration 0114: the badge now fires exactly when the supplemental preview would show a positive delta — approving an overage re-badges the family, and over-cap-only late hours no longer badge with nothing to bill behind the button.)

Boundary notes: a terminated contractor with a parent line still bills (the line proves the week's billable relationship; our HR timing must not shrink a facility's bill). A written-off parent (ADR-0053, when built) keeps badging and offering "Bill late hours" — write-off abandons a specific receivable, it does not gag billing for real work; the write-off implementation must not exclude drifted families. Payroll is untouched throughout: pay selects by date and status, never by invoice attribution (ADR-0050's contract is preserved). (Decided 2026-08-20 in the supplemental-invoice grilling session.)