PSA/ee/docs/plans/2026-03-21-system-managed-default-contract-cutover/SCRATCHPAD.md

# Scratchpad — System-Managed Default Contract Cutover

- Plan slug: `system-managed-default-contract-cutover`
- Created: `2026-03-21`

## Decisions

- (2026-03-21) Create a brand-new plan folder instead of updating `2026-03-21-client-default-contract-on-demand-routing`.
- (2026-03-21) Keep creation model on-demand at billing-configuration ensure touchpoints rather than eager create at client creation.
- (2026-03-21) Keep migration strategy lazy and deterministic; avoid broad forced backfill.
- (2026-03-21) Use hard cutover objective: remove primary-path non-contract fallback complexity once routing is stable.
- (2026-03-21) Persist explicit default-contract identity on `contracts.is_system_managed_default` and enforce uniqueness via tenant+owner-client partial unique index; deterministic naming is `System-managed default contract`.
- (2026-03-21) Centralize billing-settings row ensure in `shared/billingClients/billingSettings.ts` and make default-contract ensure part of that shared path, then route schedule/cycle-anchor/package settings/credit-expiration updates through it.
- (2026-03-21) Null client-billing-settings overrides (`settings === null`) remain delete-only and do not trigger default-contract ensure; ensure is only invoked on non-null ensure/update touchpoints.
- (2026-03-21) Add fallback client-create hook `ensureDefaultContractForClientIfBillingConfigured(...)` in shared default-contract domain and wire it into major create paths (clients package action, shared model, API service, integration import, email service) so bypass flows still reconcile when billing settings already exist.
- (2026-03-21) For API-service client deletion, enforce domain cleanup before hard delete: remove assignment/billing artifacts, then apply orphan policy to default contracts (`delete` when uninvoiced orphan, `archive` when invoiced orphan).
- (2026-03-21) Refine the target model: system-managed default contracts are attribution shells for unmatched time/usage, not recurring cadence authorities.
- (2026-03-21) Unmatched default-contract work should invoice on the client billing schedule, not on default-contract billing frequency/timing.
- (2026-03-21) System-managed default contracts should not allow contract-line authoring, recurring/service-period management, pricing-schedule authoring, or user-managed assignment date semantics.
- (2026-03-21) Add an optional client billing schedule historical bootstrap date instead of trying to encode back-dated invoiceability through default-contract assignment start dates.
- (2026-03-21) Historical bootstrap is optional, normalizes to the containing client-cycle boundary, and may move earlier only while preserving invoiced-history boundaries.

## Discoveries / Constraints

- Billing settings ensure/insert logic is duplicated across shared and package layers, so hooks must be centralized or replicated safely.
- Some client create flows bypass package-level actions (integration/email/import), so client-create hook alone is insufficient.
- API generic delete path may bypass domain cleanup used by package client delete action.
- Resolver behavior currently differs by path and can use current-time filtering instead of effective-date filtering.
- Billing engine can treat some null-assigned rows as resolvable without persisting assignment; this feeds due-work ambiguity.
- UI copy has technical/non-business labels that do not communicate default-contract behavior clearly.
- Existing package wiring tests include brittle source-string assertions for exact function signatures/throw style; those tests can fail even when runtime behavior is unchanged.
- Shared vitest config only discovers `services/**/*.test.ts` and `**/__tests__/**/*.test.ts`, so shared tests for this plan need to live under `shared/__tests__/`.
- `BaseService.delete` is generic hard-delete behavior; without `ClientService.delete` override it bypasses client-domain cleanup and can skip default-contract artifact cleanup.
- `packages/clients/src/components/clients/BillingConfiguration.tsx` general save is not the right surface for historical client-cycle bootstrap; `ClientBillingSchedule.tsx` is the existing UX entry point for schedule-specific setup.
- `shared/billingClients/createBillingCycles.ts` backfills from the current/reference cycle forward, but does not automatically create historical client cycles for back-dated work unless an explicit effective date is supplied.
- `shared/billingClients/billingSchedule.ts` and `packages/billing/src/actions/billingScheduleActions.ts` already own schedule persistence and are the natural convergence points for optional bootstrap/backfill logic.
- Blanket backdating of default-contract `client_contracts.start_date` is unsafe because contract-cadence and client-cadence recurring materialization both treat assignment start as the schedule-generation anchor/as-of boundary.
- Back-dated billable work has a parallel gap on the client-schedule side today: a new billing configuration does not automatically create historical `client_billing_cycles`, so default-contract simplification alone does not solve historical invoiceability.

