# Scratchpad — Grouped Automatic Invoices Selection

- Plan slug: `grouped-automatic-invoices-selection`
- Created: `2026-03-20`

## What This Is

Working notes for the grouped automatic-invoices selection redesign. This plan intentionally spans both UI and backend invoice-scope behavior.

## Decisions

- (2026-03-20) Group recurring due work visually by `client + invoice window`. Parent grouping is for user comprehension first, not an automatic promise that the result is one invoice.
- (2026-03-20) Parent checkbox semantics are strict: if enabled and selected, it means “generate one combined invoice.” If the group cannot combine, the parent checkbox is disabled rather than overloaded.
- (2026-03-20) `Select All` must be smart: select the parent for combinable groups and select child rows individually for non-combinable groups.
- (2026-03-20) Combined execution is allowed only when the selected children share compatible invoice-level financial scope: client, currency, PO scope, tax source, and export shape.
- (2026-03-20) Multi-assignment combined invoices are explicitly in scope for this plan. The backend must stop requiring a fake single invoice owner for valid combined selections.

## Discoveries / Constraints

- (2026-03-20) `AutomaticInvoices` already receives parent candidate rows with `members`, but the UI still behaves as a flat table and selection is only `Set<candidateKey>`. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Preview is currently gated to a single selected candidate with exactly one child member. Grouped preview behavior does not exist today.
- (2026-03-20) The shared grouping logic already computes split reasons `single_contract`, `purchase_order_scope`, and `financial_constraint` per invoice window. Files: `shared/billingClients/recurringTiming.ts`, `packages/billing/src/actions/billingAndTax.ts`.
- (2026-03-20) The current preview/generate APIs are strictly single-selector. `IRecurringDueSelectionInput` represents one selector only; generation scopes to one canonical line/window before billing. Files: `packages/types/src/interfaces/recurringTiming.interfaces.ts`, `packages/billing/src/actions/invoiceGeneration.ts`.
- (2026-03-20) Grouped preview now supports exact parent/child selection bundles through `previewGroupedInvoicesForSelectionInputs`, while direct "Generate from preview" remains intentionally single-selector until grouped generation semantics (`F015/F016`) land. Files: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`, `packages/billing/src/actions/invoiceGeneration.ts`.
- (2026-03-20) Grouped generation request semantics now exist via `generateGroupedInvoicesAsRecurringBillingRun`, and `AutomaticInvoices` now submits grouped targets (`groupKey + selectorInputs`) for bulk generation paths instead of only flattened single-selector targets. Files: `packages/billing/src/actions/recurringBillingRunActions.ts`, `packages/billing/src/actions/recurringBillingRunActions.shared.ts`, `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Combined grouped execution now routes through a multi-selector generation path (`generateInvoiceForSelectionInputs`) so one selected parent group can execute as one invoice request; incompatible child-level selections still fan out via one request per child group. File: `packages/billing/src/actions/invoiceGeneration.ts`, `packages/billing/src/actions/recurringBillingRunActions.ts`.
- (2026-03-20) Multi-assignment combined generation now persists invoice headers with `client_contract_id: null` when charges span multiple assignments, while preserving per-charge assignment attribution in `persistInvoiceCharges`. Files: `packages/billing/src/actions/invoiceGeneration.ts`, `server/src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts`.
- (2026-03-20) Recurring generation no longer throws on multi-assignment charge sets; combined invoices persist with header `client_contract_id: null` while per-charge assignment IDs remain authoritative. File: `packages/billing/src/actions/invoiceGeneration.ts`.
- (2026-03-20) PO enforcement and consumption are currently header-assignment scoped through `invoices.client_contract_id`, so grouped combination must not bypass PO compatibility constraints. Files: `packages/billing/src/services/purchaseOrderService.ts`, `packages/billing/src/actions/invoiceQueries.ts`.
- (2026-03-20) Charge-level assignment attribution exists on `invoice_charges`, but invoice read models do not currently expose enough of that provenance for a combined invoice UX. Files: `packages/billing/src/services/invoiceService.ts`, `packages/billing/src/models/invoice.ts`.

## Commands / Runbooks

- (2026-03-20) Scaffolded this plan with:
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/scaffold_plan.py "Grouped Automatic Invoices Selection" --slug grouped-automatic-invoices-selection`
- (2026-03-20) Validate the plan with:
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection`
- (2026-03-20) JSON sanity:
  - `jq empty ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection/features.json`
  - `jq empty ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection/tests.json`

## Links / References

