Close tracker

The close tracker shows where an entity's month-end close stands: the steps every close has, the organization's own tasks, the day each is due, who did a task and with what evidence, and what is overdue. The design is ADR-0034 (part B); this guide is slice C1 as built. The tracker itself runs nothing: the scheduled close job (slices C2, C3 and F3) runs the steps an entity names. The controls are in the control matrix (section "Close tracker", CA1 to CA6).

Everything is a REST operation first (tag "close tracker" in the generated reference); the MCP tool close_status_of_period reads the status.

The close calendar

GET /v1/entities/{entity}/close-schedule and PUT (owner, the working day of each step, and the steps the close job runs for the entity, automated_steps). A working day is counted from the period's last day: day 0 is that day, day n the n-th business day after it (skipping weekends and the statutory public holidays of the entity's country from the data-vNext calendars).

A step whose check does not apply (no assets, no foreign currency, no recurring invoices) is n/a. Until an entity sets its own calendar the defaults apply (configured: false).

Tasks

POST /v1/entities/{entity}/close-tasks adds a task of every month end: a title, an owner (a person of the organization; none means the close owner), the working day it is due on and, optionally, a check_id. A task with a check is decided by that check: it is done when the check passes or does not apply, and nobody marks it done by hand (409). A check id must be one the entity's checklist reports. Other tasks are done when a person records it:

POST /v1/periods/{period_id}/close-tasks/{task_id}/complete   {evidence?, note?}
POST /v1/periods/{period_id}/close-tasks/{task_id}/withdraw   {reason}

A completion is evidence: it is never deleted or edited; withdrawing it keeps it, with who withdrew it and why, and the task can be done again (a new row). At most one live completion per task and period (a unique index). A task is never deleted: PATCH /v1/close-tasks/{task_id} with active: false takes it out of the open periods' closes for good: a deactivated task is not reactivated (409, and the database refuses it too), since that would put it back into the closes of periods that closed meanwhile. A task that is wanted again is a new task.

An own task not done warns on the checklist. The close check close_tasks lists the tasks a person marks done that are part of the period's close and not done (warn, worded by code tasks_open with their titles), pass when all are done, n/a without any. It never fails: a task is a reminder and does not hold the close, but the Period Close screen no longer says "No check fails" alone while one is open; it names how many checks warn. A task decided by a check is that check's result and is not counted again, and no task can be linked to close_tasks itself.

A closed period's close is on record as it closed. Its status shows the tasks that were part of the close when the period closed (created before, and still active then) and any task done for it; a task added or deactivated later does not change it. Its completions are neither recorded nor withdrawn (409, and the database refuses it too): reopen the period to change them. The status shows a task's current title, due day and check; earlier values are in the audit trail.

The status of a period

GET /v1/periods/{period_id}/close-status?as_of= lists the steps and the tasks with their due date and done, open, overdue (not done and the due date is before as_of) or n/a, the checklist's failing checks, the close owner, the counts (done, total, overdue) and what the close job did for the period (job_log, the latest first). as_of defaults to the server's date (UTC). The close checklist is the one source of pass and fail, so the tracker never says "done" over a failing check.

Who may do what

Reading the calendar, the tasks and the status needs read. Setting the calendar, adding or changing a task and recording or withdrawing a completion are a person's acts: the policy action manage_close, which agents are always denied (rule agents_no_plan_or_close_controls). Every change is in the audit trail (close.schedule.set, close.task.create, close.task.update with the previous values, close.task.complete, close.task.withdraw).

Who does each step

step_owners in the schedule names the person who does a step (PUT .../close-schedule with {"step_owners": {"depreciation": "<user id>"}}; null gives the step back to the close owner). A step without a person of its own is the close owner's, and the status shows each step's owner that way.

On screen

Period Close, a period's card: Close steps lists every step with who does it, the day it is due, its state, who did it and when (the person who ran a period-end run, wrote the close memo, closed the period or made the latest forecast version; the checklist and the recurring invoices are done by many hands and name nobody) and why, in the person's language (reason: the deciding check's periodClose.result words, else closeTracker.result). Nobody marks a step done there: the close checklist decides it. Close tasks below lists the organization's own tasks. Settings, close schedule sets the owner of the close, each step's working day and each step's own person.

The Role Center cue Periods in close counts the regular periods that ended and are still open, from the month of the company's first posted entry on (a period of a year whose year-end close is posted counts as closed; periods_in_close of GET /v1/entities/{entity}/overview), and opens Period Close. A new company has nothing in close: the months of its first fiscal year before its first entry wait for nothing, and a company that books its history from January closes from January.

What this does not do yet

The group step after the members close (C4) is designed in ADR-0034 and not built.