## Commands / Runbooks

- Inspect prior plan scaffolds:
  - `ls -1 ee/docs/plans`
  - `ls -la ee/docs/plans/2026-03-21-client-default-contract-on-demand-routing`
- Validate new plan:
  - `jq empty ee/docs/plans/2026-03-21-system-managed-default-contract-cutover/features.json`
  - `jq empty ee/docs/plans/2026-03-21-system-managed-default-contract-cutover/tests.json`
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-21-system-managed-default-contract-cutover`
- Verify T001 coverage for default contract ensure:
  - `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
- Verify T002 concurrency coverage (same suite now includes forced race path):
  - `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
- (Optional) Package wiring spot-check:
  - `cd packages/billing && npx vitest run tests/billingSettingsActions.renewalPermissions.wiring.test.ts tests/billingSettingsActions.renewalDefaultsWiring.test.ts tests/billingSettingsActions.cadenceOwnerDefaultsWiring.test.ts`
- Inspect billing schedule UI/action insertion points for optional bootstrap:
  - `sed -n '1,260p' packages/clients/src/components/clients/ClientBillingSchedule.tsx`
  - `sed -n '1,260p' packages/billing/src/actions/billingScheduleActions.ts`
- Inspect historical cycle creation/bootstrap behavior:
  - `sed -n '1,320p' shared/billingClients/createBillingCycles.ts`
  - `sed -n '1,280p' shared/billingClients/billingSchedule.ts`
  - `sed -n '1,320p' packages/billing/src/actions/billingCycleActions.ts`
- Inspect recurring-materialization coupling that makes assignment-start backdating unsafe:
  - `sed -n '360,470p' packages/billing/src/actions/contractCadenceServicePeriodMaterialization.ts`
  - `sed -n '380,430p' packages/billing/src/actions/clientCadenceScheduleRegeneration.ts`

## Links / References

- Existing stub plan folder: `ee/docs/plans/2026-03-21-client-default-contract-on-demand-routing`
- Related ongoing plan: `ee/docs/plans/2026-03-21-service-catalog-billing-mode-decoupling`
- Key current code surfaces identified by investigation:
  - `shared/billingClients/billingSettings.ts`
  - `shared/billingClients/billingSchedule.ts`
  - `packages/billing/src/actions/billingCycleAnchorActions.ts`
  - `packages/billing/src/actions/billingSettingsActions.ts`
  - `packages/billing/src/actions/creditExpirationSettingsActions.ts`
  - `packages/scheduling/src/lib/contractLineDisambiguation.ts`
  - `packages/billing/src/lib/contractLineDisambiguation.ts`
  - `packages/billing/src/lib/billing/billingEngine.ts`
  - `packages/billing/src/actions/billingAndTax.ts`
  - `packages/billing/src/actions/invoiceGeneration.ts`
  - `packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx`
  - `packages/scheduling/src/components/time-management/time-entry/time-sheet/ContractInfoBanner.tsx`
  - `packages/clients/src/actions/clientActions.ts`
- New/updated implementation files:
  - `shared/billingClients/defaultContract.ts`
  - `shared/billingClients/billingSettings.ts`
  - `shared/billingClients/billingSchedule.ts`
  - `shared/billingClients/createBillingCycles.ts`
  - `packages/billing/src/actions/billingCycleAnchorActions.ts`
  - `packages/billing/src/actions/billingCycleActions.ts`
  - `packages/billing/src/actions/billingScheduleActions.ts`
  - `packages/billing/src/actions/billingSettingsActions.ts`
  - `packages/billing/src/actions/creditExpirationSettingsActions.ts`
  - `packages/clients/src/components/clients/ClientBillingSchedule.tsx`
  - `server/migrations/20260321150000_add_system_managed_default_contract_marker.cjs`
  - `shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
  - `packages/clients/src/actions/clientActions.ts`
  - `shared/models/clientModel.ts`
  - `server/src/lib/api/services/ClientService.ts`
  - `packages/integrations/src/services/xeroCsvClientSyncService.ts`
  - `shared/services/emailService.ts`
  - `ee/docs/plans/2026-03-21-system-managed-default-contract-cutover/ENGINEERING_NOTES.md`

## Completed Checklist Progress

