Add client billing and cost evidence workplans

workplans/FIN-WP-0002-client-attribution-and-billing-basis.md

@@ -0,0 +1,160 @@
+---
+id: FIN-WP-0002
+type: workplan
+title: "Client attribution and billing basis"
+domain: financials
+repo: fin-hub
+status: active
+owner: codex
+topic_slug: financials
+created: "2026-08-10"
+updated: "2026-08-10"
+related:
+  - FIN-WP-0001
+  - FIN-WP-0004
+  - CUST-WP-0058
+state_hub_workstream_id: "ebc1d2de-ae11-4cde-b860-047922fc74b9"
+---
+
+# FIN-WP-0002 — Client attribution and billing basis
+
+## Goal
+
+Extend fin-hub's reporting model from service-level cost evidence to a
+client × application × instance billing basis, including engagement revenue,
+margin reporting, and explainable shared-infrastructure allocation.
+
+fin-hub remains reporting-only. It does not generate invoices, execute or
+track payments, perform bookkeeping, or become authoritative for client or
+resource identity. An external GoBD-capable bookkeeping/invoicing system owns
+invoice generation and payment tracking.
+
+This workplan originates the proposal from the Custodian's
+`CUST-WP-0058-T06` gap assessment. T00 reconciled the earlier scope exclusion:
+client-level reporting and billing-basis exports are in scope, while legal
+invoice generation, bookkeeping, payment handling, and identity authority
+remain out of scope.
+
+## Reconcile scope and authority boundaries
+
+```task
+id: FIN-WP-0002-T00
+status: done
+priority: high
+state_hub_task_id: "280ff8c9-2a82-4a40-908c-37d6ca8ce3e2"
+```
+
+Reconcile this proposal with `SCOPE.md`, which currently lists multi-tenant
+customer billing as out of scope. Define the permitted boundary between
+client-level financial reporting and external invoicing/bookkeeping, and
+update the scope or defer this workplan explicitly.
+
+Also align with `FIN-WP-0004` so provider booked-cost evidence, analytical
+allocation, customer billing basis, and resource-control technical allocation
+have one authoritative owner each and do not double-count costs.
+
+Done when the repository scope explicitly permits the intended reporting and
+export surfaces, or the workplan is blocked/deferred with an identified owner
+for the capability.
+
+Completed 2026-08-10: `SCOPE.md` now includes client-level attribution,
+engagement revenue/margin reporting, and billing-basis exports, while
+explicitly excluding legal invoice generation/numbering, bookkeeping,
+payments, banking, and client/resource identity authority. `FIN-WP-0004`
+remains the coordination point for booked-cost versus technical-allocation
+authority.
+
+## Add client attribution
+
+```task
+id: FIN-WP-0002-T01
+status: todo
+priority: high
+state_hub_task_id: "904e9edc-a434-41e6-a4c7-ebb407469514"
+```
+
+After T00, extend cost rows with a stable client × application × instance cost
+attribution key. Use an explicit external string identifier initially while
+preserving a later reference seam to client-hub's authoritative app-instance
+identity. Do not make fin-hub the client registry.
+
+Cover unknown/unattributed values, uniqueness and period semantics,
+corrections, migrations, validation, and backward compatibility for existing
+service-level records.
+
+## Add engagement revenue and margin reporting
+
+```task
+id: FIN-WP-0002-T02
+status: wait
+priority: high
+state_hub_task_id: "f917bb0b-f44e-4642-9130-c1a004185180"
+```
+
+After T00 and T01, model the agreed engagement price or entitlement per
+reporting period and compute revenue, attributed cost, and margin by client
+and application. Preserve currency, effective periods, provenance, and price
+revisions; do not treat a price record as an issued invoice or received
+payment.
+
+## Define shared-infrastructure allocation
+
+```task
+id: FIN-WP-0002-T03
+status: wait
+priority: medium
+state_hub_task_id: "899a5c29-843c-481f-a63a-42d4d327af5d"
+```
+
+After T00 and in coordination with `FIN-WP-0004`, define an explainable
+per-instance allocation method for shared infrastructure. Start with the
+available namespace/resource evidence, document assumptions and residual
+unattributed cost, and keep technical allocation authority outside fin-hub
+where resource-control supplies it.
+
+Test allocation totals, rounding, missing evidence, shared overhead, revised
+allocations, and prevention of duplicate booked cost.
+
+## Export a per-client billing basis
+
+```task
+id: FIN-WP-0002-T04
+status: wait
+priority: medium
+state_hub_task_id: "b5886131-82f6-49fb-a7e3-ba47d5b627a8"
+```
+
+After T00–T03, provide an idempotent billing-basis report/export by client and
+period for consumption by an external invoicing system. Include stable record
+identity, attribution key, period, price basis, allocated cost, margin,
+currency, corrections, and provenance.
+
+The export must not issue invoices, assign legal invoice numbers, execute or
+track payments, or represent itself as bookkeeping evidence.
+
+## Select the external invoicing system
+
+```task
+id: FIN-WP-0002-T05
+status: wait
+priority: high
+state_hub_task_id: "d30b606f-43c1-4610-875d-c1fe578c412c"
+```
+
+Human gate: select the external GoBD-capable bookkeeping/invoicing system and
+record the integration boundary, required export fields, custody model, and
+retention responsibilities. Candidate products from the gap assessment are
+lexoffice and sevDesk, but selection is an operator/business decision and is
+not required to settle T00–T03.
+
+## Acceptance
+
+- [ ] Repository scope explicitly allows the reporting and export boundary.
+- [ ] Costs can be reported by client × application × instance without making
+      fin-hub authoritative for client or resource identity.
+- [ ] Revenue and margin are period-aware, currency-aware, and distinguishable
+      from invoices and payments.
+- [ ] Shared-infrastructure allocations reconcile to authoritative booked
+      costs with assumptions and unattributed residuals visible.
+- [ ] The billing-basis export is idempotent and contains no payment execution.
+- [ ] A human records the external invoicing/bookkeeping system decision.