PSA/ee/docs/plans/2026-03-16-client-owned-contracts-simplification/PRD.md

PRD — Client-Owned Contracts Simplification

• Slug: client-owned-contracts-simplification
• Date: 2026-03-16
• Status: Draft

Summary

Simplify the contracts domain so that reusable definition behavior lives only in contract templates, while every non-template contract becomes a client-owned instantiated contract header. Keep contracts as the header/line-owner table, keep client_contracts as the assignment/lifecycle window table, and remove the remaining shared-contract mental model from migration, backend rules, status handling, and the key contract-facing UI/reporting surfaces.

This work includes a production data migration for the currently shared non-template contracts, backend/schema guardrails so new cross-client sharing cannot be created, and targeted UI/reporting changes so live contract status and ownership derive from client_contracts.

Problem

The repo is split between two incompatible models:

• Newer flows, especially the contract wizard, already behave like contracts are client-specific instantiated records created from templates.
• Older model/actions/API/reporting/UI code still treats non-template contracts as reusable tenant-level objects that can legitimately fan out to multiple clients and carry their own live lifecycle state.

This mismatch already causes incorrect behavior and confusing UI:

• Billing truth is assignment-first, because invoice generation filters by client_contracts.is_active and assignment dates.
• Contract-facing UI can still show status from contracts.status.
• Reports still count “active contracts” from contracts.is_active.
• The schema does not enforce one owning client per non-template contract.

Production currently contains two real shared-contract cases where the same non-template contract_id is assigned to two different clients and owns multiple contract lines, which proves the ambiguity is not theoretical.

Goals

• Make contract_templates the only reusable contract-definition layer.
• Make every non-template contracts row require exactly one owning client.
• Keep contracts as the instantiated contract header and owner of contract lines/configuration.
• Keep client_contracts as the assignment/lifecycle window table for active/inactive dates, renewal state, and PO context.
• Make live client contract status come from client_contracts, not contracts.status.
• Migrate existing shared contracts by cloning non-template contracts per client assignment without retargeting invoice history.
• Add backend/schema guardrails so future cross-client sharing of non-template contracts is rejected.
• Update the core contract-facing UI/reporting surfaces so they reflect the client-owned model instead of the shared-contract model.

Non-goals

• Dropping the contracts table.
• Collapsing all contract header fields into client_contracts.
• Reworking contract templates beyond preserving their role as the only reusable concept.
• Retargeting historical invoices or rewriting historical financial references.
• A full redesign of all contract screens or all reports beyond the ones directly tied to shared/live contract semantics.
• Adding operational metrics, feature flags, or observability work beyond what is needed to validate the migration.

Users and Primary Flows

• Billing admin

  1. Starts from a contract template or creates a client-specific contract draft.
  2. Creates or resumes a non-template contract owned by one client.
  3. Activates, updates, renews, or terminates the client contract through assignment-aware flows.
  4. Generates invoices; billing resolves through the active assignment for that client.

• Finance / operations

  1. Reviews live client contracts and sees status derived from assignment lifecycle.
  2. Runs contract reports that count/display live contracts from assignment truth.
  3. Uses migration runbooks to verify shared contracts have been split cleanly.

• Engineers / support

  1. Can reason about one clear ownership rule for non-template contracts.
  2. Do not have to infer client ownership from a shared contract_id.

UX / UI Notes

• Templates remain a separate reusable area in Billing.
• Live “Client Contracts” UI should be assignment-first:
  • rows sourced from client_contracts joined to contracts
  • status badge derived from assignment lifecycle
  • live activate/terminate/unassign actions mutate assignment state, not shared contract-header state
• Contract detail for live client contracts should use clientContractId as the primary selection context and contractId as the header/line lookup.
• Draft contract flows may still use contract-header draft state, but once a contract is live for a client, the UI should not imply it is a shared reusable object.

Requirements

Functional Requirements

• Ownership model

  • Add contracts.owner_client_id for non-template contracts.
  • Every non-template contract must have one owning client.
  • Every client_contracts row referencing a non-template contract must have client_id = contracts.owner_client_id.

• Data migration

  • Detect any non-template contract_id linked to more than one distinct client_id.
  • For each shared contract group, preserve the original contract_id on one assignment and clone contract data for the others.
  • Preservation rules:
    • if exactly one assignment has invoice history, preserve that assignment on the original contract_id;
    • otherwise preserve the earliest-starting assignment.
  • Clone the contract header and all contract-owned line/config child records for each non-preserved assignment.
  • Repoint each non-preserved client_contracts.contract_id to its cloned contract.
  • Do not retarget invoice history in this pass.
  • Fail closed if a clone-target assignment has contract-scoped document associations or other historical references whose semantics are not explicitly handled by this pass.