- (2026-03-21) Completed features: `F001-F018`, `F055`, `F056`, `F063`, `F068`.
- (2026-03-21) Completed tests: `T001`, `T002`.

## Open Questions

- Should default-contract pointer be persisted in billing settings or inferred by deterministic query?
- Should API base delete always delegate to domain delete orchestration for client entity type?
- What is final policy when billing settings are explicitly set to null/default state: keep default contract dormant or remove assignment?
- Should the optional historical bootstrap date be persisted in `client_billing_settings` as durable metadata, or used as operational input that only shapes generated `client_billing_cycles`?
- What exact pricing source should unmatched default-contract work use once the default contract no longer authors recurring lines?

## Progress Update (2026-03-21)

- Resolver/date cutover: both scheduling and billing `contractLineDisambiguation` now accept `effectiveDate` and apply date-window filtering using `start_date <= effectiveDate(end-of-day)` and `end_date is null || end_date >= effectiveDate(start-of-day)`.
- Save/UI callers now pass effective dates consistently: time-entry save uses computed `work_date`, usage save/update uses `usage_date`, and UI eligible-lines queries pass entry/usage date.
- Removed display-only ambiguous default selection in `ContractInfoBanner`; ambiguous multi-line matches now require explicit selection instead of showing a synthetic default.
- Billing engine unresolved reconciliation now persists deterministic single eligible contract-line assignments for time/usage with `whereNull(contract_line_id)` guards, then excludes those records from unresolved output.
- Recurring due-work now emits primary unresolved identity keys (`schedule:*:unresolved:*`) instead of legacy `non_contract` keys; invoice-generation and UI parsing now support both unresolved and legacy non-contract formats for backward compatibility.
- Completed features: `F019-F026`.
- Completed tests: `T003`, `T004`.
- Completed features: `F027-F033`.
- Completed tests: `T005`, `T006`, `T007`.
- Completed features: `F034-F037`.
- Completed tests: `T008`.

## Additional Runbooks (2026-03-21)

- Verify T003/T004 effective-date coverage:
  - `cd packages/scheduling && npx vitest run tests/timeEntryCrud.changeRequests.test.ts`
  - `cd server && npx vitest run ../packages/billing/tests/usageActions.effectiveDate.test.ts`
- Verify reconciliation behavior for deterministic vs ambiguous unresolved work:
  - `cd server && npx vitest run src/test/unit/billing/billingEngine.unresolvedReconciliation.test.ts`
- Verify unresolved-key candidate + generation compatibility:
  - `cd server && npx vitest run src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts src/test/unit/billing/nonContractDueWork.integration.test.ts src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`
- Re-run default-contract ensure suite after fallback hook expansion:
  - `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
- Typecheck touched shared/integration workspaces:
  - `npm -w shared run typecheck`
  - `npm -w @alga-psa/integrations run typecheck`
  - `npm -w @alga-psa/scheduling run typecheck` (currently fails due pre-existing `packages/clients` type errors unrelated to this plan)

## Progress Update (2026-03-21, F038/F039/T009)

- Added explicit recurring due-work attribution metadata on row/candidate shapes (`source`, business label, completeness, missing fields) to carry grouped-row assignment context through server and UI layers.
- `billingAndTax` now stamps persisted rows as `explicit_contract` vs `system_managed_default_contract` and unresolved rows as `unresolved`; grouped candidates aggregate attribution summaries.
- Persisted rows with incomplete contract attribution metadata are now marked non-generatable with a blocking reason before they reach grouped selection.
- `AutomaticInvoices` now consumes attribution metadata for grouped-row context labels and warning copy (`Assignment attribution metadata missing ...`) instead of relying on heuristic-only contract field checks.
- Added UI guard coverage for grouped rows: business-safe labels for system-managed default and unresolved work, plus hard-block behavior for metadata-missing rows.
- Completed features: `F038`, `F039`.
- Completed test: `T009`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`
- `cd server && npx vitest run src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts src/test/unit/billing/nonContractDueWork.integration.test.ts`
- `npm -w shared run typecheck`

### Notes

- `npm -w @alga-psa/billing run typecheck` still reports unrelated pre-existing workspace errors outside this change set; new attribution changes compile within exercised paths.
- Running `automaticInvoices.recurringDueWork.ui.test.tsx` in the same invocation currently triggers existing router-mount test harness issues (`invariant expected app router to be mounted`) not introduced by this work.

## Progress Update (2026-03-21, F040-F044/T010)

