Punch list

The punch list is the project's queue of corrective work. Each item names what needs fixing, where it is, who has to fix it, who reviews the fix, and who signs it off.

Ball-in-court is a first-class column here, sortable and filterable, because the only question anyone asks of a punch list is what is waiting on them.

The three parties

Every item has three roles, and the lifecycle is a loop between them:

Role	Default	What they do
Assignees	none	Accept or dispute the item, do the work, submit it for review
Punch item manager	the creator	Issues the item, adjudicates disputes, reviews the submitted work, decides what happens after a final rejection
Final approver	the creator	Signs off, or rejects at the last gate

A creator who names nobody is manager and final approver by default, which is the one-person case working correctly rather than a gap.

There is also a distribution list, which is copied on events and never holds the ball.

Create an item

1. Click New item.
2. Enter a title. It is the only required field.
3. Add the description, location, type, trade, cost code, reference, priority (Low, Medium, High), due date, and cost or schedule impact.
4. Name the assignees, the manager, the final approver, and the distribution list.
5. Optionally mark it Private.
6. Click Create item.

The dialog tells you what will happen: an item created with assignees and issuing turned on goes out immediately, otherwise it is saved as a draft.

Describe from photo drafts the title and description from a photograph. It is the one metered action in this module, it needs credits, and the image must be 4 MB or smaller. Nothing is saved until you create the item yourself.

Draft means nobody has been told

A new item starts in Draft. Drafts notify nobody, and they are fully editable. Issuing an item is the Initiate action, which is what moves it to Initiated and tells the assignees.

The register carries a banner whenever the project holds unissued items, with a Send all button that issues them in a batch of up to 500. If more remain, the banner says how many and you press it again. A truthful second press beats a first press that silently half-finished.

Issuing stamps the item with when it was issued and by whom. That record is what the aging and response-time reports read; it does not affect whether an item is overdue, which is purely the due date against today.

The nine states

State	Ball is with	Meaning
Draft	Manager	Created, not issued
Initiated	Assignees	Issued, awaiting acceptance
In Dispute	Manager	The assignee contests the item
Work Required	Assignees	Work outstanding
Work Not Accepted	Assignees	The manager rejected the submitted work
Ready for Review	Manager	The assignee says the work is done
Ready to Close	Final approver	The manager accepted the work
Not Accepted	Manager	The final approver rejected at the last gate
Closed	Nobody	Signed off. Terminal.

The actions, and who takes them

Action	From	To	Who
Initiate	Draft	Initiated	Manager
Dispute	Initiated	In Dispute	An assignee
Accept assignment	Initiated	Work Required	An assignee
Resolve dispute	In Dispute	Work Required	Manager
Submit for review	In Dispute, Work Required, Work Not Accepted	Ready for Review	An assignee, or the manager
Reject work	Ready for Review	Work Not Accepted	Manager
Accept work	Ready for Review	Ready to Close	Manager
Final approve	Ready to Close	Closed	Final approver
Final reject	Ready to Close	Not Accepted	Final approver
Resubmit for approval	Not Accepted	Ready to Close	Manager
Return to assignee	Not Accepted	Work Required	Manager
Comment	any non-closed state	unchanged	Anyone with STANDARD on Punch

The two states worth reading twice are the ones that give the manager a decision rather than a dead end.

In Dispute means an assignee said "this is not my scope" or "this is not a defect". Somebody has to adjudicate. If the manager agrees, edit or void the item; if the manager disagrees, the work still has to happen, and Resolve dispute puts it back into Work Required.

Not Accepted is produced by the final approver rejecting at the last gate, which nearly always means more work. The manager can re-present the same work (Resubmit for approval) or send it back to the assignee (Return to assignee). Without the second option the manager's only choices would be to re-present rejected work unchanged or to abandon the item.

Buttons come from the machine, not from the UI. An action you cannot legally take right now is not offered, rather than offered and failing on click.

A closed item is terminal, including for comments.

Attachments and photos

Attachments are references to files already in the project. Attaching a photograph of corrected work is the single most common action a field user takes here, so the rule is deliberately looser than editing: any participant with STANDARD on Punch can attach, not just the manager and the creator.

Photos are recognised by their file type: JPEG, PNG, HEIC, HEIF, and WebP show in the item's photo gallery. Anything else attaches as a generic file rather than being rejected, because attaching a PDF cut sheet to a punch item is a reasonable thing to do.

Removing an attachment removes the reference. The file itself is untouched, because the same file may be cited by an album, a daily log, or another punch item.

Comments

Comments are an append-only thread on the item, capped at 500 per item and 4,000 characters each. A note attached to a transition is also written into the thread, so "why was this rejected" is answered where a reader actually looks.

Private items

A private punch item is visible to its creator, manager, final approver, assignees, distribution list, and anyone with ADMIN on the Punch tool. Everyone else gets 404 Not found on a direct read and never sees the row in a list or in the counts above the table.

Bulk actions

Select rows and apply one action across the selection. Legality is re-evaluated per item by the same state machine, so a selection of twelve items where nine are legal advances the nine and reports the other three individually. Partial success is the right outcome in the field; failing the whole batch just teaches people to click twelve times.

The bulk menu disables an action the selection cannot legally take, with a count, rather than offering it and half-failing.

Export and analytics

Punch report downloads the register as a PDF and CSV downloads it as a spreadsheet. Both apply the same filters the register is showing. Past the read ceiling the document prints a visible warning banner rather than quietly shipping a partial register to an owner.

The register also carries an analytics strip above the table. A punch log and a punch aging by company report are both in Reports.

Limits

Limit	Value
Punch items read per project	5,000
Register page size	200 maximum
Attachments per item	100
Comments per item	500
Comment length	4,000 characters
Title	200 characters
Description	8,000 characters
Items per Send all batch	500
Photo for Describe from photo	4 MB

Troubleshooting

"Punch item not found" on a link a colleague sent you. The item is private and you are not one of its parties. Private items answer 404 rather than 403 on purpose. Ask to be added to the distribution, or ask a Punch admin.

Send all issued some items and says others remain. One batch covers 500 items. Press it again for the rest. The count shown excludes items nobody can issue, so it never sticks at a number a second press cannot move.

An item would not issue in a Send all batch. Either you do not manage that item, or somebody else already moved it out of Draft. Neither changes on a retry, which is why those items are left out of the remaining count.

A disputed item looks stuck. Only the manager can move it. Resolve dispute puts it back into Work Required if the dispute is overruled; if the dispute is valid, edit the item or void it.

The final approver rejected it and there is nothing to do. There are two moves from Not Accepted, both the manager's: re-present the same work, or send it back to the assignee for more work.

A photo attached as a file instead of showing in the gallery. The gallery recognises JPEG, PNG, HEIC, HEIF, and WebP. Other formats still attach, they just do not render as photos.

Describe from photo is unavailable. It needs credits, and the image must be 4 MB or smaller. Nothing else in this register is affected by a zero balance.

The register says the list stopped at a limit. The project holds more items than one read returns. The totals above the table still cover everything; narrow with a filter to get a complete list.