• Guardrails

  • Non-template contract creation in supported app flows requires an owner client.
  • Assignment create/update flows reject attaching a non-template contract to a different client than its owner.
  • Renewal-draft creation copies owner client onto the new draft contract.
  • Shared-contract creation via legacy API/action paths is blocked unless explicitly exempted for internal migration tooling.

• Live status semantics

  • For live client-contract UI/actions/reporting, status must derive from assignment state (client_contracts.is_active, dates, renewal workflow state).
  • contracts.status may remain for draft/header workflow in this pass, but it is no longer the source of truth for live client contract state.

• UI/reporting cleanup

  • Billing contract list/detail flows stop implying that non-template contracts are reusable across clients.
  • Client contract lists/actions use assignment-first data.
  • Revenue/expiration/live contract reporting uses client_contracts as the fact table and joins contracts for descriptive fields only.
  • Contract-linked document visibility must continue to resolve correctly for the owning client after shared contracts are split.
  • Contract detail must separate contract-header state from assignment state so invoices, documents, and live status do not continue to imply cross-client shared ownership.

Non-functional Requirements

• Migration must be deterministic and idempotent enough to re-run safely in dry-run/validation contexts.
• Migration must fail closed on unsupported downstream references for non-preserved assignments instead of silently corrupting data.
• No new external dependencies.
• Keep plan scope to core behavior and correctness; do not expand into generalized contract-domain redesign work.

Data / API / Integrations

• Schema

  • Add contracts.owner_client_id.
  • Update IContract and any related request/response types to carry owner client information where relevant.

• Actions / API

  • Contract creation/update APIs that create non-template contracts must take or derive the owning client.
  • Live contract list/detail responses should expose assignment-derived status explicitly.
  • Existing /contracts resource semantics remain for now, but they refer to client-owned instantiated contract headers, not reusable library items.

• Billing engine

  • Keep the client_contracts -> contracts -> contract_lines read shape.
  • Rely on the new ownership invariant so the contract header/lines are unambiguous for a given client assignment.
  • Keep contract-backed client line helpers correct under the same invariant so overlap checks and contract-derived client line listings cannot bleed across clients.

• Reports

  • Contract report actions and report definitions must move active/live counting to client_contracts.

• Documents / client portal

  • Contract-linked document visibility continues to resolve via the client-owned contract invariant after migration and guardrail changes.
  • Contract-scoped document associations must be included in migration safety checks so unsupported shared-document scenarios abort instead of silently drifting.
  • Client portal billing and document views must be audited for compatibility with cloned client-owned contracts and any remaining legacy client_contract_lines assumptions must be called out or corrected.

Security / Permissions

• No new permissions are required.
• Existing billing/contract read and update permissions still gate access.
• Guardrails must prevent cross-client contract attachment even for privileged users unless an internal migration code path is explicitly used.

Observability

• Out of scope beyond existing migration logging and validation output.

Rollout / Migration

• Run a preflight query that identifies shared non-template contracts and classifies preserved vs clone-target assignments.
• Current known production shared contracts:
  • Managed IT Services in tenant Cross Industries, LLC
    • preserve The Green Thumb assignment because it has invoice history
    • clone for BTM Machinery
  • Worry-Free Essentials in tenant WorryNot Works IT Services
    • preserve WorryNot Works IT Services assignment because it has the earliest start date
    • clone for The Benjamin Wolf Group
• Verified current blast radius for clone-target assignments:
  • no invoices
  • no document associations
  • no pricing schedules
  • no direct time_entries or usage_tracking tied to those contract-line IDs
• After migration, validate that no non-template contract is linked to more than one distinct client.
• Abort newly discovered shared-contract groups from this migration if clone-target assignments carry contract-scoped documents or other historical references that need explicit copy/retarget semantics.

Open Questions

• Should a later follow-up fully remove live-status dependence on contracts.status everywhere, or is leaving it as a draft/header-only concept sufficient long-term?
• Should /contracts remain the long-term API noun for client-owned instantiated headers, or should a later API cleanup rename the resource for clarity?
• If a future shared-contract edge case includes contract-scoped docs, should those docs stay only on the preserved historical contract, be copied to cloned contracts, or eventually move to assignment/client scope?

Acceptance Criteria (Definition of Done)

• Production shared non-template contracts are split so that each non-template contract belongs to exactly one client.
• contracts.owner_client_id is populated for non-template contracts and enforced in normal app flows.
• Billing engine behavior remains correct for preserved and cloned assignments.
• Live contract UI surfaces derive status from client_contracts.
• Contract report actions no longer use contracts.is_active as the live fact source for active client contract reporting.
• Contract-linked client portal document visibility still resolves correctly for migrated cloned contracts.
• Unsupported shared-contract groups with contract-scoped documents fail closed during migration instead of silently producing incorrect document ownership.
• New attempts to attach a non-template contract to a different client than its owner fail with a clear error.