- Updated contract list UI (`ClientContractsTab`) to surface `System-managed default` badge and helper copy (`Created automatically for uncontracted work`) directly in contract-name cells.
- Added system-managed lifecycle guardrails in list actions: default contracts now only expose view/details access and hide destructive/manual lifecycle operations (`Delete`, `Terminate`, `Restore`, `Set to Active`).
- Updated contract detail UI (`ContractDetail`) with explicit system-managed banner/copy and read-only behavior for lifecycle/ownership-sensitive controls.
- Detail view now disables ownership-changing controls (assignment edit, lifecycle selectors, save) and hides destructive delete action for system-managed default contracts.
- Added static UI contract test coverage for list/detail guardrails and copy semantics.
- Completed features: `F040`, `F041`, `F042`, `F043`, `F044`.
- Completed test: `T010`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx src/test/unit/billing/systemManagedDefaultContracts.ui.static.test.ts`
- `cd server && npx vitest run src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts src/test/unit/billing/nonContractDueWork.integration.test.ts`

### Notes

- `T010` is currently implemented as a static UI contract test due test-environment import-resolution issues when rendering full `ContractDetail` runtime dependencies in isolation.

## Progress Update (2026-03-21, F045/F046/T011)

- Updated time-entry contract banner copy to remove `default rates` fallback language and use explicit `system-managed default contract` terminology for unmatched service lines.
- Updated fallback contract display label to `System-managed default contract` while preserving ambiguous-state messaging that requires explicit selection before persistence.
- Updated usage tracking tooltip, placeholder, and helper copy to mirror the same system-managed default terminology when client context is missing.
- Added a static UI terminology contract test covering both time-entry banner and usage tracking copy semantics, including guard text ensuring unresolved assignment remains explicit.
- Completed features: `F045`, `F046`.
- Completed test: `T011`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/defaultContractTerminology.ui.static.test.ts`

### Notes

- `T011` is currently implemented as a static source-contract test to avoid full UI runtime harness complexity while still enforcing copy semantics and unresolved-assignment wording.

## Progress Update (2026-03-21, F047/F048)

- Reworked `AutomaticInvoices` fallback assignment-context labels to business-safe copy, replacing technical identifier leaks in grouped rows:
  - `Assignment line <id>` -> `Assigned contract line`
  - `Execution <identity>` -> `Assigned work item`
- Preserved attribution-first behavior (`member.attribution.label`) so explicit/default/unresolved labels continue to display when provided by due-work attribution metadata.
- Added regression coverage in `automaticInvoices.nonContractSelection.ui.test.tsx` to ensure mixed explicit-contract + system-managed-default rows remain combinable when billing scopes align, and still generate as a single grouped parent target.
- Completed features: `F047`, `F048`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`

### Notes

- Broader legacy wiring suites still contain pre-existing brittle string expectations unrelated to this feature; feature verification was scoped to the recurring automatic-invoices UI integration test that exercises the changed behavior.

## Progress Update (2026-03-21, F049/F050)

- Added action-layer billing permission gates in `contractActions` for contract-view and mutation entry points used by billing contract list/detail flows (`read`, `create`, `update`).
- Added explicit server-side mutation guardrails to block create/update payload attempts that include system-managed identity fields (`is_system_managed_default`, `owner_client_id`).
- Sanitized create/update payload stripping for protected fields to ensure no accidental pass-through into model writes.
- Added wiring coverage asserting these guardrails stay present in contract actions.
- Completed features: `F049`, `F050`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx src/test/unit/billing/systemManagedContractGuardrails.wiring.test.ts`

### Notes

- Guardrails are implemented at action entry points so API/controller paths that call these actions inherit the same permission and mutation protections.

## Progress Update (2026-03-21, F051-F054)

- Added structured ensure observability in `shared/billingClients/defaultContract.ts`:
  - `default_contract.ensure` events for `created`, `reused`, and `skipped_no_billing_configuration` outcomes.
  - Included metric markers: `default_contract_created`, `default_contract_reused`, and skip marker.
- Added structured resolver routing logs in both scheduling and billing disambiguation libs:
  - `contract_line_resolver.routing` events with decisions `explicit`, `default`, or `ambiguous_or_unresolved`.
  - Included ambiguous marker metric `unresolved_ambiguous_count`.
