change_order_reconciliation v1.0.0

name: change_order_reconciliation description: "Reconcile a contractor or agency invoice against the work that was actually approved: keep a running change order log from signing to final payment, match every invoice line to base scope or an approved change order, check approval and completion evidence behind each order, flag billed work with no approval trail, and pay the undisputed lines while holding only the disputed ones. Triggers when an invoice or pay application includes extra work, a change order is billed before it was signed, cumulative billing may pass the authorized sum, or a job is closing and held items need a final decision."

Change Order Reconciliation

Purpose

Answer one question per invoice line: was this work in the original scope, or in a change order that was approved in the form the contract requires, at this amount, and is there proof it was done. Lines that pass get paid. Lines that fail get held, by amount and by name, while the rest of the invoice moves.

The core tool is a running change order log kept during the job, not a search through emails at payment time. The log fixes the authorized contract sum at every point in the job: original sum plus approved orders only. Pending, priced, verbal, and unpriced directive work adds nothing to that sum until it is approved.

This is the buyer and client side of the check. It differs from a pre-send invoice audit, which checks your own draft invoice against your own contract, and from general accounts payable, which runs intake and payment batches for all vendor bills. This skill is only about scope authority: who approved this extra work, for how much, and what proves it happened. It does not give legal advice. A dispute over a contract clause, a lien question, or a claim headed for mediation goes to counsel with the log and the worksheet attached.

The same method fits a construction job and an agency or services engagement. On a services job the base lines are the signed statement of work deliverables, the rate card replaces unit prices, and acceptance of a deliverable replaces inspection sign-off.

Workflow

1. Build the baseline before the first invoice arrives. Record the original contract sum, the base line list it splits into (the schedule of values on a construction job, the deliverable list on a services job), each line amount, the retainage terms if the contract sets any, the payment and dispute notice terms, and who has authority to approve changes. Add the base lines and check they equal the contract sum. If they do not, fix that first, in writing.

1. Start the change order log on day one. Use references/change-order-log.md for fields, statuses, and totals. Log every potential change the day it surfaces, priced or not. One change gets one numbered row, and numbers are never reused. A deductive change gets its own signed row with a negative amount.

1. Grade approval evidence before any invoice shows up. Use the tiers in references/evidence-standards.md. Tier A is a change order signed by every party the contract requires, in AIA practice the G701 form signed by owner, contractor, and architect. Tier B is a dated written approval from an authorized approver naming scope and amount or cap, where the contract allows that form. Tier C is a written directive to proceed before price is agreed, in AIA practice a construction change directive on G714. Tier C can authorize the work to proceed under those contract families, but the amount stays unapproved until the parties agree it. Tier D is a verbal claim, which is a lead to chase and never a basis to pay.

1. Keep directive and time and materials costs separate. Work done under a directive, or on a time and materials order with a cap, needs its own cost records by order number, kept while the work runs. Separate records are what let either side settle the price later without arguing over which hours or costs belonged to base scope.

1. Match every invoice line on the worksheet. Use references/reconciliation-worksheet.md, one row per line. For each line verify the ref, the approval tier, completion evidence, the rate or price basis, billed previously against that ref, and billed to date after this line. Never reconcile only the invoice total.

1. Run the reconciler. Put the authorizations and all invoices to date into one JSON case file and run the tool. It builds the authorized contract sum from approved orders only, accumulates billing per ref across every invoice, flags unapproved, unevidenced, duplicate, and over-authorized lines, splits an over-authorized line into a payable part and a held excess, checks each invoice total against its own lines, and computes retainage on payable lines only.

bash
python3 ~/workspace/skills/change-order-reconciliation/scripts/reconcile.py case.json

Exit code 0 means every line is payable, 1 means one or more lines are held or paid in part, 2 means the case file is malformed. The full worked case is in references/worked-case.json, with its story in references/worked-job.md.

1. Check what the tool cannot see, by hand, on every reconciliation:

