Skip to content

Change Orders

StatusShipped
LinearPIN-53 ↗ PIN-473 ↗ PIN-484 ↗
ModuleChange Orders ↗

Four flavors of contract change on a project: PCO (request to the GC — renamed from COR in PIN-484), CO (approved change), ICO (internal, against profit), and Backcharge. PCOs have their own lifecycle ending in a server-spawned draft CO on approval. Profit numbers are visible only to the exec tier.

Prerequisites

  • Role: PM or Assistant PM for the main pass; an Owner/Executive login for Proceed and profit checks; an Estimator login to confirm read-only.
  • Project state: any project; cost codes present make the per-line "Charges to cost code" select appear.
  • Test data: PDFs from docs-pdfs/ for attachments.

1. Open the log

Project detail → Change Orders tab (top-level, not nested). Top-down: a type legend strip (PCO blue / CO green / ICO orange / BC red), five KPI cards (Approved COs / Pending PCOs / Internal COs / Backcharges / Net CO Impact), toolbar with search, type filter buttons All / PCO / CO / ICO / Backcharge, Show history toggle (includes superseded), PDF + CSV export, New Change Order.

Table columns: # / TYPE / DESCRIPTION / TOTAL / STATUS / BALL IN COURT / COST / SCHED / LINKED RFI / AGING + a paperclip attachment count. $ in COST and S in SCHED render only when the impact is Yes; AGING shows Nd only on pending statuses.

2. Create one of each type

New Change Order — one form for all four types:

  • Type (immutable after create): PCO — request to GC, CO — approved change order, ICO — internal (against profit), Backcharge.
  • CO # — read-only preview ("Assigned on save"), per-project-per-type sequence: PCO-001, CO-001, ICO-001, BC-001. The preview re-peeks when you change Type.
  • Description * , scope line items (Qty × Unit $ with running Total, optional cost-code charge per line), Cost Impact / Schedule Impact (Yes/No/TBD), Link to RFI (project RFIs dropdown).
  • ICO only: a warning-styled block with Reason code * (Missed in estimate / Field error / Design change / Coordination issue / Other) + Reason detail with a minimum 20 characters validation — try 19 characters.
  • Budgeted profit ($) — appears only for Owner/Admin/Sr.PM/Exec; accepts negatives (ICO reducing profit).
  • Buttons: Save as Draft / Create & Submit.

3. Walk the PCO lifecycle (the special one)

PCO buttons per status: Draft → Submit (+ a Proceeded button enabled only for Owner/Executive — force-account); Submitted → Approve / Reject / Begin Negotiating; Negotiating → Approve / Reject; Rejected → Create Revision (spawns an append-only draft PCO-001-1).

Approve on a PCO spawns a draft CO — toast "PCO approved — draft CO created", navigation to the new CO, which carries a "from PCO-001" back-link chip and is non-deletable.

CO/ICO/Backcharge use the generic chain: Draft → Submitted → Under Review → Approved/Rejected/Revised (Rejected/Revised → back to Submitted).

Ball-in-court is derived, never set by hand: GC only while a PCO/CO is Submitted / Under Review / Negotiating; everything else shows Pinley (all ICO/BC regardless of status), and — once Approved.

4. Attachments and exports

  • Attach (.pdf/.png/.jpg, multiple): rows with inline preview (eye), Download, Delete. The paperclip count in the log must update immediately.
  • Export PDF (single CO) and log PDF/CSV. PDF export runs on the pure-Go renderer (PIN-504) — it should work the same on staging as anywhere else; a failure there is a real bug, not a known risk.

5. Role gating

Check Expected
Estimator / Financial Controller Read-only: sees the log, no New Change Order, no status buttons
PM / Assistant PM Create, edit, status changes, approve PCO
Proceed on a draft PCO Enabled for Owner/Executive only (visible but disabled for others)
Delete CO Owner / Administration / Senior PM only, and only Draft + non-spawned + non-revision
Profit block + Budgeted profit input Owner / Administration / Senior PM / Executive only
Subcost tracker Cost-only by design — profit never appears there for anyone

Verification Checklist

  • Numbering: first of each type gets PCO-001 / CO-001 / ICO-001 / BC-001; revision gets PCO-00N-1
  • ICO blocks save with reason detail under 20 chars
  • PCO Approve spawns a draft CO with the back-link chip; the CO can't be deleted
  • Ball-in-court flips to GC on submit and back to Pinley/— after decision; ICO/BC never show GC
  • Assistant PM can create/edit but sees no profit fields; Estimator is fully read-only
  • Attachment add/delete updates both the card badge and the log paperclip count
  • No console errors throughout

Known Issues / Current Gaps

  • ⚠ PIN-484 renamed COR→PCO labels only — searching an old "COR-001" from a GC email won't match PCO-001; accepted limitation.
Updating this walkthrough

Run the full flow yourself end-to-end. If it passes, bump last_verified: in the frontmatter to today's date. If any step fails, fix the doc or the code in the same PR — drift is the enemy.