- Added billing-engine reconciliation observability for unresolved write-back flow:
  - `billing_engine.reconcile.unresolved` events for deterministic single-match persistence and ambiguous/no-match skips.
  - Included deterministic marker `unmatched_resolved_deterministically` and ambiguous marker `unresolved_ambiguous_count`.
- Added wiring tests to lock observability contract points for ensure, resolver, and reconciliation paths.
- Completed features: `F051`, `F052`, `F053`, `F054`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/defaultContractObservability.wiring.test.ts src/test/unit/billing/systemManagedContractGuardrails.wiring.test.ts src/test/unit/billing/automaticInvoices.nonContractSelection.ui.test.tsx`

### Notes

- Structured payloads intentionally avoid end-user fields beyond tenant/client/record identifiers already present in server action context.

## Progress Update (2026-03-21, F057/F058)

- Validated and locked lazy backfill behavior via wiring coverage:
  - `ensureDefaultContractForClientIfBillingConfigured` gates ensure on `client_billing_settings` existence and returns `{ ensured: false }` otherwise.
  - This preserves no-forced-global-backfill behavior and first-qualifying-touchpoint creation semantics.
- Validated and locked targeted reconciliation wiring:
  - Due-work unresolved collection routes through `BillingEngine.calculateUnresolvedNonContractChargesForExecutionWindow`, which performs deterministic single-match write-back while leaving ambiguous/no-match rows unresolved.
- Added a dedicated wiring test file for lazy-backfill + reconciliation path contracts.
- Completed features: `F057`, `F058`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/defaultContractLazyBackfill.wiring.test.ts src/test/unit/billing/defaultContractObservability.wiring.test.ts`

## Progress Update (2026-03-21, F059)

- Added explicit sequencing runbook at `SEQUENCING_RUNBOOK.md` with stage gates, required-state criteria, and verification commands.
- Sequencing now formalizes cutover dependencies across:
  - data model + ensure,
  - hook coverage,
  - resolver/date alignment,
  - reconciliation semantics,
  - invoice selection/attribution safeguards,
  - UI guardrails,
  - lifecycle cleanup parity,
  - observability checks.
- Included rollback/safety rules to avoid partial-cutover invalid states and premature fallback removal.
- Completed feature: `F059`.

## Progress Update (2026-03-21, F061)

- Added `DEVELOPER_RUNBOOK.md` covering default-contract lifecycle, routing, reconciliation, grouped-attribution behavior, and operational verification commands.
- Documented forward guardrails to prevent reintroducing eager creation or identity-field bypasses.
- Completed feature: `F061`.

## Progress Update (2026-03-21, F069)

- Enforced canonical system-managed default contract naming convention during ensure:
  - existing default-contract rows are normalized to
    - name: `System-managed default contract`
    - description: `Created automatically for uncontracted work`
  - normalization occurs on ensure touchpoints without creating duplicate contracts.
- Added shared ensure regression coverage for legacy-named default contracts to guarantee canonical rename + assignment ensure behavior.
- Completed feature: `F069`.

### Verification commands

- `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`

## Progress Update (2026-03-21, F060/F066/F067)

- Removed obsolete legacy branch filtering in recurring invoice selection scoping:
  - dropped dead `__non_contract__` obligation-prefix exclusion in invoice generation,
  - retained legacy key parsing only at the schedule-key parser for backward compatibility.
- Renamed internal selector helper in invoice generation from non-contract-centric wording to unresolved-centric wording to match cutover semantics.
- Audited integration-created client pathway (`xeroCsvClientSyncService`) and confirmed first billing-config touchpoint hook still calls shared default-contract ensure.
- Added/kept wiring coverage asserting package/shared billing settings + schedule/anchor paths continue to use shared ensure primitives, preventing cross-package drift.
- Completed features: `F060`, `F066`, `F067`.

### Verification commands

