contract_to_invoice_audit v1.0.0

name: "contract_to_invoice_audit" description: "Audit a draft invoice against the signed agreement before it is sent: extract billing terms, rates, caps, milestones, and tax treatment into a term sheet, match every invoice line to a term and a delivery record, recompute the math, and report exceptions with evidence and a fix for each one. Triggers when a draft invoice needs checking before sending, a client disputes a rate or a cap, a milestone is about to be billed, or recurring invoices keep drawing corrections."

Contract to Invoice Audit

Purpose

Check your own draft invoice against the agreement that governs it, before the client has to. The audit answers five questions for every line: was this charge agreed, at this rate, for work actually delivered, inside every cap, and taxed the way the contract says. It ships a term extraction sheet, a line matching worksheet with a 12 code exception list, a recomputation tool, and two worked audits, one clean and one with rate and cap errors.

This is the seller side of the check that accounts payable runs on the way in. It does not give legal or tax advice. A contract conflict, a disputed clause, or a tax treatment that looks wrong for the jurisdiction goes to counsel or a tax adviser, with the audit report attached.

Workflow

1. Assemble the governing file first. Collect the signed agreement, every amendment and change order, the current rate schedule, the SOW or order form, the invoice register for this contract, and the delivery records for the billing period. If the signed agreement or the current rate schedule cannot be found, stop and say so. An audit against a proposal, a draft, or last year's rate card produces confident wrong answers.

1. Extract the terms before opening the invoice. Fill in references/term-extraction-sheet.md: rate card with rate years, escalators, every cap with what counts toward it and what has already been billed against it, milestones with their acceptance test, expense classes with receipt and approval rules, discounts and credits owed, tax treatment, billing period and increment rules, exclusions, and closed items. Quote each term and record the section it came from. A charge the contract is silent on is a finding, not a gap to fill with a guess.

1. Recompute amounts already billed. Build the cap picture from the invoice register, invoice by invoice: totals per contract, per phase, per category, per period. Never take a cumulative figure from memory or from a summary tab nobody has checked. A cap test against a wrong starting balance is worse than no cap test.

1. Match every line on the worksheet. Use references/line-matching-worksheet.md, one row per draft line. For each line record the governing term, the delivery evidence, the qty check, the rate check, the recomputed extension, and the cap and tax categories. The delivery leg matters as much as the price leg: a line priced right for work with no timesheet, delivery note, or acceptance record behind it still fails, code X09. This mirrors the standard three-way match on the buyer side, where the purchase order, the receiving record, and the invoice must agree before money moves.

1. Run the recomputation tool. Put the extracted terms and the draft lines into one JSON case file and run bin/audit_check.py. It checks duplicate lines, rates against the rate card, extensions, milestone amounts and acceptance, tax on the taxable categories only, cumulative caps, and the invoice total, all in Decimal to the cent.

bash
python3 ~/workspace/skills/contract-to-invoice-audit/bin/audit_check.py case.json

Exit code 0 is clean, 1 means exceptions, 2 means the case file is malformed. The worked input files and the expected output for both audits are in references/worked-audits.md.

1. Check what the tool cannot see. Work through these by hand on every audit:

• Expenses: receipt attached where the contract requires one, class cap respected, markup only where the contract allows it, pre-approval on file where required (X10)
• Period: every line's work dates fall inside the contract term and the billing period, and no line bills a phase or matter the file shows as closed (X11)
• Credits: retainer balances, prepayments, prompt-pay discounts, and corrections promised on earlier invoices are applied (X12). US payment law treats a payment that ignores an applicable discount or credit as improper, and clients read a missing credit the same way
• Milestones: acceptance evidence exists and the milestone was not already billed (X05)
• Required invoice fields: PO number, billing period, entity names, and tax shown separately where the contract or the jurisdiction requires separate statement

1. Classify and fix in the right order. Fix rates and extensions first, then tax, then totals, then test the caps against the corrected figures. Capping an uncorrected invoice holds the wrong amount. Severity and fixes per code are in the worksheet. Hold the invoice for any cap crossing, any unaccepted milestone, any charge with no contract term, and any line with no delivery record. Everything else is fix the draft, recompute, and rerun.

1. Apply the overlap rule. Report each exception with its own variance, and state the corrected invoice total once. Never add variances that cover the same dollars into one headline figure. A cap hold on a line that also carried a rate error is one pot of money, not two.

1. Decide the overage path before sending. When corrected work crosses a cap, the choices are: bill up to the headroom and hold the rest, get a written amendment first and then bill in full, or write the excess off with the client's relationship owner approving it. Bill the excess and hope is not on the list. Under ceiling style clauses the overage is the seller's risk, and FAR 32.704 states the same plainly for funded limits: work beyond the limit is at the contractor's risk until the limit moves in writing.

1. Close with the cause. If the same code repeats across invoices, name the process fix: a rate card the billing system never updated after an amendment, a timesheet role name that maps to no contract rate, a tax category default that taxes every line. One corrected invoice fixes a month. A fixed source fixes the contract.

Output Contract

Every audit produces:

• The term extraction sheet, filled in, with a quote and a section reference for every billing term used
• The line matching worksheet, one row per invoice line, each row ending in pass or an exception code
• The tool output for the case file, pasted into the report, with the case file kept alongside it
• An exception list: code, line, billed amount, correct amount, variance, the contract quote and delivery record that prove it, and the fix applied or the decision needed
• A cap table: every cap, its limit, previously billed, this invoice corrected, the cumulative total, and the headroom or overage
• A send verdict in one of three forms: send as drafted, send after the listed fixes with the corrected total stated, or hold with the reason and the decision or amendment needed
• A root cause line for any exception code that has appeared on a prior invoice for this client

Operating Rules

• The signed agreement, as amended, is the only source of billing truth. A proposal, an email promise, or a verbal rate does not bill until it is in an amendment. If someone insists a side agreement exists, the audit records the claim and holds the affected lines until the paper shows up.
• Never state a tax rule as universal. Tax treatment turns on the jurisdiction and on what is sold. The audit tests the invoice against the tax treatment written in the contract, and flags silence or a likely conflict for a qualified tax check. Where separate statement is required, check that tax is in fact separately stated and computed only on the taxable categories.
• Keep the evidence trail with the invoice. IRS recordkeeping guidance lists invoices among the supporting documents for gross receipts, and a line that cannot be traced to a term and a delivery record is the line that loses a dispute. File the term sheet, the worksheet, and the tool output with the sent invoice.
• Do not quietly resolve a conflict between contract documents. Quote both, note what the precedence clause says if it says anything, and route it to the relationship owner before the invoice goes out.
• Round the way the contract says. If the contract sets a billing increment or a rounding rule, extensions follow it. If it is silent, compute to the cent and say so on the worksheet.
• An audit that finds nothing still produces the full worksheet and cap table. Clean is a result that needs evidence, not a one line assurance.