• Scope match: the words in the approval against the words on the invoice line. Approved work in one room, one phase, or one deliverable billed for three fails on the extra parts.
• Date order: approval, work, and invoice dates. Approval dated after billed work is finished is a flag to record, even when the contract allows the owner to ratify it later.
• Percent complete: a line billed at a percentage needs evidence for that percentage, photos, inspection, or acceptance, not just the contractor's figure.
• Defect work: a line that prices fixing work which failed the original scope is coded R08 and routed to the contract owner. The invoice calling it a change does not make it one.
• Credits: deductive orders, returned material credits, and corrections promised in an earlier reconciliation are applied, in writing, not netted silently inside a new line.

1. Pay the undisputed lines, hold the disputed lines only. State the payable amount, the held amount per line, and the net due after retainage computed on payable lines at the contract percentage. Withholding a whole invoice over one bad line turns a record problem into a payment dispute, and on many contracts the undisputed portion stays due on its normal date. Read the contract's own dispute clause for the notice window and form, give the hold notice in writing inside that window, and if the contract is silent, send it promptly and record the date sent.

1. Write each hold as a cure, not a complaint. Every held line names the finding code, the amount, the missing record or decision, and the person who can cure it. A signed order cures R02. The signed record itself cures E01. Photos, inspection, or acceptance cure E02. A corrected invoice cures R05 and R06.

1. Close held items with a decision, not with time. A held item ends in one of three states: approved in writing at a stated amount and then paid up to that amount, rejected in writing with the reason recorded, or paid as a documented exception by the contract owner. Later approval cures the status. It does not approve more than the amount the later order states, and the difference stops being held and becomes not owed. Keep rejected and void rows in the log so the same work cannot reappear later unnoticed.

1. Reconcile the job, not just the invoice, at final payment. Billed to date against every base line and every approved order must sit at or under its authorized amount. Total paid plus total still held must equal the authorized contract sum before the final check is written, unless open held items are listed with owners and carried on purpose. Final payment with unresolved held items buried in it is how unapproved work gets paid by accident.

Output Contract

Every reconciliation produces:

• The updated change order log, with status, amount approved, billed to date, and balance remaining per order
• The worksheet, one row per invoice line, each row ending in pay, pay in part, hold, or reject, with a finding code for anything not paid in full
• The tool output for the case file, with the case file kept alongside it
• A payment summary: total claimed, lines total as recomputed, payable, held, rejected, retainage on payable lines with the contract percentage named, and net due
• An authorized sum statement: original sum, approved orders total, current authorized sum, billed to date against it, and balance left
• A held items list: line, amount, code, what cures it, and the named owner of the cure
• At final payment, a closing statement: every authorization fully billed, under billed, or over billed, and every held item marked approved and paid, rejected, or paid as an exception, with the writing behind the outcome

Operating Rules

• Approved is a status with a paper trail, not a memory. If the contract requires signed written change orders, only that form moves a line to payable. A person without approval authority under the contract cannot approve a change, whatever their job title sounds like.
• Pending and verbal amounts never enter the authorized contract sum. Show them in the log as not authorized so the size of the exposure is visible without inflating what can be billed.
• Never take a retainage percentage, a dispute deadline, or a payment term from habit. Read each one from this contract, name the clause in the output, and where the contract is silent say so instead of filling the gap with a standard figure.
• On a United States federal contract, the FAR changes framework applies instead of these defaults: a change order there is a written order signed by the contracting officer, FAR 52.243-1 requires the contractor to assert its right to an adjustment within 30 days from receipt of the written order, and a late proposal can still be considered before final payment if the contracting officer decides the facts justify it. Keep that 30 day figure inside federal work. It is not a private contract rule.
• Completion evidence and approval evidence are separate tests. Real work with no approval is held for an approval decision. Approved work with no completion proof is held for proof. Passing one test never substitutes for the other.
• Round and split the way the contract says. If it sets a billing increment or a pricing basis for changes, use it. If it is silent, compute to the cent and say so on the worksheet.
• Keep the log, the worksheet, and the evidence pointers together as the job file. The file is the dispute record if a held item is challenged months later, and it is only useful if every claim in it points at a record someone else can open.
• A reconciliation that holds nothing still produces the full worksheet and the authorized sum statement. Clean is a result that needs evidence, not a one line assurance.