- `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
- `cd server && npx vitest run src/test/unit/billing/defaultContractCrossPackageParity.wiring.test.ts src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts`

## Progress Update (2026-03-21, F062)

- Updated API contract schema to expose default-contract metadata explicitly:
  - added `is_system_managed_default` to `contractResponseSchema`.
- Added schema unit coverage verifying:
  - response payloads accept and expose `is_system_managed_default`,
  - create/update schemas keep system-managed identity marker out of writable request payloads.
- Completed feature: `F062`.

### Verification commands

- `cd server && npx vitest run src/test/unit/api/contractSchema.systemManagedDefault.schema.test.ts`

## Progress Update (2026-03-21, F064/F065/F070)

- Added a shared deterministic selection helper in both billing and scheduling disambiguation modules:
  - `resolveDeterministicContractLineSelection` now makes precedence explicit,
  - single explicit eligible line wins,
  - system-managed default (bucket-overlay line) is used only as fallback when it is uniquely deterministic,
  - ambiguous multi-active scenarios remain unresolved.
- Added package-level resolver tests in both billing and scheduling to lock fallback precedence and ambiguity behavior.
- Improved recurring invoice history attribution context:
  - history row mapping now computes explicit vs system-managed-default assignment sets from invoice charge assignments,
  - added stable history metadata fields (`assignmentDefaultContractIds`, `assignmentExplicitContractIds`, `assignmentSourceSummary`),
  - replaced raw-ID assignment labels with business-safe summaries (`System-managed default contract`, `Explicit contract assignment`, `Mixed assignment`).
- Added regression coverage for recurring invoice selection scoping to ensure contract-cadence execution windows remain explicit-obligation scoped and do not leak unresolved fallback selection semantics.
- Completed features: `F064`, `F065`, `F070`.

### Verification commands

- `npx vitest run --config vitest.config.ts tests/contractLineDisambiguation.defaultFallback.test.ts` (run in `packages/billing`)
- `npx vitest run --config vitest.config.ts tests/contractLineDisambiguation.defaultFallback.test.ts` (run in `packages/scheduling`)
- `cd server && npx vitest run src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts src/test/unit/billing/recurringInvoiceHistory.defaultContractAttribution.wiring.test.ts src/test/unit/api/contractSchema.systemManagedDefault.schema.test.ts`

## Progress Update (2026-03-21, T012-T018)

- Added lifecycle cleanup parity wiring tests for client delete flows:
  - `T012` package action path asserts deletion of billing settings/cycles and assignment artifacts.
  - `T013` API service path asserts cleanup orchestration includes default-contract assignment/header cleanup hooks.
- Extended shared billing-settings ensure tests for null-override behavior:
  - `T014` verifies deleting billing-settings override does not recreate default-contract artifacts.
- Added migration contract test for default-contract marker migration:
  - `T015` asserts table/column guards and idempotent index create/drop patterns.
- Added recurring selection regression for cadence safety:
  - `T016` verifies contract-cadence selection remains explicit-obligation scoped with unresolved fallback disabled.
- Extended observability wiring tests:
  - `T017` verifies structured logs avoid obvious PII fields in ensure/resolver/reconcile codepaths.
- Extended integration-import regression wiring coverage:
  - `T018` verifies integration-created client flow retains first qualifying billing-config ensure hook.

### Verification commands

- `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSettings.defaultContract.ensure.test.ts`
- `cd server && npx vitest run src/test/unit/billing/defaultContractDeletionCleanup.wiring.test.ts src/test/unit/billing/defaultContractCrossPackageParity.wiring.test.ts src/test/unit/billing/defaultContractObservability.wiring.test.ts src/test/unit/migrations/systemManagedDefaultContractMarkerMigration.test.ts src/test/unit/billing/invoiceGeneration.unresolvedSelectionKeys.test.ts`

## Progress Update (2026-03-21, F071-F074/F085)

- Reclassified system-managed default contracts as attribution-only in runtime guardrails:
  - backend mutation paths now block authoring for default contracts across contract update, contract-line mapping/line/config mutations, pricing schedules, and client-contract assignment mutation paths.
- Removed system-managed default contracts from recurring cadence authority surfaces:
  - contract cadence and client cadence materialization queries now explicitly exclude `contracts.is_system_managed_default = true`.
  - recurring due-work persisted-row readers and client-cadence materialization-gap checks now exclude system-managed defaults.
  - recurring service-period admin schedule listing filters out system-managed defaults, and direct management view for legacy schedule keys now hard-blocks with attribution-only messaging.
- Updated contract UI to attribution-only semantics:
  - contract detail alert copy now explains attribution-only behavior and points users to normal user-authored contracts for custom billing behavior.
  - contract lines/pricing tabs are disabled on system-managed defaults; lines/pricing components run in read-only mode with explanatory copy.
  - contract list helper copy now includes attribution-only wording.
- Added/updated static wiring tests locking the above behavior:
  - `systemManagedDefaultAttributionShell.wiring.test.ts`
  - `systemManagedDefaultContracts.ui.static.test.ts`

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/systemManagedDefaultAttributionShell.wiring.test.ts src/test/unit/billing/systemManagedDefaultContracts.ui.static.test.ts src/test/unit/billing/systemManagedContractGuardrails.wiring.test.ts`
- `npm -w @alga-psa/billing run typecheck` *(fails with pre-existing workspace errors outside this change set; no new failing assertions in targeted tests)*

