assembly

assembly

Routes through the tax-bunyip foundation hub — read its standing instructions first (skills/tax-bunyip/SKILL.md). This is the rendering substrate every per-entity output is built on (scripts/assemble.py). It collates and flags — it asserts no final tax number. The registered tax agent — or the lodging individual — finalises every figure; every computed line is marked [accountant to confirm].

Consumes CONFIRMED state, not suggestions

A working paper must not present unreviewed attributions as draft figures. Assembly admits only the gate-satisfying attribution states (confirmed-single, confirmed-split, confirmed-nil — from scripts/attribution.py). A line in any non-confirmed state is withheld — routed to the open-questions list with its state named (the routed-refusal disposition), never rendered as a figure. This is loud, not silent: the operator sees exactly which lines were withheld and why.

The mandated notice and the no-liability assertion

Every output opens with the one-line unreviewed-working-paper notice (UNREVIEWED_NOTICE). It is the first line of the Markdown and the first cell of the Excel Notice sheet — the single line separating decision support from a return one might lodge. No line asserts a final tax liability; the footer carries the explicit negative assertion (NO_FINAL_LIABILITY). write_working_paper asserts the first line before writing — a regression cannot ship a non-noticed paper.

The joined confirmed marker

A figure is confirmed only when both hold:

1. its governing rate is confirmed_by != pending (rates.is_pending False), and
2. its line-level review is cleared.

The two markers are joined, not independent — a confirmed rate whose line review is uncleared still reads UNCONFIRMED. The marker is computed in one place (line_marker) so Markdown and Excel render the identical state:

Marker	Meaning
WITHHELD — attribution not confirmed	attribution state is not gate-satisfying (routed to open questions)
PROVISIONAL — pending rate	governing rate still pending — renders flagged + appendix, never blocks
UNCONFIRMED — line review not cleared	rate confirmed (or none) but line review not cleared (the joined state)
confirmed	rate confirmed (or none) and line review cleared

Pending rates render provisional — never block

A figure on a still-pending rate renders provisionally, flagged, and is listed in the pending-rate appendix — it does not block. A fresh all-pending repo renders end-to-end. A pending rate is an expected state (the agent confirms rates later), not a defect — this is the deliberate inversion of fail-loud.

Period-keyed netting, not month-string filtered

Refunds/credits net on (category, governing_period) where the governing date drives tax treatment (generally payment). A credit dated in its own period nets there. A credit whose governing date offsets a charge in a different period is netted in its own period and raises a cross-period-credit flag naming both periods — it is never silently netted across a BAS-period or FY boundary (that would misstate a quarter). Net-not-gross is preserved within a period; the cross-boundary guard is the period-aware addition (net_lines, governing_period).

ATO labels are data, keyed on the tax category

Each line maps to an ATO label via categorize.map_to_ato_label over the labels: section of config/ato_labels. The mapping keys on the tax category (the output of tax-lens re-classification), never a budget tag. A tax category with no mapping — or a line with no tax category — is surfaced as an accountant open question, never defaulted to a label.

Excel mirrors the Markdown with a dedicated marker column

write_excel / write_working_paper emit an .xlsx whose Lines sheet carries an explicit uncertainty_marker column (EXCEL_MARKER_COLUMN) so a provisional figure is never read as final — the marker travels in its own column, not buried in a note. The Notice sheet's first cells mirror the Markdown's first line.

Atomic, post-success write

Both surfaces are rendered fully before either is written, then each is written via atomic_write_secure (0600 — PII-bearing, under the gitignored working-papers/ tree). A crash leaves the prior good paper or nothing, never a half-written paper that reads as authoritative. The working paper itself carries real figures by design (gitignored); structural raises never do.

Template-driven format

render_markdown(paper, template=...) accepts a format string with {notice} / {body} slots (templates/working_paper.md) so a tax agent's required schedule format can be adopted at the first dry-run; absent it, the suite's own format stands.

Entry points (scripts/assemble.py)

Canonical invocation: ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh scripts/assemble.py

• assemble_entity(entity, lines, fy=..., net_period=...) → WorkingPaper
• line_marker(line) / is_confirmed / is_provisional / is_withheld
• net_lines(lines, period=...) → (netted, cross_period_flags)
• governing_period(date, period=...) → the BAS-quarter / FY netting key
• render_markdown(paper, template=...) / build_excel_frames(paper) / write_excel
• write_working_paper(paper, base_dir=...) → atomic Markdown + Excel