- Related plan: `ee/docs/plans/2026-03-20-multi-active-contracts-per-client/`
- UI entry point: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`
- Grouping logic: `shared/billingClients/recurringTiming.ts`
- Due-work shaping: `packages/billing/src/actions/billingAndTax.ts`
- Execution path: `packages/billing/src/actions/invoiceGeneration.ts`
- Recurring run actions: `packages/billing/src/actions/recurringBillingRunActions.ts`
- Invoice persistence: `packages/billing/src/services/invoiceService.ts`
- PO behavior: `packages/billing/src/services/purchaseOrderService.ts`

## Progress Log

- (2026-03-20) Codified parent/child selection semantics directly in `AutomaticInvoices` with `RecurringInvoiceParentGroup` and `buildRecurringInvoiceParentGroups`, so parent rows are explicit model objects and child members are explicitly treated as execution units. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Updated ready-work explanatory copy to align with PRD semantics: parent rows group by `client + invoice window`; child obligations remain atomic execution units. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Added a jsdom UI behavior test that mocks due-work responses and verifies one top-level automatic-invoices row renders for a multi-member shared `client + invoice window` candidate. File: `packages/billing/tests/automaticInvoices.groupedParentRows.test.tsx`.
- (2026-03-20) Targeted validation for the new grouped parent-row behavior test:
  - `cd packages/billing && npx vitest run tests/automaticInvoices.groupedParentRows.test.tsx`
- (2026-03-20) Completed `F002` by refactoring the ready-work UI model into explicit parent summaries (`parentSummary`) and child execution rows (`childExecutionRows`), while keeping generation/preview wired to selected parent-group candidates. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Completed `F003` by introducing explicit parent-group identity (`parentGroupKey`) and parent-selection identity (`parentSelectionKey`) in the ready-work view model, and routing group selection state through those keys instead of child selector identities. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Added optional parent aggregate amount summary (`aggregateAmountCents`) derived from child rows when amount data is present, with an explicit fallback when unavailable. File: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-20) Completed `T002` by asserting grouped parent summary output (child count, invoice window label, aggregate amount) in the automatic invoices jsdom behavior test. File: `packages/billing/tests/automaticInvoices.groupedParentRows.test.tsx`.
- (2026-03-20) Completed `F004` with explicit parent-row expand/collapse controls and inline child-row rendering in the automatic invoices grouped table.
- (2026-03-20) Completed `F006` by rendering child details in the expanded group view, including assignment/contract context, cadence source, billing timing, service period, and amount.
- (2026-03-20) Completed `F005` by rendering parent summary combinability state alongside client, window, child-count, and aggregate-amount summaries.
- (2026-03-20) Completed `T003` by testing parent expansion and verifying child detail rendering in the automatic invoices grouped UI behavior test.
- (2026-03-20) Added financial-scope fields (`purchaseOrderScopeKey`, `currencyCode`, `taxSource`, `exportShapeKey`) to recurring due-work rows/candidates and wired those fields through due-work shaping so UI combinability logic can evaluate true invoice-scope compatibility.
- (2026-03-20) Completed `F007` by computing parent combinability from effective child scope values (client, currency, PO scope, tax source, export shape) and completed `F008` by enabling parent selection only when combinable.
- (2026-03-20) Completed `F012` by surfacing explicit non-combinable reason text on parent rows (`PO scope differs`, `Currency differs`, `Tax treatment differs`, `Export shape differs`).
- (2026-03-20) Completed `T004`-`T008` with scenario tests that verify combinability gating and each incompatibility reason.
- (2026-03-20) Validation run:
  - `cd packages/billing && npx vitest run tests/automaticInvoices.groupedParentRows.test.tsx`
  - `npm -w packages/billing run typecheck` (fails due existing unrelated package-level TS errors; see `billingCycleActions.ts`, `recurringBillingRunActions.shared.ts`, `billingEngine.ts`, `invoiceService.ts`, plus recurring due-window typing drift around `duePosition`).
- (2026-03-20) Completed `F009` by introducing dual parent/child selection targets, child-level checkbox selection in expanded groups, and parent tri-state behavior when child selections are partial.
- (2026-03-20) Completed `F010` by implementing smart `Select All`: combinable groups select parent targets, non-combinable groups select child targets.
- (2026-03-20) Completed `F011` by keeping blocked child rows visible while preventing blocked child selection in both direct child selection and `Select All`.
- (2026-03-20) Completed `T009`-`T014` with UI behavior tests covering parent selection semantics, child selection availability, parent tri-state, smart `Select All`, and blocked child visibility/selection guardrails.
- (2026-03-20) Completed `F013` by adding grouped preview request semantics end-to-end: `AutomaticInvoices` now emits grouped preview payloads from parent/child selection state and `invoiceGeneration` now exposes `previewGroupedInvoicesForSelectionInputs` with exact selector-scope support.
- (2026-03-20) Completed `F014` by updating preview rendering to show explicit invoice-count messaging (`This selection will generate N invoice(s).`) and render grouped preview cards for one-or-many preview outputs.
- (2026-03-20) Completed `T015`-`T017` with jsdom behavior tests that validate grouped parent preview count, split child preview count, and exact-scope preview payloads (no unselected siblings).
- (2026-03-20) Completed `F015` by introducing grouped generation payload semantics and wiring automatic-invoice generation calls to submit explicit grouped targets derived from parent/child selection state.
- (2026-03-20) Completed `F016` by preserving exact selector scope through grouped generation payloads and preventing sibling re-expansion in execution request construction.
- (2026-03-20) Completed `F017` by adding a grouped run execution loop that calls multi-selector invoice generation once per selected combinable parent group.
- (2026-03-20) Completed `F018` by preserving fan-out execution for incompatible selections via grouped run targets where each child selection executes independently.
- (2026-03-20) Completed `F019` by ensuring grouped recurring run execution skips duplicate selections (idempotent duplicate code path) while continuing unrelated selected groups in the same run.
- (2026-03-20) Completed `F020` by removing the single-assignment hard-fail at invoice-header persistence and allowing combined multi-assignment invoices to persist without a fake header owner.
- (2026-03-20) Completed `F021` by preserving per-charge `client_contract_id` attribution for combined multi-assignment execution paths.
- (2026-03-20) Completed `T020` with a jsdom behavior test that asserts generation sends only explicitly selected child selectors even when the group contains additional siblings.
- (2026-03-20) Completed `T018` and `T019` with server unit tests that verify grouped run execution creates one invoice for a combinable parent group and multiple invoices for split child groups.
- (2026-03-20) Completed `T021` with server unit coverage that verifies duplicate grouped/member selections are skipped without blocking unrelated sibling groups.
- (2026-03-20) Completed `T022` and `T023` by converting selector-input generation coverage to assert multi-assignment persistence semantics: header assignment ownership is optional and per-charge assignment IDs remain intact.
- (2026-03-21) Completed `F022` by extending recurring invoice history reads with assignment provenance (`assignment_contract_ids`) and rendering that provenance in history UI via assignment summary + multi-contract badge. Files: `packages/billing/src/actions/billingCycleActions.ts`, `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`.
- (2026-03-21) Completed `F023` by shifting due-work grouping to parent scope (`client + invoice window`) while preserving PO compatibility semantics through explicit `po_required`-aware `purchaseOrderScopeKey` metadata. Files: `shared/billingClients/recurringTiming.ts`, `packages/billing/src/actions/billingAndTax.ts`.
- (2026-03-21) Completed `F024` with regression-guarded legacy behavior for single-assignment/single-child parent groups across preview and generation paths. File: `packages/billing/tests/automaticInvoices.groupedParentRows.test.tsx`.
- (2026-03-21) Completed `F025` by adding explicit in-product copy for smart `Select All` semantics and introducing a dedicated grouped-automatic-invoices runbook contract. Files: `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`, `ee/docs/plans/2026-03-20-grouped-automatic-invoices-selection/RUNBOOK.md`.
- (2026-03-21) Completed `T024` and `T025` with UI behavior coverage for recurring history assignment-scope rendering (`assignmentSummary`, `Multi-contract invoice` badge). File: `packages/billing/tests/automaticInvoices.groupedParentRows.test.tsx`.
- (2026-03-21) Completed `T026` and `T027` by validating PO-scope non-combinability in grouped UI and no-PO combined generation behavior in selector-input generation tests. Files: `packages/billing/tests/automaticInvoices.groupedParentRows.test.tsx`, `server/src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts`.
- (2026-03-21) Completed `T028` and `T029` with legacy-flow coverage for single-child/single-assignment grouped parents.
- (2026-03-21) Completed `T030` and `T031` with recurring due-work integration coverage proving same-client same-window rows remain one parent group for no-PO combinations and carry PO split reasons when scopes conflict. File: `server/src/test/unit/billing/recurringDueWorkReader.integration.test.ts`.
- (2026-03-21) Completed `T032` and `T033` with grouped recurring run execution coverage for mixed parent+child fan-out semantics and duplicate-protection isolation across sibling targets. File: `server/src/test/unit/billing/recurringBillingRunActions.test.ts`.
- (2026-03-21) Completed `T034` with docs/wiring coverage that locks runbook text and in-product explanatory copy for parent grouping + smart `Select All` semantics. File: `server/src/test/unit/docs/groupedAutomaticInvoices.runbook.test.ts`.
- (2026-03-20) Validation run:
  - `cd packages/billing && npx vitest run tests/automaticInvoices.groupedParentRows.test.tsx`
  - `cd server && npx vitest run src/test/unit/billing/recurringBillingRunActions.test.ts`
- (2026-03-21) Validation run:
  - `cd packages/billing && npx vitest run tests/automaticInvoices.groupedParentRows.test.tsx`
  - `cd server && npx vitest run src/test/unit/billing/recurringDueWorkReader.integration.test.ts src/test/unit/billing/recurringBillingRunActions.test.ts src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts src/test/unit/docs/groupedAutomaticInvoices.runbook.test.ts --coverage.enabled=false`

## Open Questions

- Should multi-invoice preview render several full invoice previews or a summary-first experience with drill-down?
- Should combined multi-assignment invoices expose a dedicated badge or invoice-scope type in history/detail screens?
- Should parent totals show only ready children or both ready and blocked totals when a group contains a mix?