### Completed checklist progress

- Completed features: `F071`, `F072`, `F073`, `F074`, `F085`.

## Progress Update (2026-03-21, F075/F076)

- Updated billing engine runtime timing resolution so system-managed default contract lines always use client-schedule cadence windows:
  - `buildRecurringChargeTimingSelection` now forces `cadenceOwner = client` whenever `is_system_managed_default` is true.
  - prevents default-contract assignments from reintroducing contract-anniversary timing semantics.
- Added legacy-safety pricing guardrails for system-managed default line charges:
  - time-charge rating now skips contract-line service-config rounding/minimum/user-type overrides when line is system-managed default.
  - usage-charge rating now skips contract-line service-config minimum/custom/tiered overrides when line is system-managed default.
  - this keeps unmatched default-contract billing on default/service-catalog pricing semantics.
- Added wiring tests to lock client-schedule timing + pricing override bypass behavior.
- Completed features: `F075`, `F076`.

### Verification commands

- `cd server && npx vitest run src/test/unit/billing/defaultContractClientSchedulePricing.wiring.test.ts src/test/unit/billing/systemManagedDefaultAttributionShell.wiring.test.ts`

## Progress Update (2026-03-21, F077-F084/F086, T019-T024)

- Implemented optional historical billing bootstrap flow on client billing schedule save:
  - Added optional `billingHistoryStartDate` through shared schedule domain, package action, client helper, and client UI.
  - Added shared bootstrap preview contract with normalized boundary, uninvoiced regeneration count, and invoiced-history lock status.
- Added deterministic historical client-cycle regeneration/backfill behavior:
  - User-entered history date normalizes to containing cycle boundary.
  - Uninvoiced cycles from normalized boundary are rebuilt contiguously through current date.
  - Bootstrap requests earlier than earliest invoiced cycle boundary are blocked with explicit message.
- Converged manual effective-date bootstrap + schedule bootstrap boundary behavior in shared schedule helpers (`createNextBillingCycle` normalization).
- Completed attribution-shell and recurring-exclusion regression coverage:
  - Added UI wiring contract test for attribution-only list/detail semantics and disabled line/pricing/assignment edit surfaces.
  - Added wiring contract test for historical bootstrap + default-contract billing route semantics.
  - Added wiring contract test for recurring/service-period materialization and recurring admin exclusion of system-managed defaults.
- Updated plan docs/runbooks for attribution-shell model and historical bootstrap workflow/gates (`ENGINEERING_NOTES.md`, `DEVELOPER_RUNBOOK.md`, `SEQUENCING_RUNBOOK.md`).
- Completed features: `F077`, `F078`, `F079`, `F080`, `F081`, `F082`, `F083`, `F084`, `F086`.
- Completed tests: `T019`, `T020`, `T021`, `T022`, `T023`, `T024`.

### Verification commands

- `npx vitest run --config shared/vitest.config.ts shared/__tests__/billingSchedule.historyBootstrap.test.ts`
- `cd server && npx vitest run src/test/unit/billing/ClientBillingSchedule.ui.test.tsx src/test/unit/billing/defaultContractClientSchedulePricing.wiring.test.ts src/test/unit/billing/systemManagedDefaultAttributionShell.wiring.test.ts src/test/unit/billing/systemManagedDefaultContracts.ui.static.test.ts src/test/unit/billing/defaultContractDeletionCleanup.wiring.test.ts src/test/unit/billing/systemManagedContractGuardrails.wiring.test.ts`
- `cd server && npx vitest run src/test/unit/billing/systemManagedDefaultAttributionOnly.ui.wiring.test.ts src/test/unit/billing/defaultContractHistoricalBootstrapAndBillingRoute.wiring.test.ts src/test/unit/billing/systemManagedDefaultRecurringExclusion.wiring.test.ts src/test/unit/billing/systemManagedDefaultAttributionShell.wiring.test.ts src/test/unit/billing/defaultContractClientSchedulePricing.wiring.test.ts src/test/unit/billing/systemManagedDefaultContracts.ui.static.test.ts`